wavesimfem 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. wavesimfem-0.5.0/.github/CODE_OF_CONDUCT.md +39 -0
  2. wavesimfem-0.5.0/.github/CONTRIBUTING.md +197 -0
  3. wavesimfem-0.5.0/.github/PULL_REQUEST_TEMPLATE.md +19 -0
  4. wavesimfem-0.5.0/.github/SECURITY.md +61 -0
  5. wavesimfem-0.5.0/.pre-commit-config.yaml +70 -0
  6. wavesimfem-0.5.0/CHANGELOG.md +73 -0
  7. wavesimfem-0.5.0/CITATION.cff +33 -0
  8. wavesimfem-0.5.0/LICENSE +21 -0
  9. wavesimfem-0.5.0/MANIFEST.in +8 -0
  10. wavesimfem-0.5.0/PKG-INFO +429 -0
  11. wavesimfem-0.5.0/README.md +388 -0
  12. wavesimfem-0.5.0/assets/logo-banner.svg +124 -0
  13. wavesimfem-0.5.0/assets/logo-icon.svg +93 -0
  14. wavesimfem-0.5.0/configs/01_plate_aluminum_lamb.yaml +103 -0
  15. wavesimfem-0.5.0/configs/02_plate_cfrp.yaml +155 -0
  16. wavesimfem-0.5.0/configs/03_halfspace_steel_rayleigh.yaml +106 -0
  17. wavesimfem-0.5.0/configs/04_plate_on_halfspace_soil_bedrock.yaml +113 -0
  18. wavesimfem-0.5.0/configs/05_layers_bone_qus.yaml +137 -0
  19. wavesimfem-0.5.0/configs/06_plate_in_halfspaces_immersed_water.yaml +135 -0
  20. wavesimfem-0.5.0/configs/07_fluid_acoustic.yaml +65 -0
  21. wavesimfem-0.5.0/configs/08_fluid_solid_acoustic.yaml +84 -0
  22. wavesimfem-0.5.0/configs/README.md +521 -0
  23. wavesimfem-0.5.0/configs/template.yaml +376 -0
  24. wavesimfem-0.5.0/environment.yml +21 -0
  25. wavesimfem-0.5.0/notebooks/quickstart.ipynb +218 -0
  26. wavesimfem-0.5.0/pyproject.toml +105 -0
  27. wavesimfem-0.5.0/setup.cfg +4 -0
  28. wavesimfem-0.5.0/src/wavesimfem/__init__.py +214 -0
  29. wavesimfem-0.5.0/src/wavesimfem/__main__.py +8 -0
  30. wavesimfem-0.5.0/src/wavesimfem/_launcher.py +36 -0
  31. wavesimfem-0.5.0/src/wavesimfem/acoustic_time.py +1167 -0
  32. wavesimfem-0.5.0/src/wavesimfem/acoustics.py +1428 -0
  33. wavesimfem-0.5.0/src/wavesimfem/analysis.py +845 -0
  34. wavesimfem-0.5.0/src/wavesimfem/characterisation.py +489 -0
  35. wavesimfem-0.5.0/src/wavesimfem/characterisation_plots.py +342 -0
  36. wavesimfem-0.5.0/src/wavesimfem/cli.py +363 -0
  37. wavesimfem-0.5.0/src/wavesimfem/config.py +1228 -0
  38. wavesimfem-0.5.0/src/wavesimfem/device.py +167 -0
  39. wavesimfem-0.5.0/src/wavesimfem/lamb.py +626 -0
  40. wavesimfem-0.5.0/src/wavesimfem/materials.py +1229 -0
  41. wavesimfem-0.5.0/src/wavesimfem/numerics.py +490 -0
  42. wavesimfem-0.5.0/src/wavesimfem/parallel.py +174 -0
  43. wavesimfem-0.5.0/src/wavesimfem/py.typed +0 -0
  44. wavesimfem-0.5.0/src/wavesimfem/reporting.py +226 -0
  45. wavesimfem-0.5.0/src/wavesimfem/solvers.py +1298 -0
  46. wavesimfem-0.5.0/src/wavesimfem/solvers_gpu.py +528 -0
  47. wavesimfem-0.5.0/src/wavesimfem/sources.py +113 -0
  48. wavesimfem-0.5.0/src/wavesimfem/storage.py +129 -0
  49. wavesimfem-0.5.0/src/wavesimfem/structure_analysis.py +560 -0
  50. wavesimfem-0.5.0/src/wavesimfem/units.py +195 -0
  51. wavesimfem-0.5.0/src/wavesimfem/wave_reports.py +961 -0
  52. wavesimfem-0.5.0/src/wavesimfem/wave_spectra.py +375 -0
  53. wavesimfem-0.5.0/src/wavesimfem.egg-info/PKG-INFO +429 -0
  54. wavesimfem-0.5.0/src/wavesimfem.egg-info/SOURCES.txt +106 -0
  55. wavesimfem-0.5.0/src/wavesimfem.egg-info/dependency_links.txt +1 -0
  56. wavesimfem-0.5.0/src/wavesimfem.egg-info/entry_points.txt +2 -0
  57. wavesimfem-0.5.0/src/wavesimfem.egg-info/requires.txt +16 -0
  58. wavesimfem-0.5.0/src/wavesimfem.egg-info/top_level.txt +1 -0
  59. wavesimfem-0.5.0/tests/mpi_case.py +50 -0
  60. wavesimfem-0.5.0/tests/mpi_failure_case.py +69 -0
  61. wavesimfem-0.5.0/tests/test_acoustic_contract.py +356 -0
  62. wavesimfem-0.5.0/tests/test_acoustic_mpi_failures.py +114 -0
  63. wavesimfem-0.5.0/tests/test_acoustic_simulation.py +584 -0
  64. wavesimfem-0.5.0/tests/test_acoustic_sources.py +342 -0
  65. wavesimfem-0.5.0/tests/test_acoustic_time.py +700 -0
  66. wavesimfem-0.5.0/tests/test_acoustics.py +167 -0
  67. wavesimfem-0.5.0/tests/test_analysis.py +400 -0
  68. wavesimfem-0.5.0/tests/test_backend_validation.py +167 -0
  69. wavesimfem-0.5.0/tests/test_benchmark.py +57 -0
  70. wavesimfem-0.5.0/tests/test_characterisation.py +293 -0
  71. wavesimfem-0.5.0/tests/test_cli.py +301 -0
  72. wavesimfem-0.5.0/tests/test_compare_resolution.py +112 -0
  73. wavesimfem-0.5.0/tests/test_config.py +719 -0
  74. wavesimfem-0.5.0/tests/test_dispersion_convergence.py +231 -0
  75. wavesimfem-0.5.0/tests/test_empty_streaming.py +135 -0
  76. wavesimfem-0.5.0/tests/test_examples.py +73 -0
  77. wavesimfem-0.5.0/tests/test_figure_style.py +112 -0
  78. wavesimfem-0.5.0/tests/test_gpu.py +386 -0
  79. wavesimfem-0.5.0/tests/test_lamb.py +262 -0
  80. wavesimfem-0.5.0/tests/test_mpi.py +63 -0
  81. wavesimfem-0.5.0/tests/test_mpi_failures.py +120 -0
  82. wavesimfem-0.5.0/tests/test_numerics.py +391 -0
  83. wavesimfem-0.5.0/tests/test_parallel.py +74 -0
  84. wavesimfem-0.5.0/tests/test_physics.py +115 -0
  85. wavesimfem-0.5.0/tests/test_postprocessing_quality.py +135 -0
  86. wavesimfem-0.5.0/tests/test_reference_template.py +49 -0
  87. wavesimfem-0.5.0/tests/test_regressions.py +494 -0
  88. wavesimfem-0.5.0/tests/test_release_checks.py +150 -0
  89. wavesimfem-0.5.0/tests/test_simulation.py +180 -0
  90. wavesimfem-0.5.0/tests/test_sizing_contract.py +222 -0
  91. wavesimfem-0.5.0/tests/test_storage.py +180 -0
  92. wavesimfem-0.5.0/tests/test_structure_analysis.py +238 -0
  93. wavesimfem-0.5.0/tests/test_time_integration.py +356 -0
  94. wavesimfem-0.5.0/tests/test_tools.py +335 -0
  95. wavesimfem-0.5.0/tests/test_units_sources.py +156 -0
  96. wavesimfem-0.5.0/tests/test_wave_reports.py +378 -0
  97. wavesimfem-0.5.0/tests/test_wave_spectra.py +213 -0
  98. wavesimfem-0.5.0/tests/test_yaml_merges.py +111 -0
  99. wavesimfem-0.5.0/tools/acoustic_reference.py +123 -0
  100. wavesimfem-0.5.0/tools/benchmark.py +185 -0
  101. wavesimfem-0.5.0/tools/check_release.py +94 -0
  102. wavesimfem-0.5.0/tools/clean_junk.py +179 -0
  103. wavesimfem-0.5.0/tools/compare_resolution.py +202 -0
  104. wavesimfem-0.5.0/tools/preview_postprocessing.py +105 -0
  105. wavesimfem-0.5.0/tools/preview_structure_reports.py +377 -0
  106. wavesimfem-0.5.0/tools/run_cpu4.sh +13 -0
  107. wavesimfem-0.5.0/tools/smoke_installed.py +119 -0
  108. wavesimfem-0.5.0/tools/verify_acoustics.py +689 -0
@@ -0,0 +1,39 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and leaders pledge to make participation in our
6
+ community a harassment-free experience for everyone, regardless of age, body
7
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
8
+ identity and expression, level of experience, education, socio-economic status,
9
+ nationality, personal appearance, race, religion, or sexual identity
10
+ and orientation.
11
+
12
+ ## Our Standards
13
+
14
+ Examples of behavior that contributes to a positive environment:
15
+
16
+ * Using welcoming and inclusive language
17
+ * Being respectful of differing viewpoints and experiences
18
+ * Gracefully accepting constructive criticism
19
+ * Focusing on what is best for the community
20
+ * Showing empathy towards other community members
21
+
22
+ Examples of unacceptable behavior:
23
+
24
+ * The use of sexualized language or imagery and unwelcome sexual attention
25
+ * Trolling, insulting/derogatory comments, and personal or political attacks
26
+ * Public or private harassment
27
+ * Publishing others' private information without explicit permission
28
+ * Other conduct which could reasonably be considered inappropriate
29
+
30
+ ## Enforcement
31
+
32
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
33
+ reported to the project maintainer at [ductho.le@outlook.com](mailto:ductho.le@outlook.com).
34
+ All complaints will be reviewed and investigated promptly and fairly.
35
+
36
+ ## Attribution
37
+
38
+ This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
39
+ version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
@@ -0,0 +1,197 @@
1
+ # Contributing to WaveSimFEM
2
+
3
+ Thank you for your interest in contributing to WaveSimFEM! This guide covers
4
+ development setup, code quality standards, verification procedures, and the
5
+ release workflow.
6
+
7
+ ## Ways to Contribute
8
+
9
+ - **Bug Reports**: Open an issue with OS, Python/DOLFINx/PETSc/CuPy versions,
10
+ and a minimal YAML configuration to reproduce the problem.
11
+ - **Feature Requests**: Propose new physics models, boundary conditions,
12
+ post-processing diagnostics, or backend optimizations.
13
+ - **Code & Verification**: Submit pull requests with unit/physics tests.
14
+ - **Documentation & Examples**: Improve guides, docstrings, or benchmark
15
+ configurations in [`configs/`](../configs/).
16
+
17
+ ## Development Setup
18
+
19
+ DOLFINx, PETSc, `petsc4py`, and `mpi4py` are installed from `conda-forge` via
20
+ [`environment.yml`](../environment.yml):
21
+
22
+ ```bash
23
+ # Clone the repository
24
+ git clone https://github.com/ductho-le/WaveSimFEM.git
25
+ cd WaveSimFEM
26
+
27
+ # Create and activate the Conda environment (Linux & macOS)
28
+ conda env create -f environment.yml
29
+ conda activate wavesim
30
+
31
+ # Install WaveSimFEM in editable mode without overriding Conda FEM stacks
32
+ pip install --no-deps -e .
33
+
34
+ # Optional: install dev & release tooling (twine, packaging, pre-commit)
35
+ pip install --no-deps -e ".[dev]"
36
+
37
+ # Optional: NVIDIA CUDA GPU support
38
+ pip install -e ".[cuda]"
39
+
40
+ # Install pre-commit hooks (recommended for all contributors)
41
+ pre-commit install
42
+ ```
43
+
44
+ ### Verify Installation
45
+
46
+ ```bash
47
+ # Check package version and CLI entry point
48
+ wavesim --version
49
+
50
+ # Inspect a configuration without assembling the mesh
51
+ wavesim -c configs/01_plate_aluminum_lamb.yaml --dry-run
52
+
53
+ # Run fast local tests
54
+ python -m pytest -m "not slow"
55
+
56
+ # Run linting and formatting checks
57
+ ruff check src tests tools
58
+ ruff format --check src tests tools
59
+ ```
60
+
61
+ ## Code Quality
62
+
63
+ WaveSimFEM uses **Ruff** (`0.16.9`) for linting and formatting, enforced by
64
+ both pre-commit hooks and CI.
65
+
66
+ ### Automatic Checks (on every commit)
67
+
68
+ Once `pre-commit install` is run, commits automatically check:
69
+
70
+ | Check | Purpose |
71
+ |-------|---------|
72
+ | **`forbid-junk`** | Blocks committing caches, build artifacts, `.DS_Store`, or coverage files |
73
+ | **Ruff linter & formatter** | Enforces style, import order, bugbear/simplify rules, and 100-char formatting |
74
+ | **File & syntax hygiene** | YAML/TOML/JSON/AST validation, LF line endings, private-key detection, file size cap |
75
+ | **`clean-junk`** | Removes regenerable caches from the working tree without touching tracked files or `results_*` |
76
+
77
+ Run all hooks manually before pushing:
78
+
79
+ ```bash
80
+ pre-commit run --all-files
81
+ ```
82
+
83
+ ### Code Style Guidelines
84
+
85
+ - Follow PEP 8 (enforced by Ruff, `line-length = 100`, target Python 3.11+).
86
+ - Add type annotations on public functions and classes (`py.typed` is shipped).
87
+ - Preserve lazy top-level imports in `src/wavesimfem/__init__.py` so lightweight
88
+ modules (`config`, `units`, `sources`, `analysis`, `lamb`, `characterisation`)
89
+ never require DOLFINx, PETSc, or MPI at import time.
90
+ - Keep `ruff==0.16.9` aligned across `pyproject.toml`, `environment.yml`,
91
+ `.pre-commit-config.yaml`, and `.github/workflows/tests.yml`.
92
+
93
+ ## Running Tests & Verification
94
+
95
+ Run the full local suite before opening a pull request:
96
+
97
+ ```bash
98
+ # Full local test suite (serial, including physics verification)
99
+ python -m pytest
100
+
101
+ # Fast local subset (excludes slow end-to-end physics verification)
102
+ python -m pytest -m "not slow"
103
+
104
+ # Distributed checks on 2 MPI ranks
105
+ mpiexec -n 2 python -m pytest -q -p no:cacheprovider \
106
+ tests/test_numerics.py tests/test_acoustic_time.py \
107
+ -k "exact_point or gather or distributed or rank_local"
108
+
109
+ # Continuum acoustic verification suite
110
+ python tools/verify_acoustics.py --case all
111
+ ```
112
+
113
+ Validate packaging and isolated wheel/sdist installation:
114
+
115
+ ```bash
116
+ python -m build
117
+ python -m twine check --strict dist/*
118
+ python tools/smoke_installed.py
119
+ ```
120
+
121
+ ### Continuous Integration
122
+
123
+ - **Pushes to `main` & Pull Requests** run lightweight CI in
124
+ [`tests.yml`](workflows/tests.yml): Ruff lint & format checks, pure-Python &
125
+ array backend tests, wheel/sdist build, `twine check --strict`, and isolated
126
+ `smoke_installed.py` verification from outside the checkout.
127
+ - **Full DOLFINx / MPI / LaTeX Matrix** runs automatically every week on
128
+ schedule, on every release tag (`v*.*.*`), and on demand via:
129
+
130
+ ```bash
131
+ gh workflow run tests.yml -f full_tests=true
132
+ ```
133
+
134
+ ## Pull Request Process
135
+
136
+ 1. Fork the repository and create a branch (`git checkout -b feat/your-feature`).
137
+ 2. Keep changes focused and add/update tests in [`tests/`](../tests/).
138
+ 3. Update [`CHANGELOG.md`](../CHANGELOG.md) under `## [Unreleased]` for
139
+ user-visible changes.
140
+ 4. Run `pre-commit run --all-files` and `python -m pytest`.
141
+ 5. Open a pull request describing the motivation, numerical/physical impact, and
142
+ verification performed.
143
+
144
+ ## Adding Example Configurations
145
+
146
+ When contributing a new configuration under [`configs/`](../configs/):
147
+
148
+ - Follow the header, unit, and explicit-mesh (`mesh.nx`, `mesh.ny_per_region`)
149
+ conventions documented in [`configs/README.md`](../configs/README.md).
150
+ - Verify dry-run sizing with `wavesim -c configs/<your_file>.yaml --dry-run`.
151
+ - Ensure the configuration passes `tests/test_examples.py` and uses
152
+ `output.usetex: false` unless testing external LaTeX output explicitly.
153
+
154
+ ## Releasing (Maintainers)
155
+
156
+ Releases are automated via [`.github/workflows/release.yml`](workflows/release.yml).
157
+ Pushing a semantic version tag (`vX.Y.Z`) validates metadata, runs lint and the
158
+ full DOLFINx/MPI test matrix, verifies wheel/sdist installations, publishes to
159
+ PyPI via OIDC Trusted Publishing, and creates a GitHub Release with notes
160
+ extracted from `CHANGELOG.md`.
161
+
162
+ ### Release Checklist
163
+
164
+ 1. **Update [`CHANGELOG.md`](../CHANGELOG.md)**: Move items from
165
+ `## [Unreleased]` into a dated `## [X.Y.Z] — YYYY-MM-DD` section.
166
+ 2. **Bump version** in [`pyproject.toml`](../pyproject.toml) (`version = "X.Y.Z"`)
167
+ and [`CITATION.cff`](../CITATION.cff) (`version: X.Y.Z`, `date-released`).
168
+ 3. **Validate the tag locally** before tagging:
169
+
170
+ ```bash
171
+ python tools/check_release.py --tag vX.Y.Z --notes-file /tmp/wavesimfem-notes.md
172
+ ```
173
+
174
+ 4. **Commit, tag, and push**:
175
+
176
+ ```bash
177
+ git add CHANGELOG.md pyproject.toml CITATION.cff
178
+ git commit -m "Release vX.Y.Z"
179
+ git tag vX.Y.Z
180
+ git push origin main vX.Y.Z
181
+ ```
182
+
183
+ 5. **GitHub Actions** runs the full release gate before publishing to PyPI
184
+ (requires PyPI Trusted Publishing configured for the `pypi` environment) and
185
+ creating the GitHub Release.
186
+
187
+ ### Versioning
188
+
189
+ WaveSimFEM follows [Semantic Versioning](https://semver.org/):
190
+ - **MAJOR** (`1.0.0` → `2.0.0`): Incompatible schema or public API changes.
191
+ - **MINOR** (`0.4.0` → `0.5.0`): Backward-compatible features and physics models.
192
+ - **PATCH** (`0.4.0` → `0.4.1`): Backward-compatible bug fixes.
193
+
194
+ ## Questions?
195
+
196
+ Open an [issue](https://github.com/ductho-le/WaveSimFEM/issues) or start a
197
+ [GitHub Discussion](https://github.com/ductho-le/WaveSimFEM/discussions).
@@ -0,0 +1,19 @@
1
+ ## Summary
2
+
3
+ <!-- Describe what this PR changes and why. Link related issues if applicable (e.g., Fixes #12). -->
4
+
5
+ ## Type of Change
6
+
7
+ - [ ] Bug fix (non-breaking change fixing an issue)
8
+ - [ ] New feature (non-breaking change adding functionality)
9
+ - [ ] Breaking change (fix or feature changing existing schema, CLI, or API)
10
+ - [ ] Documentation / example configuration update
11
+ - [ ] CI / packaging / maintenance
12
+
13
+ ## Verification
14
+
15
+ - [ ] `ruff check src tests tools` and `ruff format --check src tests tools` pass
16
+ - [ ] `python -m pytest` passes locally (or `python -m pytest -m "not slow"` for non-physics edits)
17
+ - [ ] MPI / acoustic verification run if solver or parallel code was modified
18
+ - [ ] Updated `CHANGELOG.md` under `## [Unreleased]` (if user-visible)
19
+ - [ ] Updated documentation / `configs/template.yaml` (if schema or CLI changed)
@@ -0,0 +1,61 @@
1
+ # Security Policy
2
+
3
+ WaveSimFEM takes the security and integrity of scientific simulation workflows
4
+ seriously. This document outlines supported versions, responsible vulnerability
5
+ reporting, and security boundaries when running WaveSimFEM locally or on HPC
6
+ clusters.
7
+
8
+ ## Supported Versions
9
+
10
+ Security fixes are prioritized for the latest release line:
11
+
12
+ | Version | Supported |
13
+ | ------- | ------------------ |
14
+ | 0.5.x | :white_check_mark: |
15
+ | < 0.5 | :x: |
16
+
17
+ ## Reporting a Vulnerability
18
+
19
+ If you discover a security vulnerability in WaveSimFEM, please report it
20
+ responsibly:
21
+
22
+ - **Primary Contact**: Email the maintainer directly at
23
+ [ductho.le@outlook.com](mailto:ductho.le@outlook.com).
24
+ - **GitHub Security Advisory**: Open a private draft advisory via
25
+ [GitHub Security Advisories](https://github.com/ductho-le/WaveSimFEM/security/advisories/new).
26
+
27
+ Please **do not** open public GitHub issues for sensitive security
28
+ vulnerabilities. We aim to acknowledge receipt within 48 hours and coordinate
29
+ remediation prior to public disclosure.
30
+
31
+ ---
32
+
33
+ ## Security Boundaries & Safe Usage
34
+
35
+ ### 1. Safe Archive Deserialization (`.npz`)
36
+ All WaveSimFEM post-processing, verification, and utility readers open NumPy
37
+ archives strictly with `allow_pickle=False`, preventing arbitrary Python
38
+ bytecode execution when inspecting sensor archives. Still, treat archives from
39
+ untrusted sources with standard caution and verify checksums before sharing.
40
+
41
+ ### 2. Strict Configuration Parsing (YAML / TOML / JSON)
42
+ YAML configurations are parsed exclusively with `_UniqueSafeLoader` (derived
43
+ from `yaml.SafeLoader`), blocking arbitrary YAML object tags, duplicate keys,
44
+ and unrecognized schema fields. TOML and JSON inputs use Python's standard
45
+ library parsers (`tomllib`, `json`).
46
+
47
+ ### 3. External LaTeX Rendering (`output.usetex`)
48
+ External LaTeX rendering (`output.usetex: true`) invokes local `latex`,
49
+ `dvipng`, and Ghostscript binaries via Matplotlib and is **disabled by default**
50
+ (`output.usetex: false`). Do not enable `usetex: true` when post-processing
51
+ archives or configurations supplied by untrusted parties.
52
+
53
+ ### 4. Output Paths, MPI & HPC Environments
54
+ - **Atomic writes**: Archives and reports are written atomically while honoring
55
+ the process umask and existing file permissions. Use dedicated `output_dir`
56
+ paths per run rather than shared world-writable directories.
57
+ - **Distributed execution**: Multi-rank CPU simulations communicate over
58
+ standard MPI (`mpi4py` / MPICH / PETSc) communicators. On HPC clusters, run
59
+ MPI jobs within isolated internal cluster networks.
60
+ - **GPU execution**: Optional CUDA acceleration uses CuPy (`cupy-cuda12x`) and
61
+ runs custom elementwise kernels locally on the selected NVIDIA GPU device.
@@ -0,0 +1,70 @@
1
+ # Install once with `pre-commit install`; run everything with `pre-commit run --all-files`.
2
+ # Hooks run in file order: the junk guard first (fail fast), the junk cleaner last (so it
3
+ # also removes caches created by earlier hooks, e.g. .ruff_cache/).
4
+ repos:
5
+ - repo: local
6
+ hooks:
7
+ # Refuse to commit junk that was staged (e.g. with `git add -f`). Keep in sync with
8
+ # the patterns in tools/clean_junk.py.
9
+ - id: forbid-junk
10
+ name: forbid committing junk files
11
+ entry: >-
12
+ Junk files must not be committed; unstage them with `git rm --cached <path>`
13
+ language: fail
14
+ files: |
15
+ (?x)(
16
+ (^|/)__pycache__/
17
+ | \.py[co]$
18
+ | (^|/)\.(pytest|ruff|mypy)_cache/
19
+ | (^|/)\.ipynb_checkpoints/
20
+ | (^|/)htmlcov/
21
+ | (^|/)\.eggs/
22
+ | \.egg-info/
23
+ | ^(build|dist)/
24
+ | (^|/)\.DS_Store$
25
+ | (^|/)\._[^/]+$
26
+ | (^|/)(Thumbs|ehthumbs)\.db$
27
+ | (^|/)[Dd]esktop\.ini$
28
+ | \.sw[po]$
29
+ | ~$
30
+ | (^|/)\.coverage(\.[^/]+)?$
31
+ | (^|/)coverage\.xml$
32
+ )
33
+
34
+ - repo: https://github.com/pre-commit/pre-commit-hooks
35
+ rev: v6.0.0
36
+ hooks:
37
+ - id: check-yaml
38
+ - id: check-toml
39
+ - id: check-json
40
+ - id: check-ast
41
+ - id: detect-private-key
42
+ - id: end-of-file-fixer
43
+ - id: trailing-whitespace
44
+ - id: mixed-line-ending
45
+ args: ["--fix=lf"]
46
+ - id: check-added-large-files
47
+ args: ["--maxkb=1024"]
48
+ - id: check-merge-conflict
49
+ - id: check-case-conflict
50
+
51
+ - repo: https://github.com/astral-sh/ruff-pre-commit
52
+ rev: v0.16.9 # keep in sync with the ruff pin in .github/workflows/tests.yml
53
+ hooks:
54
+ - id: ruff-check
55
+ args: ["--fix"]
56
+ - id: ruff-format
57
+
58
+ # Keep this block LAST so it also removes junk produced by the hooks above.
59
+ - repo: local
60
+ hooks:
61
+ # Delete regenerable junk (caches, build artifacts, coverage, OS/editor files) from the
62
+ # working tree. Never touches results_*, *.npz, envs, .dev, or Git-tracked files.
63
+ # Manual use: `pre-commit run clean-junk` or `python tools/clean_junk.py [--dry-run]`.
64
+ - id: clean-junk
65
+ name: clean junk files and folders
66
+ entry: python tools/clean_junk.py --quiet
67
+ language: python
68
+ pass_filenames: false
69
+ always_run: true
70
+ stages: [pre-commit, manual]
@@ -0,0 +1,73 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. Versions follow
4
+ [Semantic Versioning](https://semver.org/).
5
+
6
+ ## [Unreleased]
7
+
8
+ ## [0.5.0] — 2026-11-21 — public release & performance hardening
9
+
10
+ ### Added
11
+
12
+ - **Public API & quickstart**: lazily export acoustic solver and report APIs (`build_acoustic_problem`, `solve_acoustic`, `run_acoustic_simulation`, `write_structure_report`, `write_lamb_report`, `write_characterisation`, `structure_profile`, `reference_dispersion`, `phase_velocity_spectrum`, `polarization_spectrum`) from top-level `wavesimfem`; add interactive `notebooks/quickstart.ipynb`; print `conda-forge` setup guidance when `wavesim` is invoked without DOLFINx/MPI.
13
+ - **Release automation & community governance**: add automated tag-driven release workflow (`.github/workflows/release.yml`) with OIDC PyPI publishing and GitHub Releases, release validation (`tools/check_release.py`), isolated wheel/sdist smoke checks (`tools/smoke_installed.py`), weekly full DOLFINx/MPI CI runs, and `.github/` governance docs (`CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue/PR templates).
14
+
15
+ ### Changed
16
+
17
+ - **CLI & units**: `--generate-config` requires `--force` to overwrite; `--min-frequency` / `--max-frequency` accept unit strings; ambiguous `"mhz"`/`"mHZ"` spellings are rejected; `--postprocess` combined with `--dry-run` exits with a usage error.
18
+ - **Fail-fast validation**: incompatible `lamb_modes` / `wave_characterisation` options, missing LaTeX when `usetex: true` (warn-only on `--dry-run`), and acoustic source/boundary/interface/shared-corner conflicts fail during config resolution before mesh assembly. Explicit `sensor_sample_rate` below Nyquist is raised automatically.
19
+ - **Outputs & examples**: elastic archives write `schema_version: 1`; atomic outputs preserve existing file modes or honour the umask; report READMEs reflect the active `usetex` typography mode; Examples 03–08 standardize on broadband Ricker excitation (`1 MHz` for 06–08) and consistent receiver apertures; CI expands the lightweight pure-Python/array-backend test job.
20
+
21
+ ### Performance
22
+
23
+ - **On-device acoustic recording**: serial explicit runs (`CoupledArrayRK4`) evaluate sensors (`pressure`, `displacement`, `velocity`, including prescribed boundary lifting) and quadratic fluid energy on-device in a chunked ring buffer with zero per-step host syncs; `particle_velocity` interpolates only over probe cells.
24
+ - **Array & GPU kernels**: fused CuPy `ElementwiseKernel` updates (38 → 17 vector launches per RK4 step), FP32-preserving scalar casts, zero-forcing fast paths, and Stage-4 in-place accumulation across `solvers_gpu`, `CoupledArrayRK4`, and `PetscRK4`.
25
+ - **Assembly & sampling**: cached sparse `point_evaluation_matrix` (O(`n_sensors`) DOF clearing) replaces per-step `Function.eval`; `fem.Constant` form scalars allow JIT kernel reuse across sweeps; coupled Newmark factorises the monolithic operator once (MUMPS direct, field-split GMRES / CG+BJacobi/ICC fallback).
26
+
27
+ ### Fixed
28
+
29
+ - **Solvers & numerics**: set `atol=0.0` in iterative PETSc KSP solvers for scale invariance on small right-hand sides; perform acoustic GLL mass lumping before Dirichlet elimination (omitting `Mp_fD` lifting for explicit prescribed pressure); build layered mesh interfaces directly from `y_bot`/`y_top`; check velocity finiteness in PETSc explicit runs; use explicit `float32`/`float64` CuPy kernel types with single-precision GPU test coverage.
30
+ - **Resource & MPI safety**: release PETSc temporaries and `HistoryStore` scratch directories on exception paths; avoid reporting `"single rank"` in `describe_thread_state` under unrecognized multi-rank launchers; report the first validation error in `PointSensors.gather`; enforce spec-compliant, linear-time YAML 1.1 merge precedence in `_UniqueSafeLoader` (working around PyYAML 6.0.4's `flatten_mapping` regression).
31
+ - **Post-processing & timing**: compute scalar pressure colourbar limits without stacking placeholder zeros; read sectioned `mesh` frequency bands, handle `max_frequency < f_center / 5`, and tolerate missing metadata in Lamb reports; tolerate ULP rounding on characterisation `time_window` bounds; align elastic snapshot timestamps to completed steps and share mesh-based interface tolerances.
32
+
33
+ ## [0.4.0] — 2026-10-10 — acoustic fluids
34
+
35
+ ### Breaking changes
36
+
37
+ - **Explicit meshes & CFL**: `mesh.nx` and `mesh.ny_per_region` (bottom-to-top) are required; removed `elems_per_wavelength`, `min_elems_x`, and `min_elems_y`. Explicit runs require `solver.CFL` in `(0, 1]`; preflight reports actual cell sizes (`h_x`, `h_y_per_region`).
38
+ - **Acoustic fluid default**: `material_model: fluid` defaults to inviscid scalar-pressure acoustics (`fluid_formulation: acoustic`, normal coupling with tangential slip) and rejects `fluid_shear_reg` (use `fluid_formulation: regularized_elastic` for legacy runs). Field-aware archives use `schema_version: 2` with explicit `sensor_observable`, `sensor_units`, and observable-specific keys.
39
+
40
+ ### Added
41
+
42
+ - Acoustic sources (`acoustic_pressure`, `acoustic_normal_acceleration`, `acoustic_volume`), `source_boundary`/`source_y`/`source_region`, `acoustic_boundaries` (`rigid`, `pressure_release`, `radiation`), and `sensors.observable`/`sensors.region`.
43
+ - Coupled PETSc RK4/Newmark integrators (serial & MPI), serial SciPy/CuPy `CoupledArrayRK4`, `SeparableForcing`, coupling-inclusive explicit stability bounds, continuum verification suite (`tools/verify_acoustics.py`), and Examples 07–08.
44
+ - Structure-aware multi-panel reports (`wave_physics/`) with JSON/CSV/NPZ exports and synthetic preview tools (`tools/preview_structure_reports.py`, `tools/preview_postprocessing.py`).
45
+
46
+ ### Performance & Fixed
47
+
48
+ - Coupled RK4 reuses end-of-step acceleration (4 instead of 5 evaluations/step), downloads host mirrors lazily, and evaluates fluid energy via preassembled quadratic forms.
49
+ - Aligned field-aware Gaussian source footprint to `exp(-(x - x0)² / (2σ²))` (`σ = excitation_width / 3`), matching the elastic solver; rejected mismatched `source_y` on exterior faces.
50
+ - Replaced Example 02 with an 8-ply T300/914 CFRP laminate; renamed CLI executable to `wavesim`; standardized 190 mm / 10 pt figures with `output.usetex: false` default; hardened Lamb, dispersion, and packet-characterisation reports (JSON schema v2, atomic exports).
51
+
52
+ ## [0.3.0] — 2026-10-03 — production hardening
53
+
54
+ ### Breaking changes
55
+
56
+ - **Strict devices & schema**: explicit `cuda`/`cuda:N` raises `DeviceUnavailableError` (exit code 3) instead of falling back; unknown/duplicate/ignored config keys and multi-layer `1_layer` definitions are rejected; `absorb_depth` applies only to halfspaces; legacy backend wrappers removed.
57
+ - **SI units & adaptive defaults**: public API, CLI flags (`--f-min`/`--f-max`/`--k-min`/`--k-max`), and `postprocess` keys use SI or unit strings; sponge damping, source/sensor layout, and duration default to wavelength/frequency-scaled values; implicit Newmark uses `solver.steps_per_period` (default 40); sensor histories are decimated (`sensors.sample_rate`); default `absorb_beta` lowered to `1e-9 s` at 1 MHz.
58
+
59
+ ### Added
60
+
61
+ - Hann-windowed `tone_burst` excitation; scale-adaptive units (`wavesimfem.units`); unified SciPy/CuPy explicit RK4 engine with chunked device-resident sensor ring buffer; `logging` output (`-q`, `-v`, `--version`); `output.compress_output`/`figure_formats`/`usetex`; `substrate`/`superstrate` aliases; `tools/clean_junk.py` pre-commit hooks; curated Examples 01–06.
62
+
63
+ ### Changed & Fixed
64
+
65
+ - **Solvers**: RK4 stability radius `R = 2.6` (2.6× larger rigorous step) with matching element-level preflight bounds; once-assembled implicit Newmark operator (2.1× faster, GAMG rigid-body near-nullspace); allocation-free `PetscRK4` with zero-dropped damping; vectorized `operator_bound` (~100× faster); MPI `Gatherv` sensor collection; lazy top-level imports.
66
+ - **Runtime & plotting**: automatic BLAS/OpenMP thread capping per MPI rank (`wavesimfem.parallel`); relative fluid-layer threshold (`c_T < 0.01 c_L`); isolated Matplotlib `rcParams` and clean no-TeX fallbacks; clean exit-code-2 CLI errors; hardened CI and SPDX packaging.
67
+
68
+ ## [0.2.0] — numerical robustness update
69
+
70
+ - Replaced damped Verlet with fourth-order explicit RK4 using conservative assembled stability bounds and drift-free integer time stepping.
71
+ - Added exact FE point-sensor evaluation with rank-owned histories, Hann-tapered/padded dispersion FFTs, and corrected B-scan extents.
72
+ - Added preflight resource estimation (`--dry-run`), CLI numerical overrides (`--max-frequency`, `--duration`, `--dt`, `--cfl`, `--no-postprocess`), strict input validation, PETSc convergence checks, and MPI fail-fast diagnostics.
73
+ - Reorganized codebase into the `src/wavesimfem/` package with an installable CLI, regression tests, and CI.
@@ -0,0 +1,33 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use WaveSimFEM in academic research or industrial applications, please cite it as below."
3
+ title: "WaveSimFEM: A GPU-accelerated finite element framework for acoustic and elastic wave propagation in layered media"
4
+ type: software
5
+ abstract: >-
6
+ WaveSimFEM is a GPU-accelerated finite element framework built on DOLFINx and
7
+ PETSc for acoustic and elastic wave propagation in layered media, including
8
+ guided and surface waves (Lamb, Rayleigh, leaky and interface waves) in layered plates
9
+ and halfspaces with isotropic, anisotropic and viscoelastic solids coupled to inviscid acoustic
10
+ (pressure) fluids. It
11
+ provides rigorously stable explicit RK4 solvers, including a coupling-inclusive
12
+ bound for fluid-solid systems, implicit Newmark solvers, absorbing sponge
13
+ layers, exact point sensors and 2D FFT dispersion analysis from seismic to
14
+ ultrasonic scales.
15
+ authors:
16
+ - family-names: "Le"
17
+ given-names: "Ductho"
18
+ orcid: "https://orcid.org/0000-0002-3073-1416"
19
+ affiliation: "School of Biomedical Engineering, International University, Viet Nam National University Ho Chi Minh City"
20
+ version: 0.5.0
21
+ date-released: 2026-11-21
22
+ license: MIT
23
+ repository-code: "https://github.com/ductho-le/WaveSimFEM"
24
+ keywords:
25
+ - "wavesim"
26
+ - "guided-waves"
27
+ - "finite-element-method"
28
+ - "ultrasonics"
29
+ - "dolfinx"
30
+ - "petsc"
31
+ - "rayleigh-waves"
32
+ - "lamb-waves"
33
+ - "dispersion-analysis"
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ductho Le
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,8 @@
1
+ include LICENSE README.md CHANGELOG.md CITATION.cff pyproject.toml
2
+ include environment.yml .pre-commit-config.yaml
3
+ recursive-include .github *.md
4
+ recursive-include assets *.svg
5
+ recursive-include configs *.yaml *.md
6
+ recursive-include notebooks *.ipynb
7
+ recursive-include tools *.py *.sh
8
+ recursive-include tests *.py