In [1]:
import escape as esc
esc.require("0.9.7")
from escape.utils.widgets import show

Loading material database from /home/dkor/Data/Development/workspace_escape/escape/python/src/escape/scattering/../data/mdb/materials.db

Parameters¶

Parameter_obj object is a major building block of ESCAPE library. It performs a link between created models and optimizer, which performs optimization of the parameters for the best match between modeled and experimental data. In order to create a parameter object one should use a special factory function par, which has the following arguments:

1. name - parameter name
1. value - default value
2. userlim - limits of the parameter value
3. scale - multiplicator for parameter value
4. limscale - scale for automatic limits
5. units - units of parameter
6. fixed - set to True if you would like to fix value of the parameter

Below few examples of parameter creation are given.

In [2]:
p1=esc.par("parameter 1", value=1.5, userlim=[0, 5])
p2=esc.par("parameter 2", value=2.0, scale=1e-6, userlim=[0, 5])
p3=esc.par("parameter 3", value=400.0, userlim=[0, 500])
In [3]:
p1, p2, p3
Out[3]:
(parameter(name='parameter 1', value=1.5, min=0.0, max=5.0, fixed=False),
 parameter(name='parameter 2', value=2e-06, min=0.0, max=4.9999999999999996e-06, fixed=False),
 parameter(name='parameter 3', value=400.0, min=0.0, max=500.0, fixed=False))

How to assign a value¶

There are two ways to assign parameter value:

1. by assigning to *value* property
2. by calling *force_value* method

If you try to set value outside given boundaries a warning will be generated. The force value method forces the value setting and changes boundaries.

In [4]:
p1.value = 3
print(p1)
#assigned value cannot be out of users or physical boundaries causing warning
p1.value = 10
print(p1)

parameter(name='parameter 1', value=3.0, min=0.0, max=5.0, fixed=False)
parameter(name='parameter 1', value=5.0, min=0.0, max=5.0, fixed=False)

/tmp/ipykernel_50616/3758203556.py:4: WrongValueWarning: Parameter didn't reach user value, check limits
  p1.value = 10
In [5]:
p1.force_value(10)
print(p1)

parameter(name='parameter 1', value=10.0, min=5.0, max=15.0, fixed=False)

Expressions¶

Another useful feature of parameters is that they support arithmetic operators and mathematical functions. This feature allows the user to define parameters dependencies. New parameters will observe such dependencies and certainly will be not optimized during fit. The following mathematical functions are supported: sin, cos, tan, sinh, cosh, tanh, exp, sqrt, log, log10, pow, min, max, erf

In [6]:
p4=esc.sin((p1-p2)*(p1+p2)/p1)
print(p4.value)
print(p4.independent)

-0.5440211108890345
False
In [7]:
p5=esc.min(p1, p3)
print ("p1=", p1.value, "p3=", p3.value,  "p5=", p5.value)

p1= 10.0 p3= 400.0 p5= 10.0

As you have probably noticed par factory function returns an object of type parameter_obj. Class parameter_obj has a static method convert which is responsible for conversion from int and float types to parameters. In every method which requires parameter as an input, you can, if necessary, provide a float value. The value provided by the user will be converted to parameter_obj with constant value. This parameter is considered as dependent and will be ignored by the optimizer.

To help the user setting the parameters themselves and their ranges of validity, a visual representation has been devised. A slider can be used to represent a parameter. It is easier to change a parameter's value with a slider rather than restarting each and every cell. This is an experimental feature and you will need the package escape.utils.widgets.

In [ ]:
In [8]:
show(p1)
In [9]:
show(p5)

Conditional parameters¶

Conditional parameter is the parameter which, depending on condition result, true or false, returns a value of either the first parameter or the second one, respectively. Below is an example of conditional parameter. Conditional parameters can be used everywhere where parameter is required as an input.

In [10]:
p10=esc.par("P10", 10)
p11=esc.par("P11", 8)
p12=esc.par("P12", 1)
p13=esc.par("P13", 5)
cp=esc.conditional(p11<p10, p12, p13)
show(cp)
In [ ]: