sn_validate_contract.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_API_SN_SN_VALIDATE_CONTRACT_H
#define LINE_API_SN_SN_VALIDATE_CONTRACT_H
 
/**
 * @file
 * @ingroup api_sn
 * Check a NetworkStruct against its contract (sn_contract.h): the C++ twin of
 * MATLAB's sn_validate. (`sn_validate` itself is taken in this port by the
 * JAR's SnValidate value checks, see sn_validate.h.)
 *
 * Four kinds of violation are reported, one string each: a required field is
 * missing, a field is not in the contract at all, a value has a kind the
 * contract does not admit, and a non-empty value has a shape none of the
 * field's shapes admits.
 *
 * The check runs on the FIELD VIEW of the struct (sn_contract_view), so a test
 * can drop or inject a field as the MATLAB test does with rmfield. C++ has no
 * reflection, so whether every DATA MEMBER of NetworkStruct is declared in the
 * contract is checked when the view is generated, by
 * `doc/generate-sn-contract.py --check`; at run time an unknown field is one in
 * the view the contract does not list. qn::Network::get_struct runs it once per
 * rebuild at VerboseLevel::DEBUG or with LINE_VALIDATE_SN=1, and warns.
 */
 
#include <cmath>
#include <cstdlib>
#include <regex>
#include <set>
#include <sstream>
#include <string>
#include <vector>
 
#include "line/api/sn/sn_contract.h"
#include "line/api/sn/sn_field_view.h"
#include "line/util/error.h"
#include "line/util/line_console.h"
 
namespace line {
namespace api {
 
namespace detail {
 
inline std::vector<std::string> contract_split(const std::string& s, char sep) {
    std::vector<std::string> out;
    std::string cur;
    for (char ch : s) {
        if (ch == sep) {
            out.push_back(cur);
            cur.clear();
        } else {
            cur += ch;
        }
    }
    out.push_back(cur);
    return out;
}
 
inline std::string contract_join(const std::vector<std::string>& v, const std::string& sep) {
    std::string out;
    for (std::size_t i = 0; i < v.size(); ++i) {
        out += (i ? sep : "") + v[i];
    }
    return out;
}
 
/** '*' admits any extent; a trailing '?' makes the extent an upper bound. */
inline bool contract_extent_admits(std::string tok, long n, const std::map<char, double>& dims) {
    if (n < 0) {
        return false;
    }
    bool upper = !tok.empty() && tok.back() == '?';
    if (upper) {
        tok.pop_back();
    }
    if (tok == "*") {
        return true;
    }
    static const std::regex term_re("^([0-9]*)([A-Z]*)$");
    double total = 0;
    for (const auto& term : contract_split(tok, '+')) {
        std::smatch m;
        if (!std::regex_match(term, m, term_re) || (m[1].length() == 0 && m[2].length() == 0)) {
            return false;
        }
        double f = m[1].length() ? std::stod(m[1].str()) : 1.0;
        for (char ch : m[2].str()) {
            auto it = dims.find(ch);
            f *= (it == dims.end()) ? std::nan("") : it->second;
        }
        total += f;
    }
    return upper ? n <= total : static_cast<double>(n) == total;
}
 
inline bool contract_shape_admits(const SnFieldView& v, const std::string& shape,
                                  const std::map<char, double>& dims) {
    auto parts = contract_split(shape, 'x');
    if (parts.size() == 1) {
        return contract_extent_admits(parts[0], sn_view_extent(v), dims);
    }
    if (parts.size() != 2) {
        return false;
    }
    if (v.ndim == 2) {
        return contract_extent_admits(parts[0], v.rows, dims) && contract_extent_admits(parts[1], v.cols, dims);
    }
    if (v.ndim != 1 || !contract_extent_admits(parts[0], v.rows, dims)) {
        return false;
    }
    for (long e : v.elems) {
        if (e != kEmptyExtent && !contract_extent_admits(parts[1], e, dims)) {
            return false;
        }
    }
    return true;
}
 
inline std::string contract_describe(const SnFieldView& v) {
    if (v.ndim == 2) {
        return "[" + std::to_string(v.rows) + " " + std::to_string(v.cols) + "]";
    }
    if (v.ndim == 1) {
        std::set<long> inner(v.elems.begin(), v.elems.end());
        std::vector<std::string> s;
        for (long e : inner) {
            s.push_back(e == kEmptyExtent ? "empty" : e == kNoExtent ? "none" : std::to_string(e));
        }
        return "of size " + std::to_string(v.rows) + " (element extents " + contract_join(s, ",") + ")";
    }
    return "a " + v.kind;
}
 
}  // namespace detail
 
/** True when get_struct should validate: debug verbosity, or LINE_VALIDATE_SN=1. */
inline bool sn_validate_requested() {
    const char* env = std::getenv("LINE_VALIDATE_SN");
    return util::LineConsole::get_verbose() == util::VerboseLevel::DEBUG || (env && std::string(env) == "1");
}
 
/**
 * The contract violations of a field view; with `error` true, throws
 * InternalError with id LINE:internal:Contract when there are any.
 */
inline std::vector<std::string> sn_validate_contract(const SnFieldViews& views, bool error = false) {
    std::vector<std::string> v;
    std::map<std::string, const SnContractField*> by_name;
    for (const auto& f : sn_contract()) {
        by_name[f.name] = &f;
        if (std::string(f.group) == "required" && std::string(f.via) != "" && !views.fields.count(f.name)) {
            v.push_back(std::string("required field sn.") + f.name + " is missing");
        }
    }
    for (const auto& kv : views.fields) {
        const std::string& name = kv.first;
        const SnFieldView& fv = kv.second;
        auto it = by_name.find(name);
        if (it == by_name.end() || std::string(it->second->via).empty()) {
            v.push_back("sn." + name + " is not in sn_contract: misspelled, or a new field that was never declared");
            continue;
        }
        const SnContractField& c = *it->second;
        auto kinds = detail::contract_split(c.kinds, ',');
        bool kind_ok = std::string(c.kinds).empty();
        for (const auto& k : kinds) {
            kind_ok = kind_ok || k == fv.kind;
        }
        if (!kind_ok) {
            v.push_back("sn." + name + " is a " + fv.kind + ", but the contract admits " +
                        detail::contract_join(kinds, " or "));
            continue;
        }
        if (std::string(c.shapes).empty() || fv.empty) {
            continue;
        }
        auto shapes = detail::contract_split(c.shapes, ',');
        bool ok = false;
        for (const auto& s : shapes) {
            ok = ok || detail::contract_shape_admits(fv, s, views.dims);
        }
        if (!ok) {
            v.push_back("sn." + name + " is " + detail::contract_describe(fv) + ", but the contract admits " +
                        detail::contract_join(shapes, " or "));
        }
    }
    if (error && !v.empty()) {
        throw InternalError(ErrorKind{"Contract"}, "NetworkStruct violates its contract:\n  " +
                                                       detail::contract_join(v, "\n  "));
    }
    return v;
}
 
/** The contract violations of a struct; see sn_validate_contract(const SnFieldViews&, bool). */
template <class T>
std::vector<std::string> sn_validate_contract(const qn::NetworkStruct<T>& sn, bool error = false) {
    return sn_validate_contract(sn_contract_view(sn), error);
}
 
}  // namespace api
}  // namespace line
 
#endif  // LINE_API_SN_SN_VALIDATE_CONTRACT_H