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

New 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:

Magnetic amorphous material without gradient

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

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

New in version 0.9.7.

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

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

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.

Crystal density based material

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

SLD based crystal material.

>>> m = esc.crystal("GaAs", density="mdb", dwsld0re="auto", dwsld0im="auto", dwsldhre="auto", dwsldhim="auto")

escape.scattering.material.unitcell(name: str, a: Union[ParameterLike, FunctorLike], b: Union[ParameterLike, FunctorLike], c: Union[ParameterLike, FunctorLike], adeg: Union[ParameterLike, FunctorLike], bdeg: Union[ParameterLike, FunctorLike], gdeg: Union[ParameterLike, FunctorLike]) → unitcell_obj¶

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

Returns:: Instance of unitcell_obj

escape.scattering.material.strained_unitcell(name: str, strain: Union[ParameterLike, FunctorLike], refucell: unitcell_obj) → 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: parameter_obj, double or functor_obj: Strain parameter
‘refucell’: unitcell_obj: Reference unitcell obj, normally substrate.

Returns:

Instance of unitcell_obj

escape.scattering.material.amorphous(name: str, 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[IntSettingLike] = None, mdb: Optional[mdb_obj] = <escape.scattering.mdb.mdb_obj object>, **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:

name (str):: Name of the material.
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 (parameter_obj, double value, or functor_obj):: Density of the material.
dwsld0re (parameter_obj, double value, or functor_obj):: Debye-Waller like factor for the real part of SLD0.
dwsld0im (parameter_obj, double value, or functor_obj):: Debye-Waller like factor for the imaginary part of SLD0.
sldm (parameter_obj, double value, or functor_obj):: Magnetic scattering length density.
zvar (variable_obj):: 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 (positive integer):: Number of slices in the gradient material.
mdb (mdb_obj):: Material database object (default is default_mdb).
**params_kwargs:: Additional keyword arguments for the automatically created parameters.

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(name: str, 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[IntSettingLike] = None, mdb: Optional[mdb_obj] = <escape.scattering.mdb.mdb_obj object>, **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:

name: str: The name of the crystal material.
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: double value, parameter_obj or functor_obj, optional: Debye-Waller like factor for the real part of SLD0 (default is None).
dwsld0im: double value, parameter_obj or functor_obj, optional: Debye-Waller like factor for the imaginary part of SLD0 (default is None).
dwsldhre: double value, parameter_obj or functor_obj, optional: Debye-Waller like factor for the real part of SLDH (default is None).
dwsldhim: double value, parameter_obj or functor_obj, optional: Debye-Waller like factor for the imaginary part of SLDH (default is None).
sldm: parameter_obj, double value or functor_obj, 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, optional: The material database object (default is default_mdb).
param_kwargs: dict, optional: Additional keyword arguments for the automatically created parameters.

Returns:

instance of material_obj

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

escape.scattering.material.generic_amorphous(name: str, sld0_re: Union[ParameterLike, FunctorLike], sld0_im: Union[ParameterLike, FunctorLike], sldm: Union[ParameterLike, FunctorLike] = None, zvar: Optional[variable_obj] = None, numslices: Optional[IntSettingLike] = None) → 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: parameter_obj, double value or functor_obj: Scattering length density, real part
sld0_im: parameter_obj, double value or functor_obj: Scattering length density, imaginary (absorption) part
sldm: parameter_obj, double value or functor_obj (optional): Magnetic scattering length density
zvar: variable_obj: 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: positive integer: Number of slices in the gradient material

Returns:

instance of material_obj

escape.scattering.material.generic_crystal(name: str, sld0_re: Union[ParameterLike, FunctorLike], sld0_im: Union[ParameterLike, FunctorLike], abs_sldh_re: Union[ParameterLike, FunctorLike], abs_sldh_im: Union[ParameterLike, FunctorLike], sldh_phd: DoubleSettingLike, sldm: Union[ParameterLike, FunctorLike] = None, ucell: Optional[UnitcellLike] = None, zvar: Optional[variable_obj] = None, numslices: Optional[IntSettingLike] = None) → 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:

namestr: Material name.
sld0_reparameter_obj, double value or functor_obj: Real part of scattering length density at Q=0.
sld0_imparameter_obj, double value or functor_obj: Imaginary part of scattering length density at Q=0.
abs_sldh_reparameter_obj, double value or functor_obj: Absolute value of real part of scattering length density at Q=Qb (Bragg reflection).
abs_sldh_imparameter_obj, double value or functor_obj: 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.
sldmparameter_obj, double value or functor_obj: Magnetic scattering length density.
ucellunitcell_obj: Unit cell object.
zvarvariable_obj: Variable object. Required if any of the parameters is a functor.
numslicesint: Number of slices. Required if any of the parameters is a functor.

Returns:

material_obj

class escape.scattering.material.unitcell_obj¶

Class which represents unit cell.

constrain(val)¶: Add constraint to functor.

constraints¶

Returns:: List of constraints

is_feasible¶

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

name¶

Returns:: Object name.

parameters¶

Returns:: List of parameters

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.

constrain(val)¶: Add constraint to functor.

constraints¶

Returns:: List of constraints

static convert(matinp, bydensity, mdb, globals, **param_kwargs)¶

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.

parameters¶

Returns:: List of parameters

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.

unconstrain(val)¶: Remove constraint from functor.

unconstrain_all()¶: Remove all constraints from functor.