DO NOT SQUASH: PML Refactoring by ruansava · Pull Request #328 · NDF-Poli-USP/spyro

ruansava · 2026-07-13T22:51:59Z

This pull request refactors and improves the PML module by renaming files, updating class and function names, improving code style, and documentation.

@Olender

commit 5647299 Author: ruansava <ruansava@gmail.com> Date: Mon Jun 22 16:13:35 2026 -0300 Update test_eikonal.py commit 1c6503b Author: ruansava <ruansava@gmail.com> Date: Mon Jun 22 13:04:28 2026 -0300 Fix firedrake imports and boundary sampling Fix firedrake imports and boundary sampling commit b6d937a Author: ruansava <ruansava@gmail.com> Date: Mon Jun 22 12:14:41 2026 -0300 Update meshing_habc.py commit 2e5adee Author: ruansava <ruansava@gmail.com> Date: Mon Jun 22 12:11:11 2026 -0300 Update test_habc_tools.py commit 37b7a97 Merge: b37e332 288b915 Author: ruansava <ruansava@gmail.com> Date: Mon Jun 22 11:58:32 2026 -0300 Merge branch 'main' into ruben/abc_refactoring commit 288b915 Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Sun Jun 21 16:39:38 2026 -0300 Release firedrake (2026.4.0) version (#307) * API fix * remove warnings and lint * add stifness quadrature * modifying only the dt * update to 2026 * remove duplicated test * faster run * adding older firedrake marker * marking tests * Adding docker option to use newer version (defaults to 2025.4.2) * fixing conftest * added new firedrake tag * added version checking --------- Co-authored-by: Olender <olender@usp.br> commit b37e332 Author: ruansava <ruansava@gmail.com> Date: Fri Jun 19 18:43:30 2026 -0300 Mark 3D test parameters as slow Mark 3D test parameters as slow commit b3e0ac6 Author: ruansava <ruansava@gmail.com> Date: Fri Jun 19 18:09:35 2026 -0300 Mark slow tests and tidy imports Mark expensive 3D test parametrizations as slow and clean up unused imports. commit 48f7e5e Author: ruansava <ruansava@gmail.com> Date: Fri Jun 19 15:00:29 2026 -0300 Refactor HABC and hypershape handling Refactor HABC and hypershape handling commit 9a63be5 Merge: ad64a4b 43f66b4 Author: ruansava <ruansava@gmail.com> Date: Fri Jun 19 14:51:29 2026 -0300 Merge branch 'main' into ruben/abc_refactoring commit 43f66b4 Author: Romildo Junior <89819318+rasjr1305@users.noreply.github.com> Date: Thu Jun 18 15:39:00 2026 -0300 New native hdf5 converter (#311) * Added new io functions * Added Tests for new io functions * Apply suggestion from @Olender Co-authored-by: Alexandre Olender <45005909+Olender@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Alexandre Olender <45005909+Olender@users.noreply.github.com> * Update test_io_hdf5.py * Fixed tests * Added 2d Binary read and write --------- Co-authored-by: Alexandre Olender <45005909+Olender@users.noreply.github.com> commit f2ec691 Merge: 9b44b69 025e10f Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Wed Jun 17 10:50:03 2026 -0300 Merge pull request #310 from NDF-Poli-USP/dolci/fwi_wave_inheritance DO NOT SQUASH: FWI wave inheritance commit ad64a4b Author: ruansava <ruansava@gmail.com> Date: Mon Jun 15 12:38:47 2026 -0300 Remove unused typing import and fix test string Remove unused typing import and fix test string commit 7a73b16 Author: ruansava <ruansava@gmail.com> Date: Mon Jun 15 12:35:09 2026 -0300 Use HyperLayerDegreeType and fix imports Use HyperLayerDegreeType and fix imports commit 1ebcba0 Author: ruansava <ruansava@gmail.com> Date: Mon Jun 15 12:08:39 2026 -0300 Use enums for ABC config Use enums for ABC config commit 9d05355 Author: ruansava <ruansava@gmail.com> Date: Thu Jun 11 22:57:04 2026 -0300 Add enums for layer reference frequency and degree Add enums for layer reference frequency and degree commit e184f93 Author: ruansava <ruansava@gmail.com> Date: Thu Jun 11 22:33:13 2026 -0300 Standardize docstrings and type annotations Normalize and clarify documentation across ABC, HABC, meshing, and IO modules: convert docstrings to triple-double quotes, standardize punctuation, and improve type annotations. commit dff787a Author: ruansava <ruansava@gmail.com> Date: Thu Jun 11 14:20:35 2026 -0300 Update eikonal_eq.py commit 89183bd Author: ruansava <ruansava@gmail.com> Date: Thu Jun 11 14:03:59 2026 -0300 Standardize docstrings and imports across modules Standardize docstrings and imports across modules commit d3f0e6f Author: ruansava <ruansava@gmail.com> Date: Thu Jun 11 13:27:57 2026 -0300 Improve docs, validation, and R² tests Refactor docs and small behaviors across utilities; add validation and tests for R² computation. commit 214190b Author: ruansava <ruansava@gmail.com> Date: Wed Jun 10 19:37:41 2026 -0300 Update error_management.py commit e487034 Author: ruansava <ruansava@gmail.com> Date: Wed Jun 10 19:31:10 2026 -0300 Update test_modal_solvers.py commit be3dace Author: ruansava <ruansava@gmail.com> Date: Wed Jun 10 19:29:27 2026 -0300 Use LayerShapeType enum for ABC shapes Use LayerShapeType enum for ABC shapes commit 02c8054 Author: ruansava <ruansava@gmail.com> Date: Wed Jun 10 14:43:48 2026 -0300 Fix PML init, ElasticWave super call, and imports Fix PML init, ElasticWave super call, and imports commit a2a8402 Author: ruansava <ruansava@gmail.com> Date: Wed Jun 10 13:12:24 2026 -0300 Major refactor of the absorbing-layer (ABC) code and supporting utilities: Major refactor of the absorbing-layer (ABC) code and supporting utilities commit 025e10f Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Tue Jun 2 09:54:45 2026 -0300 fixing test commit a869d34 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Mon Jun 1 15:02:47 2026 -0300 review and notebook update according the new FWI API commit 953d235 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 14:06:20 2026 -0300 wip commit 7e6e81b Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 13:57:47 2026 -0300 remove template commit e6ca326 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 13:45:22 2026 -0300 remove private method commit acc9797 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 12:10:20 2026 -0300 flake8 commit c50a6c9 Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 12:08:38 2026 -0300 Update spyro/solvers/inversion.py commit 547d149 Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 12:08:27 2026 -0300 Update spyro/solvers/inversion.py commit a3b3434 Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 12:07:41 2026 -0300 Apply suggestion from @Ig-dolci commit d2e1115 Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 12:07:12 2026 -0300 Apply suggestions from code review Co-authored-by: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> commit e5ba83d Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 11:57:00 2026 -0300 Delete peak_memory.txt commit ae5257a Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 11:56:27 2026 -0300 Delete functional_values.txt commit 99dd006 Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 11:55:25 2026 -0300 Delete control0_0.npy commit 7335a3a Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 11:53:10 2026 -0300 wip commit 12eb3bf Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 11:20:51 2026 -0300 wip commit 359b752 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 10:45:03 2026 -0300 wip commit 72c6288 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 10:27:55 2026 -0300 wip commit f6f16c3 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 10:14:40 2026 -0300 keep the main docs commit 44a27d2 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 10:04:20 2026 -0300 remve fwi enable compute functional commit 32f12ed Author: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com> Date: Fri May 29 09:53:31 2026 -0300 Apply suggestion from @Ig-dolci commit b3a7420 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 09:51:19 2026 -0300 Address FWI helper review comments commit ebd31b1 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 09:22:46 2026 -0300 Validate FWI wave support by WaveType commit bb3d3a5 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Fri May 29 08:45:15 2026 -0300 Expose FWI functional evaluation explicitly commit a77d7d3 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:51:09 2026 -0300 Restrict FWI to acoustic solvers commit d6a618e Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:41:51 2026 -0300 Document FWI initialization parameters commit d3ae99e Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:38:11 2026 -0300 Document elastic model parameter initialization commit 2cb80f3 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:32:54 2026 -0300 Use enum for elastic control parameterization commit 03ae826 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:30:33 2026 -0300 Rename elastic control field helper commit 2589e4e Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:27:21 2026 -0300 Require enum keys for elastic controls commit 47f2e9d Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu May 28 14:18:48 2026 -0300 Remove PR override decorators and document material coercion commit ebcae31 Author: Iglesia Dolci <daia.dolci@gmail.com> Date: Thu Mar 26 13:39:43 2026 -0300 Apply FWI wave inheritance on public main

Refactor PML/ABC params and validation

Tighten boundary layer imports and state

Refactors parameter and dimension checks to use shared validation helpers across ABC, HABC, meshing, solver, and IO code. Also tightens option handling, updates the model-parameter tests for the new validation flow, and adds coverage for invalid analysis values.

Implement PML and NRBC functionality with refactoring

Fix PML and test fixtures

Improve FFT frequency response calculation with windowing

Replace string-based damping type configuration with a strongly-typed LayerDampingType enum. This includes LOCAL, HYBRID, PML, and NOABCS options. Updates all references throughout the codebase and improves documentation to reference enum values instead of strings.

Tidy error docs and HABC imports

Tighten ABC parameter checks

Simplifies PML damping field setup and adjusts solver form expressions to use direct UFL operations.

Normalize `wave_type` through the enum parameter validator in `Wave` and store `ElasticWave.time` as a plain scalar instead of a Firedrake `Constant`.

Refactor PML acoustic solver formulation

Fix ABC config state and FFT sizing

Fix PML scaling

Refactor PML space construction

Temporarily skip PML adjoint gradient test

codecov · 2026-07-15T23:49:44Z

Codecov Report

❌ Patch coverage is 78.41880% with 101 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.97%. Comparing base (05b166a) to head (46db3de).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
spyro/abc/nrbc.py	20.96%	49 Missing ⚠️
spyro/meshing/meshing_habc.py	70.83%	14 Missing ⚠️
spyro/abc/abc_layer.py	65.51%	10 Missing ⚠️
spyro/tools/habc_tools.py	69.56%	7 Missing ⚠️
spyro/io/boundary_layer_io.py	91.83%	4 Missing ⚠️
...o/solvers/acoustic_solver_construction_with_pml.py	95.00%	4 Missing ⚠️
spyro/solvers/acoustic_wave.py	73.33%	4 Missing ⚠️
spyro/utils/error_management.py	85.00%	3 Missing ⚠️
spyro/habc/damp_profile.py	0.00%	2 Missing ⚠️
spyro/solvers/elastic_wave/isotropic_wave.py	66.66%	2 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #328      +/-   ##
==========================================
- Coverage   84.73%   83.97%   -0.76%     
==========================================
  Files          97       96       -1     
  Lines        9379     9455      +76     
==========================================
- Hits         7947     7940       -7     
- Misses       1432     1515      +83

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Tighten input validation checks

Olender · 2026-07-16T19:20:29Z


        # Nyquist frequency
-        self.freq_Nyquist = freq_Nyquist
+        self.freq_Nyquist = value_numerical_error("freq_Nyquist", freq_Nyquist,


I'll open an issue to adopt this in model_parameters.py

Olender · 2026-07-16T19:50:35Z

+    abc_pml_exponent: int
+        Exponent for the polynomial damping profile of the PML layer. Default is 2.
+    abc_pml_R: float
+        Theoretical reflection coefficient of the PML layer. Default is 1e-6.


I always wanted to know why this was the default

The idea is related to the attenuation of the sound measured in dB. For an attenuation of the amplitude by 1e-6, the attenuation is equivalent to 120dB. If the source's amplitude is extremely small, this attenuation might be exaggerated. See:
https://ccrma.stanford.edu/~jos/mdft/Exponentials.html#fig:exponential
https://ccrma.stanford.edu/~jos/mdft/Audio_Decay_Time_T60.html

Olender · 2026-07-16T20:01:39Z


-    def creating_velocity_profile(self, function_space,
-                                  initial_velocity_model, path_save):
+    def creating_velocity_profile(self, function_space, initial_velocity_model, path_save):


Related to issue #299

Eventually we will need to centralize this with @rasjr1305

Olender · 2026-07-16T20:07:42Z

            "spectral_quadrilateral",
            "DG_quadrilateral",
            "CG",
+            None,


Suggested change

None,

None, # TODO: remove when deprecating old options

Clarify PML docs and convergence test markers

Olender · 2026-07-18T20:56:07Z

+        Wave_object.lhs, Wave_object.rhs + Wave_object.source_function,
+        X_np1, bcs=fix_bnd, constant_jacobian=True)
    solver_parameters = dict(Wave_object.solver_parameters)
    solver_parameters["mat_type"] = "matfree"


Moving mat_type = matfree default to the default parameters everywhere and taking them outside of the sovlers in Issue #331

Olender · 2026-07-18T21:08:11Z

        )
        parallel_print(
            "Excluding PML region from gradient (mixed space)", wave_obj.comm
        )


Suggested change

)

raise ValueError("PML gradient calculation temporarily unavailable")

Olender

I'm just sad that the cpw test was failing silently before this, so it's not this PR's job to look into it. I would ask for you to explain the changes to the filter again to me later, since I'm also changing somethings related to that in another branch.

There's only one change I would like in this PR. Since it adds back the forward PML propagation, but not the gradient calculation, we need to raise some sort of value error about it (like the suggestion on line 197 of the backward_time_integration.py file or something similar

ruansava added 30 commits June 22, 2026 18:01

Merge branch 'ruben/abc_refactoring' into ruben/HABC_refactoring

10b80b5

Merge branch 'ruben/abc_refactoring' into ruben/HABC_refactoring

a1b613f

Refactor PML/ABC params and validation

ca8acc2

Refactor PML/ABC params and validation

Tighten boundary layer imports and state

9ca4c3b

Tighten boundary layer imports and state

Merge branch 'ruben/abc_refactoring' into ruben/HABC_refactoring

828011e

Update dictionaryio.py

51afe91

Merge branch 'ruben/abc_refactoring' into ruben/HABC_refactoring

1210a56

Implement PML and NRBC functionality with refactoring

3bea6ab

Implement PML and NRBC functionality with refactoring

Update meshing_habc.py

09bc902

Fix PML and test fixtures

35c650a

Fix PML and test fixtures

Update meshing_habc.py

21a31d2

Update meshing_habc.py

ef540d6

Update test_utils.py

0f79888

Improve FFT frequency response calculation with windowing

46a3ffa

Improve FFT frequency response calculation with windowing

Merge branch 'main' into ruben/HABC_refactoring

d772de0

Tidy error docs and HABC imports

c58a73a

Tidy error docs and HABC imports

Tighten ABC parameter checks

28e3497

Tighten ABC parameter checks

Update acoustic_solver_construction_with_pml.py

1286c35

Update backward_time_integration.py

0ef8212

Update acoustic_wave.py

43c37eb

Update isotropic_wave.py

c4f33b9

Refine PML forms

cbbc3d5

Simplifies PML damping field setup and adjusts solver form expressions to use direct UFL operations.

Merge branch 'main' into ruben/HABC_refactoring

d0d2743

Merge branch 'ruben/abc_refactoring' into ruben/HABC_refactoring

e825de9

Validate wave types and use scalar time

52e867f

Normalize `wave_type` through the enum parameter validator in `Wave` and store `ElasticWave.time` as a plain scalar instead of a Firedrake `Constant`.

Update elastic_wave.py

dd36713

Refactor PML acoustic solver formulation

e51f6d2

Refactor PML acoustic solver formulation

ruansava added 3 commits July 13, 2026 20:22

Fix ABC config state and FFT sizing

f42089f

Fix ABC config state and FFT sizing

Update nrbc.py

891cbc1

Fix PML scaling

6320772

Fix PML scaling

ruansava changed the title ~~PML Refactoring~~ DO NOT SQUASH: PML Refactoring Jul 15, 2026

ruansava added 5 commits July 15, 2026 15:15

Refactor PML space construction

dfd2d8f

Refactor PML space construction

Merge branch 'main' into ruben/HABC_refactoring

65cd13c

Update test_cpw_calc.py

2422ba8

Temporarily skip PML adjoint gradient test

d8f47db

Temporarily skip PML adjoint gradient test

Update test_gradient_2d_pml.py

dc6c55a

ruansava and others added 3 commits July 16, 2026 11:49

Tighten input validation checks

115a32c

Tighten input validation checks

added convergence test for pml case

ae6e5e5

debugging

a0f1322

Olender requested review from Ig-dolci and Olender July 16, 2026 19:06