Skip to content

docs: add literature references throughout the code (closes #3)#5

Merged
jankoslavic merged 1 commit into
fix/random-fds-factor-2from
docs/code-references
Jun 24, 2026
Merged

docs: add literature references throughout the code (closes #3)#5
jankoslavic merged 1 commit into
fix/random-fds-factor-2from
docs/code-references

Conversation

@jasasonc

Copy link
Copy Markdown
Collaborator

Closes #3.

Currently the references live only in the README. This adds the literature citations into the code so the theory behind each formula is discoverable at the point of use.

What was added

  • Module-level bibliography in spectrum.py and tools.py — Lalanne, Mechanical Vibration and Shock Analysis, Vol. 1/3/4/5 (2009, ISTE/Wiley) and Thomson, with consistent [LalanneN]/[Thomson] reference keys.
  • Spectrum class docstring mapping each signal type (sine / sine-sweep / random-PSD / random-time) to its governing equation.
  • Per-method and inline references with exact equation numbers:
    • sine ERS → eq [1.7], FDS → eq [3.19]
    • sine-sweep ERS → eqs [1.31]–[1.33], FDS → eq [3.65] + dwell weighting Table 3.2
    • random-PSD: segmented response RMS → eq [8.86], I0/I2/I4 closed forms → App. A6 ([A6.20]/[A6.22]/[A6.24]), n0 → eq [5.76], FDS → eq [4.41]/[4.7]–[4.8]
    • random-time FDS → eq [4.6]; damped SDOF impulse response (Thomson)

Corrections to pre-existing citations

  • Sine-sweep ERS comments cited Vol. 1 "[1.21]/[1.22]/[1.23], p.31-32" — the correct source is Vol. 5 eqs [1.31]/[1.32]/[1.33], p.16 (the below-/above-band tags were also swapped).
  • Random-PSD FDS cited "Vol. 0 … (A1-93)" → replaced with Vol. 4 eq [4.41] = Vol. 5 eqs [4.7]–[4.8].
  • response_relative_displacement cited Thomson eq (4.2-5), which is the undamped kernel; clarified that the code implements the damped impulse response.

Notes

  • Documentation only — no behaviour change. Full test suite passes (10 passed).
  • Stacked on fix/random-fds-factor-2, so the random-FDS reference comments describe the corrected n0/full-cycle formulas. Base this PR on that branch (or rebase onto master once the fix lands).

Add in-code citations to the underlying theory so the references are not
confined to the README.

- spectrum.py / tools.py: add a module-level References bibliography
  (Lalanne Mechanical Vibration and Shock Analysis, Vol. 1/3/4/5, 2009,
  + Thomson) with consistent [LalanneN]/[Thomson] keys.
- Spectrum class docstring maps each signal type to its governing equation.
- Per-method/inline references with exact equation numbers for the sine,
  sine-sweep, random-PSD and random-time ERS/FDS formulae, the segmented-PSD
  response RMS (eq [8.86]), the I0/I2/I4 closed forms (App. A6), and the
  damped SDOF impulse response.

Also corrects several pre-existing inaccurate citations:
- sine-sweep ERS comments cited Vol.1 "[1.21]/[1.22]/[1.23], p.31-32"; the
  correct source is Vol.5 eqs [1.31]/[1.32]/[1.33], p.16 (branch tags were
  also swapped).
- random-PSD FDS cited "Vol. 0 ... (A1-93)"; replaced with Vol.4 eq [4.41]
  = Vol.5 eqs [4.7]-[4.8].
- response_relative_displacement cited Thomson eq (4.2-5), the undamped
  kernel; clarified that the code implements the damped impulse response.

Documentation only; no behaviour change. Full test suite passes.
@jankoslavic jankoslavic merged commit a3d27ff into fix/random-fds-factor-2 Jun 24, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants