Parameters, variables, and functors¶

The escape.core.objects module provides methods to create variables, parameters, and functors.

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).

escape.core.entities.par(name: str = 'Parameter', value: float | int | str = 0.0, userlim: UserLimitLike | None = None, fixed: c_bool = False, scale: float = 1.0, limit_scale: float = 0.5, units: str = '', trained: c_bool = False) → parameter_obj¶

Create a new independent parameter object.

Args:: name: Parameter name value: Initial parameter value. Can be a number or string expression userlim: Optional parameter boundaries as (min, max) tuple or list fixed: If True, parameter value will not be optimized scale: Parameter value scale factor limit_scale: Scale factor for automatic boundary calculation when userlim is None units: Parameter units string trained: If True, parameter will be used by neural network regressor
Returns:: A new parameter_obj instance
Raises:: TypeError: If value is not a float, int or str

The parameter can be created either from a numeric value or a string expression. If created from a string, it will be parsed into a dependent parameter. If created from a number, it will be an independent parameter.

For independent parameters, boundaries can be set explicitly via userlim, or calculated automatically based on the value and limit_scale.

escape.core.entities.var(names: str | List[str] | Tuple[str, ...] = 'X') → variable_obj | List[variable_obj]¶

Create one or more variable objects with the given name(s).

This helper function creates variable objects that can be used in mathematical expressions. Variables are the basic building blocks for creating functors and expressions.

Args:

names: Name or list of names for the variables. Defaults to “X”.: If a single string is provided, creates one variable with that name. If a list/tuple of strings is provided, creates multiple variables.

Returns:

If names is a single string:: A single variable_obj with the given name
If names is a list/tuple:: A list of variable_obj instances, one for each provided name

Examples:

Create a single variable: >>> x = var(“x”) >>> x variable(name=’x’)

Create multiple variables: >>> x, y = var([“x”, “y”]) >>> x, y (variable(name=’x’), variable(name=’y’))

escape.core.entities.func(x, val, name: str = 'Const Functor')¶

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

Parameters:

x: list: Variables list.
val: double value or parameter_obj: Constant value or parameter value which functor will return when being called.
name: string: Name of the functor.

Returns:

Instance of functor_obj.

escape.core.entities.cfunc(x, val: complex, name: str = 'Const Complex Functor') → cplx_functor_obj¶

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

Parameters:

x: list: Variables list.
val: double complex value: Constant double complex value which functor will return when being called.
name: string: Name of the functor.

Returns:

Instance of cplx_functor_obj.

escape.core.entities.scale(func: functor_obj, x=None, y=None, name: str = 'Scaled Functor') → functor_obj¶

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
x: tuple or list, optional: X ranges to scale functor to. If None x=[0, 1]
y: tuple or list, optional: Y ranges to scale functor to. If None y=[0, 1]
name: string: Name of the functor.

Returns:

Instance of functor_obj.

escape.core.entities.reduce(func, var: variable_obj, value: float | int | str | parameter_obj, *args, name: str = 'Reduced Functor') → functor_obj | cplx_functor_obj¶

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 var: variable_obj

Variable to be bound

value: ParameterLike: Constant float value or parameter for bound variable.
args: list: Other pairs of variables and values
name: string: Name of the functor.

Returns:

Instance of functor_obj or cplx_functor_obj depending on func type.

Create a conditional parameter or functor based on a boolean condition.

This function creates a conditional parameter or functor that returns either ret_true or ret_false based on the evaluation of the condition.

Args:

cond (Union[constraint_obj, bool_functor_obj]): The boolean condition to evaluate ret_true (Union[ParameterLike, FunctorLike]): Value to return when condition is True ret_false (Union[ParameterLike, FunctorLike]): Value to return when condition is False

Returns:

Union[functor_obj, parameter_obj]: A conditional parameter or functor.: Returns parameter_obj if cond is constraint_obj, otherwise returns functor_obj.

Raises:

TypeError: If cond is not constraint_obj or bool_functor_obj

escape.core.entities.setting(label: str, value: int | float | str | bool, units: str = '', readonly: bool = False) → setting_obj¶

Create a new setting with the given label, value, units and readonly flag.

Parameters¶

label :: Setting label describing its purpose.
value :: Setting value; can be int, float, str or bool.
units :: Optional units for the setting value.
readonly :: If True, the setting value cannot be modified.

Returns¶

setting_obj: A setting object whose underlying C++ type is chosen based on the Python type of value.

Raises¶

NotImplementedError: If value is of an unsupported type.