Report generation

Configure with -DENABLE_SNT_REPORT=ON to build report generation (the default when DIP is enabled). -DENABLE_SNT_REPORT=OFF removes the Brief++ dependency. In a report-disabled build, the C++ and C report entry points return an error, while the CLI command, Python binding, and REST route are unavailable.

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(true);

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. The Parameter guide lists every effective value and links to its full reference entry in HTML and PDF. Each entry retains its value, type, units, description, schema provenance, declaration, modifications, and override history. When present, an Applied overrides index lists the effective value and source of each explicit override so changes can be reviewed before reading individual entries. The Schemas section lists the parameters each schema supplied, while individual entries distinguish a schema applied along a path from one that supplied the value node.

Parameter entries show declared !options and !condition rules, plus tags, when present. These rules remain visible without a recorded dependency graph. Author guidance such as rationale, recommended range, scientific and performance impact, dependencies, conflicts, and deprecation is shown in a separate advisory block. A recommended range or ?requires entry describes intent; it does not add a runtime validation rule.

If the environment has a recorded dependency graph, parameter entries also show their evaluated expression, direct reads, branch selection, and readers where available. These are evaluation facts: a read does not always mean that input was necessary for the final result. Source qualifiers on imported reads remain visible. Pass true to parse() to record this information; ordinary parsing keeps graph recording disabled. Reports from DIPH5 use a saved graph if present. Without one, the guide says that calculation relationships are unavailable.

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.