Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/jmrplens/phonometry. Standards-conformant acoustics library for Python: measurement and metrology, docs.jmrp.io/phonometry
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286# Copyright (c) 2026. Jose Manuel Requena Plens"""The engines' NumPy numbers, reduced to SHA-256 digests and held still.
Before the FDTD engines could step on other array backends, a frozen copy ofthem stood in the test suite, and every runner compared the refactoredengines with it bit for bit. That proved the refactor; it cannot keepproving the next change, because the copy has to go some day. What stays isthis: every scenario of ``engine_scenarios`` stepped on NumPy in float64,every array it returns reduced to a digest of its dtype, shape and bytes,and the fluid branch of the elastic energy recorded exactly, all written to``engine-digests.json`` at the root of the repository.
The bits depend on the platform (the C library's libm, and NumPy's SIMDdispatch), so the file records the environment it was measured in, and theone CI job that measures it is the one that checks it(``tests/simulation/test_engine_golden_digests.py``); the committed file isthat job's measurement. NumPy's AVX-512 kernels are switched off there andhere (``NPY_DISABLE_CPU_FEATURES``, see :func:`avx512_features`), so a runnerwith AVX-512 and one without compute the same bits. The engines step onNumPy whatever ``use()`` or ``PHONOMETRY_COMPUTE`` ask for.
The documentation clips that step an FDTD engine (the walk of``animation_fingerprint`` counts every clip whose code reaches``phonometry.simulation``, which are the field clips) are tied to thedigests and the fluid-energy record of this file, not to the engines'source and not to the environment the file records(``animation_fingerprint.engine_digest``). Rewriting an engine so that itcomputes the same numbers marks no clip stale; a change that moves arecorded number fails the CI job until the file is recorded again, and thenew file marks every one of those clips stale.
Usage::
python scripts/engine_digests.py # compare, exit 1 on a moved digest python scripts/engine_digests.py --write # measure and write the file python scripts/engine_digests.py --output FILE # compare, and keep the measurement python scripts/engine_digests.py --avx512-features # what to switch off
A different environment is only reported, unless ``PHONOMETRY_ENGINE_DIGESTS``is ``require`` (the CI job), where it fails too."""
from __future__ import annotations
import argparseimport hashlibimport importlibimport jsonimport osimport pathlibimport platformimport sysfrom typing import TYPE_CHECKING, Any
import numpy as np
_ROOT = pathlib.Path(__file__).resolve().parent.parentif str(_ROOT / "scripts") not in sys.path: sys.path.insert(0, str(_ROOT / "scripts"))
import engine_scenarios as es
if TYPE_CHECKING: from numpy.typing import NDArray
from phonometry.simulation.elastic_fdtd import ElasticFDTD2D
#: Where the digests live, beside ``gpu-parity.lock``.DIGESTS_FILE = _ROOT / "engine-digests.json"
#: Set to ``require`` (the CI job) to fail on a different environment too.REQUIRE_ENV = "PHONOMETRY_ENGINE_DIGESTS"
#: The seeds of the fluid-energy record (see :func:`fluid_energy`).FLUID_SEEDS = (0, 1, 2, 3, 4)
#: A solid at the bound c_p**2 = 2 c_s**2, just under it, so that lambda is#: clamped to exactly zero (the constructor admits a relative 1e-9 below)._LAMBDA_ZERO_C_P = 2828.427124_LAMBDA_ZERO_C_S = 2000.0
def array_digest(array: NDArray[Any]) -> str: """SHA-256 of *array*'s dtype, shape and C-ordered bytes.""" contiguous = np.ascontiguousarray(array) digest = hashlib.sha256(f"{contiguous.dtype.str}|{contiguous.shape}|".encode()) digest.update(contiguous.tobytes()) return digest.hexdigest()
def fluid_grid() -> ElasticFDTD2D: """An all-fluid elastic grid with a small solid patch whose lambda is zero.
Placed on NumPy whatever ``use()`` or ``PHONOMETRY_COMPUTE`` ask, as :func:`numpy_run` is, so its energy is NumPy's in a shell set up for the clips too. """ from phonometry.simulation import Compute, elastic_fdtd
ny, nx = 24, 30 c_p = np.full((ny, nx), 1480.0) c_s = np.zeros((ny, nx)) rho = np.full((ny, nx), 1000.0) c_p[9:15, 12:18] = _LAMBDA_ZERO_C_P c_s[9:15, 12:18] = _LAMBDA_ZERO_C_S rho[9:15, 12:18] = 2500.0 return elastic_fdtd.ElasticFDTD2D(c_p, c_s, 0.01, rho=rho, compute=Compute())
def fluid_energy(seed: int) -> float: """The energy of :func:`fluid_grid` under seeded random normal stresses.
No scenario weighs ``p**2 / (2 lam)`` enough to see a rounding in it, so the fluid branch of ``energy`` gets a record of its own. """ sim = fluid_grid() rng = np.random.default_rng(seed) shape = tuple(sim.txx.shape) sim.txx[...] = 1e3 * rng.standard_normal(shape) sim.tyy[...] = 1e3 * rng.standard_normal(shape) return sim.energy()
def avx512_features() -> list[str]: """The AVX-512 dispatch targets NumPy would use on this machine, by name.
Of the targets NumPy was built to dispatch to (``__cpu_dispatch__``), those that are AVX-512 and that this machine has (``__cpu_features__``): ``NPY_DISABLE_CPU_FEATURES`` switches off dispatch targets and nothing else, so a build without an AVX-512 kernel gives none, whatever the CPU has. From NumPy 2.4 on the x86 targets are named by microarchitecture level: ``X86_V3`` is AVX2 with FMA, and ``X86_V4`` and the ``AVX512_*`` targets above it are AVX-512. Switching those off leaves an AVX-512 runner on the kernels of one without. Before 2.4 the AVX-512 targets are named one by one (``AVX512F``, ``AVX512_SKX``). Measured under Intel SDE (``-skx``) on NumPy 2.5.3: with ``X86_V4`` on, 23 of the digests move; with it off, none does. """ module = importlib.import_module("numpy._core._multiarray_umath") features: dict[str, bool] = module.__cpu_features__ dispatch: list[str] = list(module.__cpu_dispatch__) return sorted( name for name in dispatch if (name == "X86_V4" or name.startswith("AVX512")) and features.get(name, False) )
def environment_required() -> bool: """Whether a different environment fails too: :data:`REQUIRE_ENV` is ``require``.
The CI job that measures the file sets it; anywhere else a different environment is only reported, by this script and by the test. """ return os.environ.get(REQUIRE_ENV) == "require"
def environment() -> dict[str, str]: """What decides the bits: the platform, its C library (libm), Python, NumPy and its AVX-512 kernels.""" name, version = platform.libc_ver() return { "system": platform.system(), "machine": platform.machine(), "libc": f"{name} {version}" if version else "unknown", "python": ".".join(platform.python_version_tuple()[:2]), "numpy": np.__version__, "numpy_avx512": "on" if avx512_features() else "off", }
def cpu_model() -> str: """The CPU this measurement ran on, kept beside it and never compared.
A hosted runner is an Intel or an AMD machine at random; with NumPy's AVX-512 kernels off both are expected to give the same bits, and this record is what tells the two apart if a digest ever moves between runs. """ cpuinfo = pathlib.Path("/proc/cpuinfo") if cpuinfo.exists(): for line in cpuinfo.read_text(encoding="utf-8", errors="replace").splitlines(): if line.startswith("model name"): return line.split(":", 1)[1].strip() return platform.processor() or "unknown"
def numpy_run(scenario: es.Scenario) -> dict[str, NDArray[Any]]: """*scenario* stepped on NumPy in float64, whatever ``use()`` or ``PHONOMETRY_COMPUTE`` ask.
A shell set up to render the clips names a GPU in ``PHONOMETRY_COMPUTE``; the placement passed here wins over it, so the digests are NumPy's. """ from phonometry.simulation import Compute, elastic_fdtd, fdtd
module = fdtd if scenario.kind == "acoustic" else elastic_fdtd return es.run(scenario, module, compute=Compute())
def measure() -> dict[str, Any]: """Step every scenario on NumPy and digest everything it returns.""" scenarios: dict[str, dict[str, str]] = {} for scenario in es.SCENARIOS: out = numpy_run(scenario) scenarios[scenario.name] = {key: array_digest(out[key]) for key in sorted(out)} return { "environment": environment(), "measured_on": {"cpu": cpu_model()}, "scenarios": scenarios, "fluid_energy": {str(s): float.hex(fluid_energy(s)) for s in FLUID_SEEDS}, }
def recorded() -> dict[str, Any]: """The digests in :data:`DIGESTS_FILE`.""" data: dict[str, Any] = json.loads(DIGESTS_FILE.read_text(encoding="utf-8")) return data
def differences(want: dict[str, Any], got: dict[str, Any]) -> list[str]: """Every scenario key and seed whose digest moved, appeared or vanished.""" problems: list[str] = [] for name in sorted(want["scenarios"].keys() | got["scenarios"].keys()): old = want["scenarios"].get(name, {}) new = got["scenarios"].get(name, {}) problems.extend( f"{name}: {key}" for key in sorted(old.keys() | new.keys()) if old.get(key) != new.get(key) ) old_e, new_e = want["fluid_energy"], got["fluid_energy"] problems.extend( f"fluid_energy: seed {seed}" for seed in sorted(old_e.keys() | new_e.keys()) if old_e.get(seed) != new_e.get(seed) ) return problems
def main(argv: list[str] | None = None) -> int: """Each mode of the usage above; 1 when a digest moved, or the environment where it is required.
:raises FileNotFoundError: when there is no :data:`DIGESTS_FILE` to compare with (``--write`` records one). """ parser = argparse.ArgumentParser(description=(__doc__ or "").splitlines()[0]) parser.add_argument( "--write", action="store_true", help="measure and write engine-digests.json" ) parser.add_argument( "--output", type=pathlib.Path, default=None, help="also write the measurement here", ) parser.add_argument( "--avx512-features", action="store_true", help="print the AVX-512 features to switch off", ) args = parser.parse_args(argv) if args.avx512_features: sys.stdout.write(" ".join(avx512_features()) + "\n") return 0 got = measure() text = json.dumps(got, indent=1, sort_keys=True) + "\n" if args.write: DIGESTS_FILE.write_text(text, encoding="utf-8") return 0 if args.output is not None: args.output.write_text(text, encoding="utf-8") want = recorded() problems = [f"moved: {problem}" for problem in differences(want, got)] if want["environment"] != got["environment"]: note = f"environment: recorded {want['environment']}, here {got['environment']}" if environment_required(): problems.insert(0, note) else: # Here the numbers may differ for that reason alone; the CI job decides. sys.stderr.write(f"note: {note}\n") for problem in problems: sys.stderr.write(f"{problem}\n") return 1 if problems else 0
if __name__ == "__main__": raise SystemExit(main())