docs: sync authoritative documentation set (richer pages, mixed-BC fix, URL cleanup)

docs/_static/architecture.png

@@ -0,0 +1 @@
+../assets/architecture.png

docs/_static/operator_comparison.png

@@ -0,0 +1 @@
+../assets/operator_comparison.png

docs/_static/throughput_scaling.png

@@ -0,0 +1 @@
+../assets/throughput_scaling.png

docs/api_reference/index.rst

@@ -9,13 +9,15 @@ Organised bottom-up: low-level convolution primitives first, then the
 mixer modules that compose them, then full networks, then the
 parallel, core utility, and experiments layers.
 
-See `ops/README.md <../ops/README.html>`_ for the math motivation behind
-the FFT-based ops, and ``docs-tracker.md`` at the repo root for the
-documentation coverage plan.
+Start with the :doc:`Ops Primer <../ops/README>` for the math motivation
+behind the FFT-based ops (the convolution theorem, the linear/circular
+flavours, and a decision tree for picking a function).  ``docs-tracker.md``
+at the repo root tracks the documentation coverage plan.
 
 .. toctree::
    :maxdepth: 2
 
+   Ops Primer <../ops/README>
    ops
    modules
    networks

docs/api_reference/modules.rst

@@ -12,7 +12,7 @@ residual blocks they rely on.
 Mixers
 ------
 
-Sequence/spatial mixers — Hyena, Mamba, attention variants.
+Sequence/spatial mixers: Hyena, Mamba, attention variants.
 
 .. autosummary::
    :toctree: generated/

docs/api_reference/networks.rst

@@ -6,7 +6,8 @@ Networks
 ========
 
 End-to-end classification and general-purpose networks composing the
-modules above, plus the UNet-ConvNeXt baselines used in benchmark comparisons.
+modules above, plus the UNet-ConvNeXt baselines used in benchmark
+comparisons.
 
 Classification & general-purpose
 --------------------------------

docs/api_reference/ops.rst

@@ -9,6 +9,8 @@ Low-level convolution primitives.  Pure-PyTorch reference implementations
 double as the spec the CUDA kernels must match; the
 ``subquadratic_ops_torch`` wrappers are the production path on GPU.
 
+.. _ops-fftconv-fp32:
+
 FFT convolutions (reference fp32)
 ---------------------------------
 
@@ -27,8 +29,10 @@ Use these for correctness and as the spec for the CUDA kernels below.
    ~ops.fftconv.fftconv3d_fp32_bhl
    ~ops.fftconv.causal_fftconv1d_fp32_bhl
 
+.. _ops-fftconv-custom:
+
 FFT convolutions (CUDA-accelerated)
------------------------------------
+------------------------------------
 
 Drop-in wrappers around the ``subquadratic_ops_torch`` fused CUDA kernels.
 2D non-causal and 1D causal long-conv variants share the same API as the
@@ -45,8 +49,10 @@ fp32 reference ops above.
    ~ops.fftconv_custom.causal_fftconv1d_bhl
    ~ops.fftconv_custom.causal_fftconv1d_bhl_w_reshape
 
+.. _ops-causal-conv1d:
+
 Direct 1D causal convolutions (CUDA-accelerated)
-------------------------------------------------
+-------------------------------------------------
 
 Non-FFT CUDA kernels for short and fused 1D causal convolutions.  Useful
 for small kernel sizes (where FFT overhead dominates) and as building
@@ -59,8 +65,10 @@ blocks for fused Hyena variants.
    ~ops.causal_conv1d_custom.causal_conv1d
    ~ops.causal_conv1d_custom.b2b_causal_conv1d
 
+.. _ops-circular-fftconv:
+
 Circular FFT convolutions
--------------------------
+--------------------------
 
 Periodic-boundary FFT convolutions for global mixing without zero padding.
 
@@ -72,8 +80,10 @@ Periodic-boundary FFT convolutions for global mixing without zero padding.
    ~ops.circular_fftconv.circular_fftconv2d_fp32_bhl
    ~ops.circular_fftconv.circular_fftconv3d_fp32_bhl
 
+.. _ops-chunking:
+
 Chunking utilities
-------------------
+-------------------
 
 Helpers to bound the FFT working-set memory by processing along the
 sequence axis in chunks.
@@ -87,10 +97,12 @@ sequence axis in chunks.
    ~ops.fftconv_chunked.set_default_chunk_size
    ~ops.fftconv_chunked.get_default_chunk_size
 
+.. _ops-mixed-fftconv:
+
 Mixed boundary-condition FFT convolutions
 -----------------------------------------
 
-FFT convolutions with per-axis boundary conditions — periodic on some
+FFT convolutions with per-axis boundary conditions: periodic on some
 spatial axes, zero-padded on others.  See
 :doc:`../ops/mixed_boundary_conditions` for the per-axis algorithm and the
 ``fft_padding`` API.

docs/architecture.md

@@ -30,42 +30,54 @@ research team can swap any one of them without touching the others.
 
 ## What each layer owns
 
-- **nvsubquadratic** (this library) — the PyTorch-native API.
+- **nvsubquadratic** (this library): the PyTorch-native API.
   Sequence/spatial mixers (Hyena, Mamba, attention variants), learned
   kernels, residual blocks, networks, and the datamodule/wrapper
   scaffolding consumed by `experiments`.  All public surface lives in
   the {doc}`api_reference/index`.
-- **subquadratic-ops** (separate repo) — the fused CUDA kernels.  Causal
+- **subquadratic-ops** (separate repo): the fused CUDA kernels.  Causal
   Conv1D for short kernels (2–256), FFT-based Causal Conv1D for long
   kernels (up to 8K–16M), B2B Causal Conv1D for striped Hyena
   architectures, plus the 1D/2D FFT primitives.  nvSubquadratic
   delegates here via {mod}`subquadratic_ops_torch` and the published
   docs are at
   <https://nvidia-bionemo.github.io/subquadraticOps-docs/>.
-- **megatron-core** — Megatron's distributed-training primitives
+- **megatron-core**: Megatron's distributed-training primitives
   (tensor / pipeline / context parallelism).  nvSubquadratic uses it via
   {mod}`nvsubquadratic.parallel.utils`'s
   `init_parallel_state` and the context-parallel
   `DistributedDepthwiseConvNd` wrappers.
 
-This layering keeps API ergonomics in nvSubquadratic, kernel
-optimisation in subquadratic-ops, and distributed bookkeeping in
-megatron-core.  Practically: if a kernel is slow, fix it in
-subquadratic-ops; if an interface is awkward, fix it here.
+API ergonomics live in nvSubquadratic, kernel optimisation in
+subquadratic-ops, and distributed bookkeeping in megatron-core.  In
+practice: if a kernel is slow, fix it in subquadratic-ops; if an
+interface is awkward, fix it here.
+
+## The HyenaND operator
+
+The operator that gives this stack its name is the
+`Short Conv → Gate → Long Conv → Gate` block you see throughout the network
+code.  {doc}`how_hyenand_works` builds it up from attention, with the full
+diagram and a worked trace.  Its fused FFT long-convolution path lives in
+subquadratic-ops; see {doc}`ops/README`.
 
 ## Naming conventions
 
 Two conventions show up everywhere in the ops and module code.  Both
 are documented in detail in `docs/ops/README.md`; the short version:
 
-- **`BHL` vs `BLH`** — memory layout.  `BHL` is channels-first
+- **`BHL` vs `BLH`**: memory layout.  `BHL` is channels-first
   (`[B, H, *spatial]`, matches `torch.nn.ConvNd`); `BLH` is
   channels-last (`[B, *spatial, H]`, common in transformer code).  The
   FFT runs faster on contiguous spatial axes, so BHL is the fast path.
-- **`_w_reshape`** — wrappers that accept BLH input, internally reshape
+- **`_w_reshape`**: wrappers that accept BLH input, internally reshape
   to BHL, run the fast path, and reshape back.  Recommended entry point
   for channels-last callers.
-- **`_chunked`** — processes channels in groups to cap peak FFT memory.
+- **`_chunked`**: processes channels in groups to cap peak FFT memory.
+- **`fp32` vs `fp16`**: internal compute precision.  fp16 ops require
+  power-of-2 spatial dims (cuFFT constraint) and use dual mean-centering
+  for numerical stability.  See the
+  [FP16 circular FFT convolution report](https://github.com/NVIDIA-BioNeMo/nvSubquadratic/blob/main/reports/fp16_fft_convolution/REPORT.md).
 
 So `causal_fftconv1d_fp32_bhl_w_reshape` is a causal 1D FFT conv that
 accepts channels-last input, runs the fp32 channels-first kernel under
@@ -77,27 +89,10 @@ Hyena, attention, CKConv, and Mamba all expose the same
 `(query, key, value)` mixer signature.  The dispatch lives in
 {class}`nvsubquadratic.modules.sequence_mixer.QKVSequenceMixer`:
 configure it with a `LazyConfig` over any of the mixers and the rest of
-the model code is unchanged.  Switching architectures is a one-line
-config diff.
-
-## The lazy-instantiation system
-
-Every config file under `examples/` is a tree of
-{class}`nvsubquadratic.lazy_config.LazyConfig` specs.  A spec is a
-deferred constructor call: `LazyConfig(SomeClass)(arg=...)` returns a
-proxy that holds the target and the arguments, but doesn't instantiate
-yet.  {func}`nvsubquadratic.lazy_config.instantiate` walks the tree,
-resolves nested specs depth-first, evaluates arithmetic strings (for
-`L_cache = "max(H, W)"`-style expressions), and constructs the live
-object graph.
-
-This is why most module constructors take `*_cfg: LazyConfig` rather
-than concrete instances — the user-facing config file decides what to
-instantiate; the module never imports a specific norm/conv/scheduler
-class directly.
+the model code is unchanged, so switching architectures is a one-line
+config change.
 
 ## Further reading
 
-- {doc}`api_reference/index` — the curated API.
-- `docs/ops/README.md` — math primer for the FFT-based convolution ops.
-- `docs-tracker.md` (repo root) — current docstring coverage status.
+- {doc}`api_reference/index`: the curated API.
+- `docs/ops/README.md`: math primer for the FFT-based convolution ops.