docs: def sample_upper_hull(upper_hull, random_stream):
      """
      Return a single value randomly sampled from
      the given `upper_hull`.
  
      Parameters
      ----------
      upper_hull : List[pyars.hull.HullNode]
          Upper hull to evaluate.
  
      random_stream : numpy.random.RandomState
          (Seeded) stream of random values to use during sampling.
  
      Returns
      ----------
      sample : float
          Single value randomly sampled from `upper_hull`.
  
      """
      cdf = cumsum([node.pr for node in upper_hull])
  
      # randomly choose a line segment
      U = random_stream.rand()
  
      node = next(
          (node for node, cdf_value in zip(upper_hull, cdf) if U < cdf_value),
          upper_hull[-1]  # default is last line segment
      )
  
      # sample along that line segment
      U = random_stream.rand()
  
      m, left, right = node.m, node.left, node.right
  
      M = max(m * right, m * left)
      x = (log(U * (exp(m * right - M) - exp(m * left - M)) + exp(m * left - M)) + M) / m
  
      assert(x >= left and x <= right)
  
      if isinf(x) or isnan(x):
          raise ValueError("sampled an infinite or 'nan' x")
  
      return x