parameter - Optimization parameter definition

Alias	Parameter alias.
Calculation	A Parameter with a model-specific, calculated value.
Comparisons	comparison operators
Constant	Saved state for an unmodifiable value.
Constraint	Express inequality constraints between model elements
Expression	Parameter expression
FreeVariables	A collection of parameter sets for a group of models.
Function	DEPRECATED
HasParameters
Normal	Normal distribution (Gaussian)
OperatorMixin	The set of operations that can be performed on parameter-like objects Parameter, Constant, Expression.
Operators	Operators that can be used to construct Expressions
Parameter	A parameter is a container for a symbolic value.
ParameterSet	A parameter that depends on the model.
Reference	Create an adaptor so that a model attribute can be treated as if it were a parameter.
SupportsPrior	Parameter mixin allowing the value to be restricted to a prior probability.
Uniform	Uniform distribution with hard boundaries
UniformSoftBounded	Uniform distribution with error-function PDF on boundaries
UserFunction	User-defined functions.
ValueProtocol	Values can be combined to form expressions Provide a suite of operators for creating parameter expressions.
Variable	Saved state for a random variable in the model.
acos
acosd	Return the arc cosine (measured in in degrees) of x.
acosh
arccosd	Return the arc cosine (measured in in degrees) of x.
arcsind	Return the arc sine (measured in in degrees) of x.
arctan2d	Return the arc tangent (measured in in degrees) of y/x.
arctand	Return the arc tangent (measured in in degrees) of x.
asin
asind	Return the arc sine (measured in in degrees) of x.
asinh
atan
atan2
atan2d	Return the arc tangent (measured in in degrees) of y/x.
atand	Return the arc tangent (measured in in degrees) of x.
atanh
copy_linked	make a copy of an object with parameters
cosd	Return the cosine of x (measured in in degrees).
current
fittable	Return the list of fittable parameters in no paraticular order.
flatten
format	Format parameter set for printing.
function	Convert a function into a delayed evaluator.
make_linked_copies	make a list of <num> copies of an object with parameters
max
min
priors	Return the list of parameters (fitted or computed) that have prior probabilities associated with them.
randomize	Set random values to the parameters in the parameter set, with values chosen according to the bounds.
sind	Return the sine of x (measured in in degrees).
substitute	Return structure a with values substituted for all parameters.
summarize	Return a stylized list of parameter names and values with range bars suitable for printing.
tag_all
tand	Return the tangent of x (measured in in degrees).
test_operator
to_dict
unique	Return the unique set of parameters
untag_all
varying	Return the list of fitted parameters in the model.

Fitting parameter objects.

Parameters are a big part of the interface between the model and the fitting engine. By saving and retrieving values and ranges from the parameter, the fitting engine does not need to be aware of the structure of the model.

Users can also perform calculations with parameters, tying together different parts of the model, or different models.

class bumps.parameter.Alias(obj, attr, p=None, name=None)

Bases: object

Parameter alias.

Rather than modifying a model to contain a parameter slot, allow the parameter to exist outside the model. The resulting parameter will have the full parameter semantics, including the ability to replace a fixed value with a parameter expression.

parameters()

to_dict()

update()

class bumps.parameter.Calculation(description: str = '', function: Callable = None)

Bases: ValueProtocol

A Parameter with a model-specific, calculated value. The function used to calculate this value should be well-documented in the description field, e.g. Stack.thickness: description = “a sum of the thicknesses of all layers in the stack”

description: str

set_function(function)

property value

class bumps.parameter.Comparisons(value)

Bases: Enum

comparison operators

ge = '>='

gt = '>'

le = '<='

lt = '<'

class bumps.parameter.Constant(value: float, name: str | None = None, id: str = <factory>)

Bases: ValueProtocol

Saved state for an unmodifiable value.

A constant is like a fixed parameter. You can’t change it’s value, set it equal to another parameter, or assign a prior distribution.

fittable: bool = False

fixed: bool = True

id: str

name: str | None = None

parameters()

value: float

class bumps.parameter.Constraint(a, b, op)

Bases: object

Express inequality constraints between model elements

a: Parameter | Expression | Calculation | float

b: Parameter | Expression | Calculation | float

fixed = True

op: Comparisons

property satisfied

class bumps.parameter.Expression(op: str | Operators | UserFunction, args)

Bases: ValueProtocol

Parameter expression

args: Sequence[Expression | Parameter | Calculation | float]

fittable: bool = False

fixed: bool = True

property name

op: Operators | UserFunction

parameters()

property value

class bumps.parameter.FreeVariables(names=None, parametersets=None, **kw)

Bases: object

A collection of parameter sets for a group of models.

names is the set of model names.

The parameters themselves are specified as key=value pairs, with key being the attribute name which is used to retrieve the parameter set and value being a Parameter containing the parameter that is shared between the models.

In order to evaluate the log likelihood of all models simultaneously, the fitting program will need to call set_model with the model index for each model in turn in order to substitute the values from the free variables into the model. This allows us to share a common sample across multiple data sets, with each dataset having its own values for some of the sample parameters. The alternative is to copy the entire sample structure, sharing references to common parameters and creating new parameters for each model for the free parameters. Setting up these copies was inconvenient.

Note that using FreeVariables within a fitproblem erases any caching that happens within the model. This means, for example, that the theory function will be calculated once for plotting and again for computing χ². To avoid unnecessary cache clearing, use bool(freevars) to test if there are parameters to substitute.

get_model(i)

Get the parameters for model i as {reference: substitution}

isfree(param)

names: List[str]

parameters()

Return the set of free variables for all the models.

parametersets: Dict[str, ParameterSet]

set_model(i)

Set the reference parameters for model i.

to_dict()

class bumps.parameter.Function(op, *args, **kw)

Bases: ValueProtocol

DEPRECATED

Delayed function evaluator.

f.value evaluates the function with the values of the parameter arguments at the time f.value is referenced rather than when the function was invoked.

args: Any | None

kw: Dict[Any, Any]

op: Callable[[...], float]

parameters()

to_dict()

property value

class bumps.parameter.HasParameters(*args, **kwargs)

Bases: Protocol

parameters: Callable[[], List[Parameter] | Dict[str, Parameter]]

class bumps.parameter.Normal(std: float, mean: float)

Bases: object

Normal distribution (Gaussian)

mean: float

std: float

class bumps.parameter.OperatorMixin

Bases: object

The set of operations that can be performed on parameter-like objects Parameter, Constant, Expression.

These include: +, -, , /, //, *, abs, float, int

Also, numpy math functions: sin, cos, tan, …

Much like abs(obj) => obj.__abs__(), np.sin(obj) => obj.sin()

arccos()

arccosh()

arcsin()

arcsinh()

arctan()

arctan2()

arctanh()

ceil()

cos()

cosh()

degrees()

exp()

expm1()

floor()

log()

log10()

log1p()

max()

min()

radians()

rint()

round()

sin()

sinh()

sqrt()

tan()

tanh()

trunc()

value: float

class bumps.parameter.Operators(value)

Bases: str, Enum

Operators that can be used to construct Expressions

abs = 'abs'

add = 'add'

arccos = 'arccos'

arccosh = 'arccosh'

arcsin = 'arcsin'

arcsinh = 'arcsinh'

arctan = 'arctan'

arctan2 = 'arctan2'

arctanh = 'arctanh'

ceil = 'ceil'

cos = 'cos'

cosh = 'cosh'

degrees = 'degrees'

exp = 'exp'

expm1 = 'expm1'

floor = 'floor'

floordiv = 'floordiv'

log = 'log'

log10 = 'log10'

log1p = 'log1p'

max = 'max'

min = 'min'

mul = 'mul'

neg = 'neg'

pos = 'pos'

pow = 'pow'

radians = 'radians'

rint = 'rint'

round = 'round'

sin = 'sin'

sinh = 'sinh'

sqrt = 'sqrt'

sub = 'sub'

tan = 'tan'

tanh = 'tanh'

truediv = 'truediv'

trunc = 'trunc'

class bumps.parameter.Parameter(value: float | Tuple[float, float] | None = None, slot: Variable | Expression | Parameter | Calculation | float | None = None, fixed: bool | None = None, name: str | None = None, id: str | None = None, limits: Tuple[float | Literal[None, '-inf'], float | Literal[None, 'inf']] | None = None, bounds: Tuple[float | Literal['-inf'], float | Literal['inf']] | None = None, distribution: Uniform | Normal | UniformSoftBounded = Uniform(), discrete: bool = False, tags: List[str] | None = None)

Bases: ValueProtocol, SupportsPrior

A parameter is a container for a symbolic value.

Parameters have a prior probability, as set by a bounds constraint:

import numpy as np from scipy.stats.distributions import lognorm from bumps.parameter import Parameter

p = Parameter(3) p.pmp(10) # 3 +/- 10% uniform p.pmp(-5,10) # 3 in [2.85, 3.30] uniform p.pm(2) # 3 +/- 2 uniform p.pm(-1,2) # 3 in [2,5] uniform p.range(0,5) # 3 in [0,5] uniform p.dev(2) # 3 +/- 2 gaussian p.soft_range(2,5,2) # 3 in [2,5] uniform with gauss wings p.dev(2, limits=(0,6)) # 3 +/- 2 truncated gaussian p.pdf(lognorm(3, 1)) # lognormal centered on 3, width 1.

Parameters have hard limits on the possible values, dictated by the model. These bounds apply in addition to any other bounds.

Parameters can be constrained to be equal to another parameter or parameter expression:

a, b = Parameter(3), Parameter(4) p = Parameter(limits=(6, 10)) p.equals(a+b) assert p.nllf() == 0. # within the bounds a.value = 20 assert np.isinf(p.nllf()) # out of bounds

Constraints on the computed value follow from the constraints on the underlying parameters in addition to any hard limits on the parameter value given by the model.

Inputs

value can be a constant, a variable, an expression or a link to another parameter.

bounds are user-supplied limits on the parameter value within the model. If bounds are supplied then the parameter defaults to fittable.

distribution is one of Uniform, Normal or UniformSoftBounded classes

fixed is True if the parameter is fixed, even if bounds are supplied.

name is the label associated with the parameter in plots. The names need not be unique, but it will be confusing if there are duplicates. The name will usually correspond to the role of the parameter in the model. For models with sequences (e.g., layer numbers), try using a layer name (e.g., based on the material in the layer) rather than a layer number for parameters in that layer. This will make it easier for the user to associate the parameters displayed at the end of the the fit with the layer in the model. Also, when exploring the space of models, the parameter names will be preserved even if a new layer is introduced before the existing layers. That will allow the parameters from the previous fit to be easily used as a seed for the fit to the new model.

id must be a unique identifier associated with the parameter. This is used to link parameters on save and reload.

limits are hard limits on the parameter value within the model. Separate from the prior distribution on a random variable provided by the user, the hard limits are restrictions on the value imposed by the model. For example, the thickness of a layer must be zero or more.

discrete is True if the parameter value must be an integer.

tags are user-supplied labels that can be used to group parameters together for display or for setting values, and are used in the GUI for filtering parameters.

add_tag(tag: str)

bounds: Tuple[float | Literal['-inf'], float | Literal['inf']] | None = None

static calculation(obj: Parameter | None, name: str, function: Callable[[], float]) → Parameter

Create a parameter to hold a value derived from the model. This can be used in parameter expressions, for example to constrain total thickness or to set the value in the next segment equal to the value at the end of a freeform segment.

Note that this function should be called in the __init__ or __post_init__ methods of the class where the parameter is defined, in order to bind the Calculation function to the newly created (or deserialized) Parameter before it is used.

If obj is a Parameter, use it - otherwise create a new Parameter obj with the given name.

Then create a Calculation object and attach the evaluator function to the Calculation, and put the Calculation in obj.slot

Returns obj: Parameter

clip_set(value)

Set a new value for the parameter, clipping it to the bounds.

classmethod default(value: float | Tuple[float, float] | Expression | Parameter | Calculation, **kw) → Parameter

Create a new parameter with the value and kw attributes. If value is already a parameter or expression, set it to that value.

dev(std, mean=None, limits=None, sigma=None, mu=None)

Allow the parameter to vary according to a normal distribution, with deviations from the mean added to the overall cost function for the model.

If mean is None, then it defaults to the current parameter value.

If limits are provide, then use a truncated normal distribution.

Note: sigma and mu have been replaced by std and mean, but are left in for backward compatibility.

discrete: bool = False

distribution: Uniform | Normal | UniformSoftBounded

equals(expression: Expression | Parameter | Calculation | float)

Set a parameter equal to another parameter or expression.

Use unlink() to convert from an expression to a variable.

feasible()

Value is within the limits defined by the model

property fittable

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property fixed

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

format()

Format the parameter, value and range as a string.

id: str

limits: Tuple[float | Literal['-inf'], float | Literal['inf']] = (-inf, inf)

name: str | None = None

nllf() → float

Return -log(P) for the current parameter value.

parameters()

pm(plus, minus=None, limits=None)

Allow the parameter to vary as value +/- delta.

pm(delta) -> [value-delta, value+delta]

pm(plus, minus) -> [value+minus, value+plus]

In the plus/minus form, one of the numbers should be plus and the other minus, but it doesn’t matter which.

If limits are provided, bound the end points of the range to lie within the limits.

The resulting range is converted to “nice” numbers.

pmp(plus, minus=None, limits=None)

Allow the parameter to vary as value +/- percent.

pmp(percent) -> [value*(1-percent/100), value*(1+percent/100)]

pmp(plus, minus) -> [value*(1+minus/100), value*(1+plus/100)]

In the plus/minus form, one of the numbers should be plus and the other minus, but it doesn’t matter which.

If limits are provided, bound the end points of the range to lie within the limits.

The resulting range is converted to “nice” numbers.

randomize(rng=None)

Set a random value for the parameter.

range(low, high)

Allow the parameter to vary within the given range.

remove_tag(tag: str | None = None)

residual() → float

Return the z score equivalent for the current parameter value.

That is, the given the value of the parameter in the underlying distribution, find the equivalent value in the standard normal. For a gaussian, this is the z score, in which you subtract the mean and divide by the standard deviation to get the number of sigmas away from the mean. For other distributions, you need to compute the cdf of value in the parameter distribution and invert it using the ppf from the standard normal distribution.

set(value)

Set a new value for the parameter, ignoring the bounds.

slot: Variable | Expression | Parameter | Calculation | float

soft_range(low, high, std)

Allow the parameter to vary within the given range, or with Gaussian probability, stray from the range.

tags: List[str]

unlink()

valid()

Return true if the parameter is within the valid range.

property value

class bumps.parameter.ParameterSet(reference: Parameter, names: List[str] | None = None, parameterlist: List[Parameter] | None = None)

Bases: object

A parameter that depends on the model.

get_model(index)

Get the reference and underlying model parameter for the nth model.

names: List[str] | None

property parameterlist: List[Parameter]

pm(*args, **kw)

Like Parameter.pm(), but applied to all models.

pmp(*args, **kw)

Like Parameter.pmp(), but applied to all models.

range(*args, **kw)

Like Parameter.range(), but applied to all models.

reference: Parameter

set_model(index)

Set the underlying model parameter to the value of the nth model.

to_dict()

property values

class bumps.parameter.Reference(obj, attr, **kw)

Bases: Parameter

Create an adaptor so that a model attribute can be treated as if it were a parameter. This allows only direct access, wherein the storage for the parameter value is provided by the underlying model.

Indirect access, wherein the storage is provided by the parameter, cannot be supported since the parameter has no way to detect that the model is asking for the value of the attribute. This means that model attributes cannot be assigned to parameter expressions without some trigger to update the values of the attributes in the model.

NOTE: this class can not be serialized with a dataclass schema TODO: can sasmodels just use Parameter directly?

property value

class bumps.parameter.SupportsPrior

Bases: object

Parameter mixin allowing the value to be restricted to a prior probability.

Every prior has hard limits and bounds.

bounds: Unbounded | Bounded | BoundedAbove | BoundedBelow | BoundedNormal | SoftBounded | Normal

distribution: Uniform | Normal | UniformSoftBounded

limits: Tuple[float, float]

prior: Unbounded | Bounded | BoundedAbove | BoundedBelow | BoundedNormal | SoftBounded | Normal | None

reset_prior()

class bumps.parameter.Uniform

Bases: object

Uniform distribution with hard boundaries

class bumps.parameter.UniformSoftBounded(std: float)

Bases: object

Uniform distribution with error-function PDF on boundaries

std: float

class bumps.parameter.UserFunction(fn: Callable)

Bases: object

User-defined functions.

This is a helper class for the @function decorator, which treats the operator as one of the possible expression operators.

These won’t be properly serialized/deserialized through the JSON schema unless the function is registered in advance. The schema will not include these functions as possible values even if registered, so a schema validator may fail on one of these functions.

name: str

class bumps.parameter.ValueProtocol

Bases: OperatorMixin

Values can be combined to form expressions Provide a suite of operators for creating parameter expressions.

fittable: bool = False

fixed: bool = True

parameters() → List[Parameter]

value: float

class bumps.parameter.Variable(value: float)

Bases: ValueProtocol

Saved state for a random variable in the model.

parameters()

value: float

bumps.parameter.acos(*args)

bumps.parameter.acosd(*args: Parameter | Expression | Calculation | float)

Return the arc cosine (measured in in degrees) of x.

bumps.parameter.acosh(*args)

bumps.parameter.arccosd(*args: Parameter | Expression | Calculation | float)

Return the arc cosine (measured in in degrees) of x.

bumps.parameter.arcsind(*args: Parameter | Expression | Calculation | float)

Return the arc sine (measured in in degrees) of x.

bumps.parameter.arctan2d(*args: Parameter | Expression | Calculation | float)

Return the arc tangent (measured in in degrees) of y/x. Unlike atan(y/x), the signs of both x and y are considered.

bumps.parameter.arctand(*args: Parameter | Expression | Calculation | float)

Return the arc tangent (measured in in degrees) of x.

bumps.parameter.asin(*args)

bumps.parameter.asind(*args: Parameter | Expression | Calculation | float)

Return the arc sine (measured in in degrees) of x.

bumps.parameter.asinh(*args)

bumps.parameter.atan(*args)

bumps.parameter.atan2(*args)

bumps.parameter.atan2d(*args: Parameter | Expression | Calculation | float)

Return the arc tangent (measured in in degrees) of y/x. Unlike atan(y/x), the signs of both x and y are considered.

bumps.parameter.atand(*args: Parameter | Expression | Calculation | float)

Return the arc tangent (measured in in degrees) of x.

bumps.parameter.atanh(*args)

bumps.parameter.copy_linked(has_parameters: HasParameters, exclude: List[Parameter] | None = None) → HasParameters

make a copy of an object with parameters

• then link all the parameters, except

• those in exclude

bumps.parameter.cosd(*args: Parameter | Expression | Calculation | float)

Return the cosine of x (measured in in degrees).

bumps.parameter.current(s: List[Parameter])

bumps.parameter.fittable(s)

Return the list of fittable parameters in no paraticular order.

Note that some fittable parameters may be fixed during the fit.

bumps.parameter.flatten(s)

bumps.parameter.format(p, indent=0, freevars=None, field=None)

Format parameter set for printing.

Note that this only says how the parameters are arranged, not how they relate to each other.

Note that freevars here is the substitution dictionary returned by FreeVars.get_model(i), not the FreeVars object itself.

bumps.parameter.function(fn: Callable)

Convert a function into a delayed evaluator.

The value of the function is computed from the values of the parameters at the time that the function value is requested rather than when the function is created.

Wrapped functions are automatically added to bumps.pmath

bumps.parameter.make_linked_copies(has_parameters: HasParameters, num: int = 1, exclude: List[Parameter] | None = None) → List[HasParameters]

make a list of <num> copies of an object with parameters

• then link all the parameters, except

• those in exclude

bumps.parameter.max(Parameter)

bumps.parameter.min(Parameter)

bumps.parameter.priors(s: List[Parameter]) → List[Parameter]

Return the list of parameters (fitted or computed) that have prior probabilities associated with them. This may include parameters linked to expressions and parameters that are not fitted, but excludes parameters that are unbounded.

bumps.parameter.randomize(s: List[Parameter])

Set random values to the parameters in the parameter set, with values chosen according to the bounds.

bumps.parameter.sind(*args: Parameter | Expression | Calculation | float)

Return the sine of x (measured in in degrees).

bumps.parameter.substitute(a)

Return structure a with values substituted for all parameters.

The function traverses lists, tuples and dicts recursively. Things which are not parameters are returned directly.

bumps.parameter.summarize(pars, sorted=False)

Return a stylized list of parameter names and values with range bars suitable for printing.

If sorted, then print the parameters sorted alphabetically by name.

bumps.parameter.tag_all(parameter_tree, tag, remove=False)

bumps.parameter.tand(*args: Parameter | Expression | Calculation | float)

Return the tangent of x (measured in in degrees).

bumps.parameter.test_operator()

bumps.parameter.to_dict(p)

bumps.parameter.unique(s) → List[Parameter]

Return the unique set of parameters

The ordering is stable. The same parameters/dependencies will always return the same ordering, with the first occurrence first.

bumps.parameter.untag_all(parameter_tree, tag: str | None = None)

bumps.parameter.varying(s: List[Parameter]) → List[Parameter]

Return the list of fitted parameters in the model.

This is the set of parameters that will vary during the fit.