# Bumps 0.8.1 documentation

## bounds - Parameter constraints

`pm` | Return the tuple (~v-dv,~v+dv), where ~expr is a 'nice' number near to to the value of expr. For example::.
`pmp` | Return the tuple (~v-%v,~v+%v), where ~expr is a 'nice' number near to the value of expr. For example::.
`pm_raw` | Return the tuple [v-dv,v+dv].
`pmp_raw` | Return the tuple [v-%v,v+%v]
`nice_range` | Given a range, return an enclosing range accurate to two digits.
`init_bounds` | Returns a bounds object of the appropriate type given the arguments.
`Bounds` | Bounds abstract base class.
`Unbounded` | Unbounded parameter.
`Bounded` | Bounded range.
`BoundedAbove` | Semidefinite range bounded above.
`BoundedBelow` | Semidefinite range bounded below.
`Distribution` | Parameter is pulled from a distribution.
`Normal` | Parameter is pulled from a normal distribution.
`BoundedNormal` | truncated normal bounds
`SoftBounded` | Parameter is pulled from a stretched normal distribution.

Parameter bounds and prior probabilities.

Parameter bounds encompass several features of our optimizers.

First and most trivially they allow for bounded constraints on parameter values.

Secondly, for parameter values known to follow some distribution, the bounds encodes a penalty function as the value strays from its nominal value. Using a negative log likelihood cost function on the fit, then this value naturally contributes to the overall likelihood measure.

Predefined bounds are:

    Unbounded
        range (-inf, inf)
    BoundedBelow
        range (base, inf)
    BoundedAbove
        range (-inf, base)
    Bounded
        range (low, high)
    Normal
        range (-inf, inf) with gaussian probability
    BoundedNormal
        range (low, high) with gaussian probability within
    SoftBounded
        range (low, high) with gaussian probability outside

New bounds can be defined following the abstract base class interface defined in `Bounds`, or using Distribution(rv) where rv is a scipy.stats continuous distribution.

For generating bounds given a value, we provide a few helper functions:

    v +/- d:  pm(x,dx) or pm(x,-dm,+dp) or pm(x,+dp,-dm)
        return (x-dm,x+dm) limited to 2 significant digits
    v +/- p%: pmp(x,p) or pmp(x,-pm,+pp) or pmp(x,+pp,-pm)
        return (x-pm*x/100, x+pp*x/100) limited to 2 sig. digits
    pm_raw(x,dx) or raw_pm(x,-dm,+dp) or raw_pm(x,+dp,-dm)
        return (x-dm,x+dm)
    pmp_raw(x,p) or raw_pmp(x,-pm,+pp) or raw_pmp(x,+pp,-pm)
        return (x-pm*x/100, x+pp*x/100)
    nice_range(lo,hi)
        return (lo,hi) limited to 2 significant digits

class bumps.bounds.Bounded(lo, hi)

  Bases: `bumps.bounds.Bounds`

  Bounded range.

  [lo,hi] <-> [0,1] scale is simple linear [lo,hi] <-> (-inf,inf) scale uses exponential expansion

  While technically the probability of seeing any value within the range is 1/range, for consistency with the semi-infinite ranges and for a more natural mapping between nllf and chisq, we instead set the probability to 0. This choice will not affect the fits.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.BoundedAbove(base)

  Bases: `bumps.bounds.Bounds`

  Semidefinite range bounded above.

  [-inf,base] <-> [0,1] uses logarithmic compression [-inf,base] <-> (-inf,inf) is direct below base-1, 1/(base-x) above

  Logarithmic compression works by converting sign*m*2^e+base to sign*(e+1023+m), yielding a value in [0,2048]. This can then be converted to a value in [0,1].

  Note that the likelihood function is problematic: the true probability of seeing any particular value in the range is infinitesimal, and that is indistinguishable from values outside the range. Instead we say that P = 1 in range, and 0 outside.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.BoundedBelow(base)

  Bases: `bumps.bounds.Bounds`

  Semidefinite range bounded below.

  The random initial condition is assumed to be within 1 of the maximum.

  [base,inf] <-> (-inf,inf) is direct above base+1, -1/(x-base) below [base,inf] <-> [0,1] uses logarithmic compression.

  Logarithmic compression works by converting sign*m*2^e+base to sign*(e+1023+m), yielding a value in [0,2048]. This can then be converted to a value in [0,1].

  Note that the likelihood function is problematic: the true probability of seeing any particular value in the range is infinitesimal, and that is indistinguishable from values outside the range. Instead we say that P = 1 in range, and 0 outside.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.BoundedNormal(mean=0, std=1, limits=(- inf, inf))

  Bases: `bumps.bounds.Bounds`

  truncated normal bounds

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value, or an array of values

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    For the truncated normal distribution, we can just use the normal residuals.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.Bounds

  Bases: `object`

  Bounds abstract base class.

  A range is used for several purposes. One is that it transforms parameters between unbounded and bounded forms depending on the needs of the optimizer.

  Another is that it generates random values in the range for stochastic optimizers, and for initialization.

  A third is that it returns the likelihood of seeing that particular value for optimizers which use soft constraints. Assuming the cost function that is being optimized is also a probability, then this is an easy way to incorporate information from other sorts of measurements into the model.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.Distribution(dist)

  Bases: `bumps.bounds.Bounds`

  Parameter is pulled from a distribution.

  dist must implement the distribution interface from scipy.stats. In particular, it should define methods rvs, nnlf, cdf and ppf and attributes args and dist.name.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.Normal(mean=0, std=1)

  Bases: `bumps.bounds.Distribution`

  Parameter is pulled from a normal distribution.

  If you have measured a parameter value with some uncertainty (e.g., the film thickness is 35+/-5 according to TEM), then you can use this measurement to restrict the values given to the search, and to penalize choices of this fitting parameter which are different from this value.

  mean is the expected value of the parameter and std is the 1-sigma standard deviation.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.SoftBounded(lo, hi, std=None)

  Bases: `bumps.bounds.Bounds`

  Parameter is pulled from a stretched normal distribution.

  This is like a rectangular distribution, but with gaussian tails.

  The intent of this distribution is for soft constraints on the values. As such, the random generator will return values like the rectangular distribution, but the likelihood will return finite values based on the distance from the from the bounds rather than returning infinity.

  Note that for bounds constrained optimizers which force the value into the range [0,1] for each parameter we don’t need to use soft constraints, and this acts just like the rectangular distribution.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

class bumps.bounds.Unbounded

  Bases: `bumps.bounds.Bounds`

  Unbounded parameter.

  The random initial condition is assumed to be between 0 and 1

  The probability is uniformly 1/inf everywhere, which means the negative log likelihood of P is inf everywhere. A value inf will interfere with optimization routines, and so we instead choose P == 1 everywhere.

  get01(x)

    Convert value into [0,1] for optimizers which are bounds constrained.

    This can also be used as a scale bar to show approximately how close to the end of the range the value is.

  getfull(x)

    Convert value into (-inf,inf) for optimizers which are unconstrained.

  limits = (-inf, inf)
  nllf(value)

    Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

    For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

  put01(v)

    Convert [0,1] into value for optimizers which are bounds constrained.

  putfull(v)

    Convert (-inf,inf) into value for optimizers which are unconstrained.

  random(n=1, target=1.0)

    Return a randomly generated valid value.

    target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

  residual(value)

    Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

    To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

    For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

  start_value()

    Return a default starting value if none given.

  to_dict()

bumps.bounds.init_bounds(v)

  Returns a bounds object of the appropriate type given the arguments.

  This is a helper factory to simplify the user interface to parameter objects.

bumps.bounds.nice_range(bounds)

  Given a range, return an enclosing range accurate to two digits.

bumps.bounds.pm(v, plus, minus=None, limits=None)

  Return the tuple (~v-dv,~v+dv), where ~expr is a ‘nice’ number near to to the value of expr. For example:

      >>> r = pm(0.78421, 0.0023145)
      >>> print("%g - %g"%r)
      0.7818 - 0.7866

  If called as pm(value, +dp, -dm) or pm(value, -dm, +dp), return (~v-dm, ~v+dp).

bumps.bounds.pm_raw(v, plus, minus=None)

  Return the tuple [v-dv,v+dv].

  If called as pm_raw(value, +dp, -dm) or pm_raw(value, -dm, +dp), return (v-dm, v+dp).

bumps.bounds.pmp(v, plus, minus=None, limits=None)

  Return the tuple (~v-%v,~v+%v), where ~expr is a ‘nice’ number near to the value of expr. For example:

      >>> r = pmp(0.78421, 10)
      >>> print("%g - %g"%r)
      0.7 - 0.87
      >>> r = pmp(0.78421, 0.1)
      >>> print("%g - %g"%r)
      0.7834 - 0.785

  If called as pmp(value, +pp, -pm) or pmp(value, -pm, +pp), return (~v-pm%v, ~v+pp%v).

bumps.bounds.pmp_raw(v, plus, minus=None)

  Return the tuple [v-%v,v+%v]

  If called as pmp_raw(value, +pp, -pm) or pmp_raw(value, -pm, +pp), return (v-pm%v, v+pp%v).