lots of small edits in examples and documentation

docsrc/diptensor.html

@@ -46,21 +46,21 @@
 <div class="subtitle">Description</div>
 
 <p>
-<code>diptensor</code> calculates the dipolar coupling tensor <code>T</code> (in MHz) between two spins, using the inter-spin distance vector <code>rvec</code> (in nm). It works for dipolar couplings between two electrons, for dipolar couplings between two nuclei, and for dipolar hyperfine couplings between an electron and a nucleus. See the corresponding interactions in the <a href="hamiltonian.html">spin Hamiltonian</a>.
+<code>diptensor</code> calculates the dipolar coupling tensor <code>T</code> (in MHz) between two spins, using the inter-spin distance vector <code>rvec</code> (in nm). It works for dipolar couplings between two electrons, for dipolar couplings between two magnetic nuclei, and for dipolar hyperfine couplings between an electron and a magnetic nucleus. See the corresponding interactions in the <a href="hamiltonian.html">spin Hamiltonian</a>.
 </p>
 
 <p>
-<code>g1</code>, <code>g2</code> and <code>g</code> specify the g tensor for an electron. Provide a single number for an isotropic g value. For an anisotropic g tensor, provide either the full 3x3 matrix or the principal values and the Euler angles
+<code>g1</code>, <code>g2</code> and <code>g</code> specify the g tensor for an electron. For an isotropic g value, provide a single number. For an anisotropic g tensor, provide either the full 3x3 matrix or the principal values and the Euler angles
 </p>
 
 <pre class="matlab">
 g = 2.005;  % isotropic g
-g = diag([2.0085 2.0065 2.0023]);  % full g matrix (here diagonal)
+g = diag([2.0085 2.0065 2.0023]);      % full g matrix (here diagonal)
 g = {[2 2.05 2.13],[30 68 0]*pi/180};  % principal values and Euler angles
 </pre>
 
 <p>
-The Euler angles define the transformation between the molecular frame (in which `rvec` is assumed to be defined) and the g tensor eigenframe. This is identical to the `gFrame` field in the <a href="spinsystem.html">spin system structure</a>.
+The Euler angles define the transformation between the molecular frame (in which <code>rvec</code> is assumed to be defined) and the g tensor eigenframe. This is identical to the <code>gFrame</code> field in the <a href="spinsystem.html">spin system structure</a>.
 </p>
 
 <p>
@@ -81,10 +81,12 @@
 <p>
 The dipolar coupling tensor between two electrons spaced 1 nm apart along the molecular z direction is
 </p>
+
 <pre class="matlab">
 rvec = [0; 0; 1];  % nm
 T = diptensor(gfree,gfree,rvec)
 </pre>
+
 <pre class="mloutput">
 T =
     52.0410         0         0
@@ -95,10 +97,12 @@
 <p>
 The hyperfine coupling tensor between an electron and a proton located 0.3 nm away along the molecular x axis is
 </p>
+
 <pre class="matlab">
 rvec = [0.3; 0; 0];  % nm
 A = diptensor(gfree,'1H',rvec)
 </pre>
+
 <pre class="mloutput">
 A =
     5.8566         0         0
@@ -109,13 +113,15 @@
 <p>
 The dipolar coupling tensor between two electrons 1.5 nm apart in the direction given by polar angles theta = pi/4 and phi = pi/3 is
 </p>
+
 <pre class="matlab">
 phi = pi/3;    % rad
 theta = pi/4;  % rad
 r = 1.5;       % nm
 rvec = ang2vec(phi,theta)*r;
 T = diptensor(gfree,gfree,rvec)
 </pre>
+
 <pre class="mloutput">
 T =
     9.6372  -10.0153  -11.5647
@@ -145,6 +151,7 @@
 [Tpd,Tpv] = eig(T);
 Tpd              % eigenvector matrix
 </pre>
+
 <pre class="mloutput">
 Tpd =
     0.3536    0.8660    0.3536
@@ -166,6 +173,7 @@
 rvec = [0;0.3;1];
 T = diptensor(g1,g2,rvec)
 </pre>
+
 <pre class="mloutput">
 T =
    45.0248   -1.4288   -0.1124
@@ -187,6 +195,7 @@
 rvec = [0;0.3;1];
 T = diptensor({g1pv,g1Frame},{g2pv,g2Frame},rvec)
 </pre>
+
 <pre class="mloutput">
 T =
    45.0238   -1.4284   -0.1130
@@ -203,6 +212,7 @@
 Ts = (T+T.')/2 - T0    % traceless symmetric component
 Ta = (T-T.')/2         % antisymmetric component
 </pre>
+
 <pre class="mloutput">
 T0 =
    -8.4518         0         0

docsrc/erot.html

@@ -36,7 +36,7 @@
 <div class="subtitle">Syntax</div>
 
 <pre class="matlab">
-Rp = erot(Angles)
+Rp = erot(angles)
 Rp = erot(alpha,beta,gamma)
 
 [xc,yc,zc] = erot(...,'cols')
@@ -47,7 +47,7 @@
 <div class="subtitle">Description</div>
 
 <p>
-<code>erot</code> returns an 3x3 rotation matrix in <code>Rp</code>. The 3-element vector <code>Angles=[alpha beta gamma]</code> defines the three <a href="eulerangles.html">Euler angles</a> for the rotation in radians. They can be also specified as three separate arguments <code>alpha</code>, <code>beta</code> and <code>gamma</code>.
+<code>erot</code> returns an 3x3 rotation matrix in <code>Rp</code>. The 3-element vector <code>angles=[alpha beta gamma]</code> defines the three <a href="eulerangles.html">Euler angles</a> for the rotation in radians. They can be also specified as three separate arguments <code>alpha</code>, <code>beta</code> and <code>gamma</code>.
 </p>
 
 <p>
@@ -56,11 +56,15 @@
 
 <p>
 Basically, <code>erot</code> provides a transformation matrix for vectors and matrices. If the Euler angles describe the transformation of the coordinate frame 1 to the coordinate frame 2, then you can use <code>Rp</code> to transform a vector <code>v</code> or tensor <code>A</code> from coordinates 1 to coordinates 2.
+</p>
+
 <pre class="matlab">
-  v2 = Rp*v1;
-  A2 = Rp*A1*Rp.';
+  v2 = Rp*v1;        % transform v from frame 1 to frame 2 representation
+  A2 = Rp*A1*Rp.';   % transform A from frame 1 to frame 2 representation
 </pre>
-This does not rotate the vector or matrix, but transforms them from one coordinate system representation to the other. So after the transformation, the vector/matrix is still the same, only its representation has changed. Often, such a coordinate transformation is called a passive rotation.
+
+<p>
+This does not rotate the vector or matrix, but transforms them from one coordinate system representation to the other. After the transformation, the vector/matrix is still the same, only its representation has changed. Often, such a coordinate transformation is called a passive rotation.
 </p>
 
 <p>
@@ -69,13 +73,17 @@
 
 <p>
 If the argument <code>'cols'</code> is given, <code>erot</code> returns the three columns of the rotation matrix separately. The three vectors and the rotation matrix are related by <code>Rp = [xc yc zc]</code>. Similarly, if the argument <code>'rows'</code> is given, <code>erot</code> returns the three rows of the rotation matrix separately. However, they are returned not as rows but as column vectors. These three vectors and the rotation matrix are related by <code>Rp = [xr.'; yr.'; zr.']</code>. 
+</p>
+
+<p>
+The inverse of <code>erot</code>, i.e. calculating the Euler angles from a given rotation matrix, is provided by <a class="esf" ref="eulang.html">eulang</a>.
+</p>
 
 <!-- ============================================================= -->
 <div class="subtitle">Examples</div>
 
 <p>
-To rotate the basis of the matrix <code>A</code> so that the final Z axis is along -z,
-and (X,Y) = (-y,-x), type
+To rotate the basis of the matrix <code>A</code> so that the final Z axis is along -z, and (X,Y) = (-y,-x), type
 </p>
 
 <pre class="matlab">
@@ -92,21 +100,22 @@
 
 <p>
 To rotate a magnetic field vector from the z direction to a direction
-in the first quadrant specified by the polar angles <code>theta</code> (down
-from z axis, elevation complement) and <code>phi</code> (counterclockwise
-around z from x, azimuth), use an active rotation.
+in the first quadrant specified by the polar angles <code>theta</code> (down from z axis, elevation complement) and <code>phi</code> (counterclockwise around z from x, azimuth), use an active rotation.
 </p>
 
 <pre class="matlab">
-B = [0;0;9.5]; theta = 20; phi = 75;
+B = [0;0;350];
+theta = 20;
+phi = 75;
 Rp = erot([phi theta 0]*pi/180);
-Ra = Rp.'; B1 = Ra*B
+Ra = Rp.';
+B_rotated = Ra*B
 </pre>
 <pre class="mloutput">
-B1 =
-    0.8410
-    3.1385
-    8.9271
+B_rotated =
+   30.9825
+  115.6281
+  328.8924
 </pre>
 
 <p>
@@ -147,7 +156,7 @@
 <div class="subtitle">Algorithm</div>
 
 <p>
-See <a href="eulerangles.html">relative orientations</a> for details.
+See <a href="eulerangles.html">relative orientations</a> and <a href="frames.html">coordinate frames</a>for details.
 </p>
 
 <!-- ============================================================= -->
@@ -156,6 +165,8 @@
 <p>
 <a class="esf" href="ang2vec.html">ang2vec</a>,
 <a class="esf" href="eulang.html">eulang</a>,
+<a class="esf" href="rotaxi2mat.html">rotaxi2mat</a>,
+<a class="esf" href="rotmat2axi.html">rotmat2axi</a>,
 <a class="esf" href="vec2ang.html">vec2ang</a>
 </p>
 

docsrc/eulang.html

@@ -47,12 +47,16 @@
 Given a <a href="eulerangles.html">rotation matrix</a> <code>Rp</code>, the function <code>eulang</code> computes the <a href="eulerangles.html">Euler angles</a> defining the same rotation and returns them separately or as a 3-element vector <code>angles = [alpha, beta, gamma]</code>. The angles are in radians.
 </p>
 
+<p>
+The calculated Euler angles are such that if provided to <a class="esf" href="erot.html">erot</a>, the input rotation matrix is recovered.
+</p>
+
 <p>
 For details about Euler angles and rotation matrices, see the page on <a href="eulerangles.html">relative orientations</a>.
 </p>
 
 <p>
-The rotation matrix must be a 3x3 real matrix with determinant +1 to within 0.1, otherwise the function errors. For smaller deviations, a warning is issued.
+The rotation matrix must be a 3x3 real matrix with determinant +1 to within 0.01, otherwise the function errors. For smaller deviations, a warning is issued.
 </p>
 
 <p>
@@ -66,6 +70,15 @@
 <code>eulang</code> first checks if the input matrix is orthogonal and then determines the Euler angles analytically from the matrix elements. If the input matrix is close to orthogonal, <code>eulang</code> replaces it by its closest orthogonal neighbor using singular-value decomposition. If the the matrix is too far from orthogonal, <code>eulang</code> errors.
 </p>
 
+<p>
+You can manually use SVD to orthogonalize a matrix using
+</p>
+
+<pre class="matlab">
+[U,~,V] = svd(R);  % calculate SVD, ignoring singular values
+R = U*V.';         % construct orthogonal rotation matrix 
+</pre>
+
 <!-- ============================================================= -->
 <div class="subtitle">Examples</div>