Add flag to print compiler's over-approximation of factor graph

[collin-cademartori]

Submission Checklist

• Run unit tests
• Documentation
  • If a user-facing facing change was made, the documentation PR is here:
  • OR, no user-facing changes were made

Summary

Adds a debug flag that causes the compiler to compute and print it's factor graph approximation in DOT format.

The compiler already has machinery for computing a conservative over-approximation of the factor graph for the model(s) that a Stan program implements in Factor_graph.ml. I believe this was implemented in response to #177, and while the module contains a function to print this graph to DOT format, this function is never called anywhere in the compiler or exposed to users. While the approximation is coarse, the information can still be useful.

Tests: The test integration/cli-args/stanc.t currently fails. I was unsure whether I should edit that test file manually. I think I recall @WardBrian saying something about a tool for automatically updating expected test output, but I couldn't figure out how to run that. I'm happy to update the test in whatever way is standard practice.

Docs: While the change is user-facing, I noticed that not all debug flags are currently documented in the stanc CLI doc, so I defaulted to not adding documentation so as to not clutter the doc. Also happy to add that if desired.

Release notes

Add debug flag --debug-print-factor-graph to print the compiler's conservative over-approximation of the factor graph for the model(s) implemented in the Stan program.

Copyright and Licensing

By submitting this pull request, the copyright holder is agreeing to
license the submitted work under the BSD 3-clause license (https://opensource.org/licenses/BSD-3-Clause)

[WardBrian]

Thanks @collin-cademartori!

The relevant test command is “dune runtest”, which will show a diff. If the diff looks good, “dune promote” will update your local files.

The current build failure in Jenkins will be fixed by #1672, so don’t worry about that specific error too much

[nhuurre]

Why is this considered a "debug" flag?

[WardBrian]

I think it falls into the same category as our existing flags for inspecting the MIR and optimizer, but I could be convinced it deserves a more “permanent” feeling name

[WardBrian]

@collin-cademartori since you've been looking at this output already, you might be in a good position to weigh in on if #1603 improves the approximation or not. If you do have thoughts we'd appreciate it!

[collin-cademartori]

Happy to look at it in the next few days! And thanks for pointing out dune promote, I've updated the test file.

As for whether this goes behind a debug flag, a couple thoughts:

• The factor graph plays a role in the analysis routines, but also carries some information about the statistical model, so I think it straddles internal/user-facing (though less purely internal than the other debug flags).
• If the factor graph output weren't behind a debug flag, I imagine it would be added to the CLI docs, and it would be good to have a written explanation somewhere of exactly what over-approximation to the model factor graph this is computing (e.g. no visibility into non-scalar quantities, how control flow-dependent structure is handled, etc). I think this can be done, but I'd need to carefully read and test it to be confident about it.

I think the main reason to keep it behind a debug flag is that the implementation seems scoped to what the compiler internals need. Because of the limitations of the approximation, it doesn't consistently produce the same statistical information across Stan model implementations.

That said, I'm happy to reconsider the scope if there's disagreement about exposing the factor graph computation in its current incarnation.

[WardBrian]

Thank you for your contribution @collin-cademartori!