Wyckoff Symmetry And Fitting¶

The CTR symmetry helpers make Wyckoff information available as metadata on ordinary UnitCell atoms. Structure-factor calculations still use normal UnitCell.basis coordinates; symmetry is used only for queries, file persistence, and optional fit-parameter construction.

The symmetry construction path uses optional PyXtal support. Importing CTRcalc, CTRuc, or CTRsymmetry does not import PyXtal. PyXtal is only required when assigning symmetry from a structure seed or querying Wyckoff tables. Files that already contain saved symmetry metadata can be loaded and fitted without PyXtal.

Building A Surface Symmetry Model¶

Use CTRsymmetry.model_from_seed to assign parent-crystal Wyckoff sites and then build a commensurate CTR surface unit cell:

import numpy as np
from orgui.datautils.xrayutils import CTRsymmetry

surface_spec = CTRsymmetry.SurfaceCellSpec(
    parent_a=(4.653255, 4.653255, 2.9692),
    parent_alpha=(90.0, 90.0, 90.0),
    transform=np.asarray(
        [
            [1.0, 0.0, 1.0],
            [-1.0, 0.0, 1.0],
            [0.0, 1.0, 0.0],
        ]
    ),
    layer_origins=(0.0, 0.5),
    translation_range=1,
)

model = CTRsymmetry.model_from_seed(parent_structure, surface_spec, tol=1e-3)
unitcell = model.build_unitcell("RuO2")

The transform columns are surface-cell vectors expressed in parent conventional fractional coordinates. Parent coordinates are mapped to the surface cell as:

\[p_{\mathrm{surface}} = S^{-1}(p_{\mathrm{parent}} - p_{\mathrm{origin}}).\]

If PyXtal standardizes or reorients the input structure, the surface transform must be expressed in that PyXtal parent basis.

Querying Wyckoff Metadata¶

UnitCell exposes resolved metadata:

unitcell.wyckoff_sites()
unitcell.wyckoff_couplings("O_4f")
unitcell.wyckoff_site_couplings("O_4f")
unitcell.atom_wyckoff_metadata(0)

wyckoff_sites() returns site dictionaries with the site id, element, Wyckoff label, free variables, generated atom indices, space group, and status. The status is one of:

metadata_only: Symmetry metadata is present, but no Wyckoff-related fit parameter has been added.
symmetry_preserving: A true Wyckoff variable fit was added with addWyckoffParameter.
site_displaced: A representative-site shift was added with addWyckoffShift. This moves all atoms in the assigned site together, but may lower the crystallographic site symmetry.
partially_overridden: A manual atom-coordinate parameter touches atoms in the site.

Two Fit Modes¶

addWyckoffParameter fits a true Wyckoff variable such as u, v, or w. It preserves the assigned Wyckoff-site symmetry because all equivalent atom coordinates are updated through the stored affine Wyckoff couplings:

unitcell.addWyckoffParameter(
    "O_4f",
    "u",
    absolute_limits=(0.28, 0.34),
)

The fitted value is a delta from the stored variable value. For rutile oxygen, coordinates such as u, 1-u, 0.5+u, and 0.5-u therefore move with the correct signs.

addWyckoffShift fits a parent conventional fractional displacement of the representative site coordinate:

unitcell.addWyckoffShift(
    "O_4f",
    "x",
    limits=(-0.02, 0.02),
)

Here "x", "y", and "z" are parent conventional fractional axes, not generated surface-cell axes. The shift is propagated through the stored space-group operation for each generated atom and then through the surface-cell transform. This intentionally keeps the original atom assignment and atom count while allowing the site to move away from its exact Wyckoff constraint.

Plural helpers are available for fitting several variables or shifts:

unitcell.addWyckoffParameters("Mg_8d")          # all free variables
unitcell.addWyckoffShifts("Mg_8d", axes=("x", "z"))

Container Classes¶

Film and PoissonSurface forward Wyckoff helper calls to their single template unit cell:

film.addWyckoffParameter("O_4f", "u", limits=(-0.05, 0.05))
poisson.addWyckoffShift("O_4f", "x", limits=(-0.02, 0.02))

EpitaxyInterface follows the same selector convention as its existing addFitParameter API. Select the internal unit cell with unitcell:

interface.addWyckoffParameter(
    "O_4f",
    "u",
    limits=(-0.05, 0.05),
    unitcell="top",
)

interface.addWyckoffShift(
    "O_4f",
    "x",
    limits=(-0.02, 0.02),
    unitcell=["top", "bottom"],
)

When a list is supplied, one parameter is added to each selected internal unit cell. They remain separate parameters unless a higher-level SXRDCrystal coupled parameter links them.

Linking Across Unit Cells¶

SXRDCrystal provides the same two Wyckoff helper modes at the crystal level. These helpers create one coupled crystal parameter and ordinary relative fit parameters inside each selected unit cell.

For a symmetry-preserving Wyckoff variable:

crystal.addWyckoffParameter(
    {
        "RuO2": ("O_4f", "u"),
        "TiO2": ("O_4f", "u"),
    },
    name="shared_rutile_oxygen_u",
    limits=(-0.05, 0.05),
)

For a representative-site shift:

crystal.addWyckoffShift(
    {
        "RuO2": ("O_4f", "x"),
        "TiO2": ("O_4f", "x"),
    },
    name="shared_oxygen_x_shift",
    limits=(-0.02, 0.02),
)

For EpitaxyInterface components, select the internal unit cell in the value dictionary, or use a (component, unitcell) key:

crystal.addWyckoffParameter(
    {
        "interface": {
            "site_id": "O_4f",
            "variable": "u",
            "unitcell": ("top", "bottom"),
        }
    },
    name="shared_interface_u",
    limits=(-0.05, 0.05),
)

crystal.addWyckoffShift(
    {("interface", "top"): ("O_4f", "x")},
    name="top_interface_oxygen_shift",
    limits=(-0.02, 0.02),
)

Persistence¶

Symmetry-bearing .xtal and .xpr files store resolved plain-text tables after the layer metadata. The persisted information includes:

space group number and symbol;
surface transform and origin;
Wyckoff site ids, labels, variables, and representative parent coordinates;
generated atom metadata;
Wyckoff variable couplings;
representative-site shift couplings.

Reloaded files can be queried and fitted with addWyckoffParameter and addWyckoffShift without PyXtal because the resolved couplings are already present in the file.

API Reference¶

Symmetry metadata helpers for CTR surface unit cells.

The construction helpers in this module can use PyXtal to assign parent-cell atoms to Wyckoff positions. The generated surface atoms are ordinary CTRuc.UnitCell atoms; symmetry information is kept as metadata so the structure-factor calculation remains unchanged.

class orgui.datautils.xrayutils.CTRsymmetry.AffineExpression(constant: float, coefficients: dict[str, float]=<factory>)[source]

Bases: object

Represent one fractional coordinate as an affine expression.

Parameters:

constant (float) – Constant coordinate offset in fractional coordinates.
coefficients (dict) – Mapping from variable name to fractional-coordinate coefficient.

evaluate(variables)[source]

Evaluate the expression for a variable dictionary.

Parameters:: variables (dict) – Mapping from variable name to current fractional-coordinate value.
Returns:: Coordinate value in fractional units.
Return type:: float

shifted(shift)[source]

Return a copy with an added constant offset.

Parameters:: shift (float) – Offset in fractional coordinates.
Returns:: Shifted expression.
Return type:: AffineExpression

class orgui.datautils.xrayutils.CTRsymmetry.SurfaceCellSpec(parent_a: tuple[float, float, float], parent_alpha: tuple[float, float, float], transform: ndarray, origin: tuple[float, float, float] = (0.0, 0.0, 0.0), z_bounds: tuple[float, float] = (0.0, 1.0), layer_origins: tuple[float, ...] | None = None, translation_range: int | tuple[int, int] = 1)[source]

Bases: object

Describe an oriented surface cell derived from a parent cell.

Parameters:

parent_a – Parent conventional-cell lengths in Angstrom.
parent_alpha – Parent conventional-cell angles in degrees.
transform – 3-by-3 matrix whose columns are the surface-cell vectors expressed in parent conventional fractional coordinates.
origin – Surface-cell origin in parent conventional fractional coordinates.
z_bounds – Inclusive lower and exclusive upper bounds in surface fractional z.
layer_origins – Optional fractional z positions used as layer starts. If provided, atoms are assigned to intervals between successive origins.
translation_range – Parent-cell integer translations tested in each direction before the surface cell is wrapped and deduplicated.

property inverse_transform

Return the parent-to-surface fractional-coordinate transform.

Returns:: Inverse of transform.
Return type:: numpy.ndarray

parent_translations()[source]

Generate parent conventional-cell translations to search.

Returns:: Iterator over integer translation vectors in parent fractional coordinates.
Return type:: iterator

surface_lattice_parameters()[source]

Return surface-cell lengths and angles.

Returns:: Tuple (a, alpha) where a contains lengths in Angstrom and alpha contains angles in degrees.
Return type:: tuple

parent_to_surface(parent_fractional)[source]

Transform parent conventional fractional coordinates to surface coordinates.

Parameters:: parent_fractional – Fractional coordinate in the parent conventional cell.
Returns:: Fractional coordinate in the surface cell.
Return type:: numpy.ndarray

class orgui.datautils.xrayutils.CTRsymmetry.WyckoffSiteSpec(site_id: str, element: str, wyckoff_label: str, coordinates: tuple[tuple[~orgui.datautils.xrayutils.CTRsymmetry.AffineExpression, ~orgui.datautils.xrayutils.CTRsymmetry.AffineExpression, ~orgui.datautils.xrayutils.CTRsymmetry.AffineExpression], ...], representative_parent_fractional: tuple[float, float, float] | None = None, operation_matrices: tuple[~numpy.ndarray, ...] = (), variables: dict[str, float] = <factory>, occ: float = 1.0, iDW: float = 0.5, oDW: float = 0.5)[source]

Bases: object

Describe one affine Wyckoff site in the parent conventional cell.

Parameters:

site_id (str) – Stable site identifier used by query and parameter APIs.
element (str) – Element symbol for generated atoms.
wyckoff_label (str) – Crystallographic Wyckoff label, for example "4f".
coordinates (tuple) – Parent-cell coordinate expressions for all symmetry-generated atoms.
variables (dict) – Current values of the independent Wyckoff variables.
occ (float) – Site occupancy.
iDW (float) – In-plane Debye-Waller parameter.
oDW (float) – Out-of-plane Debye-Waller parameter.

parent_positions()[source]

Evaluate the parent conventional-cell positions.

Returns:: List of fractional coordinates in the parent conventional cell.
Return type:: list

class orgui.datautils.xrayutils.CTRsymmetry.WyckoffCoupling(atom_index: int, coordinate: str, variable: str, constant: float, factor: float, site_id: str)[source]

Bases: object

Describe one atom-coordinate dependency on a Wyckoff variable.

Parameters:

atom_index (int) – Index of the generated atom in UnitCell.basis.
coordinate (str) – Coordinate name, one of "x", "y", or "z".
variable (str) – Wyckoff variable name.
constant (float) – Constant part in surface fractional coordinates.
factor (float) – Variable coefficient in surface fractional coordinates.
site_id (str) – Site identifier owning the coupling.

value(variable_value)[source]

Evaluate this coordinate for a variable value.

Parameters:: variable_value (float) – Variable value in fractional coordinates.
Returns:: Surface fractional coordinate.
Return type:: float

class orgui.datautils.xrayutils.CTRsymmetry.WyckoffSiteCoupling(atom_index: int, coordinate: str, axis: str, factor: float, site_id: str)[source]

Bases: object

Describe one atom-coordinate dependency on site representative motion.

Parameters:

atom_index (int) – Index of the generated atom in UnitCell.basis.
coordinate (str) – Surface coordinate name, one of "x", "y", or "z".
axis (str) – Parent conventional representative coordinate, one of "x", "y", or "z".
factor (float) – Surface-coordinate coefficient for a parent representative-coordinate displacement.
site_id (str) – Site identifier owning the coupling.

class orgui.datautils.xrayutils.CTRsymmetry.GeneratedWyckoffAtom(atom_index: int, element: str, site_id: str, wyckoff_label: str, parent_fractional: ndarray, surface_fractional: ndarray, layer: int, couplings: tuple[WyckoffCoupling, ...] = (), site_couplings: tuple[WyckoffSiteCoupling, ...] = ())[source]

Bases: object

Metadata for one generated surface-cell atom.

Parameters:

atom_index (int) – Index in UnitCell.basis.
element (str) – Element symbol.
site_id (str) – Source Wyckoff site identifier.
wyckoff_label (str) – Source Wyckoff label.
parent_fractional (numpy.ndarray) – Parent conventional fractional coordinate including the selected parent-cell translation.
surface_fractional (numpy.ndarray) – Wrapped surface-cell fractional coordinate.
layer (int) – Assigned layer index stored in UnitCell.basis[:, 7].
couplings (tuple) – Coordinate couplings for this atom.

class orgui.datautils.xrayutils.CTRsymmetry.SurfaceSymmetryModel(surface_spec: ~orgui.datautils.xrayutils.CTRsymmetry.SurfaceCellSpec, sites: tuple[~orgui.datautils.xrayutils.CTRsymmetry.WyckoffSiteSpec, ...], atoms: list[~orgui.datautils.xrayutils.CTRsymmetry.GeneratedWyckoffAtom] = <factory>, spacegroup_number: int | None = None, spacegroup_symbol: str | None = None)[source]

Bases: object

Hold generated surface-cell atoms and their symmetry metadata.

wyckoff_sites(parameters=None)[source]

Return summary dictionaries for generated Wyckoff sites.

Parameters:: parameters (dict) – Optional UnitCell.parameters dictionary used to report whether individual atom-coordinate parameters break a site’s symmetry.
Returns:: List of site summary dictionaries.
Return type:: list

wyckoff_couplings(site_id=None)[source]

Return Wyckoff variable couplings for generated atom coordinates.

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

wyckoff_site_couplings(site_id=None)[source]

Return site-displacement couplings for generated atom coordinates.

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

atom_wyckoff_metadata(atom_index)[source]

Return metadata for one generated atom.

Parameters:: atom_index (int) – Index in UnitCell.basis.
Returns:: Atom metadata or None when the atom has no symmetry metadata.
Return type:: GeneratedWyckoffAtom or None

symmetry_status(site_id, parameters=None)[source]

Return whether a site is still fully symmetry-preserving.

Parameters:

site_id (str) – Site identifier.
parameters (dict) – Optional UnitCell.parameters dictionary.

Returns:

"metadata_only", "symmetry_preserving", or "partially_overridden".

Return type:

str

build_unitcell(name, layer_behavior='ignore')[source]

Create a CTRuc.UnitCell and attach this model as metadata.

Parameters:

name (str) – Unit-cell name.
layer_behavior (str) – Layer behavior passed to CTRuc.UnitCell.

Returns:

Generated unit cell containing ordinary CTR atoms.

Return type:

CTRuc.UnitCell

orgui.datautils.xrayutils.CTRsymmetry.possible_wyckoff_positions(spacegroup, style='pyxtal')[source]

Return possible Wyckoff positions for a space group using PyXtal.

PyXtal is imported lazily by this function.

Parameters:

spacegroup (int) – International space-group number.
style (str) – PyXtal Wyckoff setting style.

Returns:

List of dictionaries with label, multiplicity, and dof.

Return type:

list

Raises:

ImportError – If PyXtal is not installed.

orgui.datautils.xrayutils.CTRsymmetry.sites_from_seed(seed, tol=0.0001, a_tol=5.0, backend='pymatgen', style='pyxtal', iDW=0.5, oDW=0.5, occ=1.0, variable_names=('u', 'v', 'w'))[source]

Assign parent atoms to Wyckoff sites using PyXtal.

PyXtal is imported lazily by this function. seed may be any input accepted by pyxtal.pyxtal().from_seed(), including a CIF path, pymatgen Structure, or ASE Atoms.

Parameters:

seed – Structure seed accepted by PyXtal.
tol (float) – Coordinate tolerance passed to PyXtal.
a_tol (float) – Angle tolerance in degrees passed to PyXtal.
backend (str) – PyXtal seed backend.
style (str) – PyXtal Wyckoff setting style.
iDW (float) – In-plane Debye-Waller parameter assigned to generated sites.
oDW (float) – Out-of-plane Debye-Waller parameter assigned to generated sites.
occ (float) – Occupancy assigned to generated sites.
variable_names (tuple) – Names for Wyckoff free variables in order of PyXtal free coordinates.

Returns:

Tuple (sites, spacegroup_number, spacegroup_symbol).

Return type:

tuple

Raises:

ImportError – If PyXtal is not installed.

orgui.datautils.xrayutils.CTRsymmetry.model_from_seed(seed, surface_spec, tol=0.0001, a_tol=5.0, backend='pymatgen', style='pyxtal', iDW=0.5, oDW=0.5, occ=1.0, variable_names=('u', 'v', 'w'))[source]

Build a surface symmetry model from a PyXtal-compatible seed.

Parameters:

seed – Structure seed accepted by PyXtal.
surface_spec (SurfaceCellSpec) – Surface-cell transform and parent lattice.

Returns:

Surface symmetry model ready to build a UnitCell.

Return type:

SurfaceSymmetryModel

orgui.datautils.xrayutils.CTRsymmetry.surface_unitcell_from_seed(seed, surface_spec, name, layer_behavior='ignore', **kwargs)[source]

Build a generated CTR surface UnitCell from a PyXtal-compatible seed.

Parameters:

seed – Structure seed accepted by PyXtal.
surface_spec (SurfaceCellSpec) – Surface-cell transform and parent lattice.
name (str) – Unit-cell name.
layer_behavior (str) – Layer behavior passed to CTRuc.UnitCell.
kwargs – Additional keyword arguments passed to model_from_seed().

Returns:

Generated CTR unit cell with attached symmetry metadata.

Return type:

CTRuc.UnitCell

orgui.datautils.xrayutils.CTRsymmetry.rutile_110_surface_spec(parent_a, parent_alpha=(90.0, 90.0, 90.0))[source]

Return the standard rutile (110) commensurate surface-cell spec.

The surface basis columns are [1 -1 0], [0 0 1], and [1 1 0] in parent conventional fractional coordinates.

Parameters:

parent_a – Parent conventional-cell lengths in Angstrom.
parent_alpha – Parent conventional-cell angles in degrees.

Returns:

Surface-cell specification.

Return type:

SurfaceCellSpec

orgui.datautils.xrayutils.CTRsymmetry.generate_surface_atoms(surface_spec, sites, tolerance=1e-08)[source]

Generate surface-cell atom metadata from parent Wyckoff sites.

Parameters:

surface_spec (SurfaceCellSpec) – Surface-cell transform and bounds.
sites (tuple) – Parent-cell Wyckoff site specifications.
tolerance (float) – Fractional-coordinate tolerance for bounds and deduplication.

Returns:

Generated atom metadata. atom_index values match the returned list order and therefore the order used by SurfaceSymmetryModel.

Return type:

list

orgui.datautils.xrayutils.CTRsymmetry.symmetry_metadata_to_lines(model)[source]

Serialize symmetry metadata as editable plain-text table lines.

Parameters:: model (SurfaceSymmetryModel) – Symmetry model to serialize.
Returns:: Lines without trailing newline characters.
Return type:: list

orgui.datautils.xrayutils.CTRsymmetry.symmetry_metadata_from_lines(lines, unitcell=None)[source]

Deserialize plain-text table lines into a symmetry metadata model.

This parser has no PyXtal dependency and is used when loading .xtal and .xpr files containing resolved symmetry metadata.

Parameters:

lines (list) – Symmetry metadata lines.
unitcell (CTRuc.UnitCell) – Optional unit cell providing fallback lattice and atom values.

Returns:

Parsed symmetry model, or None when no symmetry data is present.

Return type:

SurfaceSymmetryModel or None

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

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