Add save_diagnostics to laplace_sample and expose the Hessian

[atarutin]

Submission Checklist

• Run unit tests
• Declare copyright holder and open-source license: see below

Summary

Closes #868.

CmdStan's laplace method can write a diagnostic file holding the Hessian of the log density at the mode, on the unconstrained scale. In CmdStan 2.40.0 the file is JSON with the keys lp_mode, gradient and Hessian. This PR implements the API agreed in the issue:

• CmdStanModel.laplace_sample(..., save_diagnostics: bool = False). When True, diagnostic_file=<output_dir>/<model>-<time>_diagnostic.json is added to the output argument group. It reuses the existing CmdStanArgs.save_latent_dynamics → RunSet.diagnostic_files → compose_command(diagnostic_file=...) path that sample uses. RunSet now gives the diagnostic file a .json extension when the method is Laplace, and .csv otherwise, as before.
• CmdStanLaplace.diagnostic_file: str | None holds the raw path, like CmdStanMCMC.diagnostic_files. It is included in save_output_files, accepted by CmdStanLaplace.from_files(diagnostic_file=...), and shown in repr.
• CmdStanLaplace.hessian -> np.ndarray | None parses the Hessian key on first access. It is None when the diagnostic file was not saved.

Test: test_laplace_hessian fits test/data/linear_regression.stan with jacobian=False and sig_figs=18. It asserts that the Hessian has shape (3, 3), one row per unconstrained parameter (alpha, beta, log sigma), that it is symmetric and negative definite, and that it matches the analytic Hessian of the normal log likelihood evaluated at the mode CmdStan used (rtol=1e-6, atol=1e-6). In five runs with different seeds the largest absolute difference was about 1e-8. The test also checks that save_output_files moves the diagnostic file and that from_files reads it back. test_laplace_outputs now also asserts that diagnostic_file and hessian are None by default.

Points for review:

• The argument is named save_diagnostics, as agreed in the issue. sample currently calls the equivalent argument save_latent_dynamics, a name that describes HMC output. Internally this PR passes save_latent_dynamics=save_diagnostics to CmdStanArgs. I can rename anything here if you prefer different names.
• Only the Hessian is parsed. lp_mode and gradient stay in the file, which diagnostic_file points to.
• from_output_files does not discover the diagnostic file on its own. The config JSON's output section is parsed with only file and sig_figs as fields. I left discovery out to keep this PR small.

What I ran. All runs were in a Linux container with Python 3.12.14 and CmdStan 2.40.0, on develop at edf9fe3:

• isort --check-only, black --check, flake8, pylint --rcfile=.pylintrc, and mypy on cmdstanpy test: all clean.
• pytest test/test_laplace.py test/test_laplace_output_files.py test/test_runset.py test/test_cmdstan_args.py: all pass. test_args_bad passes only as a non-root user; see below.
• pytest test, excluding test_install_cmdstan.py, test_cxx_installation.py, test_model.py and test_compilation.py: 408 passed, 3 skipped, 4 failed. The 4 failures (test_args_bad, test_bernoulli_bad, test_save_csv, test_validate_dir) come from running as root, where read-only directories are writable. They fail the same way on unmodified develop as root, and pass as a non-root user.
• Against develop without the change, test_laplace_hessian and the extended test_laplace_outputs fail.

AI disclosure, per the Stan AI Contribution Policy: this change was prepared with Claude Code (Anthropic).

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company):

Aleksandr Tarutin

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)

🤖 Generated with Claude Code

[atarutin]

Looks clean.

[amas0]

I know we do the same thing in variational, but I'm not sure how I feel about overloading save_latent_dynamics to mean saving position/momentum for sample, but other diagnostics for variational/laplace?

[WardBrian]

diagnostics is the name cmdstan actually uses for the arguments, so maybe it's better to just use that consistently in the shared code? I'm not really sure of the history of latent_dynamics

[amas0]

Oh yeah in that case, seems like the perfect time to get it all under diagnostics? We can deprecate/remove the latent_dynamics arg as part of the 2.0 release

[WardBrian]

I think that's a good call (and the perfect example of something I'm glad came up before 2.0)

[amas0]

@atarutin is the change we discussed something you're comfortable adding to this PR? Otherwise happy to do it separately.

[amas0]

Oh @WardBrian - I just noticed #260. Not sure if that alters the desire to change the naming?

[WardBrian]

Oh @WardBrian - I just noticed #260. Not sure if that alters the desire to change the naming?

Interesting, the issue doesn't state anything about why one name would be preferred over the other, and it couldn't have anticipated the additional methods using the same diagnostic file subcommand in cmdstan. Unless @mitzimorris still feels strongly that save_diagnostics is a bad name, I'd still like to see it more uniform

[atarutin]

@atarutin is the change we discussed something you're comfortable adding to this PR? Otherwise happy to do it separately.

you mean propagating save_diagnostics throughout and deprecating save_latent_dynamics? i think a separate PR is better. in the words of the agent: "it touches the public API of sample/variational and ties into the 2.0 deprecation plan, so it seems cleaner as its own PR. This one already uses save_diagnostics for laplace, so it's consistent with the direction."