Report generation

snt::dip::report::generate writes a report from an evaluated snt::dip::Environment. The application-facing snt::api::generate_dip_report calls the same generator. Both use the document model in the DIP library. The renderer is Brief++, a header-only library. Supported formats are TeX, PDF, Markdown, reStructuredText, HTML, Typst, plain text, and Brief++ document JSON. All contain the evaluated report data; TeX and PDF additionally use the styled cover and contents page.

Generating a report

Parse a DIPfile project and pass the resulting environment to the API:

#include <snt/api/dip_report.h>
#include <snt/dip/dip.h>

snt::dip::DIP parser;
parser.add_project("DIPfile");
auto env = parser.parse();

snt::dip::report::ReportOptions options;
options.input_label = "DIPfile";
options.introduction_file = "introduction.tex";
snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Tex, "report.tex", options);

TeX output needs no external program. introduction_file is an optional trusted LaTeX fragment for TeX and PDF only, without a document preamble. It appears after the contents page; \subsection headings in the fragment become contents links. Other text supplied by the environment and cover options is escaped for LaTeX.

PDF output uses the same TeX document and invokes a local TeX compiler twice to resolve contents links and page numbers:

options.title = "Mock Heat Flow Study";
options.author = "Example Research Team";
options.date = "2026-09-28";
options.version = "1.0 demo";
options.tex_compiler = "pdflatex";
snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Pdf, "report.pdf", options);

tex_compiler defaults to pdflatex. Choose another compatible local compiler, such as lualatex for Unicode text, when needed. An unavailable or failing compiler raises an error; the generator does not install one.

Other formats use Brief++ renderers directly and need no external program:

options.introduction_file.clear();
snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Html, "report.html", options);
snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Markdown, "report.md", options);

The other format values are Rst, Typst, Text, and Json. Markdown uses Brief++’s MyST-style directives for tables. JSON is the briefpp/1 document tree, not DIP’s static parameter export JSON. An introduction file is rejected for these formats because it contains raw LaTeX.

Report options and content

ReportOptions defaults to the title DIP parameter report, an unspecified author, the local generation date, and the SNT build version. Set the date and version explicitly when a reproducible cover matters. input_label identifies the environment on the cover. Set source_root to a project directory to show source paths relative to it when possible.

The report contains effective values, types, array shapes and units, descriptions, parameter paths, schema information, source provenance, custom units, registered function names, and available publication references. Applied value modifications appear in order with their source locations. Override information appears only for overridden parameters. Evaluated tables have a summary of their row count and ordered column names, types, and units; their column values remain in the Parameters section. Entries are sorted by path or name. The PDF has a cover, linked contents page, and matching shaded headings for parameters, tables, schemas, sources, and custom units. Human-readable reports show a 16-character prefix of each source content hash for readability. The JSON report, environment, and DIPH5 snapshot retain full digests. Parameter paths retain their group names; there is no separate hierarchy section. Built-in PUQ unit catalogues and executable function bodies are not included.

The generator also accepts a loaded DIPH5 environment:

#include <snt/dip/environment.h>
#include <snt/dip/report/report.h>

snt::dip::Environment env;
env.load("run.diph5");
snt::dip::report::generate(
    env, snt::dip::report::ReportFormat::Tex, "loaded-report.tex");

This report contains only values and provenance retained in the snapshot. It cannot reconstruct unsaved source text, executable function bodies, reusable schema definitions, or empty containers without value descendants.

See the DIP report declarations for the full options and the API wrapper declaration. The CreateReport example includes a generated PDF. For other interfaces, see the CLI, Python, C, and REST guides.