# The {HotPath} backtracking search algorithm for fast(est) "hot" toolpath.

import hotpath_IMP

def solve(preph, BCS, SMS, Qbest, tcpufin, mp_jump):
  # The argument {BCS} must be a list of {Block} objects, and {SMS} must
  # be a list of {Seam} objects. 
  #
  # Te procedure recursively enumerates every /candidate path/:
  # a path that begins with the path {preph}, includes exactly one choice from each block
  # in {BCS}, satisfies the ordering contraints of all seams in
  # {SMS}.  Among those candidate path, it will
  # look for a /valid path/ -- one that also satisfies all cooling time 
  # constraints of {SMS}.  The procedure can be used to find
  # the valid path that has smallest fabtime.
  #
  # The procedure assumes that {Qbest}, if not {None}, is a valid toolpath,
  # The procedure will return {QBest} if it cannot find any valid tool-path
  # with better fabtime.
  # 
  # If the input block list has more than a dozen blocks or so, it is
  # usually impossible to enumerate all candidate paths, or even of all
  # valid paths that are better tha {Qbest}. Thus, there are provisions
  # to reduce the search by restricting the set of candidates to be
  # examined, and/or limiting the time spent in the search.
  # ???
  # {Qbest} is not {None}, or if it has managed to find
  # /some/ valid tool-path, it starts checking regularly the current
  # accumulated CPU clock. Once that clock reaches {tcpufin}, returns
  # the best valid path found (possibly {Qbest}).
  #
  # If {Qbest} is {None}, the procedure will ignore {tcpufin} until it
  # has found /some/ valid path. The user should impose a CPU limit
  # externally to get it to abort in this case.
  #
  # The procedure returns {None} if it found no valid candidate path.
  # 
  return hotpath_IMP.solve(preph, BCS, SMS, sufph, Qbest, tcpufin, mp_jump)