Correct what the guides get wrong, and show the clips already rendered - #508
Merged
Conversation
Two passes over the English documentation. The first fixes statements that are false, not merely thin, and the numbers they carry. A band-edge claim held for every filter family when it is true of two of five, costing a systematic +0.3 dB on band levels; a tone assessment that skipped a clause and under-reported its own worked example by 4.2 dB; a source level fed to a function expecting a received spectrum; a party wall checked in R'A against a requirement written in DnT,A, now re-referenced through the equivalent absorption area; an uncertainty that flipped a Directive verdict. Where the proposal behind a fix was itself wrong, the measured value is what got written: lowering the design ripple widens the Chebyshev and elliptic band-level bias rather than narrowing it, and raising the order is the remedy; an event-to-background ratio is 35:1, not 350:1; a first-order decay is within 1 dB after 1.58 tau, not 2.3. Three generated plates taught the error to every reader. The ISO 2631-5 chart printed a band limiting the standard says must not be applied, the ISO/TS 7849-1 chart doubled its measurement position counts, and the installed structure-borne figure carried a positive D_sa, which put a service-equipment prediction at levels no such prediction can reach. All three builders are corrected and the plates regenerated in their four variants, Spanish strings included. EN 15657 normalises a mass per unit area against a reference printed as 1 kg, which leaves a stray inverse square metre in the argument of the logarithm. The numeric result is unaffected, which is why a worked example does not catch it. Filed in the errata registry against both printed pages the paragraph straddles, and noted beside the reference in the docstring. The second pass files assets the project already renders and never showed. The two guides that document the FDTD engine embedded no animation while the project ships nineteen clips from it; the theory pages argued in prose what their own figures draw. Nine clips and thirty-four figures now sit on the pages that need them, captions and reproduction blocks included. The Spanish edition keeps parity of pages and figures; its prose is pending.
The Spanish pages carried the claims the English edition had just stopped standing behind, which is the worst state for a bilingual manual to sit in: a reader who switches language switches to worse information without being told. Ninety-three pages now say the same thing in both languages, section for section and number for number. The corrections that mattered most: the band edge claim is no longer stated for all five filter architectures, and the bias table and the note that lowering the ripple widens it while raising the order shrinks it arrive with it; the installed structure-borne adjustment term is negative, which moves a prediction that sat 20 to 40 dB low; a party wall is re-referenced through the equivalent absorption area before being compared with a requirement written in a different quantity; the tonal adjustment is attributed to the 2007 annex rather than the 2017 edition; the flow resistivity of a resilient layer is read in the units the function expects, which was silently landing in the wrong branch of the model; an event-to-background ratio reads 35:1 rather than 350:1. Three animations and the figures added on the English side arrive with their Spanish variants, their alt text translated and their titles and descriptions written for a screen reader rather than transliterated. Snippet comments and printed strings are Spanish, plot calls pass language="es", and the imported names still match their English twins exactly, which is what the snippet gate checks. Two pre-existing divergences are recorded rather than fixed, because neither belongs to this change: the See also lists point into the theory pages in English only, and a few Spanish link texts drifted from the wording the rest of the Spanish tree uses.
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @jmrplens, your pull request is larger than the review limit of 150000 diff characters
|
Important Review skippedToo many files! This PR contains 246 files, which is 146 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (20)
📒 Files selected for processing (246)
You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
github-actions
Bot
added
documentation
Reviewer's GuideDocs and guides were updated across both English and Spanish editions to correct technically wrong statements, align with the latest standards, explain subtle implementation details (especially for field insulation, filter banks, open‑plan acoustics, intensity, underwater propagation, and structure‑borne sound), and surface previously unused figures/videos and assets, while keeping EN/ES parity and adding accessibility‑friendly captions. Sequence diagram for corrected field airborne insulation measurement chainsequenceDiagram
actor Operator
participant numpy as numpy
participant building as building
Operator->>numpy: measure L1, L2_sb, L2_bg per mic position
Operator->>numpy: compute margin = L2_sb - L2_bg
numpy-->>Operator: corrected L2 (Clause_9_2_expression)
Operator->>building: energy_average_level(L1_positions, axis=0)
Operator->>building: energy_average_level(L2_corrected_positions, axis=0)
building-->>Operator: band_levels_L1, band_levels_L2
alt multiple_loudspeakers_simultaneous
Operator->>building: airborne_insulation(L1, L2, T2, area=S, volume=V)
building-->>Operator: AirborneInsulationResult(d, dnt, r_prime)
else single_loudspeaker_moved_between_positions
loop per_loudspeaker_position
Operator->>building: airborne_insulation(L1_pos_j, L2_pos_j, T2, area=S, volume=V)
building-->>Operator: AirborneInsulationResult(d_j, dnt_j, r_prime_j)
end
Operator->>numpy: combine dnt_j via Formula_6
numpy-->>Operator: combined_DnT_spectrum
end
Operator->>building: weighted_rating(DnT_or_R_prime_spectrum)
building-->>Operator: WeightedRatingResult(rating, adaptation_terms)
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #508 +/- ##
=======================================
Coverage 97.05% 97.05%
=======================================
Files 295 295
Lines 39146 39146
=======================================
Hits 37992 37992
Misses 1154 1154 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
A line of prose that happens to wrap onto a "- " or a "> " is not prose any more: CommonMark reads it as a list item or a block quote and ends the paragraph there. Four places did. The worst broke the build. An inline formula for the flanking impact level wrapped so the continuation began with the minus before K_ij, which closed the paragraph before the closing dollar, left the maths unparsed, and handed MDX the subscript braces to evaluate as JavaScript. The page failed to render with "n is not defined", n being the first subscript in L_n,ij,w. The other three are silent, which is worse to find later: the flow resistivity of asphalt and concrete, in both languages, and the uncertainty above 16 kHz in the Spanish underwater guide, each turned the tail of a sentence into a quoted block. All four are rewrapped so the marker character no longer starts a line. The llms artifacts follow the pages they are built from.
The four rewrapped paragraphs were found by reading a stack trace and then grepping for the shape of the thing that caused it. Nothing would have caught the next one, and one of the two variants leaves no trace at all. The check reads every hand-written page in both trees and reports two shapes. An inline formula that wraps onto a block marker never closes, because the marker ends the paragraph first: the maths is published as literal text, and in MDX the subscript braces become a JavaScript expression, so the page does not render. A ">" starting a line whose predecessor is ordinary prose is a comparison operator that wrapped, and it turns the tail of a sentence into a quoted block, silently. A list marker is only reported when it interrupts open maths. A list that follows its introducing line without a blank line is ordinary here (3830 of them) and is not a defect, so the unconditional rule would have been noise. The ">" rule needs no such qualification: a deliberate quotation is preceded by a blank line, and the corpus has no other case. Verified by reintroducing each of the four defects in turn and watching the check go red on it, then removing them and watching it go green over 467 pages. It found a fifth on its first run, in the porous absorbers mirror, where a Fok end-correction wrapped onto the plus sign of its own polynomial.
Contributor
Numerical conformance report✅ 533/533 conformance checks pass across 57 domains and 362 standards - filters class 1 - weightings within IEC 61672-1 class 1. Each row pins a standard clause to its expected normative value and the value the library computes. Every section below is collapsible and stays collapsed while all of its rows pass; a section with any failing row opens automatically. ✅ Numerical validation - filters & weightings: class showcase (IEC 61260-1 · IEC 61672-1 · ISO 7196)IEC 61260-1:2014 class per filter architecture (order 6, one-third-octave, 100 Hz-10 kHz, fs = 48 kHz). For each architecture the table shows, at its binding band, the measured relative attenuation and the class-1 limit it must clear, so the number and the range it must sit in are both visible. A positive margin means the acceptance limits are met with that much room.
Only Butterworth (the library default) and Chebyshev-II are class-compliant architectures. Chebyshev-I and elliptic trade the mask for passband ripple, and Bessel for a maximally-flat group delay (soft rolloff); they cannot satisfy the IEC 61260-1 Class 1/2 attenuation mask by construction, so they are labelled By design - this is expected, not a failure or regression. Frequency-weighting conformance (A/C: IEC 61672-1 Table 3; G: ISO 7196 A.3). The max deviation from nominal is informational (it falls at a frequency extreme where the tolerance is widest and asymmetric); compliance is judged at the binding frequency - the one with the least headroom - where the deviation, the applicable tolerance band and the headroom are shown together.
✅ Filters & weightings: 100% (10/10)
✅ Levels & dosimetry: 100% (9/9)
✅ Room & building acoustics: 100% (72/72)
✅ Room acoustics: 100% (16/16)
✅ Psychoacoustics: 100% (14/14)
✅ Speech transmission (IEC 60268-16): 100% (10/10)
✅ System measurement (Golay / Kirkeby / Mueller-Massarani): 100% (5/5)
✅ Intensity & sound power: 100% (10/10)
✅ Building prediction & uncertainty: 100% (15/15)
✅ Outdoor propagation & occupational exposure: 100% (10/10)
✅ Materials: absorption, airflow & impedance: 100% (6/6)
✅ Scattering & diffusion (ISO 17497): 100% (14/14)
✅ In-situ road absorption (ISO 13472): 100% (3/3)
✅ Precision sound power (ISO 3745 / 9614-3): 100% (4/4)
✅ Human vibration (ISO 8041 / 2631 / 5349): 100% (15/15)
✅ Speech intelligibility (ANSI S3.5-1997): 100% (24/24)
✅ Objective intelligibility (STOI / ESTOI): 100% (3/3)
✅ Impulsive-sound prominence (NT ACOU 112): 100% (2/2)
✅ Impulsive-sound prominence (ISO/PAS 1996-3): 100% (2/2)
✅ Room noise (ANSI S12.2-2019): 100% (3/3)
✅ Hearing threshold (ISO 7029 / ISO 389-7): 100% (3/3)
✅ Measurement uncertainty (GUM / Supplement 1): 100% (7/7)
✅ Noise-induced hearing loss (ISO 1999): 100% (6/6)
✅ Multiple-shock whole-body vibration (ISO 2631-5): 100% (6/6)
✅ Sound absorption in enclosed spaces (EN 12354-6): 100% (2/2)
✅ Prominent discrete tones (ECMA-418-1): 100% (2/2)
✅ Tonal audibility (ISO/PAS 20065): 100% (11/11)
✅ Psychoacoustic annoyance & fluctuation strength (Fastl & Zwicker): 100% (3/3)
✅ Electroacoustics: distortion & frequency response: 100% (20/20)
✅ Calibrated spectral analysis (Bendat & Piersol): 100% (12/12)
✅ Multiple-input coherence (Bendat & Piersol): 100% (5/5)
✅ Time-frequency analysis (Bendat & Piersol): 100% (3/3)
✅ Correlation, time delay and envelope (B&P / Knapp & Carter): 100% (7/7)
✅ Cepstrum, liftering and envelope spectrum (Havelock / B&P): 100% (3/3)
✅ Time synchronous averaging (McFadden 1987): 100% (5/5)
✅ Data qualification and Rice statistics (Bendat & Piersol): 100% (8/8)
✅ Underwater acoustics (ISO 18405/17208/18406): 100% (6/6)
✅ Underwater sound propagation (transmission loss): 100% (16/16)
✅ Underwater propagation regimes (Weston flux theory): 100% (3/3)
✅ Marine-mammal auditory weighting (NMFS / Southall): 100% (4/4)
✅ Underwater numerical propagation (modes / rays / PE): 100% (4/4)
✅ Aircraft noise (ICAO Annex 16 / IEC 61265): 100% (15/15)
✅ Rotorcraft noise (ECAC Doc 32 / NORAH2): 100% (12/12)
✅ CNOSSOS-EU road source (Directive 2002/49/EC Annex II): 100% (6/6)
✅ Wind-turbine noise (IEC 61400-11): 100% (3/3)
✅ Porous & multilayer absorbers (Mechel / Bies / Cox & D'Antonio): 100% (20/20)
✅ Slow-sound perfect absorbers (Jimenez et al. Appl. Sci. 2017): 100% (3/3)
✅ Program loudness (ITU-R BS.1770 / EBU R 128): 100% (8/8)
✅ 2D FDTD wave simulation (Attenborough & Van Renterghem 2021, Ch. 4): 100% (4/4)
✅ Swept-sine distortion & phase utilities (Farina / Novak): 100% (7/7)
✅ Spherical ground & barriers (Attenborough / Salomons / Bies): 100% (7/7)
✅ Panel & aperture sound insulation (Bies / Hopkins / Cremer): 100% (17/17)
✅ Bending-wave plate-junction transmission (Cremer / Craik / Hopkins): 100% (6/6)
✅ Atmospheric refraction (Salomons rays / GFPE): 100% (3/3)
✅ Electroacoustics: 100% (9/9)
✅ Industrial noise control: 100% (22/22)
✅ CNOSSOS-EU railway source (Directive 2002/49/EC Annex II): 100% (8/8)
Tests & coverage — 48204 tests, 0 failures (✅ all green)
Conformance harness: |
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
1 similar comment
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
Markdown percent-encodes non-ASCII in a URL, so a same-page link written as [La medición](#la-medición-apartados-7-y-9-de-iso-16283-1) ships as href="#la-medici%C3%B3n-...", while the heading keeps its id with the accent intact. A browser resolves that; the accessibility audit compares the raw attribute against the ids on the page and calls it a dangling anchor. Only Spanish is affected, because English headings have no accents to encode. Six links across five pages. The corpus already answered this twice, with an ASCII <span id="..."> above the heading, and the two pages that carried the span were still linking past it. The other four have one now. The audit samples 66 URLs, so it reported two of the six. The check added here reads all 467 pages instead, and gains this as its third rule: what it reports is markdown whose source reads one way and renders another, which is the one class of defect that survives review by looking correct. Renamed to match. The llms artifacts follow the pages.
|
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
1 similar comment
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A review of the English guides turned up a set of statements that are false rather than merely thin, and a set of assets the project renders and never shows. This is both, in both languages.
Statements that were wrong
Each of these is verified against the implementation and the clause it comes from, and the replacement value was recomputed rather than copied from the review:
R'Aagainst a requirement written inDnT,A. It is now re-referenced through the equivalent absorption area,A = 0.16 V / T, before the comparison.Three generated plates taught the error
D_sa, which put a service-equipment prediction at levels no such prediction reaches. With the Annex I values it moves from [18.9 ... -25.4] dB to [40.3 ... 22.7] dB.All three builders are corrected and the plates regenerated in their four variants, Spanish strings included.
Errata
EN 15657 normalises a mass per unit area against a reference printed as 1 kg, leaving a stray inverse square metre inside the logarithm. The numeric result is unaffected, which is why a worked example does not catch it. Filed against both printed pages the paragraph straddles, read as images rather than extracted text, and noted beside the reference in the docstring. Only the Spanish adoption was available, and the entry says so.
Assets that existed and were never shown
The two guides documenting the FDTD engine embedded no animation while the project ships nineteen clips from it. The theory pages argued in prose what their own figures draw. Nine clips and thirty-four figures now sit on the pages that need them, with captions and reproduction blocks.
Both languages
The Spanish edition carried the claims the English edition had just stopped standing behind. Ninety-three pages are level again, section for section and number for number, with the new figures pointing at their
_esvariants and animation titles and descriptions written for a screen reader rather than transliterated.Checks
ruff,mypy, the snippet gate (3673 blocks over 508 pages), EN/ES parity, the overview mirrors, the site report transplant, the conformance report and the errata evidence check all pass on the branch as it stands.Summary by Sourcery
Align documentation in English and Spanish with the implemented standards and engines, correcting previously incorrect statements, clarifying measurement chains and model usage, and adding richer examples, figures and animations across acoustics, vibration, underwater, environmental and simulation topics, while fixing specific errors in filter, structure-borne, survey, shock, underwater and building-code guidance.
New Features:
open_plan_metrics.Bug Fixes:
Enhancements:
Documentation: