CTR Structure-Factor Normalization¶

The CTR calculation API uses canonical structure-factor units throughout: every public F or F_uc method returns a complex scattering amplitude in electrons.

Warning

This convention changes amplitudes produced by older releases that divided unit-cell factors by area or volume. Legacy reference amplitudes and fitted experimental scale factors must be migrated by the corresponding constant normalization factor. Intensities change by the square of that factor.

Unit-cell amplitudes¶

UnitCell.F_uc returns

\[F_{\mathrm{uc}}(\mathbf{Q}) = \sum_i o_i f_i(\mathbf{Q}) \exp\left(i\mathbf{Q}\cdot\mathbf{r}_i\right),\]

including coherent-domain occupancies and displacement factors. No unit-cell area or volume normalization is applied.

Film.F_uc and PoissonSurface.F_uc sum their generated layer amplitudes and return electrons for one lateral unit cell of their source UnitCell.

An EpitaxyInterface can join materials with different lateral areas. Its canonical lateral cell is the lower unit cell. Internally it combines the upper and lower amplitudes as

\[F_{\mathrm{interface}} = A_{\mathrm{lower}} \left( \frac{F_{\mathrm{upper}}}{A_{\mathrm{upper}}} + \frac{F_{\mathrm{lower}}}{A_{\mathrm{lower}}} \right).\]

The result is therefore in electrons per lower interface cell.

Crystal composition¶

SXRDCrystal automatically uses its bulk unit cell as the reciprocal-space and lateral-area reference unless reference_uc is supplied explicitly. The constructor propagates that reference to every source and generated layer unit cell.

For each crystal component \(j\), SXRDCrystal.F evaluates

\[F_{\mathrm{crystal}} = \frac{A_{\mathrm{ref}}}{A_{\mathrm{bulk}}}F_{\mathrm{bulk}} + \sum_j w_j d_j \frac{A_{\mathrm{ref}}}{A_j}F_j ,\]

where:

\(A_{\mathrm{ref}}\) is reference_uc.uc_area;
\(A_j\) is the component uc_area;
\(w_j\) is the dimensionless crystal-component weight;
\(d_j\) is a dimensionless coherent-domain occupancy.

Thus SXRDCrystal.F returns electrons per reference lateral cell and is invariant when a component is replaced by an equivalent in-plane supercell. No illuminated footprint, detector response, or experimental scale factor is included. Calculated intensity is proportional to \(|F_{\mathrm{crystal}}|^2\).

API reference¶

class orgui.datautils.xrayutils.CTRcalc.SXRDCrystal(uc_bulk, *uc_surface, **keyargs)[source]¶

Bases: object

Compose bulk and surface amplitudes on one reference lateral cell.

Every component F_uc method returns an unnormalized structure factor in electrons for that component’s own lateral unit cell. This class converts each amplitude to the selected reference area using reference_uc.uc_area / component.uc_area before adding it.

The bulk unit cell is the default reciprocal-coordinate and area reference. No illuminated sample area, detector response, or experimental scale factor is included.

setGlobalReferenceUnitCell(uc_reference, rotMatrix=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))[source]¶

Set the crystal-wide coordinate and lateral-area reference.

Reciprocal coordinates supplied to structure-factor methods are interpreted in uc_reference reciprocal lattice units. The same unit cell supplies the reference area used by F().

This method propagates the coordinate transform to bulk, source unit cells, and all generated Film, interface, and surface layer cells.

Parameters:

uc_reference (UnitCell) – Unit cell defining reciprocal lattice units and uc_area.
rotMatrix (numpy.ndarray) – Optional 3-by-3 rotation from the reference crystal frame into the component crystal frames.

F_surf(harray, karray, Larray)[source]¶

Return the combined surface amplitude in electrons.

Each component amplitude is converted from its own lateral unit cell to the configured reference lateral cell. The bulk contribution is not included.

Parameters:

harray (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
karray (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
Larray (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.

Returns:

Complex surface amplitude in electrons per reference lateral cell.

Return type:

numpy.ndarray

apply_stacking()[source]¶: Generate object positions and cyclic layers from bottom to top.

F(harray, karray, Larray)[source]¶

Return the complete crystal structure factor in electrons.

The returned amplitude corresponds to one lateral unit cell of reference_uc. For every component j, the raw amplitude in electrons is scaled by

reference_uc.uc_area / component.uc_area.

Component weights, coherent-domain occupancies, and attenuation are dimensionless. No illuminated footprint or experimental intensity scale is included; calculated intensity is proportional to abs(F)**2.

Parameters:

harray (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
karray (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
Larray (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.

Returns:

Complex crystal amplitude in electrons per reference lateral cell.

Return type:

numpy.ndarray

setDomain(uc_no, domains)[source]¶: should be a list of tuples with: (rotmatrix, occupancy)

addRelParameter(index0_or_name, indexneg_or_name=None, initial=None, limits=(-inf, inf), prior=None, **keyargs)[source]¶

sets a new fit parameter for the weight w of a unit cell (Legacy API!, consider using addWeightParameter)

F_xtal = w * F_uc1

if indexneg_or_name is not None the structure factor will be calculated to

F_xtal = w * F_uc1 + (1 - w) * F_uc2

Parameters¶

index0_or_namestr or int: index or name of the unit cell 1 (with F_uc1)
indexneg_or_namedefault: None, str or int: index or name of the unit cell 2 (with F_uc2)
initial: float: initial value of w
limits: list: fit limits of w

addWeightParameter(indices_or_names, factors, **keyargs)[source]¶

sets a new fit parameter for the weight w of a unit cell

Parameters¶

index0_or_namestr or int: index or name of the unit cell 1 (with F_uc1)
indexneg_or_namedefault: None, str or int: index or name of the unit cell 2 (with F_uc2)
initial: float: initial value of w
limits: list: fit limits of w

addFitParameter(parameter, limits=(-inf, inf), **keyargs)[source]¶

Add a coupled fit parameter to crystal components.

parameter maps component names to dictionaries containing atoms and par index selections. An optional factors entry creates a relative parameter, and settings is forwarded to the component fit-parameter constructor.

Example:

{
    "film": {
        "atoms": (1, 2, 3),
        "par": ("z", "oDW", "iDW"),
        "factors": (1, -1, 1),
        "settings": {"name": "film_relaxation"},
    }
}

Parameters:

parameter (dict) – Component-specific fit-parameter definitions.
limits (tuple) – Lower and upper fit limits.
keyargs – Additional coupled-parameter settings.

Returns:

The created coupled parameter.

Return type:

Parameter

addWyckoffParameter(parameter, limits=(-inf, inf), **keyargs)[source]¶

Add a coupled symmetry-preserving Wyckoff parameter.

parameter maps crystal component names to Wyckoff selections. A selection can be (site_id, variable) or a dictionary with site_id and variable entries. For EpitaxyInterface components, either use a key (component, unitcell) or provide unitcell="top", unitcell="bottom", or a list in the selection dictionary.

Parameters:

parameter (dict) – Component-specific Wyckoff variable selections.
limits (tuple) – Shared delta limits in fractional units.
keyargs – Additional coupled-parameter settings such as name or prior.

Returns:

Created coupled parameter.

Return type:

Parameter

addWyckoffShift(parameter, limits=(-inf, inf), **keyargs)[source]¶

Add a coupled representative Wyckoff-site shift parameter.

parameter maps crystal component names to Wyckoff shift selections. A selection can be (site_id, axis) or a dictionary with site_id and axis entries. For EpitaxyInterface components, either use a key (component, unitcell) or provide unitcell="top", unitcell="bottom", or a list in the selection dictionary.

Parameters:

parameter (dict) – Component-specific Wyckoff shift selections.
limits (tuple) – Shared parent-coordinate delta limits in fractional units.
keyargs – Additional coupled-parameter settings such as name or prior.

Returns:

Created coupled parameter.

Return type:

Parameter

setLimits(lim)[source]¶

fit bounds.

lim shape: (n, 2)

toStr(showErrors=True)[source]¶

Serialize the complete crystal model as plain text.

Parameters:: showErrors (bool) – Include propagated component, atom, and weight errors.
Returns:: Plain-text crystal representation.
Return type:: str

toFile(filename)[source]¶

Write a plain-text .xtal or .xpr model.

.xtal files store fitted values without propagated errors. .xpr files additionally store propagated errors for weights, CTRfilm parameters, and atom parameters.

Parameters:: filename (str) – Output path ending in .xtal or .xpr.
Raises:: ValueError – If the filename has another extension.

static fromFile(filename)[source]¶

Read a plain-text .xtal or .xpr crystal model.

Values and propagated errors are reconstructed from the text. Fit parameter definitions remain in the optional companion .h5 file used by the existing fitting workflow.

Parameters:: filename (str) – Model path, or basename for automatic .xpr/.xtal lookup.
Returns:: Reconstructed crystal model.
Return type:: SXRDCrystal

class orgui.datautils.xrayutils.CTRuc.UnitCell(a, alpha, **keyargs)[source]¶

Bases: Lattice

names¶: self.fitparameters = [] self.fitparameters_name = [] self.relfitparam = [] self.relfitparam_name = [] self.fitparlimits = [] self.relfitlimits = [] self.relfitparam_prior = [] self.fitparameter_prior = []

updateFromParameters()[source]¶: Update basis from the values stored in the Parameters

setReferenceUnitCell(uc, rotMatrix=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))[source]¶

Set the reciprocal- and real-space reference coordinate system.

Parameters:

uc (UnitCell) – Unit cell defining input reciprocal lattice units.
rotMatrix (numpy.ndarray) – Optional 3-by-3 rotation from the reference crystal frame into this unit cell’s crystal frame.

property layer_cycle¶: Return the ordered local structural-layer cycle.

translate_layered(translation, name=None)[source]¶

Return a translated copy with cyclic z-layer wrapping.

The translation is expressed in unit-cell fractional coordinates. The x and y translations must be integer unit-cell offsets, and z is an integer number of structural-layer steps. Atom fractional z coordinates and layer origins are shifted by z / len(layer_cycle) while layer identifiers are reassigned through the ordered CTRstacking.LayerCycle. A positive z step moves lower layers upward and wraps the former top layer to the bottom.

Symmetry metadata is updated by remapping atom indices, atom layers, surface coordinates, parent coordinates, and Wyckoff coupling constants.

Parameters:

translation – Translation vector with shape (3,), affine matrix with shape (3, 4), or homogeneous affine matrix with shape (4, 4).
name (str) – Optional name for the returned unit cell. Defaults to this unit cell’s name.

Returns:

Transformed unit-cell copy.

Return type:

UnitCell

Raises:

ValueError – If the affine linear part is not identity or any requested translation is not an integer.

affine_layer_transform(translation, name=None)[source]¶

Return a canonical layered translation copy.

The translation input follows translate_layered(), but z layer steps are wrapped back into this unit cell’s structural-layer positions. This preserves a 0 <= z < 1 unit-cell representation for cells whose layer origins are inside that interval.

Symmetry metadata is updated by remapping atom indices, atom layers, surface coordinates, parent coordinates, and Wyckoff coupling constants.

Parameters:

translation – Translation vector with shape (3,), affine matrix with shape (3, 4), or homogeneous affine matrix with shape (4, 4).
name (str) – Optional name for the returned unit cell. Defaults to this unit cell’s name.

Returns:

Transformed unit-cell copy with wrapped layer coordinates.

Return type:

UnitCell

Raises:

ValueError – If the affine linear part is not identity or any requested translation is not an integer.

supercell(repeats, symmetry='preserve', name=None)[source]¶

Return a repeated unit-cell copy.

Parameters:

repeats – Integer repeat counts along the a, b, and c lattice directions.
symmetry (str) – "preserve" keeps generated atoms on the original Wyckoff sites, so a later Wyckoff fit parameter is shared across all repeated copies. "independent" creates one copied Wyckoff site per generated unit-cell repeat, so each copy can be fitted independently.
name (str) – Optional name for the returned unit cell. Defaults to this unit cell’s name.

Returns:

Repeated unit-cell copy.

Return type:

UnitCell

Raises:

ValueError – If repeat counts are not positive integers or symmetry is unknown.

property layer_behavior¶: Return how layer selection is handled during crystal stacking.

stack_on(below_loc, below_height, below_layer=-1, below_state=None)[source]¶

Place this unit cell on the object below it.

Parameters:

below_loc (float) – Absolute reference location of the object below in Angstrom. Unit cells do not otherwise use this value.
below_height (float) – Absolute top height of the object below in Angstrom.
below_layer (float) – Top cyclic layer identifier of the object below.

property layer_state¶: Return the top structural-layer state of this unit cell.

property stacking_height_absolute¶: Return the nominal height passed to the object above.

property stacking_loc_absolute¶: Return the nominal reference location passed upward.

setEnergy(E)[source]¶: for dispersion and absorption correction in eV

addFitParameter(indexarray, limits=(-inf, inf), **keyargs)[source]¶

Parameters¶

indexarrayTYPE: DESCRIPTION.
limitslist, optional: list with [lower, upper] bounds for the fit. The default is [-np.inf,np.inf].

Raises¶

ValueError: DESCRIPTION.

Returns¶

int: internal id of the parameter.

wyckoff_sites()[source]¶

Return Wyckoff site metadata for this unit cell.

Returns:: List of site dictionaries. The list is empty when no symmetry metadata is attached.
Return type:: list

wyckoff_couplings(site_id=None)[source]¶

Return symmetry couplings for generated Wyckoff atom coordinates.

Parameters:: site_id (str) – Optional site identifier. If omitted, all couplings are returned.
Returns:: List of coordinate coupling metadata objects.
Return type:: list

wyckoff_site_couplings(site_id=None)[source]¶

Return couplings for representative Wyckoff-site displacement.

Parameters:: site_id (str) – Optional site identifier. If omitted, all couplings are returned.
Returns:: List of site-displacement coupling metadata objects.
Return type:: list

atom_wyckoff_metadata(atom_index)[source]¶

Return symmetry metadata for one atom.

Parameters:: atom_index (int) – Index in basis.
Returns:: Atom metadata or None when no metadata is available.
Return type:: object or None

addWyckoffParameter(site_id, variable, limits=(-inf, inf), absolute_limits=None, **keyargs)[source]¶

Add a symmetry-preserving fit parameter for a Wyckoff variable.

The stored fit value is the change in the Wyckoff variable from the generated coordinates. For example, fitting rutile oxygen u adds factor * delta_u to every generated coordinate that depends on u. Multi-variable Wyckoff sites are fitted by adding one parameter per independent coordinate variable.

Parameters:

site_id (str) – Site identifier returned by wyckoff_sites().
variable (str) – Wyckoff variable name, for example "u".
limits (tuple) – Fit limits for the variable change in fractional units.
absolute_limits (tuple) – Optional absolute variable limits. These are converted to change limits around the metadata variable value.

Returns:

Created relative fit parameter.

Return type:

CTRutil.Parameter

Raises:

ValueError – If no matching affine couplings exist.

addWyckoffParameters(site_id, variables=None, limits=(-inf, inf), absolute_limits=None, **keyargs)[source]¶

Add symmetry-preserving fit parameters for Wyckoff variables.

Parameters:

site_id (str) – Site identifier returned by wyckoff_sites().
variables (iterable or None) – Iterable of coordinate variables to fit. If None, all free variables on the site are fitted.
limits – Either one (lower, upper) tuple applied to every variable or a dictionary mapping variable names to delta limits.
absolute_limits – Optional dictionary mapping variable names to absolute limits.

Returns:

Created relative fit parameters in variable order.

Return type:

list

Raises:

ValueError – If the site has no free coordinate variables.

addWyckoffShift(site_id, axis, limits=(-inf, inf), absolute_limits=None, **keyargs)[source]¶

Add a symmetry-lowering shift for representative site motion.

axis is a parent conventional fractional coordinate of the representative atom. The stored fit value is a delta from the representative coordinate; generated atoms move through the stored space-group operation and surface-cell transform factors.

Parameters:

site_id (str) – Site identifier returned by wyckoff_sites().
axis (str) – Parent representative coordinate, one of "x", "y", or "z".
limits (tuple) – Fit limits for the coordinate change in parent fractional units.
absolute_limits (tuple) – Optional absolute parent-coordinate limits, converted to changes around the stored representative coordinate.

Returns:

Created relative fit parameter.

Return type:

CTRutil.Parameter

Raises:

ValueError – If no matching site-displacement couplings exist.

addWyckoffShifts(site_id, axes=('x', 'y', 'z'), limits=(-inf, inf), absolute_limits=None, **keyargs)[source]¶

Add representative site-displacement shifts for several axes.

Parameters:

site_id (str) – Site identifier returned by wyckoff_sites().
axes (iterable) – Parent representative coordinate axes to fit.
limits – Either one (lower, upper) tuple applied to every axis or a dictionary mapping axis names to delta limits.
absolute_limits – Optional dictionary mapping axis names to absolute limits.

Returns:

Created relative fit parameters in axis order.

Return type:

list

F_uc_bulk(h, k, l, atten=0)[source]¶

Return one attenuated bulk unit-cell amplitude in electrons.

Parameters:

h (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
k (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
l (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
atten (float) – Dimensionless attenuation exponent per unit-cell translation.

Returns:

Complex structure-factor amplitude in electrons.

Return type:

numpy.ndarray

F_uc_bulk_direct(h, k, l, atten=0)[source]¶

Return one bulk-cell amplitude without reference conversion.

The result is unnormalized and has units of electrons.

Parameters:

h (numpy.ndarray) – Reciprocal coordinate in this unit cell’s r.l.u.
k (numpy.ndarray) – Reciprocal coordinate in this unit cell’s r.l.u.
l (numpy.ndarray) – Reciprocal coordinate in this unit cell’s r.l.u.
atten (float) – Dimensionless attenuation exponent.

Returns:

Complex structure-factor amplitude in electrons.

Return type:

numpy.ndarray

F_uc(h, k, l)[source]¶

Return the canonical unit-cell structure factor in electrons.

No unit-cell area or volume normalization is applied. Input reciprocal coordinates are interpreted in the configured reference unit cell and transformed into this unit cell before evaluation.

Parameters:

h (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
k (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
l (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.

Returns:

Complex structure-factor amplitude in electrons.

Return type:

numpy.ndarray

F_bulk(h, k, l, atten=0)[source]¶

Return the semi-infinite bulk structure factor in electrons.

The amplitude represents one lateral bulk unit cell. The geometric lattice sum is applied only along the out-of-plane direction.

Parameters:

h (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
k (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
l (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
atten (float) – Dimensionless attenuation exponent per bulk unit cell.

Returns:

Complex bulk amplitude in electrons per lateral bulk cell.

Return type:

numpy.ndarray

SQRT2pi = np.float64(2.5066282746310002)¶

zDensity_G(z, h, k)[source]¶

calculates h,k-th Fourier component of the electron density of the unit cell i.e. 0,0-th component is the commonly used z-projected electron density

The density is normalized to the surface area of the unit cell

Parameters¶

z1-d array: z coordinates in Angstrom, should be equidestant and monotonally increasing to avoid numerical issues with convolutions
hfloat: h-th component index
kfloat: k-th component index

Returns¶

1d- array complex128: complex h,k-th Fourier component of the electron density in electrons/Angstrom**3 calculate the absolute value to get the electron density

parameterStr(showErrors=True)[source]¶

Return atom and layer parameters as plain text.

Parameters:: showErrors (bool) – Include propagated fit errors when available.
Returns:: Serialized unit-cell parameter block.
Return type:: str

toStr(showErrors=True)[source]¶

Serialize the unit cell as plain text.

Parameters:: showErrors (bool) – Include propagated fit errors when available.
Returns:: Plain-text unit-cell representation.
Return type:: str

class orgui.datautils.xrayutils.CTRfilm.Film(unitcell, **kwargs)[source]¶

Bases: _LayerStackingMixin, LinearFitFunctions

property layers¶: Return the cyclic layer identifiers.

property uc_area¶: Return the Film lateral unit-cell area in Angstrom squared.

setReferenceUnitCell(uc, rotMatrix=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))[source]¶

Set the reference frame on the Film and every generated layer.

Parameters:

uc (UnitCell) – Unit cell defining input reciprocal lattice units.
rotMatrix (numpy.ndarray) – Optional 3-by-3 rotation from the reference frame into the Film crystal frame.

setEnergy(E)[source]¶

Set X-ray energy for the Film and generated layers.

Parameters:: E (float) – X-ray energy in eV.

F_uc(h, k, l)[source]¶

Return the Film structure factor in electrons.

The result is the unnormalized sum over all generated Film layers and corresponds to one lateral Film unit cell.

Parameters:

h (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
k (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
l (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.

Returns:

Complex Film amplitude in electrons.

Return type:

numpy.ndarray

addFitParameter(indexarray, limits=(-inf, inf), **kwarg)[source]¶: to assign multiple unitcells with the same fitparameter, provide list of unitcell names as kwarg unitcell

addRelParameter(indexarray, factors, limits=(-inf, inf), **kwarg)[source]¶: to assign multiple unitcells with the same fitparameter, provide list of unitcell names as kwarg unitcell

updateFromParameters()[source]¶: Update basis from the values stored in the Parameters

toStr(showErrors=True)[source]¶

Serialize the Film as plain text.

Parameters:: showErrors (bool) – Include propagated Film and nested unit-cell errors.
Returns:: Plain-text Film representation.
Return type:: str

class orgui.datautils.xrayutils.CTRfilm.EpitaxyInterface(uc_top, uc_bottom, type='skellam', **kwargs)[source]¶

Bases: _LayerStackingMixin, LinearFitFunctions

property layers¶: Return the cyclic layer identifiers.

property uc_area¶

Return the lower interface unit-cell area in Angstrom squared.

The lower unit cell defines the canonical lateral cell of the interface structure factor.

setReferenceUnitCell(uc, rotMatrix=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))[source]¶

Set the reference frame on the interface and generated layers.

Parameters:

uc (UnitCell) – Unit cell defining input reciprocal lattice units.
rotMatrix (numpy.ndarray) – Optional 3-by-3 rotation from the reference frame into the interface crystal frame.

setEnergy(E)[source]¶

Set X-ray energy for the source and generated unit cells.

Parameters:: E (float) – X-ray energy in eV.

set_below(loc, height)[source]¶: Place the interface at the generated height of the object below.

property stacking_height_absolute¶: Return the nominal interface boundary height in Angstrom.

property stacking_loc_absolute¶: Return the nominal interface boundary location in Angstrom.

property layer_state¶: Return the nominal layer state at the upper side of the interface.

F_uc(h, k, l)[source]¶

Return the interface structure factor in electrons.

Upper- and lower-material amplitudes are first converted to area densities using their own UnitCell.uc_area, added, and then multiplied by the lower unit-cell area. The returned amplitude therefore corresponds to one lower lateral unit cell.

Parameters:

h (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
k (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
l (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.

Returns:

Complex interface amplitude in electrons.

Return type:

numpy.ndarray

addFitParameter(indexarray, limits=(-inf, inf), **kwarg)[source]¶: to assign multiple unitcells with the same fitparameter, provide list of unitcell names as kwarg unitcell

addRelParameter(indexarray, factors, limits=(-inf, inf), **kwarg)[source]¶: to assign multiple unitcells with the same fitparameter, provide list of unitcell names as kwarg unitcell

updateFromParameters()[source]¶: Update basis from the values stored in the Parameters

toStr(showErrors=True)[source]¶

Serialize the interface as plain text.

Parameters:: showErrors (bool) – Include propagated interface and nested unit-cell errors.
Returns:: Plain-text interface representation.
Return type:: str

class orgui.datautils.xrayutils.CTRfilm.PoissonSurface(unitcell, **kwargs)[source]¶

Bases: _LayerStackingMixin, LinearFitFunctions

Signed Poisson growth or etching at a nominal Film boundary.

For the current API, W is the signed Poisson mean in structural layers and offset is a deterministic height offset. Positive W models growth, negative W models dissolution or etching, and offset = -W preserves the original mean Film height.

Legacy files using Width/layers deltaW/layers remain readable with their historical absolute-width semantics.

property layers¶: Return the cyclic layer identifiers.

property uc_area¶: Return the surface lateral unit-cell area in Angstrom squared.

setReferenceUnitCell(uc, rotMatrix=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))[source]¶

Set the reference frame on the surface and generated layers.

Parameters:

uc (UnitCell) – Unit cell defining input reciprocal lattice units.
rotMatrix (numpy.ndarray) – Optional 3-by-3 rotation from the reference frame into the surface crystal frame.

setEnergy(E)[source]¶

Set X-ray energy for the surface and generated layers.

Parameters:: E (float) – X-ray energy in eV.

property stacking_height_absolute¶: Return the expected surface height in Angstrom.

property stacking_loc_absolute¶: Return the nominal boundary location in Angstrom.

property mean_height_absolute¶: Return the expected surface height in Angstrom.

createLayers()[source]¶: Create layer domains and their Poisson surface occupancies.

F_uc(h, k, l)[source]¶

Return the Poisson surface correction in electrons.

Positive occupancies add grown material and negative occupancies remove etched material relative to the sharp Film boundary. The amplitude corresponds to one lateral surface unit cell.

Parameters:

h (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
k (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.
l (numpy.ndarray) – Reference-frame reciprocal coordinate in r.l.u.

Returns:

Complex surface-correction amplitude in electrons.

Return type:

numpy.ndarray

addFitParameter(indexarray, limits=(-inf, inf), **kwarg)[source]¶: to assign multiple unitcells with the same fitparameter, provide list of unitcell names as kwarg unitcell

addRelParameter(indexarray, factors, limits=(-inf, inf), **kwarg)[source]¶: to assign multiple unitcells with the same fitparameter, provide list of unitcell names as kwarg unitcell

updateFromParameters()[source]¶: Update basis from the values stored in the Parameters

toStr(showErrors=True)[source]¶

Serialize the Poisson surface as plain text.

Parameters:: showErrors (bool) – Include propagated surface and nested unit-cell errors.
Returns:: Plain-text Poisson-surface representation.
Return type:: str