Workflows

This page describes the current class-based DEISM workflow and the main ordering differences between shoebox and convex rooms.

Shared structure

Both workflows start from the same high-level pattern:

1. Create DEISM(mode, roomtype).

2. Update room geometry.

3. Update wall materials.

4. Update frequency-dependent state.

5. Update source/receiver geometry and directivities.

6. Run run_DEISM().

The key detail is that steps 5 and 6 are not ordered identically for all room types.

Hard versus flexible ordering

The documentation should be read with three categories in mind:

• Hard prerequisite: the later method depends directly on data produced by the earlier one.

• Recommended order: the sequence used in the examples for readability.

• Order-flexible: both methods must be run before execution, but neither is a prerequisite for the other.

Hard prerequisites shared by both room types

• update_room() should precede update_wall_materials() when material conversion depends on room volume and room areas.

• update_wall_materials() should precede update_freqs() because frequency updates interpolate materials and, in RIR mode, use reverberationTime.

• update_freqs() should precede update_directivities() because loaded directivity data is checked against params["freqs"], and receiver normalization depends on frequency-derived terms.

Shoebox workflow

After update_freqs(), the shoebox workflow becomes more flexible:

• update_directivities() and update_source_receiver() can be called in either order.

• Both still need to be completed before run_DEISM().

• The recommended example order is directivities first, then source/receiver update, because that is how the current class-based examples are written.

        flowchart TD
    A["Initialize: DEISM(mode, 'shoebox')"] --> B["update_room()"]
    B --> C["update_wall_materials()"]
    C --> D["update_freqs()"]
    D --> E["update_directivities()"]
    D --> F["update_source_receiver()"]
    E --> G["run_DEISM()"]
    F --> G
    E -. "order-flexible after update_freqs()" .- F
    

Recommended shoebox execution order

import numpy as np
from deism.core_deism import DEISM

deism = DEISM("RIR", "shoebox")
deism.update_room(roomDimensions=np.array([10.0, 8.0, 2.5]))
deism.update_wall_materials(datain=1.0, datatype="reverberationTime")
deism.params["sampleRate"] = 48000
deism.params["reverberationTime"] = 1.0
deism.update_freqs()
deism.update_directivities()
deism.update_source_receiver()
deism.run_DEISM()

Convex workflow

Convex-room execution is stricter:

• update_freqs() builds the convex room engine used later by the ARG path.

• update_source_receiver() computes image paths and reflection_matrix.

• update_directivities() for ARG source directivity uses that reflection state.

As a result, the convex order is:

update_room() -> update_wall_materials() -> update_freqs() -> update_source_receiver() -> update_directivities() -> run_DEISM().

        flowchart TD
    A["Initialize: DEISM(mode, 'convex')"] --> B["update_room() / set vertices"]
    B --> C["update_wall_materials()"]
    C --> D["update_freqs()"]
    D --> E["Build convex room engine"]
    E --> F["update_source_receiver()"]
    F --> I["images / reflection_matrix ready"]
    I --> G["update_directivities()"]
    G --> H["run_DEISM()"]
    

Recommended convex execution order

import numpy as np
from deism.core_deism import DEISM
from deism.core_deism_arg import find_wall_centers

vertices = np.array(
    [
        [0.0, 0.0, 0.0],
        [0.0, 0.0, 3.5],
        [0.0, 3.0, 2.5],
        [0.0, 3.0, 0.0],
        [4.0, 0.0, 0.0],
        [4.0, 0.0, 3.5],
        [4.0, 3.0, 2.5],
        [4.0, 3.0, 0.0],
    ]
)

deism = DEISM("RIR", "convex")
deism.update_room(roomDimensions=vertices, wallCenters=find_wall_centers(vertices))
deism.update_wall_materials()
deism.update_freqs()
deism.update_source_receiver()
deism.update_directivities()
deism.run_DEISM()

Backends

• run_DEISM() uses the Numba backend by default.

• run_DEISM_ray() is still available, but it should be treated as a legacy backend.

Best practices

• Treat geometry, materials, and frequency state as the shared prerequisite chain.

• For shoebox rooms, changing only source or receiver position usually means rerunning update_source_receiver() rather than rebuilding the full state.

• For convex rooms, any change that affects geometry, frequencies, or positions should be treated more conservatively because image and reflection-path state is coupled to later ARG directivity setup.

• If you run run_DEISM(if_clean_up=True), large image arrays are deleted after the computation. If you need them again, rerun update_source_receiver().