pyextal.callBloch¶

Attributes¶

`_BACKENDS`
`_workers_spawned`

Classes¶

`Data`	Data class to store the data of each tilt calculated by the bloch engine.
`SimParams`	Data class to store the data and parameters from the simulation.
`DataCollector`	Data collector class to retrieve data as a callback function.

Functions¶

`_check_backend`(backend)	Raise ValueError for an unknown backend name.
`updateUgh`(reflections, values[, beamDict])	Update the Ugh matrix in the common block with the given values.
`updateSymUgh`(reflections, values[, sym])	Update the Ugh matrix with given values, including all symmetry-related beams.
`symmetrizeVHKL`()	Symmetrize the structure factor adjusted in the .dat file.
`lookupSF`(reflections[, IAM, phase])	Look up the default structure factor for given reflections.
`lookupReflections`()	Look up all non-zero reflections.
`_fortran_fname`(fname)	Encodes a .dat path for the Fortran parser.
`bloch`(fname[, t_x, t_y, reflections, values, HKL, ...])	Simulate the diffraction pattern point-to-point (no interpolation).
`bloch_parse`(fname[, t_x, t_y, HKL])	Parse the .dat file.
`_eigenStoreError`(status, ntilt, nout)	Explains a failed eigen-solution gather (gather_eigen in bloch_mpi.f90).
`tilt_run`(param, tilts[, indices, ncores, HKL, backend])	Run the simulation for a given set of tilts. The eigenvalue/vectors are stored in blochwave.bloch_module
`bloch_run`(param[, HKL, subaper, subnx, subny, pixsiz, ...])	Construct a tilt net and run the simulation.
`simulate`(fname, thickness, displayParam[, t_x, t_y, ...])	Wrapper for bloch_run and cbedp to simulate and return the diffraction pattern.
`LARBED`(param, thickness[, height, width, tiltmap])	Calculate the LARBED pattern for a given thickness.
`LARBED_tilt`(param, thickness, nout[, backend])	Calculate the LARBED pattern for a given thickness with eigenvector/values store in blochwave.bloch_module.
`terminate`()	Deallocate the arrays in the blochwave module and stop the MPI workers.
`calibrateLARBED`(param, gl)	Calibrate LARBED parameters.
`calibrateCBED`(dp, center, centerTiltx, centerTilty, ...)	Calibrate CBED parameters.
`wavelength`([kv])	Calculate the wavelength of an electron beam in Angstroms based on the accelerating voltage.
`tilt`(param, t_x, t_y)	Calculate the tilt vector for a given tilt in x and y directions.
`tiltUnit`(param)	Calculate the tilt unit vectors.
`e2Xray`(→ numpy.ndarray)	Calculate the X-ray scattering factor for a given beam.
`adjustDWF`(→ None)	Adjust the Debye-Waller factor for the simulation.

Module Contents¶

pyextal.callBloch._BACKENDS = ('numpy', 'fortran')¶

pyextal.callBloch._workers_spawned = False¶

pyextal.callBloch._check_backend(backend)¶: Raise ValueError for an unknown backend name.

class pyextal.callBloch.Data¶

Data class to store the data of each tilt calculated by the bloch engine.

Variables:

ndiag (int) – Number of diagonal elements.
itilt (tuple) – (3,) tilt vector.
ix (int) – x index of the tilt.
iy (int) – y index of the tilt.
gamma (np.ndarray) – Eigenvalues.
eigenvector (np.ndarray) – Eigenvectors.
cinv (np.ndarray) – 1st column of the inverse of the eigenvectors.
cinv_full (np.ndarray, optional) – Full inverse eigenvector matrix (ndiag × ndiag). Set by the NumPy backend for multi-layer propagation; None when using the Fortran backend.

ndiag: int¶

itilt: tuple¶

ix: int¶

iy: int¶

gamma: numpy.ndarray¶

eigenvector: numpy.ndarray¶

cinv: numpy.ndarray¶

cinv_full: numpy.ndarray | None = None¶

property vr¶: Real part of the eigenvalues.

property vi¶: Imaginary part of the eigenvalues.

property ccr¶: Real part of the eigenvectors.

property cci¶: Imaginary part of the eigenvectors.

class pyextal.callBloch.SimParams¶

Data class to store the data and parameters from the simulation.

Variables:

ntilt (int) – Number of tilts.
nout (int) – Number of reflections.
nx (int) – Half width of sampling region.
hklout (np.ndarray) – (3, nout) np.int32 np.array of reflection indices.
disks (float) – Disk radius.
alpha (float) – Angle incidence.
tilt0 (np.ndarray) – (3,) np.float32 np.array of incident tilt.
gg (np.ndarray) – (3,) np.float32 np.array horizontal reciprocal vector of dp.
gh (np.ndarray) – (3,) np.float32 np.array vertical reciprocal vector of dp.
gmx (np.ndarray) – (3, 3) np.float32 np.array of gram tensor (gram matrix).
gmxr (np.ndarray) – (3, 3) np.float32 np.array of inverse of gram tensor (gram matrix).
snorm (np.ndarray) – (3,) np.float32 np.array of surface normal.
bigK (float) – Magnitude of refraction adjusted wave vector.
tilts (list) – List of Data class, each element is the data of each tilt.

ntilt: int¶

nout: int¶

nx: int¶

hklout: numpy.ndarray¶

disks: float¶

alpha: float¶

tilt0: numpy.ndarray¶

gg: numpy.ndarray¶

gh: numpy.ndarray¶

gmx: numpy.ndarray¶

gmxr: numpy.ndarray¶

snorm: numpy.ndarray¶

bigK: float¶

tilts: list¶

__post_init__()¶

__call__(i1, itilt)¶

Update blochwave parameters and pass data to cbedp common block. callback for bloch engine intensity calculation! DO NOT CALL THIS DIRECTLY! :param i1: 1-based index for the tilt. :type i1: int :param itilt: Array to be updated with the x, y index of the tilt. :type itilt: np.ndarray

Returns:: Updated itilt array.
Return type:: np.ndarray

larbedCall(i1)¶

Pass data to cbedp common block for LARBED calculation. Callback for bloch engine intensity calculation! DO NOT CALL THIS DIRECTLY!

Parameters:: i1 (int) – 1-based index for the tilt.
Returns:: The tilt vector.
Return type:: np.ndarray

cbedpCall(i1, itilt)¶

Pass data to cbedp common block for CBED calculation. Callback for cbedpy.cbedp — different from larbedCall: Fortran already knows the pixel position itilt=[ix,iy] and passes it in; no return needed. DO NOT CALL THIS DIRECTLY!

Parameters:

i1 (int) – 1-based index for the tilt.
itilt (np.ndarray) – (2,) int32 pixel coords [ix, iy] from Fortran.

simParam()¶

Return the simulation parameters as a tuple.

Returns:: A tuple containing the simulation parameters.
Return type:: tuple

store(filename='simParam.h5')¶

Store the simulation parameters to a file in HDF5 format.

Parameters:: filename (str, optional) – The name of the file to save to. Defaults to ‘simParam.h5’.

class pyextal.callBloch.DataCollector¶

Data collector class to retrieve data as a callback function.

tilts = []¶

__call__(ndiag, itilt, ix, iy, nout, ib=None)¶

Callback function to collect data from bloch engine diagonalization.

Parameters:

ndiag (int) – Number of diagonal elements.
itilt (tuple) – The tilt vector.
ix (int) – The x index of the tilt.
iy (int) – The y index of the tilt.
nout (int) – The number of reflections.
ib (np.ndarray, optional) – Beam indices. Defaults to None.

Returns:

Always returns 0.

Return type:

int

pyextal.callBloch.updateUgh(reflections, values, beamDict=None)¶

Update the Ugh matrix in the common block with the given values.

Parameters:

reflections (list) – List of tuples (nref,) for reflection indices, e.g., [(1, 1, 1), (1, 1, 0)].
values (np.ndarray) – (nref, 4) or (nref, 2) array of structure factor values. For (nref, 4): Ugh, phase, U’gh, phase. Ugh should always be positive. For (nref, 2): Ugh, U’gh.
beamDict (dict, optional) – Dictionary mapping beam pairs to their positions in the Ugh matrix. Defaults to None.

pyextal.callBloch.updateSymUgh(reflections, values, sym=None)¶

Update the Ugh matrix with given values, including all symmetry-related beams.

Parameters:

reflections (list) – List of tuples (nref,) for reflection indices, e.g., [(1, 1, 1), (1, 1, 0)].
values (np.ndarray) – (nref, 4) or (nref, 2) array of structure factor values. For (nref, 4): Ugh, phase, U’gh, phase. For (nref, 2): Ugh, U’gh.
sym (GroupSymmetry, optional) – GroupSymmetry class instance for symmetry-related beams. Defaults to None.

Note

the phaseDiff is a result of translation in the symmetry operation.

pyextal.callBloch.symmetrizeVHKL()¶: Symmetrize the structure factor adjusted in the .dat file.

pyextal.callBloch.lookupSF(reflections, IAM=False, phase=True)¶

Look up the default structure factor for given reflections. The default values are from Bird and King, Acta Cryst. A 46 (1990) 202.

Parameters:

reflections (list) – List of tuples (nref,) for reflection indices, e.g., [(1, 1, 1), (1, 1, 0)].
IAM (bool, optional) – If True, use the independent atom model (IAM) for all structure factors. If False, return the adjusted structure factor from the .dat file. Defaults to False.

Returns:

(nref, 4) array of structure factor values (Ugh, phase (deg), U’gh, phase (deg)).

Return type:

np.ndarray

pyextal.callBloch.lookupReflections()¶

Look up all non-zero reflections.

Returns:: A list of all reflections excluding the (0, 0, 0) beam.
Return type:: list

pyextal.callBloch._fortran_fname(fname)¶

Encodes a .dat path for the Fortran parser.

bloch_parse (bloch_sub.f90) takes the name as character(len=*), so any length works.

Parameters:: fname (str | Path) – Path to the .dat file.
Returns:: The UTF-8 bytes, as f2py expects.
Return type:: np.ndarray

pyextal.callBloch.bloch(fname, t_x=0, t_y=0, reflections=None, values=None, HKL=False, subaper=0, subnx=None, subny=None, pixsiz=0, ncores=1, xaxis=None, dryrun=False, backend='numpy')¶

Simulate the diffraction pattern point-to-point (no interpolation).

Parameters:

fname (str) – Path to the .dat file.
t_x (float, optional) – Tilt in the x direction (deg). Defaults to 0.
t_y (float, optional) – Tilt in the y direction (deg). Defaults to 0.
reflections (list, optional) – List of tuples (nref,) for reflection to adjust indices, e.g., [(1, 1, 1), (1, 1, 0)]. Defaults to None.
values (np.ndarray, optional) – (4, nref) array of structure factor values (Ugh, phase (deg), U’gh, phase (deg)) to adjust. Defaults to None.
HKL (bool, optional) – If True, return the hkl indices of the included beams. Defaults to False.
subaper (int, optional) – Aperture function. 0 or None: No aperture. 1: Circular aperture of input size nx (Standard CBED). 2: Custom circular aperture of radius (subnx1+subnx2). 3: Custom rectangular aperture of shape (subnx),(subny). Defaults to 0.
subnx (int, optional) – Dependent on subaper parameter. Defaults to None.
subny (int, optional) – Dependent on subaper parameter. Defaults to None.
pixsiz (float, optional) – Pixel size in diffraction space. Defaults to 0.
ncores (int, optional) – Number of cores to use. Defaults to 1.
xaxis (np.ndarray, optional) – (3,) array for the x-axis of the diffraction space. Defaults to None.
dryrun (bool, optional) – If True, perform a dry run to estimate memory usage without running the full simulation. Defaults to False.
backend (str, optional) – Simulation backend. ‘numpy’ (default): NumPy eigendecomposition on a thread pool. ‘fortran’: Fortran+MPI eigendecomposition backend (MPI build only).

Returns:

SimParams object containing simulation results, or estimated memory usage if dryrun is True. np.ndarray, optional: If HKL is True, returns a (nbeams, 3) array of reflection indices.

Return type:

SimParams or float

pyextal.callBloch.bloch_parse(fname, t_x=0, t_y=0, HKL=False)¶

Parse the .dat file.

Parameters:

fname (str) – Path to the .dat file.
t_x (float, optional) – Tilt in the x direction (deg). Defaults to 0.
t_y (float, optional) – Tilt in the y direction (deg). Defaults to 0.
HKL (bool, optional) – If True, return the hkl indices of the included
False. (beams. Defaults to)

Returns:

An empty SimParams object with simulation info. np.ndarray, optional: If HKL is True, returns a (nbeams, 3) array of reflection indices.

Return type:

SimParams

pyextal.callBloch._eigenStoreError(status, ntilt, nout)¶

Explains a failed eigen-solution gather (gather_eigen in bloch_mpi.f90).

Parameters:

status (int) – Status returned by the engine: 1 the Python process, 2 an MPI worker could not allocate its buffers, 3 too many columns for an MPI count.
ntilt (int) – Number of tilts simulated.
nout (int) – Number of output beams stored per tilt.

Returns:

The error message.

Return type:

str

pyextal.callBloch.tilt_run(param, tilts, indices=None, ncores=1, HKL=False, backend='numpy')¶

Run the simulation for a given set of tilts. The eigenvalue/vectors are stored in blochwave.bloch_module

Parameters:

param (SimParams) – SimParams object with simulation parameters.
tilts (np.ndarray) – (n, 3) array of tilt vectors.
indices (np.ndarray, optional) – (n,) array of indices. Defaults to None.
ncores (int, optional) – Number of cores to use. Defaults to 1.
HKL (bool, optional) – If True, return the hkl indices of the included
False. (beams. Defaults to)

Returns:

The updated SimParams object. np.ndarray, optional: If HKL is True, returns a (nbeams, 3) array of reflection indices.

Return type:

SimParams

pyextal.callBloch.bloch_run(param, HKL=False, subaper=0, subnx=None, subny=None, pixsiz=0, ncores=1, xaxis=None, backend='numpy')¶

Construct a tilt net and run the simulation.

Parameters:

param (SimParams) – SimParams object with simulation parameters.
HKL (bool, optional) – If True, return the hkl indices of the included beams. Defaults to False.
subaper (int, optional) – Aperture function. 0 or None: No aperture. 1: Circular aperture of input size nx (Standard CBED). 2: Custom circular aperture of radius (subnx1+subnx2). 3: Custom rectangular aperture of shape (subnx),(subny). Defaults to 0.
subnx (int, optional) – Dependent on subaper parameter. Defaults to None.
subny (int, optional) – Dependent on subaper parameter. Defaults to None.
pixsiz (float, optional) – Pixel size in diffraction space. Defaults to 0.
ncores (int, optional) – Number of cores to use. Defaults to 1.
xaxis (np.ndarray, optional) – (3,) array for the x-axis of the
None. (diffraction space. Defaults to)
backend (str, optional) – ‘numpy’ (default) or ‘fortran’ (MPI build only).

Returns:

The updated SimParams object. np.ndarray, optional: If HKL is True, returns a (nbeams, 3) array of reflection indices.

Return type:

SimParams

pyextal.callBloch.simulate(fname, thickness, displayParam, t_x=0, t_y=0, reflections=None, values=None, HKL=False, subaper=0, subnx=None, subny=None, pixsiz=0, ncores=1, dryrun=False, backend='numpy')¶

Wrapper for bloch_run and cbedp to simulate and return the diffraction pattern.

Parameters:

fname (str) – Path to the .dat file.
thickness (float) – Thickness of the sample in Angstroms.
displayParam (list) – List of parameters for display: [x0, y0, gl, xs, ys, theta].
t_x (float, optional) – Tilt in the x direction (deg). Defaults to 0.
t_y (float, optional) – Tilt in the y direction (deg). Defaults to 0.
reflections (list, optional) – List of tuples (nref,) for reflection indices, e.g., [(1, 1, 1), (1, 1, 0)]. Defaults to None.
values (np.ndarray, optional) – (4, nref) array of structure factor values (Ugh, phase (deg), U’gh, phase (deg)). Defaults to None.
HKL (bool, optional) – If True, return the hkl indices of the included beams. Defaults to False.
subaper (int, optional) – Aperture function. 0 or None: No aperture. 1: Circular aperture of input size nx (Standard CBED). 2: Custom circular aperture of radius (subnx1+subnx2). 3: Custom rectangular aperture of shape (subnx),(subny). Defaults to 0.
subnx (int, optional) – Dependent on subaper parameter. Defaults to None.
subny (int, optional) – Dependent on subaper parameter. Defaults to None.
pixsiz (float, optional) – Pixel size in diffraction space. Defaults to 0.
ncores (int, optional) – Number of cores to use. Defaults to 1.
dryrun (bool, optional) – If True, perform a dry run to estimate memory
False. (usage. Defaults to)

Returns:

(xs, ys) array of the diffraction pattern. SimParams: SimParams object with simulation parameters. np.ndarray, optional: If HKL is True, returns a (nout, 3) array of reflection indices.

Return type:

np.ndarray

pyextal.callBloch.LARBED(param, thickness, height=None, width=None, tiltmap=False)¶

Calculate the LARBED pattern for a given thickness.

Parameters:

param (SimParams) – SimParams object with simulation parameters.
thickness (int or np.ndarray) – Thickness of the sample in Angstroms. Can be a single int or a (ntilt,) array.
height (int, optional) – Height of the diffraction pattern. Defaults to None.
width (int, optional) – Width of the diffraction pattern. Defaults to None.
tiltmap (bool, optional) – If True, return the tilt map. Defaults to False.

Returns:

(nout, height, width) array of diffraction patterns. np.ndarray, optional: If tiltmap is True, returns a (nx, nx, 3) array of the tilt map.

Return type:

np.ndarray

pyextal.callBloch.LARBED_tilt(param, thickness, nout, backend='numpy')¶

Calculate the LARBED pattern for a given thickness with eigenvector/values store in blochwave.bloch_module.

Parameters:

param (SimParams) – SimParams object with simulation parameters.
thickness (int or np.ndarray) – Thickness of the sample in Angstroms. Can be a single int or a (ntilt,) array.
nout (int) – Number of output points.
backend (str, optional) – ‘numpy’ (default) reads from param.tilts populated by the numpy tilt_run; ‘fortran’ reads from the Fortran eigen arrays. Use the backend that ran the solve.

Returns:

(nout, ntilt) array of diffraction patterns.

Return type:

np.ndarray

pyextal.callBloch.terminate()¶

Deallocate the arrays in the blochwave module and stop the MPI workers.

Safe to call with either backend, on either build, and more than once: each Fortran deallocate routine runs only when the arrays it frees are allocated (f2py reports unallocated arrays as None), and the parabloch workers are despawned only if a Fortran bloch_run/tilt_run spawned them.

Warning

This ends the engine for the life of the process. Once it has run, a fresh bloch_parse() followed by bloch_run() returns an all-zero exitwave – re-parsing does not bring it back. Call it as teardown at the very end of a session, never between two simulations or between crystals.

The failure it causes is hard to trace back here: everything downstream keeps running, but every simulated intensity is zero, so a refinement sits motionless and scipy.spatial.distance.correlation returns NaN on the constant input (“invalid value encountered in scalar divide”).

pyextal.callBloch.calibrateLARBED(param, gl)¶

Calibrate LARBED parameters.

Parameters:

param (SimParams) – SimParams object with simulation parameters.
gl (float) – Geometric scaling factor.

Returns:

A tuple containing the side length and scale factor.

Return type:

tuple

pyextal.callBloch.calibrateCBED(dp, center, centerTiltx, centerTilty, gl, param)¶

Calibrate CBED parameters.

Parameters:

dp (np.ndarray) – The diffraction pattern.
center (tuple) – The center of the diffraction pattern.
centerTiltx (float) – The tilt in the x direction at the center.
centerTilty (float) – The tilt in the y direction at the center.
gl (float) – Geometric scaling factor.
param (SimParams) – SimParams object with simulation parameters.

Returns:

A tuple containing the x and y tilt maps.

Return type:

tuple

pyextal.callBloch.wavelength(kv: float = None)¶

Calculate the wavelength of an electron beam in Angstroms based on the accelerating voltage.

Parameters:: kv (float, optional) – Accelerating voltage in kilovolts (kV). If not provided, uses the default value from blochwave.difpar.kv.
Returns:: The calculated electron wavelength in Angstroms.
Return type:: float

Notes

The calculation uses the relativistic electron wavelength formula:

λ = 0.3878314 / sqrt(kv * (1 + 0.97846707e-3 * kv))

where kv is the accelerating voltage in kV.

Returns:: The wavelength in Angstroms.
Return type:: float

pyextal.callBloch.tilt(param, t_x, t_y)¶

Calculate the tilt vector for a given tilt in x and y directions.

Parameters:

param (SimParams) – SimParams object with simulation parameters.
t_x (float) – Tilt in the x direction (deg).
t_y (float) – Tilt in the y direction (deg).

pyextal.callBloch.tiltUnit(param)¶

Calculate the tilt unit vectors.

Parameters:: param (SimParams) – SimParams object with simulation parameters.
Returns:: A tuple containing the tilt unit vectors in the x and y directions.
Return type:: tuple

pyextal.callBloch.e2Xray(beam: tuple, getESF: callable) → numpy.ndarray¶

Calculate the X-ray scattering factor for a given beam.

Parameters:

beam (tuple) – The beam for which the X-ray scattering factor is to be calculated.
getESF (callable) – A function to get the electron scattering factor.

Returns:

The X-ray scattering factor for the given beam.

Return type:

np.ndarray

pyextal.callBloch.adjustDWF(dwf: list) → None¶

Adjust the Debye-Waller factor for the simulation.

Parameters:

dwf (list) –

A list of Debye-Waller factors for each atom. Can be either:

Isotropic B factors: list of floats, one per atom.
Anisotropic beta_ij: list of 6-element sequences per atom in order [β11, β22, β33, β12, β13, β23].

Raises:

ValueError – If the length of dwf does not match the number of atoms.