Crystal and Amorphous Materials#

The escape.scattering.material module provides methods to create instances of material_obj for two types of materials: amorphous and crystal.

Materials support arguments of type functor_obj that represent materials with gradients. Gradient functors must be functors of one variable, which is depth. During computation, the variable depth takes values in the range [0, 1].

Added in version 0.9.7.

New methods has been provided to create materials using a string representation and material database. The string representation of a material is a name of the material in the database.

Changed in version 0.9.7.

The amorphous and crystal methods from versions <=0.9.6 have been renamed to generic_amorphous and generic_crystal respectively.

Examples#

Prior version 0.9.7:

  1. Magnetic amorphous material without gradient

>>> m = esc.amorphous(name="T", sld0_re=1e-5, sld0_im=1e-8, sldm=5e-3)

  1. Magnetic amorphous material with gradient

>>> z = esc.var("Z")
>>> Sr = esc.par("Sldr", 1e-5)
>>> Si = esc.par("Sldi", 1e-8)
>>> Sm = esc.par("Sldm", 5e-3)
>>> sld0_re = z*Sr
>>> sld0_im = z*Si
>>> sldm = z*Sm
>>> m = esc.amorphous(name="T", sld0_re=sld0_re, sld0_im=sld0_im, sldm=sldm, zvar=z, numslices=5)
>>> m
  Name: T                         Parameters number:          3
  Parameter               Value           +-      Error           Units           Fixed
  Sldr                              1e-05 +-      0                                   0
  Sldi                              1e-08 +-      0                                   0
  Sldm                              0.005 +-      0                                   0

Added in version 0.9.7.

  1. Density based amorphous material using MDB record for Iron with the corresponding name Fe. Density is returned by MDB record.

>>> m = esc.amorphous("Fe", density="mdb")

  1. Density based amorphous material using MDB record and custom density parameter. Density is returned by MDB record.

>>> m = esc.amorphous("Fe", density=esc.par(value=7.874, units="g/cm^3"))

  1. Scattering length density based amorphous material. Debye-Waller like factors are fitting parameters with initial value set to 1.

>>> m = esc.amorphous("Fe", density=None, dwsld0re="auto", dwsld0im="auto")

Instead of auto you can provide a parameter object or a value.

  1. Crystal density based material

>>> m = esc.crystal("GaAs", density="mdb"))

  1. SLD based crystal material.

>>> m = esc.crystal("GaAs", density="mdb", dwsld0re="auto", dwsld0im="auto", dwsldhre="auto", dwsldhim="auto")
escape.scattering.material.unitcell(a: ParameterLike | FunctorLike, b: ParameterLike | FunctorLike, c: ParameterLike | FunctorLike, adeg: ParameterLike | FunctorLike, bdeg: ParameterLike | FunctorLike, gdeg: ParameterLike | FunctorLike, name: str = '', notes: str = '') → unitcell_obj#

Returns unitcell object for crystal material. Any physical property of unitcell can be a functor representing a gradient change of this property.

Parameters:
a: ParameterLike or FunctorLike

Lattice parameter a

b: ParameterLike or FunctorLike

Lattice parameter b

c: ParameterLike or FunctorLike

Lattice parameter c

adeg: ParameterLike or FunctorLike

Angle between b and c

bdeg: ParameterLike or FunctorLike

Angle between a and c

gdeg: ParameterLike or FunctorLike

Angle between a and b

name: str, optional

Unit cell name.

notes: str, optional

User notes for the object.

Returns:

Instance of unitcell_obj

escape.scattering.material.strained_unitcell(strain: ParameterLike | FunctorLike, refucell: unitcell_obj, name: str = '', notes: str = '') → unitcell_obj#

Returns strained unitcell object for crystal material. Strain can be also a functor representing a gradient change of strain in depth. This functor should be a function of one variable, which will take values in the range of [0; 1].

Parameters:
strain: ParameterLike or FunctorLike

Strain parameter

refucell: unitcell_obj

Reference unitcell obj, normally substrate.

name: str, optional

Unit cell name.

notes: str, optional

User notes for the object.

Returns:

Instance of unitcell_obj

escape.scattering.material.alloy_unitcell(x: ParameterLike, ucell_A: unitcell_obj, ucell_B: unitcell_obj, bowing_a: ParameterLike = None, bowing_c: ParameterLike = None, name: str = '', notes: str = '') → unitcell_obj#

Create a binary alloy unit cell with Vegard’s law interpolation.

Interpolates lattice parameters between two endpoint unit cells A and B using composition x and optional bowing parameters:

\[p(x) = (1-x) \cdot p_A + x \cdot p_B - b \cdot x \cdot (1-x)\]

Parameters#

xParameterLike

Composition fraction in [0, 1]. At x=0 returns endpoint A, at x=1 returns endpoint B.

ucell_Aunitcell_obj

Endpoint unit cell A (at x=0).

ucell_Bunitcell_obj

Endpoint unit cell B (at x=1).

bowing_aParameterLike, optional

Bowing parameter for in-plane lattice constants (default 0).

bowing_cParameterLike, optional

Bowing parameter for out-of-plane lattice constant (default 0).

namestr, optional

Unit cell name.

notesstr, optional

User notes.

Returns#

unitcell_obj

Unit cell with composition-dependent lattice parameters.

See Also#

quaternary_alloy_unitcell : For four-endpoint (two-composition) interpolation. epitaxial_unitcell : For applying misfit strain and relaxation.

escape.scattering.material.quaternary_alloy_unitcell(x: ParameterLike, y: ParameterLike, ucell_AC: unitcell_obj, ucell_BC: unitcell_obj, ucell_AD: unitcell_obj, ucell_BD: unitcell_obj, name: str = '', notes: str = '') → unitcell_obj#

Create a quaternary alloy unit cell with bilinear Vegard interpolation.

Models alloys of the form A(x)B(1-x)C(y)D(1-y) using bilinear interpolation over four binary endpoint unit cells.

\[p(x,y) = (1-x)(1-y) \cdot p_{AC} + x(1-y) \cdot p_{BC} + (1-x) y \cdot p_{AD} + x y \cdot p_{BD}\]

Parameters#

xParameterLike

First composition fraction in [0, 1].

yParameterLike

Second composition fraction in [0, 1].

ucell_ACunitcell_obj

Endpoint at x=0, y=0 (e.g., GaP).

ucell_BCunitcell_obj

Endpoint at x=1, y=0 (e.g., InP).

ucell_ADunitcell_obj

Endpoint at x=0, y=1 (e.g., GaAs).

ucell_BDunitcell_obj

Endpoint at x=1, y=1 (e.g., InAs).

namestr, optional

Unit cell name.

notesstr, optional

User notes.

Returns#

unitcell_obj

Unit cell with composition-dependent lattice parameters.

See Also#

alloy_unitcell : For binary (single composition) interpolation.

escape.scattering.material.epitaxial_unitcell(layer_ucell: unitcell_obj, substrate_ucell: unitcell_obj, relaxation: ParameterLike, c12_c11: ParameterLike, name: str = '', notes: str = '') → unitcell_obj#

Create an epitaxial unit cell with misfit strain and lattice relaxation.

Computes the actual in-plane and out-of-plane lattice parameters from the interplay of misfit, relaxation R, and Poisson effect:

\[ \begin{align}\begin{aligned}a_{\parallel} = a_{sub} + R \cdot (a_{bulk} - a_{sub})\\\varepsilon_{\perp} = -2 \frac{C_{12}}{C_{11}} \varepsilon_{\parallel}\\c_{\perp} = c_{bulk} (1 + \varepsilon_{\perp})\end{aligned}\end{align} \]

Parameters#

layer_ucellunitcell_obj

Natural (bulk) unit cell of the layer material. For alloys, use alloy_unitcell() to create this.

substrate_ucellunitcell_obj

Substrate unit cell providing the in-plane reference lattice.

relaxationParameterLike

Degree of lattice relaxation R in [0, 1]. R=0: fully pseudomorphic (strained), R=1: fully relaxed.

c12_c11ParameterLike

Ratio of elastic stiffness constants C12/C11 (dimensionless). Typical values: GaAs ~0.453, InP ~0.452, Si ~0.278.

namestr, optional

Unit cell name.

notesstr, optional

User notes.

Returns#

unitcell_obj

Unit cell with strain- and relaxation-modified lattice parameters.

See Also#

alloy_unitcell : Compute bulk unit cell from alloy composition. strained_unitcell : Simpler c-axis-only strain model.

escape.scattering.material.binary_alloy_crystal(mid_A, mid_B, x: ParameterLike, density: ParameterLike, ucell: unitcell_obj, dislocation_dw: ParameterLike = None, sldm: ParameterLike = None, mdb: mdb_obj = None, name: str = '', notes: str = '') → material_obj#

Create a binary alloy crystal material A(1-x)Bx from two MDB crystal records.

SLD0 and SLDh are linearly interpolated between endpoint A (x=0) and endpoint B (x=1) based on their MDB crystal records. An optional dislocation Debye-Waller factor reduces the coherent structure factor for partially relaxed layers.

Parameters#

mid_Astr

Material ID (name) in the MDB for endpoint A (x=0).

mid_Bstr

Material ID (name) in the MDB for endpoint B (x=1).

xParameterLike

Composition fraction in [0, 1].

densityParameterLike

Material density in g/cm^3.

ucellunitcell_obj

Unit cell (typically from alloy_unitcell() + epitaxial_unitcell()).

dislocation_dwParameterLike, optional

Dislocation Debye-Waller parameter. 0 = no correction (default).

sldmParameterLike, optional

Magnetic SLD. None for non-magnetic materials (default).

mdbmdb_obj, optional

Material database. Uses default if None.

namestr, optional

Material name.

notesstr, optional

User notes.

Returns#

material_obj

Crystal material with composition-interpolated scattering properties.

See Also#

alloy_unitcell : Create the composition-dependent unit cell. epitaxial_unitcell : Apply misfit strain and relaxation. quaternary_alloy_crystal : For four-endpoint interpolation.

escape.scattering.material.quaternary_alloy_crystal(mid_AC, mid_BC, mid_AD, mid_BD, x: ParameterLike, y: ParameterLike, density: ParameterLike, ucell: unitcell_obj, dislocation_dw: ParameterLike = None, sldm: ParameterLike = None, mdb: mdb_obj = None, name: str = '', notes: str = '') → material_obj#

Create a quaternary alloy crystal material A(x)B(1-x)C(y)D(1-y).

SLD is bilinearly interpolated over four MDB crystal endpoint records.

Parameters#

mid_ACstr

Material ID in the MDB for endpoint AC (x=0, y=0).

mid_BCstr

Material ID in the MDB for endpoint BC (x=1, y=0).

mid_ADstr

Material ID in the MDB for endpoint AD (x=0, y=1).

mid_BDstr

Material ID in the MDB for endpoint BD (x=1, y=1).

xParameterLike

First composition fraction in [0, 1].

yParameterLike

Second composition fraction in [0, 1].

densityParameterLike

Material density in g/cm^3.

ucellunitcell_obj

Unit cell (from quaternary_alloy_unitcell() + epitaxial_unitcell()).

dislocation_dwParameterLike, optional

Dislocation Debye-Waller parameter. 0 = no correction (default).

sldmParameterLike, optional

Magnetic SLD. None for non-magnetic materials (default).

mdbmdb_obj, optional

Material database. Uses default if None.

namestr, optional

Material name.

notesstr, optional

User notes.

Returns#

material_obj

Crystal material with bilinearly interpolated scattering properties.

See Also#

quaternary_alloy_unitcell : Create the composition-dependent unit cell. binary_alloy_crystal : For binary (single composition) alloy material.

escape.scattering.material.amorphous(mid: str = '', formula: str = '', density: Optional[float] = None, dwsld0re: Optional[ParameterLike, FunctorLike] = None, dwsld0im: Optional[ParameterLike, FunctorLike] = None, sldm: Optional[ParameterLike, FunctorLike] = None, zvar: Optional[variable_obj] = None, numslices: Optional[int] = None, mdb: Optional[mdb_obj] = <escape.scattering.mdb.mdb_obj object>, name: str = '', notes: str = '', **param_kwargs) → material_obj#

Returns an amorphous material object.

This function creates an amorphous material and provides support for gradient properties. Any physical property of the material can be represented as a functor, allowing you to model gradients within the material. These functors should be functions of one variable, taking values in the range [0, 1].

Parameters:
mid (str, optional):

Material identifier (name of the material database record). If not provided, the material name will be used as the material identifier.

formula (str, optional):

Chemical formula of the material (default is an empty string).

density: ParameterLike or FunctorLike, optional

Density of the material.

dwsld0re: ParameterLike or FunctorLike, optional

Debye-Waller like factor for the real part of SLD0.

dwsld0im: ParameterLike or FunctorLike, optional

Debye-Waller like factor for the imaginary part of SLD0.

sldm: ParameterLike or FunctorLike, optional

Magnetic scattering length density.

zvar: variable_obj, optional

Variable indicating the Z-axis, i.e., normal to the sample surface. This variable should be in the domains of all provided functors. It takes values in the range from 0 to 1, indicating upper and lower interfaces of the gradient layer.

numslices: int, optional

Number of slices in the gradient material.

mdb (mdb_obj (default: default_mdb)):

Material database object.

name (str, optional):

Material name.

notes (str, optional):

User notes for the object.

**param_kwargs: dict, optional

Additional arguments for the parameters (e.g. density_fixed).

Returns:

An instance of material_obj.

Notes: - If formula is provided, you can specify either density or both dwsld0re and dwsld0im to define the material. - If formula is not provided, you should provide name or mid and either both dwsld0re and dwsld0im or density. - Be cautious when providing both dwsld0re and dwsld0im, as they may be ignored when density is provided.

escape.scattering.material.crystal(mid: str = '', density: Optional[float] = None, dwsld0re: Optional[ParameterLike, FunctorLike] = None, dwsld0im: Optional[ParameterLike, FunctorLike] = None, dwsldhre: Optional[ParameterLike, FunctorLike] = None, dwsldhim: Optional[ParameterLike, FunctorLike] = None, sldm: Optional[ParameterLike, FunctorLike] = None, ucell: Optional[unitcell_obj] = None, zvar: Optional[variable_obj] = None, numslices: Optional[int] = None, mdb: Optional[mdb_obj] = <escape.scattering.mdb.mdb_obj object>, name: str = '', notes: str = '', **param_kwargs) → material_obj#

Returns a crystal material object using information from the Material Database. Any physical property of the material can be a functor representing a gradient change of this property. This functor should be a function of one variable, which takes values in the range [0; 1] as input.

Parameters:
mid: str, optional

The material ID or identifier (default is an empty string). If not provided, the material name will be used as the material ID.

density: double value, optional

The density of the material (default is None).

dwsld0re: ParameterLike or FunctorLike, optional

Debye-Waller like factor for the real part of SLD0 (default is None).

dwsld0im: ParameterLike or FunctorLike, optional

Debye-Waller like factor for the imaginary part of SLD0 (default is None).

dwsldhre: ParameterLike or FunctorLike, optional

Debye-Waller like factor for the real part of SLDH (default is None).

dwsldhim: ParameterLike or FunctorLike, optional

Debye-Waller like factor for the imaginary part of SLDH (default is None).

sldm: ParameterLike or FunctorLike, optional

Magnetic scattering length density (default is None).

ucell: unitcell_obj, optional

Unit cell object (default is None). If not provided, the unit cell will be taken from the material database.

zvar: variable_obj, optional

A variable that indicates the Z-axis, i.e., normal to the sample surface. This variable should be in the domains of all provided functors. Internally, it will take values in the range from 0 to 1, indicating upper and lower interfaces of the gradient layer (default is None).

numslices: positive integer, optional

The number of slices for all gradient properties (default is None).

mdb: mdb_obj (default: default_mdb)

The material database object.

name: str, optional

The name of the crystal material.

notes: str, optional

User notes for the object.

**param_kwargs: dict, optional

Additional arguments for the parameters (e.g. density_fixed).

Returns:

instance of material_obj

Notes: - If density is not provided, you should provide dwsld0re, dwsld0im, dwsldhre and dwsldhim.

escape.scattering.material.generic_amorphous(sld0_re: ParameterLike | FunctorLike, sld0_im: ParameterLike | FunctorLike, sldm: ParameterLike | FunctorLike = None, zvar: variable_obj | None = None, numslices: int | None = None, name: str = '', notes: str = '', **param_kwargs) → material_obj#

Returns amorphous material object. SLDs arguments can have a parameter_obj/value type or can be functors representing a gradient change of the corresponding property with z(depth)-variable. In the former case z-variable must be provided together with a number of gradient slices.

Parameters:
sld0_re: ParameterLike or FunctorLike

Scattering length density, real part

sld0_im: ParameterLike or FunctorLike

Scattering length density, imaginary (absorption) part

sldm: ParameterLike or FunctorLike, optional

Magnetic scattering length density

zvar: variable_obj, optional

Variable which indicates Z-axis, i.e. normal to the sample surface This variable should be in the domains of all provided functors. Internally it will take values in the range from 0 to 1, indicating upper and lower interfaces of the gradient layer.

numslices: int, optional

Number of slices in the gradient material

**param_kwargs: dict, optional

Additional arguments for the parameters.

name: str, optional

Material name.

notes: str, optional

User notes for the object.

Returns:

instance of material_obj

escape.scattering.material.generic_crystal(sld0_re: ParameterLike | FunctorLike, sld0_im: ParameterLike | FunctorLike, abs_sldh_re: ParameterLike | FunctorLike, abs_sldh_im: ParameterLike | FunctorLike, sldh_phd: float, sldm: ParameterLike | FunctorLike = None, ucell: UnitcellLike | None = None, zvar: variable_obj | None = None, numslices: int | None = None, name: str = '', notes: str = '') → material_obj#

Returns crystal material object. Any physical property of material can be a functor representing a gradient change of this property. This functor should be a function of one variable, which takes values in the range of [0; 1] as input.

Parameters:
sld0_reParameterLike or FunctorLike

Real part of scattering length density at Q=0.

sld0_imParameterLike or FunctorLike

Imaginary part of scattering length density at Q=0.

abs_sldh_reParameterLike or FunctorLike

Absolute value of real part of scattering length density at Q=Qb (Bragg reflection).

abs_sldh_imParameterLike or FunctorLike

Absolute value of imaginary part of scattering length density at Q=Qb (Bragg reflection).

sldh_phddouble value

Phase difference between sldh_re and sldh_im, both are complex values.

sldmParameterLike or FunctorLike, optional

Magnetic scattering length density.

ucellUnitcellLike, optional

Unit cell object.

zvarvariable_obj, optional

Variable object. Required if any of the parameters is a functor.

numslicesint, optional

Number of slices. Required if any of the parameters is a functor.

namestr, optional

Material name.

notesstr, optional

User notes for the object.

Returns:

material_obj

class escape.scattering.material.unitcell_obj#

Class which represents unit cell.

bind_python_object(observer=None)#
constrain(val)#

Add constraint to functor.

constraints#
Returns:

List of constraints

get_hash_int() → int#

Return the C++ entity hash used for stable identity.

is_feasible#
Returns:

True if functor is feasible, False otherwise.

name#
Returns:

Object name.

on_state_changed()#
on_value_changed()#
parameters#
Returns:

List of parameters

settings#
Returns:

List of settings

unbind_python_object()#
unconstrain(val)#

Remove constraint from functor.

unconstrain_all()#

Remove all constraints from functor.

class escape.scattering.material.material_obj#

Class which represents material.

at(idx)#

Returns material slice if class instance represent a material with gradient properties.

Parameters:
idx: int

Slice index.

Returns:

Material object.

bind_python_object(observer=None)#
constrain(val)#

Add constraint to functor.

constraints#
Returns:

List of constraints

static convert(matinp, bydensity, mdb, globals, **param_kwargs)#
get_hash_int() → int#

Return the C++ entity hash used for stable identity.

is_feasible#
Returns:

True if functor is feasible, False otherwise.

name#

Returns material name.

Returns:

string value.

numslices#
Returns:

Number of slices if material has gradient properties.

on_state_changed()#
on_value_changed()#
parameters#
Returns:

List of parameters

settings#
Returns:

List of settings

sld0(src)#

Calculates scattering length density value corresponding to zero-diffraction order.

Parameters:
src: source_obj

Source object which contains information about source (xrays or neutrons).

Returns:

Complex value of scattering length density.

sldh(src, h, k, l)#

Calculates scattering length density value corresponding to Bragg reflection of (h, k, l) order.

Parameters:
src: source_obj

Source object which contains information about source (xrays or neutrons).

h: int

Miller index h.

k: int

Miller index k.

l: int

Miller index l.

Returns:

Complex value of scattering length density.

unbind_python_object()#
unconstrain(val)#

Remove constraint from functor.

unconstrain_all()#

Remove all constraints from functor.