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

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: layer_obj | None = None, bkgr: layer_obj | None = 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.

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.

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.

parameters

Returns:

List of parameters

rms

Returns:

Root-mean-square roughness parameter value.

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.

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.

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

parameters

Returns:

List of parameters

roughness

Returns roughness instance. :return:

roughness_obj instance

thickness

Returns thickness value.

Returns:

double value

thkn

Returns thickness value.

Returns:

double value

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

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.

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

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

total_thickness

Returns total thickness of stack.

Returns:

double value

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

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

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

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

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

unconstrain(val: constraint_obj)

Remove constraint from functor.

unconstrain_all()

Remove all constraints from functor.