docs: audit ndarray chapter -- style cleanup, split numerical into two pages

Sweep for accumulated style rules across both image and ndarray chapters:
italic-before-colon, the "shape" word in non-geometric contexts,
"firmware" word, "worked example" phrasing, thousands separators in
prose, structural forward references ("the next page"), comma-separated
imports, second-person "you" in section headers and prose, and the
"framebuffer" / "frame buffer" inconsistency. Cleaned up :py:meth: /
:py:class: domain-prefix inconsistencies and a malformed cross-reference
with the signature inside the role target.

Verified accuracy against the library reference for flatten, linspace,
logspace, byteswap, arange, meshgrid, ndinfo, empty, set_printoptions,
bincount, nonzero, argsort, array, and the bool / complex dtype widths.

Split numerical.rst into two pages so the chapter ends with the wrap-up
on an even section number (9.20): "Curves and integration" keeps
interp / polyfit / polyval / convolve / trapz; new "Solvers and random
numbers" page covers scipy.integrate (quad / romberg / simpson /
tanhsinh), scipy.optimize (bisect / newton / fmin), scipy.special
(erf / erfc / gamma / gammaln), and numpy.random.Generator. Renamed the
toctree caption to "Numerical tools".

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: kwagyeman

docs/openmvcam/tutorial/numpy/basics/dtypes.rst

@@ -19,18 +19,17 @@ dtype          bytes    range
 =============  =======  ===============================
 ``uint8``      1        0 to 255
 ``int8``       1        -128 to 127
-``uint16``     2        0 to 65 535
-``int16``      2        -32 768 to 32 767
+``uint16``     2        0 to 65,535
+``int16``      2        -32,768 to 32,767
 ``float``      4 or 8   IEEE 754 (single or double)
 ``bool``       1        ``True`` / ``False``
-``complex``    8 or 16  optional, firmware-dependent
+``complex``    8 or 16  optional, build-dependent
 =============  =======  ===============================
 
-The ``float`` width depends on how the firmware was
+The ``float`` width depends on how the cam was
 built; ``complex`` is only available on cams whose
-firmware reports a ``-c`` suffix in
-:data:`ulab.__version__`. There is no ``int32`` or
-``int64``.
+:data:`ulab.__version__` carries a ``-c`` suffix.
+There is no ``int32`` or ``int64``.
 
 Pick the type that matches the hardware that produced the
 data. An 8-bit ADC sample wants ``uint8``; a 12-bit ADC
@@ -59,7 +58,7 @@ The dtype of an existing array
 :attr:`~ulab.numpy.ndarray.dtype` reads back the array's
 dtype as a :class:`ulab.dtype` instance. The single-
 character type code is what gets compared on
-firmware-conditional code paths::
+build-conditional code paths::
 
     a = np.array([1, 2, 3], dtype=np.uint8)
     print(a.dtype)            # dtype('uint8')

docs/openmvcam/tutorial/numpy/basics/making-arrays.rst

@@ -127,7 +127,7 @@ along an existing axis::
 
 All inputs must share the same dtype and ``ndim``, and
 match on every axis other than the joining one. This is
-the right shape for accumulating short buffers into a
+the right tool for accumulating short buffers into a
 longer one when the final length is known up front; for
 the streaming-append pattern see :doc:`../performance`.
 

docs/openmvcam/tutorial/numpy/basics/the-ndarray.rst

@@ -42,8 +42,8 @@ reductions, broadcasting, slicing -- works directly from
 those five values plus the data pointer, with no
 per-element Python overhead.
 
-What you get from the design
-----------------------------
+What the design buys
+--------------------
 
 Three properties fall out of "packed block + small
 descriptor" and define how the rest of the section
@@ -62,7 +62,7 @@ operators all work this way; the universal functions
 **Reshape, transpose, and slicing are free.** None of
 the three actually moves the data. Each one returns a
 new descriptor pointing at the *same* data block. The
-result is called a *view*: a second window onto the same
+result is called a *view* -- a second window onto the same
 underlying buffer. Writing through a view writes to the
 source. See :doc:`../shape/views-and-copies`.
 
@@ -73,8 +73,8 @@ small set of rules that decide which short axis stretches
 to match the long one. The stretch is virtual; no data
 is duplicated. See :doc:`../math/broadcasting`.
 
-What you give up in exchange
-----------------------------
+What the design costs
+---------------------
 
 Two restrictions follow from the same design.
 
@@ -86,24 +86,21 @@ page covers the small set of types :mod:`numpy` supports
 and the rules that come out of fixing one.
 
 **Growing an array is not free.** A list keeps spare
-slots at the end and lets you ``.append`` cheaply. An
+slots at the end and supports ``.append`` cheaply. An
 :class:`~ulab.numpy.ndarray` is exactly the size it
 needs to be; appending would mean allocating a new,
 larger buffer and copying the old contents into it.
 There is no :meth:`append` method, on purpose. The right
-shape on the camera is to pre-allocate the destination
+pattern on the camera is to pre-allocate the destination
 at its final size and *fill* it; :doc:`../performance`
-covers the pattern.
-
-Where to look next
-------------------
-
-:doc:`making-arrays` is the constructor catalogue --
-every way to actually get an
-:class:`~ulab.numpy.ndarray` from a literal, a sensor
-buffer, or a generated sequence. :doc:`dtypes` covers
-the element-type choice that decides how much RAM each
-element costs. After those two,
-:doc:`../shape/shape-and-strides` opens the descriptor
-back up to explain how multi-dimensional indexing falls
-out of it.
+covers the technique.
+
+With a packed typed buffer for the data, a small
+descriptor for the metadata, and three behavioural
+guarantees (fast element-wise math, free reshape /
+transpose / slicing, and shapes that broadcast), the
+:class:`~ulab.numpy.ndarray` is the foundation the rest
+of the chapter rests on. How an array actually comes
+into existence -- from a literal, from a pre-filled
+allocation, from a peripheral buffer -- is the next
+practical question.

docs/openmvcam/tutorial/numpy/basics/why-arrays.rst

@@ -23,7 +23,7 @@ the numerical work an OpenMV application runs into:
   buffer, an IIR filter applied to a sensor's output, a
   spectrogram a classifier wants as input.
 
-All of these want the same shape: a buffer of numbers
+All of these want the same form: a buffer of numbers
 with one operation applied to every element. A Python
 ``for`` loop is the obvious way to write it::
 
@@ -40,7 +40,7 @@ costs add up to tens of milliseconds for what is
 fundamentally a quick operation.
 
 That overhead bites every time a script reaches a buffer.
-A QVGA grayscale frame is 76 800 pixels; an
+A QVGA grayscale frame is 76,800 pixels; an
 accelerometer at 100 Hz delivers a hundred three-axis
 samples a second; a microphone fills a 1024-sample
 buffer every 64 ms. A pure-Python ``for`` loop over any
@@ -82,12 +82,12 @@ elsewhere, with the list keeping a reference to it. A
 library function looking at a list would still have to
 unpack each element through that reference and check its
 type -- exactly the cost the loop pays. Lists are the
-wrong shape for fast array math.
+wrong fit for fast array math.
 
 Why bytearray is not enough either
 ----------------------------------
 
-A :class:`bytearray` is the right *shape* -- one
+A :class:`bytearray` is the right *form* -- one
 typed buffer, one byte per element, all in one
 contiguous block. It is what most byte-oriented
 peripheral APIs hand back. What it lacks is the *math*.
@@ -97,4 +97,6 @@ for ``bytearray + bytearray`` element by element.
 
 The data structure that combines a typed buffer with
 element-wise math is the :class:`~ulab.numpy.ndarray`.
-The next page opens the box.
+What is inside the box and how each field shapes the
+fast-path behaviour are the foundations the rest of
+this chapter rests on.

docs/openmvcam/tutorial/numpy/images.rst

@@ -4,13 +4,13 @@ Images and ndarrays
 This page closes the loop the section opened with. The
 :class:`~image.Image` class is the fast surface for
 camera-native pixel work: every method on it operates
-directly on the framebuffer in the camera's native
+directly on the frame buffer in the camera's native
 pixel format. :mod:`numpy` is the generic numerical
 surface for everything else. Two methods bridge them:
 
-* :py:meth:`image.Image.to_ndarray` -- view or copy the
+* :meth:`image.Image.to_ndarray` -- view or copy the
   pixels of an image as an :class:`~ulab.numpy.ndarray`.
-* The :py:class:`image.Image` constructor -- build a
+* The :class:`image.Image` constructor -- build a
   fresh image from an :class:`~ulab.numpy.ndarray`.
 
 Together they let an application snap a frame, hand it
@@ -21,10 +21,11 @@ back into the rest of the image library.
 Image to ndarray
 ----------------
 
-:py:meth:`image.Image.to_ndarray(dtype, *, buffer=None)`
-returns an :class:`~ulab.numpy.ndarray` whose data come
-from the image's pixel buffer. The output shape depends
-on the image format:
+:meth:`~image.Image.to_ndarray` returns an
+:class:`~ulab.numpy.ndarray` whose data come from the
+image's pixel buffer. The signature is
+``to_ndarray(dtype, *, buffer=None)``, and the output
+shape depends on the image format:
 
 * **GRAYSCALE** -- 2-D array, shape ``(height, width)``.
 * **RGB565** -- 3-D array, shape ``(height, width, 3)``,
@@ -72,7 +73,7 @@ ndarray to image
 
 Going the other way, pass the
 :class:`~ulab.numpy.ndarray` as the first argument to
-:py:class:`image.Image`::
+:class:`image.Image`::
 
     image.Image(arr, *, buffer=None, copy_to_fb=False)
 
@@ -90,7 +91,7 @@ clamped to the ``0..255`` range.
 ``buffer=`` lets the application supply a
 :class:`bytearray` it already allocated for the
 resulting image. ``copy_to_fb=True`` writes the result
-into the camera's framebuffer, which is the right
+into the camera's frame buffer, which is the right
 choice when the result should appear in the IDE
 preview.
 
@@ -128,7 +129,7 @@ depth, audio) in a single computation.
 It is **not** the right answer for high-throughput
 pixel processing the :class:`~image.Image` class
 already covers. The built-in methods operate directly
-on the framebuffer in the camera's native pixel format
+on the frame buffer in the camera's native pixel format
 and are much faster than the equivalent :mod:`numpy`
 expression. Reach for the bridge for the operations
 the image library does not already provide.

docs/openmvcam/tutorial/numpy/index.rst

@@ -60,10 +60,11 @@ Python ``for`` loop.
    signals/filtering.rst
 
 .. toctree::
-   :caption: Numerical extras
+   :caption: Numerical tools
    :maxdepth: 1
 
    numerical.rst
+   solvers-and-random.rst
 
 .. toctree::
    :caption: Images

docs/openmvcam/tutorial/numpy/linalg.rst

@@ -196,11 +196,11 @@ accurate than ``np.dot(np.linalg.inv(A), b)``:
       x = sp.linalg.cho_solve(L, b)
 
 Reach for these instead of inverting whenever the
-structure of ``A`` lets you -- they save elimination
+structure of ``A`` allows -- they save elimination
 work *and* the explicit inverse.
 
-A worked example: small linear system
--------------------------------------
+Solving a small linear system
+-----------------------------
 
 ::
 

docs/openmvcam/tutorial/numpy/math/operators.rst

@@ -4,7 +4,7 @@ Operators
 The first kind of math :mod:`numpy` runs on an
 :class:`~ulab.numpy.ndarray` is the standard Python
 operators. Arithmetic, comparison, and bit-wise
-operators all work *element-wise*: each operator walks
+operators all work *element-wise* -- each operator walks
 the array (or both arrays) once from start to finish
 inside a single library call, much faster than the
 equivalent Python ``for`` loop.

docs/openmvcam/tutorial/numpy/math/selection.rst

@@ -19,7 +19,7 @@ together::
     np.where(a < 3, a, 0.0)
     # array([1.0, 2.0, 0.0, 0.0, 0.0])
 
-This is the right shape for an "if/else per element"
+This is the right tool for an "if/else per element"
 without writing a Python loop.
 
 :func:`~ulab.numpy.clip(a, lo, hi)` is shorthand for
@@ -61,7 +61,7 @@ Two reductions also produce indices:
       a[idx]                          # array([10, 20, 30, 40])
 
   ``argsort`` always returns ``uint16``; the array
-  being sorted must therefore have no more than 65 535
+  being sorted must therefore have no more than 65,535
   elements on the sorted axis.
 
 :func:`~ulab.numpy.bincount(x)` counts occurrences of each

docs/openmvcam/tutorial/numpy/math/universal-functions.rst

@@ -143,7 +143,7 @@ overrides it::
 The Python function must take a single argument and
 return a single number.
 
-:func:`~ulab.numpy.vectorize` is mostly *syntactic*:
+:func:`~ulab.numpy.vectorize` is mostly *syntactic* --
 the wrapped Python function still has to run once per
 element, so most of the per-element interpreter cost
 that a true ufunc avoids is back. Expect a modest