pyextal.superspace.tas2 ======================= .. py:module:: pyextal.superspace.tas2 .. autoapi-nested-parse:: 1T-TaS2 in its nearly commensurate phase: the worked example. Reference --------- A. Spijkerman, J. L. de Boer, A. Meetsma, G. A. Wiegers and S. van Smaalen, "X-ray crystal-structure refinement of the nearly commensurate phase of 1T-TaS2 in (3+2)-dimensional superspace", Phys. Rev. B 56, 13757 (1997). doi:10.1103/PhysRevB.56.13757 :func:`structure` returns that published model by default -- superspace group P-3(alpha,beta,1/3), 21 harmonics on Ta and 12 on S, transcribed from Tables III, IV and V. ``model='standin'`` gives a small invented triple-q wave instead, which is faster and useful for demonstrations that do not need the real amplitudes. The two settings ---------------- The paper works in a **tripled cell**, ``a0 x a0 x 3c0``, in which the modulation wave vectors are purely in-plane and the three layers are generated by superspace centring translations that carry an internal phase shift. All published parameters refer to that cell, so it is the authoritative setting here (``setting='tripled'``). The same reflections can be *indexed* in the **basic cell** ``a0 x a0 x c0``, where the wave vectors pick up commensurate components of +/- 1/3 along c0* (paper, section II). :func:`published_q`, :func:`tripled_to_basic` and :func:`basic_to_tripled` do that, and it is verified: the two settings put every reflection at the same place to 2e-16, and give the same structure factors to 8e-16 for the *unmodulated* structure. **The modulated structure is only available in the tripled setting.** In the basic cell ``q`` has a c-component, so an atom's own z enters its internal coordinate -- ``xbar_basic = xbar_tripled + q_z * z`` -- and the published modulation functions are written against the tripled convention, where it does not. Carrying them across needs an atom-dependent phase that neither a constant internal shift nor a per-atom shift by ``q_z z`` reproduces (both were tried; they leave 2-4% residuals against the tripled model). Rather than ship a structure that is quietly a few per cent wrong, :func:`published_atoms` refuses ``setting='basic'``. The tripled setting is the paper's own and is what every check in this module validates. What was checked ---------------- The amplitudes in Tables IV and V are quoted "in angstrom" referred to the ``a0 x a0 x 3c0`` cell, which is ambiguous enough to be worth verifying rather than assuming. Recomputing the paper's own published figures from the transcribed tables gives: =========================================== ========== ========== quantity recomputed paper =========================================== ========== ========== Ta max ``|u_xy|`` (Fig. 6) 0.3080 A 0.308 A Ta-Ta(100) shortest (Figs. 3-5) 3.0865 A 3.086 A Ta-Ta(100) longest (Figs. 3-5) 3.8079 A 3.806 A S ``u_z`` maximum (Fig. 10) +0.116 A +0.106 A S ``u_z`` minimum (Fig. 10) -0.114 A -0.124 A =========================================== ========== ========== The three Ta numbers agree to four significant figures, which fixes the convention: ``Ax``, ``Ay``, ``Az`` are displacements in Angstrom along a, b and c of the tripled cell, so fractional amplitudes are ``Ax/a0``, ``Ay/b0``, ``Az/(3 c0)``. The S extremes sit about 0.01 A off, in opposite directions. That is not a transcription error -- flipping the sign of any one harmonic group makes the agreement worse, and every relation in the paper's Table I closes on the transcribed values. Figure 10 plots a particular symmetry copy of S, at (2/3, 1/3, 0.086), read off contours spaced 0.0177 A apart, so half a contour interval of disagreement on a quantity a tenth the size of the Ta modulation is where this is left. The Ta modulation, which dominates every satellite intensity, is confirmed exactly. One transcription correction ---------------------------- Table V's ``B^y`` for the harmonic ``(-1, 1)`` is entered here as **-0.0107**, not +0.0107. Two independent arguments require the minus. Table I's own relation ``B^y_{-m1-m2,m1} = -B^x_{-m2,m1+m2}`` gives -0.0107; and with the positive sign the sulfur modulation violates its three-fold site symmetry by 0.043 A, a third of its own amplitude, which shows up as a [001] diffraction pattern that is visibly not three-fold. The PDF renders a minus sign as the digit 2, and this one is lost on extraction. ``test_superspace.py`` checks every dependent amplitude in both tables against Table I, which is what caught it. One inconsistency in the source ------------------------------- Table III gives S at ``(1/3, 1/3, 0.0862)``, Fig. 1 gives the basic structure's S at ``+/-(1/3, 2/3, z)``, and section V C refers to S at ``(2/3, 1/3, 0.086)``. These are not the same site. The standard CdI2-type positions ``+/-(1/3, 2/3, z)`` are used here, since they are the only ones giving Ta its octahedral sulfur coordination. That the refinement reports every cosine amplitude of Ta as zero is an independent confirmation that Ta sits on the inversion centre, as this choice requires. Attributes ---------- .. autoapisummary:: pyextal.superspace.tas2.CELL_BASIC pyextal.superspace.tas2.CELL pyextal.superspace.tas2.CELL_TRIPLED pyextal.superspace.tas2.SIGMA pyextal.superspace.tas2.TA_HARMONICS pyextal.superspace.tas2.S_HARMONICS pyextal.superspace.tas2.CZ_NC pyextal.superspace.tas2.CZ_C pyextal.superspace.tas2.SIGMA_C Functions --------- .. autoapisummary:: pyextal.superspace.tas2.published_q pyextal.superspace.tas2.commensurate_q pyextal.superspace.tas2.nearly_commensurate_q pyextal.superspace.tas2.reflection_condition pyextal.superspace.tas2.tripled_to_basic pyextal.superspace.tas2.basic_to_tripled pyextal.superspace.tas2.lattice pyextal.superspace.tas2.published_atoms pyextal.superspace.tas2.basic_atoms pyextal.superspace.tas2.ta_displacive pyextal.superspace.tas2.structure pyextal.superspace.tas2.commensurate_structure Module Contents --------------- .. py:data:: CELL_BASIC :value: (3.3649, 3.3649, 5.8971, 90.0, 90.0, 120.0) .. py:data:: CELL :value: (3.3649, 3.3649, 5.8971, 90.0, 90.0, 120.0) .. py:data:: CELL_TRIPLED .. py:data:: SIGMA :value: (0.2448, 0.0681) .. py:data:: TA_HARMONICS .. py:data:: S_HARMONICS .. py:data:: CZ_NC :value: 0.3333333333333333 .. py:data:: CZ_C :value: 0.07692307692307693 .. py:data:: SIGMA_C .. py:function:: published_q(setting='tripled', sigma=SIGMA) The refined modulation wave vectors. In the tripled setting these are ``q1 = (s1, s2, 0)`` and ``q2 = (-s2, s1+s2, 0)``, exactly as the paper states them against ``{a0*, b0*, c*}`` with ``c* = c0*/3``. Re-indexing against ``c0*`` shifts them by the commensurate amounts that fold the ``c*`` component of each reflection into the wave vectors, giving ``q1 -> q1 + c0*/3`` and ``q2 -> q2 - c0*/3``. This is what the paper means by the wave vectors acquiring components of ``+/- 1/3`` along c0*. :param setting: ``'tripled'`` or ``'basic'``. :type setting: str :param sigma: ``(sigma1, sigma2)``. :type sigma: tuple :returns: (2, 3) wave vectors in reciprocal lattice units of the chosen cell. :rtype: np.ndarray :raises ValueError: If `setting` is not recognised. .. py:function:: commensurate_q(c_component=True, n=3, cz=None) The exactly commensurate CDW wave vectors of the C phase. ``qc = (3 a0* + b0*)/13``, i.e. ``(0.2308, 0.0769)`` at ``phi = 13.9`` degrees (paper, section I), with the three-layer stacking term. Being rational these describe a genuine 3D supercell rather than an incommensurate structure, and :meth:`SuperspaceLattice.supercell_matrix` recovers it. :param c_component: Include the ``1/3 c0*`` stacking term of the *nearly* commensurate phase. False gives the in-plane idealisation, whose supercell is 13-fold not 39. Ignored when `cz` is given. :type c_component: bool :param n: How many of the three arms to return, 1 to 3. :type n: int :param cz: The ``c0*`` component outright. Use :data:`CZ_C` (1/13) for the **commensurate** phase, whose supercell is sqrt13 a x sqrt13 a x 13c (paper, section I). The 1/3 that `c_component` selects is the NC stacking and gives 3c instead -- the two phases differ in this component and only in this component. :type cz: float, optional :returns: (n, 3) wave vectors, in *basic*-cell reciprocal units. :rtype: np.ndarray .. py:function:: nearly_commensurate_q(delta=0.006, c_component=True, n=3) CDW wave vectors near, but not at, the commensurate value. Used by the stand-in model. For the real NC phase use :func:`published_q`, whose values are the refined ones. :param delta: Departure from 3/13 along a*, in reciprocal lattice units. :type delta: float :param c_component: Include the ``1/3 c0*`` term. :type c_component: bool :param n: How many arms to return, 1 to 3. :type n: int :returns: (n, 3) wave vectors, in basic-cell reciprocal units. :rtype: np.ndarray .. py:function:: reflection_condition(H) Which tripled-setting reflections the centring translations allow. The centring ``(E | 0,0,1/3 ; 2/3,1/3)`` requires ``exp(2 pi i (l/3 + (2 m1 + m2)/3)) = 1``, that is l + 2 m1 + m2 = 0 (mod 3) Main reflections therefore have ``l`` a multiple of 3, and first-order satellites sit in the planes ``l0 = n +/- 1/3`` -- the arrangement the paper describes in section II. Reflections that fail the condition are systematically absent; their structure factors come out zero anyway, since the three centred copies cancel exactly, so this is a filter for efficiency and for labelling, not a correction. :param H: (n, 5) superspace indices in the tripled setting. :type H: array-like :returns: (n,) booleans, True where the reflection is allowed. :rtype: np.ndarray .. py:function:: tripled_to_basic(H) Convert reflection indices from the tripled setting to the basic one. Equating the ``c0*`` component of the two settings gives it: the tripled setting puts ``l/3`` there and the basic one ``l0 + (m1 - m2)/3``, since its wave vectors carry ``+1/3`` and ``-1/3`` along ``c0*``. So l0 = (l - m1 + m2) / 3 which is an integer exactly when :func:`reflection_condition` holds -- ``l - m1 + m2`` and ``l + 2 m1 + m2`` differ by ``3 m1`` and so agree modulo 3, which is why the condition can be written either way but the *value* cannot. :param H: (n, 5) indices in the tripled setting. :type H: array-like :returns: (n, 5) indices in the basic setting. :rtype: np.ndarray :raises ValueError: If any reflection violates the centring condition, and so has no basic-cell index. .. py:function:: basic_to_tripled(H) Convert reflection indices from the basic setting to the tripled one. :param H: (n, 5) indices in the basic setting. :type H: array-like :returns: (n, 5) indices in the tripled setting. :rtype: np.ndarray .. py:function:: lattice(setting='tripled', model='published', d=2, commensurate=False, c_component=False, delta=0.006, **kw) The 1T-TaS2 superspace lattice. :param setting: ``'tripled'`` or ``'basic'``; used by the published model. :type setting: str :param model: ``'published'`` or ``'standin'``. :type model: str :param d: Modulation dimensions for the stand-in, 1 to 3. The published model is (3+2)D. :type d: int :param commensurate: Use exactly rational q-vectors. For the published model this is the *commensurate approximation* -- the refined modulation functions evaluated on ``(3 a0* + b0*)/13`` instead of the incommensurate wave vectors -- which is the only form with a finite 3D supercell, and so the only one a conventional Bloch-wave calculation can reach. :type commensurate: bool :param c_component: Stand-in only -- include the ``1/3 c0*`` term. :type c_component: bool :param delta: Stand-in only -- departure from 3/13. :type delta: float :param \*\*kw: Passed to :class:`SuperspaceLattice`, e.g. ``check_rank=False``. :returns: The lattice. :rtype: SuperspaceLattice :raises ValueError: If `model` is not recognised. .. py:function:: published_atoms(setting='tripled') The refined structure as a P1 list of modulated atoms. In the tripled setting the three layers are generated by the superspace centring translations, each carrying its internal phase shift -- that shift is what makes the layers different, and it is not derivable from the real-space translation because the wave vectors have no component along c. The second sulfur is the inversion partner of the first, so its sine amplitudes are unchanged and its cosine amplitudes change sign. :param setting: Must be ``'tripled'``; see the module docstring for why ``'basic'`` is refused. :type setting: str :returns: The structure, nine atoms. :rtype: list[ModulatedAtom] :raises ValueError: If `setting` is not recognised. :raises NotImplementedError: If `setting` is ``'basic'``. .. py:function:: basic_atoms(B_ta=None, B_s=None) The three atoms of the basic cell, unmodulated, listed in P1. :param B_ta: Isotropic B for Ta; the refined value when None. :type B_ta: float, optional :param B_s: Isotropic B for S; the refined value when None. :type B_s: float, optional :returns: Ta at the origin and the two sulfurs. :rtype: list[ModulatedAtom] .. py:function:: ta_displacive(lat, amplitude=0.02, harmonics=1) A simple triple-q longitudinal displacement field, for the stand-in. Each CDW arm contributes a wave displacing atoms along its own wave vector. In a (3+2) description the third arm is not independent, so it enters as a harmonic index rather than as a third dimension. :param lat: Supplies the q-vectors and the metric. :type lat: SuperspaceLattice :param amplitude: First-harmonic magnitude in fractional coordinates. :type amplitude: float :param harmonics: Harmonics per arm; higher ones get ``1/n^2``. :type harmonics: int :returns: The field, in fractional coordinates. :rtype: DisplaciveModulation .. py:function:: structure(model='published', setting='tripled', d=2, commensurate=False, c_component=False, amplitude=0.02, harmonics=1, delta=0.006, modulate_sulfur=True, **kw) The 1T-TaS2 structure, published by default. :param model: ``'published'`` for the refined 21 + 12 harmonic model, or ``'standin'`` for the small invented triple-q wave. :type model: str :param setting: Published model only -- ``'tripled'`` or ``'basic'``. :type setting: str :param d: Stand-in only -- modulation dimensions, 1 to 3. :type d: int :param commensurate: Exactly rational q, giving a 3D supercell and hence a dynamical calculation. With ``model='published'`` this is the commensurate approximation to the refined structure. :type commensurate: bool :param c_component: Stand-in only -- include the ``1/3 c0*`` term. :type c_component: bool :param amplitude: Stand-in only -- first-harmonic amplitude. :type amplitude: float :param harmonics: Stand-in only -- harmonics per arm. :type harmonics: int :param delta: Stand-in only -- departure from 3/13. :type delta: float :param modulate_sulfur: Stand-in only -- give S a weaker copy of the same field. :type modulate_sulfur: bool :param \*\*kw: Passed to :class:`SuperspaceLattice`. :returns: ``(lattice, atoms)`` ready for :func:`~pyextal.superspace.structurefactor.structure_factor`. :rtype: tuple :raises ValueError: If `model` is not recognised. .. py:function:: commensurate_structure(cz=0.0, amplitude_scale=1.0) A model of the commensurate phase, in the basic cell. **The wave vectors use the paper's basis**, ``q1 = (s1, s2, cz)`` and ``q2 = (-s2, s1+s2, cz)``, not the three-fold images. That distinction is not cosmetic: the harmonic labels ``(n1, n2)`` in Tables IV and V are *relative to that basis*, so reading them against the three-fold triplet silently rewrites the modulation function. It shows up as a diffraction pattern that is not three-fold, and as a site-symmetry residual of 0.57 A against 4.7e-4 A for the correct basis. **`cz` defaults to zero, and a nonzero value is not three-fold symmetric.** The commensurate phase really does have a sqrt13 a x sqrt13 a x 13c supercell, so its wave vector carries ``q_z = 1/13`` -- but that cannot be represented in this basis. With arms ``{q1, q2, q2 - q1}`` the c components are ``g1, g2, g2 - g1``, which are equal only when both are zero; :func:`~pyextal.superspace.symmetry.epsilon_for` duly reports the three-fold as "not a symmetry" for every basis choice with ``cz = 1/13``. Representing the stacking needs the c component in the *l index* of a 13-fold cell with centring translations, exactly as the paper puts the thirds in a tripled cell -- and the C-phase stacking sequence that would fix those translations is not in the paper. `cz` is left as a parameter for exploring that, with the warning that the result is not the C phase. **This is a model, not a refinement.** The paper refines the *nearly* commensurate phase; there is no published C-phase modulation here to use. What this builds is the refined NC modulation functions evaluated at the commensurate wave vector. It is the right object for comparing *methods* -- an exact supercell calculation against the superspace engine against the kinematic approximation, all on one structure -- but do not read its satellite intensities as a measurement of the C phase. :param cz: ``c0*`` component of q. Zero, the default, is the in-plane commensurate CDW and is three-fold symmetric. See above before setting it. :type cz: float :param amplitude_scale: Multiplies every modulation amplitude, for exploring how a comparison depends on modulation strength. :type amplitude_scale: float :returns: ``(lattice, atoms)`` with three atoms in the basic cell. :rtype: tuple