DIP commands

DIPParse accepts DIPL inputs and requests, then executes them once. For example, parse a file and request one formatted value:

#include <snt/api/dip_parse.h>

snt::api::DIPParse parse;
parse.argument_add("file", {"config.dip"});
parse.argument_request("build.python");
parse.argument_value("bool");
std::string value = parse.execute();

For a complete DIPfile manifest, use parse.argument_add("project", {"DIPfile"}). A project cannot be combined with other DIPL input arguments; see DIPfile projects.

Persisting an evaluated environment

Use argument_save() to persist the full evaluated environment during execute(). Use argument_load() instead of argument_add() to query an existing DIPH5 file without reevaluating DIPL:

snt::api::DIPParse save;
save.argument_add("string", {"simulation.steps int = 100"});
save.argument_save("parameters.diph5");
save.execute();

snt::api::DIPParse load;
load.argument_load("parameters.diph5");
load.argument_request("simulation.steps");
load.argument_value("integer");
std::string steps = load.execute(); // "100\n"

Loading cannot be combined with DIPL file, string, source, or unit inputs. Saving can accompany either parsing or loading and overwrites an existing destination. Request and tag filters affect only text output, not the saved environment. Output validation must succeed before saving. See DIP environment persistence for the format and its limitations.

Comparing DIPH5 snapshots

DIPCompare loads two snapshots and returns a structured result or bounded text summary:

#include <snt/api/dip_compare.h>

snt::api::DIPCompare command("before.diph5", "after.diph5");
auto result = command.compare();
std::string summary = command.execute();

Set ComparisonOptions through set_options() to select full scope or change the array sample size. set_max_details() bounds execute() output. compare() and execute() reuse the same result until comparison options change. See DIPH5 comparison for the fields and equality semantics.

Semantic JSON for applications

DIPSemantic exposes descriptions, discovery, and candidate previews as versioned JSON. describe_json and list_json accept a DIPfile, DIPL file, or DIPH5 snapshot. preview_json accepts a DIPfile or DIPL file and returns validation diagnostics plus a bounded diff. An invalid candidate is represented in JSON with candidate_valid: false. Pass true as the second DIPSemantic constructor argument to record dependencies while parsing. Descriptions and lists reuse the same evaluated environment; call reload() after the input changes. Previews evaluate their baseline and candidate separately. Snapshots use their saved graph.

#include <snt/api/dip_semantic.h>

snt::api::DIPSemantic model("DIPfile");
auto description = model.describe_json("simulation.steps");
auto selected = model.list_json("?simulation.");
auto candidate = model.preview_json({
    {snt::dip::PreviewOverride::Kind::Text, "simulation.steps = 200"}
});

For typed C++ results, use the DIP inspection and preview functions directly.

Generating static parameters

Use argument_generate() to export static parameters during execute(). Its format is one of cpp, c, fortran, rust, julia, json, or yaml:

snt::api::DIPParse generate;
generate.argument_add("file", {"parameters.dip"});
generate.argument_generate("cpp", "parameters.hpp");
generate.execute();

Generation can follow parsing or DIPH5 loading, and can accompany saving. It always exports the complete evaluated environment; request and tag filters only affect text output. See Static parameter generation for the generated representations.

Generating reports

snt::api::generate_dip_report takes an evaluated environment and writes a report in TeX, PDF, Markdown, reStructuredText, HTML, Typst, plain text, or Brief++ document JSON. Parse a DIPfile project, then choose the output format:

#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.title = "Simulation parameters";
options.author = "Example Research Team";
options.input_label = "DIPfile";
options.introduction_file = "introduction.tex"; // optional LaTeX fragment

snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Tex, "report.tex", options);

options.tex_compiler = "pdflatex";
snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Pdf, "report.pdf", options);

options.introduction_file.clear(); // Raw LaTeX is only for TeX/PDF.
snt::api::generate_dip_report(
    env, snt::dip::report::ReportFormat::Html, "report.html", options);

TeX output needs no external tool. PDF output runs the configured local TeX compiler and reports an error if it is unavailable. The API also accepts an environment loaded from DIPH5, with only the provenance retained in that file. See C++ report generation for cover options, report content, and a DIPH5 example, or the CreateReport example for a generated PDF.

The generated DIP command declarations and report declaration provide the member reference. API errors use the SNT exception hierarchy; see the exception declarations.