mkdocs.yml

# ─────────────────────────────────────────────────────────────────────────
# sweep-solver — documentation content
#
# The published site is the sweepx umbrella (https://sweepx.deepwave.group/):
# mkdocs-multirepo imports this `docs/` and renders it with sweepx's theme, so
# the LOOK is defined once, there — not here. This repo's own Pages deployment
# now only redirects to that site (see .github/workflows/pages.yml).
#
# What stays here: the nav, and the plugins/extensions the content itself needs
# (notebooks, API from docstrings, admonitions, math). Deliberately absent:
# theme.custom_dir, extra_css/extra_javascript, palette/font tuning — those were
# a second copy of sweepx's theme and drifted.
#
# `mkdocs serve` here still works for a quick content preview; it renders with
# plain Material, without the sweepx skin.
# ─────────────────────────────────────────────────────────────────────────
site_name: sweep-solver
site_description: The differentiable GPU wave-equation engine of the sweep ecosystem.
repo_url: https://github.com/DeepWave-KAUST/sweep
repo_name: DeepWave-KAUST/sweep
edit_uri: edit/dev/docs/

theme:
  name: material          # placeholder — sweepx supplies the published theme
  features:
    - navigation.indexes
    - content.code.copy

plugins:
  - search
  - mkdocs-jupyter:
      include_source: true        # required for the per-notebook Download button
      execute: false
      ignore_h1_titles: true
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src]
          options:
            # Inspect (= import) modules at build time so runtime docstring
            # mutations from `WaveEquation.__init_subclass__` (auto-injected
            # SPECS admonitions) are visible to griffe.
            force_inspection: true
            show_source: false
            show_root_heading: true
            docstring_style: google
            docstring_section_style: list
            members_order: source
            separate_signature: true
            show_signature_annotations: true
            merge_init_into_class: true
            line_length: 88
            # Hide noise attributes from the rendered class page:
            #   - "!^_[^_]" — single-underscore private (mkdocstrings default)
            #   - "!^__"    — dunder attributes (``__doc__``, ``__module__``,
            #                 ``__annotations__``, etc.)
            #   - FIELD_SPECS / MODEL_SPECS — already rendered by the
            #     auto-injected admonitions in the class docstring
            #     (``WaveEquation.__init_subclass__``).
            filters:
              - "!^_[^_]"
              - "!^__"
              - "!^FIELD_SPECS$"
              - "!^MODEL_SPECS$"
              - "!^default_pml_type$"
              - "!^supports_apm$"

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - tables
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      permalink: true

nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Quick Start: getting-started/quickstart.md
  - User Guide:
      - Backends: user-guide/backends.md
      - Equations: user-guide/equations.md
      - Operators: user-guide/operators.md
      - Propagators: user-guide/propagators.md
      - Domain decomposition: user-guide/parallel.md
      - Datasets: user-guide/datasets.md
      - Extending: user-guide/extending.md
      - CLI: user-guide/cli.md
  - Examples:
      - Overview: examples/index.md
      - Notebooks:
          - Hello · SWEEP: notebooks/00_hello_fwi.ipynb
          - FWI:
              - Acoustic · Marmousi: notebooks/01_fwi_acoustic_marmousi.ipynb
              - Acoustic VRZ · FWI imaging: notebooks/17_fwi_vrz_marmousi.ipynb
              - Elastic · Marmousi: notebooks/02_fwi_elastic_marmousi.ipynb
              - Multiscale: notebooks/03_fwi_multiscale.ipynb
              - Batched local windows · streamer: notebooks/23_batched_local_window_fwi.ipynb
              - 3D Overthrust: notebooks/11_fwi_acoustic_overthrust_3d.ipynb
          - NN · FWI:
              - IFWI · SIREN: notebooks/13_ifwi_siren.ipynb
          - Wavefields:
              - DAS: notebooks/04_das_zhao_vs_mu.ipynb
              - Elastic: notebooks/06_wavefield_elastic.ipynb
              - Elastic vector-reflectivity: notebooks/16_elastic_vector_reflectivity.ipynb
              - Topography (irregular FS): notebooks/15_wavefield_topography.ipynb
              - Per-edge free surface (4 faces): notebooks/24_wavefield_per_edge_free_surface.ipynb
              - Visco-acoustic · constant-Q: notebooks/29_wavefield_visco_acoustic.ipynb
              - Solver hyperparameters: notebooks/09_solver_hyperparams.ipynb
          - Anisotropic:
              - Acoustic VTI: notebooks/05_wavefield_vti.ipynb
              - Elastic TTI · rotation (2-D RSG): notebooks/10_wavefield_elastic_tti.ipynb
              - Elastic TTI · 3-D: notebooks/27_wavefield_elastic_tti_3d.ipynb
              - Elastic TTI · displacement (Oh 2020): notebooks/28_wavefield_elastic_tti_2nd.ipynb
          - Imaging:
              - RTM · Marmousi: notebooks/08_rtm_acoustic_marmousi.ipynb
              - Custom gradient: notebooks/14_custom_gradient.ipynb
              - ADCIG · Poynting (custom backward): notebooks/16_adcig.ipynb
              - ADCIG · space-lag (2D & 3D): notebooks/22_adcig_space_lag.ipynb
          - HPC:
              - Memory strategies: notebooks/07_memory_strategies.ipynb
              - FWI · boundary compression: notebooks/19_fwi_boundary_dtype.ipynb
              - Multi-GPU · DDP vs 1 GPU: notebooks/12_multi_gpu.ipynb
              - Domain decomposition · model-parallel: notebooks/25_domain_decomposition.ipynb
              - Domain decomposition · Overthrust 3-D: notebooks/26_dd_overthrust_3d.ipynb
          - Extending:
              - Add a new equation: notebooks/18_extending_add_new_equation.ipynb
          - Sensitivity & resolution:
              - Acoustic · radiation (Vp, ρ): notebooks/20_radiation_acoustic.ipynb
              - Elastic · radiation P-P/P-S/S-S: notebooks/21_radiation_elastic.ipynb
      - Scripts:
          - Multi-GPU DDP: examples/multi_gpu_dist.md
  - Playground:
      - Overview: playground/index.md
      - Wave modeling: playground/modeling.md
      - Seismogram & free surface: playground/seismogram.md
      - Numerical dispersion: playground/dispersion.md
      - Anisotropic wavefront: playground/anisotropy.md
  - API Reference:
      - api/index.md
      - Equations:
          - api/equations/index.md
          - Acoustic: api/equations/acoustic.md
          - Acoustic3D: api/equations/acoustic3d.md
          - Acoustic1st: api/equations/acoustic1st.md
          - AcousticVRZ: api/equations/acoustic_vrz.md
          - AcousticLSRTM: api/equations/acoustic_lsrtm.md
          - AcousticLSRTM3D: api/equations/acoustic_lsrtm3d.md
          - ViscoAcoustic: api/equations/visco_acoustic.md
          - Elastic: api/equations/elastic.md
          - Elastic3D: api/equations/elastic3d.md
          - ElasticTTI: api/equations/elastic_tti.md
          - ElasticTTISG: api/equations/elastic_tti_sg.md
          - ElasticTTISG3D: api/equations/elastic_tti_sg3d.md
          - ElasticTTI2nd: api/equations/elastic_tti_2nd.md
          - DAS family: api/equations/das.md
      - Operators:
          - api/operators/index.md
      - Propagators:
          - api/propagators/index.md
          - Propagator Options: api/propagators/options.md
          - PropTorch: api/propagators/prop_torch.md
          - PropJax: api/propagators/prop_jax.md
      - Parallel (DD): api/parallel.md