driver.hpp

Go to the documentation of this file.

#pragma once
 
#include "engine.hpp"
#include "game.hpp"
#include "runner.hpp"
#include <chrono>
#include <cstdlib>
#include <fstream>
#include <limits>
#include <vector>
 
namespace jaffarPlus
{
 
class Driver final
 
{
public:
  enum exitReason_t
  {
    winStateFound = 0, 
 
    outOfStates = 1, 
 
    maximumStepReached = 2, 
 
    bestBelowReference = 3, 
 
    inputHistoryNearCapacity = 4 
  };
 
  Driver(const std::string& configFilePath, const nlohmann::json& config) : _configFilePath(configFilePath)
  {
    // Getting job identifier from the system timer
    auto currentTime = std::chrono::system_clock::now();
    _jobId           = std::chrono::duration_cast<std::chrono::seconds>(currentTime.time_since_epoch()).count();
 
    // Mutable working copy of the root config; each recognized key is consumed (popped) below, so any
    // leftover key at the end is unrecognized (a typo or unsupported option) and is reported by name.
    auto configRemaining = config;
 
    // Getting driver configuration
    auto driverConfig = jaffarCommon::json::popObject(configRemaining, "Driver Configuration");
 
    // Getting end win delay config
    _endOnFirstWinState = jaffarCommon::json::popBoolean(driverConfig, "End On First Win State");
 
    // Getting maximum number of steps (zero is not established)
    _maxSteps = jaffarCommon::json::popNumber<uint32_t>(driverConfig, "Max Steps");
 
    // For testing purposes, the maximum number of steps can be overriden via environment variables
    if (auto* value = std::getenv("JAFFAR_DRIVER_OVERRIDE_DRIVER_MAX_STEP")) _maxSteps = std::stoul(value);
 
    // Getting intermediate result configuration
    auto saveIntermediateResultsJs     = jaffarCommon::json::popObject(driverConfig, "Save Intermediate Results");
    _saveIntermediateResultsEnabled    = jaffarCommon::json::popBoolean(saveIntermediateResultsJs, "Enabled");
    _saveIntermediateFrequency         = jaffarCommon::json::popNumber<float>(saveIntermediateResultsJs, "Frequency (s)");
    _saveIntermediateBestSolutionPath  = jaffarCommon::json::popString(saveIntermediateResultsJs, "Best Solution Path");
    _saveIntermediateWorstSolutionPath = jaffarCommon::json::popString(saveIntermediateResultsJs, "Worst Solution Path");
    jaffarCommon::json::checkEmpty(saveIntermediateResultsJs, "Driver Configuration > Save Intermediate Results");
 
    // Optional reference reward floor: cancel the whole job if the BEST state's reward falls below a
    // per-step reference reward trace (beyond tolerance). This is purely a driver-level stopping criterion
    // and diagnostic -- it does NOT prune states (recoverable slower-then-faster lines are kept); it only
    // detects the first step at which the leading edge falls behind the reference (e.g. a reference TAS) and
    // stops, so the run isn't ground on once it can no longer keep pace. Reward must be monotone-comparable.
    _referenceFloorEnabled   = false;
    _referenceFloorTolerance = 0.0f;
    if (driverConfig.contains("Reference Reward Floor"))
    {
      auto refJs               = jaffarCommon::json::popObject(driverConfig, "Reference Reward Floor");
      _referenceFloorEnabled   = jaffarCommon::json::popBoolean(refJs, "Enabled");
      _referenceFloorTolerance = jaffarCommon::json::popNumber<float>(refJs, "Tolerance");
      const auto refPath       = jaffarCommon::json::popString(refJs, "Path");
      jaffarCommon::json::checkEmpty(refJs, "Driver Configuration > Reference Reward Floor");
      // The trace file is a runtime artifact: only open it for a real run. Under --dryRun (JAFFAR_IS_DRY_RUN)
      // we validate the config shape but skip the read, matching how ROM / initial-solution files are deferred
      // to engine init (which dryRun never reaches) -- so config validation does not depend on the cwd-relative
      // trace being present next to the build directory.
      if (_referenceFloorEnabled && std::getenv("JAFFAR_IS_DRY_RUN") == nullptr)
      {
        std::ifstream f(refPath);
        if (f.good() == false) JAFFAR_THROW_RUNTIME("[ERROR] Could not open 'Reference Reward Floor' > 'Path': '%s'\n", refPath.c_str());
        float v;
        while (f >> v) _referenceReward.push_back(v);
        jaffarCommon::logger::log("[J+] Reference reward floor enabled: %lu steps loaded, tolerance %.4f\n", _referenceReward.size(), _referenceFloorTolerance);
      }
    }
 
    jaffarCommon::json::checkEmpty(driverConfig, "Driver Configuration");
 
    // Getting component configurations (consumed from the root so the root check below can flag strays)
    auto emulatorConfig = jaffarCommon::json::popObject(configRemaining, "Emulator Configuration");
    auto gameConfig     = jaffarCommon::json::popObject(configRemaining, "Game Configuration");
    auto runnerConfig   = jaffarCommon::json::popObject(configRemaining, "Runner Configuration");
    auto engineConfig   = jaffarCommon::json::popObject(configRemaining, "Engine Configuration");
 
    // Any remaining top-level key is unrecognized
    jaffarCommon::json::checkEmpty(configRemaining, "configuration root");
 
    // Creating runner from the configuration
    _runner = jaffarPlus::Runner::getRunner(emulatorConfig, gameConfig, runnerConfig);
 
    // Creating engine from the configuration
    _engine = std::make_unique<Engine>(emulatorConfig, gameConfig, runnerConfig, engineConfig);
  }
 
  ~Driver() {}
 
  void initialize()
  {
    // Resetting step counter
    _currentStep = 0;
 
    // Resetting win state counter
    _winStatesFound = 0;
 
    // Resetting best states reward
    _bestWinStateReward   = -std::numeric_limits<float>::infinity();
    _bestStateReward      = -std::numeric_limits<float>::infinity();
    _bestStateFloorReward = -std::numeric_limits<float>::infinity();
 
    // Resetting worst state reward
    _worstStateReward = std::numeric_limits<float>::infinity();
 
    // Initializing runner
    _runner->initialize();
 
    // Initializing engine
    _engine->initialize();
 
    // Allocating space for the current best and worst states. These are standalone snapshots outside the
    // NUMA slabs, so they hold the FULL self-contained state ([hot]+[history]), not just the hot slot.
    _stateSize = _engine->getFullStateSize();
    _bestStateStorage.resize(_stateSize);
    _worstStateStorage.resize(_stateSize);
  }
 
  int run()
  {
    // Internal flag to indicate we are still running
    _hasFinished = false;
 
    // If using ncurses, initialize terminal now
    jaffarCommon::logger::initializeTerminal();
 
    // Storage for the exit
    exitReason_t exitReason;
 
    // Starting intermediate result saving thread
    std::thread intermediateResultSaverThread;
    if (_saveIntermediateResultsEnabled == true) intermediateResultSaverThread = std::thread([this]() { intermediateResultSaveLoop(); });
 
    // Running engine until a termination point
    while (true)
    {
      // If found winning state, report it now
      if (_endOnFirstWinState && _engine->getWinStatesFound() > 0)
      {
        exitReason = exitReason_t::winStateFound;
        break;
      }
 
      // If ran out of states, finish now
      if (_engine->getStateCount() == 0)
      {
        exitReason = _engine->getWinStatesFound() > 0 ? exitReason_t::winStateFound : exitReason_t::outOfStates;
        break;
      }
 
      // If maximum step established and reached, finish now
      if (_maxSteps > 0 && _currentStep >= _maxSteps)
      {
        if (_winStatesFound > 0) exitReason = exitReason_t::winStateFound;
        if (_winStatesFound == 0) exitReason = exitReason_t::maximumStepReached;
        break;
      }
 
      // Updating best and worst states
      updateBestState();
      updateWorstState();
 
      // Reference reward floor: if the best leading edge has fallen below the reference at this step, the run
      // can no longer keep pace with the reference -- cancel now (purely a stop signal; nothing was pruned).
      if (_referenceFloorEnabled && _currentStep < _referenceReward.size() && _bestStateFloorReward < _referenceReward[_currentStep] - _referenceFloorTolerance)
      {
        jaffarCommon::logger::log("[J+] Best (%.6f) fell below reference floor (%.6f, tol %.4f) at step %lu by %.6f -- cancelling.\n", _bestStateFloorReward,
                                  _referenceReward[_currentStep], _referenceFloorTolerance, _currentStep,
                                  _referenceReward[_currentStep] - _referenceFloorTolerance - _bestStateFloorReward);
        exitReason = exitReason_t::bestBelowReference;
        break;
      }
 
      // Input-history backing guard: the "Trie" strategy's shared node pool grows ~ live-states x depth
      // toward a hard ceiling (getInputHistoryMaxMemoryBytes). Stop GRACEFULLY at a high-water mark -- or, as
      // a backstop, if a worker already latched the pool exhausted -- so the search saves its best result and
      // exits cleanly, instead of a worker hitting the ceiling mid-step and terminating the whole process.
      // No-op for None/Raw (ceiling 0): their history lives in the StateDb slot, already bounded.
      {
        const size_t ihCeiling = _engine->getInputHistoryMaxMemoryBytes();
        if (ihCeiling > 0)
        {
          const size_t ihNow     = _engine->getInputHistoryApproxMemoryBytes();
          const bool   exhausted = _engine->isInputHistoryExhausted();
          if (exhausted || ihNow >= (size_t)((double)ihCeiling * _inputHistoryCapacityWatermark))
          {
            const double GB = 1024.0 * 1024.0 * 1024.0;
            jaffarCommon::logger::log("[J+] Input-history trie at %.1f / %.1f GB (%.0f%% of its hard ceiling)%s at step %lu -- stopping "
                                      "gracefully. The Trie node pool grows ~ live-states x depth and cannot be enlarged past RAM; switch "
                                      "Store Input History Type to \"Raw\" (bounded by 'State Database/Max Size (Mb)'), or lower the State "
                                      "DB size so fewer live states slow the trie's growth.\n",
                                      (double)ihNow / GB, (double)ihCeiling / GB, 100.0 * (double)ihNow / (double)ihCeiling, exhausted ? " (pool exhausted)" : "", _currentStep);
            exitReason = exitReason_t::inputHistoryNearCapacity;
            break;
          }
        }
      }
 
      // Storing manually saved solution, if required
      storeManualSaveSolution();
 
      // Printing information
      printInfo();
 
      // Running engine step
      _engine->runStep();
 
      // Summing amount of win states found
      _winStatesFound = _engine->getWinStatesFound();
 
      // Increasing step counter
      _currentStep++;
    }
 
    // Setting finalized flag
    _hasFinished = true;
 
    // Waiting for saver thread
    if (_saveIntermediateResultsEnabled == true) intermediateResultSaverThread.join();
 
    // If using ncurses, terminate terminal now
    jaffarCommon::logger::finalizeTerminal();
 
    // Updating and storing best states
    updateBestState();
    saveBestStateInformation();
 
    // Final report
    printInfo();
 
    // Otherwise return the reason why we stopped
    return exitReason;
  }
 
  void storeManualSaveSolution()
  {
    auto manualSaveSolution = _engine->getManualSaveSolution();
 
    if (manualSaveSolution.path != "")
    {
      // Loading the saved state into the runner (its depth was recorded at capture; set it before
      // deserializing so the trie can rebuild and the solution renders to the right length).
      _runner->setStepCount(manualSaveSolution.stepCount);
      _engine->getStateDb()->loadStateIntoRunner(*_runner, manualSaveSolution.stateData);
 
      // Saving manually stored solution
      std::string solutionData = _runner->getInputHistoryString();
      jaffarCommon::file::saveStringToFile(solutionData, manualSaveSolution.path);
    }
  }
 
  void saveBestStateInformation()
  {
    // Making sure the main thread is not currently writing
    _updateIntermediateResultMutex.lock();
 
    // Saving best solution and state
    std::string jobSuffix  = std::string(".") + std::to_string(_jobId);
    std::string stepSuffix = std::string(".") + std::to_string(_currentStep);
 
    // Saving files with standard name
    if (_saveIntermediateBestSolutionPath != "") jaffarCommon::file::saveStringToFile(_bestSolutionStorage, _saveIntermediateBestSolutionPath);
 
    // Saving files with a job suffix and step number
    if (_saveIntermediateBestSolutionPath != "") jaffarCommon::file::saveStringToFile(_bestSolutionStorage, _saveIntermediateBestSolutionPath + jobSuffix + stepSuffix);
 
    // Making sure the main thread is not currently writing
    _updateIntermediateResultMutex.unlock();
  }
 
  void saveWorstStateInformation()
  {
    // Making sure the main thread is not currently writing
    _updateIntermediateResultMutex.lock();
 
    // Saving best solution and state
    std::string jobSuffix = std::string(".") + std::to_string(_jobId);
 
    // Saving best solution and state
    if (_saveIntermediateWorstSolutionPath != "") jaffarCommon::file::saveStringToFile(_worstSolutionStorage, _saveIntermediateWorstSolutionPath);
 
    // Saving best solution and state
    if (_saveIntermediateWorstSolutionPath != "") jaffarCommon::file::saveStringToFile(_worstSolutionStorage, _saveIntermediateWorstSolutionPath + jobSuffix);
 
    // Making sure the main thread is not currently writing
    _updateIntermediateResultMutex.unlock();
  }
 
  void intermediateResultSaveLoop()
  {
    // Timer for saving to file
    auto lastSaveTime = jaffarCommon::timing::now();
 
    // Run loop while the driver is still running
    while (_hasFinished == false)
    {
      // Sleeping for 100ms intervals to prevent excessive overheads
      usleep(100000);
 
      // Getting time elapsed since last save
      auto currentTime              = jaffarCommon::timing::now();
      auto timeElapsedSinceLastSave = jaffarCommon::timing::timeDeltaSeconds(currentTime, lastSaveTime);
 
      // Checking if we need to save best state
      if (timeElapsedSinceLastSave > _saveIntermediateFrequency && _currentStep > 1)
      {
        // Saving worst and best state information
        saveBestStateInformation();
        saveWorstStateInformation();
 
        // Resetting timer
        lastSaveTime = jaffarCommon::timing::now();
      }
    }
  }
 
  void updateWorstState()
  {
    // If no states in database, there is nothing to update
    if (_engine->getStateDb()->getStateCount() == 0) return;
 
    // Making sure the intermediate result thread is not currently reading
    _updateIntermediateResultMutex.lock();
 
    // Getting worst state so far
    auto worstState = _engine->getStateDb()->getWorstState();
 
    // Saving worst state into the storage (gather hot slab slot + its cold history into the full buffer)
    _engine->getStateDb()->captureSlotToBuffer(worstState, _worstStateStorage.data());
 
    // The worst state belongs to the current frontier, so its depth is the current search step (the step
    // counter is not stored per-state). Set it before loading so the solution renders to the right length.
    _runner->setSearchStep(_currentStep);
    _engine->getStateDb()->loadStateIntoRunner(*_runner, _worstStateStorage.data());
 
    // Saving worst solution into storage
    _worstSolutionStorage = _runner->getInputHistoryString();
 
    // Updating worst state reward
    _worstStateReward = _runner->getGame()->getReward();
 
    // Making sure the intermediate result thread is not currently reading
    _updateIntermediateResultMutex.unlock();
  }
 
  void updateBestState()
  {
    // If no states in database and no win states, there is nothing to update
    if (_engine->getStateDb()->getStateCount() == 0 && _winStatesFound == 0) return;
 
    // Making sure the intermediate result thread is not currently reading
    _updateIntermediateResultMutex.lock();
 
    // If we haven't found any winning state, simply use the currently best state
    if (_winStatesFound == 0)
    {
      // Getting best state so far
      auto bestState = _engine->getStateDb()->getBestState();
 
      // Saving best state into the storage (gather hot slab slot + its cold history into the full buffer)
      if (bestState != nullptr) _engine->getStateDb()->captureSlotToBuffer(bestState, _bestStateStorage.data());
    }
 
    // If we have found a winning state in this step that improves on the current best, save it now
    if (_engine->getWinStatesFound() > 0)
    {
      // Getting best win state (best reward) for the current step
      auto winStateEntry = _engine->getStepBestWinState();
 
      // If the reward if better than the current best, then make it the new best state
      if (winStateEntry.reward > _bestWinStateReward)
      {
        // Saving new best
        _bestWinStateReward = winStateEntry.reward;
 
        // Saving win state into the storage (and remembering its depth for solution rendering)
        memcpy(_bestStateStorage.data(), winStateEntry.stateData, _stateSize);
        _bestWinStateStepCount = winStateEntry.stepCount;
      }
    }
 
    // Set the runner's step counter to the best state's depth before loading (the counter is not stored
    // per-state): a win's depth was recorded at capture; an ordinary best belongs to the current frontier.
    if (_winStatesFound > 0)
      _runner->setStepCount(_bestWinStateStepCount);
    else
      _runner->setSearchStep(_currentStep);
    _bestStateStepCount = _runner->getStepCount(); // remembered so the printInfo reload uses the same depth
    _engine->getStateDb()->loadStateIntoRunner(*_runner, _bestStateStorage.data());
 
    // Updating best state reward
    _bestStateReward      = _runner->getGame()->getReward();
    _bestStateFloorReward = _runner->getGame()->getFloorReward(); // un-biased position for the Reference Reward Floor (decoupled from the magnet)
 
    // Storing best solution
    _bestSolutionStorage = _runner->getInputHistoryString();
 
    // Making sure the intermediate result thread is not currently reading
    _updateIntermediateResultMutex.unlock();
  }
 
  void printInfo()
  {
    // If using ncurses, clear terminal before printing the information for this step
    jaffarCommon::logger::clearTerminal();
 
    // Printing information
    jaffarCommon::logger::log("[J+] Job Id:                                      %lu\n", _jobId);
    jaffarCommon::logger::log("[J+] Script File:                                 '%s'\n", _configFilePath.c_str());
    jaffarCommon::logger::log("[J+] Emulator Name:                               '%s'\n", _runner->getGame()->getEmulator()->getName().c_str());
    jaffarCommon::logger::log("[J+] Game Name:                                   '%s'\n", _runner->getGame()->getName().c_str());
    jaffarCommon::logger::log("[J+] Current Step #:                              %lu", _currentStep);
    if (_maxSteps > 0) jaffarCommon::logger::log(" (Max: %lu)", _maxSteps);
    jaffarCommon::logger::log("\n");
 
    if (_winStatesFound == 0)
      jaffarCommon::logger::log("[J+] Current Reward (Best / Worst):               %.6f / %.6f (Diff: %.6f)\n", _bestStateReward, _worstStateReward,
                                _bestStateReward - _worstStateReward);
 
    if (_winStatesFound > 0)
      jaffarCommon::logger::log("[J+] Current Reward (Win / Worst):                %.6f / %.6f (Diff: %.6f)\n", _bestStateReward, _worstStateReward,
                                _bestStateReward - _worstStateReward);
 
    // When a reference reward floor is active, show the reference reward at this step and how the best
    // compares to it (positive = best ahead of the reference, negative = best behind), for easy human review.
    if (_referenceFloorEnabled)
    {
      if (_currentStep < _referenceReward.size())
        jaffarCommon::logger::log("[J+] Reference Reward (Best - Ref):               %.6f (Best %+.6f, tol %.4f)\n", _referenceReward[_currentStep],
                                  _bestStateFloorReward - _referenceReward[_currentStep], _referenceFloorTolerance);
      else
        jaffarCommon::logger::log("[J+] Reference Reward (Best - Ref):               (none: step beyond reference trace)\n");
    }
 
    // Printing engine information
    jaffarCommon::logger::log("[J+] Engine Information: \n");
    _engine->printInfo();
 
    // Loading best state into runner (same depth updateBestState() used, so the trie rebuilds correctly)
    _runner->setStepCount(_bestStateStepCount);
    _engine->getStateDb()->loadStateIntoRunner(*_runner, _bestStateStorage.data());
 
    // Printing best state information to screen
    jaffarCommon::logger::log("[J+] Runner Information (Best State): \n");
    _runner->printInfo();
    jaffarCommon::logger::log("[J+] Game Information (Best State): \n");
    _runner->getGame()->printInfo();
    jaffarCommon::logger::log("[J+] Emulator Information (Best State): \n");
    _runner->getGame()->getEmulator()->printInfo();
 
    // Division rule to separate different steps
    jaffarCommon::logger::log("[J+] --------------------------------------------------------------\n");
 
    // If using ncurses, refresh terminal now
    jaffarCommon::logger::refreshTerminal();
  }
 
  static std::unique_ptr<Driver> getDriver(const std::string& configFilePath, const nlohmann::json& config)
  {
    // Creating new engine
    auto d = std::make_unique<Driver>(configFilePath, config);
 
    // Returning engine
    return d;
  }
 
  size_t getCurrentStep() { return _currentStep; }
 
private:
  const std::string _configFilePath; 
 
  std::unique_ptr<Engine> _engine; 
 
  std::unique_ptr<Runner> _runner; 
 
  size_t _jobId; 
 
  size_t _maxSteps; 
 
  size_t _currentStep; 
 
  bool _endOnFirstWinState; 
 
  size_t _winStatesFound; 
 
  float  _bestWinStateReward;        
  size_t _bestWinStateStepCount = 0; 
  size_t _bestStateStepCount    = 0; 
 
  float _bestStateReward;      
  float _bestStateFloorReward; 
 
  float _worstStateReward; 
 
  bool               _referenceFloorEnabled;   
  float              _referenceFloorTolerance; 
  std::vector<float> _referenceReward;         
 
  double _inputHistoryCapacityWatermark = 0.95;
 
  std::string _bestStateStorage; 
 
  std::string _worstStateStorage; 
 
  std::string _bestSolutionStorage; 
 
  std::string _worstSolutionStorage; 
 
  size_t _stateSize; 
 
  __volatile__ bool _hasFinished; 
 
 
  bool _saveIntermediateResultsEnabled; 
 
  float _saveIntermediateFrequency; 
 
  std::string _saveIntermediateBestSolutionPath; 
 
  std::string _saveIntermediateWorstSolutionPath; 
 
  std::mutex _updateIntermediateResultMutex; 
};
 
} // namespace jaffarPlus