add det() and inverse() functions to Eidos

Author: bhaller

EidosScribe/EidosHelpFunctions.rtf

@@ -4466,7 +4466,20 @@ To combine vectors or matrices by row instead, see
 \f3\fs20 .\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f1\fs18 \cf2 \kerning1\expnd0\expndtw0 (*)diag([*\'a0x\'a0=\'a01], [Ni$\'a0nrow\'a0=\'a0NULL], [Ni$\'a0ncol\'a0=\'a0NULL])\
+\f1\fs18 \cf2 \kerning1\expnd0\expndtw0 (numeric$)det(numeric\'a0x)\
+\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
+
+\f0\b\fs20 \cf2 Returns the determinant
+\f3\b0  of 
+\f1\fs18 x
+\f3\fs20 , which must be a square matrix (otherwise an error is raised).  The determinant is a scalar-valued function of the entries of the matrix, and characterizes some properties of the matrix.  In particular, the determinant is nonzero if and only if the matrix is invertible.  If the determinant is zero, the matrix does not have an inverse and is referred to as \'93singular\'94.  In Eidos the determinant is calculated from the 
+\f7\i LU
+\f3\i0  decomposition of the matrix.  The return type will match the type of 
+\f1\fs18 x
+\f3\fs20 .\
+\pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
+
+\f1\fs18 \cf2 (*)diag([*\'a0x\'a0=\'a01], [Ni$\'a0nrow\'a0=\'a0NULL], [Ni$\'a0ncol\'a0=\'a0NULL])\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 
 \f0\b\fs20 \cf2 Returns the diagonal
@@ -4566,7 +4579,48 @@ Returns the result of dropping redundant dimensions
 \f3\fs20  is not a matrix or array, it is returned unmodified.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f1\fs18 \cf2 \kerning1\expnd0\expndtw0 (logical)lowerTri(*\'a0x, [logical$\'a0diag\'a0=\'a0F])\
+\f1\fs18 \cf2 \kerning1\expnd0\expndtw0 (float)inverse(numeric\'a0x)\
+\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
+
+\f0\b\fs20 \cf2 Returns the (multiplicative) inverse
+\f3\b0  of 
+\f1\fs18 x
+\f3\fs20 , which must be a square non-singular matrix (otherwise an error is raised).  If matrix 
+\f0\b B
+\f3\b0  is the inverse of 
+\f7\i n
+\f3\i0 -by-
+\f7\i n
+\f3\i0  matrix 
+\f0\b A
+\f3\b0 , then 
+\f0\b AB
+\f3\b0  = 
+\f0\b BA
+\f3\b0  = 
+\f0\b I
+\f7\i\b0\fs13\fsmilli6667 \sub n
+\f3\i0\fs20 \nosupersub , where 
+\f0\b I
+\f7\i\b0\fs13\fsmilli6667 \sub n
+\f3\i0\fs20 \nosupersub  denotes the 
+\f7\i n
+\f3\i0 -by-
+\f7\i n
+\f3\i0  identity matrix and the multiplication used is ordinary matrix multiplication as performed by 
+\f1\fs18 matrixMult()
+\f3\fs20 .  If 
+\f1\fs18 x
+\f3\fs20  might be singular (and thus non-invertible), and you wish to avoid the possibility of an error, you can call 
+\f1\fs18 det()
+\f3\fs20  first to find the determinant of the matrix; if the determinant is zero, the matrix is singular and does not have an inverse, and so 
+\f1\fs18 inverse()
+\f3\fs20  should not be called.  In Eidos the inverse is calculated from the 
+\f7\i LU
+\f3\i0  decomposition of the matrix.\
+\pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
+
+\f1\fs18 \cf2 (logical)lowerTri(*\'a0x, [logical$\'a0diag\'a0=\'a0F])\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 
 \f0\b\fs20 \cf2 Returns the lower triangle

QtSLiM/help/EidosHelpFunctions.html

@@ -360,13 +360,17 @@
 <p class="p2">(*)cbind(...)</p>
 <p class="p5"><span class="s5"><b>Combines vectors or matrices by column</b> to produce a single matrix.<span class="Apple-converted-space">  </span>The parameters must be vectors (which are interpreted by </span><span class="s6">cbind()</span><span class="s5"> as if they were one-column matrices) or matrices.<span class="Apple-converted-space">  </span>They must be of the same type, of the same class if they are of type </span><span class="s6">object</span><span class="s5">, and have the same number of rows.<span class="Apple-converted-space">  </span>If these conditions are met, the result is a single matrix with the parameters joined together, left to right.<span class="Apple-converted-space">  </span>Parameters may instead be </span><span class="s6">NULL</span><span class="s5">, in which case they are ignored; or if all parameters are </span><span class="s6">NULL</span><span class="s5">, the result is </span><span class="s6">NULL</span><span class="s5">.<span class="Apple-converted-space">  </span>A sequence of vectors, matrices, and </span><span class="s6">NULL</span><span class="s5">s may thus be concatenated with the </span><span class="s6">NULL</span><span class="s5"> values removed, analogous to </span><span class="s6">c()</span><span class="s5">.<span class="Apple-converted-space">  </span>Calling </span><span class="s6">cbind(x)</span><span class="s5"> is an easy way to create a one-column matrix from a vector.</span></p>
 <p class="p5"><span class="s5">To combine vectors or matrices by row instead, see </span><span class="s6">rbind()</span><span class="s5">.</span></p>
+<p class="p4">(numeric$)det(numeric x)</p>
+<p class="p5"><b>Returns the determinant</b> of <span class="s2">x</span>, which must be a square matrix (otherwise an error is raised).<span class="Apple-converted-space">  </span>The determinant is a scalar-valued function of the entries of the matrix, and characterizes some properties of the matrix.<span class="Apple-converted-space">  </span>In particular, the determinant is nonzero if and only if the matrix is invertible.<span class="Apple-converted-space">  </span>If the determinant is zero, the matrix does not have an inverse and is referred to as “singular”.<span class="Apple-converted-space">  </span>In Eidos the determinant is calculated from the <i>LU</i> decomposition of the matrix.<span class="Apple-converted-space">  </span>The return type will match the type of <span class="s2">x</span>.</p>
 <p class="p4">(*)diag([* x = 1], [Ni$ nrow = NULL], [Ni$ ncol = NULL])</p>
 <p class="p5"><b>Returns the diagonal</b> of <span class="s2">x</span>.<span class="Apple-converted-space">  </span>This function has four distinct usage patterns (matching R).<span class="Apple-converted-space">  </span>First, if <span class="s2">x</span> is a matrix of any type, it returns the diagonal elements of <span class="s2">x</span> as a vector; in this case, <span class="s2">nrow</span> and <span class="s2">ncol</span> must be <span class="s2">NULL</span>.<span class="Apple-converted-space">  </span>Second, if <span class="s2">x</span> is <span class="s2">1</span> (the default) and <span class="s2">nrow</span> is non-<span class="s2">NULL</span>, it returns an identity matrix with the requested number of rows (and, if <span class="s2">ncol</span> is also non-<span class="s2">NULL</span>, the requested number of columns, otherwise the matrix will be square).<span class="Apple-converted-space">  </span>Third, if <span class="s2">x</span> is a singleton <span class="s2">integer</span> value and <span class="s2">nrow</span> and <span class="s2">ncol</span> are <span class="s2">NULL</span>, it returns a square identity matrix of size <span class="s2">x</span>.<span class="Apple-converted-space">  </span>Fourth, if x is a <span class="s2">logical</span>, <span class="s2">integer</span>, or <span class="s2">float</span> vector of length at least <span class="s2">2</span>, it returns a matrix that uses the values of <span class="s2">x</span> as its diagonal (without recycling or truncation, unlike R) and has <span class="s2">F</span>, <span class="s2">0</span>, or <span class="s2">0.0</span> off-diagonal entries as appropriate.</p>
 <p class="p5">Note that using <span class="s2">diag(x)</span>, without <span class="s2">nrow</span> or <span class="s2">ncol</span>, can have unexpected effects if <span class="s2">x</span> is a vector that could be of length one.<span class="Apple-converted-space">  </span>Use <span class="s2">diag(x, nrow=length(x))</span> for consistent behavior.</p>
 <p class="p2">(integer)dim(* x)</p>
 <p class="p5"><span class="s5"><b>Returns the dimensions</b> of matrix or array </span><span class="s6">x</span><span class="s5">.<span class="Apple-converted-space">  </span>The first dimension value is the number of rows, the second is the number of columns, and further values indicate the sizes of higher-order dimensions, identically to how dimensions are supplied to </span><span class="s6">array()</span><span class="s5">.<span class="Apple-converted-space">  </span></span><span class="s6">NULL</span><span class="s5"> is returned if </span><span class="s6">x</span><span class="s5"> is not a matrix or array.</span></p>
 <p class="p2">(*)drop(* x)</p>
 <p class="p5"><span class="s5"><b>Returns the result of dropping redundant dimensions</b> from matrix or array </span><span class="s6">x</span><span class="s5">.<span class="Apple-converted-space">  </span>Redundant dimensions are those with a size of exactly 1.<span class="Apple-converted-space">  </span>Non-redundant dimensions are retained.<span class="Apple-converted-space">  </span>If only one non-redundant dimension is present, the result is a vector; if more than one non-redundant dimension is present, the result will be a matrix or array.<span class="Apple-converted-space">  </span>If </span><span class="s6">x</span><span class="s5"> is not a matrix or array, it is returned unmodified.</span></p>
+<p class="p4">(float)inverse(numeric x)</p>
+<p class="p5"><b>Returns the (multiplicative) inverse</b> of <span class="s2">x</span>, which must be a square non-singular matrix (otherwise an error is raised).<span class="Apple-converted-space">  </span>If matrix <b>B</b> is the inverse of <i>n</i>-by-<i>n</i> matrix <b>A</b>, then <b>AB</b> = <b>BA</b> = <b>I</b><span class="s13"><i><sub>n</sub></i></span>, where <b>I</b><span class="s13"><i><sub>n</sub></i></span> denotes the <i>n</i>-by-<i>n</i> identity matrix and the multiplication used is ordinary matrix multiplication as performed by <span class="s2">matrixMult()</span>.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> might be singular (and thus non-invertible), and you wish to avoid the possibility of an error, you can call <span class="s2">det()</span> first to find the determinant of the matrix; if the determinant is zero, the matrix is singular and does not have an inverse, and so <span class="s2">inverse()</span> should not be called.<span class="Apple-converted-space">  </span>In Eidos the inverse is calculated from the <i>LU</i> decomposition of the matrix.</p>
 <p class="p4">(logical)lowerTri(* x, [logical$ diag = F])</p>
 <p class="p5"><b>Returns the lower triangle</b> of <span class="s2">x</span>, which must be a matrix.<span class="Apple-converted-space">  </span>The return value will be a <span class="s2">logical</span> matrix of the same dimensions as <span class="s2">x</span>, with elements <span class="s2">T</span> in the lower triangle, <span class="s2">F</span> elsewhere.<span class="Apple-converted-space">  </span>If <span class="s2">diag</span> is <span class="s2">F</span> (the default), the diagonal is not included in the lower triangle; if <span class="s2">diag</span> is <span class="s2">T</span>, the diagonal is included in the lower triangle (i.e., its elements will be <span class="s2">T</span>).</p>
 <p class="p2">(*)matrix(* data, [Ni$ nrow = NULL], [Ni$ ncol = NULL], [logical$ byrow = F])</p>