Improve API for AD testing

[penelopeysm]

This PR makes some fairly overdue improvements to the API of DynamicPPL.TestUtils.AD.run_ad.

rng argument

A rng keyword argument is provided to make it easier to seed the parameters used for running AD. Previously, if you wanted to make sure that two calls to run_ad used the same parameters (but you didn't care what parameters they were, just that they were the same!), you had to do:

rng = Xoshiro(468)
v = DynamicPPL.link(VarInfo(rng, model), model)
xs = v[:]

run_ad(model, adtype1; varinfo=v, params=xs)
run_ad(model, adtype2; varinfo=v, params=xs)

Now you can do:

run_ad(model, adtype1; rng=Xoshiro(468))
run_ad(model, adtype2; rng=Xoshiro(468))

I made rng a keyword argument rather than a positional argument because I consider rng-as-first-argument to be a multiple dispatch abuse anti-pattern, i.e., it serves no purpose except to force someone to declare a new method.

Closes #962

Correctness testing

Previously the test, reference_backend, and expected_value_and_grad keyword arguments all served the same purpose and it was not clear when one would supersede the other (e.g. if you put test=false, reference_backend=AutoForwardDiff(), and expected_value_and_grad=(value, grad) it was unclear whether it would skip testing, compare against ForwardDiff, or compare against the explicitly specified values).

I originally made this design choice to avoid having to make my own types (which would be some boilerplate and annoying for downstream users to import), but over the course of using this function (especially in ADTests) I have found the annoyance of not having a clear API to be bigger than the annoyance of adding some more imports.

This PR fixes it so that you can't specify multiple of these at the same time.

Tolerances

Previously, it was only possible to specify the atol used for testing; rtol could not be configured (and would default to zero, because that's what isapprox does when given a non-zero atol). This caused problems such as TuringLang/ADTests#33. This PR fixes it such that testing happens with nonzero atol and rtol (which can both be configured).

Closes #963

[github-actions]

Benchmark Report for Commit 6a4b83c

Computer Information

Julia Version 1.11.5
Commit 760b2e5b739 (2025-04-14 06:53 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 4 × AMD EPYC 7763 64-Core Processor
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, znver3)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)

Benchmark Results

|                 Model | Dimension |  AD Backend |      VarInfo Type | Linked | Eval Time / Ref Time | AD Time / Eval Time |
|-----------------------|-----------|-------------|-------------------|--------|----------------------|---------------------|
| Simple assume observe |         1 | forwarddiff |             typed |  false |                  8.3 |                 1.6 |
|           Smorgasbord |       201 | forwarddiff |             typed |  false |                671.5 |                39.2 |
|           Smorgasbord |       201 | forwarddiff | simple_namedtuple |   true |                421.2 |                51.1 |
|           Smorgasbord |       201 | forwarddiff |           untyped |   true |               1001.0 |                34.4 |
|           Smorgasbord |       201 | forwarddiff |       simple_dict |   true |               6762.2 |                23.6 |
|           Smorgasbord |       201 | reversediff |             typed |   true |               1067.4 |                38.5 |
|           Smorgasbord |       201 |    mooncake |             typed |   true |               1031.3 |                 4.2 |
|    Loop univariate 1k |      1000 |    mooncake |             typed |   true |               5902.5 |                 3.9 |
|       Multivariate 1k |      1000 |    mooncake |             typed |   true |                993.1 |                 9.0 |
|   Loop univariate 10k |     10000 |    mooncake |             typed |   true |              66593.9 |                 3.5 |
|      Multivariate 10k |     10000 |    mooncake |             typed |   true |               8694.8 |                10.0 |
|               Dynamic |        10 |    mooncake |             typed |   true |                134.5 |                11.8 |
|              Submodel |         1 |    mooncake |             typed |   true |                 12.9 |                 6.3 |
|                   LDA |        12 | reversediff |             typed |   true |               1493.6 |                 1.9 |

[codecov]

Codecov Report

Attention: Patch coverage is 64.70588% with 6 lines in your changes missing coverage. Please review.

Project coverage is 82.69%. Comparing base (57a53e1) to head (6a4b83c).
Report is 1 commits behind head on breaking.

Files with missing lines	Patch %	Lines
src/test_utils/ad.jl	64.70%	6 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           breaking     #964      +/-   ##
============================================
- Coverage     82.78%   82.69%   -0.10%     
============================================
  Files            38       38              
  Lines          4015     4022       +7     
============================================
+ Hits           3324     3326       +2     
- Misses          691      696       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

DynamicPPL.jl documentation for PR #964 is available at:
https://TuringLang.github.io/DynamicPPL.jl/previews/PR964/

[mhauru]

Let me know if this is ready for review.

[penelopeysm]

Oops, I forgot about this one. Yeah I think it should be