This is the README file for /books/projects/apply-model/.

The material on this directory is in support of the paper
"Limited Second-Order Functionality in a First-Order Setting," by Kaufmann and
Moore.

This directory contains a version of APPLY$ built in an isolated package
named "MODAPP" (for Model of APPLY$).

WARNING: There is no guarantee that the definitions in the above paper or in
this directory agree with those of APPLY$ et al in the ACL2 sources!  We regard
this work as foundational and static: it backs up the definitions and arguments
in the above paper.  But once APPLY$ was integrated into the sources we felt
free (under the usual concerns that we convince ourselves of the logical
correctness of any changes) to improve it.  One such improvement occurred even
as we integrated APPLY$: we added a constraint to apply$-userfn allowing us to
prove that (APPLY$ 'fn args) is only sensitive to the first n elements of args,
where n is the arity of 'fn as reported by the badge.  An example of another
improvement we might someday make is to extend def-warrant to handle mutual
recursion.  Thus, as time goes by we expect ACL2's sources to drift away from
the foundational work here.

In this README file we address four questions: What's in this directory, why is
it in an isolated package, what is the relation between this directory and the
similarly-named /books/system/apply/, and how to certify these books?

WHAT IS IN THIS DIRECTORY?

The "MODAPP" package is defined in portcullis.acl2 and every book here is built
on top of that by virtue of the cert.acl2 file here.

The files apply-prim.lisp, apply-constraints.lisp, and apply.lisp define
APPLY$.

The file report.lisp provides the script for proving the theorems cited as
Examples in the above-mentioned paper.

A key part of the APPLY$ story is the role of warrants.  These are predicates
that stipulate the behavior of APPLY$ on user-defined functions that have been
admitted by def-warrant.  The warrant for function fn must be provided as a
hypothesis in the statement of any theorem whose proof requires knowledge of
APPLY$'s behavior on 'fn.  This allows us to avoid ``the LOCAL problem,'' which
would arise if axioms were added to describe APPLY$'s behavior on newly defined
functions.  But warrants raise another question ``Is it possible to satisfy the
assumptions made by all the warrants?'', i.e., ``is it possible that theorems
carrying warrants are valid only because the warrants are contradictory?''  The
paper addresses that question and shows, via a proof in ACL2's metatheory, that
it is possible to construct a model for any set of warrants issued by
DEF-WARRANT.  The construction of that model is complicated.  Indeed, see the
end of ACL2 source file apply-raw.lisp for a related essay, "Essay on Admitting
a Model for Apply$ and the Functions that Use It".

Another important question is whether we can execute APPLY$ on user-defined
functions.  To do so would require the assumption of the relevant warrants.
The paper addresses this question too.  The key observation is that we arrange
for the ``evaluation theory'' (the theory in which top-level ACL2 evaluation
takes place as opposed to the ``current theory'' in which theorems are proved)
to include the attachment of certains functions from the above-mentioned model
construction to the constrained functions BADGE-USERFN and APPLY$-USERFN.

Thus the model construction is important for two reasons: to assure us that our
theorems are non-vacuous and to explain how evaluation proceeds.

To support the paper, this directory provides two subdirectories, ex1/ and ex2/
that illustrate the model construction.  Ex1/ constructs the model for a small
set of user-defined functions.  Ex2/ constructs the model for a much larger set
that contains many odd uses of APPLY$ to illustrate some of the problems that
arise in the model construction.

In our opinion, ex1/ is a small enough body of work that you can grasp the
whole model construction story by reading every line in the files there,
assuming you're already familiar with apply-prim.lisp, apply-constraints.lisp,
and apply.lisp here.

Ex2/ is provided just to illustrate that def-warrant admits a pretty wide range
of functions involving APPLY$ and we can model all those warrants
simultaneously.  We recommend ex2/ only to those really wishing to see how
model construction handles certain weird but admissible situations.

WHY IS THIS DEVELOPMENT DONE IN AN ISOLATED PACKAGE?

From ACL2 Version_8.0 onwards we expect APPLY$ will be an ACL2 primitive.  This
is necessary in order to support the implicit inclusion in the evaluation
theory of all warrants, allowing top-level execution of ground apply$ forms via
attachments to the ``magic'' functions concrete-badge-userfn an
concrete-apply$-userfn.

To support execution of APPLY$ without tying down the definition or constraints
on apply$ would raise soundness issues if the user defined apply$ differently.

We thus decided to preserve the version APPLY$ described in the paper, along
with its examples, model construction, and execution model.  That's why this
directory does everything in an isolated package.

WHAT IS THE RELATIONSHIP BETWEEN THIS DIRECTORY AND /books/system/apply/?

The short answer is "none".  These files are static and support the paper
above, whereas the similarly named files in books/system/apply/ support the
build process for ACL2, particularly the claims that the definitions of APPLY$,
et al, terminate and are guard verified.  At one time the definitions in the
two directories might have agreed but they are free to drift apart.

See the Essay on the APPLY$ Integration in the ACL2 source file apply-prim.lisp.

CERTIFICATION INSTRUCTIONS

Certification of the books directly in this directory is straightforward.  But
certification of ex1/ and ex2/ is a bit non-standard because it involves
copying certain files so they can be re-certified with different portcullises.

Q. Given a book, a.lisp, defining a current theory how do you build a book,
e.lisp, whose current theory is the evaluation theory of a.lisp defined by some
attachments?

A. Put the relevant constraints in the portcullis of a.lisp.  When you certify
a you'll get a book that is the current theory of a.  Then copy a.lisp to
e.lisp.  Define a new portcullis in which the constrained functions of a.lisp
are defined to be their attachments.  Then certify e.lisp to get a book whose
current theory is the evaluation theory of a.

To certify the books in and under this directory do:

make all ACL2=<your-acl2> ACL2_SYSTEM_BOOKS=<your-acl2-books-directory>
make top ACL2=<your-acl2> ACL2_SYSTEM_BOOKS=<your-acl2-books-directory>

E.g.,
make all ACL2=v80 ACL2_SYSTEM_BOOKS=/u/moore/work/acl2/v8-0/books/
make top ACL2=v80 ACL2_SYSTEM_BOOKS=/u/moore/work/acl2/v8-0/books/
