;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; This file is part of "NOVA":  NOVA = search + COCOMO tools
; Copyright, 2008, Tim Menzies tim@menzies.us
;
; NOVA is free software: you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation, either version 3 of the License, or
; (at your option) any later version.
;
; NOVA is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
; You should have received a copy of the GNU General Public License
; a long with NOVA.  If not, see <http://www.gnu.org/licenses/>.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(defun convergence (paths energy-reduction)
  "Returns the number of constraints needed to achieve the given energy
   reduction (as a percentage).  Small values for convergence indicate that
   the given energy reduction was achieved relatively quickly (i.e., with
   relatively few constraints)."
  (let (constraints)
    (dolist (path paths (mean constraints))
      (let* ((start-state     (car (states? path)))
	     (min-state       (min-energy? path))
	     (start-e         (energy? start-state))
	     (min-e           (energy? min-state))
	     (delta-e         (- start-e min-e))
	     (target-e        (- start-e (* delta-e energy-reduction))))
	(dolist (state (states? path))
	  (when (<= (energy? state) target-e)
	    (push (constraint-count state) constraints)
	    (return)))))))