sn_field_view.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_FIELD_VIEW_H
#define LINE_API_SN_SN_FIELD_VIEW_H
 
/**
 * @file
 * @ingroup api_sn
 * The FIELD VIEW the NetworkStruct contract is checked on: for each value, its
 * kind (Matrix, vector, map, scalar, string, function, opaque), whether it is
 * empty, and its extents, so a contract written in MATLAB's dimensions (M
 * stations, K classes, ...) can be checked against a struct that is object-
 * shaped. sn_contract.h (generated) builds the view of a whole struct; this
 * header holds the hand-written `sn_field_view` overloads it calls and the
 * aggregation `sn_field_rows` that turns a member of every Station, JobClass
 * or NodeDef record into one per-record field.
 *
 * Extents: a Matrix has rows x cols; a container has its size, and records the
 * 1-D extent of each element (a container's size, a vector Matrix's length),
 * kEmptyExtent for an empty element and kNoExtent for one with no 1-D extent
 * (a scalar, a 2-D Matrix).
 */
 
#include <cstddef>
#include <functional>
#include <limits>
#include <map>
#include <set>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
#include "line/lang/qn/network_struct.h"
#include "line/util/matrix.h"
 
namespace line {
namespace api {
 
constexpr long kNoExtent = -1;
constexpr long kEmptyExtent = -2;
 
/** The view of one field. */
struct SnFieldView {
    std::string kind = "opaque";
    bool empty = false;
    int ndim = 0;          ///< 0 scalar-like, 1 container, 2 Matrix
    long rows = 0;         ///< Matrix rows, container size
    long cols = 0;         ///< Matrix cols
    std::vector<long> elems;  ///< per-element 1-D extent of a container
};
 
/** The view of a whole struct: its dimensions and one view per contract field, by MATLAB name. */
struct SnFieldViews {
    std::map<char, double> dims;
    std::map<std::string, SnFieldView> fields;
};
 
/** The 1-D extent of a field view: a container's size, a vector Matrix's length. */
inline long sn_view_extent(const SnFieldView& v) {
    if (v.empty) {
        return kEmptyExtent;
    }
    if (v.ndim == 1) {
        return v.rows;
    }
    if (v.ndim == 2 && (v.rows == 1 || v.cols == 1)) {
        return v.rows * v.cols;
    }
    return kNoExtent;
}
 
namespace detail {
template <class X, class = void>
struct is_container : std::false_type {};
template <class X>
struct is_container<X, std::void_t<typename X::value_type, decltype(std::declval<const X&>().begin()),
                                   decltype(std::declval<const X&>().size())>> : std::true_type {};
template <class X>
struct is_map : std::false_type {};
template <class K, class V, class C, class A>
struct is_map<std::map<K, V, C, A>> : std::true_type {};
template <class X>
struct is_function : std::false_type {};
template <class S>
struct is_function<std::function<S>> : std::true_type {};
template <class X>
struct is_matrix : std::false_type {};
template <class U>
struct is_matrix<Matrix<U>> : std::true_type {};
}  // namespace detail
 
template <class X>
SnFieldView sn_field_view(const X& x);
 
namespace detail {
template <class X>
long element_extent(const X& x) {
    if constexpr (is_matrix<X>::value || is_map<X>::value || is_function<X>::value ||
                  std::is_same<X, std::string>::value ||
                  (is_container<X>::value && !std::is_same<X, std::string>::value)) {
        return sn_view_extent(sn_field_view(x));
    } else {
        (void)x;
        return kNoExtent;
    }
}
}  // namespace detail
 
/** The view of one value; the kind follows its C++ type. */
template <class X>
SnFieldView sn_field_view(const X& x) {
    SnFieldView v;
    if constexpr (detail::is_matrix<X>::value) {
        v.kind = "Matrix";
        v.ndim = 2;
        v.rows = static_cast<long>(x.rows());
        v.cols = static_cast<long>(x.cols());
        v.empty = x.rows() == 0 || x.cols() == 0;
    } else if constexpr (std::is_same<X, std::string>::value) {
        v.kind = "string";
        v.empty = x.empty();
    } else if constexpr (detail::is_function<X>::value) {
        v.kind = "function";
        v.empty = !static_cast<bool>(x);
    } else if constexpr (detail::is_map<X>::value) {
        v.kind = "map";
        v.ndim = 1;
        v.rows = static_cast<long>(x.size());
        v.empty = x.empty();
        for (const auto& kv : x) {
            v.elems.push_back(detail::element_extent(kv.second));
        }
    } else if constexpr (detail::is_container<X>::value) {
        v.kind = "vector";
        v.ndim = 1;
        v.rows = static_cast<long>(x.size());
        v.empty = x.size() == 0;
        for (const auto& e : x) {
            using E = typename std::decay<decltype(e)>::type;
            v.elems.push_back(detail::element_extent(static_cast<const E&>(e)));
        }
    } else if constexpr (std::is_arithmetic<X>::value || std::is_enum<X>::value) {
        v.kind = "scalar";
    } else {
        v.kind = "opaque";
    }
    return v;
}
 
/** One field made of a member of every record (Station, JobClass, NodeDef), in record order. */
template <class R, class F>
SnFieldView sn_field_rows(const std::vector<R>& records, F member) {
    SnFieldView v;
    v.ndim = 1;
    v.rows = static_cast<long>(records.size());
    v.empty = true;
    bool first = true;
    for (const auto& r : records) {
        SnFieldView e = member(r);
        if (first) {
            v.kind = e.kind;
            first = false;
        } else if (e.kind != v.kind) {
            v.kind = "mixed";
        }
        v.empty = v.empty && e.empty;
        v.elems.push_back(sn_view_extent(e));
    }
    if (first) {
        v.kind = "vector";
    }
    // scalar records carry no per-element extent, and a record of scalars is never empty
    if (v.kind == "scalar") {
        v.empty = records.empty();
    }
    return v;
}
 
/** The dimensions the contract's shapes are written in. */
template <class T>
std::map<char, double> sn_contract_dims(const qn::NetworkStruct<T>& sn) {
    return {{'M', static_cast<double>(sn.nstations)},       {'K', static_cast<double>(sn.nclasses)},
            {'N', static_cast<double>(sn.nof_nodes())},     {'S', static_cast<double>(sn.nof_stateful())},
            {'C', static_cast<double>(sn.nchains)},         {'R', static_cast<double>(sn.regions.size())}};
}
 
}  // namespace api
}  // namespace line
 
#endif  // LINE_API_SN_SN_FIELD_VIEW_H