TileNNEmulator Class Reference

Bit-exact software emulator of the TilePPr neural-network energy reconstruction. More...

#include <TileNNEmulator.h>

Collaboration diagram for TileNNEmulator:

Classes
struct	FixSpec
struct	Layer

Public Member Functions
bool	load (const std::string &jsonText, std::string &error)
int	nSamples () const
float	sValue (float hg, float lg) const
	Combined dual-gain input sample S = (hg + lgScale*lg) / denominator.
int64_t	run (const float *s) const
int	outFracBits () const
	Fractional bits of the output word (code * 2^-outFracBits() = value).
double	amplitudeScale () const

Private Types
enum class	Round { RND_CONV , TRN }
enum class	Sat { SAT , SAT_SYM , WRAP }
enum class	Op { Dense , LeakyRelu }

Static Private Member Functions
static int64_t	rshiftRoundHalfEven (int64_t v, int k)
static int64_t	castTo (int64_t v, int fracFrom, const FixSpec &spec)

Private Attributes
int	m_nSamples = 0
double	m_lgScale = 0.0
double	m_denominator = 0.0
double	m_ampScale = 0.0
FixSpec	m_inT
FixSpec	m_castT
std::vector< Layer >	m_layers

Detailed Description

Bit-exact software emulator of the TilePPr neural-network energy reconstruction.

Definition at line 15 of file TileNNEmulator.h.

Member Enumeration Documentation

Op

enum class TileNNEmulator::Op

strongprivate

Enumerator
Dense
LeakyRelu

Definition at line 53 of file TileNNEmulator.h.

{ Dense, LeakyRelu };

Round

enum class TileNNEmulator::Round

strongprivate

Enumerator
RND_CONV
TRN

Definition at line 42 of file TileNNEmulator.h.

{ RND_CONV, TRN };

Sat

enum class TileNNEmulator::Sat

strongprivate

Enumerator
SAT
SAT_SYM
WRAP

Definition at line 43 of file TileNNEmulator.h.

{ SAT, SAT_SYM, WRAP };

Member Function Documentation

amplitudeScale()

double TileNNEmulator::amplitudeScale ( ) const

inline

Definition at line 39 of file TileNNEmulator.h.

{ return m_ampScale; }

castTo()

int64_t TileNNEmulator::castTo ( int64_t v, int fracFrom, const FixSpec & spec )

staticprivate

Definition at line 20 of file TileNNEmulator.cxx.

                                                                           {
  int d = fracFrom - spec.frac();
  if (d > 0) {
    v = (spec.round == Round::RND_CONV) ? rshiftRoundHalfEven(v, d) : (v >> d);
  } else if (d < 0) {
    v <<= -d;
  }
 
  int64_t lim = int64_t(1) << (spec.w - 1);
  switch (spec.sat) {
    case Sat::SAT:
      if (v < -lim) v = -lim;
      else if (v >= lim) v = lim - 1;
      break;
    case Sat::SAT_SYM:
      if (v <= -lim) v = -lim + 1;
      else if (v >= lim) v = lim - 1;
      break;
    case Sat::WRAP:
      v = ((v + lim) & ((int64_t(1) << spec.w) - 1)) - lim;
      break;
  }
 
  return v;
}

load()

bool TileNNEmulator::load	(	const std::string &	jsonText,
		std::string &	error )

Parameters

jsonText	the JSON document itself (not a file name, so the payload can later come from the conditions database)
error	filled with a diagnostic on failure

Returns

true on success, on any problem (malformed JSON, unknown op, size or type inconsistency) returns false and leaves the emulator unusable

Definition at line 98 of file TileNNEmulator.cxx.

                                                                     {
  using nlohmann::json;
 
  auto fix = [](const json& j) {
    FixSpec t;
    t.w = j.at("w").get<int>();
    t.i = j.at("i").get<int>();
    std::string r = j.at("round").get<std::string>();
    std::string s = j.at("sat").get<std::string>();
    if (r == "RND_CONV") t.round = Round::RND_CONV;
    else if (r == "TRN") t.round = Round::TRN;
    else throw std::runtime_error("unknown rounding mode '" + r + "'");
    if (s == "SAT") t.sat = Sat::SAT;
    else if (s == "SAT_SYM") t.sat = Sat::SAT_SYM;
    else if (s == "WRAP") t.sat = Sat::WRAP;
    else throw std::runtime_error("unknown saturation mode '" + s + "'");
 
    return t;
  };
 
  try {
    json cfg = json::parse(jsonText);
    if (cfg.at("format_version").get<int>() != 1) {
      throw std::runtime_error("unsupported format_version");
    }
 
    const json& in = cfg.at("input");
    m_nSamples = in.at("n_samples").get<int>();
    m_lgScale = in.at("lg_scale").get<double>();
    m_denominator = in.at("denominator").get<double>();
    m_inT = fix(in.at("in_t"));
    m_castT = fix(in.at("cast_t"));
    m_ampScale = cfg.at("output").at("amplitude_scale").get<double>();
    m_layers.clear();
    int width = m_nSamples;
    
    for (const json& jl : cfg.at("layers")) {
      Layer l;
      std::string op = jl.at("op").get<std::string>();
      if (op == "dense") {
        l.op = Op::Dense;
        l.nIn = jl.at("n_in").get<int>();
        l.nOut = jl.at("n_out").get<int>();
        l.weightT = fix(jl.at("weight_t"));
        l.accumT = fix(jl.at("accum_t"));
        l.biasT = fix(jl.at("bias_t"));
        l.outT = fix(jl.at("out_t"));
        l.w = jl.at("weights").get<std::vector<int64_t>>();
        l.b = jl.at("bias").get<std::vector<int64_t>>();
        if (l.w.size() != size_t(l.nIn) * l.nOut || l.b.size() != size_t(l.nOut)) {
          throw std::runtime_error("dense layer weight/bias size mismatch");
        }
 
        if (l.biasT.frac() < l.accumT.frac()) {
          throw std::runtime_error("bias grid coarser than accumulator grid");
        }
      } else if (op == "leaky_relu") {
        l.op = Op::LeakyRelu;
        l.nIn = l.nOut = jl.at("n").get<int>();
        l.alphaShift = jl.at("alpha_shift").get<int>();
        l.outT = fix(jl.at("out_t"));
      } else {
        throw std::runtime_error("unknown op '" + op + "'");
      }
 
      if (l.nIn != width) {
        throw std::runtime_error("layer input width " + std::to_string(l.nIn)
                                 + " does not chain from " + std::to_string(width));
      }
 
      width = l.nOut;
      m_layers.push_back(std::move(l));
    }
 
    if (m_layers.empty() || width != 1) {
      throw std::runtime_error("network must end in a single output");
    }
  } catch (const std::exception& e) {
    error = e.what();
    m_layers.clear();
 
    return false;
  }
 
  return true;
}

nSamples()

int TileNNEmulator::nSamples ( ) const

inline

Definition at line 27 of file TileNNEmulator.h.

{ return m_nSamples; }

outFracBits()

int TileNNEmulator::outFracBits ( ) const

inline

Fractional bits of the output word (code * 2^-outFracBits() = value).

Definition at line 38 of file TileNNEmulator.h.

{ return m_layers.back().outT.frac(); }

rshiftRoundHalfEven()

int64_t TileNNEmulator::rshiftRoundHalfEven ( int64_t v, int k )

staticprivate

Definition at line 10 of file TileNNEmulator.cxx.

                                                            {
  if (k <= 0) return v;
  int64_t q = v >> k; 
  int64_t r = v - (q << k);
  int64_t half = int64_t(1) << (k - 1);
  if (r > half || (r == half && (q & 1))) ++q;
 
  return q;
}

run()

int64_t TileNNEmulator::run

(

const float *

s

)

const

Returns

the raw integer code of the output fixed-point word

Definition at line 50 of file TileNNEmulator.cxx.

                                                {
  std::vector<int64_t> x(m_nSamples);
 
  for (int k = 0; k < m_nSamples; ++k) {
    // float -> in_t: ldexp scales by 2^frac exactly, llrint rounds the real
    // value half-to-even (FE_TONEAREST), i.e, AP_RND_CONV.
    int64_t c = std::llrint(std::ldexp(static_cast<double>(s[k]), m_inT.frac()));
    c = castTo(c, m_inT.frac(), m_inT);
    x[k] = castTo(c, m_inT.frac(), m_castT);
  }
 
  int frac = m_castT.frac();
  std::vector<int64_t> y;
 
  for (const Layer& l : m_layers) {
    if (l.op == Op::Dense) {
      y.assign(l.nOut, 0);
 
      for (int i = 0; i < l.nIn; ++i) {
        for (int j = 0; j < l.nOut; ++j) {
          int64_t p = x[i] * l.w[i * l.nOut + j];
          y[j] += castTo(p, frac + l.weightT.frac(), l.accumT);
        }
      }
 
      int up = l.biasT.frac() - l.accumT.frac();
 
      for (int j = 0; j < l.nOut; ++j) {
        y[j] = castTo((y[j] << up) + l.b[j], l.biasT.frac(), l.outT);
      }
    } else { 
      y.resize(l.nOut);
 
      for (int j = 0; j < l.nOut; ++j) {
        // Negative branch: multiplying by alpha = 2^-alphaShift is a
        // reinterpretation of the code at alphaShift more fractional bits.
        int from = (x[j] > 0) ? frac : frac + l.alphaShift;
        y[j] = castTo(x[j], from, l.outT);
      }
    }
    
    frac = l.outT.frac();
    x.swap(y);
  }
 
  return x[0];
}

sValue()

float TileNNEmulator::sValue	(	float	hg,
		float	lg ) const

Combined dual-gain input sample S = (hg + lgScale*lg) / denominator.

Definition at line 46 of file TileNNEmulator.cxx.

                                                     {
  return static_cast<float>((hg + m_lgScale * lg) / m_denominator);
}

Member Data Documentation

m_ampScale

double TileNNEmulator::m_ampScale = 0.0

private

Definition at line 69 of file TileNNEmulator.h.

m_castT

FixSpec TileNNEmulator::m_castT

private

Definition at line 70 of file TileNNEmulator.h.

m_denominator

double TileNNEmulator::m_denominator = 0.0

private

Definition at line 68 of file TileNNEmulator.h.

m_inT

FixSpec TileNNEmulator::m_inT

private

Definition at line 70 of file TileNNEmulator.h.

m_layers

std::vector<Layer> TileNNEmulator::m_layers

private

Definition at line 71 of file TileNNEmulator.h.

m_lgScale

double TileNNEmulator::m_lgScale = 0.0

private

Definition at line 67 of file TileNNEmulator.h.

m_nSamples

int TileNNEmulator::m_nSamples = 0

private

Definition at line 66 of file TileNNEmulator.h.

---

The documentation for this class was generated from the following files:

• TileNNEmulator.h
• TileNNEmulator.cxx