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.
- wavesimfem-0.5.0/.github/CODE_OF_CONDUCT.md +39 -0
- wavesimfem-0.5.0/.github/CONTRIBUTING.md +197 -0
- wavesimfem-0.5.0/.github/PULL_REQUEST_TEMPLATE.md +19 -0
- wavesimfem-0.5.0/.github/SECURITY.md +61 -0
- wavesimfem-0.5.0/.pre-commit-config.yaml +70 -0
- wavesimfem-0.5.0/CHANGELOG.md +73 -0
- wavesimfem-0.5.0/CITATION.cff +33 -0
- wavesimfem-0.5.0/LICENSE +21 -0
- wavesimfem-0.5.0/MANIFEST.in +8 -0
- wavesimfem-0.5.0/PKG-INFO +429 -0
- wavesimfem-0.5.0/README.md +388 -0
- wavesimfem-0.5.0/assets/logo-banner.svg +124 -0
- wavesimfem-0.5.0/assets/logo-icon.svg +93 -0
- wavesimfem-0.5.0/configs/01_plate_aluminum_lamb.yaml +103 -0
- wavesimfem-0.5.0/configs/02_plate_cfrp.yaml +155 -0
- wavesimfem-0.5.0/configs/03_halfspace_steel_rayleigh.yaml +106 -0
- wavesimfem-0.5.0/configs/04_plate_on_halfspace_soil_bedrock.yaml +113 -0
- wavesimfem-0.5.0/configs/05_layers_bone_qus.yaml +137 -0
- wavesimfem-0.5.0/configs/06_plate_in_halfspaces_immersed_water.yaml +135 -0
- wavesimfem-0.5.0/configs/07_fluid_acoustic.yaml +65 -0
- wavesimfem-0.5.0/configs/08_fluid_solid_acoustic.yaml +84 -0
- wavesimfem-0.5.0/configs/README.md +521 -0
- wavesimfem-0.5.0/configs/template.yaml +376 -0
- wavesimfem-0.5.0/environment.yml +21 -0
- wavesimfem-0.5.0/notebooks/quickstart.ipynb +218 -0
- wavesimfem-0.5.0/pyproject.toml +105 -0
- wavesimfem-0.5.0/setup.cfg +4 -0
- wavesimfem-0.5.0/src/wavesimfem/__init__.py +214 -0
- wavesimfem-0.5.0/src/wavesimfem/__main__.py +8 -0
- wavesimfem-0.5.0/src/wavesimfem/_launcher.py +36 -0
- wavesimfem-0.5.0/src/wavesimfem/acoustic_time.py +1167 -0
- wavesimfem-0.5.0/src/wavesimfem/acoustics.py +1428 -0
- wavesimfem-0.5.0/src/wavesimfem/analysis.py +845 -0
- wavesimfem-0.5.0/src/wavesimfem/characterisation.py +489 -0
- wavesimfem-0.5.0/src/wavesimfem/characterisation_plots.py +342 -0
- wavesimfem-0.5.0/src/wavesimfem/cli.py +363 -0
- wavesimfem-0.5.0/src/wavesimfem/config.py +1228 -0
- wavesimfem-0.5.0/src/wavesimfem/device.py +167 -0
- wavesimfem-0.5.0/src/wavesimfem/lamb.py +626 -0
- wavesimfem-0.5.0/src/wavesimfem/materials.py +1229 -0
- wavesimfem-0.5.0/src/wavesimfem/numerics.py +490 -0
- wavesimfem-0.5.0/src/wavesimfem/parallel.py +174 -0
- wavesimfem-0.5.0/src/wavesimfem/py.typed +0 -0
- wavesimfem-0.5.0/src/wavesimfem/reporting.py +226 -0
- wavesimfem-0.5.0/src/wavesimfem/solvers.py +1298 -0
- wavesimfem-0.5.0/src/wavesimfem/solvers_gpu.py +528 -0
- wavesimfem-0.5.0/src/wavesimfem/sources.py +113 -0
- wavesimfem-0.5.0/src/wavesimfem/storage.py +129 -0
- wavesimfem-0.5.0/src/wavesimfem/structure_analysis.py +560 -0
- wavesimfem-0.5.0/src/wavesimfem/units.py +195 -0
- wavesimfem-0.5.0/src/wavesimfem/wave_reports.py +961 -0
- wavesimfem-0.5.0/src/wavesimfem/wave_spectra.py +375 -0
- wavesimfem-0.5.0/src/wavesimfem.egg-info/PKG-INFO +429 -0
- wavesimfem-0.5.0/src/wavesimfem.egg-info/SOURCES.txt +106 -0
- wavesimfem-0.5.0/src/wavesimfem.egg-info/dependency_links.txt +1 -0
- wavesimfem-0.5.0/src/wavesimfem.egg-info/entry_points.txt +2 -0
- wavesimfem-0.5.0/src/wavesimfem.egg-info/requires.txt +16 -0
- wavesimfem-0.5.0/src/wavesimfem.egg-info/top_level.txt +1 -0
- wavesimfem-0.5.0/tests/mpi_case.py +50 -0
- wavesimfem-0.5.0/tests/mpi_failure_case.py +69 -0
- wavesimfem-0.5.0/tests/test_acoustic_contract.py +356 -0
- wavesimfem-0.5.0/tests/test_acoustic_mpi_failures.py +114 -0
- wavesimfem-0.5.0/tests/test_acoustic_simulation.py +584 -0
- wavesimfem-0.5.0/tests/test_acoustic_sources.py +342 -0
- wavesimfem-0.5.0/tests/test_acoustic_time.py +700 -0
- wavesimfem-0.5.0/tests/test_acoustics.py +167 -0
- wavesimfem-0.5.0/tests/test_analysis.py +400 -0
- wavesimfem-0.5.0/tests/test_backend_validation.py +167 -0
- wavesimfem-0.5.0/tests/test_benchmark.py +57 -0
- wavesimfem-0.5.0/tests/test_characterisation.py +293 -0
- wavesimfem-0.5.0/tests/test_cli.py +301 -0
- wavesimfem-0.5.0/tests/test_compare_resolution.py +112 -0
- wavesimfem-0.5.0/tests/test_config.py +719 -0
- wavesimfem-0.5.0/tests/test_dispersion_convergence.py +231 -0
- wavesimfem-0.5.0/tests/test_empty_streaming.py +135 -0
- wavesimfem-0.5.0/tests/test_examples.py +73 -0
- wavesimfem-0.5.0/tests/test_figure_style.py +112 -0
- wavesimfem-0.5.0/tests/test_gpu.py +386 -0
- wavesimfem-0.5.0/tests/test_lamb.py +262 -0
- wavesimfem-0.5.0/tests/test_mpi.py +63 -0
- wavesimfem-0.5.0/tests/test_mpi_failures.py +120 -0
- wavesimfem-0.5.0/tests/test_numerics.py +391 -0
- wavesimfem-0.5.0/tests/test_parallel.py +74 -0
- wavesimfem-0.5.0/tests/test_physics.py +115 -0
- wavesimfem-0.5.0/tests/test_postprocessing_quality.py +135 -0
- wavesimfem-0.5.0/tests/test_reference_template.py +49 -0
- wavesimfem-0.5.0/tests/test_regressions.py +494 -0
- wavesimfem-0.5.0/tests/test_release_checks.py +150 -0
- wavesimfem-0.5.0/tests/test_simulation.py +180 -0
- wavesimfem-0.5.0/tests/test_sizing_contract.py +222 -0
- wavesimfem-0.5.0/tests/test_storage.py +180 -0
- wavesimfem-0.5.0/tests/test_structure_analysis.py +238 -0
- wavesimfem-0.5.0/tests/test_time_integration.py +356 -0
- wavesimfem-0.5.0/tests/test_tools.py +335 -0
- wavesimfem-0.5.0/tests/test_units_sources.py +156 -0
- wavesimfem-0.5.0/tests/test_wave_reports.py +378 -0
- wavesimfem-0.5.0/tests/test_wave_spectra.py +213 -0
- wavesimfem-0.5.0/tests/test_yaml_merges.py +111 -0
- wavesimfem-0.5.0/tools/acoustic_reference.py +123 -0
- wavesimfem-0.5.0/tools/benchmark.py +185 -0
- wavesimfem-0.5.0/tools/check_release.py +94 -0
- wavesimfem-0.5.0/tools/clean_junk.py +179 -0
- wavesimfem-0.5.0/tools/compare_resolution.py +202 -0
- wavesimfem-0.5.0/tools/preview_postprocessing.py +105 -0
- wavesimfem-0.5.0/tools/preview_structure_reports.py +377 -0
- wavesimfem-0.5.0/tools/run_cpu4.sh +13 -0
- wavesimfem-0.5.0/tools/smoke_installed.py +119 -0
- 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"
|
wavesimfem-0.5.0/LICENSE
ADDED
|
@@ -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
|