8. Referencia de Backend y API Core ​

Para los desarrolladores o técnicos que quieran entender las entrañas de los scripts de Python del backend de simulación, aquí proveemos una guía de referencias para los métodos más esenciales del Roomwaves.Builder.

8.1. Clase Base: AcousticPipeline ​

Se comporta como el controlador de orquestación, aglutinando la matriz FEM y los módulos de cálculo posterior.

Inicializador Principal ​

python
AcousticPipeline(mesh_path: str, fs: int = 48000, c: float = 343.0)
  • mesh_path: Ruta absoluta al modelo volumétrico de malla.
  • fs: Frecuencia de muestreo destino (48 kHz o superior) para los archivos .wav de RIR generados.
  • c: La velocidad física del sonido en la sala.

load_geometry_and_tags() ​

Este método lee y levanta todo el Mesh usando FEniCSx. Asigna e indexa los identificadores geométricos (physical_group_id) y prepara los Espacios Funcionales base para el sistema continuo de Galerkin.

run_fem_solver(f_min, f_max, df) ​

El devorador de procesador. Inicia la iteración de tonos, configurando el solver de subespacio de Krylov (GMRES) acoplado con ILU.

  • Retorna un Vector o Tensor con el campo de presiones complejas P(f) para cada salto espectral df.

8.2. Módulo de Capa de Material: Materials ​

Modelos y MaterialDict ​

Usamos Pydantic para proteger la integridad de las peticiones REST. Garantiza que las propiedades físicas ingresadas de un material (como espesor d en metros) sean validadas antes de tocar el solver C++ de fondo, mapeándolas por su ID geométrico.

calculate_miki_impedance(sigma, d, f) ​

Método vectorizado sobre NumPy.

  • sigma: Resistividad al flujo (Rayls/m).
  • f: El eje de frecuencias a estudiar.
  • Devuelve la curva paramétrica (valores complejos) de la admitancia en la frontera para la construcción de matrices Robin dinámicas.

8.3. Motor de Crossover: CrossoverEngine ​

align_energy_bands(ir_low, ir_high, band) ​

Toma el vector de bajas frecuencias y el vector computado de la acústica geométrica. Calcula las áreas de las densidades de energía de ambos en el margen band y devuelve la ganancia (escala de volumen) requerida para unirlos lógicamente en dB.

apply_hann_crossover(spec_low, spec_high, cross_freq_range) ​

Ejecuta la interpolación y el enmascaramiento con pesos sinusoidales suaves, garantizando continuidad asintótica entre regímenes.

8.4. Errores Recurrentes Manejados ​

  • ConvergenceError (PETSc) Salta cuando la habitación no pudo llegar a tolerancia por GMRES. Se detona habitualmente si el diseño no es estanco (falla de watertight de las mallas que manda el cliente Web).
  • LundebyConvergenceWarning Ocurre en la extracción de ruido de fondo. Significa que Roomwaves encontró el EDC pero fue incapaz de identificar en qué bloque paraba de decaer el sonido y se mezclaba con la "estática digital". Usualmente implica una sala muerta (sorda) con tiempo de reverberación bajísimo, requiriendo intervención algorítmica de fallback.