Yhonatangayer · Yhonatangayer · Jul 12, 2026 · Jun 30, 2026 · Jul 11, 2026 · Jul 11, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a problem so it can be fixed
+title: "[BUG] "
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Minimal reproducible example**
+```python
+# smallest script that reproduces the problem
+```
+
+**Expected behaviour**
+What you expected to happen.
+
+**Actual behaviour / traceback**
+```
+paste the full error / traceback here
+```
+
+**Environment**
+- OS:
+- Python version:
+- `pyshroom` version (`python -c "import shroom; print(shroom.__version__)"`):
+- How installed (PyPI / editable checkout):
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement
+title: "[FEATURE] "
+labels: enhancement
+---
+
+**Is your feature request related to a problem?**
+A clear description of the problem or limitation. e.g. "I'm always frustrated when ..."
+
+**Describe the solution you'd like**
+What you would like to happen.
+
+**Describe alternatives you've considered**
+Any alternative solutions or features you've considered.
+
+**Additional context**
+Any references (papers, other libraries) or context that would help.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest --cov=shroom --cov-report=term-missing -q
diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml
@@ -0,0 +1,26 @@
+name: Draft JOSS paper PDF
+
+on:
+  push:
+    paths:
+      - paper/**
+      - .github/workflows/draft-pdf.yml
+  workflow_dispatch:
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          paper-path: paper/paper.md
+
+      - name: Upload PDF artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          path: paper/paper.pdf
diff --git a/.gitignore b/.gitignore
@@ -37,5 +37,13 @@ data/
 /tests/anm_ref.npz
 
 # claude
-CLAUDE.md
 .claude
+
+# benchmark output figures
+benchmarks/figures/
+
+# coverage artifacts
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
diff --git a/.gitmodules b/.gitmodules
diff --git a/CITATION.cff b/CITATION.cff
@@ -9,8 +9,10 @@ type: software
 authors:
   - family-names: Gayer
     given-names: Yhonatan
-version: 0.1.1
-date-released: "2026-04-10"
+    orcid: "https://orcid.org/0009-0009-1156-9087"
+    affiliation: "Ben-Gurion University of the Negev"
+version: 0.2.1
+date-released: "2026-07-12"
 license: MIT
 repository-code: "https://github.com/Yhonatangayer/shroom"
 url: "https://github.com/Yhonatangayer/shroom"

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing to shroom
+
+Contributions are welcome — bug reports, feature requests, documentation fixes, and pull
+requests.
+
+## Reporting issues and seeking support
+
+- **Bugs and feature requests:** open an issue at
+  <https://github.com/Yhonatangayer/shroom/issues>. Please include your OS, Python version,
+  `shroom`/`pyshroom` version, and a minimal script that reproduces the problem.
+- **Questions and support:** open an issue with the `question` label, or start a discussion
+  on the repository. There are no private support channels — please keep questions public so
+  others benefit from the answers.
+
+## Development setup
+
+Clone the repository and install it in editable mode with the development extras:
+
+```bash
+git clone https://github.com/Yhonatangayer/shroom.git
+cd shroom
+pip install -e ".[dev]"
+```
+
+This installs the core library plus the `shroom_dev` companion package and the tooling
+used for tests, examples, and benchmarks (`pytest`, `black`, `sounddevice`, `pyyaml`).
+
+## Running the tests
+
+```bash
+pytest
+```
+
+All tests should pass before you open a pull request. If you add functionality, please add
+tests that cover it under `tests/`.
+
+## Coding style
+
+- Follow PEP 8. The project uses [`black`](https://black.readthedocs.io/) (installed with the
+  `[dev]` extra); run `black src tests examples benchmarks` before committing.
+- Prefer type hints and docstrings on public functions and classes — the docstrings serve as
+  the API reference.
+- Keep new code consistent with the surrounding modules' naming and structure.
+
+## Pull requests
+
+1. Fork the repository and create a feature branch.
+2. Make your change with accompanying tests and updated docstrings.
+3. Ensure `pytest` passes and the code is `black`-formatted.
+4. Open a pull request describing the change and the motivation.
+
+By contributing, you agree that your contributions will be licensed under the MIT License
+of this project.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Yhonatan Gayer
+Copyright (c) 2024-2026 Yhonatan Gayer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -2,6 +2,9 @@
 
 **Spherical Harmonics Room**
 
+[![CI](https://github.com/Yhonatangayer/shroom/actions/workflows/ci.yml/badge.svg)](https://github.com/Yhonatangayer/shroom/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 A Python library for simulating room acoustics using Spherical Harmonics (Ambisonics). It provides tools for simulating room impulse responses (ARIR), microphone arrays, and binaural rendering.
 
 ## Features
@@ -27,17 +30,20 @@ pip install pyshroom
 
 Installs `shroom` and its runtime dependencies (numpy, scipy, matplotlib, pyroomacoustics, sofar). This is all you need to simulate rooms, encode Ambisonics, and render binaural audio from your own scripts.
 
-### 2. With `shroom_dev` — extras for examples and projects
+### 2. With `shroom_dev` — extras for examples and benchmarks
 
 ```bash
 pip install "pyshroom[dev]"
 ```
 
-Installs everything above **plus** the companion package **`shroom_dev`**, which bundles helper modules used by the examples, tests, and research projects in this repo:
+`shroom` is the library; **`shroom_dev` is an optional companion package** (installed via the
+`[dev]` extra) holding evaluation metrics, plotting, and audio-playback helpers used by the
+examples, tests, and benchmarks. **It is not required to use the core `shroom` library** —
+only to run the examples/benchmarks in this repository. It bundles:
 
 - `shroom_dev.plot` — `loglog_plot` for error curves with variance bands.
 - `shroom_dev.sound` — `play_audio` helper around `sounddevice`.
-- `shroom_dev.errors` — the ASM/BSM evaluation metrics used by the `projects/` scripts (`asm_mse_error`, `asm_bin_mse_error`, `asm_bin_magnitude_mse_error`, `linear_spectral_error`, `bsm_mse_error`, `bsm_mag_mse_error`).
+- `shroom_dev.errors` — the ASM/BSM evaluation metrics used by the `benchmarks/` scripts (`asm_mse_error`, `asm_bin_mse_error`, `asm_bin_magnitude_mse_error`, `linear_spectral_error`, `bsm_mse_error`, `bsm_mag_mse_error`).
 - `shroom_dev.file_utils` — extra file loaders.
 
 The `[dev]` extra also pulls in `pytest`, `black`, `sounddevice`, and `pyyaml`.
@@ -52,15 +58,15 @@ cd shroom
 pip install -e ".[dev]"
 ```
 
-You can then run the example scripts under `examples/` and the research scripts under `projects/` directly — they import from `shroom` and `shroom_dev`.
+You can then run the example scripts under `examples/` and the validation scripts under `benchmarks/` directly — they import from `shroom` and `shroom_dev`.
 
 ## _Quick Start_
 
 ### Basic Binaural Rendering
 
 ```python
 import numpy as np
-from shroom.acoustics.room import Room
+from shroom import Room
 from shroom.paths import DEFAULT_WAV_PATH
 
 # 1. Initialize Room
@@ -87,9 +93,7 @@ room.plot(plot_3d=True)
 ```python
 import numpy as np
 from scipy.spatial.transform import Rotation
-from shroom.acoustics.room import Room
-from shroom.acoustics.processors import BinauralDecoder
-from shroom.utils.file_utils import load_file
+from shroom import Room, BinauralDecoder, load_file
 from shroom.paths import DEFAULT_HRTF_PATH, DEFAULT_WAV_PATH
 
 # 1. Initialize Room & Compute Ambisonics (Reference Frame)
@@ -115,8 +119,7 @@ binaural = decoder.process(amb_ref)
 ### Complete ASM Processing Chain
 
 ```python
-from shroom.acoustics.processors import ProcessorChain, ArrayDecoder, ASMEncoder, BinauralDecoder
-from shroom.encoders.asm import ASM
+from shroom import ProcessorChain, ArrayDecoder, ASMEncoder, BinauralDecoder, ASM
 
 # 1. Setup Signal Chain: Room -> Array -> ASM Encoder -> Binaural Decoder
 # Note: array_time_sh and asm_instance must be pre-configured
@@ -133,8 +136,7 @@ binaural_output = chain.process(room.compute_amb())
 ### Optimized Low-Order Rendering (MagLS)
 
 ```python
-from shroom.acoustics.hrtf_processing import magls_hrtf
-from shroom.acoustics.processors import BinauralDecoder
+from shroom import magls_hrtf, BinauralDecoder
 
 # 1. Compute MagLS-optimized HRTF (Mitigates spectral artifacts at low SH orders)
 hrtf_magls = magls_hrtf(original_hrtf, sh_order=1)
@@ -171,6 +173,13 @@ If you use shroom in your research, please cite our paper:
 ```
 ## Changelog
 
+### 0.2.1
+
+Maintenance release — no functional or API changes. Adds the JOSS paper
+(`paper/`), continuous integration with coverage, contribution guidelines, and
+expanded tests; renames the research `projects/` scripts to `benchmarks/` and
+removes the unused `spaudiopy` submodule.
+
 ### 0.2.0
 
 Three coupled changes. The first two are tied together (the pyroomacoustics upgrade
@@ -208,6 +217,15 @@ matrix — and therefore ASM and AA-MagLS encoder filters — differ from shroom
 the change removes the ghost image and moves the simulated array closer to true sphere
 physics. No API changes.
 
+## Contributing & Support
+
+Contributions, bug reports, and questions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for development setup and guidelines. To report a bug, request a feature, or ask a question,
+open an issue at <https://github.com/Yhonatangayer/shroom/issues>.
+
+The `benchmarks/` directory contains validation scripts that reproduce the encoder-convergence
+figures from the paper; see [benchmarks/README.md](benchmarks/README.md).
+
 ## License
 
 MIT License
diff --git a/benchmarks/README.md b/benchmarks/README.md
@@ -0,0 +1,34 @@
+# Benchmarks
+
+Validation experiments that reproduce the encoder-convergence figures from the SHroom
+paper. Each script sweeps the spherical-harmonics (SH) order and reports how the encoder
+error decays, validating the accuracy of the encoders against high-order references.
+
+| Script | What it validates |
+|--------|-------------------|
+| `asm_convergence.py` | Ambisonics Signal Matching (ASM) encoder error vs. SH order. |
+| `bsm_convergence.py` | Binaural Signal Matching (BSM) encoder error vs. SH order (against a MATLAB reference). |
+| `aa_magls_convergence.py` | Array-aware MagLS binaural magnitude error vs. SH order. |
+
+## Requirements
+
+These scripts depend on the optional **`shroom_dev`** companion package (evaluation
+metrics in `shroom_dev.errors` and plotting in `shroom_dev.plot`). Install the `[dev]`
+extra from a checkout of the repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+`shroom_dev` is **not** required to use the core `shroom` library — only to run these
+benchmarks and the examples.
+
+## Running
+
+```bash
+python benchmarks/asm_convergence.py
+python benchmarks/bsm_convergence.py
+python benchmarks/aa_magls_convergence.py
+```
+
+Each script writes its figures to `benchmarks/figures/`.
diff --git a/projects/aa_magls_project/main.py → benchmarks/aa_magls_convergence.py b/projects/aa_magls_project/main.py → benchmarks/aa_magls_convergence.py
diff --git a/projects/asm_project/main.py → benchmarks/asm_convergence.py b/projects/asm_project/main.py → benchmarks/asm_convergence.py
diff --git a/projects/bsm_project/main.py → benchmarks/bsm_convergence.py b/projects/bsm_project/main.py → benchmarks/bsm_convergence.py
diff --git a/examples/binaural_using_asm.py b/examples/binaural_using_asm.py
@@ -9,7 +9,7 @@
     BinauralDecoder,
 )
 from shroom.geometry.sampling import sphereicalGrid
-from shroom.utils.grid_utils import from_spaudiopy_grid, from_fibonacci_grid
+from shroom.utils.grid_utils import from_fibonacci_grid
 from shroom.encoders.asm import ASM
 from shroom.utils.file_utils import load_file
 from shroom_dev.sound import play_audio

diff --git a/examples/binaural_using_bsm.py b/examples/binaural_using_bsm.py
@@ -10,7 +10,7 @@
     BSMEncoder,
 )
 from shroom.geometry.sampling import sphereicalGrid
-from shroom.utils.grid_utils import from_spaudiopy_grid, from_fibonacci_grid
+from shroom.utils.grid_utils import from_fibonacci_grid
 from shroom.encoders.bsm import BSM
 from shroom.utils.file_utils import load_file
 from shroom_dev.sound import play_audio