Sample#

stochopy.sample.sample(fun, bounds, x0=None, args=(), method='mcmc', options=None, callback=None)[source]#

Sample the variable space of an objective function.

Parameters:

  • fun (callable) – The objective function to be sampled. Must be in the form f(x, *args), where x is the argument in the form of a 1-D array and args is a tuple of any additional fixed parameters needed to completely specify the function.

  • bounds (array_like) – Bounds for variables. (min, max) pairs for each element in x, defining the finite lower and upper bounds for the sampling argument of fun. It is required to have len(bounds) == len(x). len(bounds) is used to determine the number of parameters in x.

  • x0 (array_like or None, optional, default None) – Initial sample. Array of real elements of size (ndim,), where ndim is the number of independent variables.

  • args (tuple, optional, default None) – Extra arguments passed to the objective function.

  • method (str, optional, default 'mcmc') –

    Type of sampler. Should be one of:

    • ’mcmc’

    • ’hmc’

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

    A dictionary of sampler options. All methods accept the following generic options:

    • maxiter (int): total number of samples to generate

    • seed (int or None): seed for random number generator

    • return_all (bool): set to True to return an array of all the solutions at each iteration

  • callback (callable or None, optional, default None) – Called after each iteration. It is a callable with the signature callback(xk, SampleResult state), where xk is the current population and state is a stochopy.sample.SampleResult object with the same fields as the ones from the return.

Returns:

The sampling result represented as a stochopy.sample.SampleResult. Important attributes are:

  • x: the best sample array

  • fun: the best sample function value

  • xall: the samples array

  • ’funall`: the samples’ function value array

Return type:

stochopy.sample.SampleResult

Result#

stochopy.sample.SampleResult()[source]#

Represent the sampling result.

stochopy.sample.x#

The best solution sampled.

Type:

array_like

stochopy.sample.fun#

The solution function value.

Type:

scalar

stochopy.sample.nit#

Number of samples generated.

Type:

int

Note

There may be additional attributes not listed above depending of the specific solver.

Available samplers#

Hamiltonian Monte-Carlo#

stochopy.sample.hmc(fun, bounds, x0=None, args=(), maxiter=100, nleap=10, stepsize=0.01, seed=None, jac=None, finite_diff_abs_step=0.0001, constraints=None, return_all=True, callback=None)#

Sample the variable space using the Hamiltonian (Hybrid) Monte-Carlo algorithm.

Parameters:

  • fun (callable) – The objective function to be sampled. Must be in the form f(x, *args), where x is the argument in the form of a 1-D array and args is a tuple of any additional fixed parameters needed to completely specify the function.

  • bounds (array_like) – Bounds for variables. (min, max) pairs for each element in x, defining the finite lower and upper bounds for the sampling argument of fun. It is required to have len(bounds) == len(x). len(bounds) is used to determine the number of parameters in x.

  • x0 (array_like or None, optional, default None) – Initial sample. Array of real elements of size (ndim,), where ndim is the number of independent variables.

  • args (tuple, optional, default None) – Extra arguments passed to the objective function.

  • maxiter (int, optional, default 100) – Total number of samples to generate.

  • nleap (int, optional, default 10) – Number of leap-frog steps.

  • stepsize (scalar or array_like, optional, default 0.01) – Leap-frog step size (as a fraction of feasible space defined by bounds).

  • perc (scalar, optional, default 1.0) – Number of dimensions to perturb at each iteration (as a fraction of total number of variables).

  • seed (int or None, optional, default None) – Seed for random number generator.

  • jac (callable or None, optional, default None) – Method for computing the gradient vector. If it is a callable, it should be a function in the form jac(x, *args) that returns the gradient vector where x is an array with shape (ndim,) and args is a tuple with the fixed parameters. If None, the gradient will be estimated using 2-point finite difference estimation with an absolute step size.

  • finite_diff_abs_step (scalar, optional, default 1.0e-4) – The absolute step size to use for numerical approximation of the jacobian.

  • constraints (str or None, optional, default None) –

    Constraints definition:

    • None: no constraint

    • ’Reject’: infeasible solutions are always rejected

  • return_all (bool, optional, default True) – Set to True to return an array with shape (maxiter, ndim) of all the samples.

  • callback (callable or None, optional, default None) – Called after each iteration. It is a callable with the signature callback(xk, SampleResult state), where xk is the current population and state is a stochopy.sample.SampleResult object with the same fields as the ones from the return.

Returns:

The sampling result represented as a stochopy.sample.SampleResult. Important attributes are:

  • x: the best sample array

  • fun: the best sample function value

  • xall: the samples array

  • ’funall`: the samples’ function value array

Return type:

stochopy.sample.SampleResult

References

Markov-Chain Monte-Carlo#

stochopy.sample.mcmc(fun, bounds, x0=None, args=(), maxiter=100, stepsize=0.1, perc=1.0, seed=None, constraints=None, return_all=True, callback=None)#

Sample the variable space using the Metropolis-Hastings algorithm.

Parameters:

  • fun (callable) – The objective function to be sampled. Must be in the form f(x, *args), where x is the argument in the form of a 1-D array and args is a tuple of any additional fixed parameters needed to completely specify the function.

  • bounds (array_like) – Bounds for variables. (min, max) pairs for each element in x, defining the finite lower and upper bounds for the sampling argument of fun. It is required to have len(bounds) == len(x). len(bounds) is used to determine the number of parameters in x.

  • x0 (array_like or None, optional, default None) – Initial sample. Array of real elements of size (ndim,), where ndim is the number of independent variables.

  • args (tuple, optional, default None) – Extra arguments passed to the objective function.

  • maxiter (int, optional, default 100) – Total number of samples to generate.

  • stepsize (scalar or array_like, optional, default 0.1) – Standard deviation of Gaussian perturbation (as a fraction of feasible space defined by bounds).

  • perc (scalar, optional, default 1.0) – Number of dimensions to perturb at each iteration (as a fraction of total number of variables).

  • seed (int or None, optional, default None) – Seed for random number generator.

  • constraints (str or None, optional, default None) –

    Constraints definition:

    • None: no constraint

    • ’Reject’: infeasible solutions are always rejected

  • return_all (bool, optional, default True) – Set to True to return an array with shape (maxiter, ndim) of all the samples.

  • callback (callable or None, optional, default None) – Called after each iteration. It is a callable with the signature callback(xk, SampleResult state), where xk is the current population and state is a stochopy.sample.SampleResult object with the same fields as the ones from the return.

Returns:

The sampling result represented as a stochopy.sample.SampleResult. Important attributes are:

  • x: the best sample array

  • fun: the best sample function value

  • xall: the samples array

  • ’funall`: the samples’ function value array

Return type:

stochopy.sample.SampleResult