sn_print.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_PRINT_H
#define LINE_API_SN_SN_PRINT_H
 
/**
 * @file
 * @ingroup api_sn
 * Port of matlab/src/api/sn/sn_print.m, jline.api.sn.SnPrint and the python
 * `sn_print` in api/sn/utils.py: the full debug dump of a NetworkStruct, one
 * `field: value` line per field, matrices in the compact `[a b; c d]` form,
 * integer-valued entries printed as integers.
 *
 * The field list follows the reference's, in its order and naming: the C++
 * NetworkStruct is object-shaped (per-station and per-class records instead of
 * MATLAB's flat matrices), so every MATLAB field is DERIVED from the records
 * here (the index maps, isstation / isstateful / isstatedep, phasessz and
 * phaseshift, csmask, mu / phi / pie from the (D0, D1) pairs, connmatrix from
 * rtnodes). The few fields this struct does not carry at all -- rtorig, space,
 * sync, gsync, which the refresh folds away or the CTMC analyzer builds on the
 * fly -- are the only ones not printed; `network_struct.h` documents why each
 * is absent. One port-only extra, csmatrix, follows the reference's fields.
 *
 * Returned as a string rather than printed, so a caller can route it to a
 * log, a CLI or a test, following `sn_print_routing_matrix`.
 *
 * ARITHMETIC: field, but the rendering is in double.
 */
 
#include <cmath>
#include <cstddef>
#include <cstdio>
#include <exception>
#include <limits>
#include <map>
#include <string>
#include <vector>
 
#include "line/api/mam/map_moment.h"
#include "line/lang/lang_types.h"
#include "line/lang/qn/network_struct.h"
#include "line/num/number.h"
#include "line/util/matrix.h"
 
namespace line {
namespace api {
 
namespace sn_print_detail {
 
/** One number, integer-rendered when it is one, as the reference prints. */
inline std::string num(double v) {
    if (std::isnan(v)) return "NaN";
    if (std::isinf(v)) return v > 0 ? "Inf" : "-Inf";
    if (v == std::floor(v) && std::fabs(v) < 1e15) {
        char buf[32];
        std::snprintf(buf, sizeof(buf), "%lld", static_cast<long long>(v));
        return buf;
    }
    char buf[32];
    std::snprintf(buf, sizeof(buf), "%g", v);
    return buf;
}
 
/** The compact `[a b; c d]` form of the reference's printMatrixCompact. */
inline std::string mat(const std::vector<std::vector<double>>& m) {
    if (m.empty() || m[0].empty()) return "[]";
    std::string out = "[";
    for (std::size_t i = 0; i < m.size(); ++i) {
        if (i > 0) out += "; ";
        for (std::size_t j = 0; j < m[i].size(); ++j) {
            if (j > 0) out += " ";
            out += num(m[i][j]);
        }
    }
    return out + "]";
}
 
inline std::string row(const std::vector<double>& v) {
    return mat(std::vector<std::vector<double>>(1, v));
}
 
template <class T>
std::string tmat(const Matrix<T>& m) {
    std::vector<std::vector<double>> d(m.rows(), std::vector<double>(m.cols()));
    for (std::size_t i = 0; i < m.rows(); ++i)
        for (std::size_t j = 0; j < m.cols(); ++j) d[i][j] = num_traits<T>::to_double(m(i, j));
    return mat(d);
}
 
inline std::string names(const std::vector<std::string>& v) {
    if (v.empty()) return "[]";
    std::string out = "[";
    for (std::size_t i = 0; i < v.size(); ++i) {
        if (i > 0) out += ", ";
        out += "\"" + v[i] + "\"";
    }
    return out + "]";
}
 
}  // namespace sn_print_detail
 
/** The full `field: value` dump of a NetworkStruct, ending with a newline. */
template <class T>
std::string sn_print(const qn::NetworkStruct<T>& sn) {
    using sn_print_detail::mat;
    using sn_print_detail::names;
    using sn_print_detail::num;
    using sn_print_detail::row;
    using sn_print_detail::tmat;
    typedef std::vector<double> Row;
    typedef std::vector<std::vector<double>> Tab;
    const std::size_t M = sn.nof_stations(), K = sn.nclasses, I = sn.nof_nodes();
    const std::size_t S = sn.nof_stateful();
    const double nan = std::numeric_limits<double>::quiet_NaN();
    std::string out;
 
    out += "nstations: " + num(static_cast<double>(M)) + "\n";
    out += "nstateful: " + num(static_cast<double>(S)) + "\n";
    out += "nnodes: " + num(static_cast<double>(I)) + "\n";
    out += "nclasses: " + num(static_cast<double>(K)) + "\n";
    out += "nclosedjobs: " + num(sn.nclosedjobs()) + "\n";
    out += "nchains: " + num(static_cast<double>(sn.nchains)) + "\n";
 
    // ---- the index maps the reference carries as fields; derived here
    Row isstation(I), isstateful(I), nodeToStateful(I), nodeToStation(I);
    Tab isstatedep(I, Row(3, 0.0));
    for (std::size_t i = 0; i < I; ++i) {
        isstation[i] = sn.nodes[i].station != 0 ? 1.0 : 0.0;
        isstateful[i] = sn.nodes[i].stateful ? 1.0 : 0.0;
        nodeToStateful[i] = static_cast<double>(sn.stateful_index(i + 1));
        nodeToStation[i] = static_cast<double>(sn.nodes[i].station);
        // refreshStruct.m: col 1 buffer, col 2 service (a Cache), col 3 routing
        if (sn.nodes[i].nodetype == qn::NodeType::Cache) isstatedep[i][1] = 1.0;
        for (std::size_t r = 0; r < sn.nodes[i].routing.size(); ++r) {
            const lang::RoutingStrategy rs = sn.nodes[i].routing[r];
            if (rs == lang::RoutingStrategy::RROBIN || rs == lang::RoutingStrategy::WRROBIN ||
                rs == lang::RoutingStrategy::JSQ || rs == lang::RoutingStrategy::SQ ||
                rs == lang::RoutingStrategy::SDR)
                isstatedep[i][2] = 1.0;
        }
    }
    Row stationToNode(M), stationToStateful(M), statefulToStation(S), statefulToNode(S);
    for (std::size_t i = 0; i < M; ++i) {
        stationToNode[i] = static_cast<double>(sn.node_of_station(i + 1));
        stationToStateful[i] = static_cast<double>(sn.stateful_of_station(i + 1));
    }
    for (std::size_t f = 0; f < S; ++f) {
        const std::size_t ind = sn.stateful_nodes[f];
        statefulToNode[f] = static_cast<double>(ind);
        statefulToStation[f] = static_cast<double>(ind > 0 ? sn.nodes[ind - 1].station : 0);
    }
 
    Row refstat(K), njobsv = sn.njobs(), classprio(K);
    for (std::size_t r = 0; r < K; ++r) {
        refstat[r] = static_cast<double>(sn.classes[r].refstat);
        classprio[r] = static_cast<double>(sn.classes[r].prio);
    }
    out += "refstat: " + row(refstat) + "\n";
    out += "njobs: " + row(njobsv) + "\n";
    Row nservers(M), cap(M);
    Tab classcap(M, Row(K)), phases(M, Row(K)), phasessz(M, Row(K)), phaseshift(M, Row(K + 1, 0.0));
    Tab schedparam(M, Row(K, 0.0));
    Tab droprule(M, Row(K)), procid(M, Row(K));
    for (std::size_t i = 0; i < M; ++i) {
        nservers[i] = sn.stations[i].nservers;
        cap[i] = i < sn.cap.size() ? sn.cap[i] : std::numeric_limits<double>::infinity();
        double cum = 0.0;
        for (std::size_t r = 0; r < K; ++r) {
            classcap[i][r] = i < sn.classcap.size() && r < sn.classcap[i].size()
                                 ? sn.classcap[i][r]
                                 : std::numeric_limits<double>::infinity();
            phases[i][r] = static_cast<double>(sn.phases_of(i + 1, r + 1));
            phasessz[i][r] = static_cast<double>(sn.phasessz_of(i + 1, r + 1));
            cum += phasessz[i][r];
            phaseshift[i][r + 1] = cum;  // [0, cumsum(phasessz(i,:))]
            if (r < sn.stations[i].schedparam.size())
                schedparam[i][r] = num_traits<T>::to_double(sn.stations[i].schedparam[r]);
            droprule[i][r] = i < sn.droprule.size() && r < sn.droprule[i].size()
                                 ? static_cast<double>(static_cast<int>(sn.droprule[i][r]))
                                 : static_cast<double>(static_cast<int>(qn::DropStrategy::WAITQ));
            procid[i][r] = static_cast<double>(static_cast<int>(sn.procid(i + 1, r + 1)));
        }
    }
    out += "nservers: " + row(nservers) + "\n";
 
    // `sn.connmatrix`: this port carries no link field (see
    // NetworkStruct::downstream_stations); the node graph is read off rtnodes,
    // which differs only on a declared link that routes zero mass.
    {
        Tab conn(I, Row(I, 0.0));
        if (sn.rtnodes.rows() == I * K && K > 0)
            for (std::size_t a = 0; a < I; ++a)
                for (std::size_t b = 0; b < I; ++b) {
                    bool any = false;
                    for (std::size_t r = 0; r < K && !any; ++r)
                        for (std::size_t s2 = 0; s2 < K && !any; ++s2)
                            any = num_traits<T>::to_double(sn.rtnodes(a * K + r, b * K + s2)) > 0.0;
                    conn[a][b] = any ? 1.0 : 0.0;
                }
        out += "connmatrix: " + (I > 0 ? mat(conn) : std::string("[]")) + "\n";
    }
    out += "scv: " + tmat(sn.scv) + "\n";
    out += "isstation: " + row(isstation) + "\n";
    out += "isstateful: " + row(isstateful) + "\n";
    out += "isstatedep: " + (I > 0 ? mat(isstatedep) : std::string("[]")) + "\n";
    out += "nodeToStateful: " + row(nodeToStateful) + "\n";
    out += "nodeToStation: " + row(nodeToStation) + "\n";
    out += "stationToNode: " + row(stationToNode) + "\n";
    out += "stationToStateful: " + row(stationToStateful) + "\n";
    out += "statefulToStation: " + row(statefulToStation) + "\n";
    out += "statefulToNode: " + row(statefulToNode) + "\n";
    out += "rates: " + tmat(sn.rates) + "\n";
    out += "classprio: " + row(classprio) + "\n";
    out += "phases: " + mat(phases) + "\n";
    out += "phasessz: " + mat(phasessz) + "\n";
    out += "phaseshift: " + mat(phaseshift) + "\n";
    out += "schedparam: " + mat(schedparam) + "\n";
 
    Tab chains(sn.chains.size());
    for (std::size_t c = 0; c < sn.chains.size(); ++c)
        for (std::size_t r = 0; r < sn.chains[c].size(); ++r)
            chains[c].push_back(sn.chains[c][r] ? 1.0 : 0.0);
    out += "chains: " + mat(chains) + "\n";
    out += "rt: " + tmat(sn.rt) + "\n";
 
    Tab nvars(sn.nvars.size());
    for (std::size_t i = 0; i < sn.nvars.size(); ++i)
        for (std::size_t v = 0; v < sn.nvars[i].size(); ++v)
            nvars[i].push_back(static_cast<double>(sn.nvars[i][v]));
    out += "nvars: " + mat(nvars) + "\n";
    out += "rtnodes: " + tmat(sn.rtnodes) + "\n";
 
    // `sn.csmask(r,s)`: some node switches class r into class s
    {
        Tab csmask(K, Row(K, 0.0));
        for (typename std::map<std::size_t, Matrix<T>>::const_iterator it = sn.csmatrix.begin();
             it != sn.csmatrix.end(); ++it)
            for (std::size_t r = 0; r < K && r < it->second.rows(); ++r)
                for (std::size_t s2 = 0; s2 < K && s2 < it->second.cols(); ++s2)
                    if (num_traits<T>::to_double(it->second(r, s2)) > 0.0) csmask[r][s2] = 1.0;
        out += "csmask: " + (K > 0 ? mat(csmask) : std::string("[]")) + "\n";
    }
    {
        Row isslc(K, 0.0);
        for (std::size_t r = 0; r < K; ++r) isslc[r] = sn.classes[r].self_looping ? 1.0 : 0.0;
        out += "isslc: " + row(isslc) + "\n";
    }
    out += "cap: " + row(cap) + "\n";
    out += "classcap: " + mat(classcap) + "\n";
 
    Row refclass(sn.refclass.size());
    for (std::size_t c = 0; c < sn.refclass.size(); ++c)
        refclass[c] = static_cast<double>(sn.refclass[c]);
    out += "refclass: " + row(refclass) + "\n";
 
    Tab lld;
    for (std::size_t i = 0; i < M; ++i)
        if (!sn.stations[i].lldscaling.empty()) {
            Row rw;
            for (std::size_t n = 0; n < sn.stations[i].lldscaling.size(); ++n)
                rw.push_back(num_traits<T>::to_double(sn.stations[i].lldscaling[n]));
            lld.push_back(rw);
        }
    out += "lldscaling: " + (lld.empty() ? std::string("[]") : mat(lld)) + "\n";
 
    Tab fj(sn.fj.size());
    for (std::size_t e = 0; e < sn.fj.size(); ++e) {
        fj[e].push_back(static_cast<double>(sn.fj[e].first));
        fj[e].push_back(static_cast<double>(sn.fj[e].second));
    }
    out += "fj: " + mat(fj) + "\n";
 
    out += "nodetype: ";
    if (sn.nodes.empty()) {
        out += "[]\n";
    } else {
        out += "[";
        for (std::size_t i = 0; i < I; ++i) {
            if (i > 0) out += ", ";
            out += lang::node_type_to_text(sn.nodes[i].nodetype);
        }
        out += "]\n";
    }
    std::vector<std::string> classnames(K), nodenames(I);
    for (std::size_t r = 0; r < K; ++r) classnames[r] = sn.classes[r].name;
    for (std::size_t i = 0; i < I; ++i) nodenames[i] = sn.nodes[i].name;
    out += "classnames: " + names(classnames) + "\n";
    out += "nodenames: " + names(nodenames) + "\n";
 
    // `rtorig` is not carried by this port (the refresh folds it into rt), and
    // `space` is built by the CTMC analyzer rather than stored; neither is
    // printed. `state` and `stateprior` are the declared pair (statespace,
    // stateprior), keyed by node name as the reference prints them.
    out += "state: {";
    {
        bool first = true;
        for (std::size_t f = 0; f < S; ++f) {
            const std::size_t ind = sn.stateful_nodes[f];
            if (!first) out += ", ";
            first = false;
            out += "\"" + sn.nodes[ind - 1].name + "\": ";
            const typename std::map<std::size_t, Matrix<T>>::const_iterator it =
                sn.statespace.find(ind);
            out += (it == sn.statespace.end() || it->second.rows() == 0) ? std::string("null")
                                                                         : tmat(it->second);
        }
    }
    out += "}\n";
    out += "stateprior: {";
    {
        bool first = true;
        for (std::size_t f = 0; f < S; ++f) {
            const std::size_t ind = sn.stateful_nodes[f];
            if (!first) out += ", ";
            first = false;
            out += "\"" + sn.nodes[ind - 1].name + "\": ";
            const typename std::map<std::size_t, std::vector<T>>::const_iterator it =
                sn.stateprior.find(ind);
            if (it == sn.stateprior.end() || it->second.empty()) {
                out += "null";
            } else {
                Row rw;
                for (std::size_t a = 0; a < it->second.size(); ++a)
                    rw.push_back(num_traits<T>::to_double(it->second[a]));
                out += row(rw);
            }
        }
    }
    out += "}\n";
 
    // `sn.routing(ind, r)`: the RoutingStrategy id per node and class
    {
        Tab routing(I, Row(K, static_cast<double>(static_cast<int>(lang::RoutingStrategy::DISABLED))));
        for (std::size_t i = 0; i < I; ++i)
            for (std::size_t r = 0; r < K && r < sn.nodes[i].routing.size(); ++r)
                routing[i][r] = static_cast<double>(static_cast<int>(sn.nodes[i].routing[r]));
        out += "routing: " + (I > 0 && K > 0 ? mat(routing) : std::string("[]")) + "\n";
    }
    out += "procid: " + mat(procid) + "\n";
 
    // mu, phi, pie: per station and class, from the (D0, D1) representation,
    // as refreshProcessRepresentations derives them
    {
        std::string smu = "mu: {", sphi = "phi: {", spie = "pie: {";
        for (std::size_t i = 0; i < M; ++i) {
            if (i > 0) {
                smu += ", ";
                sphi += ", ";
                spie += ", ";
            }
            const std::string head = "\"" + sn.stations[i].name + "\": {";
            smu += head;
            sphi += head;
            spie += head;
            for (std::size_t r = 0; r < K; ++r) {
                if (r > 0) {
                    smu += ", ";
                    sphi += ", ";
                    spie += ", ";
                }
                const std::string ch = "\"" + sn.classes[r].name + "\": ";
                smu += ch;
                sphi += ch;
                spie += ch;
                const lang::Distrib<T>& d = sn.service[i][r];
                if (d.disabled || d.D0.rows() == 0 || d.D1.rows() != d.D0.rows()) {
                    smu += "null";
                    sphi += "null";
                    spie += "null";
                    continue;
                }
                const std::size_t n = d.D0.rows();
                Row muv(n), phiv(n), piev(n, nan);
                for (std::size_t a = 0; a < n; ++a) {
                    const double d0 = -num_traits<T>::to_double(d.D0(a, a));
                    double d1 = 0.0;
                    for (std::size_t b = 0; b < n; ++b) d1 += num_traits<T>::to_double(d.D1(a, b));
                    muv[a] = d0;
                    phiv[a] = d0 != 0.0 ? d1 / d0 : 0.0;
                }
                try {
                    mam::Map<T> m;
                    m.D0 = d.D0;
                    m.D1 = d.D1;
                    const std::vector<T> pie = mam::map_pie(m);
                    for (std::size_t a = 0; a < n && a < pie.size(); ++a)
                        piev[a] = num_traits<T>::to_double(pie[a]);
                } catch (const std::exception&) {
                    // a degenerate (D0, D1) has no embedded law to report
                }
                smu += row(muv);
                sphi += row(phiv);
                spie += row(piev);
            }
            smu += "}";
            sphi += "}";
            spie += "}";
        }
        out += smu + "}\n" + sphi + "}\n";
        out += "proc: {";
        for (std::size_t i = 0; i < M; ++i) {
            if (i > 0) out += ", ";
            out += "\"" + sn.stations[i].name + "\": {";
            for (std::size_t r = 0; r < K; ++r) {
                if (r > 0) out += ", ";
                const lang::Distrib<T>& d = sn.service[i][r];
                out += "\"" + sn.classes[r].name + "\": ";
                if (d.disabled) {
                    out += "null";
                } else {
                    out += std::string("{\"type\": \"") + lang::process_to_text(d.type) +
                           "\", \"mean\": " + num(num_traits<T>::to_double(d.mean)) +
                           ", \"scv\": " + num(num_traits<T>::to_double(d.scv)) + "}";
                }
            }
            out += "}";
        }
        out += "}\n";
        out += spie + "}\n";
    }
 
    out += "sched: {";
    for (std::size_t i = 0; i < M; ++i) {
        if (i > 0) out += ", ";
        out += "\"" + sn.stations[i].name + "\": \"" +
               lang::sched_to_text(sn.stations[i].sched) + "\"";
    }
    out += "}\n";
 
    out += "inchain: {";
    for (std::size_t c = 0; c < sn.inchain.size(); ++c) {
        if (c > 0) out += ", ";
        Row rw;
        for (std::size_t k = 0; k < sn.inchain[c].size(); ++k)
            rw.push_back(static_cast<double>(sn.inchain[c][k]));
        out += num(static_cast<double>(c)) + ": " + row(rw);
    }
    out += "}\n";
 
    out += "visits: {";
    for (std::size_t c = 0; c < sn.visits.size(); ++c) {
        if (c > 0) out += ", ";
        out += num(static_cast<double>(c)) + ": " + tmat(sn.visits[c]);
    }
    out += "}\n";
    out += "nodevisits: {";
    for (std::size_t c = 0; c < sn.nodevisits.size(); ++c) {
        if (c > 0) out += ", ";
        out += num(static_cast<double>(c)) + ": " + tmat(sn.nodevisits[c]);
    }
    out += "}\n";
    out += "droprule: " + mat(droprule) + "\n";
 
    // `sn.nodeparam`: the per-node parameter blocks this struct carries, keyed
    // by node name; a node with none prints null
    out += "nodeparam: {";
    for (std::size_t i = 0; i < I; ++i) {
        if (i > 0) out += ", ";
        out += "\"" + sn.nodes[i].name + "\": ";
        const std::size_t ind = i + 1;
        std::string blk;
        {
            const typename std::map<std::size_t, qn::CacheParam<T>>::const_iterator it =
                sn.nodeparam.find(ind);
            if (it != sn.nodeparam.end()) {
                Row cap_r, hit, miss;
                for (std::size_t a = 0; a < it->second.itemcap.size(); ++a)
                    cap_r.push_back(it->second.itemcap[a]);
                for (std::size_t a = 0; a < it->second.hitclass.size(); ++a)
                    hit.push_back(static_cast<double>(it->second.hitclass[a]));
                for (std::size_t a = 0; a < it->second.missclass.size(); ++a)
                    miss.push_back(static_cast<double>(it->second.missclass[a]));
                blk = "{\"nitems\": " + num(static_cast<double>(it->second.nitems)) +
                      ", \"itemcap\": " + row(cap_r) + ", \"hitclass\": " + row(hit) +
                      ", \"missclass\": " + row(miss) + "}";
            }
        }
        if (blk.empty()) {
            const typename std::map<std::size_t, typename qn::NetworkStruct<T>::JoinDecl>::const_iterator
                it = sn.joindecl.find(ind);
            if (it != sn.joindecl.end())
                blk = "{\"joinStrategy\": " +
                      num(static_cast<double>(static_cast<int>(it->second.strategy))) +
                      ", \"joinRequired\": " + num(it->second.quorum) + "}";
        }
        if (blk.empty()) {
            const typename std::map<std::size_t, qn::TransitionParam<T>>::const_iterator it =
                sn.transparam.find(ind);
            if (it != sn.transparam.end())
                blk = "{\"nmodes\": " + num(static_cast<double>(it->second.nmodes)) +
                      ", \"modenames\": " + names(it->second.modenames) + "}";
        }
        if (blk.empty()) {
            const typename std::map<std::size_t, qn::ForkParam<T>>::const_iterator it =
                sn.forkparam.find(ind);
            if (it != sn.forkparam.end())
                blk = "{\"fanOut\": " + tmat(it->second.fan_out_link) + "}";
            else if (sn.nodes[i].nodetype == qn::NodeType::Fork)
                blk = "{\"fanOut\": " + num(sn.nodes[i].tasks_per_link) + "}";
        }
        out += blk.empty() ? std::string("null") : blk;
    }
    out += "}\n";
 
    // `sync` and `gsync` are built by refresh_sync / refresh_global_sync when a
    // state-space solver runs and are not stored on this struct, so they are
    // not printed. cdscaling / jdscaling are function handles in the reference
    // and print as presence here.
    {
        std::string scd = "cdscaling: {", sjd = "jdscaling: {";
        for (std::size_t i = 0; i < M; ++i) {
            if (i > 0) {
                scd += ", ";
                sjd += ", ";
            }
            scd += "\"" + sn.stations[i].name + "\": " +
                   (static_cast<bool>(sn.stations[i].cdscaling) ? "\"<function>\"" : "null");
            sjd += "\"" + sn.stations[i].name + "\": " +
                   (static_cast<bool>(sn.stations[i].jdscaling) ? "\"<function>\"" : "null");
        }
        out += scd + "}\n" + sjd + "}\n";
    }
 
    // port-only extra, after the reference's fields
    out += "csmatrix: {";
    {
        bool first = true;
        for (typename std::map<std::size_t, Matrix<T>>::const_iterator it = sn.csmatrix.begin();
             it != sn.csmatrix.end(); ++it) {
            if (!first) out += ", ";
            first = false;
            out += num(static_cast<double>(it->first)) + ": " + tmat(it->second);
        }
    }
    out += "}\n";
    return out;
}
 
}  // namespace api
}  // namespace line
 
#endif  // LINE_API_SN_SN_PRINT_H