; Implementation notes for Axe
;
; Copyright (C) 2021 Kestrel Institute
;
; License: A 3-clause BSD license. See the file books/3BSD-mod.txt.
;
; Author: Eric Smith (eric.smith@kestrel.edu)

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;; Data Strutctures ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Major data structures used by Axe:
  term - pseudo-termp
  dag - pseudo-dagp (or sometimes weak-dagp)
  dag-array - pseudo-dag-arrayp
  dag-array with accompanying indices (dag-parent-array, dag-constant-alist, dag-variable-alist) - wf-dagp

;;; Conversions ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Converting a term to a dag:
  Using the basic-evaluator for ground terms: make-term-into-dag-basic

Converting a term to a dag-array:
  Using the basic-evaluator for ground terms: make-term-into-dag-array-basic

Converting a dag to a dag-array:
  make-into-array (TODO: Use make-dag-into-array instead?)
  also make-dag-into-array and make-dag-into-array2

Converting a dag-array to a dag:
  array-to-alist (TODO: Make a function dag-array-to-dag)

Converting a dag to a term (may explode!):
  dag-to-term (but see also "Dropping non-supporters" below)
  dag-to-term-with-lets
  dag-to-term-with-lets-simple

Functions to build dag-arrays:
  dag-array-builder2.lisp: Assume the standard array names
  dag-array-builders2.lisp: Take the array names as arguments
  dag-array-builders3.lisp: Assume the standard array names, update the memoization

Building auxiliary data structures for a dag-array: make-dag-indices

;;; Algorithms ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

By "dag" we mean a DAG represented as a list (see pseudo-dagp).

DAG Size (number of nodes in corresponding tree):
 of an entire dag: dag-size in dag-size.lisp (bottom-up, TODO: Make a version that doesn't go to an array)
 of an entire dag-array: see make-size-array-for-dag-array in dag-size.lisp (bottom-up)
 of one or more nodes in a dag-array: dag-size2.lisp (top-down, worklist)

Getting all supporting vars (all vars on which a dag or node depends):
 of an entire dag: dag-vars in dags.lisp (bottom-up, takes a dag)
 of one or more nodes in a dag-array: supporting-vars.lisp (worklist, modernize?)

Getting all supporting functions:
 of an entire dag: dag-fns in dags.lisp (bottom-up, takes a dag)

Getting all supporting nodes:
 of a node in a dag-array: supporters-of-node in supporting-nodes.lisp (top-down, no worklist)

Dropping non-supporters:
 of a dag-array, returning a dag: drop-non-supporters-array in supporting-nodes.lisp (tags nodes top-down (non-worklist), rebuilds bottom-up)
 of two nodes in a dag-array, returning a dag: drop-non-supporters-array-two-nodes
 of a dag: drop-non-supporters in supporting-nodes.lisp (uses an array internally TODO: don't use an array)
 of a dag-array: crunch-dag-array-for-nodenums? crunch-dag-array2?

Merging a dag into a dag-array:
 merge-nodes-into-dag-array in merge-nodes-into-dag-array.lisp (bottom-up (needs the dag to come in reversed) returns aux structures and renaming-array)

Merging 2 dags:
 merge-dag-into-dag-quick (returns a dag, TODO: carve out the part that returns an array and aux structures)

Merging terms into a dag-array:
 merge-term-into-dag-array-basic and merge-terms-into-dag-array-basic (use the basic-evaluator, could be generated by a macro)

Merging axe trees into a dag-array:
 merge-tree-into-dag-array-basic and merge-trees-into-dag-array-basic (use the basic-evaluator, could be generated by a macro)

Computing contexts of nodes in a dag-array:
 make-full-context-array (top-down, no worklist)
