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.objects.par(name: str = '', value: Union[float, int, str] = 0.0, userlim: Optional[UserLimitLike] = 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.objects.var(names: Union[str, List[str], Tuple[str, ...]] = 'X') Union[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.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, val: complex) cplx_functor_obj¶
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, func: functor_obj, x=None, y=None) 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
- 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.reduce(name, func, var: variable_obj, value: Union[float, int, str, parameter_obj], *args) Union[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
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: Union[bool_parameter_obj, bool_functor_obj], ret_true: Union[float, int, str, parameter_obj, functor_obj, cplx_functor_obj, variable_obj], ret_false: Union[float, int, str, parameter_obj, functor_obj, cplx_functor_obj, variable_obj]) Union[functor_obj, parameter_obj]¶
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[bool_parameter_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 bool_parameter_obj, otherwise returns functor_obj.
- Raises:
TypeError: If cond is not bool_parameter_obj or bool_functor_obj
- class escape.core.objects.parameter_obj¶
Wrapper for dependent or independent parameters.
This class wraps C++ parameter objects and provides a Python interface for parameter manipulation. Parameters can be either independent (directly settable values) or dependent (calculated from other parameters).
- static convert(val: Union[float, int, str, parameter_obj], name: str = '', **kwargs) parameter_obj¶
Convert a value to a parameter object.
Parameters can be defined by formula, for example: >>> par = esc.par(value=”3.0+-1.0nm”) # Value with error >>> par = esc.par(value=”3.0nm”) # Value with units >>> par = esc.par(value=”1<=3.0<=4 nm”) # Value with bounds and units
- Args:
val: Value to convert (float, parameter_obj or str) name: Optional name for the parameter **kwargs: Additional arguments for independent parameters
- Returns:
parameter_obj: New parameter object
- Raises:
TypeError: If val has invalid type
- error¶
Parameter error after optimization.
- Returns:
float: The error value
- fixed¶
Whether the parameter is fixed during optimization.
Fixed parameters are recognized and shown by optimizer but their value is fixed during fitting.
- Returns:
bool: True if parameter is fixed
- force_value(val: float) bool¶
Set parameter value and new boundaries.
Sets value and adjusts boundaries relative to this value and limit_scale. Can only be used with independent parameters.
- Args:
val: New value to set
- Returns:
bool: True if successful
- Raises:
RuntimeError: If parameter is dependent
- get_unscaled_limits() list[float]¶
Get unscaled parameter boundaries.
- Returns:
list[float]: [min, max] list of boundary values
- static grammar(name: str, **kwargs) Any¶
Get grammar for parsing parameter expressions.
- Args:
name: Name for created parameters **kwargs: Additional parameter arguments
- Returns:
Grammar: pyparsing grammar object
- id¶
The parameter’s unique identifier.
- Returns:
int: The parameter ID
- independent¶
Whether the parameter is independent.
- Returns:
bool: True if parameter is independent
- max¶
Maximum value boundary.
- Returns:
float: The maximum allowed value
- min¶
Minimum value boundary.
- Returns:
float: The minimum allowed value
- name¶
The parameter’s name.
- Returns:
str: The parameter name
- parameters¶
Get dependent parameters.
- Returns:
list[parameter_obj]: List of parameters this depends on
- scale¶
Parameter value scale.
- Returns:
float: The scale value
- set_limits(minval: float, maxval: float) None¶
Set parameter value boundaries.
Can only be set for independent parameters.
- Args:
minval: Minimum allowed value maxval: Maximum allowed value
- Raises:
RuntimeError: If parameter is dependent
- shake(seed: int = -1) None¶
Randomly perturb the parameter value.
- Args:
seed: Random seed to use, or -1 for random
- trained¶
Whether the parameter is used by neural network regressor.
- Returns:
bool: True if parameter is trained
- units¶
The parameter’s units.
- Returns:
str: The units string
- value¶
The parameter’s current value.
- Returns:
float: The parameter value
- weight¶
Parameter weight used in optimization.
- Returns:
float: The parameter’s weight value
- class escape.core.objects.functor_obj¶
Wrapper for double functor.
A functor represents a mathematical function that can be evaluated with variables and parameters. This class wraps the C++ functor_t implementation.
- constrain(val: bool_parameter_obj) None¶
Add constraint to functor.
- Args:
val: Boolean parameter to use as constraint
- constraints¶
Get list of constraints on this functor.
- Returns:
List[bool_parameter_obj]: List of boolean parameter objects
- static convert(value: Union[functor_obj, cplx_functor_obj, variable_obj, float, int, str, parameter_obj], parent_or_vars: Optional[Union[functor_obj, cplx_functor_obj, variable_obj, list[escape.core.objects.variable_obj]]] = None) functor_obj¶
Convert value to functor.
- Args:
value: Value to convert - can be functor, variable, parameter etc. parent_or_vars: Parent functor or list of variables to use
- Returns:
functor_obj: New functor representing converted value
- Raises:
TypeError: If value or parent_or_vars have unsupported types
- is_feasible¶
Check if functor is feasible (satisfies all constraints).
- Returns:
bool: True if feasible, False otherwise
- name¶
Get name of functor.
- Returns:
str: Name of functor
- num_variables¶
Get number of variables in this functor.
- Returns:
int: Number of variables
- parameters¶
Get list of parameters used in this functor.
- Returns:
List[parameter_obj]: List of parameter objects
- show(coordinates: Optional[ndarray] = None, config: Optional[Any] = None, **kwargs) Any¶
Show kernel object in a widget.
- unconstrain(val: bool_parameter_obj) None¶
Remove constraint from functor.
- Args:
val: Boolean parameter constraint to remove
- variables¶
Get list of variables used in this functor.
- Returns:
List[variable_obj]: List of variable objects
- class escape.core.objects.cplx_functor_obj¶
A class representing a complex functor.
This class provides operator overloading to allow complex functors to be used in mathematical expressions with variables, parameters, functors, and numeric values. Supports arithmetic operations and comparisons.
The complex functor object holds a pointer to a C++ cplx_functor_t instance that handles the underlying implementation.
- constrain(val: bool_parameter_obj) None¶
Add constraint to functor.
- Args:
val: Boolean parameter constraint to add
- constraints¶
Get list of constraints on functor.
- Returns:
List[bool_parameter_obj]: List of constraints
- is_feasible¶
Check if functor satisfies all constraints.
- Returns:
bool: True if functor is feasible, False otherwise
- name¶
Get name of functor.
- Returns:
str: Name of functor
- num_variables¶
Get number of variables used in functor.
- Returns:
int: Number of variables
- parameters¶
Get list of parameters used in functor.
- Returns:
List[parameter_obj]: List of parameters
- unconstrain(val: bool_parameter_obj) None¶
Remove constraint from functor.
- Args:
val: Boolean parameter constraint to remove
- variables¶
Get list of variables used in functor.
- Returns:
List[variable_obj]: List of variables
- class escape.core.objects.variable_obj¶
A class representing a variable in mathematical expressions.
This class provides operator overloading to allow variables to be used in mathematical expressions with other variables, parameters, functors, and numeric values. Supports arithmetic operations, comparisons, and power operations.
The variable object holds a pointer to a C++ variable_t instance that handles the underlying implementation.
- name¶
Get the name of the variable.
- Returns:
str: The variable’s name