doc updaes + basic functional api start

docs/basic/install.html

@@ -349,9 +349,9 @@ <h1 class="title">Installation</h1>
 </header>
 
 
-<p><code>primate</code> is a standard <a href="https://peps.python.org/pep-0517/">PEP-517</a> package, and thus can be installed via <code>pip</code>:</p>
+<p><code>primate</code> is a standard <a href="https://peps.python.org/pep-0517/">PEP-517</a> package that can be installed via <code>pip</code>:</p>
 <div class="sourceCode" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>python <span class="op">-</span>m pip install scikit<span class="op">-</span>primate  </span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<p>Assuming your platform is natively supported, no compilation is needed; see <a href="#platform-support">platform support</a> for details.</p>
+<p>Assuming your platform is supported, no compilation is needed—see <a href="#platform-support">platform support</a> for details.</p>
 <div class="callout callout-style-default callout-note callout-titled">
 <div class="callout-header d-flex align-content-center">
 <div class="callout-icon-container">
@@ -362,7 +362,7 @@ <h1 class="title">Installation</h1>
 </div>
 </div>
 <div class="callout-body-container callout-body">
-<p>Like many packages registered on PyPI, the distribution name “<code>scikit-primate</code>” differs from the importable package name “<code>primate</code>” (also see <a href="https://github.com/pypi/support/issues/3471">#3471</a>). Once installed, all exported package modules are available through the <code>primate</code> module.</p>
+<p>Like many packages registered on PyPI, the <em>distribution</em> “<code>scikit-primate</code>” differs from the importable <em>package</em> “<code>primate</code>” (also see <a href="https://github.com/pypi/support/issues/3471">#3471</a>). Additionally, <code>primate</code> does not rely on organizational prefixes that some <a href="https://projects.scipy.org/scikits.html">scikits</a> use (e.g.&nbsp;<code>scikit-learn</code> -&gt; <code>sklearn</code>).</p>
 </div>
 </div>
 <!-- Currently the package must be built from source via cloning the repository. PYPI support is planned.  -->
@@ -422,7 +422,7 @@ <h3 class="anchored" data-anchor-id="platform-support">Platform support</h3>
 </section>
 <section id="compiling-from-source" class="level3">
 <h3 class="anchored" data-anchor-id="compiling-from-source">Compiling from source</h3>
-<p>To install the package from its source distribution, a C++20 compiler is required; the current builds are all built with some variant of <a href="https://clang.llvm.org/">clang</a>, preferably version 15.0 or higher. For platform- and compiler-specific settings, consult the build scripts and CI configuration files.</p>
+<p>A C++20 compiler is required to install the package from its source distribution. Current builds all compile with some variant of <a href="https://clang.llvm.org/">clang</a> (version 15.0+). For platform- and compiler-specific settings, consult the <a href="https://github.com/peekxc/primate/blob/main/meson.build">build scripts</a> and <a href="https://github.com/peekxc/primate/tree/main/.github/workflows">CI configuration files</a>.</p>
 </section>
 <section id="c-installation" class="level3">
 <h3 class="anchored" data-anchor-id="c-installation">C++ Installation</h3>

docs/basic/integration.html

@@ -363,15 +363,15 @@ <h1 class="title">Integration</h1>
 </header>
 
 
-<p><code>primate</code> supports a variety of matrix-types of the box, including numpy <code>ndarray</code>’s, compressed <a href="https://docs.scipy.org/doc/scipy/reference/sparse.html">sparse matrices</a> (a lá SciPy), and <a href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html">LinearOperators</a>—the latter enables the use of <em>matrix free</em> operators.</p>
-<p>Outside of the natively types above, the basic requirements for any operator <code>A</code> to be used with e.g.&nbsp;the <code>Lanczos</code> method in <code>primate</code> are:</p>
+<p><code>primate</code> supports a variety of matrix-types of the box, including numpy <code>ndarray</code>’s, compressed <a href="https://docs.scipy.org/doc/scipy/reference/sparse.html">sparse matrices</a> (a lá SciPy), and <a href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html">LinearOperators</a>.</p>
+<p>More generally, the basic requirements for any operator <code>A</code> to be used with e.g.&nbsp;the <code>Lanczos</code> method are:</p>
 <ol type="1">
 <li>A method <code>A.matvec(input: ndarray) -&gt; ndarray</code> implementing <span class="math inline">v \mapsto Av</span></li>
 <li>An attribute <code>A.shape -&gt; tuple[int, int]</code> giving the output/input dimensions of <span class="math inline">A</span></li>
 </ol>
 <!-- Note that in the matrix setting, `A.shape()` yields `(A.nrow(), A.ncol())`, so existing matrix implementations like [ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html)'s and [sparray](https://docs.scipy.org/doc/scipy/reference/sparse.html#sparse-array-classes)'s natively support the interface. -->
 <!-- Using [PyLops](adthedocs.io/en/stable/index.html) terminology, any self-adjoint operator supporting _forward model_ of matrix-vector multiplication is compatible with most of `primate`'s API.  -->
-<p>Here’s an example of a simple operator representing a Diagonal matrix, which inherits a <code>.matvec()</code> method by following the subclassing rules of <a href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html">SciPy’s LinearOperator</a>:</p>
+<p>Here’s an example of a simple operator representing a Diagonal matrix:</p>
 <div class="sourceCode" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="im">import</span> numpy <span class="im">as</span> np </span>
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> numpy.typing <span class="im">import</span> ArrayLike</span>
 <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> scipy.sparse.linalg <span class="im">import</span> LinearOperator </span>
@@ -387,21 +387,10 @@ <h1 class="title">Integration</h1>
 <span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a>  <span class="kw">def</span> _matvec(<span class="va">self</span>, x: ArrayLike) <span class="op">-&gt;</span> np.ndarray:</span>
 <span id="cb1-14"><a href="#cb1-14" aria-hidden="true" tabindex="-1"></a>    out <span class="op">=</span> <span class="va">self</span>.diag <span class="op">*</span> np.ravel(x)</span>
 <span id="cb1-15"><a href="#cb1-15" aria-hidden="true" tabindex="-1"></a>    <span class="cf">return</span> out.reshape(x.shape)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<!-- Sure enough, you 
-
-```python
-from scipy.sparse.linalg import eigsh
-
-D = DiagonalOp(np.arange(10))
-np.allclose(
-  eigsh(DiagonalOp(v), k = 9, return_eigenvectors=False),
-  np.arange(1, 10)
-) 
-## True
-``` -->
+<p>Note that by following the subclassing rules of <a href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html">SciPy’s LinearOperator</a>, this class inherits a <code>.matvec()</code> method and thus satisfies the constraints above.</p>
 <section id="c-usage" class="level2">
 <h2 class="anchored" data-anchor-id="c-usage">C++ usage</h2>
-<p>Similarly, to get started calling any matrix-free function provided by <code>primate</code> on the C++ side, such <code>hutch</code> or <code>lanczos</code>, simply pass any type with <code>.shape()</code> and <code>.matvec()</code> member functions:</p>
+<p>Similarly, to call any C++ function, such <code>hutch</code> or <code>lanczos</code>, simply pass any type with <code>.shape()</code> and <code>.matvec()</code> member functions:</p>
 <div class="sourceCode" id="cb2"><pre class="sourceCode cpp code-with-copy"><code class="sourceCode cpp"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> LinOp <span class="op">{</span></span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>  <span class="dt">int</span> nrow<span class="op">,</span> ncol<span class="op">;</span></span>
 <span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>  </span>
@@ -414,7 +403,7 @@ <h2 class="anchored" data-anchor-id="c-usage">C++ usage</h2>
 <span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a>  <span class="dt">void</span> shape<span class="op">()</span> <span class="at">const</span> <span class="op">{</span> <span class="cf">return</span> <span class="bu">std::</span>make_pair<span class="op">(</span>nrow<span class="op">,</span> ncol<span class="op">);</span> <span class="op">}</span></span>
 <span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>It’s up to you to ensure <code>shape()</code> yields the correct size; <code>primate</code> will supply vectors to <code>input</code> of size <code>.shape().second</code> (number of columns) and guarantees the pointer to the <code>output</code> will be at least <code>shape().first</code> (number of rows), no more.</p>
-<p>To read more about how semantics extend to the C++ side as well via <em>C++20 concepts</em>—see the <a href="../advanced/cpp_integration.html">C++ integration guide</a>. If you’re using pybind11 and you want to extend <code>primate</code>’s Python API to work natively with linear operator implemented in C++, see the <a href="../advanced/pybind11_integration.html">pybind11 integration guide</a>.</p>
+<p>To read more about how semantics extend to the C++ side via <em>C++20 concepts</em>, see the <a href="../advanced/cpp_integration.html">C++ integration guide</a>. If you’re using pybind11 and you want to extend <code>primate</code>’s Python API to work natively with linear operator implemented in C++, see the <a href="../advanced/pybind11_integration.html">pybind11 integration guide</a>.</p>
 
 
 </section>

docs/basic/performance.html

@@ -342,7 +342,7 @@ <h1 class="title">Performance</h1>
 <p><code>primate</code> provides a variety of efficient algorithms for estimating quantities derived from matrix functions. These algorithms are largely implemented in C++ to minimize overhead, and for some computational problems <code>primate</code> can out-perform the standard algorithms for estimating spectral quantities by several orders of magnitude. Nonetheless, there are some performance-related caveats to be aware of.</p>
 <!-- The main  -->
 <!-- To illustrate this, we give an example below using Toeplitz matrices.   -->
-<div id="edff6716" class="cell" data-execution_count="1">
+<div id="15e6050a" class="cell" data-execution_count="1">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> scipy.linalg <span class="im">import</span> toeplitz</span>
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> primate.trace <span class="im">import</span> hutch </span>
 <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a></span>
@@ -386,7 +386,7 @@ <h1 class="title">Performance</h1>
 <span id="cb1-41"><a href="#cb1-41" aria-hidden="true" tabindex="-1"></a>a, b <span class="op">=</span> lanczos(T, deg<span class="op">=</span><span class="dv">499</span>, orth<span class="op">=</span><span class="dv">150</span>)</span>
 <span id="cb1-42"><a href="#cb1-42" aria-hidden="true" tabindex="-1"></a>np.<span class="bu">sum</span>(np.<span class="bu">abs</span>(eigvalsh_tridiagonal(a,b)))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<div id="43019448" class="cell" data-execution_count="2">
+<div id="8c293315" class="cell" data-execution_count="2">
 <div class="sourceCode cell-code" id="cb2"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="im">import</span> timeit </span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>timeit.timeit(<span class="kw">lambda</span>: hutch(A, maxiter<span class="op">=</span><span class="dv">20</span>, deg<span class="op">=</span><span class="dv">5</span>, fun<span class="op">=</span><span class="st">"log"</span>, quad<span class="op">=</span><span class="st">"fttr"</span>), number <span class="op">=</span> <span class="dv">1000</span>)</span>
 <span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>timeit.timeit(<span class="kw">lambda</span>: np.<span class="bu">sum</span>(np.log(np.linalg.eigvalsh(A))), number <span class="op">=</span> <span class="dv">1000</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>

docs/basic/todo.html

@@ -323,7 +323,7 @@
 
 
 
-<div id="76c9f600" class="cell" data-execution_count="1">
+<div id="0bd7e8f8" class="cell" data-execution_count="1">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co"># a, b = 0.8, 2</span></span>
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="co"># x = np.random.uniform(low=0, high=10, size=40)</span></span>
 <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="co"># eps = np.random.normal(loc=0, scale=1.0, size=40)</span></span>