Fix FirstOrder(lowpass=false) docstring to match k*sT/(sT+1)

[ChrisRackauckas-Claude]

Summary

FirstOrder(lowpass=false) documented Y/U = (sT + 1 - k)/(sT + 1) while the equations implement Y/U = k*sT/(sT + 1) (DC gain 0, high-frequency gain k). Those formulas agree only for k = 1. This PR updates the docstring to the implemented transfer function and adds a regression test against the analytical unit-step response y(t) = k*exp(-t/T) with a tolerance derived from the solver tolerances, plus a docstring check.

Reviewer note: Changing the implementation to match the old docstring would be a behaviour change (non-zero DC gain for k ≠ 1) and needs an explicit maintainer decision. This PR only fixes the documentation to match current behaviour.

Failing before / passing after

With the test change present and the src docstring fix stashed:

Test Summary: | Pass  Fail  Total     Time
PT1           |    6     2      8  6m49.8s

(docstring assertions failed: missing k*sT, still contained sT + 1 - k)

With the docstring fix restored:

Test Summary: | Pass  Total     Time
PT1           |    8      8  5m41.2s

Validation

• Runic formatted src/Blocks/continuous.jl and test/continuous.jl
• typos clean on those files
• GROUP=Core via Pkg.test — passed (Core/continuous.jl | 80 80; overall Testing ModelingToolkitStandardLibrary tests passed)

Tail of Core run:

Test Summary:      | Pass  Total     Time
Core/continuous.jl |   80     80  1m22.0s
...
Test Summary: | Pass  Total  Time
Core/utils.jl |   14     14  6.9s
     Testing ModelingToolkitStandardLibrary tests passed

Not verified

• Full docs build (no docs/ source change; docs/src/API/blocks.md only uses @docs FirstOrder)
• Downstream packages / registered release version
• Whether any external docs/tutorials copy the old (sT+1-k)/(sT+1) formula

What a reviewer should push back on

• Whether the intended high-pass should instead be (sT+1-k)/(sT+1) (behaviour change) rather than documenting k*sT/(sT+1)
• Whether the docstring assertion belongs in the sim test or a separate docs/QA check
• Whether tol = 100 * max(abstol, reltol * abs(k)) is the preferred solver-derived tolerance scale

Fixes #515

Please ignore this draft until reviewed by @ChrisRackauckas.

Risk assessment

• Risk: low
• Blast radius: documentation only in src/. The FirstOrder(lowpass=false) docstring now states the implemented transfer function k*s*T/(s*T+1), and the equations are untouched. A test covers the high-pass step response.
• Evidence: the new analytic test (step response k*exp(-t/T) with a 100× margin over the solver tolerances) passes. Measured error is 4.9e-8 at tol 1e-6. docs/src/API/blocks.md pulls in the docstring, so the rendered docs pick up the fix.
• Independent review: Claude Code (Opus 5.5; the author is Cursor Auto) rated it low with high confidence: docs-only, and the implemented formula is correct for the equations. Verdict CHANGES (minor test cleanup). The follow-up commit 262360f was checked by the head session and does exactly what was asked.
• Merge: auto-merge candidate once CI is green. Reviewer note: the documented and implemented formulas agree only at k = 1. Changing the implementation instead would be a behaviour change and was deliberately not done.

🤖 Generated with Cursor Agent CLI 2026.09.26-dd393fe (model: auto), transcript /home/crackauc/sandbox/goals/issue-backlog/jobs/fix-ModelingToolkitStandardLibrary.jl-515/log.txt on amdci2.julia.csail.mit.edu

Made with Cursor

Risk assessment and review coordination by 🤖 Claude Code (model: claude-opus-5-5[1m]), https://claude.ai/code/session_01NdFVhANTF4nepTbqYxjfRP