spin polarization: edits to examples, docs, tests

docsrc/spinpolarization.html

@@ -99,7 +99,23 @@ <h1>Spin-polarized systems and photoselection</h1>
 </pre>
 
 <p>
-Alternatively, you can take advantage of the fact that T<sub>x</sub>, T<sub>y</sub> and T<sub>z</sub> are equal to the zero-field states. Provide populations for the zero-field states in order of ascending energy and specify <code>'zerofield'</code> as the basis. For example
+Here is a full example of a triplet generated by ISC from an excited singlet state
+</p>
+<pre class="matlab">
+Triplet.S = 1;
+Triplet.D = [500 -100];  % MHz
+Triplet.lwpp = 1;  % mT
+Triplet.initState = {[0.2 0.5 0.3],'xyz'};  % Tx, Ty, Tz
+
+Exp.mwFreq = 9.5;  % GHz
+Exp.Range = [310 370];  % mT
+Exp.Harmonic = 0;  % no field modulation
+
+pepper(Triplet,Exp);
+</pre>
+
+<p>
+Alternatively, you can use the fact that T<sub>x</sub>, T<sub>y</sub> and T<sub>z</sub> are equal to the zero-field states. Provide populations for the zero-field states in order of ascending energy and specify <code>'zerofield'</code> as the basis. For example
 </p>
 
 <pre class="matlab">
@@ -131,22 +147,6 @@ <h1>Spin-polarized systems and photoselection</h1>
 Be careful in determining the energy order of the zero-field triplet states correctly when using <code>Sys.initState</code> with the <code>'zerofield'</code> basis to simulate spectra from the literature, or when interpreting results from least-squares fitting.
 </p>
 
-<p>
-Here is a full example of a triplet generated by ISC from an excited singlet state
-</p>
-<pre class="matlab">
-Triplet.S = 1;
-Triplet.D = [500 -100];  % MHz
-Triplet.lwpp = 1;  % mT
-Triplet.initState = {[0.2 0.5 0.3],'xyz'};  % Tx, Ty, Tz
-
-Exp.mwFreq = 9.5;  % GHz
-Exp.Range = [310 370];  % mT
-Exp.Harmonic = 0;  % no field modulation
-
-pepper(Triplet,Exp);
-</pre>
-
 <p>
 The shape of the EPR spectrum only depends on the <em>polarizations</em> of the transitions, i.e. only on the <em>differences</em> of the populations in <code>Sys.initState</code>. Therefore, adding any constant to all three numbers will not affect the shape of the spectrum. It will, however, affect the overall intensity of the simulated spectrum, since EasySpin does not normalize the populations nor the spectrum.
 </p>

docsrc/spinsystem.html

@@ -328,6 +328,7 @@ <h1>The spin system</h1>
 
 <p>
 With these angles, EasySpin can transform a g tensor from its diagonal eigenframe representation to the molecular frame representation. Here is an explicit example how this is done:
+</p>
 
 <pre class="matlab">
 gpv = [2.1 1.97 2.04];       % principal values
@@ -340,6 +341,7 @@ <h1>The spin system</h1>
 
 <p>
 which gives the following output
+</p>
 
 <pre class="mloutput">
 R_M2g =
@@ -546,6 +548,7 @@ <h1>The spin system</h1>
 
 <p>
 Here is an example of how to convert from e<sup>2</sup>Qq/h and &eta; to the three principal Q values:
+</p>
 
 <pre class="matlab">
 eeQqh = 1;     % MHz
@@ -589,6 +592,7 @@ <h1>The spin system</h1>
 
 <p>
 Here is how principal values and angles can be converted to a full matrix:
+</p>
 
 <pre class="matlab">
 Qpv = [-0.9 -1.1 2]*0.125;        % principal values, MHz
@@ -719,7 +723,7 @@ <h1>The spin system</h1>
 <p>
 Prior to EasySpin 5, the field <code>Dpa</code> was used instead of <code>DFrame</code>.
 To convert old <code>Dpa</code> values to <code>DFrame</code>, invert the order and flip the sign of the three Euler angles.
-    
+</p>
 
 </div>
 &nbsp;<br>
@@ -820,6 +824,7 @@ <h1>The spin system</h1>
 
 <p>
 For each pair of electron spins, a <a href="hamiltonian.html#eei">bilinear coupling matrix</a> (composed of isotropic, anisotropic, and antisymmetric terms) can be given. You can enter it in one of several ways:
+</p>
 <ul>
 <li>Give the isotropic, symmetric, and antisymemtric parts separately in <code>Sys.J</code>, <code>Sys.dip</code>, and <code>Sys.dvec</code>.
 <li>Give the principal values of the coupling matrix in <code>Sys.ee</code> (with <code>Sys.eeFrame</code>).
@@ -937,6 +942,7 @@ <h1>The spin system</h1>
 </em>
 <p>
 List of vectors (one per row, in units of MHz) that describe the antisymmetric part of the coupling between two electron spins (Dzyaloshinskii-Moriya interaction). The associated <a href="hamiltonian.html#eei">spin Hamiltonian</a> is d<sub>12</sub>.(S<sub>1</sub>xS<sub>2</sub>), where d<sub>12</sub> is the interaction vector. 
+</p>
 
 <pre class="matlab">
 Sys.S = [1/2 1/2];    % two spins
@@ -946,6 +952,7 @@ <h1>The spin system</h1>
 
 <p>
 For more than two spins, the vectors are ordered in lexicographic order, for example 1-2, 1-3, 2-3 for a three-spin system.
+</p>
 
 <pre class="matlab">
 Sys.S = [1 1 1];        % three spins
@@ -957,6 +964,7 @@ <h1>The spin system</h1>
 
 <p>
 You can use either <code>Sys.J</code> (together with <code>Sys.dip</code> and <code>Sys.dvec</code> if needed) or <code>Sys.ee</code> (with <code>Sys.eeFrame</code>), but not both at the same time.
+</p>
 </div>
 </div>
 
@@ -990,17 +998,18 @@ <h1>The spin system</h1>
 
 <p>
 If only isotropic couplings are needed, use <code>Sys.J</code> (see above).
-
+</p>
 <p>
 It is also possible to specify the full 3x3 interaction matrices instead of the 3 principal values and 3 Euler angles. These matrices combine the isotropic, antisymmetric and symmetric parts of the interaction. For a 2-electron system, <code>ee</code> is a single 3x3 array.
-
+</p>
 <pre class="matlab">
 Sys.S = [1/2 1/2];                   % two spins
 Sys.ee = [80 0 0;0 80 0; 0 0 20];   % one coupling matrix, MHz
 </pre>
 
 <p>
 For more electrons, the 3x3 matrices are stacked on top of each other, to give a 3Nx3 array.
+</p>
 
 <pre>
 Sys.S = [1/2 1/2 1/2];                   % three spins
@@ -1176,7 +1185,6 @@ <h1>The spin system</h1>
 <a name="soi"><div class="subtitle">Orbital angular momenta and spin-orbit interaction</div></a>
 Each electron spin in the spin system can be coupled to an orbital angular momentum, with the associated quantum number defined in the field <code>L</code> and the associated isotropic orbital g factors in the field <code>gL</code> . Spin-orbit coupling is specified via the field <code>soc</code>. Orbital angular momenta are supported by the simulation functions <a class="esf" href="pepper.html">pepper</a> (solid-state EPR) and <a class="esf" href="curry.html">curry</a> (magnetometry).
 
-<p>
 <div class="optionfield"><code>L</code></div>
 <div class="optiondescr">
 Gives the quantum numbers for orbital angular momenta to which the electron spins are coupled. <code>L</code> is an optional field. If given, it must have the same number of entries as <code>S</code> and the entries have to be nonnegative integers. The kth orbital angular momentum is coupled to the kth spin angular momentum. Examples:
@@ -1203,6 +1211,7 @@ <h1>The spin system</h1>
 
 <p>
 Each field that is given should contain a row vector of 2k+1 parameters, in order of decreasing q, running from +k to -k. For example:
+</p>
 
 <pre class="matlab">
 Sys.CF2 = [0 0 560 0 0];          % CF(2,q) with q = +2,+1,0,-1,-2
@@ -1212,6 +1221,7 @@ <h1>The spin system</h1>
 
 <p>
 In the common case that only the q=0 element is needed for a given k, it can be given alone in an abbreviated syntax valid for any k.
+</p>
 
 <pre class="matlab">
 Sys.CF2 = [0 0 99 0 0];  % CF(2,0) only, full form
@@ -1223,6 +1233,7 @@ <h1>The spin system</h1>
 
 <p>
 If more than one electron spin (and therefore more than one orbital angular moment) is present, specify one row of 2k+1 elements for each orbital angular moment. The first row is for the first orbital angular moment, etc.
+</p>
 
 <pre class="matlab">
 Sys.S = [5/2 2];     % two spins
@@ -1278,13 +1289,15 @@ <h1>The spin system</h1>
 <a name="Ham"><div class="subtitle">General parameters for spin Hamiltonian expanded in magnetic field and electron spin</div></a>
 <p>
 The Spin-Hamiltonian is in general a polynom of the magnetic field and the spin operator. This general expansion is implemented for electron spins (not for nuclei). Currently, general parameter are supported by the simulation functions <a class="esf" href="pepper.html">pepper</a> (solid-state EPR)and <a class="esf" href="curry.html">curry</a>. The coefficients can be provided in the following way:
+</p>
 <div class="optionfield"><code>Ham</code></div>  
 <div class="optiondescr">
 The coefficients C(p<sub>B</sub>, p<sub>S</sub>, p, q) should be real and in units of MHz (mT)<sup>-p<sub>B</sub></sup>.The p<sub>B</sub>, p<sub>S</sub>, p are integrated in the field name in this order. If any of these fields are not given, they are treated as zero.
 Each field that is given should contain a row vector of 2p+1 parameters, in order of decreasing q, running from +p to -p. For example: 
 <pre class="matlab">
 Sys.Ham134 = [0 0 36 0 0 0 12 0 0 0]; % pB = 1, pS = 3, p = 4, q = +4,+3,+2,+1,0,-1,-2,-3,-4
-</pre></p>
+</pre>
+
 <pre class="matlab">
 %convert the more common D and E:
 Sys.Ham022 = [sqrt(2)*E 0 sqrt(2/3)*D 0 0];
@@ -1348,27 +1361,32 @@ <h1>The spin system</h1>
 
 <p>
 The options for defining non-equilibrium states through <code>Sys.initState</code> are the following:
+</p>
+
 <ul>
-<li>Give the population vector and the corresponding basis.
+<li>Population vector and the corresponding basis.
 
 <ul>
-<li> Energy-ordered populations of the eigenstates of the spin Hamiltonian at zero field:
+
+<li>
+Populations of the T<sub>X</sub>, T<sub>Y</sub> and T<sub>Z</sub> states (for triplets only)
 <pre class="matlab">
-Sys.initState = {[p1 p2 p3],'zerofield'};
+Sys.initState = {[pTx pTy pTz],'xyz'};
 </pre>
-E.g., if <code>Sys.initState = {[0.85 0.95 1.2],'zerofield'}</code> for a triplet system (S=1), the population of the lowest-energy zero-field state has a population of 0.85, the middle one has 0.95, and the highest-energy zero-field state has a population of 1.2. If there are coupled nuclei, the populations of all nuclear sublevels within each electron spin manifold are assumed to be equal.
-</p>
-<li> Populations of the X, Y and Z eigenstates of the ZFS interaction Hamiltonian (for <code>Sys.S = 1</code> only)
+
+<li>
+Populations of the eigenstates of the spin Hamiltonian at zero field, in order of increasing energy:
 <pre class="matlab">
-Sys.initState = {[px py pz],'xyz'};
+Sys.initState = {[p1 p2 p3],'zerofield'};
 </pre>
-</p>
-<li> Populations of the eigenstates of the full spin Hamiltonian in order of increasing energy
+E.g., if <code>Sys.initState = {[0.85 0.95 1.2],'zerofield'}</code> for a triplet system (S=1), the population of the lowest-energy zero-field state has a population of 0.85, the middle one has 0.95, and the highest-energy zero-field state has a population of 1.2. If there are coupled nuclei, the populations of all nuclear sublevels within each electron spin manifold are assumed to be equal.
+
+<li> Populations of the eigenstates of the full spin Hamiltonian, in order of increasing energy
 <pre class="matlab">
 Sys.initState = {[p1 p2 p3],'eigen'};
 </pre>
 E.g. <code>Sys.initState = {[0 1 0],'eigen'}</code> for a triplet system (S=1) corresponds to a triplet state populated only in the high-field T<sub>0</sub> level, for example from recombination from a radical pair.
-</p>
+
 <li> Populations of the coupled basis states for systems of two spins
 <pre class="matlab">
 Sys.initState = {[pTp pT0 pTm pS],'coupled'}; % for two coupled S = 1/2
@@ -1378,7 +1396,7 @@ <h1>The spin system</h1>
 </p>
 </ul>
 
-<li>Give the density matrix and the corresponding basis.
+<li>Density matrix and the corresponding basis.
 <ul>
 <li>
 <pre class="matlab">
@@ -1403,12 +1421,12 @@ <h1>The spin system</h1>
 </ul>
 </p>
 
-<li>Give a string specifying the initial state. The available shorthands are:
+<li>String shorthand specifying the initial state. The available shorthands are:
 
 <ul>
 <li> Spin polarisation arising from population of the singlet state for two coupled identical spins (e.g. spin-correlated radical pair with singlet precursor)
 <pre class="matlab">
-Sys.initState = 'singlet';
+Sys.initState = 'singlet';   % only possible if Sys.S = [1/2 1/2]
 </pre> 
 </p>
 <li> Spin polarisation arising from population of the T<sub>0</sub> sublevel in a triplet state (e.g. for a triplet formed by recombination from a spin-correlated radical pair state)
@@ -1424,7 +1442,7 @@ <h1>The spin system</h1>
 </p>
 
 <p>
-In the presence of degenerate energy levels at zero field, the states for the <code>zerofield</code> basis are not uniquely defined, preventing unambiguous assignment of the provided energy-ordered populations to basis states within EasySpin. In order to simulate spectra for these cases, the full non-equilibrium density matrix should be provided in the uncoupled basis (see <a href="../examples/photoexcitation/triplet_axialZFS_spinpolarized.m">triplet_axialZFS_spinpolarized.m</a> for an example illustrating this for a triplet state with axial ZFS).
+In the presence of degenerate energy levels at zero field, the states for the <code>'zerofield'</code> basis are not uniquely defined, preventing unambiguous assignment of the provided energy-ordered populations to basis states within EasySpin. In order to simulate spectra for these cases, the full non-equilibrium density matrix should be provided in the uncoupled basis (see <a href="../examples/photoexcitation/triplet_axialZFS_spinpolarized.m">triplet_axialZFS_spinpolarized.m</a> for an example illustrating this for a triplet state with axial ZFS).
 </p>
 
 <p>

examples/photoexcitation/quartet_PDITEMPO.m

@@ -1,7 +1,6 @@
 % Photoexcited quartet state
 %===========================================================
-% Photoexcitation of a PDI-TEMPO molecule leads to a 
-% spin-polarised quartet state 
+% Photoexcitation of a PDI-TEMPO molecule leads to a spin-polarised quartet state 
 % 
 % see
 %  - Mayländer et al, J. Am. Chem. Soc., 143, 7050–7058 (2021)
@@ -20,29 +19,30 @@
 Sys.DStrain = [100 100; 0 0];
 
 % Coupling between triplet and doublet states
-Sys.J = -1.2e3; % MHz
-Sys.dip = -66;%[-65 -65 130]; % MHz
+Sys.J = -1.2e3;  % MHz
+Sys.dip = -66;%[-65 -65 130];  % MHz
 
 Sys.Nucs = '14N';
-Sys.A = [0 0 19 96]; % MHz
+Sys.A = [0 0 19 96];  % MHz
+
+Sys.lw = 0.65;  % mT
 
 % High-field state populations (different populations of nuclear sublevels)
 Pop = [0 0 0 0.50 0.63 0.77 0.13 0.00 0.80 0.85 0.54 0.48 0.04 0.96 0.04 0 0 0];
 Sys.initState = {Pop,'eigen'};
 
-Sys.lw = 0.65; % mT
-
 % Experimental parameters
-Exp.Range = [1165 1260]; % mT
-Exp.mwFreq = 34; % GHz
-Exp.nPoints = 4096;
+Exp.Range = [1165 1260];  % mT
+Exp.mwFreq = 34;  % GHz
 Exp.Harmonic = 0;
 
+% Spectral simulation
 [B,spc] = pepper(Sys,Exp);
 
 % Plot result
 title('PDI-TEMPO quartet state')
 hold on; box on;
-plot(B,spc,'k')
+plot(B,spc)
 axis tight
 xlabel('Magnetic Field (mT)')
+grid on

examples/photoexcitation/scrp_spinpolarized_transitions.m

@@ -22,7 +22,7 @@
 Sys.lwpp = 0.04; % mT
 
 % Set up the initial density matrix (in the uncoupled basis of EasySpin)
-S = cgmatrix(Sys.S(1),Sys.S(2),0).';
+S = cgmatrix(Sys.S(1),Sys.S(2),0).';  % singlet state
 Sys.initState = S*S';
 
 Exp.Range = [346.5 349.5]; % mT

examples/photoexcitation/triplet_C60fullerene.m

@@ -9,21 +9,21 @@
 clear
 
 Sys.S = 1;
-Sys.g = 2.00; % neglecting small anisotropy
+Sys.g = 2.00;  % neglecting small anisotropy
 
 % Wasielewski 1991 values for zero-field splitting
-D = -0.0114 * 100*clight/1e6; % cm^-1 -> MHz
-E = 0.00069 * 100*clight/1e6; % cm^-1 -> MHz
+D_cm = -0.0114;  % cm^-1
+E_cm =  0.00069;  % cm^-1
 
-Sys.D = [D E]; % MHz
+Sys.D = [D_cm E_cm] * 100*clight/1e6;  % cm^-1 -> MHz
 
-Sys.lwpp = 0.9; % mT
+Sys.lwpp = 0.9;  % mT
 
-Exp.mwFreq = 9.248; % GHz
-Exp.Range = [310 350]; % mT
+Exp.mwFreq = 9.248;  % GHz
+Exp.Range = [310 350];  % mT
 
 % The three numbers in the first input to Sys.initState give the
-% relative populations of the three sublevels, X, Y and Z at zero-field
+% relative populations of the three sublevels Tx, Ty and Tz
 Sys.initState = {[0.5 0.5 0],'xyz'};
 
 pepper(Sys,Exp);