API — ICoreBlocks/ICoreVerification

The public contract of 2 header(s) under src/ICoreBlocks/ICoreVerification — 4 class/struct definition(s), 15 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreCodeExportVerifier.h#

src/ICoreBlocks/ICoreVerification/CodeExportVerification/ICoreCodeExportVerifier.h

ICoreVerificationResult#

ICoreCodeExportVerifier.h:17 · struct · 0 declaration(s)

struct ICoreVerificationResult {
public:
    bool passed = false;
    std::string failureReason;

    // Aligned data (time col + signal cols), ready to hand to ICoreChart::plot
    ICoreMatrix alignedEmulated;
    ICoreMatrix alignedSimulated;
    ICoreMatrix residuals;       // col0 = time, col j = emulated_j - simulated_j

    // Time metadata
    bool fixedStep = false;
    double stepTime = 0.0;       // valid if fixedStep
    double startTime = 0.0;      // start of compared window
    double endTime = 0.0;        // end of compared window
    double choppedFromStart = 0.0; // duration trimmed from the longer vector's head
    double choppedFromEnd = 0.0;   // duration trimmed from the longer vector's tail
    size_t comparedRows = 0;
    size_t signalCount = 0;      // number of non-time columns

    // Per-signal + overall stats
    double maxAbsError = 0.0;
    double rmsError = 0.0;
    double meanAbsError = 0.0;
    std::vector<double> perSignalMaxAbsError; // size = signalCount

    // Relative-error metrics: maxAbsError expressed as a percentage of the simulated signal's
    // peak (largest absolute value across the aligned simulated signal columns). residualPercent
    // is infinite when the simulated peak is ~0 but there is a non-zero error.
    double maxAbsSimulated = 0.0;
    double residualPercent = 0.0;

    // ---- text columns (T5.8) ----------------------------------------------
    //
    // A String signal has no residual and no band: two strings are equal or
    // they are not. So a text column contributes NOTHING to maxAbsError, rms or
    // residualPercent -- a 0/1 "residual" folded into those would be compared
    // against a percentage tolerance, and on a rig that also carries a large
    // double it would slip under the band and report a wrong word as a pass.
    //
    // It fails the run outright instead: a mismatch sets `passed` false and
    // `failureReason`, which is the same road a structural failure already
    // takes and needs no change at any of the four call sites.
    std::size_t textColumnCount = 0;

    // "sig2 at t=0.030000: emulated \"ab\" vs simulated \"abc\"", capped -- a
    // wrong string usually stays wrong for every remaining step, and a reason
    // string holding 20 000 of them helps nobody.
    std::vector<std::string> textMismatches;
};
};

ICoreVerificationTrace#

ICoreCodeExportVerifier.h:83 · struct · 0 declaration(s)

What a verification run carries that a matrix of doubles cannot (T5.8).

struct ICoreVerificationTrace {
public:
    // Column index (0 is time) -> that column's value on every compared row.
    std::map<std::size_t, std::vector<std::string>> textColumns;
};
};

ICoreCodeExportVerifier#

ICoreCodeExportVerifier.h:88 · class · pImpl · 10 declaration(s)

class ICoreCodeExportVerifier {
public:
    explicit ICoreCodeExportVerifier();
    ~ICoreCodeExportVerifier();

    static ICoreVerificationResult verifyMatrices(const ICoreMatrix &emulated, const ICoreMatrix &simulated);

    // The same comparison, plus the text columns the two matrices could not
    // carry. A column present in one trace and absent from the other is a
    // FAILURE and not a skip: it means the two sides disagree about what that
    // column IS, which is the one thing a verifier must never shrug at.
    static ICoreVerificationResult verifyMatrices(const ICoreMatrix &emulated, const ICoreMatrix &simulated,
                                                  const ICoreVerificationTrace &emulatedText,
                                                  const ICoreVerificationTrace &simulatedText);

    // The program that builds/runs a target's testbench, ready for a shell line:
    // the target's own path when its "Use Toolchains setting" is off, otherwise
    // the toolchain registry's answer (ICoreToolchains).
    // "" when there is none.
    static std::string resolveCompiler(const ICoreCodeExportTarget* target);

    // The registry's tool for a code-export language (C and C++ are two), or
    // none for a language that runs nothing.
    static std::optional<ICoreToolId> toolchainFor(const std::string& codeExportType);

    // Generates a random pulse-train test input for the top node's input gates
    // and writes it to <project>/CodeExportTests/<name>_input.csv. The same CSV
    // drives both the native simulation and the emulated Python testbench.
    static bool generateAndExportTestInputs(const ICoreCodeExportTarget* target);

    // Builds & runs the exported testbench for the target. If compilerLog is non-null, every
    // shell command (compile/transpile/run) is appended to it with its combined stdout+stderr
    // and exit code, so the caller can surface the full toolchain output to the user.
    // Returns an empty matrix when the code could not be generated/built/run; failureReason
    // (if non-null) then carries the reason so the caller can report it instead of letting
    // the empty result surface as a misleading comparison error.
    //
    // `textTrace`, when non-null, receives the text columns of the target's
    // output CSV -- a String signal's word per row. Null means "score the
    // numbers only", which is what every caller wanted before String ports
    // existed and is still correct for a model that has none.
    static ICoreMatrix emulateTarget(const ICoreCodeExportTarget* target, std::string* compilerLog = nullptr,
                                     std::string* failureReason = nullptr,
                                     ICoreVerificationTrace* textTrace = nullptr);

    static ICoreMatrix getSimulatedSourceData(const ICoreCodeExportTarget* target,
                                              ICoreVerificationTrace* textTrace = nullptr);
    static std::vector<std::string> getSimulatedSignalNames(const ICoreCodeExportTarget* target);
    static std::vector<std::pair<std::string, std::string>> getSimulatedSignalMap(const ICoreCodeExportTarget* target);

    static std::vector<std::string> getAvailableVerificationLevels();

    void showUI() const;

    static const std::string VERIFICATION_TYPE_NONE;
    static const std::string VERIFICATION_TYPE_LEVEL1;
    static const std::string VERIFICATION_TYPE_LEVEL2;
    static const std::string VERIFICATION_TYPE_STRICT;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

File-scope declarations#

// Opaque: the full enum is ICoreBlocks/ICoreServices/ICoreToolchains.h.
enum class ICoreToolId;

ICoreModelVerification.h#

src/ICoreBlocks/ICoreVerification/ModelVerification/ICoreModelVerification.h

ICoreModelVerification#

ICoreModelVerification.h:9 · class · 5 declaration(s)

class ICoreModelVerification {
public:
    static bool verifyProject();
    static bool verifyAllDescendentsAreAlive(const ICoreSubsystemTreeNode* treenode);
    static bool verifyAllDescendentsHaveUniquePaths(const ICoreSubsystemTreeNode *treenode);
    static bool verifyAllLinksHaveValidRoots(const ICoreSubsystemTreeNode *treenode);
    static bool verifyConnections(const ICoreSubsystemTreeNode *treenode);
};
};