IR collections
An IR collection is a DataFrame-backed view of impulse responses and their metadata. It lets you treat many source-receiver IRs as rows in a dataset while keeping the larger audio payloads available through the SDK data-loading layer.
Focused task examples are covered in the IR collections how-to and a complete end-to-end workflow is covered in the IR collections tutorial.
Collection model
Each row in an IR collection represents one impulse response for a source-receiver configuration. The row stores identifiers, locations, simulation metadata, optional device-rendering metadata, and any custom columns you add for analysis or dataset construction.
The collection is backed by a Polars DataFrame. DataFrame-backed metadata gives you columnar filtering, sorting, sampling, joins, and persistence without requiring IR audio files to be present locally.
Metadata and audio data
IR collection metadata and IR audio data have different lifecycles. Metadata is compact and can be saved as .parquet files. Audio data is larger and may live in cloud storage until an IRDataLoader fetches it for a local workflow.
This separation lets you inspect and transform a collection before downloading audio. It also lets you store reproducible dataset definitions without duplicating the underlying IR files.
The metadata-first design keeps saved collection files small, supports on-demand access to cloud-backed simulation results, and lets the SDK manage local audio caching. The metadata file acts as the dataset definition, while the cache contains downloaded audio for the workflows that have requested it.
Supported IR collection file formats include .parquet, .csv, .ndjson, .json, .ipc, and .arrow.
System columns
Several columns define the minimum identity and reconstruction information for a collection:
| Column | Role |
|---|---|
id | Identifies one IR collection row. |
source_id | Links the row to a source. |
receiver_id | Links the row to a receiver. |
simulation_id | Links the row to the simulation that produced the IR. |
simulation_type | Records the simulation type used for the IR. |
Custom columns can store derived values such as source-receiver distance, line-of-sight flags, acoustic parameters, data splits, or task-specific labels. System columns must remain available so the SDK can reconstruct IRInfo objects and resolve associated simulation data.
IRInfo objects
IRInfo is the row-level object exposed when you index or iterate over an IR collection. It connects DataFrame row values with structured SDK objects such as the source, receiver, simulation, device metadata, and IR access methods.
This row object is useful when metadata depends on both structured SDK objects and DataFrame values. For example, a computed metadata column may use source and receiver positions from IRInfo, then store the result back into the collection DataFrame.
Data loading and caching
IRDataLoader resolves IR audio data from collection rows. In lazy loading mode, the loader fetches an IR when code requests it and writes the result to the configured cache directory. In eager loading mode, the loader can fetch a collection subset before iteration begins.
The SDK exposes these data-loading modes:
| Mode | Behavior |
|---|---|
lazy | Fetches IR audio when code requests it, then stores it in the configured cache directory. This is the default mode. |
eager | Fetches the collection subset before iteration begins, then stores the audio data in the configured cache directory. |
lazy_no_cache | Fetches IR audio on demand without storing it locally. Repeated access may require repeated downloads, so this mode is not recommended for iterative workflows. |
Generated h5 files are internal SDK artifacts. Don't open, read, parse, or depend on these files directly in user code. Use collection access methods such as get_mono_ir(), get_spatial_ir(), get_device_ir(), and get_moving_ir() to retrieve IR audio through the supported interface.
Simulation and device collections
Simulation collections and IR collections represent different levels of granularity. A simulation collection groups simulations. Converting it to an IR collection expands completed simulations into source-receiver IR rows.
Device-rendered IR collections extend the same row model with device-specific metadata, such as the device and orientation used for rendering. This keeps device IR workflows compatible with filtering, metadata persistence, and data-loader-based access.