Examples
========

All repository examples live in ``examples/``. They are not all at the same
level of maturity: some scripts use the current class-based workflow, while a
few older research scripts still use lower-level helper paths.

Recommended starting points
---------------------------

Use these first if you are learning the current API:

.. list-table::
   :widths: 30 12 12 46
   :header-rows: 1

   * - File
     - Room
     - Mode
     - Purpose
   * - ``deism_singleparam_example.py``
     - shoebox
     - RIR
     - Current class-based single-run example
   * - ``deism_arg_singleparam_example.py``
     - convex
     - RIR
     - Current class-based convex-room example
   * - ``deisms_lc_mix_test.py``
     - shoebox
     - RTF
     - Compare ``ORG``, ``LC``, and ``MIX`` using the current class workflow
   * - ``shoebox_images_cal_compare.py``
     - shoebox
     - RTF
     - Compare shoebox image-calculation variants in the current class workflow

Class-based workflow examples
-----------------------------

``deism_singleparam_example.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Uses ``DEISM("RIR", "shoebox")``.
- Good first script for the current shoebox pipeline.
- Writes outputs below ``outputs/RTFs``.

``deism_arg_singleparam_example.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Uses ``DEISM("RIR", "convex")``.
- Shows the current convex-room update order:
  room -> materials -> frequencies -> source/receiver -> directivities -> run.
- Good first script for DEISM-ARG with the current class pipeline.

``deisms_lc_mix_test.py``
~~~~~~~~~~~~~~~~~~~~~~~~~

- Uses the current class-based shoebox workflow.
- Compares the ``ORG``, ``LC``, and ``MIX`` methods.
- Useful when evaluating method trade-offs rather than learning the API from
  scratch.

``shoebox_images_cal_compare.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Uses the current class-based shoebox workflow.
- Focuses on image-generation variants and timing.
- Useful when evaluating image-calculation performance rather than acoustics
  correctness alone.

Advanced and legacy research scripts
------------------------------------

The following scripts are still useful, but they are not the best introduction
to the current public workflow:

``deism_args_compare.py``
~~~~~~~~~~~~~~~~~~~~~~~~~

- Convex-room comparison script.
- Uses older lower-level helper paths rather than the current class-first pattern.
- Useful for method comparison and research inspection.

``deism_arg_pra_compare.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Convex-room validation against ``pyroomacoustics``.
- Uses older helper paths rather than the current class-first pattern.
- Useful for image-generation validation and benchmarking.

Paper reproduction examples
---------------------------

``deism_arg_IWAENC_fig5_fig6.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Reproduces IWAENC 2024 figures for arbitrary geometries.
- Uses the class-based convex path.
- Best treated as a research reproduction script, not a first-run example.

``deism_JASA_fig8.py`` and ``deism_JASA_fig9.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Reproduce figures from the main JASA paper.
- Useful as reference workflows for publication-aligned settings.
- More complex than the basic examples and may depend on external data files.

Other scripts
-------------

``DEinterface.py`` and ``DeismInterface.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Integration or interface-oriented scripts.
- Not recommended as entry points for understanding the main DEISM workflow.