sn_fluid_refusal.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_FLUID_REFUSAL_H
#define LINE_API_SN_SN_FLUID_REFUSAL_H
 
/**
 * @file
 * @ingroup api_sn
 * Port of matlab/src/api/sn/sn_fluid_refusal.m.
 *
 * The structural rules of a Fluid Stochastic Petri Net, shared by every solver that declares FluidPlace. A
 * fluid place holds a level, not tokens, so a token arc on it, an initial token marking or a Source routed into
 * it is refused; a fluid arc must name a fluid place; an immediate mode carries no flow, since it runs for zero
 * time; and only an exponential clock can be re-timed by a level.
 */
 
#include <cmath>
#include <cstddef>
#include <string>
#include <vector>
 
#include "line/lang/qn/network_struct.h"
#include "line/num/number.h"
 
namespace line {
namespace api {
 
/** The verdict of `sn_fluid_refusal`: `ok` when no rule is broken, else the reason. */
struct SnFluidVerdict {
    bool ok = true;
    std::string reason;
};
 
/**
 * Whether the net breaks a structural rule of an FSPN. Always OK for a net with no fluid.
 *
 * @param sn the network structure
 */
template <class T>
SnFluidVerdict sn_fluid_refusal(const qn::NetworkStruct<T>& sn) {
    SnFluidVerdict v;
    const std::size_t I = sn.nodes.size(), K = sn.classes.size();
    std::vector<bool> fluid(I + 1, false);
    for (std::size_t ind = 1; ind <= I; ++ind) fluid[ind] = sn.is_fluid_node(ind);
    for (std::size_t ind = 1; ind <= I; ++ind) {
        if (!fluid[ind]) continue;
        const auto im = sn.initmarking.find(ind);
        if (im != sn.initmarking.end())
            for (const T& tok : im->second)
                if (num_traits<T>::to_double(tok) > 0.0) {
                    v.ok = false;
                    v.reason = "fluid place " + sn.nodes[ind - 1].name +
                               " holds an initial token marking; a fluid place holds a level, set with "
                               "setFluidLevel";
                    return v;
                }
        for (std::size_t src = 1; src <= I; ++src) {
            if (sn.nodes[src - 1].nodetype != lang::NodeType::Source) continue;
            bool linked = false;
            if (sn.rtnodes.rows() >= I * K && sn.rtnodes.cols() >= I * K)
                for (std::size_t r = 0; r < K && !linked; ++r)
                    for (std::size_t s = 0; s < K && !linked; ++s)
                        if (num_traits<T>::to_double(sn.rtnodes((src - 1) * K + r, (ind - 1) * K + s)) > 0.0)
                            linked = true;
            if (linked) {
                v.ok = false;
                v.reason = "Source " + sn.nodes[src - 1].name + " is routed into fluid place " +
                           sn.nodes[ind - 1].name +
                           "; a fluid place receives fluid only through setFluidRate and setFluidImpulse";
                return v;
            }
        }
    }
    for (const auto& kv : sn.transparam) {
        const std::size_t ind = kv.first;
        const qn::TransitionParam<T>& tp = kv.second;
        const std::string& tname = sn.nodes[ind - 1].name;
        for (std::size_t m = 0; m < tp.nmodes; ++m) {
            const std::string mname = (m < tp.modenames.size() && !tp.modenames[m].empty())
                                          ? tp.modenames[m]
                                          : ("Mode" + std::to_string(m + 1));
            const std::vector<Matrix<T>>* arcs[3] = {&tp.enabling, &tp.inhibiting, &tp.firing};
            const char* arcname[3] = {"enabling", "inhibiting", "firing"};
            for (int w = 0; w < 3; ++w) {
                if (m >= arcs[w]->size()) continue;
                const Matrix<T>& A = (*arcs[w])[m];
                for (std::size_t p = 0; p < A.rows() && p < I; ++p) {
                    if (!fluid[p + 1]) continue;
                    for (std::size_t r = 0; r < A.cols(); ++r) {
                        // an absent inhibitor arc is stored as Inf, not 0
                        const double a = num_traits<T>::to_double(A(p, r));
                        if (!std::isfinite(a) || a == 0.0) continue;
                        v.ok = false;
                        v.reason = "mode " + mname + " of transition " + tname + " has a token " + arcname[w] +
                                   " arc on fluid place " + sn.nodes[p].name +
                                   "; a fluid place is read through setFluidGuard and moved through "
                                   "setFluidRate/setFluidImpulse";
                        return v;
                    }
                }
            }
            const bool isimm = m < tp.timing.size() && tp.timing[m] == lang::TimingStrategy::IMMEDIATE;
            if (isimm && !tp.fluid_rates(m).empty()) {
                v.ok = false;
                v.reason = "immediate mode " + mname + " of transition " + tname +
                           " carries a fluid flow; an immediate mode runs for zero time, so its flow moves "
                           "nothing. Use setFluidImpulse";
                return v;
            }
            std::vector<std::size_t> named;
            for (const auto& a : tp.fluid_rates(m)) named.push_back(a.node);
            for (const auto& g : tp.fluid_guards(m)) named.push_back(g.node);
            for (const auto& a : tp.fluid_impulses(m)) named.push_back(a.node);
            for (const auto& d : tp.fluid_deps(m)) named.push_back(d.node);
            for (const auto& fd : tp.fluid_flow_deps(m)) {
                bool flows = false;
                for (const auto& a : tp.fluid_rates(m)) flows = flows || a.node == fd.node;
                if (!flows) {
                    v.ok = false;
                    v.reason = "mode " + mname + " of transition " + tname +
                               " has a fluid flow dependence on place " +
                               (fd.node >= 1 && fd.node <= I ? sn.nodes[fd.node - 1].name : std::to_string(fd.node)) +
                               " but no flow into or out of it; set the flow with setFluidRate first";
                    return v;
                }
                for (std::size_t rd : fd.read)
                    if (rd == 0 || rd > I || sn.nodes[rd - 1].nodetype != lang::NodeType::Place || fluid[rd]) {
                        v.ok = false;
                        v.reason = "mode " + mname + " of transition " + tname +
                                   " has a fluid flow dependence reading a node that is not a token place; a flow "
                                   "multiplier reads the marking, and a level is read by setFluidRateDependence";
                        return v;
                    }
            }
            for (std::size_t nd : named)
                if (nd == 0 || nd > I || !fluid[nd]) {
                    v.ok = false;
                    v.reason = "mode " + mname + " of transition " + tname + " has a fluid arc on place " +
                               (nd >= 1 && nd <= I ? sn.nodes[nd - 1].name : std::to_string(nd)) +
                               ", which is not a fluid place; declare it with setFluid(true)";
                    return v;
                }
            if (!tp.fluid_deps(m).empty() &&
                (m >= tp.firingproc.size() || tp.firingproc[m].disabled ||
                 tp.firingproc[m].type != lang::ProcessType::EXP)) {
                v.ok = false;
                v.reason = "mode " + mname + " of transition " + tname +
                           " has a fluid rate dependence on a non-exponential firing time; only an "
                           "exponential clock can be re-timed by the level";
                return v;
            }
        }
    }
    return v;
}
 
}  // namespace api
}  // namespace line
 
#endif  // LINE_API_SN_SN_FLUID_REFUSAL_H