Fix six issues flagged by the Greptile review:

- Make DeepONetWrapper / DeepONet3DWrapper inherit from
  physicsnemo.core.module.Module (MOD-001). Core DeepONet / DeepONet3D
  also pass proper MetaData dataclasses.
- Raise ValueError at __init__ when mionet / fourier_mionet / tno are
  constructed without branch2_config (prevents silent degradation to a
  single-branch model).
- Add optional output_window constructor parameter so the
  temporal_projection decoder registers temporal_head at __init__,
  producing a deterministic state_dict that round-trips cleanly.
  set_output_window is retained for backwards compatibility.
- Raise ValueError from MLPBranch when num_layers < 2.
- Convert public docstrings to r-prefixed raw strings with
  Parameters / Forward / Outputs sections and LaTeX shape notation
  per MOD-003.
- Add jaxtyping.Float annotations and torch.compiler.is_compiling()
  guarded shape validation to all public forward methods
  (MOD-005, MOD-006).

Signed-off-by: wdyab <wdyab@nvidia.com>
Made-with: Cursor

Fix the new P1 issue flagged in the second Greptile review and close
two secondary gaps the summary called out:

- DeepONet.forward / DeepONet3D.forward: raise RuntimeError when
  decoder_type='temporal_projection' is used but temporal_head is
  still None (i.e. the user neither passed output_window at
  construction nor called set_output_window before forward).
  Previously the silent ``if temporal_head is not None`` skip
  returned (B, H, W, width) instead of (B, H, W, K).
- Deduplicate the VALID_VARIANTS list: pulled to a module-level
  _VALID_VARIANTS tuple; both DeepONet and DeepONet3D still expose it
  as the VALID_VARIANTS class attribute for a stable public API.
- Extend the parametrized test lists to cover fourier_deeponet,
  hybrid_deeponet, and fourier_mionet, and add a dedicated
  TestFourierBranchPaths class with num_fourier_layers > 0 so the
  spectral-conv code path in SpatialBranch / SpatialBranch3D is
  actually exercised in CI.
- Add a TestTemporalProjectionGuard::test_forward_without_output_window_raises
  regression test for the new RuntimeError.

Signed-off-by: wdyab <wdyab@nvidia.com>
Made-with: Cursor

Proactive audit on top of Greptile's round-4 findings.  All
plausible silent-degradation combinations at the config boundary
now fail loudly at __init__ instead of producing wrong shapes or
cryptic PyTorch errors at forward time.

Construction-time guards added to both DeepONet and DeepONet3D:

- Unknown decoder_type is rejected up front against a new
  module-level ``_VALID_DECODER_TYPES`` set (previously deferred
  to ``_build_decoder`` and only surfaced on the non-temporal
  branch).
- MLPBranch branch1 paired with decoder_type='conv' is rejected
  (would otherwise crash inside ``Conv2d`` with a generic
  "Expected 3D or 4D input" message).  Unified with the existing
  temporal_projection guard into a single check.
- MLPBranch branch1 paired with a non-MLPBranch branch2 is
  rejected (element-wise product assumed matching ranks;
  previously broadcast nonsensically or raised a cryptic dim
  mismatch at forward).

Regression tests:

- ``TestMLPBranchConvDecoderGuard`` -- 2D/3D
- ``TestMixedBranchTypeGuard`` -- 2D/3D
- ``TestInvalidDecoderTypeGuard`` -- 2D/3D

Full suite: 47 passed.

Signed-off-by: wdyab <wdyab@nvidia.com>
Made-with: Cursor

``_build_conv_encoder`` called ``get_activation`` directly without
the ``sin`` special-case handling used in every other activation
site in ``branches.py``.  Passing
``{"encoder": {"type": "conv", "activation_fn": "sin"}}`` therefore
raised ``KeyError: Activation function sin not found``.

``torch.sin`` is a bare callable and cannot be placed inside an
``nn.Sequential`` (which requires ``nn.Module`` instances), so the
fix introduces a small ``_SinActivation`` wrapper module alongside
``_build_conv_encoder``.  The helper is module-level and is called
from both ``DeepONet`` and ``DeepONet3D``; only one fix site exists
despite the function being invoked from both classes.

Regression test ``TestConvEncoderSinActivation`` constructs a
multi-layer conv encoder with ``activation_fn="sin"`` and runs a
forward pass to confirm neither the ``KeyError`` nor a
``nn.Sequential`` ``TypeError`` resurface.

Signed-off-by: wdyab <wdyab@nvidia.com>
Made-with: Cursor

- Rewrite test suite to the constructor + non-regression + checkpoint
  + gradient + compile pattern; relocate to
  ``test/experimental/models/xdeeponet/`` to match the ``flare/`` /
  ``fno/`` per-model layout.  Commit ``.pth`` goldens + regeneration
  script under ``data/``.
- Add ``Examples`` sections to every user-facing class.
- Add ``jaxtyping.Float`` annotations to top-level ``forward`` methods
  (MOD-006).
- Remove ``README.md``; no model under ``physicsnemo/`` ships one.
  Design rationale now lives in module-level and class-level docstrings.

Signed-off-by: wdyab <wdyab@nvidia.com>
Made-with: Cursor

Address @peterdsharpe review feedback on PR NVIDIA#1576: the ``variant`` and
``decoder_type`` parameters now carry ``typing.Literal`` annotations
rather than bare ``str``, so static type checkers and IDE
auto-completion can flag unknown values at the call site instead of
deferring to the runtime ``ValueError``.

The ``Literal`` aliases ``_VariantStr`` and ``_DecoderTypeStr`` are
defined once at module scope in ``deeponet.py`` and imported into
``wrappers.py``.  ``_VALID_VARIANTS`` and ``_VALID_DECODER_TYPES`` are
now derived from those aliases via ``typing.get_args`` so the static
and runtime views cannot drift.

Behaviour is unchanged: Python does not enforce ``Literal`` at runtime,
so the existing ``.lower()`` normalization and ``ValueError`` guards
keep mixed-case inputs working (verified by the existing
``TestDecoderTypeNormalization`` round-trip).  No tests, fixtures, or
constructor signatures were affected; full suite remains 13 passing
(+ 1 deselected ``torch.compile`` smoke run separately).

Signed-off-by: wdyab <wdyab@nvidia.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Addresses the inline-comment housekeeping items from the May-12 review
on PR NVIDIA#1576, with no public-API or semantic changes:

- Modernize type hints across xdeeponet sources: ``Dict[str, Any]`` ->
  ``dict[str, Any] | None``, ``Optional[X]`` -> ``X | None``,
  ``List`` / ``Tuple`` -> ``list`` / ``tuple``. Drop ``Dict``,
  ``Optional``, ``List``, ``Tuple`` imports from ``typing``. Annotation
  files already had ``from __future__ import annotations`` so this is
  safe on the minimum supported Python.
- Rename ``padding.py`` -> ``_padding.py`` to signal that the module is
  package-internal and may be restructured without notice. Update the
  one importer (``wrappers.py``) accordingly. Add ``jaxtyping.Shaped``
  annotations and full Parameters/Returns docstrings on
  ``pad_right_nd`` and ``pad_spatial_right``; the helpers are
  dtype-agnostic (used on real-valued tensors but the implementation is
  structural) so ``Shaped`` is preferred over ``Float``.
- Add a prominent ``.. important::`` block to ``_UNet2DFromUNet3D``
  spelling out the 8x memory/compute cost of selecting
  ``num_unet_layers > 0`` in a 2D ``SpatialBranch``, since the upstream
  library UNet is 3D-only and we tile.
- Expose ``has_temporal_projection`` as a public read-only property on
  both ``DeepONet`` and ``DeepONet3D`` to replace external reads of
  ``_temporal_projection``. Drop the dead cache of that flag in the two
  wrapper classes (the assignment had no remaining readers).
- Replace the 2D wrapper's permute/slice/permute spatial extraction
  with the cleaner ``x[:, :, :, 0, :]`` slice that mirrors the 3D
  version. Same result, fewer ops.
- Document the ``branch1_config`` / ``branch2_config`` / ``trunk_config``
  dict schemas in a new Notes section on the ``DeepONet`` class
  docstring, with ``.. code-block::`` examples enumerating all
  recognised keys and their defaults. ``DeepONet3D`` already references
  the 2D docstring so it inherits the schema for free.

Bumps no version, removes no public symbols. Behavior, state_dict keys
and forward outputs are unchanged.

Adds an elementwise sine activation as a regular ``nn.Module`` and
registers it under the key ``"sin"`` in
``physicsnemo.nn.module.activations.ACT2FN`` so it can be looked up by
name via ``get_activation("sin")``.  Also re-exports the ``Sin`` class
from ``physicsnemo.nn``.

This unblocks the xdeeponet refactor (next commit), which previously
carried a private ``_SinActivation`` shim and several
``if activation_fn.lower() == "sin"`` special-cases in branch/decoder
construction.  Both can now go away because the activation registry
handles ``"sin"`` natively.

Addresses Peter Sharpe's CHANGES_REQUESTED review on PR NVIDIA#1576 in full,
and subsumes the 3D-UFNO portion of the planned xFNO PR into this one.
Net: -139 lines despite gaining trunkless mode, time-axis-extend,
multi-channel output, coord features, multi-layer lift, and 2D/3D
genericity.

Theme 1 — Dimensional unification (Peter NVIDIA#37, NVIDIA#47, NVIDIA#52, NVIDIA#53):

- ``DeepONet`` (formerly DeepONet + DeepONet3D) takes ``dimension: int``
  (2 or 3) and dispatches via ``_DIM_DEFAULTS`` and per-dim conv/spectral
  primitives, mirroring the ``FNO`` pattern.
- ``SpatialBranch`` (formerly SpatialBranch + SpatialBranch3D) takes
  ``dimension`` and uses an ``_DIM_LAYERS`` lookup for
  ``SpectralConv``/``Conv``/``BatchNorm``/``AdaptiveAvgPool``/
  ``UNetAdapter`` and the permute helpers.
- ``Conv{2,3}dFCLayer`` is selected via a one-line lookup
  (Peter NVIDIA#45).

Theme 2 — Wrappers folded into DeepONet (Peter NVIDIA#54, NVIDIA#64, NVIDIA#65):

- ``wrappers.py`` deleted (``DeepONetWrapper`` and ``DeepONet3DWrapper``
  removed).  Padding behaviour is now a constructor flag,
  ``auto_pad: bool = False``, and the model dispatches to
  ``_forward_packed`` / ``_forward_packed_trunkless`` accordingly.
- 6-cell call matrix (trunked/trunkless × packed/core × spatial/mlp)
  is documented in the class docstring.
- The previous private ``_temporal_projection`` attribute is exposed as
  a public ``has_temporal_projection`` property (Peter NVIDIA#55).

Theme 3 — Deduplication (Peter NVIDIA#43, NVIDIA#44, NVIDIA#50, NVIDIA#51, NVIDIA#40, related Greptile):

- ``TrunkNet`` and ``MLPBranch`` deleted — both duplicated
  ``physicsnemo.models.mlp.FullyConnected``; users now pass any
  ``nn.Module`` for the trunk / branches (DI-first API).
- ``_SinActivation`` deleted; the activation is registered as ``"sin"``
  in ``physicsnemo.nn.module.activations.ACT2FN`` (previous commit).
  All ``if activation_fn.lower() == "sin"`` special-cases removed.
- ``DeepONet.from_config`` and the dict-config schema removed entirely;
  Hydra-style ``_target_`` instantiation supersedes it.
- ``count_params`` collapsed from 4 duplicate copies to 1.

Theme 4 — xFNO fold-in:

- ``trunk: nn.Module | None = None`` enables trunkless mode (the 3D-UFNO
  use case from the planned xFNO PR).
- ``out_channels: int = 1`` adds multi-channel output to every path.
- ``time_modes: int | None`` enables xFNO-style time-axis-extend in
  trunkless packed mode: replicate-pads the last spatial axis to fit
  ``2 * time_modes`` and crops to the requested ``target_times``.
- ``coord_features`` and ``lift_layers``/``lift_hidden_width`` parameters
  on ``SpatialBranch`` replace the deleted dict-driven "conv encoder"
  option.

Theme 5 — Housekeeping (Peter NVIDIA#33, NVIDIA#34, NVIDIA#38, NVIDIA#41, NVIDIA#48, NVIDIA#57, NVIDIA#58, NVIDIA#59,
Charlelie NVIDIA#26, Greptile NVIDIA#5, NVIDIA#6):

- ``padding.py`` renamed to private ``_padding.py``; all functions
  carry ``jaxtyping.Shaped`` annotations.
- All public forward methods carry ``jaxtyping.Float`` annotations and
  ``torch.compiler.is_compiling`` shape-validation guards.
- ``Literal`` type aliases for ``decoder_type`` and other enums;
  case-insensitive validation against ``get_args`` (Greptile NVIDIA#15).
- Modern type hints throughout (``dict[str, Any] | None``, no
  ``Dict``/``Optional``).
- All public docstrings use ``r"""`` raw-string prefix, LaTeX math for
  tensor shapes, double backticks for inline code, and Examples
  sections.
- ``Notes`` block in ``branches.py`` documents the ``num_unet_layers``
  8x memory/compute penalty (Peter NVIDIA#49).

Theme 6 — Tests (Peter NVIDIA#60, NVIDIA#61, NVIDIA#62, NVIDIA#63, Charlelie NVIDIA#29):

- ``_FIXTURE_REGISTRY`` drives all non-regression tests across 9
  scenarios: u_deeponet 2D/3D, fourier_deeponet, mionet,
  temporal_projection, multi-channel packed 2D, xfno trunkless 3D
  (with and without time-axis-extend), and core 2D MLP-branch.
- New 3D gradient-flow test and 3D ``torch.compile`` test.
- ``fullgraph=True`` probe tests for 2D and 3D marked
  ``@pytest.mark.xfail(strict=False)`` to empirically answer Peter NVIDIA#63.
- ``_load_golden`` uses ``pytest.skip`` for missing fixtures so CI
  passes pending cluster-side golden regeneration.
- Test class structure mirrors MOD-008a/b/c: ``TestDeepONetConstructor``,
  ``TestDeepONetNonRegression``, ``TestDeepONetCheckpoint``,
  ``TestDeepONetGradientFlow``, ``TestDeepONetCompile``,
  ``TestDeepONetTimeAxisExtend``.

CHANGELOG bullet rewritten to describe the actual shipped API
(was stale, still described the old config-driven 8-variant model).