Parameters, variables, functors and kernels

The escape.core.objects module provides methods to create variables, parameters, 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 helper 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, like in functors, user provides an array of values and output array of proper length.

Kernels support parallelization, 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=u'', value=0.0, userlim=None, bool fixed=False, double scale=1.0, double limit_scale=0.5, units=u'')

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

Parameters:

value: double or str

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 helper 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, int numthreads=0, rc=None, rc_ids=None, rc_fragments=None)

Creates a kernel object for functor func. The kernel evaluates func

over successive input arrays with multithreading and cluster computation support.

New in version 0.9.7.

Added support of parallel computation in a cluster. The current implementation is based on iparallel module.

Changed in version 0.9.7.

Use numthreads argument to set exact number of threads for the computation.

Parameters:

func: functor_obj :

Functor to be called by the kernel instance.

multithreaded: bool :

Set to True to use parallel computation in CPU threads.

numthreads: int:

New in version 0.9.7.

Number of threads to use for parallel computation. If equal to 0, then all available threads are used.

rc: object, None :

New in version 0.9.7.

Cluster client instance

rc_ids: list of integers or None:

New in version 0.9.7.

IDs of engines where the kernel should be executed. If None, the kernel will be executed on all engines.

rc_fragments: None, list of floats or ‘auto’ :

New in version 0.9.7.

Defines the fragmentation of input arrays for each engine. If None the input arrays are split equally between engines. If ‘auto’, the benchmarking of CPU performance will be started on each engine to determine an optimal fragmentation of the input arrays. The fragmentation can be also specified by user as a list of float values. The number of these values should be equal to the number of engines and the sum of all fragments should be equal to unit.

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 domain size of a given functor. For example, for a given initital functor f(x, y, z), one can achieve a custom functor of reduced domain size, 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. Parameter can be defined by formula, for example: >>> par = esc.par(value=”3.0+-1.0nm”) >>> par = esc.par(value=”3.0nm”)

Parameters:

val: float, parameter_obj or str

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(value, parent_or_vars=None)

domain_size

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.

domain_size

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.

domain_size

Returns:

Number of functor variables.

name

Returns:

Kernel’s name.

num_of_params

Returns:

Number of parameters.

parameter(self, size_t i)

parameters

Returns:

List of parameters

shake(self)

Randomly change functor’s parameters.

variables

Returns:

List of variables names.