Lead the API pages with the module, and type the conformance report as data (#369)
Two things the pages were saying about themselves rather than about their
subject.
All 120 generated API pages opened with the "auto-generated from the source
docstrings, do not edit by hand" note. That is a message to whoever might edit
the file, and it was standing where the module's own summary belongs: it was
the paragraph a search result quoted and the one the `speakable` selector
points assistants at. The summary leads now and the note follows it.
The conformance report page was typed as an article. It is a machine-generated
table with a fixed schema, regenerated by CI, downloadable at a stable URL, so
it is a Dataset, and it is the most citable object the project owns. Both
language versions now declare one, with the column schema, the download URL
and the DOI. The counts in the description are read from the report itself
rather than written out.
451 pages build, html-validate clean, i18n parity holds, the site-reports and
conformance-claims gates pass, and the three JSON-LD blocks on each
conformance page parse.
Lead the API pages with the module, and type the conformance report as data (#369)
Two things the pages were saying about themselves rather than about their
subject.
All 120 generated API pages opened with the "auto-generated from the source
docstrings, do not edit by hand" note. That is a message to whoever might edit
the file, and it was standing where the module's own summary belongs: it was
the paragraph a search result quoted and the one the `speakable` selector
points assistants at. The summary leads now and the note follows it.
The conformance report page was typed as an article. It is a machine-generated
table with a fixed schema, regenerated by CI, downloadable at a stable URL, so
it is a Dataset, and it is the most citable object the project owns. Both
language versions now declare one, with the column schema, the download URL
and the DOI. The counts in the description are read from the report itself
rather than written out.
451 pages build, html-validate clean, i18n parity holds, the site-reports and
conformance-claims gates pass, and the three JSON-LD blocks on each
conformance page parse.
Lead the API pages with the module, and type the conformance report as data (#369)
Two things the pages were saying about themselves rather than about their
subject.
All 120 generated API pages opened with the "auto-generated from the source
docstrings, do not edit by hand" note. That is a message to whoever might edit
the file, and it was standing where the module's own summary belongs: it was
the paragraph a search result quoted and the one the `speakable` selector
points assistants at. The summary leads now and the note follows it.
The conformance report page was typed as an article. It is a machine-generated
table with a fixed schema, regenerated by CI, downloadable at a stable URL, so
it is a Dataset, and it is the most citable object the project owns. Both
language versions now declare one, with the column schema, the download URL
and the DOI. The counts in the description are read from the report itself
rather than written out.
451 pages build, html-validate clean, i18n parity holds, the site-reports and
conformance-claims gates pass, and the three JSON-LD blocks on each
conformance page parse.
Geometry drawings: to-scale device cross-sections for materials (#381)
* Geometry drawings: to-scale device cross-sections for materials
New rendering module with drafting primitives (dimension lines with
extension leaders, material fills, microphone/loudspeaker symbols,
cross-section emblems) and six to-scale drawings:
- Layered absorber stack (porous/air/perforated/MPP/membrane), with
each layer dimensioned and the hole pattern of perforated plates
drawn at its real pitch.
- Square-section Helmholtz resonator.
- One period of the slit metamaterial absorber (slow-sound panel).
- QRD well profile from qrd_well_depths.
- ISO 10534-2 impedance tube and ASTM E2611 transmission tube: side
views at true scale with microphone positions, sample, termination,
cross-section emblem and the plane-wave working range.
API: layer dataclasses and HelmholtzResonator gain .plot();
LayeredAbsorberResult, SlitResonatorAbsorberResult,
DiffuserPolarResponse, ImpedanceTubeResult and TransferMatrix gain
.plot_geometry() with the defining geometry retained on the result
(trailing optional fields, backward compatible); six public
plot_*_geometry functions cover design-time drawing before any
computation. All drawings are bilingual and validate inputs before
touching matplotlib.
24 generated SVG variants, guide embeds (EN/ES and the GitHub
mirrors) with runnable snippets, curated API table rows and generated
API pages, and 16 new tests (smoke, retention round-trips, to-scale
checks, refusal paths for hand-built results).
* Address review: QRD pitch, sequence contract, language and bounds validation
- The drawn N = 7 QRD keeps the published 3.6 m total width: an 85.7 mm
pitch split into an 80.7 mm well plus a 5 mm fin (figure, snippets and
alt texts updated).
- plot_absorber_stack and plot_slit_absorber_geometry normalise any
Sequence, matching their advertised contracts.
- The six module-level renderers validate language and reject
non-positive diameter/sample_thickness before creating any figure;
layer-type dispatch moved ahead of axes creation.
- DiffuserPolarResponse docstring: well_width/periods are always
retained by the predictor; only depths distinguishes the
explicit-reflection path.
* Address static analysis: float comparisons, literal hoist, flat conditionals
- _dim: tolerance-based checks instead of float equality for the span
and the offset.
- Incident-sound label computed once per arrow.
- Tube emblem shape extracted from the nested conditional.
- Exception tests build their fixtures outside pytest.raises.
- Regenerated API page for the DiffuserPolarResponse docstring.
Geometry drawings: secondary set-ups across building, materials and rooms (#386)
* Geometry drawings: secondary set-ups across building, materials and rooms
Nine more to-scale drawings, each with the realistic dimensions of its
standard rig or textbook case:
- Composite facade elevation with the element areas to scale
(FacadePredictionResult retains its elements).
- Mass-spring-mass double wall: 12,5 mm plasterboard leaves on a
100 mm cavity, resonance annotated (double-wall results retain
mass1/mass2/gap).
- Plate junctions L/T1/T2/X following the junction_transmission
conventions (plate 1 continuous for T1/X, the perpendicular pair
continuous for T2/X); results retain both thicknesses.
- In-situ road absorption set-up: source at 1,25 m, microphone at
0,25 m, the 1,34 m sampled radius of the 5 ms window.
- Dynamic-stiffness resonance rig: 200 mm square specimen under the
8 kg load plate.
- Free-field diffusion goniometer in plan: 37 microphones on the 5 m
arc, source at 10 m.
- Baffled radiating plate (RadiationEfficiencyResult already carries
its geometry).
- Open-plan measurement line with rD/rP marked (OpenPlanResult
retains the microphone positions).
- Face-to-face p-p intensity probe with the 12 mm spacer
(IntensityResult retains the spacing).
Nine public plot_* functions, retention fields on six results
(trailing, defaulted), 36 generated SVG variants embedded in nine
guides (EN/ES and the GitHub mirrors, including the first figures of
the junction-transmission and vibration-sound-power guides), curated
table and generated API pages updated, and 10 new tests.
* Address review: junction alt texts, retained-field docs, small guards
- The T-junction figure alt texts now name T2, matching the drawn
geometry and the runnable example.
- Retained-geometry fields documented on all six result docstrings
(and the generated API pages regenerated).
- plot_facade_elements rejects an explicit zero area instead of
silently substituting the nominal tile, and its kwargs contract now
names the first element rectangle; plot_goniometer_geometry
validates sample_width and documents it in the curated table.
- Facade prose spelling unified with the surrounding sections.
* Drop the identical-in-both-languages unit literal from the translation table
Geometry drawings: to-scale device cross-sections for materials (#381)
* Geometry drawings: to-scale device cross-sections for materials
New rendering module with drafting primitives (dimension lines with
extension leaders, material fills, microphone/loudspeaker symbols,
cross-section emblems) and six to-scale drawings:
- Layered absorber stack (porous/air/perforated/MPP/membrane), with
each layer dimensioned and the hole pattern of perforated plates
drawn at its real pitch.
- Square-section Helmholtz resonator.
- One period of the slit metamaterial absorber (slow-sound panel).
- QRD well profile from qrd_well_depths.
- ISO 10534-2 impedance tube and ASTM E2611 transmission tube: side
views at true scale with microphone positions, sample, termination,
cross-section emblem and the plane-wave working range.
API: layer dataclasses and HelmholtzResonator gain .plot();
LayeredAbsorberResult, SlitResonatorAbsorberResult,
DiffuserPolarResponse, ImpedanceTubeResult and TransferMatrix gain
.plot_geometry() with the defining geometry retained on the result
(trailing optional fields, backward compatible); six public
plot_*_geometry functions cover design-time drawing before any
computation. All drawings are bilingual and validate inputs before
touching matplotlib.
24 generated SVG variants, guide embeds (EN/ES and the GitHub
mirrors) with runnable snippets, curated API table rows and generated
API pages, and 16 new tests (smoke, retention round-trips, to-scale
checks, refusal paths for hand-built results).
* Address review: QRD pitch, sequence contract, language and bounds validation
- The drawn N = 7 QRD keeps the published 3.6 m total width: an 85.7 mm
pitch split into an 80.7 mm well plus a 5 mm fin (figure, snippets and
alt texts updated).
- plot_absorber_stack and plot_slit_absorber_geometry normalise any
Sequence, matching their advertised contracts.
- The six module-level renderers validate language and reject
non-positive diameter/sample_thickness before creating any figure;
layer-type dispatch moved ahead of axes creation.
- DiffuserPolarResponse docstring: well_width/periods are always
retained by the predictor; only depths distinguishes the
explicit-reflection path.
* Address static analysis: float comparisons, literal hoist, flat conditionals
- _dim: tolerance-based checks instead of float equality for the span
and the offset.
- Incident-sound label computed once per arrow.
- Tube emblem shape extracted from the nested conditional.
- Exception tests build their fixtures outside pytest.raises.
- Regenerated API page for the DiffuserPolarResponse docstring.
Metadiffusers: deep-subwavelength Schroeder diffusers (#397)
* Metadiffusers: deep-subwavelength Schroeder diffusers
A new materials module models the slotted panels of Jimenez, Cox,
Romero-Garcia and Groby (Sci. Rep. 7:5389, 2017): thin slits loaded by
Helmholtz resonators whose slow sound pulls the quarter-wavelength
condition of each well into the deep-subwavelength regime, so a
centimetres-thick panel reproduces the reflection-phase profile of a
Schroeder diffuser tens of centimetres deep, and critically coupled
slits provide the perfectly absorbing state of ternary sequences.
The per-well chain reuses the slow-sound absorber transfer matrix,
extended with the paper's two-dimensional resonator model: slit-geometry
visco-thermal effective parameters for necks and cavities and the 2-D
end-correction fits (0.41 w_n polynomials), selected by a new
resonator_geometry switch that keeps the square-duct model as default
elsewhere. metadiffuser_reflection returns the per-well complex R_n(f),
and metadiffuser_polar_response / metadiffuser_diffusion_spectrum reduce
it through the bare Fraunhofer far field of the paper (no obliquity
factor) to the ISO 17497-2 directional and normalized coefficients.
The tests pin the implementation to the published designs: the first
slit of the quadratic-residue panel reaches critical coupling at the
printed 2270 Hz within 1.6 %, its reflection matches the target QRD at
the 2 kHz evaluation to under 4 degrees per well, the ternary perfect
absorber peaks at alpha = 0.999 at 502 Hz, the primitive-root panel
shows its sharp slit resonance at 1505 Hz and a -19 dB specular notch,
and the diffusion coefficients of the supplementary land inside soft
bounds. Necks wider than their slit fall outside the fitted domain of
the Dubos correction and now raise a warning (the broadband Table 4
design does this by construction, so only its mid-band diffusion is
pinned).
The surface-scattering guide gains a metadiffuser section with the
published five-slit panel as a runnable example, a to-scale panel
drawing (MetadiffuserResult.plot_geometry) and a polar overlay showing
the 2 cm panel scattering like the 27.4 cm QRD it mimics.
* Metadiffuser FDTD clip: three panels meshed at 0.25 mm with GPU-first fields
The clip compares a flat rigid control slab, the 27 cm QRD and the 2 cm
metadiffuser under the same tapered 2 kHz wavefront, all in a free-field
box (sponges on the four sides; the lateral cosine taper keeps the
incident front off the side sponges, so it stays plane and the free-field
reference subtracts exactly). A unit-cell convergence check against the
transfer-matrix phase fixed the mesh at 0.25 mm, where the reflection
phase is converged to under 2 degrees; the fields run on the .env GPU
host through the fdtd_gpu runner when it answers, with a three-worker
CPU pool as the fallback.
* Address review: QRD clip loop restored, docstrings, dedup rows, plot smoke tests
The three-column edit had also widened the panel loop of the original
animate_fdtd_diffusion, which would crash its next render; the loop is
back to two panels and the function is again identical to main. The
Table-1 rows are hoisted into one shared constant, the trail reference
is guarded against a silent zero, the GPU history is preallocated, the
metadiffuser docstrings document resonator_geometry and the drawing
orientation, the citation carries the accented author names, and the
new plot renderers gained smoke tests in both languages (the SonarCloud
coverage gap) together with the hoisted constructions and helper
extractions the analysis asked for.
* Address review: regenerate the API page and hoist the last raises construction
Geometry drawings: to-scale device cross-sections for materials (#381)
* Geometry drawings: to-scale device cross-sections for materials
New rendering module with drafting primitives (dimension lines with
extension leaders, material fills, microphone/loudspeaker symbols,
cross-section emblems) and six to-scale drawings:
- Layered absorber stack (porous/air/perforated/MPP/membrane), with
each layer dimensioned and the hole pattern of perforated plates
drawn at its real pitch.
- Square-section Helmholtz resonator.
- One period of the slit metamaterial absorber (slow-sound panel).
- QRD well profile from qrd_well_depths.
- ISO 10534-2 impedance tube and ASTM E2611 transmission tube: side
views at true scale with microphone positions, sample, termination,
cross-section emblem and the plane-wave working range.
API: layer dataclasses and HelmholtzResonator gain .plot();
LayeredAbsorberResult, SlitResonatorAbsorberResult,
DiffuserPolarResponse, ImpedanceTubeResult and TransferMatrix gain
.plot_geometry() with the defining geometry retained on the result
(trailing optional fields, backward compatible); six public
plot_*_geometry functions cover design-time drawing before any
computation. All drawings are bilingual and validate inputs before
touching matplotlib.
24 generated SVG variants, guide embeds (EN/ES and the GitHub
mirrors) with runnable snippets, curated API table rows and generated
API pages, and 16 new tests (smoke, retention round-trips, to-scale
checks, refusal paths for hand-built results).
* Address review: QRD pitch, sequence contract, language and bounds validation
- The drawn N = 7 QRD keeps the published 3.6 m total width: an 85.7 mm
pitch split into an 80.7 mm well plus a 5 mm fin (figure, snippets and
alt texts updated).
- plot_absorber_stack and plot_slit_absorber_geometry normalise any
Sequence, matching their advertised contracts.
- The six module-level renderers validate language and reject
non-positive diameter/sample_thickness before creating any figure;
layer-type dispatch moved ahead of axes creation.
- DiffuserPolarResponse docstring: well_width/periods are always
retained by the predictor; only depths distinguishes the
explicit-reflection path.
* Address static analysis: float comparisons, literal hoist, flat conditionals
- _dim: tolerance-based checks instead of float equality for the span
and the offset.
- Incident-sound label computed once per arrow.
- Tube emblem shape extracted from the nested conditional.
- Exception tests build their fixtures outside pytest.raises.
- Regenerated API page for the DiffuserPolarResponse docstring.
Geometry drawings: secondary set-ups across building, materials and rooms (#386)
* Geometry drawings: secondary set-ups across building, materials and rooms
Nine more to-scale drawings, each with the realistic dimensions of its
standard rig or textbook case:
- Composite facade elevation with the element areas to scale
(FacadePredictionResult retains its elements).
- Mass-spring-mass double wall: 12,5 mm plasterboard leaves on a
100 mm cavity, resonance annotated (double-wall results retain
mass1/mass2/gap).
- Plate junctions L/T1/T2/X following the junction_transmission
conventions (plate 1 continuous for T1/X, the perpendicular pair
continuous for T2/X); results retain both thicknesses.
- In-situ road absorption set-up: source at 1,25 m, microphone at
0,25 m, the 1,34 m sampled radius of the 5 ms window.
- Dynamic-stiffness resonance rig: 200 mm square specimen under the
8 kg load plate.
- Free-field diffusion goniometer in plan: 37 microphones on the 5 m
arc, source at 10 m.
- Baffled radiating plate (RadiationEfficiencyResult already carries
its geometry).
- Open-plan measurement line with rD/rP marked (OpenPlanResult
retains the microphone positions).
- Face-to-face p-p intensity probe with the 12 mm spacer
(IntensityResult retains the spacing).
Nine public plot_* functions, retention fields on six results
(trailing, defaulted), 36 generated SVG variants embedded in nine
guides (EN/ES and the GitHub mirrors, including the first figures of
the junction-transmission and vibration-sound-power guides), curated
table and generated API pages updated, and 10 new tests.
* Address review: junction alt texts, retained-field docs, small guards
- The T-junction figure alt texts now name T2, matching the drawn
geometry and the runnable example.
- Retained-geometry fields documented on all six result docstrings
(and the generated API pages regenerated).
- plot_facade_elements rejects an explicit zero area instead of
silently substituting the nominal tile, and its kwargs contract now
names the first element rectangle; plot_goniometer_geometry
validates sample_width and documents it in the curated table.
- Facade prose spelling unified with the surrounding sections.
* Drop the identical-in-both-languages unit literal from the translation table
Geometry drawings: secondary set-ups across building, materials and rooms (#386)
* Geometry drawings: secondary set-ups across building, materials and rooms
Nine more to-scale drawings, each with the realistic dimensions of its
standard rig or textbook case:
- Composite facade elevation with the element areas to scale
(FacadePredictionResult retains its elements).
- Mass-spring-mass double wall: 12,5 mm plasterboard leaves on a
100 mm cavity, resonance annotated (double-wall results retain
mass1/mass2/gap).
- Plate junctions L/T1/T2/X following the junction_transmission
conventions (plate 1 continuous for T1/X, the perpendicular pair
continuous for T2/X); results retain both thicknesses.
- In-situ road absorption set-up: source at 1,25 m, microphone at
0,25 m, the 1,34 m sampled radius of the 5 ms window.
- Dynamic-stiffness resonance rig: 200 mm square specimen under the
8 kg load plate.
- Free-field diffusion goniometer in plan: 37 microphones on the 5 m
arc, source at 10 m.
- Baffled radiating plate (RadiationEfficiencyResult already carries
its geometry).
- Open-plan measurement line with rD/rP marked (OpenPlanResult
retains the microphone positions).
- Face-to-face p-p intensity probe with the 12 mm spacer
(IntensityResult retains the spacing).
Nine public plot_* functions, retention fields on six results
(trailing, defaulted), 36 generated SVG variants embedded in nine
guides (EN/ES and the GitHub mirrors, including the first figures of
the junction-transmission and vibration-sound-power guides), curated
table and generated API pages updated, and 10 new tests.
* Address review: junction alt texts, retained-field docs, small guards
- The T-junction figure alt texts now name T2, matching the drawn
geometry and the runnable example.
- Retained-geometry fields documented on all six result docstrings
(and the generated API pages regenerated).
- plot_facade_elements rejects an explicit zero area instead of
silently substituting the nominal tile, and its kwargs contract now
names the first element rectangle; plot_goniometer_geometry
validates sample_width and documents it in the curated table.
- Facade prose spelling unified with the surrounding sections.
* Drop the identical-in-both-languages unit literal from the translation table
Metadiffusers: deep-subwavelength Schroeder diffusers (#397)
* Metadiffusers: deep-subwavelength Schroeder diffusers
A new materials module models the slotted panels of Jimenez, Cox,
Romero-Garcia and Groby (Sci. Rep. 7:5389, 2017): thin slits loaded by
Helmholtz resonators whose slow sound pulls the quarter-wavelength
condition of each well into the deep-subwavelength regime, so a
centimetres-thick panel reproduces the reflection-phase profile of a
Schroeder diffuser tens of centimetres deep, and critically coupled
slits provide the perfectly absorbing state of ternary sequences.
The per-well chain reuses the slow-sound absorber transfer matrix,
extended with the paper's two-dimensional resonator model: slit-geometry
visco-thermal effective parameters for necks and cavities and the 2-D
end-correction fits (0.41 w_n polynomials), selected by a new
resonator_geometry switch that keeps the square-duct model as default
elsewhere. metadiffuser_reflection returns the per-well complex R_n(f),
and metadiffuser_polar_response / metadiffuser_diffusion_spectrum reduce
it through the bare Fraunhofer far field of the paper (no obliquity
factor) to the ISO 17497-2 directional and normalized coefficients.
The tests pin the implementation to the published designs: the first
slit of the quadratic-residue panel reaches critical coupling at the
printed 2270 Hz within 1.6 %, its reflection matches the target QRD at
the 2 kHz evaluation to under 4 degrees per well, the ternary perfect
absorber peaks at alpha = 0.999 at 502 Hz, the primitive-root panel
shows its sharp slit resonance at 1505 Hz and a -19 dB specular notch,
and the diffusion coefficients of the supplementary land inside soft
bounds. Necks wider than their slit fall outside the fitted domain of
the Dubos correction and now raise a warning (the broadband Table 4
design does this by construction, so only its mid-band diffusion is
pinned).
The surface-scattering guide gains a metadiffuser section with the
published five-slit panel as a runnable example, a to-scale panel
drawing (MetadiffuserResult.plot_geometry) and a polar overlay showing
the 2 cm panel scattering like the 27.4 cm QRD it mimics.
* Metadiffuser FDTD clip: three panels meshed at 0.25 mm with GPU-first fields
The clip compares a flat rigid control slab, the 27 cm QRD and the 2 cm
metadiffuser under the same tapered 2 kHz wavefront, all in a free-field
box (sponges on the four sides; the lateral cosine taper keeps the
incident front off the side sponges, so it stays plane and the free-field
reference subtracts exactly). A unit-cell convergence check against the
transfer-matrix phase fixed the mesh at 0.25 mm, where the reflection
phase is converged to under 2 degrees; the fields run on the .env GPU
host through the fdtd_gpu runner when it answers, with a three-worker
CPU pool as the fallback.
* Address review: QRD clip loop restored, docstrings, dedup rows, plot smoke tests
The three-column edit had also widened the panel loop of the original
animate_fdtd_diffusion, which would crash its next render; the loop is
back to two panels and the function is again identical to main. The
Table-1 rows are hoisted into one shared constant, the trail reference
is guarded against a silent zero, the GPU history is preallocated, the
metadiffuser docstrings document resonator_geometry and the drawing
orientation, the citation carries the accented author names, and the
new plot renderers gained smoke tests in both languages (the SonarCloud
coverage gap) together with the hoisted constructions and helper
extractions the analysis asked for.
* Address review: regenerate the API page and hoist the last raises construction
Lead the API pages with the module, and type the conformance report as data (#369)
Two things the pages were saying about themselves rather than about their
subject.
All 120 generated API pages opened with the "auto-generated from the source
docstrings, do not edit by hand" note. That is a message to whoever might edit
the file, and it was standing where the module's own summary belongs: it was
the paragraph a search result quoted and the one the `speakable` selector
points assistants at. The summary leads now and the note follows it.
The conformance report page was typed as an article. It is a machine-generated
table with a fixed schema, regenerated by CI, downloadable at a stable URL, so
it is a Dataset, and it is the most citable object the project owns. Both
language versions now declare one, with the column schema, the download URL
and the DOI. The counts in the description are read from the report itself
rather than written out.
451 pages build, html-validate clean, i18n parity holds, the site-reports and
conformance-claims gates pass, and the three JSON-LD blocks on each
conformance page parse.