Multilayers#

This module provides factory functions for creating multilayer and layer objects compatible with the C++ scattering API.

Main types: - roughness_obj: Surface roughness parameters (RMS, lateral correlation, Hurst). - layer_obj: Single layer (material, thickness, roughness); use layer, substrate, or env. - layerstack_obj: Repeating stack of layers; use layer_stack. - multilayer_obj: Full stack with foreground and substrate; use multilayer.

Factory functions accept optional name and notes (object label and user notes). They are used for High Resolution X-ray Diffraction, Neutron and X-ray Specular Reflectivity, and Polarized Neutron Reflectivity.

escape.scattering.layer.layer(material: MaterialLike, thkn: ParameterLike = 10, rough: ParameterLike = 1, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, name: str = 'Layer', notes: str = '', **param_kwargs) → layer_obj#

Returns a layer object.

Parameters:

material: MaterialLike: Material object.
thkn: ParameterLike: Layer thickness.
rough: ParameterLike: RMS roughness.
bydensity: bool, optional: If True, the material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
name: str, optional: Layer name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters (e.g. thkn_userlim, density_fixed).

Returns:

object of type ‘layer_obj’

escape.scattering.layer.magnetic_layer(material: MaterialLike, b_phi: ParameterLike, b_theta: ParameterLike, thkn: ParameterLike, rough: ParameterLike, delta_phi: ParameterLike = None, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, name: str = 'Magnetic Layer', notes: str = '', **param_kwargs) → layer_obj#

Returns magnetic layer object. The magnetization angles \(\phi\) and \(\theta\) define the magnetization components in the sample coordinate system as:

\[M_x = cos(\phi) sin(\theta), \quad M_y = sin(\phi), \quad M_z = cos(\phi) cos(\theta)\]

The sample coordinate system is right-handed with X-axis towards the detector and Z-axis normal to the sample plane. The angles are for samples installed vertically (external field along sample Y-axis).

Parameters:

material: MaterialLike: Material object.
b_phi: ParameterLike: \(\phi\) angle in degrees (layer magnetization vs XZ plane).
b_theta: ParameterLike: \(\theta\) angle in degrees (projection on XZ vs Z-axis).
thkn: ParameterLike: Layer thickness.
rough: ParameterLike: RMS roughness.
delta_phi: ParameterLike, optional: In-layer magnetisation rotation angle in degrees. Models helical or spiral magnetic structures (Fortran: delta_phi per layer). The effective magnetic optical potential is scaled by \(|\sin(\delta\phi)|\); None or 0 means no modulation (full magnetism used, default behaviour).
bydensity: bool, optional: If True, material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
name: str, optional: Layer name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters (e.g. thkn_userlim, density_fixed).

Returns:

object of type ‘layer_obj’

escape.scattering.layer.substrate(material: MaterialLike, rough: ParameterLike, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, name: str = 'Substrate', notes: str = '', **param_kwargs) → layer_obj#

Returns a substrate instance (semi-infinite bottom layer).

Parameters:

material: MaterialLike: Material object.
rough: ParameterLike: RMS roughness.
bydensity: bool, optional: If True, material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
name: str, optional: Layer name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters (e.g. thkn_userlim, density_fixed).

Returns:

object of type layer_obj

escape.scattering.layer.magnetic_substrate(material: MaterialLike, b_phi: ParameterLike, b_theta: ParameterLike, rough: ParameterLike, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, name: str = 'Magnetic Substrate', notes: str = '', **param_kwargs) → layer_obj#

Returns a magnetic substrate object. Magnetization angles \(\phi\) and \(\theta\) define components in the sample coordinate system (right-handed, X towards detector, Z normal to plane; vertical installation, field along Y).

Parameters:

material: MaterialLike: Material object.
b_phi: ParameterLike: \(\phi\) angle in degrees.
b_theta: ParameterLike: \(\theta\) angle in degrees.
rough: ParameterLike: RMS roughness.
bydensity: bool, optional: If True, material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
name: str, optional: Layer name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters.

Returns:

object of type layer_obj

escape.scattering.layer.env(material: MaterialLike, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, name: str = 'Environment', notes: str = '', **param_kwargs) → layer_obj#

Returns a foreground (environment) layer (semi-infinite top layer).

Parameters:

material: MaterialLike: Material object.
bydensity: bool, optional: If True, material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
name: str, optional: Layer name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters.

Returns:

object of type ‘layer_obj’

escape.scattering.layer.air(name: str = 'Air', notes: str = '') → layer_obj#

Returns an air foreground (environment) layer.

Parameters:

name: str, optional: Layer name.
notes: str, optional: User notes for the object.

Returns:

object of type ‘layer_obj’

escape.scattering.layer.layer_stack(formula: str = '', repeat: int = 1, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, globals: dict = {}, name: str = 'Layer Stack', notes: str = '', **param_kwargs) → layerstack_obj#

Creates layer stack instance (repeating sequence of layers).

Parameters:

formula: str, optional: Layer stack formula (if non-empty, parsed to build the stack).
repeat: int, optional: Repetition count of the stack.
bydensity: bool, optional: If True, material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
globals: dict, optional: Global variables for formula parsing.
name: str, optional: Layer stack name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters.

Returns:

object of type ‘layerstack_obj’

escape.scattering.layer.multilayer(formula: str = '', frgr: Optional[layer_obj] = None, bkgr: Optional[layer_obj] = None, bydensity: bool = False, mdb: mdb_obj = <escape.scattering.mdb.mdb_obj object>, globals: dict = {}, name: str = 'Multilayer', notes: str = '', **param_kwargs) → multilayer_obj#

Creates multilayer instance (stack of layers with foreground and substrate).

Parameters:

formula: str, optional: Multilayer formula (if non-empty, parsed to build the multilayer).
frgr: layer_obj, optional: Foreground (environment) layer.
bkgr: layer_obj, optional: Background (substrate) layer.
bydensity: bool, optional: If True, material is specified by density, otherwise by SLD.
mdb: mdb_obj (default: default_mdb): The material database.
globals: dict, optional: Global variables for formula parsing.
name: str, optional: Multilayer name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters.

Returns:

instance of ‘multilayer_obj’

escape.scattering.layer.roughness(rough: ParameterLike, lateral: ParameterLike | None = None, hurst: ParameterLike | None = None, name: str = 'Roughness', notes: str = '', **param_kwargs) → roughness_obj#

Returns instance of ‘roughness_obj’.

Parameters:

rough: ParameterLike: Root-mean-square roughness.
lateral: Optional[ParameterLike], optional: Lateral correlation length of roughness.
hurst: Optional[ParameterLike], optional: Hurst parameter.
name: str, optional: Object name.
notes: str, optional: User notes for the object.
**param_kwargs: dict: Additional arguments for the parameters.

Returns:

object of type ‘roughness_obj’

class escape.scattering.layer.roughness_obj#

roughness_obj is a container for surface roughness parameters.

bind_python_object(observer=None)#

constrain(val: constraint_obj)#: Add constraint to functor.

constraints#

Returns:: List of constraints

static convert(obj: object, name: str, **param_kwargs) → roughness_obj#

Converts the input object to a roughness object.

Parameters:

obj: roughness_obj or value: Roughness object or value
name: string: Roughness name
**param_kwargs: dict: Additional arguments for the parameters.

Returns:

roughness_obj: Roughness object instance.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

hurst#

Returns:: Hurst parameter value.

is_feasible#

Returns:: True if functor is feasible, False otherwise.

lateral#

Returns:: Correlation length of lateral roughness.

name#

Returns:: Object name.

on_state_changed()#

on_value_changed()#

parameters#

Returns:: List of parameters

rms#

Returns:: Root-mean-square roughness parameter value.

settings#

Returns:: List of settings

unbind_python_object()#

unconstrain(val: constraint_obj)#: Remove constraint from functor.

unconstrain_all()#: Remove all constraints from functor.

class escape.scattering.layer.layer_obj#

‘layer_obj’ is a wrapper class for layers. It contains relevant parameters and material description for layer.

bind_python_object(observer=None)#

constrain(val: constraint_obj)#: Add constraint to functor.

constraints#

Returns:: List of constraints

static convert(inp: object, name: str, bydensity: bool, mdb: mdb_obj, globals: dict = {}, **param_kwargs) → layer_obj#

Converts the input object or string to a layer object using the given material database mdb object.

Parameters:: inp (object, layer_obj or string): The input object or string with material name to be converted. name (str): The name of the layer object to be created. bydensity (bool): If True, the material is specified by density, otherwise by SLD. mdb (mdb_obj): The material database mdb object. globals (dict): Global variables dictionary. param_kwargs (dict): Additional arguments for the parameters.

Note: When converting from a string, param_kwargs are not applied; the C++ parser creates layers with default parameter settings. Each key should have a prefix with the parameter name. For example ‘thkn_userlim’ for thickness user boundaries, ‘density_fixed’ for density fixed flag, etc.
Returns:: layer_obj: Layer object instance.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

is_feasible#

Returns:: True if functor is feasible, False otherwise.

material#

Returns material instance.

Returns:: material_obj instance

name#

Returns object name.

Returns:: string value

on_state_changed()#

on_value_changed()#

parameters#

Returns:: List of parameters

roughness#: Returns roughness instance. :return:

roughness_obj instance

settings#

Returns:: List of settings

thickness#

Returns thickness value.

Returns:: double value

thkn#

Returns thickness value.

Returns:: double value

unbind_python_object()#

unconstrain(val: constraint_obj)#: Remove constraint from functor.

unconstrain_all()#: Remove all constraints from functor.

class escape.scattering.layer.layerstack_obj#

layerstack_obj is a wrapper class for layer stacks.

add(lay: layer_obj)#

Appends layer to stack.

Parameters:

lay: layer_obj: layer object

bind_python_object(observer=None)#

constrain(val: constraint_obj)#: Add constraint to functor.

constraints#

Returns:: List of constraints

static convert(inp: object, name: str, bydensity: bool, mdb: mdb_obj, globals: dict, **param_kwargs) → layerstack_obj#

Converts the input object or string to a layerstack object using the given material database mdb object.

Parameters:

inp (object, layerstack_obj or string): The input object or string: with layerstack to be converted.

name (str): The name of the layerstack object to be created. bydensity (bool): If True, the material is specified by density,

otherwise by SLD.

mdb (mdb_obj): The material database mdb object. globals (dict): Global variables dictionary. param_kwargs (dict): Additional arguments for the parameters.

Each key should have a prefix with the parameter name. For example ‘thkn_userlim’ for thickness user boundaries, ‘density_fixed’ for density fixed flag, etc.

Returns:

layerstack_obj: Layerstack object instance.

erase(idx: size_t)#: Erases layer with index ‘idx’ from stack.

erase_all()#: Erases all layers from stack.

get(idx: size_t) → layer_obj#: Returns a layer from stack by index.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

insert(idx: size_t, lay: layer_obj)#

Inserts layer to stack.

Parameters:

idx: size_t: layer index to replace
lay: layer_obj: new layer object

is_feasible#

Returns:: True if functor is feasible, False otherwise.

min_thickness#

Returns:: Minimal thickness of stack.

name#

Returns object name.

Returns:: string value

on_state_changed()#

on_value_changed()#

parameters#

Returns:: List of parameters

set(idx: size_t, lay: layer_obj)#

Replaces layer in stack.

Parameters:

idx: size_t: layer index to replace
lay: layer_obj: new layer object

settings#

Returns:: List of settings

total_thickness#

Returns total thickness of stack.

Returns:: double value

unbind_python_object()#

unconstrain(val: constraint_obj)#: Remove constraint from functor.

unconstrain_all()#: Remove all constraints from functor.

class escape.scattering.layer.multilayer_obj#

This class is used to describe layered samples. Layered samples can consist of layers or layer stacks. The topmost and bottommost layers are called the foreground (environment) and background (substrate), respectively, and are considered to have infinite thickness. Normally, the foreground layer has a zero scattering length density. If not, the wave-vector components of the incident wave will be corrected according to Snell’s law.

add(obj: object)#

Appends layer or layerstack

Parameters:

obj: layer_obj or layerstack_obj: layer or layerstack object

bind_python_object(observer=None)#

constrain(val: constraint_obj)#: Add constraint to functor.

constraints#

Returns:: List of constraints

static convert(inp: object, name: str, bydensity: bool, mdb: mdb_obj, globals: dict, **param_kwargs) → multilayer_obj#

Converts the input object or string to a multilayer object using the given material database mdb object. If layer has been created earlier, it can be used in the formula. In this case globals dictionary is required to be passed to the function.

Parameters:: inp (object, multilayer_obj or string): The input object or string with multilayer forumula. name (str): The name of the multilayer object to be created. bydensity (bool): If True, the material is specified by density, otherwise by SLD. mdb (mdb_obj): The material database mdb object. globals (dict): Global variables dictionary. param_kwargs (dict): Additional arguments for the parameters.

Each key should have a prefix with the parameter name. For example ‘thkn_userlim’ for thickness user boundaries, ‘density_fixed’ for density fixed flag, etc.
Returns:: multilayer_obj: Multilayer object instance.

erase(idx: size_t)#

Erases layer or layerstack

Parameters:

idx: size_t: layer index to replace

erase_all()#

Erases all layers

Parameters:

idx: size_t: layer index to replace

get(idx: size_t) → layerstack_obj#: Returns a layer stack from multilayer by index.

get_bkgr() → layer_obj#: Returns the background/substrate layer.

get_frgr() → layer_obj#: Returns the foreground/environment layer.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

insert(idx: size_t, obj: object)#

Inserts layer or layerstack

Parameters:

idx: size_t: layer index to replace
obj: layer_obj or layerstack_obj: layer or layerstack object

is_feasible#

Returns:: True if functor is feasible, False otherwise.

min_thickness#

Return minimal thickness of multilayer

Returns:: double value

move_down(idx: size_t)#

Moves layer or layerstack down

Parameters:

idx: size_t: layer index to replace

move_up(idx: size_t)#

Moves layer or layerstack up

Parameters:

idx: size_t: layer index to replace

name#

Returns object name.

Returns:: string value

on_state_changed()#

on_value_changed()#

parameters#

Returns:: List of parameters

set(idx: size_t, obj: object)#

Replaces layer or layerstack

Parameters:

idx: size_t: layer index to replace
obj: layer_obj or layerstack_obj: layer or layerstack object

set_bkgr(lay: layer_obj)#

Set the background (substrate) layer.

Parameters:

lay: layer_obj: Substrate layer object

set_frgr(lay: layer_obj)#

Set the foreground (environment) layer.

Parameters:

lay: layer_obj: Foreground layer object

settings#

Returns:: List of settings

show(profile: str = '', source: source_obj | None = None, config: Any | None = None, **kwargs) → ProfileLayout#

Show profile of the layer.

Parameters:

profile: str, optional: Profile type (default is “”).
source: Optional[source_obj], optional: Source object (default is None).
config: Optional[Any], optional: ProfileConfig or None (default is None).
**kwargs: dict: Additional keyword arguments passed to ProfileLayout.

total_thickness#

Return total thickness of multilayer

Returns:: double value

unbind_python_object()#

unconstrain(val: constraint_obj)#: Remove constraint from functor.

unconstrain_all()#: Remove all constraints from functor.