UQpy package

Submodules

UQpy.Distributions module

UQpy.Inference module

UQpy.ReadInputFile module

UQpy.Reliability module

class UQpy.Reliability.SubsetSimulation(dimension=None, samples_init=None, nsamples_ss=None, p_cond=None, pdf_target_type=None, pdf_target=None, pdf_target_params=None, pdf_proposal_type=None, pdf_proposal_scale=None, algorithm=None, model_type=None, model_script=None, input_script=None, output_script=None)

A class used to perform Subset Simulation.

This class estimates probability of failure for a user-defined model using Subset Simulation

References: S.-K. Au and J. L. Beck, “Estimation of small failure probabilities in high dimensions by subset simulation,”

Probabilistic Eng. Mech., vol. 16, no. 4, pp. 263–277, Oct. 2001.

Input: :param dimension: A scalar value defining the dimension of target density function.

Default: 1
Parameters:
  • nsamples_ss (int) – Number of samples to generate in each conditional subset No Default Value: nsamples_ss must be prescribed
  • p_cond (float) – Conditional probability at each level Default: p_cond = 0.1
  • algorithm (str) –

    Algorithm used to generate MCMC samples. Options:

    ’MH’: Metropolis Hastings Algorithm ‘MMH’: Component-wise Modified Metropolis Hastings Algorithm ‘Stretch’: Affine Invariant Ensemble MCMC with stretch moves

    Default: ‘MMH’

  • pdf_target_type (str) –

    Type of target density function for acceptance/rejection in MMH. Not used for MH or Stretch. Options:

    ’marginal_pdf’: Check acceptance/rejection for a candidate in MMH using the marginal pdf
    For independent variables only

    ’joint_pdf’: Check acceptance/rejection for a candidate in MMH using the joint pdf

    Default: ‘marginal_pdf’

  • pdf_target (function, function list, or str) –

    Target density function from which to draw random samples The target joint probability density must be a function, or list of functions, or a string. If type == ‘str’

    The assigned string must refer to a custom pdf defined in the file custom_pdf.py in the working
    directory
    If type == function
    The function must be defined in the python script calling MCMC
    If dimension > 1 and pdf_target_type=’marginal_pdf’, the input to pdf_target is a list of size
    [dimensions x 1] where each item of the list defines a marginal pdf.

    Default: Multivariate normal distribution having zero mean and unit standard deviation

  • pdf_target_params (list) – Parameters of the target pdf
  • pdf_proposal_type (str or str list) –

    Type of proposal density function for MCMC. Only used with algorithm = ‘MH’ or ‘MMH’ Options:

    ’Normal’ : Normal proposal density ‘Uniform’ : Uniform proposal density

    Default: ‘Uniform’ If dimension > 1 and algorithm = ‘MMH’, this may be input as a list to assign different proposal

    densities to each dimension. Example pdf_proposal_type = [‘Normal’,’Uniform’].
    If dimension > 1, algorithm = ‘MMH’ and this is input as a string, the proposal densities for all
    dimensions are set equal to the assigned proposal type.
  • pdf_proposal_scale –

    Scale of the proposal distribution If algorithm == ‘MH’ or ‘MMH’

    For pdf_proposal_type = ‘Uniform’
    Proposal is Uniform in [x-pdf_proposal_scale/2, x+pdf_proposal_scale/2]
    For pdf_proposal_type = ‘Normal’
    Proposal is Normal with standard deviation equal to pdf_proposal_scale
    If algorithm == ‘Stretch’
    pdf_proposal_scale sets the scale of the stretch density
    g(z) = 1/sqrt(z) for z in [1/pdf_proposal_scale, pdf_proposal_scale]

    Default value: dimension x 1 list of ones

  • model_type (str) –

    Define the model as a python file or as a third party software model (e.g. Matlab, Abaqus, etc.) Options: None - Run a third party software model

    ’python’ - Run a python model. When selected, the python file must contain a class RunPythonModel
    that takes, as input, samples and dimension and returns quantity of interest (qoi) in in list form where there is one item in the list per sample. Each item in the qoi list may take type the user prefers.

    Default: None

  • model_script –
    Defines the script (must be either a shell script (.sh) or a python script (.py)) used to call
    the model.

    This is a user-defined script that must be provided. If model_type = ‘python’, this must be a python script (.py) having a specified class

    structure. Details on this structure can be found in the UQpy documentation.
  • input_script –
    Defines the script (must be either a shell script (.sh) or a python script (.py)) that takes
    samples generated by UQpy from the sample file generated by UQpy (UQpy_run_{0}.txt) and imports them into a usable input file for the third party solver. Details on UQpy_run_{0}.txt can be found in the UQpy documentation.

    If model_type = None, this is a user-defined script that the user must provide. If model_type = ‘python’, this is not used.

  • output_script (str) –
    (Optional) Defines the script (must be either a shell script (.sh) or python script (.py))
    that extracts quantities of interest from third-party output files and saves them to a file (UQpy_eval_{}.txt) that can be read for postprocessing and adaptive sampling methods by UQpy.
    If model_type = None, this is an optional user-defined script. If not provided, all run files
    and output files will be saved in the folder ‘UQpyOut’ placed in the current working directory. If provided, the text files UQpy_eval_{}.txt are placed in this directory and all other files are deleted.

    If model_type = ‘python’, this is not used.
Type:

model_script: str
Type:

input_script: str

Output:

Parameters:pf (float) – Probability of failure estimate

UQpy.RunModel module

class UQpy.RunModel.RunModel(samples=None, dimension=None, model_type=None, model_script=None, input_script=None, output_script=None, cpu=None)

A class used to run a computational model a specified sample points.

This class takes samples, either passed as a variable or read through a text file, and runs a specified computational model at those sample points. This can be done by either passing variables and running entirely in python or by calling shell scripts that run a third-party software model.

Input: :param samples: The sample values at which the model will be evaluated. Samples can be passed directly as an array

or can be passed through the text file ‘UQpy_Samples.txt’. If passing samples via text file, set samples = None or do not set the samples input.
Parameters:
  • dimension (int) – The dimension of the random variable whose samples are being passed to the model.
  • model_type (str) –

    Define the model as a python file or as a third party software model (e.g. Matlab, Abaqus, etc.) Options: None - Run a third party software model

    ’python’ - Run a python model. When selected, the python file must contain a class RunPythonModel
    that takes, as input, samples and dimension and returns quantity of interest (qoi) in in list form where there is one item in the list per sample. Each item in the qoi list may take type the user prefers.

    Default: None

  • model_script –
    Defines the script (must be either a shell script (.sh) or a python script (.py)) used to call
    the model.

    This is a user-defined script that must be provided. If model_type = ‘python’, this must be a python script (.py) having a specified class

    structure. Details on this structure can be found in the UQpy documentation.
  • input_script –
    Defines the script (must be either a shell script (.sh) or a python script (.py)) that takes
    samples generated by UQpy from the sample file generated by UQpy (UQpy_run_{0}.txt) and imports them into a usable input file for the third party solver. Details on UQpy_run_{0}.txt can be found in the UQpy documentation.

    If model_type = None, this is a user-defined script that the user must provide. If model_type = ‘python’, this is not used.

  • output_script (str) –
    (Optional) Defines the script (must be either a shell script (.sh) or python script (.py))
    that extracts quantities of interest from third-party output files and saves them to a file (UQpy_eval_{}.txt) that can be read for postprocessing and adaptive sampling methods by UQpy.
    If model_type = None, this is an optional user-defined script. If not provided, all run files
    and output files will be saved in the folder ‘UQpyOut’ placed in the current working directory. If provided, the text files UQpy_eval_{}.txt are placed in this directory and all other files are deleted.

    If model_type = ‘python’, this is not used.

  • cpu (int) – Number of CPUs over which to run the job. UQpy distributes the total number of model evaluations over this number of CPUs Default: 1 - Runs serially
Type:

model_script: str
Type:

input_script: str

Output: :param model_eval: An instance of a sub-class that contains the model solutions. Depending on how the model is run,

model_eval is an instance of a different class.
If model_type = ‘python’, model_eval is an instance of the class RunPythonModel defined in the
python model_script.

If model_type = ‘None’ and cpu <= 1, model_eval is an instance of the class RunSerial If model_type = ‘None’ and cpu > 1, model_eval is an instance of the class RunParallel Regardless of model_type, model_eval has the following key attributes:

model_eval.samples = Sample values at which the model has been run. model_eval.QOI = Solution of the model at each sample value.
Type:model_eval: The two key attributes of model_eval have the following type. model_eval.samples = numpy array model_eval.QOI = list
class RunParallel(samples=None, cpu=None, model_script=None, input_script=None, output_script=None, dimension=None)

A subclass of RunModel to run a third-party software model with parallel processing.

Most attributes of this subclass are inhereted from RunModel. The only variable that is not inherited is QOI.

Input: :param samples: Inherited from RunModel. See its documentation. :type samples: numpy array

Parameters:
  • dimension (int) – Inherited from RunModel. See its documentation.
  • model_script – Inherited from RunModel. See its documentation.
  • input_script – Inherited from RunModel. See its documentation.
  • output_script (str) – Inherited from RunModel. See its documentation.
Type:

model_script: str
Type:

input_script: str

Output: :param QOI: List containing the Quantity of Interest from the simulations

Each item in the list corresponds to one simulation
class RunSerial(samples=None, dimension=None, model_script=None, input_script=None, output_script=None)

A subclass of RunModel to run a third-party software model serially (without parallel processing).

Most attributes of this subclass are inherited from RunModel. The only variable that is not inherited is QOI.

Input: :param samples: Inherited from RunModel. See its documentation. :type samples: numpy array

Parameters:
  • dimension (int) – Inherited from RunModel. See its documentation.
  • model_script – Inherited from RunModel. See its documentation.
  • input_script – Inherited from RunModel. See its documentation.
  • output_script (str) – Inherited from RunModel. See its documentation.
Type:

model_script: str
Type:

input_script: str

Output: :param QOI: List containing the Quantity of Interest from the simulations

Each item in the list corresponds to one simulation

UQpy.SampleMethods module

This module contains functionality for all the sampling methods supported in UQpy.

class UQpy.SampleMethods.LHS(dimension=None, pdf_type=None, pdf_params=None, lhs_criterion=None, lhs_metric=None, lhs_iter=None, nsamples=None)

A class that creates a Latin Hypercube Design for experiments. SamplesU01 belong in hypercube [0, 1]^n while samples belong to the parameter space

Parameters:
  • pdf_type (list) – Distribution of the parameters
  • pdf_params (list) – Distribution parameters
  • lhs_criterion (str) –

    The criterion for generating sample points Options:

    1. random - completely random
    2. centered - points only at the centre
    3. maximin - maximising the minimum distance between points
    4. correlate - minimizing the correlation between the points
  • lhs_iter (int) – The number of iteration to run. Only for maximin, correlate and criterion
  • lhs_metric (str) –

    The distance metric to use. Supported metrics are ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’,

    ’euclidean’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’,

    ’rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’,

    ’yule’.
class UQpy.SampleMethods.MCMC(dimension=None, pdf_proposal_type=None, pdf_proposal_scale=None, pdf_target_type=None, pdf_target=None, pdf_target_params=None, algorithm=None, jump=None, nsamples=None, seed=None, nburn=None)

Generate samples from an arbitrary probability density function using Markov Chain Monte Carlo.

This class generates samples from an arbitrary user-specified distribution using Metropolis-Hastings(MH), Modified Metropolis-Hastings, of Affine Invariant Ensemble Sampler with stretch moves.

References: S.-K. Au and J. L. Beck, “Estimation of small failure probabilities in high dimensions by subset simulation,”

Probabilistic Eng. Mech., vol. 16, no. 4, pp. 263–277, Oct. 2001.
  1. Goodman and J. Weare, “Ensemble samplers with affine invariance,” Commun. Appl. Math. Comput. Sci., vol. 5,
    no. 1, pp. 65–80, 2010.

Input: :param dimension: A scalar value defining the dimension of target density function.

Default: 1
Parameters:
  • pdf_proposal_type (str or str list) –

    Type of proposal density function for MCMC. Only used with algorithm = ‘MH’ or ‘MMH’ Options:

    ’Normal’ : Normal proposal density ‘Uniform’ : Uniform proposal density

    Default: ‘Uniform’ If dimension > 1 and algorithm = ‘MMH’, this may be input as a list to assign different proposal

    densities to each dimension. Example pdf_proposal_type = [‘Normal’,’Uniform’].
    If dimension > 1, algorithm = ‘MMH’ and this is input as a string, the proposal densities for all
    dimensions are set equal to the assigned proposal type.
  • pdf_proposal_scale –

    Scale of the proposal distribution If algorithm == ‘MH’ or ‘MMH’

    For pdf_proposal_type = ‘Uniform’
    Proposal is Uniform in [x-pdf_proposal_scale/2, x+pdf_proposal_scale/2]
    For pdf_proposal_type = ‘Normal’
    Proposal is Normal with standard deviation equal to pdf_proposal_scale
    If algorithm == ‘Stretch’
    pdf_proposal_scale sets the scale of the stretch density
    g(z) = 1/sqrt(z) for z in [1/pdf_proposal_scale, pdf_proposal_scale]

    Default value: dimension x 1 list of ones

  • pdf_target_type (str) –

    Type of target density function for acceptance/rejection in MMH. Not used for MH or Stretch. Options:

    ’marginal_pdf’: Check acceptance/rejection for a candidate in MMH using the marginal pdf
    For independent variables only

    ’joint_pdf’: Check acceptance/rejection for a candidate in MMH using the joint pdf

    Default: ‘marginal_pdf’

  • pdf_target (function, function list, or str) –

    Target density function from which to draw random samples The target joint probability density must be a function, or list of functions, or a string. If type == ‘str’

    The assigned string must refer to a custom pdf defined in the file custom_pdf.py in the working
    directory
    If type == function
    The function must be defined in the python script calling MCMC
    If dimension > 1 and pdf_target_type=’marginal_pdf’, the input to pdf_target is a list of size
    [dimensions x 1] where each item of the list defines a marginal pdf.

    Default: Multivariate normal distribution having zero mean and unit standard deviation

  • pdf_target_params (list) – Parameters of the target pdf
  • algorithm (str) –

    Algorithm used to generate random samples. Options:

    ’MH’: Metropolis Hastings Algorithm ‘MMH’: Component-wise Modified Metropolis Hastings Algorithm ‘Stretch’: Affine Invariant Ensemble MCMC with stretch moves

    Default: ‘MMH’

  • jump – Number of samples between accepted states of the Markov chain. Default value: 1 (Accepts every state)
  • nsamples (int) – Number of samples to generate No Default Value: nsamples must be prescribed
  • seed (float or numpy array) –

    Seed of the Markov chain(s) For ‘MH’ and ‘MMH’, this is a single point, defined as a numpy array of dimension (1 x dimension) For ‘Stretch’, this is a numpy array of dimension N x dimension, where N is the ensemble size Default:

    For ‘MH’ and ‘MMH’: zeros(1 x dimension) For ‘Stretch’: No default, this must be specified.
  • nburn (int) – Length of burn-in. Number of samples at the beginning of the chain to discard. This option is only used for the ‘MMH’ and ‘MH’ algorithms. Default: nburn = 0
Type:

jump: int

Output: :return: MCMC.samples: :rtype: MCMC.samples: numpy array

class UQpy.SampleMethods.MCS(dimension=None, pdf_type=None, pdf_params=None, nsamples=None)

A class used to perform brute force Monte Carlo design of experiment (MCS). SamplesU01 belong in hypercube [0, 1]^n while samples belong to the parameter space

Parameters:
  • dimension (int) – Number of parameters
  • nsamples (int) – Number of samples to be generated
  • pdf_type (list) – Type of distributions
  • pdf_params (list) – Distribution parameters
class UQpy.SampleMethods.PSS(dimension=None, pdf_type=None, pdf_params=None, pss_design=None, pss_strata=None)

This class generates a partially stratified sample set on U(0,1) as described in: Shields, M.D. and Zhang, J. “The generalization of Latin hypercube sampling” Reliability Engineering and System Safety. 148: 96-108

Parameters:
  • pss_design (list) –

    Vector defining the subdomains to be used. Example: 5D problem with 2x2D + 1x1D subdomains using pss_design = [2,2,1].

    Note: The sum of the values in the pss_design vector equals the dimension of the problem.

  • pss_strata (list) –

    Vector defining how each dimension should be stratified. Example: 5D problem with 2x2D + 1x1D subdomains with 625 samples using

    pss_pss_stratum = [25,25,625].

    Note: pss_pss_stratum(i)^pss_design(i) = number of samples (for all i)
Returns:

pss_samples: Generated samples Array (nSamples x nRVs)

Created by: Jiaxin Zhang Last modified: 24/01/2018 by D.G. Giovanis

class UQpy.SampleMethods.STS(dimension=None, pdf_type=None, pdf_params=None, sts_design=None, pss_=None)
Parameters:
  • dimension –
  • pdf_type –
  • pdf_params –
  • sts_design –
  • pss –
class UQpy.SampleMethods.Strata(nstrata=None, input_file=None, origins=None, widths=None)

Define a rectilinear stratification of the n-dimensional unit hypercube with N strata.

Parameters:
  • nstrata – array-like An array of dimension 1 x n defining the number of strata in each of the n dimensions Creates an equal stratification with strata widths equal to 1/nstrata The total number of strata, N, is the product of the terms of nstrata Example - nstrata = [2, 3, 2] creates a 3d stratification with: 2 strata in dimension 0 with stratum widths 1/2 3 strata in dimension 1 with stratum widths 1/3 2 strata in dimension 2 with stratum widths 1/2
  • input_file – string File path to input file specifying stratum origins and stratum widths
  • origins –

    array-like An array of dimension N x n specifying the origins of all strata The origins of the strata are the coordinates of the stratum orthotope nearest the global origin Example - A 2D stratification with 2 strata in each dimension origins = [[0, 0]

    [0, 0.5] [0.5, 0] [0.5, 0.5]]
  • widths –

    array-like An array of dimension N x n specifying the widths of all strata in each dimension Example - A 2D stratification with 2 strata in each dimension widths = [[0.5, 0.5]

    [0.5, 0.5] [0.5, 0.5] [0.5, 0.5]]
fullfact(levels)

Create a general full-factorial design

levels : array-like
An array of integers that indicate the number of levels of each input design factor.
mat : 2d-array
The design matrix with coded levels 0 to k-1 for a k-level factor
>>> fullfact([2, 4, 3])
array([[ 0.,  0.,  0.],
       [ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 1.,  1.,  0.],
       [ 0.,  2.,  0.],
       [ 1.,  2.,  0.],
       [ 0.,  3.,  0.],
       [ 1.,  3.,  0.],
       [ 0.,  0.,  1.],
       [ 1.,  0.,  1.],
       [ 0.,  1.,  1.],
       [ 1.,  1.,  1.],
       [ 0.,  2.,  1.],
       [ 1.,  2.,  1.],
       [ 0.,  3.,  1.],
       [ 1.,  3.,  1.],
       [ 0.,  0.,  2.],
       [ 1.,  0.,  2.],
       [ 0.,  1.,  2.],
       [ 1.,  1.,  2.],
       [ 0.,  2.,  2.],
       [ 1.,  2.,  2.],
       [ 0.,  3.,  2.],
       [ 1.,  3.,  2.]])

UQpy.Surrogates module

UQpy.UQpyModules module

class UQpy.UQpyModules.RunModel(cpu=None, solver=None, input_=None, output_=None, adaptive=None, dimension=None)

A class used to run the computational model.

Parameters:
  • cpu –
  • solver –
  • input –
  • output –
  • adaptive –
  • dimension –

UQpy.UQpy_cmd module

Module contents