torchrir 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

torchrir/plotting.py

@@ -20,7 +20,15 @@ def plot_scene_static(
     title: Optional[str] = None,
     show: bool = False,
 ):
-    """Plot a static room with source and mic positions."""
+    """Plot a static room with source and mic positions.
+
+    Example:
+        >>> ax = plot_scene_static(
+        ...     room=[6.0, 4.0, 3.0],
+        ...     sources=[[1.0, 2.0, 1.5]],
+        ...     mics=[[2.0, 2.0, 1.5]],
+        ... )
+    """
     plt, ax = _setup_axes(ax, room)
 
     size = _room_size(room, ax)
@@ -46,21 +54,35 @@ def plot_scene_dynamic(
     src_traj: Tensor | Sequence,
     mic_traj: Tensor | Sequence,
     step: int = 1,
+    src_pos: Optional[Tensor | Sequence] = None,
+    mic_pos: Optional[Tensor | Sequence] = None,
     ax: Any | None = None,
     title: Optional[str] = None,
     show: bool = False,
 ):
-    """Plot source and mic trajectories within a room."""
+    """Plot source and mic trajectories within a room.
+
+    If trajectories are static, only positions are plotted.
+
+    Example:
+        >>> ax = plot_scene_dynamic(
+        ...     room=[6.0, 4.0, 3.0],
+        ...     src_traj=src_traj,
+        ...     mic_traj=mic_traj,
+        ... )
+    """
     plt, ax = _setup_axes(ax, room)
 
     size = _room_size(room, ax)
     _draw_room(ax, size)
 
-    src_traj = _as_trajectory(src_traj, ax)
-    mic_traj = _as_trajectory(mic_traj, ax)
+    src_traj = _as_trajectory(src_traj)
+    mic_traj = _as_trajectory(mic_traj)
+    src_pos_t = _extract_positions(src_pos, ax) if src_pos is not None else src_traj[0]
+    mic_pos_t = _extract_positions(mic_pos, ax) if mic_pos is not None else mic_traj[0]
 
-    _plot_trajectories(ax, src_traj, step=step, label="source path")
-    _plot_trajectories(ax, mic_traj, step=step, label="mic path")
+    _plot_entity(ax, src_traj, src_pos_t, step=step, label="sources", marker="^")
+    _plot_entity(ax, mic_traj, mic_pos_t, step=step, label="mics", marker="o")
 
     if title:
         ax.set_title(title)
@@ -176,18 +198,32 @@ def _extract_positions(entity: Source | MicrophoneArray | Tensor | Sequence, ax:
     return pos
 
 
-def _scatter_positions(ax: Any, positions: Tensor, *, label: str, marker: str) -> None:
+def _scatter_positions(
+    ax: Any,
+    positions: Tensor,
+    *,
+    label: str,
+    marker: str,
+    color: Optional[str] = None,
+) -> None:
     """Scatter-plot positions in 2D or 3D."""
     if positions.numel() == 0:
         return
     dim = positions.shape[1]
     if dim == 2:
-        ax.scatter(positions[:, 0], positions[:, 1], label=label, marker=marker)
+        ax.scatter(positions[:, 0], positions[:, 1], label=label, marker=marker, color=color)
     else:
-        ax.scatter(positions[:, 0], positions[:, 1], positions[:, 2], label=label, marker=marker)
+        ax.scatter(
+            positions[:, 0],
+            positions[:, 1],
+            positions[:, 2],
+            label=label,
+            marker=marker,
+            color=color,
+        )
 
 
-def _as_trajectory(traj: Tensor | Sequence, ax: Any | None) -> Tensor:
+def _as_trajectory(traj: Tensor | Sequence) -> Tensor:
     """Validate and normalize a trajectory tensor."""
     traj = as_tensor(traj)
     if traj.ndim != 3:
@@ -195,16 +231,73 @@ def _as_trajectory(traj: Tensor | Sequence, ax: Any | None) -> Tensor:
     return traj
 
 
-def _plot_trajectories(ax: Any, traj: Tensor, *, step: int, label: str) -> None:
-    """Plot trajectories for each entity."""
+def _plot_entity(
+    ax: Any,
+    traj: Tensor,
+    positions: Tensor,
+    *,
+    step: int,
+    label: str,
+    marker: str,
+) -> None:
+    """Plot trajectories and/or static positions with a unified legend entry."""
     if traj.numel() == 0:
         return
-    dim = traj.shape[2]
-    if dim == 2:
-        for idx in range(traj.shape[1]):
-            xy = traj[::step, idx]
-            ax.plot(xy[:, 0], xy[:, 1], label=f"{label} {idx}")
+    import matplotlib.pyplot as plt
+
+    if positions.shape != traj.shape[1:]:
+        positions = traj[0]
+    moving = _is_moving(traj, positions)
+    colors = plt.rcParams.get("axes.prop_cycle", None)
+    if colors is not None:
+        palette = colors.by_key().get("color", [])
     else:
-        for idx in range(traj.shape[1]):
-            xyz = traj[::step, idx]
-            ax.plot(xyz[:, 0], xyz[:, 1], xyz[:, 2], label=f"{label} {idx}")
+        palette = []
+    if not palette:
+        palette = ["C0", "C1", "C2", "C3", "C4", "C5"]
+
+    dim = traj.shape[2]
+    for idx in range(traj.shape[1]):
+        color = palette[idx % len(palette)]
+        lbl = label if idx == 0 else "_nolegend_"
+        if moving:
+            if dim == 2:
+                xy = traj[::step, idx]
+                ax.plot(
+                    xy[:, 0],
+                    xy[:, 1],
+                    label=lbl,
+                    color=color,
+                    marker=marker,
+                    markevery=[0],
+                )
+            else:
+                xyz = traj[::step, idx]
+                ax.plot(
+                    xyz[:, 0],
+                    xyz[:, 1],
+                    xyz[:, 2],
+                    label=lbl,
+                    color=color,
+                    marker=marker,
+                    markevery=[0],
+                )
+        pos = positions[idx : idx + 1]
+        _scatter_positions(ax, pos, label="_nolegend_", marker=marker, color=color)
+    if not moving:
+        # ensure legend marker uses the group label
+        _scatter_positions(
+            ax,
+            positions[:1],
+            label=label,
+            marker=marker,
+            color=palette[0],
+        )
+
+
+def _is_moving(traj: Tensor, positions: Tensor, *, tol: float = 1e-6) -> bool:
+    """Return True if any trajectory deviates from the provided positions."""
+    if traj.numel() == 0:
+        return False
+    pos0 = positions.unsqueeze(0).expand_as(traj)
+    return torch.any(torch.linalg.norm(traj - pos0, dim=-1) > tol).item()

torchrir/plotting_utils.py

@@ -26,6 +26,8 @@ def plot_scene_and_save(
 ) -> tuple[list[Path], list[Path]]:
     """Plot static and dynamic scenes and save images to disk.
 
+    Dynamic plots show trajectories for moving entities and points for fixed ones.
+
     Args:
         out_dir: Output directory for PNGs.
         room: Room size tensor or sequence.
@@ -41,6 +43,17 @@ def plot_scene_and_save(
 
     Returns:
         Tuple of (static_paths, dynamic_paths).
+
+    Example:
+        >>> plot_scene_and_save(
+        ...     out_dir=Path("outputs"),
+        ...     room=[6.0, 4.0, 3.0],
+        ...     sources=[[1.0, 2.0, 1.5]],
+        ...     mics=[[2.0, 2.0, 1.5]],
+        ...     src_traj=src_traj,
+        ...     mic_traj=mic_traj,
+        ...     prefix="scene",
+        ... )
     """
     out_dir = Path(out_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
@@ -85,11 +98,12 @@ def plot_scene_and_save(
                 room=view_room,
                 src_traj=view_src_traj,
                 mic_traj=view_mic_traj,
+                src_pos=view_src,
+                mic_pos=view_mic,
                 step=step,
                 title=f"Room scene ({view_dim}D trajectories)",
                 show=False,
             )
-            _overlay_positions(ax, view_src, view_mic)
             dynamic_path = out_dir / f"{prefix}_dynamic_{view_dim}d.png"
             _save_axes(ax, dynamic_path, show=show)
             dynamic_paths.append(dynamic_path)
@@ -142,32 +156,3 @@ def _save_axes(ax: Any, path: Path, *, show: bool) -> None:
     if show:
         plt.show()
     plt.close(fig)
-
-
-def _overlay_positions(ax: Any, sources: torch.Tensor, mics: torch.Tensor) -> None:
-    """Overlay static source and mic positions on an axis."""
-    if sources.numel() > 0:
-        if sources.shape[1] == 2:
-            ax.scatter(sources[:, 0], sources[:, 1], marker="^", label="sources", color="tab:green")
-        else:
-            ax.scatter(
-                sources[:, 0],
-                sources[:, 1],
-                sources[:, 2],
-                marker="^",
-                label="sources",
-                color="tab:green",
-            )
-    if mics.numel() > 0:
-        if mics.shape[1] == 2:
-            ax.scatter(mics[:, 0], mics[:, 1], marker="o", label="mics", color="tab:orange")
-        else:
-            ax.scatter(
-                mics[:, 0],
-                mics[:, 1],
-                mics[:, 2],
-                marker="o",
-                label="mics",
-                color="tab:orange",
-            )
-    ax.legend(loc="best")

torchrir/results.py

@@ -13,7 +13,13 @@ from .scene import Scene
 
 @dataclass(frozen=True)
 class RIRResult:
-    """Container for RIRs with metadata."""
+    """Container for RIRs with metadata.
+
+    Example:
+        >>> from torchrir import ISMSimulator
+        >>> result = ISMSimulator().simulate(scene, config)
+        >>> rirs = result.rirs
+    """
 
     rirs: Tensor
     scene: Scene

torchrir/room.py

@@ -13,7 +13,11 @@ from .utils import as_tensor, ensure_dim
 
 @dataclass(frozen=True)
 class Room:
-    """Room geometry and acoustic parameters."""
+    """Room geometry and acoustic parameters.
+
+    Example:
+        >>> room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+    """
 
     size: Tensor
     fs: float
@@ -43,7 +47,11 @@ class Room:
         device: Optional[torch.device | str] = None,
         dtype: Optional[torch.dtype] = None,
     ) -> "Room":
-        """Create a rectangular (shoebox) room."""
+        """Create a rectangular (shoebox) room.
+
+        Example:
+            >>> room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+        """
         size_t = as_tensor(size, device=device, dtype=dtype)
         size_t = ensure_dim(size_t)
         beta_t = None
@@ -54,7 +62,11 @@ class Room:
 
 @dataclass(frozen=True)
 class Source:
-    """Source container with positions and optional orientation."""
+    """Source container with positions and optional orientation.
+
+    Example:
+        >>> sources = Source.positions([[1.0, 2.0, 1.5]])
+    """
 
     positions: Tensor
     orientation: Optional[Tensor] = None
@@ -79,7 +91,11 @@ class Source:
         device: Optional[torch.device | str] = None,
         dtype: Optional[torch.dtype] = None,
     ) -> "Source":
-        """Construct a Source from positions."""
+        """Construct a Source from positions.
+
+        Example:
+            >>> sources = Source.positions([[1.0, 2.0, 1.5]])
+        """
         return cls.from_positions(
             positions, orientation=orientation, device=device, dtype=dtype
         )
@@ -103,7 +119,11 @@ class Source:
 
 @dataclass(frozen=True)
 class MicrophoneArray:
-    """Microphone array container."""
+    """Microphone array container.
+
+    Example:
+        >>> mics = MicrophoneArray.positions([[2.0, 2.0, 1.5]])
+    """
 
     positions: Tensor
     orientation: Optional[Tensor] = None
@@ -128,7 +148,11 @@ class MicrophoneArray:
         device: Optional[torch.device | str] = None,
         dtype: Optional[torch.dtype] = None,
     ) -> "MicrophoneArray":
-        """Construct a MicrophoneArray from positions."""
+        """Construct a MicrophoneArray from positions.
+
+        Example:
+            >>> mics = MicrophoneArray.positions([[2.0, 2.0, 1.5]])
+        """
         return cls.from_positions(
             positions, orientation=orientation, device=device, dtype=dtype
         )

torchrir/scene.py

@@ -13,7 +13,12 @@ from .room import MicrophoneArray, Room, Source
 
 @dataclass(frozen=True)
 class Scene:
-    """Container for room, sources, microphones, and optional trajectories."""
+    """Container for room, sources, microphones, and optional trajectories.
+
+    Example:
+        >>> scene = Scene(room=room, sources=sources, mics=mics, src_traj=src_traj, mic_traj=mic_traj)
+        >>> scene.validate()
+    """
 
     room: Room
     sources: Source

torchrir/scene_utils.py

@@ -15,7 +15,13 @@ def sample_positions(
     rng: random.Random,
     margin: float = 0.5,
 ) -> torch.Tensor:
-    """Sample random positions within a room with a safety margin."""
+    """Sample random positions within a room with a safety margin.
+
+    Example:
+        >>> rng = random.Random(0)
+        >>> room = torch.tensor([6.0, 4.0, 3.0])
+        >>> positions = sample_positions(num=2, room_size=room, rng=rng)
+    """
     dim = room_size.numel()
     low = [margin] * dim
     high = [float(room_size[i].item()) - margin for i in range(dim)]
@@ -27,7 +33,11 @@ def sample_positions(
 
 
 def linear_trajectory(start: torch.Tensor, end: torch.Tensor, steps: int) -> torch.Tensor:
-    """Create a linear trajectory between start and end."""
+    """Create a linear trajectory between start and end.
+
+    Example:
+        >>> traj = linear_trajectory(torch.tensor([1.0, 1.0, 1.0]), torch.tensor([4.0, 2.0, 1.0]), 8)
+    """
     return torch.stack(
         [start + (end - start) * t / (steps - 1) for t in range(steps)],
         dim=0,
@@ -35,7 +45,11 @@ def linear_trajectory(start: torch.Tensor, end: torch.Tensor, steps: int) -> tor
 
 
 def binaural_mic_positions(center: torch.Tensor, offset: float = 0.08) -> torch.Tensor:
-    """Create a two-mic binaural layout around a center point."""
+    """Create a two-mic binaural layout around a center point.
+
+    Example:
+        >>> mics = binaural_mic_positions(torch.tensor([2.0, 2.0, 1.5]))
+    """
     dim = center.numel()
     offset_vec = torch.zeros((dim,), dtype=torch.float32)
     offset_vec[0] = offset
@@ -45,7 +59,11 @@ def binaural_mic_positions(center: torch.Tensor, offset: float = 0.08) -> torch.
 
 
 def clamp_positions(positions: torch.Tensor, room_size: torch.Tensor, margin: float = 0.1) -> torch.Tensor:
-    """Clamp positions to remain inside the room with a margin."""
+    """Clamp positions to remain inside the room with a margin.
+
+    Example:
+        >>> clamped = clamp_positions(positions, torch.tensor([6.0, 4.0, 3.0]))
+    """
     min_v = torch.full_like(room_size, margin)
     max_v = room_size - margin
     return torch.max(torch.min(positions, max_v), min_v)

torchrir/signal.py

@@ -21,6 +21,9 @@ def fft_convolve(signal: Tensor, rir: Tensor) -> Tensor:
 
     Returns:
         1D tensor of length len(signal) + len(rir) - 1.
+
+    Example:
+        >>> y = fft_convolve(signal, rir)
     """
     if signal.ndim != 1 or rir.ndim != 1:
         raise ValueError("fft_convolve expects 1D tensors")
@@ -41,6 +44,9 @@ def convolve_rir(signal: Tensor, rirs: Tensor) -> Tensor:
 
     Returns:
         (n_mic, n_samples + rir_len - 1) tensor or 1D for single mic.
+
+    Example:
+        >>> y = convolve_rir(signal, rirs)
     """
     signal = _ensure_signal(signal)
     rirs = _ensure_static_rirs(rirs)

torchrir/simulators.py

@@ -24,7 +24,11 @@ class RIRSimulator(Protocol):
 
 @dataclass(frozen=True)
 class ISMSimulator:
-    """ISM-based simulator using the current core implementation."""
+    """ISM-based simulator using the current core implementation.
+
+    Example:
+        >>> result = ISMSimulator().simulate(scene, config)
+    """
 
     def simulate(self, scene: Scene, config: SimulationConfig | None = None) -> RIRResult:
         scene.validate()

torchrir/utils.py

@@ -41,6 +41,9 @@ def resolve_device(
     """Resolve a device string (including 'auto') into a torch.device.
 
     Falls back to CPU when the requested backend is unavailable.
+
+    Example:
+        >>> device = resolve_device("auto")
     """
     if device is None:
         return torch.device("cpu")
@@ -76,7 +79,12 @@ def resolve_device(
 
 @dataclass(frozen=True)
 class DeviceSpec:
-    """Resolve device + dtype defaults consistently."""
+    """Resolve device + dtype defaults consistently.
+
+    Example:
+        >>> spec = DeviceSpec(device="auto", dtype=torch.float32)
+        >>> device, dtype = spec.resolve(tensor)
+    """
 
     device: Optional[torch.device | str] = None
     dtype: Optional[torch.dtype] = None
@@ -140,7 +148,11 @@ def estimate_beta_from_t60(
     device: Optional[torch.device | str] = None,
     dtype: Optional[torch.dtype] = None,
 ) -> Tensor:
-    """Estimate reflection coefficients from T60 using Sabine's formula."""
+    """Estimate reflection coefficients from T60 using Sabine's formula.
+
+    Example:
+        >>> beta = estimate_beta_from_t60(torch.tensor([6.0, 4.0, 3.0]), t60=0.4)
+    """
     if t60 <= 0:
         raise ValueError("t60 must be positive")
     size = as_tensor(size, device=device, dtype=dtype)
@@ -172,7 +184,11 @@ def estimate_t60_from_beta(
     device: Optional[torch.device | str] = None,
     dtype: Optional[torch.dtype] = None,
 ) -> float:
-    """Estimate T60 from reflection coefficients using Sabine's formula."""
+    """Estimate T60 from reflection coefficients using Sabine's formula.
+
+    Example:
+        >>> t60 = estimate_t60_from_beta(torch.tensor([6.0, 4.0, 3.0]), beta=torch.full((6,), 0.9))
+    """
     size = as_tensor(size, device=device, dtype=dtype)
     size = ensure_dim(size)
     beta = as_tensor(beta, device=size.device, dtype=size.dtype)
@@ -244,7 +260,11 @@ def orientation_to_unit(orientation: Tensor, dim: int) -> Tensor:
 
 
 def att2t_sabine_estimation(att_db: float, t60: float) -> float:
-    """Convert attenuation (dB) to time based on T60."""
+    """Convert attenuation (dB) to time based on T60.
+
+    Example:
+        >>> t = att2t_sabine_estimation(att_db=60.0, t60=0.4)
+    """
     if t60 <= 0:
         raise ValueError("t60 must be positive")
     if att_db <= 0:
@@ -253,17 +273,29 @@ def att2t_sabine_estimation(att_db: float, t60: float) -> float:
 
 
 def att2t_SabineEstimation(att_db: float, t60: float) -> float:
-    """Legacy alias for att2t_sabine_estimation."""
+    """Legacy alias for att2t_sabine_estimation.
+
+    Example:
+        >>> t = att2t_SabineEstimation(att_db=60.0, t60=0.4)
+    """
     return att2t_sabine_estimation(att_db, t60)
 
 
 def beta_SabineEstimation(room_size: Tensor, t60: float) -> Tensor:
-    """Legacy alias for estimate_beta_from_t60."""
+    """Legacy alias for estimate_beta_from_t60.
+
+    Example:
+        >>> beta = beta_SabineEstimation(torch.tensor([6.0, 4.0, 3.0]), t60=0.4)
+    """
     return estimate_beta_from_t60(room_size, t60)
 
 
 def t2n(tmax: float, room_size: Tensor, c: float = _DEF_SPEED_OF_SOUND) -> Tensor:
-    """Estimate image counts per dimension needed to cover tmax."""
+    """Estimate image counts per dimension needed to cover tmax.
+
+    Example:
+        >>> nb_img = t2n(0.3, torch.tensor([6.0, 4.0, 3.0]))
+    """
     if tmax <= 0:
         raise ValueError("tmax must be positive")
     size = as_tensor(room_size)

{torchrir-0.1.0.dist-info → torchrir-0.1.2.dist-info}/METADATA

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: torchrir
-Version: 0.1.0
-Summary: Add your description here
+Version: 0.1.2
+Summary: PyTorch-based room impulse response (RIR) simulation toolkit for static and dynamic scenes.
+Project-URL: Repository, https://github.com/taishi-n/torchrir
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -18,6 +19,22 @@ This project has been substantially assisted by AI using Codex.
 ## License
 Apache-2.0. See `LICENSE` and `NOTICE`.
 
+## Installation
+```bash
+pip install torchrir
+```
+
+## Current Capabilities
+- ISM-based static and dynamic RIR simulation (2D/3D shoebox rooms).
+- Directivity patterns: `omni`, `cardioid`, `hypercardioid`, `subcardioid`, `bidir` with orientation handling.
+- Acoustic parameters: `beta` or `t60` (Sabine), optional diffuse tail via `tdiff`.
+- Dynamic convolution via `DynamicConvolver` (`trajectory` or `hop` modes).
+- GPU acceleration for ISM accumulation (CUDA/MPS; MPS disables LUT).
+- Dataset utilities with CMU ARCTIC support and example pipelines.
+- Plotting utilities for static and dynamic scenes.
+- Metadata export helpers for time axis, DOA, and array attributes (JSON-ready).
+- Unified CLI with JSON/YAML config and deterministic flag support.
+
 ## Example Usage
 ```bash
 # CMU ARCTIC + static RIR (fixed sources/mics)
@@ -26,16 +43,22 @@ uv run python examples/static.py --plot
 # Dynamic RIR demos
 uv run python examples/dynamic_mic.py --plot
 uv run python examples/dynamic_src.py --plot
+uv run python examples/dynamic_mic.py --gif
+uv run python examples/dynamic_src.py --gif
 
 # Unified CLI
 uv run python examples/cli.py --mode static --plot
 uv run python examples/cli.py --mode dynamic_mic --plot
 uv run python examples/cli.py --mode dynamic_src --plot
+uv run python examples/cli.py --mode dynamic_mic --gif
+uv run python examples/dynamic_mic.py --gif --gif-fps 12
 
 # Config + deterministic
 uv run python examples/cli.py --mode static --deterministic --seed 123 --config-out outputs/cli.json
 uv run python examples/cli.py --config-in outputs/cli.json
 ```
+GIF FPS is auto-derived from signal duration and RIR steps unless overridden with `--gif-fps`.
+For 3D rooms, an additional `*_3d.gif` is saved.
 YAML configs are supported when `PyYAML` is installed.
 ```bash
 # YAML config
@@ -43,6 +66,24 @@ uv run python examples/cli.py --mode static --config-out outputs/cli.yaml
 uv run python examples/cli.py --config-in outputs/cli.yaml
 ```
 `examples/cli_example.yaml` provides a ready-to-use template.
+Examples also save `*_metadata.json` alongside audio outputs.
+
+```python
+from torchrir import DynamicConvolver, MicrophoneArray, Room, Source, simulate_rir
+
+room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+sources = Source.positions([[1.0, 2.0, 1.5]])
+mics = MicrophoneArray.positions([[2.0, 2.0, 1.5]])
+
+rir = simulate_rir(
+    room=room,
+    sources=sources,
+    mics=mics,
+    max_order=6,
+    tmax=0.3,
+    device="auto",
+)
+```
 
 ```python
 from torchrir import DynamicConvolver
@@ -55,6 +96,20 @@ y = DynamicConvolver(mode="hop", hop=1024).convolve(signal, rirs)
 ```
 Dynamic convolution is exposed via `DynamicConvolver` only (no legacy function wrappers).
 
+## Limitations and Potential Errors
+- Ray tracing and FDTD simulators are placeholders and raise `NotImplementedError`.
+- `TemplateDataset` methods are not implemented and will raise `NotImplementedError`.
+- `simulate_rir`/`simulate_dynamic_rir` require `max_order` (or `SimulationConfig.max_order`) and either `nsample` or `tmax`.
+- Non-`omni` directivity requires orientation; mismatched shapes raise `ValueError`.
+- `beta` must have 4 (2D) or 6 (3D) elements; invalid sizes raise `ValueError`.
+- `simulate_dynamic_rir` requires `src_traj` and `mic_traj` to have matching time steps.
+- Dynamic simulation currently loops per time step; very long trajectories can be slow.
+- MPS disables the sinc LUT path (falls back to direct sinc), which can be slower and slightly different numerically.
+- Deterministic mode is best-effort; some backends may still be non-deterministic.
+- YAML configs require `PyYAML`; otherwise a `ModuleNotFoundError` is raised.
+- CMU ARCTIC downloads require network access.
+- GIF animation output requires Pillow (via matplotlib animation writer).
+
 ### Dataset-agnostic utilities
 ```python
 from torchrir import (
@@ -129,6 +184,7 @@ device, dtype = DeviceSpec(device="auto").resolve()
 
 ## References
 - [gpuRIR](https://github.com/DavidDiazGuerra/gpuRIR)
+- [Cross3D](https://github.com/DavidDiazGuerra/Cross3D)
 - [pyroomacoustics](https://github.com/LCAV/pyroomacoustics)
 - [das-generator](https://github.com/ehabets/das-generator)
 - [rir-generator](https://github.com/audiolabs/rir-generator)
@@ -211,3 +267,5 @@ y = DynamicConvolver(mode="trajectory").convolve(signal, rirs)
 - FDTD backend: implement `FDTDSimulator` with configurable grid resolution and boundary conditions.
 - Dataset expansion: add additional dataset integrations beyond CMU ARCTIC (see `TemplateDataset`).
 - Enhanced acoustics: frequency-dependent absorption and more advanced diffuse tail models.
+- Add microphone and source directivity models similar to gpuRIR/pyroomacoustics.
+- Add regression tests comparing generated RIRs against gpuRIR outputs.