Parameters, variables, functors and kernels

Model parameters

There are two types of model parameters in ESCAPE: independent and dependent. Both are represented by parameter_obj type. Independent parameters are optimized during curve fitting by optimizer. Dependent parameters are those which are defined, for example, with algebraic expressions. Since both have the same type, user can control dependencies of parameters in a single model or between several models.

This gives a lot of flexibility. For example, one layer in your sample has a parameter T - thickness with initial value of \(100\quad nm\) And you know that every next layer is \(\delta T=10\quad nm\) larger, than previous. You can define thiknesses of layers as following:

>>> T = esc.par("T", 100, units="nm")
>>> dT = esc.par("dT", 10, units="nm")
>>> T1 = T + dT
>>> T2 = T + 2*dT
>>> T3 = T + 3*dT

T1, T2, T3 are dependent parameters. User can use them as input parameters for layer objects and optimizer will optimize only T and dt which are independent.

Parameters support all elementary mathematical functions including trigonometric, for example, dependent parameter can be defined as following

>>> S = esc.sin(T)*esc.cos(T)

The boundaries of independent parameter are set by default to \(\pm 50\%\) of initial value, when are not specified by user. If intitial value is zero, default boundaries are also set to zero. For more details, check full docs for par function below.

Variables and functors.

In ESCAPE functor object fo type functor_obj represents mathematical function of given variables. ESCAPE supports functors of maximum five variables.

Variable is declared as following:

>>> x = esc.var('X')
>>> y = esc.var('Y')

Functors can be defined by user as a mathematical expression, for example, one-dimensional functor:

>>> F1 = esc.sin(x)*esc.cos(x)

or two-dimensional functor

>>> F2 = esc.sin(x)*esc.cos(y)

Special functors can be created by factory functions. Special functors normally represent a more complicated, than a simple mathematical expression, problem. For example, esc.average or esc.specrefl for the calculation of averaging integral or specular reflectivity, respectively. The advantage of this approach is a customization of any scattering problem not only in terms of parameters, but also in terms of final intensity formula. User can easily add custom non-linear background or special illumination correction.

A functor instance returns calculated value when being called

>>> F2(1.0, 2.3)
0.01743834

There are two types of functors in ESCAPE: functor_obj - double functor and cplx_functor_obj - functor which returns complex value. There is also a bool_functor_obj, which returns boolean value, but it is used as a part of conditional functor only (see below).

Kernel

Kernel objects of type kernel_obj do a little, but important job. They run functors in serial mode. When kernel is called, instead of values of variables as input arguments, user provides an array of values and output array of proper length.

Kernels support parallelisation, effectively splitting input arrays among all available CPU cores. Currently, kernels support functors of type functor_obj and work with double values only.

For more details, see example notebooks.

escape.core.objects.par(name='', double value=0.0, userlim=None, bool fixed=False, double scale=1.0, double limit_scale=0.5, units='arbitr.')

Given name name, and value value, this function returns a new independent parameter object.

Parameters
value: double

Initial parameter value.

userlim: list with min and max values

Parameter boundaries.

fixed: boolean

Values of fixed Parameters are not optimized.

scale: double

Parameter value scale.

limit_scale:

if userlim is None, boundaries are set automatically in the range +-limit_scale*value

units: string

Parameter units.

Returns

instance of parameter_obj

escape.core.objects.var(names='X')

Given name name, this factory function returns a new variable object.

Parameters
names: string, list or tuple

Variable name or list of names.

Returns

if a list of names is provided as argument, than returns tuple with items of variable_obj type or single variable_obj.

escape.core.objects.func(name, x, val)

Given name name, variables list x and value or parameter val, this function returns const double functor instance.

Parameters
name: string

Name of the functor.

x: list

Variables list.

val: double value or parameter_obj

Constant value or parameter value which functor will return when being called.

Returns

Instance of functor_obj.

escape.core.objects.cfunc(name, x, double complex val)

Given name name, variables list x and complex value val, this function returns const complex functor instance.

Parameters
name: string

Name of the functor.

x: list

Variables list.

val: double complex value

Constant double complex value which functor will return when being called.

Returns

Instance of cplx_functor_obj.

escape.core.objects.scale(name, functor_obj func, x=None, y=None)

Scale functor to \(Af(x)+B\) so that it crosses (x1, y1) and (x2, y2) points.

Parameters
func: functor_obj

Functor of one-variable to scale

y: tuple or list

Y ranges to scale functor to. If None y=[0, 1]

x: tuple or list

X ranges to scale functor to. If None x=[0, 1]

Returns

Instance of functor_obj.

escape.core.objects.kernel(name, functor_obj func, bool multithreaded=True)

Creates a kernel oobject for functor func with or without multihtread support.

Parameters
func; functor_obj

Functor to be called by the kernel instance.

multithreaded: boolean:

Multithread support on or off. Default - on.

Returns

Instance of kernel_obj.

escape.core.objects.reduce(name, func, variable_obj var, value, *args)

Returns functor_obj or cplx_functor_obj instance which binds variables with constant values or parameters and reduces dimensionality of a given functor. For example, for a given initital functor f(x, y, z), one can achieve a custom functor of reduced dimensions, f2(x)=f(x, y=2, z=3) by

>>> f2=reduce(f1, y, 2, z, 3) 
Parameters
func: functor_obj or cplx_functor_obj

Name of the functor.

var: variable_obj

Variable to be bound

value: parameter_obj or float value

Constant float value or parameter for bound variable.

args: list

Other pairs of variables and values

Returns

Instance of functor_obj or cplx_functor_obj depending on func type.

escape.core.objects.conditional(cond, ret_true, ret_false)

Given condition of type bool_parameter_obj or bool_functor_obj and ret_true and ret_false parameters or functors, this function returns conditional parameter or functor, which when being called returns value of ret_true or ret_false, depending on result of condition.

Parameters
cond: bool_parameter_obj or bool_functor_obj

Condition.

ret_true: parameter_obj or functor_obj

Parameter or function to be called if condition returns True.

ret_false: parameter_obj or functor_obj

Parameter or function to be called if condition returns False.

Returns

Instance of functor_obj or parameter_obj depending on type of cond.

escape.core.objects.rotate2d(name, func, variable_obj x0, variable_obj x1, adeg)

Returns rotated functor_obj or cplx_functor_obj instance with coordinates x0 and x1.

Parameters
func: functor_obj or cplx_functor_obj

Name of the functor.

x0: variable_obj

Variable x0.

x1: variable_obj

Variable x1.

adeg: double value or parameter_obj

Rotation angle.

Returns

Instance of functor_obj or cplx_functor_obj depending on func type.

class escape.core.objects.parameter_obj

Wrapper for dependent or independent parameters.

static convert(val, name='')

Converts val to parameter.

Parameters
val: float or parameter_obj

Value to convert.

Returns

Instance of parameter_obj.

error
Returns

Parameter error after optimization.

fixed

Fixed parameters are recognized and shown by optimizer but their value is fixed during fitting.

Returns

True if parameter is fixed, otherwise False.

force_value(self, double val)

Set parameter value and new boundaries relative to this value and limit_scale parameter.

get_unscaled_limits(self)

Returns unscaled parameter boundaries.

Returns

list(min, max)

get_unscaled_value(self)

Returns unscaled parameter value.

Returns

double value

id
Returns

Parameter id.

independent
Returns

True if parameter is independent.

max
Returns

Maximum value boundary.

min
Returns

Minimum value boundary.

name
Returns

Parameter value.

num_of_params
Returns

If parameter is dependent, returns number of independent parameters it depends on.

parameter(self, size_t i)
Returns

If parameter is dependent, returns independent parameter with index i

scale
Returns

Parameter value scale.

set_limits(self, double minval, double maxval)

Set parameter value boundaries.

units
Returns

Parameter units.

value
Returns

Parameter value.

class escape.core.objects.functor_obj

Wrapper for double functor.

static convert(val, parent=None)
dimensions
Returns

Number of variables.

name
Returns

Name of functor instance.

num_of_params
Returns

Number of parameters.

parameter(self, size_t i)
Returns

Parameter with index i

variables
Returns

List of variables names.

class escape.core.objects.cplx_functor_obj

Wrapper for complex functor.

dimensions
Returns

Number of variables.

name
Returns

Name of the functor.

num_of_params
Returns

Number of parameters.

parameter(self, size_t i)
Returns

Name of the functor.

variables
Returns

List of variables names.

class escape.core.objects.kernel_obj

Wrapper for ESCAPE kernel implementation.

dimensions
Returns

Number of functor variables.

name
Returns

Kernel’s name.

num_of_params
Returns

Number of parameters.

parameter(self, size_t i)
shake(self)

Randomly change functor’s parameters.