pyextal.superspace.modulation ============================= .. py:module:: pyextal.superspace.modulation .. autoapi-nested-parse:: Modulation functions and the modulated atom. In a modulated structure an atom's position, occupancy and displacement parameters are not numbers but *functions* of the internal coordinate ``xbar = (xbar_4, ..., xbar_(3+d))``, periodic with period 1 in each component. Everything here is a truncated Fourier series in that coordinate:: u(xbar) = sum_n [ A_n sin(2 pi n.xbar) + B_n cos(2 pi n.xbar) ] with ``n`` a d-dimensional integer harmonic index. The published 1T-TaS2 refinement used 21 harmonics on Ta and 12 on S, so the representation has to carry an arbitrary number of them rather than assume a single wave. Displacements are held in **fractional** coordinates of the basic cell, which makes the structure-factor phase a plain dot product with the effective reciprocal index and keeps the units straight. Classes ------- .. autoapisummary:: pyextal.superspace.modulation.Harmonic pyextal.superspace.modulation.DisplaciveModulation pyextal.superspace.modulation.OccupationalModulation pyextal.superspace.modulation.ModulatedAtom Functions --------- .. autoapisummary:: pyextal.superspace.modulation.phase_shift pyextal.superspace.modulation.invert Module Contents --------------- .. py:class:: Harmonic One term of a Fourier series in the internal coordinate. :ivar n: (d,) integer harmonic index. :vartype n: tuple :ivar sin: Amplitude of the sine term -- (3,) for a displacive modulation, () for an occupational one. :vartype sin: np.ndarray :ivar cos: Amplitude of the cosine term, same shape as `sin`. :vartype cos: np.ndarray .. py:attribute:: n :type: tuple .. py:attribute:: sin :type: numpy.ndarray .. py:attribute:: cos :type: numpy.ndarray .. py:method:: __post_init__() .. py:property:: order ``sum |n_j|``, the harmonic order. :type: int .. py:class:: DisplaciveModulation(harmonics=(), d=1) Bases: :py:obj:`_FourierSeries` Positional modulation: a displacement field over internal space. :ivar harmonics: Terms with (3,) amplitudes, in fractional coordinates of the basic cell. :vartype harmonics: tuple[Harmonic] :ivar d: Number of modulation dimensions. :vartype d: int .. py:method:: evaluate(xbar) Displacement at each internal coordinate. :param xbar: (npts, d) internal coordinates. :type xbar: np.ndarray :returns: (npts, 3) displacement in fractional coordinates; all zeros when there are no harmonics. :rtype: np.ndarray .. py:method:: max_amplitude() float: Largest single-harmonic amplitude, for grid sizing. .. py:class:: OccupationalModulation(average=1.0, harmonics=(), d=1) Bases: :py:obj:`_FourierSeries` Occupancy as a function of internal coordinate. :ivar average: The ``n = 0`` term, i.e. the mean occupancy. :vartype average: float :ivar harmonics: Terms with scalar amplitudes. :vartype harmonics: tuple[Harmonic] :ivar d: Number of modulation dimensions. :vartype d: int .. py:attribute:: average .. py:method:: evaluate(xbar) Occupancy at each internal coordinate. :param xbar: (npts, d) internal coordinates. :type xbar: np.ndarray :returns: (npts,) occupancies. :rtype: np.ndarray .. py:class:: ModulatedAtom One atom of the basic structure, with its modulation functions. :ivar label: Free-form name, e.g. ``'Ta1'``. :vartype label: str :ivar element: Symbol used to look up the scattering factor. :vartype element: str :ivar position: (3,) fractional coordinates in the basic cell. :vartype position: np.ndarray :ivar occupancy: Site occupancy of the basic structure; ignored when `occupational` is set, which carries its own average. :vartype occupancy: float :ivar B: Isotropic displacement parameter in Angstrom^2. Modulated ADPs are not implemented -- see the module note in :mod:`~pyextal.superspace.structurefactor`. :vartype B: float :ivar displacive: Positional modulation. :vartype displacive: DisplaciveModulation, optional :ivar occupational: Occupancy modulation. :vartype occupational: OccupationalModulation, optional .. py:attribute:: label :type: str .. py:attribute:: element :type: str .. py:attribute:: position :type: numpy.ndarray .. py:attribute:: occupancy :type: float :value: 1.0 .. py:attribute:: B :type: float :value: 0.0 .. py:attribute:: displacive :type: DisplaciveModulation :value: None .. py:attribute:: occupational :type: OccupationalModulation :value: None .. py:method:: __post_init__() .. py:method:: displacement(xbar) Displacement field, zeros if the atom is not positionally modulated. :param xbar: (npts, d) internal coordinates. :type xbar: np.ndarray :returns: (npts, 3) fractional displacements. :rtype: np.ndarray .. py:method:: occupation(xbar) Occupancy field, constant if the atom is not occupationally modulated. :param xbar: (npts, d) internal coordinates. :type xbar: np.ndarray :returns: (npts,) occupancies. :rtype: np.ndarray .. py:function:: phase_shift(series, tau) The same modulation seen from an internal-space origin moved by `tau`. An atom generated by a superspace centring translation ``(E | t, tau_i)`` carries its parent's modulation evaluated at ``xbar - tau_i``. Rewriting A sin(2 pi n.(xbar - tau)) + B cos(2 pi n.(xbar - tau)) back into sine and cosine of ``2 pi n.xbar`` mixes the two amplitudes through ``phi = 2 pi n.tau``:: A' = A cos(phi) + B sin(phi) B' = -A sin(phi) + B cos(phi) which is exact, so no resampling or interpolation is involved. :param series: The parent's modulation, or None. :type series: DisplaciveModulation or OccupationalModulation :param tau: (d,) internal-space shift. :type tau: array-like :returns: The same type as `series` with shifted harmonics, or None if `series` was None. .. py:function:: invert(series) The modulation of the atom related to this one by a centre of symmetry. Inversion sends ``r -> -r``, hence ``xbar -> -xbar`` and ``u -> -u``, so ``u'(xbar) = -u(-xbar)``: the sine amplitudes are unchanged and the cosine amplitudes change sign. An atom sitting *on* an inversion centre must therefore have no cosine terms at all -- which is exactly why the published 1T-TaS2 refinement reports every cosine amplitude of Ta as zero. :param series: The parent's modulation, or None. :type series: DisplaciveModulation :returns: The image atom's modulation. :rtype: DisplaciveModulation or None