other
(in-package "ACL2")
*acl2-system-documentation*constant
(defconst *acl2-system-documentation* '((&allow-other-keys (pointers) "See [macro-args].") (&body (pointers) "See [macro-args].") (&key (pointers) "See [macro-args].") (&optional (pointers) "See [macro-args].") (&rest (pointers) "See [macro-args].") (&whole (pointers) "See [macro-args].") (* (numbers acl2-built-ins) "Multiplication macro [47m*[0m is really a macro that expands to calls of the function [47m[binary-*][0m. So for example (* x y 4 z) represents the same term as (binary-* x (binary-* y (binary-* 4 z))). See [binary-*]. [47m*[0m is a Common Lisp function. See any Common Lisp documentation for more information. Subtopics [Binary-*] Multiplication function") (*acl2-exports* (packages acl2-built-ins) "Symbols that are often imported into new [packages] to provide easy access to ACL2 functionality. When you define a new package for your own work with [defpkg], you will usually want to import many symbols from the [47m"ACL2"[0m package; for instance you will usually want to be able to use symbols like [defthm], [in-theory], [xargs], [state], etc., without an [47macl2::[0m prefix. The constant [47m*acl2-exports*[0m lists [47m1663[0m symbols, including most documented ACL2 system constants, functions, and macros. You will typically also want to import many symbols from Common Lisp; see [*common-lisp-symbols-from-main-lisp-package*]. Those who write code using built-in ACL2 functions (see [ACL2-built-ins]) may wish to import symbols into their package from the large list [47m[*ACL2-system-exports*][0m. (& &allow-other-keys &aux &body &key &optional &rest &whole * *acl2-exports* *common-lisp-specials-and-constants* *common-lisp-symbols-from-main-lisp-package* *df-pi* *main-lisp-package-name* *standard-chars* *standard-ci* *standard-co* *standard-oi* + - / /= 1+ 1- < <-on-others <= = > >= ?-fn @ a! abort! abort-soft abs access accumulated-persistence accumulated-persistence-oops acl2-count acl2-input-channel-package acl2-number-listp acl2-numberp acl2-oracle acl2-output-channel-package acl2-package acl2-unwind-protect acons active-or-non-runep active-runep add-binop add-custom-keyword-hint add-default-hints add-default-hints! add-global-stobj add-include-book-dir add-include-book-dir! add-invisible-fns add-ld-keyword-alias add-ld-keyword-alias! add-macro-alias add-macro-fn add-match-free-override add-nth-alias add-override-hints add-override-hints! add-pair add-pair-preserves-all-boundp add-suffix add-suffix-to-fn add-timers add-to-set add-to-set-eq add-to-set-eql add-to-set-equal adjust-ld-history alistp alistp-forward-to-true-listp all-attachments all-boundp all-boundp-preserves-assoc all-vars all-vars1 all-vars1-lst allocate-fixnum-range alpha-char-p alpha-char-p-forward-to-characterp alphorder always$ always$+ and and-macro append append$ append$+ apply$ apply$-guard apply$-lambda apply$-lambda-guard apply$-userfn aref1 aref2 args arities-okp arity array1p array1p-cons array1p-forward array1p-linear array2p array2p-cons array2p-forward array2p-linear aset1 aset1-trusted aset2 ash assert$ assert* assert-event assign assoc assoc-add-pair assoc-eq assoc-eq-equal assoc-eq-equal-alistp assoc-equal assoc-keyword assoc-string-equal assoc2 associativity-of-* associativity-of-+ assume atom atom-listp atom-listp-forward-to-true-listp attach-stobj backchain-limit badge badge-userfn binary-* binary-+ binary-append binary-df* binary-df+ binary-df-log binary-df/ bind-free bit bitp boole$ boolean-listp boolean-listp-cons boolean-listp-forward boolean-listp-forward-to-symbol-listp booleanp booleanp-characterp booleanp-compound-recognizer bounded-integer-alistp bounded-integer-alistp-forward-to-eqlable-alistp bounded-integer-alistp2 boundp-global boundp-global1 break$ break-on-error brr brr-evisc-tuple brr-near-missp brr@ build-state1 butlast caaaar caaadr caaar caadar caaddr caadr caar cadaar cadadr cadar caddar cadddr caddr cadr canonical-pathname car car-cdr-elim car-cons case case-list case-list-check case-match case-split case-split-limitations case-test cbd cdaaar cdaadr cdaar cdadar cdaddr cdadr cdar cddaar cddadr cddar cdddar cddddr cdddr cddr cdr cdr-cons cdrn ceiling certify-book certify-book! change char char-code char-code-code-char-is-identity char-code-linear char-downcase char-equal char-upcase char< char<= char> char>= character character-alistp character-listp character-listp-append character-listp-coerce character-listp-forward-to-eqlable-listp character-listp-remove-duplicates-eql character-listp-revappend character-listp-string-downcase-1 character-listp-string-upcase1-1 characterp characterp-char-downcase characterp-char-upcase characterp-nth characterp-page characterp-return characterp-rubout characterp-tab check-invariant-risk check-vars-not-free checkpoint-forced-goals checkpoint-summary-limit clause clear-memoize-statistics clear-memoize-table clear-memoize-tables close-input-channel close-output-channel close-trace-file closure code-char code-char-char-code-is-identity code-char-type coerce coerce-inverse-1 coerce-inverse-2 coerce-object-to-state coerce-state-to-object collect$ collect$+ comment community-books commutativity-of-* commutativity-of-+ comp compare-objects completion-of-* completion-of-+ completion-of-< completion-of-car completion-of-cdr completion-of-char-code completion-of-code-char completion-of-coerce completion-of-complex completion-of-denominator completion-of-imagpart completion-of-intern-in-package-of-symbol completion-of-numerator completion-of-realpart completion-of-symbol-name completion-of-symbol-package-name completion-of-unary-/ completion-of-unary-minus complex complex-0 complex-definition complex-equal complex-implies1 complex-rationalp complex/complex-rationalp compress1 compress11 compress2 compress21 compress211 concatenate cond cond-clausesp cond-macro conjugate cons cons-equal cons-subtrees cons-with-hint consp consp-assoc-equal constraint-info constraint-tracking corollary count-keys cpu-core-count ctx ctxp current-package current-theory cw cw! cw!+ cw+ cw-gstack cw-gstack-for-subterm cw-gstack-for-subterm* cw-gstack-for-term cw-gstack-for-term* cw-print-base-radix cw-print-base-radix! d< declare defabbrev defabsstobj defabsstobj-missing-events defattach defattach-system default default-*-1 default-*-2 default-+-1 default-+-2 default-<-1 default-<-2 default-backchain-limit default-car default-cdr default-char-code default-coerce-1 default-coerce-2 default-coerce-3 default-compile-fns default-complex-1 default-complex-2 default-defun-mode default-defun-mode-from-state default-denominator default-hints default-imagpart default-measure-function default-numerator default-print-prompt default-realpart default-ruler-extenders default-state-vars default-symbol-name default-symbol-package-name default-total-parallelism-work-limit default-unary-/ default-unary-minus default-verify-guards-eagerness default-well-founded-relation defaxiom defbadge defchoose defcong defconst defequiv defevaluator defexec define-pc-atomic-macro define-pc-help define-pc-macro define-pc-meta define-trusted-clause-processor deflabel deflock defmacro defmacro-last defmacro-untouchable defn defnd defpkg defproxy defrec defrefinement defstobj defstub deftheory deftheory-static defthm defthm-std defthmd defthy defttag defun defun$ defun-df defun-inline defun-notinline defun-nx defun-sk defun-std defund defund-inline defund-notinline defund-nx defuns defuns-std defwarrant delete-assoc delete-assoc-eq delete-assoc-equal delete-file$ delete-include-book-dir delete-include-book-dir! denominator df* df+ df- df-abs df-abs-fn df-acos df-acos-fn df-acosh df-acosh-fn df-asin df-asin-fn df-asinh df-asinh-fn df-atan df-atan-fn df-atanh df-atanh-fn df-cos df-cos-fn df-cosh df-cosh-fn df-exp df-exp-fn df-expt df-expt-fn df-log df-minus-1 df-pi df-rationalize df-round df-sin df-sin-fn df-sinh df-sinh-fn df-sqrt df-sqrt-fn df-string df-tan df-tan-fn df-tanh df-tanh-fn df/ df/=-fn df0 df1 df< df<-fn df<= df= df=-fn df> df>= dfp digit-char-p digit-to-char dimensions disable disable-forcing disable-immediate-force-modep disable-ubt disabledp disassemble$ distributivity dmr-start dmr-stop do$ doc doc! docs doppelganger-apply$-userfn doppelganger-badge-userfn double-rewrite doublet-listp dumb-occur dumb-occur-var duplicates e/d e0-ord-< e0-ordinalp ec-call eighth eliminate-destructors eliminate-irrelevance enable enable-forcing enable-immediate-force-modep encapsulate endp eq eql eqlable-alistp eqlable-alistp-forward-to-alistp eqlable-listp eqlable-listp-forward-to-atom-listp eqlablep eqlablep-recog equal equal-char-code er er-cmp er-hard er-hard? er-let* er-let*-cmp er-progn er-progn-cmp er-progn-fn er-progn-fn@par er-progn@par er-soft er-soft-logic ev$ ev$-list evenp evens event evisc-tuple executable-counterpart-theory exists exit explain-giant-lambda-object explode-atom explode-nonnegative-integer expt expt-type-prescription-non-zero-base extend-pathname extend-pe-table extend-world extra-info f-boundp-global f-get-global f-put-global fast-alist-clean fast-alist-clean! fast-alist-fork fast-alist-fork! fast-alist-free fast-alist-free-on-exit fast-alist-len fast-alist-summary fc-report fertilize fgetprop fifth file-clock file-clock-p file-clock-p-forward-to-integerp file-length$ file-write-date$ finalize-event-user first first-n-ac fix fix-pkg fix-true-list flet floor flush-compress flush-hons-get-hash-table-link fms fms! fms!-to-string fms-to-string fmt fmt! fmt!-to-string fmt-hard-right-margin fmt-soft-right-margin fmt-to-comment-window fmt-to-comment-window! fmt-to-comment-window!+ fmt-to-comment-window+ fmt-to-string fmt1 fmt1! fmt1!-to-string fmt1-to-string fmx fmx!-cw fmx-cw fn-equal fncall-term forall force formula fourth from-df function-symbolp function-theory gag-mode gc$ gc-strategy gc-verbose gcs generalize get-check-invariant-risk get-command-sequence get-cpu-time get-defun-event get-dwp get-enforce-redundancy get-event-data get-global get-guard-checking get-in-theory-redundant-okp get-output-stream-string$ get-persistent-whs get-real-time get-register-invariant-risk get-serialize-character get-slow-alist-action get-timer get-wormhole-status getenv$ getprop getprop-default getpropc getprops getprops1 global-table global-table-cars global-table-cars1 global-val good-bye granularity ground-zero gthm guard guard-obligation guard-theorem hands-off-lambda-objects-theory hard-error has-propsp has-propsp1 header help hide hist hons hons-acons hons-acons! hons-assoc-equal hons-clear hons-clear! hons-copy hons-copy-persistent hons-equal hons-equal-lite hons-get hons-resize hons-resize-fn hons-shrink-alist hons-shrink-alist! hons-summary hons-wash hons-wash! i-am-here i-close i-large i-limited i-small id idates identity if if* iff iff-implies-equal-implies-1 iff-implies-equal-implies-2 iff-implies-equal-not iff-is-an-equivalence ifix ignorable ignore illegal imagpart imagpart-complex immediate-force-modep implies improper-consp in-arithmetic-theory in-package in-tau-intervalp in-theory include-book incompatible incompatible! increment-file-clock increment-timer induct induction-depth-limit initialize-event-user int= integer integer-0 integer-1 integer-abs integer-implies-rational integer-length integer-listp integer-listp-forward-to-rational-listp integer-range-p integer-step integerp intern intern$ intern-in-package-of-symbol intern-in-package-of-symbol-symbol-name intersection$ intersection-eq intersection-equal intersection-theories intersectp intersectp-eq intersectp-equal inverse-of-* inverse-of-+ invisible-fns-table irrelevant keyword-package keyword-value-listp keyword-value-listp-assoc-keyword keyword-value-listp-forward-to-true-listp keywordp keywordp-forward-to-symbolp known-package-alist known-package-alistp known-package-alistp-forward-to-true-list-listp-and-alistp kwote kwote-lst l< lambda lambda$ last last-cdr last-prover-steps ld ld-always-skip-top-level-locals ld-error-action ld-error-triples ld-evisc-tuple ld-history ld-history-entry-error-flg ld-history-entry-input ld-history-entry-stobjs-out ld-history-entry-stobjs-out/value ld-history-entry-user-data ld-history-entry-value ld-keyword-aliases ld-missing-input-ok ld-post-eval-print ld-pre-eval-filter ld-pre-eval-print ld-prompt ld-query-control-alist ld-redefinition-action ld-skip-proofsp ld-user-stobjs-modified-warning ld-verbose legal-case-clausesp len len-update-nth length let let* let-mbe lex-fix lexorder lexp list list$ list* list*-macro list-macro listp local logand logandc1 logandc2 logbitp logcount logeqv logic logic-fns-list-listp logic-fns-listp logic-fnsp logic-term-list-listp logic-term-listp logic-termp logior lognand lognor lognot logorc1 logorc2 logtest logxor loop$ lower-case-p lower-case-p-char-downcase lower-case-p-forward-to-alpha-char-p lowest-terms lp macro-aliases macro-args macrolet magic-ev-fncall main-timer main-timer-type-prescription make make-character-list make-character-list-make-character-list make-event make-fast-alist make-fmt-bindings make-input-channel make-list make-list-ac make-mv-nths make-ord make-output-channel make-summary-data make-tau-interval make-var-lst make-var-lst1 make-wormhole-status makunbound-global max maximum-length may-need-slashes maybe-convert-to-mv maybe-flush-and-compress1 mbe mbt mbt* member member-eq member-equal member-symbol-name memoize memoize-partial memoize-summary memsum meta-extract-contextual-fact meta-extract-formula meta-extract-global-fact meta-extract-global-fact+ meta-extract-rw+-term mfc mfc-ancestors mfc-ap mfc-clause mfc-rdepth mfc-relieve-hyp mfc-rw mfc-rw+ mfc-ts mfc-type-alist mfc-unify-subst mfc-world min minimal-theory minusp mod mod-expt monitor monitor! monitored-runes more more! more-doc msg msgp must-be-equal mutual-recursion mutual-recursion-guardp mv mv-let mv-list mv-nth mv? mv?-let nat-listp natp near-misses needs-slashes never-memoize newline nfix nfix-list nil nil-is-not-circular ninth no-duplicatesp no-duplicatesp-eq no-duplicatesp-equal non-exec nonnegative-integer-quotient nonnegative-product nonzero-imagpart not nqthm-to-acl2 nth nth-0-cons nth-0-read-run-time-type-prescription nth-add1 nth-aliases nth-update-nth nthcdr null number-subtrees numerator o-finp o-first-coeff o-first-expt o-infp o-p o-rst o< o<= o> o>= observation observation-cw oddp odds ok-if old-and-new-event-data oops open-channel-listp open-channel1 open-channel1-forward-to-true-listp-and-consp open-channels-p open-channels-p-forward open-input-channel open-input-channel-any-p open-input-channel-any-p1 open-input-channel-p open-input-channel-p1 open-input-channels open-output-channel open-output-channel! open-output-channel-any-p open-output-channel-any-p1 open-output-channel-p open-output-channel-p1 open-output-channels open-trace-file optimize or or-macro ordered-symbol-alistp ordered-symbol-alistp-add-pair ordered-symbol-alistp-add-pair-forward ordered-symbol-alistp-forward-to-symbol-alistp ordered-symbol-alistp-getprops ordered-symbol-alistp-remove1-assoc-eq otherwise our-digit-char-p override-hints p! pairlis$ pairlis2 pand pargs partial-encapsulate partition-rest-and-keyword-args pbt pc pcb pcb! pcs pe pe! peek-char$ pf pkg-imports pkg-witness pl pl2 plet plist-worldp plist-worldp-forward-to-assoc-eq-equal-alistp plusp pointers pop-timer por position position-ac position-eq position-eq-ac position-equal position-equal-ac positive posp power-eval pprogn pr pr! preprocess prin1$ prin1-with-slashes prin1-with-slashes1 princ$ print-base-p print-cl-cache print-gv print-object$ print-object$+ print-object$-fn print-object$-preserving-case print-rational-as-decimal print-timer profile prog2$ progn progn! progn$ program project-dir-alist proof-tree proofs-co proper-consp props prove pseudo-term-listp pseudo-term-listp-forward-to-true-listp pseudo-termp pso pso! psof psog pspv pstack puff puff* push-timer push-untouchable put-assoc put-assoc-eq put-assoc-eql put-assoc-equal put-global putprop quick-and-dirty-subsumption-replacement-step quit quote quotep quote~ r-eqlable-alistp r-symbol-alistp random$ rassoc rassoc-eq rassoc-equal ratio rational rational-implies1 rational-implies2 rational-listp rational-listp-forward-to-true-listp rationalp rationalp-* rationalp-+ rationalp-expt-type-prescription rationalp-implies-acl2-numberp rationalp-unary-- rationalp-unary-/ read-acl2-oracle read-acl2-oracle-preserves-state-p1 read-byte$ read-char$ read-file-into-string read-file-listp read-file-listp-forward-to-true-list-listp read-file-listp1 read-file-listp1-forward-to-true-listp-and-consp read-files read-files-p read-files-p-forward-to-read-file-listp read-idate read-object read-object-suppress read-object-with-case read-run-time read-run-time-preserves-state-p1 readable-file readable-file-forward-to-true-listp-and-consp readable-files readable-files-listp readable-files-listp-forward-to-true-list-listp-and-alistp readable-files-p readable-files-p-forward-to-readable-files-listp real-listp real/rationalp realfix realpart realpart-complex realpart-imagpart-elim rebuild redef redef! redef+ redef- redo-flat regenerate-tau-database rem remove remove-assoc remove-assoc-eq remove-assoc-equal remove-binop remove-custom-keyword-hint remove-default-hints remove-default-hints! remove-duplicates remove-duplicates-eq remove-duplicates-eql remove-duplicates-equal remove-eq remove-equal remove-global-stobj remove-guard-holders remove-invisible-fns remove-macro-alias remove-macro-fn remove-nth-alias remove-override-hints remove-override-hints! remove-untouchable remove1 remove1-assoc remove1-assoc-eq remove1-assoc-equal remove1-eq remove1-equal reset-fc-reporting reset-kill-ring reset-ld-specials reset-prehistory reset-print-control resize-list rest restore-memoization-settings retract-world retrieve return-last return-last-table revappend reverse revert-world rewrite-equiv rewrite-lambda-modep rewrite-lambda-objects-theory rewrite-quoted-constant rewrite-stack-limit rfix rize round runes-diff rw-cache satisfies save-and-clear-memoization-settings save-exec saving-event-data search second serialize-read serialize-write set-absstobj-debug set-accumulated-persistence set-backchain-limit set-bad-lisp-consp-memoize set-body set-bogus-defun-hints-ok set-bogus-measure-ok set-bogus-mutual-recursion-ok set-brr-evisc-tuple set-case-split-limitations set-cbd set-check-invariant-risk set-checkpoint-summary-limit set-compile-fns set-compiler-enabled set-constraint-tracking set-debugger-enable set-default-backchain-limit set-default-hints set-default-hints! set-deferred-ttag-notes set-difference$ set-difference-eq set-difference-equal set-difference-theories set-duplicate-keys-action set-duplicate-keys-action! set-dwp set-dwp! set-enforce-redundancy set-equalp-equal set-evisc-tuple set-fast-cert set-fc-criteria set-fc-report-on-the-fly set-fmt-hard-right-margin set-fmt-soft-right-margin set-gag-mode set-gc-strategy set-guard-checking set-guard-msg set-ignore-ok set-in-theory-redundant-okp set-induction-depth-limit set-induction-depth-limit! set-inhibit-er set-inhibit-er! set-inhibit-output-lst set-inhibit-warnings set-inhibit-warnings! set-inhibited-summary-types set-invisible-fns-table set-iprint set-irrelevant-formals-ok set-ld-always-skip-top-level-locals set-ld-error-action set-ld-error-triples set-ld-evisc-tuple set-ld-keyword-aliases set-ld-keyword-aliases! set-ld-missing-input-ok set-ld-post-eval-print set-ld-pre-eval-filter set-ld-pre-eval-print set-ld-prompt set-ld-query-control-alist set-ld-redefinition-action set-ld-skip-proofs set-ld-skip-proofsp set-ld-user-stobjs-modified-warning set-ld-verbose set-let*-abstraction set-let*-abstractionp set-match-free-default set-match-free-error set-measure-function set-non-linear set-non-linearp set-override-hints set-override-hints! set-parallel-execution set-persistent-whs-and-ephemeral-whs set-print-base set-print-base-radix set-print-case set-print-circle set-print-clause-ids set-print-escape set-print-gv-defaults set-print-length set-print-level set-print-lines set-print-radix set-print-readably set-print-right-margin set-proofs-co set-prover-step-limit set-raw-mode set-raw-mode-on set-raw-mode-on! set-raw-proof-format set-raw-warning-format set-register-invariant-risk set-rewrite-stack-limit set-ruler-extenders set-rw-cache-state set-rw-cache-state! set-serialize-character set-serialize-character-system set-skip-meta-termp-checks set-skip-meta-termp-checks! set-slow-alist-action set-splitter-output set-standard-co set-standard-oi set-state-ok set-subgoal-loop-limits set-table-guard set-tau-auto-mode set-temp-touchable-fns set-temp-touchable-vars set-timer set-total-parallelism-work-limit set-total-parallelism-work-limit-error set-trace-co set-trace-evisc-tuple set-verify-guards-eagerness set-w set-warnings-as-errors set-waterfall-parallelism set-waterfall-parallelism-hacks-enabled set-waterfall-parallelism-hacks-enabled! set-waterfall-printing set-well-founded-relation set-wormhole-data set-wormhole-entry-code set-write-acl2x setenv$ seventh sgetprop show-accumulated-persistence show-bdd show-bodies show-custom-keyword-hint-expansion show-fc-criteria signed-byte signed-byte-p signum simplify sixth skip-proofs sleep some-slashable spec-mv-let splitter-output stable-under-simplificationp standard-char standard-char-listp standard-char-listp-append standard-char-listp-forward-to-character-listp standard-char-p standard-char-p+ standard-char-p-nth standard-co standard-oi standard-part standardp start-proof-tree state state-global-let* state-global-let*-cleanup state-global-let*-get-globals state-global-let*-put-globals state-p state-p+ state-p-implies-and-forward-to-state-p1 state-p1 state-p1-forward state-p1-update-main-timer state-p1-update-nth-2-world step-limit stobj-let stobj-table stop-proof-tree string string-alistp string-append string-append-lst string-downcase string-downcase1 string-equal string-equal1 string-is-not-circular string-listp string-upcase string-upcase1 string< string<-irreflexive string<-l string<-l-asymmetric string<-l-irreflexive string<-l-transitive string<-l-trichotomy string<= string> string>= stringp stringp-symbol-package-name strip-cars strip-cdrs subgoal-loop-limits sublis sublis-fn sublis-fn-lst-simple sublis-fn-simple subseq subseq-list subsequencep subsetp subsetp-eq subsetp-equal subst substitute substitute-ac suitably-tamep-listp sum$ sum$+ summary swap-stobjs symbol symbol-alistp symbol-alistp-forward-to-eqlable-alistp symbol-doublet-listp symbol-equality symbol-listp symbol-listp-forward-to-true-listp symbol-name symbol-name-intern-in-package-of-symbol symbol-name-lst symbol-package-name symbol< symbol<-asymmetric symbol<-irreflexive symbol<-transitive symbol<-trichotomy symbolp symbolp-intern-in-package-of-symbol sync-ephemeral-whs-with-persistent-whs synp syntactically-clean-lambda-objects-theory syntaxp sys-call sys-call* sys-call+ sys-call-status t table table-alist take tamep tamep-functionp tamep-lambdap tau-data tau-database tau-interval-dom tau-interval-hi tau-interval-hi-rel tau-interval-lo tau-interval-lo-rel tau-intervalp tau-status tau-system tc tca tcp tenth term-list-listp term-listp term-order termination-theorem termp the the-check the-fixnum the-fixnum! the-number the-true-list theory theory-invariant thereis$ thereis$+ third thm time$ time-tracker time-tracker-tau timer-alistp timer-alistp-forward-to-true-list-listp-and-symbol-alistp to-df to-dfp toggle-inhibit-er toggle-inhibit-er! toggle-inhibit-warning toggle-inhibit-warning! toggle-pc-macro top-level trace! trace$ trace* trace-co trans trans! trans* trans*- trans-eval trans-eval-default-warning trans-eval-no-warning trans1 translam translate-and-test trichotomy true-list-fix true-list-listp true-list-listp-forward-to-true-listp true-list-listp-forward-to-true-listp-assoc-equal true-listp true-listp-cadr-assoc-eq-for-open-channels-p true-listp-update-nth truncate trust-mfc ttag ttags-seen tthm type typed-io-listp typed-io-listp-forward-to-true-listp typespec-check u ubt ubt! ubt-prehistory ubt? ubu ubu! ubu? unary-- unary-/ unary-df- unary-df-log unary-df/ unary-function-symbol-listp unicity-of-0 unicity-of-1 union$ union-eq union-equal union-theories universal-theory unmemoize unmonitor unquote unsave unsigned-byte unsigned-byte-p until$ until$+ untouchable-marker untrace$ untrans-table untranslate update-acl2-oracle update-acl2-oracle-preserves-state-p1 update-file-clock update-global-table update-idates update-nth update-nth-array update-open-input-channels update-open-output-channels update-read-files update-user-stobj-alist update-user-stobj-alist1 update-written-files upper-case-p upper-case-p-char-upcase upper-case-p-forward-to-alpha-char-p user-stobj-alist user-stobj-alist1 value value-cmp value-triple verbose-pstack verify verify-guard-implication verify-guards verify-guards+ verify-guards-formula verify-termination w walkabout warning! warrant waterfall-parallelism waterfall-printing weak-ld-history-entry-p well-formed-lambda-objectp wet when$ when$+ with-brr-data with-cbd with-current-package with-fast-alist with-global-stobj with-guard-checking with-guard-checking-error-triple with-guard-checking-event with-live-state with-local-state with-local-stobj with-output with-output! with-output-lock with-prover-step-limit with-prover-step-limit! with-prover-time-limit with-serialize-character with-stolen-alist without-evisc wof world wormhole wormhole-data wormhole-entry-code wormhole-eval wormhole-p wormhole-statusp wormhole1 writable-file-listp writable-file-listp-forward-to-true-list-listp writable-file-listp1 writable-file-listp1-forward-to-true-listp-and-consp write-byte$ writeable-files writeable-files-p writeable-files-p-forward-to-writable-file-listp written-file written-file-forward-to-true-listp-and-consp written-file-listp written-file-listp-forward-to-true-list-listp-and-alistp written-files written-files-p written-files-p-forward-to-written-file-listp xargs xor xxxjoin zero zerop zip zp zpf)") (*common-lisp-symbols-from-main-lisp-package* (packages acl2-built-ins) "Symbols that are often imported into new packages to provide easy access to Common Lisp functionality. When you define a new package for your own work with [defpkg], you will usually want to import many symbols from the [47m"COMMON-LISP"[0m package so that you can access them without a [47mcommon-lisp::[0m or [47macl2::[0m prefix. The constant [47m*common-lisp-symbols-from-main-lisp-package*[0m lists the [47m978[0m symbols of the [47mCOMMON-LISP[0m package found in {dpAns | http://dx.doi.org/10.1145/147135.147249}. You will typically also want to import many symbols from ACL2; see [*ACL2-exports*]. (&allow-other-keys *print-miser-width* &aux *print-pprint-dispatch* &body *print-pretty* &environment *print-radix* &key *print-readably* &optional *print-right-margin* &rest *query-io* &whole *random-state* * *read-base* ** *read-default-float-format* *** *read-eval* *break-on-signals* *read-suppress* *compile-file-pathname* *readtable* *compile-file-truename* *standard-input* *compile-print* *standard-output* *compile-verbose* *terminal-io* *debug-io* *trace-output* *debugger-hook* + *default-pathname-defaults* ++ *error-output* +++ *features* - *gensym-counter* / *load-pathname* // *load-print* /// *load-truename* /= *load-verbose* 1+ *macroexpand-hook* 1- *modules* < *package* <= *print-array* = *print-base* > *print-case* >= *print-circle* abort *print-escape* abs *print-gensym* acons *print-length* acos *print-level* acosh *print-lines* add-method adjoin atom boundp adjust-array base-char break adjustable-array-p base-string broadcast-stream allocate-instance bignum broadcast-stream-streams alpha-char-p bit built-in-class alphanumericp bit-and butlast and bit-andc1 byte append bit-andc2 byte-position apply bit-eqv byte-size apropos bit-ior caaaar apropos-list bit-nand caaadr aref bit-nor caaar arithmetic-error bit-not caadar arithmetic-error-operands bit-orc1 caaddr arithmetic-error-operation bit-orc2 caadr array bit-vector caar array-dimension bit-vector-p cadaar array-dimension-limit bit-xor cadadr array-dimensions block cadar array-displacement boole caddar array-element-type boole-1 cadddr array-has-fill-pointer-p boole-2 caddr array-in-bounds-p boole-and cadr array-rank boole-andc1 call-arguments-limit array-rank-limit boole-andc2 call-method array-row-major-index boole-c1 call-next-method array-total-size boole-c2 car array-total-size-limit boole-clr case arrayp boole-eqv catch ash boole-ior ccase asin boole-nand cdaaar asinh boole-nor cdaadr assert boole-orc1 cdaar assoc boole-orc2 cdadar assoc-if boole-set cdaddr assoc-if-not boole-xor cdadr atan boolean cdar atanh both-case-p cddaar cddadr clear-input copy-tree cddar clear-output cos cdddar close cosh cddddr clrhash count cdddr code-char count-if cddr coerce count-if-not cdr compilation-speed ctypecase ceiling compile debug cell-error compile-file decf cell-error-name compile-file-pathname declaim cerror compiled-function declaration change-class compiled-function-p declare char compiler-macro decode-float char-code compiler-macro-function decode-universal-time char-code-limit complement defclass char-downcase complex defconstant char-equal complexp defgeneric char-greaterp compute-applicable-methods define-compiler-macro char-int compute-restarts define-condition char-lessp concatenate define-method-combination char-name concatenated-stream define-modify-macro char-not-equal concatenated-stream-streams define-setf-expander char-not-greaterp cond define-symbol-macro char-not-lessp condition defmacro char-upcase conjugate defmethod char/= cons defpackage char< consp defparameter char<= constantly defsetf char= constantp defstruct char> continue deftype char>= control-error defun character copy-alist defvar characterp copy-list delete check-type copy-pprint-dispatch delete-duplicates cis copy-readtable delete-file class copy-seq delete-if class-name copy-structure delete-if-not class-of copy-symbol delete-package denominator eq deposit-field eql describe equal describe-object equalp destructuring-bind error digit-char etypecase digit-char-p eval directory eval-when directory-namestring evenp disassemble every division-by-zero exp do export do* expt do-all-symbols extended-char do-external-symbols fboundp do-symbols fceiling documentation fdefinition dolist ffloor dotimes fifth double-float file-author double-float-epsilon file-error double-float-negative-epsilon file-error-pathname dpb file-length dribble file-namestring dynamic-extent file-position ecase file-stream echo-stream file-string-length echo-stream-input-stream file-write-date echo-stream-output-stream fill ed fill-pointer eighth find elt find-all-symbols encode-universal-time find-class end-of-file find-if endp find-if-not enough-namestring find-method ensure-directories-exist find-package ensure-generic-function find-restart find-symbol get-internal-run-time finish-output get-macro-character first get-output-stream-string fixnum get-properties flet get-setf-expansion float get-universal-time float-digits getf float-precision gethash float-radix go float-sign graphic-char-p floating-point-inexact handler-bind floating-point-invalid-operation handler-case floating-point-overflow hash-table floating-point-underflow hash-table-count floatp hash-table-p floor hash-table-rehash-size fmakunbound hash-table-rehash-threshold force-output hash-table-size format hash-table-test formatter host-namestring fourth identity fresh-line if fround ignorable ftruncate ignore ftype ignore-errors funcall imagpart function import function-keywords in-package function-lambda-expression incf functionp initialize-instance gcd inline generic-function input-stream-p gensym inspect gentemp integer get integer-decode-float get-decoded-time integer-length get-dispatch-macro-character integerp get-internal-real-time interactive-stream-p intern lisp-implementation-type internal-time-units-per-second lisp-implementation-version intersection list invalid-method-error list* invoke-debugger list-all-packages invoke-restart list-length invoke-restart-interactively listen isqrt listp keyword load keywordp load-logical-pathname-translations labels load-time-value lambda locally lambda-list-keywords log lambda-parameters-limit logand last logandc1 lcm logandc2 ldb logbitp ldb-test logcount ldiff logeqv least-negative-double-float logical-pathname least-negative-long-float logical-pathname-translations least-negative-normalized-double-float logior least-negative-normalized-long-float lognand least-negative-normalized-short-float lognor least-negative-normalized-single-float lognot least-negative-short-float logorc1 least-negative-single-float logorc2 least-positive-double-float logtest least-positive-long-float logxor least-positive-normalized-double-float long-float least-positive-normalized-long-float long-float-epsilon least-positive-normalized-short-float long-float-negative-epsilon least-positive-normalized-single-float long-site-name least-positive-short-float loop least-positive-single-float loop-finish length lower-case-p let machine-instance let* machine-type machine-version mask-field macro-function max macroexpand member macroexpand-1 member-if macrolet member-if-not make-array merge make-broadcast-stream merge-pathnames make-concatenated-stream method make-condition method-combination make-dispatch-macro-character method-combination-error make-echo-stream method-qualifiers make-hash-table min make-instance minusp make-instances-obsolete mismatch make-list mod make-load-form most-negative-double-float make-load-form-saving-slots most-negative-fixnum make-method most-negative-long-float make-package most-negative-short-float make-pathname most-negative-single-float make-random-state most-positive-double-float make-sequence most-positive-fixnum make-string most-positive-long-float make-string-input-stream most-positive-short-float make-string-output-stream most-positive-single-float make-symbol muffle-warning make-synonym-stream multiple-value-bind make-two-way-stream multiple-value-call makunbound multiple-value-list map multiple-value-prog1 map-into multiple-value-setq mapc multiple-values-limit mapcan name-char mapcar namestring mapcon nbutlast maphash nconc mapl next-method-p maplist nil nintersection package-error ninth package-error-package no-applicable-method package-name no-next-method package-nicknames not package-shadowing-symbols notany package-use-list notevery package-used-by-list notinline packagep nreconc pairlis nreverse parse-error nset-difference parse-integer nset-exclusive-or parse-namestring nstring-capitalize pathname nstring-downcase pathname-device nstring-upcase pathname-directory nsublis pathname-host nsubst pathname-match-p nsubst-if pathname-name nsubst-if-not pathname-type nsubstitute pathname-version nsubstitute-if pathnamep nsubstitute-if-not peek-char nth phase nth-value pi nthcdr plusp null pop number position numberp position-if numerator position-if-not nunion pprint oddp pprint-dispatch open pprint-exit-if-list-exhausted open-stream-p pprint-fill optimize pprint-indent or pprint-linear otherwise pprint-logical-block output-stream-p pprint-newline package pprint-pop pprint-tab read-char pprint-tabular read-char-no-hang prin1 read-delimited-list prin1-to-string read-from-string princ read-line princ-to-string read-preserving-whitespace print read-sequence print-not-readable reader-error print-not-readable-object readtable print-object readtable-case print-unreadable-object readtablep probe-file real proclaim realp prog realpart prog* reduce prog1 reinitialize-instance prog2 rem progn remf program-error remhash progv remove provide remove-duplicates psetf remove-if psetq remove-if-not push remove-method pushnew remprop quote rename-file random rename-package random-state replace random-state-p require rassoc rest rassoc-if restart rassoc-if-not restart-bind ratio restart-case rational restart-name rationalize return rationalp return-from read revappend read-byte reverse room simple-bit-vector rotatef simple-bit-vector-p round simple-condition row-major-aref simple-condition-format-arguments rplaca simple-condition-format-control rplacd simple-error safety simple-string satisfies simple-string-p sbit simple-type-error scale-float simple-vector schar simple-vector-p search simple-warning second sin sequence single-float serious-condition single-float-epsilon set single-float-negative-epsilon set-difference sinh set-dispatch-macro-character sixth set-exclusive-or sleep set-macro-character slot-boundp set-pprint-dispatch slot-exists-p set-syntax-from-char slot-makunbound setf slot-missing setq slot-unbound seventh slot-value shadow software-type shadowing-import software-version shared-initialize some shiftf sort short-float space short-float-epsilon special short-float-negative-epsilon special-operator-p short-site-name speed signal sqrt signed-byte stable-sort signum standard simple-array standard-char simple-base-string standard-char-p standard-class sublis standard-generic-function subseq standard-method subsetp standard-object subst step subst-if storage-condition subst-if-not store-value substitute stream substitute-if stream-element-type substitute-if-not stream-error subtypep stream-error-stream svref stream-external-format sxhash streamp symbol string symbol-function string-capitalize symbol-macrolet string-downcase symbol-name string-equal symbol-package string-greaterp symbol-plist string-left-trim symbol-value string-lessp symbolp string-not-equal synonym-stream string-not-greaterp synonym-stream-symbol string-not-lessp t string-right-trim tagbody string-stream tailp string-trim tan string-upcase tanh string/= tenth string< terpri string<= the string= third string> throw string>= time stringp trace structure translate-logical-pathname structure-class translate-pathname structure-object tree-equal style-warning truename truncate values-list two-way-stream variable two-way-stream-input-stream vector two-way-stream-output-stream vector-pop type vector-push type-error vector-push-extend type-error-datum vectorp type-error-expected-type warn type-of warning typecase when typep wild-pathname-p unbound-slot with-accessors unbound-slot-instance with-compilation-unit unbound-variable with-condition-restarts undefined-function with-hash-table-iterator unexport with-input-from-string unintern with-open-file union with-open-stream unless with-output-to-string unread-char with-package-iterator unsigned-byte with-simple-restart untrace with-slots unuse-package with-standard-io-syntax unwind-protect write update-instance-for-different-class write-byte update-instance-for-redefined-class write-char upgraded-array-element-type write-line upgraded-complex-part-type write-sequence upper-case-p write-string use-package write-to-string use-value y-or-n-p user-homedir-pathname yes-or-no-p values zerop)") (*df-pi* (pointers) "See [df].") (*standard-ci* (io acl2-built-ins) "An ACL2 character-based analogue of CLTL's [47m*standard-input*[0m The value of the ACL2 constant [47m*standard-ci*[0m is an open character input channel that is synonymous to Common Lisp's [47m*standard-input*[0m. ACL2 character input from [47m*standard-ci*[0m is actually obtained by reading [characters] from the stream named by Common Lisp's [47m*standard-input*[0m. That is, by changing the setting of [47m*standard-input*[0m in raw Common Lisp you can change the source from which ACL2 reads on the channel [47m*standard-ci*[0m. See [*standard-co*].") (*standard-co* (io acl2-built-ins) "The ACL2 analogue of CLTL's [47m*standard-output*[0m The value of the ACL2 constant [47m*standard-co*[0m is an open character output channel that is synonymous to Common Lisp's [47m*standard-output*[0m. ACL2 character output to [47m*standard-co*[0m will go to the stream named by Common Lisp's [47m*standard-output*[0m. That is, by changing the setting of [47m*standard-output*[0m in raw Common Lisp you can change the actual destination of ACL2 output on the channel named by [47m*standard-co*[0m. Observe that this happens without changing the logical value of [47m*standard-co*[0m (which is some channel symbol). Changing the setting of [47m*standard-output*[0m in raw Common Lisp essentially just changes the map that relates ACL2 to the physical world of terminals, files, etc. To see the value of this observation, consider the following. Suppose you write an ACL2 function which does character output to the constant channel [47m*standard-co*[0m. During testing you see that the output actually goes to your terminal. Can you use the function to output to a file? Yes, if you are willing to do a little work in raw Common Lisp: open a stream to the file in question, set [47m*standard-output*[0m to that stream, call your ACL2 function, and then close the stream and restore [47m*standard-output*[0m to its nominal value. Similar observations can be made about the two ACL2 input channels, [47m[*standard-oi*][0m and [47m[*standard-ci*][0m, which are analogues of [47m*standard-input*[0m. Another reason you might have for wanting to change the actual streams associated with [47m[*standard-oi*][0m and [47m*standard-co*[0m is to drive the ACL2 top-level loop, [47m[ld][0m, on alternative input and output streams. This end can be accomplished easily within ACL2 by either calling [47m[ld][0m on the desired channels or file names or by resetting the ACL2 [47m[state][0m global variables [47m'[0m[47m[standard-oi][0m and [47m'[0m[47m[standard-co][0m which are used by [47m[ld][0m. See [standard-oi] and see [standard-co].") (*standard-oi* (io acl2-built-ins) "An ACL2 object-based analogue of CLTL's [47m*standard-input*[0m The value of the ACL2 constant [47m*standard-oi*[0m is an open object input channel that is synonymous to Common Lisp's [47m*standard-input*[0m. ACL2 object input from [47m*standard-oi*[0m is actually obtained by reading from the stream named by Common Lisp's [47m*standard-input*[0m. That is, by changing the setting of [47m*standard-input*[0m in raw Common Lisp you can change the source from which ACL2 reads on the channel [47m*standard-oi*[0m. See [*standard-co*].") (+ (numbers acl2-built-ins) "Addition macro [47m+[0m is really a macro that expands to calls of the function [47m[binary-+][0m. So for example (+ x y 4 z) represents the same term as (binary-+ x (binary-+ y (binary-+ 4 z))). See [binary-+]. [31;1mMacro: [0m<+> (defmacro + (&rest rst) (if rst (if (cdr rst) (xxxjoin 'binary-+ rst) (cons 'binary-+ (cons 0 (cons (car rst) nil)))) 0)) Subtopics [Binary-+] Addition function") (- (numbers acl2-built-ins) "Macro for subtraction and negation See [binary-+] for addition and see [unary--] for negation. Note that [47m-[0m represents subtraction as follows: (- x y) represents the same term as (+ x (- y)) which is really (binary-+ x (unary-- y)). Also note that [47m-[0m represents arithmetic negation as follows: (- x) expands to (unary-- x). [31;1mMacro: [0m<-> (defmacro - (x &optional (y 'nil binary-casep)) (if binary-casep (let ((y (if (and (consp y) (eq (car y) 'quote) (consp (cdr y)) (acl2-numberp (car (cdr y))) (eq (cdr (cdr y)) nil)) (car (cdr y)) y))) (if (acl2-numberp y) (cons 'binary-+ (cons (unary-- y) (cons x nil))) (cons 'binary-+ (cons x (cons (cons 'unary-- (cons y nil)) nil))))) (let ((x (if (and (consp x) (eq (car x) 'quote) (consp (cdr x)) (acl2-numberp (car (cdr x))) (eq (cdr (cdr x)) nil)) (car (cdr x)) x))) (if (acl2-numberp x) (unary-- x) (cons 'unary-- (cons x nil))))))") (/ (numbers acl2-built-ins) "Macro for division and reciprocal See [binary-*] for multiplication and see [unary-/] for reciprocal. Note that [47m/[0m represents division as follows: (/ x y) represents the same term as (* x (/ y)) which is really (binary-* x (unary-/ y)). Also note that [47m/[0m represents reciprocal as follows: (/ x) expands to (unary-/ x). [47m/[0m is a Common Lisp macro. See any Common Lisp documentation for more information. [31;1mMacro: [0m</> (defmacro / (x &optional (y 'nil binary-casep)) (cond (binary-casep (list 'binary-* x (list 'unary-/ y))) (t (list 'unary-/ x))))") (/= (numbers acl2-built-ins) "Test inequality of two numbers [47m(/= x y)[0m is logically equivalent to [47m(not (equal x y))[0m. Unlike [47m[equal][0m, [47m/=[0m has a [guard] requiring both of its arguments to be numbers. Generally, [47m/=[0m is executed more efficiently than a combination of [47m[not][0m and [47m[equal][0m. For a discussion of the various ways to test against 0, See [zero-test-idioms]. [47m/=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m</=> (defun /= (x y) (declare (xargs :guard (and (acl2-numberp x) (acl2-numberp y)))) (not (equal x y)))") (1+ (numbers acl2-built-ins) "Increment by 1 [47m(1+ x)[0m is the same as [47m(+ 1 x)[0m. See [+]. [47m1+[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<1+> (defmacro 1+ (x) (list '+ 1 x))") (1- (numbers acl2-built-ins) "Decrement by 1 [47m(1- x)[0m is the same as [47m(- x 1)[0m. See [-]. [47m1-[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<1-> (defmacro 1- (x) (list '- x 1))") (< (numbers acl2-built-ins) "Less-than Completion Axiom ([47mcompletion-of-<[0m): (equal (< x y) (if (and (rationalp x) (rationalp y)) (< x y) (let ((x1 (if (acl2-numberp x) x 0)) (y1 (if (acl2-numberp y) y 0))) (or (< (realpart x1) (realpart y1)) (and (equal (realpart x1) (realpart y1)) (< (imagpart x1) (imagpart y1))))))) [Guard] for [47m(< x y)[0m: (and (rationalp x) (rationalp y)) Notice that like all arithmetic functions, [47m<[0m treats non-numeric inputs as [47m0[0m. Thus, the following are theorems. (thm (equal (< (fix x) y) (< x y))) (thm (equal (< x (fix y)) (< x y))) This function has the usual meaning on the rational numbers, but is extended to the complex rational numbers using the lexicographic order: first the real parts are compared, and if they are equal, then the imaginary parts are compared.") (<= (numbers acl2-built-ins) "Less-than-or-equal test [47m<=[0m is a macro, and [47m(<= x y)[0m expands to the same thing as [47m(not (< y x))[0m. See [<]. [47m<=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<<=> (defmacro <= (x y) (list 'not (list '< y x)))") (= (numbers equal equality-variants acl2-built-ins) "Test equality of two numbers [47m(= x y)[0m is logically equivalent to [47m(equal x y)[0m. Unlike [47m[equal][0m, [47m=[0m has a [guard] requiring both of its arguments to be numbers. Generally, [47m=[0m is executed more efficiently than [47m[equal][0m. For a discussion of the various ways to test against 0, See [zero-test-idioms]. [47m=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<=> (defun = (x y) (declare (xargs :guard (and (acl2-numberp x) (acl2-numberp y)))) (equal x y))") (> (numbers acl2-built-ins) "Greater-than test [47m>[0m is a macro, and [47m(> x y)[0m expands to the same thing as [47m(< y x)[0m. See [<]. [47m>[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<>> (defmacro > (x y) (list '< y x))") (>= (numbers acl2-built-ins) "Greater-than-or-equal test [47m>=[0m is a macro, and [47m(>= x y)[0m expands to the same thing as [47m(not (< x y))[0m. See [<]. [47m>=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<>=> (defmacro >= (x y) (list 'not (list '< x y)))") (@ (programming-with-state acl2-built-ins) "Get the value of a global variable in [47m[state][0m Examples: (+ (@ y) 1) (assign a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B)) General Form: (@ symbol) where [47msymbol[0m is any symbol to which you have [47m[assign][0med a global value. This macro expands into [47m(f-get-global 'symbol state)[0m, which retrieves the stored value of the symbol. The macro [47mf-get-global[0m is closely related to [47m[@][0m: [47m(@ var)[0m macroexpands to [47m(f-get-global 'var state)[0m. The macro [47m[assign][0m makes it convenient to set the value of a symbol. The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of [47m[state][0m. Thus, you may use these globals to hang onto useful data structures even though you may undo back past where you computed and saved them.") (a! (ld) "To return to the top-level of ACL2's command loop When [47m(a!)[0m is evaluated inside of ACL2's command loop, the current computation is aborted and control returns to the top of the command loop, exactly as though the user had interrupted and aborted the current computation. (Note: Versions of ACL2 up to Version_3.4 provided `[47m#.[0m' for this purpose, but no longer; see [sharp-dot-reader].) If you are at an ACL2 prompt (as opposed to a raw Lisp break), then you may type [47m:a![0m in place of [47m(a!)[0m; see [keyword-commands]. For a related feature that only pops up one level of [47m[ld][0m, see [47m[p!][0m. However, [47mp![0m behaves differently if you're typing to the interactive break caused by [break-rewrite]. Instead of popping up one level, [47mp![0m in break-rewrite prints a message and is otherwise a no-op. Logically speaking, [47m(a!) = nil[0m. But imagine that it is defined in such a way that it causes a stack overflow or other resource exhaustion when called.") (abort! (ld) "To return to the top-level of ACL2's command loop This is an alias for [47ma![0m; see [a!]. For a related feature that only pops up one level, see [p!].") (abort-soft (miscellaneous) "Control how interrupts are handled in proofs ACL2 arranges by default that when a proof is interrupted (with [47mControl-C[0m), a ``soft'' abort occurs in the following sense: the message below is printed and then the proof attempt continues temporarily before ultimately failing (usually very soon thereafter). *********************************************** Note: interrupt signal Will attempt to exit the proof in progress; otherwise, the next interrupt will abort the proof. For an immediate abort see :DOC abort-soft. *********************************************** This default behavior supports proper operation of the utility, [47m[redo-flat][0m, when a proof is interrupted. It also supports more complete summaries than would be obtained with an immediate abort. If you nevertheless want proofs to abort immediately, you may evaluate the form [47m(assign abort-soft nil)[0m. To restore the default behavior, evaluate [47m(assign abort-soft t)[0m. Remarks for system hackers. * An important effect of having evaluated [47m(assign abort-soft nil)[0m is that an interrupt will send you immediately back to the ACL2 read-eval-print loop, in contrast to the default behavior where the prover returns an [error-triple] whose error component is non-[47mnil[0m. * It may be preferable to bind [state] global [47mabort-soft[0m rather than to assign it globally. See the implementation of [prove$] (specifically, the definition of [47mprove$-fn[0m in [community-book] [47mbooks/tools/prove-dollar.lisp[0m) for an example.") (about-acl2 (start-here) "General information About ACL2 This is ACL2 Version 8.6, [copyright] (C) 2026, Regents of the University of Texas, authored by Matt Kaufmann and J Strother Moore. This manual contains installation instructions (see [INSTALLATION]), tutorials (see [ACL2-TUTORIAL]), and [acknowledgments], as well as information about mailing lists (see [MAILING-LISTS]), related publications, and ACL2 Workshops. See [documentation] for how to access the ACL2+Books User's Manual. See [releases] for information about past ACL2 releases. See the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/} for other information, including seminars. For statistics on ACL2 code size, see file [47mdoc/acl2-code-size.txt[0m. Subtopics [Acknowledgments] Some contributors to the well-being of ACL2 [ACL2-help] The acl2-help mailing list [ACL2-tutorial] Tutorial introduction to ACL2 [Common-lisp] Relation to Common Lisp, including deviations from the spec [Copyright] ACL2 copyright, license, authorship [Git-quick-start] Git quick start guide. [How-to-contribute] Guide to contributing code to ACL2. [Installation] Installing ACL2 [Mailing-lists] Mailing lists for ACL2 users [Operational-semantics] Modeling State Machines [Pre-built-binary-distributions] Pre-built binary distributions of ACL2 [Recursion-and-induction] Recursion and Induction [Release-notes] Pointers to what has changed [Releases] ACL2 releases [Soundness] Correctness property claimed for ACL2 [Using-ACL2] Using ACL2 [Version] ACL2 Version Number") (about_models (pages_written_especially_for_the_tours) "About Models {IMAGE} (see [Models_of_Computer_Hardware_and_Software]) ACL2 is used to construct mathematical models of computer hardware and software (i.e., ``digital systems''). {IMAGE} A [31;1mmathematical model[0m is a set of mathematical formulas used to predict the behavior of some artifact. The use of mathematical models allows [31;1mfaster[0m and [31;1mcheaper[0m delivery of [31;1mbetter[0m systems. Models need not be [31;1mcomplete[0m or [31;1mperfectly accurate[0m to be useful to the trained engineer. Click here (see [Models_in_Engineering]) for more discussion of these assertions in an engineering context. {IMAGE} (see [Models_of_Computer_Hardware_and_Software])") (about_the_acl2_home_page (pages_written_especially_for_the_tours) "About the ACL2 Home Page {IMAGE} (see [What_Is_ACL2{Q}]) The {ACL2 Home Page | https://www.cs.utexas.edu/users/moore/acl2/} on the web contains links to demos, publications, mailing lists, installation instructions, and more --- and, especially, to the {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}, which provides online documentation for ACL2 and its libraries, known as ``books''. For example, to use the online documentation to find out about [rewrite] {ICON} (see [A_Tiny_Warning_Sign]) rules you could click on the link. (If you do that, remember to use your browser's [31;1mBack Button[0m to come back here.) The tiny warning signs {ICON} (see [A_Tiny_Warning_Sign]) mark links that lead out of the introductory-level material and into the user documentation. We advise against following such links upon your first reading of the documentation. At the end of the tours you will have a chance to revisit them quickly to explore alternative paths more fully. {IMAGE} (see [What_Is_ACL2{Q}])") (about_the_admission_of_recursive_definitions (pages_written_especially_for_the_tours) "About the Admission of Recursive Definitions You can't just add any formula as an axiom or definition and expect the logic to stay sound! For example, if we were permitted to define [47m(APP X Y)[0m so that it was equal to [47m(NOT (APP X Y))[0m then we could prove anything. The purported ``definition'' of [47mAPP[0m must have several properties to be admitted to the logic as a new axiom. The key property a recursive definition must have is that the recursion terminate. This, along with some syntactic criteria, ensures us that there exists a function satisfying the definition. Termination must be proved before the definition is admitted. This is done in general by finding a measure of the arguments of the function and a well-founded relation such that the arguments ``get smaller'' every time a recursive branch is taken. For [47mapp[0m the measure is the ``size'' of the first argument, [47mx[0m, as determined by the primitive function [47m[ACL2-count][0m {ICON} (see [A_Tiny_Warning_Sign]). The well-founded relation used in this example is [47m[o-p][0m {ICON} (see [A_Tiny_Warning_Sign]), which is the standard ordering on the ordinals less than ``epsilon naught.'' These particular choices for [47mapp[0m were made ``automatically'' by ACL2. But they are in fact determined by various ``default'' settings. The user of ACL2 can change the defaults or specify a ``hint'' to the [47m[defun][0m {ICON} (see [A_Tiny_Warning_Sign]) command to specify the measure and relation. You should now return to the Walking Tour (see [Revisiting_the_Admission_of_App]).") (about_the_prompt (pages_written_especially_for_the_tours) "About the Prompt The string ``[47mACL2 !>[0m'' is the ACL2 prompt. The prompt tells the user that an ACL2 [command] {ICON} (see [A_Tiny_Warning_Sign]) is expected. In addition, the prompt tells us a little about the current state of the ACL2 command interpreter. We explain the prompt briefly below. But first we talk about the command interpreter. An ACL2 command is generally a Lisp expression to be evaluated. There are some unusual commands (such as [47m:[0m[q] {ICON} (see [A_Tiny_Warning_Sign]) for [31;1mquitting[0m ACL2) which cause other behavior. But most commands are read, evaluated, and then have their results printed. Thus, we call the command interpreter a ``read-eval-print loop.'' The ACL2 command interpreter is named [47m[ld][0m {ICON} (see [A_Tiny_Warning_Sign]) (after Lisp's ``load''). When a command is read, all the symbols in it are converted to uppercase. Thus, typing [47m(defun app ...)[0m is the same as typing [47m(DEFUN APP ...)[0m or [47m(defun App ...)[0m. There are ways to force lowercase case characters into symbols but we won't discuss them here. A consequence of Common Lisp's default uppercasing is that you'll see a general lack of concern over the case used when symbols are displayed in this documentation. In addition, symbols ``belong'' to ``packages'' which give the user a way to control namespaces. The prompt tells us which package is the default one, namely [47m"ACL2"[0m. That means when we call [47mcar[0m, for example, we are invoking the standard definition of that symbol. If the packager were [47m"JONES"[0m then [47mcar[0m would refer to the definition of that symbol in that package (which may or may not be different depending on what symbols were imported into that package. A command like [31;1m(defun app (x y) ...)[0m causes ACL2 to evaluate the [defun] {ICON} (see [A_Tiny_Warning_Sign]) function on [31;1mapp[0m, [31;1m(x y)[0m and [31;1m...[0m. When that command is evaluated it prints some information to the terminal explaining the processing of the proposed definition. It returns the symbol [47mAPP[0m as its value, which is printed by the command interpreter. (Actually, [47mdefun[0m is not a function but a macro (see [DEFMACRO]) {ICON} (see [A_Tiny_Warning_Sign]) which expands to a form that involves [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign]), a necessary precondition to printing output to the terminal and to ``changing'' the set of axioms. But we do not discuss this further here.) The [47mdefun[0m command is an example of a special kind of command called an ``event.'' [Events] {ICON} (see [A_Tiny_Warning_Sign]) are those commands that change the ``logical world'' by adding such things as axioms or theorems to ACL2's database. See [world] {ICON} (see [A_Tiny_Warning_Sign]). But not every command is an event command. A command like [31;1m(app '(1 2 3) '(4 5 6 7))[0m is an example of a non-event. It is processed the same general way: the function [31;1mapp[0m is applied to the indicated arguments and the result is printed. The function [31;1mapp[0m does not print anything and does not change the ``world.'' A third kind of command is one that displays information about the current logical world or that ``roll back'' to previous versions of the world. Such commands are called ``[history]'' {ICON} (see [A_Tiny_Warning_Sign]) commands. What does the ACL2 prompt tell us about the read-eval-print loop? The prompt ``[47mACL2 !>[0m'' tells us that the command will be read with [47m[current-package][0m {ICON} (see [A_Tiny_Warning_Sign]) set to [47m"ACL2"[0m, that guard checking (see [set-guard-checking] {ICON} (see [A_Tiny_Warning_Sign])) is on (``[47m![0m''), and that we are at the top-level (there is only one ``[47m>[0m''). For more about the prompt, see [default-print-prompt] {ICON} (see [A_Tiny_Warning_Sign]). You should now return to the Walking Tour (see [Revisiting_the_Admission_of_App]).") (about_types (pages_written_especially_for_the_tours) "About Types The universe of ACL2 objects includes objects of many different types. For example, [47mt[0m is a ``symbol'' and 3 is an ``integer.'' Roughly speaking the objects of ACL2 can be partitioned into the following types: * Numbers (see [Numbers_in_ACL2]) such as [47m3, -22/7, #c(3 5/2)[0m. * Characters (see [ACL2_Characters]) such as [47m#\A, #\a, #\Space[0m. * Strings (see [ACL2_Strings]) such as [47m"This is a string."[0m. * Symbols (see [ACL2_Symbols]) such as [47m'abc, 'smith::abc[0m. * Conses (or Ordered Pairs) (see [ACL2_Conses_or_Ordered_Pairs]) such as [47m'((a . 1) (b . 2))[0m. When proving theorems it is important to know the types of object returned by a term. ACL2 uses a complicated heuristic algorithm, called [47m[type-set][0m {ICON} (see [A_Tiny_Warning_Sign]), to determine what types of objects a term may produce. The user can more or less program the [47mtype-set[0m algorithm by proving [47m[type-prescription][0m {ICON} (see [A_Tiny_Warning_Sign]) rules. ACL2 is an ``untyped'' logic in the sense that the syntax is not typed: It is legal to apply a function symbol of n arguments to any n terms, regardless of the types of the argument terms. Thus, it is permitted to write such odd expressions as [47m(+ t 3)[0m which sums the symbol [47mt[0m and the integer 3. Common Lisp does not prohibit such expressions. We like untyped languages because they are simple to describe, though proving theorems about them can be awkward because, unless one is careful in the way one defines or states things, unusual cases (like [47m(+ t 3)[0m) can arise. To make theorem proving easier in ACL2, the axioms actually define a value for such terms. The value of [47m(+ t 3)[0m is 3; under the ACL2 axioms, non-numeric arguments to [47m+[0m are treated as though they were 0. You might immediately wonder about our claim that ACL2 is Common Lisp, since [47m(+ t 3)[0m is ``an error'' (and will sometimes even ``signal an error'') in Common Lisp. It is to handle this problem that ACL2 has [31;1mguards[0m. We will discuss guards later in the Walking Tour. However, many new users simply ignore the issue of guards entirely and that is what we recommend for now. You should now return to the Walking Tour (see [Revisiting_the_Admission_of_App]).") (abs (numbers acl2-built-ins) "The absolute value of a real number [47m(Abs x)[0m is [47m-x[0m if [47mx[0m is negative and is [47mx[0m otherwise. The [guard] for [47mabs[0m requires its argument to be a rational ([real], in ACL2(r)) number. [47mAbs[0m is a Common Lisp function. See any Common Lisp documentation for more information. From ``Common Lisp the Language'' page 205, we must not allow complex [47mx[0m as an argument to [47mabs[0m in ACL2, because if we did we would have to return a number that might be a floating point number and hence not an ACL2 object. [31;1mFunction: [0m<abs> (defun abs (x) (declare (xargs :guard (real/rationalp x))) (if (minusp x) (- x) x))") (abstract-stobj (pointers) "See [defabsstobj].") (access (defrec acl2-built-ins) "Accessor macro for [defrec] structures. The [47maccess[0m macro is built into ACL2, and allows you to access particular fields from structures that have been introduced with [defrec]. For instance: (access employee x :name) would return the [47mname[0m field from the employee [47mx[0m. See [defrec] for more information.") (accumulated-persistence (debugging) "To get statistics on which [rune]s are being tried Useful Forms: (accumulated-persistence t) ; Activate statistics gathering. (accumulated-persistence :all) ; As above, ``enhanced'' (see below) (show-accumulated-persistence :frames) ; Display statistics ordered by (show-accumulated-persistence :tries) ; frames built, times tried, (show-accumulated-persistence :ratio) ; or their ratio. (show-accumulated-persistence) ; Same as supplying :frames argument. (accumulated-persistence nil) ; Deactivate. (accumulated-persistence-oops) ; Undo the clearing effect of ; (accumulated-persistence t). Advanced forms: (show-accumulated-persistence :frames-s) ; The `s', `f', and `a' suffixes (show-accumulated-persistence :frames-f) ; stand for `success' (`useful'), (show-accumulated-persistence :frames-a) ; `failure' (`useless'), and `all', (show-accumulated-persistence :tries-s) ; respectively. The only effect of (show-accumulated-persistence :tries-f) ; the `s' and `f' versions is to (show-accumulated-persistence :tries-a) ; sort first by useful or useless ; applications, respectively (see ; below). The `a' versions avoid ; showing the useful/useless ; breakdown. (show-accumulated-persistence :runes) ; Just show runes alphabetically. (show-accumulated-persistence :useless) ; Just show useless runes. (show-accumulated-persistence :useless :list) ; Just show useless runes as a list. In summary, [47m(accumulated-persistence t)[0m turns on fresh statistics gathering for rules, [47m(accumulated-persistence nil)[0m turns it off, [47m(show-accumulated-persistence)[0m displays the statistics that were gathered, and [47m(accumulated-persistence-oops)[0m restores the statistics, if any, that were cleared by [47m(accumulated-persistence t)[0m or [47m(accumulated-persistence :all)[0m. In general, if the optional second argument of [47mshow-accumulated-persistence[0m is supplied as [47m:list[0m, then instead of the result being displayed a ``pretty'' human-readable format, the result will be displayed as a corresponding list of entries of the form [47m(frames tries xrune)[0m. Note: [47mset-accumulated-persistence[0m is equivalent to [47maccumulated-persistence[0m. See the end of this item for a discussion of ``enhanced statistics gathering,'' which can be useful for more fine-grained proof debugging. Generally speaking, the more ACL2 knows, the slower it runs. That is because the search space grows with the number of alternative rules. Often, the system tries to apply rules that you have forgotten were even there, if you knew about them in the first place! ``Accumulated-persistence'' is a statistic (originally developed for Nqthm) that helps you identify the rules that are causing ACL2's search space to explode. For other proof debugging utilities, see [break-rewrite], [with-brr-data], and [dmr]. Accumulated persistence tracking can be turned on or off. It is generally off. When on, proofs may take a little more time than otherwise. (We measured approximately 11% more time in a so-called ``everything'' regression run in May 2020.) But some useful numbers are collected. When it is turned on, by ACL2 !>(accumulated-persistence t) an accumulation site is initialized and henceforth data about which rules are being tried is accumulated into that site. That accumulated data can be displayed with [47mshow-accumulated-persistence[0m, as described in detail below. When accumulated persistence is turned off, with [47m(accumulated-persistence nil)[0m, the accumulation site is wiped out and the data in it is lost. The ``accumulated persistence'' of a [rune] is the number of [rune]s the system has attempted to apply (since accumulated persistence was last activated) while the given [rune] was being tried. Consider a [47m:[0m[47m[rewrite][0m rule named [47m[rune][0m. For simplicity, let us imagine that [47m[rune][0m is tried only once in the period during which accumulated persistence is being monitored. Recall that to apply a rewrite rule we must match the left-hand side of the conclusion to some term we are trying to rewrite, establish the hypotheses of [47m[rune][0m by rewriting, and, if successful, then rewrite the right-hand side of the conclusion. We say [47m[rune][0m is ``being tried'' from the time we have matched its left-hand side to the time we have either abandoned the attempt or finished rewriting its right-hand side. (By ``match'' we mean to include any loop-stopper requirement; see [loop-stopper].) During that period of time other rules might be tried, e.g., to establish the hypotheses. The rules tried while [47m[rune][0m is being tried are ``billed'' to [47m[rune][0m in the sense that they are being considered here only because of the demands of [47m[rune][0m. Thus, if no other rules are tried during that period, the accumulated persistence of [47m[rune][0m is [47m1[0m --- we ``bill'' [47m[rune][0m once for its own application attempt. If, on the other hand, we tried [47m10[0m rules on behalf of that application of [47m[rune][0m, then [47m[rune][0m's accumulated persistence would be [47m11[0m. One way to envision accumulated persistence is to imagine that every time a [rune] is tried it is pushed onto a stack. The rules tried on behalf of a given application of a [rune] are thus pushed and popped on the stack above that [rune]. A lot of work might be done on its behalf --- the stack above the [rune] grows and shrinks repeatedly as the search continues for a way to use the [rune]. All the while, the [rune] itself ``persists'' in the stack, until we finish with the attempt to apply it, at which time we pop it off. The accumulated persistence of a [rune] application is thus the number of stack frames built while that [rune] was on the stack. Note that accumulated persistence is tallied whether or not the attempt to apply a [rune] is successful. Each of the rules tried on its behalf might have failed and the attempt to apply the [rune] might have also failed. The ACL2 proof script would make no mention of the [rune] or the rules tried on its behalf because they did not contribute to the proof. But time was spent pursuing the possible application of the [rune] and accumulated persistence is a measure of that time. A high accumulated persistence might come about in two extreme ways. One is that the rule causes a great deal of work every time it is tried. The other is that the rule is ``cheap'' but is tried very often. We therefore keep track of the number of times each rule is tried as well as its persistence. The ratio between the two is the average amount of work done on behalf of the rule each time it is tried. We do not claim that tracking of runes for accumulated-persistence is perfect. In practice, we believe it is quite reliable with the exception of [congruence] runes and, in some cases [executable-counterpart] runes. (For the latter, details are in a comment in the ACL2 source definition of function [47mprint-useless-runes[0m.) When the accumulated persistence totals are displayed by the function [47mshow-accumulated-persistence[0m we sort them so that the most expensive [rune]s are shown first. We can sort according to one of three basic keys: :frames - the number of frames built on behalf of the rune :tries - the number of times the rune was tried :ratio - frames built per try The key simply determines the order in which the information is presented. If no argument is supplied to [47mshow-accumulated-persistence[0m, [47m:frames[0m is used. The display breaks each total into ``useful'' and ``useless'' subtotals. A ``useful'' rule try is one that is viewed as contributing to the progress of the proof, and the rest are ``useless'' rule applications. For example, if a [47m:[0m[47m[rewrite][0m rule is tried but its hypotheses are not successfully relieved, then that rule application and all work done on behalf of those hypotheses is ``useless'' work. In general, an attempt to apply a [rune] is viewed as ``useful'' unless the attempt fails or the attempt is on the stack (as described above) for a [rune] application that ultimately fails. A large number of ``useless'' [47m:frames[0m or [47m:tries[0m along with correspondingly small ``useful'' counts may suggest [rune]s to consider disabling (see [disable] and see [in-theory]). Thus, here is a more complete list of the arguments that may be supplied to [47mshow-accumulated-persistence[0m. Suffixes ``s'', ``f'', and ``a'' are intended to suggest ``success'' (``useful''), ``failure'' (``useless''), and ``all''. :frames - sort by the number of frames built on behalf of the rune :frames-s - as above, but sort by useful applications :frames-f - as above, but sort by useless applications :frames-a - as above, but inhibit display of ``useful'' and ``useless'' subtotals :tries - sort by the number of times the rune was tried :tries-s - as above, but sort by useful applications :tries-f - as above, but sort by useless applications :tries-a - as above, but inhibit display of ``useful'' and ``useless'' subtotals :ratio - sort by frames built per try :useless - show only the runes tried whose tries were all ``useless'' For a given line of the report, every frame credited to a ``useful'' (respectively, ``useless'') rule application is considered ``useful'' (respectively, ``useless''). We illustrate with the following example. (progn (defstub hyp (x) t) (defstub concl (x) t) (defstub bad (x) t) (defstub good (x) t) (defaxiom good-ax (implies (good x) (hyp x))) (defaxiom bad-ax (implies (bad x) (hyp x))) (defaxiom hyp-implies-concl (implies (hyp x) (concl x))) ) (accumulated-persistence t) (thm (implies (good x) (concl x))) (show-accumulated-persistence) To prove the [47m[thm][0m form, ACL2 attempts to rewrite [47m(concl x)[0m to true by applying rule [47mhyp-implies-concl[0m. It then attempts to establish [47m(hyp x)[0m first by trying rule [47mbad-ax[0m, which fails, and second by trying rule [47mgood-ax[0m, which succeeds. As expected, the report labels as ``useless'' the failure of the attempt to establish the hypothesis, [47m(bad x)[0m. -------------------------------- 1 1 ( 1.00) (:REWRITE BAD-AX) 0 0 [useful] 1 1 [useless] -------------------------------- Now consider the top-level application of rule [47mhyp-implies-concl[0m. Even though the above report shows the application of [47mbad-ax[0m as ``useless'', note that this rule was applied on behalf of the successful (``useful'') application of [47mhyp-implies-concl[0m, and hence is incorporated into the ``useful'' line for [47mhyp-implies-concl[0m, as follows. -------------------------------- 3 1 ( 3.00) (:REWRITE HYP-IMPLIES-CONCL) 3 1 [useful] 0 0 [useless] -------------------------------- In summary: categorization of [47m:frames[0m as ``useful'' or ``useless'' is based on whether they support ``useful'' or ``useless'' [47m:tries[0m. See [useless-runes] for a way to speed up proofs by automatically turning off useless rules. Note that a [rune] with high accumulated persistence may not actually be the ``culprit.'' For example, suppose [47mrune1[0m is reported to have a [47m:ratio[0m of [47m101[0m, meaning that on the average a hundred and one frames were built each time [47mrune1[0m was tried. Suppose [47mrune2[0m has a [47m:ratio[0m of [47m100[0m. It could be that the attempt to apply [47mrune1[0m resulted in the attempted application of [47mrune2[0m and no other [rune]. Thus, in some sense, [47mrune1[0m is ``cheap'' and [47mrune2[0m is the ``culprit'' even though it is reported as costing less than [47mrune1[0m. If a proof is aborted, then in general, [47m[show-accumulated-persistence][0m will only display totals for runes whose attempted application is complete: that is, if the rewriter was in the process of relieving hypotheses for a rule, then information for that rule will not be included in the tally. We say ``in general'' because, as indicated near the top of the output from [47m[show-accumulated-persistence][0m when such incomplete information is omitted, you can get this information by using argument [47m:frames-a[0m or [47m:tries-a[0m. There are other subtleties in how rune applications are tallied, documented elsewhere: see [accumulated-persistence-subtleties]. We conclude with a discussion of ``enhanced'' statistics gathering, which is enabled by supplying [47maccumulated-persistence[0m the argument [47m:ALL[0m: (accumulated-persistence :all) At some additional performance expense (but probably well under a factor of 2 altogether), ACL2 then gathers additional statistics for individual hypotheses of rules as well as their conclusions. To understand how this works, suppose [47mrn[0m is a [rune]. Then we prepend the keyword [47m:CONC[0m to [47mrn[0m to form what we call its ``conclusion xrune'', and for its [47mI[0m-th hypothesis we prepend [47m:HYP I[0m to [47mrn[0m to form its [47mI[0m-th ``hypothesis xrune.'' Here, ``xrune'' is pronounced ``ex rune'', and is mnemonic for ``extended rune.'' For example, if [47m(REWRITE FOO)[0m is a [rune] then [47m(:CONC REWRITE FOO)[0m is its conclusion xrune, and [47m(:HYP 2 REWRITE FOO)[0m is a hypothesis xrune corresponding to the second hypothesis of the corresponding rewrite rule. With [47m(accumulated-persistence :all)[0m, we instruct ACL2 to track not only runes but also xrunes. Then, [47m(show-accumulated-persistence)[0m will display information for all xrunes in a format that we consider to be ``raw'', in the sense that data for xrunes are displayed just as for runes. But a ``merged'' format is also available. Here is a summary of display commands, followed below by further discussion. (show-accumulated-persistence :frames t) ; t is optional, i.e., the default ; Display enhanced statistics sorted by frames, in a ``raw'' format. (show-accumulated-persistence :frames :merge) ; Display enhanced statistics sorted by frames, in a ``merged'' format. (show-accumulated-persistence :frames nil) ; Display regular statistics sorted by frames ; (runes only, that is, without the enhancements). (show-accumulated-persistence :frames :merge) ; Display a list of entries (frames tries xrune), sorted by frames ; More generally, the descriptions just above apply for any legal first ; argument: (show-accumulated-persistence KEY t) (show-accumulated-persistence KEY :merge) (show-accumulated-persistence KEY nil) (show-accumulated-persistence KEY :list) ; Note also these alternate forms, equivalent to the first of the two forms ; just above, i.e., the form with second argument of t: (show-accumulated-persistence KEY :raw) (show-accumulated-persistence KEY) There is a significant difference between how runes are tracked and how ACL2 tracks hypothesis and conclusion xrunes: unlike regular runes, these xrunes do not contribute to the accumulated [47m:frames[0m counts. Rather, they serve as accumulation sites without contributing their [47m:tries[0m to any accumulation. Consider for example the snippet below, taken from a report created with the [47m:merge[0m option (to be discussed further below), i.e., by evaluating the form [47m(show-accumulated-persistence :frames :merge)[0m. :frames :tries :ratio rune -------------------------------- 462 211 ( 2.18) (:REWRITE PERM-MEM) 13 6 [useful] 449 205 [useless] ............................. 251 47 ( 5.34) (:HYP 2 :REWRITE PERM-MEM) 6 6 [useful] 245 41 [useless] ............................. 0 211 ( 0.00) (:HYP 1 :REWRITE PERM-MEM) 0 6 [useful] 0 205 [useless] ............................. 0 7 ( 0.00) (:CONC :REWRITE PERM-MEM) 0 6 [useful] 0 1 [useless] -------------------------------- Notice that while [47m:tries[0m are recorded for the xrune [47m(:HYP 1 :REWRITE PERM-MEM)[0m, no [47m:frames[0m are recorded. This is because no stack frames were built for runes while this xrune was on the stack --- only for the xrune itself, which as we explained above is not accumulated into the total [47m:frames[0m counts. As it turns out, this lack of stack frames is explained by the fact that the rewrite rule [47mPERM-MEM[0m has a free variable in the first hypothesis. ACL2 !>:pe perm-mem 18 (DEFTHM PERM-MEM (IMPLIES (AND (PERM X Y) (MEM A X)) (MEM A Y)) :RULE-CLASSES ((:REWRITE :MATCH-FREE :ONCE))) ACL2 !> The second hypothesis, however, does cause additional rewriting in order to rewrite it to true, resulting in 251 stack frames for runes. We see that the conclusion does not lead to creation of any rune stack frames, which might seem to suggest that only 251 stack frames for runes were created on behalf of this rule application --- yet, we see that 462 frames were actually created. The difference is the 211 frames created for the rewrite rule itself. Even if the total had been a bit more than 462, one need not be surprised, as there could be some work recorded during application of the rewrite rule, such as type reasoning (see [TYPE-REASONING]), that is not done during rewriting of a hypothesis or the conclusion. Now suppose we have executed [47m(accumulated-persistence :all)[0m and attempted some proofs, and now we are ready to see statistics. The form [47m(show-accumulated-persistence)[0m displays statistics exactly as described above, treating these extra xrunes just as though they are runes; similarly for the form [47m(show-accumulated-persistence KEY)[0m, for any legal [47mKEY[0m. A second optional argument may however be supplied to [47mshow-accumulated-persistence[0m. The default for that second argument is [47mt[0m, and a second argument of [47m:raw[0m is treated the same as [47mt[0m; thus, these arguments provide the behavior just described, where data for xrunes are displayed just as for runes. You may restrict output to runes, ignoring hypothesis and conclusion xrunes, by giving a second argument of [47mnil[0m. (This gives the same behavior as if we had started with the command [47m(accumulated-persistence t)[0m instead of the command [47m(accumulated-persistence :all)[0m.) You may give a second argument of [47m:merge[0m, in which case output will be sorted and displayed as though only runes were tracked (not the extra xrunes), but each data item for a non-rune xrune will be merged so that it is displayed in suitable order just below its corresponding rune, as in the [47mPERM-MEM[0m example displayed above. Finally, you may give a second argument of [47m:list[0m, which is equivalent to the default second argument of [47mt[0m, except that the results are printed as a list of entries [47m(frames tries xrune)[0m. We close by mentioning two aspects of enhanced statistics display for [47m:CONC[0m xrunes that have potential to be confusing. First consider the following example. :frames :tries :ratio rune -------------------------------- 14 4 ( 3.50) (:REWRITE DEFAULT-+-2) 0 0 [useful] 14 4 [useless] ............................. 10 4 ( 2.50) (:HYP 1 :REWRITE DEFAULT-+-2) 0 0 [useful] 10 4 [useless] -------------------------------- It may be surprising that no data is displayed for the corresponding [47m:CONC[0m xrune. The explanation, however, is simple: the hypothesis never rewrote to true, so the conclusion was never rewritten. This is consistent with the marking as ``useless'' of all [47m:frames[0m and [47m:tries[0m for the rune and the hypothesis xrune. Note by the way, once again, that the hypothesis xrune does not contribute to any [47m:frames[0m count. Another reason not to see data displayed for a [47m:CONC[0m xrune is that if a rule has no hypotheses, then no such data is collected. This decision was made because in the case of no hypotheses, we expect it to be very rare that information for the [47m:CONC[0m xrune will add any useful insight. On a final note: [47m(show-accumulated-persistence :runes)[0m may be used simply to see a list of all [rune]s (or xrunes) displayed alphabetically. Users are encouraged to think about other meters we could install in ACL2 to help diagnose performance problems. Subtopics [Accumulated-persistence-subtleties] Some subtle aspects of the counting done by [47m[accumulated-persistence][0m [Dmr] Dynamically monitor rewrites and other prover activity [Useless-runes] Speed up proofs by disabling useless [rune]s") (accumulated-persistence-oops (pointers) "See [accumulated-persistence].") (accumulated-persistence-subtleties (accumulated-persistence) "Some subtle aspects of the counting done by [47m[accumulated-persistence][0m In this topic we cover the overcounting of ``useful'' [rune] application attempts, and we describe how ``useless'' rune application attempts can actually be critical for a proof's success. We conclude with a few words about counting frames when there are nested (recursive) applications of a rune. [3mOvercounting of ``useful'' rune application attempts.[0m Not every [rune] application may be necessary for a proof's success. Consider for example: (thm (equal (car (cons a (cdr (cons b x)))) a)) Then [47mshow-accumulated-persistence[0m will tell us that [47m:[0m[47m[rewrite][0m rules [47mcar-cons[0m and [47mcdr-cons[0m each had one useful application. However, the rule [47mcdr-cons[0m is used to simplify [47m(cdr (cons b x))[0m to [47mx[0m, and this simplification is unnecessary for the proof. Indeed, the proof succeeds even when preceded by the event: [47m(in-theory (disable cdr-cons))[0m. We thus see that a [rune] application labeled as ``useful'' may be simplifying a term that is not relevant to the proof. As of this writing, we consider every [47m:[0m[47m[forward-chaining][0m rule application to be ``useful'', for simplicity of the implementation. Moreover, our counting of these rules is such that a single rule may be counted more than once. [3mHow ``useless'' attempts can be critical for a proof's success.[0m The command [47m(accumulated-persistence :useless[0m) will list rules that did not contribute directly to the proof (see [accumulated-persistence], in particular the discussion of ``useless'' there). However, a ``useless'' rule can on rare occasions be critical to the success of a proof. In the following example, we have a ``bad'' rule that can take the proof in the wrong direction, but a ``useless'' rule does a rewrite that prevents the successful relieving of a hypothesis of the ``bad'' rule. In summary: ; Assume p0. We want to prove p1. ; Key rule: p0 -> p1 = t ; Bad rule that could ruin the proof: p3 -> p1 = p2 ; But unfortunately, we know p3: p0 -> p3 ; Important ``useless'' rule, preventing ``bad rule'' above from firing: p3 = p4 The following event captures the rules described above. (encapsulate ((p0 (x) t) (p1 (x) t) (p2 (x) t) (p3 (x) t) (p4 (x) t)) (local (defun p0 (x) x)) (local (defun p1 (x) x)) (local (defun p2 (x) x)) (local (defun p3 (x) x)) (local (defun p4 (x) x)) ; Key rule: (defthm p0-implies-p1 (implies (p0 x) (p1 x))) ; Bad rule that could ruin the proof: (defthm p3-implies-p1-is-p2 (implies (p3 x) (equal (p1 x) (p2 x)))) ; But unfortunately, we know p3: (defthm p0-implies-p3 (implies (p0 x) (p3 x))) ; Important ``useless'' rule, preventing p3-implies-p1-is-p2 from firing: (defthm p3-is-p4 (equal (p3 x) (p4 x)))) Now we can see that [47mp3-is-p4[0m is labeled as ``useless'', by evaluating these commands. (accumulated-persistence t) (thm (implies (p0 x) (p1 x))) (show-accumulated-persistence) If instead we first evaluate [47m(in-theory (disable p3-is-p4))[0m before the [47mthm[0m above, then the proof fails, even though [47mp3-is-p4[0m was labeled as ``useless''! Nevertheless, in general it is probably safe to disable rules reported as ``useless'' by [47m(show-accumulated-persistence :useless)[0m, and doing so may speed up a proof considerably. Remark. The example above suggests a surprising fact: on rare occasions, a proof may fail when you give an [47m:[0m[47m[in-theory][0m hint consisting of exactly the [rune]s reported in a proof that succeeds. For, imagine a rule R that is needed in part of the proof but is ``bad'' in a second part, and that some other, ``useless'' rule prevents the application of R in that second part. The example above suggests that disabling this ``useless'' rule can allow the second application of R, thus preventing the proof. Finally we discuss accumulation into frame counts in the case of a nested (recursive) application of a rule: that is, the case that during the application of a rule, the rule is applied again --- in particular, while relieving a hypothesis or rewriting the right-hand side from the original rule application. Recall that the implementation of [accumulated-persistence] keeps a stack of [rune]s currently being applied; thus, we are considering here the case that a rune is pushed onto a stack on which it already resides. In that case, we count tries as usual but we avoid accumulating until we reach the outermost (topmost) application of that rune. Consider the following example. (defun mem (a x) (if (atom x) nil (or (equal a (car x)) (mem a (cdr x))))) Now suppose we consider the theorem [47m(mem a (list 1 2 3 a))[0m. Each time the definition of [47mmem[0m is applied, a new stack frame is pushed. We avoid accumulating into the [47m:frames[0m count for that stack frame unless it is the topmost stack frame for that definition. Otherwise the final [47m:frames[0m count would be the sum of the counts for those individual frames, which form a linear sequence whose sum would therefore be quadratic in the number of applications of the definition of [47mmem[0m.") (acknowledgments (about-acl2) "Some contributors to the well-being of ACL2 The development of ACL2 was initially made possible by funding from the U. S. Department of Defense, including ARPA and ONR. We thank all the organizations that have contributed support, including the following (in alphabetical order). * AMD, for providing significant time over several years for Matt Kaufmann to carry out ACL2 research, support, and development * Computational Logic, Inc. and its president, Don Good, where the first eight years of ACL2 development occurred * Centaur Technology * Collins Aerospace * DARPA * Digital Equipment Corporation * EDS, which provided some time for Matt Kaufmann's ACL2 work 1998-1999 * ForrestHunt and, more generally, Warren A. Hunt, Jr. (see below) * IBM * Intel * Kestrel Institute * Kestrel Technology * NSF (see below) * ONR * SRC * Sun Microsystems * U.S. Army, in particular ARL * University of Texas at Austin (in particular support to J Moore through the Admiral B. R. Inman Chair of Computing Theory) Regarding DARPA support: We thank DARPA for approving release of the following documentation topics and support with ``DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.'' * [Recursion-and-induction] together with its subtopics and its answer key ([community-books] files [47mdemos/r-and-i-answer-key-input.lsp[0m and [47mdemos/r-and-i-answer-key-log.txt[0m) * [Gentle-introduction-to-ACL2-programming] * [Loop$-primer] together with its subtopics and its answer key ([community-books] files [47mlp6.lisp[0m, [47mlp8.lisp[0m, [47mlp12.lisp[0m, [47mlp14.lisp[0m, [47mlp17-11-lemma2.lisp[0m, and [47mlp17.lisp[0m) * [Start-here] Regarding NSF support: * This material is based upon work supported by the National Science Foundation under Grant Nos. CCF-1526760, CNS-1525472, CCF-1153558, EIA-0303609, CNS-0429591, ISS-0417413, CCF-0945316, and CNS-0910913. * Any opinions, findings and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation. We are especially grateful to Warren A. Hunt, Jr. for his unrivaled efforts in securing support for the entire ACL2 research group at both Computational Logic, Inc., and the University of Texas at Austin. Without his efforts, we would have spent less time working on the system and fewer students would have been funded to apply it. ACL2 was started in August, 1989 by Boyer and Moore working together. They co-authored the first versions of axioms.lisp and basis.lisp, with Boyer taking the lead in the formalization of ``[state]'' and the most primitive [io] functions. Boyer also had a significant hand in the development of the early versions of the files interface-raw.lisp and translate.lisp. For several years, Moore alone was responsible for developing the ACL2 system code, though he consulted often with both Boyer and Kaufmann. In August, 1993, Kaufmann became jointly responsible with Moore for developing the system. Boyer has continued to provide valuable consulting on an informal basis. Bishop Brock was the heaviest early user of ACL2, and provided many suggestions for improvements. In particular, the [47m:cases[0m and [47m:restrict[0m [hints] were his idea; he developed an early version of congruence-based reasoning for Nqthm; and he helped in the development of some early [books] about arithmetic. In a demonstration of his courage and faith in us, he pushed for Computational Logic, Inc., to agree to the Motorola CAP contract --- which required formalizing a commercial DSP in the untested ACL2 --- and moved to Scottsdale, AZ, to do the work with the Motorola design team. His demonstration of ACL2's utility was an inspiration, even to those of us designing ACL2. John Cowles also helped in the development of some early [books] about arithmetic, and also provided valuable feedback and bug reports. Other early users of ACL2 at Computational Logic, Inc. helped influence its development. In particular, Warren Hunt helped with the port to Macintosh Common Lisp, and Art Flatau and Mike Smith provided useful general feedback. Mike Smith helped develop the Emacs portion of the implementation of proof trees. ACL2 depends on the availability of robust Common Lisp implementations, so we are grateful to the developers of those implementations. Early in ACL2's history, Bill Schelter made some enhancements to AKCL (now GCL) that helped to enhance ACL2 performance in that Common Lisp implementation, and more generally, responded helpfully to our bug reports. Camm Maguire has since provided wonderful GCL support, and has created a Debian package for ACL2 built on GCL. Gary Byers and R. Matthew Emerson have continually improved Clozure Common Lisp (CCL), often based on feedback from the ACL2 community. We are also grateful to developers of other Common Lisp implementations. Kent Pitman helped in our interaction with the ANSI Common Lisp standardization committee, X3J13. John Cowles helped with the port to Windows (98) by answering questions and running tests. Ruben Gamboa created a modification of ACL2 to allow reasoning about the real numbers using non-standard analysis. His work has been incorporated into the ACL2 distribution; see [real]. Rob Sumners has made numerous useful suggestions. In particular, he has designed and implemented improvements for [stobj]s and been key in our development of locally-bound stobjs; see [note-2-6]. Robert Krug has designed and implemented many changes in the vicinity of the linear arithmetic package and its connection to type-set and rewrite. He was also instrumental in the development of [extended-metafunctions]. Pete Manolios has made numerous useful suggestions. In particular, Pete helped us to organize the first workshop and was a wonderful equal partner with the two of us (Kaufmann and Moore) in producing the books that arose from that workshop. Pete and his student, Daron Vroon, provided the current implementation of [ordinals]. Jared Davis, Sol Swords, and David Rager have our gratitude for starting the {ACL2+Books repository | https://github.com/acl2/acl2/}. We thank David L. Rager for contributing an initial version of the support for [parallelism] in an experimental extension of ACL2. Bob Boyer and Warren A. Hunt, Jr. developed a canonical representation for ACL2 data objects, applicative hash tables, and a function memoization mechanism to facilitate reuse of previously computed results. Subsequently, Jared Davis and Sol Swords made further contributions. We thank them all for this work, most of which has been incorporated into ACL2; see [hons-and-memoization]. Other contributions to the ACL2 system continue to be made by members of the ACL2 community. In particular, following the first Developers Workshop in May, 2017 through the time of this writing in November, 2019, such contributors include Alessandro Coglio, Keshav Kini, Mihir Mehta, Pete Manolios, and especially Sol Swords, while Eric Smith and many others have suggested changes that we have implemented, often by providing helpful examples. The [release-notes] detail such contributions as well as many suggestions from the community for improvements that we ultimately implemented. We also thank the contributors to the ACL2 workshops for some suggested improvements and for the extensive collection of publicly distributed benchmark problems. And we thank participants at the ACL2 seminar at the University of Texas for useful feedback. More generally, we thank the ACL2 community for feedback, contributed [books] (see [community-books]), and their interest in the ACL2 project. [3mRegarding the documentation:[0m Bill Young wrote significant portions of the original [47macl2-tutorial[0m section of the ACL2 documentation, including what is now called [alternative-introduction]. This was an especially important task in the early years when there was no guide for how to use ACL2 and we are very grateful. He, Bishop Brock, Rich Cohen, and Noah Friedman read over considerable amounts of the documentation, and made many useful comments. Others, particularly Bill Bevier and John Cowles, have also made useful comments on the [documentation]. Art Flatau helped develop the ACL2 markup language in which ACL2 [documentation] was originally developed, along with translators from that language to Texinfo and HTML. Michael ``Bogo'' Bogomolny created a search engine, beginning with Version 2.6, and for that purpose modified the HTML translator to create one file per topic (a good idea in any case). Laura Lawless provided many hours of help in marking up appropriate parts of the [documentation] in typewriter font. Noah Friedman developed an Emacs tool that helped us insert ``invisible links'' into the [documentation], which improve the usability of that documentation under HTML readers such as Mosaic. Richard Stallman contributed a texinfo patch, to be found in the file [47mdoc/texinfo.tex[0m. Jared Davis created the [xdoc] system that is now the basis not only for the ACL2 system [documentation] (file [47mbooks/system/doc/acl2-doc.lisp[0m), but also for the [community-books] documentation. We thank Blake Grugett for designing the current version of the ACL2 logo (which for example appears on the ACL2 home page), based on an original design created in the 1990s by Computational Logic, Inc.") (acl2 (top) "ACL2 system documentation Those topics that pertain to the ACL2 system belong under this node of the [documentation]. See [top] for the top node of this manual, under which may be found many topics pertaining to the [community-books]. Subtopics [Bdd] Ordered binary decision diagrams with rewriting [Events] Functions that extend the logic [History] Functions to display or change contents of the logical [world] [Hons-and-memoization] Hash cons, function memoization, and applicative hash tables [Installation] Installing ACL2 [Macros] Macros allow you to extend the syntax of ACL2. [Mailing-lists] Mailing lists for ACL2 users [Miscellaneous] A miscellany of documented functions and concepts (often cited in more accessible [documentation]) [Operational-semantics] Modeling State Machines [Output-controls] Methods for controlling the output produced by the ACL2 prover [Parallelism] Experimental extension for parallel execution and proofs [Programming] Programming in ACL2 [Proof-builder] An interactive tool for controlling ACL2's proof processes. [Real] ACL2(r) support for real numbers [Recursion-and-induction] Recursion and Induction [Rule-classes] Adding rules to the database [Start-here] Introductory information about ACL2 [Theories] Sets of [rune]s to [enable]/[disable] in concert") (acl2-as-standalone-program (acl2-tutorial) "Calling ACL2 from another program ACL2 is intended for interactive use. It is generally unrealistic to expect it to prove theorems fully automatically; see [the-method], and see [introduction-to-the-theorem-prover] for a more detailed tutorial. Nevertheless, here we describe an approach for how to call the ACL2 theorem prover noninteractively. These steps can of course be modified according to your needs. Here, we illustrate how to call ACL2 from another Lisp program (or an arbitrary program) to attempt to prove an arithmetic theorem. See also [interfacing-tools]. In particular, if you want to make a command-line tool to ACL2 with options, you may be interested in [oslib::argv], [getopt], and especially [getopt-demo::demo2]. Alternately, if you want to develop a server application on top of ACL2, you might consider [bridge]. Step 1 Build a suitable ACL2 image by starting ACL2 and then executing the following forms. In particular, these define a macro, [47mtry-thm[0m, that causes ACL2 to exit with an exit status indicating success or failure of a proof attempt. (include-book "arithmetic-5/top" :dir :system) (defmacro try-thm (&rest args) `(mv-let (erp val state) (with-prover-time-limit 3 (thm ,@args)) (declare (ignore val)) (prog2$ (if erp (exit 1) (exit 0)) state)))) (reset-prehistory) ; optional :q (save-exec "arith-acl2" "Included arithmetic-4/top") If you prefer, above you can replace 3 by some other number of seconds as a time limit for the prover. Also, you can replace (with-prover-time-limit 3 (thm ,@args)) by (with-output :off :all (with-prover-time-limit 3 (thm ,@args))) if you want to turn off output. It may be best to leave the output on, instead eliminating it in the calling program (see Step 3 below). Step 2 Try a little test. In that same directory try this: echo '(try-thm (equal x x))' | ./arith-acl2 echo $? The exit status should be 0, indicating success. Now try this: echo '(try-thm (not (equal x x)))' | ./arith-acl2 echo $? The exit status should be 1, indicating failure. Step 3 Create a shell script that automates Step 2, for example: #!/bin/sh (echo "(try-thm $1)" | ./arith-acl2) >& /dev/null exit $? Step 4 Try your script from a Lisp program, if you like. Here is how you can do it in SBCL, for example. (Different Lisps have different ways to do this, as summarized in function [47msystem-call[0m in ACL2 source file [47macl2-init.lisp[0m.) (defun provable? (x) (let ((status (process-exit-code (sb-ext:run-program "./try-thm.sh" (list (format nil "~s" x)) :output t :search t)))) (eql status 0))) Then here is a log: * (provable? '(equal x y)) NIL * (provable? '(equal x x)) T * Certainly refinements are possible --- for example the above doesn't distinguish between unprovable and ill-formed input. But it's a start.") (acl2-built-ins (programming) "''Catch-all'' topic for built-in ACL2 functions This [documentation] topic is a parent topic under which we include documentation for built-in functions, macros, and special forms that are typically used in [programming]. For others, including those typically used as top-level commands or those that create [events] ([47m[defun][0m, [47m[defmacro][0m, [47m[defthm][0m, and so on), documentation may be found as a subtopic of some other parent topic. We do not document some of the more obscure functions provided by ACL2 that do not correspond to functions of Common Lisp. If you are already familiar with Common Lisp (or even some other Lisp variant), then you may find it helpful to start with the topic, [introduction-to-programming-in-ACL2-for-those-who-know-lisp]. See any documentation for Common Lisp for more details on many of these functions. Subtopics [*] Multiplication macro [*ACL2-exports*] Symbols that are often imported into new [packages] to provide easy access to ACL2 functionality. [*common-lisp-symbols-from-main-lisp-package*] Symbols that are often imported into new packages to provide easy access to Common Lisp functionality. [*standard-ci*] An ACL2 character-based analogue of CLTL's [47m*standard-input*[0m [*standard-co*] The ACL2 analogue of CLTL's [47m*standard-output*[0m [*standard-oi*] An ACL2 object-based analogue of CLTL's [47m*standard-input*[0m [+] Addition macro [-] Macro for subtraction and negation [/] Macro for division and reciprocal [/=] Test inequality of two numbers [1+] Increment by 1 [1-] Decrement by 1 [<] Less-than [<=] Less-than-or-equal test [=] Test equality of two numbers [>] Greater-than test [>=] Greater-than-or-equal test [@] Get the value of a global variable in [47m[state][0m [Abs] The absolute value of a real number [Access] Accessor macro for [defrec] structures. [ACL2-count] A commonly used measure for justifying recursion [ACL2-number-listp] Recognizer for a true list of numbers [ACL2-numberp] Recognizer for numbers [Acons] Constructor for association lists [Add-to-set] Add a symbol to a list [Alist-keys-subsetp] Check that all keys of the alist belong to a given set [Alist-to-doublets] Convert an alist to a list of two-element lists [Alistp] Recognizer for association lists [Allocate-fixnum-range] Set aside fixnums in GCL [Alpha-char-p] Recognizer for alphabetic characters [Alphorder] Total order on atoms [And] Conjunction [Append] [concatenate] zero or more lists [Apply$] Apply a badged function or tame lambda to arguments [Aref1] Access the elements of a 1-dimensional array [Aref2] Access the elements of a 2-dimensional array [Arities-okp] check the arities of given function symbols [Arity] number of arguments of a function symbol [Array1p] Recognize a 1-dimensional array [Array2p] Recognize a 2-dimensional array [Aset1] Set the elements of a 1-dimensional array [Aset1-trusted] Set the elements of a 1-dimensional array without [invariant-risk] [Aset2] Set the elements of a 2-dimensional array [Ash] Arithmetic shift operation [Assert$] Cause a hard error if the given test is false [Assert*] Create a [guard] proof obligation that given test holds [Assign] Assign to a global variable in [47m[state][0m [Assoc] Look up key in association list [Assoc-keyword] Look up key in a [47m[keyword-value-listp][0m [Assoc-string-equal] Look up key, a string, in association list [Atom] Recognizer for atoms [Atom-listp] Recognizer for a true list of [atom]s [Binary-*] Multiplication function [Binary-+] Addition function [Binary-append] [concatenate] two lists [Bitp] A recognizer for the set of bits, {0,1} [Boole$] Perform a bit-wise logical operation on 2 two's complement integers [Boolean-listp] Recognizer for a true list of booleans [Booleanp] Recognizer for booleans [Break$] Cause an immediate Lisp break [Break-on-error] Break when encountering a hard or soft error caused by ACL2 [Butlast] All but a final segment of a list [Caaaar] [47m[car][0m of the [47m[caaar][0m [Caaadr] [47m[car][0m of the [47m[caadr][0m [Caaar] [47m[car][0m of the [47m[caar][0m [Caadar] [47m[car][0m of the [47m[cadar][0m [Caaddr] [47m[car][0m of the [47m[caddr][0m [Caadr] [47m[car][0m of the [47m[cadr][0m [Caar] [47m[car][0m of the [47m[car][0m [Cadaar] [47m[car][0m of the [47m[cdaar][0m [Cadadr] [47m[car][0m of the [47m[cdadr][0m [Cadar] [47m[car][0m of the [47m[cdar][0m [Caddar] [47m[car][0m of the [47m[cddar][0m [Cadddr] [47m[car][0m of the [47m[cdddr][0m [Caddr] [47m[car][0m of the [47m[cddr][0m [Cadr] [47m[car][0m of the [47m[cdr][0m [Canonical-pathname] The true absolute filename, with soft links resolved [Car] Returns the first element of a non-empty list, else [47mnil[0m [Case] Conditional based on if-then-else using [47m[eql][0m [Case-match] Pattern matching or destructuring [Cbd] Connected book directory string [Cdaaar] [47m[cdr][0m of the [47m[caaar][0m [Cdaadr] [47m[cdr][0m of the [47m[caadr][0m [Cdaar] [47m[cdr][0m of the [47m[caar][0m [Cdadar] [47m[cdr][0m of the [47m[cadar][0m [Cdaddr] [47m[cdr][0m of the [47m[caddr][0m [Cdadr] [47m[cdr][0m of the [47m[cadr][0m [Cdar] [47m[cdr][0m of the [47m[car][0m [Cddaar] [47m[cdr][0m of the [47m[cdaar][0m [Cddadr] [47m[cdr][0m of the [47m[cdadr][0m [Cddar] [47m[cdr][0m of the [47m[cdar][0m [Cdddar] [47m[cdr][0m of the [47m[cddar][0m [Cddddr] [47m[cdr][0m of the [47m[cdddr][0m [Cdddr] [47m[cdr][0m of the [47m[cddr][0m [Cddr] [47m[cdr][0m of the [47m[cdr][0m [Cdr] Returns the second element of a [47m[cons][0m pair, else [47mnil[0m [Ceiling] Division returning an integer by truncating toward positive infinity [Change] Mutator macro for [defrec] structures. [Char] The [nth] element (zero-based) of a string [Char-code] The numeric code for a given character [Char-downcase] Turn upper-case [characters] into lower-case [characters] [Char-equal] Character equality without regard to case [Char-upcase] Turn lower-case [characters] into upper-case [characters] [Char<] Less-than test for [characters] [Char<=] Less-than-or-equal test for [characters] [Char>] Greater-than test for [characters] [Char>=] Greater-than-or-equal test for [characters] [Character-alistp] Recognizer for association lists with characters as keys [Character-listp] Recognizer for a true list of characters [Characterp] Recognizer for [characters] [Code-char] The character corresponding to a given numeric code [Coerce] Coerce a character list to a string and a string to a list [Comment] Variant of [47m[prog2$][0m to help debug evaluation failures during proofs [Comp] Compile some ACL2 functions [Comp-gcl] Compile some ACL2 functions leaving .c and .h files [Complex] Create an ACL2 number [Complex-rationalp] Recognizes complex rational numbers [Complex/complex-rationalp] Recognizer for complex numbers [Compress1] Remove irrelevant pairs from a 1-dimensional array [Compress2] Remove irrelevant pairs from a 2-dimensional array [Concatenate] Concatenate lists or strings together [Cond] Conditional based on if-then-else [Conjugate] Complex number conjugate [Cons] Pair and list constructor [Cons-count-bounded] Count the number of conses (up to a limit) [Cons-subtrees] Build a fast alist whose keys are the subtrees of X [Cons-with-hint] Alternative to [47m[cons][0m that tries to avoid consing when a suitable [47mcons[0m structure is provided as a hint. [Consp] Recognizer for [cons] pairs [Count] Count the number of occurrences of an item in a string or true-list [Count-keys] Count the number of keys in association list [Cpu-core-count] The number of cpu cores [Cw] Print to the comment window [Cw!] Print readably to the comment window [Cw!+] Print readably and uninhibited to the comment window [Cw+] Print uninhibited to the comment window [Cw-print-base-radix] Print to the comment window in a given print-base [Cw-print-base-radix!] Print to the comment window in a given print-base [Declare] Extra declarations that can occur in function definitions, [let] bindings, and so forth. [Default] Return the [47m:default[0m from the [header] of a 1- or 2-dimensional array [Defbadge] Issue a badge for a function so [47m[apply$][0m can evaluate with it [Defwarrant] Issue a warrant for a function so [47m[apply$][0m can use it in proofs [Delete-assoc] Deprecated version of [remove1-assoc] [Denominator] Divisor of a ratio in lowest terms [Df] Support for floating-point operations [Digit-char-p] The number, if any, corresponding to a given character [Digit-to-char] Map a digit to a character [Dimensions] Return the [47m:dimensions[0m from the [header] of a 1- or 2-dimensional array [Ec-call] Execute a call in the ACL2 logic instead of raw Lisp [Eighth] Eighth member of the list [Endp] Recognizer for empty lists [Eq] Equality of symbols [Eql] Test equality (of two numbers, symbols, or [characters]) [Eqlable-alistp] Recognizer for a true list of pairs whose [47m[car][0ms are suitable for [47m[eql][0m [Eqlable-listp] Recognizer for a true list of objects each suitable for [47m[eql][0m [Eqlablep] The [guard] for the function [47m[eql][0m [Equal] True equality [Er] Print an error message and ``cause an error'' [Er-hard] Print an error message and ``cause a hard error'' [Er-hard?] Print an error message and ``cause a hard error'' [Er-progn] Perform a sequence of state-changing ``error triples'' [Er-soft] Print an error message and ``cause a soft error'' [Error1] Print an error message and cause a ``soft error'' [Evenp] Test whether an integer is even [Evens] The even-indexed members of a list [Explode-atom] Convert any [atom] into a [character-listp] that contains its printed representation, rendering numbers in your choice of print base. [Explode-nonnegative-integer] The list of [characters] in the radix-r form of a number [Expt] Exponential function [Extend-pathname] Extend a relative pathname to an absolute pathname [F-boundp-global] Check whether a global variable in [47m[state][0m has a value [F-get-global] Get the value of a global variable in [47m[state][0m [F-put-global] Assign to a global variable in [47m[state][0m [Fast-alist-clean] [47m(fast-alist-clean alist)[0m can be used to eliminate "shadowed pairs" from a fast alist. [Fast-alist-clean!] [47m(fast-alist-clean! alist)[0m is an alternative to [47m[fast-alist-clean][0m that produces a [normed] result. [Fast-alist-fork] [47m(fast-alist-fork alist ans)[0m can be used to eliminate "shadowed pairs" from an alist or to copy [fast-alists]. [Fast-alist-fork!] [47m(fast-alist-fork! alist ans)[0m is an alternative to [47m[fast-alist-fork][0m that produces a [normed] result. [Fast-alist-free] [47m(fast-alist-free alist)[0m throws away the hash table associated with a fast alist. [Fast-alist-free-on-exit] Free a fast alist after the completion of some form. [Fast-alist-len] [47m(fast-alist-len alist)[0m counts the number of unique keys in a fast alist. [Fast-alist-summary] [47m(fast-alist-summary)[0m prints some basic statistics about any current fast alists. [Fifth] Fifth member of the list [First] First member of the list [Fix] Coerce to a number [Fix-true-list] Coerce to a true list [Flet] Local binding of function symbols [Floor] Division returning an integer by truncating toward negative infinity [Flush-compress] Flush the under-the-hood array for the given name [Flush-hons-get-hash-table-link] Deprecated feature [Fms] [47m(fms str alist co-channel state evisc) => state[0m [Fms!] [47m(fms! str alist co-channel state evisc) => state[0m [Fmt] Formatted printing [Fmt!] [47m(fmt! str alist co-channel state evisc) => state[0m [Fmt-to-comment-window] Print to the comment window [Fmt-to-comment-window!] Print readably to the comment window [Fmt-to-comment-window!+] Print readably and uninhibited to the comment window [Fmt-to-comment-window+] Print uninhibited to the comment window [Fmt1] [47m(fmt1 str alist col co-channel state evisc) => (mv col state)[0m [Fmt1!] [47m(fmt1! str alist col channel state evisc) => (mv col state)[0m [Fmx] [47m(fmx str &rest args) => state[0m [Fmx-cw] [47m(fmx-cw str &rest args) => state[0m [Formula] The formula of a name or [rune] [Fourth] Fourth member of the list [Gc$] Invoke the garbage collector [Gc-strategy] The garbage collection strategy [Get-cpu-time] Read elapsed cpu time [Get-internal-time] Runtime vs. realtime in ACL2 timings [Get-real-time] Read elapsed real time [Getenv$] Read an environment variable [Getprop] Access fast property lists [Getpropc] Access fast property lists [Good-bye] Quit entirely out of Lisp [Hard-error] Print an error message and stop execution [Header] Return the header of a 1- or 2-dimensional array [Hons] [47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m. [Hons-acons] [47m(hons-acons key val alist)[0m is the main way to create or extend [fast-alists]. [Hons-acons!] [47m(hons-acons! key val alist)[0m is an alternative to [47m[hons-acons][0m that produces [normed], fast alists. [Hons-assoc-equal] [47m(hons-assoc-equal key alist)[0m is [31;1mnot fast[0m; it serves as the logical definition for [47m[hons-get][0m. [Hons-clear] [47m(hons-clear gc)[0m is a drastic garbage collection mechanism that clears out the underlying Hons Space. [Hons-clear!] A version of [47m[hons-clear][0m for [parallel] execution [Hons-copy] [47m(hons-copy x)[0m returns a [normed] object that is equal to X. [Hons-copy-persistent] [47m(hons-copy-persistent x)[0m returns a [normed] object that is equal to X and which will be re-normed after any calls to [47m[hons-clear][0m. [Hons-equal] [47m(hons-equal x y)[0m is a recursive equality check that optimizes when parts of its arguments are [normed]. [Hons-get] [47m(hons-get key alist)[0m is the efficient lookup operation for [fast-alists]. [Hons-resize] [47m(hons-resize ...)[0m can be used to manually adjust the sizes of the hash tables that govern which ACL2 Objects are considered [normed]. [Hons-shrink-alist] Deprecated feature [Hons-shrink-alist!] Deprecated feature [Hons-summary] [47m(hons-summary)[0m prints basic information about the sizes of the tables in the current Hons Space. [Hons-wash] [47m(hons-wash)[0m is like [47m[gc$][0m but can also garbage collect [normed] objects (CCL and GCL Only). [Hons-wash!] A version of [47m[hons-wash][0m for [parallel] execution [Identity] The identity function [If] If-then-else function [Iff] Logical ``if and only if'' [Ifix] Coerce to an integer [Illegal] Print an error message and stop execution [Imagpart] Imaginary part of a complex number [Implies] Logical implication [Improper-consp] Recognizer for improper (non-[47mnil[0m-terminated) non-empty lists [In-package] Select current package [In-tau-intervalp] Boolean membership in a tau interval [Int=] Test equality of two integers [Integer-length] Number of bits in two's complement integer representation [Integer-listp] Recognizer for a true list of integers [Integer-range-p] Recognizer for integers between two bounds. [Integerp] Recognizer for whole numbers [Intern] Create a new symbol in a given package [Intern$] Create a new symbol in a given package [Intern-in-package-of-symbol] Create a symbol with a given name [Intersection$] Elements common to the given lists [Intersectp] Test whether two lists intersect [Keyword-listp] Recognizer for true lists of keywords [Keyword-value-listp] Recognizer for true lists whose even-position elements are keywords [Keywordp] Recognizer for keywords [Kwote] Quote an arbitrary object [Kwote-lst] Quote an arbitrary true list of objects [Last] The last [47m[cons][0m (not element) of a list [Last-cdr] The last [47m[cdr][0m of a list [Last-prover-steps] The number of prover steps most recently taken [Len] Length of a list [Length] Length of a string or proper list [Let] Binding of lexically scoped (local) variables [Let*] Binding of lexically scoped (local) variables [Lexorder] Total order on ACL2 objects [List] Build a list [List$] Build a list [List*] Build a list [Listp] Recognizer for (not necessarily proper) lists [Logand] Bitwise logical `and' of zero or more integers [Logandc1] Bitwise logical `and' of two ints, complementing the first [Logandc2] Bitwise logical `and' of two ints, complementing the second [Logbitp] The [47mi[0mth bit of an integer [Logcount] Number of ``on'' bits in a two's complement number [Logeqv] Bitwise logical equivalence of zero or more integers [Logic-fns-list-listp] Recognizer for when a given list of lists of [term]s calls only [47m:[0m[47m[logic][0m-mode function symbols [Logic-fns-listp] Recognizer for when a given list of [term]s calls only [47m:[0m[47m[logic][0m-mode function symbols [Logic-fnsp] Recognizer for when a given [term] calls only [47m:[0m[47m[logic][0m-mode function symbols [Logic-term-list-listp] Recognizer for lists of lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols [Logic-term-listp] Recognizer for lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols [Logic-termp] Recognizer for [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols [Logior] Bitwise logical inclusive or of zero or more integers [Lognand] Bitwise logical `nand' of two integers [Lognor] Bitwise logical `nor' of two integers [Lognot] Bitwise not of a two's complement number [Logorc1] Bitwise logical inclusive or of two ints, complementing the first [Logorc2] Bitwise logical inclusive or of two ints, complementing the second [Logtest] Test if two integers share a `1' bit [Logxor] Bitwise logical exclusive or of zero or more integers [Loop$] Iteration with an analogue of the Common Lisp [47mloop[0m macro [Lower-case-p] Recognizer for lower case characters [Macrolet] Local binding of macro symbols [Make] Constructor macro for [defrec] structures. [Make-character-list] [coerce] to a list of characters [Make-fast-alist] [47m(make-fast-alist alist)[0m creates a fast-alist from the input alist, returning [47malist[0m itself or, in some cases, a new object equal to it. [Make-list] Make a list of a given size [Make-ord] A constructor for ordinals. [Make-tau-interval] Make a tau interval [Makunbound-global] Remove the value assigned to a global variable in [47m[state][0m [Max] The larger of two numbers [Maximum-length] Return the [47m:maximum-length[0m from the [header] of an array [Maybe-flush-and-compress1] Compress a one-dimensional array only if necessary [Mbe] Attach code for execution [Mbe1] Attach code for execution [Mbt] Introduce a test into the logic that, however, evaluates to [47mt[0m [Mbt*] Introduce a guard proof obligation [Member] Membership predicate [Merge-sort-lexorder] Sort a list [Min] The smaller of two numbers [Minusp] Test whether a number is negative [Mod] Remainder using [47m[floor][0m [Mod-expt] Exponential function [Msg] Construct a ``message'' suitable for the [47m~@[0m directive of [47m[fmt][0m [Msgp] Recognizer for a ``message'' [Must-be-equal] Attach code for execution [Mv] Returning a multiple value [Mv-let] Calling multi-valued ACL2 functions [Mv-list] Converting [multiple-value] result to a single-value list [Mv-nth] The nth element (zero-based) of a multiply valued expression [Mv?] Return one or more values [Mv?-let] Calling possibly multi-valued ACL2 functions [Nat-listp] Recognizer for a true list of natural numbers [Natp] A recognizer for the natural numbers [Nfix] Coerce to a natural number [Ninth] Ninth member of the list [No-duplicatesp] Check for duplicates in a list [Non-exec] Mark code as non-executable [Nonnegative-integer-quotient] Natural number division function [Not] Logical negation [Nth] The nth element (zero-based) of a list [Nthcdr] Final segment of a list [Null] Recognizer for the empty list [Number-subtrees] [47m(number-subtrees x)[0m returns the number of distinct subtrees of X, in the sense of [47m[equal][0m [Numerator] Dividend of a ratio in lowest terms [O-finp] Recognizes if an ordinal is finite [O-first-coeff] Returns the first coefficient of an ordinal [O-first-expt] The first exponent of an ordinal [O-infp] Recognizes if an ordinal is infinite [O-p] A recognizer for the ordinals up to epsilon-0 [O-rst] Returns the rest of an infinite ordinal [O<] The well-founded less-than relation on ordinals up to [47mepsilon-0[0m [O<=] The less-than-or-equal relation for the ordinals [O>] The greater-than relation for the ordinals [O>=] The greater-than-or-equal relation for the ordinals [Observation] Print an observation [Oddp] Test whether an integer is odd [Odds] The odd-indexed members of a list [Open-output-channel!] When trust tags are needed to open output channels [Or] Disjunction [Packn] Build a symbol from a list [Packn-pos] Build a symbol in a specified package from a list [Pairlis$] Zipper together two lists [Pairlis-x1] Cons a given element to each member of a list [Pairlis-x2] Cons each element of a list with a given element [Pand] Parallel, Boolean version of [47m[and][0m [Pargs] Parallel evaluation of arguments in a function call [Pkg-witness] Return a specific symbol in the indicated package [Plet] Parallel version of [47m[let][0m [Plusp] Test whether a number is positive [Por] Parallel, Boolean version of [47m[or][0m [Pos-listp] Recognizer for a true list of positive integers [Position] Position of an item in a string or a list [Posp] A recognizer for the positive integers [Pprogn] Evaluate a sequence of forms that return [state] [Primitive] Primitive functions built into ACL2 without definitions [Princ$] Print an atom [Print-base-p] Recognizer for print bases that are understood by functions such as [explode-nonnegative-integer] and [explode-atom]. [Print-object$] Print an object to an open object output channel [Print-object$+] Print an object to an open output channel in a specified manner [Prog2$] Execute two forms and return the value of the second one [Progn$] Execute a sequence of forms and return the value of the last one [Proofs-co] The proofs character output channel [Proper-consp] Recognizer for proper ([47mnil[0m-terminated) non-empty lists [Pseudo-term-listp] A predicate for recognizing lists of term-like s-expressions [Pseudo-termp] A predicate for recognizing term-like s-expressions [Put-assoc] Modify an association list by associating a value with a key [Putprop] Update fast property lists [Quote] Create a constant [R-eqlable-alistp] Recognizer for a true list of pairs whose [47m[cdr][0ms are suitable for [47m[eql][0m [R-symbol-alistp] Recognizer for association lists with symbols as values [Random$] Obtain a random value [Rassoc] Look up value in association list [Rational-listp] Recognizer for a true list of rational numbers [Rationalp] Recognizer for rational numbers (ratios and integers) [Read-ACL2-oracle] Pop the oracle field of the state [Read-run-time] Read elapsed runtime [Real-listp] ACL2(r) recognizer for a true list of real numbers [Real/rationalp] Recognizer for rational numbers (including real number in ACL2(r)) [Realfix] Coerce to a real number [Realpart] Real part of a complex number [Rem] Remainder using [47m[truncate][0m [Remove] Remove all occurrences [Remove-assoc] Remove all pairs with a given key from an association list [Remove-duplicates] Remove duplicates from a string or a list [Remove1] Remove first occurrences, testing using [47m[eql][0m [Remove1-assoc] Remove the first pair with a given key from an association list [Resize-list] List resizer in support of [stobj]s [Rest] Rest ([47m[cdr][0m) of the list [Return-last] Return the last argument, perhaps with side effects [Revappend] Concatenate the [reverse] of one list to another [Reverse] Reverse a list or string [Rfix] Coerce to a rational number [Round] Division returning an integer by rounding off [Search] Search for a string or list in another string or list [Second] Second member of the list [Serialize-read] Read a serialized ACL2 object from a file [Serialize-write] Write an ACL2 object into a file [Set-difference$] Elements of one list that are not elements of another [Set-fmt-hard-right-margin] Set the right margin for formatted output [Set-fmt-soft-right-margin] Set the soft right margin for formatted output [Set-gc-strategy] Set the garbage collection strategy (CCL only) [Set-print-base] Control radix in which numbers are printed [Set-print-base-radix] Control radix in which numbers are printed and printing of the radix [Set-print-case] Control whether [symbols] are printed in upper case or in lower case [Set-print-radix] Control printing of the radix for numbers [Setenv$] Set an environment variable [Seventh] Seventh member of the list [Signed-byte-p] Recognizer for signed integers that fit in a specified bit width [Signum] Indicator for positive, negative, or zero [Sixth] Sixth member of the list [Spec-mv-let] Modification of [47m[mv-let][0m supporting speculative and parallel execution [Standard-char-listp] Recognizer for a true list of standard characters [Standard-char-p] Recognizer for standard characters [Standard-char-p+] Recognizer for standard characters whose guard is [47mt[0m [Standard-co] The character output channel to which [47m[ld][0m prints [Standard-oi] The standard object input ``channel'' [State-global-let*] Bind [state] global variables [String] [coerce] to a string [String-alistp] Recognizer for association lists with strings as keys [String-append] [concatenate] two strings [String-downcase] In a given string, turn upper-case [characters] into lower-case [String-equal] String equality without regard to case [String-listp] Recognizer for a true list of strings [String-upcase] In a given string, turn lower-case [characters] into upper-case [String<] Less-than test for strings [String<=] Less-than-or-equal test for strings [String>] Greater-than test for strings [String>=] Less-than-or-equal test for strings [Stringp] Recognizer for strings [Strip-cars] Collect up all first components of pairs in a list [Strip-cdrs] Collect up all second components of pairs in a list [Sublis] Substitute an alist into a tree [Subseq] Subsequence of a string or list [Subsetp] Test if every [47m[member][0m of one list is a [47m[member][0m of the other [Subst] A single substitution into a tree [Substitute] Substitute into a string or a list, using [47m[eql][0m as test [Swap-stobjs] Swap two congruent [stobj]s [Symbol-alistp] Recognizer for association lists with symbols as keys [Symbol-listp] Recognizer for a true list of symbols [Symbol-name] The name of a symbol (a string) [Symbol-name-lst] Lift [47m[symbol-name][0m to lists [Symbol-package-name] The name of the package of a symbol (a string) [Symbol<] Less-than test for symbols [Symbolp] Recognizer for symbols [Sys-call] Make a system call to the host operating system [Sys-call*] Make a system call to the host OS, returning a status [Sys-call+] Make a system call to the host OS, returning status and output [Sys-call-status] Exit status from the preceding system call [Take] Initial segment (first n elements) of a list [Tenth] Tenth member of the list [Term-list-listp] recognizer for a list of [clause]s [Term-listp] recognizer for a list of quotations of terms and of [clause]s [Term-order] The ordering relation on terms used by ACL2 [Termp] recognizer for the quotation of a [term] [The] Special form for execution efficiency or run-time type checks [The-number] Coerce an expected number to a number [The-true-list] Coerce an expected true list to a true list [Third] Third member of the list [Time$] Time the evaluation of a given form [Time-tracker] Display time spent during specified evaluation [Trace-co] The [trace] character output channel [True-list-fix] Coerce to a true list [True-list-listp] Recognizer for true (proper) lists of true lists [True-listp] Recognizer for proper ([47mnil[0m-terminated) lists [Truncate] Division returning an integer by truncating toward 0 [Unary--] Arithmetic negation function [Unary-/] Reciprocal function [Union$] A list that contains exactly the elements of the given lists [Unquote] Obtain the object being quoted [Unsigned-byte-p] Recognizer for natural numbers that fit in a specified bit width [Update-nth] Modify a list by putting the given value at the given position [Update-nth-array] Update a stobj array [Upper-case-p] Recognizer for upper case characters [Value-triple] Compute a value, optionally checking that it is not [47mnil[0m [With-fast-alist] [47m(with-fast-alist name form)[0m causes [47mname[0m to be a fast alist for the execution of [47mform[0m. [With-global-stobj] Operate on a global single-threaded object [With-guard-checking] Suppress or enable guard-checking for a form [With-guard-checking-error-triple] Suppress or enable guard-checking for a form [With-guard-checking-event] Suppress or enable guard-checking for an event form [With-live-state] Allow a reference to [47mstate[0m in raw Lisp [With-local-state] Locally bind state [With-local-stobj] Locally bind a single-threaded object [With-output-lock] Provides a mutual-exclusion mechanism for performing output in parallel [With-serialize-character] Control output mode for [47mprint-object$[0m [With-stolen-alist] [47m(with-stolen-alist name form)[0m ensures that [47mname[0m is a fast alist at the start of the execution of [47mform[0m. At the end of execution, it ensures that [47mname[0m is a fast alist if and only if it was originally. That is, if [47mname[0m was not a fast alist originally, its hash table link is freed, and if it was a fast alist originally but its table was modified during the execution of [47mform[0m, that table is restored. Note that any extended table created from the original fast alist during [47mform[0m must be manually freed. [Without-evisc] Print output in full [Xor] Logical ``exclusive or'' [Zerop] Test an acl2-number against 0 [Zip] Testing an ``integer'' against 0 [Zp] Testing a ``natural'' against 0 [Zpf] Testing a nonnegative fixnum against 0") (acl2-count (basics acl2-built-ins) "A commonly used measure for justifying recursion [47m(Acl2-count x)[0m returns a nonnegative integer that indicates the ``size'' of its argument [47mx[0m. All [characters] and symbols have [47macl2-count 0[0m. The [47macl2-count[0m of a string is the number of [characters] in it, i.e., its length. The [47macl2-count[0m of a [47m[cons][0m is one greater than the sum of the [47macl2-count[0ms of the [47m[car][0m and [47m[cdr][0m. The [47macl2-count[0m of an integer is its absolute value. The [47macl2-count[0m of a rational is the sum of the [47macl2-count[0ms of the numerator and denominator. The [47macl2-count[0m of a complex rational is one greater than the sum of the [47macl2-count[0ms of the real and imaginary parts. [31;1mFunction: [0m<acl2-count> (defun acl2-count (x) (declare (xargs :guard t)) (if (consp x) (+ 1 (acl2-count (car x)) (acl2-count (cdr x))) (if (rationalp x) (if (integerp x) (integer-abs x) (+ (integer-abs (numerator x)) (denominator x))) (if (complex/complex-rationalp x) (+ 1 (acl2-count (realpart x)) (acl2-count (imagpart x))) (if (stringp x) (length x) 0)))))") (acl2-customization (miscellaneous) "File of initial commands for ACL2 to run at [startup] ACL2 provides a mechanism to load automatically a so-called ``ACL2 customization file,'' via [47m[ld][0m, the first time [47m[lp][0m is called in an ACL2 session. ACL2 looks for this file as follows. 1. If the host Lisp reads a non-empty value for the system's environment variable [47mACL2_CUSTOMIZATION[0m, then that string value is used for the customization file name. In this case, if the file does not exist or if the string is "NONE" then there is no customization file. Notes: * If the customization file name is a relative pathname (see [pathname]), then the pathname is considered relative to the connected book directory (see [cbd]). * If this variable is not already defined, then its value is set to [47mNONE[0m when books are certified using [build::cert.pl] or other, legacy Make-based certification tools. 2. Otherwise (empty environment variable value), file [47m"acl2-customization.lsp"[0m or [47m"acl2-customization.lisp"[0m on the connected book directory (see [cbd]), generally the current directory, is the customization file (in that order) if either exists. 3. Otherwise file [47m"acl2-customization.lsp"[0m or [47m"acl2-customization.lisp"[0m on your home directory is the customization file (in that order), if either exists (except, this case is skipped on Windows operating systems. Except for the fact that this [47m[ld][0m command is not typed explicitly by you, it is a standard [47m[ld][0m command except that any settings of [47m[ld][0m specials are remembered once this call of [47m[ld][0m has completed other than [47m[ld-error-action][0m, which will always be [47m:command-conventions[0m after that call of [47mld[0m completes. For example, suppose that you start your customization file with [47m(set-ld-skip-proofsp t state)[0m, so that proofs are skipped as it is loaded with [47m[ld][0m. Then the [47m[ld][0m special [47m[ld-skip-proofsp][0m will remain [47mt[0m after the [47m[ld][0m has completed, causing proofs to be skipped in your ACL2 session, unless your customization file sets this variable back to [47mnil[0m, say with [47m(set-ld-skip-proofsp nil state)[0m. If the customization file exists, it is loaded with [47m[ld][0m using the usual default values for the [47m[ld][0m specials (see [ld]) except that [47m:ld-error-action[0m is [47m:error[0m. If an error is encountered, then no subsequent forms in the file will be evaluated and ACL2 will quit immediately. To create a customization file it is recommended that you first give it a name other than [47m"acl2-customization.lsp"[0m or [47m"acl2-customization.lisp"[0m so that ACL2 does not try to include it prematurely when you next enter [47m[lp][0m. Then, while in the uncustomized [47m[lp][0m, explicitly invoke [47m[ld][0m on your evolving (but renamed) customization file until all forms are successfully evaluated. The same procedure is recommended if for some reason ACL2 cannot successfully evaluate all forms in your customization file: temporarily rename your customization file so that ACL2 does not try to [47m[ld][0m it automatically and then debug the new file by explicit calls to [47m[ld][0m. WARNING! If you certify a book after the (automatic) loading of a customization file, the forms in that file will be part of the [portcullis] of the [books] you certify! That is, the forms in your customization file at certification time will be loaded whenever anybody uses the [books] you are certifying. Since customization files generally contain idiosyncratic [command]s, you may not want yours to be part of the [books] you create for others. Thus, if you have a customization file then you may want to invoke [47m:[0m[47m[ubt][0m[47m 1[0m before certifying any [books]; alternatively, see [certify-book!] for automatic invocation of [47m[ubt][0m. On the other hand, if you wish to prevent undoing commands from the customization file, see [reset-prehistory]. Note that except on Windows-based systems, if there is a file [47macl2-init.lsp[0m in your home directory, then it will be loaded into raw Lisp when ACL2 is invoked. Silent loading of ACL2 customization files When the environment variable [47mACL2_CUSTOMIZATION_QUIET[0m is set and not [47m""[0m, there will generally be no output from ACL2 customization. A special value of [47m"all"[0m for this variable will cause continued minimal output after startup, as explained in the following remark. Technical Remark. For quiet loading of acl2-customization files, [47m[ld][0m specials are bound to the following values. ld-verbose = nil ld-pre-eval-print = :never ld-post-eval-print = nil ld-prompt = nil These [47mld[0m specials are returned to their normal values after loading an ACL2 customization file, with one exception: if [47mACL2_CUSTOMIZATION_QUIET[0m has value [47m"ALL"[0m (or [47m"all"[0m; the case is irrelevant), then those values are retained in the ACL2 loop even after customization completes.") (acl2-defaults-table (table) "A [table] specifying certain defaults, e.g., the default [defun-mode] Example Forms: (table acl2-defaults-table :defun-mode) ; current default defun-mode (table acl2-defaults-table :defun-mode :program) ; set default defun-mode to :program See [table] for a discussion of tables in general. The legal keys for this [table] are shown below. They may be accessed and changed via the general mechanisms provided by [table]s. However, there are often more convenient ways to access and/or change the defaults. (See also the note below.) :user The [47m:user[0m key is for ACL2 users; the system does not consult this key or set it (other than as part of general [47macl2-defaults-table [0m maintenance). Its value is required to be an association list ([47m[alistp][0m), so that different users can read and write their ``own'' keys. For example, suppose user Joe uses key [47m:j[0m while user Mary uses key [47m:m[0m; then we could see a value for [47m:user[0m of [47m((:j . 3) (:m . 4))[0m after Joe sets his value to 3 and Mary sets her value to 4. :defun-mode the default [defun-mode], which must be [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m. See [defun-mode] for a general discussion of [defun-mode]s. The [47m:[0m[47m[defun-mode][0m key may be conveniently set by keyword commands naming the new [defun-mode], [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m. See [program] and see [logic]. :enforce-redundancy if [47mt[0m, cause ACL2 to insist that most events are redundant (see [redundant-events]); if [47m:warn[0m, cause a warning instead of an error for such non-redundant events; else, [47mnil[0m. See [set-enforce-redundancy]. :verify-guards-eagerness an integer between 0 and 3 indicating how eager the system is to verify the [guard]s of a [defun] event. See [set-verify-guards-eagerness]. :compile-fns When this key's value is [47mt[0m, functions are compiled when they are [47m[defun][0m'd; otherwise, the value is [47mnil[0m. (Except, this key's value is ignored when explicit compilation is suppressed; see [compilation].) To set the flag, see [set-compile-fns]. :measure-function the default measure function used by [47m[defun][0m when no [47m:measure[0m is supplied in [47m[xargs][0m. The default measure function must be a function symbol of one argument. Let [47mmfn[0m be the default measure function and suppose no [47m:measure[0m is supplied with some recursive function definition. Then [47m[defun][0m finds the first formal, [47mvar[0m, that is tested along every branch and changed in each recursive call. The system then ``guesses'' that [47m(mfn var)[0m is the [47m:measure[0m for that [47m[defun][0m. :well-founded-relation the default well-founded relation used by [47m[defun][0m when no [47m:well-founded-relation[0m is supplied in [47m[xargs][0m. The default well-founded relation must be a function symbol, [47mrel[0m, of two arguments about which a [47m:well-founded-relation[0m rule has been proved. See [well-founded-relation-rule]. :bogus-defun-hints-ok When this key's value is [47mt[0m, ACL2 allows [47m:hints[0m and also [47m:measure[0m for nonrecursive function definitions. Otherwise, the value is [47mnil[0m (the default) or [47m:warn[0m (which makes the check but merely warns when the check fails). See [set-bogus-defun-hints-ok] and [set-bogus-measure-ok]. :bogus-mutual-recursion-ok When this key's value is [47mt[0m, ACL2 skips the check that every function in a [47m[mutual-recursion][0m (or [47m[defuns][0m) ``clique'' calls at least one other function in that ``clique.'' Otherwise, the value is [47mnil[0m (the default) or [47m:warn[0m (which makes the check but merely warns when the check fails). See [set-bogus-mutual-recursion-ok]. :irrelevant-formals-ok When this key's value is [47mt[0m, the check for irrelevant formals is bypassed; otherwise, the value is the keyword [47mnil[0m (the default) or [47m:warn[0m (which makes the check but merely warns when the check fails). See [irrelevant-formals] and see [set-irrelevant-formals-ok]. :ignore-ok When this key's value is [47mt[0m, the check for ignored variables is bypassed; otherwise, the value is the keyword [47mnil[0m (the default) or [47m:warn[0m (which makes the check but merely warns when the check fails). See [set-ignore-ok]. :bdd-constructors This key's value is a list of function symbols used to define the notion of ``BDD normal form.'' See [bdd-algorithm] and see [hints]. :ttag This key's value, when non-[47mnil[0m, allows certain operations that extend the trusted code base beyond what is provided by ACL2. See [defttag]. See [defttag]. :state-ok This key's value is either [47mt[0m or [47mnil[0m and indicates whether the user is aware of the syntactic restrictions on the variable symbol [47mSTATE[0m. See [set-state-ok]. :backchain-limit This key's value is a list of two ``numbers.'' Either ``number'' may optionally be [47mnil[0m, which is treated like positive infinity. The numbers control backchaining through hypotheses during [type-reasoning] and rewriting. See [backchain-limit]. :default-backchain-limit This key's value is a list of two ``numbers.'' Either ``number'' may optionally be [47mnil[0m, which is treated like positive infinity. The numbers are used respectively to set the backchain limit of a rule if one has not been specified. See [backchain-limit]. :step-limit This key's value is either [47mnil[0m or a natural number not exceeding the value of [47m*default-step-limit*[0m. If the value is [47mnil[0m or the value of [47m*default-step-limit*[0m, there is no limit on the number of ``steps'' that ACL2 counts during a proof: currently, the number of top-level rewriting calls. Otherwise, the value is the maximum number of such calls allowed during evaluation of any event. See [set-prover-step-limit]. :rewrite-stack-limit This key's value is a nonnegative integer less than [47m(expt 2 28)[0m. It is used to limit the depth of calls of ACL2 rewriter functions. See [rewrite-stack-limit]. :let*-abstractionp This key affects how the system displays subgoals. The value is either [47mt[0m or [47mnil[0m. When t, let* expressions are introduced before printing to eliminate common subexpressions. The actual goal being worked on is unchanged. :case-split-limitations This key's value is a list of two ``numbers.'' Either ``number'' may optionally be [47mnil[0m, which is treated like positive infinity. The numbers control how the system handles case splits in the simplifier. See [set-case-split-limitations]. :include-book-dir-alist This key's value is used by [47m[include-book][0m's [47m:DIR[0m argument to associate a directory with a keyword. It need not associate a value with [47m:SYSTEM[0m, to denote the [47mbooks/[0m directory (see [community-books]; see [include-book], in particular the section on ``Books Directory.'' Also see [47m[add-include-book-dir][0m, [47m[add-include-book-dir!][0m, and [47m[project-dir-alist][0m. :match-free-default This key's value is either [47m:all[0m, [47m:once[0m, or [47mnil[0m. See [set-match-free-default]. :match-free-override This key's value is a list of runes. See [add-match-free-override]. :match-free-override-nume This key's value is an integer used in the implementation of [add-match-free-override], so that only existing runes are affected by that event. :non-linearp This key's value is either [47mt[0m or [47mnil[0m and indicates whether the user wishes ACL2 to extend the linear arithmetic decision procedure to include non-linear reasoning. See [non-linear-arithmetic]. :tau-auto-modep This key's value is either [47mt[0m or [47mnil[0m and indicates whether the user wishes ACL2 to look for opportunities to create [47m:[0m[47m[tau-system][0m rules from all suitable [47mdefun[0ms and from all suitable [47mdefthm[0ms (with non-[47mnil[0m [47m:[0m[47m[rule-classes][0m). See [set-tau-auto-mode]. :subgoal-loop-limits This key's value must be a [47m[cons][0m whose [47m[car][0m is either [47mnil[0m or a natural number and whose [47m[cdr][0m is [47mnil[0m or a natural number. See [set-subgoal-loop-limits]. :ruler-extenders This key's value may be a list of symbols, indicating those function symbols that are not to block the collection of rulers; see [defun]. Otherwise the value is [47m:all[0m to indicate all function symbols, i.e., so that no function symbol blocks the collection of rulers. If a list is specified (rather than [47m:all[0m), then it may contain the keyword [47m:lambdas[0m, which has the special role of specifying all [47mlambda[0m applications. No other keyword is permitted in the list. See [rulers]. :memoize-ideal-okp This key's value must be either [47mt[0m, [47mnil[0m, or [47m:warn[0m. If the value is [47mnil[0m or not present, then it is illegal by default to [memoize] a [47m:[0m[47m[logic][0m mode function that has not been [guard]-verified (see [verify-guards]), sometimes called an ``ideal-mode'' function. This illegality is the default because such calls of such functions in the ACL2 loop are generally evaluated in the logic (using executable counterpart definitions; see [evaluation]), rather than directly by executing calls of the corresponding (memoized) raw Lisp function. However, such a raw Lisp call can be made when the function is called by a [47m:[0m[47m[program][0m mode function, so we allow you to override the default behavior by associating the value [47mt[0m or [47m:warn[0m with the key [47m:memoize-ideal-okp[0m, where with [47m:warn[0m you get a suitable warning. Note that you can also allow memoization of ideal-mode functions by supplying argument [47m:ideal-okp[0m to your memoization event (see [memoize]), in which case the value of [47m:memoize-ideal-okp[0m in the [47macl2-defaults-table[0m is irrelevant. :check-invariant-risk For an explanation of this key, see [set-check-invariant-risk]. :register-invariant-risk For an explanation of this key, see [set-register-invariant-risk]. :in-theory-redundant-okp When this key's value is [47mt[0m, an [47m[in-theory][0m event may be redundant. See [47m[set-in-theory-redundant-okp][0m. Note: Unlike all other [table]s, [47macl2-defaults-table[0m can affect the soundness of the system. The [table] mechanism therefore enforces on it a restriction not imposed on other [table]s: when [47m[table][0m is used to update the [47macl2-defaults-table[0m, the key and value must be variable-free forms. Thus, while (table acl2-defaults-table :defun-mode :program), (table acl2-defaults-table :defun-mode ':program), and (table acl2-defaults-table :defun-mode (compute-mode *my-data*)) are all examples of legal [events] (assuming [47mcompute-mode[0m is a function of one non-[47m[state][0m argument that produces a [defun-mode] as its single value), (table acl2-defaults-table :defun-mode (compute-mode (w state))) is not legal because the value form is [47m[state][0m-sensitive. Consider for example the following three [events] which one might make into the text of a book. (in-package "ACL2") (table acl2-defaults-table :defun-mode (if (ld-skip-proofsp state) :logic :program)) (defun crash-and-burn (x) (car x)) The second event is illegal because its value form is [47m[state][0m-sensitive. If it were not illegal, then it would set the [47m:[0m[47m[defun-mode][0m to [47m:[0m[47m[program][0m when the book was being certified but would set the [defun-mode] to [47m:[0m[47m[logic][0m when the book was being loaded by [47m[include-book][0m. That is because during certification, [47m[ld-skip-proofsp][0m is [47mnil[0m (proof obligations are generated and proved), but during book inclusion [47m[ld-skip-proofsp][0m is non-[47mnil[0m (those obligations are assumed to have been satisfied.) Thus, the above book, when loaded, would create a function in [47m:[0m[47m[logic][0m mode that does not actually meet the conditions for such status. For similar reasons, [47m[table][0m [events] affecting [47macl2-defaults-table[0m are illegal within the scope of [47m[local][0m forms. That is, the text (in-package "ACL2") (local (table acl2-defaults-table :defun-mode :program)) (defun crash-and-burn (x) (car x)) is illegal because [47macl2-defaults-table[0m is changed locally. If this text were acceptable as a book, then when the book was certified, [47mcrash-and-burn[0m would be processed in [47m:[0m[47m[program][0m mode, but when the certified book was included later, [47mcrash-and-burn[0m would have [47m:[0m[47m[logic][0m mode because the [47m[local][0m event would be skipped. The text (in-package "ACL2") (program) ;which is (table acl2-defaults-table :defun-mode :program) (defun crash-and-burn (x) (car x)) is acceptable and defines [47mcrash-and-burn[0m in [47m:[0m[47m[program][0m mode, both during certification and subsequent inclusion. We conclude with important observations about the interaction of the [47macl2-defaults-table[0m with [47m[include-book][0m, [47m[certify-book][0m, and [47m[encapsulate][0m. If the [47macl2-defaults-table[0m has value [47mV[0m and you evaluate a call of [47m[include-book][0m, [47m[certify-book][0m, or [47m[encapsulate][0m, then the [47macl2-defaults-table[0m has value [47mV[0m when that call returns. Thus, if you want to set the [47macl2-defaults-table[0m in a way that persists, you need to do so using [command]s that are not inside [books]. It may be useful to set your favorite defaults in your [47m[ACL2-customization][0m file; see [ACL2-customization]. ACL2 disallows (for logical reasons) setting of the [47macl2-defaults-table[0m in the context of [47mLOCAL[0m. Often it is easy simply to avoid wrapping an [47macl2-defaults-table[0m event, or a macro that generates such an event, inside a [47mLOCAL[0m; after all, a local context is not useful when setting the [47macl2-defaults-table[0m, since that table is restored as discussed above upon completion of [47m[include-book][0m, [47m[certify-book][0m, and [47m[encapsulate][0m forms. Occasionally a bit more thought is required to work around this restriction, but usually it's not difficult to do so. Suppose for example that you attempt to put following event form into a book. (local (progn (defttag t) (defun foo (x) (sys-call x nil)))) ACL2 responds with the following error message. ACL2 Error in ( PROGN (DEFTTAG T) ...): The form (DEFTTAG T) is not an embedded event form in the context of LOCAL because it implicitly sets the acl2-defaults-table in a local context; see :DOC acl2-defaults-table, in particular the explanation about this error message. See :DOC embedded-event-form. A solution is to use [47m[encapsulate][0m instead of (or in addition to) [47m[progn][0m, because [47m[encapsulate][0m establishes a new context that is not considered within a surrounding [47mLOCAL[0m. For example, the following replacement for the form above is legal in a book. (local (encapsulate () (defttag t) (defun foo (x) (sys-call x nil)))) To see that this works, try creating a file [47m"foo.lisp"[0m whose first form is [47m(in-package "ACL2")[0m and whose only other form is the one displayed just above. Then the command [47m(certify-book "foo" 0 t :ttags :all)[0m will successfully certify that book.") (acl2-doc (documentation) "A custom Emacs browser for reading ACL2 [documentation] As discussed elsewhere (see [documentation]), the web-based {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html} provides a way to browse the combined documentation for the ACL2 system and community books. Such documentation can also be read at the terminal using the [47m:[0m[47m[doc][0m command, though documentation for [books] will only be included for those books that have been included in the session. In this topic we describe how to browse the documentation using ACL2-Doc, a browser for reading documentation inside Emacs. It supports reading the combined documentation (ACL2 plus books), but it also supports reading the ACL2-only manual as well as custom manuals. We assume some familiarity with Emacs, for example, the notion of a ``prefix argument'': a numeric value given first with the [47mmeta[0m key (or, probably the [47mcontrol[0m key), for example, [47mmeta-0 control-t g[0m or [47mcontrol-3 control-t /[0m. Note: If you are not happy with the way text is displayed with ACL2-Doc, see [xdoc::terminal]. While ACL2-Doc is much like Emacs Info, it is a separate system that provides some additional functionality. ACL2-Doc is text-based. Any word that names a topic is a link: you can hit the [47m<Return>[0m key while standing on that topic to go to the page of documentation for that topic. However, many links are shown explicitly, inside square brackets. For example, here is a link that will take you to the BOOKS topic; it should show up surrounded by square brackets if you are now reading at the terminal or in ACL2-Doc, but there are no square brackets for this link if you are reading on the web. [books] It should be very rare for square brackets to be intended simply as square brackets, not as link indicators. In order to use ACL2-Doc, load into Emacs the distributed file [47macl2-doc.el[0m from an appropriate directory; see [emacs]. This will happen automatically if you load [47memacs-acl2.el[0m from an appropriate directory; again, see [emacs]. Then to start the browser at the top-level topic, either execute the Emacs command meta-x acl2-doc or else type: Control-t g Thus, you can put the following form in your [47m.emacs[0m file if you want [47macl2-doc[0m to run automatically when Emacs starts up. (acl2-doc) By default you will browse the ACL2+Books Manual, though if you are using a git version between ACL2 releases then you may be queried; more on that below. Or, see below for how to set a variable in your [47m.emacs[0m file, [47m*acl2-doc-manual-name*[0m, so that you will browse a custom manual. You can enter the ACL2-Doc browser at a specific documentation topic as follows (in analogy to Emacs command [47mMeta-.[0m): Control-t . In each of the cases above, you will now be in a buffer called "[47macl2-doc[0m", which will be displaying the top-level ACL2 topic in a special mode, the ACL2-Doc major mode. That mode provides the following key bindings; you can also see these by typing [47mControl-h m[0m while in that buffer. <Return> acl2-doc-go! Shift-<Return> acl2-doc-go!-new-buffer g acl2-doc-go G acl2-doc-go-new-buffer h acl2-doc-help ? acl2-doc-summary i acl2-doc-index , acl2-doc-index-next < acl2-doc-index-previous K acl2-doc-kill-buffers l acl2-doc-last n acl2-doc-search-next p acl2-doc-search-previous q acl2-doc-quit r acl2-doc-return s acl2-doc-search S acl2-doc-re-search t acl2-doc-top u acl2-doc-up w acl2-doc-where SPC scroll-up TAB acl2-doc-tab <backtab> (which often is Shift-TAB): acl2-doc-tab-back D acl2-doc-rendered-combined-download H acl2-doc-history I acl2-doc-initialize / acl2-doc-definition Control-t / acl2-doc-definition W acl2-doc-where-definition You can see the documentation for each of these in the usual way, using [47mControl-h k {key}[0m or [47mControl-h f {command}[0m. Here is what you will find in each case if you do that. <Return> acl2-doc-go! Go to the topic occurring at the cursor position. In the case of <NAME>, instead go to the source code definition of NAME for the current manual (as for `/', but without a minibuffer query). Shift-<Return> acl2-doc-go!-new-buffer Go to the topic occurring at the cursor position in a new buffer. In the case of <NAME>, instead go to the source code definition of NAME for the current manual (as for `/', but without a minibuffer query). The new buffer's name reflects that topic name, but it stays the same even if the topic is subsequently changed there. g acl2-doc-go Go to the specified topic; performs completion. The new buffer's name reflects that topic name, but it stays the same even if the topic is subsequently changed there. G acl2-doc-go-new-buffer Go to the specified topic in a new buffer; performs completion. h acl2-doc-help Go to the ACL2-DOC topic to read about how to use the ACL2-Doc browser. ? acl2-doc-summary Go to the ACL2-Doc-summary topic for one-line summaries of ACL2-Doc browser commands. i acl2-doc-index Go to the specified topic or else one containing it as a substring; performs completion. If the empty string is supplied, then go to the index buffer. Otherwise, with prefix argument, consider only descendants of the topic supplied in response to a prompt. Note that the index buffer is in ACL2-Doc mode; thus, in particular, you can type <RETURN> while standing on a topic in order to go directly to that topic. , acl2-doc-index-next Find the next topic containing, as a substring, the topic of the most recent i command. Note: if this is the first "," or "<" after an exact match from "i", then start the topic search alphabetically from the beginning, but avoid a second hit on the original topic. Also note that this command is buffer-local; it will follow the most recent i command executed in the current ACL2-Doc buffer. < acl2-doc-index-previous Find the previous topic containing, as a substring, the topic of the most recent i command. Note: if this is the first "," or "<" after an exact match from "i", then start the topic search alphabetically (backwards) from that exact match. Also note that this command is buffer-local like the "," command. l acl2-doc-last Go to the last topic visited in the current buffer. This command is buffer-local. n acl2-doc-search-next Find the next occurrence for the most recent search or regular expression search. Note that this command is buffer-local; it will follow the most recent search initiated in the current buffer. p acl2-doc-search-previous Find the previous occurrence for the most recent search or regular expression search. Note: as for "n", the cursor will end up at the end of the match, and this command is buffer-local. q acl2-doc-quit Quit the current ACL2-Doc buffer. K acl2-doc-kill-buffers Kill all background ACL2-Doc buffers. If invoked in an ACL2-Doc buffer, all ACL2-Doc buffers except the current one will be killed. If invoked in any other buffer, all ACL2-Doc buffers will be killed. With prefix argument, avoid a query that asks for confirmation. r acl2-doc-return Return to the last topic visited in the current buffer, popping the stack of such topics. This command is buffer-local. s acl2-doc-search Search forward from the top of the manual for the input string. If the search succeeds, then go to that topic with the cursor put immediately after the found text, with the topic name displayed in the minibuffer. With prefix argument, consider (also for subsequent "n" and "p" commands) only descendants of the topic supplied in response to a prompt. S acl2-doc-re-search Perform a regular expression search, forward from the top of the manual, for the input string. If the search succeeds, then go to that topic with the cursor put immediately after the found text, with the topic name displayed in the minibuffer. With prefix argument, consider (also for subsequent "n" and "p" commands) only descendants of the topic supplied in response to a prompt. t acl2-doc-top Go to the top topic. u acl2-doc-up Go to the parent of the current topic. w acl2-doc-where Display the topic name in the minibuffer, together with the manual name (ACL2+Books Manual or ACL2 User's Manual) SPC scroll-up Scroll up (same as Control-v) TAB acl2-doc-tab Visit the next link after the cursor on the current page, searching from the top if no link is below the cursor. <backtab> (which often is Shift-TAB): acl2-doc-tab-back Visit the previous link before the cursor on the current page, searching from the bottom if no link is below the cursor. D Download the ``bleeding edge'' ACL2+Books Manual from the web; then restart the ACL2-Doc browser to view that manual. If this fails, evaluate Emacs variable acl2-doc-download-error for information on how to perform the download without Emacs. H acl2-doc-history Visit a buffer that displays the names of all topics visited (in any ACL2-Doc buffer) in order, newest at the bottom. That buffer is in acl2-doc mode; thus the usual acl2-doc commands may be used. In particular, you can visit a displayed topic name by putting your cursor on it and typing <RETURN>. I acl2-doc-initialize Restart the ACL2-Doc browser, clearing its state. With a prefix argument, a query asks you to select the name of an available manual, using completion. See the section on "Selecting a Manual", below, for more information. / acl2-doc-definition (also control-t /) Find an ACL2 definition (in analogy to built-in Emacs command meta-.). With numeric prefix argument, find the next matching definition; otherwise, the user is prompted, where the default is the name at the cursor, obtained after stripping off any enclosing square brackets ([..]), angle brackets (<..>) as from srclink tags, and package prefixes. With control-u prefix argument, search only ACL2 source definitions; otherwise, books are searched as well. As with built-in Emacs command meta-. , exact matches are given priority. For more information, see the Section on "Selecting a Manual" in the acl2-doc online XDOC-based documentation. W acl2-doc-where-definition Find an ACL2 definition. This is the same as acl2-doc-definition (the acl2-doc `/' command, as well as control-t /), except that the default comes from the name of the current page's topic instead of the cursor position. Searches are continued identically when control-t / is given a numeric prefix argument, regardless of whether the first command was /, control-t /, or W; thus, a search started with W can be continued with, for example, meta-3 control-t /. Selecting a Manual, Tags Files, and Custom Manuals ACL2-Doc can display the ACL2 User's Manual, which includes documentation for the ACL2 system but not for the [community-books]. But by default, ACL2-Doc will display the ACL2+Books Manual, which includes documentation for those books as well. To change which of these two manuals you display, just give a prefix argument to the `[47mI[0m' command, as described briefly above. For the `[47m/[0m' and `[47mW[0m' commands, you will need tags table files. These come with the ACL2 gzipped tarfile distribution, but if you obtain ACL2 from github then you will need to build them. The file [47m"TAGS"[0m is used when these commands are given a prefix argument (to search only the ACL2 sources), and is generated when building the [47msaved_acl2[0m executable with `[47mmake[0m'. Without a prefix argument the file [47m"TAGS-acl2-doc"[0m is used for searching both the ACL2 sources and the books, and is created automatically if you build the manual by certifying community book [47mbooks/doc/top.lisp[0m. You can also build [47m"TAGS-acl2-doc"[0m by running the command [47mbin/make-tags-acl2-doc.sh[0m, or by building the ACL2 executable after setting variable [47mTAGS_ACL2_DOC[0m to a non-empty value other than [47mSKIP[0m either on the command line with `[47mmake[0m' or, for example, by putting one of the following forms in your [47m~/.cshrc[0m or [47m~/.bashrc[0m, respectively. setenv TAGS_ACL2_DOC t export TAGS_ACL2_DOC=t If you are using a git version of ACL2 and the books, between releases, then you may need to download an extra file in order to browse the ACL2+Books Manual. Most likely you will just answer [47my[0m when queried about downloading the file when first using ACL2-Doc. If you want more details, see the last of the notes in the ``Notes'' section below. As mentioned above, you can give the `[47mI[0m' command a prefix argument in order to select a specific manual. You will be asked for a name, which by default will be the most recently selected such name, if any. As noted above, the only two manuals initially known to acl2-doc are the ACL2+Books Manual and the ACL2 User's Manual. These have the names `[47mcombined[0m' and `[47macl2-only[0m', respectively. You can also tell acl2-doc about a custom manual, by evaluating (in Emacs) the following form, e.g., by adding it to your [47m~/.emacs[0m file before starting Emacs. Here, [47mfilename[0m is the pathname of a file typically created by calling [xdoc::save-rendered]. (extend-acl2-doc-manual-alist 'name ; the name of the manual filename ; documentation source, typically of the form *doc*.lsp 'top ; the top node name, typically TOP printname ; optional print name (user-level name) of manual url ; optional URL of gzipped file to download into filename tags-file-name ; optional tags filename (from output of etags) acl2-tags-file-name ; as above, but without files from books/ directory ) For example, acl2-doc is initially built with the following two forms, which is why you can respond to the query mentioned above with `[47mcombined[0m' or `[47macl2-only[0m'. (extend-acl2-doc-manual-alist 'combined (concat *acl2-sources-dir* "books/system/doc/rendered-doc-combined.lsp") 'TOP "ACL2+Books Manual" "https://acl2.org/doc/rendered-doc-combined.lsp.gz" (concat *acl2-sources-dir* "TAGS-acl2-doc") (concat *acl2-sources-dir* "TAGS")) (extend-acl2-doc-manual-alist 'acl2-only (concat *acl2-sources-dir* "doc.lisp") 'ACL2 "ACL2 User's Manual" nil nil (concat *acl2-sources-dir* "TAGS")) Note that the first of these forms specifies the location of the [47m"TAGS-acl2-doc"[0m and [47m"TAGS"[0m files mentioned above, but the second only specifies [47m"TAGS"[0m since the second form is for an ACL2-only manual (no books). If you want a specific manual to come up when you first run acl2-doc in an Emacs session, you can put the following into your [47m.emacs[0m file, where [47m'name[0m is the name a manual for which you have included a form [47m(extend-acl2-doc-manual-alist 'name ...)[0m in your [47m.emacs[0m file. (setq *acl2-doc-manual-name* 'name) Color By default, links (indeed, any text) in square brackets will be shown in blue. You can customize this behavior by setting (e.g., in your [47m.emacs[0m file) the Emacs variable [47m*acl2-doc-link-color*[0m to the desired link color, or to [47mnil[0m if you don't want the links to be in color. For example: (setq *acl2-doc-link-color* "#FF0000") ; red (setq *acl2-doc-link-color* "Green") ; green (setq *acl2-doc-link-color* nil) ; no special color for links Notes * You might find that when you attempt to follow some-broken-link, you find yourself at the [broken-link] topic. If you are using the ACL2 User's Manual rather than the ACL2+Books Manual, the reason might be that [47msome-broken-link[0m is documented in a book, not in the ACL2 system. In that case, the [47mbroken-link[0m page will show you where to find that book; but if you want to read the documentation for [47msome-broken-link[0m in the ACL2-Doc browser, you can do so by switching to the ACL2+Books Manual. See the [47mI[0m command, documented above. * Files with names ending in [47m.acl2-doc[0m will come up in ACL2-Doc mode. Thus, you may wish to save a file with that extension, for example [47mbookmarks.acl2-doc[0m, that contains your favorite bookmarks. You may wish to use the history command ([47mH[0m) to obtain a list of names of visited topics, in order to create an initial such file. * Many commands offer defaults, and many offer completion. The default is determined by cursor position: if the cursor is sitting on a letter of a documentation topic name, or on a space character immediately after it, then that name will be offered as the default. Completion tips: * Completion is carried out with the usual emacs ``[47mcompleting-read[0m''; thus, for example, the character `[47m?[0m' is a help key, so if you want that character as part of your topic name, prefix it with [47mcontrol-q[0m. For example, after the `[47mg[0m' command you can go to the topic [47m[mv?][0m by typing the character sequence [47m<m,v,control-q ?>[0m. * To find completions that have package prefixes, type a colon (:) in the front, and completion will show matching topics. For example, [47m"g"[0m followed by [47m":rew"[0m and then two tabs will show, at least in recent versions of Emacs, a list of topics that includes [47m"ACL2-PC::REWRITE"[0m. * Square brackets typically indicate documentation topic names, for example: [47m[acl2-doc][0m. (As mentioned above, there are occasional exceptions, where square brackets are simply part of the intended documentation text.) The square brackets are really there, for example when you are searching using "s", "S", or "n". However, for purposes of determining the default name (see above), the only effect of the enclosing square brackets is to extend the region in which the default is offered. For example, consider the string "[47m[acl2-doc][0m": the default name of "[47macl2-doc[0m" is offered if the cursor is on either square bracket. But links have some idiosyncrasies. 1. Topic names, including links `[47m[..][0m' to topic names, are printed relative to the ACL2 package. Especially in the case of the ACL2+Books Manual, you may therefore see links that include package prefixes. Here, for example, is a sentence from the documentation for [gl] in the ACL2+Books Manual. We call these structures [gl::symbolic-objects]. The "[47mgl[0m" package prefix allows commands to pick up "[47mgl::symbolic-objects[0m" as the name to use as a default, so that for example, hitting [47m<Return>[0m will take you to that topic. But when reading the sentence, for best results you should ignore package prefixes. So for example, you would read the sentence above as follows. We call these structures symbolic-objects. 2. Inside ACL2-Doc, topic names that originally contained spaces now have underscores in place of the spaces. So for example, the topic [ACL2-tutorial] in the ACL2+Books Manual contains a link to the topic originally named as follows. [47m|Pages Written Especially for the Tours|[0m This link shows up in the ACL2-Doc browser as: [47m[Pages_Written_Especially_for_the_Tours][0m. Of course, the web-based browser avoids these idiosyncrasies (see [xdoc::save]); in particular, that browser is best for ``Tours'' pages like the one shown above and its subtopics, in part because that way you may see images. Hence the web-based browser may be more appropriate for some topics, and for those who have no particular preference for using Emacs to browse the documentation. * Searching using the "s" or "S" command is carried out by searching top-to-bottom in a hidden Emacs buffer that contains all of the documentation. The topics are listed in the following order according to topic name: 1. All topics whose names reside in the "[47mACL2[0m" package; 2. All topics whose names reside in the "[47mACL2-PC[0m" package; and, for the ACL2+Books Manual, 3. All other topics, sorted by [47m[symbol-name][0m and then by [47m[symbol-package-name][0m. * You may be queried, regarding whether you want to browse the ACL2+Books Manual, which is preferred, or the ACL2 User's Manual, which omits documentation for the books. Both of these manuals are based on files that you will have if you are using a released version of ACL2 (after Version 6.3). But if you are using a {git version | https://github.com/acl2/acl2/}, then to use the ACL2+Books Manual you will need an extra file. You can build this file yourself, as described below but you may prefer to download it: for example, when you start ACL2-Doc, you may be given the option of downloading {a tarball for the latest ``bleeding edge'' copy | https://acl2.org/doc/rendered-doc-combined.lsp.gz} and extracting into directory [47msystem/doc/[0m of your community books directory. Indeed, the system will do all this for you if you answer [47my[0m to that query. Alternatively, you can insist on a download of a ``bleeding edge'' version by using the `[47mD[0m' command. However, if you prefer to browse the ACL2 User's Manual (without the books), you can put the following form into your [47m~/.emacs[0m file, above the form that loads the code for ACL2-Doc (see above). (defvar *acl2-doc-manual-name* 'acl2-only) If you prefer to build [47mrendered-doc-combined.lsp[0m yourself, you can do so as follows. 1. Build ACL2: make 2. Build the file [47mbooks/system/doc/rendered-doc-combined.lsp[0m while standing in the [47mbooks/[0m directory, as follows. If "[47macl2[0m" invokes the ACL2 executable that you just built, then you may omit "[47mACL2=acl2[0m" below; otherwise replace "[47macl2[0m" by a suitable executable. On a multi-core machine you may wish to use [47m-j[0m, e.g., [47mmake -j 4 ...[0m. cd books make doc/top.cert USE_QUICKLISP=1 ACL2=acl2") (acl2-doc-summary (documentation) "Summary of [ACL2-doc] commands See [ACL2-doc] for information about the custom Emacs browser for viewing ACL2 [documentation]. In the present topic we list the commands with extremely abbreviated documentation: only a single line for each. For even briefer summaries, you can use the standard Emacs command, [47mControl-h m[0m. <Return> acl2-doc-go! Go to the topic occurring at the cursor position. Shift-<Return> acl2-doc-go!-new-buffer Go to the topic occurring at the cursor position in a new buffer. g acl2-doc-go Go to the specified topic; performs completion. G acl2-doc-go-new-buffer Go to the specified topic in a new buffer; performs completion. h acl2-doc-help Go to the ACL2-Doc topic to read about how to use the ACL2-Doc browser. ? acl2-doc-summary Go to the ACL2-Doc-summary topic for one-line summaries of commands. i acl2-doc-index Go to the specified topic or else one containing it as a substring. , acl2-doc-index-next Continue to the next topic for the most recent i command. < acl2-doc-index-previous Return to the preceding topic for the most recent i command. K acl2-doc-kill-buffers Kill all background ACL2-Doc buffers. l acl2-doc-last Go to the last topic visited. n acl2-doc-search-next Find the next occurrence for the most recent search. p acl2-doc-search-previous Find the previous occurrence for the most recent search. q acl2-doc-quit Quit the ACL2-Doc browser. r acl2-doc-return Return to the last topic visited, popping the stack of such topics. s acl2-doc-search Search for the input string (with prefix arg: under a given topic). S acl2-doc-re-search Regular-expression search (with prefix arg: under a given topic). t acl2-doc-top Go to the top topic. u acl2-doc-up Go to the parent of the current topic. w acl2-doc-where Display the topic and manual name in the minibuffer. SPC scroll-up Scroll up (same as Control-v) TAB acl2-doc-tab Visit the next link on the current page. <backtab> (which often is Shift-TAB): acl2-doc-tab-back Visit the previous link on the current page. D Download the manual from the web; then restart ACL2-Doc. H acl2-doc-history Visit the History buffer, with names of all visited topics in order. I acl2-doc-initialize Restart ACL2-Doc. With a prefix argument, choose which manual. / acl2-doc-definition Control-t / acl2-doc-definition Find an ACL2 definition (in analogy to built-in Emacs command meta-.). W acl2-doc-where-definition Find an ACL2 definition, with default from current page's topic.") (acl2-help (about-acl2) "The acl2-help mailing list You can email questions about ACL2 usage to the acl2-help mailing list: [47macl2-help@utlists.utexas.edu[0m. If you have more general questions about ACL2, for example, about projects completed using ACL2, you may prefer the acl2 mailing list, [47macl2@utlists.utexas.edu[0m, which tends to have wider distribution. The following mailing list pages include links to their archives. * acl2-help list: [47m{https://utlists.utexas.edu/sympa/info/acl2-help | https://utlists.utexas.edu/sympa/info/acl2-help}[0m * acl2 list: [47m{https://utlists.utexas.edu/sympa/info/acl2 | https://utlists.utexas.edu/sympa/info/acl2}[0m") (acl2-number-listp (numbers lists acl2-built-ins) "Recognizer for a true list of numbers The predicate [47macl2-number-listp[0m tests whether its argument is a true list of numbers. [31;1mFunction: [0m<acl2-number-listp> (defun acl2-number-listp (l) (declare (xargs :guard t)) (cond ((atom l) (eq l nil)) (t (and (acl2-numberp (car l)) (acl2-number-listp (cdr l))))))") (acl2-numberp (numbers acl2-built-ins) "Recognizer for numbers [47m(acl2-numberp x)[0m is true if and only if [47mx[0m is a number, i.e., a rational or complex rational number.") (acl2-sedan (acl2-tutorial) "ACL2 Sedan interface Many successful ACL2 users run in a shell under Emacs; see [emacs]. However, those not familiar with Emacs may prefer to start with an Eclipse-based interface initially developed by Peter Dillinger and Pete Manolios called the ACL2 Sedan or ``ACL2s''. ACL2 sessions in the ACL2 Sedan can utilize non-standard extensions and enhancements, especially geared toward new users, termination reasoning, and attaching rich user interfaces. These extensions are distributed with the ACL2 community books in [47mbooks/acl2s/distribution/acl2s-hooks/[0m. Thanks to Peter Dillinger, Pete Manolios, Daron Vroon, and Harsh Raju Chamarthi for their work on the ACL2 Sedan and for making their books available to ACL2 users.") (acl2-tutorial (start-here about-acl2) "Tutorial introduction to ACL2 To learn about ACL2, read at least the following two links. * Industrial Applications of ACL2 (see [INTERESTING-APPLICATIONS]) (10 minutes) to help you understand what sophisticated users can do; * A Flying Tour (see [A_Flying_Tour_of_ACL2]) (10 minutes) to get an overview of the system and what skills the user must have. Alternatively, or in addition, there are [talks] that you can peruse, many of them introductory in nature. If you want to learn [3mhow to use[0m ACL2, we recommend that you read a selection of the materials referenced below, depending on your learning style, and do suggested exercises. * A Walking Tour (see [A_Walking_Tour_of_ACL2]) (1 hour) provides an overview of the theorem prover. * The {Try ACL2 | http://tryacl2.org} web site provides interactive lessons to get you started using ACL2. * See [introduction-to-the-theorem-prover] (10-40 hours) for instruction on how to interact with the system. Unlike the three documents above, this document expects you to [3mthink[0m! It cites the necessary background pages on programming in ACL2 and on the logic and then instructs you in [the-method], which is how expert users use ACL2. It concludes with some challenge problems for the ACL2 beginner (including solutions) and an FAQ. Most users will spend several hours a day for several days working through this material. * The book {Computer-Aided Reasoning: An Approach | https://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html} is worth a careful read, as you work exercises and learn [the-method]. * Annotated ACL2 Scripts and Demos (see [ANNOTATED-ACL2-SCRIPTS]) contains relatively elementary proof scripts that have been annotated to help train the newcomer. * Many files (``books'') in the ACL2 community books (see [community-books]) are extensively annotated. * An Alternative Introduction (see [ALTERNATIVE-INTRODUCTION]) document, while largely subsumed by the Introduction to the Theorem Prover (see [INTRODUCTION-TO-THE-THEOREM-PROVER]) mentioned above, still might be useful because it covers much of the tutorial material in a different way. At this point you are probably ready to use ACL2 on your own [3msmall[0m projects. A common mistake for beginners is to browse the documentation and then try to do something that is too big! Think of a very small project and then simplify it! Note that ACL2 has a very supportive user network. See the link to ``Mailing Lists'' on the {ACL2 home page | https://www.cs.utexas.edu/users/moore/acl2}. The topics listed below are a hodge podge, developed over time. Although some of these are not mentioned above, you might find some to be useful as well. Subtopics [ACL2-as-standalone-program] Calling ACL2 from another program [ACL2-sedan] ACL2 Sedan interface [Advanced-features] Some advanced features of ACL2 [Alternative-introduction] Introduction to ACL2 [Annotated-ACL2-scripts] Examples of ACL2 scripts [Emacs] Emacs support for ACL2 [Interesting-applications] Some industrial examples of ACL2 use [Introduction-to-the-theorem-prover] How the theorem prover works --- level 0 [Nqthm-to-ACL2] ACL2 analogues of Nqthm functions and commands [Pages_Written_Especially_for_the_Tours] Pages Written Especially for the Tours [Startup] How to start using ACL2; the ACL2 [command] loop [Talks] Some talks about ACL2 [The-method] How to find proofs [Tidbits] Some basic hints for using ACL2 [Tips] Some hints for using the ACL2 prover [Tours] The Tours") (acl2-unwind-protect (pointers) "See [system-utilities].") (acl2-user (packages) "A package the ACL2 user may prefer This package imports the standard Common Lisp symbols that ACL2 supports and also a few symbols from package [47m"ACL2"[0m that are commonly used when interacting with ACL2. You may prefer to select this as your current package so as to avoid colliding with ACL2 system names. This package imports the symbols listed in [47m*common-lisp-symbols-from-main-lisp-package*[0m, which contains hundreds of CLTL function and macro names including those supported by ACL2 such as [47m[cons][0m, [47m[car][0m, and [47m[cdr][0m. It also imports the symbols in [47m*acl2-exports*[0m, which contains a few symbols that are frequently used while interacting with the ACL2 system, such as [47m[implies][0m, [47m[defthm][0m, and [47m[rewrite][0m. It imports nothing else. Thus, names such as [47m[alistp][0m, [47m[member-equal][0m, and [47m[type-set][0m, which are defined in the [47m"ACL2"[0m package are not present here. If you find yourself frequently colliding with names that are defined in [47m"ACL2"[0m you might consider selecting [47m"ACL2-USER"[0m as your current package (see [in-package]). If you select [47m"ACL2-USER"[0m as the current package, you may then simply type [47m[member-equal][0m to refer to [47macl2-user::member-equal[0m, which you may define as you see fit. Of course, should you desire to refer to the [47m"ACL2"[0m version of [47m[member-equal][0m, you will have to use the [47m"ACL2::"[0m prefix, e.g., [47macl2::member-equal[0m. If, while using [47m"ACL2-USER"[0m as the current package, you find that there are symbols from [47m"ACL2"[0m that you wish we had imported into it (because they are frequently used in interaction), please bring those symbols to our attention. For example, should [47m[union-theories][0m and [47m[universal-theory][0m be imported? Except for stabilizing on the ``frequently used'' names from [47m"ACL2"[0m, we intend never to define a symbol whose [47m[symbol-package-name][0m is [47m"ACL2-USER"[0m.") (acl2p (pointers) "See [parallelism].") (acl2p-key-checkpoints (parallel-proof) "Key checkpoints in ACL2(p) This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. For printing output, the parallel version of the waterfall follows the precedent of [47m[gag-mode][0m. The idea behind gag mode is to print only the subgoals most relevant to debugging a failed proof attempt. These subgoals are called 'key checkpoints' (see [set-gag-mode] for the definition of ``key'' and ``checkpoint''), and we restrict the default output mode for the parallel version of the waterfall to printing checkpoints similar to these key checkpoints. As of this writing, we are aware of exactly one discrepancy between gag mode's key checkpoints and the parallel version of the waterfall's checkpoints. This discrepancy occurs when using ``by'' hints (see [hints]). As an example, take the following form, which attempts to prove a non-theorem: (thm (equal (append x y z) (append z (append y x))) :hints (("Subgoal *1/2'''" :by nil))) With waterfall parallelism enabled, [47mSubgoal *1/2''[0m will be printed as a key checkpoint. This is different from using [47m[gag-mode][0m while running the serial version of the waterfall, which skips printing the subgoal as a checkpoint. For those familiar with the ACL2 waterfall, we note that the parallel version of the waterfall prints key checkpoints that are unproved in the following sense: a subgoal is a key checkpoint if it leads, in the current call of the waterfall, to a goal that is pushed for induction.") (acl2r (pointers) "See [real].") (acl2s (pointers) "See [ACL2-sedan].") (acl2_as_an_interactive_theorem_prover (pages_written_especially_for_the_tours) "ACL2 as an Interactive Theorem Prover The ACL2 theorem prover finds proofs in the ACL2 logic. It can be automatic. But most often the user must help it. {IMAGE} The user usually guides ACL2 by suggesting that it first prove key [31;1mlemmas[0m. Lemmas are just theorems used in the proofs of other theorems.") (|ACL2_AS_AN_INTERACTIVE_THEOREM_PROVER_{CONT}| (pages_written_especially_for_the_tours) "ACL2 as an Interactive Theorem Prover (cont) {IMAGE} (see [ACL2_System_Architecture]) When ACL2 proves a lemma, it is converted into one or more [31;1mrules[0m and stored in a [31;1mdatabase[0m. The theorem prover is [31;1mrule-driven[0m. By proving lemmas you can configure ACL2 to behave in certain ways when it is trying to prove formulas in a certain problem domain. The expert user can make ACL2 do amazingly ``smart'' looking things. But it would be wrong to think that ACL2 [3mknows[0m the mathematical content of a formula just because it has proved it. What ACL2 knows --- all ACL2 knows --- is what is encoded in its rules. There are many types of rules (see [rule-classes] {ICON} (see [A_Tiny_Warning_Sign])). Many formulas can be effectively coded as rules. But by the same token, it is possible to encode a formula as a rule that is so ineffective it cannot even prove itself! The way a formula is stored as a rule is entirely up to the user. That is, [31;1myou[0m determine how ACL2 should use each formula that it proves. The most common kind of rule is the [31;1mrewrite rule[0m. It is so common that if you don't tell ACL2 how to store a formula, it stores it as a rewrite rule. {IMAGE} (see [ACL2_System_Architecture])") (acl2_characters (pages_written_especially_for_the_tours) "ACL2 Characters ACL2 accepts 256 distinct characters, which are the characters obtained by applying the function [47m[code-char][0m {ICON} (see [A_Tiny_Warning_Sign]) to each integer from 0 to 255. Among these, Common Lisp designates certain ones as [47m*standard-characters*[0m, namely those of the form [47m(code-char n)[0m where n is from 33 to 126, together with [47m#\Newline[0m and [47m#\Space[0m. The actual standard characters may be viewed by evaluating the constant expression [47m*standard-chars*[0m. The standard character constants are written by writing a hash mark followed by a backslash (#\) followed by the character. The function [47m[characterp][0m {ICON} (see [A_Tiny_Warning_Sign]) recognizes characters. For more details, See [characters] {ICON} (see [A_Tiny_Warning_Sign]).") (acl2_conses_or_ordered_pairs (pages_written_especially_for_the_tours) "ACL2 Conses or Ordered Pairs The function [47m[cons][0m {ICON} (see [A_Tiny_Warning_Sign]) creates an ordered pair. [47m[Car][0m {ICON} (see [A_Tiny_Warning_Sign]) and [47m[cdr][0m {ICON} (see [A_Tiny_Warning_Sign]) return the first and second components, respectively, of an ordered pair. The function [47m[consp][0m {ICON} (see [A_Tiny_Warning_Sign]) recognizes ordered pairs. Ordered pairs are used to represent lists and trees. See any Common Lisp documentation for a discussion of how list constants are written and for the many list processing functions available. Also, see [programming] {ICON} (see [A_Tiny_Warning_Sign]) where we list all the ACL2 primitive functions. Here are some examples of list constants to suggest their syntax. '(a . b) ; a pair whose car is 'a and cdr is 'b '(a . nil) ; a pair whose car is 'a and cdr is nil '(a) ; another way to write the same thing '(a b) ; a pair whose car is 'a and cdr is '(b) '(a b c) ; a pair whose car is 'a and cdr is '(b c) ; i.e., a list of three symbols, a, b, and c. '((a . 1) (b . 2)) ; a list of two pairs It is useful to distinguish ``proper'' conses from ``improper'' ones, the former being those cons trees whose right-most branch terminates with [47mnil[0m. A ``true list'' (see [true-listp] {ICON} (see [A_Tiny_Warning_Sign])) is either [47mnil[0m or a proper cons. [47m(A b c . 7)[0m is an improper cons and hence not a true list.") (acl2_is_an_untyped_language (pages_written_especially_for_the_tours) "ACL2 is an Untyped Language The example ACL2 !>[31;1m(app '(a b c) 27)[0m (A B C . 27) illustrates the fact that ACL2's logic is untyped (click here (see [About_Types]) for a brief discussion of the typed versus untyped nature of the logic). The definition of [47mapp[0m makes no restriction of the arguments to lists. The definition says that if the first argument satisfies [47m[endp][0m {ICON} (see [A_Tiny_Warning_Sign]) then return the second argument. In this example, when [47mapp[0m has recursed three times down the [47mcdr[0m of its first argument, [47m'(a b c)[0m, it reaches the final [47mnil[0m, which satisfies [47mendp[0m, and so 27 is returned. It is naturally consed into the emerging list as the function returns from successive recursive calls (since [47mcons[0m does not require its arguments to be lists, either). The result is an ``improper'' list, [47m(a b c . 27)[0m. You can think of [47m(app x y)[0m as building a binary tree by replacing the right-most tip of the tree [47mx[0m with the tree [47my[0m.") (acl2_strings (pages_written_especially_for_the_tours) "ACL2 Strings Strings of ACL2 characters (see [ACL2_Characters]) are written as sequences of characters delimited by ``double quotation marks'' ("). To put a double quotation mark in a string (or, any other character such as backslash or newline that seems to cause problems), escape it by preceding it with a backslash (\). The function [47m[stringp][0m {ICON} (see [A_Tiny_Warning_Sign]) recognizes strings and [47m[char][0m {ICON} (see [A_Tiny_Warning_Sign]) will fetch the nth character of a string. There are many other primitives for handling strings, such as [47m[string<][0m {ICON} (see [A_Tiny_Warning_Sign]) for comparing two strings lexicographically. We suggest you See [programming] {ICON} (see [A_Tiny_Warning_Sign]) where we list all of the primitive ACL2 functions. Alternatively, see any Common Lisp language documentation.") (acl2_symbols (pages_written_especially_for_the_tours) "ACL2 Symbols Common Lisp's symbols are a data type representing words. They are frequently regarded as atomic objects in the sense that they are not frequently broken down into their constituents. Often the only important properties of symbols is that they are not numbers, characters, strings, or lists and that two symbols are not equal if they look different (!). Examples of symbols include [47mPLUS[0m and [47mSMITH::ABC[0m. All function and variable names in ACL2 are symbols. When symbols are used as constants they must be quoted, as in [47m'PLUS[0m. The symbol [47mT[0m is commonly used as the Boolean ``true.'' The symbol [47mNIL[0m is commonly used both as the Boolean ``false'' and as the ``empty list.'' Despite sometimes being called the ``empty list'' [47mNIL[0m is a [31;1msymbol[0m not an ``empty cons.'' Unlike other symbols, [47mT[0m and [47mNIL[0m may be used as constants without quoting them. Usually, symbols are written as sequences of alphanumeric characters other than those denoting numbers. Thus, [47mA12[0m, [47m+1A[0m and [47m1+[0m are symbols but [47m+12[0m is a number. Roughly speaking, when symbols are read lower case characters are converted to upper case, so we frequently do not distinguish [47mABC[0m from [47mAbc[0m or [47mabc[0m. Click here (see [SYMBOLS]) {ICON} (see [A_Tiny_Warning_Sign]) for information about case conversion when symbols are read. However, any character can be used in a symbol, but some characters must be ``escaped'' to allow the Lisp reader to parse the sequence as a symbol. For example, [47m|Abc|[0m is a symbol whose first character is capitalized and whose remaining characters are in lower case. [47m|An odd duck|[0m is a symbol containing two #\Space characters. See any Common Lisp documentation for the syntactic rules for symbols. Technically, a symbol is a special kind of pair consisting of a package name (which is a string) and a symbol name (which is also a string). (See [symbol-package-name] {ICON} (see [A_Tiny_Warning_Sign]) and see [symbol-name] {ICON} (see [A_Tiny_Warning_Sign]).) The symbol SMITH::ABC is said to be in package "SMITH" and to have the symbol name "ABC". The symbol [47mABC[0m in package "SMITH" is generally not equal to the symbol [47mABC[0m in package "JONES". However, it is possible to ``import'' symbols from one package into another one, but in ACL2 this can only be done when the package is created. (See [defpkg] {ICON} (see [A_Tiny_Warning_Sign]).) If the [47m[current-package][0m {ICON} (see [A_Tiny_Warning_Sign]) is "SMITH" then [47mSMITH::ABC[0m may be more briefly written as just [47mABC[0m. [47m[Intern][0m {ICON} (see [A_Tiny_Warning_Sign]) ``creates'' a symbol of a given name in a given package.") (acl2_system_architecture (pages_written_especially_for_the_tours) "ACL2 System Architecture {IMAGE} (see [Rewrite_Rules_are_Generated_from_DEFTHM_Events]) {IMAGE} The user interacts with the theorem prover by giving it definitions, theorems and advice. Most often the advice is about how to store each proved theorem as a rule. Sometimes the advice is about how to prove a specific theorem. The database consists of all the rules ACL2 ``knows.'' It is possible to include in the database all of the rules in some certified file of other events. Such certified files are called [books] {ICON} (see [A_Tiny_Warning_Sign]). Interesting proofs are usually built on top of many books, some of which are written especially for that problem domain and others of which are about oft-used domains, like arithmetic or list processing. ACL2's distribution includes many books written by users. See the ``books'' link under the [31;1mLemma Libraries and Utilities[0m {ICON} (see [A_Tiny_Warning_Sign]) link of the ACL2 home page. {IMAGE} (see [Rewrite_Rules_are_Generated_from_DEFTHM_Events])") (acons (alists acl2-built-ins) "Constructor for association lists [47m(Acons key datum alist)[0m equals the result of consing the pair [47m(cons key datum)[0m to the front of the association list [47malist[0m. [47m(Acons key datum alist)[0m has a [guard] of [47m(alistp alist)[0m. [47mAcons[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<acons> (defun acons (key datum alist) (declare (xargs :guard (alistp alist))) (cons (cons key datum) alist))") (active-or-non-runep (theories) "Require a [rune] to exist, and check that it is [enable]d This variant of [47mactive-runep[0m causes an error if its argument is not a [rune]. See [active-runep].") (active-runep (theories) "Check that a [rune] exists and is [enable]d Example: (active-runep '(:rewrite left-to-right)) General Form: (active-runep rune &optional strict) where [47mrune[0m has the shape of a [rune]. This macro expands to an expression using the variables [47mens[0m and [47mstate[0m, and returns non-[47mnil[0m when the given rune exists and is [enable]d (according to the given ``enabled structure,'' [47mens[0m, and the current logical [world] of the given [47m[state][0m). See [theory-invariant] for how this macro can be of use. When the optional argument is [47mnil[0m or is omitted, then although the argument is required to have the shape of a [rune], it need not be a rune. For example, if there is no rewrite rule named [47mleft-to-right[0m, then [47m(active-runep '(:rewrite left-to-right))[0m will simply return [47mnil[0m. If instead you'd like this call to cause an error, use a non-nil optional argument or, equivalently, use [47m[active-or-non-runep][0m.") (add-binop (macros) "Associate a function name with a macro name The form [47m(add-binop macro macro-fn)[0m is an abbreviation for the form [47m(add-macro-fn macro macro-fn t)[0m. See [add-macro-fn].") (add-custom-keyword-hint (events) "Add a new custom keyword hint Examples: (add-custom-keyword-hint :my-hint (my-hint-fn val ...)) (add-custom-keyword-hint :my-hint (my-hint-fn val ...) :checker (my-hint-checker-fn val ...)) General Form: (add-custom-keyword-hint :key term1 :checker term2) where [47m:key[0m is a [47m[keywordp][0m not among the primitive keyword hints listed in [47m*hint-keywords*[0m, the [47m:checker[0m argument is optional, and [47mterm1[0m and (if supplied) [47mterm2[0m are terms with certain free-variable and signature restrictions described below. Henceforth, [47m:key[0m is treated as a custom keyword hint, e.g., the user can employ [47m:key[0m in hints to [47m[defthm][0m, such as: (defthm name ... :hints (("Subgoal *1/1'" ... :key val ...))). Custom keyword hints are complicated. To use them you must understand [47m[state][0m, multiple values (e.g., [47m[mv][0m and [47m[mv-let][0m), ACL2's notion of error triples (see [programming-with-state]), how to generate ``soft'' errors with [47m[er][0m, how to use [47m[fmt][0m-strings to control output, how to use computed hints (see [computed-hints]) and some aspects of ACL2's internal event processing. Furthermore, it is possible to implement a custom keyword hint that can make an event non-reproducible! So we recommend that these hints be developed by ACL2 experts. Basically the custom keyword feature allows the implementors and other experts to extend the hint facility without modifying the ACL2 sources. [47mTerm1[0m is called the ``generator'' term and [47mterm2[0m is called the ``checker'' term of the custom keyword hint [47m:key[0m. Together they specify the semantics of the new custom keyword hint [47m:key[0m. Roughly speaking, when a custom keyword hint is supplied by the user, as in (defthm name ... :hints (("Subgoal *1/1'" ... :my-hint val ...))). the checker term is evaluated on [47mval[0m to check that [47mval[0m is of the expected shape. Provided [47mval[0m passes the check, the generator term is used to compute a standard hint. Like computed hints, the generator of a custom keyword hint is allowed to inspect the actual [clause] on which it is being fired. Indeed, it is allowed to inspect the entire list of hints (standard and custom) supplied for that clause. Thus, in the most general case, a custom keyword hint is just a very special kind of computed hint. The generator, [47mterm1[0m, must have no free variables other than: (val keyword-alist id clause world stable-under-simplificationp hist pspv ctx state). Moreover, either [47mterm1[0m must evaluate to a single non-[stobj] value, or else it must be single-threaded in [47mstate[0m and have the standard [error-triple] output signature, [47m(mv * * state)[0m. The restrictions on the checker, [47mterm2[0m, are that it be single-threaded in [47mstate[0m, have the standard [error-triple] output signature, [47m(mv * * state)[0m, and have no free variables other than: (val world ctx state). For examples, see the community books directory [47mbooks/hints/[0m, in particular [47mbasic-tests.lisp[0m. To delete a previously added custom keyword hint, see [remove-custom-keyword-hint]. The community book [47mhints/merge-hint.lisp[0m can be useful in writing custom keyword hints. See the examples near the of the file. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded.") (add-default-hints (default-hints) "Add to the default hints Examples: (add-default-hints '((computed-hint-1 clause) (computed-hint-2 clause stable-under-simplificationp))) (add-default-hints '((computed-hint-3 id clause world)) :at-end t) Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs (see [add-default-hints!] for a corresponding non-[47m[local][0m event). General Forms: (add-default-hints lst) (add-default-hints lst :at-end flg) where [47mlst[0m is a list. Generally speaking, the elements of [47mlst[0m should be suitable for use as [47m[computed-hints][0m. This event is completely analogous to [47m[set-default-hints][0m, the difference being that [47madd-default-hints[0m appends the indicated hints to the front of the list of default hints, so that they are tried first --- or, if [47mflg[0m is supplied and evaluates to other than [47mnil[0m, at the end of the list, so that they are tried last --- rather than [31;1mreplacing[0m the default hints with the indicated hints. Each new hint is thus considered after each existing hint when both are applied to the same goal. Also See [set-default-hints], see [remove-default-hints], and see [default-hints]. Finally, note that the effects of [47mset-default-hints[0m, [47m[add-default-hints][0m, and [47m[remove-default-hints][0m are [47m[local][0m to the book in which they appear. Thus, users who include a book with such forms will not have their default hints affected by such forms. In order to export the effect of setting the default hints, use [47m[set-default-hints!][0m, [47m[add-default-hints!][0m, or [47m[remove-default-hints!][0m. For a related feature, which however is only for advanced system builders, see [override-hints].") (add-default-hints! (default-hints) "Add to the default hints non-[47m[local][0mly Please see [add-default-hints], which is the same as [47madd-default-hints![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [add-default-hints] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (add-dive-into-macro (dive-into-macros-table) "Associate [proof-builder] diving function with macro name Examples: (add-dive-into-macro cat expand-address-cat) This feature is used so that the interactive [proof-builder]'s [47mDV[0m command and numeric diving commands (e.g., [47m3[0m) will dive properly into subterms. Please see [dive-into-macros-table].") (add-global-stobj (events stobj) "Add a global [stobj] with a given name See [stobj] for background on stobjs, and see [defstobj] and [defabsstobj] for further background. We start with the General Form and an Example Form, which are followed by discussions of global stobjs and the effect of this utility. General Form: (add-global-stobj x state) where [47mx[0m evaluates to the name of a stobj that does not already have a global value, either because it was introduced by [47m[defstobj][0m or [47m[defabsstobj][0m with keyword value [47m:non-executable t[0m or because [47m[remove-global-stobj][0m was previously applied to that name. Example Form: (add-global-stobj 'st state) ; st non-global from defstobj or defabsstobj By default, [47mdefstobj[0m and [47mdefabsstobj[0m create a ``live'', mutable object for the given name that can be referenced at the top level, which we call a ``global'' stobj. This is illustrated by the following log. ACL2 !>(defstobj st fld) Summary Form: ( DEFSTOBJ ST ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) ST ACL2 !>st ; global stobj for the name, ST <st> ACL2 !>(fld st) NIL ACL2 !>(update-fld 3 st) <st> ACL2 !>(fld st) 3 ACL2 !> However, the following log shows that we can introduce a stobj without creating a global stobj, by using the keyword value [47m:non-executable t[0m. ACL2 !>(defstobj st2 fld2 :non-executable t) Summary Form: ( DEFSTOBJ ST2 ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) ST2 ACL2 !>(fld2 st2) ACL2 Error [Evaluation] in TOP-LEVEL: Unbound var ST2. Note that ST2 is a non-executable stobj. ACL2 !> The function [47madd-global-stobj[0m creates a global stobj for a given stobj name when one does not already exist. Let's continue the log started immediately above. ACL2 !>(add-global-stobj 'st2 state) ST2 ACL2 !>(fld2 st2) NIL ACL2 !>(update-fld2 3 st2) <st2> ACL2 !>(fld2 st2) 3 ACL2 !> The function [47mremove-global-stobj[0m removes the indicated global stobj. We continue the log above. ACL2 !>(remove-global-stobj 'st2 state) ST2 ACL2 !>(fld2 st2) ACL2 Error [Evaluation] in TOP-LEVEL: Unbound var ST2. Note that ST2 is a non-executable stobj. ACL2 !> If we remove a global stobj, as shown just above, and then add the corresponding global stobj, we get a fresh copy of that stobj; all previous updates are discarded. ACL2 !>(add-global-stobj 'st2 state) ST2 ACL2 !>(fld2 st2) NIL ACL2 !>") (add-include-book-dir (books-reference) "Link keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m Example Forms: ; For (include-book "foo" :dir :smith), prepend to "foo" the absolute ; directory pathname "/u/smith/": (add-include-book-dir :smith "/u/smith/") ; For (include-book "bar" :dir :util), prepend to "bar" the absolute ; directory pathname corresponding to the interpretation of "utilities/" ; with respect to the current connected-book-directory (cbd): (add-include-book-dir :util "utilities") ; For (include-book "lib/floor-mod/top" :dir :arith), prepend to ; "lib/floor-mod/top" the string "<dir>/arithmetic-5/" where "<dir>" ; is the community books directory pathname string: (add-include-book-dir :arith (:system . "arithmetic-5")) Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs. See [47m[add-include-book-dir!][0m for a corresponding non-[47m[local][0m event. General Form: (add-include-book-dir kwd dir) where [47mkwd[0m is a [47m[keywordp][0m and [47mdir[0m represents a directory: either a relative or absolute [pathname] string or a [sysfile]. If the final '[47m/[0m' is missing for the resulting directory, ACL2 will add it for you. The effect of this event is to modify the meaning of the [47m:dir[0m keyword argument of [47m[include-book][0m and [47m[ld][0m as indicated by the examples above, that is, by associating the indicated directory with the indicated keyword for purposes of the [47m:dir[0m argument. By the ``indicated directory'' we mean, when a relative pathname is supplied, the directory relative to the current connected book directory; see [cbd]. See [delete-include-book-dir] for how to undo this effect. For a keyword already associated with a directory string by a previous invocation of [47madd-include-book-dir[0m or [47m[add-include-book-dir!][0m, it is illegal to associate a different directory string until removing the existing association; see [delete-include-book-dir] (and see [delete-include-book-dir!] if the existing association was made by [47m[add-include-book-dir!][0m. If however the new directory string is identical with the existing one, which was already assigned by [47madd-include-book-dir[0m, then the new call of [47madd-include-book-dir[0m will be redundant (see [redundant-events]). See [47m[project-dir-alist][0m for another way to associate keywords with directory names, to take place only at the time ACL2 starts up. Note that a keyword bound in the [47mproject-dir-alist[0m may also be bound by [47madd-include-book-dir[0m, but only if both bindings are to the same directory. The keyword [47m:system[0m can never be redefined. It will always point to the absolute pathname of the [community-books] directory, which by default is the subdirectory [47m"books/"[0m of the directory where the ACL2 executable was built (see [include-book], in particular the discussion there of ``Books Directory''). This macro generates a [47m[table][0m event that updates the [47m[ACL2-defaults-table][0m and thus is automatically [local] to the book or [47m[encapsulate][0m event in which it occurs (and, it is thus illegal to call [47madd-include-book-dir[0m in an explicitly [47m[local][0m context). See [47m[add-include-book-dir!][0m for a corresponding non-[47m[local][0m event. As with [47m[add-include-book-dir!][0m, direct table updates are disallowed; you must use [47madd-include-book-dir[0m to add to the [47macl2-defaults-table[0m and [47m[delete-include-book-dir][0m to remove from it.") (add-include-book-dir! (books-reference) "Non-[47m[local][0mly link keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m This topic assumes familiarity with [add-include-book-dir], which has completely analogous syntax and semantics, except that [47madd-include-book-dir![0m is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [47m[add-include-book-dir][0m is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. This macro is essentially a [47m[table][0m event that updates the table [47minclude-book-dir!-table[0m, which associates keywords with absolute pathnames. However, as with [47m[add-include-book-dir][0m, direct table updates are disallowed; you must use [47madd-include-book-dir![0m to add to the table and [47m[delete-include-book-dir!][0m to remove from the table. See [47m[project-dir-alist][0m for another way to associate keywords with directory names, to take place only at the time ACL2 starts up. Note that a keyword bound in the [47mproject-dir-alist[0m may also be bound by [47madd-include-book-dir![0m, but only if both bindings are to the same directory. It is illegal to call [47madd-include-book-dir![0m in a [47m[local][0m context. (If you are tempted to do that, consider using [47m[add-include-book-dir][0m instead.) To understand this restriction, imagine a book that contains the following sequence of [events]. (add-include-book-dir! :my-dir "path/to/BAD/dir") (local (delete-include-book-dir! :my-dir)) (local (add-include-book-dir! :my-dir "path/to/GOOD/dir")) (include-book "foo" :dir :my-dir) (defthm f-def (equal (f x) x)) During the first (proof) pass of [47m[certify-book][0m, the book [47mpath/to/GOOD/dir/foo.lisp[0m will be included. But on the second pass, the book [47mpath/to/BAD/dir/foo.lisp[0m will be included. Now imagine that the ``good'' version contains the event [47m(defun f (x) x)[0m but the ``bad'' version instead contains the event [47m(defun f (x) (not x))[0m. Then we can easily prove [47mnil[0m from the theorem [47mf-def[0m! Although it is likely that [book-hash] values could catch this error at [47m[include-book][0m time, we prefer not to rely on these for soundness.") (add-invisible-fns (loop-stopper) "Make some unary functions invisible to the [loop-stopper] algorithm Examples: (add-invisible-fns binary-+ unary-- foo) (add-invisible-fns + unary-- foo) Each of the [events] above makes unary functions [47m[unary--][0m and [47mfoo[0m ``invisible'' for the purposes of applying permutative [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees. Thus, [47marg[0m and [47m(unary-- arg)[0m will be given the same weight and will be permuted so as to be adjacent. General Form: (add-invisible-fns top-fn unary-fn1 ... unary-fnk) where [47mtop-fn[0m is a function symbol and the [47munary-fni[0m are unary function symbols, or more generally, these are all macro aliases for such function symbols (see [macro-aliases-table]). For more information see [invisible-fns-table]. Also see [set-invisible-fns-table], which explains how to set the entire table in a single event, and see [remove-invisible-fns].") (add-ld-keyword-alias (pointers) "See [ld-keyword-aliases].") (add-ld-keyword-alias! (pointers) "See [ld-keyword-aliases].") (add-macro-alias (macros) "Associate a function name with a macro name Example: (add-macro-alias append binary-append) This example associates the function symbol [47m[binary-append][0m with the macro name [47m[append][0m. As a result, the name [47m[append][0m may be used as a runic designator (see [theories]) by the various theory functions. See [add-macro-fn] and [add-binop] for extensions of this utility that also affect printing. General Form: (add-macro-alias macro-name sym) where [47mmacro-name[0m is a macro name and [47msym[0m is a symbol. If [47msym[0m is a function symbol, then this event establishes [47mmacro-name[0m as a [3mmacro-alias[0m for [47msym[0m by associating [47mmacro-name[0m with [47msym[0m in the [table], [47mmacro-aliases-table[0m; see [macro-aliases-table] for detailed discussion. In particular, that discussion explains the use of macro-aliases to allow a macro name as the second argument of [47madd-macro-alias[0m, as in the example below. (defun fn (x) x) (defmacro mac1 (x) (fn x)) (defmacro mac2 (x) (list 'mac1 x)) (add-macro-alias mac1 fn); or (table macro-aliases-table 'mac1 'fn) ; The following is equivalent to (add-macro-alias mac2 fn), since ; mac1 is a macro-alias for fn by virtue of the preceding event. ; Note that the form (table macro-aliases-table 'mac2 'mac1) ; would not suffice here; that is, the in-theory event below would cause an ; error, because mac1 is not a function symbol. (add-macro-alias mac2 mac1) ; Success: (in-theory (disable mac2)) Also see [macro-aliases-table] and also see [remove-macro-alias].") (add-macro-fn (macros) "Associate a function name with a macro name Examples: (add-macro-fn append binary-append) (add-macro-fn append binary-append t) These examples each associate the function symbol [47m[binary-append][0m with the macro name [47m[append][0m. As a result, theory functions will understand that [47mappend[0m refers to [47mbinary-append[0m --- see [add-macro-alias] --- and moreover, proof output will be printed using [47mappend[0m rather than [47mbinary-append[0m. In the first case, [47m(append x (append y z))[0m is printed rather than [47m(append x y z)[0m. In the second case, right-associated arguments are printed flat: [47m(append x y z)[0m. Such right-association is considered only for binary function symbols; otherwise the optional third argument is ignored. General Forms: (add-macro-fn macro-name function-name) (add-macro-fn macro-name function-name nil) ; same as above (add-macro-fn macro-name function-name t) This is a convenient way to add an entry to [47m[macro-aliases-table][0m and at the same time extend the [47m[untrans-table][0m. As suggested by the example above, calls of a function in this table will be printed as corresponding calls of macros, with right-associated arguments printed flat in the case of a binary function symbol if the optional third argument is t. In that case, for a binary function symbol [47mfn[0m associated with macro name [47mmac[0m, then a call [47m(fn arg1 (fn arg2 (... (fn argk arg))))[0m will be displayed to the user as though the ``term'' were [47m(mac arg1 arg2 ... argk arg)[0m. For a call [47m(f a1 ... ak)[0m of a function symbol that is not binary, or the optional argument is not supplied as [47mt[0m, then the effect is simply to replace [47mf[0m by the corresponding macro symbol. See [add-macro-alias], which is invoked on the first two arguments. Also see [remove-macro-alias], see [untrans-table], and see [remove-macro-fn].") (add-match-free-override (free-variables) "Set [47m:match-free[0m value to [47m:once[0m or [47m:all[0m in existing rules Example Forms: (add-match-free-override :once t) ; Try only the first binding of free variables when relieving hypotheses ; of any rule of class :rewrite, :linear, or :forward-chaining. (add-match-free-override :all (:rewrite foo) (:rewrite bar)) ; For rewrite rules foo and bar, try all bindings of free variables when ; relieving hypotheses. (add-match-free-override :clear) ; Restore :match-free to what was originally stored for each rule (either ; :all or :once). As described elsewhere (see [free-variables]), a [rewrite], [linear], or [forward-chaining] rule may have free variables in its hypotheses, and ACL2 can be directed either to try all bindings (``[47m:all[0m'') or just the first (``[47m:once[0m'') when relieving a hypothesis, as a basis for relieving subsequent hypotheses. This direction is generally provided by specifying either [47m:match-free :once[0m or [47m:match-free :all[0m in the [47m:[0m[47m[rule-classes][0m of the rule, or by using the most recent [47m[set-match-free-default][0m event. Also see [rule-classes]. However, if a proof is going slowly, you may want to modify the behavior of some such rules so that they use only the first match for free variables in a hypothesis when relieving subsequent hypotheses, rather than backtracking and trying additional matches as necessary. (But note: [47madd-match-free-override[0m is not relevant for [type-prescription] rules.) The event [47m(add-match-free-override :once t)[0m has that effect. Or at the other extreme, perhaps you want to specify all rules as [47m:all[0m rules except for some specific exceptions. Then you can execute [47m(add-match-free-override :all t)[0m followed by, say, [47m(add-match-free-override :once (:rewrite foo) (:linear bar))[0m. General Forms: (add-match-free-override :clear) (add-match-free-override flg t) (add-match-free-override flg rune1 rune2 ... runek) where [47mflg[0m is [47m:once[0m or [47m:all[0m and the [47mrunei[0m are [47m[rune][0ms. If [47m:clear[0m is specified then all rules will have the [47m:all[0m/[47m:once[0m behavior from when they were first stored. The second general form causes all [rewrite] [linear], and [forward-chaining] rules to have the behavior specified by [47mflg[0m ([47m:all[0m or [47m:once[0m). Finally, the last of these, where runes are specified, is additive in the sense that only the indicated rules are affected; all others keep the behavior they had just before this event was executed (possible because of earlier [47madd-match-free-override[0m events). At the conclusion of this event, ACL2 prints out the list of all [47m:[0m[47m[linear][0m, [47m:[0m[47m[rewrite][0m, and [47m:[0m[47m[forward-chaining][0m runes whose rules contain free variables in hypotheses that are to be bound [47m:once[0m, except that if there are no overrides (value [47m:clear[0m was used), then [47m:clear[0m is printed. This event only affects rules that exist at the time it is executed. Future rules are not affected by the override. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It uses the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs. [3mRemarks[0m Lists of the [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, and [47m:[0m[47m[forward-chaining][0m [rune]s whose behavior was originally [47m:once[0m or [47m:all[0m are returned by the following forms, respectively. (free-var-runes :once (w state)) (free-var-runes :all (w state)) The form (match-free-override (w state)) evaluates to a pair, whose [47m[car][0m is a number used by ACL2 to determine whether a [rune] is sufficiently old to be affected by the override, and whose [47m[cdr][0m is the list of [rune]s whose behavior is specified as [47m:once[0m by [47madd-match-free-override[0m; except, if no runes have been overridden, then the keyword [47m:clear[0m is returned.") (add-nth-alias (nth-aliases-table) "Associate one symbol with another for printing of [47m[nth][0m/[47m[update-nth][0m terms Example: (add-nth-alias st0 st) This example associates the symbol [47mst0[0m with the symbol [47mst[0m for purposes of printing certain terms of the form [47m(nth n st0)[0m and [47m(update-nth n val st0)[0m. General Form: (add-nth-alias alias-name name) This is a convenient way to add an entry to [47m[nth-aliases-table][0m. See [nth-aliases-table] and also see [remove-nth-alias].") (add-override-hints (override-hints) "Add to the [override-hints] See [override-hints] for a discussion of override-hints. Here we describe how to extend the list of override-hints. Note that the effects of [47madd-override-hints[0m [events] are [local] to the [books] or [47mencapsulate[0m [events] in which they reside; see [add-override-hints!] to avoid that restriction. Also see [set-override-hints] to set a new list of override-hints to it, ignoring the present list rather than adding to it. General Forms: (add-override-hints form) (add-override-hints form :at-end t) (add-override-hints form :at-end nil) ; default for :at-end where [47mform[0m evaluates to a list of computed hint forms. The effect of this event is to extend the current list of [override-hints] by appending the result of that evaluation. The default is to append the evaluation result to the front of the current list of override-hints, but if [47m:at-end t[0m is specified, then the evaluation result is appended to the end of the current list.") (add-override-hints! (override-hints) "Add non-[local]ly to the [override-hints] [47mAdd-override-hints![0m is the same as [47m[add-override-hints][0m, except that the former is not [local] to [books] or [47m[encapsulate][0m [events] in which it occurs. See [add-override-hints]; also see [set-override-hints].") (add-suffix (pointers) "See [system-utilities].") (add-suffix-to-fn (pointers) "See [system-utilities].") (add-to-set (lists symbols acl2-built-ins) "Add a symbol to a list General Forms: (add-to-set x lst) (add-to-set x lst :test 'eql) ; same as above (eql as equality test) (add-to-set x lst :test 'eq) ; same, but eq is equality test (add-to-set x lst :test 'equal) ; same, but equal is equality test For a symbol [47mx[0m and an object [47mlst[0m, [47m(add-to-set-eq x lst)[0m is the result of [47m[cons][0ming [47mx[0m on to the front of [47mlst[0m, unless [47mx[0m is already a [47m[member][0m of [47mlst[0m, in which case the result is [47mlst[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements of [47mlst[0m. The [guard] for a call of [47madd-to-set[0m depends on the test. In all cases, the second argument must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47madd-to-set[0m and its variants: [47m(add-to-set-eq x lst)[0m is equivalent to [47m(add-to-set x lst :test 'eq)[0m; [47m(add-to-set-equal x lst)[0m is equivalent to [47m(add-to-set x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47madd-to-set-equal[0m.") (add-to-set-eq (pointers) "See [add-to-set].") (add-to-set-eql (pointers) "See [add-to-set].") (add-to-set-equal (pointers) "See [add-to-set].") (adjust-ld-history (pointers) "See [ld-history].") (advanced-features (acl2-tutorial programming) "Some advanced features of ACL2 Maybe you've been using ACL2 for awhile, and you wonder if there are lesser-known features that you might find useful. Then this topic is for you. We present below a ``laundry list'' of some such features, with brief descriptions and links to [documentation] topics. Although the list below is long, it is not intended to be complete, and indeed some topics have been deliberately excluded. Some have fallen out of use, perhaps for good reason, such as [obdd]. Others are already likely to be discovered when needed, such as [47m[getenv$][0m and perhaps [47m[double-rewrite][0m. Some topics are referenced by documentation for others in the list, such as [47m[mbt][0m, which is referenced by [47m[mbe][0m. Some utilities such as [47m[pstack][0m and [47m[verbose-pstack][0m seem too low-level to be worthy of inclusion below. For an extensive introduction to using the prover, which may include some aspects new to you, see [introduction-to-the-theorem-prover]. A shorter topic contains highlights for efficient prover usage: see [tips]. Also see [ACL2-sedan] for an extension of ACL2 (written by others), ACL2s, that includes an Eclipse-based interface, more powerful and automatic termination reasoning, and other features. We now move on to the list. Top-level commands and utilities: * See [a!] and see [p!] to abort or pop. * See [ACL2-customization] for initial commands to run at startup. * See [keyword-commands] for how keyword commands are processed. * See [ld] for many ways to control the top-level loop. * See [compilation] for a discussion of [47mset-compiler-enabled[0m and other compiler-related utilities. * For useful reader macros `[47m#![0m', `[47m#.[0m', and `[47m#u[0m', see [sharp-bang-reader], see [sharp-dot-reader], and see [sharp-u-reader]. * To save and use an ACL2 executable, see [ACL2-as-standalone-program] and see [save-exec]. * For utilities related to timing, see [time$], see [with-prover-time-limit], see [with-prover-step-limit], and see [set-prover-step-limit]. * To query and manage the database, see [history] (which discusses many useful utilities, such as [47m:[0m[47m[pbt][0m and [47m:[0m[47m[pl][0m), and see [dead-events]. * See [add-include-book-dir], [add-include-book-dir!], and [project-dir-alist] for linking keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m. * See [rebuild] for a fast way to load a file without waiting for proofs. * For parallel certification, see [books-certification] for use of the [47m-j[0m option of `make'; also see [provisional-certification]. Some relatively less common events * See [reset-prehistory] to reset the prehistory. * See [assert-event] to assert that a given form returns a non-nil value. * See [defattach] to execute constrained functions using corresponding attached functions. * See [defun-sk] to define a function whose body has an outermost quantifier. * See [defchoose] to define a Skolem (witnessing) function. * See [set-verify-guards-eagerness] to specify when [guard] verification is tried by default. Output and its control (see [io] for additional information) * See [with-output] to suppress or turn on specified output for an event. * See [evisc-table] for support for abbreviated output. * See [nth-aliases-table] for a table used to associate names for [47m[nth][0m/[47m[update-nth][0m printing. * See [output-to-file] to redirect output to a file. * See [print-control] to control ACL2 printing. * See [set-evisc-tuple] to control suppression of details when printing. * See [set-inhibit-output-lst] to control output by type. * See [set-iprint] to allow abbreviated output to be read back in. * See [set-print-base-radix] (also [set-print-base] and [set-print-radix]) to control the radix in which numbers are printed. * See [set-print-case] to control whether symbols are printed in upper case or in lower case. On proving termination for definitions: * See [ordinals] for a discussion of ordinals in ACL2. * See [ruler-extenders] for a control on ACL2's termination and induction analyses. * See [induction-coarse-v-fine-grained] for a discussion of how a well-chosen setting for [ruler-extenders] can improve an induction scheme, especially for a function containing [47m[let][0m and [47m[let*][0m bindings that contain conditional recursive calls. * See [set-well-founded-relation] to set the default well-founded relation for termination analysis. * See [ACL2-sedan] for a related tool that provides extra automation for termination proofs. Proof debugging and output control: * See [accumulated-persistence] to get statistics on which runes are being tried. * See [add-macro-fn] and see [add-macro-alias] to associate a function name with a macro name. * See [break-rewrite] for how to monitor rewrite rules. * See [dmr] for dynamic monitoring of rewriting and other prover activity. * See [forward-chaining-reports] to see reports about the forward chaining process. * See [guard-debug] and [measure-debug] to generate markers to indicate sources of [guard] and termination proof obligations. * See [proof-builder] for support for low-level interaction. * See [redo-flat] for redo on failure of a [47m[progn][0m, [47m[encapsulate][0m, or [47m[certify-book][0m. * See [set-gag-mode] and see [pso] to abbreviate or restore proof output. * See [set-inhibit-output-lst], see [set-inhibit-warnings], see [set-inhibit-er], and see [set-inhibited-summary-types] to inhibit various types of output. * See [set-raw-proof-format] to make proof output display lists of [rune]s and, optionally, clausal form for goals. * See [set-raw-warning-format] to make some warnings display in a ``raw'' s-expression format. * See [skip-proofs] to skip proofs for a given form. * See [with-brr-data] for finding the source of a term in prover output. Program debugging: * See [break$] to cause an immediate Lisp break. * See [break-on-error] to break when encountering a hard or soft error caused by ACL2. * See [disassemble$] to disassemble a function. * See [print-gv] to print a form whose evaluation caused a guard violation. * See [profile] to turn on profiling for one function. * See [trace$] and see [open-trace-file] to [trace] function evaluations, possibly sending trace output to a file. * See [wet] to evaluate a form and print a subsequent error trace. Programming and evaluation idioms, support, utilities (also see [programming] for more utilities, e.g., [47m[random$][0m). * See [arrays] and See [defstobj] for introductions to ACL2 arrays and single-threaded objects (stobjs), respectively, each of which provides efficient destructive operations in an applicative setting. Also see [with-local-stobj] for a way to create local stobjs. * See [assert$] to cause a hard error if the given test is false. * See [canonical-pathname] to obtain the true absolute filename, with soft links resolved. * See [case-match] for a utility providing pattern matching and destructuring. * See [defpun] to define a tail-recursive function symbol. * See [ec-call] to execute a call in the ACL2 logic instead of raw Lisp. * See [er] to print an error message and ``cause an error''. * See [flet] and [macrolet] to provide local binding of function and macro names. * See [gc$] to invoke the garbage collector. * See [mbe] to attach code for execution. * See [mv-list] to convert a [multiple-value] result to a single-value list. * See [mv?] to return one or more values. * For non-executable code, see [defun-nx] and see [non-exec]. * See [prog2$] and see [progn$] to execute two or more forms and return the value of the last one. * See [programming-with-state] for how to program using the von Neumannesque ACL2 [state] object. * See [top-level] to evaluate a top-level form as a function body. * See [with-guard-checking] to suppress or enable guard-checking for a form. * For ways to fake access to the state see [wormhole], see [with-local-state], see [cw], see [cw!], see [printing-to-strings], see [observation-cw], and (dangerous!) see [with-live-state]. Connecting with the underlying host Lisp, and doing other evil: * See [defttag] to introduce a trust tag (ttag). * See [defmacro-last] to define a macro that returns its last argument, but with side effects. * See [progn!] to evaluate forms that are not necessarily [events]. * See [return-last] to return the last argument, perhaps with side effects. * See [set-raw-mode] to enter or exit ``raw mode,'' a raw Lisp environment. * See [sys-call], [sys-call+], and [sys-call*] to make a system call to the host operating system. Macros and related utilities: * See [defabbrev] for a convenient form of macro definition for simple expansions. * See [macro-args] for the formals list of a macro definition (see [defmacro]). * See [make-event] for a sort of extension of [47m[defmacro][0m that allows access to the [state], by evaluating (expanding) a given form and then evaluate the result of that expansion. * See [trans], see [trans!], and see [trans1] to print the macroexpansion of a form. Additional capabilities: * See [hons-and-memoization] for a discussion of the [hons-enabled] features providing hash cons, function memoization, and applicative hash tables. In particular, see [memoize] for efficient function memoization and see [profile] for profiling. * See [real] for ACL2(r), which supports the real numbers. * See [parallelism] for ACL2(p), which supports parallel evaluation and proof. Database control and query: * See [disabledp] to determine whether a given name or rune is disabled. * For redefinition support see [redef], see [redef!], see [redef+], see [redef-], and see [redefined-names]. * See [table] for user-managed tables. * See [guard-formula-utilities] for how to view a guard proof obligation without doing the proof. Prover control * For congruence-based reasoning see [defcong], see [congruence], see [equivalence], see [defequiv], and see [defrefinement]. * For meta rules and [clause] processors see [meta], see [defevaluator], see [clause-processor], see [define-trusted-clause-processor] (for connecting with external tools, such as SAT solvers), and See [extended-metafunctions] (for [state] and context-sensitive metafunctions). * For theory control, see [theories] for detailed information, but in particular see [deftheory], see [theory-functions], see [in-arithmetic-theory] (and see [non-linear-arithmetic]), and see [theory-invariant]. * See [hints] for a complete list of prover hints, including some of the more obscure ones such as [47m:restrict[0m, [47m:[0m[47m[clause-processor][0m, [47m:nonlinearp[0m, [47m:backchain-limit-rw[0m, [47m:reorder[0m, and [47m:backtrack[0m. Also see [hints-and-the-waterfall] for an explanation of how hints interact with the ACL2 proof process. For other topics related to hints, see [override-hints], see [add-custom-keyword-hint], see [default-hints], and see [computed-hints] and [using-computed-hints]. * See [bind-free] to bind [free-variables] of a [rewrite] or [linear] rule. * See [case-split] for a utility like [47m[force][0m that immediately splits the top-level goal on the indicated hypothesis. * See [case-split-limitations] for a way to the number of cases produced at once * See [default-backchain-limit] to specify the backchain limit for a rule. * See [force] for an identity function used to force a hypothesis. * See [otf-flg] for a way to push more than one initial subgoal for induction. * See [rule-classes] to add various kinds of rules to the database, including more unusual sorts such as [47m:[0m[47m[built-in-clause][0m rules and [47m:[0m[47m[induction][0m rules. * See [set-backchain-limit] to set the backchain-limit used by the type-set and rewriting mechanisms. * See [set-body] to set an alternate definition body for [47m:expand[0m [hints]. * See [set-rewrite-stack-limit] to set the [rewrite] stack depth used by the rewriter. * See [syntaxp] to attach a heuristic filter on a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[meta][0m, or [47m:[0m[47m[linear][0m rule. Subtopics [Invariant-risk] Potential slowdown for [program]-mode updates to [stobj]s or [arrays] [Program-wrapper] Avoiding expensive [guard] checks using [program]-mode functions [Set-check-invariant-risk] Affect certain [program]-mode updates to [stobj]s or [arrays] [Set-duplicate-keys-action] Control action for macro calls with duplicate keyword arguments [Set-register-invariant-risk] Avoid [invariant-risk] checking for specified functions") (alist-keys-subsetp (alists acl2-built-ins) "Check that all keys of the alist belong to a given set The call [47m(alist-keys-subsetp alist keys)[0m returns [47mt[0m when each key of the given alist belongs to the given list of keys; else it returns [47mnil[0m. This is Boolean-equivalent to [47m(subsetp-eq (strip-cars alist) keys)[0m, but it avoids consing up the keys of [47malist[0m.") (alist-to-doublets (alists acl2-built-ins) "Convert an alist to a list of two-element lists The call [47m(alist-to-doublets alist)[0m returns the result of replacing each pair [47m(x . y)[0m in the given alist by the two-element list [47m(x y)[0m. The order is preserved, i.e., the following is a theorem. (implies (and (natp i) (< i (len alist))) (equal (nth i (alist-to-doublets alist)) (let ((pair (nth i alist))) (list (car pair) (cdr pair)))))") (alistp (alists acl2-built-ins) "Recognizer for association lists [47m(alistp x)[0m is true if and only if [47mx[0m is a list of [47m[cons][0m pairs. [47m(alistp x)[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<alistp> (defun alistp (l) (declare (xargs :guard t)) (cond ((atom l) (eq l nil)) (t (and (consp (car l)) (alistp (cdr l))))))") (alists (programming) "Operations on association lists, which bind keys to values. Subtopics [Acons] Constructor for association lists [Alist-keys-subsetp] Check that all keys of the alist belong to a given set [Alist-to-doublets] Convert an alist to a list of two-element lists [Alistp] Recognizer for association lists [Assoc] Look up key in association list [Assoc-string-equal] Look up key, a string, in association list [Character-alistp] Recognizer for association lists with characters as keys [Delete-assoc] Deprecated version of [remove1-assoc] [Eqlable-alistp] Recognizer for a true list of pairs whose [47m[car][0ms are suitable for [47m[eql][0m [Fast-alists] Alists with hidden hash tables for faster execution [Pairlis] See [pairlis$] [Pairlis$] Zipper together two lists [Pairlis-x1] Cons a given element to each member of a list [Pairlis-x2] Cons each element of a list with a given element [Put-assoc] Modify an association list by associating a value with a key [R-eqlable-alistp] Recognizer for a true list of pairs whose [47m[cdr][0ms are suitable for [47m[eql][0m [R-symbol-alistp] Recognizer for association lists with symbols as values [Rassoc] Look up value in association list [Remove-assoc] Remove all pairs with a given key from an association list [Remove1-assoc] Remove the first pair with a given key from an association list [String-alistp] Recognizer for association lists with strings as keys [Strip-cars] Collect up all first components of pairs in a list [Strip-cdrs] Collect up all second components of pairs in a list [Sublis] Substitute an alist into a tree [Symbol-alistp] Recognizer for association lists with symbols as keys") (all-attachments (pointers) "See [system-utilities].") (all-calls (pointers) "See [system-utilities].") (all-fnnames (pointers) "See [system-utilities].") (all-fnnames-lst (pointers) "See [system-utilities].") (all-fnnames1 (pointers) "See [system-utilities].") (all-vars (pointers) "See [system-utilities].") (allegro-cl (obtaining-common-lisp) "Allegro Common Lisp as a host for ACL2 {Allegro Common Lisp | https://franz.com/products/allegro-common-lisp/} (Allegro CL) is one of the Common Lisp implementations upon which an ACL2 executable can be built (see [obtaining-common-lisp]). But here, we discuss a concern. Although testing is ongoing for ACL2 built upon Allegro CL, the version used has been Allegro CL 10.1 since 2017. What's more, in September 2025, for an ACL2 executable built with host Lisp Allegro CL, the use of ``[47mmake regression[0m'' resulted in four books (in the [community-books]) that failed to certify. We discuss those failures in the ``[31;1mDetails[0m'' section below. These failures may suggest that Allegro CL, at least for its Version 10.1, does not correctly support the Common Lisp language, or at least there is problematic ACL2 code specific to Allegro CL. In practice we don't expect a lot of problems when using ACL2 built on Allegro CL. However, since Allegro CL is relatively slow compared to several other Common Lisp implementations that can host ACL2 --- SBCL, CCL, LispWorks, and GCL --- those failures suggest that Allegro CL might not be a good choice for ACL2 users. Details Here are details regarding the four certification failures under [47mbooks/[0m that are referenced above. [31;1mThese details are quite technical and probably only of interest to system implementors.[0m * [47mkestrel/c/syntax/validator.lisp[0m The following error from the corresponding [47mvalidator.cert.out[0m file is very surprising, since the [47m[defrec][0m form for [47mACL2::CLAUSE-PROCESSOR-HINT[0m has a ``cheap'' flag of [47mnil[0m, so the same error can be expected to show up regardless of the host Lisp --- yet as of this writing (in September 2025) it seems not to have shown up for a long time, if ever. HARD ACL2 ERROR in ACL2::RECORD-ERROR: An attempt was made to treat (49683 :TYPE-PRESCRIPTION BLOCK-ITEM-TYPES) as a record of type ACL2::CLAUSE-PROCESSOR-HINT. There were other errors like that one as well. So for that same ACL2 version (ACL2 git hash fe29908c4589c1de3b41d6c98cc8bec012c7eba3), the same book and the books that (recursively) support it were certified using a safety-3 ACL2 executable built on CCL. The book certified without any ``HARD ACL2 ERROR''. This suggests that the problem is likely restricted to runs using Allegro CL. However, that book allows some trust tags (in file [47mcert.acl2[0m in that directory), so perhaps there are shenanigans that somehow exonerate the Allegro CL build of ACL2. But the last failure discussed below does not involve trust tags. * [47mkestrel/axe/examples/aes-blast.lisp[0m [47mkestrel/axe/examples/aes-blast-boolean.lisp[0m These two report errors (in their [47m.cert.out[0m files) that involve using the [serialize] capability to write the [47m.cert[0m file. But [47mcert.acl2[0m in that directory allows trust tags, which could be relevant. Note that serialize errors may be very difficult to debug. A second certification was tried on the second of these (picked arbitrarily) in case this was just a weird glitch. However, a similar error occurred (though with a slightly different backtrace). * [47mprojects/aleo/vm/circuits/axe/blake2s-proof2.lisp[0m This one shows a backtrace that includes the following form. (RATIONALP 8444461749428370424248824938781546531375899335154063827935233455916872368129) That shouldn't cause an error, but apparently it did. Maybe the image was already corrupted. Submitting that form in a fresh session produced no error. As with the first example, a safety-3 CCL-based certification (of this book and all supporting books, recursively) produced no errors. But unlike the first example, this book does not allow trust tags. This example thus provides strong evidence that Allegro CL is not a great choice for hosting ACL2.") (allocate-fixnum-range (numbers acl2-built-ins) "Set aside fixnums in GCL [47m(Allocate-fixnum-range fixnum-lo fixnum-hi)[0m causes Gnu Common Lisp (GCL), versions preceding 2.7, to create a persistent table for the integers between [47mfixnum-lo[0m and [47mfixnum-hi[0m (both bounds inclusive). This table is referenced first when any integer is boxed and the existing box in the table is used if the integer is in bounds. This can speed up GCL (again, for versions preceding 2.7) considerably by avoiding wasteful fixnum boxing. Here, [47mfixnum-lo[0m and [47mfixnum-hi[0m should be fixnums. On 32-bit machines it would be good for them to be of type [47m(signed-byte 30)[0m, with [47mfixnum-lo <= fixnum-hi[0m. When this function is executed in a Lisp implementation other than a GCL version preceding 2.7, it has no side effect other than to print a message. This function always returns [47mnil[0m. In GCL versions starting with 2.7.0, allocation for the table would generally be a no-op other than to waste space, which is why [47mallocate-fixnum-range[0m is a no-op for those versions.") (alpha-char-p (characters acl2-built-ins) "Recognizer for alphabetic characters [47m(Alpha-char-p x)[0m is true for a character [47mx[0m if and only if [47mx[0m is alphabetic, i.e., one of the [characters] [47m#\a[0m, [47m#\b[0m, ..., [47m#\z[0m, [47m#\A[0m, [47m#\B[0m, ..., [47m#\Z[0m. The [guard] for [47malpha-char-p[0m states that its argument is a character. [47mAlpha-char-p[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<alpha-char-p> (defun alpha-char-p (x) (declare (xargs :guard (characterp x))) (cond ((standard-char-p x) (and (member x '(#\a #\b #\c #\d #\e #\f #\g #\h #\i #\j #\k #\l #\m #\n #\o #\p #\q #\r #\s #\t #\u #\v #\w #\x #\y #\z #\A #\B #\C #\D #\E #\F #\G #\H #\I #\J #\K #\L #\M #\N #\O #\P #\Q #\R #\S #\T #\U #\V #\W #\X #\Y #\Z)) t)) (t (alpha-char-p-non-standard x))))") (alphorder (<< acl2-built-ins) "Total order on atoms [47mAlphorder[0m is a non-strict total order, a ``less than or equal,'' on atoms. By ``non-strict total order'' we mean a function that always returns [47mt[0m or [47mnil[0m and satisfies the following properties. * Antisymmetry: [47mXrY & YrX -> X=Y[0m * Transitivity: [47mXrY & YrZ -> XrZ[0m * Trichotomy: [47mXrY v YrX[0m Also see [lexorder], which extends [47malphorder[0m to all objects. [47m(Alphorder x y)[0m has a guard of [47m(and (atom x) (atom y))[0m. Within a single type: rationals are compared arithmetically, complex rationals are compared lexicographically, characters are compared via their char-codes, and strings and symbols are compared with alphabetic ordering. Across types, rationals come before complexes, complexes come before characters, characters before strings, and strings before symbols. We also allow for ``bad atoms,'' i.e., atoms that are not legal Lisp objects but make sense in the ACL2 logic; these come at the end, after symbols. [31;1mFunction: [0m<alphorder> (defun alphorder (x y) (declare (xargs :guard (and (atom x) (atom y)))) (cond ((real/rationalp x) (cond ((real/rationalp y) (<= x y)) (t t))) ((real/rationalp y) nil) ((complex/complex-rationalp x) (cond ((complex/complex-rationalp y) (or (< (realpart x) (realpart y)) (and (= (realpart x) (realpart y)) (<= (imagpart x) (imagpart y))))) (t t))) ((complex/complex-rationalp y) nil) ((characterp x) (cond ((characterp y) (<= (char-code x) (char-code y))) (t t))) ((characterp y) nil) ((stringp x) (cond ((stringp y) (and (string<= x y) t)) (t t))) ((stringp y) nil) (t (cond ((symbolp x) (cond ((symbolp y) (not (symbol< y x))) (t t))) ((symbolp y) nil) (t (bad-atom<= x y))))))") (alternative-introduction (acl2-tutorial) "Introduction to ACL2 This section contains introductory material on ACL2 including what ACL2 is, how to get started using the system, how to read the output, and other introductory topics. It was written almost entirely by Bill Young of Computational Logic, Inc. You might also find CLI Technical Report 101 helpful, especially if you are familiar with Nqthm. If you would like more familiarity with Nqthm, we suggest CLI Technical Report 100. [3mOVERVIEW[0m ACL2 is an automated reasoning system developed (for the first 9 years) at Computational Logic, Inc. and (from January, 1997) at the University of Texas at Austin. It is the successor to the Nqthm (or Boyer-Moore) logic and proof system and its Pc-Nqthm interactive enhancement. The acronym ACL2 actually stands for ``A Computational Logic for Applicative Common Lisp''. This title suggests several distinct but related aspects of ACL2. We assume that readers of the ACL2 [documentation] have at least a very slight familiarity with some Lisp-like language. We will address the issue of prerequisites further, in ``ABOUT THIS TUTORIAL'' below. As a [31;1mlogic[0m, ACL2 is a formal system with rigorously defined syntax and semantics. In mathematical parlance, the ACL2 logic is a first-order logic of total recursive functions providing mathematical induction on the ordinals up to epsilon-0 and two extension principles: one for recursive definition and one for constrained introduction of new function symbols, here called encapsulation. The syntax of ACL2 is that of Common Lisp; ACL2 specifications are ``also'' Common Lisp programs in a way that we will make clear later. In less formal language, the ACL2 logic is an integrated collection of rules for defining (or axiomatizing) recursive functions, stating properties of those functions, and rigorously establishing those properties. Each of these activities is mechanically supported. As a [31;1mspecification language[0m, ACL2 supports modeling of systems of various kinds. An ACL2 function can equally be used to express purely formal relationships among mathematical entities, to describe algorithms, or to capture the intended behavior of digital systems. For digital systems, an ACL2 specification is a mathematical [31;1mmodel[0m that is intended to formalize relevant aspects of system behavior. Just as physics allows us to model the behavior of continuous physical systems, ACL2 allows us to model digital systems, including many with physical realizations such as computer hardware. As early as the 1930's Church, Kleene, Turing and others established that recursive functions provide an expressive formalism for modeling digital computation. Digital computation should be understood in a broad sense, covering a wide variety of activities including almost any systematic or algorithmic activity, or activity that can be reasonably approximated in that way. This ranges from the behavior of a digital circuit to the behavior of a programming language compiler to the behavior of a controller for a physical system (as long as the system can be adequately modeled discretely). All of these have been modeled using ACL2 or its predecessor Nqthm. ACL2 is a [31;1mcomputational[0m logic in at least three distinct senses. First, the theory of recursive functions is often considered the mathematics of computation. Church conjectured that any ``effective computation'' can be modeled as a recursive function. Thus, ACL2 provides an expressive language for modeling digital systems. Second, many ACL2 specifications are executable. In fact, recursive functions written in ACL2 [31;1mare[0m Common Lisp functions that can be submitted to any compliant Common Lisp compiler and executed (in an environment where suitable ACL2-specific macros and functions are defined). Third, ACL2 is computational in the sense that calculation is heavily integrated into the reasoning process. Thus, an expression with explicit constant values but no free variables can be simplified by calculation rather than by complex logical manipulations. ACL2 is a powerful, automated [31;1mtheorem prover[0m or proof checker. This means that a competent user can utilize the ACL2 system to discover proofs of theorems stated in the ACL2 logic or to check previously discovered proofs. The basic deductive steps in an ACL2-checked proof are often quite large, due to the sophisticated combination of decision procedures, conditional rewriting, mathematical and structural induction, propositional simplification, and complex heuristics to orchestrate the interactions of these capabilities. Unlike some automated proof systems, ACL2 does not produce a formal proof. However, we believe that if ACL2 certifies the ``theoremhood'' of a given conjecture, then such a formal proof exists and, therefore, the theorem is valid. The ultimate result of an ACL2 proof session is a collection of ``[events],'' possibly grouped into ``[books],'' that can be replayed in ACL2. Therefore, a proof can be independently validated by any ACL2 user. ACL2 may be used in purely automated mode in the shallow sense that conjectures are submitted to the prover and the user does not interact with the proof attempt (except possibly to stop it) until the proof succeeds or fails. However, any non-trivial proof attempt is actually interactive, since successful proof ``[events]'' influence the subsequent behavior of the prover. For example, proving a lemma may introduce a rule that subsequently is used automatically by the prover. Thus, any realistic proof attempt, even in ``automatic'' mode, is really an interactive dialogue with the prover to craft a sequence of [events] building an appropriate theory and proof rules leading up to the proof of the desired result. Also, ACL2 supports annotating a theorem with ``[hints]'' designed to guide the proof attempt. By supplying appropriate [hints], the user can suggest proof strategies that the prover would not discover automatically. There is a ``[proof-tree]'' facility (see [proof-tree]) that allows the user to [monitor] the progress and structure of a proof attempt in real-time. Exploring failed proof attempts is actually where heavy-duty ACL2 users spend most of their time. ACL2 can also be used in a more explicitly interactive mode. The interactive [proof-builder] subsystem of ACL2 allows exploration of a proof on a fairly low level including expanding calls of selected function symbols, invoking specific [rewrite] rules, and selectively navigating around the proof. This facility can be used to gain sufficient insight into the proof to construct an automatic version, or to generate a detailed interactive-style proof that can be replayed in batch mode. Because ACL2 is all of these things --- computational logic, specification language, [programming] system, and theorem prover --- it is more than the sum of its parts. The careful integration of these diverse aspects has produced a versatile automated reasoning system suitable for building highly reliable digital systems. In the remainder of this tutorial, we will illustrate some simple uses of this automated reasoning system. [3mABOUT THIS TUTORIAL[0m ACL2 is a complex system with a vast array of features, bells and whistles. However, it is possible to perform productive work with the system using only a small portion of the available functionality. The goals of this tutorial are to: familiarize the new user with the most basic features of and modes of interaction with ACL2; familiarize her with the form of output of the system; and work through a graduated series of examples. The more knowledge the user brings to this system, the easier it will be to become proficient. On one extreme: the [31;1mideal[0m user of ACL2 is an expert Common Lisp programmer, has deep understanding of automated reasoning, and is intimately familiar with the earlier Nqthm system. Such ideal users are unlikely to need this tutorial. However, without some background knowledge, the beginning user is likely to become extremely confused and frustrated by this system. We suggest that a new user of ACL2 should: (a) have a little familiarity with Lisp, including basic Lisp programming and prefix notation (a Lisp reference manual such as Guy Steele's ``Common Lisp: The Language'' is also helpful); (b) be convinced of the utility of formal modeling; and (c) be willing to gain familiarity with basic automated theorem proving topics such as rewriting and algebraic simplification. We will not assume any deep familiarity with Nqthm (the so-called ``Boyer-Moore Theorem Prover''), though the book ``A Computational Logic Handbook'' by Boyer and Moore (Academic Press, 1988) is an extremely useful reference for many of the topics required to become a competent ACL2 user. We'll refer to it as ACLH below. As we said in the introduction, ACL2 has various facets. For example, it can be used as a Common Lisp [programming] system to construct application programs. In fact, the ACL2 system itself is a large Common Lisp program constructed almost entirely within ACL2. Another use of ACL2 is as a specification and modeling tool. That is the aspect we will concentrate on in the remainder of this tutorial. [3mGETTING STARTED[0m This section is an abridged version of what's available elsewhere; feel free to see [startup] for more details. How you start ACL2 will be system dependent, but you'll probably type something like ``acl2'' at your operating system prompt. Consult your system administrator for details. When you start up ACL2, you'll probably find yourself inside the ACL2 [command] loop, as indicated by the following [prompt]. ACL2 !> If not, you should type [47m(LP)[0m. See [lp], which has a lot more information about the ACL2 [command] loop. There are two ``modes'' for using ACL2, [47m:[0m[47m[logic][0m and [47m:[0m[47m[program][0m. When you begin ACL2, you will ordinarily be in the [47m:[0m[47m[logic][0m mode. This means that any new function defined is not only executable but also is axiomatically defined in the ACL2 logic. (See [defun-mode] and see [default-defun-mode].) Roughly speaking, [47m:[0m[47m[program][0m mode is available for using ACL2 as a [programming] language without some of the logical burdens necessary for formal reasoning. In this tutorial we will assume that we always remain in [47m:[0m[47m[logic][0m mode and that our purpose is to write formal models of digital systems and to reason about them. Now, within the ACL2 [command] loop you can carry out various kinds of activities, including the following. (We'll see examples later of many of these.) define new functions (see [defun]); execute functions on concrete data; pose and attempt to prove conjectures about previously defined functions (see [defthm]); query the ACL2 ``[world]'' or database (e.g., see [pe]); and numerous other things. In addition, there is extensive on-line [documentation], of which this tutorial introduction is a part. [3mINTERACTING WITH ACL2[0m The standard means of interacting with ACL2 is to submit a sequence of forms for processing by the ACL2 system. These forms are checked for syntactic and semantic acceptability and appropriately processed by the system. These forms can be typed directly at the ACL2 [prompt]. However, most successful ACL2 users prefer to do their work using the Emacs text editor, maintaining an Emacs ``working'' buffer in which forms are edited. Those forms are then copied to the ACL2 interaction buffer, which is often the [47m"*shell*"[0m buffer. In some cases, processing succeeds and makes some change to the ACL2 ``logical [world],'' which affects the processing of subsequent forms. How can this processing fail? For example, a proposed theorem will be rejected unless all function symbols mentioned have been previously defined. Also the ability of ACL2 to discover the proof of a theorem may depend on the user previously having proved other theorems. Thus, the order in which forms are submitted to ACL2 is quite important. Maintaining forms in an appropriate order in your working buffer will be helpful for re-playing the proof later. One of the most common [events] in constructing a model is introducing new functions. New functions are usually introduced using the [47m[defun][0m form; we'll encounter some exceptions later. Proposed function definitions are checked to make sure that they are syntactically and semantically acceptable (e.g., that all mentioned functions have been previously defined) and, for recursive functions, that their recursive calls [31;1mterminate[0m. A recursive function definition is guaranteed to terminate if there is some some ``measure'' of the arguments and a ``well-founded'' ordering such that the arguments to the function get smaller in each recursive call. See [well-founded-relation-rule]. For example, suppose that we need a function that will append two lists together. (We already have one in the ACL2 [47m[append][0m function; but suppose perversely that we decide to define our own.) Suppose we submit the following definition (you should do so as well and study the system output): (defun my-app (x y) (if (atom x) y (cons (car x) (my-app x y)))) The system responds with the following message: ACL2 Error in ( DEFUN MY-APP ...): No :MEASURE was supplied with the definition of MY-APP. Our heuristics for guessing one have not made any suggestions. No argument of the function is tested along every branch and occurs as a proper subterm at the same argument position in every recursive call. You must specify a :MEASURE. See :DOC defun. This means that the system could not find an expression involving the formal parameters [47mx[0m and [47my[0m that decreases under some well-founded order in every recursive call (there is only one such call). It should be clear that there is no such measure in this case because the only recursive call doesn't change the arguments at all. The definition is obviously flawed; if it were accepted and executed it would loop forever. Notice that a definition that is rejected is not stored in the system database; there is no need to take any action to have it ``thrown away.'' Let's try again with the correct definition. The interaction now looks like (we're also putting in the ACL2 [prompt]; you don't type that): ACL2 !>(defun my-app (x y) (if (atom x) y (cons (car x) (my-app (cdr x) y)))) The admission of MY-APP is trivial, using the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). We observe that the type of MY-APP is described by the theorem (OR (CONSP (MY-APP X Y)) (EQUAL (MY-APP X Y) Y)). We used primitive type reasoning. Summary Form: ( DEFUN MY-APP ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: None Time: 0.07 seconds (prove: 0.00, print: 0.00, other: 0.07) MY-APP Notice that this time the function definition was accepted. We didn't have to supply a measure explicitly; the system inferred one from the form of the definition. On complex functions it may be necessary to supply a measure explicitly. (See [xargs].) The system output provides several pieces of information. The revised definition is acceptable. The system realized that there is a particular measure (namely, [47m(acl2-count x)[0m) and a well-founded relation ([47mo<[0m) under which the arguments of [47mmy-app[0m get smaller in recursion. Actually, the theorem prover proved several theorems to admit [47mmy-app[0m. The main one was that when [47m(atom x)[0m is false the [47macl2-count[0m of [47m(cdr x)[0m is less than (in the [47mo<[0m sense) the [47macl2-count[0m of [47mx[0m. [47m[Acl2-count][0m is the most commonly used measure of the ``size`` of an ACL2 object. [47m[o<][0m is the ordering relation on ordinals less than epsilon-0. On the natural numbers it is just ordinary ``<''. The observation printed about ``the type of MY-APP'' means that calls of the function [47mmy-app[0m will always return a value that is either a [cons] pair or is equal to the second parameter. The [summary] provides information about which previously introduced definitions and lemmas were used in this proof, about some notable things to watch out for (the Warnings), and about how long this event took to process. Usually, it's not important to read this information. However, it is a good habit to scan it briefly to see if the type information is surprising to you or if there are Warnings. We'll see an example of them later. After a function is accepted, it is stored in the database and available for use in other function definitions or lemmas. To see the definition of any function use the [47m:[0m[47m[pe][0m command (see [pe]). For example, ACL2 !>:pe my-app L 73:x(DEFUN MY-APP (X Y) (IF (ATOM X) Y (CONS (CAR X) (MY-APP (CDR X) Y)))) This displays the definition along with some other relevant information. In this case, we know that this definition was processed in [47m:[0m[47m[logic][0m mode (the ``[47mL[0m'') and was the 73rd [command] processed in the current session. We can also try out our newly defined function on some sample data. To do that, just submit a form to be evaluated to ACL2. For example, ACL2 !>(my-app '(0 1 2) '(3 4 5)) (0 1 2 3 4 5) ACL2 !>(my-app nil nil) NIL ACL2 !> Now suppose we want to prove something about the function just introduced. We conjecture, for example, that the length of the [append] of two lists is the sum of their lengths. We can formulate this conjecture in the form of the following ACL2 [47m[defthm][0m form. (defthm my-app-length (equal (len (my-app x y)) (+ (len x) (len y)))) First of all, how did we know about the functions [47mlen[0m and [47m[+][0m, etc.? The answer to that is somewhat unsatisfying --- we know them from our past experience in using Common Lisp and ACL2. It's hard to know that a function such as [47mlen[0m exists without first knowing some Common Lisp. If we'd guessed that the appropriate function was called [47m[length][0m (say, from our knowledge of Lisp) and tried [47m:pe length[0m, we would have seen that [47m[length][0m is defined in terms of [47mlen[0m, and we could have explored from there. Luckily, you can write a lot of ACL2 functions without knowing too many of the primitive functions. Secondly, why don't we need some ``type'' hypotheses? Does it make sense to append things that are not lists? Well, yes. ACL2 and Lisp are both quite weakly typed. For example, inspection of the definition of [47mmy-app[0m shows that if [47mx[0m is not a [cons] pair, then [47m(my-app x y)[0m always returns [47my[0m, no matter what [47my[0m is. Thirdly, would it matter if we rewrote the lemma with the equality reversed, as follows? (defthm my-app-length2 (equal (+ (len x) (len y)) (len (my-app x y)))). The two are [31;1mlogically[0m equivalent, but...yes, it would make a big difference. Recall our remark that a lemma is not only a ``fact'' to be proved; it also is used by the system to prove other later lemmas. The current lemma would be stored as a [rewrite] rule. (See [rule-classes].) For a [rewrite] rule, a conclusion of the form [47m(EQUAL LHS RHS)[0m means to replace instances of the [47mLHS[0m by the appropriate instance of the [47mRHS[0m. Presumably, it's better to [rewrite] [47m(len (my-app x y))[0m to [47m(+ (len x) (len y))[0m than the other way around. The reason is that the system ``knows'' more about [47m[+][0m than it does about the new function symbol [47mmy-app[0m. So let's see if we can prove this lemma. Submitting our preferred [47m[defthm][0m to ACL2 (do it!), we get the following interaction: -------------------------------------------------- ACL2 !>(defthm my-app-length (equal (len (my-app x y)) (+ (len x) (len y)))) Name the formula above *1. Perhaps we can prove *1 by induction. Three induction schemes are suggested by this conjecture. These merge into two derived induction schemes. However, one of these is flawed and so we are left with one viable candidate. We will induct according to a scheme suggested by (LEN X), while accommodating (MY-APP X Y). These suggestions were produced using the :induction rules LEN and MY-APP. If we let (:P X Y) denote *1 above then the induction scheme we'll use is (AND (IMPLIES (NOT (CONSP X)) (:P X Y)) (IMPLIES (AND (CONSP X) (:P (CDR X) Y)) (:P X Y))). This induction is justified by the same argument used to admit LEN. When applied to the goal at hand the above induction scheme produces two nontautological subgoals. Subgoal *1/2 (IMPLIES (NOT (CONSP X)) (EQUAL (LEN (MY-APP X Y)) (+ (LEN X) (LEN Y)))). But simplification reduces this to T, using the :definitions of FIX, LEN and MY-APP, the :type-prescription rule LEN, the :rewrite rule UNICITY-OF-0 and primitive type reasoning. Subgoal *1/1 (IMPLIES (AND (CONSP X) (EQUAL (LEN (MY-APP (CDR X) Y)) (+ (LEN (CDR X)) (LEN Y)))) (EQUAL (LEN (MY-APP X Y)) (+ (LEN X) (LEN Y)))). This simplifies, using the :definitions of LEN and MY-APP, primitive type reasoning and the :rewrite rules COMMUTATIVITY-OF-+ and CDR-CONS, to Subgoal *1/1' (IMPLIES (AND (CONSP X) (EQUAL (LEN (MY-APP (CDR X) Y)) (+ (LEN Y) (LEN (CDR X))))) (EQUAL (+ 1 (LEN (MY-APP (CDR X) Y))) (+ (LEN Y) 1 (LEN (CDR X))))). But simplification reduces this to T, using linear arithmetic, primitive type reasoning and the :type-prescription rule LEN. That completes the proof of *1. Q.E.D. Summary Form: ( DEFTHM MY-APP-LENGTH ...) Rules: ((:REWRITE UNICITY-OF-0) (:DEFINITION FIX) (:REWRITE COMMUTATIVITY-OF-+) (:DEFINITION LEN) (:REWRITE CDR-CONS) (:DEFINITION MY-APP) (:TYPE-PRESCRIPTION LEN) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:FAKE-RUNE-FOR-LINEAR NIL)) Warnings: None Time: 0.30 seconds (prove: 0.13, print: 0.05, other: 0.12) MY-APP-LENGTH -------------------------------------------------- Wow, it worked! In brief, the system first tried to [rewrite] and simplify as much as possible. Nothing changed; we know that because it said ``Name the formula above *1.'' Whenever the system decides to name a formula in this way, we know that it has run out of techniques to use other than proof by induction. The induction performed by ACL2 is structural or ``Noetherian'' induction. You don't need to know much about that except that it is induction based on the structure of some object. The heuristics infer the structure of the object from the way the object is recursively decomposed by the functions used in the conjecture. The heuristics of ACL2 are reasonably good at selecting an induction scheme in simple cases. It is possible to override the heuristic choice by providing an [47m:induction[0m hint (see [hints]). In the case of the theorem above, the system inducts on the structure of [47mx[0m as suggested by the decomposition of [47mx[0m in both [47m(my-app x y)[0m and [47m(len x)[0m. In the base case, we assume that [47mx[0m is not a [47m[consp][0m. In the inductive case, we assume that it is a [47m[consp][0m and assume that the conjecture holds for [47m(cdr x)[0m. There is a close connection between the analysis that goes on when a function like [47mmy-app[0m is accepted and when we try to prove something inductively about it. That connection is spelled out well in Boyer and Moore's book ``A Computational Logic,'' if you'd like to look it up. But it's pretty intuitive. We accepted [47mmy-app[0m because the ``size'' of the first argument [47mx[0m decreases in the recursive call. That tells us that when we need to prove something inductively about [47mmy-app[0m, it's a good idea to try an induction on the size of the first argument. Of course, when you have a theorem involving several functions, it may be necessary to concoct a more complicated [induction] schema, taking several of them into account. That's what's meant by ``merging'' the induction schemas. The proof involves two cases: the base case, and the inductive case. You'll notice that the subgoal numbers go [31;1mdown[0m rather than up, so you always know how many subgoals are left to process. The base case ([47mSubgoal *1/2[0m) is handled by opening up the function definitions, simplifying, doing a little rewriting, and performing some reasoning based on the types of the arguments. You'll often encounter references to system defined lemmas (like [47municity-of-0[0m). You can always look at those with [47m:[0m[47m[pe][0m; but, in general, assume that there's a lot of simplification power under the hood that's not too important to understand fully. The inductive case ([47mSubgoal *1/1[0m) is also dispatched pretty easily. Here we assume the conjecture true for the [47m[cdr][0m of the list and try to prove it for the entire list. Notice that the prover does some simplification and then prints out an updated version of the goal ([47mSubgoal *1/1'[0m). Examining these gives you a pretty good idea of what's going on in the proof. Sometimes one goal is split into a number of subgoals, as happened with the induction above. Sometimes after some initial processing the prover decides it needs to prove a subgoal by induction; this subgoal is given a name and pushed onto a stack of goals. Some steps, like generalization (see ACLH), are not necessarily validity preserving; that is, the system may adopt a false subgoal while trying to prove a true one. (Note that this is ok in the sense that it is not ``unsound.'' The system will fail in its attempt to establish the false subgoal and the main proof attempt will fail.) As you gain facility with using the prover, you'll get pretty good at recognizing what to look for when reading a proof script. The prover's [proof-tree] utility helps with monitoring an ongoing proof and jumping to designated locations in the proof (see [proof-tree]). See [tips] for a number of useful pointers on using the theorem prover effectively. When the prover has successfully proved all subgoals, the proof is finished. As with a [47m[defun][0m, a [summary] of the proof is printed. This was an extremely simple proof, needing no additional guidance. More realistic examples typically require the user to look carefully at the failed proof log to find ways to influence the prover to do better on its next attempt. This means either: proving some rules that will then be available to the prover, changing the global state in ways that will affect the proof, or providing some [hints] locally that will influence the prover's behavior. Proving this lemma ([47mmy-app-length[0m) is an example of the first. Since this is a [rewrite] rule, whenever in a later proof an instance of the form [47m(LEN (MY-APP X Y))[0m is encountered, it will be rewritten to the corresponding instance of [47m(+ (LEN X) (LEN Y))[0m. Disabling the rule by executing the [command] (in-theory (disable my-app-length)), is an example of a global change to the behavior of the prover since this [rewrite] will not be performed subsequently (unless the rule is again [enable]d). Finally, we can add a (local) [disable] ``hint'' to a [47m[defthm][0m, meaning to [disable] the lemma only in the proof of one or more subgoals. For example: (defthm my-app-length-commutativity (equal (len (my-app x y)) (len (my-app y x))) :hints (("Goal" :in-theory (disable my-app-length)))) In this case, the hint supplied is a bad idea since the proof is much harder with the hint than without it. Try it both ways. By the way, to undo the previous event use [47m:u[0m (see [u]). To undo back to some earlier event use [47m:ubt[0m (see [ubt]). To view the current event use [47m:pe :here[0m. To list several [events] use [47m:pbt[0m (see [pbt]). Notice the form of the hint in the previous example (see [hints]). It specifies a goal to which the hint applies. [47m"Goal"[0m refers to the top-level goal of the theorem. Subgoals are given unique names as they are generated. It may be useful to suggest that a function symbol be [disable]d only for Subgoal 1.3.9, say, and a different function [enable]d only on Subgoal 5.2.8. Overuse of such [hints] often suggests a poor global proof strategy. We now recommend that you visit [documentation] on additional examples. See [annotated-ACL2-scripts].") (always$ (pointers) "See [loop$].") (always$+ (pointers) "See [loop$].") (analyzing_common_lisp_models (pages_written_especially_for_the_tours) "Analyzing Common Lisp Models To analyze a model you must be able to reason about the operations and relations involved. Perhaps, for example, some aspect of the model depends upon the fact that the concatenation operation is associative. In any Common Lisp you can confirm that (app '(A B) (app '(C D) '(E F))) and (app (app '(A B) '(C D)) '(E F))) both evaluate to the same thing, [47m(A B C D E F)[0m. But what distinguishes ACL2 (the logic) from applicative Common Lisp (the language) is that in ACL2 you can [31;1mprove[0m that the concatenation function [47mapp[0m is associative when its arguments are true-lists, whereas in Common Lisp all you can do is test that proposition. That is, in ACL2 it makes sense to say that the following formula is a ``theorem.'' [31;1mTheorem[0m Associativity of App (implies (and (true-listp a) (true-listp b)) (equal (app (app a b) c) (app a (app b c)))) Theorems about the properties of models are proved by symbolically manipulating the operations and relations involved. If the concatenation of sequences is involved in your model, then you may well need the theorem above in order to that your model has some particular property.") (and (basics acl2-built-ins) "Conjunction [47mAnd[0m is the macro for conjunctions. [47mAnd[0m takes any number of arguments. [47mAnd[0m returns [47mnil[0m if one of the arguments is [47mnil[0m, but otherwise returns the last argument. If there are no arguments, [47mand[0m returns [47mt[0m. [47mAnd[0m is a Common Lisp macro. See any Common Lisp documentation for more information. [31;1mMacro: [0m<and> (defmacro and (&rest args) (and-macro args)) [31;1mFunction: [0m<and-macro> (defun and-macro (lst) (declare (xargs :guard t)) (if (consp lst) (if (consp (cdr lst)) (list 'if (car lst) (and-macro (cdr lst)) nil) (car lst)) t))") (annotated-acl2-scripts (acl2-tutorial) "Examples of ACL2 scripts Beginning users may find these annotated scripts useful. We suggest that you read these in the following order: [Tutorial1-Towers-of-Hanoi] [Tutorial2-Eights-Problem] [Tutorial3-Phonebook-Example] [Tutorial4-Defun-Sk-Example] [Tutorial5-Miscellaneous-Examples] You can also find useful demos in the [community-books] directory, [47mbooks/demos/[0m, and its subdirectories. The web page {Brief ACL2 Tutorial | https://www.cs.utexas.edu/users/moore/publications/tutorial/rev3.html} contains a script that illustrates how it feels to use The Method to prove an unusual list reverse function correct. The screen shots of ACL2's proof output are outdated --- in the version shown, ACL2 does not print Key Checkpoints, but the concept of key checkpoint is clear in the discussion and the behavior of the user. See {Polishing Proofs Tutorial | https://www.cs.utexas.edu/users/moore/acl2/contrib/POLISHING-PROOFS-TUTORIAL.html} for a tutorial on becoming successful at approaching a formalization and proof problem in ACL2. That tutorial, written by Shilpi Goel and Sandip Ray, has two parts: it illustrates how to guide the theorem prover to a successful proof, and it shows how to clean up the proof in order to facilitate maintenance and extension of the resulting book (see [books]). The {ACL2 Demo Given at TPHOLs 2008 | https://www.cs.utexas.edu/users/moore/publications/tutorial/kaufmann-TPHOLs08/index.html} by Matt Kaufmann includes scripts and a gzipped tar file containing the entire contents of the demos. The {sort equivalence demo | https://www.cs.utexas.edu/users/moore/publications/tutorial/sort-equivalence} is a collection of scripts illustrating both high-level strategy and lower-level tactics dealing with the functional equivalence of various list sorting algorithms. Start with the [47mREADME[0m on that directory. There is also a {gzipped tar file | https://www.cs.utexas.edu/users/moore/publications/tutorial/sort-equivalence.tgz} with all of these scripts. When you feel you have read enough examples, you might want to try the following very simple example on your own. (See [solution-to-simple-example] for a solution, after you work on this example.) First define the notion of the ``fringe'' of a tree, where we identify trees simply as [cons] structures, with [atom]s at the leaves. For example: ACL2 !>(fringe '((a . b) c . d)) (A B C D) Next, define the notion of a ``leaf'' of a tree, i.e., a predicate [47mleaf-p[0m that is true of an atom if and only if that atom appears at the tip of the tree. Define this notion without referencing the function [47mfringe[0m. Finally, prove the following theorem, whose proof may well be automatic (i.e., not require any lemmas). (defthm leaf-p-iff-member-fringe (iff (leaf-p atm x) (member-equal atm (fringe x)))) Subtopics [Solution-to-simple-example] Solution to a simple example [Tutorial1-towers-of-hanoi] The Towers of Hanoi Example [Tutorial2-eights-problem] The Eights Problem Example [Tutorial3-phonebook-example] A Phonebook Specification [Tutorial4-defun-sk-example] Example of quantified notions [Tutorial5-miscellaneous-examples] Miscellaneous ACL2 examples") (an_example_common_lisp_function_definition (pages_written_especially_for_the_tours) "An Example Common Lisp Function Definition {IMAGE} (see [An_Example_of_ACL2_in_Use]) Consider the binary trees [47mx[0m and [47my[0m below. {IMAGE} In Lisp, [47mx[0m is written as the list [47m'(A B)[0m or, equivalently, as [47m'(A B . NIL)[0m. Similarly, [47my[0m may be written [47m'(C D E)[0m. Suppose we wish to replace the right-most tip of [47mx[0m by the entire tree [47my[0m. This is denoted [47m(app x y)[0m, where [47mapp[0m stands for ``append''. {IMAGE} We can define [47mapp[0m with: [31;1m(defun app (x y)[0m [3m; Concatenate x and y.[0m [31;1m(declare (type (satisfies true-listp) x))[0m[3m; We expect x to end in NIL.[0m [31;1m(cond ((endp x) y)[0m [3m; If x is empty, return y.[0m [31;1m(t (cons (car x)[0m [3m; Else, copy first node[0m [31;1m(app (cdr x) y)))))[0m [3m; and recur into next.[0m If you defined this function in some Common Lisp, then to run [47mapp[0m on the [47mx[0m and [47my[0m above you could then type (app '(A B) '(C D E)) and Common Lisp will print the result [47m(A B C D E)[0m. {IMAGE} (see [An_Example_of_ACL2_in_Use])") (an_example_of_acl2_in_use (pages_written_especially_for_the_tours) "An Example of ACL2 in Use {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions]) To introduce you to ACL2 we will consider the [47mapp[0m function discussed in the Common Lisp (see [Common_Lisp]) page, [31;1mexcept[0m we will omit for the moment the [31;1mdeclare[0m form, which in ACL2 is called a [31;1mguard[0m. Guards are arbitrary ACL2 terms that express the ``intended domain'' of functions. In that sense, guards are akin to type signatures. However, Common Lisp and ACL2 are untyped programming languages: while the language supports several different data types and the types of objects can be determined by predicates at runtime, any type of object may be passed to any function. Thus, guards are ``extra-logical.'' Recognizing both the practical and intellectual value of knowing that your functions are applied to the kinds of objects you intend, ACL2 imposes guards on Common Lisp and provides a means of proving that functions are used as intended. But the story is necessarily complicated and we do not recommend it to the new user. Get used to the fact that any ACL2 function may be applied to any objects and program accordingly. Read about guards later. Here is the definition again [31;1m(defun app (x y)[0m [31;1m(cond ((endp x) y)[0m [31;1m(t (cons (car x) [0m [31;1m(app (cdr x) y)))))[0m The next few stops along the Walking Tour will show you * how to use the ACL2 documentation, * what happens when the above definition is submitted to ACL2, * what happens when you evaluate calls of [47mapp[0m, * what one simple theorem about [47mapp[0m looks like, * how ACL2 proves the theorem, and * how that theorem can be used in another proof. Along the way we will talk about the [31;1mdefinitional principle[0m, [31;1mtypes[0m, the ACL2 [31;1mread-eval-print loop[0m, and how the [31;1mtheorem prover[0m works. When we complete this part of the tour we will return briefly to the notion of [31;1mguards[0m and revisit several of the topics above in that context. {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions])") (append (lists acl2-built-ins) "[concatenate] zero or more lists [47mAppend[0m, which takes zero or more arguments, expects all the arguments except perhaps the last to be true ([47mnil[0m-terminated) lists. It returns the result of concatenating all the elements of all the given lists into a single list. Actually, in ACL2 [47mappend[0m is a macro that expands into calls of the binary function [47m[binary-append][0m if there are at least two arguments; if there is just one argument then the expansion is that argument; and finally, [47m(append)[0m expands to [47mnil[0m. [47mAppend[0m is a Common Lisp function. See any Common Lisp documentation for more information. See [append-without-guard] for a version of [47mappend[0m that has a guard of [47mt[0m. [31;1mMacro: [0m<append> (defmacro append (&rest rst) (cond ((null rst) nil) ((null (cdr rst)) (car rst)) (t (xxxjoin 'binary-append rst)))) [31;1mFunction: [0m<binary-append> (defun binary-append (x y) (declare (xargs :guard (true-listp x))) (cond ((endp x) y) (t (cons (car x) (binary-append (cdr x) y))))) Subtopics [Binary-append] [concatenate] two lists") (append$ (pointers) "See [loop$].") (append$+ (pointers) "See [loop$].") (apply$ (acl2-built-ins programming) "Apply a badged function or tame lambda to arguments We recommend that you read the paper {``Limited Second-Order Functionality in a First-Order Setting'' | https://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore for both motivation and foundational details. You might also read [introduction-to-apply$]! This documentation starts with a [31;1mglossary[0m of terms. Then we provide some [31;1mexamples[0m and present the [31;1mspecification[0m of [47mapply$[0m. Next, we deal with issues related to [47mapply$[0m in [31;1mdefinitions[0m, [31;1mstating and proving theorems[0m, [31;1mguards and guard verification[0m, and [31;1mtop-level evaluation[0m. Finally we exhibit the [31;1mformal definitions[0m [47mapply$[0m and some related concepts. We have sprinkled in a little tutorial material for readability but have not provided much motivation for some design decisions. Glossary Here is a brief glossary of terms used in the semantics of [47mapply$[0m. While we provide links to the documentation of the concepts, we urge you not to follow those links until you've understood the big picture! * [47mapply$[0m --- the ACL2 function that takes two arguments, one representing a function and the other listing actuals to be fed to that function. Under certain conditions, [47mapply$[0m applies the function to the arguments and returns the result. [47mApply$[0m is mutually recursive with [47m[apply$-lambda][0m, [47m[ev$][0m, and [47m[ev$-list][0m. [47mApply$[0m's ``badge'' (see below) is [47m(APPLY$-BADGE 2 1 :FN NIL)[0m its arity is 2, its ``out arity'' is 1 (i.e., it returns 1 result), its first argument has ``ilk'' [47m:FN[0m and is thus treated as a ``function;'' its second argument has ilk [47mNIL[0m and is thus treated as an ordinary object. * [47m[badge][0m --- an object associated with some function symbols indicating that [47mapply$[0m can ``handle'' them and under what conditions. The badge of a function symbol specifies its arity, its ``out arity,'' (i.e., the number of results the function returns), and the [ilk] of each argument position telling [47mapply$[0m how each argument is treated. The ilks are [47m:FN[0m, [47m:EXPR[0m and [47mNIL[0m. The association between a non-primitive function symbol and its badge is managed by [47m[warrant][0ms. In proofs, [47mapply$[0m must have a warrant for every non-primitive function symbol to be applied. Those warrants are provided as hypotheses to the theorem being proved. Symbols without badges cannot be [47mapply$[0md. Badges are generated, when possible, by [47m[defwarrant][0m. (Badges can be generated for [47m:[0m[47mprogram[0m mode functions by [47m[defbadge][0m, allowing [47mapply$[0m to handle such functions in top level evaluation not in proofs.) Not every function symbol can have a badge. * compiled [47mLAMBDA[0m cache (or simply [3mcache[0m in this context) --- a cache in the raw Lisp under ACL2 that supports the application of [47mapply$[0m on well-formed, guard verified [47mLAMBDA[0m objects. Later in this Glossary we define ``lambda expression,'' ``[47mLAMBDA[0m object,'' and ``lambda$ expression'' --- three similar looking phrases with very different meanings. See [47m[print-cl-cache][0m for some details of the cache. * evaluation theory --- the logical theory in which expressions submitted at the top level of the ACL2 read-eval-print loop are evaluated. The evaluation theory is a consistent extension of the proof theory, the latter being the logical theory in which the ACL2 theorem prover operates. The evaluation theory was introduced in ACL2 when [47m[defattach][0m was added, but it was changed with the introduction of [47mapply$[0m. All [47m[warrant][0ms introduced by [47mdefwarrant[0m are assumed true in the evaluation theory but not in the proof theory. This means ACL2 can execute calls of [47mapply$[0m that arise in the evaluation of top-level input, but ACL2 cannot evaluate all calls of [47mapply$[0m that arise in proofs unless the appropriate warrants are available as hypotheses. See [guarantees-of-the-top-level-loop] for some details of the evaluation theory and how it differs from the proof theory supported by the ACL2 theorem prover. * lambda expression --- an integral part of ACL2's formal term syntax, lambda expressions are the way [47mlet[0m expressions and other variable-binding idioms are translated into formal terms. Lambda expressions have nothing to do with [47mapply$[0m! See [lambda] for a discussion of three confusingly similar but different concepts: lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions. Read carefully anytime you see the word ``lambda!'' * [47mLAMBDA[0m object --- an ACL2 list constant, typically of the form [47m(LAMBDA vars body)[0m or [47m(LAMBDA vars dcl body)[0m that may be used as a ``function'' by [47mapply$[0m. [47mApply$[0m treats any [47m[consp][0m object in its first argument position as though it were a [47mLAMBDA[0m object. But it only gives sensible meanings to [tame] [47mLAMBDA[0m objects. And only well-formed [47mLAMBDA[0m objects are executed efficiently. But well-formed [47mLAMBDA[0m objects are hard to type by hand --- there are many constraints to keep in mind to guarantee well-formedness. See [47m[well-formed-lambda-objectp][0m if you really want to see all the rules. But that is generally unnecessary. We [3mstrongly[0m recommend not entering [47mLAMBDA[0m objects as quoted constants, e.g., [47m'(LAMBDA (X) (+ 1 X))[0m --- which is actually ill-formed! Instead, use [47m[lambda$][0m, as in [47m(lambda$ (x) (+ 1 x))[0m. See also [lambda] for some clarifications. * [47m[lambda$][0m expression --- an ACL2 macro that allows you to enter quoted well-formed [47mLAMBDA[0m objects into your terms by typing untranslated expressions that resemble lambda expressions. The [47mlambda$[0m expression [47m(lambda$ (x) (+ 1 x))[0m essentially translates into the quoted [47mLAMBDA[0m object [47m'(LAMBDA (X) (BINARY-+ '1 X))[0m. We say ``essentially'' because [47mlambda$[0m always inserts a [47m(DECLARE (IGNORABLE v1 ... vn))[0m listing every formal and tags the body with a [47m[return-last][0m form that indicates it came from a translated [47mlambda$[0m. See also [lambda] for some clarifications. * [47m[scion][0m --- a function that is ancestrally dependent on [47mapply$[0m. In the early days of [47mapply$[0m we called scions ``mapping functions'' but in the Lisp community that implies iteration over a list and scions are more general. Of course, a function that iterates over a list [47mapply$[0ming a ``function'' to each element and collecting the results is an example of a scion. But so is function that takes a ``function'' and applies it in one special situation, e.g., as a test or base case. Any function ancestrally dependent on [47mapply$[0m is a scion whether or not it takes a ``function'' as an argument or maps over a domain. * [tame] --- the class of functions that [47mapply$[0m knows about; we actually talk about ``tame functions,'' ``tame [47mLAMBDA[0m objects,'' and ``tame expressions.'' The last are expressions that are evaluable by an interpreter named [47m[ev$][0m that is mutually-recursive with [47mapply$[0m. [47mApply$[0m cannot handle all definable functions: ACL2 is first order and if [47mapply$[0m were able to ``handle'' certain functions the logic would be inconsistent. * [47m[warrant][0m --- a 0-ary predicate associated with some user-defined function symbols that must be a hypothesis of any theorem whose proof involves ``expanding'' [47mapply$[0m on such symbols; the warrant gives [47mapply$[0m ``permission'' to expand if the arguments to which the function is applied are appropriately [tame]. The warrant for a function specifies the function's [47m[badge][0m and how [47mapply$[0m behaves on the function symbol. Warrants (and badges) are computed and introduced by the [47m[defwarrant][0m event. Not all function symbols can be warranted. You will get a much better understanding of these concepts if you read the paper cited above. Examples To illustrate [47mapply$[0m and some related concepts we need some user-defined functions. We therefore imagine that the following events have been successfully admitted. [31;1mWe strongly recommend that you include the following book in any session in which you intend to use or reason about [47mapply$[0m[31;1m.[0m (include-book "projects/apply/top" :dir :system) (defun$ sq (x) (* x x)) (defun$ collect$ (fn lst) (if (endp lst) nil (cons (apply$ fn (list (car lst))) (collect$ fn (cdr lst))))) (defun$ foldr (lst fn init) (if (endp lst) init (apply$ fn (list (car lst) (foldr (cdr lst) fn init))))) (defun$ russell (fn x) (not (apply$ fn (list x x)))) Note: [47mCollect$[0m is pre-defined in ACL2 because it is part of the support for the [47m[loop$][0m statement. [47mCollect$[0m and [47mfoldr[0m might informally be called ``mapping functions'' because they map a given function over some domain and accumulate the answers somehow. They are useful examples of what we call [3mscions of[0m [47mapply$[0m or simply [3mscions[0m: functions in which [47mapply$[0m is ancestral, i.e., functions that call [47mapply$[0m or call functions that call [47mapply$[0m, etc. [47mRussell[0m is also a scion. See [scion] for more. Here are some evaluations carried out at the top-level of the ACL2 loop after the events above. Top-level evaluations take place in ACL2's evaluation theory (see the discussion of the semantics of [47m[defattach][0m), which is an extension of the theory in which proofs are conducted. Put more bluntly, the following evaluations won't be carried out in proofs unless you have the right hypotheses! ACL2 !>(apply$ 'sq '(5)) 25 ACL2 !>(collect$ 'sq '(1 2 3 4 5)) (1 4 9 16 25) ACL2 !>(collect$ (lambda$ (x) (* x x)) '(1 2 3 4 5)) (1 4 9 16 25) ACL2 !>(foldr '(1 2 3) 'cons '(4 5 6)) (1 2 3 4 5 6) ACL2 !>(foldr '(1 2 3 4 5) (lambda$ (x y) (cons (sq x) y)) nil) (1 4 9 16 25) ACL2 !>(foldr '(1 2 3 4) (lambda$ (x y) (foldr y 'cons (list x))) nil) (4 3 2 1) ACL2 !>(russell 'natp 3) NIL ACL2 !>(russell 'consp 3) T [47mApply$[0m doesn't always work the way you might want! ACL2 !>(let ((x 'russell))(russell x x)) ACL2 Error in TOP-LEVEL: The value of APPLY$-USERFN is not specified when the first argument, fn, is RUSSELL, and the second argument, args, is (RUSSELL RUSSELL). Fn has badge (APPLY$-BADGE 2 1 :FN NIL) and args is not known to satisfy the tameness requirement of that badge. [47m[Apply$-userfn][0m is the undefined function called by [47mapply$[0m when it is asked to apply a user-defined function symbol instead of a builtin function symbol. The [47m[warrant][0m for [47mrussell[0m actually specifies the value of [47m(apply$-userfn 'russell ...)[0m under the [47m[tame][0mness requirements, and those requirements are violated above. This is necessary to preserve the consistency of the logic. Otherwise: (russell 'russell 'russell) = {by defun of russell} (not (apply$ 'russell (list 'russell 'russell))) = {by the naive expectation that apply$ always ``works''} (not (russell 'russell 'russell)) Contradiction! Top-level evaluation of [47mapply$[0m expressions raises problems not seen anywhere else in ACL2's execution model: While executing syntactically legal terms the evaluator can encounter undefined functions or weirdly ill-formed terms not caught by the usual ACL2 translation mechanism. The ACL2 translation mechanism checks the well-formedness of [47m[lambda$][0m expressions (and user-typed quoted [47mLAMBDA[0m objects) that occur in positions of ilk [47m:FN[0m and are therefore destined for [47mapply$[0m. But the translation checks can be defeated. The [47mLAMBDA[0m object below contains a call of the undefined function [47mfoo[0m but the error is not caught at translation time; it is caught only when the form executed. ACL2 !>(apply$ `(lambda (x) (foo x)) '(5)) ACL2 Error in TOP-LEVEL: The value of BADGE-USERFN is not specified on FOO because FOO is not a known function symbol. Note the [3mbackquote[0m on the [47mLAMBDA[0m object. This defeats the check of well-formedness because the [47mLAMBDA[0m object is not [47mquote[0md. We could have equally written ACL2 !>(apply$ (list 'lambda '(x) (cons 'foo '(x))) '(5)) with the same result. There is nothing unsound about this. [47mApply$[0m can take any objects as arguments. But it won't always ``behave'' as you might expect. One way to explore the edge cases of [47mapply$[0m is to execute it on ill-formed input. In addition, some theorems may require consing up a [47mLAMBDA[0m object in terms of objects used elsewhere in the theorem. See example theorem [47m[3][0m below. A peculiar aspect of [47mLAMBDA[0m objects is that they can be written as legal ACL2 constants [3mbefore[0m they are well-formed [47mLAMBDA[0m objects, e.g., by referring to undefined functions, [47m:program[0m mode functions, unbadged functions, etc. They are, after all, just arbitrary quoted objects and any value in ACL2 can be quoted. But an ill-formed object can [3mbecome[0m well-formed if the world is appropriately extended, e.g., the appropriate [47mdefun[0ms, [47mdefbadge[0ms, and [47mdefwarrant[0ms are made. Perhaps worse, they can be well-formed and then [3mbecome[0m ill-formed by an undo. So at runtime [47mapply$[0m has to check that the function symbol or [47mLAMBDA[0m object is appropriate. There is a sophisticated cache behind the execution machinery for [47mLAMBDA[0m objects in the evaluation theory. See [47m[print-cl-cache][0m. Here are some theorems that can be proved about these concepts. The last of the theorems shown below requires two lemmas, named [47mweird-little-lemma1[0m and [47mweird-little-lemma2[0m, shown in [47mbooks/projects/apply/report.lisp[0m. For a summary of how the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m [scion]s, see [rewriting-calls-of-apply$-ev$-and-loop$-scions]. ; [1] SQ squares, if you have the warrant for sq! Imagine for a moment that ; we could prove (equal (apply$ 'SQ (list i)) (* i i)) without the warrant ; hypothesis shown below. And imagine that we did so in an encapsulated ; environment in which sq was locally defined to be (* x x). Then imagine we ; exported the simpler theorem out of that encapsulate and defined sq to be ; (+ 1 (* x x)). Then ACL2 would be unsound. Exporting a theorem requires ; that the theorem be ancestrally independent of every locally defined ; function and the simpler hypothetical theorem is, because the symbol 'SQ is ; not ancestrally dependent on sq. But ACL2 cannot prove the simpler ; theorem! It cannot ``open'' apply$ on 'SQ without the warrant for sq and ; the warrant for sq is ancestrally dependent on sq. So the theorem below ; cannot be exported from an environment in which sq is locally defined. ; Thus warrants solve the so-called ``LOCAL problem.'' (thm (implies (warrant sq) (equal (apply$ 'SQ (list i)) (* i i)))) ; [2] Collect$ distributes over append for any fn. (thm (equal (collect$ fn (append a b)) (append (collect$ fn a) (collect$ fn b)))) ; [3] Foldr can be used to collect$, but the collection must ; be with an ``ok'' function (a tame function of one ; argument). Note the backquote on the LAMBDA. This is ; a theorem that requires us to cons up a LAMBDA object. (thm (implies (ok-fnp fn) (equal (foldr lst `(LAMBDA (X Y) (CONS (,fn X) Y)) nil) (collect$ fn lst)))) Specification of APPLY$ [31;1mWe strongly recommend that you include the following book in any session in which you intend to use or reason about [47mapply$[0m[31;1m.[0m (include-book "projects/apply/top" :dir :system) General Form: (apply$ fn args) where [47mfn[0m is some function symbol or [47mLAMBDA[0m object and [47margs[0m is a true list. Informally, [47mapply$[0m applies the function named by the first argument to the appropriate number of elements taken from the second argument. We might express this as: [31;1mNaive Specification (for a single-valued function):[0m (apply$ 'fn args) = (fn (nth 0 args) ... (nth (- n 1) args)) [31;1mNaive Specification (for a multi-valued function):[0m (apply$ 'fn args) = (mv-list k (fn (nth 0 args) ... (nth (- n 1) args))) where [47mfn[0m is of arity [47mn[0m and [47mk[0m is the ``out arity'' of [47mfn[0m (the number of returned values). [31;1mHowever[0m, these naive specifications are guaranteed only if either (i) [47mfn[0m is a function symbol that has a [47m[badge][0m and [47margs[0m satisfies the [tame]ness requirements of the badge, or (ii) [47mfn[0m is a well-formed [47mLAMBDA[0m object that returns 1 result. The tameness requirement is that if an element of [47margs[0m is in an argument position of [47mfn[0m with ilk [47m:FN[0m then the element must satisfy [47mtamep-functionp[0m and if the element is in an argument position of ilk [47m:EXPR[0m it must satisfy [47mtamep[0m. See [47m[badge][0m for further discussion of condition (i). As for (ii), rather than explain ``well-formed [47mLAMBDA[0m object'' here we encourage you to write [47m[lambda$][0m expressions when you want to [47mapply$[0m a [47mLAMBDA[0m object. The [ilk]s of [47mapply$[0m are [47m:FN[0m and [47mNIL[0m respectively, telling us that [47mapply$[0m treats its first argument as a ``function'' and its second as an ordinary object (never as a function). Initially [47mapply$[0m and several functions used in the translation of [47mloop$[0m statements are the only symbols in ACL2 with an ilk of [47m:FN[0m. However as [47m[defwarrant][0m is used successfully on [scion]s --- functions that somehow call [47mapply$[0m --- user-defined symbols can have ilk [47m:FN[0m too. [47mApply$[0m has a guard, namely [47m(apply$-guard fn args)[0m. This is an exceptionally weak guard, requiring only that [47margs[0m be a true-list and, if [47mfn[0m is a cons --- which is automatically treated as a [47mLAMBDA[0m object --- the length of [47margs[0m be the length of the second element of [47mfn[0m. We discuss [31;1mguards and guard verification[0m in a subsequent section. [31;1mNote for Experts[0m: Technically, [47mapply$[0m treats any [47mconsp[0m object as a [47mLAMBDA[0m object. But the results are as you'd naively expect only if the object is a [tame] [47mLAMBDA[0m object. However, we frequently write as though the object must be [3mwell-formed[0m, which is different from but implies tameness. What's going on? The reason for this and related discrepancies in the documentation is that there is a tension between the logical definition of [47mapply$[0m and the practical business of executing it. The former involves the existence of a model, soundness, and the difficulty of proving theorems about [47mapply$[0m. The latter involves the Common Lisp compiler. We want the logical foundations to be simple to make it easier to reason about [47mapply$[0m, but the compiler imposes unavoidable and complicated restrictions. The upshot is that the logical foundations assign meaning to [47mLAMBDA[0m objects that cannot be compiled. Applying merely ``tame'' [47mLAMBDA[0ms is slower than applying ``well-formed'' ones. In a sense, by acting like ``tame [47mLAMBDA[0m objects'' and ``well-formed [47mLAMBDA[0m objects'' are synonymous we're trying to trick you! If you ever have occasion to formally express the restrictions on [47mapply$[0m in some theorem, use [47mtamep-functionp[0m. But when you write concrete [47mLAMBDA[0m constants, try to keep them well-formed. We encourage this by providing [47m[lambda$][0m and by enforcing full blown well-formedness checks --- not just tameness checks --- in translate on every quoted [47mLAMBDA[0m object entered in a [47m:FN[0m slot. And we give you ways to circumvent these checks --- see [gratuitous-lambda-object-restrictions] --- if you really mean to supply ill-formed [47mLAMBDA[0m objects to [47m:FN[0m slots. Badges are assigned by [47m[defwarrant][0m, and also by [47m[defbadge][0m. See [47m[badge][0m for documentation about how to find out whether a function has a badge and how to interpret a badge. The terms ``out arity'' and ``tameness requirements,'' used above, are explained there too. Intuitively, the badge of [47mfn[0m tells [47mapply$[0m how each formal of [47mfn[0m is used in the definition of [47mfn[0m and there are only three ``ilks'' of use. Ilk [47m:FN[0m means the formal is used exclusively as a function, meaning the formal can be passed into [47m:FN[0m slots of other functions and eventually reaches [47mapply$[0m, but it is never touched by other ACL2 functions. Ilk [47m:EXPR[0m means the formal is used exclusively as an expression, meaning the formal may be passed into [47m:EXPR[0m slots of other functions and eventually reaches [47m[ev$][0m, but is never otherwise touched. Finally, ilk [47mNIL[0m means the formal is treated as an ordinary ACL2 object and, in particular, never used as either a function or an expression. The ``tameness requirement'' on each actual is determined by the ilk of the corresponding formal: actuals in [47m:FN[0m slots must satisfy [47mtamep-functionp[0m, actuals in [47m:EXPR[0m slots must satisfy [47mtamep[0m, and there are no requirements on actuals in ilk [47mNIL[0m slots. For discussions of [47mtamep-functionp[0m and [47mtamep[0m see the topic [tame]. Generally speaking, if you want to be able to [47mapply$[0m a function you should introduce it with [47m[defun][0m and then call [47m[defwarrant][0m on the function name, or use [47m[defun$][0m, which is a convenient abbreviation for the above sequence of events. But [47mdefun$[0m only works for [47m:logic[0m mode functions because [47mdefwarrant[0m enforces that restriction. If you want to [47mapply$[0m a [47m:program[0m mode function you should define it with [47mdefun[0m and then call [47mdefbadge[0m on its name. We summarize the specification of [47mapply$[0m with an example. Consider (apply$ 'foldr '((1 2 3) ; actual 1 cons ; actual 2 (4 5 6))) ; actual 3 The badge of [47mfoldr[0m, computed by [47m(badge 'foldr)[0m, is [47m(APPLY$-BADGE 3 1 NIL :FN NIL)[0m. The arity is [47m3[0m, the out arity is 1 ([47mfoldr[0m is single-valued) and the ilks list is [47m(NIL :FN NIL)[0m. Thus the first and third formals have ilk [47mNIL[0m and are treated as ordinary objects; the second formal has ilk [47m:FN[0m and is treated as a function. Thus, the tameness requirement is that the second actual to a call of [47mfoldr[0m must satisfy [47mtamep-functionp[0m. Referring to the specification above, we see that the [47mapply$[0m term has the ``naive specification'' since [47mfoldr[0m has a badge, its out arity is 1, and its second actual, [47mcons[0m, satisfies [47mtamep-functionp[0m. That is, (apply$ 'foldr '((1 2 3) ; actual 1 cons ; actual 2 (4 5 6))) ; actual 3 = (foldr '(1 2 3) 'cons '(4 5 6)) = '(1 2 3 4 5 6) The first equation above is just the naive specification of [47mapply$[0m and the second equation is just the definition of [47mfoldr[0m. Formals are classified by [47m[defwarrant][0m when it tries to compute the badge of a function. What are the rules that lead to a formal being assigned ilk [47m:FN[0m, for example? What does ilk [47m:FN[0m actually signify? Let [3mv[0m be the [3mi [0mth formal parameter of a badged function [3mfn[0m. If the badge says that [3mv[0m has ilk [47m:FN[0m then we know that [3mv [0m is ``used as a function'' in the definition of [3mfn [0m, i.e., the value of [3mv [0m eventually makes its way into the first argument of [47mapply$[0m. Furthermore, [3mv [0m is never used any other way: every place [3mv [0m occurs in the body it is treated as a function. And finally, in every recursive call of [3mfn [0m [3mv [0m is passed identically in the [3mi [0mth argument position of every recursive call. If the badge says that formal variable [3mv [0m has ilk [47m:EXPR[0m then it signifies analogous conditions except that instead of eventually getting into the first argument of [47mapply$[0m it eventually gets into the first argument of [47mev$[0m. We say such formals are ``used as expressions.'' [47m[Ev$][0m is the natural notion of evaluation in this context: look up the values of variables in the alist argument to [47mev$[0m, return quoted constants, and otherwise [47mapply$[0m function symbols and [47mlambda[0m objects to the recursively obtained list of values returned by evaluating the actuals. However, [47mev$[0m first checks that the expression is [47m[tamep][0m. If the badge says a formal [3mv [0m has ilk [47mNIL[0m in the definition of [3mfn [0m then [3mv [0m is [3mnever used [0m as a function or as an expression in the definition. It is the job of [47m[defwarrant][0m to analyze a definition and assign ilks, if possible. But it may not be possible! For example, (defun foo (x) (apply$ x (list x))) is such a definition. The formal [47mx[0m is used as a function in its first occurrence but is not used as a function in its second. Thus (defwarrant foo) will fail. When successful, [47m[defwarrant][0m also defines the [47m[warrant][0m function for the function it analyzed. Warrants are crucial to stating and proving theorems about function symbols being applied with [47mapply$[0m. We illustrated warrants in the ``Examples'' section above and discuss them further in the section on ``Theorems Involving [47mApply$[0m'' below. See also [47m[warrant][0m. [47mApply$[0m is a defined function in the ACL2 source code. We exhibit its definition at the end of this documentation but you may also see its definition by doing ACL2 !>:pe apply$ The definition is mutually recursive with * [47m[apply$-lambda][0m: used by [47mapply$[0m to handle the case when the first argument to [47mapply$[0m is a [47mLAMBDA[0m object. * [47m[ev$][0m: used by [47mapply$-lambda[0m to evaluate the body of a [47mLAMBDA[0m object in an environment binding the object's formal variables to the actuals. * [47m[ev$-list][0m: used by [47mev$[0m to evaluate a list of expressions in an environment binding formals to actuals. [47mApply$[0m calls three undefined functions: * [47m[apply$-userfn][0m: used by [47mapply$[0m when it is asked to apply anything other than a [47mLAMBDA[0m object or a built-in function symbol. In the evaluation theory, we attach a function to [47mapply$-userfn[0m that explicitly enforces the tameness requirements for each user-defined [47m:logic[0m mode function symbol that has had a badge computed by [47m[defwarrant][0m and, if those requirements are met, applies the corresponding function. Magically, that attachment to [47mapply$-userfn[0m can also evaluate [47m:program[0m mode functions with badges created by [47m[defbadge][0m. We say ``magically'' because there are no axioms that explain this behavior, just as there are no axioms that explain how you can evaluate ordinary calls of [47m:program[0m mode functions in the evaluation theory. But in the proof theory [47mapply$-userfn[0m remains undefined. The value of [47m(apply$-userfn 'fn ...)[0m, and thus of [47m(apply$ 'fn ...)[0m, is specified by a special hypothesis, called the ``warrant for [47mfn[0m.'' You can't prove anything interesting about the behavior of [47mapply$[0m on a user-defined function symbol [47mfn[0m unless the warrant for [47mfn[0m is a governing hypothesis. We discuss warrants in [47m[warrant][0m. See also [47m[defwarrant][0m. * [47muntame-apply$[0m: used by [47mapply$[0m when it is asked to deal with a situation in which tameness is violated. * [47muntame-ev$[0m: used by [47mev$[0m when it is asked to deal with a situation in which tameness is violated. Definitions Involving on [47mApply$[0m In one sense, [47mapply$[0m is just an ordinary ACL2 function that takes two arguments and returns one result. Like all ACL2 functions, [47mapply$[0m is untyped. You can supply any two objects as arguments and the axioms tell you what the result is --- though sometimes the result is delivered by an undefined function. But in a deeper sense, if you want [47mapply$[0m to ``behave,'' and in particular if you want functions that use [47mapply$[0m to ``behave,'' you have to follow certain rules. For example, ACL2 must be able to determine whether a formal parameter is ``used as a function'' in a given definition. Basically, you will want every [47m:logic[0m mode function that you define to be processed by [47mdefwarrant[0m so that it gets a badge and warrant if at all possible and at least has a chance of being applied as expected by [47mapply$[0m. The macro [47mdefun$[0m is just an abbreviation for a [47mdefun[0m followed by a [47mdefwarrant[0m and it is easy to imagine the other ACL2 definitional idioms introduced in the ACL2 Community Books eventually being extended to include a subsequent [47mdefwarrant[0m. So the question becomes ``What rules must a [47mdefun[0m obey in order to be processed successfully by [47mdefwarrant[0m?'' The full answer is given in the documentation for [47m[defwarrant][0m. But here are some guidelines to follow: * use [47m:logic[0m mode, * use a measure that either returns a natural number or a lexicographic combination of natural numbers as defined by the [47mllist[0m function in the Community Books at [47mbooks/ordinals/[0m, * make sure every function used in the definition has a badge, * ensure that every [47m:FN[0m slot in the body is occupied either by a formal parameter or a quoted, badged function symbol or [47m[lambda$][0m expression, and * ensure that no parameter occupying a [47m:FN[0m slot is ever used in a slot of any other ilk, and * ensure that every parameter passed into a [47m:FN[0m slot is passed into the same argument position in any recursive calls of the function being defined. You can certainly violate some of these rules and still get an admissible definition. For example [47m(defun rus (x) (not (apply$ x (list x))))[0m is admissible and you can run it on some arguments, e.g., [47m(rus 'consp)[0m evaluates to [47mT[0m. You can even prove [47m(equal (rus 'consp) t)[0m. But [47m(defwarrant rus)[0m fails because [47mrus[0m violates the rules. So you will not be able to [47mapply$[0m [47m'rus[0m. [31;1mNote for Experts[0m: One may wonder why it is possible to warrant a function, [47mfn[0m, that calls badged but unwarranted functions. Naively one might expect the semantics of [47m(apply$ 'fn args[0m would involve the [47mev$[0m of the body of [47mfn[0m and therefore require the successful application (via [47mapply$[0m) of subfunctions in the body. But that expectation is incorrect. The semantics of [47m(apply$ 'fn args)[0m as formalized by the warrant for [47mfn[0m says that (under restrictions on the tameness of the arguments) [47m(apply$ 'fn args)[0m is [47m(fn (car args) (cadr args) ...)[0m. Theorems Involving [47mApply$[0m Because [47mapply$[0m is undefined on user-defined function symbols and warrant hypotheses specify the tameness requirements and value of [47mapply$[0m on such symbols, you can't prove much about the application of particular user-defined symbols unless you provide the corresponding warrants as hypotheses. To emphasize this point, suppose [47msq[0m has been introduced with [47mdefun$[0m as shown above, then the following top-level evaluation is possible: ACL2 !>(apply$ 'sq '(5)) 25 You might expect to be able to prove the obvious little theorem (thm (equal (apply$ 'sq '(5)) 25)) However, you would be wrong! While ACL2's evaluation theory assumes all warrants, the proof theory does not. (If it did we could suffer the [47mLOCAL[0m problem mentioned in example theorem [47m[1][0m above and in [introduction-to-apply$].) Logically, there is no connection between the symbol [47m'SQ[0m and the user-defined function [47msq[0m. That connection is established by warrant. All the necessary warrants must be explicitly provided as hypotheses by the user. The warranted version of the little theorem above is easily proved. (thm (implies (warrant sq) (equal (apply$ 'sq '(5)) 25))) Here [47m(warrant sq)[0m is just an abbreviation for a call of the 0-ary function symbol [47mapply$-warrant-sq[0m which is the name of the warrant for [47msq[0m. [47mApply$-warrant-sq[0m is introduced when [47m(defwarrant sq)[0m completes successfully. In particular, the following is a theorem: (warrant sq) <--> (force (apply$-warrant-sq)) <--> (((badge 'SQ) = '(APPLY$-BADGE 1 1 . T)) & ((apply$ 'SQ args) = (sq (car args)))) Note that the [47m[warrant][0m macro [47m[force][0ms the warrants for the functions listed. But logically [47mforce[0m is just the identity. Thus, the warrant for [47msq[0m specifies the value of [47m(badge 'sq)[0m and of [47m(apply$ 'sq ...)[0m. Operationally, by forcing the warrant it means the absence of a warrant among the hypotheses of a conjecture which is otherwise provable just results in a forcing round that highlights the need for the warrant. If you try to prove the unwarranted version of the little theorem about [47m'sq[0m it fails in a forcing round with [1]Goal (APPLY$-WARRANT-SQ) This is a clear indication that you forgot to provide the warrant. You might worry that theorems burdened by warrants are vacuously valid because it might be impossible to satisfy all the warrant hypotheses. You needn't worry about this. [3mThere is a model of [47mapply$[0m[3m and all of its scions that makes every warrant issued by [47mdefwarrant[0m[3m valid.[0m The proof of this is sketched in {``Limited Second-Order Functionality in a First-Order Setting'' | https://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore and fully fleshed out in the comment titled [47mEssay on Admitting a Model for Apply$ and the Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m. So there are four lessons here: [31;1mLesson 1:[0m When stating theorems involving [47mapply$[0m or scions on concrete user-defined functions, provide as additional hypotheses the warrants for all user-defined functions that [47mapply$[0m will encounter during the proof. This generally means you should add the hypothesis [47m(warrant [0m[3mfn1 fn2 ... fnk[0m[47m)[0m typically listing every function symbol that appears inside a quoted constant destined for [47mapply$[0m or [47mev$[0m in your conjecture. In particular, you should include every quoted function symbol appearing in a [47m:FN[0m slot of [47mapply$[0m or any scion, including every function symbol appearing in the body of any [47mLAMBDA[0m object or [47mlambda$[0m term or any [47muntil[0m, [47mwhen[0m, or body expressions of [47mloop$[0ms. (Macro expansion in [47mlambda$[0ms and [47mloop$[0ms may introduce function symbols not evident in the untranslated forms. See [47m:[0m[47m[translam][0m and [47m:[0m[47m[trans][0m.) [31;1mLesson 2:[0m You need not worry that adding warrant hypotheses makes your theorems vacuously valid! There is a model of [47mapply$[0m and all your scions in which all warrants are valid. [31;1mLesson 3:[0m If a proof involving [47mapply$[0m or a scion fails in a forcing round with a checkpoint whose conclusion is the warrant for some function, you should remember Lesson 1 and include the warrant for that function symbol in the hypotheses of your conjecture! That is, if you forget to supply a warrant but your conjecture is otherwise provable, ACL2's checkpoints will often remind you. (It is possible, in the absence of an explicit warrant hypothesis, for a proof to fail before the prover detects that only the warrant is missing.) [31;1mLesson 4:[0m If a proof involving [47mapply$[0m or a scion fails here are some things to think about. The basic question is whether something is ``wrong'' with one or more function symbols supposedly handled by [47mapply$[0m. You have to identify which quoted function symbols are not being simplified or expanded. Typically you'll see a checkpoint with a term like [47m(apply$ 'fn ...)[0m or [47m(ev$ '(fn ...) ...)[0m that you expect would be expanded into an actual call of [47mfn[0m. In that case, [47mfn[0m is of interest. You should realize that problems of these sorts can drastically slow down a proof attempt. We have seen example proofs where failure to simplify an [47mapply$[0m term slowed the proof-attempt down by several orders of magnitude. Here are some questions you should ask yourself about [47mfn[0m. * Is [47mfn[0m defined and in [47m:logic[0m mode? If [47mfn[0m is in [47m:program[0m mode it is treated by the prover as an undefined symbol. You should try to convert it [47m:logic[0m mode with [47m[verify-termination][0m. * Is [47mfn[0m warranted? If not, see [47m[defwarrant][0m. If [47mfn[0m is warranted then it is possible [47mfn[0m is not the problem. Maybe the warrant for [47mfn[0m was not provided as a hypothesis? Normally, missing warrant hypotheses are forced, but the proof might have failed for other reasons before the warrant for [47mfn[0m was forced. But you should ask whether forcing is disabled; see [47m[force][0m. * If you see [47m(apply$ 'fn ...)[0m then perhaps the rewrite rule [47mAPPLY$-fn[0m is disabled. That rule is the one that forces the warrant for [47mfn[0m and it was proved when [47mfn[0m was warranted. * Consider how the rewriter handles [47mapply$[0m terms, by reading [rewriting-calls-of-apply$-ev$-and-loop$-scions] and inspecting the enabled/disabled status of the runes mentioned there. These issues are discussed further in the documentation for [47m[warrant][0m. An unfortunate implication of the need for warrants is highlighted during the proofs of measure conjectures while admitting new definitions. Consider (defun$ my-cdr (x) (cdr x)) (defun$ my-len (x) (if (endp x) 0 (+ 1 (my-len (apply$ 'my-cdr (list x)))))) The definition of [47mmy-len[0m fails! The reason is that without the warrant for [47mmy-cdr[0m we cannot prove that the measure decreases in the recursion above. Unfortunately, there is no way to provide a warrant in a definition. At the moment we advise users to avoid the use of [47mapply$[0m --- and functions that use [47mapply$[0m --- in ``termination-critical'' roles. By that we mean do not use [47mapply$[0m if its properties are important to proofs of your measure conjectures. This is easy advice to implement in the case of [47mmy-len[0m, i.e., replace the recursive call above by [47m(my-len (my-cdr x))[0m. However, in more sophisticated definitions, e.g., where a [47m[loop$][0m is being used in recursive calls and the [47mloop$[0m calls user-defined functions in its body, following this advice means replacing that [47mloop$[0ms by a recursive function. That is unfortunate since the whole point of [47mloop$[0m is to avoid the introduction of such functions! We hope to address this limitation in the future, e.g., by making the definition of [47mmy-len[0m above be conditional on the warrant for [47mmy-cdr[0m. Guards and Guard Verification As noted, [47mapply$[0m has a guard of [47m(apply$-guard fn args)[0m and is itself guard verified. The guard is weak, basically requiring that [47mfn[0m either be a symbol or a [47mLAMBDA[0m object, that [47margs[0m be a true-list, and, when [47mfn[0m is a [47mLAMBDA[0m object, the length of the list of formals is equal to the length of [47margs[0m. To verify the guards of a scion you must make sure these properties hold of every application of anything in a [47m:FN[0m slot. Mainly you must make sure that every time a function object is [47mapply$[0md, it is applied to a list of the right length. Note also that [mixed-mode-functions], i.e., [47m:logic[0m mode functions that use [47m:program[0m mode functions in slots of [ilk] [47m:FN[0m or [47m:EXPR[0m, cannot be guard verified. But guards arise in another way in connection with [47mapply$[0m. How does [47m(apply$ fn args)[0m behave when [47mfn[0m has guards? The short answer is: logically speaking, [47mapply$[0m completely ignores guards. Guards in ACL2 are ``extra-logical.'' Let's define and warrant a well-guarded version of ``square'', (defun$ squ (n) (declare (xargs :guard (natp n))) (* n n)) [47mSqu[0m is guard verified. Now let's consider the little conjecture: (thm (implies (warrant squ) (equal (apply$ 'SQU (list x)) (* x x)))) Do we need need to require [47m(natp x)[0m? We would if the logical definition of [47mapply$[0m checked the guard of [47mfn[0m before interpreting it. But it does not check. It just behaves as specified above. So, regardless of whether the guard is satisfied or not, [47m(apply$ 'squ (list x))[0m naively expands (under the warrant) to [47m(squ x)[0m, from which the rest of the proof follows. However, now let's do a top-level evaluation of this [47mapply$[0m term: ACL2 !>(apply$ 'SQU (list 'NAN)) ACL2 Error in TOP-LEVEL: The guard for the function call (SQU N), which is (NATP N), is violated by the arguments in the call (SQU 'NAN). (Remember that ACL2's evaluation theory effectively assumes all warrants.) What happened? [47mApply$[0m expanded to [47m(SQU 'NAN)[0m and that caused the usual guard violation, given the default configuration of [47m[set-guard-checking][0m. A similar guard violation error is signaled if a guarded [47mLAMBDA[0m object is [47mapply$[0med to something violating its guard. But now consider (defun$ strange (x) (declare (xargs :guard t)) (apply$ 'SQU (list x))) This succeeds and [47mstrange[0m is now a guard verified, warranted function, with a guard of [47mT[0m. This might be surprising since (a) the guard of [47mstrange[0m tells us nothing about [47mx[0m, (b) [47mSQU[0m is applied to [47mx[0m, and (c) we know the guard of [47mSQU[0m requires its argument to be a [47mnatp[0m. Guard verification ignores the guards of a quoted function symbol being applied by a scion. This may be particularly offensive to one's intuitions when the scion is [47mapply$[0m itself, since the appropriate information is available. But consider a call of an arbitrary user-defined scion, e.g., [47m(my-scion 'SQU x)[0m. To what arguments will [47mmy-scion[0m [47mapply$[0m [47mSQU[0m? And how can the definition of [47mmy-scion[0m even specify what functional objects are acceptable in its first argument? This is a limitation suffered by ACL2 that a logic with a suitably expressive type system would not suffer. Our way of coping with it is to ignore the guard here and make sure that when [47mapply$[0m applies the function symbol executes it checks the guard of the symbol. Guard verification does not ignore guards of a quoted lambda object being [47mapply$[0med. Thus, for example, while [47mstrange[0m can be guard verified, (defun$ stranger (x) (declare (xargs :guard t)) (apply$ (lambda$ (e) (SQU e)) (list x))) cannot be guard verified, because guard verification tries to verify the guards of every [47mlambda[0m object in a [47m:FN[0m slot so that the [47mlambda[0m object can be marked as guard verified in the compiled [47mlambda[0m cache (see [47m[print-cl-cache][0m). But guards of [47mlambda[0m objects must be verified independently of the context in which they are used. To be specific, even (defun$ stranger (x) (declare (xargs :guard (natp x))) (apply$ (lambda$ (e) (SQU e)) (list x))) cannot be guard verified because the [47mlambda[0m object's guards are verified independently of the context. The [47mlambda[0m object must carry its own guard, as in (defun$ stranger (x) (declare (xargs :guard (natp x))) (apply$ (lambda$ (e) (declare (xargs :guard (natp e))) (SQU e)) (list x))) The last definition of stranger can be guard verified, the [47mlambda[0m object is so marked in the cache and compiled, and if that [47mlambda[0m object is used in any other context it is recognized as being guard verified. The guard for that [47mlambda[0m is checked when the object is [47mapply$[0med but if the check approves then the body of the [47mlambda[0m is executed as compiled code without further guard checking. While [47mapply$[0m is not evident in a [47m[loop$][0m statement like (loop$ for e in lst collect (SQU e)) similar treatment is given. In particular, the [47mloop$[0m above cannot be guard verified but (loop$ for e in lst collect :guard (natp e) (SQU e)) can be and is compiled into a Common Lisp [47mloop[0m. Recall also from the [47m[loop$][0m documentation that the formal semantics of the above statement is essentially (collect$ (lambda$ (e) (declare (xargs :guard (natp e))) (SQU e)) lst) so guard verification of the [47mloop$[0m also compiles and marks that [47mlambda[0m expression as guard verified. So now let's return to consideration of (defun$ strange (x) (declare (xargs :guard t)) (apply$ 'SQU (list x))) which we've seen is guard verified despite the fact that [47mSQU[0m expects a natural number and will not necessarily be given one. What happens when we call [47mstrange[0m on a non-natural? ACL2 !>(strange 'NAN) ACL2 Error in TOP-LEVEL: The guard for the function call (SQU N), which is (NATP N), is violated by the arguments in the call (SQU 'NAN). ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (strange 'nan) ACL2 Error in ACL2-INTERFACE: The guard for the function call (SQU N), which is (NATP N), is violated by the arguments in the call (SQU 'NAN). We see that we can provoke a guard violation with [47mstrange[0m even though it is guard verified with a guard of [47mT[0m. Furthermore, we get the error both in the ACL2 read-eval-print loop and in the raw Lisp under ACL2. (Be careful though about exiting the ACL2 loop; see [q].) This might at first violate your understanding of the link between ACL2 and Common Lisp. Naively, a guard verified ACL2 function with a guard of [47mT[0m never causes a runtime error in Common Lisp. But that's not quite what the guarantee is. Such a function will never cause a hard Lisp error, other than possibly resource errors like running out of memory or stack space. Neither of the errors above were signaled by Common Lisp. They were ``soft'' ACL2 errors. In particular, when [47mapply$[0m calls [47msqu[0m above, even when running in raw Lisp, it actually calls the executable counterpart of [47msqu[0m, which checks guards at runtime and executes properly under the ACL2 axioms. ACL2 !>(set-guard-checking :none) Turning off guard checking entirely. ACL2 >(strange 'nan) 0 The last evaluation can be explained by the fact that ACL2 multiplication defaults non-numbers to 0. We discuss the evaluation of ground [47mapply$[0m terms in the evaluation theory further below. When the guard conjectures of a function are proved all necessary warrants are assumed. This is unlike what happens when the measure conjectures are proved. The reason we can assume warrants during guard verification is that guard verification is relevant in the evaluation theory, where attachments are allowed and all warrants have true attachments. Top-Level Evaluation of Apply$ As noted, ACL2's evaluation theory implicitly assumes all warrants produced by [47m[defwarrant][0m. See [guarantees-of-the-top-level-loop]. Since top-level evaluation in ACL2 is conducted in the evaluation theory, ground calls of [47mapply$[0m --- whether literally in top-level input to the ACL2 read-eval-print loop or hidden inside scions called from the top-level --- can be evaluated on quoted warranted function symbols and [47m[lambda$][0m expressions --- provided the [tame]ness restrictions are met. This is in contrast to opportunities for evaluation of ground [47mapply$[0m expressions arising in proofs, where warrant hypotheses must be explicit. In this section we focus on calls of [47mapply$[0m arising in the evaluation theory. We start with a discussion of the use of [47mapply$[0m with warranted [47m:logic[0m mode functions. We then describe how [47mapply$[0m handles badged [47m:program[0m mode functions. Note that a mere badge is [3mnot[0m sufficient for evaluation when using [47mapply$[0m on a [47m:logic[0m mode function that is not warranted; see [47m[defbadge][0m and [guarantees-of-the-top-level-loop] for discussion of this case. In short: evaluation involving [47m:logic[0m mode functions is expected to respect the evaluation theory, and while [47mdefwarrant[0m extends the evaluation theory appropriately, [47mdefbadge[0m does not. Evaluation of [47mapply$[0m terms in the evaluation theory respects guards on quoted function symbols and [47m[lambda$][0m expressions (which is to say, on the quoted well-formed [47mLAMBDA[0m objects that [47m[lambda$][0m produces). So consider a call of [47mapply$[0m on [47mfn[0m and [47margs[0m in the evaluation theory, where [47mfn[0m is a warranted function symbol or a well-formed (and thus tame) [47mLAMBDA[0m object. Here's what happens. Except where noted, the description below applies both to warranted [47m:logic[0m and badged [47m:program[0m mode functions. [47mApply$[0m determines whether [47mfn[0m's tameness restrictions are met by [47margs[0m. Tameness is a syntactic property and so can be checked. If the function's tameness restrictions are not met, an error is caused. If the tameness restrictions are met, [47mapply$[0m determines whether [47mfn[0m has been guard verified. In the case of function symbols this is a simple lookup on the property list of [47mfn[0m. (Of course, this check fails for [47m:program[0m mode functions.) In the case of [47mLAMBDA[0m objects it is a cache query (see [47m[print-cl-cache][0m) and if the query reveals that we have not yet tried to verify the guards of this [47mLAMBDA[0m object, [47mapply$[0m uses tau reasoning alone (see [introduction-to-the-tau-system]) to try to verify the guard conjectures. [31;1mNote:[0mAn important distinction between the runtime handling of function symbols versus [47mLAMBDA[0m objects by [47mapply$[0m is that function symbols can only be guard verified by prior events, e.g., the introductory [47m[defun][0m or a subsequent [47mverify-guards[0m, but [47mapply$[0m tries to verify the guards of [47mLAMBDA[0m objects [3mon the fly[0m! The reason for this distinction is that we anticipate that many [47mLAMBDA[0m objects will not be associated with any event. For example, an ACL2 macro might generate a call of a scion on a never-before-seen [47mLAMBDA[0m object and that [47mLAMBDA[0m object may only be seen by the top-level evaluator. We discuss this further in [47m[verify-guards][0m If [47mfn[0m is guard verified, [47mapply$[0m next checks whether [47mfn[0m's guard holds of the actuals in [47margs[0m. This is done by evaluation of the compiled code for the guard on [47margs[0m. If the guard check of [47margs[0m succeeds, a compiled version of [47mfn[0m is applied to [47margs[0m. If the check fails, a guard violation is signaled or else the application of [47mfn[0m to [47margs[0m is interpreted under the definitional axioms of [47mapply$[0m and [47mev$[0m, depending on how [47m[set-guard-checking][0m has been configured. Finally, if [47mfn[0m is not guard verified, the application of [47mfn[0m to [47margs[0m is interpreted under the definitional axioms of [47mapply$[0m and [47mev$[0m. We discuss the cache that supports [47mLAMBDA[0m application in [47m[print-cl-cache][0m. See also the discussion of guard verification in [47m[lambda$][0m. It should be noted that a [47mLAMBDA[0m object can also be guard verified using the [47m[verify-guards][0m event. This brings the full power of the prover to bear on the guard verification of the [47mLAMBDA[0m object, instead of relying just on the tau system. Users are accustomed to executing [47m:program[0m mode functions at the top-level of the ACL2 read-eval-print loop. Indeed, the prover itself and the various event commands are mostly written in [47m:program[0m mode. Furthermore, the evaluation theory is described as an extension of the proof theory, i.e., as an axiomatic theory. And yet no part of that axiomatization explains how [47m:program[0m mode functions are run! It simply isn't important. The implementation supports it and no questions are asked. We, the implementors of ACL2, view top-level evaluation of [47m:program[0m mode functions as a convenience not affecting the consistency of the proof theory. No inconsistency results from starting a non-terminating computation because you can never inspect the result, whereas if you added the corresponding definition as an axiom you might be able to prove something contradictory. So we regard the seamless execution of [47m:program[0m mode functions as a convenience to the user who might use them to inspect the ACL2 logical world, gather data, experiment with constrained formal models by attaching executable code to unspecified functions, prototype something to be formalized, etc. In that spirit, we have arranged for [47mapply$[0m to handle [47m:program[0m mode functions [3mprovided they have badges[0m. Badges are critical because it means that execution of the functions won't ``go outside the sandbox.'' However, [47mapply$[0m runs [47m:program[0m mode functions in [47m[safe-mode][0m to ensure the functional substitutivity of [47mapply$[0m: identical calls must always yield identical results. It may seem counterintuitive that a top-level [47mapply$[0m of a [47m:logic[0m mode function cannot be executed unless [47mdefwarrant[0m has succeeded but a top-level [47mapply$[0m of a [47m:program[0m mode function can be executed. As noted earlier, the reason is simple: execution of [47m:logic[0m mode functions is justified by the axioms of the evaluation theory while no such assurances are offered for [47m:program[0m mode functions. Logical Definitions In the following definitions, [47mapply$-userfn[0m is an undefined function that is constrained by warrants to describe the tameness requirement and behavior of [47mapply$[0m on specific function symbols. The functions [47muntame-apply$[0m and [47muntame-ev$[0m are simply undefined functions for giving unspecified values when untame objects are being used. [31;1mFunction: [0m<apply$> (defun apply$ (fn args) (declare (xargs :guard (apply$-guard fn args))) (cond ((consp fn) (apply$-lambda fn args)) ((apply$-primp fn) (apply$-prim fn args)) ((eq fn 'badge) (badge (car args))) ((eq fn 'tamep) (tamep (car args))) ((eq fn 'tamep-functionp) (tamep-functionp (car args))) ((eq fn 'suitably-tamep-listp) (ec-call (suitably-tamep-listp (car args) (cadr args) (caddr args)))) ((eq fn 'apply$) (if (tamep-functionp (car args)) (ec-call (apply$ (car args) (cadr args))) (untame-apply$ fn args))) ((eq fn 'ev$) (if (tamep (car args)) (ev$ (car args) (cadr args)) (untame-apply$ fn args))) (t (apply$-userfn fn args)))) [31;1mFunction: [0m<apply$-lambda> (defun apply$-lambda (fn args) (declare (xargs :guard (apply$-lambda-guard fn args))) (apply$-lambda-logical fn args)) [31;1mMacro: [0m<apply$-lambda-logical> (defmacro apply$-lambda-logical (fn args) (declare (xargs :guard (symbolp fn))) (cons 'ev$ (cons (cons 'lambda-object-body (cons fn 'nil)) (cons (cons 'ec-call (cons (cons 'pairlis$ (cons (cons 'lambda-object-formals (cons fn 'nil)) (cons args 'nil))) 'nil)) 'nil)))) [31;1mFunction: [0m<ev$> (defun ev$ (x a) (declare (xargs :guard t)) (cond ((not (tamep x)) (untame-ev$ x a)) ((variablep x) (ec-call (cdr (ec-call (assoc-equal x a))))) ((fquotep x) (cadr x)) ((eq (car x) 'if) (if (ev$ (cadr x) a) (ev$ (caddr x) a) (ev$ (cadddr x) a))) ((eq (car x) 'apply$) (apply$ 'apply$ (list (cadr (cadr x)) (ev$ (caddr x) a)))) ((eq (car x) 'ev$) (apply$ 'ev$ (list (cadr (cadr x)) (ev$ (caddr x) a)))) (t (apply$ (car x) (ev$-list (cdr x) a))))) [31;1mFunction: [0m<ev$-list> (defun ev$-list (x a) (declare (xargs :guard t)) (cond ((atom x) nil) (t (cons (ev$ (car x) a) (ev$-list (cdr x) a))))) [31;1mFunction: [0m<apply$-guard> (defun apply$-guard (fn args) (declare (xargs :guard t)) (if (atom fn) (true-listp args) (apply$-lambda-guard fn args))) [31;1mFunction: [0m<apply$-lambda-guard> (defun apply$-lambda-guard (fn args) (declare (xargs :guard t)) (and (consp fn) (consp (cdr fn)) (true-listp args) (equal (len (cadr fn)) (length args)))) Subtopics [Apply$-guard] The guard on [47mapply$[0m [Apply$-lambda] Used by [47mapply$[0m on [47mLAMBDA[0m objects [Apply$-lambda-guard] The guard on [47mapply$-lambda[0m [Apply$-userfn] Undefined function used by [47mapply$[0m on non-primitives [Badge] Syntactic requirements on a function symbol to be used by [47mapply$[0m [Badge-userfn] Undefined function used by [47mbadge[0m on non-primitives [Defbadge] Issue a badge for a function so [47m[apply$][0m can evaluate with it [Defun$] Define a function symbol and generate a warrant [Defwarrant] Issue a warrant for a function so [47m[apply$][0m can use it in proofs [Ev$] Evaluate a tame expression using [47mapply$[0m [Explain-giant-lambda-object] print data related to a large lambda object [Fn-equal] Equivalence relation on tame functions [Gratuitous-lambda-object-restrictions] Enforcement of logically unnecessary restrictions on [47m:FN[0m slots [Ilk] Indicator of how an argument is used [Introduction-to-apply$] Background knowledge on how to use [47m[apply$][0m, [47m[defwarrant][0m, etc. [L<] Ordering on naturals or lists of naturals [Lambda] Lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions [Lambda$] Lambda object constructor for use with [47mapply$[0m [Mixed-mode-functions] [47m:[0m[47m[logic][0m mode functions can [47m[apply$][0m [47m:[0m[47m[program][0m mode functions [Print-cl-cache] Information about the cache supporting [47mapply$[0m [Rewriting-calls-of-apply$-ev$-and-loop$-scions] How the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m terms [Scion] A function ancestrally dependent on [47mapply$[0m [Tame] Definitions of the various notions of tameness [Translam] Print the translation of a lambda$ expression [Warrant] Giving [47m[apply$][0m permission to handle a user-defined function in proofs [Well-formed-lambda-objectp] Predicate for recognizing well-formed [47mLAMBDA[0m objects") (apply$-guard (apply$) "The guard on [47mapply$[0m The guard on [47m(apply$ fn lst)[0m is [47m(apply$-guard fn lst)[0m which is extraordinarily weak. [31;1mFunction: [0m<apply$-guard> (defun apply$-guard (fn args) (declare (xargs :guard t)) (if (atom fn) (true-listp args) (apply$-lambda-guard fn args))) where [31;1mFunction: [0m<apply$-lambda-guard> (defun apply$-lambda-guard (fn args) (declare (xargs :guard t)) (and (consp fn) (consp (cdr fn)) (true-listp args) (equal (len (cadr fn)) (length args)))) This guard is just strong enough to allow the definitions of the functions in the [47mapply$[0m clique to be guard verified. It does not guarantee that [47mfn[0m is tame or well-formed or that [47margs[0m satisfy the guard of [47mfn[0m. The last condition is in fact impossible to state given the untyped nature of ACL2. Thus, [47m(apply$ fn args)[0m has to check tameness, well-formedness, guard verified, and that [47mfn[0m's guard is satisfied by [47margs[0m when the [47mapply$[0m is executed in the evaluation theory. The issue of guards and guard verification of definitions involving [47mapply$[0m is further discussed in [47m[apply$][0m and in [47m[verify-guards][0m.") (apply$-lambda (apply$) "Used by [47mapply$[0m on [47mLAMBDA[0m objects When [47mapply$[0m is given a [47mconsp[0m object as its first argument it treats it as a [47mLAMBDA[0m expression and calls this function to apply it. This function evaluates the body of the object with [47mev$[0m under an alist binding the formals of the object to the actuals. See [47m[apply$][0m for details.") (apply$-lambda-guard (apply$) "The guard on [47mapply$-lambda[0m The guard on [47m(apply$-lambda fn lst)[0m is [47m(apply$-lambda-guard fn lst)[0m which is extraordinarily weak. [31;1mFunction: [0m<apply$-lambda-guard> (defun apply$-lambda-guard (fn args) (declare (xargs :guard t)) (and (consp fn) (consp (cdr fn)) (true-listp args) (equal (len (cadr fn)) (length args)))) This guard is just strong enough to allow the definitions of the functions in the [47mapply$[0m clique to be guard verified. It does not guarantee that [47mfn[0m is [47mtame[0m or well-formed or that [47margs[0m satisfy the guard of [47mfn[0m. The last condition is in fact impossible to state given the untyped nature of ACL2. Thus, [47m(apply$ fn args)[0m has to check tameness, well-formedness, guard verified and that [47mfn[0m's guard is satisfied by [47margs[0m when the [47mapply$[0m is executed in the evaluation theory. The issue of guards and guard verification of definitions involving [47mapply$[0m is further discussed in [47m[apply$][0m and in [47m[verify-guards][0m.") (apply$-userfn (apply$) "Undefined function used by [47mapply$[0m on non-primitives When [47mapply$[0m is given a non-primitive function symbol it calls this function to determine the results of applying that symbol to the given arguments. But this function is undefined. In the proof theory, its value on a given function symbol [47mfn[0m is specified, if at all, by the [47m[warrant][0m for [47mfn[0m which must be available as a hypothesis in the formula being proved. In the evaluation theory, [47mapply$-userfn[0m has an attachment that makes it behave as though all warrants are assumed. See [47m[apply$][0m for details.") (apropos (pointers) "See [finding-documentation].") (architecture-of-the-prover (introduction-to-the-theorem-prover) "A simple overview of how the prover works Six built-in proof techniques are used by ACL2 to decompose the goal formula into subgoals. * [3msimplification[0m --- decision procedures and rewriting with previously proved rules, but actually including a host of other techniques under your control. Simplification is the only proof technique that can reduce a formula to 0 subgoals (i.e., prove it) rather than just transform it to other formulas. The predominant activity in most proofs is simplification. There are many ways you can affect what the simplifier does to your formulas. Good users spend most of their time thinking about how to control the simplifier. * [3mdestructor elimination[0m --- getting rid of ``destructor terms'' like [47m(CAR X)[0m and [47m(CDR X)[0m by replacing a variable, e.g., [47mX[0m, by a ``constructor'' term, e.g., [47m(CONS A B)[0m. But you can tell ACL2 about new destructor/constructor combinations. * [3mfertilization[0m --- using an equivalence hypothesis by substituting one side for the other in the goal. When under induction, ACL2 may decide to restrict the substitution as follows, using its so-called [3mcross-fertilization[0m heuristic: substitute only into one side of the conclusion, thus using an inductive hypothesis in preparation for possible generalization in advance of another induction. Note that cross-fertilization is used only when generalization is enabled: with the hint [47m:do-not '(generalize)[0m, only full fertilization is applied. * [3mgeneralization[0m --- replacing a term by a new variable and restricting the new variable to have some of the properties of the term. You can control the restrictions imposed on the new variable. This is a heuristic that prepares the goal for another induction. * [3melimination of irrelevance[0m --- throwing away unnecessary hypotheses. This is a heuristic that prepares the goal for another induction. * [3minduction[0m --- selecting an induction scheme to prove a formula. Inductions are ``suggested'' by the recursive functions appearing in the formula. But you can control what inductions are suggested by terms. But you can add additional techniques, called [3mclause processors[0m. The various techniques are tried in turn, with simplification first and induction last. Each technique reports one of three outcomes: it found nothing to change (i.e., the technique doesn't [3mapply[0m to that subgoal), it decided to abort the proof attempt (typically because there is reason to believe the proof is failing), or it decomposed the goal into [3mk[0m subgoals. The last outcome has a special case: if [3mk[0m is 0 then the technique proved the goal. Whenever [3mk[0m is non-0, the process starts over again with simplification on each of the [3mk[0m subgoals. However, it saves up all the subgoals for which induction is the only proof technique left to try. That way you see how it performs on every base case and induction step of one induction before it launches into another induction. It runs until you or one of the proof techniques aborts the proof attempt or until all subgoals have been proved. Note that if simplification produces a subgoal, that subgoal is re-simplified. This process continues until the subgoal cannot be simplified further. Only then is the next proof technique tried. Such subgoals are said to be [3mstable under simplification[0m. While this is happening, the prover prints an English narrative describing the process. Basically, after each goal is printed, the system prints an English paragraph that names the next applicable proof technique, gives a brief description of what that technique does to the subgoal, and says how many new subgoals are produced. Then each subgoal is dealt with in turn. If the proof is successful, you could read this log as a proof of the conjecture. But output from successful proofs is generally never read because it is not important to The Method described in [introduction-to-the-theorem-prover]. The output of an unsuccessful proof attempt concludes with some [3mkey[0m [3mcheckpoints[0m which usually bear looking at. For more information about how ACL2 orchestrates its proof techniques, see [hints-and-the-waterfall].") (aref1 (arrays acl2-built-ins) "Access the elements of a 1-dimensional array Example Form: (aref1 'delta1 a (+ i k)) General Form: (aref1 name alist index) where [47mname[0m is a symbol, [47malist[0m is a 1-dimensional array and [47mindex[0m is a legal index into [47malist[0m. This function returns the value associated with [47mindex[0m in [47malist[0m, or else the default value of the array. See [arrays] for details. This function executes in virtually constant time if [47malist[0m is in fact the ``semantic value'' associated with [47mname[0m (see [arrays]). When it is not, [47maref1[0m must do a linear search through [47malist[0m. In that case the correct answer is returned but a [31;1mslow array[0m comment is printed to the comment window. See [slow-array-warning]. [31;1mFunction: [0m<aref1> (defun aref1 (name l n) (declare (xargs :guard (and (array1p name l) (integerp n) (>= n 0) (< n (car (dimensions name l)))))) (let ((x (and (not (eq n :header)) (assoc n l)))) (cond ((null x) (default name l)) (t (cdr x)))))") (aref2 (arrays acl2-built-ins) "Access the elements of a 2-dimensional array Example Form: (aref2 'delta1 a i j) General Form: (aref2 name alist i j) where [47mname[0m is a symbol, [47malist[0m is a 2-dimensional array and [47mi[0m and [47mj[0m are legal indices into [47malist[0m. This function returns the value associated with [47m(i . j)[0m in [47malist[0m, or else the default value of the array. See [arrays] for details. This function executes in virtually constant time if [47malist[0m is in fact the ``semantic value'' associated with [47mname[0m (see [arrays]). When it is not, [47maref2[0m must do a linear search through [47malist[0m. In that case the correct answer is returned but a [31;1mslow array[0m comment is printed to the comment window. See [slow-array-warning]. [31;1mFunction: [0m<aref2> (defun aref2 (name l i j) (declare (xargs :guard (and (array2p name l) (integerp i) (>= i 0) (< i (car (dimensions name l))) (integerp j) (>= j 0) (< j (cadr (dimensions name l)))))) (let ((x (assoc2 i j l))) (cond ((null x) (default name l)) (t (cdr x)))))") (arglistp (pointers) "See [system-utilities].") (args (documentation) "[47margs[0m, [47m[guard][0m, [47mtype[0m, [47m[constraint][0m, etc., of a function symbol Example: :args assoc-eq [47mArgs[0m takes one argument, a symbol which must be the name of a function or macro, and prints out some information about it including the formal parameters, the [guard] expression, the output [signature], the deduced type, the [constraint] (if any), and its [47m[badge][0m and [47m[warrant][0m, if any.") (arities-okp (acl2-built-ins) "check the arities of given function symbols Example: (arities-okp '((IF . 3) (CAR . 1) (CONS . 2)) (w state)) General Form: (arities-okp alist w) where [47malist[0m is a [47m[symbol-alistp][0m and [47mw[0m is an ACL2 logical [world]. The alist is presumed to pair [47m:[0m[47m[logic][0m-mode function symbols with arities. The result is [47mt[0m or [47mnil[0m according to whether each symbol in the alist is a [47m:logic[0m-mode function symbol with the associated arity as its [47m[arity][0m in [47mw[0m. See [well-formedness-guarantee]. [31;1mFunction: [0m<arities-okp> (defun arities-okp (user-table w) (declare (xargs :guard (and (symbol-alistp user-table) (plist-worldp-with-formals w)))) (cond ((endp user-table) t) (t (and (equal (arity (car (car user-table)) w) (cdr (car user-table))) (logicp (car (car user-table)) w) (arities-okp (cdr user-table) w)))))") (arity (acl2-built-ins) "number of arguments of a function symbol Examples: (arity 'IF (w state)) (arity '(LAMBDA (X) (CONS X X)) (w state)) General Form: (arity fn w) where [47mfn[0m is a function symbol or a lambda expression and [47mw[0m is an ACL2 logical [world]. The result is the number of arguments the function or lambda expression takes, or [47mnil[0m if the function symbol is not defined in [47mw[0m. See [arity+] for a variant of [47marity[0m with a stronger [guard].") (array (pointers) "See [arrays].") (array1p (arrays acl2-built-ins) "Recognize a 1-dimensional array Example Form: (array1p 'delta1 a) General Form: (array1p name alist) where [47mname[0m and [47malist[0m are arbitrary objects. This function returns [47mt[0m if [47malist[0m is a 1-dimensional ACL2 array. Otherwise it returns [47mnil[0m. The function operates in constant time if [47malist[0m is the semantic value of [47mname[0m. See [arrays]. [31;1mFunction: [0m<array1p> (defun array1p (name l) (declare (xargs :guard t)) (and (symbolp name) (alistp l) (let ((header-keyword-list (cdr (assoc-eq :header l)))) (and (keyword-value-listp header-keyword-list) (let ((dimensions (cadr (assoc-keyword :dimensions header-keyword-list))) (maximum-length (cadr (assoc-keyword :maximum-length header-keyword-list)))) (and (true-listp dimensions) (equal (length dimensions) 1) (integerp (car dimensions)) (integerp maximum-length) (< 0 (car dimensions)) (< (car dimensions) maximum-length) (<= maximum-length (array-maximum-length-bound)) (bounded-integer-alistp l (car dimensions))))))))") (array2p (arrays acl2-built-ins) "Recognize a 2-dimensional array Example Form: (array2p 'delta1 a) General Form: (array2p name alist) where [47mname[0m and [47malist[0m are arbitrary objects. This function returns [47mt[0m if [47malist[0m is a 2-dimensional ACL2 array. Otherwise it returns [47mnil[0m. The function operates in constant time if [47malist[0m is the semantic value of [47mname[0m. See [arrays]. [31;1mFunction: [0m<array2p> (defun array2p (name l) (declare (xargs :guard t)) (and (symbolp name) (alistp l) (let ((header-keyword-list (cdr (assoc-eq :header l)))) (and (keyword-value-listp header-keyword-list) (let ((dimensions (cadr (assoc-keyword :dimensions header-keyword-list))) (maximum-length (cadr (assoc-keyword :maximum-length header-keyword-list)))) (and (true-listp dimensions) (equal (length dimensions) 2) (let ((d1 (car dimensions)) (d2 (cadr dimensions))) (and (integerp d1) (integerp d2) (integerp maximum-length) (< 0 d1) (< 0 d2) (< (* d1 d2) maximum-length) (<= maximum-length (array-maximum-length-bound)) (bounded-integer-alistp2 l d1 d2)))))))))") (arrays (programming) "ACL2 arrays and operations on them Below we begin a detailed presentation of ACL2 arrays. ACL2's single-threaded objects (see [stobj]) provide a similar functionality that is generally more efficient when there are updates (writes), but is also more restrictive. See [arrays-example] for a brief introduction illustrating the use of ACL2 arrays. ACL2 provides relatively efficient 1- and 2-dimensional arrays. Arrays are awkward to provide efficiently in an applicative language because the programmer rightly expects to be able to ``modify'' an array object with the effect of changing the behavior of the element accessing function on that object. This, of course, does not make any sense in an applicative setting. The element accessing function is, after all, a function, and its behavior on a given object is immutable. To ``modify'' an array object in an applicative setting we must actually produce a new array object. Arranging for this to be done efficiently is a challenge to the implementors of the language. In addition, the programmer accustomed to the von Neumann view of arrays must learn how to use immutable applicative arrays efficiently. In this note we explain 1-dimensional arrays. In particular, we explain briefly how to create, access, and ``modify'' them, how they are implemented, and how to program with them. 2-dimensional arrays are dealt with by analogy. The Logical Description of ACL2 Arrays An ACL2 1-dimensional array is an object that associates arbitrary objects with certain integers, called ``indices.'' Every array has a dimension, [47mdim[0m, which is a positive integer. The indices of an array are the consecutive integers from [47m0[0m through [47mdim-1[0m. To obtain the object associated with the index [47mi[0m in an array [47ma[0m, one uses [47m(aref1 name a i)[0m. [47mName[0m is a symbol that is irrelevant to the semantics of [47m[aref1][0m but affects the speed with which it computes. We will talk more about array ``names'' later. To produce a new array object that is like [47ma[0m but which associates [47mval[0m with index [47mi[0m, one uses [47m(aset1 name a i val)[0m. An ACL2 1-dimensional array is actually an alist. There is no special ACL2 function for creating arrays; they are generally built with the standard list processing functions [47m[list][0m and [47m[cons][0m. However, there is a special ACL2 function, called [47m[compress1][0m, for speeding up access to the elements of such an alist. We discuss [47m[compress1][0m later. One element of the alist must be the ``header'' of the array. The [header] of a 1-dimensional array with dimension [47mdim[0m is of the form: (:HEADER :DIMENSIONS (dim) :MAXIMUM-LENGTH max :DEFAULT obj ; optional :NAME name ; optional :ORDER order ; optional values are < (the default), >, or :none/nil ). [47mObj[0m may be any object and is called the ``default value'' of the array. [47m[Max][0m must be an integer greater than [47mdim[0m. [47mName[0m must be a symbol. The [47m:[0m[47m[default][0m and [47m:name[0m entries are optional; if [47m:[0m[47m[default][0m is omitted, the default value is [47mnil[0m. The function [47m[header][0m, when given a name and a 1- or 2-dimensional array, returns the [header] of the array. The functions [47m[dimensions][0m, [47m[maximum-length][0m, and [47m[default][0m are similar and return the corresponding fields of the [header] of the array. The role of the [47m:[0m[47m[dimensions][0m field is obvious: it specifies the legal indices into the array. The roles played by the [47m:[0m[47m[maximum-length][0m and [47m:[0m[47m[default][0m fields are described below. Aside from the [header], the other elements of the alist must each be of the form [47m(i . val)[0m, where [47mi[0m is an integer and [47m0 <= i < dim[0m, and [47mval[0m is an arbitrary object. The [47m:order[0m field of the header is ignored for 2-dimensional arrays. For 1-dimensional arrays, it specifies the order of keys ([47mi[0m, above) when the array is compressed as with [47m[compress1][0m, as described below. An [47m:order[0m of [47m:none[0m or [47mnil[0m specifies no reordering of the alist by [47m[compress1][0m, and an order of [47m>[0m specifies reordering by [47m[compress1][0m so that keys are in descending order. Otherwise, the alist is reordered by [47m[compress1][0m so that keys are in ascending order. [47m(Aref1 name a i)[0m is [guard]ed so that [47mname[0m must be a symbol, [47ma[0m must be an array and [47mi[0m must be an index into [47ma[0m. The value of [47m(aref1 name a i)[0m is either [47m(cdr (assoc i a))[0m or else is the default value of [47ma[0m, depending on whether there is a pair in [47ma[0m whose [47m[car][0m is [47mi[0m. Note that [47mname[0m is irrelevant to the value of an [47m[aref1][0m expression. You might [47m:pe aref1[0m to see how simple the definition is. [47m(Aset1 name a i val)[0m is [guard]ed analogously to the [47m[aref1][0m expression. The value of the [47m[aset1][0m expression is essentially [47m(cons (cons i val) a)[0m. Again, [47mname[0m is irrelevant. Note [47m(aset1 name a i val)[0m is an array, [47ma'[0m, with the property that [47m(aref1 name a' i)[0m is [47mval[0m and, except for index [47mi[0m, all other indices into [47ma'[0m produce the same value as in [47ma[0m. Note also that if [47ma[0m is viewed as an alist (which it is) the pair ``binding'' [47mi[0m to its old value is in [47ma'[0m but ``covered up'' by the new pair. Thus, the length of an array grows by one when [47m[aset1][0m is done. Because [47m[aset1][0m covers old values with new ones, an array produced by a sequence of [47m[aset1][0m calls may have many irrelevant pairs in it. The function [47m[compress1][0m can remove these irrelevant pairs. Thus, [47m(compress1 name a)[0m returns an array that is equivalent (vis-a-vis [47m[aref1][0m) to [47ma[0m but which may be shorter. For technical reasons, the alist returned by [47m[compress1][0m may also list the pairs in a different order than listed in [47ma[0m. To prevent arrays from growing excessively long due to repeated [47m[aset1][0m operations, [47m[aset1][0m essentially calls [47m[compress1][0m on the new alist whenever the length of the new alist exceeds the [47m:[0m[47m[maximum-length][0m entry, [47m[max][0m, in the [header] of the array. See the definition of [47m[aset1][0m (for example by using [47m:[0m[47m[pe][0m). This is primarily just a mechanism for freeing up [47m[cons][0m space consumed while doing [47m[aset1][0m operations. Note however that this [47m[compress1][0m call is replaced by a hard error if the header specifies an [47m:order[0m of [47m:none[0m or [47mnil[0m. This completes the logical description of 1-dimensional arrays. 2-dimensional arrays are analogous. The [47m:[0m[47m[dimensions][0m entry of the [header] of a 2-dimensional array should be [47m(dim1 dim2)[0m. A pair of indices, [47mi[0m and [47mj[0m, is legal iff [47m0 <= i < dim1[0m and [47m0 <= j < dim2[0m. The [47m:[0m[47m[maximum-length][0m must be greater than [47mdim1*dim2[0m. [47m[Aref2][0m, [47m[aset2][0m, and [47m[compress2][0m are like their counterparts but take an additional [47mindex[0m argument. Finally, the pairs in a 2-dimensional array are of the form [47m((i . j) . val)[0m. The Implementation of ACL2 Arrays Very informally speaking, the function [47m[compress1][0m ``creates'' an ACL2 array that provides fast access, while the function [47m[aref1][0m ``maintains'' fast access. We now describe this informal idea more carefully. [47m[Aref1][0m is essentially [47m[assoc][0m. If [47m[aref1][0m were implemented naively the time taken to access an array element would be linear in the dimension of the array and the number of ``assignments'' to it (the number of [47m[aset1][0m calls done to create the array from the initial alist). This is intolerable; arrays are ``supposed'' to provide constant-time access and change. The apparently irrelevant names associated with ACL2 arrays allow us to provide constant-time access and change when arrays are used in ``conventional'' ways. The implementation of arrays makes it clear what we mean by ``conventional.'' Recall that array names are symbols. Behind the scenes, ACL2 associates two objects with each ACL2 array name. The first object is called the ``semantic value'' of the name and is an alist. The second object is called the ``raw lisp array'' and is a Common Lisp array. When [47m(compress1 name alist)[0m builds a new alist, [47ma'[0m, it sets the semantic value of [47mname[0m to that new alist. Furthermore, it writes into a Common Lisp array all of the index/value pairs of [47ma'[0m, initializing unassigned indices with the default value. In general this is a new array, which becomes the raw lisp array of [47mname[0m. However, if a raw lisp array is already associated with [47mname[0m and is at least as long as the dimension specified in the [header], then that array is reused and all indices out of range are ignored. (Such reuse can be avoided; see [flush-compress] for how to remove the existing association of a raw lisp array with a name.) Either way, [47m[compress1][0m then returns [47ma'[0m, the semantic value, as its result, as required by the definition of [47m[compress1][0m. When [47m(aref1 name a i)[0m is invoked, [47m[aref1][0m first determines whether the semantic value of [47mname[0m is [47ma[0m (i.e., is [47m[eq][0m to the alist [47ma[0m). If so, [47m[aref1][0m can determine the [47mi[0mth element of [47ma[0m by invoking Common Lisp's [47maref[0m function on the raw lisp array associated with name. Note that no linear search of the alist [47ma[0m is required; the operation is done in constant time and involves retrieval of two global variables, an [47m[eq][0m test and [47mjump[0m, and a raw lisp array access. In fact, an ACL2 array access of this sort is about 5 times slower than a C array access. On the other hand, if [47mname[0m has no semantic value or if it is different from [47ma[0m, then [47m[aref1][0m determines the answer by linear search of [47ma[0m as suggested by the [47massoc-like[0m definition of [47m[aref1][0m. Thus, [47m[aref1][0m always returns the axiomatically specified result. It returns in constant time if the array being accessed is the current semantic value of the name used. The ramifications of this are discussed after we deal with [47m[aset1][0m. When [47m(aset1 name a i val)[0m is invoked, [47m[aset1][0m does two [47m[cons][0mes to create the new array. Call that array [47ma'[0m. It will be returned as the answer. (In this discussion we ignore the case in which [47m[aset1][0m does a [47m[compress1][0m.) However, before returning, [47m[aset1][0m determines if [47mname[0m's semantic value is [47ma[0m. If so, it makes the new semantic value of [47mname[0m be [47ma'[0m and it smashes the raw lisp array of [47mname[0m with [47mval[0m at index [47mi[0m, before returning [47ma'[0m as the result. Thus, after doing an [47m[aset1][0m and obtaining a new semantic value [47ma'[0m, all [47m[aref1][0ms on that new array will be fast. Any [47m[aref1][0ms on the old semantic value, [47ma[0m, will be slow. To understand the performance implications of this design, consider the chronological sequence in which ACL2 (Common Lisp) evaluates expressions: basically inner-most first, left-to-right, call-by-value. An array use, such as [47m(aref1 name a i)[0m, is ``fast'' (constant-time) if the alist supplied, [47ma[0m, is the value returned by the most recently executed [47m[compress1][0m or [47m[aset1][0m on the name supplied. In the functional expression of ``conventional'' array processing, all uses of an array are fast. The [47m:name[0m field of the [header] of an array is completely irrelevant. Our convention is to store in that field the symbol we mean to use as the name of the raw lisp array. But no ACL2 function inspects [47m:name[0m and its primary value is that it allows the user, by inspecting the semantic value of the array --- the alist --- to recall the name of the raw array that probably holds that value. We say ``probably'' since there is no enforcement that the alist was compressed under the name in the [header] or that all [47maset[0ms used that name. Such enforcement would be inefficient. Some Programming Examples In the following examples we will use ACL2 ``global variables'' to hold several arrays. See [@], and see [assign]. Let the [47m[state][0m global variable [47ma[0m be the 1-dimensional compressed array of dimension [47m5[0m constructed below. ACL2 !>(assign a (compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (0 . zero)))) Then [47m(aref1 'demo (@ a) 0)[0m is [47mzero[0m and [47m(aref1 'demo (@ a) 1)[0m is [47muninitialized[0m. Now execute ACL2 !>(assign b (aset1 'demo (@ a) 1 'one)) Then [47m(aref1 'demo (@ b) 0)[0m is [47mzero[0m and [47m(aref1 'demo (@ b) 1)[0m is [47mone[0m. All of the [47m[aref1][0ms done so far have been ``fast.'' Note that we now have two array objects, one in the global variable [47ma[0m and one in the global variable [47mb[0m. [47mB[0m was obtained by assigning to [47ma[0m. That assignment does not affect the alist [47ma[0m because this is an applicative language. Thus, [47m(aref1 'demo (@ a) 1)[0m must [31;1mstill[0m be [47muninitialized[0m. And if you execute that expression in ACL2 you will see that indeed it is. However, a rather ugly comment is printed, namely that this array access is ``slow.'' The reason it is slow is that the raw lisp array associated with the name [47mdemo[0m is the array we are calling [47mb[0m. To access the elements of [47ma[0m, [47m[aref1][0m must now do a linear search. Any reference to [47ma[0m as an array is now ``unconventional;'' in a conventional language like Ada or Common Lisp it would simply be impossible to refer to the value of the array before the assignment that produced our [47mb[0m. Now let us define a function that counts how many times a given object, [47mx[0m, occurs in an array. For simplicity, we will pass in the name and highest index of the array: ACL2 !>(defun cnt (name a i x) (declare (xargs :guard (and (array1p name a) (integerp i) (>= i -1) (< i (car (dimensions name a)))) :mode :logic :measure (nfix (+ 1 i)))) (cond ((zp (1+ i)) 0) ; return 0 if i is at most -1 ((equal x (aref1 name a i)) (1+ (cnt name a (1- i) x))) (t (cnt name a (1- i) x)))) To determine how many times [47mzero[0m appears in [47m(@ b)[0m we can execute: ACL2 !>(cnt 'demo (@ b) 4 'zero) The answer is [47m1[0m. How many times does [47muninitialized[0m appear in [47m(@ b)[0m? ACL2 !>(cnt 'demo (@ b) 4 'uninitialized) The answer is [47m3[0m, because positions [47m2[0m, [47m3[0m and [47m4[0m of the array contain that default value. Now imagine that we want to assign [47m'two[0m to index [47m2[0m and then count how many times the 2nd element of the array occurs in the array. This specification is actually ambiguous. In assigning to [47mb[0m we produce a new array, which we might call [47mc[0m. Do we mean to count the occurrences in [47mc[0m of the 2nd element of [47mb[0m or the 2nd element of [47mc[0m? That is, do we count the occurrences of [47muninitialized[0m or the occurrences of [47mtwo[0m? If we mean the former the correct answer is [47m2[0m (positions [47m3[0m and [47m4[0m are [47muninitialized[0m in [47mc[0m); if we mean the latter, the correct answer is [47m1[0m (there is only one occurrence of [47mtwo[0m in [47mc[0m). Below are ACL2 renderings of the two meanings, which we call [47m[former][0m and [47m[latter][0m. (Warning: Our description of these examples, and of an example [47m[fast former][0m that follows, assumes that only one of these three examples is actually executed; for example, they are not executed in sequence. See ``A Word of Warning'' below for more about this issue.) (cnt 'demo (aset1 'demo (@ b) 2 'two) 4 (aref1 'demo (@ b) 2)) ; [former] (let ((c (aset1 'demo (@ b) 2 'two))) ; [latter] (cnt 'demo c 4 (aref1 'demo c 2))) Note that in [47m[former][0m we create [47mc[0m in the second argument of the call to [47mcnt[0m (although we do not give it a name) and then refer to [47mb[0m in the fourth argument. This is unconventional because the second reference to [47mb[0m in [47m[former][0m is no longer the semantic value of [47mdemo[0m. While ACL2 computes the correct answer, namely [47m2[0m, the execution of the [47m[aref1][0m expression in [47m[former][0m is done slowly. A conventional rendering with the same meaning is (let ((x (aref1 'demo (@ b) 2))) ; [fast former] (cnt 'demo (aset1 'demo (@ b) 2 'two) 4 x)) which fetches the 2nd element of [47mb[0m before creating [47mc[0m by assignment. It is important to understand that [47m[former][0m and [47m[fast former][0m mean exactly the same thing: both count the number of occurrences of [47muninitialized[0m in [47mc[0m. Both are legal ACL2 and both compute the same answer, [47m2[0m. Indeed, we can symbolically transform [47m[fast former][0m into [47m[former][0m merely by substituting the binding of [47mx[0m for [47mx[0m in the body of the [47m[let][0m. But [47m[fast former][0m can be evaluated faster than [47m[former][0m because all of the references to [47mdemo[0m use the then-current semantic value of [47mdemo[0m, which is [47mb[0m in the first line and [47mc[0m throughout the execution of the [47mcnt[0m in the second line. [47m[Fast former][0m is the preferred form, both because of its execution speed and its clarity. If you were writing in a conventional language you would have to write something like [47m[fast former][0m because there is no way to refer to the 2nd element of the old value of [47mb[0m after smashing [47mb[0m unless it had been saved first. We turn now to [47m[latter][0m. It is both clear and efficient. It creates [47mc[0m by assignment to [47mb[0m and then it fetches the 2nd element of [47mc[0m, [47mtwo[0m, and proceeds to count the number of occurrences in [47mc[0m. The answer is [47m1[0m. [47m[Latter][0m is a good example of typical ACL2 array manipulation: after the assignment to [47mb[0m that creates [47mc[0m, [47mc[0m is used throughout. It takes a while to get used to this because most of us have grown accustomed to the peculiar semantics of arrays in conventional languages. For example, in raw lisp we might have written something like the following, treating [47mb[0m as a ``global variable'': (cnt 'demo (aset 'demo b 2 'two) 4 (aref 'demo b 2)) which sort of resembles [47m[former][0m but actually has the semantics of [47m[latter][0m because the [47mb[0m from which [47maref[0m fetches the 2nd element is not the same [47mb[0m used in the [47maset[0m! The array [47mb[0m is destroyed by the [47maset[0m and [47mb[0m henceforth refers to the array produced by the [47maset[0m, as written more clearly in [47m[latter][0m. A Word of Warning: Users must exercise care when experimenting with [47m[former][0m, [47m[latter][0m and [47m[fast former][0m. Suppose you have just created [47mb[0m with the assignment shown above, ACL2 !>(assign b (aset1 'demo (@ a) 1 'one)) If you then evaluate [47m[former][0m in ACL2 it will complain that the [47m[aref1][0m is slow and compute the answer, as discussed. Then suppose you evaluate [47m[latter][0m in ACL2. From our discussion you might expect it to execute fast --- i.e., issue no complaint. But in fact you will find that it complains repeatedly. The problem is that the evaluation of [47m[former][0m changed the semantic value of [47mdemo[0m so that it is no longer [47mb[0m. To try the experiment correctly you must make [47mb[0m be the semantic value of [47mdemo[0m again before the next example is evaluated. One way to do that is to execute ACL2 !>(assign b (compress1 'demo (@ b))) before each expression. Because of issues like this it is often hard to experiment with ACL2 arrays at the top-level. We find it easier to write functions that use arrays correctly and efficiently than to so use them interactively. This last assignment also illustrates a very common use of [47m[compress1][0m. While it was introduced as a means of removing irrelevant pairs from an array built up by repeated assignments, it is actually most useful as a way of insuring fast access to the elements of an array. Many array processing tasks can be divided into two parts. During the first part the array is built. During the second part the array is used extensively but not modified. If your [programming] task can be so divided, it might be appropriate to construct the array entirely with list processing, thereby saving the cost of maintaining the semantic value of the name while few references are being made. Once the alist has stabilized, it might be worthwhile to treat it as an array by calling [47m[compress1][0m, thereby gaining constant time access to it. ACL2's theorem prover uses this technique in connection with its implementation of the notion of whether a [rune] is [disable]d or not. Associated with every [rune] is a unique integer [47mindex[0m, called its ``nume.'' When each rule is stored, the corresponding nume is stored as a component of the rule. [Theories] are lists of [rune]s and membership in the ``current theory'' indicates that the corresponding rule is [enable]d. But these lists are very long and membership is a linear-time operation. So just before a proof begins we map the list of [rune]s in the current theory into an alist that pairs the corresponding numes with [47mt[0m. Then we compress this alist into an array. Thus, given a rule we can obtain its nume (because it is a component) and then determine in constant time whether it is [enable]d. The array is never modified during the proof, i.e., [47m[aset1][0m is never used in this example. From the logical perspective this code looks quite odd: we have replaced a linear-time membership test with an apparently linear-time [47m[assoc][0m after going to the trouble of mapping from a list of [rune]s to an alist of numes. But because the alist of numes is an array, the ``apparently linear-time [47m[assoc][0m'' is more apparent than real; the operation is constant-time. Subtopics [Aref1] Access the elements of a 1-dimensional array [Aref2] Access the elements of a 2-dimensional array [Array1p] Recognize a 1-dimensional array [Array2p] Recognize a 2-dimensional array [Arrays-example] An example illustrating ACL2 arrays [Aset1] Set the elements of a 1-dimensional array [Aset1-trusted] Set the elements of a 1-dimensional array without [invariant-risk] [Aset2] Set the elements of a 2-dimensional array [Compress1] Remove irrelevant pairs from a 1-dimensional array [Compress2] Remove irrelevant pairs from a 2-dimensional array [Default] Return the [47m:default[0m from the [header] of a 1- or 2-dimensional array [Dimensions] Return the [47m:dimensions[0m from the [header] of a 1- or 2-dimensional array [Flush-compress] Flush the under-the-hood array for the given name [Header] Return the header of a 1- or 2-dimensional array [Maximum-length] Return the [47m:maximum-length[0m from the [header] of an array [Maybe-flush-and-compress1] Compress a one-dimensional array only if necessary [Slow-array-warning] A warning or error issued when [arrays] are used inefficiently") (arrays-example (arrays) "An example illustrating ACL2 arrays The example below illustrates the use of ACL2 arrays. It is not, of course, a substitute for the detailed explanations provided elsewhere (see [arrays], including subtopics). ACL2 !>(defun defarray (name size initial-element) (compress1 name (cons (list :HEADER :DIMENSIONS (list size) :MAXIMUM-LENGTH (1+ size) :DEFAULT initial-element :NAME name) nil))) Since DEFARRAY is non-recursive, its admission is trivial. We observe that the type of DEFARRAY is described by the theorem (AND (CONSP (DEFARRAY NAME SIZE INITIAL-ELEMENT)) (TRUE-LISTP (DEFARRAY NAME SIZE INITIAL-ELEMENT))). We used the :type-prescription rule COMPRESS1. Summary Form: ( DEFUN DEFARRAY ...) Rules: ((:TYPE-PRESCRIPTION COMPRESS1)) Warnings: None Time: 0.02 seconds (prove: 0.00, print: 0.02, other: 0.00) DEFARRAY ACL2 !>(assign my-ar (defarray 'a1 5 17)) ((:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 6 :DEFAULT 17 :NAME A1)) ACL2 !>(aref1 'a1 (@ my-ar) 3) 17 ACL2 !>(aref1 'a1 (@ my-ar) 8) ACL2 Error in TOP-LEVEL: The guard for the function symbol AREF1, which is (AND (ARRAY1P NAME L) (INTEGERP N) (>= N 0) (< N (CAR (DIMENSIONS NAME L)))), is violated by the arguments in the call (AREF1 'A1 '(#) 8). ACL2 !>(assign my-ar (aset1 'a1 (@ my-ar) 3 'xxx)) ((3 . XXX) (:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 6 :DEFAULT 17 :NAME A1)) ACL2 !>(aref1 'a1 (@ my-ar) 3) XXX ACL2 !>(aset1 'a1 (@ my-ar) 3 'yyy) ; BAD: (@ my-ar) now points to ; an old copy of the array! ((3 . YYY) (3 . XXX) (:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 6 :DEFAULT 17 :NAME A1)) ACL2 !>(aref1 'a1 (@ my-ar) 3) ; Because of "BAD" above, the array ; access is done using assoc rather ; than Lisp aref, hence is slower; ; but the answer is still correct, ; reflecting the value in (@ my-ar), ; which was not changed above. ********************************************************** Slow Array Access! A call of AREF1 on an array named A1 is being executed slowly. See :DOC slow-array-warning ********************************************************** XXX ACL2 !>") (aset1 (arrays acl2-built-ins) "Set the elements of a 1-dimensional array Example Form: (aset1 'delta1 a (+ i k) 27) General Form: (aset1 name alist index val) where [47mname[0m is a symbol, [47malist[0m is a 1-dimensional array named [47mname[0m, [47mindex[0m is a legal index into [47malist[0m, and [47mval[0m is an arbitrary object. See [arrays] for details. Roughly speaking this function ``modifies'' [47malist[0m so that the value associated with [47mindex[0m is [47mval[0m. More precisely, it returns a new array, [47malist'[0m, of the same name and dimension as [47malist[0m that, under [47m[aref1][0m, is everywhere equal to [47malist[0m except at [47mindex[0m where the result is [47mval[0m. That is, [47m(aref1 name alist' i)[0m is [47m(aref1 name alist i)[0m for all legal indices [47mi[0m except [47mindex[0m, where [47m(aref1 name alist' i)[0m is [47mval[0m. In order to ``modify'' [47malist[0m, [47maset1[0m [47m[cons][0mes a new pair onto the front. If the length of the resulting alist exceeds the [47m:[0m[47m[maximum-length][0m entry in the array [header], [47maset1[0m compresses the array as with [47m[compress1][0m. It is generally expected that the ``semantic value'' of [47mname[0m will be [47malist[0m (see [arrays]). This function operates in virtually constant time whether this condition is true or not (unless the [47m[compress1][0m operation is required). But the value returned by this function cannot be used efficiently by subsequent [47maset1[0m operations unless [47malist[0m is the semantic value of [47mname[0m when [47maset1[0m is executed. Thus, if the condition is not true, [47maset1[0m prints a [31;1mslow array[0m warning to the comment window. See [slow-array-warning]. Note that [47m[aset1][0m is marked as having [47m[invariant-risk][0m, which can affect the execution of [47m:[0m[47m[program][0m-mode functions. To get around this problem (but only with great care!), see [aset1-trusted]. [31;1mFunction: [0m<aset1> (defun aset1 (name l n val) (declare (xargs :guard (and (array1p name l) (integerp n) (>= n 0) (< n (car (dimensions name l)))))) (let ((l (cons (cons n val) l))) (cond ((> (length l) (maximum-length name l)) (compress1 name l)) (t l)))) Subtopics [Aset1-trusted] Set the elements of a 1-dimensional array without [invariant-risk]") (aset1-trusted (arrays acl2-built-ins aset1) "Set the elements of a 1-dimensional array without [invariant-risk] Example Form: (aset1-trusted 'delta1 a (+ i k) 27) General Form: (aset1-trusted name alist index val) This utility is identical to [47m[aset1][0m; in fact, it has the same guard. The difference is that it does not carry [invariant-risk]. Because of that, functions that call [47maset1-trusted[0m may suffer from invariant-risk but not be noted by the system as carrying invariant-risk. Therefore, [47maset1-trusted[0m it is [untouchable] and should be used with great care. If your system consists of [47m:[0m[47m[logic][0m-mode functions, then there is no reason to use [47maset1-trusted[0m, because only [47m:[0m[47m[program][0m-mode functions truly carry invariant-risk. [31;1mFunction: [0m<aset1-trusted> (defun aset1-trusted (name l n val) (declare (xargs :guard (and (array1p name l) (integerp n) (>= n 0) (< n (car (dimensions name l)))))) (aset1 name l n val))") (aset2 (arrays acl2-built-ins) "Set the elements of a 2-dimensional array Example Form: (aset2 'delta1 a i j 27) General Form: (aset2 name alist i j val) where [47mname[0m is a symbol, [47malist[0m is a 2-dimensional array named [47mname[0m, [47mi[0m and [47mj[0m are legal indices into [47malist[0m, and [47mval[0m is an arbitrary object. See [arrays] for details. Roughly speaking this function ``modifies'' [47malist[0m so that the value associated with [47m(i . j)[0m is [47mval[0m. More precisely, it returns a new array, [47malist'[0m, of the same name and dimension as [47malist[0m that, under [47m[aref2][0m, is everywhere equal to [47malist[0m except at [47m(i . j)[0m where the result is [47mval[0m. That is, [47m(aref2 name alist' x y)[0m is [47m(aref2 name alist x y)[0m for all legal indices [47mx[0m [47my[0m except [47mi[0m and [47mj[0m where [47m(aref2 name alist' i j)[0m is [47mval[0m. In order to ``modify'' [47malist[0m, [47maset2[0m [47m[cons][0mes a new pair onto the front. If the length of the resulting [47malist[0m exceeds the [47m:[0m[47m[maximum-length][0m entry in the array [header], [47maset2[0m compresses the array as with [47m[compress2][0m. It is generally expected that the ``semantic value'' of [47mname[0m will be [47malist[0m (see [arrays]). This function operates in virtually constant time whether this condition is true or not (unless the [47m[compress2][0m operation is required). But the value returned by this function cannot be used efficiently by subsequent [47maset2[0m operations unless [47malist[0m is the semantic value of [47mname[0m when [47maset2[0m is executed. Thus, if the condition is not true, [47maset2[0m prints a [31;1mslow array[0m warning to the comment window. See [slow-array-warning]. [31;1mFunction: [0m<aset2> (defun aset2 (name l i j val) (declare (xargs :guard (and (array2p name l) (integerp i) (>= i 0) (< i (car (dimensions name l))) (integerp j) (>= j 0) (< j (cadr (dimensions name l)))))) (let ((l (cons (cons (cons i j) val) l))) (cond ((> (length l) (maximum-length name l)) (compress2 name l)) (t l))))") (ash (numbers acl2-built-ins) "Arithmetic shift operation [47m(ash i c)[0m is the result of taking the two's complement representation of the integer [47mi[0m and shifting it by [47mc[0m bits: shifting left and padding with [47mc[0m [47m0[0m bits if [47mc[0m is positive, shifting right and dropping [47m(abs c)[0m bits if [47mc[0m is negative, and simply returning [47mi[0m if [47mc[0m is [47m0[0m. The [guard] for [47mash[0m requires that its arguments are integers. [47mAsh[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<ash> (defun ash (i c) (declare (xargs :guard (and (integerp i) (integerp c)))) (floor (* (ifix i) (expt 2 c)) 1))") (assert$ (errors acl2-built-ins) "Cause a hard error if the given test is false General Form: (assert$ test form) where [47mtest[0m returns a single value and [47mform[0m is arbitrary. Semantically, this call of [47massert$[0m is equivalent to [47mform[0m. However, it causes a hard error if the value of [47mtest[0m is [47mnil[0m. That hard error invokes the function [47m[illegal][0m, which has a [guard] that is equal to [47mnil[0m; so if you use [47massert$[0m in code for which you verify guards, then a proof obligation will be that the occurrence of [47mtest[0m is never [47mnil[0m. See also [47m[assert*][0m. Both [47m[assert$][0m and [47m[assert*][0m create a [guard] proof obligation (when used in a definition made in [47m[logic][0m-mode). However, [47massert$[0m checks the assertion at runtime, while [47massert*[0m does not. Also see [assert-event] for an assertion-checking utility that is an [event].") (assert* (errors acl2-built-ins) "Create a [guard] proof obligation that given test holds General Form: (assert* test form) where [47mtest[0m returns a single value and [47mform[0m is arbitrary. Semantically, this call of [47massert*[0m is equivalent to [47mform[0m. However, a [guard] proof obligation is created that [47mtest[0m holds, when used in a definition made in [47m[logic][0m-mode. For a related utility, see [assert$]. Both [47massert$[0m and [47massert*[0m create a [guard] proof obligation (when used in a definition made in [47m[logic][0m-mode). However, [47massert$[0m checks the assertion at runtime, while [47massert*[0m does not. Also see [assert-event] for an assertion-checking utility that is an [event]. [31;1mMacro: [0m<assert*> (defmacro assert* (test form) (cons 'and (cons (cons 'mbt* (cons test 'nil)) (cons form 'nil))))") (assert-event (events errors) "Assert that a given form returns a non-[47mnil[0m value [47mAssert-event[0m provides a flexible way to check that evaluation of an expression returns a non-[47mnil[0m value, causing an error otherwise. Calls of [47massert-event[0m are [event] forms; thus, they may occur in [books] as well as [47m[encapsulate][0m and [47m[progn][0m events. See also [assert!] and [assert!-stobj] for simple interfaces to [47massert-event[0m. See [assert$] and [assert*] for assertion-checking utilities to use in programs. Basic calls of [47massert-event[0m will take just one argument, called an ``assertion'', which is a form that evaluates to a single value that is not a [stobj]. The following log shows a successful invocation --- one where the assertion evaluates to a non-[47mnil[0m value. ACL2 !>(assert-event (equal (+ 3 4) 7)) :PASSED ACL2 !> Such a use of [47massert-event[0m will probably suffice for most users, that is, where the form evaluates to a single non-stobj value and there are no keyword arguments. The keyword arguments, which are optional and discussed below, extend that functionality, for example: multiple values are permitted by keyword [47m:stobjs-out[0m, and keyword [47m:on-skip-proofs[0m can override the default behavior of ignoring assertions when proofs are being skipped. General Form: (assert-event assertion :event event ; default nil ;; evaluated keyword arguments: :ctx ; default 'assert-event :msg msg ; default t :on-skip-proofs sp ; default nil :safe-mode safe-mode ; default :same :stobjs-out stobjs-out ; default nil ) where [47massertion[0m and [47mevent[0m are not evaluated but all the other arguments are evaluated, with the defaults shown above corresponding to values after evaluation. The following example illustrates all of the keyword arguments, which are documented below. (assert-event (mv (equal (+ 3 4) 7) state) :event (defun f (x) (cons x x)) :ctx '(assert-event . <some-mv>) :msg (msg "Oops, I forgot what ~x0+~x1 is!" 3 4) :on-skip-proofs t :safe-mode nil :stobjs-out '(nil state)) [47mAssert-event[0m is a macro whose expansion directly produces a call of the primitive event, [47mvalue-triple[0m, where: if a call of [47massert-event[0m specifies [47m:msg msg[0m, then the corresponding call of [47mvalue-triple[0m specifies [47m:check (or msg t)[0m. But unlike [47mvalue-triple[0m, [47massert-event[0m can specify an event to evaluate when the assertion has non-[47mnil[0m value, using the [47m:event[0m keyword. (You can get a sense of the [47mvalue-triple[0m call generated from an [47massert-event[0m call by using [47m:[0m[47m[trans1][0m on the [47massert-event[0m form.) The remaining keyword arguments of [47massert-event[0m are also arguments of [47mvalue-triple[0m. Here is a brief summary of the keyword arguments, but [31;1mNOTE[0m: see [value-triple] for more detailed explanations of keywords other than [47m:EVENT[0m. [47m:EVENT event[0m (default [47mnil[0m): When [47mevent[0m is not [47mnil[0m, it should be an [event], that is, a form that may be in a book or a call of [47m[encapsulate][0m or [47m[progn][0m. If the assertion evaluates to a non-[47mnil[0m value (or to multiple values where the first value is not a stobj and is non-[47mnil[0m; see [47m:STOBJS-OUT[0m below), then [47mevent[0m is evaluated; otherwise the evaluation results in an error. [47m:CTX ctx[0m (default: [47m'assert-event[0m): context for error messages. [47m:MSG msg[0m (default: [47mt[0m): message to print when there is an error (equivalent to keyword argument [47m:CHECK[0m of [47m[value-triple][0m). [47m:ON-SKIP-PROOFS sp[0m (default: [47mnil[0m): supply [47mt[0m to evaluate the assertion even when skipping proofs (i.e., during [47m[include-book][0m or the second pass of an [47m[encapsulate][0m event, or after invoking [47m[set-ld-skip-proofsp][0m to skip proofs). [47m:SAFE-MODE safe-mode[0m (default: [47m:same[0m): provides backward compatibility, but is probably best ignored. [47m:STOBJS-OUT stobjs-out[0m (default: [47mnil[0m): specify [47m:auto[0m to allow any return, even with multiple values provided the first return value is not a [stobj]; or specify a list starting with [47mnil[0m, corresponding to the multiple values returned, with stobjs in stobj positions and [47mnil[0m elsewhere. A [47mstobjs-out[0m of [47mnil[0m is treated as [47m(nil)[0m. The first return value is the one checked to be non-[47mnil[0m with one exception: when an [error-triple] [47m(mv erp val state)[0m is returned, [47merp[0m must be [47mnil[0m and it is [47mval[0m that is checked to be non-[47mnil[0m.") (assertions (pointers) "See [errors].") (assign (programming-with-state acl2-built-ins) "Assign to a global variable in [47m[state][0m Examples: (assign x (expt 2 10)) (assign a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B)) General Form: (assign symbol term) where [47msymbol[0m is any symbol (with certain enforced exclusions to avoid overwriting ACL2 system ``globals'') and [47mterm[0m is any ACL2 term that could be evaluated at the top-level. [47mAssign[0m evaluates the term, stores the result as the value of the given symbol in the [47mglobal-table[0m of [47m[state][0m, and returns the result. (Note: the actual implementation of the storage of this value is much more efficient than this discussion of the logic might suggest.) [47mAssign[0m is a macro that effectively expands to the more complicated but understandable: (pprogn (f-put-global 'symbol term state) (mv nil (f-get-global 'symbol state) state)). The macro [47mf-put-global[0m is closely related to [47m[assign][0m: [47m(assign var val)[0m macroexpands to [47m(f-put-global 'var val state)[0m. The macro [47m[@][0m gives convenient access to the value of such globals. The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of [47m[state][0m. Thus, you may use these globals to hang onto useful data structures even though you may undo back past where you computed and saved them.") (assoc (alists acl2-built-ins) "Look up key in association list General Forms: (assoc x alist) (assoc x alist :test 'eql) ; same as above (eql as equality test) (assoc x alist :test 'eq) ; same, but eq is equality test (assoc x alist :test 'equal) ; same, but equal is equality test [47m(Assoc x alist)[0m is the first member of [47malist[0m whose [47m[car][0m is [47mx[0m, or [47mnil[0m if no such member exists. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with the [47m[car][0ms of successive elements of [47malist[0m. The [guard] for a call of [47massoc[0m depends on the test. In all cases, the second argument must satisfy [47m[alistp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-alistp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-alistp][0m. See [equality-variants] for a discussion of the relation between [47massoc[0m and its variants: [47m(assoc-eq x alist)[0m is equivalent to [47m(assoc x alist :test 'eq)[0m; [47m(assoc-equal x alist)[0m is equivalent to [47m(assoc x alist :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47massoc-equal[0m. [47mAssoc[0m is defined by Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<assoc-equal> (defun assoc-equal (x alist) (declare (xargs :guard (alistp alist))) (cond ((endp alist) nil) ((equal x (car (car alist))) (car alist)) (t (assoc-equal x (cdr alist)))))") (assoc-eq (pointers) "See [assoc].") (assoc-equal (pointers) "See [assoc].") (assoc-keyword (keyword-value-listp acl2-built-ins) "Look up key in a [47m[keyword-value-listp][0m If [47ml[0m is a list of even length of the form [47m(k1 a1 k2 a2 ... kn an)[0m, where each [47mki[0m is a keyword, then [47m(assoc-keyword key l)[0m is the first tail of [47ml[0m starting with [47mkey[0m if key is some [47mki[0m, and is [47mnil[0m otherwise. The [guard] for [47m(assoc-keyword key l)[0m is [47m(keyword-value-listp l)[0m. [31;1mFunction: [0m<assoc-keyword> (defun assoc-keyword (key l) (declare (xargs :guard (keyword-value-listp l))) (cond ((endp l) nil) ((eq key (car l)) l) (t (assoc-keyword key (cddr l)))))") (assoc-string-equal (alists acl2-built-ins) "Look up key, a string, in association list [47m(Assoc-string-equal x alist)[0m is similar to [47m[assoc-equal][0m. However, for string [47mx[0m and alist [47malist[0m, the comparison of [47mx[0m with successive keys in [47malist[0m is done using [47m[string-equal][0m rather than [47m[equal][0m. The [guard] for [47massoc-string-equal[0m requires that [47mx[0m is a string and [47malist[0m is an alist. [31;1mFunction: [0m<assoc-string-equal> (defun assoc-string-equal (str alist) (declare (xargs :guard (and (stringp str) (string-alistp alist)))) (cond ((endp alist) nil) ((string-equal str (car (car alist))) (car alist)) (t (assoc-string-equal str (cdr alist)))))") (assume-true-false-aggressive-p (rewrite system-attachments) "Control rewriter's use of the [type-alist] with [47mIF[0m calls This topic concerns an advanced control for the ACL2 prover. This zero-ary attachable system function controls the rewriter's use of the [type-alist] when diving into calls of [47mIF[0m. By default, when ACL2 rewrites what amounts to [47m(if (or test1 test2) (if test1 _ x) _)[0m, the type-alist will fail to note that [47mtest2[0m is true when rewriting [47mx[0m. Attach the function [47mconstant-t-function-arity-0[0m to strengthen the use of the type-alist so that [47mtest2[0m is instead noted as true in that case. Note that this strengthening may slow down ACL2 considerably in some cases, and should rarely if ever be necessary when calling the prover; but it can be useful in applications that call the rewriter directly. Attach the function [47mconstant-nil-function-arity-0[0m to restore the default behavior.") (atom (conses acl2-built-ins) "Recognizer for atoms [47m(atom x)[0m is true if and only if [47mx[0m is an atom, i.e., not a [47m[cons][0m pair. [47mAtom[0m has a [guard] of [47mt[0m, and is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<atom> (defun atom (x) (declare (xargs :guard t)) (not (consp x))) Subtopics [Atom-listp] Recognizer for a true list of [atom]s") (atom-listp (atom lists acl2-built-ins) "Recognizer for a true list of [atom]s The predicate [47matom-listp[0m tests whether its argument is a [47m[true-listp][0m of [atom]s, i.e., of non-conses. [31;1mFunction: [0m<atom-listp> (defun atom-listp (lst) (declare (xargs :guard t)) (cond ((atom lst) (eq lst nil)) (t (and (atom (car lst)) (atom-listp (cdr lst))))))") (attach-stobj (defabsstobj) "Attach an ``implementation [stobj]'' to an attachable stobj For an illustration of [47mattach-stobj[0m, see [community-books] directory [47mbooks/demos/attach-stobj/[0m, in particular file [47mREADME.txt[0m in that directory. An overview of the subject of this topic may be found in the paper, {``Extended Abstract: Mutable Objects with Several Implementations'' | https://cgi.cse.unsw.edu.au/~eptcs/paper.cgi?ACL2in2025.7} by Matt Kaufmann, Yahya Sohail, and Warren A. Hunt Jr. This topic assumes familiarity with abstract [stobj]s; see [defabsstobj]. It documents a way to modify the foundation and primitives of an abstract [stobj], [47mgen[0m, that is introduced by [47mdefabsstobj[0m using the keyword argument [47m:attachable t[0m. Such a stobj is called an [3mattachable[0m stobj. Execution of its primitives can be provided by corresponding primitives of a specified abstract stobj, [47mimpl[0m, which we say is [3mattached to[0m [47mgen[0m (or: [47mimpl[0m is the [3mimplementation stobj attached to[0m [47mgen[0m); said differently, [47mgen[0m has [47mimpl[0m as an attachment. That relationship is specified by the following General Form: (attach-stobj gen impl) where [47mgen[0m and [47mimpl[0m are symbols, [47mgen[0m is not currently the [name] of any [event] (function, macro, constant, stobj, etc.), and [47mimpl[0m is an abstract stobj. A subsequent attempt to introduce [47mgen[0m as an attachable stobj will require [47mgen[0m and [47mimpl[0m to have [3mcorresponding logical skeletons[0m as described below. In that case, the foundation of [47mgen[0m, as well as execution of the primitives of [47mgen[0m, will effectively be provided by [47mimpl[0m; details are below. In the General Form above, [47mimpl[0m is allowed to be [47mnil[0m, i.e., the event [47m(attach-stobj gen nil)[0m is legal, where it is still required that [47mgen[0m not be the name of any existing event. The effect of this ``attachment'' of [47mnil[0m is to cancel the effect of any previous [47m(attach-stobj gen impl)[0m on any future introduction of [47mgen[0m. Below, we assume the common case that [47mimpl[0m is not [47mnil[0m. Note that [47mimpl[0m may itself have an attachment, say, [47mimpl2[0m, in which case we say that [47mimpl2[0m is attached to [47mgen[0m. If furthermore [47mimpl3[0m is attached to [47mimpl2[0m, then [47mimpl3[0m is said to be attached to [47mgen[0m; and so on. The guiding principle is that [47mgen[0m is modified by its attachment to [47mimpl[0m so that [47mgen[0m behaves exactly as [47mimpl[0m except for the names introduced and the [47m:non-executable[0m keyword. Specifically, if [47mimpl[0m is attached to [47mgen[0m, then the following properties hold. (See [defabsstobj] for the notion of a ``function spec'' and its ``completion''.) * Both [47mgen[0m and [47mimpl[0m are abstract stobjs, and moreover, [47mgen[0m is an attachable stobj. * [47mImpl[0m was introduced before the use of [47mattach-stobj[0m to attach [47mimpl[0m to [47mgen[0m, which took place before [47mgen[0m was introduced. * [47mGen[0m and [47mimpl[0m have corresponding logical skeletons (as defined below). In particular, each primitive of [47mgen[0m has the same logical meaning (i.e., the same [47m:logic[0m function) as the corresponding primitive of [47mimpl[0m. * For each primitive [47mp_gen[0m of [47mgen[0m and corresponding primitive [47mp_impl[0m of [47mimpl[0m, if [47m(p_impl . kwd-alist)[0m is the completion of the corresponding function spec for [47mp_impl[0m, then the function spec for [47mp_gen[0m is effectively given as [47m(p_gen . kwd-alist)[0m, with the following exception. Each [47m:updater[0m keyword is replaced appropriately, as follows: if [47mkwd-alist[0m specifies [47m:updater u_impl[0m and primitive [47mu_gen[0m of [47mgen[0m corresponds to primitive [47mu_impl[0m of [47mimpl[0m, then [47m:updater u_impl[0m is replaced by [47m:updater u_gen[0m to obtain the effective function spec for [47mp_gen[0m. * The [47m:protect-default[0m and [47m:congruent-to[0m keyword arguments for [47mgen[0m are effectively those of [47mimpl[0m. * The [47m:non-executable[0m keyword argument for [47mgen[0m is unchanged by the attachment. As promised above, we now define when two [47mdefabsstobj[0m events have [3mcorresponding logical skeletons[0m, as follows. The [47m:exports[0m keyword argument of each must be of the same length, establishing a positional one-one correspondence between them. Corresponding exports (i.e., exports in the same position) must have the same [47m:logic[0m functions and, if one of them specifies [47m:updater u1[0m, then the other must specify [47m:updater u2[0m where [47mu1[0m and [47mu2[0m correspond. Remarks on Performance. Stobj attachments are designed to be efficient. There is no indirection: in raw Lisp, each primitive macroexpands to a call of the [47m:exec[0m primitive of the attachment (which is itself a macro call). The trade-off is that when a function [47mF[0m is defined in the course of evaluating an [47m[include-book][0m event, then if the guard or body of [47mF[0m calls an attachable stobj primitive --- either directly or by way of inline functions or macroexpansion, and whether or not that stobj has an attachment --- then [47mF[0m will be compiled at that time. (This is in contrast to the usual case, where compiled code from the book's compiled file will be installed to avoid such recompilation.) Most likely this will not be a noticeable problem in practice, but if it is, then one can define a wrapper --- a function that does nothing more than call the primitive --- to avoid such recompilation at the cost of a runtime function call for each such primitive. End of Remarks on Performance. Note that the notion of redundancy for [47mdefabsstobj[0m was not changed by support for the [47m:attachable[0m keyword. As noted in the topic [redundant-events], a [47mdefabsstobj[0m event is redundant if there is already an identical such event in the logical [world]. The [community-books] directory [47msystem/tests/attachable-stobjs/[0m has examples that use attachable stobjs.") (auto-instance (pointers) "See [defthm<w].") (a_flying_tour_of_acl2 (pages_written_especially_for_the_tours) "A Flying Tour of ACL2 {IMAGE} (see [About_the_ACL2_Home_Page]) On this tour you will learn a little about what ACL2 is for rather than how ACL2 works. At the top and bottom of the ``page'' there are ``flying tour'' icons. Click on either icon to go to the next page of the tour. The tour visits the following topics sequentially. But on your first reading, don't navigate through the tour by clicking on these links; they are shown as live links only so that later you can determine what you've visited. Instead, just use the flying tour icons. [31;1mThe Flight Plan[0m * This Documentation (see [About_the_ACL2_Home_Page]) * What is ACL2? (see [What_Is_ACL2{Q}]) * Mathematical Logic (see [What_is_a_Mathematical_Logic{Q}]) * Mechanical Theorem Proving (see [What_is_a_Mechanical_Theorem_Prover{Q}]) * Mathematical Models in General (see [About_Models]) * Mathematical Models of Computing Machines (see [Models_of_Computer_Hardware_and_Software]) Formalizing Models (see [A_Typical_State]) Running Models (see [Running_Models]) Symbolic Execution of Models (see [Symbolic_Execution_of_Models]) Proving Theorems about Models (see [Proving_Theorems_about_Models]) * Requirements of ACL2 The User's Skills (see [What_is_Required_of_the_User{Q}]) Training (see [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}]) Host System (see [Other_Requirements]) On your first reading, don't explore other links you see in the tour. Some of them lead to the Walking Tour, which you can take coherently when you finish this tour. Others lead into the extensive hypertext documentation and you are liable to get lost there unless you're trying to answer a specific question. We intend the tour to take about 10 minutes of your time. {IMAGE} (see [About_the_ACL2_Home_Page])") (a_sketch_of_how_the_rewriter_works (pages_written_especially_for_the_tours) "A Sketch of How the Rewriter Works Below we show the first target term, extracted from the current conjecture. Below it we show the associativity rule. {IMAGE} The variables of the rewrite rule are [31;1minstantiated[0m so that the [31;1mleft-hand side[0m of the rule matches the target: variable term from target a x1 b x2 c (app x3 x4) Then the target is [31;1mreplaced[0m by the instantiated [31;1mright-hand side[0m of the rule. Sometimes rules have [31;1mhypotheses[0m. To make a long story short, if the rule has hypotheses, then after matching the left-hand side, the rewriter instantiates the hypotheses and rewrites them recursively. This is called [31;1mbackchaining[0m. If they all rewrite to true, then the target is replaced as above. We discuss the rewriter in more detail in the extended introduction to how to use the theorem prover, see [introduction-to-the-theorem-prover], which we will recommend you work through [31;1mafter[0m you have finished the two tours.") (a_tiny_warning_sign (pages_written_especially_for_the_tours) "A Tiny Warning Sign {IMAGE} This warning sign, which usually appears as ``{ICON}'', indicates that the link it marks takes you into ACL2's online documentation. The documentation is a vast graph of documented topics intended to help the [3muser[0m of ACL2 rather than the [3mpotential user[0m. If you are exploring ACL2's home page to learn about the system, perhaps you should go back rather than follow the link marked with this sign. But you are welcome to explore the online documentation as well. Good luck.") (a_trivial_proof (pages_written_especially_for_the_tours) "A Trivial Proof {IMAGE}") (a_typical_state (pages_written_especially_for_the_tours) "A Typical State {IMAGE} (see [Functions_for_Manipulating_these_Objects]) {IMAGE} Observe that the states in typical models talk about [31;1mbooleans[0m [31;1mintegers[0m [31;1mvectors[0m [31;1mrecords[0m [31;1mcaches[0m [31;1mbits[0m [31;1msymbols[0m [31;1marrays[0m [31;1mstacks[0m [31;1mfiles[0m [31;1mcharacters[0m [31;1mstrings[0m [31;1msequences[0m [31;1mtables[0m [31;1mdirectories[0m These objects are [31;1mdiscrete[0m rather than [31;1mcontinuous[0m; furthermore they are built incrementally or [31;1minductively[0m by repeatedly using primitive operations to put together smaller pieces. The functions we need to manipulate these objects do things like [31;1mconcatenate[0m, [31;1mreverse[0m, [31;1msort[0m, [31;1msearch[0m, [31;1mcount[0m, etc. {IMAGE} (see [Functions_for_Manipulating_these_Objects])") (a_walking_tour_of_acl2 (pages_written_especially_for_the_tours) "A Walking Tour of ACL2 {IMAGE} (see [Common_Lisp]) On this tour you will learn a little more about the ACL2 logic, the theorem prover, and the user interface. This time we will stick with really simple things, such as the associativity of list concatenation. We assume you have taken the Flying Tour but that you did not necessarily follow all the ``off-tour'' links because we encouraged you not to. With the Walking Tour we encourage you to visit off-tour links --- provided they are not marked with the tiny warning sign ({ICON} (see [A_Tiny_Warning_Sign])). But they are ``branches'' in the tour that lead to ``dead ends.'' When you reach a dead end, remember to use your browser's Back Button to return to the Walking Tour to continue. When you get to the end of the tour we'll give you a chance to repeat quickly both the Flying and the Walking Tours to visit any off-tour links still of interest. {IMAGE} (see [Common_Lisp])") (backchain-limit (rewrite meta linear type-prescription) "Limiting the effort expended on relieving hypotheses Before ACL2 can apply a rule with hypotheses, it must establish that the hypotheses are true. (We ignore the relaxing of this requirement afforded by [47m[case-split][0ms and [47m[force][0md hypotheses.) ACL2 typically establishes each hypothesis by backchaining --- instantiating the hypothesis and then rewriting it recursively. Here we describe how ACL2 allows the user to limit backchaining. At the end, below, we describe the function [47m[backchain-limit][0m. Each hypothesis of a [47m[rewrite][0m, [47m[meta][0m, [47m[linear][0m, or [47m[type-prescription][0m rule is assigned a backchain-limit when the rule is stored. By default, this limit is [47mnil[0m, denoting infinity (no limit). However, the value used for the default may be set to a non-negative integer (or to [47mnil[0m) by the user; see [set-default-backchain-limit]. The default is overridden when a [47m:backchain-limit-lst[0m is supplied explicitly with the rule; see [rule-classes]. The number of recursive applications of backchaining starting with the hypothesis of a rule is limited to the backchain-limit associated with that hypothesis. Moreover, the user may set global backchain-limits that limit the total backchaining depth. See [set-backchain-limit]. One limit is for the use of [47m[rewrite][0m, [47m[meta][0m, and [47m[linear][0m rules, while the other limit is for so-called ``type reasoning'', which uses rules of class [47m[type-prescription][0m rules (see [type-reasoning]). The two limits operate independently. Below, we discuss the first kind of backchain limits, i.e., for other than [47m[type-prescription][0m rules, except as otherwise indicated; but the mechanism for those rules is similar. Below we lay out the precise sense in which a global backchain-limit interacts with the backchain-limits of individual rules in order to limit backchaining. But first we note that when further backchaining is disallowed, ACL2 can still prove a hypothesis in a given context by using that contextual information. In fact, type reasoning may be used (except that a weaker version of it is used in the second case above, i.e., where we are already doing type-set reasoning). Thus, the relieving of hypotheses may be limited to the use of contextual information (without backchaining, i.e., without recursively rewriting hypotheses) by executing [47m:set-backchain-limit 0[0m. Recall that there are two sorts of backchain limits: those applied to hypotheses of individual rules, as assigned by their [47m:[0m[47m[rule-classes][0m or else taken from the default (see [set-default-backchain-limit]); and the global limit, initially [47mnil[0m (no limit) but settable with [47m:[0m[47m[set-backchain-limit][0m. Here is how these two types of limits interact to limit backchaining, i.e., recursive rewriting of hypotheses. ACL2 maintains a current backchain limit, which is the limit on the depth of recursive calls to the rewriter, as well as a current backchain depth, which is initially 0 and is incremented each time ACL2 backchains (and is decremented when a backchain completes). When ACL2 begins to rewrite a literal (crudely, one of the ``top-level'' terms of the goal currently being worked on), it sets the current backchain-limit to the global value, which is initially [47mnil[0m but can be set using [47m:[0m[47m[set-backchain-limit][0m. When ACL2 is preparing to relieve a hypothesis by backchaining (hence, after it has already tried type-set reasoning), it first makes sure that the current backchain limit is greater than the current backchain depth. If not, then it refuses to relieve that hypothesis. Otherwise, it increments the current backchain depth and calculates a new current backchain-limit by taking the minimum of two values: the existing current backchain-limit, and the sum of the current backchain depth and the backchain-limit associated with the hypothesis. Thus, ACL2 only modifies the current backchain-limit if it is necessary to decrease that limit in order to respect the backchain limit associated with the hypothesis. We illustrate with the following examples. ; We stub out some functions so that we can reason about them. (defstub p0 (x) t) (defstub p1 (x) t) (defstub p2 (x) t) (defstub p3 (x) t) ; Initially, the default-backchain-limit is nil, or infinite. (defaxiom p2-implies-p1-limitless (implies (p2 x) (p1 x))) ; The following rule will have a backchain-limit of 0. (defaxiom p1-implies-p0-limit-0 (implies (p1 x) (p0 x)) :rule-classes ((:rewrite :backchain-limit-lst 0))) ; We have (p2 x) ==> (p1 x) ==> (p0 x). We wish to establish that ; (p2 x) ==> (p0 x). Normally, this would be no problem, but here ; we fail because ACL2 cannot establish (p0 x) by type-set reasoning ; alone. (thm (implies (p2 x) (p0 x))) ; We set the default-backchain-limit (for rewriting) to 1. :set-default-backchain-limit 1 ; The following is more powerful than p1-implies-p0-limit-0 ; because it can use rewrite rules to establish (p1 x). (defaxiom p1-implies-p0-limit-1 (implies (p1 x) (p0 x))) ; This theorem will succeed: (thm (implies (p2 x) (p0 x))) ; We return the default-backchain-limit to its initial value. :set-default-backchain-limit nil ; Here is our last axiom. (defaxiom p3-implies-p2-limitless (implies (p3 x) (p2 x))) ; We now have (p3 x) ==> (p2 x) ==> (p1 x) ==> (p0 x). However the ; rule p1-implies-p0-limit-1 has a backchain-limit of 1; hence we ; are not allowed to backchain far enough back to use ; p3-implies-p2-limitless. We therefore lose. (defthm will-fail (implies (p3 x) (p0 x))) Finally, we remark that to see the current global backchain-limits, issue the following commands. (backchain-limit wrld :ts) ; backchain limit for type-set reasoning (backchain-limit wrld :rewrite) ; backchain limit for rewriting Subtopics [Set-backchain-limit] Sets the backchain-limit used by the type-set and rewriting mechanisms [Set-default-backchain-limit] Sets the default backchain-limit used when admitting a rule") (backchain-limit-rw (pointers) "See [hints] for information about the keyword [47m:backchain-limit-rw[0m.") (backchaining (rule-classes) "Attempting to relieve the hypotheses of a rule When the theorem prover attempts to apply a rule (e.g., a [rewrite] rule), it must relieve (prove) the hypotheses of that rule. In the ACL2 community, this process of relieving hypotheses is called backchaining. There is no such thing as a backchaining or backward-chaining rule class (see [rule-classes]) in ACL2.") `(reader) (backtrack (pointers) "See [hints] for information about the keyword [47m:backtrack[0m.") (badge (apply$) "Syntactic requirements on a function symbol to be used by [47mapply$[0m ``Badge'' is both the name of an ACL2 function and the name of a concept key to the [47m[apply$][0m machinery. We discuss the function named [47mbadge[0m first. The discussion also mentions the concept of warrants, which are easily confused with badges. See the discussion of [31;1mBadges versus Warrants[0m at the top of [47mdefbadge[0m. But roughly put, badges extend the ACL2 syntax and warrants extend the proof theory. You'll need a badge for [47mfn[0m to allow the system to syntactically analyze [47m(apply$ 'fn ...)[0m. You'll need a both a badge and a warrant for [47mfn[0m if you wish to reason about that term with ACL2. General Form: (badge fn) The argument, [47mfn[0m, is expected to be a function symbol. If [47mfn[0m is one of about 800 ACL2 primitives (discussed below) or is a user-defined function successfully processed by either the event [47m[defbadge][0m or the event [47m[defwarrant][0m, the result is an object, called the ``badge'' of [47mfn[0m, which among other things specifies the [ilk] of each formal of [47mfn[0m. Otherwise, an error is caused. We explain below, where we define the concepts of the ``out arity,'' ``ilks,'' and ``tameness requirements'' of [47mfn[0m's badge. A function symbol must have a badge in order to [47mapply$[0m the symbol and it is up to you, the user, to invoke an event that will assign a badge to your user-defined functions, if possible. [47mDefbadge[0m will assign a badge to a function symbol, if possible, and [47mdefwarrant[0m will assign both a badge (if the function symbol doesn't already have one) and a [47m[warrant][0m, if possible. The macro [47m[defun$][0m is just an abbreviation for a [47mdefun[0m followed by a [47mdefwarrant[0m. Almost all primitive system functions already have badges. The complete list of badged primitives can be seen by evaluating (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP APPLY$ EV$) (strip-cars *badge-prim-falist*)) [47mBadge[0m is a defined function in ACL2. You can inspect its definition with ACL2 !>:pe badge and see that after handling the built-in symbols it defers to the undefined function [47m[badge-userfn][0m. In the evaluation theory, [47mbadge-userfn[0m has an attachment that returns the badge computed by [47mdefbadge[0m or [47mdefwarrant[0m. But in the proof theory, [47mbadge-userfn[0m is undefined and the [47m[warrant][0m for [47mfn[0m specifies the badge of [47mfn[0m. Thus, in the proof theory, you cannot reason about the application of a non-primitive function unless there is a warrant for the function available as a hypothesis. The rest of this documentation illustrates and explains what badges mean, starting with a few examples. ACL2 !>(badge 'cons) (APPLY$-BADGE 2 1 . T) ACL2 !>(badge 'apply$) (APPLY$-BADGE 2 1 :FN NIL) ACL2 !>(badge 'foldr) (APPLY$-BADGE 3 1 NIL :FN NIL) The last example assumes that [47mfoldr[0m has been defined with (defun$ foldr (lst fn init) (if (endp lst) init (apply$ fn (list (car lst) (foldr (cdr lst) fn init))))) In general, badges have the form [47m(APPLY$-BADGE n k . ilks)[0m, where [47mn[0m is the arity of [47mfn[0m, [47mk[0m is the out arity (i.e., the number of results returned by [47mfn[0m) and [47milks[0m is either [47mT[0m or a list of [47mn[0m tokens. Each token is either [47m:FN[0m, [47m:EXPR[0m, or [47mNIL[0m. The badge of [47mfn[0m, if any, is computed when the event [47m(defbadge fn)[0m or [47m(defwarrant fn)[0m completes successfully. See [47m[defbadge][0m for a sketch of the algorithm used to compute badges. Here though we are just concerned with how badges impact [47mapply$[0m. The [47milks[0m of a function, [47mfn[0m, determines the ``tameness requirements'' mentioned in the specification of [47m[apply$][0m. When the [47milks[0m component of [47mfn[0m's badge is a list, it has as many elements as there are formals to [47mfn[0m and each successive element is called the [3milk[0m of the corresponding formal. For example, given the definition of [47mfoldr[0m above and the badge shown for it, the first and third formals, [47mlst[0m and [47minit[0m, each have ilk [47mNIL[0m and the second formal, [47mfn[0m, has ilk [47m:FN[0m. In the special case that [47milks[0m is not a list it is [47mT[0m and we just say each formal has [3milk[0m [47mNIL[0m -- treating that [47mT[0m as a suitably long list of [47mNIL[0ms. Each non-[47mNIL[0m ilk imposes a [3mtameness requirement[0m on [47m(apply$ fn args)[0m. If a formal has ilk [47m:FN[0m the corresponding element of [47margs[0m must satisfy [47mtamep-functionp[0m. If a formal has ilk [47m:EXPR[0m the corresponding element of [47margs[0m must satisfy [47mtamep[0m. Ilk [47mNIL[0m imposes no requirement. (Thus, if the [47milks[0m of [47mfn[0m's badge is [47mT[0m, as it is for [47mcons[0m for example, there is no tameness requirement at all.) See [tame] for a discussion of the various notions of tameness. Informally, if a formal's ilk is [47m:FN[0m, the corresponding element of [47margs[0m must be a tame function symbol or well-formed [47mLAMBDA[0m object. If a formal's ilk is [47m:EXPR[0m, the corresponding element of [47margs[0m must be a tame expression. If a formal has ilk [47m:FN[0m then you are allowed to put a [47m[lambda$][0m expression in that slot. Any quoted [47mLAMBDA[0m object you explicitly write in such a slot must be well-formed (see [well-formed-lambda-objectp]). Well-formedness can be hard to achieve in quoted hand-written [47mLAMBDA[0m objects; we recommend that you use [47mlambda$[0m! But the restrictions on what can occupy a [47m:FN[0m slot are enforced when user input is translated into formal terms. It is possible to circumvent these syntactic checks without endangering soundness: axiomatically [47mapply$[0m puts no restrictions on its arguments, it just doesn't behave the way you might expect on ill-formed [47mLAMBDA[0m objects. See [gratuitous-lambda-object-restrictions]. [31;1mClarification[0m: The careful reader will note that the formal requirement on a [47m:FN[0m argument is that it must satisfy [47mtamep-functionp[0m. Inspection of the definition of [47mtamep-functionp[0m reveals that the argument must either be badged symbol with ilks [47mT[0m or else be a tame [47mLAMBDA[0m object. But in the informal description above we said that it must be a ``tame function symbol or a [3mwell-formed[0m [47mLAMBDA[0m object.'' Well-formedness implies tameness but they are not the same. What's going on? The reason for this and related discrepancies in the documentation is that there is a tension between the logical definition of [47mapply$[0m and the practical business of executing it. The former involves the existence of a model, soundness, and the difficulty of proving theorems about [47mapply$[0m. The latter involves the Common Lisp compiler. We want the logical foundations to be simple so we -- and you -- can reason about [47mapply$[0m, but the compiler imposes unavoidable and complicated restrictions. The upshot is that the logical foundations assign meaning to [47mLAMBDA[0m objects that cannot be compiled. Applying merely ``tame'' [47mLAMBDA[0ms is slower than applying ``well-formed'' ones. In a sense by acting like ``tame [47mLAMBDA[0m objects'' and ``well-formed [47mLAMBDA[0m objects'' are the same thing we're trying to trick you! If you ever have occasion to formally express the restrictions on [47mapply$[0m in some theorem, use [47mtamep-functionp[0m. But when you write concrete [47mLAMBDA[0m constants, try to keep them well-formed. We try to encourage this by providing [47m[lambda$][0m, which guarantees well-formedness at translate-time, and by implementing full well-formedness checks -- not just tameness checks -- on quoted [47mLAMBDA[0m objects in [47m:FN[0m slots. And we give you ways to circumvent these checks -- see [gratuitous-lambda-object-restrictions] -- if you really mean to.") (badge-userfn (apply$) "Undefined function used by [47mbadge[0m on non-primitives When [47m[badge][0m is given a non-primitive function symbol [47mfn[0m it calls this function to determine the badge of [47mfn[0m. But this function is undefined. In the proof theory, its value on a given function symbol [47mfn[0m is specified, if at all, by the [47m[warrant][0m for [47mfn[0m which must be available as a hypothesis in the formula being proved. In the evaluation theory, [47mbadge-userfn[0m has an attachment that makes it behave as though all warrants are assumed. See [47m[badge][0m for details.") (basics (programming) "Basic control structures for [programming] like [if] and [cond], binding operators like [let] and [flet], multiple-value constructs like [mv], and so forth. Subtopics [ACL2-count] A commonly used measure for justifying recursion [And] Conjunction [Booleanp] Recognizer for booleans [Case] Conditional based on if-then-else using [47m[eql][0m [Case-match] Pattern matching or destructuring [Cond] Conditional based on if-then-else [Equal] True equality [Flet] Local binding of function symbols [Good-bye] Quit entirely out of Lisp [Identity] The identity function [If] If-then-else function [Iff] Logical ``if and only if'' [Implies] Logical implication [Let] Binding of lexically scoped (local) variables [Let*] Binding of lexically scoped (local) variables [Macrolet] Local binding of macro symbols [Mv] Returning a multiple value [Mv-let] Calling multi-valued ACL2 functions [Not] Logical negation [Null] Recognizer for the empty list [Or] Disjunction [Progn$] Execute a sequence of forms and return the value of the last one [Quote] Create a constant [Return-last] Return the last argument, perhaps with side effects [Xor] Logical ``exclusive or''") (bdd (acl2 boolean-reasoning proof-automation) "Ordered binary decision diagrams with rewriting Note. The ACL2 bdd capability has been essentially superseded by GL; see [gl]. Ordered binary decision diagrams (OBDDs, often simply called BDDs) are a technique, originally published by Randy Bryant, for the efficient simplification of Boolean expressions. In ACL2 we combine this technique with rewriting to handle arbitrary ACL2 terms that can represent not only Boolean values, but non-Boolean values as well. In particular, we provide a setting for deciding equality of bit vectors (lists of Boolean values). An introduction to BDDs for the automated reasoning community may be found in ``Introduction to the OBDD Algorithm for the ATP Community'' by J Moore, [3mJournal of Automated Reasoning[0m (1994), pp. 33--45. (This paper also appears as Technical Report #84 from Computational Logic, Inc.) Further information about BDDs in ACL2 can be found in the subtopics of this [documentation] section. In particular, see [bdd-introduction] for a good starting place that provides a number of examples. See [hints] for a description of [47m:bdd[0m hints. For quick reference, here is an example; but only the [47m:vars[0m part of the hint is required, as explained in the documentation for [hints]. The values shown are the defaults. (:vars nil :bdd-constructors (cons) :prove t :literal :all) We suggest that you next visit the documentation topic [bdd-introduction]. Subtopics [Bdd-algorithm] Summary of the BDD algorithm in ACL2 [Bdd-introduction] Examples illustrating the use of BDDs in ACL2 [If*] For conditional rewriting with BDDs [Obdd] Ordered binary decision diagrams with rewriting [Show-bdd] Inspect failed BDD proof attempts") (bdd-algorithm (bdd) "Summary of the BDD algorithm in ACL2 The BDD algorithm in ACL2 uses a combination of manipulation of [47mIF[0m terms and unconditional rewriting. In this discussion we begin with some relevant mathematical theory. This is followed by a description of how ACL2 does BDDs, including concluding discussions of soundness, completeness, and efficiency. We recommend that you read the other documentation about BDDs in ACL2 before reading the rather technical material that follows. See [bdd]. Here is an outline of our presentation. Readers who want a user perspective, without undue mathematical theory, may wish to skip to Part (B), referring to Part (A) only on occasion if necessary. (A) [31;1mMathematical Considerations[0m (A1) BDD term order (A2) BDD-constructors and BDD terms, and their connection with aborting the BDD algorithm (A3) Canonical BDD terms (A4) A theorem stating the equivalence of provable and syntactic equality for canonical BDD terms (B) [31;1mAlgorithmic Considerations[0m (B1) BDD rules (rules used by the rewriting portion of the ACL2 BDD algorithm) (B2) Terms ``known to be Boolean'' (B3) An ``IF-lifting'' operation used by the algorithm, as well as an iterative version of that operation (B4) The ACL2 BDD algorithm (B5) Soundness and Completeness of the ACL2 BDD algorithm (B6) Efficiency considerations (A) [31;1mMathematical Considerations[0m (A1) [3mBDD term order[0m Our BDD algorithm creates a total ``BDD term order'' on ACL2 terms, on the fly. We use this order in our discussions below of IF-lifting and of canonical BDD terms, and in the algorithm's use of commutativity. The particular order is unimportant, except that we guarantee (for purposes of commutative functions) that constants are smaller in this order than non-constants. (A2) [3mBDD-constructors[0m (assumed to be [47m'(cons)[0m) and [3mBDD terms[0m We take as given a list of function symbols that we call the ``BDD-constructors.'' By default, the only BDD-constructor is [47m[cons][0m, although it is legal to specify any list of function symbols as the BDD-constructors, either by using the [ACL2-defaults-table] (see [ACL2-defaults-table]) or by supplying a [47m:BDD-CONSTRUCTORS[0m hint (see [hints]). Warning: this capability is largely untested and may produce undesirable results. Henceforth, except when explicitly stated to the contrary, we assume that BDD-constructors is [47m'(cons)[0m. Roughly speaking, a [bdd] term is the sort of [term] produced by our BDD algorithm, namely a tree with all [47m[cons][0m nodes lying above all non-[47mCONS[0m nodes. More formally, a [term] is said to be a [bdd] term if it contains [31;1mno[0m subterm of either of the following forms, where [47mf[0m is not [47mCONS[0m. (f ... (CONS ...) ...) (f ... 'x ...) ; where (consp x) = t We will see that whenever the BDD algorithm attempts to create a [term] that is not a [bdd] term, it aborts instead. Thus, whenever the algorithm completes without aborting, it creates a [bdd] term. (A3) [3mCanonical BDD terms[0m We can strengthen the notion of ``BDD term'' to a notion of ``canonical BDD term'' by imposing the following additional requirements, for every subterm of the form [47m(IF x y z)[0m: (a) [47mx[0m is a variable, and it precedes (in the BDD term order) every variable occurring in [47my[0m or [47mz[0m; (b) [47my[0m and [47mz[0m are syntactically distinct; and, (c) it is not the case that [47my[0m is [47mt[0m and [47mz[0m is [47mnil[0m. We claim that it follows easily from our description of the BDD algorithm that every term it creates is a canonical BDD term, assuming that the variables occurring in all such terms are treated by the algorithm as being Boolean (see (B2) below) and that the terms contain no function symbols other than [47mIF[0m and [47mCONS[0m. Thus, under those assumptions the following theorem shows that the BDD algorithm never creates distinct terms that are provably equal, a property that is useful for completeness and efficiency (as we explain in (B5) and (B6) below). (A4) [3mProvably equal canonical BDD terms are identical[0m We believe that the following theorem and proof are routine extensions of a standard result and proof to terms that allow calls of [47mCONS[0m. [31;1mTheorem[0m. Suppose that [47mt1[0m and [47mt2[0m are canonical BDD terms that contain no function symbols other than [47mIF[0m and [47mCONS[0m. Also suppose that [47m(EQUAL t1 t2)[0m is a theorem. Then [47mt1[0m and [47mt2[0m are syntactically identical. Proof of theorem: By induction on the total number of symbols occurring in these two terms. First suppose that at least one term is a variable; without loss of generality let it be [47mt1[0m. We must prove that [47mt2[0m is syntactically the same as [47mt1[0m. Now it is clearly consistent that [47m(EQUAL t1 t2)[0m is false if [47mt2[0m is a call of [47mCONS[0m (to see this, simply let [47mt1[0m be an value that is not a [47mCONSP[0m). Similarly, [47mt2[0m cannot be a constant or a variable other than [47mt1[0m. The remaining possibility to rule out is that [47mt2[0m is of the form [47m(IF t3 t4 t5)[0m, since by assumption its function symbol must be [47mIF[0m or [47mCONS[0m and we have already handled the latter case. Since [47mt2[0m is canonical, we know that [47mt3[0m is a variable. Since [47m(EQUAL t1 t2)[0m is provable, i.e., (EQUAL t1 (if t3 t4 t5)) is provable, it follows that we may substitute either [47mt[0m or [47mnil[0m for [47mt3[0m into this equality to obtain two new provable equalities. First, suppose that [47mt1[0m and [47mt3[0m are distinct variables. Then these substitutions show that [47mt1[0m is provably equal to both [47mt4[0m and [47mt5[0m (since [47mt3[0m does not occur in [47mt4[0m or [47mt5[0m by property (a) above, as [47mt2[0m is canonical), and hence [47mt4[0m and [47mt5[0m are provably equal to each other, which implies by the inductive hypothesis that they are the same term --- and this contradicts the assumption that [47mt2[0m is canonical (property (b)). Therefore [47mt1[0m and [47mt3[0m are the same variable, i.e., the equality displayed above is actually [47m(EQUAL t1 (if t1 t4 t5))[0m. Substituting [47mt[0m and then [47mnil[0m for [47mt1[0m into this provable equality lets us prove [47m(EQUAL t t4)[0m and [47m(EQUAL nil t5)[0m, which by the inductive hypothesis implies that [47mt4[0m is (syntactically) the term [47mt[0m and [47mt5[0m is [47mnil[0m. That is, [47mt2[0m is [47m(IF t1 t nil)[0m, which contradicts the assumption that [47mt2[0m is canonical (property (c)). Next, suppose that at least one term is a call of [47mIF[0m. Our first observation is that the other term is also a call of [47mIF[0m. For if the other is a call of [47mCONS[0m, then they cannot be provably equal, because the former has no function symbols other than [47mIF[0m and hence is Boolean when all its variables are assigned Boolean values. Also, if the other is a constant, then both branches of the [47mIF[0m term are provably equal to that constant and hence these branches are syntactically identical by the inductive hypothesis, contradicting property (b). Hence, we may assume for this case that both terms are calls of [47mIF[0m; let us write them as follows. t0: (IF t1 t2 t3) u0: (IF u1 u2 u3) Note that [47mt1[0m and [47mu1[0m are variables, by property (a) of canonical BDD terms. First we claim that [47mt1[0m does not strictly precede [47mu1[0m in the BDD term order. For suppose [47mt1[0m does strictly precede [47mu1[0m. Then property (a) of canonical BDD terms guarantees that [47mt1[0m does not occur in [47mu0[0m. Hence, an argument much like one used above shows that [47mu0[0m is provably equal to both [47mt2[0m (substituting [47mt[0m for [47mt1[0m) and [47mt3[0m (substituting [47mnil[0m for [47mt1[0m), and hence [47mt2[0m and [47mt3[0m are provably equal. That implies that they are identical terms, by the inductive hypothesis, which then contradicts property (b) for [47mt0[0m. Similarly, [47mu1[0m does not strictly precede [47mt1[0m in the BDD term order. Therefore, [47mt1[0m and [47mu1[0m are the same variable. By substituting [47mt[0m for this variable we see that [47mt2[0m and [47mu2[0m are provably equal, and hence they are equal by the inductive hypothesis. Similarly, by substituting [47mnil[0m for [47mt1[0m (and [47mu1[0m) we see that [47mt3[0m and [47mu3[0m are provably, hence syntactically, equal. We have covered all cases in which at least one term is a variable or at least one term is a call of [47mIF[0m. If both terms are constants, then provable and syntactic equality are clearly equivalent. Finally, then, we may assume that one term is a call of [47mCONS[0m and the other is a constant or a call of [47mCONS[0m. The constant case is similar to the [47mCONS[0m case if the constant is a [47mCONSP[0m, so we omit it; while if the constant is not a [47mCONSP[0m then it is not provably equal to a call of [47mCONS[0m; in fact it is provably [3mnot[0m equal! So, we are left with a final case, in which canonical BDD terms [47m(CONS t1 t2)[0m and [47m(CONS u1 u2)[0m are provably equal, and we want to show that [47mt1[0m and [47mu1[0m are syntactically equal as are [47mt2[0m and [47mu2[0m. These conclusions are easy consequences of the inductive hypothesis, since the ACL2 axiom [47mCONS-EQUAL[0m (which you can inspect using [47m:[0m[47m[pe][0m) shows that equality of the given terms is equivalent to the conjunction of [47m(EQUAL t1 t2)[0m and [47m(EQUAL u1 u2)[0m. Q.E.D. (B) [31;1mAlgorithmic Considerations[0m (B1) [3mBDD rules[0m A rule of class [47m:[0m[47m[rewrite][0m (see [rule-classes]) is said to be a ``[bdd] rewrite rule'' if and only if it satisfies the following criteria. (1) The rule is [enable]d. (2) Its [equivalence] relation is [47m[equal][0m. (3) It has no hypotheses. (4) Its [47m:[0m[47m[loop-stopper][0m field is [47mnil[0m, i.e., it is not a permutative rule. (5) All variables occurring in the rule occur in its left-hand side (i.e., there are no ``free variables''; see [rewrite]). A rule of class [47m:[0m[47m[definition][0m (see [rule-classes]) is said to be a ``[bdd] definition rule'' if it satisfies all the criteria above (except (4), which does not apply), and moreover the top function symbol of the left-hand side was not recursively (or mutually recursively) defined. Technical point: Note that this additional criterion is independent of whether or not the indicated function symbol actually occurs in the right-hand side of the rule. Both BDD rewrite rules and BDD definition rules are said to be ``BDD rules.'' (B2) [3mTerms ''known to be Boolean''[0m We apply the BDD algorithm in the context of a top-level goal to prove, namely, the goal at which the [47m:BDD[0m hint is attached. As we run the BDD algorithm, we allow ourselves to say that a set of [term]s is ``known to be Boolean'' if we can verify that the goal is provable from the assumption that at least one of the terms is not Boolean. Equivalently, we allow ourselves to say that a set of terms is ``known to be Boolean'' if we can verify that the original goal is provably equivalent to the assertion that if all terms in the set are Boolean, then the goal holds. The notion ``known to be Boolean'' is conservative in the sense that there are generally sets of terms for which the above equivalent criteria hold and yet the sets of terms are not noted as as being ``known to be Boolean.'' However, ACL2 uses a number of tricks, including [type-reasoning] and analysis of the structure of the top-level goal, to attempt to establish that a sufficiently inclusive set of terms is known to be Boolean. From a practical standpoint, the algorithm determines a set of terms known to be Boolean; we allow ourselves to say that each term in this set is ``known to be Boolean.'' The algorithm assumes that these terms are indeed Boolean, and can make use of that assumption. For example, if [47mt1[0m is known to be Boolean then the algorithm simplifies [47m(IF t1 t nil)[0m to [47mt1[0m; see (iv) in the discussion immediately below. (B3) [3mIF-lifting[0m and the [3mIF-lifting-for-IF loop[0m Suppose that one has a [term] of the form [47m(f ... (IF test x y) ...)[0m, where [47mf[0m is a function symbol other than [47mCONS[0m. Then we say that ``IF-lifting'' [47mtest[0m ``from'' this term produces the following term, which is provably equal to the given term. (if test (f ... x ...) ; resulting true branch (f ... y ...)) ; resulting false branch Here, we replace each argument of [47mf[0m of the form [47m(IF test .. ..)[0m, for the same [47mtest[0m, in the same way. In this case we say that ``IF-lifting applies to'' the given term, ``yielding the test'' [47mtest[0m and with the ``resulting two branches'' displayed above. Whenever we apply IF-lifting, we do so for the available [47mtest[0m that is least in the BDD term order (see (A1) above). We consider arguments [47mv[0m of [47mf[0m that are ``known to be Boolean'' (see above) to be replaced by [47m(IF v t nil)[0m for the purposes of IF-lifting, i.e., before IF-lifting is applied. There is one special case, however, for IF-lifting. Suppose that the given term is of the form [47m(IF v y z)[0m where [47mv[0m is a variable and is the test to be lifted out (i.e., it is least in the BDD term order among the potential tests). Moreover, suppose that neither [47my[0m nor [47mz[0m is of the form [47m(IF v W1 W2)[0m for that same [47mv[0m. Then IF-lifting does not apply to the given term. We may now describe the IF-lifting-for-IF loop, which applies to terms of the form [47m(IF test tbr fbr)[0m where the algorithm has already produced [47mtest[0m, [47mtbr[0m, and [47mfbr[0m. First, if [47mtest[0m is [47mnil[0m then we return [47mfbr[0m, while if [47mtest[0m is a non-[47mnil[0m constant or a call of [47mCONS[0m then we return [47mtbr[0m. Otherwise, we see if IF-lifting applies. If IF-lifting does not apply, then we return [47m(IF test tbr fbr)[0m. Otherwise, we apply IF-lifting to obtain a term of the form [47m(IF x y z)[0m, by lifting out the appropriate test. Now we recursively apply the IF-lifting-for-IF loop to the term [47m(IF x y z)[0m, unless any of the following special cases apply. (i) If [47my[0m and [47mz[0m are the same term, then return [47my[0m. (ii) Otherwise, if [47mx[0m and [47mz[0m are the same term, then replace [47mz[0m by [47mnil[0m before recursively applying IF-lifting-for-IF. (iii) Otherwise, if [47mx[0m and [47my[0m are the same term and [47my[0m is known to be Boolean, then replace [47my[0m by [47mt[0m before recursively applying IF-lifting-for-IF. (iv) If [47mz[0m is [47mnil[0m and either [47mx[0m and [47my[0m are the same term or [47mx[0m is ``known to be Boolean'' and [47my[0m is [47mt[0m, then return [47mx[0m. NOTE: When a variable [47mx[0m is known to be Boolean, it is easy to see that the form [47m(IF x t nil)[0m is always reduced to [47mx[0m by this algorithm. (B4) [3mThe ACL2 BDD algorithm[0m We are now ready to present the BDD algorithm for ACL2. It is given an ACL2 [term], [47mx[0m, as well as an association list [47mva[0m that maps variables to terms, including all variables occurring in [47mx[0m. We maintain the invariant that whenever a variable is mapped by [47mva[0m to a term, that term has already been constructed by the algorithm, except: initially [47mva[0m maps every variable occurring in the top-level term to itself. The algorithm proceeds as follows. We implicitly ordain that whenever the BDD algorithm attempts to create a [term] that is not a [bdd] term (as defined above in (A2)), it aborts instead. Thus, whenever the algorithm completes without aborting, it creates a [bdd] term. If [47mx[0m is a variable, return the result of looking it up in [47mva[0m. If [47mx[0m is a constant, return [47mx[0m. If [47mx[0m is of the form [47m(IF test tbr fbr)[0m, then first run the algorithm on [47mtest[0m with the given [47mva[0m to obtain [47mtest'[0m. If [47mtest'[0m is [47mnil[0m, then return the result [47mfbr'[0m of running the algorithm on [47mfbr[0m with the given [47mva[0m. If [47mtest'[0m is a constant other than [47mnil[0m, or is a call of [47mCONS[0m, then return the result [47mtbr'[0m of running the algorithm on [47mtbr[0m with the given [47mva[0m. If [47mtbr[0m is identical to [47mfbr[0m, return [47mtbr[0m. Otherwise, return the result of applying the IF-lifting-for-IF loop (described above) to the term [47m(IF test' tbr' fbr')[0m. If [47mx[0m is of the form [47m(IF* test tbr fbr)[0m, then compute the result exactly as though [47m[if][0m were used rather than [47m[if*][0m, except that if [47mtest'[0m is not a constant or a call of [47mCONS[0m (see paragraph above), then abort the BDD computation. Informally, the tests of [47m[if*][0m terms are expected to ``resolve.'' NOTE: This description shows how [47m[if*][0m can be used to implement conditional rewriting in the BDD algorithm. If [47mx[0m is a [47mLAMBDA[0m expression [47m((LAMBDA vars body) . args)[0m (which often corresponds to a [47m[let][0m term; see [let]), then first form an alist [47mva'[0m by binding each [47mv[0m in [47mvars[0m to the result of running the algorithm on the corresponding member of [47margs[0m, with the current alist [47mva[0m. Then, return the result of the algorithm on [47mbody[0m in the alist [47mva'[0m. Otherwise, [47mx[0m is of the form [47m(f x1 x2 ... xn)[0m, where [47mf[0m is a function symbol other than [47m[if][0m or [47m[if*][0m. In that case, let [47mxi'[0m be the result of running the algorithm on [47mxi[0m, for [47mi[0m from 1 to [47mn[0m, using the given alist [47mva[0m. First there are a few special cases. If [47mf[0m is [47m[equal][0m then we return [47mt[0m if [47mx1'[0m is syntactically identical to [47mx2'[0m (where this test is very fast; see (B6) below); we return [47mx1'[0m if it is known to be Boolean and [47mx2'[0m is [47mt[0m; and similarly, we return [47mx2'[0m if it is known to be Boolean and [47mx1'[0m is [47mt[0m. Next, if each [47mxi'[0m is a constant and the [47m:[0m[47m[executable-counterpart][0m of [47mf[0m is enabled, then the result is obtained by computation. Next, if [47mf[0m is [47m[booleanp][0m and [47mx1'[0m is known to be Boolean, [47mt[0m is returned. Otherwise, we proceed as follows, first possibly swapping the arguments if they are out of (the BDD term) order and if [47mf[0m is known to be commutative (see below). If a BDD rewrite rule (as defined above) matches the term [47m(f x1'... xn')[0m, then the most recently stored such rule is applied. If there is no such match and [47mf[0m is a BDD-constructor, then we return [47m(f x1'... xn')[0m. Otherwise, if a BDD definition rule matches this term, then the most recently stored such rule (which will usually be the original definition for most users) is applied. If none of the above applies and neither does IF-lifting, then we return [47m(f x1'... xn')[0m. Otherwise we apply IF-lifting to [47m(f x1'... xn')[0m to obtain a term [47m(IF test tbr fbr)[0m; but we aren't done yet. Rather, we run the BDD algorithm (using the same alist) on [47mtbr[0m and [47mfbr[0m to obtain terms [47mtbr'[0m and [47mfbr'[0m, and we return [47m(IF test tbr' fbr')[0m unless [47mtbr'[0m is syntactically identical to [47mfbr'[0m, in which case we return [47mtbr'[0m. When is it the case that, as said above, ``[47mf[0m is known to be commutative''? This happens when an enabled rewrite rule is of the form [47m(EQUAL (f X Y) (f Y X))[0m. Regarding swapping the arguments in that case: recall that we may assume very little about the BDD term order, essentially only that we swap the two arguments when the second is a constant and the first is not, for example, in [47m(+ x 1)[0m. Other than that situation, one cannot expect to predict accurately when the arguments of commutative operators will be swapped. (B5) Soundness and Completeness of the ACL2 BDD algorithm Roughly speaking, ``soundness'' means that the BDD algorithm should give correct answers, and ``completeness'' means that it should be powerful enough to prove all true facts. Let us make the soundness claim a little more precise, and then we'll address completeness under suitable hypotheses. [31;1mClaim[0m (Soundness). If the ACL2 BDD algorithm runs to completion on an input term [47mt0[0m, then it produces a result that is provably equal to [47mt0[0m. We leave the proof of this claim to the reader. The basic idea is simply to check that each step of the algorithm preserves the meaning of the term under the bindings in the given alist. Let us start our discussion of completeness by recalling the theorem proved above in (A4). [31;1mTheorem[0m. Suppose that [47mt1[0m and [47mt2[0m are canonical BDD terms that contain no function symbols other than [47mIF[0m and [47mCONS[0m. Also suppose that [47m(EQUAL t1 t2)[0m is a theorem. Then [47mt1[0m and [47mt2[0m are syntactically identical. Below we show how this theorem implies the following completeness property of the ACL2 BDD algorithm. We continue to assume that [47mCONS[0m is the only BDD-constructor. [31;1mClaim[0m (Completeness). Suppose that [47mt1[0m and [47mt2[0m are provably equal terms, under the assumption that all their variables are known to be Boolean. Assume further that under this same assumption, top-level runs of the ACL2 BDD algorithm on these terms return terms that contain only the function symbols [47mIF[0m and [47mCONS[0m. Then the algorithm returns the same term for both [47mt1[0m and [47mt2[0m, and the algorithm reduces [47m(EQUAL t1 t2)[0m to [47mt[0m. Why is this claim true? First, notice that the second part of the conclusion follows immediately from the first, by definition of the algorithm. Next, notice that the terms [47mu1[0m and [47mu2[0m obtained by running the algorithm on [47mt1[0m and [47mt2[0m, respectively, are provably equal to [47mt1[0m and [47mt2[0m, respectively, by the Soundness Claim. It follows that [47mu1[0m and [47mu2[0m are provably equal to each other. Since these terms contain no function symbols other than [47mIF[0m or [47mCONS[0m, by hypothesis, the Claim now follows from the Theorem above together with the following lemma. [31;1mLemma[0m. Suppose that the result of running the ACL2 BDD algorithm on a top-level term [47mt0[0m is a term [47mu0[0m that contains only the function symbols [47mIF[0m and [47mCONS[0m, where all variables of [47mt0[0m are known to be Boolean. Then [47mu0[0m is a canonical BDD term. Proof: left to the reader. Simply follow the definition of the algorithm, with a separate argument for the IF-lifting-for-IF loop. Finally, let us remark on the assumptions of the Completeness Claim above. The assumption that all variables are known to be Boolean is often true; in fact, the system uses the forward-chaining rule [47mboolean-listp-forward[0m (you can see it using [47m:[0m[47m[pe][0m) to try to establish this assumption, if your theorem has a form such as the following. (let ((x (list x0 x1 ...)) (y (list y0 y1 ...))) (implies (and (boolean-listp x) (boolean-listp y)) ...)) Moreover, the [47m:BDD[0m hint can be used to force the prover to abort if it cannot check that the indicated variables are known to be Boolean; see [hints]. Finally, consider the effect in practice of the assumption that the terms resulting from application of the algorithm contain calls of [47mIF[0m and [47mCONS[0m only. Typical use of BDDs in ACL2 takes place in a theory (see [theories]) in which all relevant non-recursive function symbols are enabled and all recursive function symbols possess enabled BDD rewrite rules that tell them how open up. For example, such a rule may say how to expand on a given function call's argument that has the form [47m(CONS a x)[0m, while another may say how to expand when that argument is [47mnil[0m). (See for example the rules [47mappend-cons[0m and [47mappend-nil[0m in the documentation for [47m[if*][0m.) We leave it to future work to formulate a theorem that guarantees that the BDD algorithm produces terms containing calls only of [47mIF[0m and [47mCONS[0m assuming a suitably ``complete'' collection of rewrite rules. (B6) [3mEfficiency considerations[0m Following Bryant's algorithm, we use a graph representation of [term]s created by the BDD algorithm's computation. This representation enjoys some important properties. (Time efficiency) The test for syntactic equality of BDD terms is very fast. (Space efficiency) Equal BDD data structures are stored identically in memory. [3mImplementation note.[0m The representation actually uses a sort of hash table for BDD terms that is implemented as an ACL2 1-dimensional array. See [arrays]. In addition, we use a second such hash table to avoid recomputing the result of applying a function symbol to the result of running the algorithm on its arguments. We believe that these uses of hash tables are standard. They are also discussed in Moore's paper on BDDs; see [bdd] for the reference.") (bdd-introduction (bdd) "Examples illustrating the use of BDDs in ACL2 See [bdd] for a brief introduction to BDDs in ACL2 and for pointers to other documentation on BDDs in ACL2. Here, we illustrate the use of BDDs in ACL2 by way of some examples. For a further example, see [if*]. Let us begin with a really simple example. (We will explain the [47m:bdd[0m hint [47m(:vars nil)[0m below.) ACL2 !>(thm (equal (if a b c) (if (not a) c b)) :hints (("Goal" :bdd (:vars nil)))) ; Prove with BDDs [Note: A hint was supplied for the goal above. Thanks!] But simplification with BDDs (7 nodes) reduces this to T, using the :definitions EQUAL and NOT. Q.E.D. Summary Form: ( THM ...) Rules: ((:DEFINITION EQUAL) (:DEFINITION NOT)) Warnings: None Time: 0.18 seconds (prove: 0.05, print: 0.02, other: 0.12) Proof succeeded. ACL2 !> The [47m:bdd[0m hint [47m(:vars nil)[0m indicates that BDDs are to be used on the indicated goal, and that any so-called ``variable ordering'' may be used: ACL2 may use a convenient order that is far from optimal. It is beyond the scope of the present documentation to address the issue of how the user may choose good variable orderings. Someday our implementation of BDDs may be improved to include heuristically-chosen variable orderings rather than rather random ones. Here is a more interesting example. (defun v-not (x) ; Complement every element of a list of Booleans. (if (consp x) (cons (not (car x)) (v-not (cdr x))) nil)) ; Now we prove a rewrite rule that explains how to open up v-not on ; a consp. (defthm v-not-cons (equal (v-not (cons x y)) (cons (not x) (v-not y)))) ; Finally, we prove for 7-bit lists that v-not is self-inverting. (thm (let ((x (list x0 x1 x2 x3 x4 x5 x6))) (implies (boolean-listp x) (equal (v-not (v-not x)) x))) :hints (("Goal" :bdd ;; Note that this time we specify a variable order. (:vars (x0 x1 x2 x3 x4 x5 x6))))) It turns out that the variable order doesn't seem to matter in this example; using several orders we found that 30 nodes were created, and the proof time was about 1/10 of a second on a (somewhat enhanced) Sparc 2. The same proof took about a minute and a half without any [47m:bdd[0m hint! This observation is a bit misleading perhaps, since the theorem for arbitrary [47mx[0m, (thm (implies (boolean-listp x) (equal (v-not (v-not x)) x))) only takes about 1.5 times as long as the [47m:bdd[0m proof for 7 bits, above! Nevertheless, BDDs can be very useful in reducing proof time, especially when there is no regular structure to facilitate proof by induction, or when the induction scheme is so complicated to construct that significant user effort is required to get the proof by induction to go through. Finally, consider the preceding example, with a [47m:bdd[0m hint of (say) [47m(:vars nil)[0m, but with the rewrite rule [47mv-not-cons[0m above disabled. In that case, the proof fails, as we see below. That is because the BDD algorithm in ACL2 uses hypothesis-free [47m:[0m[rewrite] rules, [47m:[0m[47m[executable-counterpart][0m[47ms[0m, and nonrecursive definitions, but it does not use recursive definitions. Notice that when we issue the [47m(show-bdd)[0m command, the system's response clearly shows that we need a rewrite rule for simplifying terms of the form [47m(v-not (cons ...))[0m. ACL2 !>(thm (let ((x (list x0 x1 x2 x3 x4 x5 x6))) (implies (boolean-listp x) (equal (v-not (v-not x)) x))) :hints (("Goal" :bdd (:vars nil) :in-theory (disable v-not-cons)))) [Note: A hint was supplied for the goal above. Thanks!] ACL2 Error in ( THM ...): Attempted to create V-NOT node during BDD processing with an argument that is a call of a bdd-constructor, which would produce a non-BDD term (as defined in :DOC bdd-algorithm). See :DOC show-bdd. Summary Form: ( THM ...) Rules: NIL Warnings: None Time: 0.58 seconds (prove: 0.13, print: 0.00, other: 0.45) ******** FAILED ******** See :DOC failure ******** FAILED ******** ACL2 !>(show-bdd) BDD computation on Goal yielded 17 nodes. ------------------------------ BDD computation was aborted on Goal, and hence there is no falsifying assignment that can be constructed. Here is a backtrace of calls, starting with the top-level call and ending with the one that led to the abort. See :DOC show-bdd. (LET ((X (LIST X0 X1 X2 X3 X4 X5 ...))) (IMPLIES (BOOLEAN-LISTP X) (EQUAL (V-NOT (V-NOT X)) X))) alist: ((X6 X6) (X5 X5) (X4 X4) (X3 X3) (X2 X2) (X1 X1) (X0 X0)) (EQUAL (V-NOT (V-NOT X)) X) alist: ((X (LIST X0 X1 X2 X3 X4 X5 ...))) (V-NOT (V-NOT X)) alist: ((X (LIST X0 X1 X2 X3 X4 X5 ...))) (V-NOT X) alist: ((X (LIST X0 X1 X2 X3 X4 X5 ...))) ACL2 !> The term that has caused the BDD algorithm to abort is thus [47m(V-NOT X)[0m, where [47mX[0m has the value [47m(LIST X0 X1 X2 X3 X4 X5 ...)[0m, i.e., [47m(CONS X0 (LIST X1 X2 X3 X4 X5 ...))[0m. Thus, we see the utility of introducing a rewrite rule to simplify terms of the form [47m(V-NOT (CONS ...))[0m. The moral of this story is that if you get an error of the sort shown above, you may find it useful to execute the command [47m(show-bdd)[0m and use the result as advice that suggests the left hand side of a rewrite rule. Here is another sort of failed proof. In this version we have omitted the hypothesis that the input is a bit vector. Below we use [47mshow-bdd[0m to see what went wrong, and use the resulting information to construct a counterexample. This failed proof corresponds to a slightly modified input theorem, in which [47mx[0m is bound to the 4-element list [47m(list x0 x1 x2 x3)[0m. ACL2 !>(thm (let ((x (list x0 x1 x2 x3))) (equal (v-not (v-not x)) x)) :hints (("Goal" :bdd ;; This time we do not specify a variable order. (:vars nil)))) [Note: A hint was supplied for the goal above. Thanks!] ACL2 Error in ( THM ...): The :BDD hint for the current goal has successfully simplified this goal, but has failed to prove it. Consider using (SHOW-BDD) to suggest a counterexample; see :DOC show-bdd. Summary Form: ( THM ...) Rules: NIL Warnings: None Time: 0.18 seconds (prove: 0.07, print: 0.00, other: 0.12) ******** FAILED ******** See :DOC failure ******** FAILED ******** ACL2 !>(show-bdd) BDD computation on Goal yielded 73 nodes. ------------------------------ Falsifying constraints: ((X0 "Some non-nil value") (X1 "Some non-nil value") (X2 "Some non-nil value") (X3 "Some non-nil value") ((EQUAL 'T X0) T) ((EQUAL 'T X1) T) ((EQUAL 'T X2) T) ((EQUAL 'T X3) NIL)) ------------------------------ Term obtained from BDD computation on Goal: (IF X0 (IF X1 (IF X2 (IF X3 (IF # # #) (IF X3 # #)) (IF X2 'NIL (IF X3 # #))) (IF X1 'NIL (IF X2 (IF X3 # #) (IF X2 # #)))) (IF X0 'NIL (IF X1 (IF X2 (IF X3 # #) (IF X2 # #)) (IF X1 'NIL (IF X2 # #))))) ACL2 Query (:SHOW-BDD): Print the term in full? (N, Y, W or ?): n ; I've seen enough. The assignment shown above suggests ; (though not conclusively) that if we bind x3 to a non-nil ; value other than T, and bind x0, x1, and x2 to t, then we ; this may give us a counterexample. ACL2 !>(let ((x0 t) (x1 t) (x2 t) (x3 7)) (let ((x (list x0 x1 x2 x3))) ;; Let's use LIST instead of EQUAL to see how the two ;; lists differ. (list (v-not (v-not x)) x))) ((T T T T) (T T T 7)) ACL2 !> See [if*] for another example.") (bibliography (pointers) "See publications.") (binary-* (* acl2-built-ins) "Multiplication function Completion Axiom ([47mcompletion-of-*[0m): (equal (binary-* x y) (if (acl2-numberp x) (if (acl2-numberp y) (binary-* x y) 0) 0)) [Guard] for [47m(binary-* x y)[0m: (and (acl2-numberp x) (acl2-numberp y)) Notice that like all arithmetic functions, [47mbinary-*[0m treats non-numeric inputs as [47m0[0m. Calls of the macro [47m[*][0m expand to calls of [47mbinary-*[0m; see [*].") (binary-+ (+ acl2-built-ins) "Addition function Completion Axiom ([47mcompletion-of-+[0m): (equal (binary-+ x y) (if (acl2-numberp x) (if (acl2-numberp y) (binary-+ x y) x) (if (acl2-numberp y) y 0))) [Guard] for [47m(binary-+ x y)[0m: (and (acl2-numberp x) (acl2-numberp y)) Notice that like all arithmetic functions, [47mbinary-+[0m treats non-numeric inputs as [47m0[0m. Thus, the following are theorems. (thm (equal (+ (fix x) y) (+ x y))) (thm (equal (+ x (fix y)) (+ x y))) Calls of the macro [47m[+][0m expand to calls of [47mbinary-+[0m; see [+].") (binary-append (append acl2-built-ins) "[concatenate] two lists This binary function implements [47m[append][0m, which is a macro in ACL2. See [append] The [guard] for [47mbinary-append[0m requires the first argument to be a [47m[true-listp][0m. [31;1mFunction: [0m<binary-append> (defun binary-append (x y) (declare (xargs :guard (true-listp x))) (cond ((endp x) y) (t (cons (car x) (binary-append (cdr x) y)))))") (binary-df* (pointers) "See [df].") (binary-df+ (pointers) "See [df].") (binary-df-log (pointers) "See [df].") (binary-df/ (pointers) "See [df].") (bind-free (rewrite linear definition) "To bind free variables of a rewrite, definition, or linear rule Examples: (IMPLIES (AND (RATIONALP LHS) (RATIONALP RHS) (BIND-FREE (FIND-MATCH-IN-PLUS-NESTS LHS RHS) (X))) (EQUAL (EQUAL LHS RHS) (EQUAL (+ (- X) LHS) (+ (- X) RHS)))) (IMPLIES (AND (BIND-FREE (FIND-RATIONAL-MATCH-IN-TIMES-NESTS LHS RHS MFC STATE) (X)) (RATIONALP X) (CASE-SPLIT (NOT (EQUAL X 0)))) (EQUAL (< LHS RHS) (IF (< 0 X) (< (* (/ X) LHS) (* (/ X) RHS)) (< (* (/ X) RHS) (* (/ X) LHS))))) General Forms: (BIND-FREE term var-list) (BIND-FREE term t) (BIND-FREE term) A rule which uses a [47mbind-free[0m hypothesis has similarities to both a rule which uses a [47m[syntaxp][0m hypothesis and to a [47m:[0m[47m[meta][0m rule. [47mBind-free[0m is like [47m[syntaxp][0m, in that it logically always returns [47mt[0m but may affect the application of a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule when it is called at the top-level of a hypothesis. It is like a [47m:[0m[47m[meta][0m rule, in that it allows the user to perform transformations of terms under programmatic control. Note that a [47mbind-free[0m hypothesis does not, in general, deal with the meaning or semantics or values of the terms, but rather with their syntactic forms. Before attempting to write a rule which uses [47mbind-free[0m, the user should be familiar with [47m[syntaxp][0m and the internal form that ACL2 uses for terms. This internal form is similar to what the user sees, but there are subtle and important differences. [47m[Trans][0m can be used to view this internal form. Just as for a [47m[syntaxp][0m hypothesis, there are two basic types of [47mbind-free[0m hypotheses. The simpler type of [47mbind-free[0m hypothesis may be used as the nth hypothesis in a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule whose [47m:[0m[47m[corollary][0m is [47m(implies (and hyp1 ... hypn ... hypk) (equiv lhs rhs))[0m provided [47mterm[0m is a term, [47mterm[0m contains at least one variable, and every variable occurring freely in [47mterm[0m occurs freely in [47mlhs[0m or in some [47mhypi[0m, [47mi<n[0m. In addition, [47mterm[0m must not use any stobjs. Later below we will describe the second type, an [3mextended[0m [47mbind-free[0m hypothesis, which is similar except that it may use [47m[state][0m and [47m[mfc][0m. Whether simple or extended, a [47mbind-free[0m hypothesis may return an alist that binds free variables, as explained below, or it may return a list of such alists. We focus on the first of these cases: return of a single binding alist. We conclude our discussion with a section that covers the other case: return of a list of alists. We begin our description of [47mbind-free[0m by examining the first example above in some detail. We wish to write a rule which will cancel ``like'' addends from both sides of an equality. Clearly, one could write a series of rules such as (DEFTHM THE-HARD-WAY-2-1 (EQUAL (EQUAL (+ A X B) (+ X C)) (EQUAL (+ A B) (FIX C)))) with one rule for each combination of positions the matching addends might be found in (if one knew before-hand the maximum number of addends that would appear in a sum). But there is a better way. (In what follows, we assume the presence of an appropriate set of rules for simplifying sums.) Consider the following definitions and theorem: (DEFUN INTERSECTION-EQUAL (X Y) (COND ((ENDP X) NIL) ((MEMBER-EQUAL (CAR X) Y) (CONS (CAR X) (INTERSECTION-EQUAL (CDR X) Y))) (T (INTERSECTION-EQUAL (CDR X) Y)))) (DEFUN PLUS-LEAVES (TERM) (IF (EQ (FN-SYMB TERM) 'BINARY-+) (CONS (FARGN TERM 1) (PLUS-LEAVES (FARGN TERM 2))) (LIST TERM))) (DEFUN FIND-MATCH-IN-PLUS-NESTS (LHS RHS) (IF (AND (EQ (FN-SYMB LHS) 'BINARY-+) (EQ (FN-SYMB RHS) 'BINARY-+)) (LET ((COMMON-ADDENDS (INTERSECTION-EQUAL (PLUS-LEAVES LHS) (PLUS-LEAVES RHS)))) (IF COMMON-ADDENDS (LIST (CONS 'X (CAR COMMON-ADDENDS))) NIL)) NIL)) (DEFTHM CANCEL-MATCHING-ADDENDS-EQUAL (IMPLIES (AND (RATIONALP LHS) (RATIONALP RHS) (BIND-FREE (FIND-MATCH-IN-PLUS-NESTS LHS RHS) (X))) (EQUAL (EQUAL LHS RHS) (EQUAL (+ (- X) LHS) (+ (- X) RHS))))) How is this rule applied to the following term? (equal (+ 3 (expt a n) (foo a c)) (+ (bar b) (expt a n))) As mentioned above, the internal form of an ACL2 term is not always what one sees printed out by ACL2. In this case, by using [47m:[0m[47m[trans][0m one can see that the term is stored internally as (equal (binary-+ '3 (binary-+ (expt a n) (foo a c))) (binary-+ (bar b) (expt a n))). When ACL2 attempts to apply [47mcancel-matching-addends-equal[0m to the term under discussion, it first forms a substitution that instantiates the left-hand side of the conclusion so that it is identical to the target term. This substitution is kept track of by the substitution alist: ((LHS . (binary-+ '3 (binary-+ (expt a n) (foo a c)))) (RHS . (binary-+ (bar b) (expt a n)))). ACL2 then attempts to relieve the hypotheses in the order they were given. Ordinarily this means that we instantiate each hypothesis with our substitution and then attempt to rewrite the resulting instance to true. Thus, in order to relieve the first hypothesis, we rewrite: (RATIONALP (binary-+ '3 (binary-+ (expt a n) (foo a c)))). Let us assume that the first two hypotheses rewrite to [47mt[0m. How do we relieve the [47mbind-free[0m hypothesis? Just as for a [47m[syntaxp][0m hypothesis, ACL2 evaluates [47m(find-match-in-plus-nests lhs rhs)[0m in an environment where [47mlhs[0m and [47mrhs[0m are instantiated as determined by the substitution. In this case we evaluate (FIND-MATCH-IN-PLUS-NESTS '(binary-+ '3 (binary-+ (expt a n) (foo a c))) '(binary-+ (bar b) (expt a n))). Observe that, just as in the case of a [47m[syntaxp][0m hypothesis, we substitute the quotation of the variables bindings into the term to be evaluated. See [syntaxp] for the reasons for this. The result of this evaluation, [47m((X . (EXPT A N)))[0m, is then used to extend the substitution alist: ((X . (EXPT A N)) (LHS . (binary-+ '3 (binary-+ (expt a n) (foo a c)))) (RHS . (binary-+ (bar b) (expt a n)))), and this extended substitution determines [47mcancel-matching-addends-equal[0m's result: (EQUAL (+ (- X) LHS) (+ (- X) RHS)) ==> (EQUAL (+ (- (EXPT A N)) 3 (EXPT A N) (FOO A C)) (+ (- (EXPT A N)) (BAR B) (EXPT A N))). Question: What is the internal form of this result? Hint: Use [47m:[0m[47m[trans][0m. When this rule fires, it adds the negation of a common term to both sides of the equality by selecting a binding for the otherwise-free variable [47mx[0m, under programmatic control. Note that other mechanisms such as the binding of [free-variables] may also extend the substitution alist. Just as for a [47m[syntaxp][0m test, a [47mbind-free[0m form signals failure by returning [47mnil[0m. However, while a [47m[syntaxp][0m test signals success by returning true, a [47mbind-free[0m form signals success by returning an alist which is used to extend the current substitution alist. Because of this use of the alist, there are several restrictions on it --- in particular the alist must only bind variables, these variables must not be already bound by the substitution alist, and the variables must be bound to ACL2 terms. If [47mterm[0m returns an alist and the alist meets these restrictions, we append the alist to the substitution alist and use the result as the new current substitution alist. This new current substitution alist is then used when we attempt to relieve the next hypothesis or, if there are no more, instantiate the right hand side of the rule. There is also a second, optional, [47mvar-list[0m argument to a [47mbind-free[0m hypothesis. If provided, it must be either [47mt[0m, [47mnil[0m, or a non-empty list of variables. If it is not provided, it defaults to [47mt[0m; and it is also treated as [47mt[0m if the value provided is [47mnil[0m. If it is a non-empty list of variables, this second argument is used to place a further restriction on the possible values of the alist to be returned by [47mterm[0m: any variables bound in the alist must be present in that list of variables. We strongly recommend the use of this list of variables, as that list is considered to contribute to the list of variables in the hypotheses of a linear rule; see [linear], in particular condition (b) mentioned there regarding a requirement that maximal terms and hypotheses must suffice for instantiating all the variables in the conclusion. If [47mvar-list[0m is [47mt[0m (either explicitly or implicitly, as described above), then that condition is considered to be met trivially; this could prevent ACL2 from rejecting ineffective linear rules. An extended [47mbind-free[0m hypothesis is similar to the simple type described above, but it uses two additional variables, [47mmfc[0m and [47mstate[0m, which must not be bound by the left hand side or an earlier hypothesis of the rule. They must be the last two variables mentioned by [47mterm[0m: first [47mmfc[0m, then [47mstate[0m. These two variables give access to the functions [47mmfc-[0mxxx; see [extended-metafunctions]. As described there, [47mmfc[0m is bound to the so-called metafunction-context and [47mstate[0m to ACL2's [47m[state][0m. See [bind-free-examples] for examples of the use of these extended [47mbind-free[0m hypotheses. [31;1mSECTION[0m: Returning a list of alists. As promised above, we conclude with a discussion of the case that evaluation of the [47mbind-free[0m term produces a list of alists, [47mx[0m, rather than a single alist. In this case each member [47mb[0m of [47mx[0m is considered in turn, starting with the first and proceeding through the list. Each such [47mb[0m is handled exactly as discussed above, as though it were the result of evaluating the [47mbind-free[0m term. Thus, each [47mb[0m extends the current variable binding alist, and all remaining hypotheses are then relieved, as though [47mb[0m had been the value obtained by evaluating the [47mbind-free[0m term. As soon as one such [47mb[0m leads to successful relieving of all remaining hypotheses, the process of relieving hypotheses concludes, so no further members of [47mx[0m are considered. We illustrate with a simple pedagogical example. First introduce functions [47mp1[0m and [47mp2[0m such that a rewrite rule specifies that [47mp2[0m implies [47mp1[0m, but with a free variable. (defstub p1 (x) t) (defstub p2 (x y) t) (defaxiom p2-implies-p1 (implies (p2 x y) (p1 x))) If we add the following axiom, then [47m(p1 x)[0m follows logically for all [47mx[0m. (defaxiom p2-instance (p2 v (cons v 4))) Unfortunately, evaluation of [47m(thm (p1 a))[0m fails, because ACL2 fails to bind the free variable [47my[0m in order to apply the rule [47mp2-instance[0m. Let's define a function that produces a list of alists, each binding the variable [47my[0m. Of course, we know that only the middle one below is necessary in this simple example. In more complex examples, one might use heuristics to construct such a list of alists. (defun my-alists (x) (list (list (cons 'y (fcons-term* 'cons x ''3))) (list (cons 'y (fcons-term* 'cons x ''4))) (list (cons 'y (fcons-term* 'cons x ''5))))) The following rewrite rule uses [47mbind-free[0m to return a list of candidate alists binding [47my[0m. (defthm p2-implies-p1-better (implies (and (bind-free (my-alists x) (y)) ; the second argument, (y), is optional (p2 x y)) (p1 x))) Now the proof succeeds for [47m(thm (p1 a))[0m. Why? When ACL2 applies the [47mrewrite[0m rule [47mp2-implies-p1-better[0m, it evaluates [47mmy-alists[0m, as we can see from the following [trace], to bind [47my[0m in three different alists. ACL2 !>(thm (p1 a)) 1> (ACL2_*1*_ACL2::MY-ALISTS A) <1 (ACL2_*1*_ACL2::MY-ALISTS (((Y CONS A '3)) ((Y CONS A '4)) ((Y CONS A '5)))) Q.E.D. The first alist, binding [47my[0m to [47m(cons a '3)[0m, fails to allow the hypothesis [47m(p2 x y)[0m to be proved. But the next binding of [47my[0m, to [47m(cons a '4)[0m, succeeds: then the current binding alist is [47m((x . a) (y . (cons a '4)))[0m, for which the hypothesis [47m(p2 x y)[0m rewrites to true using the rewrite rule [47mp2-instance[0m. Subtopics [Bind-free-examples] Examples pertaining to [47m[bind-free][0m hypotheses") (bind-free-examples (bind-free) "Examples pertaining to [47m[bind-free][0m hypotheses See [bind-free] for a basic discussion of the use of [47mbind-free[0m to control rewriting. Note that the examples below all illustrate the common case in which a [47mbind-free[0m hypothesis generates a binding alist. See [bind-free], in particular the final section, for a discussion of the case that instead a list of binding alists is generated. We give examples of the use of [47m[bind-free][0m hypotheses from the perspective of a user interested in reasoning about arithmetic, but it should be clear that [47m[bind-free][0m can be used for many other purposes also. EXAMPLE 1: Cancel a common factor. (defun bind-divisor (a b) ; If a and b are polynomials with a common factor c, we return a ; binding for x. We could imagine writing get-factor to compute the ; gcd, or simply to return a single non-invertible factor. (let ((c (get-factor a b))) (and c (list (cons 'x c))))) (defthm cancel-factor ;; We use case-split here to ensure that, once we have selected ;; a binding for x, the rest of the hypotheses will be relieved. (implies (and (acl2-numberp a) (acl2-numberp b) (bind-free (bind-divisor a b) (x)) (case-split (not (equal x 0))) (case-split (acl2-numberp x))) (iff (equal a b) (equal (/ a x) (/ b x))))) EXAMPLE 2: Pull integer summand out of floor. Note: This example has an [3mextended[0m [47m[bind-free][0m hypothesis, which uses the term [47m(find-int-in-sum sum mfc state)[0m. (defun fl (x) ;; This function is defined, and used, in the IHS books. (floor x 1)) (defun int-binding (term mfc state) ;; The call to mfc-ts returns the encoded type of term. ;; Thus, we are asking if term is known by type reasoning to ;; be an integer. (declare (xargs :stobjs (state) :mode :program)) (if (ts-subsetp (mfc-ts term mfc state) *ts-integer*) (list (cons 'int term)) nil)) (defun find-int-in-sum (sum mfc state) (declare (xargs :stobjs (state) :mode :program)) (if (and (nvariablep sum) (not (fquotep sum)) (eq (ffn-symb sum) 'binary-+)) (or (int-binding (fargn sum 1) mfc state) (find-int-in-sum (fargn sum 2) mfc state)) (int-binding sum mfc state))) ; Some additional work is required to prove the following. So for ; purposes of illustration, we wrap skip-proofs around the defthm. (skip-proofs (defthm cancel-fl-int ;; The use of case-split is probably not needed, since we should ;; know that int is an integer by the way we selected it. But this ;; is safer. (implies (and (acl2-numberp sum) (bind-free (find-int-in-sum sum mfc state) (int)) (case-split (integerp int))) (equal (fl sum) (+ int (fl (- sum int))))) :rule-classes ((:rewrite :match-free :all))) ) ; Arithmetic libraries will have this sort of lemma. (defthm hack (equal (+ (- x) x y) (fix y))) (in-theory (disable fl)) (thm (implies (and (integerp x) (acl2-numberp y)) (equal (fl (+ x y)) (+ x (fl y))))) EXAMPLE 3: Simplify terms such as (equal (+ a (* a b)) 0) (defun factors (product) ;; We return a list of all the factors of product. We do not ;; require that product actually be a product. (if (eq (fn-symb product) 'BINARY-*) (cons (fargn product 1) (factors (fargn product 2))) (list product))) (defun make-product (factors) ;; Factors is assumed to be a list of ACL2 terms. We return an ;; ACL2 term which is the product of all the elements of the ;; list factors. (cond ((atom factors) ''1) ((null (cdr factors)) (car factors)) ((null (cddr factors)) (list 'BINARY-* (car factors) (cadr factors))) (t (list 'BINARY-* (car factors) (make-product (cdr factors)))))) (defun quotient (common-factors sum) ;; Common-factors is a list of ACL2 terms. Sum is an ACL2 term each ;; of whose addends have common-factors as factors. We return ;; (/ sum (make-product common-factors)). (if (eq (fn-symb sum) 'BINARY-+) (let ((first (make-product (set-difference-equal (factors (fargn sum 1)) common-factors)))) (list 'BINARY-+ first (quotient common-factors (fargn sum 2)))) (make-product (set-difference-equal (factors sum) common-factors)))) (defun intersection-equal (x y) (cond ((endp x) nil) ((member-equal (car x) y) (cons (car x) (intersection-equal (cdr x) y))) (t (intersection-equal (cdr x) y)))) (defun common-factors (factors sum) ;; Factors is a list of the factors common to all of the addends ;; examined so far. On entry, factors is a list of the factors in ;; the first addend of the original sum, and sum is the rest of the ;; addends. We sweep through sum, trying to find a set of factors ;; common to all the addends of sum. (declare (xargs :measure (acl2-count sum))) (cond ((null factors) nil) ((eq (fn-symb sum) 'BINARY-+) (common-factors (intersection-equal factors (factors (fargn sum 1))) (fargn sum 2))) (t (intersection-equal factors (factors sum))))) (defun simplify-terms-such-as-a+ab-rel-0-fn (sum) ;; If we can find a set of factors common to all the addends of sum, ;; we return an alist binding common to the product of these common ;; factors and binding quotient to (/ sum common). (if (eq (fn-symb sum) 'BINARY-+) (let ((common-factors (common-factors (factors (fargn sum 1)) (fargn sum 2)))) (if common-factors (let ((common (make-product common-factors)) (quotient (quotient common-factors sum))) (list (cons 'common common) (cons 'quotient quotient))) nil)) nil)) (defthm simplify-terms-such-as-a+ab-=-0 (implies (and (bind-free (simplify-terms-such-as-a+ab-rel-0-fn sum) (common quotient)) (case-split (acl2-numberp common)) (case-split (acl2-numberp quotient)) (case-split (equal sum (* common quotient)))) (equal (equal sum 0) (or (equal common 0) (equal quotient 0))))) (thm (equal (equal (+ u (* u v)) 0) (or (equal u 0) (equal v -1))))") (bitp (numbers acl2-built-ins) "A recognizer for the set of bits, {0,1} [47mBitp[0m returns [47mt[0m if and only its argument is [47m0[0m or [47m1[0m, and [47mnil[0m otherwise. Note that this is a predicate form of the [type-spec] declaration [47m(TYPE BIT b)[0m. [31;1mFunction: [0m<bitp> (defun bitp (x) (declare (xargs :guard t)) (or (eql x 0) (eql x 1)))") (body (pointers) "See [system-utilities].") (book-compiled-file (books-reference) "Creating and loading of compiled and expansion files for [books] An effect of [compilation] is to speed up the execution of the functions defined in a book. Compilation can also remove tail recursion, thus avoiding stack overflows. The presence of compiled code for the functions in the book should not otherwise affect the performance of ACL2. See [guard] for a discussion; also see [compilation]. By default, the [47m[certify-book][0m command compiles the book that it certifies. see [certify-book] for how to control this behavior. By default, the [47m[include-book][0m command loads the compiled file for the book. The details of how this loading works are subtle, and do not need to be understood by most users. The ACL2 source code contains an ``Essay on Hash Table Support for Compilation'' that explains such details for those interested. All that users should generally need to know about this is that the compiled file is always the result of compiling a so-called ``expansion file'', which contains certain additional code besides the book itself. The relevance to users of the expansion file is that it can be loaded if the compiled file is missing (except when [47m:load-compiled-file t[0m is specified by the [47m[include-book][0m form), and its existence is required in order for [47m[include-book][0m to create a book's compiled file, as described below. Most users can skip the remainder of this documentation topic, which addresses the uncommon activity of using [47m[include-book][0m to compile books. [47mInclude-book[0m can be made to compile a book by supplying its keyword argument [47m:load-compiled-file[0m the value [47m:comp[0m. However, a compiled file can only be produced if there is already an [3mexpansion file[0m that is at least as recent as the book's [certificate]. Such a file, whose name happens to be the result of concatenating the string [47m"@expansion.lsp"[0m to the book's filename after removing the [47m".lisp"[0m suffix, is created by [47m[certify-book][0m when state global variable [47m'save-expansion-file[0m has a non-[47mnil[0m value. That will be the case if ACL2 started up when environment variable [47mACL2_SAVE_EXPANSION[0m was [47mt[0m (or any value that is not the empty string and whose [47m[string-upcase][0m is not [47m"NIL"[0m), until the time (if any) that [47m'save-expansion-file[0m is assigned a different value by the user. In most respects, the [47m:comp[0m setting is treated exactly the same as [47m:warn[0m; but after all events in the book are processed, the expansion file is compiled if a compiled file was not loaded, after which the resulting compiled file is loaded. One can thus, for example, compile books for several different host Lisps --- useful when installing ACL2 executables at the same site that are built on different host Lisps. A convenient way to do this in an environment that provides Gnu `make' is to certify the community books using the shell command ``[47mmake regression[0m'' in the [47macl2-sources/[0m directory, after setting environment variable [47mACL2_SAVE_EXPANSION[0m to [47mt[0m, and then moving to the [47mbooks[0m directory and executing the appropriate `make' commands to compile the books (targets [47mfasl[0m, [47mo[0m, and so on, according to the compiled file extension for the host Lisp). We conclude by saying more about the [47m:load-compiled-file[0m argument of [47m[include-book][0m. We assume that [state] global [47m'compiler-enabled[0m has a non-[47mnil[0m value; otherwise [47m:load-compiled-file[0m is always treated as [47mnil[0m. We do not consider raw mode below (see [set-raw-mode]), which presents a special case: ACL2 will attempt to load the book itself whenever it would otherwise load the expansion or compiled file, but cannot (either because the [47m:load-compiled-file[0m argument is [47mnil[0m, or for each of the expansion and compiled files, either it does not exist or it is out of date with respect to the [47m.cert[0m file). The [47m:load-compiled-file[0m argument is not recursive: calls of [47minclude-book[0m that are inside the book supplied to [47minclude-book[0m use their own [47m:load-compiled-file[0m arguments. However, those subsidiary [47minclude-book[0m calls can nevertheless be sensitive to the [47m:load-compiled-file[0m arguments of enclosing [47minclude-book[0m calls, as follows. If [47m:load-compiled-file[0m has value [47mt[0m, then every subsidiary [47minclude-book[0m is required to load a compiled file. Moreover, if a book's compiled file or expansion file is loaded in raw Lisp, then an attempt will be made to load the compiled file or expansion file for any [47m[include-book][0m form encountered during that load. If that attempt fails, then that load immediately aborts, as does its parent load, and so on up the chain. If, when going up the chain, an [47m[include-book][0m is aborted for which keyword argument [47m:load-compiled-file[0m has value [47mt[0m, then an error occurs. When loading a book's compiled file or expansion file, [47mFILE[0m, it is possible to encounter an [47m[include-book][0m form for a book that has no suitable compiled file or expansion file. In that case, the load of [47mFILE[0m is aborted at that point. Similarly, the load of [47mFILE[0m is aborted in the case that this [47minclude-book[0m form has a suitable compiled file or expansion file whose load is itself aborted. Thus, whenever any [47minclude-book[0m aborts, so do all of its parent [47minclude-book[0ms, up the chain. Such an abort causes an error when the [47minclude-book[0m form specifies a [47m:load-compiled-file[0m value of [47mt[0m.") (book-contents (books-tour) "Restrictions on the forms inside [books] Example Book: ; This book defines my app function and the theorem that it is ; associative. One irrelevant help lemma is proved first but ; it is local and so not seen by include-book. I depend on the ; inferior book "weird-list-primitives" from which I get ; definitions of hd and tl. (in-package "MY-PKG") (include-book "weird-list-primitives") (defun app (x y) (if (consp x) (cons (hd x) (app (tl x) y)) y)) (local (defthm help-lemma (implies (true-listp x) (equal (app x nil) x)))) (defthm app-is-associative (equal (app (app a b) c) (app a (app b c)))) The first form in a book must be [47m(in-package "pkg")[0m where [47m"pkg"[0m is some package name known to ACL2 whenever the book is certified. The rest of the forms in a book are embedded event forms, i.e., [47m[defun][0ms, [47m[defthm][0ms, etc., some of which may be marked [47m[local][0m. See [embedded-event-form]. The usual Common Lisp commenting conventions are provided. Note that since a book consists of embedded event forms, we can talk about the ``[47m[local][0m'' and ``non-local'' [events] of a book. Because [47m[in-package][0m is not an embedded event form, the only [47m[in-package][0m in a book is the initial one. Because [47m[defpkg][0m is not an embedded event form, a book can never contain a [47m[defpkg][0m form. Because [47m[include-book][0m is an embedded event form, [books] may contain references to other [books]. This makes [books] structured objects. When the forms in a book are read from the file, they are read with [47m[current-package][0m set to the package named in the [47m[in-package][0m form at the top of the file. The effect of this is that all symbols are [intern]ed in that package, except those whose packages are given explicitly with the ``::'' notation. For example, if a book begins with [47m(in-package "ACL2-X")[0m and then contains the form (defun fn (x) (acl2::list 'car x)) then [47m[defun][0m, [47mfn[0m, [47mx[0m, and [47m[car][0m are all [intern]ed in the [47m"ACL2-X"[0m package. I.e., it is as though the following form were read instead: (acl2-x::defun acl2-x::fn (acl2-x::x) (acl2::list 'acl2-x::car acl2-x::x)). Of course, [47macl2-x::defun[0m would be the same symbol as [47macl2::defun[0m if the [47m"ACL2-X"[0m package imported [47macl2::defun[0m. If each book has its own unique package name and all the names defined within the book are in that package, then name clashes between [books] are completely avoided. This permits the construction of useful logical [world]s by the successive inclusion of many [books]. Although it is often too much trouble to manage several packages, their judicious use is a way to minimize name clashes. Often, a better way is to use [47mlocal[0m; see [local]. How does [47m[include-book][0m know the definitions of the packages used in a book, since [47m[defpkg][0ms cannot be among the forms? More generally, how do we know that the forms in a book will be admissible in the host logical [world] of an [47m[include-book][0m? See [certificate] for answers to these questions.") (book-example (books-tour) "How to create, certify, and use a simple book Suppose you have developed a sequence of admissible [events] which you want to turn into a book. We call this ``publishing'' the book. This note explains how to do that. A key idea of [books] is that they are ``incremental'' in the sense that when you include a book in a host logical [world], the [world] is incrementally extended by the results established in that book. This is allowed only if every name defined by the incoming book is either new or is already identically defined. See [redundant-events]. This is exactly the same problem faced by a programmer who wishes to provide a utility to other people: how can he make sure he doesn't create name conflicts? The solution, in Common Lisp, is also the same: use packages. While [books] and packages have a very tenuous formal connection (every book must start with an [47m[in-package][0m), the creation of a book is intimately concerned with the package issue. Having motivated what would otherwise appear as an unnecessary fascination with packages below, we now proceed with a description of how to publish a book. Just to be concrete, let's suppose you have already gotten ACL2 to accept the following sequence of [command]s, starting in the ACL2 initial [state]. (defpkg "ACL2-MY-BOOK" (union-eq *common-lisp-symbols-from-main-lisp-package* *acl2-exports*)) (in-package "ACL2-MY-BOOK") (defun app (x y) (if (consp x) (cons (car x) (app (cdr x) y)) y)) (defun rev (x) (if (consp x) (app (rev (cdr x)) (list (car x))) nil)) (defthm rev-app-hack (equal (rev (app a (list x))) (cons x (rev a)))) (defthm rev-rev (implies (acl2::true-listp x) (equal (rev (rev x)) x))) Observe that the first form above defines a package (which imports the symbols defined in CLTL such as [47m[if][0m and [47m[cons][0m and the symbols used to [command] ACL2 such as [47m[defun][0m and [47m[defthm][0m). The second form selects that package as the current one. All subsequent forms are read into that package. The remaining forms are just event forms: [47m[defun][0ms and [47m[defthm][0ms in this case. Typically you would have created a file with Emacs containing these forms and you will have submitted each of them interactively to ACL2 to confirm that they are all admissible. That interactive verification should start in ACL2's initial [world] --- although you might, of course, start your sequence of [events] with some [47m[include-book][0ms to build a more elaborate [world]. The first step towards publishing a book containing the results above is to create a file that starts with the [47m[in-package][0m and then contains the rest of the forms. Let's call that file [47m"my-book.lisp"[0m. The name is unimportant, except it must end with [47m".lisp"[0m. If there are [events] that you do not wish to be available to the user of the book --- e.g., lemmas you proved on your way toward proving the main ones --- you may so mark them by enclosing them in [47m[local][0m forms. See [local]. Let us suppose you wish to hide [47mrev-app-hack[0m above. You may also add standard Lisp comments to the file. The final content of [47m"my-book.lisp"[0m might be: ; This book contains my app and rev functions and the theorem ; that rev is its own inverse. (in-package "ACL2-MY-BOOK") (defun app (x y) (if (consp x) (cons (car x) (app (cdr x) y)) y)) (defun rev (x) (if (consp x) (app (rev (cdr x)) (list (car x))) nil)) ; The following hack is not exported. (local (defthm rev-app-hack (equal (rev (app a (list x))) (cons x (rev a))))) (defthm rev-rev (implies (acl2::true-listp x) (equal (rev (rev x)) x))) The file shown above [31;1mis[0m the book. By the time this note is done you will have seen how to certify that the book is correct, how to compile it, and how to use it in other host [world]s. Observe that the [47m[defpkg][0m is not in the book. It cannot be: Common Lisp compilers disagree on how to treat new package definitions appearing in files to be compiled. Since a book is just a source file typed by the user, ACL2 provides a mechanism for checking that the [events] are all admissible and then marking the file as checked. This is called certification. To certify [47m"my-book.lisp"[0m you should first get into ACL2 with an initial [world]. Then, define the package needed by the book, by typing the following [47m[defpkg][0m to the ACL2 [prompt]: ACL2 !>(defpkg "ACL2-MY-BOOK" (union-eq *common-lisp-symbols-from-main-lisp-package* *acl2-exports*)) Then execute the [command]: ACL2 !>(certify-book "my-book" 1 t) ; the `t' is in fact the default Observe that you do not type the [47m".lisp"[0m part of the file name. For purposes of [books], the book's name is [47m"my-book"[0m and by the time all is said and done, there will be several extensions in addition to the [47m".lisp"[0m extension associated with it. The [47m1[0m tells [47m[certify-book][0m that you acknowledge that there is one command in this ``certification [world]'' (namely the [47m[defpkg][0m). To use the book, any prospective host [world] must be extended by the addition of whatever [command]s occurred before certification. It would be a pity to certify a book in a [world] containing junk because that junk will become the ``[portcullis]'' guarding entrance to the book. The [47mt[0m above tells [47m[certify-book][0m that you wish to compile [47m"my-book.lisp"[0m also (but see [compilation] for an exception). [47m[Certify-book][0m makes many checks but by far the most important and time-consuming one is that it ``proves'' every event in the file. When [47m[certify-book][0m is done it will have created two new files. The first will be called [47m"my-book.cert"[0m and contains the ``[certificate]'' attesting to the admissibility of the [events] in [47m"my-book.lisp"[0m. The [certificate] contains the [47m[defpkg][0m and any other forms necessary to construct the certification [world]. It also contains so-called [book-hash] values that are used to help you keep track of which version of [47m"my-book.lisp"[0m was certified. The second file that may be created by [47m[certify-book][0m is the compiled version of [47m"my-book.lisp"[0m and will have a name that is assigned by the host compiler (e.g., [47m"my-book.o"[0m in GCL, [47m"my-book.fasl"[0m in SBCL). [47m[Certify-book][0m will also load this object file. When [47m[certify-book][0m is done, you may throw away the logical [world] it created, for example by executing the [command] [47m:u[0m. To use the book later in any ACL2 session, just execute the event [47m(include-book "my-book")[0m. This will do the necessary [47m[defpkg][0m, load the non-[47m[local][0m [events] in [47m"my-book.lisp"[0m and then may load the compiled code for the non-local functions defined in that file. Checks are made to ensure that the [certificate] file exists and describes the version of [47m"my-book.lisp"[0m that is read. The compiled code is loaded if and only if it exists and has a later write date than the source file (but see [compilation] for an exception). Since [47m[include-book][0m is itself an event, you may put such forms into other [books]. Thus it is possible for the inclusion of a single book to lead to the inclusion of many others. The [book-hash] information maintained in [certificate]s helps deal with the version control problem of the referenced [books]. I.e., if this version of [47m"my-book"[0m is used during the certification of [47m"your-book"[0m, then the [certificate] for [47m"your-book"[0m includes the book-hash for this version of [47m"my-book"[0m. If a later [47m(include-book "your-book")[0m finds a version of [47m"my-book"[0m with a different book-hash, an error is signaled. But book-hash values are not perfect and the insecurity of the host file system prevents ACL2 from guaranteeing the logical soundness of an [47m[include-book][0m event, even for a book that appears to have a valid [certificate] (they can be forged, after all). (See [certificate] for further discussion.) This concludes the example of how to create, certify and use a book. If you wish, you could now review the [documentation] for book-related topics (see [books]) and browse through them. They'll probably make sense in this context. Alternatively, you could continue the ``guided tour'' through the rest of the [documentation] of [books]. See [book-name], following the pointer given at the conclusion.") (book-hash (books) "Assigning ``often unique'' fingerprints to [books] ACL2 provides a [3mcertification[0m process for recording into a [certificate] file that a book is valid. That process records certain ``fingerprint'' values for the book and the books that it includes, in order to give some confidence in the book's validity. We call that value the ``book-hash'' for the book. By default, a book-hash is an alist that records, for a given book ([47m.lisp[0m file), its file size (in bytes) and its write-date. You can arrange for a book-hash to be a checksum instead of an alist, which gives a bit greater security, as illustrated in an example provided below. See [checksum]. Nevertheless, the (default) use of book-hash alists may be worthwhile, in spite of the decreased security, because of faster times for [47m[certify-book][0m and [47m[include-book][0m when using book-hash alists instead of checksums. If you want to use checksums, however, there are these two ways to do so. * Before starting ACL2, set environment variable [47mACL2_BOOK_HASH_ALISTP[0m to [47mNIL[0m (or [47mnil[0m; actually it suffices that [47m[string-upcase][0m applied to the indicated string is [47m"NIL"[0m). A common way to get this effect is to supply the argument [47mACL2_BOOK_HASH_ALISTP=NIL[0m with your [47m"make"[0m command. * After starting ACL2, set [state] global variable [47mbook-hash-alistp[0m to [47mnil[0m, e.g.: [47m(assign book-hash-alistp nil)[0m. (Set this variable to [47mt[0m to revert to the default behavior: [47m(assign book-hash-alistp t)[0m.) The simple example below illustrates the potential weakness of book-hash alists (as compared to checksums), by exploiting the fact that these alists do not hash information in the [certificate] itself. (Book-hash alists also ignore [portcullis] [command]s and the corresponding [47m.acl2x[0m file, if any (see [set-write-ACL2x]); but we don't exploit these facts in this example.) We start with the following book, [47m"foo.lisp"[0m. (in-package "ACL2") (make-event '(defun foo (x) (cons x x))) Now start ACL2 and run these commands. (assign book-hash-alistp t) ; a no-op, by default (certify-book "foo") (read-file "foo.cert" state) (quit) Next, replace the contents of [47m"foo.cert"[0m by the values in the list printed by the [47mread-file[0m form above (hence, without the outer parentheses). Further edit that file by twice changing [47m(cons x x)[0m to [47mx[0m. Also, update the write-date on the compiled file, e.g. with [47mtouch foo.dx64fsl[0m, if you want to avoid a warning. Then submit [47m(include-book "foo")[0m. We get the following contradictory behavior, without any warnings. ACL2 !>(foo 3) (3 . 3) ACL2 !>(thm (equal (foo x) x)) Q.E.D. Summary Form: ( THM ...) Rules: ((:DEFINITION FOO)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Prover steps counted: 5 Proof succeeded. ACL2 !> For more information about connections between book-hash values and certification status, see [book-hash-mismatch]. Subtopics [Book-hash-mismatch] Deeming a book uncertified because of a [book-hash] mismatch") (book-hash-mismatch (book-hash) "Deeming a book uncertified because of a [book-hash] mismatch When [47m[include-book][0m is invoked, the specified book may be considered uncertified by ACL2 because its [book-hash] --- which by default is an alist specifying the book's size and write-date, but could be a checksum --- does not match what was expected. In that case you will typically see a warning such as the following, which instead will be an error if this occurs during certification. In this topic, we explain how this warning can occur. ACL2 Warning [Uncertified] in ( INCLUDE-BOOK "foo" ...): The certificate for "/Users/kaufmann/temp/foo.lisp" lists the book- hash of that book as ((:BOOK-LENGTH . 38) (:BOOK-WRITE-DATE . 3674050905)). But its book-hash is now computed to be ((:BOOK-LENGTH . 39) (:BOOK-WRITE-DATE . 3674050914)). See :DOC book-hash-mismatch. Probably the simplest way for such a mismatch to occur is if you change the book after certifying it, and then try to include the book. In the example message displayed above, the book-hash for [47mfoo.lisp[0m stored into [47mfoo.cert[0m was 516310554. But then [47mfoo.lisp[0m was edited (in this case, by adding a single newline character), and ACL2 complained because at [47minclude-book[0m time it computed a different book-hash for that book. The mismatch might occur on a book that is being included while including a superior book. For example, suppose that the act of evaluating [47m(include-book "bk1")[0m triggers evaluation of the event [47m(include-book "bk2")[0m from [47mbk1.lisp[0m, which similarly in turn causes evaluation of the event [47m(include-book "bk3")[0m from [47mbk2.lisp[0m. Now certify [47mbk3.lisp[0m, then [47mbk2.lisp[0m, and finally [47mbk1.lisp[0m. So far, so good. But now suppose we edit the lowest-level book, [47mbk3.lisp[0m. We will likely get a warning (or error, if during book certification) such as the one displayed above when evaluating [47m(include-book "bk1")[0m, complaining that the book-hash for [47mbk3.lisp[0m has changed --- followed by warnings complaining about inclusions of uncertified books by superior books. There are several ways for a book-hash in a [47m.cert[0m file to become invalid, that is, to fail to match a recomputation of the book-hash when later including the book. All such mismatches are due to a difference between the value of a book-hash at certification time and at later [47minclude-book[0m time; see [book-hash]. Note that it is possible to mix alist and checksum book-hash values. The key is to avoid conflicts between book-hash values stored for the same book in different [47m.cert[0m files. The following example works fine, because there is no such conflict: the book [47m"sub"[0m is associated with a book-hash checksum in [47msub.cert[0m, which provides that same checksum as the book-hash value for [47m"sub"[0m in [47mtop.cert[0m; and the book [47m"top"[0m is associated with a book-hash alist in [47mtop.cert[0m. (certify-book "sub") (u) (assign book-hash-alistp t) (certify-book "top") ; contains the event (include-book "sub") (u) (include-book "top") ; no problem! However, if we instead evaluate the following forms in a fresh ACL2 session, the last one causes an error, because a checksum serves as the book-hash for [47m"sub"[0m in [47mtop.cert[0m, but at [47minclude-book[0m time the book-hash for [47m"sub"[0m in [47msub.cert[0m is an alist, not a checksum. (certify-book "sub") :u (certify-book "top") ; contains the event (include-book "sub") :u (assign book-hash-alistp t) (certify-book "sub") ; now the book-hash for sub is an alist :u ; Error: mismatch for book-hash values for "sub" in ; new sub.cert and earlier top.cert. (include-book "top") That said, ACL2 does not care about the current value of state global [47mbook-hash-alistp[0m at [47minclude-book[0m time. For example, the following works without error: ACL2 sees the checksum stored in [47msub.cert[0m, so at [47minclude-book[0m time it computes a checksum for the book [47m"sub"[0m, not an alist, even though [47m'book-hash-alistp[0m has value [47mt[0m. (assign book-hash-alistp nil) (certify-book "foo") (assign book-hash-alistp t) (include-book "foo") We conclude by discussing a rather insidious book-hash mismatch that can occur when including a book using an ACL2 executable that differs from the executable that was used when certifying the book. Here is an example. Consider a book, [47m"foo.lisp"[0m, containing the event [47m(include-book "tools/remove-hyps" :dir :system)[0m. Suppose we have ACL2 executables [47macl2-cksum[0m and [47macl2-alist[0m, in different ACL2 directories. Also suppose that we have certified (disjoint copies of) the [community-books] with each of these ACL2 executables, where we used [47mACL2_BOOK_HASH_ALISTP=NIL[0m in our [47m"make"[0m command with [47macl2-cksum[0m but not with [47macl2-alist[0m. Now suppose we certify [47m"foo.lisp"[0m using [47macl2-cksum[0m but then, in a session with [47macl2-alist[0m, we include that same book. Then we will see a warning beginning as displayed below. It complains that the book-hash required of [47mbooks/tools/remove-hyps.cert[0m according to [47mfoo.cert[0m --- which was created using [47macl2-cksum[0m --- differs from the book-hash in the [47m.cert[0m file of the copy of that book that is under the directory of the currently running ACL2, [47macl2-alist[0m. ACL2 Warning [Uncertified] in ( INCLUDE-BOOK "foo" ...): After including the book "/Users/smith/temp/foo.lisp": -- its certificate requires the book "/Users/smith/acl2/books/tools/remove- hyps.lisp" with certificate annotations ((:SKIPPED-PROOFSP) (:AXIOMSP) (:TTAGS)) and book hash 1958615726, but we have included a version of "remove-hyps" with certificate annotations ((:SKIPPED-PROOFSP) (:AXIOMSP) (:TTAGS)) and book-hash ((:BOOK-LENGTH . 14650) (:BOOK-WRITE-DATE . 3656629263)), so book recertification is probably required;") (book-makefiles (pointers) "See [books-certification].") (book-name (books-tour) "Conventions associated with book-names Examples: "list-processing" "/usr/home/smith/my-arith" A [3mbook-name[0m is typically a string constant that represents a file. (Much later below we discuss other book-names that are not strings, namely, [sysfile]s; but till then we consider only strings.) We elaborate book names by concatenating the ``connected book directory'' (see [cbd]) string on the left and perhaps a [47m".lisp"[0m ``extension'' on the right. However, the connected book directory is not added if the book-name itself already represents an absolute file name. Furthermore, [47m[include-book][0m and [47m[certify-book][0m temporarily reset the connected book directory to be the directory of the book being processed. This allows [47m[include-book][0m forms to use relative pathnames without explicit mention of the enclosing book's directory. You may wish to read elsewhere for details of ACL2 file name conventions (see [pathname]), for a discussion of the filename that is the result of the elaboration described here (see [full-book-name]), and for details of the concept of the connected book directory (see [cbd]). For details of how [47m[include-book][0m (see [include-book]) and [47m[certify-book][0m (see [certify-book]) use these concepts, see below. Often a book-name is simply the familiar name of the file. (See [full-book-name] for discussion of the notions of ``directory string,'' ``familiar name,'' and ``extension''. These concepts are not on the guided tour through [books] and you should read them separately.) However, it is permitted for a book-name to include a directory or part of a directory name. Book-names often do not include the extension, since ACL2 must routinely tack several different extensions onto the name during [47m[include-book][0m. For example, [47m[include-book][0m uses the [47m".lisp"[0m, [47m".cert"[0m and possibly a compiled file extension (like [47m".fasl"[0m) of the book-name. A book-name is elaborated into a [full-book-name] by [47m[include-book][0m and [47m[certify-book][0m. This elaboration is sensitive to the ``connected book directory.'' The connected book directory is an absolute filename string (see [pathname]) that is part of the ACL2 [47m[state][0m. (You may wish to see [cbd] and to see [set-cbd] --- note that these are not on the guided tour). If a book-name is an absolute filename string, ACL2 elaborates it simply by appending the desired extension to the right. If a book-name is a relative filename string, ACL2 appends the connected book directory on the left and the desired extension on the right. Note that it is possible that the book-name includes some partial specification of the directory. For example, if the connected book directory is [47m"/usr/home/smith/"[0m then the book-name [47m"project/task-1/arith"[0m is a book-name that will be elaborated to "/usr/home/smith/project/task-1/arith.lisp". Observe that while the [events] in this [47m"arith"[0m book are being processed the connected book directory will temporarily be set to "/usr/home/smith/project/task-1/". Thus, if the book requires other [books], e.g., (include-book "naturals") then it is not necessary to specify the directory on which they reside provided that directory is the same as the superior book. This inheritance of the connected book directory and its use to elaborate the names of inferior [books] makes it possible to move [books] and their inferiors to new directories, provided they maintain the same relative relationship. It is even possible to move with ease whole collections of [books] to different filesystems that use a different operating system than the one under which the original certification was performed. The [47m".cert"[0m extension of a book, if it exists, is presumed to contain the most recent [certificate] for the book. See [certificate] (or, if you are on the guided tour, wait until the tour gets there). Finally we mention another kind of book-name: a [sysfile], which is a pair that associates a keyword with a relative pathname. This kind of book-name is used by the implementation, for example in [certificate] files, but is rarely visible to users. If you run across a sysfile and want to understand more about it, see [sysfile]. See [book-contents] to continue the guided tour.") (bookdata (books) "Write small files with meta-data about certified [books] ACL2 provides a primitive capability for writing out a file of metadata associated with a book. This information might be useful, for example, in building a database that allows you to search for name conflicts. See [community-books] directory [47mbooks/tools/book-conflicts/[0m for an application of this capability by Dave Greve. If you use this capability and have ideas for enhancing it, please feel free to send them to the ACL2 developers. If the book has the name [47mBK[0m, then the output file is named [47mBK__bookdata.out[0m. That file is generated in the same directory as [47mBK[0m, by certifying [47mBK[0m when [state] global [47m'write-bookdata[0m has a non-[47mnil[0m value, for example as follows. (assign write-bookdata t) (certify-book "BK" ...) Alternatively, one may set environment variable [47mACL2_WRITE_BOOKDATA[0m to any non-empty value to cause [47mBK__bookdata.out[0m to be written, with one exception, namely: when the value of state global [47mwrite-bookdata[0m is [47m:never[0m. The resulting file will contain a single form of the following shape, although not necessarily in the following order, according to the description that follows below. ("...BK.lisp" :PKGS pkgs-val :BOOKS book-val :PORT-BOOKS port-book-val :CONSTS consts-val :PORT-CONSTS port-consts-val :FNS fns-val :PORT-FNS port-fns-val :LABELS labels-val :PORT-LABELS port-labels-val :MACROS macros-val :PORT-MACROS port-macros-val :STOBJS stobjs-val :PORT-STOBJS port-stobjs-val :THEORIES theories-val :PORT-THEORIES port-theories-val :THMS thms-val :PORT-THMS port-thms-val ) The first entry in the form will always be the [full-book-name] of the certified book, [47mBK[0m, possibly in [sysfile] format. Subsequent values in the form are based on [events] introduced by including [47mBK[0m. For various values of [47mxxx[0m as described below, [47mport-[0m[3mxxx[0m[47m-val[0m is a list of values corresponding to [events] introduced in the certification [world] for [47mBK[0m (see [portcullis]), and [3mxxx[0m[47m-val[0m is a list of values corresponding to [events] introduced non-[47m[local][0mly by [47mBK[0m. These lists include only ``top-level'' events, not those that are introduced by a book included either in [47mBK[0m or its certification world. [47mPkgs-val[0m is a list of names of packages introduced in the certification world (at the top level, not in an included book). Note that no packages are introduced in a book itself, so no distinction is made between [47mpkgs-val[0m and [47mport-pkgs-val[0m. Both [47mport-book-val[0m and [47mbook-val[0m are lists of [full-book-name]s of included books. The values associated with the other keywords are, themselves, association lists (see [alistp]) such that each key is a package name, which is associated with a list of [symbol-name]s for symbols in that package that are introduced for that keyword. For example, [47mfns-val[0m may be the alist (("ACL2" "F1" "F2") ("MY-PKG" "G1" "G2")) if the function symbols introduced in the book are [47mF1[0m and [47mF2[0m in the [47m"ACL2"[0m package, as well as [47mG1[0m and [47mG2[0m in the [47m"MY-PKG"[0m package. We next explain what kinds of symbols are introduced for each keyword [47m:xxx[0m. Each such symbol would be associated with either the keyword [47m:port-xxx[0m or the keyword [47m:xxx[0m depending respectively on whether the symbol is introduced at the top level of the certification world for [47mBK[0m or [47mBK[0m itself. [47m:CONSTS[0m constant symbol introduced by [47mdefconst[0m [47m:FNS[0m function symbol: introduced by [47mdefun[0m, [47mdefuns[0m, or [47mdefchoose[0m; or constrained (by an [47m[encapsulate][0m event) [47m:LABELS[0m symbol introduced by [47mdeflabel[0m [47m:MACROS[0m macro name introduced by [47mdefmacro[0m [47m:STOBJS[0m [47mstobj[0m name introduced by [47mdefstobj[0m or [47mdefabsstobj[0m [47m:THEORIES[0m theory name introduced by [47mdeftheory[0m [47m:THMS[0m theorem name, which may be introduced by [47mdefthm[0m or a macro call expanding to a call of [47mdefthm[0m, such as see [defequiv] or [47mdefaxiom[0m; but may be introduced by [47m[defpkg][0m, for example, with name [47m"MYPKG-PACKAGE"[0m if the package name is [47m"MYPKG"[0m Our hope is that people in the ACL2 community will generate and use this data to improve the ACL2 [community-books]. Here is an example illustrating how to generate bookdata files for those books as a byproduct of a regression run. Below, we write [47m{DIR}[0m as an abbreviation for the ACL2 sources directory, and assume that this command is run from that directory. Of course, you may wish to use [47mmake[0m options like [47m-j 8[0m and [47mmake[0m variable settings like [47mACL2={DIR}/my-saved_acl2[0m; see [books-certification] for details. make regression-fresh \ ACL2_CUSTOMIZATION={DIR}/acl2-customization-files/bookdata.lisp") (books (top) "[3mBooks[0m are files of ACL2 [events]---they are the main way to split up large ACL2 developments into separate modules. This [documentation] topic is about ACL2 {source code | https://en.wikipedia.org/wiki/Source_code} files. However, there are also books published about ACL2 and its applications; see pubs::pubs-books. You will almost surely want to organize your own ACL2 work into books. They facilitate reuse, allow you to reload proofs more quickly, allow you to rebuild parts of your proof in parallel, and so forth. You will also want to be aware of the many [3mcommunity books[0m, which provide useful tools and lemmas to build upon. See [community-books] for more information, including how to contribute. Introduction A [31;1mbook[0m is a file of ACL2 forms. Books are prepared entirely by the user of the system, i.e., they are [3msource files[0m not [3mobject files[0m. Some of the forms in a book are marked [47m[local][0m and the others are considered ``non-local.'' [47m[Include-book][0m lets you load a book into any ACL2 [world]. A successful [47minclude-book[0m extends the logic of the host [world] by adding just the non-local [events] in the book. Ordinarily, you might include a variety of books to load all of their definitions and rules. Successful book inclusion is consistency preserving, provided that the book itself is consistent, as discussed later. However, [47m[include-book][0m assumes the [events] in a book are valid, so if you include a book that contains an inconsistency (e.g., an inadmissible definition) then the resulting theory is inconsistent! [47m[Certify-book][0m lets you [3mcertify[0m a book to guarantee that its successful inclusion is consistency preserving. During certification, both the [47m[local][0m and non-local forms are processed. This lets you mark as [47m[local][0m any [events] you need for certification, but that you want to hide from users of the book---e.g., the hacks, crocks, and kludges on the way to a good set of [rewrite] rules. Certification can also compile (see [COMPILATION]) a book to speed up the execution of the functions defined within it. The desire to compile books is largely responsible for the restrictions we put on the forms allowed in books. Extensive [documentation] is available on the various aspects of books. We recommend that you read it all before using books. It has been written so as to make sense when read in a certain linear sequence, called the ``guided tour'', though in general you may browse through it randomly. If you are on the guided tour, you should next read [book-example]. Subtopics [Book-hash] Assigning ``often unique'' fingerprints to [books] [Bookdata] Write small files with meta-data about certified [books] [Books-reference] Reference guide for ACL2 functionality related to books, e.g., [include-book], [certify-book], [cbd], etc. [Books-tour] The [3mguided tour[0m of concepts related to ACL2 [books]. [Community-books] Libraries of ACL2 [books] developed by the ACL2 community. [Project-dir-alist] Support for moving project directories (also [47m:dir[0m arguments) [Sysfile] File representation using ACL2 project directories [Uncertified-books] Invalid [certificate]s and uncertified [books]") (books-certification (community-books) "Instructions for certifying the ACL2 [community-books]. The Community Books (see [COMMUNITY-BOOKS]) provides a [47mmake[0m system, which is recommended for certifying a specified subset of those books from the [47mbooks/[0m directory of your ACL2 distribution. Alternate instructions are however available for certifying from the top-level directory (see [books-certification-alt]). Below are instructions for certifying various sets of books. They all have the following form in common. Note: If there is a suitable [47m"acl2"[0m executable on your Unix [47mPATH[0m --- for example, if the [47mbin[0m subdirectory of the main ACL2 directory is on your [47mPATH[0m, so that [47mbin/acl2[0m may be your executable --- then you can omit [47m"ACL2=..."[0m below. cd /path/to/acl2-sources/books make ACL2=/path/to/acl2-sources/saved_acl2 ... For example, the section ``A Full Build'', below, says to do the following if you would like to make a change to the [community-books] (where the [47m-j[0m argument is optional). $ cd /path/to/acl2-sources/books $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 all Success is indicated by a Linux exit status of 0. Equivalently, there should be no failures in the log. Failures may be found by searching for [47m**[0m; for example, if output is redirected to a log file [47mmake-regression.log[0m, then the following should provide no output. fgrep -a '**' make-regression.log Unusual books that create output in the log file should not produce the string [47m**[0m except upon failure. By default, [47mmake[0m commands for certifying books take advantage of files [47m*@useless-runes.lsp[0m. See [useless-runes]. Prerequisites We assume that you have already installed ACL2 as per the [installation-instructions]. In particular, the [community-books] should be present as the [47mbooks/[0m subdirectory of your ACL2 distribution. We assume you know the path to your ACL2 executable. Typically this is a script named [47msaved_acl2[0m in your [47macl2-sources[0m directory. The instructions below are suitable for ACL2 and all of its experimental extensions, e.g., ACL2(p) and ACL2(r). It may be preferable to avoid being logged in as root, since developers do not test as root and at least one community book ([47mbooks/oslib/tests/copy.lisp[0m) has failed to certify when logged in as root. A Basic Build The default [47mmake[0m target in [47mbooks/GNUmakefile[0m, called [47mbasic[0m, is quite fast --- it excludes many books and certifies only the directories listed below, which tend to be widely used. [31;1mWARNING[0m: This basic build is insufficient for validating changes that will go into the [community-books]; for that, see [how-to-contribute]. * arithmetic * arithmetic-3 * arithmetic-5 * [ihs] * misc * tools (mostly) * [std] (mostly) * [xdoc] (in part) * data-structures * apply To certify these books, you should be able to run [47mmake[0m as follows. The [47m-j 2[0m part of this command is suitable for a computer with two cores. If you have, e.g., a quad-core computer, you should probably use [47m-j 4[0m instead, and so on. $ cd /path/to/acl2-sources/books $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 basic If you configure your [47mPATH[0m so that you can launch ACL2 by typing [47macl2[0m, then you may omit the [47mACL2=...[0m part. Certifying Additional Books We expect that most ACL2 users will want to certify at least the [47mbasic[0m books described above. But what if you also need other books? One option is to do a full build (see below). But it is usually [31;1mmuch faster[0m to simply tell [47mmake[0m to build the books you actually want to use. There are [47mmake[0m targets corresponding to most directory names. For instance, to build the books under [47mcoi[0m and [47mrtl[0m and [47mcgen[0m, you can run: $ cd /path/to/acl2-sources/books $ make ACL2=/path/to/acl2-sources/saved_acl2 coi rtl cgen -j 2 For finer grained control, you can name individual books. This works particularly well for libraries that have [47mtop[0m books. For instance, if you want the [47mrtl/rel9[0m library, you could run: $ cd /path/to/acl2-sources/books $ make ACL2=/path/to/acl2-sources/saved_acl2 rtl/rel9/lib/top.cert -j 2 Books that Require ACL2 Extensions Some books require experimental extensions to ACL2, such as ACL2(p) (see [parallelism]) or ACL2(r) (see [real]). Other books require certain additional software. The build system will automatically determine which kind of ACL2 you are running (ACL2, ACL2(p), or ACL2(r)) and, based on this, may prevent incompatible books from being certified. The output of [47mmake[0m should explain which books are being excluded and why. These kinds of book requirements are controlled by special [build::cert_param] comments. Books that Require Quicklisp Some books, especially [interfacing-tools] like [oslib] and the ACL2 [bridge], require certain Common Lisp libraries. These libraries are now bundled with ACL2 via [quicklisp], so you should not need to download anything extra to use them. They are enabled by default for all host Lisps except GCL, but you can avoid books that depend on Quicklisp libraries by setting [47mUSE_QUICKLISP=0[0m in your [47mmake[0m command. Using Quicklisp should definitely work if the host Lisp is CCL or SBCL. (Note however that certification of [books] that use Quicklisp may require [47mopenssl[0m to be installed if it is not already on your system.) There is some chance it will work with Allegro CL, LispWorks, and CMUCL. It will almost certainly [31;1mnot[0m work for GCL (at least as of 2018). Books that Require Additional Software Some other books based on [satlink] and [gl] require a SAT solver, typically Glucose, to be installed; see [satlink::sat-solver-options] for installation options. The build system should automatically determine if Glucose is installed on your system, and will avoid trying to certify these books unless Glucose is present. Building the manual If you just want to get a copy of the ACL2+Books manual for local viewing, you probably [31;1mdon't need to build it yourself[0m because you can just {download | download/} a copy. If for some reason you do want to build the manual yourself, you should be able to do so as follows. $ cd /path/to/acl2-sources/books $ make manual -j 4 Building the manual should work on at least CCL and SBCL on Linux and Mac OS X. It [31;1mmay not work[0m for some other OS/Lisp combinations. In particular, building the manual requires some features from [oslib] and [quicklisp] that may not be available on some other Lisps. The resulting web-based manual may be found in: acl2-sources/books/doc/manual/index.html See also [ACL2-doc] for details about how to build your own Emacs-based manual, and [xdoc::save] for general information about how to build and distribute custom XDOC manuals, e.g., manuals that additionally include your own unreleased books. A Full Build Building all of the books can take hours and is [31;1musually unnecessary[0m. That said, it is easy to do: just run [47mmake all[0m, for example as follows. (But as noted above, you may omit [47m"ACL2=..."[0m if a suitable executable named [47macl2[0m is on your Unix [47mPATH[0m, such as [47mbin/acl2[0m.) $ cd /path/to/acl2-sources/books $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 all This includes a few books that are quite slow to certify. You can exclude those by replacing ``[47mall[0m'' by ``[47mregression[0m'' in the command above. Cleaning Up If you want to delete generated files, you can run [47mmake clean[0m to remove certificates, compiled files, and build logs. If you just want to remove the files in a particular subdirectory (and its subdirectories), you can go into that directory and then run the [47mbuild/clean.pl[0m script. This will delete, starting from your current directory, recursively, all certificates, logs, compiled files, etc. Note that [47mmake clean[0m doesn't remove some files, e.g., [xdoc] manuals. To remove everything, try [47mmake moreclean[0m. Debugging Failed Certifications If a book fails to certify, you may want to try certifying it in an interactive session. The most reliable way to do this is to replicate the environment and commands that the build system used. This information can be found at the top of the [47m[bookname].cert.out[0m file. For instance: ;; foo.cert.out -*- Mode: auto-revert -*- ... Environment variables: ACL2_CUSTOMIZATION=NONE ;; <-- first configure your ACL2_SYSTEM_BOOKS=/path/to/acl2/books ;; environment to match ACL2=/path/to/saved_acl2 ;; these settings ... Temp lisp file: (acl2::value :q) ;; <--- then submit these commands to (acl2::in-package "ACL2") ;; $ACL2 to debug the failure ... ;; interactively --- End temp lisp file --- Some other notes/tips: * Make sure the ACL2 image you run is the same as the one listed as ACL2 in those environment variables! * You may wish to set the environment variables for only the duration of your ACL2 session by using the "env" command. * You may wish to edit some of the commands for better debugging purposes; e.g. you may modify the [set-inhibit-output-lst] command, or insert a [set-debugger-enable] command, etc. * If you don't want your session to exit after a successful certification, replace the last form [47m(er-progn (time$ (certify-book ...[0m with just the [47m(time$ (certify-book ...))[0m part. Further Resources The build system is largely based on [build::cert.pl]. There is considerable documentation about [47mcert.pl[0m, and we highly recommend using it to manage your own ACL2 projects. The main build script is [47mbooks/GNUmakefile[0m. There are many comments at the start of this file, and you can also inspect it to see what targets are available. Please feel absolutely free to contact the [ACL2-help] mailing list with any questions about building the community books. Subtopics [Books-certification-alt] Alternate instructions for certifying the [community-books], from the perspective of the [47macl2-sources[0m directory. [Books-certification-classic] Classic ACL2 `make'-based certification of [books] [Provisional-certification] Certify a book in stages for improved book-level parallelism") (books-certification-alt (books-certification) "Alternate instructions for certifying the [community-books], from the perspective of the [47macl2-sources[0m directory. WARNING: Parts of this documentation are probably obsolete, but parts are still relevant. See [books-certification] as the primary source of information on how to certify the [community-books]. For background on the ACL2 community books, see [community-books]. Here we explain how to certify those books, or some of those books, with ACL2. We thank Bishop Brock, Jared Davis, and Sol Swords for their substantial contributions to this methodology. See [47mbooks/GNUmakefile[0m, in the community books, for more about ``Credits and History'', and for additional technical details not covered in this topic. For more information about installing ACL2, see [installation]. For information about so-called ``classic ACL2 `make'-based certification'', which provides support for certifying directories of books but may disappear in a future ACL2 release, see [books-certification-classic]. [31;1mThe Basics[0m We make the following assumptions. * Gnu `make' is available on your system via the `make' command (rather than some other flavor of `make'). (Execute `[47mmake --version[0m to verify this.) * You have built or obtained an ACL2 executable. * The ACL2 [community-books] are installed in the [47mbooks/[0m subdirectory of your ACL2 distribution, as is the case when you have followed the standard [installation] instructions. Note: All commands shown below are issued in the top-level (ACL2 sources) directory of your ACL2 distribution. By default the ACL2 executable is file [47msaved_acl2[0m in your ACL2 sources directory, and you can issue the following command to the shell in order to do a ``regression run'' that certifies all of the community books using that executable. make regression Better yet, save a log file in case there are problems, for example as follows. (make regression) >& make-regression.log or perhaps better yet: (time nice make regression) >& make-regression.log For the sake of brevity, below we'll skip mentioning any of `[47mtime[0m', `[47mnice[0m', or `[47m>& make-regression.log[0m'. But saving a log file, in particular, is useful in case you encounter problems to report. If you fetched the community books using git, then you will have a directory such [47mbooks/workshops/[0m that is not necessary for certifying the most widely-included books. You can certify just such books as follows. (time nice make basic) >& make-basic.log Whether you use target `[47mregression[0m' or target `[47mbasic[0m', then for each book [47mfoo.lisp[0m whose certification is attempted, a file [47mfoo.cert.out[0m in the same directory will contain the output from the book's certification attempt. A regression run may take a few hours, but if you have a multiprocessing computer, you can speed it up by certifying some books in parallel, by providing a value for `make' option [47m-j[0m. For example, if you have 8 hardware threads then you might want to issue the following command. make regression -j 8 [31;1mSpecifying the ACL2 Executable[0m If your ACL2 executable is not file [47msaved_acl2[0m in the ACL2 sources directory, then you will need to specify that executable. You can do that by setting variable [47mACL2[0m, either as an environment variable or, as displayed below, as a `make' variable. Either way, you will need to avoid relative pathnames. For example, the first two forms below are legal, but the third is not, assuming that [47mmy-acl2[0m is on your [47mPATH[0m in a Unix-like environment (e.g., linux or MacOS) and that [47mmy-saved_acl2[0m is just a pathname relative to your ACL2 sources directory, which is not on your path. make regression -j 8 ACL2=my-acl2 make regression -j 8 ACL2=/u/smith/bin/acl2 # The following only works if my-saved_acl2 is on your path (see above). make regression -j 8 ACL2=my-saved_acl2 [31;1mCleaning[0m You can delete files generated by book certification (including [47m.cert[0m files, [47m.out[0m files, compiled files, and more) by issuing the following command (again, in your ACL2 sources directory). make clean-books Alternatively, if you want to cause such deletion and then do a regression, simply replace the `[47mregression[0m' target by `[47mregression-fresh[0m. If however you only want to clean up generated files residing under a given directory (or its subdirectories, and recursively), you can issue the following command while standing in that directory, where [47mDIR[0m is a pathname of your [47mbooks[0m directory. DIR/clean.pl For example, to clean up generated files under [47mbooks/arithmetic[0m, you could do the following. cd books/arithmetic ../clean.pl cd - # to return to the ACL2 sources directory, if you wish to do so [31;1mRestricting to Specific Directories and Books[0m You can specify which books you want certified by using any or all of the variables [47mEXCLUDED_PREFIXES[0m, [47mACL2_BOOK_CERTS[0m, or [47mACL2_BOOK_DIRS[0m. First, the set of desired [47m.cert[0m files is restricted to those that do not start with any string that is one of the words in the value of [47mEXCLUDED_PREFIXES[0m. Then [47mACL2_BOOK_CERTS[0m and [47mACL2_BOOK_DIRS[0m, if supplied, specify which books should be certified, as illustrated by the following example. make -j 8 regression-fresh \ ACL2_BOOK_DIRS="symbolic paco" \ ACL2_BOOK_CERTS=" \ workshops/2006/cowles-gamboa-euclid/Euclid/ed6a.cert \ workshops/2006/cowles-gamboa-euclid/Euclid/ed4bb.cert \ " Then all book in directories [47msymbolic[0m and [47mpaco[0m will be certified, as will the books [47mworkshops/2006/cowles-gamboa-euclid/Euclid/ed6a.lisp[0m and [47mworkshops/2006/cowles-gamboa-euclid/Euclid/ed4bb.lisp[0m. Note that all pathnames should be relative to your community books directory; in particular, they should not be absolute pathnames. Also notice the [47m.cert[0m extension used in files supplied for [47mACL2_BOOK_CERTS[0m. Alternatively, you may wish to invoke [47mbooks/cert.pl[0m while standing in a directory under which you want to certify books. This will certify not only those books, but all supporting books --- even those not under the current directory --- that do not have up-to-date [47m.cert[0m files. The following is a simple command to invoke that will certify all books in the current directory, where if the [47mbooks/[0m directory is not on your path, you will need to provide a suitable filename, e.g. [47m../../cert.pl[0m or [47m~/acl2/books/cert.pl[0m. cert.pl -j 4 *.lisp Here is a more complex command, which illustrates a way to certify books in subdirectories (as well as the current directory), the use of provisional certification (see [provisional-certification]), and `make'-level parallelism (in this case specifying four parallel processes). cert.pl --pcert-all -j 4 `find . -name '*.lisp'` Note that with this approach, unlike classic ACL2 `make'-based certification (see [books-certification-classic], out-of-date [47m.cert[0m files that are not under the current directory will also be built. For documentation of [47mcert.pl[0m invoke: cert.pl -h See the top of [47mcert.pl[0m for authorship and copyright information. Finally, we give a brief summary of how to use so-called ``classic ACL2 `make'-based certification'' for community books; see [books-certification-classic] for details. Note that support for this approach might be eliminated in a future ACL2 release. We welcome comments from the ACL2 community about whether or not that would be a good thing to do. See the discussion above about [47mACL2_BOOK_DIRS[0m for the ``modern'' way to accomplish the same thing. Many community book directories have a [47mMakefile[0m. If you modify books only in such a directory, you can recertify by standing in that directory and issuing a `make' command. This command can optionally specify an ACL2 executable as well as parallelism, for example as follows, where the first line ([47mmake clean[0m) is optional. make clean (time nice make -j 8 ACL2=my-acl2) [31;1mACL2 Customization Files[0m By default, your acl2-customization file (see [ACL2-customization]) is ignored by all flavors of ``[47mmake regression[0m''. However, you can specify the use of an acl2-customization file by setting the value of environment variable [47mACL2_CUSTOMIZATION[0m to the empty string, indicating a default such file, or to the desired absolute pathname. For example: make regression ACL2_CUSTOMIZATION='' make regression ACL2_CUSTOMIZATION='~/acl2-customization.lisp' [31;1mRegressions for Variants of ACL2[0m The discussion above also pertains to using ACL2(p) (see [parallel]) or ACL2(r) (see [real]), in which case the default is [47msaved_acl2p[0m or [47msaved_acl2r[0m respectively, rather than [47msaved_acl2[0m. However, we recommend that you use ACL2, not ACL2(p), for your regression. Then you can use ACL2(p) for your own proof developments. However, if you want to use ACL2(p) or for your regression, see [waterfall-parallelism-for-book-certification]. [31;1mProvisional Certification[0m To use provisional certification (see [provisional-certification]), supply [47mACL2_PCERT=t[0m with your `make' command. Here is an example. time nice make regression -j 4 ACL2_BOOK_DIRS=deduction ACL2_PCERT=t [31;1mMiscellany[0m Other control of the certification process may be found by perusing community books file [47mbooks/make_cert[0m. In particular, the [47mINHIBIT[0m variable may be set to a call of [47m[set-inhibit-output-lst][0m, for example as follows to obtain the output one would get by default in an (interactive) ACL2 session. time nice make regression -j 4 ACL2_BOOK_DIRS=arithmetic \ INHIBIT='(set-inhibit-output-lst proof-tree)' [31;1mTroubleshooting[0m If you run into problems, you can get help by joining the [47macl2-help[0m email list (follow the link from the ACL2 home page) and sending a message to that list. Also consider trying another version of GNU `make'; for example, we have found that versions 3.81 and 3.82 sometimes cause errors on Linux where version 3.80 does not. Note however that Version 3.80 does not print certain informational messages that are printed by later versions.") (books-certification-classic (books-certification) "Classic ACL2 `make'-based certification of [books] This [documentation] topic explains an approach to certifying directories of books, which we call ``classic ACL2 `make'-based certification''. Warning: The capability described in this section might be replaced at any time by a capability based on corresponding support for community books (see [books-certification]). If you think that would be a hardship, please contact the ACL2 implementors. This topic discusses a way to certify a directory of books other than the ACL2 community books. See [books-certification] for how to certify the set of ACL2 community [books]. There is also a section in that [documentation] topic, ``Restricting to Specific Directories and Books'', that provides an alternative to classic ACL2 `make'-based certification (as discussed in the present topic) for certifying specified sets of books. We assume here a familiarity with Unix/Linux `make'. We also assume that you are using GNU `make' rather than some other flavor of `make'. And finally, we assume, as is typically the case by following the standard [installation] instructions, that you install the ACL2 community books in the [47mbooks/[0m subdirectory of your ACL2 distribution. We will refer below to that directory as [47mBOOKS[0m. In summary: to use `make' to certify [books] under a given directory, you may create a simple Makefile in that directory (as explained below) so that when you stand in that directory, you can submit the command, `make', to certify those books. If you have a multi-processor machine or the like, then you can use the `[47m-j[0m flag `make'-level parallelism by specifying the number of concurrent processes. For example: make -j 4 For each book [47mfoo.lisp[0m, a file [47mfoo.out[0m in the same directory as [47mfoo.lisp[0m will contain the output from the corresponding certification attempt. If you have previously executed such a command, then you might first want to delete [certificate] files and other generated files by executing the following command. make clean Note that when you run `make', then by default, the first error will cause the process to stop. You can use [47mmake -i[0m to force `make' to ignore errors, thus continuing past them. Or, use [47mmake -k[0m to keep going, but skipping certification for any book that includes another whose certification has failed. By default, your acl2-customization file (see [ACL2-customization]) is ignored by such `make' commands. However, you can specify the use of an acl2-customization file by setting the value of environment variable [47mACL2_CUSTOMIZATION[0m to the empty string, indicating a default such file, or to the desired absolute pathname. For example: make ACL2_CUSTOMIZATION='' make ACL2_CUSTOMIZATION='~/acl2-customization.lisp' We now discuss how to create makefiles to support `make' commands as discussed above. First we give five steps for creating a [47mMakefile[0m to support certification of a directory of books, without subdirectories. For examples of such Makefiles you can look in community book directories (which, however, might disappear in future versions of ACL2). 1. Include the file [47mMakefile-generic[0m from the [47mbooks/[0m subdirectory of your ACL2 sources directory, but first perhaps define the variable `[47mACL2[0m'. Consider the following example. ACL2 ?= /Users/john_doe/acl2/acl2-sources/saved_acl2 include /Users/john_doe/acl2/acl2-sources/books/Makefile-generic In this example, you can omit the first line, because the default ACL2 executable is file [47msaved_acl2[0m in the directory immediately above the directory of the specified [47mMakefile-generic[0m file. Indeed, that is the common case. Note the use of [47m?=[0m instead of [47m=[0m or [47m:=[0m, so that [47mACL2[0m can instead be defined by the environment or provided on the command line as part of the `make' command. 2. (Optional; usually skipped.) Set the [47mINHIBIT[0m variable if you want to see more than the [summary] output. For example, if you want to see the same output as you would normally see at the terminal, put this line in your Makefile after the `[47minclude[0m' lines. INHIBIT = (assign inhibit-output-lst (list (quote proof-tree))) For other values to use for [47mINHIBIT[0m, see [set-inhibit-output-lst] and see the original setting of [47mINHIBIT[0m in [47mbooks/Makefile-generic[0m. 3. Specify the books to be certified. Normally, every file with extension [47m.lisp[0m will be a book that you want to certify, in which case you can skip this step. Otherwise, put a line in your [47mMakefile[0m after the ones above that specifies the books to be certified. The following example, from an old version of community books file [47mbooks/finite-set-theory/osets/Makefile[0m, should make this clear. BOOKS = computed-hints fast instance map membership outer primitives \ quantify set-order sets sort But better yet, use the extension [47m.lsp[0m for any Lisp or ACL2 files that are not to be certified, so that the definition of [47mBOOKS[0m can be omitted. 4. Create [47m.acl2[0m files for books that are to be certified in other than the initial ACL2 world (see [portcullis]). For example, if you look in community books file [47mbooks/arithmetic/equalities.acl2[0m you will see [47m[defpkg][0m forms followed by a [47m[certify-book][0m command, because it was determined that [47m[defpkg][0m forms were necessary in the certification world in order to certify the [47mequalities[0m book. In general, for each [47m<book-name>.lisp[0m whose certification requires a non-initial certification world, you will need a corresponding [47m<book-name>.acl2[0m file that ends with the appropriate [47m[certify-book][0m command. You also have the option of creating a file [47mcert.acl2[0m that has a special role. When file [47m<book-name>.lisp[0m is certified, if there is no file [47m<book-name>.acl2[0m but there is a file [47mcert.acl2[0m, then [47mcert.acl2[0m will be used as [47m<book-name>.acl2[0m would have been used, as described in the preceding paragraph, except that the appropriate [47m[certify-book][0m command will be generated automatically. Thus, no [47mcertify-book[0m command should occur in [47mcert.acl2[0m. It is actually allowed to put raw lisp forms in a [47m.acl2[0m file (presumably preceded by [47m:q[0m or [47m(value :q)[0m and followed by [47m(lp)[0m). But this is not recommended (see [q]); we make no guarantees about certification performed any time after raw Lisp has been entered in the ACL2 session. 5. Generally, the next step is to include the following line after the `[47minclude[0m' of [47mMakefile-generic[0m (see the first step above). -include Makefile-deps This will cause `make' to create and then include a file [47mMakefile-deps[0m that contains ``dependency'' lines needed by `make'. If those dependencies are somehow flawed, it may be because you have [47m[include-book][0m forms that are not truly including books, for example in multi-line comments ([47m#|..|#[0m). These will be ignored if preceded by a semicolon ([47m;[0m), or if you add a line break after ``[47minclude-book[0m.'' But instead of adding the `[47m-include[0m' line above, you can create dependency lines yourself by running the command make dependencies and pasting the result into the end of your [47mMakefile[0m, and editing as you see fit. This concludes the basic instructions for creating a [47mMakefile[0m in a directory including books. Here are some other capabilities offered by community books file [47mbooks/Makefile-subdirs[0m. Not included below is a discussion of how to increase parallelism by avoiding the need to certify included books before certifying a given book; see [provisional-certification]. [31;1mSubdirectory Support[0m There is support for using `make' to certify books in subdirectories. Consider the following example. DIRS = pass1 bind-free floor-mod include ../Makefile-subdirs This indicates that we are to run `make' in subdirectories [47mpass1/[0m, [47mbind-free/[0m, and [47mfloor-mod/[0m of the current directory. You can combine this subdirectory support with the support already discussed for certifying books in the top-level directory. Here is an example, which as of this writing is in community books file [47mbooks/arithmetic-3/Makefile[0m contains the following lines. arith-top: top all all: top DIRS = pass1 bind-free floor-mod include ../Makefile-subdirs include ../Makefile-generic -include Makefile-deps The `[47mtop[0m' target is defined in [47m../Makefile-subdirs[0m to call `make' in each subdirectory specified in [47mDIRS[0m. We have set the default target in the example above to a new name, [47marith-top[0m, that makes that [47mtop[0m target before making the `[47mall[0m' target which, in turn, is the default target in any [47mMakefile-generic[0m, and is responsible for certifying books in the current directory as discussed in the five steps displayed above. Use [47mMakefile-psubdirs[0m instead of [47mMakefile-subdirs[0m if certification of a book in a subdirectory never depends on certification of a book in a different subdirectory, because then the [47m-j[0m option of `make' can allow subdirectories to be processed in parallel. [31;1mCleaning Up[0m We note that there is a [47mclean[0m target. Thus, make clean will remove generated files including [47m.cert[0m, [47m.out[0m files, and compiled files. [31;1mSystem Books[0m An environment variable [47mACL2_SYSTEM_BOOKS[0m is generally set automatically, so you can probably skip reading the following paragraph unless your attempt to certify books fails to locate those books properly. The environment variable [47mACL2_SYSTEM_BOOKS[0m can be set to the top-level directory of the ACL2 community books. A Unix-style pathname, typically ending in [47mbooks/[0m or [47mbooks[0m, is permissible. In most cases, your ACL2 executable is a small script in which you can set this environment variable just above the line on which the actual ACL2 image is invoked, for example: export ACL2_SYSTEM_BOOKS ACL2_SYSTEM_BOOKS=/home/acl2/v3-2/acl2-sources/books However, you can also set [47mACL2_SYSTEM_BOOKS[0m as a `make' variable, by setting it in your [47mMakefile[0m before the first target definition, e.g.: ACL2_SYSTEM_BOOKS ?= /home/acl2/v3-2/acl2-sources/books [31;1mCompilation Support[0m The file [47mbooks/Makefile-generic[0m provides support for compiling books that are already certified (but see [compilation] for an exception). For example, suppose that you have certified books using GCL as the host Lisp, resulting in compiled files with the [47m.o[0m extension. Now suppose you would like to compile the books for Allegro Common Lisp, whose compiled files have the [47m.fasl[0m extension. The following command will work if you have included [47mbooks/Makefile-generic[0m in your [47mMakefile[0m. make fasl In general, the compiled file extension for a Lisp supported by ACL2 will be a target name for building compiled files for all your books (after certifying the books, if not already up-to-date on certification). If you run into problems, you can get help by joining the [47macl2-help[0m email list (follow the link from the ACL2 home page) and sending a message to that list. Also consider trying another version of GNU `make'; for example, we have found that versions 3.81 and 3.82 sometimes cause errors on Linux where version 3.80 does not.") (books-reference (books) "Reference guide for ACL2 functionality related to books, e.g., [include-book], [certify-book], [cbd], etc. Subtopics [Add-include-book-dir] Link keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m [Add-include-book-dir!] Non-[47m[local][0mly link keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m [Book-compiled-file] Creating and loading of compiled and expansion files for [books] [Cbd] Connected book directory string [Certify-book] How to produce a [certificate] for a book [Certify-book-debug] Some possible ways to work around [47m[certify-book][0m failures [Delete-include-book-dir] Unlink keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m [Delete-include-book-dir!] Non-[47m[local][0mly unlink keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m [Full-book-name] Book naming conventions assumed by ACL2 [Include-book] Load the [events] in a file [Pathname] Introduction to filename conventions in ACL2 [Set-cbd] To set the connected book directory [Set-write-ACL2x] Cause [47m[certify-book][0m to write out a [47m.acl2x[0m file [With-cbd] To bind the connected book directory [With-current-package] To bind the [current-package]") (books-tour (books) "The [3mguided tour[0m of concepts related to ACL2 [books]. The tour begins with [book-example]. Subtopics [Book-contents] Restrictions on the forms inside [books] [Book-example] How to create, certify, and use a simple book [Book-name] Conventions associated with book-names [Certificate] A file specifying validity of a given book [Certify-book] How to produce a [certificate] for a book [Include-book] Load the [events] in a file [Keep] How we know if [47m[include-book][0m read the correct files [Portcullis] The gate guarding the entrance to a certified book") (boole$ (numbers acl2-built-ins) "Perform a bit-wise logical operation on 2 two's complement integers When integers [47mx[0m and [47my[0m are viewed in their two's complement representation, [47m(boole$ op x y)[0m returns the result of applying the bit-wise logical operation specified by [47mop[0m. The following table is adapted from documentation for the analogous Common Lisp function {boole | https://www.lispworks.com/documentation/HyperSpec/Body/f_boole.htm} in the {Common Lisp Hyperspec | https://www.lispworks.com/documentation/HyperSpec/}. Note that the values of [47mop[0m for [47mboole$[0m are ACL2 constants, rather than corresponding values of [47mop[0m for the Common Lisp function [47mboole[0m. op result ----------- --------- *boole-1* x *boole-2* y *boole-andc1* and complement of x with y *boole-andc2* and x with complement of y *boole-and* and *boole-c1* complement of x *boole-c2* complement of y *boole-clr* the constant 0 (all zero bits) *boole-eqv* equivalence (exclusive nor) *boole-ior* inclusive or *boole-nand* not-and *boole-nor* not-or *boole-orc1* or complement of x with y *boole-orc2* or x with complement of y *boole-set* the constant -1 (all one bits) *boole-xor* exclusive or The guard of [47mboole$[0m specifies that [47mop[0m is the value of one of the constants above and that [47mx[0m and [47my[0m are integers. See any Common Lisp documentation for analogous information about Common Lisp function [47mboole[0m. [31;1mFunction: [0m<boole$> (defun boole$ (op i1 i2) (declare (type (integer 0 15) op) (type integer i1 i2)) (cond ((eql op *boole-1*) i1) ((eql op *boole-2*) i2) ((eql op *boole-and*) (logand i1 i2)) ((eql op *boole-andc1*) (logandc1 i1 i2)) ((eql op *boole-andc2*) (logandc2 i1 i2)) ((eql op *boole-c1*) (lognot i1)) ((eql op *boole-c2*) (lognot i2)) ((eql op *boole-clr*) 0) ((eql op *boole-eqv*) (logeqv i1 i2)) ((eql op *boole-ior*) (logior i1 i2)) ((eql op *boole-nand*) (lognand i1 i2)) ((eql op *boole-nor*) (lognor i1 i2)) ((eql op *boole-orc1*) (logorc1 i1 i2)) ((eql op *boole-orc2*) (logorc2 i1 i2)) ((eql op *boole-set*) 1) ((eql op *boole-xor*) (logxor i1 i2)) (t 0)))") (boolean-listp (booleanp lists acl2-built-ins) "Recognizer for a true list of booleans The predicate [47mboolean-listp[0m tests whether its argument is a [47m[true-listp][0m of objects each or which satisfies [47m[booleanp][0m, i.e., is [47mt[0m or [47mnil[0m. [31;1mFunction: [0m<boolean-listp> (defun boolean-listp (lst) (declare (xargs :guard t)) (cond ((atom lst) (eq lst nil)) (t (and (or (eq (car lst) t) (eq (car lst) nil)) (boolean-listp (cdr lst))))))") (booleanp (basics acl2-built-ins) "Recognizer for booleans [47m(Booleanp x)[0m is [47mt[0m if [47mx[0m is [47mt[0m or [47mnil[0m, and is [47mnil[0m otherwise. See [generalized-booleans] for a discussion of a potential soundness problem for ACL2 related to the question: Which Common Lisp functions are known to return Boolean values? [31;1mFunction: [0m<booleanp> (defun booleanp (x) (declare (xargs :guard t)) (if (eq x t) t (eq x nil))) Subtopics [Boolean-listp] Recognizer for a true list of booleans") (bounders (tau-system) "Intervals, bounder functions, and bounder correctness [3mBounder Forms 1 and 2[0m: (implies (and (tau-intervalp i1) ... (or (equal (tau-interval-dom i1) 'dom1-1) ...) ... (in-tau-intervalp x1 i1) ...) (and (tau-intervalp (bounder-fn i1 ...)) (in-tau-intervalp [3mtarget[0m (bounder-fn i1 ...)))) where [3mtarget[0m is either [47m(fn x1 ... y1 ...)[0m or [47m(mv-nth 'n (fn x1 ... y1 ...))[0m, depending on whether we are in the [3mForm 1[0m or [3mForm 2[0m case, respectively. However, the shape above is meant just as a reminder. Details are given below. This topic first explains the basic shape of [3mBounder Form 1[0m. Then it illustrates [3mBounder Form 2[0m. Finally, it deals briefly with proving bounder correctness theorems. The community book [47mtau-bounders/elementary-bounders[0m contains bounders for various elementary functions including [47m[+][0m, [47m[*][0m, [47m[/][0m, [47m[floor][0m, [47m[mod][0m, [47m[logand][0m, [47m[lognot][0m, [47m[logior][0m, [47m[logorc1][0m, [47m[logeqv][0m, [47m[logxor][0m, and [47m[ash][0m. You might look at or include this book to see more example theorems, to see how proofs of such theorems are managed, and to experiment with their effects on proving theorems involving arithmetic over finite or half-finite intervals. A bounder correctness theorem establishes that [47mbounder-fn[0m is a ``bounder'' for the function [47mfn[0m. That means that when trying to compute a tau for a call of [47mfn[0m (or, in the case of [3mForm 2[0m, for the [47mn[0mth component of the multiple-value vector returned by a call of [47mfn[0m) the tau system can call [47mbounder-fn[0m on the intervals containing certain arguments of [47mfn[0m. Let us start with an example. Let [47mfn[0m be the addition function, [47m+[0m (actually, [47m[binary-+][0m). Consider the target term [47m(+ x y)[0m and contemplate the question: if you know intervals containing [47mx[0m and [47my[0m, say [47mintx[0m and [47minty[0m respectively, what is an interval containing their sum? The answer is pretty easy to state in English: the domain of the answer interval is the less restrictive of the domains of [47mintx[0m and [47minty[0m. The lower bound of the answer interval is the sum of the lower bounds of [47mintx[0m and [47minty[0m, and the lower relation is the stronger of the lower relations of [47mintx[0m and [47minty[0m. Analogous comments define the upper bound and relation of the answer interval. So for example, if [47mx[0m is an [47mINTEGERP[0m such that [47m0 <= x <= 10[0m and [47my[0m is a [47mRATIONALP[0m such that [47m0 < y <= 20[0m, then [47m(+ x y)[0m is a [47mRATIONALP[0m such that [47m0 < (+ x y) <= 30[0m. Defining this precisely is more tedious than describing it in English because one must make precise the notions of ``less restrictive'' domains, ``weaker'' relations, and the possibility that either or both of the bounds could be ``infinite.'' But we can easily imagine defining the function [47mbounder-for-+[0m that returns the answer interval described, given [47mintx[0m and [47minty[0m. Then the following [3mBounder Form 1[0m formula establishes the correctness of [47mbounder-for-+[0m and allows the tau system to use it to produce bounds in the tau computed for [47m+[0m-expressions: (implies (and (tau-intervalp intx) (tau-intervalp inty) (in-tau-intervalp x intx) (in-tau-intervalp y inty)) (and (tau-intervalp (bounder-for-+ intx inty)) (in-tau-intervalp (+ x y) (bounder-for-+ intx inty)))) For example, suppose we have a formula with the following hypotheses (and (integerp a) (<= 0 a) (<= a 10) (rationalp b) (< 0 b) (<= b 20)) and suppose the tau system encounters the term [47m(+ a b)[0m. When the term is encountered, the tau for [47ma[0m would include an [47mINTEGERP[0m interval such that [47m0 <= a <= 10[0m and the tau for [47mb[0m would include a [47mRATIONALP[0m interval such that [47m0 < b <= 20[0m. In its most primitive configuration, the tau system would only know that the tau for [47m(+ a b)[0m includes the recognizer [47mRATIONALP[0m (and all that it is known to imply). But after the bounder theorem above is proved and available as a [47m:tau-system[0m rule the tau system would infer that [47m(+ a b)[0m was in the [47mRATIONALP[0m interval such that [47m0 < (+ a b) <= 30[0m. Thus, by defining bounder functions and proving them correct the user can give the tau system the ability to compute the bounds on function calls as a function of the known bounds on their actuals. It is sometimes useful to restrict the domains of the intervals to be considered. For example, in bounding [47m*[0m-expressions it is simplifying to restrict one's attention to intervals over the integers or rationals (and thus exclude the complex rationals so one need not think about the getting negative bounds by multiplying two ``positive'' complex rationals or how to ``round up'' from complex bounds to the rationals required by our intervals). If we were to define [47mbounder-for-*[0m so that it works correctly to bound [47m*[0m-expressions, but only for integer or rational arguments, its correctness theorem would be: (implies (and (tau-intervalp intx) ; (a) (tau-intervalp inty) (or (equal (tau-interval-dom intx) 'INTEGERP) ; (b) (equal (tau-interval-dom intx) 'RATIONALP)) (or (equal (tau-interval-dom inty) 'INTEGERP) (equal (tau-interval-dom inty) 'RATIONALP)) (in-tau-intervalp x intx) ; (c) (in-tau-intervalp y inty)) (and (tau-intervalp (bounder-for-* intx inty)) ; (d) (in-tau-intervalp (* x y) ; (e) (bounder-for-* intx inty)))) In this case, [47mbounder-for-*[0m would be applied to the intervals for [47mx[0m and [47my[0m only if those intervals were over the integers or the rationals. The above theorem for [47mbounder-for-*[0m begins to suggest the general form of a bounder theorem and we will use it to explain the general form. The hypotheses of a bounder theorem must be a conjunction and the conjuncts must be partitionable into three parts, (a), (b), and (c). The conclusion, must be a conjunction, must contain at least two conjuncts, (d) and (e), and is allowed to contain others that are simply ignored for purposes of bounders. (See the note below about why we allow but ignore additional conjuncts in the conclusion.) Part (a) introduces some distinct ``interval variables,'' here called ``ivars,'' that are known to denote intervals; for the example above, the ivars are [47mintx[0m and [47minty[0m. Each hypothesis in part (a) is of the form [47m(TAU-INTERVALP ivar)[0m. Part (b) allows us to restrict the domains of some of the intervals. Each hypothesis in part (b) must be a disjunction and each of the disjuncts must be of the form [47m(EQUAL (TAU-INTERVAL-DOM ivar) 'dom)[0m, where [47mivar[0m is one of the interval variables and [47mdom[0m is one of [47mINTEGERP[0m, [47mRATIONALP[0m, [47mACL2-NUMBERP[0m, or [47mNIL[0m. It is not necessary to restrict every interval variable. Indeed, part (b) may be empty, as in the theorem for [47mbounder-for-+[0m above. Part (c) consists of a set of [47m(IN-TAU-INTERVALP avar ivar)[0m hypotheses where each [47mavar[0m is a variable and no two hypotheses in part (c) use the same [47mavar[0m or [47mivar[0m. We call the set of all such [47mavar[0m the ``actual variables'' or ``avars.'' The avars and ivars must be distinct. Part (c) sets up a correspondence between the avars and the ivars, each avar is in an interval denoted by one ivar. Part (d) introduces the name of the bounder function, here [47mbounder-for-*[0m, and the order of its ivar arguments. We see that [47mbounder-for-*[0m takes two arguments and they correspond, in order, to the intervals containing [47mx[0m and [47my[0m. Part (d) also establishes that the bounder function always returns an interval under hypotheses (a), (b), and (c). Note that it is sometimes useful to return the ``universal interval'' (one that contains everything) if you don't want to compute a better interval for some case; see [47m[tau-intervalp][0m or [47m[in-tau-intervalp][0m. Part (e) introduces the name of the function being bounded, here [47m*[0m, and the order of its arguments. It establishes that the function being bounded really is bounded by the interval computed by the bounder function. In general, the function being bounded may take additional arguments. It is possible that the function being bounded takes some arguments that do not affect the bounds of its output. Thus, parts (c) and (e) together establish a mapping between the actuals of a call of the function being bounded and the intervals to be supplied to the bounder. The parts identified above may be presented in any order and the literals constituting those parts may be mingled. Thus, for example, here is another version of the theorem above that generates the same bounding information for the tau system. In this version, the hypotheses and conclusions are rearranged, [47mbounder-for-*[0m takes its arguments in the opposite order, and the theorem includes an additional conclusion. (implies (and (tau-intervalp intx) ; (a) (or (equal (tau-interval-dom intx) 'INTEGERP) ; (b) (equal (tau-interval-dom intx) 'RATIONALP)) (in-tau-intervalp x intx) ; (c) (tau-intervalp inty) ; (a) (or (equal (tau-interval-dom inty) 'INTEGERP) ; (b) (equal (tau-interval-dom inty) 'RATIONALP)) (in-tau-intervalp y inty)) (and (in-tau-intervalp (* x y) ; (e) (bounder-for-* inty intx)) (tau-intervalp (bounder-for-* inty intx)) ; (d))) (or (equal (tau-interval-dom (bounder-for-* inty intx)) 'INTEGERP) (equal (tau-interval-dom (bounder-for-* inty intx)) 'RATIONALP)) [3mNote on why bounder forms allow additional conjuncts in the conclusion[0m: It is often the case that one creates bounders by composing other bounders. To prove compositional bounds correct one must often prove more than the mere correctness of the components. For example, one might need to prove that the domain of the new bounding interval is [47mINTEGERP[0m or otherwise restricted. We allow such ``unnecessary'' conclusions simply to save the user the burden of stating multiple theorems. [3mAn Illustration of Bounder Form 2[0m: Suppose [47m(quad i)[0m is defined so that truncates the integer [47mi[0m to the largest multiple of 4 weakly below [47mi[0m and, additionally, returns the remainder. For example, [47m(quad 26)[0m returns [47m(mv 24 2)[0m. Then here are bounders for each of its return values: (defun quad-bounds-0 (i) (cond ((and (tau-interval-lo i) (<= 0 (tau-interval-lo i))) (make-tau-interval 'integerp nil 0 nil (tau-interval-hi i))) (t (make-tau-interval nil nil nil nil nil)))) (defun quad-bounds-1 (i) (cond ((and (tau-interval-lo i) (<= 0 (tau-interval-lo i))) (make-tau-interval 'integerp nil 0 nil 3)) (t (make-tau-interval nil nil nil nil nil)))) Note that the bounders assume [47mi[0m is an [47mINTEGERP[0m and return the universal interval when [47mi[0m is not a natural. As noted in the discussion below about how to prove bounder correctness theorems, proving these bounders correct will require an arithmetic book, e.g., (include-book "arithmetic-5/top" :dir :system) Here then are two bounder correctness theorems of [3mForm 2[0m: (defthm quad-bounds-0-correct (implies (and (tau-intervalp i) (equal (tau-interval-dom i) 'INTEGERP) (in-tau-intervalp x i)) (and (tau-intervalp (quad-bounds-0 i)) (in-tau-intervalp (mv-nth 0 (quad x)) (quad-bounds-0 i)))) :rule-classes :tau-system) (defthm quad-bounds-1-correct (implies (and (tau-intervalp i) (equal (tau-interval-dom i) 'INTEGERP) (in-tau-intervalp x i)) (and (tau-intervalp (quad-bounds-1 i)) (in-tau-intervalp (mv-nth 1 (quad x)) (quad-bounds-1 i)))) :rule-classes :tau-system) As noted above, if these bounders are to be used in constructing other bounders, we might include (in the first theorem) an additional concluding conjunct, such as (equal (tau-interval-dom (quad-bounds-0 i)) 'INTEGERP) so that we can keep [47mquad-bounds-0[0m disabled to allow us to use [47mquad-bounds-0-correct[0m as a [47m:rewrite[0m or other rule and still relieve hypotheses about the domain of the interval it produces. These hypotheses would arise if some other verified bounder was called on the produced interval. In addition, as noted below, we might replace the [47m:rule-classes[0m above with :rule-classes ((:rewrite) (:forward-chaining :trigger-terms ((quad-bounds-0 i)))) Since the theorem is being stored as some kind of rule and since it satisfies the [3mBounder Form 2[0m shape, it will additionally be stored as a [47m:tau-system[0m rule. [3mNote on proving bounder theorems[0m: Proving bounder theorems is just like proving any other arithmetic theorem and you will need whatever libraries are appropriate for the problem domain you are working in. Do not expect the tau system to be of much use in proving bounder theorems. A typical bounder theorem might require you to prove a subgoal like [47m(< (fn x y) (g (tau-interval-hi int1) int2))[0m. But tau deals with inequalities relating terms to constants, e.g., [47m(< ... 16)[0m. A bounder theorem is a sort of ``metatheorem'' about [3mhow to construct[0m bounded intervals from other bounded intervals. So when you undertake to define a bounder and prove it correct, go into the project with your eyes open! But bounder functions can be broadly divided into two classes, those defined in terms of arithmetic on the interval bounds and those defined in terms of other bounders. For example, given that (LOGXOR x y) = (LOGNOT (LOGEQV x y)) an interval for bounding [47mLOGXOR[0m can be constructed by composing the constructions of intervals for [47mLOGEQV[0m and [47mLOGNOT[0m. So some bounder correctness proofs will involve direct manipulation of arithmetic inequalities and others might involve appeal to the correctness of other bounders, depending on how the new bounder is defined. Regardless of which style of bounder we are dealing with, we have found it useful to prove the basic theorems relating the tau interval accessors to [47m[make-tau-interval][0m, e.g., (equal (tau-interval-dom (make-tau-interval dom lo-rel lo hi-rel hi)) dom) and then disable those functions to avoid seeing excessive [47mcar[0ms and [47mcdr[0ms. When dealing with bounders defined in the direct, arithmetic style, we tend to keep [47m[tau-intervalp][0m and [47m[in-tau-intervalp][0m enabled so they unfold and expose the algebra. When dealing with bounders defined compositionally in terms of other verified bounders, we tend to keep [47m[tau-intervalp][0m and [47m[in-tau-intervalp][0m disabled so we can rely on the previously proved bounder theorems as rewrite and forward chaining rules. Note that this last remark means that when you prove bounder correctness theorems you should include corollaries that are useful [47m:rewrite[0m and possibly [47m:forward-chaining[0m rules if you anticipate using that bounder in more complex ones. We tend to trigger the forward chaining with the bounder expression itself, rather than one of the hypotheses. For example in the rule above for [47mbounder-for-*[0m we would include [47m(:forward-chaining :trigger-terms ((tau-bounder-expt2 int2)))[0m and let the [47min-tau-intervalp[0m hypotheses select the free variables [47mx[0m and [47my[0m.") (break$ (errors acl2-built-ins) "Cause an immediate Lisp break ACL2 users are generally advised to avoid breaking into raw Lisp. Advanced users may, on occasion, see the need to do so. Evaluating [47m(break$)[0m will have that effect. (Exception: [47mbreak$[0m is disabled after evaluation of [47m(set-debugger-enable :never)[0m; see [set-debugger-enable].) [47mBreak$[0m returns [47mnil[0m. Note that upon returning to the ACL2 read-eval-print loop (for example, using [47m:q[0m if the host Lisp is CCL), one will be at the top level even if one had been inside a recursive call of [47m[ld][0m or a [wormhole]. [31;1mFunction: [0m<break$> (defun break$ nil (declare (xargs :guard t)) nil)") (break-lemma (break-rewrite) "A quick introduction to breaking rewrite rules in ACL2 Example: :brr t ; if you haven't done that yet :monitor (:rewrite lemma12) t ; to install a break point on the ; rule named (:rewrite lemma12) :monitor! (:rewrite lemma12) t ; quiet version of :monitor that ; invokes :brr t ACL2 does not support Nqthm's [47mbreak-lemma[0m but supports a very similar and more powerful break facility. Suppose some proof is failing; apparently some particular rule is not being used and you wish to learn why. Then you need the ACL2 [break-rewrite] facility. See [break-rewrite] and all of its associated [47m:[0m[47m[doc][0m topics for details. The following basic steps are required. (1) To enable the ``break rewrite'' feature, you must first execute ACL2 !>:brr t at the top-level of ACL2. Equivalently, evaluate [47m(brr t)[0m. [Break-rewrite] stays enabled until you disable it with [47m(brr nil)[0m. When [break-rewrite] is enabled the ACL2 rewriter will run slower than normal but you will be able to [monitor] the attempts to apply specified rules. (2) Decide what [rune]s (see [rune]) you wish to [monitor]. For example, you might want to know why [47m(:rewrite lemma12 . 2)[0m is not being used in the attempted proof. That, by the way, is the name of the second rewrite rule generated from the event named [47mlemma12[0m. The command ACL2 !>:monitor (:rewrite lemma12 . 2) t will install an ``unconditional'' break point on that rule. The ``[47mt[0m'' at the end of the command means it is unconditional, i.e., a break will occur every time the rule is tried. ACL2 supports conditional breaks also, in which case the [47mt[0m is replaced by an expression that evaluates to non-[47mnil[0m when you wish for a break to occur. See [monitor]. The above keyword command is, of course, equivalent to ACL2 !>(monitor '(:rewrite lemma12 . 2) t) which you may also type. You may install breaks on as many rules as you wish. You must use [47m[monitor][0m on each rule. You may also change the break condition on a rule with [47m[monitor][0m. Use [47m[unmonitor][0m (see [unmonitor]) to remove a rule from the list of [monitor]ed rules. (3) Then try the proof again. When a [monitor]ed rule is tried by the rewriter you will enter an interactive break, called [break-rewrite]. See [break-rewrite] for a detailed description. Very simply, [break-rewrite] lets you inspect the context of the attempted application both before and after the attempt. When [break-rewrite] is entered it will print out the ``target'' term being rewritten. If you type [47m:go[0m [break-rewrite] will try the rule and then exit, telling you (a) whether the rule was applied, (b) if so, how the target was rewritten, and (c) if not, why the rule failed. There are many other commands. See [brr-commands]. (4) When you have finished using the [break-rewrite] feature you should disable it to speed up the rewriter. You can disable it with ACL2 !>:brr nil The list of [monitor]ed rules and their break conditions persists but is ignored. If you enable [break-rewrite] later, the list of [monitor]ed rules will be displayed and will be used again by rewrite. You should disable the [break-rewrite] feature whenever you are not intending to use it, even if the list of [monitor]ed rules is empty, because the rewriter is slowed down as long as [break-rewrite] is enabled. If you get a stack overflow, see [cw-gstack].") (break-on-error (trace acl2-built-ins) "Break when encountering a hard or soft error caused by ACL2 General forms: (break-on-error t) ; installs a trace causing a continuable error (break) ; when an error is invoked by ACL2. (break-on-error) ; same as above (break-on-error :all) ; same as above, but even when inside the prover (break-on-error nil) ; uninstall any above trace Evaluation of [47m(break-on-error :all)[0m generates a suitable [trace] of error functions, so that the Lisp debugger is entered whenever ACL2 calls them. You can then continue the interrupted computation by suitable exit from the debugger (with a command that depends on the host Lisp). Evaluation of [47m(Break-on-error t)[0m, or equivalently, [47m(break-on-error)[0m, is similar except that certain errors are ignored when inside the theorem prover; this is probably preferable, in general, to [47m(break-on-error :all)[0m. Finally, evaluation of [47m(break-on-error nil)[0m removes those traces. [31;1mRemarks[0m. * The argument, if supplied, is evaluated and must evaluate to [47mt[0m, [47mnil[0m, or [47m:all[0m. * For technical reasons, you may see breaks or error messages more than once. * It is an error to call [47mbreak-on-error[0m while in [raw-mode]. * [47mBreak-on-error[0m is implemented using ACL2 [47m[trace!][0m, which is a version of [47m[trace$][0m that uses a [ttag] and hence generates a ``[47mTTAG NOTE[0m'' message. You can use [47m:[0m[47m[trans1][0m to see the [47mtrace![0m call generated by a given call of [47mbreak-on-error[0m. Evaluate [47m(trace$)[0m if you want to see the current trace specs. You are of course welcome to define your own version of [47mbreak-on-error[0m by modifying a copy of the source definition (search for ``[47m(defmacro break-on-error)[0m'' in ACL2 source file [47mother-events.lisp[0m). Please feel free to send your version of [47mbreak-on-error[0m to the ACL2 implementors, to consider for inclusion into ACL2. Also see [set-debugger-enable] for how to get raw-Lisp backtrace information when an error occurs as a result of [47mbreak-on-error[0m, or even of a raw Lisp error, by calling [47mset-debugger-enable[0m with argument [47m:bt[0m, [47m:bt-break[0m, or [47m:break-bt[0m. Note that for ACL2 errors (as opposed to raw Lisp errors), i.e. errors affected by [47mbreak-on-error[0m, all three of those keyword values are treated equivalently (and, all are ignored for non-ANSI GCL; see [set-debugger-enable]).") (break-rewrite (debugging) "A version of the ACL2 rewriter with interactive breaks ACL2 allows the user to [monitor] the application of [rewrite], [definition], and [linear] rules. When the rewriter is about to try to apply an [47m[enable][0md [monitor]ed rule, it can trigger an interactive break managed by a version of the rewriter called ``break-rewrite''. These breaks can be caused by * failure of a rewrite rule's equivalence relation to be a known refinement of the permitted relations, * failure of a rule's triggering pattern to match the target term while ``almost'' matching, * failure to relieve the hypotheses of the rule, or * failure of any of several heuristic checks to prevent looping in the rewriter. From within this read-eval-print loop you can inspect the context, attempt to apply the rule, and see what happens. This interactive loop is technically just a call of the standard ACL2 read-eval-print loop, [47m[ld][0m, on a ``[wormhole] [state]'' (see [wormhole]). While in break-rewrite, certain keyword commands are available for accessing information about the context in which the lemma is being tried. These keywords are called break-rewrite ``commands''; see [brr-commands]. Interactive breaks occur only if the [47mbreak-rewrite[0m utility is turned on (see [47m[brr][0m), a monitored rune is being considered by the rewriter, and the break conditions specified in the monitor are satisfied (see [47m[monitor][0m). The following utilities can also be helpful for proof [debugging]. * [47m[Dmr][0m (Dynamically Monitor Rewrites) allows you to watch progress of the rewriter in real time. * The [proof-builder] allows you to interactively construct a proof. * [47m[with-brr-data][0m helps you to find the source of a term in prover output. To abort from inside break-rewrite at any time, execute [47m:[0m[47m[a!][0m. Output from break-rewrite is abbreviated by default, but that can be changed. See [set-brr-evisc-tuple]. When the break-rewrite facility is turned on (see [47m[brr][0m), the rewriter performs more sluggishly than when break-rewrite is turned off. Therefore if you have done [47m(brr t)[0m to debug a rewriting problem, we recommend that you do [47m(brr nil)[0m after the situation is remedied and you resume normal proof development. For further information, see the related [47m:[0m[47m[doc][0m topics listed below. [3mAdvice to Developers and Maintainers of ACL2[0m: If you intend to modify break-rewrite, we strongly urge you to read the Essay on Break-Rewrite in the source code file [47mrewrite.lisp[0m. There we explain the abstraction provided by break-rewrite, how it is implemented as a state machine operating in a wormhole, and some low-level tools for inspecting the state of break-rewrite. Attempts to add new features without understanding virtually everything about the implementation is most likely to create a mess. It is possible to cause the ACL2 rewriter to [monitor] the attempted application of selected rules. When such a rule is about to be tried, the rewriter evaluates its break condition and if the result is non-[47mnil[0m, an interactive read-eval-print loop is entered. Break-rewrite permits the user to inspect the current [state] by evaluating break-rewrite commands. Type [47m:help[0m in break-rewrite to see what the break-rewrite commands are. However, break-rewrite is actually just a call of the general ACL2 read-eval-print loop, [47m[ld][0m, on a certain [state] and the break-rewrite commands are simply aliases provided by [47mld-keyword-aliases[0m [table] (see [ld-keyword-aliases]). See [ld] for details about this read-eval-print loop. Thus, with a few exceptions, anything you can do at the ACL2 top-level can be done within break-rewrite. For example, you can evaluate arbitrary expressions, use the keyword command hack, access [documentation], print [events], and even define functions and prove theorems. However, the ``certain [state]'' upon which [47m[ld][0m was called is a ``wormhole state'' (see [wormhole]) because break-rewrite is not allowed to have any effect upon the behavior of rewrite. What this means, at a high level, is that break-rewrite operates on a copy of the [state] being used by rewrite and when break-rewrite exits the [wormhole] closes and the [state] ``produced'' by break-rewrite disappears. For example, all invocations of [47m[trace$][0m and [47m[untrace$][0m that are made during such a break are undone when proceeding from that break (including when proceeding via the [47m:eval[0m brr-command). Thus, break-rewrite lets you query the state of the rewriter and even do experiments involving proofs, etc., but these experiments have no effect on the ongoing proof attempt. There are however exceptions to this loss of state when exiting a break. One exception pertains to iprinting (see [set-iprint]). When iprinting is enabled in a break, it nevertheless is again disabled upon exiting the break. However, the association of values with iprint indices persists even after exiting the break; that is, you can still obtain their values, and if you re-enable iprinting then indices will be generated from where they left off rather than returning to index 1. The other exception pertains to setting the [47m[brr-evisc-tuple][0m while inside break-rewrite: the effects persist. See [47m[set-brr-evisc-tuple][0m. When you enter break-rewrite a simple herald is printed such as: (3 Breaking (:rewrite lemma12) on (delta a (+ 1 j)): The integer after the open parenthesis indicates the depth of nested break-rewrite calls. In this discussion we use [47m3[0m consistently for this integer. Unless you abort or somehow enter unbalanced parentheses into the script, the entire session at a given depth will be enclosed in balanced parentheses, making it easy to skip over them in Emacs. You then will see the break-rewrite [prompt]: 3 ACL2 !> The leading integer is, again, the depth. Because breaks often occur recursively it is convenient always to know the level with which you are interacting. You may type arbitrary commands as in the top-level ACL2 loop. For example, you might type: 3 ACL2 !>:help or 3 ACL2 !>:pe lemma12 Exceptions are that [47m:[0m[47m[ubt][0m and related commands such as [47m:[0m[47m[ubu][0m, as well as [47m[puff][0m and [47m[puff*][0m, are only allowed to touch [command]s issued after entering the interactive break. (Technical detail: that is because [47m[disable-ubt][0m is invoked when entering the break.) More likely than typing a history command, upon entering break-rewrite you will determine the context of the attempted application. Here are some useful commands: 3 ACL2 >:target ; the term being rewritten 3 ACL2 >:unify-subst ; the unifying substitution 3 ACL2 >:path ; the stack of goals pursued by the rewriter ; starting at the top-level clause being simplified ; and ending with the current application The output of the [47m:path[0m command shows a stack of simplification and rewriting ``frames'' starting with the current top-level goal (in clausal form as a list of literals) and ending with the current target. Frames should be self-explanatory. Frames describing the attempt to apply a rewrite rule will display the name of the equivalence relation the rule uses (unless the relation is [47mequal[0m). All rewrite frames (including the attempt to apply a given rewrite rule) will display the current [geneqv] (the sense of equivalence the rewriter is obligated to maintain) unless the geneqv denotes just the [47mequal[0mity relation. At this point in the interaction the system has not yet tried to apply the [monitor]ed rule. That is, it has not tried to establish the hypotheses, considered the heuristic cost of backchaining, rewritten the right-hand side of the conclusion, etc. When you are ready for it to try the rule you can type one of several different ``proceed'' commands. The basic proceed commands are [47m:ok[0m, [47m:go[0m, and [47m:eval[0m. :ok exits break-rewrite without further interaction at the current depth. When break-rewrite exits it prints ``[47m3)[0m'' (actually, of course, the current depth!), closing the parenthesis that opened the current depth, [47m3[0m, interaction. However, between your typing the [47m:ok[0m command and the exit from depth [47m3[0m you may well see deeper break-rewrite breaks --- triggered by any of your monitored runes --- as the rewriter tries to apply the lemma that prompted the current depth [47m3[0m break. :go exits break-rewrite without further interaction at the current depth, but as it exits it prints out the result of the application attempt, i.e., whether the application succeeded, if so, what the [47m:target[0m term was rewritten to, and if not why the rule was not applicable. :eval causes break-rewrite to attempt to apply the rule but interaction at this depth of break-rewrite resumes when the attempt is complete. When control returns to this level of break-rewrite a message indicating the result of the application attempt (just as in [47m:go[0m) is printed, followed by the [prompt] for additional user input for the current depth [47m3[0m. Generally speaking, [47m:ok[0m and [47m:go[0m are used when the break in question is routine or uninteresting and [47m:eval[0m is used when the break is one that the user anticipates is causing trouble. For example, if you are trying to determine why a lemma isn't being applied to a given term and the [47m:target[0m of the current break-rewrite is the term in question, you would usually [47m:eval[0m the rule and if break-rewrite reports that the rule failed then you are in a position to determine why, for example by carefully inspecting the [47m:[0m[47m[type-alist][0m and perhaps the [linear-arithmetic] [47m:pot-list[0m of governing assumptions or why some hypothesis of the rule could not be established. It is often the case that when you are in break-rewrite you wish to change the set of [monitor]ed [rune]s. This can be done by using [47m:[0m[47m[monitor][0m and [47m:[0m[47m[unmonitor][0m as noted above. For example, you might want to [monitor] a certain rule, say [47mhyp-reliever[0m, just when it is being used while attempting to apply another rule, say [47mmain-lemma[0m. Typically then you would [monitor] [47mmain-lemma[0m at the ACL2 top-level, start the proof-attempt, and then in the break-rewrite in which [47mmain-lemma[0m is about to be tried, you would install a [monitor] on [47mhyp-reliever[0m. If you then [47m:eval[0m and get a break on [47mhyp-reliever[0m you will know it is being used under the attempt to apply [47mmain-lemma[0m. However, when the rewriter leaves this attempt to apply [47mmain-lemma[0m, [47mhyp-reliever[0m will no longer be monitored. That is, the list of monitored runes is maintained as a local variable of break-rewrite. See [47m[monitored-runes][0m. [47m:Ok![0m, [47m:go![0m, and [47m:eval![0m are just like their counterparts ([47m:ok[0m, [47m:go[0m, and [47m:eval[0m, respectively), except that before proceeding they unmonitor all runes. Of course, this is only done in the scope of the interactive break in which these commands were used. When control returns to the top-level of the ACL2 loop the monitored runes will have reverted to its original value there. These commands allow you to proceed from the current depth without getting any deeper breaks. [47m:Ok$[0m, [47m:go$[0m, and [47m:eval$[0m are similar but take an additional argument which must be a list of runic designators (or a single designator). See [rune]. Two examples the use of [47m:eval$[0m are 3 ACL2 !>:eval$ hyp-reliever and 3 ACL2 !>:eval$ (hyp-reliever (:definition foo)) The second command above is exactly equivalent to 3 ACL2 !>:monitor hyp-reliever t 3 ACL2 !>:monitor (:definition foo) t 3 ACL2 !>:eval Analogous remarks apply to [47m:go$[0m and [47m:ok$[0m. If you want to specify more sophisticated break criteria (rather than just [47m:condition t[0m) you must use the [47m:monitor[0m command explicitly before proceeding. Thus, there are nine ways to proceed from the initial entry into break-rewrite although we often speak as though there are two, [47m:ok[0m and [47m:eval[0m, and leave the others implicit. We group [47m:go[0m with [47m:ok[0m because in all their flavors they exit break-rewrite without further interaction (at the current depth). All the flavors of [47m:eval[0m require further interaction after the rule has been tried. You are not permitted to ``re-[47m:eval[0m'' a rule. That is, after issuing the [47m:eval[0m command in a given break, you cannot issue it again in that break. The rule has been evaluated, the results are available to you, and that's that! All you can do, aside from inspecting the context, is allow rewrite to continue, by issuing an [47m:ok[0m or [47m:go[0m, or abort. To abort a proof attempt and return to the top-level of ACL2 you may at any time type [47m(a!)[0m followed by a carriage return or, equivalently (if you are not in a raw Lisp break) use the keyword command [47m:a![0m. See [a!]. We now address ourselves to the post-[47m:eval[0m interaction with break-rewrite. As noted, post-[47m:eval[0m interaction begins with break-rewrite's report on the results of applying the rule: whether it worked and either what it produced or why it failed. This information is also printed by certain keyword commands available after [47m:eval[0m, namely [47m:wonp[0m, [47m:rewritten-rhs[0m or (for [linear] rules) [47m:poly-list[0m, and [47m:failure-reason[0m. In addition, by using [47m[brr@][0m you can obtain this information in the form of ACL2 data objects. This allows the development of more sophisticated ``break conditions'' that test the context of the pending break and that return a list of commands to execute if a break occurs; see [monitor] for examples. In this connection we point out the macro form [47m(ok-if term)[0m. See [ok-if]. This command exits break-rewrite if [47mterm[0m evaluates to non-[47mnil[0m and otherwise does not exit. Thus it is possible to define macros that provide other kinds of exits from break-rewrite. The only way to exit break-rewrite after [47m:eval[0m is [47m:ok[0m or [47m:go[0m or the use of [47m[ok-if][0m. Note that when inside break-rewrite, all [history] commands, such as [47m:[0m[47m[pe][0m, show the [enable]d status of rules with respect to the current point in the proof attempt. For example, if you break while the prover is working on Subgoal 3, and the [hints] supplied for the proof specify [47m("Subgoal 3" :in-theory (disable foo))[0m for some rule [47mfoo[0m, then [47m:[0m[47m[pe][0m will indicate that [47mfoo[0m is [disable]d: even though [47mfoo[0m may be enabled globally, it is shown as disabled because it is disabled during Subgoal 3. See subtopics of [history] for a list of all such history commands. In addition to those commands, the function [47m[disabledp][0m is also evaluated inside break-rewrite with respect to the current enabled state of the prover. We have not discussed ``near-miss'' breaks. These are caused when a monitored rune specifies one of the near-miss break criteria and the rune's pattern fails to match the target but ``almost'' matches according to the criteria. See [47m[monitor][0m for a discussion of near-miss break criteria. But for example, if [47mmain-lemma[0m rewrites the term [47m(f (g (h x) y) x)[0m and you've installed a monitor on it like this: :monitor main-lemma (:abstraction (f (g u v) w)) then if the rewriter encountered the target term [47m(F (G (MUMBLE A) B) C)[0m it would cause a near-miss break because the pattern of [47mmain-lemma[0m does not match the target but the specified abstraction of the pattern does match the target. You interact with a near-miss break just like the breaks described above, except some commands (e.g., [47m:eval[0m) are unavailable because the rule did not match and thus there is no way to proceed except to exit the break and try the next lemma. The rest of this [documentation] discusses a few implementation details of break-rewrite and may not be interesting to the typical user. There is no ACL2 function named break-rewrite --- which is why we don't write it in typewriter font in this documentation. Break-rewrite is an illusion created by appropriate calls to three ``break point handlers'' named [47mnear-miss-brkpt1[0m, [47mbrkpt1[0m and [47mbrkpt2[0m. As previously noted, break-rewrite is [47m[ld][0m operating on a [wormhole] [state]. One might therefore wonder how break-rewrite can apply a rule and then communicate the results back to the rewriter running in the external [state]. The answer is that it cannot. Nothing can be communicated through a [wormhole]. In fact, the break point handlers are each calls of [47m[ld][0m running on [wormhole] [state]s. They maintain a state machine inside the wormhole. For example, [47mbrkpt1[0m is called by rewrite after a successful match, if the monitored [47m:condition[0m is true, an interactive break occurs. Upon an [47m:ok[0m or [47m:eval[0m, the wormhole's status information is updated, the wormhole is exited (losing any state changes made inside the wormhole), rewrite continues to do whatever rewrite does for that lemma, and then [47mbrkpt2[0m is called. [47mBrkpt2[0m then uses the state information in the wormhole to decide whether to interact or not. This helps explain why the rewriter behaves more sluggishly when [47m(brr t)[0m has been done: it is entering and exiting wormholes to figure out whether to trigger an interactive break. When you are through with break-rewrite, we recommend [47m(brr nil)[0m. This design causes certain anomalies that might be troubling. Suppose you are inside a depth [47m3[0m break before [47m:evaling[0m a rule (i.e., you're in the [47mbrkpt1[0m [wormhole] [state]) you define some function, [47mfoo[0m. Suppose then you [47m:eval[0m the rule and eventually control returns to the depth [47m3[0m break (i.e., now you're in the [47mbrkpt2[0m [wormhole] [state] with the results of the application in it). You will discover that [47mfoo[0m is no longer defined! That is because the [wormhole] [state] created during your pre-[47m:eval[0m interaction is lost when we exit the [wormhole] to resume the proof attempt. The post-[47m:eval[0m [wormhole] [state] is in fact identical to the initial pre-[47m:eval[0m [state] (except for the results of the application) because [47m[rewrite][0m did not change the external [state] and both [wormhole] [state]s are copies of it. A similar issue occurs with the use of [trace] utilities: all effects of calling [47m[trace$][0m and [47m[untrace$][0m are erased when you proceed from a break in the break-rewrite loop. See the subtopics listed below to learn more about [47mbreak-rewrite[0m. Subtopics [Break-lemma] A quick introduction to breaking rewrite rules in ACL2 [Brr] To enable or disable the breaking of rewrite rules [Brr-commands] [Break-Rewrite] Commands [Brr-near-missp] attachable function for determining ``near misses'' [Brr@] To access context sensitive information within [47m[break-rewrite][0m [Cw-gstack] Debug a rewriting loop or stack overflow [Dmr] Dynamically monitor rewrites and other prover activity [Geneqv] the rewriter's generated equivalence relation [Monitor] To monitor attempted applications of certain rules by the rewriter [Monitor!] A quiet combination of [47m[monitor][0m and [47m[brr][0m [Monitored-runes] Print the [monitor]ed [rune]s and their break conditions [Ok-if] Conditional exit from [47mbreak-rewrite[0m [Refinement-failure] what to do when a rewrite rule fails the refinement check [Unmonitor] To stop monitoring a rule name [Why-brr] An explanation of why ACL2 has an explicit [47m[brr][0m mode [With-brr-data] Finding the source of a term in prover output") (breaks (errors) "Common Lisp breaks Example: Broken at PROVE. Type :H for Help. >>:Q ACL2 !> You may interrupt the system by typing various control character sequences. The precise sequences are determined by the host Lisp and operating system environment. For example, in GCL and Allegro Common Lisp, a console interrupt is caused by typing ``[47mctrl-c[0m''. If, however, the GCL or Allegro is running in an Emacs shell buffer, one must type ``ctrl-c ctrl-c''. If a break occurs, for example because of a bug in ACL2 or a user interrupt, the break will run a Common Lisp read-eval-print loop, not an ACL2 read-eval-print loop. This may not be obvious if the [prompt]s in the two loops are similar. Because you are typing to a Common Lisp evaluator, you must be careful. It is possible to damage your ACL2 state in irreparable ways by executing non-ACL2 Common Lisp. It is even possible to disrupt and render inaccurate the interrupted evaluation of a simple ACL2 expression. For ACL2 built on most host Common Lisps, you can expect to see a different prompt at the break than you would see in the ACL2 read-eval-print loop. See [prompt] for how to change the raw Lisp prompt to emphasize that one is in raw Lisp, and hence may wish to quit from the break. The most reliable way to return to the ACL2 top level is by executing the following command: [47m([0m[47m[abort!][0m[47m)[0m. Appropriate cleanup will then be done, which should leave you in an appropriate state. However, you may be able to quit from the break in the normal Lisp manner (as with [47m:q[0m in GCL or CCL, [47m:reset[0m in Allegro CL, and [47mq[0m in CMU CL). If this attempt to quit is successful, it will return you to the innermost ACL2 read-eval-print loop, with appropriate cleanup performed first. Note that if you are within a [47m[brr][0m environment when the break occurs, quitting from the break will only return you to that environment, not to the top of ACL2's read-eval-print loop.") (broken-link (documentation) "Placeholder for link to documentation that resides in the community books You may have attempted to access information about the ACL2 [community-books] while looking at the ACL2 User's Manual, which contains [documentation] only about the ACL2 [3msystem[0m, and does not include documentation from the [community-books]. Please point your browser at the {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html} (or if browsing in [ACL2-Doc], switch to that manual with meta-0 I) to access the desired topic. If you want information about the book where your missing topic is defined, see [broken-link-table]. Subtopics [Broken-link-table] Map [documentation] topics to the community books that define them") (broken-link-table (broken-link) "Map [documentation] topics to the community books that define them The table below maps topics to book locations that reside only in the ACL2+Books combined manual, not the ACL2 User's Manual. For example, the entry (b* "[books]/std/util/bstar.lisp") signifies that the topic [47mB*[0m is documented in the community book [47mstd/util/bstar.lisp[0m. ((*acl2-system-exports* "[books]/system/acl2-system-exports.lisp") (<< "[books]/misc/total-order.lisp") (acl2s::acl2s-installation "[books]/acl2s/installation.lisp") (add-io-pairs "[books]/std/util/add-io-pairs.lisp") (algebra "[books]/doc/more-topics.lisp") (append-without-guard "[books]/std/lists/flatten.lisp") (oslib::argv "[books]/oslib/argv-logic.lisp") (arith-equivs "[books]/std/basic/arith-equiv-defs.lisp") (arithmetic "[books]/doc/more-topics.lisp") (arithmetic-1 "[books]/arithmetic/top.lisp") (arithmetic/natp-posp "[books]/arithmetic/natp-posp.lisp") (arity+ "[books]/std/system/arity-plus.lisp") (assert! "[books]/std/testing/assert-bang.lisp") (assert!-stobj "[books]/std/testing/assert-bang-stobj.lisp") (b* "[books]/std/util/bstar.lisp") (bit-vectors "[books]/doc/more-topics.lisp") (bridge "[books]/centaur/bridge/top.lisp") (oslib::catpath "[books]/oslib/catpath.lisp") (build::cert.pl "[books]/build/doc.lisp") (build::cert_param "[books]/build/doc.lisp") (cgen "[books]/acl2s/cgen/top.lisp") (checkpoint-list "[books]/kestrel/utilities/checkpoints-doc.lisp") (community "[books]/doc/more-topics.lisp") (consideration "[books]/hints/consider-hint.lisp") (build::custom-certify-book-commands "[books]/build/doc.lisp") (std::defaggregate "[books]/std/util/defaggregate.lisp") (defconsts "[books]/std/util/defconsts.lisp") (defdata "[books]/acl2s/defdata/top.lisp") (define "[books]/std/util/define.lisp") (defmac "[books]/misc/defmac.lisp") (defmacroq "[books]/kestrel/utilities/defmacroq.lisp") (fty::defprod "[books]/centaur/fty/top.lisp") (defpun "[books]/misc/defpun.lisp") (defthm<w "[books]/kestrel/utilities/auto-instance.lisp") (defthmg "[books]/tools/defthmg.lisp") (acl2s::defunc "[books]/acl2s/defunc.lisp") (defxdoc "[books]/xdoc/topics.lisp") (getopt-demo::demo2 "[books]/centaur/getopt/demo2.lisp") (developers-guide "[books]/system/doc/developers-guide.lisp") (developers-guide-utilities "[books]/system/doc/developers-guide.lisp") (do-not-hint "[books]/tools/do-not.lisp") (easy-simplify-term "[books]/tools/easy-simplify.lisp") (er-soft+ "[books]/kestrel/utilities/er-soft-plus.lisp") (final-cdr "[books]/std/lists/final-cdr.lisp") (fty "[books]/centaur/fty/top.lisp") (getopt "[books]/centaur/getopt/top.lisp") (gl "[books]/centaur/gl/doc.lisp") (hacker "[books]/hacking/hacking-xdoc.lisp") (ihs "[books]/ihs/ihs-doc-topic.lisp") (include-raw "[books]/tools/include-raw.lisp") (install-not-normalized "[books]/misc/install-not-normalized.lisp") (list-equiv "[books]/std/lists/equiv.lisp") (list-fix "[books]/std/lists/list-fix.lisp") (logbitp-reasoning "[books]/centaur/bitops/equal-by-logbitp.lisp") (make-flag "[books]/tools/flag.lisp") (make-termination-theorem "[books]/kestrel/utilities/make-termination-theorem.lisp") (xdoc::markup "[books]/xdoc/topics.lisp") (memoized-prover-fns "[books]/tools/memoize-prover-fns.lisp") (must-fail "[books]/std/testing/must-fail.lisp") (str::nat-to-dec-string "[books]/std/strings/decimal.lisp") (non-parallel-book "[books]/std/system/non-parallel-book.lisp") (note-6-4-books "[books]/doc/relnotes.lisp") (note-6-5-books "[books]/doc/relnotes.lisp") (note-7-0-books "[books]/doc/relnotes.lisp") (note-7-1-books "[books]/doc/relnotes.lisp") (note-7-2-books "[books]/doc/relnotes.lisp") (note-8-0-books "[books]/doc/relnotes.lisp") (note-8-1-books "[books]/doc/relnotes.lisp") (note-8-2-books "[books]/doc/relnotes.lisp") (note-8-3-books "[books]/doc/relnotes.lisp") (note-8-4-books "[books]/doc/relnotes.lisp") (note-8-5-books "[books]/doc/relnotes.lisp") (note-8-6-books "[books]/doc/relnotes.lisp") (str::numbers "[books]/std/strings/top.lisp") (open-trace-file! "[books]/tools/open-trace-file-bang.lisp") (oracle-timelimit "[books]/tools/oracle-timelimit.lisp") (oslib "[books]/oslib/top-logic.lisp") (patbind-the "[books]/std/util/bstar.lisp") (build::pre-certify-book-commands "[books]/build/doc.lisp") (xdoc::preprocessor "[books]/xdoc/topics.lisp") (str::pretty "[books]/std/strings/pretty.lisp") (str::pretty-printing "[books]/std/strings/pretty.lisp") (profile-acl2 "[books]/centaur/memoize/old/profile.lisp") (profile-all "[books]/centaur/memoize/old/profile.lisp") (prove$ "[books]/tools/prove-dollar.lisp") (quicklisp "[books]/quicklisp/top.lisp") (release-notes-books "[books]/doc/relnotes.lisp") (removable-runes "[books]/tools/removable-runes.lisp") (remove-hyps "[books]/tools/remove-hyps.lisp") (rewrite$ "[books]/tools/rewrite-dollar.lisp") (rewrite-equiv-hint "[books]/coi/util/rewrite-equiv.lisp") (rtl "[books]/rtl/rel11/lib/doc.lisp") (run-script "[books]/tools/run-script.lisp") (satlink::sat-solver-options "[books]/centaur/satlink/top.lisp") (satlink "[books]/centaur/satlink/top.lisp") (xdoc::save "[books]/xdoc/topics.lisp") (xdoc::save-rendered "[books]/xdoc/topics.lisp") (xdoc::save-rendered-event "[books]/xdoc/topics.lisp") (set-max-mem "[books]/centaur/misc/memory-mgmt-logic.lisp") (spacewalk "[books]/centaur/misc/spacewalk.lisp") (std "[books]/std/top.lisp") (std/io "[books]/std/io/top.lisp") (std/strings "[books]/std/strings/top.lisp") (std/util "[books]/std/util/top.lisp") (std::strict-list-recognizers "[books]/std/util/deflist-base.lisp") (subseq-list "[books]/std/lists/subseq.lisp") (xdoc::terminal "[books]/xdoc/topics.lisp") (trans-eval-error-triple "[books]/kestrel/utilities/trans-eval-error-triple.lisp") (trans-eval-state "[books]/kestrel/utilities/trans-eval-error-triple.lisp") (unsound-read "[books]/std/io/unsound-read.lisp") (untranslate-patterns "[books]/misc/untranslate-patterns.lisp") (use-trivial-ancestors-check "[books]/tools/trivial-ancestors-check.lisp") (build::using-extended-acl2-images "[books]/build/doc.lisp") (with-raw-mode "[books]/hacking/hacking-xdoc.lisp") (with-redef-allowed "[books]/hacking/hacking-xdoc.lisp") (with-timeout "[books]/acl2s/cgen/with-timeout.lisp") (without-subsumption "[books]/tools/without-subsumption.lisp") (working-with-packages "[books]/doc/practices.lisp") (write-list "[books]/misc/file-io-doc.lisp") (xdoc "[books]/xdoc/topics.lisp"))") (brr (break-rewrite) "To enable or disable the breaking of rewrite rules Example: :brr t ; enable (brr t) ; enable (same as above) (brr t t) ; enable with less output (rarely invoked interactively) :brr nil ; disable General Form: (brr flg &optional quietp) where [47mflg[0m and the optional [47mquietp[0m argument evaluate to [47mt[0m or [47mnil[0m. This function modifies [47m[state][0m so that the attempted application of certain rewrite rules are ``broken.'' ``[47mBrr[0m'' stands for ``break-rewrite'' and can be thought of as a mode with two settings. The normal mode is ``disabled.'' For a more thorough introduction to the break rewrite system see [break-rewrite]. For a related proof debugging utility see [with-brr-data]. When [47mbrr[0m mode is ``enabled'' the ACL2 rewriter monitors the attempts to apply certain rules and advises the user of those attempts by entering an interactive wormhole break. From within this break the user can watch selected application attempts. The user can also interact with the system during [47mbrr[0m breaks via [47m[brr-commands][0m. The rules monitored are selected by using the [47m[monitor][0m and [47m[unmonitor][0m commands. It is possible to break a rune ``conditionally'' in the sense that an interactive break will occur only if a specified predicate is true of the environment at the time of the attempted application. See [monitor] and see [unmonitor]. Even if a non-empty set of rules has been selected, no breaks will occur unless [47mbrr[0m mode is enabled. Thus, the first time in a session that you wish to monitor a rewrite rule, use [47m:brr[0m [47mt[0m to enable [47mbrr[0m mode. Thereafter you may select runes to be monitored with [47m[monitor][0m and [47m[unmonitor][0m with the effect that whenever monitored rules are tried (and their break conditions are met) an interactive break will occur. Be advised that when [47mbrr[0m mode is enabled the rewriter is somewhat slower than normal. Furthermore, that sluggishness persists even if no runes are monitored. You may regain normal performance --- regardless of what runes are monitored --- by disabling [47mbrr[0m mode with [47m:brr[0m [47mnil[0m. Why isn't [47mbrr[0m mode disabled automatically when no runes are monitored? More generally, why does ACL2 have [47mbrr[0m mode at all? Why not just test whether there are monitored runes? If you care about the answers, see [why-brr]. BRR Mode, Console Interrupts, and Subsidiary Prover Calls: If the system is operating in [47mbrr[0m mode and you break into raw Lisp (as by causing a console interrupt or happening upon a signaled Lisp error; see [breaks]), you can return to the ACL2 top-level, outside any break-rewrite environment, by executing [47m([0m[47m[abort!][0m[47m)[0m. Otherwise, the normal way to quit from such a raw Lisp break (for example [47m:q[0m in GCL, [47m:reset[0m in Allegro CL, and [47mq[0m in CMU CL) will return to the innermost ACL2 read-eval-print loop, which may or may not be the top-level of your ACL2 session! In particular, if the interrupt or error break happens to occur while ACL2 is within a break-rewrite break (in which it is preparing to read [47m[brr-commands][0m), the abort will merely return to break-rewrite break. Upon exiting that environment, normal theorem proving is continued (and the break-rewrite breaks may be entered again in response to subsequent monitored rule applications). In addition, if while in a break-rewrite break, say at depth [47md[0m, you invoke the theorem prover recursively as by typing a [47m[thm][0m or [47m[defthm][0m or [47m[defun][0m command to break-rewrite, recursive breaks may occur with depths starting at [47md+1[0m. This can get confusing because it may appear that the ongoing (sub-)proofs are part of the original proof when in fact the system is just carrying out your commands. Subtopics [Brr-evisc-tuple] Determines partial suppression of output from [brr-commands] [Set-brr-evisc-tuple] Set the [47m[brr-evisc-tuple][0m") (brr-commands (break-rewrite) "[Break-Rewrite] Commands Below is a list of commonly used [break-rewrite] keyword commands. These are only defined within the breaks caused by [47m[monitor][0ms on runes in the process of being considered by the ACL2 rewriter. These breaks interact with you from within a [47m[wormhole][0m and are handled by [47m[ld][0m (the same function that manages ACL2's top-level interactive read-eval-print loop). So within certain limitations imposed by wormholes, you can evaluate any command you would at the top-level of ACL2 in addition to the special commands below. Many break commands display terms, e.g., the target being rewritten, and ``large'' terms are ``eviscerated'' (i.e., abbreviated) before printing. These commands have corresponding commands suffixed with a ``+'' that avoid evisceration so that the terms in question are printed in full. See [brr-evisc-tuple]. The notation ``[47m:ancestors[+][0m'' below indicates that the [47m:ancestors[0m command may print abbreviate terms but the [47m:ancestors+[0m command does not. :a! abort to ACL2 top-level :ancestors[+] negations of backchaining hypotheses being pursued :btm[+] bottom-most frame in :path :eval try the rule (i.e., recursively try to relieve the hypotheses and other conditions, possibly producing other breaks) and return to this break afterwards so you can query results :eval! :eval but remove all monitors first (see below) :eval$ runes :eval but first add monitors for runes (see below) :explain-near-miss[+] print an explanation of why the rule's pattern failed to match the :target; only relevant in a break caused by a near miss :failure-reason[+] reason rule failed (after :eval) :final-ttree[+] ttree after :eval (see :DOC ttree) :frame[+] i ith frame in :path :geneqv[+] generated equivalence relation to be maintained :go :eval but don't return to this break, just print the result of the try :go! :go but first remove all monitors (see below) :go$ runes :go but first add monitors for runes (see below) :help this message :hyp i ith hypothesis of the rule :hyps hypotheses of the rule :initial-ttree[+] ttree before :eval (see :DOC ttree) :lhs[+] left-hand side of rule's conclusion (or, in the case of :rewrite-quoted-constant rules of form [2], the right-hand side!); this is the pattern that the target must match for this :rewrite rule to fire :max-term[+] maximal term of a :linear lemma; this is the pattern that the target must match for this :linear rule to fire :ok like :go, but don't print the result of the try :ok! :ok but first remove all monitors (see below) :ok$ runes :ok but first add monitors for runes (see below) :path[+] rewriter's path from top clause to :target :poly-list[+] list of polynomials (after :eval) of a linear rule, where the leading term of each is enclosed in an extra set of parentheses :pot-list[+] set of polynomials governing :target, organized by maximal term :rewritten-rhs[+] rewritten :rhs (after :eval) of a rewrite rule :rhs right-hand side of rule's conclusion (or, in the case of :rewrite-quoted-constant rules of form [2], the left-hand side!) :standard-help :help message from ACL2 top-level :target[+] term being rewritten :top[+] top-most frame in :path :type-alist[+] type assumptions governing :target :unify-subst[+] substitution making :lhs equal :target :wonp indicates whether application succeeded (after :eval) The form [47m([0m[47m[brr@][0m[47m :cmd)[0m, when evaluated within a break, will return the value that is only printed by certain of the keyword commands above. This is particularly useful when programming break conditions. See [47m[monitor][0m. Since you're actually in a general read-eval-print loop when interacting with [break-rewrite] you may type the usual ACL2 commands like [47m:[0m[47m[pbt][0m or [47m:[0m[47m[pe][0m or even [47m[defun][0m and [47m[defthm][0m. You cannot modify [stobj]s or files from within the break. However, all [state] changes you cause from within [break-rewrite] are lost when you exit or [47m:eval[0m the rule. Note that if you are breaking on a [monitor]ed [linear] rule, several of the commands listed above do not apply: [47m:lhs[0m, [47m:rhs[0m, [47m:initial-ttree[0m, and [47m:final-ttree[0m. The pattern used to fire a linear rule is found with the command [47m:max-term[0m. In addition, [47m:rewritten-rhs[0m also does not apply to linear rules, but instead, [47m:poly-list[0m shows the result of applying the linear lemma as a list of polynomials, implicitly conjoined. The leading term of each polynomial is enclosed in an extra set of parentheses. See the discussion of form [2] [47m:[0m[47m[rewrite-quoted-constant][0m rules for an explanation of the swapped meanings of ``[47m:lhs[0m'' and ``[47m:rhs[0m.'' The commands [47m:eval$[0m, [47m:go$[0m, and [47m:ok$[0m take an argument, called runes, which may be a list of runes and/or runic designators (see [rune]) or a single rune or runic designator. For each rune in runes, these commands execute [47m:[0m[47m[monitor][0m rune [47mt[0m, and then execute [47m:eval[0m, [47m:go[0m or [47m:ok[0m as appropriate. This is useful if you want to monitor the use of a ``secondary'' rune only during the attempt to apply a ``primary'' rune: install the monitor on the secondary rune inside the break caused by the primary rune. In the case of [47m:eval$[0m, when the attempt to apply the primary rune is finished you will be back in the interactive break and can inspect the results. You will notice that the secondary rune is still on the list of [47m[monitored-runes][0m. However, when you exit that break [47mmonitored-runes[0m will be restored to its earlier value. In the case of [47mgo$[0m and [47mok$[0m, no interactive break occurs after the primary rune has been applied. Similar remarks apply to [47m:eval![0m, [47m:go![0m, and [47m:ok![0m except they first [47m:[0m[47m[unmonitor][0m [47m:all[0m, before proceeding with the appropriate [47m:eval[0m, [47m:go[0m, or [47m:ok[0m. These commands are useful if you want no breaks to occur while attempting to apply the rune that caused the current break. Recall (from the discussion of [47m[monitor][0ms) that break conditions terms installed as part of break criteria do not just determine whether a break occurs but can compute the initial break commands fed to the interactive loop. Thus, for example, you can install a monitor that causes the rewriter to not only break when a certain rune is used, but then automatically print information, proceed from the break, inspect the result, and then either exit the break or prompt for user input. See the discussion in [47m[monitor][0m. Note: If you use commands that change the monitored runes during a break, e.g., [47m[monitor][0m, [47m[unmonitor][0m, or [47m:eval![0m, [47m:eval$[0m, etc., then abort during the recursion, the list of monitored runes will not necessarily be restored to its original top-level setting.") (brr-evisc-tuple (brr evisc-tuple) "Determines partial suppression of output from [brr-commands] See [evisc-tuple] for relevant background on ``evisceration'': eliding of subexpressions during printing. Also see [break-rewrite] for background on the break-rewrite loop. General Form: (brr-evisc-tuple state) The value of this function is used as the evisceration tuple by [brr-commands]. The value can be changed with [47m[set-brr-evisc-tuple][0m or the more general [47m[set-evisc-tuple][0m. A special value, [47m:default[0m, is legal for this evisc-tuple, and is its initial value. In that case the actual evisc-tuple used during output from [brr-commands] --- which we call the [3meffective value[0m of the [47mbrr-evisc-tuple[0m --- is the value of the evisc-tuple for terms. See [set-evisc-tuple], in particular, the discussion of the [47m:term[0m site for setting evisc-tuples. Think of [47mbrr-evisc-tuple[0m as a true global variable, not a locally bound variable of break-rewrite. In particular, if you set the [47mbrr-evisc-tuple[0m inside a break-rewrite interactive break and eventually exit that break --- either to enter a deeper break or return to a shallower break or to the ACL2 top-level --- the [47mbrr-evisc-tuple[0m will retain its chronologically most recent setting. The [47mbrr-evisc-tuple[0m is used when [break-rewrite] prints its banner opening or closing a break on some monitored rune and when certain [brr-commands] print their results. When you're in a break-rewrite break, you're actually dealing with the read-eval-print loop managed by [47m[ld][0m. It prints its results using the [47m[ld-evisc-tuple][0m, while [47m[brr-commands][0m use [47mbrr-evisc-tuple[0m. This can cause some confusion. For example, suppose you have set the [47mbrr-evisc-tuple[0m to [47m(evisc-tuple 2 3 nil nil)[0m so break-rewrite banners and brr-commands only print to depth 2 and length 3. Suppose the target term is [47m(F (G (H 1)) 2 3 4 5 6 7)[0m. Then the following interaction with break-rewrite could occur: 3 ACL2 >:target (F (G #) 2 ...) 3 ACL2 >(make-list 10) (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL) You might ask ``Given that the [47mbrr-evisc-tuple[0m limits the print length to [47m3[0m, which I see when I print [47m:target[0m, how come the [47mmake-list[0m showed all 10 elements?'' The answer is that the [47mbrr-command[0m [47m:target[0m actually printed the target with the [47mbrr-evisc-tuple[0m and returned [47m(value :invisible)[0m which [47mld[0m's read-eval-print loop doesn't print. But the [47mmake-list[0m returned a list of length ten and the read-eval-print loop printed it using the [47m[ld-evisc-tuple][0m. Another issue relating [47mbrr-evisc-tuple[0m and [47mld-evisc-tuple[0m is that while [47mbrr-evisc-tuple[0m is a true global, retaining its chronologically most recently set value at all depths of break-rewrite, [47mld-evisc-tuple[0m is locally bound by break-rewrite (actually, by the [47mld[0m in [47mwormhole[0m) and so sees its value restored as break-rewrite ascends back toward the top-level of ACL2. Subtopics [Set-brr-evisc-tuple] Set the [47m[brr-evisc-tuple][0m") (brr-near-missp (break-rewrite) "attachable function for determining ``near misses'' This is a system function that determine whether a failed match of a monitored rule constitutes a near miss. [31;1mNote:[0mThis function is attachable (see [defattach]). General Form: (brr-near-missp msgp lemma target rcnst criteria-alist) where msgp is [47mt[0m or [47mnil[0m, [47mlemma[0m is the ACL2 record representing a [47m[monitor][0med [47m:rewrite[0m rule or [47m:linear[0m rule, [47mtarget[0m is a term to which the rewriter tried to apply the rule but failed to match the pattern in the lemma, [47mrcnst[0m is the rewrite constant at the time of the attempt, and [47mcriteria-alist[0m is a symbol-alist associated with the rule in [47m[monitored-runes][0m. The function determines whether the pattern of the lemma ``almost'' matches the target, i.e., whether a ``near miss'' has occurred. The function is only called if the exact match failed. The built-in version of this function checks the criteria described in [47m[monitor][0m. If a near miss has occurred, the result is either [47mt[0m or a message (see [47m[msg][0m) object describing the near miss. If a near miss did not occur, the result is [47mnil[0m. See the source code for [47mbuilt-in-brr-near-missp[0m for details of how the built-in version of this function operates.") (brr@ (break-rewrite) "To access context sensitive information within [47m[break-rewrite][0m Example: (brr@ :target) ; the term being rewritten (brr@ :unify-subst) ; the unifying substitution General Form: (brr@ :symbol) where [47m:symbol[0m is one of the keywords displayed below. This utility may be most useful for system hackers; see [brr-commands] for queries that are more at a user level. In particular, keywords marked below with [47m*[0m probably require an implementor's knowledge of the system to use effectively. They are supported but not well documented. More is said on this topic following the table. For background on the notion of ``translated'' term, see [term]. :symbol (brr@ :symbol) ------- --------------------- :target the term to be rewritten. This term is an instantiation of the left-hand side of the conclusion of the rewrite-rule being broken. This term is in translated form! Thus, if you are expecting (equal x nil) -- and your expectation is almost right -- you will see (equal x 'nil); similarly, instead of (cadr a) you will see (car (cdr a)). In translated forms, all constants are quoted (even nil, t, strings and numbers) and all macros are expanded. :unify-subst the substitution that, when applied to :target, produces the left-hand side of the rule being broken. This substitution is an alist pairing variable symbols to translated (!) terms. :wonp t or nil indicating whether the rune was successfully applied. (brr@ :wonp) returns nil if evaluated before :EVALing the rule. :rewritten-rhs the result of successfully applying the rewrite rule or else nil if (brr@ :wonp) is nil. The result of successfully applying the rule is always a translated (!) term and is never nil. :poly-list the result of successfully applying the linear rule or else nil if (brr@ :wonp) is nil. This result represents the list of polynomials produced by the rule application. The leading term of each polynomial is enclosed in an extra set of parentheses. :pot-list * the pot-list, which is the set of polynomials that are assumed in the current context, organized by maximal term. Each polynomial in the list is a linear-pot record. :failure-reason some non-nil lisp object indicating why the rule was not applied or else nil. Before the rule is :EVALed, (brr@ :failure-reason) is nil. After :EVALing the rule, (brr@ :failure-reason) is nil if (brr@ :wonp) is t. Rather than document the various non-nil objects returned as the failure reason, we encourage you simply to evaluate (brr@ :failure-reason) in the contexts of interest. Alternatively, study the ACL2 function tilde-@- failure-reason-phrase. :lemma * the rewrite rule being broken. For example, (access rewrite-rule (brr@ :lemma) :lhs) will return the left-hand side of the conclusion of the rule. :type-alist * a display of the type-alist governing :target. Elements on the displayed list are of the form (term type), where term is a term and type describes information about term assumed to hold in the current context. (See also the documentation for type-alist.) The type-alist may be used to determine the current assumptions, e.g., whether A is a CONSP. :geneqv * the generated equivalence relation that specifies what equivalence relations may be used to rewrite the target. (See the documentation for geneqv and refinement-failure.) :ancestors * a stack of frames indicating the backchain history of the current context. The theorem prover is in the process of trying to establish each hypothesis in this stack. Thus, the negation of each hypothesis can be assumed false. Each frame also records the rules on behalf of which this backchaining is being done and the weight (function symbol count) of the hypothesis. All three items are involved in the heuristic for preventing infinite backchaining. Exception: Some frames are ``binding hypotheses'' (equal var term) or (equiv var (double-rewrite term)) that bind variable var to the result of rewriting term. The ACL2 source code has a definition (defrec ancestor ...) that may provide some relevant insight. :initial-ttree * the initial and (after :EVAL) final tag trees, :final-ttree respectively. (Tag trees are low-level data structures that store lemmas used and other information, as documented in topic TTREE.) :gstack * the current goal stack. The gstack is maintained by rewrite and is the data structure printed as the current ``path.'' Thus, any information derivable from the :path brr command is derivable from gstack. For example, from gstack one might determine that the current term is the second hypothesis of a certain rewrite rule. In general [47mbrr@-expressions[0m are used in break conditions, the expressions that determine whether interactive breaks occur when [monitor]ed [rune]s are applied. See [monitor]. For example, you might want to break only those attempts in which one particular term is being rewritten or only those attempts in which the binding for the variable [47ma[0m is known to be a [47m[consp][0m. Such conditions can be expressed using ACL2 system functions and the information provided by [47mbrr@[0m. Unfortunately, digging some of this information out of the internal data structures may be awkward or may, at least, require intimate knowledge of the system functions. But since conditional expressions may employ arbitrary functions and macros, we anticipate that a set of convenient primitives will gradually evolve within the ACL2 community. It is to encourage this evolution that [47mbrr@[0m provides access to the [47m*[0m'd data.") (built-in-clause (rule-classes) "To build a [clause] into the simplifier See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Example: (defthm acl2-count-abl (and (implies (and (true-listp x) (not (equal x nil))) (< (acl2-count (abl x)) (acl2-count x))) (implies (and (true-listp x) (not (equal nil x))) (< (acl2-count (abl x)) (acl2-count x)))) :rule-classes :built-in-clause) A [47m:built-in-clause[0m rule can be built from any formula other than propositional tautologies. Roughly speaking, the system uses the list of built-in [clause]s as the first method of proof when attacking a new goal. Any goal that is subsumed by a built in clause is proved ``silently.'' ACL2 maintains a set of ``built-in'' clauses that are used to short-circuit certain theorem proving tasks. We discuss this at length below. When a theorem is given the rule class [47m:built-in-clause[0m ACL2 flattens the [47m[implies][0m and [47m[and][0m structure of the [47m:[0m[47m[corollary][0m formula so as to obtain a set of formulas whose conjunction is equivalent to the given corollary. It then converts each of these to clausal form and adds each clause to the set of built-in clauses. The example above (regardless of the definition of [47mabl[0m) will build in two clauses, {(not (true-listp x)) (equal x nil) (< (acl2-count (abl x)) (acl2-count x))} and {(not (true-listp x)) (equal nil x) (< (acl2-count (abl x)) (acl2-count x))}. We now give more background. Recall that a clause is a set of terms, implicitly representing the disjunction of the terms. Clause [47mc1[0m is ``subsumed'' by clause [47mc2[0m if some instance of [47mc2[0m is a subset [47mc1[0m. For example, let [47mc1[0m be {(not (consp l)) (equal a (car l)) (< (acl2-count (cdr l)) (acl2-count l))}. Then [47mc1[0m is subsumed by [47mc2[0m, shown below, {(not (consp x)) ; second term omitted here (< (acl2-count (cdr x)) (acl2-count x))} because we can instantiate [47mx[0m in [47mc2[0m with [47ml[0m to obtain a subset of [47mc1[0m. Observe that [47mc1[0m is the clausal form of (implies (and (consp l) (not (equal a (car l)))) (< (acl2-count (cdr l)) (acl2-count l))), [47mc2[0m is the clausal form of (implies (consp l) (< (acl2-count (cdr l)) (acl2-count l))) and the subsumption property just means that [47mc1[0m follows trivially from [47mc2[0m by instantiation. The set of built-in clauses is just a set of known theorems in clausal form. Any formula that is subsumed by a built-in clause is thus a theorem. If the set of built-in theorems is reasonably small, this little theorem prover is fast. ACL2 uses the ``built-in clause check'' in four places: (1) at the top of the iteration in the prover --- thus if a built-in clause is generated as a subgoal it will be recognized when that goal is considered, (2) within the simplifier so that no built-in clause is ever generated by simplification, (3) as a filter on the clauses generated to prove the termination of recursively [47m[defun][0m'd functions and (4) as a filter on the clauses generated to verify the guards of a function. The latter two uses are the ones that most often motivate an extension to the set of built-in clauses. Frequently a given formalization problem requires the definition of many functions which require virtually identical termination and/or guard proofs. These proofs can be short-circuited by extending the set of built-in clauses to contain the most general forms of the clauses generated by the definitional schemes in use. The attentive user might have noticed that there are some recursive schemes, e.g., recursion by [47m[cdr][0m after testing [47m[consp][0m, that ACL2 just seems to ``know'' are ok, while for others it generates measure clauses to prove. Actually, it always generates measure clauses but then filters out any that pass the built-in clause check. When ACL2 is initialized, the clause justifying [47m[cdr][0m recursion after a [47m[consp][0m test is added to the set of built-in clauses. (That clause is [47mc2[0m above.) Note that only a subsumption check is made; no rewriting or simplification is done. Thus, if we want the system to ``know'' that [47m[cdr][0m recursion is ok after a negative [47m[atom][0m test (which, by the definition of [47m[atom][0m, is the same as a [47m[consp][0m test), we have to build in a second clause. The subsumption algorithm does not ``know'' about commutative functions. Thus, for predictability, we have built in commuted versions of each clause involving commutative functions. For example, we build in both {(not (integerp x)) (< 0 x) (= x 0) (< (acl2-count (+ -1 x)) (acl2-count x))} and the commuted version {(not (integerp x)) (< 0 x) (= 0 x) (< (acl2-count (+ -1 x)) (acl2-count x))} so that the user need not worry whether to write [47m(= x 0)[0m or [47m(= 0 x)[0m in definitions. [47m:built-in-clause[0m rules added by the user can be enabled and disabled.") (butlast (lists acl2-built-ins) "All but a final segment of a list [47m(Butlast l n)[0m is the list obtained by removing the last [47mn[0m elements from the true list [47ml[0m. The following are theorems. (implies (and (integerp n) (<= 0 n) (true-listp l)) (equal (length (butlast l n)) (if (< n (length l)) (- (length l) n) 0))) (equal (len (butlast l n)) (nfix (- (len l) (nfix n))))) For related functions, see [take] and see [nthcdr]. The [guard] for [47m(butlast l n)[0m requires that [47mn[0m is a nonnegative integer and [47mlst[0m is a true list. [47mButlast[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note: In Common Lisp the second argument of [47mbutlast[0m is optional, but in ACL2 it is required. [31;1mFunction: [0m<butlast> (defun butlast (lst n) (declare (xargs :guard (and (true-listp lst) (integerp n) (<= 0 n)))) (let ((lng (len lst)) (n (nfix n))) (if (<= lng n) nil (take (- lng n) lst))))") (by (pointers) "See [hints] for information about the keyword [47m:by[0m.") (caaaar (conses acl2-built-ins) "[47m[car][0m of the [47m[caaar][0m See any Common Lisp documentation for details.") (caaadr (conses acl2-built-ins) "[47m[car][0m of the [47m[caadr][0m See any Common Lisp documentation for details.") (caaar (conses acl2-built-ins) "[47m[car][0m of the [47m[caar][0m See any Common Lisp documentation for details.") (caadar (conses acl2-built-ins) "[47m[car][0m of the [47m[cadar][0m See any Common Lisp documentation for details.") (caaddr (conses acl2-built-ins) "[47m[car][0m of the [47m[caddr][0m See any Common Lisp documentation for details.") (caadr (conses acl2-built-ins) "[47m[car][0m of the [47m[cadr][0m See any Common Lisp documentation for details.") (caar (conses acl2-built-ins) "[47m[car][0m of the [47m[car][0m See any Common Lisp documentation for details.") (cadaar (conses acl2-built-ins) "[47m[car][0m of the [47m[cdaar][0m See any Common Lisp documentation for details.") (cadadr (conses acl2-built-ins) "[47m[car][0m of the [47m[cdadr][0m See any Common Lisp documentation for details.") (cadar (conses acl2-built-ins) "[47m[car][0m of the [47m[cdar][0m See any Common Lisp documentation for details.") (caddar (conses acl2-built-ins) "[47m[car][0m of the [47m[cddar][0m See any Common Lisp documentation for details.") (cadddr (conses acl2-built-ins) "[47m[car][0m of the [47m[cdddr][0m See any Common Lisp documentation for details.") (caddr (conses acl2-built-ins) "[47m[car][0m of the [47m[cddr][0m See any Common Lisp documentation for details.") (cadr (conses acl2-built-ins) "[47m[car][0m of the [47m[cdr][0m See any Common Lisp documentation for details.") (calling-ld-in-bad-contexts (ld) "Errors caused by calling [47m[ld][0m in inappropriate contexts The macro [47m[ld][0m was designed to be called directly in the top-level ACL2 loop, although there may be a few occasions for calling it from functions. ACL2 cannot cope with invocations of [47m[ld][0m during the process of loading a compiled file for a book, so that is an error. Specifically: ACL2 will cause an error in the following two circumstances: * when calling [47m[ld][0m inside [47m[progn!][0m unless state global [47mld-okp[0m is first set to [47mt[0m, e.g., using [47m(assign ld-okp t)[0m; also, * when calling [47mld[0m while inside raw Lisp, e.g., when loading a compiled file during an invocation of [47m[include-book][0m. Consider for example the following book, where file [47mconst.lsp[0m contains the single form [47m(defconst *foo* '(a b))[0m after its initial [47m[in-package][0m form. (in-package "ACL2") (defttag t) (progn! (ld "const.lsp")) An attempt to certify this book as follows (certify-book "const-wrapper" 0 t :ttags :all) will cause an error: ACL2 Error in LD: It is illegal to call LD in this context. See :DOC calling-ld-in-bad-contexts. However, that error can be avoided by expanding the [47m[progn!][0m call as follows. (progn! (assign ld-okp t) (ld "const.lsp")) Now certification succeeds; however, any subsequent call of [47m[include-book][0m will fail to load the compiled file for the book. Again, that is necessary because of how ACL2 is designed; in this case, the [47m[ld][0m call would interfere with tracking of constant definitions when loading the compiled file for the book. To avoid warnings about loading compiled files, either certify the book without creating a compiled file or else include the book without loading the compiled file; see [certify-book] and [include-book]. Note that it is legal to put a definition such as the following into a book, where [47mld[0m is called in the body of a function; the two conditions above do not prohibit this. (defun foo (state) (declare (xargs :guard t :stobjs state :mode :program)) (ld '((defun h (x) x)) :ld-user-stobjs-modified-warning t)) One can then include the book, evaluate [47m(foo state)[0m, and then evaluate calls of [47mh[0m.") (canonical-pathname (programming-with-state acl2-built-ins) "The true absolute filename, with soft links resolved For the name [47mfname[0m of a file, the form [47m(canonical-pathname fname nil state)[0m evaluates to a Unix-style absolute filename representing the same file as [47mfname[0m, but generally without any use of soft links in the name. (Below, we explain the qualifier ``generally''.) If however the file indicated by [47mfname[0m does not exist, [47m(canonical-pathname fname nil state)[0m is [47mnil[0m. Thus, [47mcanonical-pathname[0m can be used as one would use the raw Lisp function [47mprobe-file[0m. The specification of [47m(canonical-pathname fname dir-p state)[0m when [47mdir-p[0m is not [47mnil[0m is similar, except that if the specified file exists but is not a directory, then the result is [47mnil[0m. The function [47mcanonical-pathname[0m has a guard of [47mt[0m, though the second argument must be the ACL2 [47m[state][0m. This function is introduced with the following properties. (defthm canonical-pathname-is-idempotent (equal (canonical-pathname (canonical-pathname x dir-p state) dir-p state) (canonical-pathname x dir-p state))) (defthm canonical-pathname-type (or (equal (canonical-pathname x dir-p state) nil) (stringp (canonical-pathname x dir-p state))) :rule-classes :type-prescription) We use the qualifier ``generally'', above, because there is no guarantee that the filename will be canonical without soft links, though we expect this to be true in practice. ACL2 attempts to compute the desired result and then checks that the input and result have the same Common Lisp ``[47mtruename[0m''. This check is expected to succeed, but if it fails then the input string is returned unchanged, and to be conservative, the value returned is [47mnil[0m in this case if [47mdir-p[0m is true.") (car (conses acl2-built-ins) "Returns the first element of a non-empty list, else [47mnil[0m Completion Axiom ([47mcompletion-of-car[0m): (equal (car x) (cond ((consp x) (car x)) (t nil))) [Guard]: (or (consp x) (equal x nil)) Notice that in the ACL2 logic, [47mcar[0m returns [47mnil[0m for every [atom].") (case (basics acl2-built-ins) "Conditional based on if-then-else using [47m[eql][0m Example Form: (case typ ((:character foo) (open file-name :direction :output)) (bar (open-for-bar file-name)) (otherwise (my-error "Illegal."))) is the same as (cond ((member typ '(:character foo)) (open file-name :direction :output)) ((eql typ 'bar) (open-for-bar file-name)) (t (my-error "Illegal."))) which in turn is the same as (if (member typ '(:character foo)) (open file-name :direction :output) (if (eql typ 'bar) (open-for-bar file-name) (my-error "Illegal."))) Notice the quotations that appear in the example above: [47m'(:character foo)[0m and [47m'bar[0m. Indeed, a [47mcase[0m expression expands to a [47m[cond][0m expression in which each tested form is quoted, and [47m[eql][0m is used to test equality, as described below.. General Forms: (case expr (x1 val-1) ... (xk val-k) (otherwise val-k+1)) (case expr (x1 val-1) ... (xk val-k) (t val-k+1)) (case expr (x1 val-1) ... (xk val-k)) where each [47mxi[0m is either [47m[eqlablep][0m or a true list of [47m[eqlablep][0m objects. The final [47motherwise[0m or [47mt[0m case is optional; if neither is present, then an equivalent expression results from adding the final case [47m(t nil)[0m. As suggested above, each case [47m(xi val-i)[0m generates an if-then-else expression as follows. If [47mxi[0m is a non-nil atom (i.e., [47mxi[0m is not [47mnil[0m or a cons pair), then that case generates the expression [47m(if (eql expr (quote xi)) vali ...)[0m where `[47m...[0m' denotes the expression generated by the rest of the cases. If however [47mxi[0m is a list, then instead the generated expression is [47m(if (member expr (quote xi)) vali ...)[0m. The final case [47m(t val-k+1)[0m or [47m(otherwise val-k+1)[0m generates [47mval-k+1[0m. Note that [47mt[0m and [47motherwise[0m here must be in the [47m"ACL2"[0m package. Also note that to compare [47mexpr[0m with [47mnil[0m, you should write the case as [47m((nil) val-i)[0m rather than [47m(nil val-i)[0m --- and similarly for [47mt[0m or [47motherwise[0m --- that is, put the symbol in a list. [47mCase[0m is defined in Common Lisp. See any Common Lisp documentation for more information.") (case-match (basics acl2-built-ins) "Pattern matching or destructuring General Form: (case-match x (pat1 dcl1 ... body1) ... (patk dclk ... bodyk)) where [47mx[0m is a symbol, the [47mpati[0m are structural patterns as described below, each ``[47mdcli ...[0m'' indicates 0 or more [47m[declare][0m forms, and the [47mbodyi[0m are terms. The legal [47mdeclare[0m forms are the same as for [47m[let][0m: [47mignore[0m, [47mignorable[0m, and [47mtype[0m. Return the value(s) of the [47mbodyi[0m corresponding to the first [47mpati[0m matching [47mx[0m, or [47mnil[0m if none matches. Pattern Language: With the few special exceptions described below, matching requires that the [47m[cons][0m structure of [47mx[0m be isomorphic to that of the pattern, down to the [atom]s in the pattern. Non-symbol [atom]s in the pattern match only themselves. Symbols in the pattern denote variables which match anything and which are bound by a successful match to the corresponding substructure of [47mx[0m. Variables that occur more than once must match the same ([47m[equal][0m) structure in every occurrence. Exceptions: & Matches anything and is not bound. Repeated occurrences of & in a pattern may match different structures. nil, t, *sym*, :sym These symbols cannot be bound and match only their global values. !sym where sym is a symbol that is already bound in the context of the case-match, matches only the current binding of sym. 'obj Matches only itself. This is the same as (QUOTE obj). (QUOTE~ sym) where sym is a symbol, is like (QUOTE sym) except it matches any symbol with the same symbol-name as sym. Note that QUOTE~ is in the "ACL2" package. Some examples are shown below. Below we show some sample patterns and examples of things they match and do not match. pattern matches non-matches (x y y) (ABC 3 3) (ABC 3 4) ; 3 is not 4 (fn x . rst) (P (A I) B C) (ABC) ; NIL is not (x . rst) (J (A I)) ; rst matches nil ('fn (g x) 3) (FN (H 4) 3) (GN (G X) 3) ; 'fn matches only itself (& t & !x) ((A) T (B) (C)) ; provided x is '(C) Consider the two binary trees that contain three leaves. They might be described as [47m(x . (y . z))[0m and [47m((x . y) . z)[0m, where [47mx[0m, [47my[0m, and [47mz[0m are atomic. Suppose we wished to recognize those trees. The following [47mcase-match[0m would do: (case-match tree ((x . (y . z)) (and (atom x) (atom y) (atom z))) (((x . y) . z) (and (atom x) (atom y) (atom z)))) Suppose we wished to recognize such trees where all three tips are identical. Suppose further we wish to return the tip if the tree is one of those recognized ones and to return the number [47m7[0m otherwise. (case-match tree ((x . (x . x)) (if (atom x) x 7)) (((x . x) . x) (if (atom x) x 7)) (& 7)) Note that [47mcase-match[0m returns [47mnil[0m if no [47mpati[0m matches. Thus if we must return [47m7[0m in that case, we have to add as the final pattern the [47m&[0m, which always matches anything. Technical point: The symbol [47msym[0m referenced by the symbol [47m!sym[0m is in the same package as [47m!sym[0m but with the leading exclamation point character, [47m\#![0m, removed from the [47m[symbol-name][0m of [47m!sym[0m.") (case-split (rewrite linear type-prescription definition meta forward-chaining) "Like force but immediately splits the top-level goal on the hypothesis [47mCase-split[0m is a variant of [47m[force][0m, which has similar special treatment in hypotheses of rules for the same [rule-classes] as for [47mforce[0m (see [force]). This treatment takes place for rule classes [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[meta][0m (actually in that case, the result of evaluating the hypothesis metafunction call), and [47m:[0m[47m[forward-chaining][0m. When a hypothesis of a conditional rule (of one of the classes listed above) has the form [47m(case-split hyp)[0m it is logically equivalent to [47mhyp[0m. However it affects the application of the rule generated as follows: if ACL2 attempts to apply the rule but cannot establish that the required instance of [47mhyp[0m holds in the current context, it considers the hypothesis true anyhow, but (assuming all hypotheses are seen to be true and the rule is applied) creates a subgoal in which that instance of [47mhyp[0m is assumed false. (There are exceptions, noted below.) For example, given the rule (defthm p1->p2 (implies (case-split (p1 x)) (p2 x))) then an attempt to prove (implies (p3 x) (p2 (car x))) can give rise to a single subgoal: (IMPLIES (AND (NOT (P1 (CAR X))) (P3 X)) (P2 (CAR X))). Unlike [47m[force][0m, [47mcase-split[0m does not delay the ``false case'' to a forcing round but tackles it more or less immediately. The special ``split'' treatment of [47mcase-split[0m can be disabled by disabling forcing: see [force] for a discussion of disabling forcing, and also see [disable-forcing]. Finally, we should mention that the rewriter is never willing to split when there is an [47m[if][0m term present in the goal being simplified. Since [47m[and][0m terms and [47m[or][0m terms are merely abbreviations for [47m[if][0m terms, they also prevent splitting. Note that [47m[if][0m terms are ultimately eliminated using the ordinary flow of the proof (but see [set-case-split-limitations]), so [47mcase-split[0m will ultimately function as intended. When in the interactive [proof-builder], [47mcase-split[0m behaves like [47mforce[0m. [31;1mFunction: [0m<case-split> (defun case-split (x) (declare (xargs :guard t)) x)") (case-split-limitations (miscellaneous) "Limiting the number of immediate subgoals Examples: ACL2 !>(case-split-limitations (w state)) (500 100) With the setting above, which is the default, [47mclausify[0m will not try subsumption/replacement if more than 500 [clause]s are involved. Furthermore, the simplifier, as it sweeps over a clause, will inhibit further case splits when it has accumulated 100 subgoals. To implement this inhibition, ACL2 refuses to rewrite subsequent literals, although it continues to split on any [47mIF[0m calls in those literals. The following example illustrates how the latter restriction --- specifically, not rewriting subsequent literals to avoid further case splits --- can work. We define a (rather nonsensical) function whose body introduces several cases. (defun f1 (a b c) (if a (if b (equal c 0) (equal c 1)) (if b (equal c 2) (equal c 3)))) (set-case-split-limitations '(500 10)) (set-gag-mode nil) (thm (or (equal (f1 a b c) xxx) (equal (f1 d e f) yyy) (equal (f1 g h i) zzz)) :hints (("Goal" :in-theory (disable f1)) ("Goal'" :in-theory (enable f1))) :otf-flg t) We show the output below. The simplification of the original goal to Goal' replaces the original goal, which is the clause (i.e., disjunction) consisting of the single literal (i.e., term) shown above, to the clause consisting of three literals, namely, the list: ; Goal', as a clause (disjunction of three literals) ((EQUAL (F1 A B C) XXX) (EQUAL (F1 D E F) YYY) (EQUAL (F1 G H I) ZZZ)) That simplification is reflected in the value printed (as an implication) for Goal' in the output, below. If we omit the call of [47m[set-case-split-limitations][0m above, then we get 64 cases, from opening up the calls of [47mf1[0m and splitting on the variables [47ma[0m, [47mb[0m, [47md[0m, [47me[0m, [47mg[0m, and [47mh[0m. But with the limit of 10 provided by set-case-split-limitations above, fewer cases are generated because rewriting of literals is inhibited, as explained below. Here is the first part of the output for that limit of 10. [Note: A hint was supplied for the goal above. Thanks!] This simplifies, using trivial observations, to [Note: A hint was supplied for the goal below. Thanks!] Goal' (IMPLIES (AND (NOT (EQUAL (F1 A B C) XXX)) (NOT (EQUAL (F1 D E F) YYY))) (EQUAL (F1 G H I) ZZZ)). This simplifies, using the :definition F1 (if-intro), to the following thirteen conjectures. Subgoal 13 (IMPLIES (AND A B (NOT (EQUAL (EQUAL C 0) XXX)) (NOT (EQUAL (F1 D E F) YYY))) (EQUAL (F1 G H I) ZZZ)). Why, though, are there 13 cases, even though the limit was specified as 10? Initially, the first literal [47m(EQUAL (F1 A B C) XXX)[0m was rewritten, splitting into four cases; and for each of those cases, the second literal was rewritten, splitting further; and so on. However, the first time more than 10 cases were generated was when there were 10 cases generated so far and a literal generated four cases --- then since that one literal generated four cases, 4-1 = 3 cases were added to the 10 already generated. From that point on, further rewriting of literals did not take place. In short: the first time a literal splits into enough cases so that the accumulated number of cases exceeds the limit, rewriting stops --- but that last split can put us significantly past the limit specified. See [set-case-split-limitations] for a more general discussion.") (cases (pointers) "See [hints] for information about the keyword [47m:cases[0m.") (cbd (books-reference programming-with-state acl2-built-ins) "Connected book directory string Example: ACL2 !>:cbd "/usr/home/smith/" The connected book directory (``cbd'') is a string ending with the [47m/[0m character that specifies a directory as an absolute pathname. (See [pathname] for a discussion of file naming conventions.) When utilities that take a filename argument, such as [47m[include-book][0m, are given a relative pathname, it is elaborated into an absolute pathname, essentially by appending the connected book directory string to the left and [47m".lisp"[0m to the right. (This absolute pathname is actually canonical when elaborating book names. For more details on book names, see [book-name] and also see [full-book-name].) Furthermore, [47m[include-book][0m and [47m[ld][0m temporarily set the connected book directory to the directory string of the resulting full pathname so that references to files in the same directory may omit the directory. See [set-cbd] for how to set the connected book directory string. Note that the cbd is used for elaborating every [pathname] argument, not just a pathname that represents a book. (Technical remark: Some utilities, such as [47m[open-input-channel][0m, use the cbd indirectly as follows. That utility uses the Common Lisp utility, [47mopen[0m, which knows nothing about the cbd. However, ACL2 arranges that the Lisp global [47m*default-pathname-defaults*[0m always has the cbd as its value, and Lisp uses that global to elaborate relative pathnames much as ACL2 uses the cbd.) General Form: (cbd) This is a macro that expands into a term involving the single free variable [47m[state][0m. It returns the connected book directory string. For example, if the [47mcbd[0m is [47m"/usr/home/smith/"[0m then the [book-name] [47m"project/task-1/arith"[0m is elaborated using the [47mcbd[0m to the [full-book-name] [47m"/usr/home/smith/project/task-1/arith.lisp"[0m, which is what [include-book] opens to read the source text for the book. The [47mcbd[0m may be changed using [47m[set-cbd][0m. As noted above, during the processing of the [events] in a book, [47m[include-book][0m sets the [47mcbd[0m to be the directory string of the [full-book-name] of the book; similarly for [47m[ld][0m. Thus, if the [47mcbd[0m is [47m"/usr/home/smith/"[0m then during the processing of [events] by (include-book "project/task-1/arith") the [47mcbd[0m will be set to [47m"/usr/home/smith/project/task-1/"[0m. Note that if [47m"arith"[0m recursively includes a sub-book, say [47m"naturals"[0m, that resides on the same directory, the [47m[include-book][0m event for it may omit the specification of that directory. For example, [47m"arith"[0m might contain the event (include-book "naturals"). In general, suppose we have a superior book and several inferior [books] which are included by [events] in the superior book. Any inferior book residing on the same directory as the superior book may be referenced in the superior without specification of the directory. We call this a ``relative'' as opposed to ``absolute'' naming. The use of relative naming is preferred because it permits [books] (and their accompanying inferiors) to be moved between directories while maintaining their [certificate]s and utility. Certified [books] that reference inferiors by absolute file names are unusable (and rendered uncertified) if the inferiors are moved to new directories.") (ccl-installation (obtaining-common-lisp) "Installing Clozure Common Lisp (CCL) For those who use ACL2 built on CCL as the host Common Lisp implementation, it has been common practice to use the latest GitHub version of CCL. We provide the following instructions for you to choose from. The ``brief'' instructions for Linux or Mac (according to your operating system) might well suffice; the ``elaborate'' instructions have helped with version control. * [ccl-installation-linux-brief] * [ccl-installation-mac-brief] * [ccl-installation-linux-elaborate] * [ccl-installation-mac-elaborate] You may prefer instead to look at the {CCL Releases | https://github.com/Clozure/ccl/releases} page, which has potentially more up-to-date information; then you can use the links above only as needed (e.g., for Linux-specific information or for discussion of [47mCCL_DEFAULT_DIRECTORY[0m). One of the links listed above should generally suffice. But if you would like additional information on CCL installation and implementation, see [ccl-installation-extra]. Subtopics [Ccl-installation-extra] Clozure Common Lisp (CCL) installation and implementation details [Ccl-installation-linux-brief] Installing Clozure Common Lisp (CCL) on Linux (brief version) [Ccl-installation-linux-elaborate] Installing Clozure Common Lisp (CCL) on Linux (elaborate version) [Ccl-installation-mac-brief] Installing Clozure Common Lisp (CCL) on Mac (brief version) [Ccl-installation-mac-elaborate] Installing Clozure Common Lisp (CCL) on Mac (elaborate version)") (ccl-installation-extra (ccl-installation) "Clozure Common Lisp (CCL) installation and implementation details [31;1mNOTE[0m: See {the Clozure CL releases page | https://github.com/Clozure/ccl/releases/} for the latest information, which may supersede some of what is included below. This topic, contributed by Warren A. Hunt, Jr., extends the basic information given in [ccl-installation]. It may be useful to some, especially those who use ACL2 in ways that particularly stress memory. Another resource may be found on {this page | https://github.com/Clozure/ccl/releases/}. Below we provide instructions to build CCL on FreeBSD and MacOS; building on Linux will be similar. Before providing the build instructions, we mention a few facts about CCL's implementation. CCL's implementation can't expand stack space automatically. The sizes of various stacks are set at thread creation time. Most programs don't need very big stacks. The CCL default value and temp stack sizes may be too small for compute-intensive applications. The various stack sizes are set when creating a thread with code in [47mCCL::MAKE-PROCESS[0m and [47mCCL::PROCESS-RUN-FUNCTION[0m, and they set the three stack sizes of the initial listener thread that is created when CCL starts. The value stack is used for data in deeply-nested lisp recursion. ACL2 can benefit from an increase in the size of the value stack. The temp stack is used for dynamic-extent objects. This might need need to be larger than the default. The control stack is used to run C and binary code; it would be surprising to need to increase its size. If only one or two threads are needed, giant (e.g., 4 GB) stacks can be OK, but with many threads large stacks use lots of memory. Below are the stacks along with their current (April, 2020) default sizes. ccl::*default-control-stack-size* ;; default 2^21 ccl::*initial-listener-default-control-stack-size* ;; default 2^21 ccl::*default-value-stack-size* ;; default 2^21 ccl::*initial-listener-default-value-stack-size* ;; default 2^21 ccl::*initial-listener-default-temp-stack-size* ;; default 2^20 ccl::*default-temp-stack-size* ;; default 2^20 If we are running on a 32-bit platform, we set the stack sizes modestly. If we are on a 64-bit platform, we set the stack sizes to much larger values. See the later discussion about ``configure-ccl.lisp'' below to see how to alter (increase) stack sizes. MacOS Build Instructions: git clone https://github.com/Clozure/ccl.git ccl-dev curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12-dev.5/darwinx86.tar.gz cd ccl-dev ; tar xf ../darwinx86.tar.gz Rebuild C-based, Lisp kernel To rebuild the Lisp-code part of the kernel, do... cd lisp-kernel/darwinx8664 ; make ; cd ../.. Unlike for FreeBSD and Linux, we exclude ``:full t'' from the ``rebuild-ccl'' command just below Matt Emerson (a CCL expert) writes: After looking at your log, I was able to duplicate the problem myself. For some reason I do not understand, it appears that on Catalina, removing the running lisp kernel binary causes run-program to break (trying to run external programs gets signal 9). This surprises me very much. One of the effects of running (rebuild-ccl :full t), is that it first does a "make clean" in the lisp kernel directory, and then does a regular make. This has worked for years, and I do not know why it has stopped working. To avoid this, rebuild the lisp with (rebuild-ccl :clean t) instead. Do not specify ``[47m:full t[0m''. Since you have already built the lisp kernel, you gain nothing from ``[47m:full t[0m'' doing it again. So, once the C-based, Lisp kernel is built, then do: echo "(in-package :ccl) (rebuild-ccl :verbose t :clean t)" | \ ./dx86cl64 -n |& tee ./ccl-build-compile.log Matt Emerson suggests that one re-build again. We asked Matt a long-simmering question: we have been told that it is a good idea to compile CCL twice. Is that so that the CCL compiler produced by pass one on the target system is used to compile the CCL system that will be used (on the target system)? Or, is compiling twice some silly myth? Matt Emerson responded: It's not entirely mythic. Some rare changes do need the lisp to be rebuilt twice for bootstrapping purposes, but usually it isn't required. Thus, we recommend you re-build (compile) the Lisp code again. echo "(in-package :ccl) (rebuild-ccl :verbose t :clean t)" | \ ./dx86cl64 -n |& tee ./ccl-build-compile-2.log Finally, one may specialize the final image by: cat configure-ccl.lisp | ./dx86cl64 -n |& tee ~/ccl-build-specialize.log where ``configure-ccl.lisp'' (not supplied) contains whatever CCL specialization commands you wish to have in the version of CCL you use for ACL2 or other work. See the end of this note for an example of ``configure-ccl.lisp''. FreeBSD Build Instructions: The FreeBSD build instructions are similar to the MacOS build instruction, but the names are changed appropriately. git clone https://github.com/Clozure/ccl.git ccl-dev curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12-dev.5/freebsd12-x8664.tar.gz cd ccl-dev tar xf ../freebsd12-x8664.tar.gz Rebuild C-based Lisp kernel cd lisp-kernel/freebsdx8664 ; make ; cd ../.. To rebuild the Lisp-code part of the kernel, do... echo "(in-package :ccl) (rebuild-ccl :full t :verbose t :clean t)" | \ ./fx86cl64 -n |& tee ./ccl-build-compile.log FreeBSD is OK with the ``:full t'' flag, which as of MacOS 10.15 breaks (but used to work on earlier versions of MacOS). So, this option persists on the FreeBSD build. Matt Emerson recommends building the Lisp code a second time; see the ``MacOS Build Instructions'' above for his rationale. echo "(in-package :ccl) (rebuild-ccl :full t :verbose t :clean t)" | \ ./fx86cl64 -n |& tee ./ccl-build-compile-2.log Finally, one may specialize the final image by: cat ~/a/scripts/configure-ccl.lisp | ./fx86cl64 -n |& tee ~/ccl-build-specialize.log where ``configure-ccl.lisp'' (not supplied) contains whatever CCL specialization commands you wish to have in the version of CCL you use for ACL2 or other work. configure-ccl.lisp Sample ``configure-ccl.lisp'' file for 64-bit implementation: (progn ;; Parameters to configure CCL for use on FreeBSD and MacOS (in-package :ccl) ;; Enlarge stack sizes (setq *default-value-stack-size* (expt 2 28)) (setq *initial-listener-value-stack-size* (expt 2 28)) (setq *default-temp-stack-size* (expt 2 24)) (setq *initial-listener-temp-stack-size* (expt 2 24)) (setq *default-control-stack-size* (expt 2 24)) (setq *initial-listener-default-control-stack-size* (expt 2 24)) ;; For CCL double precision (setf *read-default-float-format* 'double-float) ;; Make DEFUN save the source code for later recovery via ;; FUNCTION-LAMBDA-EXPRESSION. (setq *save-definitions* t) (setq *fasl-save-definitions* t) ;; Make GC verbose; see ACL2 documentation topic GC-VERBOSE. (gc-verbose t t) ;; Dump executable heap image; see ACL2 documentation topic SAVE-EXEC. (save-exec *heap-image-name* "Modification string to print at startup") )") (ccl-installation-linux-brief (ccl-installation) "Installing Clozure Common Lisp (CCL) on Linux (brief version) [31;1mNOTE:[0m See {the Clozure CL releases page | https://github.com/Clozure/ccl/releases/} for the latest information, which probably supersedes what is included below. See [ccl-installation] for introductory remarks. The instructions below describe how to install CCL on Linux. For more elaborate ``cookbook'' instructions see [ccl-installation-linux-elaborate]. [31;1mNote[0m: Linux users may need to install m4. Fetch CCL from GitHub into a fresh subdirectory, [47mccl/[0m. git clone https://github.com/Clozure/ccl Next fetch and extract a development snapshot in the new [47mccl[0m directory. [31;1mWARNING.[0m The version below is current as of this writing (November, 2023), but see {https://github.com/Clozure/ccl/releases/ | https://github.com/Clozure/ccl/releases/} for the latest snapshots; in particular, [47m"v1.12.2"[0m below could change, e.g., to [47m"v1.12.3"[0m or [47m"v1.13"[0m. cd ccl wget https://github.com/Clozure/ccl/releases/download/v1.12.2/linuxx86.tar.gz tar xfz linuxx86.tar.gz Rebuild and quit, twice. echo '(rebuild-ccl :full t)' | ./lx86cl64 echo '(rebuild-ccl :full t)' | ./lx86cl64 Create the following executable script, which you will probably want to name [47m"ccl"[0m, where [47m<DIR>[0m is the absolute pathname (without using ``[47m~[0m'') of the directory in which you issued the ``[47mgit clone[0m'' command. Place this script wherever you wish, though putting it in a directory on your Unix [47mPATH[0m might be helpful (since then you can invoke it as, say [47m"ccl"[0m). #!/bin/sh export CCL_DEFAULT_DIRECTORY=<DIR>/ccl ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@" You're done! (Note however that certification of [books] that use [Quicklisp] may require [47mopenssl[0m to be installed if it is not already on your system.)") (ccl-installation-linux-elaborate (ccl-installation) "Installing Clozure Common Lisp (CCL) on Linux (elaborate version) [31;1mNOTE:[0m See {the Clozure CL releases page | https://github.com/Clozure/ccl/releases/} for the latest information, which may well supersede what is included below. See [ccl-installation] for introductory remarks. The ``cookbook'' instructions below give you one way to install CCL on Linux without any knowledge of git or CCL. For more streamlined instructions see [ccl-installation-linux-brief]. [31;1mNote[0m: Linux users may need to install m4. First fetch CCL from GitHub as follows. (You may prefer to use ``[47mgit pull[0m'' if you previously did this step. In that case you probably won't want to do the optional renaming of the directory, mentioned below.) # Obtain a ccl distribution in a fresh directory: mkdir temp cd temp git clone https://github.com/Clozure/ccl # Optionally rename that directory as suggested below, after # executing the following three commands. cd ccl git rev-parse HEAD cd ../../ # Optionally change directory name, and then go back to ccl directory: # You'll want the last 10 hex digits to match those of the # output from the ``git rev-parse HEAD'' command above: do # that twice here and once further below. mv temp 2017-12-07-6be8298fe5 cd 2017-12-07-6be8298fe5/ccl Next fetch and extract a development snapshot in the new [47mccl[0m directory. [31;1mWARNING.[0m The version below is current as of this writing (November, 2023), but see {https://github.com/Clozure/ccl/releases/ | https://github.com/Clozure/ccl/releases/} for the latest snapshots; in particular, [47m"v1.12.2"[0m below could change, e.g., to [47m"v1.12.3"[0m or [47m"v1.13"[0m. wget https://github.com/Clozure/ccl/releases/download/v1.12.2/linuxx86.tar.gz tar xfz linuxx86.tar.gz Rebuild and quit, twice. echo '(rebuild-ccl :full t)' | ./lx86cl64 echo '(rebuild-ccl :full t)' | ./lx86cl64 Create an executable script like the following. You might want to call it ``[47mccl[0m'' and put it into a directory on your path. Be sure to change the name (shown as ``2017-12-07-6be8298fe5'' above) to match the name change already made above. #!/bin/sh export CCL_DEFAULT_DIRECTORY=/projects/acl2/lisps/ccl/2017-12-07-6be8298fe5/ccl ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@" Now ensure that your script is executable, e.g.: chmod +x my-script You're done! (Note however that certification of [books] that use [Quicklisp] may require [47mopenssl[0m to be installed if it is not already on your system.)") (ccl-installation-mac-brief (ccl-installation) "Installing Clozure Common Lisp (CCL) on Mac (brief version) [31;1mNOTE:[0m See {the Clozure CL releases page | https://github.com/Clozure/ccl/releases/} for the latest information, which probably supersedes what is included below. See [ccl-installation] for introductory remarks. The instructions below describe how to install CCL on a Mac (Darwin). For more elaborate ``cookbook'' instructions see [ccl-installation-mac-elaborate]. Fetch CCL from GitHub into a fresh subdirectory, [47mccl/[0m. git clone https://github.com/Clozure/ccl Next fetch and extract a development snapshot in the new [47mccl[0m directory. [31;1mWARNING.[0m The version below is current as of this writing (November, 2023), but see {https://github.com/Clozure/ccl/releases/ | https://github.com/Clozure/ccl/releases/} for the latest snapshots; in particular, [47m"v1.12.2"[0m below could change, e.g., to [47m"v1.12.3"[0m or [47m"v1.13"[0m. cd ccl curl -O -L https://github.com/Clozure/ccl/releases/download/v1.12.2/darwinx86.tar.gz tar xfz darwinx86.tar.gz Rebuild the lisp kernel by hand before trying to rebuild the lisp. cd lisp-kernel/darwinx8664; make clean; make cd - Rebuild and quit, twice. echo '(rebuild-ccl :clean t)' | ./dx86cl64 echo '(rebuild-ccl :clean t)' | ./dx86cl64 Create the following executable script, which you will probably want to name [47m"ccl"[0m, where [47m<DIR>[0m is the absolute pathname (without using ``[47m~[0m'') of the directory in which you issued the ``[47mgit clone[0m'' command. Place this script wherever you wish, though putting it in a directory on your Unix [47mPATH[0m might be helpful (since then you can invoke it as, say [47m"ccl"[0m). #!/bin/sh export CCL_DEFAULT_DIRECTORY=<DIR>/ccl ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@" You're done! (Note however that certification of [books] that use [Quicklisp] may require [47mopenssl[0m to be installed if it is not already on your system.)") (ccl-installation-mac-elaborate (ccl-installation) "Installing Clozure Common Lisp (CCL) on Mac (elaborate version) [31;1mNOTE:[0m See {the Clozure CL releases page | https://github.com/Clozure/ccl/releases/} for the latest information, which may well supersede what is included below. See [ccl-installation] for introductory remarks. The ``cookbook'' instructions below give you one way to install CCL on a Mac (Darwin) without any knowledge of git or CCL. For more streamlined instructions see [ccl-installation-mac-brief]. First fetch CCL from GitHub as follows. (You may prefer to use ``[47mgit pull[0m'' if you previously did this step. In that case you probably won't want to do the optional renaming of the directory, mentioned below.) # Obtain a ccl distribution in a fresh directory: mkdir temp cd temp git clone https://github.com/Clozure/ccl # Optionally rename that directory as suggested below, after # executing the following three commands. cd ccl git rev-parse HEAD cd ../../ # Optionally change directory name, and then go back to ccl directory: # You'll want the last 10 hex digits to match those of the # output from the ``git rev-parse HEAD'' command above: do # that twice here and once further below. mv temp 2017-12-07-6be8298fe5 cd 2017-12-07-6be8298fe5/ccl Next fetch and extract a development snapshot in the new [47mccl[0m directory. [31;1mWARNING.[0m The version below is current as of this writing (November, 2023), but see {https://github.com/Clozure/ccl/releases/ | https://github.com/Clozure/ccl/releases/} for the latest snapshots; in particular, [47m"v1.12.2"[0m below could change, e.g., to [47m"v1.12.3"[0m or [47m"v1.13"[0m. curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12.2/darwinx86.tar.gz tar xfz darwinx86.tar.gz Rebuild the lisp kernel by hand before trying to rebuild the lisp. (Note: This step was formerly unnecessary and might become unnecessary again, but it seems to have been necessary on MacOS Catalina (10.15). cd lisp-kernel/darwinx8664; make clean; make cd - Rebuild and quit, twice. echo '(rebuild-ccl :clean t)' | ./dx86cl64 echo '(rebuild-ccl :clean t)' | ./dx86cl64 Create an executable script like the following. You might want to call it ``[47mccl[0m'' and put it into a directory on your path. Be sure to change the name (shown as ``2017-12-07-6be8298fe5'' above) to match the name change already made above. #!/bin/sh export CCL_DEFAULT_DIRECTORY=/projects/acl2/lisps/ccl/2017-12-07-6be8298fe5/ccl ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 "$@" Now ensure that your script is executable, e.g.: chmod +x my-script You're done! (Note however that certification of [books] that use [Quicklisp] may require [47mopenssl[0m to be installed if it is not already on your system.)") (ccl-updates (pointers) "See [ccl-installation].") (cdaaar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[caaar][0m See any Common Lisp documentation for details.") (cdaadr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[caadr][0m See any Common Lisp documentation for details.") (cdaar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[caar][0m See any Common Lisp documentation for details.") (cdadar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cadar][0m See any Common Lisp documentation for details.") (cdaddr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[caddr][0m See any Common Lisp documentation for details.") (cdadr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cadr][0m See any Common Lisp documentation for details.") (cdar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[car][0m See any Common Lisp documentation for details.") (cddaar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cdaar][0m See any Common Lisp documentation for details.") (cddadr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cdadr][0m See any Common Lisp documentation for details.") (cddar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cdar][0m See any Common Lisp documentation for details.") (cdddar (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cddar][0m See any Common Lisp documentation for details.") (cddddr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cdddr][0m See any Common Lisp documentation for details.") (cdddr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cddr][0m See any Common Lisp documentation for details.") (cddr (conses acl2-built-ins) "[47m[cdr][0m of the [47m[cdr][0m See any Common Lisp documentation for details.") (cdr (conses acl2-built-ins) "Returns the second element of a [47m[cons][0m pair, else [47mnil[0m Completion Axiom ([47mcompletion-of-cdr[0m): (equal (cdr x) (cond ((consp x) (cdr x)) (t nil))) [Guard]: (or (consp x) (equal x nil)) Notice that in the ACL2 logic, [47mcdr[0m returns [47mnil[0m for every [atom].") (ceiling (numbers acl2-built-ins) "Division returning an integer by truncating toward positive infinity Example Forms: ACL2 !>(ceiling 14 3) 5 ACL2 !>(ceiling -14 3) -4 ACL2 !>(ceiling 14 -3) -4 ACL2 !>(ceiling -14 -3) 5 ACL2 !>(ceiling -15 -3) 5 [47m(Ceiling i j)[0m is the result of taking the quotient of [47mi[0m and [47mj[0m and returning the smallest integer that is at least as great as that quotient. For example, the quotient of [47m-14[0m by [47m3[0m is [47m-4 2/3[0m, and the smallest integer at least that great is [47m-4[0m. The [guard] for [47m(ceiling i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real], in ACL2(r)) numbers and [47mj[0m is non-zero. [47mCeiling[0m is a Common Lisp function. See any Common Lisp documentation for more information. However, note that unlike Common Lisp, the ACL2 [47mceiling[0m function returns only a single value, [31;1mFunction: [0m<ceiling> (defun ceiling (i j) (declare (xargs :guard (and (real/rationalp i) (real/rationalp j) (not (eql j 0))))) (let* ((q (* i (/ j))) (n (numerator q)) (d (denominator q))) (cond ((= d 1) n) ((>= n 0) (+ (nonnegative-integer-quotient n d) 1)) (t (- (nonnegative-integer-quotient (- n) d))))))") (certifiable (pointers) "See [certify-book].") (certificate (books-tour) "A file specifying validity of a given book A book, say [47m"arith"[0m, is said to have a ``certificate'' if there is a file named [47m"arith.cert"[0m. Certificates are created by the function [47m[certify-book][0m and inspected by [47m[include-book][0m. [Book-hash] values are used to help ensure that certificates are legitimate and that the corresponding book has not been modified since certification. But because the file system is insecure and book-hash values are not perfect, it is possible for the inclusion of a book to cause inconsistency even though the book carries an impeccable certificate. The certificate includes the version number of the certifying ACL2. A book is considered uncertified if it is included in an ACL2 with a different [version] number. The presence of a ``valid'' certificate file for a book attests to two things: all of the [events] of the book are admissible in a certain extension of the initial ACL2 logic, and the non-[47m[local][0m [events] of the book are independent of the [47m[local][0m ones (see [local-incompatibility]). In addition, the certificate contains the [command]s used to construct the [world] in which certification occurred. Among those [command]s, of course, are the [47m[defpkg][0ms defining the packages used in the book. When a book is included into a host [world], that [world] is first extended by the [command]s listed in the certificate for the book. Unless that causes an error due to name conflicts, the extension ensures that all the packages used by the book are identically defined in the host [world]. [3mSecurity:[0m Because the host file system is insecure, there is no way ACL2 can guarantee that the contents of a book remain the same as when its certificate was written. That is, between the time a book is certified and the time it is used, it may be modified. Furthermore, certificates can be counterfeited. [Book-hash] values are used to help detect such problems, but provide imperfect security: two different files can have the same book-hash. Therefore, from the strictly logical point of view, one must consider even the inclusion of certified [books] as placing a burden on the user: The non-erroneous inclusion of a certified book is consistency preserving provided (a) the objects read by [47m[include-book][0m from the certificate were the objects written there by a [47m[certify-book][0m and (b) the forms read by [47m[include-book][0m from the book itself are the forms read by the corresponding [47m[certify-book][0m. We say that a given execution of [47m[include-book][0m is ``certified'' if a certificate file for the book is present and well-formed and the [book-hash] information contained within it supports the conclusion that the [events] read by the [47m[include-book][0m are the ones checked by [47m[certify-book][0m. When an uncertified [47m[include-book][0m occurs, warnings are printed or errors are caused. But even if no warning is printed, you must accept burdens (a) and (b) if you use [books]. These burdens are easier to live with if you protect your [books] so that other users cannot write to them, you abstain from running concurrent ACL2 jobs, and you abstain from counterfeiting certificates. But even on a single user uniprocessor, you can shoot yourself in the foot by using the ACL2 [io] primitives to fabricate an inconsistent book and the corresponding certificate. Note that part (a) of the burden described above implies, in particular, that there are no guarantees when a certificate is copied. When [books] are renamed (as by copying them), it is recommended that their certificates be removed and the [books] be recertified. The expectation is that recertification will go through without a hitch if relative [pathname]s are used. See [pathname], which is not on the guided tour. Certificates contain a [portcullis] and a [keep], each documented later in this guided tour through [books]. We mention here two other parts, which we do not document elsewhere because we view them as implementation details: an [47mexpansion-alist[0m, which records [47m[make-event][0m expansions; and [47mcert-data[0m, which contains logical information associated with the book. (Those curious about [47mcert-data[0m are invited to look at the ``Essay on Cert-data'' in the source code.) See [portcullis] to continue the guided tour through [books]. Subtopics [Checksum] Assigning ``often unique'' integers to files and objects") (certify-book (books-reference books-tour) "How to produce a [certificate] for a book Also see [certificate] for information about the [47m".cert"[0m file produced by [47mcertify-book[0m, in particular for information about the use of [book-hash] values to help ensure that the corresponding book has not been modified since certification. See [certify-book-debug] for some potential remedies for failures of [47mcertify-book[0m. Examples: (certify-book "my-arith") ; certify in a world with 0 commands (certify-book "my-arith" 3) ; ... in a world with 3 commands (certify-book "my-arith" ?) ; ... in a world without checking the ; number of commands (certify-book "my-arith" 0 nil) ; ... without compilation (certify-book "my-arith" 0 t) ; ... with compilation (default) (certify-book "my-arith" 0 t :ttags (foo)) ; ... allowing trust tag (ttag) foo (certify-book "my-arith" 0 t :ttags :all) ; ... allowing all trust tags (ttags) (certify-book "my-arith" 0 nil :acl2x t) ; ... writing or reading a .acl2x file (certify-book "my-arith" 0 t :useless-runes :write) ; ... write file to speed up future proofs (certify-book "my-arith" 0 t :useless-runes :read) ; ... read file to speed up future proofs General Form: (certify-book book-name k ; [default 0] compile-flg ; [default t] :defaxioms-okp t/nil ; [default nil] :skip-proofs-okp t/nil ; [default nil] :ttags ttags ; [default nil] :acl2x t/nil ; [default nil] :ttagsx ttags ; [default nil] :pcert pcert ; [default nil] :write-port t/nil ; [default t unless pcert is non-nil] :useless-runes ; :write/:read/:read?/n/-n/nil ; (-100 < n < 0 or 0 < n <= 100) ; [default nil or from environment] :write-event-data ; [default nil or from environment] ) where [47mbook-name[0m is a book filename, [47mk[0m is used to indicate your approval of the ``certification [world],'' and [47mcompile-flg[0m can control whether the book is to be compiled. The defaults for [47mcompile-flg[0m, [47mskip-proofs-okp[0m, [47macl2x[0m, [47mwrite-port[0m, [47mpcert[0m, [47m:useless-runes[0m, and [47m:write-event-data[0m can be affected by environment variables. All of these arguments are described in detail below, except for [47m:pcert[0m, [47m:useless-runes[0m, and [47m:write-event-data[0m: see [provisional-certification], [useless-runes], and [saving-event-data], respectively, for the effects of these three arguments and related environment variables, as we ignore those effects in the present topic. NOTE: If a given book includes some books (see [include-book]), then those included books need to be certified before the given book is certified. See [build::cert.pl] for a tool that certifies not only a given book but also all of the books that it includes, as well as all the books that those books include, and so on --- all in the proper order, and with parallelism by using the [47m-j[0m option. Certification occurs in some logical [world], called the ``certification [world].'' That [world] must contain the [47m[defpkg][0ms needed to read and execute the forms in the book. The [command]s necessary to recreate that [world] from the ACL2 initial [world] are called the ``[portcullis] commands,'' and will be copied into the [certificate] created for the book. Those [command]s will be re-executed whenever the book is included, to ensure that the appropriate packages (and all other names used in the certification [world]) are correctly defined. Note that Step 1 of [47mcertify-book[0m will fail if a package mentioned in the book is not defined before attempting the certification, i.e., defined by a portcullis command in the certification world. For example, suppose that your book contains the symbol [47mFOO::X[0m, but the package "FOO" is not currently defined. Then an error message will likely complain either about a missing package [47m"FOO"[0m, or about a symbol [47mFOO::X[0m that is ``not in any of the packages known to ACL2.'' A solution is to define the package "FOO", perhaps directly using [47m[defpkg][0m or by including a book that defines this package, before attempting the certification. The certified book will be more often usable if the certification [world] is kept to a minimal extension of the ACL2 initial [world] (for example, to prevent name clashes with functions defined in other books, or to avoid including undesired rules). Alternatively, use [47m[local][0m [events] to build your certification world, as these will be skipped when including the certified book. But perhaps it's simplest just to get into the initial ACL2 [world] (e.g., with [47m:ubt 1[0m or by just starting a new ACL2 run), then define the desired packages (directly with [47m[defpkg][0m or by including books that define the packages), and finally invoke [47mcertify-book[0m. The [47mk[0m argument to [47mcertify-book[0m has default value [47m0[0m, and it must be either a nonnegative integer or else the symbol [47m?[0m in any package. If [47mk[0m is an integer, then it must be the number of [command]s that have been executed after the initial ACL2 [world] to create the [world] in which [47mcertify-book[0m was called. One way to obtain this number is by doing [47m:pbt :start[0m to see all the [command]s back to the first one. Otherwise, [47mk[0m is [47m?[0m (or any symbol whose [47m[symbol-name][0m is [47m"?"[0m). In that case there is no check made on the certification world. This can be a nice convenience but at the cost of eliminating a potentially valuable check that the certification [world] may be as expected. We next describe the meaning of [47mcompile-flg[0m and how it defaults. If explicit compilation has been suppressed by [47m(set-compiler-enabled nil state)[0m, then [47mcompile-flg[0m is coerced to [47mnil[0m; see [compilation]. Otherwise [47mcompile-flg[0m may be given the value of [47mt[0m (or [47m:all[0m, which is equivalent to [47mt[0m except during provisional certification; see [provisional-certification]), indicating that the book is to be compiled, or else [47mnil[0m. (Note that compilation initially creates a compiled file with a temporary file name, and then moves that temporary file to the final compiled file name obtained by adding a suitable extension to the book's filename. Thus, a compiled file will appear atomically in its intended location.) Finally, if [47mcompile-flg[0m is not supplied (or is [47m:default[0m) then it is treated as [47mt[0m. Note that the value [47m:all[0m is equivalent to [47mt[0m except for during the Convert procedure of provisional certification; see [provisional-certification]. Two keyword arguments, [47m:defaxioms-okp[0m and [47m:skip-proofs-okp[0m, determine how the system handles the inclusion of [47m[defaxiom][0m events and [47m[skip-proofs][0m events, respectively, in the book. The value [47mt[0m allows such events, but prints a warning message. The value [47mnil[0m causes an error if such an event is found. [47mNil[0m is the default unless keyword argument [47m:acl2x t[0m is provided and state global [47m'write-acl2x[0m is a cons (see [set-write-ACL2x]), in which case the default is [47mt[0m. The keyword argument [47m:ttags[0m may normally be omitted. A few constructs, used for example if you are building your own system based on ACL2, may require it. See [defttag] for an explanation of this argument. When book [47mB[0m is certified with value [47mt[0m (the default, unless the value used for [47mpcert[0m is non-[47mnil[0m) for keyword argument [47m:write-port[0m, a file [47mB.port[0m is written by certification process. This file contains all of the [portcullis] [command]s for [47mB[0m, i.e., all user commands present in the ACL2 logical [world] at the time [47mcertify-book[0m is called. If [47mB.lisp[0m later becomes uncertified, say because [events] from that file or an included book have been edited, then [47m(include-book "B")[0m will consult [47mB.port[0m to evaluate forms in that file before evaluating the events in [47mB.lisp[0m. On the other hand, [47mB.port[0m is ignored when including [47mB[0m if [47mB[0m is certified. If you use [guard]s, please note [47mcertify-book[0m is executed as though [47m(set-guard-checking t)[0m has been evaluated; see [set-guard-checking]. If you want to run with different guard-checking, consider using [47mld[0m instead, or in addition; see [ld]. For a general discussion of books, see [books]. [47mCertify-book[0m is akin to what we have historically called a ``proveall'': all the forms in the book are ``proved'' to guarantee their admissibility. More precisely, [47mcertify-book[0m (1) reads the forms in the book, confirming that the appropriate packages are defined in the certification [world]; (2) does the full admissibility checks on each form (proving termination of recursive functions, proving theorems, etc.), checking as it goes that each form is an embedded event form (see [embedded-event-form]); (3) may roll back the logical [world] (how far? --- see below) and perform an [47m[include-book][0m to check for [47m[local][0m incompatibilities (see [local-incompatibility]); (4) writes a [certificate] recording not only that the book was certified but also recording the [command]s necessary to recreate the certification [world] (so the appropriate packages can be defined when the book is included in other [world]s) and a [book-hash] for each of the [books] involved (see [certificate]); and (5) compiles the book if so directed (and then loads the object file in that case). [47mCertify-book[0m is a macro that returns an [error-triple], where success is indicated by an error component of [47mnil[0m and has the effect of extending the [world] with a corresponding [47m[include-book][0m event. If you don't want the included book's [events] in your present [world], simply execute [47m:[0m[47m[u][0m. Remark. Step (3) above mentions rolling back the logical [world] to check for local incompatibilities. This process is skipped if no [local] event is encountered. Otherwise, the world is rolled back through the first local event past the boot-strap world --- see [local-incompatibility] --- before the book is included. Note that if that first local event is in the certification world, then all commands from that event onward will be rolled back. See [fast-cert] for a way to skip entirely this process of roll-back and check, regardless of local events, but with a risk to soundness. End of Remark. A utility is provided to assist in debugging failures of [47mcertify-book[0m; see [redo-flat].) [47mCertify-book[0m requires that the default [defun-mode] (see [default-defun-mode]) be [47m:[0m[47m[logic][0m when certification is attempted. If the mode is not [47m:[0m[47m[logic][0m, an error is signaled. An error will occur if [47mcertify-book[0m has to deal with any uncertified book other than the one on which it was called. For example, if the book being certified includes another book, that sub-book must already have been certified; that is, that sub-book must have a valid [certificate] file. If you have a certified book that has remained unchanged for some time you might well not remember the appropriate [47m[defpkg][0ms for it, though they are stored in the [certificate] file and (by default) also in the [47m.port[0m file. If you begin to change the book, don't throw away its [certificate] file just because it has become invalid! It is an important historical document until the book is re-certified. More important, don't throw away the [47m.port[0m file, as it will provide the [portcullis] commands when including the book as an uncertified book; see [include-book]. When [47mcertify-book[0m is directed to produce a compiled file, it calls the Common Lisp function [47mcompile-file[0m on the original source file. This creates a compiled file with an extension known to ACL2, e.g., if the book is named [47m"my-book"[0m then the source file is [47m"my-book.lisp"[0m and the compiled file under GCL will be [47m"my-book.o"[0m while under SBCL it will be [47m"my-book.fasl"[0m. The compiled file is then loaded. When [47m[include-book][0m is used later on [47m"my-book"[0m it will automatically load the compiled file, provided the compiled file has a later write date than the source file. The only effect of such [compilation] and loading is that the functions defined in the book execute faster. See [guard] for a discussion of the issues, and if you want more details about [books] and compilation, see [book-compiled-file]. When [47mcertify-book[0m is directed not to produce a compiled file, it will delete any existing compiled file for the book, so as not to mislead [47m[include-book][0m into loading the now outdated compiled file. Otherwise, [47mcertify-book[0m will create a temporary ``expansion file'' to compile, obtained by appending the string "@expansion.lsp" to the end of the book's filename. Remark: Users may ignore that file, which is automatically deleted unless [state] global variable [47m'save-expansion-file[0m has been set, presumably by a system developer, to a non-[47mnil[0m value; see [book-compiled-file] for more information about this issue, including the role of environment variable [47mACL2_SAVE_EXPANSION[0m. After execution of a [47mcertify-book[0m form, the value of [47m[ACL2-defaults-table][0m is restored to what it was immediately before that [47mcertify-book[0m form was executed. See [ACL2-defaults-table]. Those who use the relatively advanced features of trust tags (see [defttag]) and [47m[make-event][0m may wish to know how to create a [certificate] file that avoids dependence on trust tags that are used only during [47m[make-event][0m expansion. For this, including documentation of the [47m:acl2x[0m and [47m:ttagsx[0m keyword arguments for [47mcertify-book[0m, see [set-write-ACL2x]. This completes the tour through the [documentation] of [books]. Subtopics [Certify-book!] A variant of [47m[certify-book][0m [Certify-book-debug] Some possible ways to work around [47m[certify-book][0m failures [Fast-cert] A mode for faster, but possibly unsound, book certification [Useless-runes] Speed up proofs by disabling useless [rune]s") (certify-book! (certify-book) "A variant of [47m[certify-book][0m Examples: (certify-book! "my-arith" 3) ;Certify in a world with 3 ; commands, starting in a world ; with at least 3 commands. (certify-book! "my-arith") ;Certify in the initial world. General Form: (certify-book! book-name k compile-flg) where [47mbook-name[0m is a book filename, [47mk[0m is a nonnegative integer used to indicate the ``certification [world],'' and [47mcompile-flg[0m indicates whether you wish to compile the (functions in the) book. This [command] is identical to [47m[certify-book][0m, except that the second argument [47mk[0m may not be [47mt[0m in [47mcertify-book![0m and if [47mk[0m exceeds the current [command] number, then an appropriate [47m[ubt!][0m will be executed first. See [certify-book] and see [ubt!].") (certify-book-debug (certify-book books-reference) "Some possible ways to work around [47m[certify-book][0m failures This topic provides some ideas for how to deal with [47m[certify-book][0m failures. Ideally, this topic will continue to grow over time. Stack overflows may show up as follows. *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Stack overflow on value stack. *********************************************** When this occurs during book certification, it could be during an attempt to handle large objects, in particular by the [serialize] writer or by a [memoize]d version of the check for ``bad'' objects. These two potential causes can be remedied by first evaluating the following forms, respectively. (set-serialize-character-system nil state) (set-bad-lisp-consp-memoize nil) If the large object is in an event in the book under certification, then you may need to avoid printing it, as follows. (set-inhibit-output-lst '(proof-tree event)) Other failures of [47mcertify-book[0m may have error messages that point to the problem. When that is not the case, it would be good to explain possible workarounds in this topic!") (certify-book-failure (pointers) "See [certify-book-debug].") (certifying-books (pointers) "See [books-certification].") (change (defrec acl2-built-ins) "Mutator macro for [defrec] structures. The [47mchange[0m macro is built into ACL2, and allows you to "modify" instances of structures that have been introduced with [defrec]. Of course, since ACL2 is applicative, the original structure is not actually changed---instead, a new structure is constructed, copying some fields from the original structure and installing new values for other fields. For instance, suppose we first use [make] to create an employee structure, e.g.,: (defconst *jimmy* (make employee :name "Jimmy" :salary 0 :position "Unpaid Intern") Then we can use [47mchange[0m to mutate this structure, e.g.,: (change employee *jimmy* :salary 300000 :position "Vice President") Produces a new [47memployee[0m structure where the [47mname[0m is still "Jimmy", but where the [47msalary[0m and [47mposition[0m have been updated to 300000 and "Vice President", respectively. See [defrec] for more information.") (char (strings characters acl2-built-ins) "The [nth] element (zero-based) of a string [47m(Char s n)[0m is the [47mn[0mth element of [47ms[0m, zero-based. If [47mn[0m is greater than or equal to the length of [47ms[0m, then [47mchar[0m returns [47mnil[0m. [47m(Char s n)[0m has a [guard] that [47mn[0m is a non-negative integer and [47ms[0m is a [47m[stringp][0m. [47mChar[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<char> (defun char (s n) (declare (xargs :guard (and (stringp s) (integerp n) (>= n 0) (< n (length s))))) (nth n (coerce s 'list)))") (char-code (characters numbers acl2-built-ins) "The numeric code for a given character This function maps a character to its code, for example: [47m(char-code #\A)[0m evaluates to [47m65[0m. See [47m[code-char][0m for a sort of inverse function, which maps a code to the corresponding character. Completion Axiom ([47mcompletion-of-char-code[0m): (equal (char-code x) (if (characterp x) (char-code x) 0)) [Guard] for [47m(char-code x)[0m: (characterp x) This function maps all non-characters to [47m0[0m.") (char-downcase (characters acl2-built-ins) "Turn upper-case [characters] into lower-case [characters] [47m(Char-downcase x)[0m is equal to [47m#\a[0m when [47mx[0m is [47m#\A[0m, [47m#\b[0m when [47mx[0m is [47m#\B[0m, ..., and [47m#\z[0m when [47mx[0m is [47m#\Z[0m, and is [47mx[0m for any other character. The [guard] for [47mchar-downcase[0m states that its argument is a character. [47mChar-downcase[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<char-downcase> (defun char-downcase (x) (declare (xargs :guard (characterp x))) (cond ((standard-char-p x) (let ((pair (assoc x '((#\A . #\a) (#\B . #\b) (#\C . #\c) (#\D . #\d) (#\E . #\e) (#\F . #\f) (#\G . #\g) (#\H . #\h) (#\I . #\i) (#\J . #\j) (#\K . #\k) (#\L . #\l) (#\M . #\m) (#\N . #\n) (#\O . #\o) (#\P . #\p) (#\Q . #\q) (#\R . #\r) (#\S . #\s) (#\T . #\t) (#\U . #\u) (#\V . #\v) (#\W . #\w) (#\X . #\x) (#\Y . #\y) (#\Z . #\z))))) (cond (pair (cdr pair)) (t x)))) (t (char-downcase-non-standard x))))") (char-equal (characters acl2-built-ins) "Character equality without regard to case For [characters] [47mx[0m and [47my[0m, [47m(char-equal x y)[0m is true if and only if [47mx[0m and [47my[0m are the same except perhaps for their case. The [guard] on [47mchar-equal[0m states that its arguments are both [characters]. [47mChar-equal[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<char-equal> (defun char-equal (x y) (declare (xargs :guard (and (characterp x) (characterp y)))) (eql (char-downcase x) (char-downcase y)))") (char-upcase (characters acl2-built-ins) "Turn lower-case [characters] into upper-case [characters] [47m(Char-upcase x)[0m is equal to [47m#\A[0m when [47mx[0m is [47m#\a[0m, [47m#\B[0m when [47mx[0m is [47m#\b[0m, ..., and [47m#\Z[0m when [47mx[0m is [47m#\z[0m, and is [47mx[0m for any other character. The [guard] for [47mchar-upcase[0m states that its argument is a character. [47mChar-upcase[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<char-upcase> (defun char-upcase (x) (declare (xargs :guard (characterp x))) (cond ((standard-char-p x) (let ((pair (assoc x '((#\a . #\A) (#\b . #\B) (#\c . #\C) (#\d . #\D) (#\e . #\E) (#\f . #\F) (#\g . #\G) (#\h . #\H) (#\i . #\I) (#\j . #\J) (#\k . #\K) (#\l . #\L) (#\m . #\M) (#\n . #\N) (#\o . #\O) (#\p . #\P) (#\q . #\Q) (#\r . #\R) (#\s . #\S) (#\t . #\T) (#\u . #\U) (#\v . #\V) (#\w . #\W) (#\x . #\X) (#\y . #\Y) (#\z . #\Z))))) (cond (pair (cdr pair)) (t x)))) (t (char-upcase-non-standard x))))") (char< (characters acl2-built-ins) "Less-than test for [characters] [47m(char< x y)[0m is true if and only if the character code of [47mx[0m is less than that of [47my[0m. See [char-code]. The [guard] for [47mchar<[0m specifies that its arguments are [characters]. [47mChar<[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<char<> (defun char< (x y) (declare (xargs :guard (and (characterp x) (characterp y)))) (< (char-code x) (char-code y)))") (char<= (characters acl2-built-ins) "Less-than-or-equal test for [characters] [47m(char<= x y)[0m is true if and only if the character code of [47mx[0m is less than or equal to that of [47my[0m. See [char-code]. The [guard] for [47mchar<=[0m specifies that its arguments are [characters]. [47mChar<=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<char<=> (defun char<= (x y) (declare (xargs :guard (and (characterp x) (characterp y)))) (<= (char-code x) (char-code y)))") (char> (characters acl2-built-ins) "Greater-than test for [characters] [47m(char> x y)[0m is true if and only if the character code of [47mx[0m is greater than that of [47my[0m. See [char-code]. The [guard] for [47mchar>[0m specifies that its arguments are [characters]. [47mChar>[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<char>> (defun char> (x y) (declare (xargs :guard (and (characterp x) (characterp y)))) (> (char-code x) (char-code y)))") (char>= (characters acl2-built-ins) "Greater-than-or-equal test for [characters] [47m(char>= x y)[0m is true if and only if the character code of [47mx[0m is greater than or equal to that of [47my[0m. See [char-code]. The [guard] for [47mchar>=[0m specifies that its arguments are [characters]. [47mChar>=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<char>=> (defun char>= (x y) (declare (xargs :guard (and (characterp x) (characterp y)))) (>= (char-code x) (char-code y)))") (character-alistp (characters alists acl2-built-ins) "Recognizer for association lists with characters as keys [47m(Character-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of the form [47m(cons key val)[0m where [47mkey[0m is a [47m[characterp][0m. [31;1mFunction: [0m<character-alistp> (defun character-alistp (x) (declare (xargs :guard t)) (cond ((atom x) (eq x nil)) (t (and (consp (car x)) (characterp (car (car x))) (character-alistp (cdr x))))))") (character-encoding (io) "How bytes are parsed into characters When the Common Lisp reader comes across bytes in a file or at the terminal, they are parsed into characters. The simplest case is when each byte that is read is a standard character (see [standard-char-p]). It is actually quite common that each byte that is read corresponds to a single character. The parsing of bytes into characters is based on a [3mcharacter encoding[0m, that is, a mapping that associates one or more bytes with each legal character. In order to help guarantee the portability of files (including [books]), ACL2 installs a common character encoding for reading files, often known as ISO-8859-1 or Latin-1. For some host Lisps this character encoding is also used for reading from the terminal; but, sadly, this may not hold for all host Lisps, and may not even be possible for some of them. The use of the above encoding could in principle cause problems if one's editor produces files using an encoding other than ISO-8859-1, at least if one uses non-standard characters. In particular, the default Emacs buffer encoding may be utf-8. If your file has non-standard characters, then in Emacs you can evaluate the form (setq save-buffer-coding-system 'iso-8859-1) before saving the buffer into a file. This will happen automatically for users who load distributed file [47memacs-acl2.el[0m (from a suitable directory; see [emacs]) into their Emacs sessions. For an example of character encodings in action, see the community book [47mbooks/misc/character-encoding-test.lisp[0m.") (character-listp (characters lists acl2-built-ins) "Recognizer for a true list of characters The predicate [47mcharacter-listp[0m tests whether its argument is a true list of [characters]. [31;1mFunction: [0m<character-listp> (defun character-listp (l) (declare (xargs :guard t)) (cond ((atom l) (equal l nil)) (t (and (characterp (car l)) (character-listp (cdr l))))))") (characterp (characters acl2-built-ins) "Recognizer for [characters] [47m(characterp x)[0m is true if and only if [47mx[0m is a character. Note that ACL2 supports characters with ASCII codes between 0 and 255. See also [code-char] and [char-code].") (characters (programming) "Characters in ACL2 and operations on them ACL2 accepts 256 distinct characters, which are the characters obtained by applying the function [47m[code-char][0m to each integer from [47m0[0m to [47m255[0m. Among these, Common Lisp designates certain ones as [3mstandard characters[0m, namely those of the form [47m(code-char n)[0m where [47mn[0m is from [47m33[0m to [47m126[0m, together with [47m#\Newline[0m and [47m#\Space[0m. The actual standard characters may be viewed by evaluating the [47m[defconst][0m [47m*standard-chars*[0m. To be more precise, Common Lisp does not specify the precise relationship between [47m[code-char][0m and the standard characters. However, we check that the underlying Common Lisp implementation uses a particular relationship that extends the usual ASCII coding of characters. We also check that Space, Tab, Newline, Page, Rubout, and Return correspond to characters with respective [47m[char-code][0ms [47m32[0m, [47m9[0m, [47m10[0m, [47m12[0m, [47m127[0m, and [47m13[0m. [47m[Code-char][0m has an inverse, [47m[char-code][0m. Thus, when [47m[char-code][0m is applied to an ACL2 character, [47mc[0m, it returns a number [47mn[0m between [47m0[0m and [47m255[0m inclusive such that [47m(code-char n)[0m = [47mc[0m. The preceding paragraph implies that there is only one ACL2 character with a given character code. CLTL allows for ``attributes'' for characters, which could allow distinct characters with the same code, but ACL2 does not allow this. [3mThe Character Reader[0m ACL2 supports the `[47m#\[0m' notation for characters provided by Common Lisp, with some restrictions. First of all, for every character [47mc[0m, the notation #\c may be used to denote the character object [47mc[0m. That is, the user may type in this notation and ACL2 will read it as denoting the character object [47mc[0m. In this case, the character immediately following [47mc[0m must be one of the following ``terminating characters'': a Tab, a Newline, a Page character, a space, or one of the characters: " ' ( ) ; ` , Other than the notation above, ACL2 accepts alternate notation for five characters. #\Space #\Tab #\Newline #\Page #\Rubout #\Return Again, in each of these cases the next character must be from among the set of ``terminating characters'' described in the single-character case. Our implementation is consistent with ISO-8859-1, even though we don't provide [47m#\[0m syntax for entering characters other than that described above. Finally, we note that it is our intention that any object printed by ACL2's top-level-loop may be read back into ACL2. Please notify the implementors if you find a counterexample to this claim. Subtopics [Alpha-char-p] Recognizer for alphabetic characters [Char] The [nth] element (zero-based) of a string [Char-code] The numeric code for a given character [Char-downcase] Turn upper-case [characters] into lower-case [characters] [Char-equal] Character equality without regard to case [Char-upcase] Turn lower-case [characters] into upper-case [characters] [Char<] Less-than test for [characters] [Char<=] Less-than-or-equal test for [characters] [Char>] Greater-than test for [characters] [Char>=] Greater-than-or-equal test for [characters] [Character-alistp] Recognizer for association lists with characters as keys [Character-listp] Recognizer for a true list of characters [Characterp] Recognizer for [characters] [Code-char] The character corresponding to a given numeric code [Coerce] Coerce a character list to a string and a string to a list [Digit-char-p] The number, if any, corresponding to a given character [Digit-to-char] Map a digit to a character [Explode-atom] Convert any [atom] into a [character-listp] that contains its printed representation, rendering numbers in your choice of print base. [Explode-nonnegative-integer] The list of [characters] in the radix-r form of a number [Lower-case-p] Recognizer for lower case characters [Make-character-list] [coerce] to a list of characters [Standard-char-listp] Recognizer for a true list of standard characters [Standard-char-p] Recognizer for standard characters [Standard-char-p+] Recognizer for standard characters whose guard is [47mt[0m [Upper-case-p] Recognizer for upper case characters") (check-invariant-risk (pointers) "See [set-check-invariant-risk].") (check-sum (pointers) "See [checksum].") (check-vars-not-free (macros) "Avoid variable capture in macro calls [47mCheck-vars-not-free[0m is a macro that is useful for avoiding capture of variables in macro calls. We explain using a running example, after which we give a precise explanation (at the end of this documentation topic). These definitions are rather contrived but are designed to illustrate how [47mcheck-vars-not-free[0m can be useful. (defmacro has-length (x n) `(let ((k (len ,x))) (equal k ,n))) (defun f1 (u v) (and (natp v) (has-length u (* 2 v)))) (defun f2 (lst k) (and (natp k) (has-length lst (* 2 k)))) One might expect [47mf1[0m and [47mf2[0m to be the same function, since the only change seems to be from the choices of formal parameters. However, consider these evaluations. ACL2 !>(f1 '(a b c d e f) 3) T ACL2 !>(f2 '(a b c d e f) 3) NIL ACL2 !> The problem becomes clear if we expand the macro call in the body of [47mf2[0m. ACL2 !>:trans1 (has-length lst (* 2 k)) (LET ((K (LEN LST))) (EQUAL K (* 2 K))) ACL2 !> We see that when expanding the call of the macro [47mhas-length[0m in the body of [47mf2[0m, the substitution of [47m(* 2 k)[0m for [47m,n[0m causes [47mk[0m to be``captured'' by the binding of [47mk[0m to [47m(len lst)[0m. The macro [47mcheck-vars-not-free[0m is designed to enforce that no such capture takes place. An improved definition of [47mhas-length[0m is as follows, since it insists that the variable [47mk[0m must not appear in the term that replaces [47m,n[0m. (defmacro has-length (x n) `(let ((k (len ,x))) (equal k (check-vars-not-free (k) ,n)))) Now, the attempt to define [47mf2[0m as above causes an error. ACL2 !>(defun f2 (lst k) (and (natp k) (has-length lst (* 2 k)))) ACL2 Error in ( DEFUN F2 ...): CHECK-VARS-NOT-FREE failed: It is forbidden to use K in (BINARY-* '2 K). Note: this error occurred in the context (CHECK-VARS-NOT-FREE (K) (* 2 K)). Summary Form: ( DEFUN F2 ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Error in ( DEFUN F2 ...): See :DOC failure. ******** FAILED ******** ACL2 !> The error message shows that the check performed by [47mcheck-vars-not-free[0m has failed, because the variable [47mk[0m occurs in the expression [47m(* 2 k)[0m. More precisely, what is checked is that [47mk[0m does not occur in the translation to a [term] of the expression [47m(* 2 k)[0m, namely, [47m(binary-* '2 k)[0m. The general form of a call of [47mcheck-vars-not-free[0m is (check-vars-not-free (var_1 ... var_n) expr) where [47mvar_1[0m, ..., [47mvar_n[0m are variables and [47mexpr[0m is an expression. This call is equivalent to [47mexpr[0m --- indeed, there is no effect on the code generated when using this call in place of [47mexpr[0m --- but ACL2 requires that the indicated variables do not occur free in the translation of [47mexpr[0m to a term.") (checkpoint-forced-goals (proof-tree) "Cause forcing goals to be checkpointed in proof trees Example forms: (checkpoint-forced-goals t) (checkpoint-forced-goals nil) Also see [proof-tree]. By default, goals are not marked as checkpoints by a proof tree display (as described elsewhere; see [proof-tree]) merely because they [force] some hypotheses, thus possibly contributing to a forcing round. However, some users may want such behavior, which will occur once the command [47m(checkpoint-forced-goals[0m [47mt[0m) has been executed. To return to the default behavior, use the command [47m(checkpoint-forced-goals nil)[0m.") (checkpoint-summary-limit (summary set-gag-mode) "Control printing of key checkpoints upon a proof's failure See [set-checkpoint-summary-limit] for a discussion of the checkpoint-summary-limit. Evaluation of the form [47m(checkpoint-summary-limit)[0m produces the current checkpoint-summary-limit, and can be invoked with the keyword hack (see [keyword-commands]). For example: ACL2 !>:checkpoint-summary-limit (NIL . 3) ACL2 !>") (checksum (certificate) "Assigning ``often unique'' integers to files and objects See [book-hash] for a discussion of how ACL2 can use checksums (though not by default) to increase security in the [books] mechanism. A [3mchecksum[0m is an integer in some fixed range computed from the printed representation of an object, e.g., the sum, modulo [47m2**32[0m, of the ascii codes of all the [characters] in the printed representation. Ideally, you would like the checksum of an object to be uniquely associated with that object, like a fingerprint. It could then be used as a convenient way to recognize the object in the future: you could remember the checksum (which is relatively small) and when an object is presented to you and alleged to be the special one you could compute its checksum and see if indeed it was. Alas, there are many more objects than checksums (after all, each checksum is an object, and then there's [47mt[0m). So you try to design a checksum algorithm that maps similar looking objects far apart, in the hopes that corruptions and counterfeits --- which appear to be similar to the object --- have different checksums. Nevertheless, the best you can do is a many-to-one map. If an object with a different checksum is presented, you can be positive it is not the special object. But if an object with the same checksum is presented, you have no grounds for positive identification. The basic checksum algorithm in ACL2 is called [47mcheck-sum-obj[0m, which computes the checksum of an ACL2 object. Roughly speaking, we scan the print representation of the object and, for each character encountered, we multiply the ascii code of the character times its position in the stream (modulo a certain prime) and then add (modulo a certain prime) that into the running sum. This is inaccurate in many senses (for example, we don't always use the ascii code and we see numbers as though they were printed in base 127) but indicates the basic idea.") (clause (miscellaneous) "A representation of prover goals In ACL2, a [3mclause[0m is a list of [term]s, and the meaning of a clause is the ACL2 disjunction of those terms where a term [47mp[0m is considered ``false'' if ``[47mp[0m = [47mnil[0m'' and is true otherwise. The elements of a clause are called ``literals,'' even though they are just terms. For example the goal [47m(IMPLIES (AND p q) r)[0m is internally represented as the clause [47m((NOT p) (NOT q) r)[0m. The literals of that clause are the terms [47m(NOT p)[0m, [47m(NOT q)[0m, and [47mr[0m. The ACL2 prover acts on clauses: a goal is represented as a clause, and each of the resulting subgoals is represented as a clause. Thus, the terms (literals) in a clause are all translated (see [term]). To be precise, suppose that [47m(L1 .. Lk M)[0m is a clause containing at least two literals. ACL2 proof output displays that clause as an implication; this is called ``prettyifying a clause''. Below, [47m~Li[0m denotes the [3mnegation[0m of [47mLi[0m in the following sense: if [47mLi[0m is of the form [47m(NOT P)[0m then [47m~Li[0m designates [47mP[0m, and otherwise [47m~Li[0m designates [47m(NOT Li)[0m. [31;1mPrettyifying a clause with at least two literals[0m (L1 .. Lk M) transforms it to the term (IMPLIES (AND ~L1 ~L2 ... ~Lk) M). Of course, the disjunction represented by the clause is propositionally equivalent to the resulting call of [47mIMPLIES[0m. It is sometimes helpful to understand that ACL2's proof processes all operate on clauses. In particular, proof output --- obtained when [gag-mode] is turned off or when using [47m:[0m[47m[pso][0m or related utilities --- may include a parenthetical remark as follows. [31;1mWARNING[0m: This parenthetical remark is printed only by the main simplifier, not by the preprocessor (see [simple]). This simplifies (dropping false conclusion; see :DOC clause), using .... What this remark signifies is that the last literal of the clause is false in at least one subgoal, and therefore does not appear in it (even in rewritten form). Let's see how that works with the following example. (defstub foo (x) t) (defaxiom foo-consp (implies (consp x) (foo x))) (set-gag-mode nil) (thm (implies (and (consp x) (natp (car x))) (not (foo x)))) The proof attempt starts as follows. ACL2 !>(thm (implies (and (consp x) (natp (car x))) (not (foo x)))) By the simple :definition NATP we reduce the conjecture to Goal' (IMPLIES (AND (CONSP X) (INTEGERP (CAR X)) (<= 0 (CAR X))) (NOT (FOO X))). This simplifies (dropping false conclusion; see :DOC clause), using the :rewrite rule FOO-CONSP, to Goal'' (IMPLIES (AND (CONSP X) (INTEGERP (CAR X))) (< (CAR X) 0)). The change from [47mGoal'[0m to [47mGoal''[0m may be jarring because the ``conclusion'' --- the second argument of the displayed [47mIMPLIES[0m call --- has changed drastically. Let's analyze this change from the perspective of the goals printed; then we'll look at it from the perspective of clauses. A moment's reflection shows that because of the rule [47mFOO-CONSP[0m, [47mGoal'[0m is equivalent to (IMPLIES (AND (CONSP X) (INTEGERP (CAR X)) (<= 0 (CAR X))) NIL). And a little more reflection shows that the term above is propositionally equivalent to [47mGoal''[0m above. But this may make more sense if we consider the clauses on which the prover operated. Here are the clauses for [47mGoal'[0m and [47mGoal''[0m; the corresponding [47mIMPLIES[0m terms displayed above are obtained by prettyifying the respective clauses (in the sense of ``prettyifying'' discussed above). Goal' ((NOT (CONSP X)) (NOT (INTEGERP (CAR X))) (< (CAR X) '0) (NOT (FOO X))) Goal'' ((NOT (CONSP X)) (NOT (INTEGERP (CAR X))) (< (CAR X) '0)) For each of these clauses, the third literal, [47m(< (CAR X) '0)[0m, is just the negation of the (untranslated) [term], [47m(<= 0 (CAR X))[0m, shown in the prover output. Recall that a clause represents the disjunction of its literals. Since the last literal of [47mGoal'[0m, [47m(NOT (FOO X))[0m, rewrote to [47mNIL[0m using the rule [47mFOO-CONSP[0m, it was dropped when creating [47mGoal''[0m: after all, [47m(OR P NIL)[0m is propositionally equivalent to [47mP[0m. So in [47mGoal''[0m the last literal is [47m(< (CAR X) '0)[0m. Therefore, the conclusion of each [47mIMPLIES[0m term obtained by prettyifying the clause has changed from [47m(NOT (FOO X))[0m to [47m(< (CAR X) '0)[0m. Finally, note that although ``dropping false conclusion'' signifies that the conclusion was dropped in at least one subgoal, if however there are at least two subgoals then it might not be dropped in all of them. Consider the following variant of the earlier example. (defstub foo (x) t) (defaxiom foo-consp (implies (consp x) (foo x))) (set-gag-mode nil) (defstub bar (x) t) ; The proof fails for the following event (not important here). (thm (implies (and (or (bar x) (consp x)) (natp (car x))) (not (foo x))) :otf-flg t) The output includes the following. Goal' (IMPLIES (AND (OR (BAR X) (CONSP X)) (INTEGERP (CAR X)) (<= 0 (CAR X))) (NOT (FOO X))). This simplifies (dropping false conclusion; see :DOC clause), using the :rewrite rule FOO-CONSP, to the following two conjectures. Subgoal 2 (IMPLIES (AND (BAR X) (INTEGERP (CAR X)) (<= 0 (CAR X))) (NOT (FOO X))). [[.. output elided ..]] Subgoal 1 (IMPLIES (AND (CONSP X) (INTEGERP (CAR X))) (< (CAR X) 0)). We see that the conclusion was false, hence dropped, in Subgoal 1, but remained in Subgoal 2.") (clause-identifier (goal-spec) "The internal form of a [goal-spec] To each goal-spec, [47mstr[0m, there corresponds a [clause]-identifier produced by [47m(parse-clause-id str)[0m. For example, (parse-clause-id "[2]Subgoal *4.5.6/7.8.9'''") returns [47m((2 4 5 6) (7 8 9) . 3)[0m. The function [47mstring-for-tilde-@-clause-id-phrase[0m inverts [47mparse-clause-id[0m in the sense that given a clause identifier it returns the corresponding goal-spec. As noted in the documentation for [goal-spec], each clause printed in the theorem prover's proof attempt is identified by a name. When these names are represented as strings they are called ``goal specs.'' Such strings are used to specify where in the proof attempt a given hint is to be applied. The function [47mparse-clause-id[0m converts goal-specs into clause identifiers, which are cons-trees containing natural numbers (and if [47m:OR[0m [hints] are used, they may also contain symbols of the form [47mDn[0m where [47mn[0m is a natural number, e.g., [47mD23[0m.) Examples of goal-specs and their corresponding clause identifiers are shown below. parse-clause-id --> "Goal" ((0) NIL . 0) "Subgoal 3.2.1'" ((0) (3 2 1) . 1) "[2]Subgoal *4.5.6/7.8.9'''" ((2 4 5 6) (7 8 9) . 3) <-- string-for-tilde-@-clause-id-phrase The caar of a clause id specifies the forcing round, the cdar specifies the goal being proved by induction, the cadr specifies the particular subgoal, and the cddr is the number of primes in that subgoal. Internally, the system maintains clause ids, not goal-specs. The system prints clause ids in the form shown by goal-specs. When a goal-spec is used in a hint, it is parsed (before the proof attempt begins) into a clause id. During the proof attempt, the system watches for the clause id and uses the corresponding hint when the id arises. (Because of the expense of creating and garbage collecting a lot of strings, this design is more efficient than the alternative.)") (clause-processor (rule-classes) "Make or apply a [47m:clause-processor[0m rule (goal-level simplifier) See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. We will introduce clause-processor rules by way of the following example. But note that the clause-processor utility is more general than this example may suggest; for example, the second argument of [47mevl0[0m in the hypothesis need not be the same as its second argument in the conclusion. ; Example (which we'll return to, below): (defthm correctness-of-note-fact-clause-processor (implies (and (pseudo-term-listp cl) (alistp a) (evl0 (conjoin-clauses (note-fact-clause-processor cl term)) a)) (evl0 (disjoin cl) a)) :rule-classes :clause-processor) We begin this documentation with an introduction, focusing on the example above, and then conclude with a detailed general discussion of clause-processor rules. You might find it most useful simply to look at the examples in community books directory [47mbooks/clause-processors/[0m; see file [47mReadme.lsp[0m in that directory. Also see [define-trusted-clause-processor] for documentation of an analogous utility that does not require the clause-processor to be proved correct. But please read the present documentation before reading about that utility. Both utilities designate functions as ``clause-processors''. Such functions must be executable --- hence not constrained by virtue of being introduced in the [signature] of an [47m[encapsulate][0m --- and must respect [stobj], [df], and output arity restrictions. For example, something like [47m(car (mv ...))[0m is illegal; also see [signature]. INTRODUCTION A [47m:clause-processor[0m rule installs a simplifier at the level of goals, where a goal is represented as a [clause]: a list of [term]s that is implicitly viewed as a disjunction (the application of [47m[or][0m). For example, if ACL2 prints a goal in the form [47m(implies (and p q) r)[0m, then the clause might be the one-element list containing the internal representation of this term --- [47m(implies (if p q 'nil) r)[0m --- but more likely, the corresponding clause is [47m((not p) (not q) r)[0m. Note that the members of a clause are [3mtranslated[0m terms; see [term] and [47m[termp][0m. For example, they do not contain calls of the macro [47mAND[0m, and constants are quoted. The result of running a clause-processor must be a list of legal clauses; see [meta] for a discussion of translated terms, and for related discussion about ``forbidden'' function symbols, [set-skip-meta-termp-checks]. The recognizer for a clause is the function [47m[term-listp][0m and the recognizer for a list of clauses is [47m[term-list-listp][0m. Note that clause-processor simplifiers are similar to metafunctions, and similar efficiency considerations apply. See [meta], in particular the discussion on how to ``make a metafunction maximally efficient.'' Unlike rules of class [47m:[0m[47m[meta][0m, rules of class [47m:clause-processor[0m must be applied by explicit [47m:clause-processor[0m [hints]; they are not applied automatically (unless by way of computed hints; see [computed-hints]). But [47m:clause-processor[0m rules can be useful in situations for which it is more convenient to code a simplifier that manipulates the entire goal clause rather than individual subterms of terms in the clause. We begin with a simple illustrative example: a clause-processor that assumes an alleged fact (named [47mterm[0m in the example) and creates a separate goal to prove that fact. We can extend the hypotheses of the current goal (named [47mcl[0m in the example) with a term by adding the negation of that term to the clause (disjunctive) representation of that goal. So the following returns a list of two clauses: the result of adding [47mterm[0m as a hypothesis to the input clause, as just described, and a second clause consisting only of that term. This list of two clauses can be viewed as the conjunction of the first clause and the second clause (where again, each clause is viewed as a disjunction). (defun note-fact-clause-processor (cl term) (declare (xargs :guard t)) ; optional, for better efficiency (list (cons (list 'not term) cl) (list term))) As with [47m:[0m[47m[meta][0m rules, we need to introduce a suitable evaluator; see [defevaluator] if you want details. Since we expect to reason about the function [47m[not][0m, because of its role in [47mnote-fact-clause-processor[0m as defined above, we include [47mNOT[0m in the set of functions known to this evaluator. We also include [47mIF[0m, as is often a good idea. (defevaluator evl0 evl0-list ((not x) (if x y z))) ACL2 can now prove the following theorem automatically. (This is the example displayed at the outset of this [documentation] topic.) Of course, [47m:clause-processor[0m rules about clause-processor functions less trivial than [47mnote-fact-clause-processor[0m may require lemmas to be proved first! The function [47mdisjoin[0m takes a clause and returns its disjunction (the result of applying [47m[or][0m to its members), and [47mconjoin-clauses[0m applies [47mdisjoin[0m to every element of a given list of clauses and then conjoins (applies [47mAND[0m) to the corresponding list of resulting terms. (defthm correctness-of-note-fact-clause-processor (implies (and (pseudo-term-listp cl) (alistp a) (evl0 (conjoin-clauses (note-fact-clause-processor cl term)) a)) (evl0 (disjoin cl) a)) :rule-classes :clause-processor) Now let us submit a silly but illustrative example theorem to ACL2, to show how a corresponding [47m:clause-processor[0m hint is applied. The hint says to apply the clause-processor function, [47mnote-fact-clause-processor[0m, to the current goal clause and a ``user hint'' as the second argument of that function, in this case [47m(equal a a)[0m. Thus, a specific variable, [47mclause[0m, is always bound to the current goal clause for the evaluation of the [47m:clause-processor[0m hint, to produce a list of clauses. Since two subgoals are created below, we know that this list contained two clauses. Indeed, these are the clauses returned when [47mnote-fact-clause-processor[0m is applied to two arguments: the current clause, which is the one-element list [47m((equal (car (cons x y)) x))[0m, and the user hint, [47m(equal a a)[0m. ACL2 !>(thm (equal (car (cons x y)) x) :hints (("Goal" :clause-processor (note-fact-clause-processor clause '(equal a a))))) [Note: A hint was supplied for the goal above. Thanks!] We now apply the verified :CLAUSE-PROCESSOR function NOTE-FACT-CLAUSE- PROCESSOR to produce two new subgoals. Subgoal 2 (IMPLIES (EQUAL A A) (EQUAL (CAR (CONS X Y)) X)). But we reduce the conjecture to T, by the :executable-counterpart of IF and the simple :rewrite rule CAR-CONS. Subgoal 1 (EQUAL A A). But we reduce the conjecture to T, by primitive type reasoning. Q.E.D. Summary Form: ( THM ...) Rules: ((:EXECUTABLE-COUNTERPART IF) (:EXECUTABLE-COUNTERPART NOT) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:REWRITE CAR-CONS)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Proof succeeded. ACL2 !> That concludes our introduction to clause-processor rules and hints. We turn now to detailed documentation. DETAILED DOCUMENTATION The [signature] of a clause-processor function, [47mCL-PROC[0m, must have one of the following forms. Here, each [47mst_i[0m is a [stobj] (possibly [47m[state][0m) while the other parameters and results are not stobjs (see [stobj]). Note that there need not be input stobjs in [3] --- i.e., [47mk[0m can be 0 --- and even if there are, there need not be output stobjs. In most ways [3] and [3+] are treated similarly; see [make-summary-data] for a discussion of the form of [47md[0m in [3+] and, more generally, for how [3+] differs from [3] by enhancing the [summary]. [1] ((CL-PROC cl) => cl-list) [2] ((CL-PROC cl hint) => cl-list) [3] ((CL-PROC cl hint st_1 ... st_k) => (mv erp cl-list st_i1 ... st_in)) [3+] ((CL-PROC cl hint st_1 ... st_k) => (mv erp cl-list st_i1 ... st_in d)) We call [47mcl-list[0m the [3mclauses-result[0m. In [3] and [3+], we think of the first component of the result as an error flag. Indeed, a proof will instantly abort if that error flag is not [47mnil[0m. We next discuss the legal forms of [47m:clause-processor[0m rules, followed below by a discussion of [47m:clause-processor[0m [hints]. In the discussion below, we use lower-case names to represent specific symbols, for example [47mimplies[0m, and also to represent [stobj] names; and we use upper-case names to represent arbitrary pieces of syntax (which we will describe), for example, [47mCL[0m. If a [47m:[0m[47m[rule-classes][0m specification includes [47m:clause-processor[0m, then the corresponding term must have the following form. (Additional ``meta-extract'' hypotheses, not shown or discussed below, may be included as desired in order to use facts from the logical [47m[world][0m to help prove the rule; see [meta-extract] for explanation of this advanced feature.) ; General Form (omitting possible meta-extract hypotheses) (implies (and (pseudo-term-listp CL) (alistp A) (EVL (conjoin-clauses <CL-LIST>) B)) (EVL (disjoin CL) A)) Here [47mEVL[0m is a known evaluator; [47mCL[0m and [47mA[0m are distinct non-stobj variables; and [47m<CL-LIST>[0m is an expression representing the clauses returned by the clause-processor function [47mCL-PROC[0m, whose form depends on the [signature] of that function, as follows. Typically [47mB[0m is [47mA[0m, but it can be any term (useful when generalization is occurring; see the example ``Test generalizing alist'' in community book [47mbooks/clause-processors/basic-examples.lisp[0m). For cases [1] and [2] above, [47m<CL-LIST>[0m is of the form [47m(CL-PROC CL)[0m or [47m(CL-PROC CL HINT)[0m, respectively, where in the latter case [47mHINT[0m is a non-stobj variable distinct from the variables [47mCL[0m and [47mA[0m. For cases [3] and [3+], [47m<CL-LIST>[0m is the result of wrapping the function [47mclauses-result[0m around a call of [47mCL-PROC[0m: (clauses-result (CL-PROC CL HINT ...)) Logically, [47mclauses-result[0m returns the [47m[cadr][0m if the [47m[car][0m is [47mNIL[0m, and otherwise (for the error case) returns a list containing the empty (false) clause. So in the non-error case, [47mclauses-result[0m picks out the second result, denoted [47mcl-list[0m in [3] and [3+] above, and in the error case the implication above trivially holds. In the above theorem, we are asked to prove [47m(EVL (disjoin CL) A)[0m assuming that the conjunction of all clauses produced by the clause processor evaluates to a non-[47mnil[0m value under some alist [47mB[0m. In fact, we can choose [47mB[0m so as to allow us to assume evaluations of the generated clauses over many different alists. This technique is discussed in the community book [47mbooks/clause-processors/multi-env-trick.lisp[0m, which introduces some macros that may be helpful in accomplishing proofs of this type. The clause-processor function, [47mCL[0m, must have a guard that ACL2 can trivially prove from the hypotheses that the first argument of [47mCL[0m is known to be a [47mpseudo-term-listp[0m and any [stobj] arguments are assumed to satisfy their stobj predicates. Next we specify the legal forms for [47m:clause-processor[0m [hints]. The basic form is [47m:clause-processor TERM[0m, such that the translation of [47mTERM[0m to a legal ACL2 term yields a call of a clause-processor function [47m(CL-PROC clause)[0m or [47m(CL-PROC clause HINT ...)[0m, where [47mHINT[0m is a term whose only non-stobj free variable (if any) is the symbol, [47mclause[0m. Note that the first argument of the call is literally the variable, [47mclause[0m. Recall that at the time the :clause-processor hint is applied to the clausal form [47mCL[0m of the current subgoal, [47mclause[0m is bound to [47mCL[0m; moreover, any stobj names will be bound to the corresponding stobjs. But there are two additional general forms for [47m:clause-processor[0m hints, which may viewed as abbreviations for the basic form discussed above. The first additional general form, which we call the ``[47m:function[0m form'', includes the following two classes of expressions. :clause-processor (:function F) :clause-processor (:function F :hint HINT) The first of these [47m:function[0m forms abbreviates the following hint, where either [47mF[0m is a macro-alias for the function symbol [47mCL-PROC[0m (see [add-macro-alias]), and otherwise [47mCL-PROC[0m is just the function symbol [47mF[0m. :clause-processor (CL-PROC clause) Similarly the second of the [47m:function[0m forms above abbreviates the following, where [47mCL-PROC[0m is as above and the output signature of [47mCL-PROC[0m is [47m(nil nil st_1 ... st_k)[0m. :clause-processor (CL-PROC clause HINT st_1 ... st_k) Besides the ``[47m:function[0m form'', there is one more additional general form for [47m:clause-processor[0m hint: a symbol, as follows. :clause-processor F This expands to a basic form as follows, depending on [47mF[0m. * If [47mF[0m is a macro with one required argument or a function symbol with one argument: [47m:clause-processor (F clause)[0m * If [47mF[0m is a macro with two required arguments or a function symbol with two arguments: [47m:clause-processor (F clause nil)[0m * If [47mF[0m is a function symbol with inputs of the form [3] or [3+] above, that is, with input signature [47m(nil nil st_1 ... st_k)[0m: [47m:clause-processor (F clause nil st_1 ... st_k)[0m For examples of these syntactic forms, see community book [47mbooks/clause-processors/basic-examples.lisp[0m). We turn now to discussion of when a [47m:clause-processor[0m hint causes an abort. A [47m:clause-processor[0m hint causes the proof to abort if the clauses-result is not a list of clauses, i.e., a list of (translated) [term] lists in the current logical [world]. This test is done explicitly every time a clause processor is run unless a [47m:[0m[47m[well-formedness-guarantee][0m has been provided with the [47m:clause-processor[0m rule or [47m[set-skip-meta-termp-checks][0m has been used with an active trust tag to skip the check at the user's risk. The proof also aborts when the clause-processor function returns at least two values and the first value returned --- the ``[47merp[0m'' value from cases [3] and [3+] above --- is not [47mnil[0m. In that case, [47merp[0m is used for printing an error message as follows: if it is a string, then that string is printed; but if it is a non-empty true list whose first element is a string, then it is printed as though by [47m(fmt ~@0 (list (cons #\0 erp)) ...)[0m (see [fmt]). Otherwise, a non-[47mnil[0m [47merp[0m value causes a generic error message to be printed. If there is no error as above, but the [47mCL-PROC[0m call returns a clause list whose single element is equal to the input clause, then the hint is ignored since we are left with the goal with which we started. In that case, the other prover processes are then applied as usual (see [hints-and-the-waterfall]). You can see all current [47m:clause-processor[0m rules by issuing the following command: [47m(print-clause-processor-rules)[0m. The following paper discusses ACL2 clause-processors at a high level suitable for a non-ACL2 audience: M. Kaufmann, J S. Moore, S. Ray, and E. Reeber, ``Integrating External Deduction Tools with ACL2.'' [3mJournal of Applied Logic[0m (Special Issue: Empirically Successful Computerized Reasoning), Volume 7, Issue 1, March 2009, pp. 3--25. Also published online (DOI [47m10.1016/j.jal.2007.07.002[0m). Preliminary version in: Proceedings of the 6th International Workshop on the Implementation of Logics (IWIL 2006) (C. Benzmueller, B. Fischer, and G. Sutcliffe, editors), {CEUR Workshop Proceedings Vol. 212 | http://ceur-ws.org/Vol-212/}, Phnom Penh, Cambodia, pp. 7--26, November 2006. Subtopics [Make-summary-data] Return summary data from a [clause-processor] function [Meta-extract] Meta reasoning using valid terms extracted from context or [world] [Set-skip-meta-termp-checks] Skip output checks for [meta] functions and [clause-processor]s [Set-skip-meta-termp-checks!] Skip output checks non-[local]ly for [meta] functions and [clause-processor]s") (clear-memoize-statistics (memoize) "Clears all profiling info displayed by [47m([0m[47m[memoize-summary][0m[47m)[0m Logically, this function just returns [47mnil[0m. It clears all profiling info displayed by [47m([0m[47m[memoize-summary][0m[47m)[0m [31;1mFunction: [0m<clear-memoize-statistics> (defun clear-memoize-statistics nil (declare (xargs :guard t)) nil)") (clear-memoize-table (memoize) "Forget values remembered for the given function This function returns its argument, [47mfn[0m, unchanged. The values memoized for [47mfn[0m are forgotten. [31;1mFunction: [0m<clear-memoize-table> (defun clear-memoize-table (fn) (declare (xargs :guard t)) fn)") (clear-memoize-tables (memoize) "Forget values remembered for all the memoized functions [47mClear-memoize-tables[0m is a logical no-op. All memoized values are forgotten. It returns [47mnil[0m, invoking [47m[clear-memoize-table][0m for each memoized function. [31;1mFunction: [0m<clear-memoize-tables> (defun clear-memoize-tables nil (declare (xargs :guard t)) nil)") (close-input-channel (pointers) "See [io].") (close-output-channel (pointers) "See [io].") (close-trace-file (trace) "Stop redirecting trace output to a file General Form: (close-trace-file) ; trace output is no longer redirected to a file Output from [47m[trace$][0m normally goes to the screen, or more precisely, [47m[standard-co][0m. It can be redirected to a file; see [open-trace-file]. Use [47mclose-trace-file[0m to redirect trace output to [47m[standard-co][0m.") (code-char (characters numbers acl2-built-ins) "The character corresponding to a given numeric code This function maps a numeric code to the corresponding character, for example: [47m(code-char 65)[0m evaluates to [47m#\A[0m. See [47m[char-code][0m for a sort of inverse function, which maps a character to its code. Completion Axiom ([47mcompletion-of-code-char[0m): (equal (code-char x) (if (and (integerp x) (>= x 0) (< x 256)) (code-char x) (code-char 0))) [Guard] for [47m(code-char x)[0m: (and (integerp x) (>= x 0) (< x 256)) ACL2 supports 8-bit [characters]. Inputs not between [47m0[0m and [47m255[0m are treated as [47m0[0m.") (coerce (strings characters acl2-built-ins) "Coerce a character list to a string and a string to a list Completion Axiom ([47mcompletion-of-coerce[0m): (equal (coerce x y) (cond ((equal y 'list) (if (stringp x) (coerce x 'list) nil)) (t (coerce (make-character-list x) 'string)))) [Guard] for [47m(coerce x y)[0m: (if (equal y 'list) (stringp x) (if (equal y 'string) (character-listp x) nil)) Also see community book [47mbooks/misc/fast-coerce.lisp[0m, contributed by Jared Davis, for a version of [47mcoerce[0m that may be faster for Common Lisp implementations other than CCL 1.3 or later, if the second argument is [47m'list[0m (for coercing a string to a list). Logical Note The function [47mcoerce[0m can be viewed as the constructor for strings. As discussed in Section 7 of "{A Precise Description of the ACL2 Logic | http://www.cs.utexas.edu/users/moore/publications/km97a.pdf}" (Matt Kaufmann and J Moore, April, 1998), a string may be built by coercing its list of characters: for example, [47m"abc"[0m is [47m(coerce '(#\a #\b #\c) 'string)[0m. More precisely, [47m"abc"[0m is an abbreviation for [47m(coerce '(#\a #\b #\c) 'string)[0m, where even more pedantically, [47m'(#\a #\b #\c)[0m is an abbreviation for [47m(cons '#\a (cons '#\b (cons '#\c 'nil)))[0m.") (coherence (pointers) "See [wormhole-status].") (collect$ (pointers) "See [loop$].") (collect$+ (pointers) "See [loop$].") ,(pointers) (comma-atsign (pointers) "See [backquote].") (command (history) "Forms you type at the top-level, but... ...the word ``command'' usually refers to a top-level form whose evaluation produces a new logical [world]. Typical commands are: (defun foo (x) (cons x x)) (defthm consp-foo (consp (foo x))) (defrec pair (hd . tl) nil) The first two forms are examples of commands that are in fact primitive [events]. See [events]. [47mDefrec[0m, on the other hand, is a macro that expands into a [47m[progn][0m of several primitive [events]. In general, a [world] extending command generates one or more [events]. Both [events] and commands leave landmarks on the [world] that enable us to determine how the given [world] was created from the previous one. Most of your interactions will occur at the command level, i.e., you type commands, you print previous commands, and you undo back through commands. Commands are denoted by command descriptors. See [command-descriptor].") (command-descriptor (history) "An object describing a particular [command] typed by the user Examples: :max ; the command most recently typed by the user :x ; synonymous with :max (:x -1) ; the command before the most recent one (:x -2) ; the command before that :x-2 ; synonymous with (:x -2) 5 ; the fifth command typed by the user 1 ; the first command typed by the user 0 ; the last command of the system initialization -1 ; the next-to-last initialization command :min ; the first command of the initialization :start ; the last command of the initial ACL2 logical world fn ; the command that introduced the logical name fn (:search (defmacro foo-bar)) ; the first command encountered in a search from :max to ; 0 that either contains defmacro and foo-bar in the ; command form or contains defmacro and foo-bar in some ; event within its block. The recorded [history] of your interactions with the top-level ACL2 [command] loop is marked by the [command]s you typed that changed the logical [world]. Each such [command] generated one or more [events], since the only way for you to change the logical [world] is to execute an event function. See [command] and see [events]. We divide [history] into ``[command] blocks,'' grouping together each [world] changing [command] and its [events]. A ``[command] descriptor'' is an object that can be used to describe a particular [command] in the [history] of the ongoing session. Each [command] is assigned a unique integer called its ``[command] number'' which indicates the [command]'s position in the chronological ordering of all of the [command]s ever executed in this session (including those executed to initialize the system). We assign the number 1 to the first [command] you type to ACL2. We assign 2 to the second and so on. The non-positive integers are assigned to ``prehistoric'' [command]s, i.e., the [command]s used to initialize the ACL2 system: 0 is the last [command] of the initialization, -1 is the one before that, etc. The legal [command] descriptors are described below. We use [47mn[0m to denote any integer, [47msym[0m to denote any logical name (see [logical-name]), and [47mcd[0m to denote, recursively, any [command] descriptor. command command descriptor described :max -- the most recently executed command (i.e., the one with the largest command number) :x -- synonymous with :max :x-k -- synonymous with (:x -k), if k is an integer and k>0 :min -- the earliest command (i.e., the one with the smallest command number and hence the first command of the system initialization) :start -- the last command when ACL2 starts up n -- command number n (If n is not in the range :min<=n<=:max, n is replaced by the nearest of :min and :max.) sym -- the command that introduced the logical name sym (cd n) -- the command whose number is n plus the command number of the command described by cd (:search pat cd1 cd2) In this command descriptor, pat must be either an atom or a true list of atoms and cd1 and cd2 must be command descriptors. We search the interval from cd1 through cd2 for the first command that matches pat. Note that if cd1 occurs chronologically after cd2, the search is ``backwards'' through history while if cd1 occurs chronologically before cd2, the search is ``forwards''. A backwards search will find the most recent match; a forward search will find the chronologically earliest match. A command matches pat if either the command form itself or one of the events in the block contains pat (or all of the atoms in pat if pat is a list). (:search pat) the command found by (:search pat :max 0), i.e., the most recent command matching pat that was part of the user's session, not part of the system initialization.") (command-line (interfacing-tools) "Handling of command-line arguments when ACL2 is invoked You may provide command-line arguments when invoking ACL2, which are passed to the host Lisp. For more information on this topic, along with a discussion of how to save an ACL2 executable that avoids passing command-line arguments to the host Lisp, see [save-exec]. Subtopics [Save-exec] Save an executable image and a wrapper script") (comment (hide acl2-built-ins) "Variant of [47m[prog2$][0m to help debug evaluation failures during proofs Semantically, [47m(comment x y)[0m equals [47my[0m; the value of [47mx[0m is ignored. Thus [47mcomment[0m is much like [47m[prog2$][0m. However, when you see a call of [47mcomment[0m in ACL2 proof output, it will likely be under a call of [47m[hide][0m, with information that may be helpful in understanding why the call of [47mhide[0m was inserted. Below we illustrate the various ways in which ACL2 may replace a term [47mtm[0m by [47m(hide (comment "..." tm))[0m. (On occasion you will simply see [47m(hide tm)[0m; such cases are not discussed here.) Also see [hide] for further discussion of how to avoid such proof failures, and for how to keep the prover from inserting a [47mcomment[0m call under a call of [47m[hide][0m. Evaluation during rewriting Forms: (HIDE (COMMENT "Failed attempt to call constrained function <fn>" <term>)) (HIDE (COMMENT "Failed attempt to call non-executable function <fn>" <term>)) Consider the following example. (defstub f (x) t) (defun g (x) (cons (f x) x)) (defund h (x) (cons x (cdr (g x)))) (thm (equal (h 3) '(3 . 3))) Note that the [definition] of [47mh[0m is disabled, but its [executable-counterpart] is not. The proof attempt fails for the [47m[thm][0m call, indicating the checkpoint shown below. *** Key checkpoint at the top level: *** Goal' (EQUAL (HIDE (COMMENT "Failed attempt to call constrained function F; see :DOC comment" (H 3))) '(3 . 3)) The first argument of [47mequal[0m is logically just [47m(h 3)[0m. But the [47mcomment[0m and [47mhide[0m wrappers are telling us that evaluation of [47m(h 3)[0m failed because it led to a call of the constrained function [47mf[0m. It is easy to see why in this case, by looking at the definitions, where [47mh[0m calls [47mg[0m, which calls [47mf[0m. But more complicated such failures may be difficult to understand without such information. In very complicated cases, one might even want to use the Lisp debugger after designating a [47m[break$][0m call using [47m[trace$][0m, like this (here, shown using host Lisp CCL). ACL2 !>(trace$ (f :entry (break$))) ((F :ENTRY (BREAK$))) ACL2 !>(thm (equal (h 3) '(3 . 3))) > Break: Break > While executing: BREAK$, in process listener(1). > Type :GO to continue, :POP to abort, :R for a list of available restarts. > If continued: Return from BREAK. > Type :? for other options. 1 > :b ; user input to get backtrace (262932A0) : 0 (BREAK$) 157 (262932F0) : 1 (F 3) 141 (26293338) : 2 (FUNCALL #'#<(:INTERNAL ACL2_*1*_ACL2::G ACL2_*1*_ACL2::G)> 3) 37 (26293350) : 3 (FUNCALL #'#<(:INTERNAL ACL2_*1*_ACL2::H ACL2_*1*_ACL2::H)> 3) 37 (26293368) : 4 (RAW-EV-FNCALL H (3) NIL NIL [[.. output elided ..]] This output from Lisp is quite low-level, but reading from the bottom up provides the following sequence of events. * 4. Call [47mh[0m with argument list [47m(3)[0m. * 3. Call the [executable-counterpart] of [47mh[0m. * 2. Call the [executable-counterpart] of [47mg[0m. * 1. Attempt to call the constrained function, [47mf[0m. An easy way to avoid this proof failure is to avoid execution of calls of [47mh[0m and [47mg[0m, as follows. (thm (equal (h 3) '(3 . 3)) :hints (("Goal" :in-theory (disable (:e g) (:e h))))) (It actually suffices to disable only [47m(:e h)[0m, but the workings of the ACL2 rewriter are out of scope here.) If the offending function (here, [47mf[0m) is introduced as [non-executable] rather than constrained, in particular if that function is defined using [47m[defun-nx][0m or [47m[defund-nx][0m, then in the first argument of comment you will see ``non-executable'' instead of ``constrained''. Evaluation during substitution Form: (HIDE (COMMENT "Failed attempt (during substitution) to call constrained function <fn>; see :DOC comment" <term>)) Consider how ACL2 approaches the proof of the non-theorem below. (defstub foo (x) t) (defund bar (x) (foo x)) (thm (implies (equal x 3) (equal (bar x) yyy))) The prover attacks the [47m[thm][0m event by substituting the constant [47m'3[0m for [47mx[0m, which results in an attempt to evaluate [47m(bar 3)[0m. This evaluation fails because [47mbar[0m calls the undefined function [47mfoo[0m. The checkpoint is as follows. (EQUAL (HIDE (COMMENT "Failed attempt (during substitution) to call constrained function FOO; see :DOC comment" (BAR 3))) YYY) Failure to expand using a rule Form: (HIDE (COMMENT "Unable to expand using the rule <name>; see :DOC comment" <term>)) Consider how ACL2 approaches the proof for the second event below. (defthm nth-open (implies (and (consp x) (posp n)) (equal (nth n x) (nth (1- n) (cdr x)))) :rule-classes ((:definition :controller-alist ((nth t t)) :install-body t))) (thm (equal (nth i y) zzz) :hints (("Goal" :expand (nth i y) :do-not-induct t))) The checkpoint is as follows. What happened is that the rule [47mnth-open[0m had a hypothesis that was false when an attempt was made to apply it to the term [47m(nth i y)[0m. (IMPLIES (NOT (CONSP Y)) (EQUAL (HIDE (COMMENT "Unable to expand using the rule NTH-OPEN; see :DOC comment" (NTH I Y))) ZZZ)) Failure due to disabled or missing warrants Forms: (HIDE (COMMENT "Call failed because the rule apply$-<fn> is disabled; see :DOC comment" <term>)) (HIDE (COMMENT "Call failed because the warrant for <fn> is not known to be true; see :DOC comment" <term>)) The first of these forms may appear when an attempt to evaluate a call of [47m[apply$][0m fails because a necessary [warrant] is disable)d. The second form may appear when the warrant is not known to be true in the present context, either because it is known to be false or because it cannot be assumed true because forcing is [disable]d. In the following example, the attempt to simplify the call of [47mapply$[0m in the theorem ultimately leads to an attempt to evaluate a call of [47m[ev$][0m, which ultimately fails because it leads to a call to evaluate [47m(apply$ 'bar '(3))[0m [47mbar[0m. That call causes an error because the warrant is unavailable since the rule [47mapply$-bar[0m is disabled, hence cannot rewrite a term [47m(apply$ 'bar args)[0m to [47m(bar (car args))[0m. (include-book "projects/apply/top" :dir :system) (defun$ bar (x) x) (thm (implies (warrant bar) (equal (apply$ '(lambda (y) (bar y)) '(3)) 3)) :hints (("Goal" :in-theory (disable apply$-bar ev$)))) The checkpoint in the proof for the [47mthm[0m just above is as follows. (IMPLIES (APPLY$-WARRANT-BAR) (EQUAL (HIDE (COMMENT "Call failed because the rule APPLY$-BAR is disabled; see :DOC comment" (EV$ '(BAR Y) '((Y . 3))))) 3)) Similarly, if we instead submit the following event, we see the other such message, in this case about a false warrant. (thm (implies (not (warrant bar)) (equal (apply$ '(lambda (y) (bar y)) '(3)) 3)) :hints (("Goal" :in-theory (disable ev$)))) Here is the resulting checkpoint. (IMPLIES (NOT (APPLY$-WARRANT-BAR)) (EQUAL (HIDE (COMMENT "Call failed because the warrant for BAR is not known to be true; see :DOC comment" (EV$ '(BAR Y) '((Y . 3))))) 3)) Our final example illustrates a failure due to forcing being disabled. The use of [47m[loop$][0m in the definition of [47mbar[0m expands to create a call of [47m[ev$][0m, which cannot be simplified during the proof of the [47m[thm][0m below because the necessary warrant hypothesis is missing and cannot be forced, since forcing is disabled (see also [disable-forcing]). (defun$ hello (x) (declare (xargs :guard t)) (list 'hi x)) (defun bar (lst) (declare (xargs :guard (true-listp lst))) (loop$ for name in lst collect (hello name)))) (thm (equal (bar '(john)) '((hi john))) :hints (("Goal" :in-theory (disable (:e force))))) Here is the resulting checkpoint. (EQUAL (HIDE (COMMENT "Call failed because the warrant for HELLO is not known to be true; see :DOC comment" (EV$ '(RETURN-LAST 'PROGN '(LAMBDA$ (LOOP$-IVAR) (LET ((NAME LOOP$-IVAR)) (DECLARE (IGNORABLE NAME)) (HELLO NAME))) ((LAMBDA (NAME) (HELLO NAME)) LOOP$-IVAR)) '((LOOP$-IVAR . JOHN))))) '(HI JOHN))") (common-lisp (about-acl2) "Relation to Common Lisp, including deviations from the spec ACL2 is a logic, a theorem prover, and a programming language based on Common Lisp. A connection with Common Lisp is established with guards (see [guard]). However, here we document potential deviations from Common Lisp semantics even in the presence of verified guards. Our view is that these deviations are extremely unlikely to manifest; indeed, as of this writing we are unaware of any cases in which these issues arise in practice. However, we feel obligated to acknowledge their possibility, which could result in surprises during evaluation or even proof. The Common Lisp spec allows certain predicates to return what it calls ``generalized Booleans,'' which are really arbitrary values that are to be viewed as either [47mnil[0m or non-[47mnil[0m. However, in ACL2 these functions are assumed to return [47mnil[0m or [47mt[0m. For details, see [generalized-booleans]. The execution of forms with [47m:[0m[47m[program][0m mode functions can result in calls of functions on arguments that do not satisfy their [guard]s. In practice, this simply causes hard Lisp errors. But in principle one could imagine a damaged Lisp image that operates incorrectly. See [defun-mode-caveat]. The Common Lisp spec, specifically Section {Section 3.2.2.3 | https://www.lispworks.com/documentation/HyperSpec/Body/03_bbc.htm} of the {Common Lisp Hyperspec | https://www.lispworks.com/documentation/HyperSpec/Front}, allows for undefined results when a function is ``multiply defined'' in a compiled file. ACL2 allows redundant [47m[defun][0ms in a book, and in general [books] are compiled by [47mcertify-book[0m (but see [certify-book] and see [compilation] for how to control such compilation). Moreover, ACL2 provides a redefinition capability (see [ld-redefinition-action] and see [redef]), and the above section also allows for undefined results when a function is defined in a compiled file and then redefined, presumably (for example) because of inlining. Subtopics [Defun-mode-caveat] Potential soundness issue for functions with [defun-mode] [47m:[0m[47m[program][0m [Escape-to-common-lisp] Escaping to Common Lisp [Generalized-booleans] Potential soundness issues related to ACL2 predicates [Raw-lisp-error] Raw lisp errors") (common_lisp (pages_written_especially_for_the_tours) "Common Lisp {IMAGE} (see [An_Example_Common_Lisp_Function_Definition]) The logic of ACL2 is based on Common Lisp. Common Lisp is the standard list processing programming language. It is documented in: Guy L. Steele, {[31;1mCommon Lisp The Language[0m | https://www.cs.cmu.edu/Groups/AI/html/cltl/cltl2.html}, Digital Press, 12 Crosby Drive, Bedford, MA 01730, 1990. ACL2 formalizes only a subset of Common Lisp. It includes such familiar Lisp functions as [47mcons[0m, [47mcar[0m and [47mcdr[0m for creating and manipulating list structures, various arithmetic primitives such as [47m+[0m, [47m*[0m, [47mexpt[0m and [47m<=[0m, and [47mintern[0m and [47msymbol-name[0m for creating and manipulating symbols. Control primitives include [47mcond[0m, [47mcase[0m and [47mif[0m, as well as function call, including recursion. New functions are defined with [47mdefun[0m and macros with [47mdefmacro[0m. See [programming] {ICON} (see [A_Tiny_Warning_Sign]) for a list of the Common Lisp primitives supported by ACL2. ACL2 supports five of Common Lisp's datatypes: * the precisely represented, unbounded numbers (integers, rationals, and the complex numbers with rational components, called the ``complex rationals'' here), * the characters with ASCII codes between 0 and 255 * strings of such characters * symbols (including packages) * conses ACL2 is a large subset of the first-order [31;1mapplicative[0m part of Common Lisp. (Roughly speaking, a language is applicative if it follows the rules of function application. For example, [47mf(x)[0m must be equal to [47mf(x)[0m, which means, among other things, that the value of [47mf[0m must not be affected by ``global variables'' and the object [47mx[0m must not change over time.) It does not support higher-order features of Common Lisp, like functional objects and [47mapply[0m. It does not support Common Lisp primitives that have side-effects such as [47msetq[0m, [47msetf[0m, the Common Lisp Object System, etc. However, ACL2 does provide some special features that can be used efficiently to do many of the same jobs as these omitted Common Lisp primitives. The ACL2 system is largely implemented in the language it supports. {IMAGE} (see [An_Example_Common_Lisp_Function_Definition])") (common_lisp_as_a_modeling_language (pages_written_especially_for_the_tours) "Common Lisp as a Modeling Language In ACL2 we have adopted Common Lisp as the basis of our modeling language. If you have already read our brief note on Common Lisp and recall the example of [47mapp[0m, please proceed. Otherwise click here (see [Common_Lisp]) for an exceedingly brief introduction to Common Lisp and then come [31;1mback[0m here. In Common Lisp it is very easy to write systems of formulas that manipulate discrete, inductively constructed data objects. In building a model you might need to formalize the notion of sequences and define such operations as concatenation, length, whether one is a permutation of the other, etc. It is easy to do this in Common Lisp. Furthermore, if you have a Common Lisp ``theory of sequences'' you can [31;1mrun[0m the operations and relations you define. That is, you can execute the functions on concrete data to see what results your formulas produce. If you define the function [47mapp[0m as shown above and then type (app '(A B) '(C D E)) in any Common Lisp, the answer will be computed and will be [47m(A B C D E)[0m. The [31;1mexecutable[0m nature of Common Lisp and thus of ACL2 is very handy when producing models. But executability is not enough for a modeling language because the purpose of models is to permit analysis. Click here (see [Analyzing_Common_Lisp_Models]) to continue.") (community-book (pointers) "See [community-books].") (community-books (books) "Libraries of ACL2 [books] developed by the ACL2 community. This topic discusses ACL2 [books], which are files of ACL2 [events] like definitions and theorems. See also [community]. The ACL2 [31;1mCommunity Books[0m are the canonical set of open-source books for ACL2, developed since the early 1990s by members of the ACL2 community. They include libraries for reasoning in many domains, macro libraries for more quickly writing and documenting code, interfacing tools for connecting ACL2 to other systems, productivity tools for better proof automation and debugging, and specialty libraries for areas like hardware verification. Most installations of ACL2 contain a copy of the Community Books. See [installation]. Users are encouraged to contribute their own books. See [how-to-contribute]. See [community] for more ways to become involved with the ACL2 community. Subtopics [Books-certification] Instructions for certifying the ACL2 [community-books].") (comp (compilation events acl2-built-ins) "Compile some ACL2 functions NOTE: [47mComp[0m is a no-op if explicit compilation is suppressed; see [compilation]. The documentation here assumes that this is not the case. See [evaluation] for background on executable-counterpart and submitted functions. Examples: :comp t ; compile all uncompiled ACL2 functions (comp t) ; same as above, but can be put into a book (comp :exec) ; compile all uncompiled executable-counterpart definitions :comp foo ; compile the defined function foo (both its submitted and ; executable-counterpart functions) :comp (:raw foo) ; compile the submitted function for the defined function foo ; but not the corresponding executable-counterpart :comp (foo bar) ; compile the defined functions foo and bar :comp (foo (:raw bar)) ; compile the defined functions foo and bar, but for ; bar do not compile the executable-counterpart General Form: :comp specifier where specifier is one of the following: t compile all user-defined ACL2 functions that are currently uncompiled (redefined built-in functions are not recompiled) :exec same as t, except that only executable-counterparts are compiled (see below), not submitted definitions :raw same as t, except that only submitted definitions are compiled, not executable-counterparts (name-1 ... name-k) a non-empty list of names of functions defined by DEFUN in ACL2, except that each name-i can be of the form (:raw sym) or (:exec sym), where sym is the name of such a function name same as (name) When you define a function in ACL2, you are really causing two definitions to be made ``under the hood'' in Common Lisp: the definition is submitted explicitly to raw Lisp, but so is a corresponding executable-counterpart; see [evaluation]. If guards have not been verified, then only the executable-counterpart will be evaluated; see [evaluation] and see [guards-and-evaluation], in particular the section titled ``Guards and evaluation V: efficiency issues''. Thus, if you are not verifying [guard]s and you want the benefit of Lisp compilation for speed and space efficiency, then you may want to place the form [47m(comp :exec)[0m in your [books]. Generally it is not necessary to place the form [47m(comp t)[0m, or the form [47m(comp :raw)[0m, in a book, because [47m[certify-book][0m compiles the raw Lisp definitions anyhow, by default. But you may wish to put [47m(comp t)[0m or [47m(comp fn1 fn2 ... fnk)[0m in a book when such a form precedes expensive calls of functions, for example for proofs involving calls of functions on large constants, or to support computationally expensive macroexpansion. As suggested by the examples above, if a function specifier is of the form [47m(:raw fn)[0m, then [47mfn[0m will be compiled in raw Common Lisp but its corresponding executable-counterpart definition will not be compiled; and for [47m(:exec fn)[0m, it's the other way around. The use of [47m:comp[0m may create various files whose names start with ``[47mTMP*[0m'', but it then deletes them. If you want to save these files, evaluate [47m(assign keep-tmp-files t)[0m. Also see [set-compile-fns] for a way to compile each function as it is defined. But note that [47mset-compile-fns[0m is ignored during [47m[include-book][0m. Note that if functions are traced (see [trace$]), then [47mcomp[0m will first untrace the functions that are to be compiled, then will do the compile(s), and finally will re-trace the functions that it untraced (using their original trace specs). In particular, if you have traced a function and then you compile it using [47m:comp[0m, the resulting traced function will be compiled as well unless you specified [47m:compile nil[0m in your trace spec; and after you untrace the function it will definitely run compiled. We conclude with a technical remark only for those who use trust tags to write raw Lisp code. [47m:Comp[0m generally creates files to compile unless it is given a single function to compile. Those files contain the ACL2 definitions of all functions to compile, omitting those in the lists obtained by evaluating the forms [47m(@ logic-fns-with-raw-code)[0m and [47m(@ program-fns-with-raw-code)[0m. [47m:Comp[0m skips compilation for functions that are already compiled, as is typically the case when you redefine functions in raw Lisp using [include-raw]. But if you define interpreted (as opposed to compiled) functions with raw Lisp code, say by using trust tags (see [defttag]) and [47m[progn!][0m, then you are advised to add all such symbols to one of the lists stored in the two [state] globals above: to [47mlogic-fns-with-raw-code[0m if the function symbol is in [47m:[0m[47m[logic][0m mode, else to [47mprogram-fns-with-raw-code[0m. Then, instead of the corresponding ACL2 definition (without raw Lisp code) being written to a file, the function symbol will be passed directly to the Lisp [47mcompile[0m function. Note that the above two state globals are both untouchable, so you may need to deal with that before modifying them, for example as follows (also see [remove-untouchable]). (defttag t) (progn! :state-global-bindings ((acl2::temp-touchable-vars t acl2::set-temp-touchable-vars)) (f-put-global 'acl2::logic-fns-with-raw-code (cons 'my-fn (@ acl2::logic-fns-with-raw-code)) state))") (comp-gcl (compilation acl2-built-ins) "Compile some ACL2 functions leaving .c and .h files [47mComp-gcl[0m is for use by experts who want to examine the results of GCL compilation, and it may only be used with ACL2 implementations built on top of GCL. It takes exactly the same arguments as [47m[comp][0m, and has the same basic functionality (see [comp]), but has two additional effects. First, files [47m"TMP.lisp"[0m and [47m"TMP1.lisp"[0m are always created, even when a single function is specified. Second, [47mcomp-gcl[0m always leaves files [47m"TMP.c"[0m, [47m"TMP.h"[0m, [47m"TMP1.c"[0m, and [47m"TMP1.h"[0m when compilation is complete.") (compare-objects (debugging) "show differences between two ACL2 objects In theorem prover output it can sometimes be difficult to see where two Lisp objects differ. (Emacs' compare-windows can often help.) This function is an attempt to help while remaining entirely in ACL2. General Form: (compare-objects x y) where [47mx[0m and [47my[0m are two (almost) arbitrary objects but which must both be [47mcons[0m trees for the comparison to be non-trivial. The output (described below) might be confusing if either object contains keywords of the form [47m:<|s...|>[0m, where the ellipsis is the decimal representation of a natural number. For example, the output would be confusing if [47mx[0m or [47my[0m contained [47m:|<s1>|[0m because [47mcompare-objects[0m inserts tokens like that to mark differences. [47mCompare-objects[0m walks through both objects to detect where corresponding substructures first differ. It replaces differences by the keyword symbols [47m:|<s1>|[0m, [47m:|<s2>|[0m, [47m:|<s3>|[0m, ..., which we call ``placeholders.'' It then assembles a ``legend'' that displays triplets of the form [47m(si xi yi)[0m where [47msi[0m is a placeholder marking a position in the common superstructure of both [47mx[0m and [47my[0m and [47mxi[0m and [47myi[0m are the substructures of [47mx[0m and [47my[0m, respectively, at that position that differ. [47mCompare-objects[0m returns a list consisting of the ``common object'' showing the shared superstructure and the legend. For example, ACL2 !>(compare-objects '(a b c) '(a b . c)) ((:OBJ (A B . :|<s1>|)) (:LEGEND ((:|<s1>| (C) C)))) ACL2 !>(compare-objects '(f x y (g x '(a b c))) '(f y x (g x '(a b c . d)))) ((:OBJ (F :|<s1>| :|<s2>| (G X '(A B C . :|<s3>|)))) (:LEGEND ((:|<s1>| X Y) (:|<s2>| Y X) (:|<s3>| NIL D)))) By the way, the [47mbrr[0m command [47m:[0m[47m[explain-near-miss][0m sometimes calls [47mcompare-objects[0m to show the differences between two unequal quoted constants involved in a mismatch. When [47m:explain-near-miss[0m prettyprints the output of [47mcompare-object[0m it does so with an [47m[evisc-tuple][0m that simplifies the placeholders. [47m:Explain-near-miss[0m would display the second example above as ((:OBJ '(F <s1> <s2> (G X '(A B C . <s3>)))) (:LEGEND ((<s1> X Y) (<s2> Y X) (<s3> NIL D)))). [47mCompare-objects[0m might be especially helpful when looking at big [47mlambda[0m objects as produced by translating and rewriting [47m[loop$][0m expressions. For example, below we use [47mcompare-objects[0m to discover where two large [47mDO$[0m terms differ. ACL2 !>(compare-objects '(DO$ ; First term '(LAMBDA (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'LST ALIST)))) (CONS (CONS 'LST LST0) '((ANS . 0))) '(LAMBDA (ALIST) (IF (ENDP (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS ':RETURN (CONS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (CONS (CONS (CONS 'LST (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))) 'NIL)) 'NIL))) (CONS 'NIL (CONS 'NIL (CONS (CONS (CONS 'LST (CDR (CDR (ASSOC-EQ-SAFE 'LST ALIST)))) (CONS (CONS 'ANS (BINARY-+ '1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))) 'NIL)) 'NIL))))) '(LAMBDA (ALIST) (CONS 'NIL (CONS 'NIL (CONS (CONS (CONS 'LST (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))) 'NIL)) 'NIL)))) '(NIL) 'NIL) '(DO$ ; Second term '(LAMBDA (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'LST ALIST)))) (CONS (CONS 'LST LST0) '((ANS . 0))) '(LAMBDA (ALIST) (IF (ENDP (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS ':RETURN (CONS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (CONS (CONS (CONS 'LST (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))) 'NIL)) 'NIL))) (CONS 'NIL (CONS 'NIL (CONS (CONS (CONS 'LST (CDR (CDR (ASSOC-EQ-SAFE 'LST ALIST)))) (CONS (CONS 'ANS (BINARY-+ '1 (CDR (ASSOC-EQ 'ANS ALIST)))) 'NIL)) 'NIL))))) '(LAMBDA (ALIST) (CONS 'NIL (CONS 'NIL (CONS (CONS (CONS 'LST (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))) 'NIL)) 'NIL)))) '(NIL) 'NIL)) ((:OBJ (DO$ '(LAMBDA (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'LST ALIST)))) (CONS (CONS 'LST LST0) '((ANS . 0))) '(LAMBDA (ALIST) (IF (ENDP (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS ':RETURN (CONS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (CONS (CONS (CONS 'LST (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))) 'NIL)) 'NIL))) (CONS 'NIL (CONS 'NIL (CONS (CONS (CONS 'LST (CDR (CDR (ASSOC-EQ-SAFE 'LST ALIST)))) (CONS (CONS 'ANS (BINARY-+ '1 (CDR (:|<s1>| 'ANS ALIST)))) 'NIL)) 'NIL))))) '(LAMBDA (ALIST) (CONS 'NIL (CONS 'NIL (CONS (CONS (CONS 'LST (CDR (ASSOC-EQ-SAFE 'LST ALIST))) (CONS (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))) 'NIL)) 'NIL)))) '(NIL) 'NIL)) (:LEGEND ((:|<s1>| ASSOC-EQ-SAFE ASSOC-EQ)))) [47mCompare-objects[0m tells us that a position [47m:|<s1>|[0m the first term calls [47mASSOC-EQ-SAFE[0m while the second one calls [47mASSOC-EQ[0m.") (compilation (programming) "Compiling ACL2 functions ACL2 has several mechanisms to speed up the evaluation of function calls by [3mcompiling[0m functions: see [comp], see [set-compile-fns], and see [certify-book]. The intention is that compilation never changes the value returned by a function call, though it could cause the call to succeed rather than fail, for example by avoiding a stack overflow. The [47m[state][0m global variable [47m'compiler-enabled[0m is set automatically when the system is built, and may depend on the underlying Lisp implementation. (In order to disable the compiler at build time, which will defeat the speed-up but usually be pretty harmless when the host Lisp is CCL or SBCL, see the discussion of [47mACL2_COMPILER_DISABLED[0m in distributed file [47mGNUmakefile[0m.) The value of [47m'compiler-enabled[0m, as returned by [47m(@ compiler-enabled)[0m, can be [47mt[0m, [47m:books[0m, or [47mnil[0m. If the value is [47mnil[0m, then [47m[include-book][0m and [47m[certify-book][0m coerce their arguments [47m:load-compile-file[0m and [47mcompile-flg[0m arguments (respectively) to [47mnil[0m. Otherwise, the value is [47m:books[0m or [47mt[0m and there is no such coercion; but if the value is not [47mt[0m, then [47m[comp][0m and [47m[set-compile-fns][0m are no-ops, which is probably desirable for Lisps such as CCL and SBCL that compile on-the-fly even when the compiler is not explicitly invoked. However, you may have reason to want to change the above (default) behavior. To enable compilation by default for [47m[certify-book][0m and [47m[include-book][0m but not for [47m[comp][0m or [47m[set-compile-fns][0m: (set-compiler-enabled :books state) To enable compilation not only as above but also for [47m[comp][0m and [47m[set-compile-fns][0m: (set-compiler-enabled t state) To suppress compilation and loading of compiled files by [47m[include-book][0m (for example, if you get a raw Lisp error such as ``Wrong FASL version''): (set-compiler-enabled nil state) Remark for users of [47m[make-event][0m. If [47mset-compiler-enabled[0m is invoked during [47mmake-event[0m expansion, its effect on [47m[state][0m global variable [47m'compiler-enabled[0m will persist after evaluation completes for that [47mmake-event[0m form. So for example, one might use the following idiom in a book so that for all books included on behalf of a given [47m[include-book][0m form, no compiled files are loaded, but (optionally) no such effect takes place for later [47minclude-book[0m forms in that book. (make-event (pprogn (f-put-global 'saved-compiler-enabled (@ compiler-enabled) state) (set-compiler-enabled nil state) (value '(value-triple nil))) :check-expansion t) (include-book "my-book") ; optional (make-event (pprogn (set-compiler-enabled (@ saved-compiler-enabled) state) (value '(value-triple nil))) :check-expansion t) Upon completion of an invocation of [47m[include-book][0m or [47m[certify-book][0m, the value of [47m[state][0m global variable [47m'compiler-enabled[0m is restored to the value it had immediately before that invocation. See [book-compiled-file] for more discussion about compilation and [books]. We close with a discussion of a feature that allows control over the loading of [47m.port[0m files in close analogy to how loading of compiled files is controlled by [47mset-compiler-enabled[0m, as described above. (See [uncertified-books] for a discussion of [47m.port[0m files.) A [state] global variable, [47m'port-file-enabled[0m exists for this purpose, and it is set as follows. (set-port-file-enabled t state) ; permit loading of .port files (default) (set-port-file-enabled nil state) ; skip loading of .port files Just as described above for state global [47mcompiler-enabled[0m, the value of [47m'port-file-enabled[0m persists after [47m[make-event][0m expansion and is restored after [47m[certify-book][0m and [47m[include-book][0m. The idiom displayed above, for avoiding loading of compiled files, can be modified or extended in the obvious way to avoid loading of [47m.port[0m files. Subtopics [Comp] Compile some ACL2 functions [Comp-gcl] Compile some ACL2 functions leaving .c and .h files [Disassemble$] Disassemble a function [Set-compile-fns] Have each function compiled as you go along. [Set-compiler-enabled] Disable [compilation]. [The] Special form for execution efficiency or run-time type checks") (compiling-acl2p (parallelism) "Compiling ACL2(p) This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. See [parallelism-tutorial] for an introduction to parallel programming in ACL2. You can build an experimental version of ACL2 that supports parallel execution in the following host Common Lisp implementations: * CCL (OpenMCL) * Lispworks 6.0 * SBCL with threads (feature [47m:sb-thread[0m) The command below will compile ACL2 to support parallel execution, including parallel execution during proofs. Any non-empty string may be used in place of [47mt[0m, and the value of [47mLISP[0m (shown here as [47mccl[0m) is any Lisp executable on which one can build ACL2(p) (see [parallelism]). make ACL2_PAR=t LISP=ccl So for example, to make an executable image and also documentation (which will appear in subdirectories [47mdoc/EMACS[0m and [47mdoc/HTML[0m), using the Lisp executable [47mccl[0m: make large DOC ACL2_PAR=t LISP=ccl") (complex (numbers acl2-built-ins) "Create an ACL2 number Examples: (complex x 3) ; x + 3i, where i is the principal square root of -1 (complex x y) ; x + yi (complex x 0) ; same as x, for rational numbers x The function [47mcomplex[0m takes two rational number arguments and returns an ACL2 number. This number will be of type [47m(complex rational)[0m [as defined in the Common Lisp language], except that if the second argument is zero, then [47mcomplex[0m returns its first argument. The function [47m[complex-rationalp][0m is a recognizer for complex rational numbers, i.e. for ACL2 numbers that are not rational numbers. The reader macro [47m#C[0m (which is the same as [47m#c[0m) provides a convenient way for typing in complex numbers. For explicit rational numbers [47mx[0m and [47my[0m, [47m#C(x y)[0m is read to the same value as [47m(complex x y)[0m. The functions [47m[realpart][0m and [47m[imagpart][0m return the real and imaginary parts (respectively) of a complex (possibly rational) number. So for example, [47m(realpart #C(3 4)) = 3[0m, [47m(imagpart #C(3 4)) = 4[0m, [47m(realpart 3/4) = 3/4[0m, and [47m(imagpart 3/4) = 0[0m. The following built-in axiom may be useful for reasoning about complex numbers. (defaxiom complex-definition (implies (and (real/rationalp x) (real/rationalp y)) (equal (complex x y) (+ x (* #c(0 1) y)))) :rule-classes nil) A completion axiom that shows what [47mcomplex[0m returns on arguments violating its [guard] (which says that both arguments are rational numbers) is the following, named [47mcompletion-of-complex[0m. (equal (complex x y) (complex (if (rationalp x) x 0) (if (rationalp y) y 0)))") (complex-rationalp (numbers acl2-built-ins) "Recognizes complex rational numbers Examples: (complex-rationalp 3) ; nil, as 3 is rational, not complex rational (complex-rationalp #c(3 0)) ; nil, since #c(3 0) is the same as 3 (complex-rationalp t) ; nil (complex-rationalp #c(3 1)) ; t, as #c(3 1) is the complex number 3 + i See [complex] for more about complex rationals in ACL2.") (complex/complex-rationalp (numbers acl2-built-ins) "Recognizer for complex numbers For most ACL2 users, this is a macro abbreviating [47mcomplex-rationalp[0m; see [complex-rationalp]. In ACL2(r) (see [real]), a complex number [47mx[0m may have irrational real and imaginary parts. This macro abbreviates the predicate [47mcomplexp[0m in ACL2(r), which holds for such [47mx[0m. Most ACL2 users can ignore this macro and use [47m[complex-rationalp][0m instead. Some community books use [47mcomplex/complex-rationalp[0m so that they are suitable for ACL2(r) as well.") (compound-recognizer (rule-classes) "Make a rule used by the typing mechanism See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Examples: (defthm alistp-implies-true-listp-compound-recognizer (implies (alistp x) ; When (alistp x) is assumed true, add (true-listp x)) ; the additional hypothesis that x is :rule-classes :compound-recognizer) ; of primitive type true-listp. (defthm natp-compound-recognizer ; See discussion below. (equal (natp x) (and (integerp x) (<= 0 x))) :rule-classes :compound-recognizer) Before presenting the General Forms, we start with a motivating example: the second [47m[defthm][0m form above, which provides a nice example of a [47m:compound-recognizer[0m rule that is built into ACL2. To see how this rule might be useful, consider the following (admittedly very simple) [events]. (defun triple (x) (* 3 x)) (defthm triple-preserves-integerp (implies (integerp x) (integerp (triple x)))) (in-theory (disable triple natp)) If the above [47m:compound-recognizer[0m rule is disabled, then the following trivial theorem fails as shown; we explain below. (thm (implies (natp x) (integerp (triple x))) :hints (("Goal" :in-theory (disable natp-compound-recognizer)))) The problem is that when ACL2 tries to rewrite the term [47m(integerp (triple x))[0m using the [47m:[0m[47m[rewrite][0m rule [47mtriple-preserves-integerp[0m, it needs to rewrite the hypothesis [47m(integerp x)[0m to [47mt[0m, but instead what is known is [47m(natp x)[0m. If we remove the hint, then the proof succeeds because the above [47m:compound-recognizer[0m rule tells ACL2 that when assuming [47m(natp x)[0m to be true, it should actually assume both [47m(integerp x)[0m and [47m(<= 0 x)[0m to be true. General Forms: (implies (fn x) concl) ; (1) (implies (not (fn x)) concl) ; (2) (and (implies (fn x) concl1) ; (3) (implies (not (fn x)) concl2)) (if (fn x) concl1 concl2) ; (4) (iff (fn x) concl) ; (5) (equal (fn x) concl) ; (6) where [47mfn[0m is a Boolean valued function of one argument, [47mx[0m is a variable symbol, and the system can deduce some restriction on the primitive type of [47mx[0m from the assumption that [47mconcl[0m holds. The last restriction is vague but one way to understand it is to strengthen it a little to ``and [47mconcl[0m is a non-tautological disjunction of the primitive type recognizers listed below.'' The primitive ACL2 types and a suitable primitive recognizing expression for each are listed below. type suitable primitive recognizer zero (equal x 0) one (equal x 1) negative integers (and (integerp x) (< x 0)) positive integers > 1 (and (integerp x) (> x 1)) negative ratio (and (rationalp x) (not (integerp x)) (< x 0)) positive ratio (and (rationalp x) (not (integerp x)) (> x 0)) complex rational (complex-rationalp x) nil (equal x nil) t (equal x t) other symbols (and (symbolp x) (not (equal x nil)) (not (equal x t))) proper conses (and (consp x) (true-listp x)) improper conses (and (consp x) (not (true-listp x))) strings (stringp x) characters (characterp x) Thus, since the naturals comprise the types [47mzero[0m, [47mone[0m, and [47mpositive integers > 1[0m, a suitable [47mconcl[0m to recognize the naturals would be (or (equal x 0) (equal x 1) (and (integerp x) (> x 1))) However, it turns out that we also permit [47m(and (integerp x) (>= x 0))[0m, i.e. [47mconcl[0m doesn't literally need to be formed as a direct disjunction of terms from the table above. Similarly, the true-lists could be specified by (or (equal x nil) (and (consp x) (true-listp x))) but we in fact allow [47m(true-listp x)[0m as well. When time permits we may document more fully what is allowed or implement a macro that permits direct specification of the desired type in terms of the primitives. There are essentially four forms of [47m:compound-recognizer[0m rules, as the forms labeled (3) and (4) above are equivalent, as are those labeled (5) and (6). We explain how such rules are used by considering the individual forms. Consider form (1), [47m(implies (fn x) concl)[0m. The effect of such a rule is that when the rewriter assumes [47m(fn x)[0m true, as it would while diving through [47m(if (fn x) xxx ...)[0m to rewrite [47mxxx[0m, it restricts the type of [47mx[0m as specified by [47mconcl[0m. For example, if [47mconcl[0m is the term [47m(integerp x)[0m, then when rewriting [47mxxx[0m, [47mx[0m will be assumed to be an integer. However, when assuming [47m(fn x)[0m false, as necessary in [47m(if (fn x) ... xxx)[0m, the rule permits no additional assumptions about the type of [47mx[0m. For example, if [47mfn[0m is [47mprimep[0m, i.e., the predicate that recognizes prime numbers, then [47m(implies (primep x) (and (integerp x) (>= x 0)))[0m is a compound recognizer rule of the first form. When [47m(primep x)[0m is assumed true, the rewriter gains the additional information that [47mx[0m is a natural number. When [47m(primep x)[0m is assumed false, no additional information is gained --- since [47mx[0m may be a non-prime natural or may not even be a natural. Form (2) is the symmetric case, when assuming [47m(fn x)[0m false permits type restrictions on [47mx[0m but assuming [47m(fn x)[0m true permits no such restrictions. For example, if we defined [47mexprp[0m to be the recognizer for well-formed expressions for some language in which all symbols, numbers, character objects and strings were well-formed --- e.g., the well-formedness rules only put restrictions on expressions represented by [47m[consp][0ms --- then the theorem [47m(implies (not (exprp x)) (consp x))[0m is a rule of the second form. Assuming [47m(exprp x)[0m true tells us nothing about the type of [47mx[0m; assuming it false tells us [47mx[0m is a [47m[consp][0m. Forms (3) and (4), which are really equivalent, address themselves to the case where one type may be deduced from [47m(fn x)[0m and a generally unrelated type may be deduced from its negation. If we modified the expression recognizer above so that character objects are illegal, then rules of the forms (3) and (4) are (and (implies (exprp x) (not (characterp x))) (implies (not (exprp x)) (or (consp x) (characterp x)))). (if (exprp x) (not (characterp x)) (or (consp x) (characterp x))) Finally, rules of forms (5) and (6) address the case where [47mfn[0m recognizes all and only the objects whose type is described. In these cases, [47mfn[0m is really just a new name for some ``compound recognizers.'' The classic example is [47m(booleanp x)[0m, which is just a handy combination of two primitive types: (iff (booleanp x) (or (equal x t) (equal x nil))). Often it is best to disable [47mfn[0m after proving that it is a compound recognizer, since otherwise the term [47m(fn x)[0m will be expanded and thus disappear. Every time you prove a new compound recognizer rule about [47mfn[0m it overrides all previously proved compound recognizer rules about [47mfn[0m. Thus, if you want to establish the type implied by [47m(fn x)[0m and you want to establish the type implied by [47m(not (fn x))[0m, you must prove a compound recognizer rule of the third, fourth, fifth, or sixth forms. Proving a rule of the first form followed by one of the second only leaves the second fact in the database. Compound recognizer rules can be disabled with the effect that older rules about [47mfn[0m, if any, are exposed. If you prove more than one compound recognizer rule for a function, you may see a [31;1mwarning[0m message to the effect that the new rule is not as ``restrictive'' as the old. That is, the new rules do not give the rewriter strictly more type information than it already had. The new rule is stored anyway, overriding the old, if enabled. You may be playing subtle games with enabling or rewriting. But two other interpretations are more likely, we think. One is that you have forgotten about an earlier rule and should merely print it out to make sure it says what you intend, and then discard your new rule. The other is that you meant to give the system more information and the system has simply been unable to extract the intended type information from the term you placed in the conclusion of the new rule. Given our lack of specificity in saying how type information is extracted from rules, you can hardly blame yourself for this problem. Sorry. If you suspect you've been burned this way, you should rephrase the new rule in terms of the primitive recognizing expressions above and see if the warning is still given. It would also be helpful to let us see your example so we can consider it as we redesign this stuff. Compound recognizer rules are similar to [47m:[0m[47m[forward-chaining][0m rules in that the system deduces new information from the act of assuming something true or false. If a compound recognizer rule were stored as a forward chaining rule it would have essentially the same effect as described, when it has any effect at all. The important point is that [47m:[0m[47m[forward-chaining][0m rules, because of their more general and expensive form, are used ``at the top level'' of the simplification process: we forward chain from assumptions in the goal being proved. But compound recognizer rules are built in at the bottom-most level of the simplifier, where type reasoning (see [TYPE-REASONING]) is done. All that said, compound recognizer rules are a rather fancy, specialized mechanism. It may be more appropriate to create [47m:[0m[47m[forward-chaining][0m rules instead of [47m:compound-recognizer[0m rules.") (compress1 (arrays acl2-built-ins) "Remove irrelevant pairs from a 1-dimensional array Example Form: (compress1 'delta1 a) General Form: (compress1 name alist) where [47mname[0m is a symbol and [47malist[0m is a 1-dimensional array, generally named [47mname[0m. See [arrays] for details. Logically speaking, this function can remove irrelevant pairs from [47malist[0m, possibly shortening it. The function returns a new array, [47malist'[0m, with the same [47m[header][0m (including name and dimension) as [47malist[0m, that, under [47m[aref1][0m, is everywhere equal to [47malist[0m. That is, [47m(aref1 name alist' i)[0m is [47m(aref1 name alist i)[0m, for all legal indices [47mi[0m. [47mAlist'[0m may be shorter than [47malist[0m and the non-irrelevant pairs may occur in a different order than in [47malist[0m. Practically speaking, this function plays an important role in the efficient implementation of [47m[aref1][0m. In addition to creating the new array, [47malist'[0m, [47mcompress1[0m makes that array the ``semantic value'' of [47mname[0m and allocates a raw lisp array to [47mname[0m. For each legal index, [47mi[0m, that raw lisp array contains [47m(aref1 name alist' i)[0m in slot [47mi[0m. Thus, subsequent [47m[aref1][0m operations can be executed in virtually constant time provided they are given [47mname[0m and the [47malist'[0m returned by the most recently executed [47mcompress1[0m or [47m[aset1][0m on [47mname[0m. See [arrays]. In general, [47mcompress1[0m returns an alist whose [47m[cdr][0m is an association list whose keys are nonnegative integers in ascending order. However, if the [47m[header][0m specifies an [47m:order[0m of [47m>[0m then the keys will occur in descending order; and if the [47m:order[0m is [47m:none[0m or [47mnil[0m then the keys will not be sorted and the header may appear anywhere (even more than once), i.e., [47mcompress1[0m is logically the identity function (though it still attaches an array under the hood). Note however that a [47m[compress1][0m call is replaced by a hard error if the header specifies an [47m:order[0m of [47m:none[0m or [47mnil[0m and the array's length exceeds the [47m[maximum-length][0m field of its [47m[header][0m. We close with a remark concerning efficiency in the case that the [47m:ORDER[0m specified by the given [array]'s [header] is [47m<[0m or [47m>[0m and the alist is properly ordered: header occurring only first, then ascending (for [47m:ORDER <[0m) or descending (for [47m:ORDER >[0m) order of indices, with no value in the alist equal to the [47m:DEFAULT[0m specified by the header. In particular, this can cut the time to run [47mcompress1[0m on an alist containing only the header by more than half. [31;1mFunction: [0m<compress1> (defun compress1 (name l) (declare (xargs :guard (array1p name l))) (case (array-order (header name l)) (< (cons (header name l) (compress11 name l 0 (car (dimensions name l)) (default name l)))) (> (cons (header name l) (reverse (compress11 name l 0 (car (dimensions name l)) (default name l))))) (t (prog2$ (and (> (length l) (maximum-length name l)) (hard-error 'compress1 "Attempted to compress a one-dimensional array named ~ ~x0 whose header specifies :ORDER ~x1 and whose ~ length, ~x2, exceeds its maximum-length, ~x3." (list (cons #\0 name) (cons #\1 nil) (cons #\2 (length l)) (cons #\3 (maximum-length name l))))) l))))") (compress2 (arrays acl2-built-ins) "Remove irrelevant pairs from a 2-dimensional array Example Form: (compress2 'delta1 a) General Form: (compress2 name alist) where [47mname[0m is a symbol and [47malist[0m is a 2-dimensional array, generally named [47mname[0m. See [arrays] for details. Logically speaking, this function removes irrelevant pairs from [47malist[0m, possibly shortening it. The function returns a new array, [47malist'[0m, with the same [47m[header][0m (including name and dimension) as [47malist[0m, that, under [47m[aref2][0m, is everywhere equal to [47malist[0m. That is, [47m(aref2 name alist' i j)[0m is [47m(aref2 name alist i j)[0m, for all legal indices [47mi[0m and [47mj[0m. [47mAlist'[0m may be shorter than [47malist[0m and the non-irrelevant pairs may occur in a different order in [47malist'[0m than in [47malist[0m. Practically speaking, this function plays an important role in the efficient implementation of [47m[aref2][0m. In addition to creating the new array, [47malist'[0m, [47mcompress2[0m makes that array the ``semantic value'' of [47mname[0m and allocates a raw lisp array to [47mname[0m. For all legal indices, [47mi[0m and [47mj[0m, that raw lisp array contains [47m(aref2 name alist' i j)[0m in slot [47mi[0m,[47mj[0m. Thus, subsequent [47m[aref2][0m operations can be executed in virtually constant time provided they are given [47mname[0m and the [47malist'[0m returned by the most recently executed [47mcompress2[0m or [47m[aset2][0m on [47mname[0m. See [arrays]. [31;1mFunction: [0m<compress2> (defun compress2 (name l) (declare (xargs :guard (array2p name l))) (cons (header name l) (compress21 name l 0 (car (dimensions name l)) (cadr (dimensions name l)) (default name l))))") (computed-hint (pointers) "See [computed-hints].") (computed-hints (hints) "Computing advice to the theorem proving process General Form of :hints: (hint1 hint2 ... hintk) Each element, hinti, must be either a common hint or a computed hint. A common hint is of the form (goal-spec :key1 val1 ... :keyn valn) where [47mgoal-spec[0m is as specified in [goal-spec] and each [47m:keyi[0m and [47mvali[0m is as specified in [hints]. Among the ``common hints'' we include both the primitive hints and user-defined custom keyword hints (see [custom-keyword-hints]). A computed hint may be a symbol, in which case it must be a function symbol of three, four or seven arguments. Otherwise, a computed hint is a term with the following properties: (a) the only free variables allowed in the term are [47mID[0m, [47mCLAUSE[0m, [47mWORLD[0m, [47mSTABLE-UNDER-SIMPLIFICATIONP[0m, [47mHIST[0m, [47mPSPV[0m, [47mCTX[0m, and [47m[state][0m; (b) the output signature of the term is either [47m(MV * * STATE)[0m, which is to be treated as an error triple (see below), or is [47m*[0m, denoting a single non-[stobj] value; and (c) in the former case of (b) above, the term is single-threaded in [47m[state][0m. If a computed hint is a function symbol [47mfn[0m, whose arity n is therefore three, four, or seven, then it is treated as the term resulting from applying that [47mfn[0m to the first n variables shown in (a) above. Notice that it must then return a single non-[stobj] value, not an error triple, since [47mstate[0m is not one of the first seven variables shown in (a). Note: Error triples are an ACL2 idiom for implementing ``errors''; see [error-triple]. If a computation returns [47m(mv erp val state)[0m in a context in which ACL2 is respecting the error triple convention (see [ld-error-triples] and see [ld-error-action]), then an error is deemed to have occurred if [47merp[0m is non-[47mnil[0m. The computation is expected to have printed an appropriate error message to [47m[state][0m and further computation is aborted. On the other hand, if a computation returns an error triple in which [47merp[0m is nil, then ``value'' of the computation is taken to be the second component, [47mval[0m, of the triple (along with the possibly modified [47m[state][0m), and computation continues. For more information about programming with error triples, see [programming-with-state]. The function symbol cases are treated as abbreviations of the term [47m(fn ID CLAUSE WORLD)[0m, [47m(fn ID CLAUSE WORLD STABLE-UNDER-SIMPLIFICATIONP)[0m, or [47m(fn ID CLAUSE WORLD STABLE-UNDER-SIMPLIFICATIONP HIST PSPV CTX)[0m as appropriate for the arity of [47mfn[0m. (Note that this tells you which argument of [47mfn[0m is which.) Moreover, in these cases the value returned must be a single ordinary (non-[stobj]) value, not an error triple. In the discussion below we assume all computed hints are of the term form. Indeed, we almost assume all computed hints are of the 3 and 4 argument forms. We only comment briefly on the 7 argument form in [using-computed-hints-8]. The semantics of a computed hint term is as follows. On every subgoal, the term is evaluated in an environment in which the variables mentioned in (a) above are bound to context-sensitive values explained below. Either the computed hint signals an error, in which the proof attempt aborts, or else it returns a value, [47mval[0m and a new state, [47m[state][0m. Any changes to those parts of [47m[state][0m that affect logical soundness are undone; more specifically, the values of symbols (sometimes called ``state global variables'') in the list [47m*protected-system-state-globals*[0m in the global table of the state (see [state]) are restored when changed during evaluation. The value, [47mval[0m, of a non-erroneous computed hint calculation is either [47mnil[0m, which means the computed hint did not apply to the subgoal in question, or it is an alternating list of [47m:keyi vali[0m pairs as specified in [hints]. With one exception, those new hints are applied to the given subgoal as though the user had typed them explicitly. The exception is that the first keyword in the returned [47mval[0m is allowed to be [47m:COMPUTED-HINT-REPLACEMENT[0m. Its value should be [47mnil[0m, [47mt[0m, or a list of terms. If this keyword is not present, the default value of [47mnil[0m is provided. We explain [47m:COMPUTED-HINT-REPLACEMENT[0m below. The evaluation of a hint term is done with guard checking turned off (see [set-guard-checking]); e.g., the form [47m(car 23)[0m in a computed hint returns [47mnil[0m as per the axioms. When a non-[47mnil[0m value is returned, the keyword/value pairs (other than the optional [47m:COMPUTED-HINT-REPLACEMENT[0m) are used as the hint for the subgoal in question. Thus, your job as the programmer of computed hints is either to cause an error, typically by invoking [47m[er][0m, or to return a non-erroneous value triple whose value is the list of keys and values you would have typed had you supplied a common hint for the subgoal. (In particular, any theory expressions in it are evaluated with respect to the global current-theory, not whatever theory is active at the subgoal in question.) If the generated list of keywords and values is illegal, an error will be signaled and the proof attempt will be aborted. The purpose of the [47m:COMPUTED-HINT-REPLACEMENT[0m keyword and its value, [47mchr[0m, is to change the list of hints. If [47mchr[0m is [47mnil[0m, then the computed hint which was applied is removed from the list of hints that is passed down to the children of the subgoal in question. This is the default. If [47mchr[0m is [47mt[0m, then the computed hint is left in the list of hints. This means that the same computed hint may act on the children of the subgoal. Otherwise, [47mchr[0m must be a list of terms, each of which is treated as a computed hint. The computed hint which was applied is deleted from the list of hints and the computed hints in [47mchr[0m are added to the list of hints passed to the children of the subgoal. The ability to generate new computed hints and pass them down allows strange and wonderful behavior. Notice that certain hints, for example [47m:in-theory[0m and [47m:expand[0m hints, which appear in the computed hint will continue to take effect even when [47mchr[0m is [47mnil[0m. This might give one the false impression that a removed computed hint still hangs around. See [hints-and-the-waterfall] for a more detailed discussion about how [47m:in-theory[0m and other hints are handled in the waterfall. For these purposes, the goals produced by induction and the top-level goals of forcing rounds are not considered children; all original hints are available to them. Only the first hint applicable to a goal, as specified in the user-supplied list of [47m:hints[0m followed by the [47m[default-hints-table][0m, will be applied to that goal. (For an advanced exception, see [override-hints].) It remains only to describe the bindings of the free variables. Suppose the theorem prover is working on a [clause] named by some [47m[goal-spec][0m, e.g., "Subgoal *1/2'''". Corresponding to the printed [47mgoal-spec[0m is an internal data structure called a ``clause identifier'' id. See [clause-identifier]. In the case of a common hint, the hint applies if the goal-spec of the hint is the same as the goal-spec of the clause in question. In the case of a computed hint, the variable [47mID[0m is bound to the clause id, the variable [47mCLAUSE[0m is bound to the (translated form of the) clause, and the variable [47mWORLD[0m is bound to the current ACL2 world. The variable [47mSTABLE-UNDER-SIMPLIFICATIONP[0m is bound to [47mt[0m or [47mnil[0m. It is bound to [47mt[0m only if the clause is known to be stable under simplification. That is, the simplifier has been applied to the clause and did not change it. Such a clause is sometimes known as a ``simplification checkpoint.'' It is frequently useful to inject hints (e.g., to enable a rule or provide a [47m:use[0m hint) only when the goal in question has stabilized. If a hint is provided, the processing of the clause starts over with simplification. As for [47mCTX[0m and [47m[state][0m, they are provided so that you can pass them to the [47m[er][0m macro to print error messages. The remaining variables, [47mHIST[0m and [47mPSPV[0m are not documented yet. Only users familiar with the internals of ACL2 are likely to need them or understand their values. For some instruction about how to use computed hints, see [using-computed-hints]. Subtopics [Using-computed-hints] How to use computed hints") (concatenate (lists strings acl2-built-ins) "Concatenate lists or strings together Examples: (concatenate 'string "ab" "cd" "ef") ; equals "abcdef" (concatenate 'string "ab") ; equals "ab" (concatenate 'list '(a b) '(c d) '(e f)) ; equals '(a b c d e f) (concatenate 'list) ; equals nil General Form: (concatenate result-type x1 x2 ... xn) where [47mn >= 0[0m and either: [47mresult-type[0m is [47m'[0m[47m[string][0m and each [47mxi[0m is a string; or [47mresult-type[0m is [47m'[0m[47m[list][0m and each [47mxi[0m is a true list. [47mConcatenate[0m simply concatenates its arguments to form the result string or list. Also see [append] and see [string-append]. (The latter immediately generates a call to [47mconcatenate[0m when applied to strings.) Note: We do *not* try to comply with the Lisp language's insistence that [47mconcatenate[0m copies its arguments. Not only are we in an applicative setting, where this issue shouldn't matter for the logic, but also we do not actually modify the underlying lisp implementation of [47mconcatenate[0m; we merely provide a definition for it. [47mConcatenate[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<concatenate> (defmacro concatenate (result-type &rest sequences) (declare (xargs :guard (or (equal result-type ''string) (equal result-type ''list)))) (cond ((equal result-type ''string) (cond ((and sequences (cdr sequences) (null (cddr sequences))) (list 'string-append (car sequences) (cadr sequences))) (t (list 'string-append-lst (cons 'list sequences))))) ((endp sequences) nil) (t (cons 'append (append sequences (list nil))))))") (cond (basics acl2-built-ins) "Conditional based on if-then-else [47mCond[0m is the construct for IF, THEN, ELSE IF, ... The test is against [47mnil[0m. The argument list for [47mcond[0m is a list of ``cond clauses'', each of which is a list. In ACL2, cond clauses must have length 1 or 2. ; Example 1. The form (COND ((CONSP X) (FOO X Y)) ((SYMBOLP X) (BAR X Y)) (T (LIST X Y))) ; abbreviates the following. (IF (CONSP X) (FOO X Y) (IF (SYMBOLP X) (BAR X Y) (LIST X Y))) ; Example 2. The form (COND ((CONSP X)) ((SYMBOLP X) (BAR X Y))) ; abbreviates the following. (OR (CONSP X) (IF (SYMBOLP X) (BAR X Y) NIL)) The results above were obtained by typing [47m:trans1[0m followed by the form in the ACL2 loop, and then hitting [47m<RETURN>[0m. See [trans1]. You can experiment in this way to see other such examples. [47mCond[0m is a Common Lisp macro. See any Common Lisp documentation for more information. [31;1mMacro: [0m<cond> (defmacro cond (&rest clauses) (declare (xargs :guard (cond-clausesp clauses))) (cond-macro clauses)) [31;1mFunction: [0m<cond-macro> (defun cond-macro (clauses) (declare (xargs :guard (cond-clausesp clauses))) (if (consp clauses) (if (and (eq (car (car clauses)) t) (eq (cdr clauses) nil)) (if (cdr (car clauses)) (car (cdr (car clauses))) (car (car clauses))) (if (cdr (car clauses)) (list 'if (car (car clauses)) (car (cdr (car clauses))) (cond-macro (cdr clauses))) (list 'or (car (car clauses)) (cond-macro (cdr clauses))))) nil))") (congruence (rule-classes) "The relations to maintain while simplifying arguments See [rule-classes] for a general discussion of rule classes and how they are used to build rules from formulas. An example [47m:[0m[47m[corollary][0m formula from which a rule of class [47m:congruence[0m might be built, assuming that [47mset-equal[0m is a known [equivalence] relation, is: Example: (defthm set-equal-implies-iff-memb-2 (implies (set-equal x y) (iff (memb e x) (memb e y))) :rule-classes :congruence) Also see [defcong] and see [equivalence]. NOTE: This topic discusses so-called ``classic'' congruence rules. A more general class of rules, so-called ``patterned'' congruence rules, is supported. We discuss only classic congruence rules below; for a discussion of patterned congruence rules, first read the present topic and then see [patterned-congruence]. General Form: (implies (equiv1 xk xk-equiv) (equiv2 (fn x1... xk ...xn) (fn x1... xk-equiv ...xn))) where [47mequiv1[0m and [47mequiv2[0m are known equivalence relations, [47mfn[0m is an [47mn-ary[0m function symbol other than [47mif[0m, and the [47mxi[0m and [47mxk-equiv[0m are all distinct variables. The effect of such a rule is to record that the [47mequiv2[0m-equivalence of [47mfn[0m-expressions can be maintained if, while rewriting the [47mkth[0m argument position, [47mequiv1[0m-equivalence is maintained. See [equivalence] for a general discussion of the issues. We say that [47mequiv2[0m, above, is the ``outside equivalence'' in the rule and [47mequiv1[0m is the ``inside equivalence for the [47mk[0mth argument.'' The macro form [47m(defcong equiv1 equiv2 (fn x1 ... x1) k)[0m is an abbreviation for a [47m[defthm][0m of rule-class [47m:congruence[0m that attempts to establish that [47mequiv2[0m is maintained by maintaining [47mequiv1[0m in [47mfn[0m's [47mk[0mth argument. The [47m[defcong][0m macro automatically generates the general formula shown above. See [defcong]. The [47mmemb[0m example above tells us that [47m(memb e x)[0m is propositionally equivalent to [47m(memb e y)[0m, provided [47mx[0m and [47my[0m are [47mset-equal[0m. The outside equivalence is [47m[iff][0m and the inside equivalence for the second argument is [47mset-equal[0m. If we see a [47mmemb[0m expression in a propositional context, e.g., as a literal of a [clause] or test of an [47m[if][0m (but not, for example, as an argument to [47m[cons][0m), we can rewrite its second argument maintaining [47mset-equality[0m. For example, a rule stating the commutativity of [47m[append][0m (modulo set-equality) could be applied in this context. Since equality is a refinement of all equivalence relations, all equality rules are always available. See [refinement]. All known congruence rules about a given outside equivalence and [47mfn[0m can be used independently. That is, consider two congruence rules with the same outside equivalence, [47mequiv[0m, and about the same function [47mfn[0m. Suppose one says that [47mequiv1[0m is the inside equivalence for the first argument and the other says [47mequiv2[0m is the inside equivalence for the second argument. Then [47m(fn a b)[0m is [47mequiv[0m [47m(fn a' b')[0m provided [47ma[0m is [47mequiv1[0m to [47ma'[0m and [47mb[0m is [47mequiv2[0m to [47mb'[0m. This is an easy consequence of the transitivity of [47mequiv[0m. It permits you to think independently about the inside equivalences. Furthermore, it is possible that more than one inside equivalence for a given argument slot will maintain a given outside equivalence. For example, [47m(length a)[0m is equal to [47m(length a')[0m if [47ma[0m and [47ma'[0m are related either by [47mlist-equal[0m or by [47m[string-equal][0m. You may prove two (or more) congruence rules for the same slot of a function. The result is that the system uses a new, ``generated'' equivalence relation for that slot with the result that rules of both (or all) kinds are available while rewriting. See [geneqv] for a discussion of how generated equivalence relations are derived using congruence rules and how generated equivalence relations are represented. Congruence rules can be [disable]d. For example, if you have two different inside equivalences for a given argument position and you find that the [47m:[0m[47m[rewrite][0m rules for one are unexpectedly preventing the application of the desired rule, you can disable the rule that introduced the unwanted inside equivalence. [31;1mNOTE[0m however that unlike other rules, the tracking of congruence rules is incomplete. Specifically: when congruence rules are used by the rewriter as it descends through terms, to maintain the generated equivalence relation used for rewriting, ACL2 does not track the congruence rules that are used, even though it is relevant that they are all [enable]d. Congruence rules that are used only in this way will therefore not appear in the [summary]. [3mRemark on Replacing IFF by EQUAL.[0m You may encounter a warning suggesting that a congruence rule ``can be strengthened by replacing the second equivalence relation, IFF, by EQUAL.'' Suppose for example that this warning occurs when you submit the following rule: (defcong equiv1 iff (fn x y) 2) which is shorthand for the following: (defthm equiv1-implies-iff-fn-2 (implies (equiv1 y y-equiv) (iff (fn x y) (fn x y-equiv))) :rule-classes (:congruence)) The warning is telling you that ACL2 was able to deduce that [47mfn[0m always returns a Boolean, and hence a trivial but useful consequence is obtained by replacing [47m[iff][0m by [47m[equal][0m --- (defcong equiv1 equal (fn x y) 2) --- which is shorthand for the following: (defthm equiv1-implies-equal-fn-2 (implies (equiv1 y y-equiv) (equal (fn x y) (fn x y-equiv))) :rule-classes (:congruence)) If you have difficulty proving the latter directly, you can derive it from the former by giving a suitable hint, minimally as follows. (defcong equiv1 equal (fn x y) 2 :hints (("Goal" :use equiv1-implies-iff-fn-2 :in-theory (union-theories '((:type-prescription fn)) (theory 'minimal-theory))))) By heeding this warning, you may avoid unnecessary [47m[double-rewrite][0m warnings later. We now explain why, but see [double-rewrite] for relevant background material. For example, suppose you have proved the ``[47miff[0m'' version of the congruence rule above, and later you submit the following rewrite rule. (defthm equal-list-perm (implies (equiv1 x y) (fn x y))) Since [47mfn[0m is known to return a Boolean, ACL2 performs an optimization that stores this rule as though it were the following. (defthm equal-list-perm (implies (equiv1 x y) (equal (fn x y) t))) Thus, if ACL2's rewriter sees a term [47m(fn a b)[0m in a context where the equivalence relation [47m[iff][0m is not being maintained, then it cannot use rule [47mequiv1-implies-iff-fn-2[0m, so it rewrites argument [47ma[0m without the benefit of knowing that it suffices to maintain [47mequiv1[0m; and then it caches the result. When ACL2 subsequently attempts to relieve the hypothesis [47m(equiv1 x y)[0m, it will rewrite [47mx[0m simply by returning the rewritten value of [47ma[0m from the result cache. This is unfortunate if [47ma[0m could have been rewritten more completely under maintenance of the equivalence relation [47mequiv1[0m --- which is legal in the hypothesis since [47ma[0m is an argument of [47mequiv1[0m, which is an [equivalence] relation. The user who observes the warning from rule [47mequiv1-implies-iff-fn-2[0m, and replaces it with [47mequiv1-implies-equal-fn-2[0m, will avoid this unfortunate case.") (conjoin (pointers) "See [system-utilities].") (conjoin2 (pointers) "See [system-utilities].") (conjugate (numbers acl2-built-ins) "Complex number conjugate [47mConjugate[0m takes an ACL2 number as an argument, and returns its complex conjugate (i.e., the result of negating its imaginary part.). [47mConjugate[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<conjugate> (defun conjugate (x) (declare (xargs :guard (acl2-numberp x))) (complex (realpart x) (- (imagpart x))))") (cons (conses acl2-built-ins) "Pair and list constructor [47m(cons x y)[0m is a pair whose first component is [47mx[0m and second component is [47my[0m. If [47my[0m is a list, then [47m(cons x y)[0m is a list that has an additional element [47mx[0m on the front.") (cons-count-bounded (conses acl2-built-ins) "Count the number of conses (up to a limit) The call [47m(cons-count-bounded x)[0m returns the number of cons nodes in [47mx[0m (without accounting for sharing), but truncated above by the value of [47m(fn-count-evg-max-val)[0m, which is 200,000 as of this writing.") (cons-subtrees (fast-alists acl2-built-ins) "Build a fast alist whose keys are the subtrees of X [47m(cons-subtrees x nil)[0m builds a fast alist that associates each subtree of X with T, without duplication. [31;1mFunction: [0m<cons-subtrees> (defun cons-subtrees (x al) (declare (xargs :guard t)) (cond ((atom x) al) ((hons-get x al) al) (t (cons-subtrees (car x) (cons-subtrees (cdr x) (hons-acons x t al))))))") (cons-term (pointers) "See [system-utilities].") (cons-term* (pointers) "See [system-utilities].") (cons-with-hint (conses acl2-built-ins) "Alternative to [47m[cons][0m that tries to avoid consing when a suitable [47mcons[0m structure is provided as a hint. This is a special purpose function that is intended to help with reducing the memory usage of functions that modify existing cons tree structures. Also see [hons] for a way to share [cons] structures; however, [47mcons-with-hint[0m is likely much cheaper than [47mhons[0m and hence can be useful for reducing consing without the overhead of [47mhons[0m. Logically [47m(cons-with-hint x y hint)[0m is just [47m(cons x y)[0m; [47mhint[0m is completely irrelevant and ignored. We generally expect that [47mcons-with-hint[0m will just be left [enable]d, so you should never have to reason about it. But [47mcons-with-hint[0m has a special raw Common Lisp definition that tries to avoid consing by using your [47mhint[0m. Specifically: if [47mhint[0m is the cons [47m(x . y)[0m, then [47mhint[0m is returned without creating a new cons. Equality checking against [47mx[0m and [47my[0m is done using [47m[eql][0m, which makes it a fast but incomplete check for equality. What good is this? A fairly common operation in ACL2 is to ``change'' an existing data structure by consing together a new structure that is similar to it, but perhaps with some subtrees replaced. In many cases, some portion of the structure does not need to change. For instance, consider a function like [47m[remove-equal][0m, which updates a list by removing all copies of some element from it. The definition of [47mremove-equal[0m is as follows (in the logic; it has a slightly different definition in raw Lisp). [31;1mFunction: [0m<remove-equal> (defun remove-equal (x l) (declare (xargs :guard (true-listp l))) (cond ((endp l) nil) ((equal x (car l)) (remove-equal x (cdr l))) (t (cons (car l) (remove-equal x (cdr l)))))) You can see that if [47ml[0m doesn't have any copies of [47mx[0m, this function will essentially make a fresh copy of the whole list [47mx[0m. That could waste a lot of memory when [47mx[0m is long. The choice was made to define [47mremove-equal[0m ``under the hood'' to call Common Lisp's function, [47mremove[0m; but it is easy to write a new version of [47mremove-equal[0m that uses [47mcons-with-hint[0m: (defun remove-equal-with-hint (x l) (declare (xargs :guard (true-listp l))) (mbe :logic (remove-equal x l) :exec (cond ((endp l) nil) ((equal x (car l)) (remove-equal-with-hint x (cdr l))) (t (cons-with-hint (car l) (remove-equal-with-hint x (cdr l)) l))))) This new version avoids consing in the case that we are not dropping an element. For example, at the time of this writing, we found the following memory usages on our copy of ACL2 built on CCL: :q ;; 16 MB of memory allocated (let ((list (make-list 1000 :initial-element 0))) (time (loop for i from 1 to 1000 do (remove-equal i list)))) ;; 0 MB of memory allocated (let ((list (make-list 1000 :initial-element 0))) (time (loop for i from 1 to 1000 do (remove-equal-with-hint i list)))) This memory usage is not very surprising when you consider that the list does not change when no removal takes place. For example (still in raw Lisp): ? (let ((x '(a b c d e))) (eq x (remove-equal-with-hint 3 x))) T ? Note that ACL2 asks Lisp to inline calls of [47mcons-with-hint[0m, so there will likely be no function call overhead for using [47mcons-with-hint[0m.") (conservativity-of-defchoose (defchoose) "Proof of conservativity of [47m[defchoose][0m This documentation topic provides underlying theory. It is of theoretical interest only; it has no relationship to the effective use of ACL2. The argument below for the conservativity of [defchoose] replaces the terse and somewhat misleading reference to a forcing argument in Appendix B of the paper by ACL2 authors Kaufmann and Moore, ``Structured Theory Development for a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2 (2001), pp. 161--203). Our basic idea is to take a (countable) first-order structure for ACL2, M, together with a function symbol, f, introduced by [defchoose], and find a way to expand M with an interpretation of f (without changing the universe of M) so that e0-induction continues to hold in the expansion. A remark at the end of this documentation topic shows why care is necessary. A concept called ``forcing'', originally introduced by Paul Cohen for set theory, has long since been adapted by logicians (in a simplified form) to model theory. This simplified model-theoretic forcing provides the means for making our careful expansion. The forcing argument presented below is intended to be completely self-contained for those familiar with basic first-order logic and ACL2; in particular, see [defchoose]. No background in forcing (model-theoretic or otherwise) is expected, though we do expect a rudimentary background in first-order logic and familiarity with the following. Preliminaries. We write s[p<-p0] to denote the result of extending or modifying the assignment s by binding p to p0. Now let A be a subset of the universe U of a first-order structure M. A is said to be ``first-order definable with parameters'' in M if for some formula phi, variable x, and assignment s binding the free variables of phi except perhaps for x, A = {a \in U: M |= phi[s[x<-a]]}. Note that we are writing ``\in'' to denote set membership. Finally, we indicate the end of a proof (or of a theorem statement, when the proof is omitted) with the symbol ``-|''. We gratefully acknowledge very helpful feedback from John Cowles, who found several errors in a draft of this note and suggested the exercises. We also thank Ruben Gamboa for helpful feedback, and we thank Jim Schmerl for an observation that led us directly to this proof in the first place. We are given a consistent first-order theory T, extending the ACL2 ground-zero theory, that satisfies the e0-induction scheme. We wish to show that the extension of T by the following arbitrary defchoose event is conservative, where g is a new function symbol. (defchoose g <bound-vars> <free-vars> <body>) Note that by ``the extension of T'' here we mean the extension of T by not only the new defchoose axiom displayed just below, but also the addition of e0-induction axioms for formulas in the expanded language obtained by including the new defchoose function symbol, g. <body> -> (LET <bound-vars> = g(<free-vars>) in <body>) By definition of conservativity, since proofs are finite, it clearly suffices to consider an arbitrary finite subset of T. Then by the completeness, soundness, and downward Lowenheim-Skolem theorems of first-order logic, it suffices to show that an arbitrary countable model of T can be expanded (i.e., by interpreting the new symbol g without changing the universe of the model) to a model of the corresponding defchoose axiom above, in which all e0-induction axioms hold in the language of that model (i.e., the expanded language). Below, we will carry out a so-called [3mforcing[0m construction, which allows us to expand any countable model M of T to a model M[G] for the expanded language that satisfies e0-induction (in the expanded language) and also satisfies the axiom displayed above, generated from the defchoose event. The ideas in this argument are standard in model theory; no novelty is claimed here. Fix a countable model M of a theory T that satisfies e0-induction for its countable language and extends the ACL2 ground-zero theory. Also fix the above defchoose axiom, where g is not in the language of T. We start by defining a partial order P as follows. Let Nb and Nf be the lengths of <bound-vars> and <free-vars>, respectively. P consists of all fn in M such that the following formula is true in M. Roughly speaking, it says that fn is a finite function that witnesses, on its domain, the requirement above for g. alistp(fn) & no-duplicatesp-equal(strip-cars(fn)) & (forall <bound-vars>, <free-vars> . (member-equal(cons(<free-vars>,<bound-vars>), fn) -> (length(<bound-vars>) = Nb & length(<free-vars>) = Nf & ((exists <bound-vars> . <body>) -> (LET <bound-vars> = g(<free-vars>) in <body>))))) P is ordered by subset, i.e., we say that p2 [3mextends[0m p1 if p1 is a subset (not necessarily proper) of p2 (more precisely, M |= subsetp-equal(p1,p2)). Remark. The original argument in Appendix B of the aforementioned paper can essentially be salvaged, as we now show. The key observation is that the particular choice of P is nearly irrelevant for the argument that follows below. In particular, we can instead define P to consist of finite one-one functions with domain contained in the set of natural numbers. More precisely, consider the following definitions. (defun function-p (fn) (and (alistp fn) (no-duplicatesp-equal (strip-cars fn)))) (defun nat-function-p (x) (and (function-p x) (nat-listp (strip-cars x)))) and define an inverse function on alists as follows. (defun inverse (fn) (if (endp fn) nil (cons (cons (cdar fn) (caar fn)) (inverse (cdr fn))))) Then P may instead be defined to consist of those fn for which nat-function-p(fn) & function-p(inverse(fn)). With this alternate definition of P, the argument below then goes through virtually unchanged, and we get an expansion M[G] of M in which there is a definable enumeration of the universe. The conservativity of defchoose then follows easily because the function being introduced can be defined explicitly using that enumeration (namely, always pick the least witness in the sense of the enumeration). End of Remark. Next we present the relevant forcing concepts from model theory. A [3mdense[0m subset of P is a subset D of P such that for every p \in P, there is d \in D such that d extends p. A subset G of P is [3mgeneric[0m with respect to a collection Ds of dense subsets of P, also written ``G is Ds-generic,'' if G is closed under subset (if p2 \in G and p2 extends p1 then p1 \in G), G is pairwise compatible (the union-equal of any two elements of G is in G), and every set in Ds has non-empty intersection with G. For p \in P, we say that a subset D of P is [3mdense beyond[0m p if for all p1 extending p there exists p2 extending p1 such that p2 \in D. This notion makes sense even for D not a subset of P if we treat elements of D not in P as nil. Proposition 1. For any partial order P and countable collection Ds of dense subsets of P, there is a Ds-generic subset of P. Proof. Let Ds = {D0,D1,D2,...}. Define a sequence <p_0,p_1,...> such that for all i, p_i \in Di and p_(i+1) extends p_i. Let G = {p \in P: for some i, pi extends p}. Then G is Ds-generic. -| Note that P is first-order definable (with parameters) in M. Let Df be the set of dense subsets of P that are first-order definable (with parameters) in M. A standard argument shows there are only countably many first-order definitions with parameters in a countable model M whose language is countable --- for example, we can Goedel number all terms and then all formulas --- hence, Df is countable. By Proposition 1, let G be Df-generic. Notice that for any list x of length Nf in M, the set of elements f of P for which x is in the domain of f is dense and first-order definable. We may thus define a function g0 as follows: g0(x_1,...,x_Nf) = y if there is some element of G containing the pair ((x_1 ... x_Nf) . y). It is easy to see that g0 is a total function on M. Let L be the language of T and let L[g] be the union of L with a set containing a single new function symbol, g. Let M[G] be the expansion of M to L[g] obtained by interpreting g to be g0 (see also Proposition 5 below). So now we have fixed M, P, Df, G, and g0, where G is Df-generic. Proposition 2. Let Df be the set of dense subsets of P that are first-order definable (with parameters) in M. Suppose that p \in G and D \in Df. Then for some q \in G extending p, q \in D. Proof. Let D0 be the set of p' \in D that either extend p or have no extension in D that extends p. We leave it as a straightforward exercise to show that D0 is dense, and D0 is clearly first-order definable (with parameters) in M. So by genericity of G, we may pick q \in D0 such that q \in G. Thus q \in D. By definition of generic, some extension q1 of both p and q belongs to G. Pick q2 \in D extending q1; thus q has an extension in D that extends p (namely, q2), so by definition of D0, q extends p. -| Definition of forcing. Let phi(x1,...,xk) be a first-order formula in L[g] and let p \in P. We define a formula of L, denoted ``p ||- phi'' (``p forces phi''), by recursion on phi (in the metatheory) as follows. (Here, we view ``or'' and ``forall'' as abbreviations.) If phi is atomic, then let phi'(A) be the result of replacing, inside-out, each subterm of the form g(x_1,...,x_Nb) with the term (cdr (assoc-equal (list x_1 ... x_Nb) A)), where A is neither p nor a variable occurring in phi. Then p ||- phi is defined as follows: ``The set {A \in P: A extends p and phi'(A)} is dense beyond p''. That is, p ||- phi is the following formula: (forall p1 \in P extending p) (exists p2 \in P extending p1) phi'(p2). p ||- ~phi is: (forall p' \in P extending p) ~(p' ||- phi) p ||- phi_1 & phi_2 is: (p ||- phi_1) & (p ||- phi_2) p ||- (exists x) phi is: (exists x) (p ||- phi) We will need the following definition later. Definition. p ||-w phi (p [3mweakly forces[0m phi) is an abbreviation for p ||- ~~phi. The following exercises were suggested by John Cowles as a means for gaining familiarity with the definition of forcing. Exercise 1. Consider the formula (phi_1 OR phi_2) as an abbreviation for ~(~phi_1 & ~phi_2), Show that p ||- (phi_1 OR phi_2) is equivalent to the following. (forall p' \in P extending p) (exists p'' \in P extending p') ((p'' ||- phi_1) OR (p'' ||- phi_2)) Exercise 2. Consider the formula (forall x)phi as an abbreviation for ~(exists x)~phi, Show that p ||- (forall x)phi is equivalent to the following. (forall x) (forall p1 \in P extending p) (exists p2 \in P extending p1) (p2 ||- phi). Exercise 3. Prove that p ||-w phi is equivalent to the following. (forall p' \in P extending p) (exists p'' \in P extending p') (p'' ||- phi). Exercise 4. Let phi be a formula of L[g]. Prove: M |= (p ||- phi)[s[p<-p0]] implies M |= (p ||-w phi)[s[p<-p0]]. Exercise 5. Let phi be a formula of L[g]. Prove: M |= (p ||- ~phi)[s[p<-p0]] iff M |= (p ||-w ~phi)[s[p<-p0]]. [End of exercises.] The definition of forcing stipulates how to view ``p ||- phi(x1,...,xk)'' as a new formula theta(p,x1,...,xk). That is, ``||-'' transforms formulas, so for any first-order formula phi, ``p ||- phi'' is just another first-order formula. That observation shows that a formula such as ((p ||- phi) OR (p ||- ~phi)) is really just another first-order formula. The following proposition thus follows easily. Proposition 3. For any formula phi of L[g], {p0: M |= ((p ||- phi) OR (p ||- ~phi))[s[p<-p0]]]} is a dense subset of P, which (since it is first-order definable with parameters in M) intersects G. -| The following proposition is easily proved by a structural induction on phi, and is left to the reader. Proposition 4. Let phi be a formula of L[g]. Suppose p0 \in P, p1 \in P, M |= (p ||- phi)[s[p<-p0]], and p1 extends p0. Then M |= (p ||- phi)[s[p<-p1]]. -| We will also need the following. Proposition 5. The following is dense for any finite set S of Nf-tuples: {p \in P: for some <x_1 ... x_Nf> \in S, (list x_1 ... x_Nf) \in strip-cars(p)}. Thus, the function g0 is a total function. -| The next lemma tells us that the sentences true in M[G] are those that are forced by an element of G. Truth Lemma. Let phi be a formula in L[g], let s be an assignment to the free variables of phi, and let p be a variable not in the domain of s. Then M[G] |= phi[s] iff for some p0 \in G, M |= (p ||- phi)[s[p<-p0]]. Proof. The proof is by induction on the structure of phi. First suppose phi is atomic. Let D* be the set of elements p0 \in P such that every assoc-equal evaluation from the definition of forcing phi returns a pair when A is bound to p0. (Intuitively, this means that p0 is a sufficiently large approximation from any G containing p0 to make sense of phi in M[G].) We make the following claim. (*) For all p0 \in G such that p0 \in D*, M[G] |= phi[s] iff M |= (p ||- phi)[s[p<-p0]]. To prove the claim, fix p0 in both G and D*, and recall the function g0 constructed from G in the definition of M[G]. Suppose that t_1, ..., t_Nf are terms and g(t_1, ..., t_Nf) is a subterm of phi. Then s assigns a value in M to each of the t_i. Let a_i be the value assigned by s to t_i. Then g0(a_1, ..., a_Nf) = (cdr (assoc-equal (list a_1 ... a_Nf) p0)), as the assoc-equal is a pair (since p0 \in D*) and has the indicated value (because p0 \in G). It follows by the definition of formula phi' in the definition of forcing: M[G] |= phi[s] iff M |= phi'(p)[s[p<-p0]] Moreover, because p0 \in D* it is clear that this holds if p0 is replaced by an arbitrary extension of p0. Then (*) easily follows. By Proposition 5, D* is dense, so there is some p0 in the intersection of D* and G. The forward direction of the conclusion then follows by (*). The reverse direction is clear from (*) by application of Proposition 2 to D* and Proposition 4. Next, suppose M[G] |= ~phi[x]. Then it is not the case that M[G] |= phi, so by the inductive hypothesis, there is no p0 \in G for which M |= (p ||- phi)[s[p<-p0]]. By Proposition 3, there is p0 \in G for which M |= (p ||- ~phi)[s[p<-p0]]. For the other direction, suppose it is not the case that M[G] |= ~phi[s]. So M[G] |= phi[s], and by the inductive hypothesis, there is p0 \in G for which M |= (p ||- phi)[s[p<-p0]]. It follows that there is no p1 \in G for which M |= (p ||- ~phi)[s[p<-p1]], since from such p1 we can find a common extension p2 of p0 and p1 (since G is generic), and since p2 extends p0 then by Proposition 4, M |= (p ||- phi)[s[p<-p2]], contradicting (by definition of forcing) M |= (p ||- ~phi)[s[p<-p1]] since p2 extends p1. The case (phi_1 & phi_2) follows easily from the inductive hypothesis. For the forward direction, apply Proposition 4 and the observation that by genericity, if p0 \in G and p1 \in G then p0 and p1 have a common extension in G. Finally, the case (exists x) phi follows trivially from the inductive hypothesis. -| Truth Lemma Corollary. The Truth Lemma holds with ||-w replacing ||-. Proof. This is clear by applying the Truth Lemma to ~~phi. -| Here is our main theorem. Recall that all first-order theories in our ACL2 context satisfy the e0-induction scheme. Theorem. M[G] satisfies e0-induction. Proof. We consider an arbitrary instance of e0-induction in L[g], stated using a strict well-founded relation <| and a formula phi. We write phi(y) to indicate that y may be among the free variables of phi, and phi(y<-x) to denote the result of substituting x for y in phi. theta: (forall y) [((forall x <| y) phi(y<-x)) -> phi(y)] -> (forall y) phi(y) Our goal is to prove that theta holds in M[G]. Below, we abuse notation by leaving assignments implicit and by writing ``p ||- phi(y0)'' to signify that the formula (p ||- phi(y)) is true in M under the extension of the explicit assignment that binds y to y0. We believe that the intended meaning will be clear. Consider the following set D. D = {p \in P: either p ||-w phi(y0) for all y0, or else for some y0, p ||- ~phi(y0) and for all y1 <| y0 p ||-w phi(y1)}. The set D is clearly first-order definable (with parameters) in M. We claim that D is a dense subset of P. For suppose p0 \in P; we find p1 \in D extending p0, as follows. If p0 ||-w phi(y0) for all y0, then we may take p1 to be p0. Otherwise, by definition of ||-w and ||-, there is some y0 such that for some extension p0' of p0, p0' ||- ~phi(y0). Pick a <|-minimal such y0, and correspondingly pick p1 so that p1 extends p0 and p1 ||- ~phi(y0). In order to show that p1 \in D, it remains to show that for all y1 <| y0, p1 ||-w phi(y1), i.e., there is no q extending p1 such that q ||- ~phi(y1). This is indeed the case since otherwise q and y1 would contradict the <|-minimality of y0. Applying the genericity of G and just-proved density of D, pick p0 \in G such that p0 \in D. If p0 ||-w phi(y0) for all y0, then by the Truth Lemma Corollary, M[G] |= phi(y0) for all y0, and thus M[G] |= theta. Otherwise, since p0 \in D we may choose y0 such that p0 ||- ~phi(y0) and for all y1 <| y0, p0 ||-w phi(y1). By the Truth Lemma and its corollary, since p0 \in G we have: (1) M[G] |= ~phi(y0). (2) For all y1 <| y0, M[G] |= phi(y1). It follows that the antecedent of theta is false in M[G], as witnessed by y = y0; thus M[G] |= theta. -| Remark. We close by returning, as promised above, to the question of why so much care is necessary in constructing an expansion of M. We assume familiarity here with the notion of a ``non-standard'' natural number of M, i.e., one that is greater than the interpretation of any term that has the form (+ 1 1 1 ... 1). Here is a very simple example that illustrates the need for some care. Consider the following event, which introduces a function foo with the following property: for all x, if natp(x) then natp(foo(x)). (defchoose foo (y) (x) (implies (natp x) (natp y))) Certainly we can build a model of the above property from a model M of the ground-zero theory, by interpreting foo so that for all x for which M satisfies natp(x), foo(x) is also a natp in M. But suppose we start with a non-standard model M of the ground-zero theory, and we happen to define foo(x) to be 1 for all non-standard natural numbers x and 0 for all other x. The resulting expansion of M will not satisfy the e0-induction scheme or even the ordinary natural number induction scheme: foo(0)=0 holds in that expansion as does the implication foo(n)=0 => foo(n+1)=0 for every natural number n of M, standard or not; and yet foo(k)=0 fails for every non-standard natural number k of M.") (conses (programming) "A [31;1mcons[0m is an ordered pair. In ACL2, data structures like [lists], [alists], etc., are made up of conses. Subtopics [Atom] Recognizer for atoms [Caaaar] [47m[car][0m of the [47m[caaar][0m [Caaadr] [47m[car][0m of the [47m[caadr][0m [Caaar] [47m[car][0m of the [47m[caar][0m [Caadar] [47m[car][0m of the [47m[cadar][0m [Caaddr] [47m[car][0m of the [47m[caddr][0m [Caadr] [47m[car][0m of the [47m[cadr][0m [Caar] [47m[car][0m of the [47m[car][0m [Cadaar] [47m[car][0m of the [47m[cdaar][0m [Cadadr] [47m[car][0m of the [47m[cdadr][0m [Cadar] [47m[car][0m of the [47m[cdar][0m [Caddar] [47m[car][0m of the [47m[cddar][0m [Cadddr] [47m[car][0m of the [47m[cdddr][0m [Caddr] [47m[car][0m of the [47m[cddr][0m [Cadr] [47m[car][0m of the [47m[cdr][0m [Car] Returns the first element of a non-empty list, else [47mnil[0m [Cdaaar] [47m[cdr][0m of the [47m[caaar][0m [Cdaadr] [47m[cdr][0m of the [47m[caadr][0m [Cdaar] [47m[cdr][0m of the [47m[caar][0m [Cdadar] [47m[cdr][0m of the [47m[cadar][0m [Cdaddr] [47m[cdr][0m of the [47m[caddr][0m [Cdadr] [47m[cdr][0m of the [47m[cadr][0m [Cdar] [47m[cdr][0m of the [47m[car][0m [Cddaar] [47m[cdr][0m of the [47m[cdaar][0m [Cddadr] [47m[cdr][0m of the [47m[cdadr][0m [Cddar] [47m[cdr][0m of the [47m[cdar][0m [Cdddar] [47m[cdr][0m of the [47m[cddar][0m [Cddddr] [47m[cdr][0m of the [47m[cdddr][0m [Cdddr] [47m[cdr][0m of the [47m[cddr][0m [Cddr] [47m[cdr][0m of the [47m[cdr][0m [Cdr] Returns the second element of a [47m[cons][0m pair, else [47mnil[0m [Cons] Pair and list constructor [Cons-count-bounded] Count the number of conses (up to a limit) [Cons-with-hint] Alternative to [47m[cons][0m that tries to avoid consing when a suitable [47mcons[0m structure is provided as a hint. [Consp] Recognizer for [cons] pairs [Listp] Recognizer for (not necessarily proper) lists [Subst] A single substitution into a tree") (consp (conses acl2-built-ins) "Recognizer for [cons] pairs [47m(consp x)[0m is true if and only if [47mx[0m is a [cons] pair.") (constraint (encapsulate) "Restrictions on certain functions introduced in [47m[encapsulate][0m [events] Suppose that a given theorem, [47mthm[0m, is to be functionally instantiated using a given functional substitution, [47malist[0m. (See [lemma-instance], or for an example, see [functional-instantiation-example].) What is the set of proof obligations generated? It is the set obtained by applying [47malist[0m to all terms, [47mtm[0m, such that (a) [47mtm[0m mentions some function symbol in the domain of [47malist[0m, and (b) either (i) [47mtm[0m is the ``constraint'' (see below) on a function symbol ancestral in [47mthm[0m or in some [47m[defaxiom][0m or (ii) [47mtm[0m is the body of a [47m[defaxiom][0m. Here, a function symbol is ``ancestral'' in [47mthm[0m if either it occurs in [47mthm[0m, or it occurs in the definition of some function symbol that occurs in [47mthm[0m, and so on. The remainder of this note explains what we mean by ``constraint'' in the words above. For a utility that obtains the constraint for a given function symbol, see [constraint-info]. For help in dealing with failures to prove constraint obligations generated by the [47m:functional-instance[0m hint (see [hints]), see [47m[set-constraint-tracking][0m. In a certain sense, function symbols are introduced in essentially two ways. The most common way is to use [47m[defun][0m (or when there is mutual recursion, [47m[mutual-recursion][0m or [47m[defuns][0m). There is also a mechanism for introducing ``witness functions''; see [defchoose]. The documentation for these [events] describes the axioms they introduce, which we will call here their ``definitional axioms.'' These definitional axioms are generally the constraints on the function symbols that these axioms introduce. However, when a function symbol is introduced in the scope of an [47m[encapsulate][0m event, its constraints may differ from the definitional axioms introduced for it. For example, suppose that a function's definition is [47m[local][0m to the [47m[encapsulate][0m; that is, suppose the function is introduced in the [signature] of the [47m[encapsulate][0m. Then its constraints include, at the least, those non-[47m[local][0m theorems and definitions in the [47m[encapsulate][0m that mention the function symbol. Actually, it will follow from the discussion below that if the [signature] is empty for an [47m[encapsulate][0m, then the constraint on each of its new function symbols is exactly the definitional axiom introduced for it. Intuitively, we view such [47mencapsulates[0m just as we view [47m[include-book][0m [events]. But the general case, where the [signature] is not empty, is more complicated. In the discussion that follows we describe in detail exactly which constraints are associated with which function symbols that are introduced in the scope of an [47m[encapsulate][0m event. In order to simplify the exposition we make two cuts at it. In the first cut we present an over-simplified explanation that nevertheless captures the main ideas. In the second cut we complete our explanation by explaining how we view certain [events] as being ``lifted'' out of the [47m[encapsulate][0m, resulting in a possibly smaller [47m[encapsulate][0m, which becomes the target of the algorithm described in the first cut. At the end of this note we present an example showing why a more naive approach is unsound. Finally, before we start our ``first cut,'' we note that any information you want ``exported'' outside an [47m[encapsulate][0m event must be there as an explicit definition or theorem. For example, even if a function [47mfoo[0m has output type [47m(mv t t)[0m in its [signature], the system will not know [47m(true-listp (foo x))[0m merely on account of this information. Thus, if you are using functions like [47mfoo[0m (constrained [47m[mv][0m functions), then you may find it useful to prove (inside the [47mencapsulate[0m, to be exported) a [47m:[0m[47m[type-prescription][0m rule for the constrained function, for example, the [47m:[0m[47m[type-prescription][0m rule [47m(true-listp (foo x))[0m. [3mFirst cut at constraint-assigning algorithm.[0m Consider the set of formulas introduced by all [events] in the scope of an [47m[encapsulate][0m: * for every [47m[defthm][0m and [47m[defaxiom][0m event, include its formula as well as the formulas of all its corollaries; * for every [47m[defun][0m event, include the formula that equates the body with the application of the function applied to the formals; * for every [47mdefchoose[0m event, include the axiom that it adds (see [defchoose]); * and so on, including axioms added by [47m[defpkg][0m and (recursively) any subsidiary [47mencapsulate[0m events. Then quite simply, all such formulas are conjoined, and each function symbol introduced by the [47m[encapsulate][0m is assigned that conjunction as its constraint. Clearly this is a rather severe algorithm. Let us consider two possible optimizations in an informal manner before presenting our second cut. Consider the (rather artificial) event below. The function [47mbefore1[0m does not refer at all, even indirectly, to the locally-introduced function [47msig-fn[0m, so it is unfortunate to saddle it with constraints about [47msig-fn[0m. (encapsulate (((sig-fn *) => *)) (defun before1 (x) (if (consp x) (before1 (cdr x)) x)) (local (defun sig-fn (x) (cons x x))) (defthm sig-fn-prop (consp (sig-fn x))) ) We would like to imagine moving the definition of [47mbefore1[0m to just in front of this [47m[encapsulate][0m, as follows. (defun before1 (x) (if (consp x) (before1 (cdr x)) x)) (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (cons x x))) (defthm sig-fn-prop (consp (sig-fn x))) ) Thus, we will only assign the constraint [47m(consp (sig-fn x))[0m, from the theorem [47msig-fn-prop[0m, to the function [47msig-fn[0m, not to the function [47mbefore1[0m. More generally, suppose an event in an [47m[encapsulate][0m event does not mention any function symbol in the [signature] of the [47m[encapsulate][0m, nor any function symbol that mentions any such function symbol, and so on. (We might say that no function symbol from the [signature] is an ``ancestor'' of any function symbol occurring in the event.) Then we imagine moving the event, so that it appears in front of the [47m[encapsulate][0m. We don't actually move it, but we pretend we do when it comes time to assign constraints. Thus, such definitions only introduce definitional axioms as the constraints on the function symbols being defined. In the example above, the event [47msig-fn-prop[0m introduces no constraints on function [47mbefore1[0m. Once this first optimization is performed, we have in mind a set of ``constrained functions.'' These are the functions introduced in the [47m[encapsulate][0m that would remain after moving some of them in front, as indicated above. Consider the collection of all formulas introduced by the [47m[encapsulate][0m, except the definitional axioms, that mention these constrained functions. So for example, in the event below, no such formula mentions the function symbol [47mafter1[0m. (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (cons x x))) (defthm sig-fn-prop (consp (sig-fn x))) (defun after1 (x) (sig-fn x)) ) We can see that there is really no harm in imagining that we move the definition of [47mafter1[0m out of the [47m[encapsulate][0m, to just after the [47m[encapsulate][0m. Many subtle aspects of this rearrangement process have been omitted. For example, suppose the function [47mfn[0m uses [47msig-fn[0m, the latter being a function in the signature of the encapsulation. Suppose a formula about [47mfn[0m is proved in the encapsulation. Then from the discussion above [47mfn[0m is among the constrained functions of the encapsulate: it cannot be moved before the encapsulate and it cannot be moved after the encapsulation. But why is [47mfn[0m constrained? The reason is that the theorem proved about [47mfn[0m may impose or express constraints on [47msig-fn[0m. That is, the theorem proved about [47mfn[0m may depend upon properties of the witness used for [47msig-fn[0m. Here is a simple example: (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (declare (ignore x)) 0)) (defun fn (lst) (if (endp lst) t (and (integerp (sig-fn (car lst))) (fn (cdr lst))))) (defthm fn-always-true (fn lst))) In this example, there are no [47m[defthm][0m events that mention [47msig-fn[0m explicitly. One might therefore conclude that it is completely unconstrained. But the witness we chose for it always returns an integer. The function [47mfn[0m uses [47msig-fn[0m and we prove that [47mfn[0m always returns true. Of course, the proof of this theorem depends upon the properties of the witness for [47msig-fn[0m, even though those properties were not explicitly ``called out'' in theorems proved about [47msig-fn[0m. It would be unsound to move [47mfn-always-true[0m after the encapsulate. It would also be unsound to constrain [47msig-fn[0m to satisfy just [47mfn-always-true[0m without including in the constraint the relation between [47msig-fn[0m and [47mfn[0m. Hence both [47msig-fn[0m and [47mfn[0m are constrained by this encapsulation and the constraint imposed on each is the same and states the relation between the two as characterized by the equation defining [47mfn[0m as well as the property that [47mfn[0m always returns true. Suppose, later, one proved a theorem about [47msig-fn[0m and wished to functionally instantiate it. Then one must also functionally instantiate [47mfn[0m, even if it is not involved in the theorem, because it is only through [47mfn[0m that [47msig-fn[0m inherits its constrained properties. This is a pathological example that illustrate a trap into which one may easily fall: rather than identify the key properties of the constrained function the user has foreshadowed its intended application and constrained those notions. Clearly, the user wishing to introduce the [47msig-fn[0m above would be well-advised to use the following instead: (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (declare (ignore x)) 0)) (defthm integerp-sig-fn (integerp (sig-fn x)))) (defun fn (lst) (if (endp lst) t (and (integerp (sig-fn (car lst))) (fn (cdr lst))))) (defthm fn-always-true (fn lst))) Note that [47msig-fn[0m is constrained merely to be an integer. It is the only constrained function. Now [47mfn[0m is introduced after the encapsulation, as a simple function that uses [47msig-fn[0m. We prove that [47mfn[0m always returns true, but this fact does not constrain [47msig-fn[0m. Future uses of [47msig-fn[0m do not have to consider [47mfn[0m at all. Sometimes it is necessary to introduce a function such as [47mfn[0m within the [47mencapsulate[0m merely to state the key properties of the undefined function [47msig-fn[0m. But that is unusual and the user should understand that both functions are being constrained. Another subtle aspect of encapsulation that has been brushed over so far has to do with exactly how functions defined within the encapsulation use the signature functions. For example, above we say ``Consider the collection of all formulas introduced by the encapsulate, [3mexcept the definitional axioms[0m, that mention these constrained functions.'' We seem to suggest that a definitional axiom which mentions a constrained function can be moved out of the encapsulation and considered part of the ``post-encapsulation'' extension of the logical [world], if the defined function is not used in any non-definitional formula proved in the encapsulation. For example, in the encapsulation above that constrained [47msig-fn[0m and introduced [47mfn[0m within the encapsulation, [47mfn[0m was constrained because we proved the formula [47mfn-always-true[0m within the encapsulation. Had we not proved [47mfn-always-true[0m within the encapsulation, [47mfn[0m could have been moved after the encapsulation. But this suggests an unsound rule because whether such a function can be moved after the encapsulate depend on whether its [3madmission[0m used properties of the witnesses! In particular, we say a function is ``subversive'' if any of its governing tests or the actuals in any recursive call involve a function in which the signature functions are ancestral. See [infected-constraints] and see [subversive-recursions]. (Aside: The definition of [47mfn[0m in the first encapsulation above that defines [47mfn[0m, i.e., the encapsulation with [47mfn-always-true[0m inside, is subversive because the call of the macro [47m[and][0m expands to a call of [47mIF[0m that governs a recursive call of [47mfn[0m, in this case: (defun fn (lst) (if (endp lst) t (if (integerp (sig-fn (car lst))) (fn (cdr lst)) nil))). If we switch the order of conjuncts in [47mfn[0m, then the definition of [47mfn[0m is no longer subversive, but it still ``infects'' the constraint generated for the encapsulation, hence for [47msig-fn[0m, because [47mfn-always-true[0m blocks the definition of [47mfn[0m from being moved back (to after the encapsulation). Also see [infected-constraints]. If we both switch the order of conjuncts and drop [47mfn-always-true[0m from the encapsulation, then the definition of [47mfn[0m is in essence moved back to after the encapsulation, and the constraint for [47msig-fn[0m no longer includes the definition of [47mfn[0m. End of aside.) Another aspect we have not discussed is what happens to nested encapsulations when each introduces constrained functions. We say an [47mencapsulate[0m event is ``trivial'' if it introduces no constrained functions, i.e., if its list of signatures is [47mnil[0m. Trivial encapsulations are just a way to wrap up a collection of events into a single event. From the foregoing discussion we see we are interested in exactly how we can ``rearrange'' the events in a non-trivial encapsulation --- moving some ``before'' the encapsulation and others ``after'' the encapsulation. We are also interested in which functions introduced by the encapsulation are ``constrained'' and what the ``constraints'' on each are. We may summarize the observations above as follows, after which we conclude with a more elaborate example. [3mSecond cut at constraint-assigning algorithm.[0m First, we focus only on non-trivial encapsulations that neither contain nor are contained in non-trivial encapsulations. (Nested non-trivial encapsulations are not rearranged at all: do not put anything in such a nest unless you mean for it to become part of the constraints generated.) Second, in what follows we only consider the non-[47mlocal[0m events of such an [47mencapsulate[0m, assuming that they satisfy the restriction of using no locally defined function symbols other than the signature functions. Given such an [47mencapsulate[0m event, move, to just in front of it and in the same order, all definitions and theorems for which none of the signature functions is ancestral. Now collect up all formulas (theorems) introduced in the [47m[encapsulate][0m other than definitional axioms. Add to this set any of those definitional equations that is either subversive or defines a function used in a formula in the set. The conjunction of the resulting set of formulas is called the ``constraint'' and the set of all the signature functions of the [47mencapsulate[0m together with all function symbols defined in the [47mencapsulate[0m and mentioned in the constraint is called the ``constrained functions.'' Assign the constraint to each of the constrained functions. Move, to just after the [47mencapsulate[0m, the definitions of all function symbols defined in the [47mencapsulate[0m that have been omitted from the constraint. Implementation note. In the implementation we do not actually move [events], but we create constraints that pretend that we did. Here is an example illustrating our constraint-assigning algorithm. It builds on the preceding examples. (encapsulate (((sig-fn *) => *)) (defun before1 (x) (if (consp x) (before1 (cdr x)) x)) (local (defun sig-fn (x) (cons x x))) (defthm sig-fn-prop (consp (sig-fn x))) (defun during (x) (if (consp x) x (cons (car (sig-fn x)) 17))) (defun before2 (x) (before1 x)) (defthm before2-prop (atom (before2 x))) (defthm during-prop (implies (and (atom x) (before2 x)) (equal (car (during x)) (car (sig-fn x))))) (defun after1 (x) (sig-fn x)) (defchoose after2 (x) (u) (and (< u x) (during x))) ) Only the functions [47msig-fn[0m and [47mduring[0m receive extra constraints. The functions [47mbefore1[0m and [47mbefore2[0m are viewed as moving in front of the [47m[encapsulate][0m, as is the theorem [47mbefore2-prop[0m. The functions [47mafter1[0m and [47mafter2[0m are viewed as being moved past the [47m[encapsulate][0m. The implementation reports the following. In addition to SIG-FN, we export AFTER2, AFTER1, BEFORE2, DURING and BEFORE1. The following constraint is associated with both of the functions DURING and SIG-FN: (AND (EQUAL (DURING X) (IF (CONSP X) X (CONS (CAR (SIG-FN X)) 17))) (CONSP (SIG-FN X)) (IMPLIES (AND (ATOM X) (BEFORE2 X)) (EQUAL (CAR (DURING X)) (CAR (SIG-FN X))))) Notice that the formula [47m(consp (during x))[0m is not a conjunct of the constraint. During the first pass of the [47mencapsulate[0m, this formula is stored as a [47m:[0m[47m[type-prescription][0m rule deduced during the definition of the function [47mduring[0m. However, the rule is not exported because of a rather subtle soundness issue. (If you are interested in details, see the comments in source function [47mputprop-type-prescription-lst[0m.) We conclude by asking (and to a certain extent, answering) the following question: Isn't there an approach to assigning constraints that avoids over-constraining more simply than our ``second cut'' above? Perhaps it seems that given an [47m[encapsulate][0m, we should simply assign to each locally defined function the theorems exported about that function. If we adopted that simple approach the events below would be admissible. (encapsulate (((foo *) => *)) (local (defun foo (x) x)) (defun bar (x) (foo x)) (defthm bar-prop (equal (bar x) x) :rule-classes nil)) (defthm foo-id (equal (foo x) x) :hints (("Goal" :use bar-prop))) ; The following event is not admissible in ACL2. (defthm ouch! nil :rule-classes nil :hints (("Goal" :use ((:functional-instance foo-id (foo (lambda (x) (cons x x)))))))) Under the simple approach we have in mind, [47mbar[0m is constrained to satisfy both its definition and [47mbar-prop[0m because [47mbar[0m mentions a function declared in the signature list of the encapsulation. In fact, [47mbar[0m is so-constrained in the ACL2 semantics of encapsulation and the first two events above (the [47mencapsulate[0m and the consequence that [47mfoo[0m must be the identity function) are actually admissible. But under the simple approach to assigning constraints, [47mfoo[0m is unconstrained because no theorem about it is exported. Under that approach, [47mouch![0m is provable because [47mfoo[0m can be instantiated in [47mfoo-id[0m to a function other than the identity function. It's tempting to think we can fix this by including definitions, not just theorems, in constraints. But consider the following slightly more elaborate example. The problem is that we need to include as a constraint on [47mfoo[0m not only the definition of [47mbar[0m, which mentions [47mfoo[0m explicitly, but also [47mabc[0m, which has [47mfoo[0m as an ancestor. (encapsulate (((foo *) => *)) (local (defun foo (x) x)) (local (defthm foo-prop (equal (foo x) x))) (defun bar (x) (foo x)) (defun abc (x) (bar x)) (defthm abc-prop (equal (abc x) x) :rule-classes nil)) (defthm foo-id (equal (foo x) x) :hints (("Goal" :use abc-prop))) ; The following event is not admissible in ACL2. (defthm ouch! nil :rule-classes nil :hints (("Goal" :use ((:functional-instance foo-id (foo (lambda (x) (cons x x))) (bar (lambda (x) (cons x x)))))))) Subtopics [Constraint-info] Obtaining the [constraint] on a function symbol") (constraint-info (system-utilities constraint) "Obtaining the [constraint] on a function symbol See [constraint]s for relevant background. [47mConstraint-info[0m is a rather technical system utility, and detailed documentation may be found in comments in the ACL2 source code, in particular in the definition of [47mconstraint-info[0m. Here we give only an overview of this utility. For a function symbol, [47mfn[0m, and a logical [world], [47mwrld[0m --- for example, the current world, [47m(w state)[0m --- evaluation of the form [47m(constraint-info fn wrld)[0m returns [47m(mv flg x origins)[0m, as follows. When [47mflg[0m is [47mnil[0m, [47mx[0m is a term and [47morigins[0m is a single [3morigin token[0m such as [47m(DEFUN FN)[0m, indicating the source of the constraint, [47mx[0m, on [47mfn[0m. When [47mflg[0m is non-[47mnil[0m it is a function name, and usually [47mx[0m is a list of terms and [47morigins[0m is an equally long list of corresponding origin tokens; but there is a special case if the constraints are unknown, as can be the case with use of [47m[partial-encapsulate][0m. We illustrate with the following example. (encapsulate (((f1 *) => *) ((f3 *) => *)) (local (defun f1 (x) x)) (defun f2 (x) (f1 x)) (local (defun f3 (x) x)) (defun f4 (x) (f3 x)) (defthm f1-prop (equal (f1 x) (f4 x)))) Then we can see the results of [47mconstraint-info[0m on each introduced function symbol, as follows. ACL2 !>(let ((wrld (w state))) (list 'result 'f1 (mv-let (flg1 x1 origin1) (constraint-info 'f1 wrld) (list flg1 x1 origin1)) 'f2 (mv-let (flg2 x2 origin2) (constraint-info 'f2 wrld) (list flg2 x2 origin2)) 'f3 (mv-let (flg3 x3 origin3) (constraint-info 'f3 wrld) (list flg3 x3 origin3)) 'f4 (mv-let (flg4 x4 origin4) (constraint-info 'f4 wrld) (list flg4 x4 origin4)))) (RESULT F1 (F1 ((EQUAL (F4 X) (F3 X)) (EQUAL (F1 X) (F4 X))) ((DEFUN F4) (THEOREM F1-PROP))) F2 (NIL (EQUAL (F2 X) (F1 X)) (DEFUN F2)) F3 (F1 ((EQUAL (F4 X) (F3 X)) (EQUAL (F1 X) (F4 X))) ((DEFUN F4) (THEOREM F1-PROP))) F4 (F1 ((EQUAL (F4 X) (F3 X)) (EQUAL (F1 X) (F4 X))) ((DEFUN F4) (THEOREM F1-PROP)))) ACL2 !> Notice that the flag (first result) for [47mf2[0m is [47mnil[0m, because even though the definition of [47mf2[0m is lexically inside the [47mencapsulate[0m, it doesn't affect the constraints because it can be safely moved to just after the [47mencapsulate[0m. However, the definition of [47mf4[0m does affect (or ``infect''; see [subversive-recursions]) the constraints: it can't be moved to after the [47mencapsulate[0m because of the [47mdefthm[0m after it.") (constraint-tracking (encapsulate) "Generate markers to indicate origins of constraints See [47m[set-constraint-tracking][0m.") (context (pointers) "See [ctx].") (context-message-pair (kestrel-utilities system-utilities-non-built-in) "A common ACL2 programming idiom: [error-triple]s without [state] [3mContext-message pairs[0m are of the form [47m(mv erp val)[0m, where there are the following two cases: the first indicates a successful computation and the second indicates an error. * [31;1mNormal case[0m: [47merp[0m is [47mnil[0m and [47mval[0m is what we call the ``value'' of that context-message pair. * [31;1mError case[0m: [47merp[0m is not [47mnil[0m. [47mVal[0m may be [47mnil[0m; otherwise [47mval[0m is a message (see [msgp]) suitable for printing with [47m[fmt][0m and related functions using the [47m~@[0m directive, and [47merp[0m is a context suitable for error messages (see [ctx]). A convention generally observed (for example, by ACL2 system function [47mcmp-to-error-triple[0m, which converts a context-message pair to an [error-triple] that may be printed in the error case) is when [47merp[0m and [47mval[0m are both non-[47mnil[0m, then [47merp[0m is not [47mt[0m. To see how this works let us consider the ACL2 source function, [47mtranslate-cmp[0m, whose input is a user-level (``untranslated'') term as input and returns a context-message pair. In the non-error case, the value returned is the internal (``translated'') form of that input; see [term]. The log below first shows a successful translation, returning multiple values [47m(mv nil (binary-+ x '3))[0m, thus illustrating the ``Normal case'' above, where the first value returned (the error indicator) is [47mnil[0m and the second is the value of the pair. The second example in the log shows an error case returning a context and a message. Don't worry about the various arguments of [47mtranslate-cmp[0m; the examples are merely to illustrate programming with context-message pairs, not to explain [47mtranslate-cmp[0m! ACL2 !>(translate-cmp '(+ x 3) t t t 'top (w state) (default-state-vars state)) (NIL (BINARY-+ X '3)) ACL2 !>(translate-cmp '(quote 3 4) t t t 'top (w state) (default-state-vars state)) (TOP ("The proper form of a quoted constant is (quote x), but ~ ~x0 is not of this form." (#0 QUOTE 3 4))) ACL2 !> The following macros are useful when programming with context-message pairs. * [47m(value-cmp x)[0m: same as [47m(mv nil x)[0m. Example: ACL2 !>(value-cmp (* 3 4)) (NIL 12) ACL2 !> * [47m(er-cmp ctx str &rest args)[0m: Return [47m(mv ctx msg)[0m where [47mmsg[0m is formed from [47mstr[0m and [47margs[0m. Example: ACL2 !>(er-cmp 'example "I don't like 3-element lists like ~x0.~|" (make-list 3)) (EXAMPLE ("I don't like 3-element lists like ~x0.~|" (#0 NIL NIL NIL))) ACL2 !>(mv-let (ctx msg) (er-cmp 'example "I don't like 3-element lists like ~x0.~|" (make-list 3)) (fmx "Error in ~x0: ~@1" ctx msg)) Error in EXAMPLE: I don't like 3-element lists like (NIL NIL NIL). (0 <state>) ACL2 !> * [47m(er-let*-cmp alist body)[0m: Analogue of [47m[er-let*][0m for context-message pairs. So, it evaluates the bindings in [47malist[0m much as [47m[let*][0m-bindings would be evaluated, but where each expression should return a context-message pair and so should [47mbody[0m. If any of those expression evaluations returns a pair with a non-nil first value, then that pair is returned. Otherwise, [47mbody[0m --- which should return a context-message pair --- is evaluated with respect to the resulting bindings. Examples (refer to previous examples that use [47mtranslate-cmp[0m): ACL2 !>(er-let*-cmp ((x (value-cmp '(+ x 3))) (val (translate-cmp x t t t 'top (w state) (default-state-vars state))) (y (value-cmp (list :term val)))) (value-cmp (list :result y))) (NIL (:RESULT (:TERM (BINARY-+ X '3)))) ACL2 !>(er-let*-cmp ((x (value-cmp '(quote 3 4))) (val (translate-cmp x t t t 'top (w state) (default-state-vars state))) (y (value-cmp (list :term val)))) (value-cmp (list :result y))) (TOP ("The proper form of a quoted constant is (quote x), but ~ ~x0 is not of this form." (#0 QUOTE 3 4))) ACL2 !> * [47m(er-progn-cmp form1 ... formk)[0m: Each [47mformi[0m should evaluate to a context-message pair. If any of these evaluations produces a pair with a non-[47mnil[0m first component (thus indicating an error), return that pair. Otherwise return the context-message pair produced by evaluating [47mformk[0m. Examples: ACL2 !>(er-progn-cmp (value-cmp (+ 2 8)) (er-cmp 'top "Ouch") (value-cmp (* 3 4))) (TOP ("Ouch")) ACL2 !>(er-progn-cmp (value-cmp (+ 2 8)) (value-cmp (* 3 4))) (NIL 12) ACL2 !>") (copyright (about-acl2) "ACL2 copyright, license, authorship This topic provides information about copyright, license, and authorship of the ACL2 system. For information about copyright and authorship of [documentation], see [documentation-copyright], which notes that there are many documentation authors. ACL2 Version 8.6 --- A Computational Logic for Applicative Common Lisp Copyright (C) 2026, Regents of the University of Texas This version of ACL2 is a descendant of ACL2 Version 1.9, Copyright (C) 1997 Computational Logic, Inc. See the documentation topic NOTE-2-0. This program is free software; you can redistribute it and/or modify it under the terms of the LICENSE file distributed with ACL2. This program 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 LICENSE for more details. Written by: Matt Kaufmann and J Strother Moore email: Kaufmann@cs.utexas.edu and Moore@cs.utexas.edu Department of Computer Science University of Texas at Austin Austin, TX 78712 U.S.A. Please also see [acknowledgments]. Subtopics [Documentation-copyright] Copyright and authorship of documentation") (corollary (rule-classes) "The corollary formula of a [rune] See [formula]. This is a low-level system function at the present time. See [pr] and see [pr!] instead. Also see [rule-classes] for the use of the symbol [47m:corollary[0m in specifying a rule class.") (corroborating_models (pages_written_especially_for_the_tours) "Corroborating Models {IMAGE} (see [Models_of_Computer_Hardware_and_Software]) After producing a model, it must be [31;1mcorroborated[0m against reality. The Falling Body Model has been corroborated by a vast number of experiments in which the time and distance were measured and compared according to the formula. In general all models must be corroborated by experiment. The Falling Body Model can be derived from deeper models, namely Newton's laws of motion and the assertion that, over the limited distances concerned, gravitation exerts a constant acceleration on the object. When the model in question can be derived from other models, it is the other models that are being corroborated by our experiments. Because nature is not formal, we cannot [31;1mprove[0m that our models of it are correct. All we can do is test our models against nature's behavior. Such testing often exposes restrictions on the applicability of our models. For example, the Falling Body Model is inaccurate if air resistance is significant. Thus, we learn not to use that model to predict how long it takes a feather to fall from a 200 foot tower in the earth's atmosphere. In addition, attempts at corroboration might reveal that the model is actually incorrect. Careful measurements might expose the fact that the gravitational force increases as the body falls closer to earth. Very careful measurements might reveal relativistic effects. Technically, the familiar Falling Body Model is just wrong, even under excessive restrictions such as ``in a perfect vacuum'' and ``over small distances.'' But it is an incredibly useful model nonetheless. There are several morals here. [31;1mModels need not be complete to be useful.[0m [31;1mModels need not be perfectly accurate to be useful.[0m [31;1mThe user of a model must understand its limitations.[0m {IMAGE} (see [Models_of_Computer_Hardware_and_Software])") (count (lists strings acl2-built-ins) "Count the number of occurrences of an item in a string or true-list Example Forms: (count #\D "DabcDefcDe") ; = 3 (count #\D "DabcDefcDe" :start 1) ; = 2 (count #\D "DabcDefcDe" :start 1 :end 5) ; = 1 (count #\D "DabcDefcDe" :start 1 :end 4) ; = 0 (count #\z "DabcDefcDe") ; = 0 (count '(a b) '(17 (a b) 23 (a b) (c d))) ; = 2 General Form: (count item sequence &key start end) [47m(Count item sequence)[0m returns the number of times [47mitem[0m occurs in [47msequence[0m. The [guard] for calls of [47mcount[0m (which is actually a macro in ACL2) specifies that [47msequence[0m is a string or a true-list, and that [47mstart[0m, which defaults to 0, and [47mend[0m, which defaults to the length of [47msequence[0m, are valid indices into sequence. See any Common Lisp documentation for more information about [47mcount[0m, which is a Common Lisp utility. At this time ACL2 does not support keyword arguments for [47mcount[0m other than [47m:start[0m and [47m:end[0m; we may add support for the [47m:from-end[0m keyword upon request. [31;1mMacro: [0m<count> (defmacro count (item sequence &key (start '0) end) (cons 'count-fn (cons item (cons sequence (cons start (cons end 'nil))))))") (count-keys (stobj acl2-built-ins) "Count the number of keys in association list [47m(Count-keys al)[0m returns the number of distinct keys in an association list. [47mCount-keys[0m has a guard of [47mt[0m. This function is called in the body of function, [47m<h>-count[0m where [47m<h>[0m is a hash-table field of a [stobj]. See [defstobj]. [31;1mFunction: [0m<hons-remove-assoc> (defun hons-remove-assoc (k x) (declare (xargs :guard t)) (if (atom x) nil (if (and (consp (car x)) (not (equal k (caar x)))) (cons (car x) (hons-remove-assoc k (cdr x))) (hons-remove-assoc k (cdr x))))) [31;1mFunction: [0m<count-keys> (defun count-keys (al) (declare (xargs :guard t)) (if (atom al) 0 (if (consp (car al)) (+ 1 (count-keys (hons-remove-assoc (caar al) (cdr al)))) (count-keys (cdr al)))))") (course-materials (documentation) "Some ACL2 course materials The links listed below will take you to materials for some courses that involve ACL2. This list is loosely maintained and incomplete, and is given in no particular order. We strongly encourage you to send email to {Matt Kaufmann | mailto:kaufmann@cs.utexas.edu} and {J Strother Moore | mailto:moore@cs.utexas.edu} if you have additional such links to contribute; or if you are a contributor to the ACL2 [community-books], please feel free to add them yourself. * See [recursion-and-induction] for notes you can use to teach yourself how to prove theorems about recursively defined functions using mathematical induction. That document started as notes for the course ``Recursion and Induction'' in the Department of Computer Science of the University of Texas at Austin. * {Courses taught by Pete Manolios | https://www.ccs.neu.edu/home/pete/teaching.html}, which use the ACL2 Sedan (ACL2s) (see [ACL2-SEDAN]), including {one taught at Northeastern in Spring 2020 | https://www.ccs.neu.edu/home/pete/courses/Logic-and-Computation/2020-Spring/} * The following two interfaces to ACL2 support the teaching of ACL2 to undergraduates: * The ACL2 Sedan (ACL2s) (see [ACL2-SEDAN]) * {DrACuLa | http://dracula-lang.github.io/index.html} * John Cowles, {COSC5010: Formalizing the JVM in ACL2 | http://www.cs.uwyo.edu/~cowles/jvm-acl2/}, Univ. of Wyoming * Links to some of Warren Hunt's courses, many of which use ACL2, may be found {here | http://www.cs.utexas.edu/users/hunt/class/index.html}. * Links to some of J Moore's courses, many of which use ACL2, may be found {here | http://www.cs.utexas.edu/users/moore/classes/index.html}.") (cpu-core-count (parallelism acl2-built-ins) "The number of cpu cores This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. Unless the ACL2 executable supports parallel execution (see [parallelism]), this function returns [47m(mv 1 state)[0m. Otherwise: [47m(Cpu-core-count state)[0m returns [47m(mv core-count state)[0m, where [47mcore-count[0m is determined as follows. If environment variable [47mACL2_CORE_COUNT[0m has a non-empty value, then that value should represent a positive integer (else an error occurs), which is the returned [47mcore-count[0m. Otherwise, the returned [47mcore-count[0m may be obtained from the underlying Common Lisp implementation, else as a positive integer value from [state] global variable [47m'cpu-core-count[0m (see [assign]). Otherwise an error occurs. Example: (cpu-core-count state) ==> (mv 4 state) [47mCpu-core-count[0m has the following logical definition. [31;1mFunction: [0m<cpu-core-count> (defun cpu-core-count (state) (declare (xargs :stobjs state :guard t)) (mv-let (nullp val state) (read-acl2-oracle state) (declare (ignore nullp)) (mv val state)))") (creating-executable (installation-support) "Creating or obtaining an executable image This topic may be avoided by following the [installation-instructions], which are intended to be self-contained. After obtaining the ACL2 sources, the next step is to produce an executable image. Proceed according to one of the four sections below, and after reading that section, continue by reading the topic, see [using-ACL2]. * Pre-built images * Building an executable image on a Unix-like system * Building an executable image on other than a Unix-like system * Observations on building an executable image on a Windows system Pre-built images {This website | https://www.cs.utexas.edu/users/moore/acl2/v8-6/distrib/images/Readme.html} contains links to ACL2 executables and packages. Each [47m-md5sum[0m file was created using [47mmd5sum[0m. We may add additional links from time to time. See also [pre-built-binary-distributions]. Building an executable image on a Unix-like system We assume you have obtained ACL2, described in [installation-instructions], but you have not obtained a pre-built image. Change to the directory containing the ACL2 sources and execute the command make LISP=<your_lisp> where [47m<your_lisp>[0m is the command to run your local Common Lisp. By default, if no [47mLISP=<your_lisp>[0m is specified, then [47mLISP=ccl[0m is used, which presumably invokes CCL (see [obtaining-common-lisp]). This will create executable [47msaved_acl2[0m in the current directory. The time taken to carry out this process depends on the host Lisp and the host processor but may well be under a minute. The size of the resulting binary image is dependent on which Lisp was used, but it may be on the order of a couple hundred megabytes or so. This [47mmake[0m command works for the supported host Common Lisp implementations; see [obtaining-common-lisp], on systems we have tested. If this [47mmake[0m command does not work for you, see the instructions below for ``Building an executable image on other than a Unix-like system''. See [save-exec] for how to build an ACL2 executable from a state resulting from the running of specified [command]s. Building an executable image on other than a Unix-like system It may be best to use this option only if you are using a Common Lisp on which you cannot save an image (e.g., a trial version of a commercial lisp). Next we describe how to create a binary image containing ACL2 without using the `[47mmake[0m' utility. If you cannot save an image, perhaps because you are using a trial version of your Common Lisp, then you may not be able to save an image. In that case, see [running-ACL2-without-executable]. Your Common Lisp should be one of those listed in [obtaining-common-lisp]. Stand in the directory where you have downloaded ACL2. 1. Remove file [47mnsaved_acl2[0m if it exists. 2. Start up Common Lisp and submit the following sequence of commands. (load "init.lisp") (in-package "ACL2") (compile-acl2) ; essentially a no-op if the Lisp is CCL or SBCL The commands above may, depending on the host Lisp, compile the ACL2 sources and create compiled object files in the current directory. (But they should be run even for Lisps that do not compile the ACL2 sources.) Below, we assume that saved images have extension [47m.core[0m; but this will depend on your host Lisp and operating system. 3. Now exit your Common Lisp. Make sure you are in the directory where you ran the commands displayed above. Start your Common Lisp and run the following commands to [3minitialize[0m ACL2. (load "init.lisp") (in-package "ACL2") (save-acl2 (quote (initialize-acl2)) "saved_acl2") This will load ACL2 source files (possibly compiled) into Lisp and then bootstrap ACL2 by reading and processing the source files, concluding by saving an image. Exit Lisp now. Subsequent steps will put the image in the right place. 4. Remove [47mosaved_acl2[0m if it exists. 5. [31;1mIF[0m [47msaved_acl2[0m and [47msaved_acl2.core[0m both exist [31;1mTHEN[0m: * move [47msaved_acl2.core[0m to [47mosaved_acl2.core[0m * move [47msaved_acl2[0m to [47mosaved_acl2[0m and edit [47mosaved_acl2[0m, changing [47msaved_acl2.core[0m (at end of line) to [47mosaved_acl2.core[0m [31;1mELSE IF[0m [47msaved_acl2[0m exists [31;1mTHEN[0m: * move [47msaved_acl2[0m to [47mosaved_acl2[0m 6. Move [47mnsaved_acl2[0m to [47msaved_acl2[0m . 7. Move [47mnsaved_acl2.core[0m to [47msaved_acl2.core[0m . 8. Make sure [47msaved_acl2[0m is executable. For Windows this involves two mini-steps: * Remove the [47m"$@"[0m from the [47msaved_acl2[0m script (because Windows may not understand [47m"$@"[0m). Consequently, any arguments you pass to ACL2 via the command line will be ignored. * Rename [47msaved_acl2[0m to [47msaved_acl2.bat[0m, for example by executing the following command. rename saved_acl2 saved_acl2.bat Observations on building an executable image on a Windows system You may be able to avoid this section by downloading a pre-built binary distribution; see [pre-built-binary-distributions], and also see ``Pre-built images'' above. Otherwise, see [windows-installation] for information on installing ACL2 on Windows systems.") (ctx (errors) "Context object for error messages Calls of [47m[er][0m, such as [47m(er soft ctx ...)[0m, take a context argument, typically called [47mctx[0m, for the initial part of the message: [47m"ACL2 Error in"[0m. If [47mctx[0m is [47mnil[0m, only [47m"ACL2 Error:"[0m is printed for that initial part of the message. Otherwise, the string printed after [47m"in"[0m depends on the form of that context, as follows. (See [ctxp] for the definition of a valid context.) * If [47mctx[0m is a symbol, print it with [47m[fmt][0m using [47m"~x"[0m. * If [47mctx[0m is a pair whose [47mcar[0m is a symbol, use [47m[fmt][0m to print [47m"(~x0 ~x1 ...)"[0m, with [47m#\0[0m and [47m#\1[0m bound respectively to the [47mcar[0m and [47mcdr[0m of [47mctx[0m. [31;1mException[0m: if the [47mcar[0m is a member of the value of constant [47m*fmt-ctx-spacers*[0m, then a space is printed after the left parenthesis. That explains why there is a space, for example, in [47m"( DEFUN"[0m in error messages starting with: ACL2 Error in ( DEFUN FOO ...): * Otherwise, print [47mctx[0m with [47mfmt[0m using [47m"~@"[0m.") (ctxp (errors) "Recognizer for context objects for error messages See [ctx] for relevant background. The function [47mctxp[0m returns [47mt[0m when [47mctx[0m is a valid context according to the definition below (also see [msgp]), else [47mnil[0m. [31;1mFunction: [0m<ctxp> (defun ctxp (x) (declare (xargs :guard t)) (or (symbolp x) (and (consp x) (symbolp (car x))) (msgp x)))") (current-package (ld) "The package used for reading and printing [47mCurrent-package[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(current-package state)[0m and the updater is [47m(set-current-package val state)[0m, or more conventionally, [47m(in-package val)[0m. The value of [47mcurrent-package[0m is actually the string that names the package. (Common Lisp's ``package'' objects do not exist in ACL2.) The current package must be known to ACL2, i.e., it must be one of the initial packages or a package defined with [47m[defpkg][0m by the user. When printing symbols, the package prefix is displayed if it is not the [47mcurrent-package[0m and may be optionally displayed otherwise. Thus, if [47mcurrent-package[0m is [47m"ACL2"[0m then the symbol [47m'ACL2::SYMB[0m may be printed as [47mSYMB[0m or [47mACL2::SYMB[0m, while [47m'MY-PKG::SYMB[0m must be printed as [47mMY-PKG::SYMB[0m. But if [47mcurrent-package[0m is [47m"MY-PKG"[0m then the former symbol must be printed as [47mACL2::SYMB[0m while the latter may be printed as [47mSYMB[0m. In Common Lisp, [47mcurrent-package[0m also affects how objects are read from character streams. Roughly speaking, read and print are inverses if the [47mcurrent-package[0m is fixed, so reading from a stream produced by printing an object must produce an equal object. In ACL2, the situation is more complicated because we never read objects from character streams, we only read them from object ``streams'' (channels). Logically speaking, the objects in such a channel are fixed regardless of the setting of [47mcurrent-package[0m. However, our host file systems do not support the idea of Lisp object files and instead only support character files. So when you open an object input channel to a given (character file) we must somehow convert it to a list of ACL2 objects. This is done by a [3mdeus ex machina[0m (``a person or thing that appears or is introduced suddenly and unexpectedly and provides a contrived solution to an apparently insoluble difficulty,'' Webster's Ninth New Collegiate Dictionary). Roughly speaking, the [3mdeus ex machina[0m determines what sequence of calls to [47mread-object[0m will occur in the future and what the [47mcurrent-package[0m will be during each of those calls, and then produces a channel containing the sequence of objects produced by an analogous sequence of Common Lisp reads with [47m*current-package*[0m bound appropriately for each. A simple rule suffices to make sane file [io] possible: before you read an object from an object channel to a file created by printing to a character channel, make sure the [47mcurrent-package[0m at read-time is the same as it was at print-time.") (current-theory (theories theory-functions) "Currently [enable]d rules as of logical name Examples: (current-theory :here) (current-theory 'lemma3) See [logical-name]. General Form: (current-theory logical-name) Returns the current theory as it existed immediately after the introduction of [47m[logical-name][0m provided it is evaluated in an environment in which the variable symbol WORLD is bound to the current ACL2 logical world, [47m(w state)[0m. Thus, ACL2 !>(current-theory :here) will cause an (unbound variable) error while ACL2 !>(let ((world (w state))) (current-theory :here)) will return the current theory in world. See [theories] and see [logical-name] for a discussion of theories in general and why the commonly used ``theory functions'' such as [47mcurrent-theory[0m are really macros that expand into terms involving the variable [47mworld[0m. The theory returned by [47mcurrent-theory[0m is in fact the theory selected by the [47m[in-theory][0m event most recently preceding logical name, extended by the rules introduced up through [47m[logical-name][0m. You may experience a fencepost problem in deciding which logical name to use. [47m[Deflabel][0m can always be used to mark unambiguously for future reference a particular point in the development of your theory. The order of [events] in the vicinity of an [47m[encapsulate][0m is confusing. See [encapsulate]. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (custom-keyword-hints (hints) "User-defined hints See [add-custom-keyword-hint] for a discussion of how advanced users can define their own hint keywords. For examples, see the community books directory [47mbooks/hints/[0m, in particular [47mbasic-tests.lisp[0m. Subtopics [Show-custom-keyword-hint-expansion] Print out custom keyword hints when they are expanded") (cw (io acl2-built-ins) "Print to the comment window [47mCw[0m is a macro that expands to a function whose guard is [47mt[0m. For a guarded variant of [47mcw[0m, see [fmx-cw]. For variants of [47mcw[0m that provide readable output (suffix [47m"!"[0m) and are never inhibited (suffix [47m"+"[0m), see [cw!], [cw+], and [cw!+]. For corresponding functions see [fmt-to-comment-window], [fmt-to-comment-window!], [fmt-to-comment-window+], and [fmt-to-comment-window!+]. Example: (cw "The goal is ~x0 and the alist is ~x1.~%" (untranslate term t nil) unify-subst) Logically, this expression is equivalent to [47mnil[0m. However, it has the effect of first printing to the so-called ``comment window'' the [47m[fmt][0m string as indicated. Thus, [47mcw[0m is like [47mfmt[0m (see [fmt]) except in four important ways. First, it is a macro whose calls expand to calls of a [47m:[0m[47m[logic][0m mode function. Second, it neither takes nor returns the ACL2 [47m[state][0m; logically [47mcw[0m simply returns [47mnil[0m, although it prints to a [3mcomment window[0m that just happens to share the terminal screen with the standard character output [47m[*standard-co*][0m. Third, its [47mfmt[0m args are positional references, so that for example (cw "Answers: ~x0 and ~x1" ans1 ans2) prints in the same manner as: (fmt "Answers: ~x0 and ~x1" (list (cons #\0 ans1) (cons #\1 ans2)) *standard-co* state nil) And finally, output from [47mcw[0m is suppressed if the [47mCOMMENT[0m type of output is suppressed; see [set-inhibit-output-lst]. Typically, calls of [47mcw[0m are embedded in [47m[prog2$][0m forms, e.g., (prog2$ (cw ...) (mv a b c)) which has the side-effect of printing to the comment window and logically returning [47m(mv a b c)[0m. General Form: (cw fmt-string arg1 arg2 ... argn) where n is between 0 and 9 (inclusive). The macro uses [47m[fmt-to-comment-window][0m, passing it the column [47m0[0m and [evisc-tuple] [47mnil[0m, after assembling the appropriate alist binding the [47m[fmt][0m vars #\0 through #\9; see [fmt]. If you want (a) more than 10 vars, (b) vars other than the digit chars, (c) a different column, or (d) a different evisc-tuple, then call [47m[fmt-to-comment-window][0m instead. Finally, we discuss another way to create formatted output that also avoids the need to pass in the ACL2 [47m[state][0m. The idea is to use wormholes; see [wormhole]. Below is a function you can write, along with some calls, providing an illustration of this approach. (defun my-fmt-to-comment-window (str alist) (wormhole 'my-fmt-to-comment-window '(lambda (whs) whs) (list str alist) '(pprogn (fms (car (@ wormhole-input)) (cadr (@ wormhole-input)) *standard-co* state nil) (value :q)) :ld-verbose nil :ld-error-action :return ; harmless return on error :ld-prompt nil)) ; A non-erroneous call: (my-fmt-to-comment-window "Here is ~x0 for your inspection~%" (list (cons #\0 'foo))) ; An error inside the fmt string (unbound fmt var); note that even ; with the error, the wormhole is exited. (my-fmt-to-comment-window "Here is ~x1 for your inspection~%" (list (cons #\0 'foo))) ; A guard violation in the binding; note that even with the error, ; the wormhole is exited. (my-fmt-to-comment-window "Here is ~x0 for your inspection~%" (list (cons #\0 (car 'foo)))) Subtopics [Cw!] Print readably to the comment window [Cw!+] Print readably and uninhibited to the comment window [Cw+] Print uninhibited to the comment window [Fmt-to-comment-window] Print to the comment window [Fmt-to-comment-window!] Print readably to the comment window [Fmt-to-comment-window!+] Print readably and uninhibited to the comment window [Fmt-to-comment-window+] Print uninhibited to the comment window") (cw! (cw io acl2-built-ins) "Print readably to the comment window See [cw] for important background. This is nearly the same as [47m[cw][0m, but [47mcw![0m avoids inserting backslash (\) characters when forced to print past the right margin. Use [47mcw![0m if you want to be able to read the forms back in.") (cw!+ (cw io acl2-built-ins) "Print readably and uninhibited to the comment window See [cw] for important background. This is nearly the same as [47m[cw][0m, but [47mcw+[0m always produces readable output (like [47m[cw!][0m), even when the [47mCOMMENT[0m output type is inhibited (like [47m[cw+][0m).") (cw+ (cw io acl2-built-ins) "Print uninhibited to the comment window See [cw] for important background. This is nearly the same as [47m[cw][0m, but [47mcw+[0m always produces output, even when the [47mCOMMENT[0m output type is inhibited (see [set-inhibit-output-lst]).") (cw-gstack (break-rewrite debugging) "Debug a rewriting loop or stack overflow After [break-rewrite] is enabled (with [47m:[0m[47m[brr][0m[47m t[0m or in the scope of [47m[with-brr-data][0m), [47mcw-gstack[0m can be invoked to show a stack backtrace when a proof is interrupted (because of control-c or because of a loop). Example Forms: (cw-gstack) (cw-gstack :frames 10) ; show only the top 10 frames (cw-gstack :frames '(1 10)) ; same as above: show only frames 1 through 10 (cw-gstack :frames '(10 20)) ; show only frames 10 through 20 (cw-gstack :evisc-tuple (evisc-tuple 3 4 nil nil)) ; print with print-level 3 and print-length 4 (cw-gstack :evisc-tuple nil) ; print using default ``evisceration'', ; essentially the same as just above (cw-gstack :evisc-tuple '(nil 3 4 (hide))) ; same as just above General Form: (cw-gstack :frames frames :evisc-tuple evisc-tuple) where [47m:frames[0m and [47m:evisc-tuple[0m are optional, but if they are supplied, their values are evaluated. The value of [47mframes[0m should be either a natural number or a list of two natural numbers, the first less than the second; and the value of [47mevisc-tuple[0m should be an evisc-tuple (see [evisc-tuple]). If [47m:evisc-tuple[0m is omitted, then by default, substructures deeper than 3 are replaced by ``[47m#[0m'' and those longer than 4 are replaced by ``[47m...[0m'', and terms of the form [47m(hide ...)[0m are printed as [47m<hidden>[0m; this behavior can be changed by setting the [47m:TERM[0m [evisc-tuple] (see [set-evisc-tuple]). Also see [set-iprint] for an alternative to printing ``[47m#[0m'' and ``[47m...[0m''. Stack overflows may occur, perhaps caused by looping rewrite rules. In some Lisps, stack overflows may manifest themselves as segmentation faults, causing the entire ACL2 image to crash. Finding looping rewrite rules can be tricky, especially if you are using books supplied by other people. (However, see [set-rewrite-stack-limit] for a way to avoid stack overflows caused by rewriter loops.) Normally, a stack overflow will cause the printing of an error message that suggests how to proceed. Just follow those instructions, and you will generally be able to see what is causing the loop. Suggestion: Once you have found the loop and fixed it, you should execute the ACL2 command [47m:[0m[47m[brr][0m[47m nil[0m, so that you don't slow down subsequent proof attempts.") (cw-gstack-for-subterm (pointers) "See [with-brr-data].") (cw-gstack-for-subterm* (pointers) "See [with-brr-data].") (cw-gstack-for-term (pointers) "See [with-brr-data].") (cw-gstack-for-term* (pointers) "See [with-brr-data].") (cw-print-base-radix (io acl2-built-ins) "Print to the comment window in a given print-base See [47m[cw][0m for relevant background. This variant of [47mcw[0m requires specification of a print-base and, optionally, a print-radix (see [set-print-base], [set-print-radix], and [set-print-base-radix]). The following examples show that [47mcw-print-base-radix[0m is just like [47m[cw][0m, except that there is a new argument in the first position that specifies the print-base and can, for that print-base, override the default print-radix. ACL2 !>(cw-print-base-radix 16 "~x0~%" '(3 12 16 17)) (#x3 #xC #x10 #x11) NIL ACL2 !>(cw-print-base-radix '(16 . t) "~x0~%" '(3 12 16 17)) (#x3 #xC #x10 #x11) NIL ACL2 !>(cw-print-base-radix '(16 . nil) "~x0~%" '(3 12 16 17)) (3 C 10 11) NIL ACL2 !>(cw-print-base-radix 10 "~x0~%" '(3 12 16 17)) (3 12 16 17) NIL ACL2 !>(cw-print-base-radix '(10 . t) "~x0~%" '(3 12 16 17)) (3. 12. 16. 17.) NIL ACL2 !>(cw-print-base-radix '(10 . nil) "~x0~%" '(3 12 16 17)) (3 12 16 17) NIL ACL2 !> General Forms: (cw-print-base-radix print-base fmt-string arg1 arg2 ... argn) (cw-print-base-radix print-base/print-radix fmt-string arg1 arg2 ... argn) where all arguments of this macro are evaluated; [47mprint-base[0m is a legal print-base as recognized by [47m[print-base-p][0m; [47mprint-base/print-radix[0m is a cons whose car is a legal print-base; [47mfmt-string[0m is a string suitable for passing to [47m[fmt][0m; and [47marg1[0m through [47margn[0m (where n is at most 9) are corresponding arguments for [47mfmt-string[0m. Printing is done according to the specified print-base, which is the first argument in the first general form and is the car of the first argument in the second general form. The print-radix value that is used for printing in the first general form is the print-radix as specified for [47m[set-print-base-radix][0m, while in the second general form, it is the cdr.") (cw-print-base-radix! (io acl2-built-ins) "Print to the comment window in a given print-base This is nearly the same as [47m[cw-print-base-radix][0m, but [47mcw-print-base-radix![0m avoids inserting backslash (\) characters when forced to print past the right margin. Use [47mcw-print-base-radix![0m if you want to be able to read the forms back in.") (d< (pointers) "See [l<].") (dead-events (debugging) "Using proof supporters to identify dead code and unused theorems Below, when we talk about ``an event [47mA[0m'', we mean an event whose name is [47mA[0m. When event [47mA[0m is used in a proof performed to admit event [47mB[0m that you submit to ACL2, we say that [47mA[0m is a ``proof-supporter'' of [47mB[0m. ACL2 stores an association list such that for every event [47mB[0m with at least one proof-supporter, [47mB[0m is associated with a list of all of its proof-supporters, sorted by [47m[symbol<][0m. The following form evaluates to that alist, which is called the ``proof-supporters-alist''. (global-val 'proof-supporters-alist (w state)) By ``used in a proof'' above, we mean: applied as a rule or supplied explicitly via [hints] of type [47m:use[0m, [47m:by[0m, or [47m:clause-processor[0m. That is, the [events] ``used in a proof'' for admitting an event [47mE[0m are those listed in the [summary] printed at the conclusion of admitting [47mE[0m. Note that if proofs are skipped when admitting event [47mE[0m, say because the last admission of [47mE[0m was done by [47m[include-book][0m (or [47mcertify-book[0m, which ends with an [47m[include-book][0m), then there will be no entry in that alist for [47mE[0m. (An exception is made however for [47m[encapsulate][0m [events], where proof-supporters are remembered from the first pass; see below.) So if you want the proof-supporters-alist to include supporters for events in a book, use [47m[ld][0m rather than [47m[include-book][0m or [47m[certify-book][0m to process the events in that book. If however you are interested in the proof-supporters FROM a book that support a later event, then it is fine to include that book. The case for [47m[encapsulate][0m is slightly tricky. Consider an example of the following form. A ; event preceding the encapsulate (encapsulate () B (local C) ; uses A and B in a proof D ; uses C in a proof ) At the conclusion of this [47m[encapsulate][0m event, the proof-supporters-alist associates [47mD[0m with [47mA[0m and [47mB[0m, but not [47mC[0m (which has disappeared, since it is [local]). Note that this sort of ``transitive closure'' operation is only performed when necessary due to the disappearance of [local] [events]. For example, if we replace [47m(local C)[0m above by just [47mC[0m, then [47mD[0m is associated in the proof-supporters-alist only with [47mC[0m, not with [47mA[0m or [47mB[0m. If you want the transitive closure of the relation computed by the proof-supporters-alist, you have to compute it yourself. (This was a deliberate design decision, in order to avoid slowing down event processing.) However, there is help available on how to do such a computation: A community book, [47mbooks/tools/dead-events.lisp[0m, does such a transitive closure, and moreover uses that information to find ``dead events'' relative to a list of ``desired'' events. For example, suppose you use [47m[ld][0m to process the events, with proofs, in a book intended to prove theorems [47mMAIN-1[0m and [47mMAIN-2[0m. (Remember, [47m[certify-book][0m will not save such information.) Suppose furthermore that the book begins with some [47m[include-book][0m forms followed by [47m(deflabel book-start)[0m. You could evaluate this form: (dead-events '(main-1 main-2) :start 'book-start) The result is a list of events that you probably can delete from the book without causing any proofs to fail. See the [47mdead-events.lisp[0m book for further documentation. You might also find the code in the above book to be helpful for writing your own utilities based on the proof-supporters-alist.") (dealing-with-key-combinations-of-function-symbols (introduction-to-the-theorem-prover) "How to get rid of key combinations of function symbols Suppose [47mREV[0m reverses a list, [47mMEMBER[0m checks that its first argument is an element of its second, and [47mSQUARES-PLUS-3P[0m is some complicated predicate. Suppose you're proving some Main Theorem that involves those concepts and the theorem prover presents you with the following hideous formula as a key checkpoint. What action should you take? Hint: Don't read the formula ``for sense,'' i.e., don't try to understand what this formula is saying! Just look at every subterm involving a nest of two function symbols and ask if you know something about those two symbols that allows you to [3msimplify[0m that one subterm. (IMPLIES (AND (CONSP X) (MEMBER (+ 3 (* I I)) (REV X)) (LIST-OF-INTEGERS X) (INTEGERP I) (<= 0 I) (INTEGERP K) (<= 0 K) (< I K) (SQUARES-PLUS-3P K X) (NOT (EQUAL (CAR X) (+ 3 (* I I)))) (NOT (MEMBER (+ 3 (* I I)) X))) (SQUARES-PLUS-3P K (REV X)))? The experienced ACL2 user will stop reading at the second hypothesis! (MEMBER (+ 3 (* I I)) (REV X)) The combination of [47mMEMBER[0m and [47mREV[0m can be simplified. The question ``is [47me[0m a member of [47m(REV x)[0m'' can be answered by asking ``is [47me[0m a member of [47mx[0m''. The two questions are equivalent. This insight comes from your intuition about the [3msemantics[0m of [47mREV[0m --- it just reorders the elements but doesn't add or delete any. The second question is simpler since it doesn't mention [47mREV[0m, so this is a good transformation to make. And the theorem that they are equivalent is simpler than the key checkpoint above because it involves fewer functions and smaller expressions. You might formalize this insight as (equal (member e (rev x)) (member e x)) But this conjecture is [3mnot[0m a theorem, because [47m(member e x)[0m returns the [47mcdr[0m of [47mx[0m that begins with [47me[0m, not just a Boolean ([47mt[0m or [47mnil[0m) indicating whether [47me[0m is an element of [47mx[0m. The location of the first [47me[0m in [47m(rev x)[0m is generally different than the location in [47mx[0m. So when we say the two questions are ``equivalent'' we don't mean they are equal. We mean that they're propositionally equivalent: both [47mnil[0m or both non-[47mnil[0m. This sense of equivalence is called ``if and only if'' and is checked by the function [47miff[0m. So our intuitive insight can be phrased as this theorem: (iff (member e (rev x)) (member e x)) Suggesting that this formulation of the insight is ``obvious'' begs many questions. Mathematically, we could have avoided [47miff[0m and just written two implications: (and (implies (member e x) (member e (rev x))) (implies (member e (rev x)) (member e x))). or (and (implies (member e x) (member e (rev x))) (implies (not (member e x)) (not (member e (rev x))))). Or we could have used [47miff[0m but ``oriented'' it the other way: (iff (member e x) (member e (rev x))) We choose to write (iff (member e (rev x)) (member e x)) because of [3mour knowledge of how ACL2 turns formulas into rules![0m We deal with this at greater length later. But just to drive the point home, if we issue the command: (defthm member-rev (iff (member e (rev x)) (member e x))) ACL2 will build in a rule that causes every propositional occurrence of [47m(MEMBER e (REV x))[0m to be replaced by [47m(MEMBER e x)[0m. (By ``propositional occurrence'' we mean an occurrence in which the value is tested, as by [47mIF[0m or the propositional connectives. Remember, one might use [47mmember[0m to determine the location of an element too.) Note carefully: [3mif you do not tell ACL2 how to make a rule[0m from a theorem, it makes a rewrite rule. Rewrite rules always replace instances of the left-hand side by the corresponding instances of the right-hand side. That is, when interpreted as a rewrite rule, [47m(iff [0m[3malpha[0m [3mbeta[0m[47m)[0m makes ACL2 replace [3malpha[0m by [3mbeta[0m. Probably the biggest mistake new users make is forgetting that every theorem they prove creates a very specific rule. You must remember that you are [3mprogramming[0m ACL2 with these rules. Being careless in your statement of theorems is tantamount to being careless in your programming. What you get is a mess. Had we proved the same equivalence, but with the [47miff[0m commuted, we would be giving ACL2 [3mbad advice[0m. We would be telling it ``replace instances of [47m(MEMBER e x)[0m by the corresponding instances of [47m(MEMBER e (REV x))[0m''! If ACL2 had that rule and ever tried to simplify any [47mmember[0m expression, e.g., [47m(MEMBER A B)[0m, it would get into an infinite loop, e.g., producing the following sequence of transformations: (MEMBER A B) (MEMBER A (REV B)) (MEMBER A (REV (REV B))) ... until it eventually exhausted some resource. Recall that we entertained the idea of phrasing our insight about [47mmember[0m and [47mrev[0m with implications rather than [47miff[0m. Generally speaking, implications produce weaker rules --- rules that apply less often. We discuss that later. Now suppose we've proved [47mmember-rev[0m, oriented so as to rewrite [47m(member e (rev x))[0m to [47m(member e x)[0m, and built it in as a rewrite rule. Then suppose we repeated the attempt to prove our Main Theorem. This time, when the prover is processing the hideous Key Checkpoint printed above, our new lemma, [47mmember-rev[0m, will hit it. It will transform the formula to: (IMPLIES (AND (CONSP X) (MEMBER (+ 3 (* I I)) X) ; <-- the hyp has simplified (LIST-OF-INTEGERS X) (INTEGERP I) (<= 0 I) (INTEGERP K) (<= 0 K) (< I K) (SQUARES-PLUS-3P K X) (NOT (EQUAL (CAR X) (+ 3 (* I I)))) (NOT (MEMBER (+ 3 (* I I)) X))) (SQUARES-PLUS-3P K (REV X)))? and then that will collapse to [47mT[0m, since the [47mIMPLIES[0m has contradictory hypotheses (note the last hypothesis above). By proving [47mmember-rev[0m we proved the hideous checkpoint. We never had to look at the rest of the formula or think about why it is a theorem. Furthermore, attacking the main theorem again, from scratch, with [47mmember-rev[0m in the database, may eliminate other checkpoints that came up the last time we tried to prove our main goal. So we recommend addressing one checkpoint at a time. This example illustrates that purely [3mlocal[0m thinking --- looking for simplifiable combinations of function symbols --- can sometimes lead to proofs and should always be your first reaction to a key checkpoint: what local fact do you know that would clean up the formula? Don't think about deep questions like ``why is this true?'' until you can't see any way to make it simpler. It is important to train yourself to see combinations of function symbols and to create strong rules for eliminating them. We will give you opportunities to practice this later in the tutorial. If you have been reading the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-key-checkpoints].") (dealing-with-tau-problems (introduction-to-the-tau-system) "Some advice on dealing with problems caused by the tau system For background on the tau system, see [introduction-to-the-tau-system]. The two most common problems caused by the tau system have to do with the system's interaction with ``legacy'' proof scripts. Such scripts may suffer because they were not designed to exploit tau reasoning and which may configure the tau database in quite incomplete and arbitrary ways. The two most common problems we have seen are (a) significant slow downs in a few proofs and (b) failed proof attempts due to hints being misapplied because the tau system caused subgoals to be renumbered. We discuss the rather limited means of dealing with these problems here. In [future-work-related-to-the-tau-system] we list some major inadequacies of the tau system. If the tau system contributes to a proof, the [rune] [47m(:[0m[47m[executable-counterpart][0m[47m tau-system)[0m will be listed among the Rules in the [Summary]. However, merely by being attempted the tau system can slow down proofs in which it makes no contribution. The most brutal and fool-proof way to isolate a proof from the tau system is to disable the entire system. This can be done globally by (in-theory (disable (tau-system))) ; (:executable-counterpart tau-system) or locally with a subgoal specific hint: ... :hints (("...subgoal id..." :in-theory (disable (tau-system)))) Conducting a proof with and without the participation of the tau system can help you determine whether tau reasoning is helping or hurting. [3mDealing with Slowdowns[0m The [47m[time-tracker][0m utility was added to allow users to investigate whether excessive amounts of time are being spent in a given function. It was then used to annotate the code for the tau system as described in [time-tracker-tau]. The result is that if ``excessive'' time is spent in tau reasoning, messages to that effect will be printed to the proof log. The question is: aside from disabling the tau system how can the proof be sped up? There are two common causes of slowdown in the tau system. The first stems from the system's use of [47m:[0m[47m[executable-counterpart][0ms to determine whether a constant has a given tau. Recall that a tau is a conjunction of monadic predicates. To determine whether some constant satisfies the tau, the predicates are executed. If you have a hard-to-compute predicate this can be very slow. The most typical such predicates in ACL2 applications are those that check invariants, e.g., that recognize ``good states'' or ``well-formed data.'' These are often written inefficiently because they are intended only for use in theorems and, before the tau system was added, they may have never been applied to constants. The most common constants tau predicates are applied to are [47m0[0m, [47mT[0m, and [47mNIL[0m, although different models may stress other constants. To understand why [47mNIL[0m for example is frequently tested, if the test of an [47mIF[0m-expression is computed to have tau [3ms[0m then the next question we ask is ``does [47mnil[0m satisfy [3ms[0m?'' You may determine whether the tau system is spending time executing tau predicates by observing the rewriter --- see [dmr] --- or by interrupting the system and getting a backtrace (see [set-debugger-enable]). If excessive time is being spent in a tau predicate, a draconian solution is to disable the [47m:[0m[47m[executable-counterpart][0m of that predicate, for example in either of these equivalent ways. The tau system does not execute disabled [47m:[0m[47m[executable-counterpart][0ms. (in-theory (disable (:executable-counterpart foo))) (in-theory (disable (foo))) In either case above, you may prefer to provide local [47m:[0m[47m[in-theory][0m [47m:[0m[47m[hints][0m rather than [47m:in-theory[0m [events]. Disabling the executable-counterpart of expensive tau predicates will weaken the tau system, probably only negligibly, because it can no longer run the predicates to determine whether they admits given constants. A more sophisticated solution is to make the tau system record values of the [47m:[0m[47m[logic][0m-mode function in question, so that the system will look up the necessary values rather than running the function every time the question arises. It will look up recorded values whether the executable-counterpart of the tau predicate is enabled or disabled. Here is an example of a lemma that can provide such a solution. See the discussion of the [3mEval[0m form of [47m:[0m[47m[tau-system][0m rules. (defthm lemma (and (foo 0) (foo 17) (foo t) (not (foo '(a b c)))) :rule-classes :tau-system) It might be difficult to determine [3mwhich[0m constants are being repeatedly tested, although tracing ([47m[trace$][0m) suspected tau predicates will show what they are being called on. At the moment there are no better user-level tools to discover this. However, some users may wish to consider the following hack: In the ACL2 source file [47mtau.lisp[0m, immediately after the definition of the system function [47mev-fncall-w-tau-recog[0m, there is a comment which contains some raw Lisp code that can be used to investigate whether tau's use of evaluation on constants is causing a problem and to determine which constants are involved. The second main cause of slowdowns by the tau system is that the system contains ``too many'' conjunctive rules (see the [3mConjunctive[0m form in [47m[tau-system][0m). Unfortunately, we have no tools for either identifying the problem or addressing it! That said, let us tell you what we do know! Conjunctive rules are used to ``complete'' each tau as it is built. Referring to the [47mweekdayp[0m example in [47m[tau-system][0m, if a tau is constructed that recognizes weekdays but not [47mMON[0m, [47mTUE[0m, [47mTHU[0m, or [47mFRI[0m, it is completed by adding that the tau recognizes (only) [47mWED[0m. This means that when we construct a tau we scan all known conjunctive rules and see whether all but one of the literals of any conjunctive rule are present. This can be expensive. To mitigate this expense, the tau system caches the computation on a per proof basis (the cache is cleared after every proof). To learn what conjunctive rules there are in your system, evaluate (assoc 'tau-conjunctive-rules (tau-database (w state))) Perhaps by sending the implementors that list, we can think of ways to index the conjunctive rules to save time. [3mDealing with Misapplied Hints[0m The second common problem caused by the tau system in legacy proof scripts is that it can cause subgoals to be renumbered and thus cause hints to be missed. The only ways to address this problem is either to disable the tau system (locally or globally by disabling [47m(:executable-counterpart tau-system)[0m) or change the legacy hints to use the new subgoal names.") (debugging (top) "Tools for debugging failed or slow proofs, or misbehaving functions. Subtopics [Accumulated-persistence] To get statistics on which [rune]s are being tried [Break-rewrite] A version of the ACL2 rewriter with interactive breaks [Compare-objects] show differences between two ACL2 objects [Cw-gstack] Debug a rewriting loop or stack overflow [Dead-events] Using proof supporters to identify dead code and unused theorems [Disassemble$] Disassemble a function [Dmr] Dynamically monitor rewrites and other prover activity [Efficiency] Efficiency considerations [Explain-near-miss] show why a rule's pattern and the :target do not match [Failed-forcing] How to deal with a proof [failure] in a forcing round [Failure] How to deal with a failure to admit an event [Forward-chaining-reports] To see reports about the forward chaining process [Guard-debug] Generate markers to indicate sources of [guard] proof obligations [Invariant-risk] Potential slowdown for [program]-mode updates to [stobj]s or [arrays] [Measure-debug] Generate markers to indicate sources of [measure] proof obligations [Near-misses] Approximate event name matches [Nil-goal] How to proceed when the prover generates a goal of [47mNIL[0m [Print-gv] Print a form whose evaluation caused a guard violation [Proof-builder] An interactive tool for controlling ACL2's proof processes. [Proof-tree] Proof tree displays [Pstack] Seeing what the prover is up to [Quick-and-dirty-subsumption-replacement-step] (advanced topic) controlling a heuristic in the prover's clausifier [Redo-flat] Redo on failure of a [47m[progn][0m, [47m[encapsulate][0m, or [47m[certify-book][0m [Set-check-invariant-risk] Affect certain [program]-mode updates to [stobj]s or [arrays] [Set-debugger-enable] Control whether Lisp errors and breaks invoke the Lisp debugger [Set-guard-msg] Specify what is printed when a [guard] is violated [Set-print-gv-defaults] Set default keyword values for [47m[print-gv][0m [Set-register-invariant-risk] Avoid [invariant-risk] checking for specified functions [Splitter] Reporting of rules whose application may have caused case splits [Tail-biting] Rewriting a true term to [47mNIL[0m [Time-tracker] Display time spent during specified evaluation [Trace] Tracing functions in ACL2 [Type-prescription-debugging] Improve a built-in [type-prescription] rule [Walkabout] Explore an ACL2 cons tree [With-brr-data] Finding the source of a term in prover output") (declaration (pointers) "See [declare].") (declare (programming acl2-built-ins) "Extra declarations that can occur in function definitions, [let] bindings, and so forth. Common Lisp provides a declaration mechanism that allows the programmer to explain additional information to the compiler. For instance: * The programmer might declare that some variable always has some particular type. The compiler might then, depending on its optimization/safety settings, either add run-time checks to ensure that this really is true, or optimize the compiled code by assuming the variable has the correct type. * The programmer might declare that some variable is [47mignore[0md. The compiler might then, instead of warning the programmer that the variable is never used, explicitly check to make sure that it really is never used. ACL2 supports the above kinds of declarations, and also adds its own kinds of declarations for specifying things like the [guard]s and [measure]s of functions, as described in [xargs]. There are also other kinds of Common Lisp declarations that ACL2 does not support, e.g., pertaining to inlining, safety settings, variable lifetime, and so forth. Usage Examples: (declare (ignore x y z)) (declare (ignorable x y z) (irrelevant w) ; for DEFUN only (type integer i j k) (type (satisfies integerp) m1 m2)) (declare (xargs :guard (and (integerp i) (<= 0 i)) :guard-hints (("Goal" :use (:instance lemma3 (x (+ i j))))))) General Form: (declare d1 ... dn) where, in ACL2, each [47mdi[0m is of one of the following forms: [47m(ignore v1 ... vn)[0m where each [47mvi[0m is a variable introduced in the immediately superior lexical environment. These variables must not occur free in the scope of the declaration. This declaration can be useful for inhibiting compiler warnings; see also [set-ignore-ok]. [47m(ignorable v1 ... vn)[0m where each [47mvi[0m is a variable introduced in the immediately superior lexical environment. These variables need not occur free in the scope of the declaration. This declaration can be useful for inhibiting compiler warnings; see also [set-ignore-ok]. [47m(irrelevant v1 ... vn)[0m where each [47mvi[0m is a formal parameter declared at the top level of a surrounding [47m[defun][0m form, as shown below. See [irrelevant-formals] for more information. [47m(type type-spec v1 ... vn)[0m where each [47mvi[0m is a variable introduced in the immediately superior lexical environment and [47mtype-spec[0m is a type specifier (as described in the documentation for [type-spec]). This declaration can be useful for optimizing Common Lisp execution speed. See also [the]. [47m(xargs :key1 val1 ... :keyn valn)[0m where the legal values of the keys and values are described in the documentation for [xargs]. These declarations are only allowed at the top level of definitions ([47m[defun][0m and [47m[defmacro][0m, as shown below), and convey information such as the [guard] and [measure] for a function. [47m(optimize ...)[0m for example, [47m(optimize (safety 3))[0m. This is allowed only at the top level of [47m[defun][0m forms and is probably only rarely of any interest. See any Common Lisp documentation for more information. Declarations in ACL2 may occur only where [47mdcl[0m occurs in the following display (not including lambda objects, discussed later below, and not showing documentation strings here, which are essentially ignored by ACL2)): * [47m(DEFUN name args dcl ... dcl body)[0m * [47m(DEFMACRO name args dcl ... dcl body)[0m * [47m(LET ((v1 t1) ...) dcl ... dcl body)[0m * [47m(MV-LET (v1 ...) term dcl ... dcl body)[0m * [47m(FLET ((name args dcl ... dcl body) ...))[0m * [47m(MACROLET ((name args dcl ... dcl body) ...))[0m Each of the cases above permits certain declarations, as follows. * [47mDEFUN[0m: [47m(ignore ignorable irrelevant type optimize xargs)[0m * [47mDEFMACRO[0m: [47m(ignore ignorable type xargs)[0m * [47mLET[0m: [47m(ignore ignorable type)[0m * [47mMV-LET[0m: [47m(ignore ignorable type)[0m * [47mFLET[0m: [47m(ignore ignorable type)[0m * [47mMACROLET[0m: [47m(ignore ignorable type)[0m Of course, declarations are permitted in macro calls to the extent that they are permitted in the macroexpansions. For example, [47mdeclare[0m forms generated by calls of [47m[let*][0m and [47m[case-match][0m may wind up in corresponding [47m[let][0m forms in the macroexpansions, where they would be subject to the restrictions on [47mdeclare[0m forms for [47mlet[0m shown just above. Also see [lambda] for discussion of lambda objects and their legal [47mdeclare[0m forms. [47mDeclare[0m is defined in Common Lisp. See any Common Lisp documentation for more information. Subtopics [Declare-stobjs] Declaring a formal parameter name to be a single-threaded object [Set-ignore-ok] Allow unused formals and locals without an [47mignore[0m or [47mignorable[0m declaration [Set-irrelevant-formals-ok] Allow irrelevant formals in definitions [Type-spec] Type specifiers can be used in Common Lisp type declarations and [the] forms, and may result in improved efficiency of execution. [Xargs] Extra arguments, for example to give [hints] to [47m[defun][0m") (declare-stobjs (stobj declare) "Declaring a formal parameter name to be a single-threaded object When a [47m[defun][0m uses one of its formals as a single-threaded object ([stobj]), the [47mdefun[0m [3mmust[0m include a declaration that the formal is to be so used. An exception is the formal ``[47m[state][0m,'' which if not declared as explained below, may still be used provided an appropriate global ``declaration'' is issued: see [set-state-ok]. If the formal in question is [47mcounters[0m then an appropriate declaration is (declare (xargs :stobjs counters)) or, more generally, (declare (xargs :stobjs (... counters ...))) where all the single-threaded formals are listed. For such a declaration to be legal it must be the case that all the names have previously been defined as single-threaded objects with [47m[defstobj][0m. When an argument is declared to be single-threaded the guard of the function is augmented by conjoining to it the condition that the argument satisfy the recognizer for the single-threaded object. Furthermore, the syntactic checks done to enforce the legal use of single-threaded objects are also sufficient to allow these guard conjuncts to be automatically proved. The obvious question arises: Why does ACL2 insist that you declare stobj names before using them in [47mdefun[0ms if you can only declare names that have already been defined with [47mdefstobj[0m? What would go wrong if a formal were treated as a single-threaded object if and only if it had already been so defined? Suppose that one user, say Jones, creates a book in which [47mcounters[0m is defined as a single-threaded object. Suppose another user, Smith, creates a book in which [47mcounters[0m is used as an ordinary formal parameter. Finally, suppose a third user, Brown, wishes to use both books. If Brown includes Jones' book first and then Smith's, then Smith's function treats [47mcounters[0m as single-threaded. But if Brown includes Smith's book first, the argument is treated as ordinary. ACL2 insists on the declaration to ensure that the definition is processed the same way no matter what the context.") (defabbrev (macros events programming) "A convenient form of macro definition for simple expansions Examples: (defabbrev snoc (x y) (append y (list x))) (defabbrev sq (x) (declare (type (signed-byte 8) x)) (* x x)) General Form: (defabbrev name (v1 ... vn) doc-string decl1 ... declk body) where [47mname[0m is a new function symbol, the [47mvi[0m are distinct variable symbols, and [47mbody[0m is a term. The [47mdecli[0m, if supplied, should be legal [47mdeclare[0m forms; see [declare]. [47mDoc-string[0m, if non-[47mnil[0m, is an optional string that can provide documentation but is essentially ignored by ACL2. Roughly speaking, the [47mdefabbrev[0m event is akin to defining [47mf[0m so that [47m(f v1 ... vn) = body[0m. But rather than do this by adding a new axiom, [47mdefabbrev[0m defines [47mf[0m to be a macro so that [47m(f a1 ... an)[0m expands to [47mbody[0m, with the ``formals,'' [47mvi[0m, replaced by the ``actuals,'' [47mai[0m. For example, if [47msnoc[0m is defined as shown in the first example above, then [47m(snoc (+ i j) temp)[0m is just an abbreviation for (append temp (list (+ i j))). In order to generate efficiently executable Lisp code, the macro that [47mdefabbrev[0m introduces uses a [47m[let][0m to bind the ``formals'' to the ``actuals.'' Consider the second example above. Logically speaking, [47m(sq (ack i j))[0m is an abbreviation for [47m(* (ack i j) (ack i j))[0m. But in fact the macro for [47msq[0m introduced by [47mdefabbrev[0m actually arranges for [47m(sq (ack i j))[0m to expand to: (let ((x (ack i j))) (* x x)) which executes more efficiently than [47m(* (ack i j) (ack i j))[0m. In the theorem prover, the [47mlet[0m above expands to ((lambda (x) (* x x)) (ack i j)) and thence to [47m(* (ack i j) (ack i j))[0m. It is important to note that the term in [47mbody[0m should not contain a call of [47mname[0m --- i.e., [47mdefabbrev[0m should not be used in place of [47mdefun[0m when the function is recursive. ACL2 will not complain when the [47mdefabbrev[0m form is processed, but instead ACL2 will more than likely go into an infinite loop during macroexpansion of any form that has a call of [47mname[0m. It is also important to note that the parameters of any call of a macro defined by defabbrev will, as is the case for the parameters of a function call, be evaluated before the body is evaluated, since this is the evaluation order of [47m[let][0m. This may lead to some errors or unexpected inefficiencies during evaluation if the body contains any conditionally evaluated forms like [47mcond[0m, [47mcase[0m, or [47mif[0m. Consider the following example. (defabbrev foo (x y) (if (test x) (bar y) nil)) Notice a typical one-step expansion of a call of [47mfoo[0m (see [trans1]): ACL2 !>:trans1 (foo expr1 expr2) (LET ((X EXPR1) (Y EXPR2)) (IF (TEST X) (BAR Y) NIL)) ACL2 !> Now imagine that [47mexpr2[0m is a complicated expression whose evaluation is intended only when the predicate [47mtest[0m holds of [47mexpr1[0m. The expansion above suggests that [47mexpr2[0m will always be evaluated by the call [47m(foo expr1 expr2)[0m, which may be inefficient (since perhaps we only need that value when [47mtest[0m is true of [47mexpr1[0m). The evaluation of [47mexpr2[0m may even cause an error, for example in [47m:[0m[47m[program][0m mode if the expression [47mexpr2[0m has been constructed in a manner that could cause a guard violation unless [47mtest[0m holds of [47mexpr1[0m.") (defabsstobj (events stobj) "Define a new abstract single-threaded object We assume familiarity with single-threaded objects; see [stobj] and see [defstobj]. The event [47mdefabsstobj[0m defines a so-called ``abstract stobj'', a notion we introduce briefly now and then explain in more depth below. Recall that a [defstobj] event produces logical definitions for several functions: a recognizer, which characterizes the [stobj] in terms of lists; a creator, which produces an initial suitable list structure; and field accessors and updaters, defined in terms of [47m[nth][0m and [47m[update-nth][0m. [47mDefabsstobj[0m provides a way to define alternate definitions for ``stobj primitives'' for a corresponding single-threaded object. These stobj primitives include a recognizer, a creator, and other ``exported'' functions. In essence, [47mdefabsstobj[0m establishes interface functions, or ``exports'', on a new stobj that is a copy of an existing stobj, its ``foundation'', which is either [3mconcrete[0m (introduced by [47m[defstobj][0m) or [3mabstract[0m (introduced by [47mdefabsstobj[0m). We begin below with an introduction to abstract [stobj]s. We then explain the [47m[defabsstobj][0m event by way of an example. We conclude by giving summary documentation for the [47mdefabsstobj[0m event. For another introduction to abstract stobjs, see the paper ``Abstract Stobjs and Their Application to ISA Modeling'' by Shilpi Goel, Warren A. Hunt, Jr., and Matt Kaufmann, in the proceedings of {ACL2 Workshop 2013 | http://www.cs.uwyo.edu/~ruben/acl2-13}. [31;1mINTRODUCTION[0m We start with a brief review of [stobj]s and some potential problems with them, followed by an introduction to abstract stobjs and how they can avoid these problems. Prior experience with stobjs will probably help the reader to absorb the ideas below. Recall that single-threaded objects, or [stobj]s, provide a way for ACL2 users to stay within the ACL2 logic --- where every data object is an atom or a [47m[cons][0m of data objects --- while obtaining the benefits of fast evaluation through destructive updates. Consider for example this very simple event. (defstobj st fld) This event introduces a recognizer, [47mstp[0m, and a creator, [47mcreate-st[0m, for a data structure consisting of a single field accessed and updated by functions [47mfld[0m and [47mupdate-fld[0m, respectively. Each of these four primitive functions has both a logical definition, which is used when the prover reasons about the function, and an executable definition, which is used in raw Lisp. In the logic, [47mstp[0m recognizes objects that have the requisite fields. In raw Lisp, there is a ``live stobj'', which is typically an array object whose fields correspond to those specified by the [47m[defstobj][0m event. (If there is a single stobj field that is an array or hash-table field, then that field is the entire stobj in raw Lisp; but we ignore that case below.) Here are the logical definition and the executable definition, respectively, that are introduced for the field accessor, [47mfld[0m, introduced above. Notice that since a stobj is represented in raw Lisp using an array, the raw Lisp accessor uses a raw Lisp array accessor, [47msvref[0m. (You can see all the logical and executable definitions by evaluating the form [47m(trace$ defstobj-axiomatic-defs defstobj-raw-defs)[0m before evaluating the [47m[defstobj][0m form.) ; logical definition (defun fld (st) (declare (xargs :guard (stp st) :verify-guards t)) (nth 0 st)) ; executable (raw Lisp) definition (defun fld (st) (svref st 0)) Sophisticated programming with stobjs can provide efficient implementations of algorithms, but may require the preservation of a complex invariant. One can, of course, define a function to implement such an invariant after introducing the stobj, as follows. ; Introduce a stobj. (defstobj st fld1 ... fldk) ; Define an invariant on that stobj. (defun good-stp (st) (declare (xargs :stobjs st)) ...) ; Define some basic functions that update the stobj and preserve the ; invariant. (defun update-st (... st ...) (declare (xargs :stobjs st :guard (and (good-stp st) ...))) ...) ... ; Prove that the invariant is indeed preserved by those basic functions. (defthm good-stp-update-st (implies (and (good-stp st) ...) (good-stp (update-st ... st ...)))) ... ; Implement algorithms built on the basic functions. (defun foo (... st ...) (declare (xargs :stobjs st :guard (and (good-stp st) ...))) ... (update-st ... st ...) ...) ; Prove invariance theorems about these algorithms. (defthm good-stp-foo (implies (and (good-stp st) ...) (good-stp (foo ... st ...)))) ... ; Prove other properties of these algorithms. (defthm foo-is-correct (implies (and (good-stp st) ...) (some-property (foo ... st ...)))) ... But there are at least two potential difficulties in using stobjs as described above. 1. When [47mfoo[0m is executed on concrete data in the ACL2 loop, the guard check may be expensive because [47m(good-stp st)[0m is expensive. 2. Reasoning about [47mfoo[0m (using rules like [47mfoo-is-correct[0m above) involves proving hypotheses of invariance theorems, which may be complicated for the user to manage or slow for the theorem prover. The [47mdefabsstobj[0m event offers an opportunity to address these issues. It introduces a new stobj, which we call an ``abstract stobj'', which is associated with a corresponding ``foundational stobj'' introduced by an earlier [47m[defstobj][0m or [47mdefabsstobj[0m event. The [47mdefabsstobj[0m event specifies a logical ([47m:LOGIC[0m) and an executable ([47m:EXEC[0m) definition for each primitive operation, or ``stobj primitive'', involving that stobj. As is the case for [47m[defstobj][0m, the logical definition is what ACL2 reasons about, and is appropriate to apply to an ACL2 object satisfying the logical definition of the recognizer function for the stobj. The executable definition is applied in raw Lisp to a live stobj (as discussed above). Remark. It is common to use ``a'' and ``c'' in a suffix to suggest ``abstract'' and ``concrete'', respectively. The foundational stobj was, at one time, called the ``corresponding concrete stobj''. That old terminology may still be appropriate in the common case that the foundational stobj is a concrete stobj (rather than another abstract stobj). So below, a name like [47mst$c0[0m suggests a foundational (``concrete'') stobj for an abstract stobj named [47mst[0m, whose abstract stobj recognizer is [47mst$ap[0m, and so on. End of Remark. We can picture a sequence of updates to an abstract stobj and its foundational stobj. Initially in this picture, [47mst$a0[0m and [47mst$c0[0m are an abstract stobj and its foundation (respectively). Then an update, [47mu1[0m, is applied with [47m:LOGIC[0m and [47m:EXEC[0m functions [47mu$a1[0m and [47mu$c1[0m, respectively. The resulting abstract and foundational stobj, [47mst$a1[0m and [47mst$c1[0m, correspond as before. Then a second update, [47mu2[0m, is applied with [47m:LOGIC[0m and [47m:EXEC[0m functions [47mu$a2[0m and [47mu$c2[0m, respectively --- again preserving the correspondence. And so on. Abstract u$a1 u$a2 u$a3 (:logic) st$a0 --> st$a1 --> st$a2 --> ... ^ ^ ^ ^ Correspondence | | | ... | v v v v u$c1 u$c2 u$c3 Foundation st$c0 --> st$c1 --> st$c2 --> ... (:exec) We conclude this introduction with some remarks about implementation. Consider an abstract stobj [47mst[0m with corresponding foundation [47mst$c[0m. The live stobjs for [47mst[0m and [47mst$c[0m have the same structure, but are distinct arrays. Indeed, the raw Lisp creator function for [47mst$c[0m is called to create a new initial live stobj for [47mst[0m. As we will see below, reads and writes in raw Lisp to the live stobj for [47mst[0m are ultimately performed using the primitive accessors and updaters defined for [47mst$c[0m. One might think of the live stobjs for [47mst[0m and [47mst$c[0m as being congruent stobjs (see [defstobj]), except that the stobjs themselves are not truly congruent: in particular, the stobj primitives introduced for [47mst[0m may be applied to [47mst[0m, but field updaters of [47mst$c[0m may not. As one might expect, the [47m:EXEC[0m function for an exported function is applied to the live stobj for [47mst[0m in raw Lisp. [31;1mEXAMPLE[0m We present examples, with detailed comments intended to explain abstract stobjs, in two community books: [47mbooks/demos/defabsstobj-example-1.lisp[0m and [47mbooks/demos/defabsstobj-example-2.lisp[0m. In this section we outline the first of these. We suggest that after you finish this [documentation] topic, you read through those two books. There are other books [47mbooks/dmeos/defabsstobj-example-*.lisp[0m that may be helpful to read; in particular, [47mbooks/demos/defabsstobj-example-5.lisp[0m illustrates building an abstract stobj on top of another abstract stobj (as its so-called ``foundation'', as described below). Here is the first of two closely related [47mdefabsstobj[0m [events] from the book [47mdefabsstobj-example-1.lisp[0m, but in expanded form. We will show the abbreviated form later, which omits most of the data in the form that is immediately below. Thus most of the information shown here is default information. We believe that the comments below explain most or all of what you need to know in order to start using [47mdefabsstobj[0m, and that you will learn the remainder when you see error messages. For example, we do not say in the comments below that every [47m:LOGIC[0m and [47m:EXEC[0m function must be [guard]-verified, but that is indeed a requirement. (defabsstobj st ; The new abstract stobj is named st. ; The foundational stobj for st is st$c: :foundation st$c ; The recognizer for the new abstract stobj is stp, which is defined to be ; st$ap in the logic, and is executed on the live stobj in raw Lisp using ; st$cp. :recognizer (stp :logic st$ap :exec st$cp) ; The initial stobj is defined as create-st (a function of no arguments), ; which is defined logically as create-st$a, though create-st$c is invoked to ; create the initial live stobj for st. The :correspondence and :preserved ; keywords refer to proof obligations, discussed below. :creator (create-st :logic create-st$a :exec create-st$c :correspondence create-st{correspondence} :preserved create-st{preserved}) ; Proof obligations are generated that involve a correspondence between the ; new abstract stobj and corresponding foundational stobj. The function ; st$corr, which need not be executable (see :DOC defun-nx), takes two ; arguments, a foundational stobj and an abstract stobj. This function symbol ; is used in the statements of the proof obligations. :corr-fn st$corr ; In this example we have four exports. In each case a new function is ; introduced that has the same signature as its :EXEC function, except that ; st$c is replaced by st. The :LOGIC and :EXEC functions are as specified, ; and the other keywords refer to proof obligations that we discuss below. :exports ((lookup :logic lookup$a :exec mem$ci :correspondence lookup{correspondence} :guard-thm lookup{guard-thm}) (update :logic update$a :exec update-mem$ci :correspondence update{correspondence} :preserved update{preserved} :guard-thm update{guard-thm}) (misc :logic misc$a :exec misc$c :correspondence misc{correspondence}) (update-misc :logic update-misc$a :exec update-misc$c :correspondence update-misc{correspondence} :preserved update-misc{preserved}))) Note that all stobj primitives (recognizer, creator, and exported functions) are defined in the ACL2 loop in terms of their [47m:LOGIC[0m functions and in raw Lisp in terms of their [47m:EXEC[0m functions. In the ACL2 loop, a [47m[defun][0m form defines a function, while in raw Lisp, a [47m[defmacro][0m form defines a macro (for efficiency). We first illustrate how that works for the recognizer. (You can see all the logical and executable definitions by evaluating the form [47m(trace$ defabsstobj-axiomatic-defs defabsstobj-raw-defs)[0m before evaluating the [47m[defstobj][0m form.) ; In the ACL2 loop: (defun stp (st) (declare (xargs :guard 't)) (st$ap st)) ; In raw Lisp: (defmacro stp (&rest args) (cons 'st$cp args)) The definitions are made similarly for exported functions. [Guard]s are derived from their [47m:LOGIC[0m functions as follows. Consider the exported function [47mupdate[0m in our example. Its [47m:LOGIC[0m function, [47mupdate$a[0m, has formals [47m(k val st$a)[0m and the following guard. (and (and (integerp k) (<= 0 k) (<= k 49)) (and (integerp val) (<= 0 val)) (st$ap st$a) (mem$c-entryp val)) The formals of [47mupdate[0m are obtained by starting with the formals of its [47m:EXEC[0m function, [47mupdate-mem$ci[0m --- which are [47m(i v st$c)[0m --- and replacing the foundational stobj name [47mst$c[0m by the new stobj name [47mst[0m. The formals of [47mupdate[0m are thus [47m(i v st)[0m. The guard for [47mupdate[0m is obtained in two steps. The first step is to substitute the formals of [47mupdate[0m for the formals of [47mupdate$a[0m in the guard for [47mupdate$a[0m, to obtain the following. (and (and (integerp i) (<= 0 i) (<= i 49)) (and (integerp v) (<= 0 v)) (st$ap st) (mem$c-entryp v)) The second step is to replace, for each new stobj primitive [47mp[0m, the [47m:LOGIC[0m function for [47mp[0m by [47mp[0m itself. The only [47m:LOGIC[0m function occurring in the formula just above is [47mst$ap[0m, which is the [47m:LOGIC[0m function for [47mstp[0m. The guard for [47mupdate[0m is thus as follows. (and (and (integerp i) (<= 0 i) (<= i 49)) (and (integerp v) (<= 0 v)) (stp st) (mem$c-entryp v)) Note that the [47m:EXEC[0m version of an abstract [stobj] export must not include the abstract stobj name among its formals. We turn now to the proof obligations, as promised above. There are three types: [47m:CORRESPONDENCE[0m, [47m:PRESERVED[0m, and [47m:GUARD-THM[0m. All required lemmas may be printed simply by defining the necessary [47m:LOGIC[0m and [47m:EXEC[0m functions and then submitting the [47mdefabsstobj[0m event. (To advanced users: also see [defabsstobj-missing-events] for a utility that returns the required formulas in translated form.) Although the [47mdefabsstobj[0m event will fail if the required lemmas have not been proved, first it will print the [47m[defthm][0m forms that must be admitted in order to complete submission of the [47mdefabsstobj[0m event. (Note that although those theorems are stated exactly in the form expected by the system, you are welcome to supply whatever [47m:[0m[47m[rule-classes][0m you prefer, even though the system creates [47m:rule-classes nil[0m by default.) The detailed theory explaining the need for these lemmas may be found in ACL2 source file [47mother-events.lisp[0m, in a comment entitled ``Essay on the Correctness of Abstract Stobjs''. Here, we give an informal sense of the importance of these lemmas as we present examples of them. Fundamental is the notion of evaluation in the logic versus evaluation using live stobjs, where one imagines tracking the current value of each abstract stobj during each of these two evaluations. We start with the [47m:CORRESPONDENCE[0m lemmas. These guarantee that evaluation in the logic agrees with evaluation using live stobjs, in the sense that the only difference is between a logical stobj and a live stobj, where the two correspond in the sense of the function specified by [47m:CORR-FN[0m. We start with the [47m:CREATOR[0m function where the statement is quite simple, stating that the [47m:CORR-FN[0m holds initially. (defthm create-st{correspondence} (st$corr (create-st$c) (create-st$a))) For the exported functions, there are essentially two cases. If an exported function returns other than the new abstract stobj, then the theorem asserts the equality of the results of applying the [47m:LOGIC[0m and [47m:EXEC[0m functions for the exported function. Hypotheses include the [47m:CORR-FN[0m correspondence followed by the [guard] for the [47m:LOGIC[0m function, which is stated in terms of the formal parameters of the [47m:EXEC[0m function except using the abstract stobj (here, [47mst[0m) in place of the foundational stobj (here, [47mst$c[0m). The conclusion uses the [47m:EXEC[0m formals, modified in the call of the [47m:LOGIC[0m function (here, [47mlookup$a[0m) to use the abstract stobj, as in the hypotheses. (defthm lookup{correspondence} (implies (and (st$corr st$c st) (integerp i) (<= 0 i) (<= i 49) (st$ap st)) (equal (mem$ci i st$c) (lookup$a i st))) :rule-classes nil) By contrast, if the exported function returns the new abstract stobj, then the conclusion uses the correspondence function instead of [47mEQUAL[0m, as in the following. (defthm update{correspondence} (implies (and (st$corr st$c st) (integerp i) (<= 0 i) (<= i 49) (integerp v) (<= 0 v) (st$ap st) (mem$c-entryp v)) (st$corr (update-mem$ci i v st$c) (update$a i v st))) :rule-classes nil) For exported functions that return multiple values, such conclusions are conjoined together over the returned values. The [47m:PRESERVED[0m lemmas guarantee that updates to the abstract stobj preserve its recognizer. The fact that every exported function has this property provides justification for an optimization performed by ACL2 during generation of proof obligations for [guard] verification, by assuming that the recognizer always holds. The [47m:PRESERVED[0m lemma for the [47m:CREATOR[0m shows that the recognizer holds initially. (defthm create-st{preserved} (st$ap (create-st$a))) Here is a typical such lemma, for the exported function [47mupdate[0m. Note that there is no such lemma for [47mlookup[0m, since [47mlookup[0m does not return [47mst[0m. (defthm update{preserved} (implies (and (integerp i) (<= 0 i) (<= i 49) (integerp v) (<= 0 v) (st$ap st) (mem$c-entryp v)) (st$ap (update$a i v st)))) Finally, we consider the [47m:GUARD-THM[0m lemmas. These serve to guarantee that the [guard] holds for each call of an [47m:EXEC[0m function. During guard verification, logical definitions are used; in particular, since each exported function is defined in the logic as the corresponding call of its [47m:LOGIC[0m function, guard verification shows that each call of the [47m:LOGIC[0m function for an exported function satisfies that function's guard. But why is this true for raw Lisp evaluation using live stobjs, where the [47m:EXEC[0m function is called for an exported function? The [47m:GUARD-THM[0m lemmas provide the answer, as they state that if the [47m:LOGIC[0m function's guard holds, then the [47m:EXEC[0m function's guard holds. Here is an example. Note that the hypotheses come from the correspondence of the foundational and abstract function as guaranteed by the [47m:CORR[0m function, together with the guard of the [47m:LOGIC[0m function; and the conclusion comes from the guard of the [47m:EXEC[0m function. (defthm lookup{guard-thm} (implies (and (st$corr st$c c) (integerp i) (<= 0 i) (<= i 49) (st$ap st)) (and (integerp i) (<= 0 i) (< i (mem$c-length st$c)))) :rule-classes nil) We conclude this EXAMPLE section by showing a short form for the [47mdefabsstobj[0m form displayed above. (defabsstobj st :exports ((lookup :exec mem$ci) (update :exec update-mem$ci) misc update-misc)) [31;1mSUMMARY DOCUMENTATION[0m The General Form is as shown below, where the order of keywords is unimportant. Duplicate keywords are discouraged; while permitted, only the first (leftmost) occurrence of a given keyword is used. Only the [47m:exports[0m keyword is required. (defabsstobj st :foundation foundation :recognizer recognizer :creator creator :corr-fn corr-fn :corr-fn-exists corr-fn-exists :congruent-to congruent-to :non-executable non-executable :protect-default protect-default :attachable att :exports (e1 ... ek)) The keyword argument [47m:EXPORTS[0m must be supplied, and missing or [47mnil[0m keyword arguments have defaults as indicated below. All arguments must satisfy the conditions below. Before we describe the arguments, we define a notion of a ``function spec'' and its ``completion''. A function spec is either a symbol or else a list of the form (fn [47m:kwd1[0m val1 ... [47m:kwdn[0m valn), that is, a symbol followed by a [47m[keyword-value-listp][0m. Each [47mvali[0m must be a symbol. We view the case of a symbol, [47ms[0m, as the function spec [47m(s)[0m, with no keywords. There must be no duplicate keywords. In each case that we expect a function spec, the context provides a set of valid keywords for that function spec; it is an error to provide any other keyword in the function spec. Each function spec is interpreted as its ``completion'', obtained by extending the function spec with a default value for each valid keyword as indicated below. With that interpretation, the ``exported function'' of a function spec is its [47mcar[0m, and that function symbol and each keyword value must be a guard-verified function symbol; and moreover, the [47m:EXEC[0m function must not include the new abstract stobj name, [47mst[0m, among its formals. We are ready to describe the arguments of [47mdefabsstobj[0m. [47mSt[0m is a symbol, which names the new abstract stobj. [47mFoundation[0m is the name of an existing stobj, which may have been introduced either with [47m[defstobj][0m or with [47mdefabsstobj[0m. [47mRecognizer[0m is a function spec (for the recognizer function). The valid keywords are [47m:LOGIC[0m and [47m:EXEC[0m. The default for [47mrecognizer[0m is obtained by adding the suffix [47m"P"[0m to [47mname[0m. The default value for [47m:LOGIC[0m is formed by adding the suffix [47m"$AP"[0m to [47mrecognizer[0m; for [47m:EXEC[0m, by adding the suffix [47m"$CP"[0m. The [47m:EXEC[0m function must be the recognizer for the foundational stobj (which can be specified using the [47m:FOUNDATION[0m keyword). [47mCreator[0m is a function spec (for the creator function). The valid keywords are [47m:LOGIC[0m and [47m:EXEC[0m. The default for [47mcreator[0m is obtained by adding the prefix [47m"CREATE-"[0m to [47mname[0m. The default value for [47m:LOGIC[0m is formed by adding the suffix [47m"$A"[0m to [47mcreator[0m; for [47m:EXEC[0m, by adding the suffix [47m"$C"[0m. The [47m:EXEC[0m function must be the creator for the foundational stobj (which can be specified using the [47m:FOUNDATION[0m keyword). [47mCorr-fn[0m is a known function symbol that takes two arguments (for the correspondence theorems). The default for [47mcorr-fn[0m is obtained by adding the suffix [47m"$CORR"[0m to [47mname[0m. [47mCorr-fn-exists[0m is a Boolean with default [47mnil[0m, which will generally serve well. See [stobj-attachment-restrictions] for a discussion of this argument. [47mCongruent-to[0m should either be [47mnil[0m (the default) or the name of an abstract stobj previously introduced (by [47m[defabsstobj][0m). In the latter case, the current and previous abstract stobj should have the same foundational stobj (not merely congruent foundational stobjs), and their [47m:EXPORTS[0m fields should have the same length and also correspond, as follows: the ith export of each should have the same [47m:LOGIC[0m and [47m:EXEC[0m symbols. See [defstobj] for more about congruent stobjs. Note that if two names are congruent, then they are either both ordinary stobjs or both abstract stobjs. [47mNon-executable[0m should either be [47mnil[0m (the default) or [47mt[0m. When [47mt[0m, a global stobj is not created for the given name; see [defstobj], Section ``Specifying Non-executable Stobjs'', for details, as the meaning of [47m:non-executable[0m is the same for [47mdefabsstobj[0m as it is for [47mdefstobj[0m. [47mProtect-default[0m should either be [47mnil[0m (the default) or [47mt[0m. It provides the value of keyword [47m:PROTECT[0m for each member of [47mexports[0m that does not explicitly specify [47m:PROTECT[0m. See the discussion of [47mexports[0m below. [47mAttachable[0m should be [47mnil[0m (the default) or [47mt[0m. See [attach-stobj] for a discussion of this keyword. An important aspect of the [47mcongruent-to[0m parameter is that if it is not [47mnil[0m, then the checks for lemmas --- [47m{CORRESPONDENCE}[0m, [47m{GUARD-THM}[0m, and [47m{PRESERVED}[0m --- are omitted. Thus, the values of keywords [47m:CORR-FN[0m and [47m:CORR-FN-EXISTS[0m, and the values of keywords [47m:CORRESPONDENCE[0m, [47m:GUARD-THM[0m, and [47m:PRESERVED[0m in each export (as we discuss next), are irrelevant; they are not inferred and they need not be supplied. The value of [47m:EXPORTS[0m is a non-empty true list. Each [47mei[0m is a function spec (for an exported function). The valid keywords are [47m:LOGIC[0m, [47m:EXEC[0m, [47m:CORRESPONDENCE[0m, [47m:GUARD-THM[0m, [47m:PROTECT[0m, and [47m:UPDATER[0m, and also [47m:PRESERVED[0m if and only if the specified [47m:EXEC[0m function returns the foundational stobj. The default values for all of these keywords except [47m:UPDATER[0m and [47m:PROTECT[0m are obtained by respectively adding the suffix [47m"$A"[0m [47m"$C"[0m, [47m"{CORRESPONDENCE}"[0m, [47m"{GUARD-THM}"[0m, or [47m"{PRESERVED}"[0m. For [47m:PROTECT[0m, the default is [47mnil[0m unless the [47mdefabsstobj[0m event specifies [47m:PROTECT-DEFAULT t[0m. If [47m:UPDATER upd[0m is supplied and [47mupd[0m is not [47mnil[0m, then function exported by the function spec is a child stobj accessor whose corresponding updater is [47mupd[0m; see the discussion of [47m:UPDATER[0m in [nested-stobjs]. Not shown is the keyword, [47m:MISSING[0m; the effect of [47m:missing t[0m is to turn the call of [47mdefabsstobj[0m into a corresponding call of [47m[defabsstobj-missing-events][0m. Note that a [47mdefabsstobj[0m event will fail if the required lemmas --- that is, those for valid keywords [47m:CORRESPONDENCE[0m, [47m:GUARD-THM[0m, and [47m:PRESERVED[0m --- have not been proved, unless proofs are being skipped. The exemption when skipping proofs allows the supporting lemmas to be [47m[local][0m to [books] and [47m[encapsulate][0m [events]. If the [47m[ld][0m special [47m[ld-skip-proofsp][0m is [47mt[0m, then the missing [events] are printed with a warning before the [47mdefabsstobj[0m event is admitted; but if [47mld-skip-proofsp[0m is the symbol [47mINCLUDE-BOOK[0m, then that warning is omitted. (Also see [skip-proofs] and see [ld-skip-proofsp].) If however proofs are not being skipped, then the [47mdefabsstobj[0m event will fail after printing the missing events. Advanced users may wish to see [defabsstobj-missing-events] for a utility that returns a data structure containing the missing lemmas. Let [47mst[0m be an abstract stobj with corresponding foundational stobj [47mst$c[0m. Let [47mf[0m be an exported function for [47mst[0m and let [47mf$a[0m and [47mf$c[0m be the corresponding [47m:LOGIC[0m and [47m:EXEC[0m functions, respectively. The formals of [47mf[0m are obtained by taking the formals of [47mf$c[0m and replacing [47mst$c[0m by [47mst[0m. The [guard] for [47mf[0m is derived as follows from the guard of [47mf$a[0m. First, the formals of [47mf$a[0m are replaced by the formals of [47mf[0m in the guard of [47mf$a[0m, to obtain a term we denote here as [47mguard-pre[0m. Now for each exported function symbol [47mg[0m of [47mst[0m with corresponding [47m:LOGIC[0m function [47mg$a[0m, form a functional substitution by consing [47mg$a[0m with [47mg[0m. Finally, apply that functional substitution to [47mguard-pre[0m; the result is the guard of [47mf[0m. That guard must satisfy the usual conditions of a guard: thus, it must return a single non-[stobj] value and satisfy normal syntactic restrictions, including single-threadedness in its handling of stobjs. [47mRemark[0m. Because of how guards are created for exported functions, and in particular because [47m:LOGIC[0m functions are replaced as discussed above, a good discipline is to define [47m:LOGIC[0m functions that are not intended for general use, but are intended only for use as [47m:LOGIC[0m functions of corresponding stobj primitives. For example, suppose that you use [47mlength[0m as the [47m:LOGIC[0m function for some stobj primitive, [47mf[0m (as opposed to using your own function, say, [47mfoo-length[0m or [47mfoo$a[0m). Then every call of [47mlength[0m will be replaced by [47mf[0m when creating the guard of a stobj primitive from the guard of its [47m:LOGIC[0m function. This might not be what you intended if you were using [47mlength[0m in that guard simply to compute the length of an ordinary list. Additional restrictions include the following. * All exported function names must be new (unless redefinition is on; see [ld-redefinition-action]), and there must be no duplicates among them. * The foundational stobj name must be a formal parameter of the [47m:EXEC[0m function of every function spec, except for the [47m:CREATOR[0m function spec. * The [47m:LOGIC[0m and [47m:EXEC[0m function for a function spec must agree on both the number of inputs and the number of outputs. * The foundational stobj must not be a [declare]d stobj of the [47m:LOGIC[0m function of any function spec. (This restriction could perhaps be removed, but it is convenient for the implementation of the events generated by a call of [47mdefabsstobj[0m.) * The [47m:PROTECT[0m keyword is something that you should ignore unless you get an error message about it, pertaining to modifying the foundational stobj non-atomically. In that case, you can eliminate the error by providing [47m:PROTECT t[0m in the function spec, or by providing [47mdefabsstobj[0m keyword argument [47m:PROTECT-DEFAULT t[0m at the top level, in order to restore the required atomicity. The above explanation is probably all you need to know about [47m:PROTECT[0m, but just below is a more complete explanation for those who desire it. Further information is also available if you need it; see [set-absstobj-debug], and see the example uses of these keywords in community book [47mbooks/demos/defabsstobj-example-2.lisp[0m. For those who are interested, here is a more detailed discussion of [47m:PROTECT[0m and [47m:PROTECT-DEFAULT[0m, as promised above. It applies to any function spec for an export (hence not to the [47m:CREATOR[0m function spec). If the [47m:EXEC[0m function is a stobj primitive, then clearly the following property holds: any execution of a call of that function can only update the foundational stobj at most once --- i.e., modification of the foundational stobj is atomic. ACL2 can deduce this property not only for stobj primitives but for many other functions as well. However, if ACL2 cannot deduce this property, then it will cause an error saying that the [47m:EXEC[0m function ``appears capable of modifying the foundational stobj, [47m<stobj_name>[0m, non-atomically.'' That message also explains how to eliminate this error: provide [47m:PROTECT t[0m for the function spec. Alternatively, all function specs without an explicit [47m:PROTECT[0m keyword can be implicitly supplied [47m:PROTECT t[0m by supplying the value [47mt[0m for the [47m:PROTECT-DEFAULT[0m keyword parameter of the [47mdefabsstobj[0m event. However, beware that when [47m:PROTECT[0m is [47mt[0m, the generated raw Lisp code runs slightly less efficiently --- though perhaps with negligible efficiency loss if the [47m:EXEC[0m function is not trivial. Community books [47mbooks/demos/defabsstobj-example-3.lisp[0m and [47mbooks/demos/defabsstobj-example-4.lisp[0m provide related information. Also see [set-absstobj-debug] for a potentially dangerous way to eliminate that inefficiency using argument [47m:ignore[0m. We conclude with some remarks. Unlike [47m[defstobj][0m, there is no [47m:renaming[0m argument. Instead, the scheme described above provides a flexible way to assign names. Also unlike [47m[defstobj][0m, there is no [47m:inline[0m or [47m:non-memoizable[0m argument; [47m:inline[0m is essentially t, in the sense that stobj primitives are macros in raw Lisp; and the [47m:non-memoizable[0m argument is derived implicitly, to agree with non-memoizability of the foundational stobj. Those who use [hons-enabled] features, including function memoization (see [memoize]), may be aware that the memo table for a function is flushed whenever it is the case that one of its stobj inputs is updated. In fact, such flushing happens even when a stobj that is congruent to one of its stobj inputs is updated. For that purpose, an abstract stobj is considered to be congruent to its foundational stobj. Subtopics [Attach-stobj] Attach an ``implementation [stobj]'' to an attachable stobj [Illegal-state] Illegal ACL2 state [Set-absstobj-debug] Get more information when atomic update fails for an abstract stobj") (defabsstobj-missing-events (events) "Obtain the [events] needed to admit a [47m[defabsstobj][0m event We assume familiarity with [47m[defabsstobj][0m. [47mDefabsstobj-missing-events[0m is a macro is for advanced users (who, for example, understand the role of the [47mtranslate[0m and [47muntranslate[0m functions), who want programmatic access to the [47m[defthm][0m events required to admit a specific [47mdefabsstobj[0m event. This macro has the same syntax as [47m[defabsstobj][0m --- to use it, just replace a call of [47m[defabsstobj][0m by a call of [47mdefabsstobj-missing-events[0m on the same arguments. The result is an error triple [47m(mv erp val state)[0m. If [47merp[0m is [47mnil[0m, then [47mval[0m is the list of all objects [47m(name formula . old-formula)[0m, where a [47m[defthm][0m event named [47mname[0m remains to be admitted whose translated formula is [47mformula[0m, and where [47mold-formula[0m is [47mnil[0m unless the indicated event already exists (hence with a different formula), in which case [47mold-formula[0m is the existing translated formula. To build a [47m[defthm][0m event from the above value, [47mval[0m, we suggest evaluating a form like [47m(untranslate formula t (w state))[0m.") (defattach (events) "Execute constrained functions using corresponding attached functions General Forms: (defattach f g) ; single attach or, if g is nil, unattach (defattach (f1 g1 :kwd val ...) ... (fk gk :kwd' val' ...) :kwd'' val'' ...) where each indicated keyword-value pair is optional and each keyword is in the list [47m(:hints :instructions :otf-flg :attach :skip-checks :system-ok)[0m. More details are in the ``Syntax and Semantics'' section below. A related utility can cause a function call to be evaluated using an alternate, provably equal function. See [memoize], option [47m:INVOKE[0m. This [documentation] topic is organized into the following sections: * Introductory Example. * Syntax and Semantics of Defattach. * Three Primary Uses of Defattach. * Miscellaneous Remarks, with discussion of possible user errors. Please see [encapsulate] if you intend to use [47mdefattach[0m but are not already familiar with the use of [47mencapsulate[0m to introduce constrained functions. It may also be helpful to see [evaluation]. See community book [47mbooks/misc/defattach-example.lisp[0m for a small example. it illustrates how [47mdefattach[0m may be used to build something like ``higher-order'' programs, in which constrained functions may be refined to different executable functions. More uses of [47mdefattach[0m may be found in the ACL2 source code, specifically, file [47mboot-strap-pass-2-a.lisp[0m. Introductory Example. We begin with a short log illustrating the use of [47mdefattach[0m. Notice that after evaluating the event [47m(defattach f g)[0m, a call of the constrained function [47mf[0m is evaluated by instead calling [47mg[0m on the arguments. ACL2 !>(encapsulate ((f (x) t :guard (true-listp x))) (local (defun f (x) x)) (defthm f-property (implies (consp x) (consp (f x))))) [... output omitted ...] T ACL2 !>(defun g (x) (declare (xargs :guard (or (consp x) (null x)))) (cons 17 (car x))) [... output omitted ...] G ACL2 !>(f '(3 4)) ; undefined function error ACL2 Error in TOP-LEVEL: ACL2 cannot ev the call of undefined function F on argument list: ((3 4)) To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !>(defattach f g) [... output omitted ...] :ATTACHMENTS-RECORDED ACL2 !>(f '(3 4)) ; f is evaluated using g (17 . 3) ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(f '(3 4)) ; f is evaluated using g 1> (ACL2_*1*_ACL2::F (3 4)) 2> (ACL2_*1*_ACL2::G (3 4)) 3> (G (3 4)) <3 (G (17 . 3)) <2 (ACL2_*1*_ACL2::G (17 . 3)) <1 (ACL2_*1*_ACL2::F (17 . 3)) (17 . 3) ACL2 !>(defattach f nil) ; unattach f (remove its attachment) [... output omitted ...] :ATTACHMENTS-RECORDED ACL2 !>(f '(3 4)) ; undefined function error once again 1> (ACL2_*1*_ACL2::F (3 4)) ACL2 Error in TOP-LEVEL: ACL2 cannot ev the call of undefined function F on argument list: ((3 4)) To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> Syntax and Semantics of Defattach. The log above shows that the event [47m(defattach f g)[0m allows [47mg[0m to be used for evaluating calls of [47mf[0m. From a logical perspective, the evaluation takes place in the addition to the current session of an ``attachment equation'' axiom (universally quantified over all [47mx[0m) for each [47mdefattach[0m event: (equal (f x) (g x)) ;;; attachment equation axiom for (defattach f g) Below we explain [47mdefattach[0m in some detail. But it is important to keep in mind that evaluation with the attachment equations takes place in an extension of the logical theory of the session. ACL2 guarantees that this so-called ``evaluation theory'' remains consistent, assuming the absence of [47m[defaxiom][0m [events] from the user. This guarantee is a consequence of a more general guarantee: an ACL2 logical [world] exists in which (loosely speaking) the attachment equation for [47m(defattach f g)[0m, as [47m(defun f (...) (g ...))[0m, takes the place of the original defining event for [47mf[0m, for each [47mdefattach[0m event. This more general guarantee holds even if there are [47m[defaxiom][0m events, though as explained below, no function symbol that syntactically supports a [47mdefaxiom[0m formula is allowed to get an attachment. A deeper discussion of the logical issues is available (but not intended to be read by most users) in a long comment in the ACL2 source code labeled ``Essay on Defattach.'' Example Forms: (defattach f g) ; call g in place of calling constrained function f (defattach (f g)) ; same as just above (defattach (f g :hints (("Goal" :in-theory (enable foo))))) ; equivalent to first form above, except with hints for the ; proof that the guard of f implies the guard of g (defattach (f g :hints (("Goal" :in-theory (enable foo))) :otf-flg t)) ; as above, except with an :otf-flg of t for the proof that ; the guard of f implies the guard of g (defattach (f g) :hints (("Goal" :use my-thm))) ; equivalent to first form above, except with hints for the ; proof that the constraints on f hold for g (defattach (f g) :hints (("Goal" :use my-thm)) :otf-flg t) ; as above, except with an :otf-flg of t for the proof that ; the constraints on f hold for g (defattach (f g) (h j)) ; Attach g to f and attach j to h (defattach (f g :attach nil) (h j)) ; Same as just above, including the same proof obligations, ; except for one difference: because of :attach nil, calls ; of f will not be evaluated, i.e., there will be no ; executable attachment of g to f (defattach (f nil) (h j)) ; Attach j to h and unattach f (defattach (f g :hints (("Goal" :in-theory (enable foo)))) (h j :hints (("Goal" :in-theory (enable bar)))) :hints (("Goal" :use my-thm))) ; Attach g to f and attach j to h, with hints: ; - For proving that the guard of f implies the guard of g, ; enable foo; ; - For proving that the guard of h implies the guard of j, ; enable bar; and ; - For proving that the constraints on f and h hold for ; g and j (respectively), use theorem my-thm. (defattach f nil) ; remove the attachment of f, if any (e.g., g above) (defattach (f nil)) ; same as just above General Forms: (defattach f g) ; single attach or, if g is nil, unattach (defattach (f1 g1 :kwd11 val11 ...) ... (fk gk :kwdk1 valk1 ...) :kwd1 val1 ...) where each indicated keyword-value pair is optional and each keyword is in the list [47m(:hints :instructions :otf-flg :attach :skip-checks :system-ok)[0m. We distinguish between keywords within the [47m(fi gi :kwdi1 vali1 ...)[0m, which we call [3mguard keywords[0m, and keywords at the top level, shown above as [47m:kwd1 val1 ...[0m, which we call [3mtop-level keywords[0m. * The guard keywords are in the list [47m(:hints :instructions :otf-flg :attach)[0m. The [47m:[0m[47m[hints][0m, [47m:[0m[47m[instructions][0m, and [47m:[0m[47m[otf-flg][0m keywords in [47m(fi gi ...)[0m are used in the proofs of the guard proof obligation for the attachment of [47mgi[0m to [47mfi[0m. They have their usual values and meanings, as when used (for example) in [47m[defthm][0m [47m[events][0m. The value of each [47m:attach[0m keyword is either [47mt[0m or [47mnil[0m. We discuss the [47m:attach[0m keyword later in this [documentation] topic. * The top-level keywords [47m:hints[0m, [47m:instructions[0m, and [47m:otf-flg[0m are used in the constraint proof obligations just as described above for the guard proof obligations. When [47m:attach[0m is used as a top-level keyword, its value serves as a default for entries [47m(fi gi ...)[0m that do not specify [47m:attach[0m. [47m:Skip-checks[0m and [47m:system-ok[0m are described below. No keyword may occur twice in the same context: that is, neither twice as a guard keyword in the same [47m(fi gi ...)[0m entry, nor twice as a top-level keyword. Moreover, [47m:instructions[0m may not occur in the same context with [47m:hints[0m or [47m:otf-flg[0m. The argument [47m:skip-checks t[0m enables easy experimentation with [47mdefattach[0m, by permitting use of [47m:[0m[47m[program][0m mode functions and the skipping of semantic checks. Also permitted is [47m:skip-checks nil[0m (the default) and [47m:skip-checks :cycles[0m, which turns off only the update of the extended ancestor relation (defined below) and hence the check for cycles in this relation (which is discussed below). We do not make any logical claims when the value of [47m:skip-checks[0m is non-[47mnil[0m; indeed, a trust tag is then required (see [defttag]). Note that the interaction of [memoization] and attachments is not tracked for attachments introduced with a non-[47mnil[0m value of [47m:skip-checks[0m. For more discussion of [47m:skip-checks t[0m, see [defproxy]; we do not discuss [47m:skip-checks[0m further, here. The argument [47m:system-ok t[0m allows attachment to system functions. Without this argument, the [47mdefattach[0m event will fail if any [47mfi[0m is a built-in ACL2 function. Rather than supplying this argument directly, it is recommended to use [47m[defattach-system][0m, which has the same syntax as [47mdefattach[0m with two exceptions: it adds [47m:system-ok t[0m automatically, that is, [47m:system-ok[0m is implicit; and it expands to a [47m[local][0m call of [47mdefattach[0m. The latter is important so that the attachment does not affect system behavior outside a book containing the [47mdefattach[0m event. Of course, if it is truly intended to affect such behavior, the argument [47m:system-ok t[0m may be given directly to [47mdefattach[0m, without a surrounding use of [47mlocal[0m. The first General Form above is simply an abbreviation for the form [47m(defattach (f g))[0m, which is an instance of the second General Form above. For the second General Form we say that [47mgi[0m is ``attached to'' [47mfi[0m (by the [47mdefattach[0m event) if [47mgi[0m is not [47mnil[0m, and otherwise we say that [47mfi[0m is ``unattached'' (by the [47mdefattach[0m event). It is also convenient to refer to [47m<fi,gi>[0m as an ``attachment pair'' (of the event) if [47mgi[0m is not [47mnil[0m. We may refer to the set of [47mfi[0m as the ``attachment nest'' of each [47mfi[0m. We start with a brief introduction to the first General Form in the case that [47mg[0m is not [47mnil[0m. This form arranges that during evaluation, with exceptions noted below, every call of the constrained function symbol [47mf[0m will in essence be replaced by a call of the function symbol [47mg[0m on the same arguments. We may then refer to [47mg[0m as the ``attachment of'' [47mf[0m, or say that ``[47mg[0m is attached to [47mf[0m.'' Notable exceptions, where we do not use attachments during evaluation, are for macroexpansion, evaluation of [47m[defconst][0m and [47m[defpkg][0m terms, evaluation during [47m[table][0m events, some [stobj] operations including all updates (see [STOBJ]), and especially evaluation of ground terms (terms without free variables) during proofs. However, even for these cases we allow the use of attachments in the first argument of [47m[prog2$][0m and, more generally, the next-to-last (i.e., second) argument of [47m[return-last][0m when its first argument is not of the form [47m'm[0m for some macro, [47mm[0m. To see why attachments are disallowed during evaluation of ground terms during proofs (except for the [47m[prog2$][0m and [47m[return-last][0m cases mentioned above), consider the following example. (defstub f (x) t) (defun g (x) (+ 3 x)) (defattach f g) If the form [47m(f 2)[0m is submitted at the ACL2 prompt, the result will be [47m5[0m because the attachment [47mg[0m of [47mf[0m is called on the argument, [47m2[0m. However, during a proof the term [47m(f 2)[0m will not be simplified to [47m5[0m, since that would be unsound, as there are no axioms about [47mf[0m that would justify such a simplification. For the case that [47mg[0m is [47mnil[0m in the first General Form above, the result is the removal of the existing attachment to [47mf[0m, if any. After this removal, calls of [47mf[0m will once again cause errors saying that ``ACL2 cannot ev the call of undefined function [47mf[0m ...''. In this case not only is the previous attachment to [47mf[0m removed; moreover, for every function symbol [47mf'[0m in the attachment nest of [47mf[0m in the [47mdefattach[0m event that introduced the existing attachment to [47mf[0m, then [47mf'[0m is unattached. (An example near the end of this [documentation] topic shows why this unattachment needs to be done.) Such removal takes place before the current [47mdefattach[0m is processed, but is restored if the new event fails to be admitted. We focus henceforth on the second General Form. There must be at least one attachment, i.e., [47mi[0m must be at least 1. All keywords are optional; their role is described below. The [47mfi[0m must be distinct constrained function symbols, that is, function symbols all introduced in [signature]s of [47m[encapsulate][0m [events] (or macros such as [47m[defstub][0m that generate [47m[encapsulate][0m events). Each non-[47mnil[0m [47mgi[0m is a [47m:[0m[47m[logic][0m-mode function symbol that has had its guards verified, with the same [signature] as [47mfi[0m (though formal parameters for [47mfi[0m and [47mgi[0m may have different names). (Note: The macro [47mdefattach![0m, defined in community book [47mbooks/misc/defattach-bang[0m, avoids this restriction.) This event generates proof obligations and an ordering check, both described below. The effect of this event is first to remove any existing attachments for all the function symbols [47mfi[0m, as described above for the first General Form, and then to attach each [47mgi[0m to [47mfi[0m. Proof obligations must be checked before making attachments. For this discussion we assume that each [47mgi[0m is non-[47mnil[0m (otherwise first remove all attachment pairs [47m<fi,gi>[0m for which [47mgi[0m is nil). Let [47ms[0m be the functional substitution mapping each [47mfi[0m to [47mgi[0m. For any term [47mu[0m, we write [47mu\s[0m for the result of applying [47ms[0m to [47mu[0m; that is, [47mu\s[0m is the ``functional instance'' obtained by replacing each [47mfi[0m by [47mgi[0m in [47mu[0m. Let [47mG_fi[0m and [47mG_gi[0m be the guards of [47mfi[0m and [47mgi[0m, respectively. Let [47mG_fi'[0m be the result of replacing each formal of [47mfi[0m by the corresponding formal of [47mgi[0m in [47mG_fi[0m. ACL2 first proves, for each [47mi[0m (in order), the formula [47m(implies G_fi' G_gi)\s[0m. If this sequence of proofs succeeds, then the remaining formula to prove is the functional instance [47mC\s[0m of the conjunction [47mC[0m of the constraints on the symbols [47mfi[0m; see [constraint]. This last proof obligation is thus similar to the one generated by functional instantiation (see [constraint]). As with functional instantiation, ACL2 stores the fact that such proofs have been done so that they are avoided in future events (see [lemma-instance]). Thus, you will likely avoid some proofs with the sequence (defattach f g) (defattach f nil) (defattach f g) (defattach f nil) ... rather than the sequence: (defattach f g) :u (defattach f g) :u ... It remains to describe an ordering check. We begin with the following motivating example. (defstub f (x) t) ; constrained function with no constraints (defun g (x) (declare (xargs :guard t)) (not (f x))) (defattach f g) ; ILLEGAL! Were the above [47mdefattach[0m event to succeed, the evaluation theory (discussed above) would be inconsistent: [47m(f x)[0m equals [47m(g x)[0m by the new attachment equation, which in turn equals [47m(not (f x))[0m by definition of [47mg[0m. The evaluation would therefore be meaningless. Also, from a practical perspective, there would be an infinite loop resulting from any call of [47mf[0m. We consider a function symbol [47mg[0m to be an [3mextended immediate ancestor of[0m a function symbol [47mf[0m if either of the following two criteria is met: (a) [47mg[0m occurs in the formula that introduces [47mf[0m (i.e., definition body or constraint) and [47mg[0m is introduced by an event different from (earlier than) the event introducing [47mf[0m; or (b) [47mg[0m is attached to [47mf[0m. We also consider [47mg[0m to be an extended immediate ancestor of [47mf[0m if there are function symbols [47mf'[0m and [47mg'[0m that are introduced in the same events as [47mf[0m and [47mg[0m, respectively (such as the same [47m[mutual-recursion][0m or the same [47m[encapsulate][0m with non-empty signatures), such that [47mg'[0m is an extended immediate ancestor of [47mf'[0m in the sense above. For a proposed [47mdefattach[0m event, we check that the graph defined by this relation has no cycles, where for condition (b) we include all attachment pairs that would result, including those remaining from earlier [47mdefattach[0m events. Of course, a special case is that no function symbol may be attached to itself. Similarly, no function symbol may be attached to any of its ``siblings'' --- function symbols introduced by the same event --- as siblings are considered equivalent for purposes of the acyclicity check. Three Primary Uses of Defattach. We anticipate three uses of [47mdefattach[0m: 1. Constrained function execution 2. Sound modification of the ACL2 system 3. Program refinement We discuss these in turn. 1. The example at the beginning of this [documentation] illustrates constrained function execution. 2. ACL2 is written essentially in itself. Thus, there is an opportunity to attach to system functions. For example, encapsulated function [47mtoo-many-ifs-post-rewrite[0m, in the ACL2 source code, receives an attachment of [47mtoo-many-ifs-post-rewrite-builtin[0m, which implements a heuristic used in the rewriter. See [system-attachments]. To find all such examples, search the source code for the string `-builtin'. Over time, we expect to continue replacing ACL2 source code in a similar manner. We invite the ACL2 community to assist in this ``open architecture'' enterprise; feel free to email the ACL2 implementors if you are interested in such activity. 3. Recall that for an attachment pair [47m<f,g>[0m, a proof obligation is (speaking informally) that [47mg[0m satisfies the constraint on [47mf[0m. Yet more informally speaking, [47mg[0m is ``more defined'' than [47mf[0m; we can think of [47mg[0m as ``refining'' [47mf[0m. With these informal notions as motivation, we can view defattach as providing refinement through the following formal observation: the evaluation theory extends the theory of the ACL2 session, specifically by the addition of all attachment equations. For the logic-inclined, it may be useful to think model-theoretically: The class of models of the evaluation theory is non-empty but is a subset of the class of models of the current session theory. Miscellaneous Remarks, with discussion of possible user errors. We conclude with remarks on some details. A [47mdefattach[0m event is never redundant (see [redundant-events]); in that sense it is analogous to [47m[in-theory][0m. As mentioned above, the use of attachments is disabled for evaluation of ground terms during proofs. However, attachments can be used on code during the proof process, essentially when the ``program refinement'' is on theorem prover code rather than on functions we are reasoning about. The attachment to [47mtoo-many-ifs-post-rewrite[0m described above provides one example of such attachments. Another example is that a meta function or clause-processor function can call functions that have attachments, with a restriction that those attached functions must not also be ancestral in a corresponding evaluator. See [evaluator-restrictions] for a discussion of that restriction, and see [transparent-functions] for a device that can relax the restriction (while imposing additional requirements on attachments). For an attachment pair [47m<f,g>[0m, evaluation of [47mf[0m never consults the [guard] of [47mf[0m. Rather, control passes to [47mg[0m, whose guard is checked if necessary. The proof obligation related to guards, as described above, guarantees that any legal call of [47mf[0m is also a legal call of [47mg[0m. Thus for guard-verified code that results in calls of [47mf[0m in raw Lisp, it is sound to replace these calls with corresponding calls of [47mg[0m. [47mDefattach[0m events are illegal inside any [47m[encapsulate][0m event with a non-empty [signature] unless they are [local] to the [47m[encapsulate][0m. (Of interest only to users of [47m[apply$][0m.) Special handling is applied when attempting to attach to a so-called [3mwarrant[0m, which is produced by an application of [47m[defwarrant][0m (or [47m[defun$][0m). In that case it is legal to attach the function [47mtrue-apply$-warrant[0m to the warrant, without any proof obligation. This attachment is actually performed automatically by [47mdefwarrant[0m, so users (even users of [47mapply$[0m) need not deal explicitly with such attachments. However, these attachments make warrants executable in the loop; for example, after [47m(defwarrant foo)[0m, [47m(warrant foo)[0m will evaluate to [47mt[0m in the loop. We next discuss a restriction based on a notion of a function symbol syntactically supporting an event. Function symbol [47mf[0m is [3mancestral[0m in event [47mE[0m if either [47mf[0m occurs in [47mE[0m, or (recursively) [47mf[0m occurs in an event [47mE'[0m that introduces some function symbol [47mg[0m that is ancestral in [47mE[0m. We require that no function symbol ancestral in the formula of a [47m[defaxiom][0m event may have an attachment. Theoretical reasons are discussed in comments in the ACL2 source code, but here we give a little example showing the need for some such restriction: without it, we show how to prove [47mnil[0m! (defn g1 () 1) (defn g2 () 2) (defstub f1 () t) (defstub f2 () t) (defund p (x) (declare (ignore x)) t) (defevaluator evl evl-list ((p x))) (defaxiom f1-is-f2 (equal (f1) (f2))) (defun meta-fn (x) (cond ((equal (f1) (f2)) x) (t *nil*))) (defthm bad-meta-rule (equal (evl x a) (evl (meta-fn x) a)) :rule-classes ((:meta :trigger-fns (p)))) (defattach f1 g1) (defattach f2 g2) (defthm contradiction nil :hints (("Goal" :use ((:instance (:theorem (not (p x))) (x t))))) :rule-classes nil) The form [47m(all-attachments (w state))[0m evaluates to the list of all attachments except in two cases: [warrant]s, and attachments introduced with a non-[47mnil[0m value of [47m:skip-checks[0m. To obtain the attachment to a function symbol [47mFN[0m, without the above restrictions and with value [47mnil[0m if there is no attachment to [47mFN[0m: [47m(cdr (attachment-pair 'FN (w state)))[0m. Next we discuss the [47m:ATTACH[0m keyword. There is rarely if ever a reason to specify [47m:ATTACH T[0m, but the following (admittedly contrived) example shows why it may be necessary to specify [47m:ATTACH NIL[0m. First we introduce three new function symbols. (defstub f (x) t) (defun g (x) (f x)) (encapsulate ((h (x) t)) (local (defun h (x) (g x))) (defthm h-prop (equal (h x) (g x)))) Now suppose we want to attach the function [47m[ACL2-numberp][0m to both [47mf[0m and [47mh[0m. (defattach (f acl2-numberp) (h acl2-numberp)) Such an attempt fails, because the following constraint is generated but is not a theorem: [47m(EQUAL (ACL2-NUMBERP X) (G X))[0m. Clearly we also need to attach to [47mg[0m as well. (defattach (f acl2-numberp) (h acl2-numberp) (g acl2-numberp)) But this fails for a different reason, as explained by the error message: ACL2 Error in ( DEFATTACH (F ACL2-NUMBERP) ...): It is illegal to attach to function symbol G, because it was introduced with DEFUN. See :DOC defattach. That is: logically, we need to attach [47macl2-numberp[0m to [47mg[0m, but we cannot actually attach to [47mg[0m because it was not introduced with [47m[encapsulate][0m (it was introduced with [47m[defun][0m). So we specify [47m:ATTACH NIL[0m for the attachment to [47mg[0m, saying that no actual attachment should be made to the code for [47mg[0m, even though for logical purposes we should consider that [47mg[0m has been given the indicated attachment. (defattach (f acl2-numberp) (h acl2-numberp) (g acl2-numberp :attach nil)) Finally, we can check that [47mf[0m, [47mg[0m, and [47mh[0m execute as expected. ACL2 !>(assert-event (and (f 3) (not (f t)) (g 3) (not (g t)) (h 3) (not (h t)))) :PASSED ACL2 !> The advanced feature, [47m[with-global-stobj][0m, imposes certain restrictions on a [47mdefattach[0m event. You can probably ignore this point unless you get an error pertaining to [47mwith-global-stobj[0m. For relevant documentation see [with-global-stobj], specifically the section on ``Constrained Functions and Defattach''. We conclude with an example promised above, showing why it is necessary in general to unattach all function symbols in an existing attachment nest when unattaching any one of those function symbols. Consider the following example. (defstub f1 () t) (encapsulate ((f2 () t)) (local (defun f2 () (f1))) (defthm f2=f1 (equal (f2) (f1)))) (encapsulate ((f3 () t)) (local (defun f3 () (f1))) (defthm f3=f1 (equal (f3) (f1)))) (defun four () (declare (xargs :guard t)) 4) (defun five () (declare (xargs :guard t)) 5) (defattach (f1 four) (f2 four)) (defattach (f1 five) (f3 five)) The second [47mdefattach[0m erases the existing attachment pair [47m<f1,four>[0m before installing the new attachment pairs [47m<f1,five>[0m and [47m<f3,five>[0m. After the second defattach, both [47m(f1)[0m and [47m(f3)[0m evaluate to 5. Now suppose that the attachment pair [47m<f2,four>[0m were not erased. Then we would have [47m(f1)[0m evaluating to 5 and [47m(f2)[0m evaluating to 4, contradicting the constraint [47mf2=f1[0m. The evaluation theory would thus be inconsistent, and at a more concrete level, the user might well be surprised by evaluation results if the code were written with the assumption specified in the constraint [47mf2=f1[0m. Subtopics [Defattach-system] Attach to built-in, system-level, constrained functions [Ignored-attachment] Why attachments are sometimes not used [System-attachments] System-level algorithms that users can modify with attachments") (defattach-system (defattach) "Attach to built-in, system-level, constrained functions For background on attachments, see [defattach]. The macro [47mdefattach-system[0m is a convenient way to attach to built-in functions. The event [47m(defattach f g)[0m will fail if [47mf[0m is built into ACL2. This failure can be overcome by specifying top-level keyword argument [47m:system-ok t[0m, for example: [47m(defattach (f g) :system-ok t)[0m. However, rather than supplying this argument directly, it is recommended to use [47mdefattach-system[0m, which has the same syntax as [47mdefattach[0m with two exceptions: it adds [47m:system-ok t[0m automatically, that is, [47m:system-ok[0m is implicit; and it expands to a [47m[local][0m call of [47mdefattach[0m. The latter is important so that the attachment does not affect system behavior outside a book containing the [47mdefattach[0m event. Of course, if it is truly intended to affect such behavior, the argument [47m:system-ok t[0m may be given directly to [47mdefattach[0m, without a surrounding use of [47mlocal[0m. See [system-attachments] for discussion of system attachments. Also see [efficiency] for how to use attachments to modify the prover's behavior.") (default (arrays acl2-built-ins) "Return the [47m:default[0m from the [header] of a 1- or 2-dimensional array Example Form: (default 'delta1 a) General Form: (default name alist) where [47mname[0m is an arbitrary object and [47malist[0m is a 1- or 2-dimensional array. This function returns the contents of the [47m:default[0m field of the [header] of [47malist[0m. When [47m[aref1][0m or [47m[aref2][0m is used to obtain a value for an index (or index pair) not bound in [47malist[0m, the default value is returned instead. Thus, the array [47malist[0m may be thought of as having been initialized with the default value. [47mdefault[0m operates in virtually constant time if [47malist[0m is the semantic value of [47mname[0m. See [arrays]. [31;1mFunction: [0m<default> (defun default (name l) (declare (xargs :guard (or (array1p name l) (array2p name l)))) (cadr (assoc-keyword :default (cdr (header name l)))))") (default-backchain-limit (rule-classes) "Specifying the backchain limit for a rule See [backchain-limit]. The initial value is [47m(nil nil)[0m. To inspect the current value (as explained elsewhere; see [backchain-limit]): (default-backchain-limit wrld :ts) ; for type-set reasoning (default-backchain-limit wrld :rewrite) ; for rewriting") (default-defun-mode (miscellaneous) "The default [defun-mode] of [47m[defun][0m'd functions When a [47m[defun][0m is processed and no [47m:mode[0m [47mxarg[0m is supplied, the function [47mdefault-defun-mode[0m is used. To find the default [defun-mode] of the current ACL2 [world], type [47m(default-defun-mode (w state))[0m. See [defun-mode] for a discussion of [defun-mode]s. To change the default [defun-mode] of the ACL2 [world], type one of the keywords [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m. The default ACL2 [prompt] displays the current default [defun-mode] by showing the character [47mp[0m for [47m:[0m[47m[program][0m mode, and omitting it for [47m:[0m[47m[logic][0m mode; see [default-print-prompt]. The default [defun-mode] may be changed using the keyword [command]s [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m, which are equivalent to the [command]s [47m(program)[0m and [47m(logic)[0m. Each of these names is documented separately: see [program] and see [logic]. The default [defun-mode] is stored in the [table] [47m[ACL2-defaults-table][0m and hence may also be changed by a [47m[table][0m [command]. See [table] and also see [ACL2-defaults-table]. Both mode-changing [command]s are [events]. While [events] that change the default [defun-mode] are permitted within an [47m[encapsulate][0m or the text of a book, their effects are [47m[local][0m in scope to the duration of the encapsulation or inclusion. For example, if the default [defun-mode] is [47m:[0m[47m[logic][0m and a book is included that contains the event [47m(program)[0m, then subsequent [events] within the book are processed with the default [defun-mode] [47m:[0m[47m[program][0m; but when the [47m[include-book][0m event completes, the default [defun-mode] will still be [47m:[0m[47m[logic][0m. [Command]s that change the default [defun-mode] are not permitted inside [47m[local][0m forms.") (default-hints (hints) "A list of hints added to every proof attempt Examples: ACL2 !>(default-hints (w state)) ((computed-hint-1 clause) (computed-hint-2 clause stable-under-simplificationp)) The value returned by this function is appended to the right of any explicitly provided :[hints] argument of every [47m[defthm][0m, [47m[thm][0m, and [47m[defun][0m event, and similarly for the [47m:guard-hints[0m argument of [47mdefun[0m, and, for ACL2(r), the [47m:std-hints[0m argument. See [set-default-hints] for a more general discussion. Advanced users only: see [override-hints] for an advanced variant of default hints that are not superseded by [47m:[0m[47m[hints][0m arguments. Subtopics [Add-default-hints] Add to the default hints [Add-default-hints!] Add to the default hints non-[47m[local][0mly [Default-hints-table] A [table] used to provide [hints] for proofs [Remove-default-hints] Remove from the default hints [Remove-default-hints!] Remove from the default hints non-[47m[local][0mly [Set-default-hints] Set the default hints [Set-default-hints!] Set the default hints non-[47m[local][0mly") (default-hints-table (default-hints) "A [table] used to provide [hints] for proofs Please see [set-default-hints], see [add-default-hints], and see [remove-default-hints] for how to use this table. For completeness, we mention here that under the hood, these events all update the [47mdefault-hints-table[0m by updating its key, [47mt[0m, for example as follows. (table default-hints-table t '((computed-hint-1 clause) (computed-hint-2 clause stable-under-simplificationp))) The use of default hints is explained elsewhere; see [set-default-hints]. Advanced users only: see [override-hints] for an advanced variant of default hints.") (default-print-prompt (ld) "The default [prompt] printed by [47m[ld][0m Example prompt: ACL2 p!s> The [prompt] printed by ACL2 displays the current package, followed by a space, followed by zero or more of the three [characters] as specified below, followed by the character [47m[>][0m printed one or more times, reflecting the number of recursive calls of [47m[ld][0m. The three [characters] in the middle are as follows: p ; when (default-defun-mode (w state)) is :program ! ; when guard checking is on s ; when (ld-skip-proofsp state) is t See [default-defun-mode], see [set-guard-checking], and see [ld-skip-proofsp]. Also see [ld-prompt] to see how to install your own [prompt]. Here are some examples with [47mld-skip-proofsp nil[0m. ACL2 !> ; logic mode with guard checking on ACL2 > ; logic mode with guard checking off ACL2 p!> ; program mode with guard checking on ACL2 p> ; program mode with guard checking off Here are some examples with [47m[default-defun-mode][0m of [47m:[0m[47m[logic][0m. ACL2 > ; guard checking off, ld-skip-proofsp nil ACL2 s> ; guard checking off, ld-skip-proofsp t ACL2 !> ; guard checking on, ld-skip-proofsp nil ACL2 !s> ; guard checking on, ld-skip-proofsp t Finally, here is the prompt in raw mode (see [set-raw-mode]), regardless of the settings above: ACL2 P>") (default-ruler-extenders (rulers) "The default [ruler-extenders] for [47m[defun][0m'd functions When a [47m[defun][0m is processed and no [47m:ruler-extenders[0m [47mxarg[0m is supplied, the function [47mdefault-ruler-extenders[0m is used to obtain the current ruler-extenders; see [rulers]. To find the default ruler-extenders of the current ACL2 [world], type [47m(default-ruler-extenders (w state))[0m. While [events] that change the default ruler-extenders are permitted within an [47m[encapsulate][0m or the text of a book, their effects are [47m[local][0m in scope to the duration of the encapsulation or inclusion. See [default-defun-mode] for an analogous discussion for defun-modes.") (default-state-vars (pointers) "See [system-utilities].") (default-total-parallelism-work-limit (parallel-proof) "For ACL2(p): returns the default value for global [47mtotal-parallelism-work-limit[0m See [set-total-parallelism-work-limit].") (default-verify-guards-eagerness (pointers) "See [set-verify-guards-eagerness].") (defaxiom (events) "Add an axiom WARNING: We strongly recommend that you not add axioms. If at all possible you should use [47m[defun][0m or [47m[mutual-recursion][0m to define new concepts recursively or use [47m[encapsulate][0m to constrain them constructively. If your goal is to defer proving a formula that is, logically speaking, a theorem of the current theory, then consider using [47m[skip-proofs][0m instead. One such case is the use of a top-down style, as per the discussion on ``Top-Down Proof'' in Section B.1.2 of ``Computer-Aided Reasoning: An Approach.'' Note that adding new axioms may frequently render the logic inconsistent! Example: (defaxiom sbar (equal t nil) :rule-classes nil) General Form: (defaxiom name term :rule-classes rule-classes) where [47mname[0m is a new symbolic name (see [name]), [47mterm[0m is a term intended to be a new axiom, and [47mrule-classes[0m is a legal value for [47m:rule-classes[0m (see [rule-classes]). The keyword argument is optional. If [47m:[0m[47m[rule-classes][0m is not supplied, the list [47m(:rewrite)[0m is used; if you wish the axiom to generate no rules, specify [47m:[0m[47m[rule-classes][0m [47mnil[0m.") (defbadge (apply$ acl2-built-ins) "Issue a badge for a function so [47m[apply$][0m can evaluate with it It is best to be somewhat familiar with the documentation of [47m[apply$][0m before reading this topic. Before using [47mdefbadge[0m or a utility like [47m[defun$][0m that relies on it: (include-book "projects/apply/top" :dir :system) Badges versus Warrants It is easy to confuse [badge]s, which are issued by [47mdefbadge[0m, with [warrant]s, which are issued by [47m[defwarrant][0m. Badges and warrants are necessary to ACL2's support of [47m[apply$][0m because ACL2 is actually first-order, functions cannot be passed around as objects, ordinary symbols play the role of ``function objects,'' and somehow the logic must allow the association of a symbol with the function it names. Furthermore, to insure the consistency of the logic [47mapply$[0m is not allowed to handle certain functions such as the [47mrussell[0m function illustrated in [47m[introduction-to-apply$][0m. But to determine whether a newly defined function is allowed to be known to [47mapply$[0m, the ACL2 system must be able to determine, in some sense, all the functions reachable from it. And finally, to be able to prove theorems about the application of such function names, the link between the symbols and the functions and the analyzed properties of the functions must be available to the prover in the form of axioms. Particularly vexing is the so-called ``[47mlocal[0m problem'' which raises the possibility of proving a theorem about the application of a name in the context of a local definition of the corresponding function and then exporting that theorem to a context where the name is defined differently (see [31;1mLesson 12[0m of [introduction-to-apply$]). Roughly speaking, badges are about syntax and warrants are about semantics. The badge for a symbol is a data structure in the ACL2 system that records information like whether the symbol names a known ACL2 function, how many arguments that function takes, how many results it returns, which arguments are treated like function objects to be [47m[apply$][0m'd, which are treated like expressions to be [47m[ev$][0m'd, and which are treated like ordinary ACL2 objects to be [47mcar[0m'd, [47mcdr[0m'd, consed, etc. The warrant for a function is in fact another function (actually a 0-ary predicate) defined in the logic. That predicate asserts some facts about the symbol. In particular, it specifies the badge of the symbol and it constrains the behavior of [47mapply$[0m on the symbol. [47mDefbadge[0m analyzes the definition of a function and constructs the badge if possible. [47mDefbadge[0m does not affect the logic --- no definitions or axioms are added. [47mDefbadge[0m can analyze both [47m:program[0m mode functions and [47m:logic[0m mode functions. [47mDefwarrant[0m, on the other hand, can only analyze [47m:logic[0m mode functions because it must inspect the measure used to justify the termination of the function and, if it is successful, it adds a [47m:logic[0m mode definition of the warrant to the logic. This definition links the symbol to the function via [47mbadge[0m and [47mapply$[0m and if the warrant is a hypothesis of a conjecture then the prover ``knows'' about the linkage. Both [47mdefbadge[0m and [47mdefwarrant[0m affect the top-level read-eval-print loop because that loop treats [47m:program[0m and [47m:logic[0m functions differently so that it can (a) allow [47m:program[0m mode terms to be evaluated to carry out commands such as [47m[defun][0m and [47m[defthm][0m, query the world or build and test prototypes, and (b) allow [47m:logic[0m mode terms to be evaluated while guaranteeing a certain correspondence with what can be proved. See [guarantees-of-the-top-level-loop]. Requirements of [47mDefbadge[0m General Form: (defbadge fn) where [47mfn[0m is a defined function name in either [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m mode. This command analyzes the body of [47mfn[0m to determine whether it satisfies certain stringent syntactic conditions discussed below. If the conditions are not met, [47mdefbadge[0m signals an error. Otherwise, it records a [badge] for [47mfn[0m. Badges record the input and output arities of [47mfn[0m and specify which arguments are ``functions'' that may be applied with [47mapply$[0m, which are ``expressions'' that may be evaluated with [47m[ev$][0m, and which are neither. The conditions checked are sufficient to allow [47m[apply$][0m to run the function safely at the top level of the ACL2 read-eval-print loop. However, in order to prove anything about a call of [47mapply$[0m on [47mfn[0m --- or even to evaluate such a call if [47mfn[0m is in [47m:[0m[47m[logic][0m mode, as discussed above --- [47mfn[0m will need a [warrant] as issued by [47m[defwarrant][0m. [47mDefbadge[0m does not issue warrants, just badges. [47mDefwarrant[0m can issue both badges and warrants. The first condition on [47mfn[0m is that it must be a defined function symbol. Since [47mfn[0m must be defined it may not be a constrained function such as one introduced by [47m[defchoose][0m or [47m[encapsulate][0m. In addition, [47mfn[0m may not be one of a very few ``blacklisted'' symbols (see the value of [47m*blacklisted-apply$-fns*[0m) like [47m[sys-call][0m (which requires a trust tag) or an [untouchable]. (For technical reasons, untouchables are disallowed even if they are on [47mtemp-touchable-fns[0m; see [47m[remove-untouchable][0m.) The other conditions depend on whether [47m[apply$][0m is reachable from [47mfn[0m. That is, can a call of [47mfn[0m lead to a call of [47mapply$[0m? If [47mapply$[0m is not reachable from [47mfn[0m, then there are no more conditions on [47mfn[0m. A badge for [47mfn[0m is computed and stored. We are more precise about ``reachability'' later. If [47mapply$[0m is reachable from [47mfn[0m, then there are additional conditions that must be checked. First, [47mfn[0m must not have been introduced with [47m[mutual-recursion][0m. The current badging machinery is unable to enforce the syntactic restrictions for mutually-recursive cliques. Another restriction is that every function mentioned in the body of [47mfn[0m, except [47mfn[0m itself, must already have a badge. Finally, [47mfn[0m must respect certain conventions regarding its use of [47m[apply$][0m and other [scion]s. The basic idea of this last restriction is to make sure that [47mapply$[0m is always called on a ``known'' function symbol or [47m[lambda][0m object. This restriction is enforced by checking the following conditions: [3m(a)[0m It must be possible for each formal of [47mfn[0m to be assigned one of three [ilk]s, [47m:FN[0m, [47m:EXPR[0m, or [47mNIL[0m, as described below. The basic idea is that a formal can be assigned ilk [47m:FN[0m (or ilk [47m:EXPR[0m) iff it is sometimes passed into a [47m:FN[0m (or [47m:EXPR[0m) slot in the body of [47mfn[0m and is never passed into any other kind of slot. A formal can be be assigned ilk [47mNIL[0m iff it is never passed into a slot of ilk [47m:FN[0m or [47m:EXPR[0m, i.e., if it is used exclusively as an ``ordinary'' object. We are more precise below. [3m(b)[0m Every [47m:FN[0m and [47m:EXPR[0m slot of every function called in the body of [47mfn[0m is occupied either by a formal of [47mfn[0m of the same ilk or, in the case of calls of functions other than [47mfn[0m, a quoted [tame] function symbol or quoted tame (preferably well-formed) [47mLAMBDA[0m object. (See [47m[well-formed-lambda-objectp][0m.) This completes the list of restrictions imposed by [47mdefbadge[0m. Discussion and Examples Note that if [47mapply$[0m is not reachable from [47mfn[0m, the restrictions imposed on [47mfn[0m are comparatively generous. Such a [47mfn[0m could be badged and warranted despite being defined mutually recursively or in terms of unbadged or even unbadgeable functions. Basically, if [47mfn[0m doesn't depend on [47mapply$[0m there is no danger that some argument of [47mfn[0m will be treated like a function object or an expression. After a successful [47mdefbadge[0m event for [47mfn[0m, the function [47m[badge][0m will return the computed badge (when executed in the top-level loop) and [47m[apply$][0m will be able to accept the [47mfn[0m as a functional argument. Here is an annotated script. First, carry out these two events, defining [47mfoldr[0m as a [47m:program[0m mode function. (include-book "projects/apply/top" :dir :system) (defun foldr (lst fn init) (declare (xargs :mode :program)) (if (endp lst) init (apply$ fn (list (car lst) (foldr (cdr lst) fn init))))) Note the [47mapply$[0m call in the definition. We see that [47mfoldr[0m treats its middle argument, [47mfn[0m, as a function of arity 2. We can run [47mfoldr[0m, even without assigning a badge to [47mfoldr[0m, as long as we supply a badged function symbol of arity 2 as the middle argument. Since the ACL2 primitive [47mcons[0m has a badge and has arity 2, we can use it: ACL2 !>(foldr '(a b c) 'cons '(d e f)) (A B C D E F) Since [47mfoldr[0m has arity 3, we can try to apply it to a list of three things. (apply$ 'foldr (list '(a b c) 'cons '(d e f))) ACL2 Error in TOP-LEVEL: The value of APPLY$-USERFN is not specified on FOLDR because FOLDR has not been badged. However, we can use [47mdefbadge[0m to compute and store the badge for [47mfoldr[0m. The badge says [47mfoldr[0m has input arity 3, output arity 1, and treats its middle argument as a function. We can recover the badge by calling the function [47m[badge][0m. We can successfully apply [47mfoldr[0m. We can even use it in a [47mlambda[0m expression that we pass as the middle argument to [47mfoldr[0m. ACL2 !>(defbadge foldr) FOLDR now has the badge (APPLY$-BADGE 3 1 NIL :FN NIL) but has no warrant. T ACL2 !>(badge 'foldr) (APPLY$-BADGE 3 1 NIL :FN NIL) ACL2 !>(apply$ 'foldr (list '(a b c) 'cons '(d e f))) (A B C D E F) ACL2 !>(foldr '((a b c) (d e) (f g h) (i j k)) (lambda$ (x y) (foldr x 'cons y)) nil) (A B C D E F G H I J K) The ``Reachability'' Test We now clarify the test that we colloquially described above as whether [47mapply$[0m is reachable from [47mfn[0m. The actual test is whether [47mapply$-userfn[0m is ancestral in [47mfn[0m. That is, does [47mfn[0m call [47mapply$-userfn[0m, or a function that calls [47mapply$-userfn[0m, or a function that calls a function that calls [47mapply$-userfn[0m, etc. Since the only system functions that call [47mapply$-userfn[0m are [47mapply$[0m, [47mev$[0m, and [warrant]s, and since it is very unusual for a user-defined function to call directly [47mapply$-userfn[0m, [47mev$[0m, or warrants, we think of this test colloquially as whether [47mapply$[0m is ancestral in [47mfn[0m. The test and the onerous conditions imposed when [47mapply$[0m is reachable is crucial to the soundness of the ACL2 proof theory. We discuss this further in the background material for [47m[apply$][0m, including {``Limited Second-Order Functionality in a First-Order Setting'' | http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore and offer a fully fleshed out metalevel proof that [47mapply$[0m and all [47m:logic[0m-mode scions can be modeled in the comment titled [47mEssay on Admitting a Model for Apply$ and the Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m. But badges are more concerned with syntax (and, for [47m:program[0m mode functions, evaluation) than the proof theory. Even if we convert [47mfoldr[0m to [47m:logic[0m mode we cannot prove anything interesting about what happens when it is applied with [47mapply$[0m. We can't even prove that [47mfoldr[0m has a badge or what that badge is! ACL2 !>(verify-termination foldr) [Successful. Output deleted.] FOLDR ACL2 !>(thm (equal (apply$ 'foldr (list x 'cons z)) (append x z))) [Unsuccessful. Output deleted.] ******** FAILED ******** ACL2 !>(thm (equal (badge 'foldr) '(APPLY$-BADGE 3 1 NIL :FN NIL))) [Unsuccessful. Output deleted.] ******** FAILED ******** In order to prove anything nontrivial about [47mfoldr[0m's badge or behavior under [47mapply$[0m we need the [47m[warrant][0m for [47mfoldr[0m. Warrants are issued by [47m[defwarrant][0m. If we execute (defwarrant foldr) and then amend the failed [47mthm[0m commands above by adding [47m(warrant foldr)[0m as a hypothesis, both amended formulas are provable. How Ilks Are Assigned If a formal variable (or its slot among the actuals) has an ilk of [47m:FN[0m then the variable is ``used as a function'' in the sense that it might eventually reach the first argument of a call of [47mapply$[0m and is never passed into an ``ordinary'' slot like those for [47mcons[0m. Similarly, an ilk of [47m:EXPR[0m means the variable is ``used as an expression'' and may eventually reach the first argument of [47mev$[0m. An ilk of [47mNIL[0m means the variable is never used as a function or an expression. The correctness of this algorithm is crucial to the safe evaluation of [47mapply$[0m on user-defined function symbols. It also is crucial to the termination argument justifying the consistency of the proof theory created if and when [47mfn[0m is warranted. The key to the inductive correctness of the algorithm implicitly described below is the fact that when the ACL2 logic is being booted up the only function symbol with a slot of ilk [47m:FN[0m is [47mapply$[0m and the only function with a slot of ilk [47m:EXPR[0m is [47mev$[0m. In both functions it is the first argument slot that is so distinguished. All other ACL2 primitives that use [47mapply$[0m or [47mev$[0m, e.g., [47mcollect$[0m, are defined, admissible, badged, and warranted under the same conditions user-defined functions are. Let [3mv [0m be the [3mi [0mth formal parameter of a defined function [3mfn[0m. Then the ilk of [3mv [0m is [47m:FN[0m iff the value of [3mv [0m eventually makes its way into the first argument of [47mapply$[0m, either in the definition of [47mfn[0m or in some function ancestral to (i.e., eventually called by) [47mfn[0m. Another way to say this is that there is an occurrence of [3mv [0m in a slot of ilk [47m:FN[0m. Furthermore, [3mv [0m is never used any other way: every place [3mv [0m occurs in the body of [3mfn [0m is in a slot of ilk [47m:FN[0m. And finally, in every recursive call of [3mfn [0m, [3mv [0m is passed identically in the [3mi [0mth argument position of the call. We say such a [3mv [0m is ``used (exclusively) as a function.'' The [3mi [0mth formal variable [3mv [0m has ilk [47m:EXPR[0m under analogous conditions except that instead of eventually getting into the first argument of [47mapply$[0m it eventually gets into the first argument of [47mev$[0m. We say such a [3mv [0m is ``used (exclusively) as an expression.'' Note: [47m[ev$][0m is the natural notion of expression evaluation in this context: look up the values of variables in the alist argument to [47mev$[0m, return quoted constants, and otherwise [47mapply$[0m function symbols and [47mLAMBDA[0m objects to the recursively obtained list of values returned by evaluating the actuals. However, [47mev$[0m first checks that the expression is [47m[tamep][0m. The [3mi [0mth formal variable [3mv [0m has ilk [47mNIL[0m if it never occurs in a [47m:FN[0m slot and never occurs in an [47m:EXPR[0m slot. We say such a [3mv [0m is ``used (exclusively) as an ordinary object.''") (defchoose (events) "Define a Skolem (witnessing) function Examples: (defchoose choose-x-for-p1-and-p2 (x) (y z) (and (p1 x y z) (p2 x y z))) ; Axiom added by the event above: (IMPLIES (AND (P1 X Y Z) (P2 X Y Z)) (LET ((X (CHOOSE-X-FOR-P1-AND-P2 Y Z))) (AND (P1 X Y Z) (P2 X Y Z)))) (defchoose choose-x-for-p1-and-p2 x (y z) ; equivalent to the above (and (p1 x y z) (p2 x y z))) ; The following is as above, but strengthens the axiom added to pick a sort ; of canonical witness, as described below. (defchoose choose-x-for-p1-and-p2 x (y z) (and (p1 x y z) (p2 x y z)) :strengthen t) (defchoose choose-x-and-y-for-p1-and-p2 (x y) (z) (and (p1 x y z) (p2 x y z))) General Form: (defchoose fn (bound-var1 ... bound-varn) (free-var1 ... free-vark) body :strengthen b), where [47mfn[0m is the symbol you wish to define and is a new symbolic name (see [name]), [47m(bound-var1 ... bound-varn)[0m is a list of distinct `bound' variables (see below), [47m(free-var1 ... free-vark)[0m is the list of formal parameters of [47mfn[0m and is disjoint from the bound variables, and [47mbody[0m is a term. The use of [47mlambda-list[0m keywords (such as [47m&optional[0m) is not allowed. The [47m:strengthen[0m keyword argument is optional; if supplied, it must be [47mt[0m or [47mnil[0m. The system treats [47mfn[0m very much as though it were declared in the [signature] of an [47m[encapsulate][0m event, with a single axiom exported as described below. If you supply a [47m:use[0m hint (see [hints]), [47m:use fn[0m, it will refer to that axiom. No rule (of class [47m:[0m[47m[rewrite][0m or otherwise; see [rule-classes]) is created for [47mfn[0m. [47mDefchoose[0m is only executed in [defun-mode] [47m:[0m[47m[logic][0m; see [defun-mode]. Also see [defun-sk]. In the most common case, where there is only one bound variable, it is permissible to omit the enclosing parentheses on that variable. The effect is the same whether or not those parentheses are omitted. We describe this case first, where there is only one bound variable, and then address the other case. Both cases are discussed assuming [47m:strengthen[0m is [47mnil[0m, which is the default. We deal with the case [47m:strengthen t[0m at the end. The effect of the form (defchoose fn bound-var (free-var1 ... free-vark) body) is to introduce a new function symbol, [47mfn[0m, with formal parameters [47m(free-var1 ... free-vark)[0m. Now consider the following axiom, which states that [47mfn[0m picks a value of [47mbound-var[0m so that the body will be true, if such a value exists: (1) (implies body (let ((bound-var (fn free-var1 ... free-vark))) body)) This axiom is ``clearly conservative'' under the conditions expressed above: the function [47mfn[0m simply picks out a ``witnessing'' value of [47mbound-var[0m if there is one. For a rigorous statement and proof of this conservativity claim, see [conservativity-of-defchoose]. Next consider the case that there is more than one bound variable, i.e., there is more than one bound-var in the following. (defchoose fn (bound-var1 ... bound-varn) (free-var1 ... free-vark) body) Then [47mfn[0m returns a multiple value with [47mn[0m components, and formula (1) above is expressed using [47m[mv-let][0m as follows: (implies body (mv-let (bound-var1 ... bound-varn) (fn free-var1 ... free-vark) body)) We now discuss the case that [47m:strengthen t[0m is supplied. For simplicity we return to our simplest case, with [47mdefchoose[0m applied to function [47mfn[0m, a single free variable [47my[0m, and a single bound variable [47mbound-var[0m. The idea is that if we pick the ``smallest'' witnessing [47mbound-var[0m for two different free variables [47my[0m and [47my1[0m, then either those two witnesses are the same, or else one is less than the other, in which case the smaller one is a witness for its free variable but not for the other. (See comments in source function [47mdefchoose-constraint-extra[0m for more details.) Below, [47mbody1[0m is the result of replacing [47my[0m by [47my1[0m in [47mbody[0m. (2) (or (equal (fn y) (fn y1)) (let ((bound-var (fn y))) (and body (not body1))) (let ((bound-var (fn y1))) (and body1 (not body)))) An important application of this additional axiom is to be able to define a ``fixing'' function that picks a canonical representative of each equivalence class, for a given equivalence relation. The following events illustrate this point. (encapsulate ((equiv (x y) t)) (local (defun equiv (x y) (equal x y))) (defequiv equiv)) (defchoose efix (x) (y) (equiv x y) :strengthen t) (defthm equiv-implies-equal-efix-1 (implies (equiv y y1) (equal (efix y) (efix y1))) :hints (("Goal" :use efix)) :rule-classes (:congruence)) (defthm efix-fixes (equiv (efix x) x) :hints (("Goal" :use ((:instance efix (y x)))))) If there is more than one bound variable, then (2) is modified in complete analogy to (1) to use [47m[mv-let][0m in place of [47m[let][0m. Comment for logicians: As we point out in the documentation for [47m[defun-sk][0m, [47mdefchoose[0m is ``appropriate,'' by which we mean that it is conservative, even in the presence of [47mepsilon-0[0m induction. For a proof, See [conservativity-of-defchoose]. Subtopics [Conservativity-of-defchoose] Proof of conservativity of [47m[defchoose][0m") (defcong (events) "Prove [congruence] rule [47mDefcong[0m is used to prove that one [equivalence] relation preserves another in a given argument position of a given function. Example: (defcong set-equal iff (memb x y) 2) is an abbreviation for (defthm set-equal-implies-iff-memb-2 (implies (set-equal y y-equiv) (iff (memb x y) (memb x y-equiv))) :rule-classes (:congruence)) See [congruence] and also see [equivalence]. General Form: (defcong equiv1 equiv2 term k :package package :event-name event-name :rule-classes rule-classes :instructions instructions :hints hints :otf-flg otf-flg) where [47mequiv1[0m and [47mequiv2[0m are known [equivalence] relations; [47mterm[0m is a call of a function [47mfn[0m, other than [47mif[0m, on the correct number of distinct variable arguments, [47m(fn x1 ... xn)[0m; [47mk[0m is a positive integer less than or equal to the arity of [47mfn[0m; [47mpackage[0m, if supplied, is one of [47m:current[0m, [47m:equiv1[0m, [47m:equiv2[0m, [47m:function[0m or [47m:legacy[0m; [47mevent-name[0m, if supplied, is a symbol; and other arguments are as specified in the documentation for [47m[defthm][0m. The [47mdefcong[0m macro expands into a call of [47m[defthm][0m. The name of the [47m[defthm][0m event is [47mequiv1-implies-equiv2-fn-k[0m, unless an [47m:event-name[0m keyword argument is supplied, in which case [47mevent-name[0m is used. The package of symbols generated, such as variables and [47m[defthm][0m names, is determined by the [47mpackage[0m argument: if it is not supplied or its value is [47m:current[0m, then the [47m[current-package][0m is used; if its value is [47m:equiv1[0m or [47m:legacy[0m, then the package of [47m:equiv1[0m is used; if its value is [47m:equiv2[0m, then the package of [47m:equiv2[0m is used; and if its value is [47m:function[0m, then the package of [47mfn[0m is used. The term of the theorem is (implies (equiv1 xk yk) (equiv2 (fn x1... xk ...xn) (fn x1... yk ...xn))). The rule-class [47m:[0m[47m[congruence][0m is added to the [47m[rule-classes][0m specified, if it is not already there. All other arguments to the generated [47m[defthm][0m form are as specified by the keyword arguments above. NOTE: In normal usage, [47mdefcong[0m can only create classic [congruence] rules, not [patterned-congruence] rules. However, if [47mfn[0m is a macro, it's possible for a patterned congruence rule to be generated, depending on what [47mterm[0m expands to. For example, the following produces a shallow patterned congruence rule: (defun f (x y) (and x y)) (defmacro g (x) `(f ,x t)) (defcong iff equal (g x) 1)") (defconst (events programming) "Define a constant Examples: (defconst *my-digits* '(0 1 2 3 4 5 6 7 8 9)) (defconst *len-my-digits* (the unsigned-byte (length *my-digits*))) General Form: (defconst name term) where [47mname[0m is a symbol beginning and ending with the character [47m*[0m and [47mterm[0m is a variable-free term that is evaluated to determine the value of the constant. There are two restrictions on [47mterm[0m aside from it being variable-free. Both restrictions relate to ancestral uses of [47m[apply$][0m in [47mterm[0m, i.e., uses of [47mapply$[0m by [47mterm[0m or any function that might be called during the evaluation of [47mterm[0m. First, only badged primitive functions may be applied. See [badge] for a way to obtain the complete list of badged primitives. Second, [47mloop$[0m and [47mlambda$[0m may not be used anywhere in the ancestry of term. See [47mignored-attachment[0m and [47mprohibition-of-loop$-and-lambda$[0m for more discussion. When a constant symbol is used as a [term], ACL2 replaces it by its value; see [term]. Note that [47mdefconst[0m uses so-called [safe-mode] to evaluate its form, in order to avoids soundness issues but with an efficiency penalty (perhaps increasing the evaluation time by several hundred percent). If efficiency is a concern, or if for some reason you need the form to be evaluated without safe mode (e.g., you are an advanced system hacker using trust tags to traffic in raw Lisp code), consider using [defconsts] instead. Also see [using-tables-efficiently] for an analogous issue with [47m[table][0m events. [47mDefconst[0m sets the [47mconst[0m property of [47mname[0m to the quoted value of [47mterm[0m. This can be retrieved with [47m[getpropc][0m. It may be of interest to note that [47mdefconst[0m is implemented at the lisp level using [47mdefparameter[0m, as opposed to [47mdefconstant[0m. (Implementation note: this is important for proper support of undoing and redefinition.) We close with a technical remark, perhaps of interest only who make use of the [hons-enabled] features of ACL2. For an event of the form [47m(defconst *C* (quote OBJ))[0m, i.e., [47m(defconst *C* 'OBJ)[0m, then the value associated with [47m*C*[0m is [47mOBJ[0m; that is, the value of [47m*C*[0m is [47m[eq][0m to the actual object [47mOBJ[0m occurring in the [47mdefconst[0m form. So for example, if [47m[make-event][0m is used to generate such a [47mdefconst[0m event, as it is in the two books mentioned above, and [47mOBJ[0m is a fast alist (see [fast-alists]), then the value of [47m*C*[0m is a fast alist. This guarantee disappears if the term in the [47mdefconst[0m form is not a quoted object, i.e., if it is not of the form [47m(quote OBJ)[0m. Subtopics [Ignored-attachment] Why attachments are sometimes not used [Prohibition-of-loop$-and-lambda$] Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms [Sharp-dot-reader] Read-time evaluation of constants") (defequiv (events) "Prove that a function is an [equivalence] relation Example: (defequiv set-equal) is an abbreviation for (defthm set-equal-is-an-equivalence (and (booleanp (set-equal x y)) (set-equal x x) (implies (set-equal x y) (set-equal y x)) (implies (and (set-equal x y) (set-equal y z)) (set-equal x z))) :rule-classes (:equivalence)) See [equivalence]. General Form: (defequiv equiv :package package :event-name event-name :rule-classes rule-classes :instructions instructions :hints hints :otf-flg otf-flg) where [47mequiv[0m is a function symbol of arity 2; [47mpackage[0m, if supplied, is one of [47m:current[0m, [47m:equiv[0m or [47m:legacy[0m; [47mevent-name[0m, if supplied, is a symbol; and all other arguments are as specified in the documentation for [47m[defthm][0m. The [47mdefequiv[0m macro expands into a call of [47m[defthm][0m. The name of the [47m[defthm][0m is [47mequiv-is-an-equivalence[0m, unless an [47m:event-name[0m keyword argument is supplied, in which case [47mevent-name[0m is used. The package of symbols generated, such as variables and [47m[defthm][0m names, is determined by the [47mpackage[0m argument: if it is not supplied or its value is [47m:current[0m, then the [47m[current-package][0m is used; if its value is [47m:equiv[0m or [47m:legacy[0m (which are treated identically), then the package of [47m:equiv[0m is used. All other arguments to the generated [47m[defthm][0m form are as specified by the other keyword arguments above. The rule-class [47m:[0m[47m[equivalence][0m is added to the [rule-classes] specified, if it is not already there. The term generated for the [47m[defthm][0m event states that [47mequiv[0m is Boolean, reflexive, symmetric, and transitive.") (defevaluator (events) "Introduce an evaluator function Example: (defevaluator evl evl-list ((length x) (member-equal x y))) See [meta]. General Form: (defevaluator ev ev-list ((g1 x1 ... xn_1) ... (gk x1 ... xn_k)) :namedp flg) ; [optional keyword argument] where [47mev[0m and [47mev-list[0m are new function symbols and [47mg1[0m, ..., [47mgk[0m are old function symbols with the indicated number of formals, i.e., each [47mgi[0m has [47mn_i[0m formals. If the [47m:namedp[0m keyword argument is provided, its value should be Boolean. If not provided, the default value for [47mflg[0m is [47mnil[0m. This function provides a convenient way to constrain [47mev[0m and [47mev-list[0m to be mutually-recursive evaluator functions for the symbols [47mg1[0m, ..., [47mgk[0m. Roughly speaking, an evaluator function for a fixed, finite set of function symbols is a restriction of the universal evaluator to terms composed of variables, constants, lambda expressions, and applications of the given functions. However, evaluator functions are constrained rather than defined, so that the proof that a given metafunction is correct vis-a-vis a particular evaluator function can be lifted (by functional instantiation) to a proof that it is correct for any larger evaluator function. See [meta] for a discussion of metafunctions. If the [47m:namedp[0m [47mflg[0m is [47mnil[0m (the default) constraints have names of the form [3mev[0m[47m-CONSTRAINT-[0m[3mi[0m, e.g., [47mEV-CONSTRAINT-0[0m, [47mEV-CONSTRAINT-1[0m, etc. If [47mflg[0m is non-[47mnil[0m, the constraints are named more mnemonically, e.g., [47mEV-OF-VARIABLE[0m, [47mEV-OF-REVAPPEND-CALL[0m, etc. We illustrate the [47m:namedp t[0m names below. [47mDefevaluator[0m executes an [47m[encapsulate][0m after generating the appropriate [47m[defun][0m and [47m[defthm][0m events. Perhaps the easiest way to understand what [47mdefevaluator[0m does is to execute the keyword command :trans1 (defevaluator evl evl-list ((length x) (member-equal x y))) and inspect the output. This trick is also useful in the rare case that the event fails because a hint is needed. In that case, the output of [47m:[0m[47m[trans1][0m can be edited by adding hints, then submitted directly. Formally, [47mev[0m is said to be an ``evaluator function for [47mg1[0m, ..., [47mgk[0m, with mutually-recursive counterpart [47mev-list[0m'' iff [47mev[0m and [47mev-list[0m are constrained functions satisfying just the [constraint]s discussed below. [47mEv[0m and [47mev-list[0m must satisfy [constraint]s (0)-(7) and (k) below. When [47m:namedp nil[0m is supplied, the [3mi[0m in the generated constraint names are the parenthesized numbers below. When [47m:namedp t[0m is supplied, the mnemonic names are those shown in brackets below. (0) How to ev an arbitrary function application: [EV-OF-FNCALL-ARGS] (implies (and (consp x) (syntaxp (not (equal a ''nil))) (not (equal (car x) 'quote))) (equal (ev x a) (ev (cons (car x) (kwote-lst (ev-list (cdr x) a))) nil))) (1) How to ev a variable symbol: [EV-OF-VARIABLE] (implies (symbolp x) (equal (ev x a) (and x (cdr (assoc-equal x a))))) (2) How to ev a constant: [EV-OF-QUOTE] (implies (and (consp x) (equal (car x) 'quote)) (equal (ev x a) (cadr x))) (3) How to ev a lambda application: [EV-OF-LAMBDA] (implies (and (consp x) (consp (car x))) (equal (ev x a) (ev (caddar x) (pairlis$ (cadar x) (ev-list (cdr x) a))))) (4) How to ev an empty argument list: [EV-LIST-OF-ATOM] (implies (not (consp x-lst)) (equal (ev-list x-lst a) nil)) (5) How to ev a non-empty argument list: [EV-LIST-OF-CONS] (implies (consp x-lst) (equal (ev-list x-lst a) (cons (ev (car x-lst) a) (ev-list (cdr x-lst) a)))) (6) How to ev a non-symbol atom: [EV-OF-NONSYMBOL-ATOM] (implies (and (not (consp x)) (not (symbolp x))) (equal (ev x a) nil)) (7) How to ev a cons whose car is a non-symbol atom: [EV-OF-BAD-FNCALL] (implies (and (consp x) (not (consp (car x))) (not (symbolp (car x)))) (equal (ev x a) nil)) (k) For each i from 1 to k, how to ev an application of gi, where gi is a function symbol of n arguments: [EV-OF-gi-CALL] (implies (and (consp x) (equal (car x) 'gi)) (equal (ev x a) (gi (ev x1 a) ... (ev xn a)))), where xi is the (cad...dr x) expression equivalent to (nth i x). [47mDefevaluator[0m defines suitable witnesses for [47mev[0m and [47mev-list[0m, proves the theorems about them, and constrains [47mev[0m and [47mev-list[0m appropriately. We expect [47mdefevaluator[0m to work without assistance from you, though the proofs do take some time and generate a lot of output. The proofs are done in the context of a fixed theory, namely the value of the constant [47m*defevaluator-form-base-theory*[0m. (Aside: (3) above may seem surprising, since the bindings of [47ma[0m are not included in the environment that is used to evaluate the lambda body, [47m(caddar x)[0m. However, ACL2 lambda expressions are all [3mclosed[0m: in [47m(lambda (v1 ... vn) body)[0m, the only free variables in [47mbody[0m are among the [47mvi[0m. See [term].) Acknowledgment: We thank Sol Swords and Jared Davis for their community book [47mtools/defevaluator-fast.lisp[0m, which provided the model on which the current [47mdefevaluator[0m is based. The original [47mdefevaluator[0m was very inefficient, e.g., taking thousands of times longer than the current one on an evaluator interpreting 800 function symbols. We refactored their [47mdefevaluator-fast[0m (with permission) and made it the new implementation as of ACL2 Version_7.2. Both implementations produce the same constraints modulo the naming option provided by [47m:namedp[0m.") (defexec (events mbe) "Attach a terminating executable function to a definition Suppose you define a function [47m(fn x)[0m with a [guard] of [47m(good-input-p x)[0m, and you know that when the guard holds, the measure decreases on each recursive call. Unfortunately, the definitional principle (see [defun]) ignores the guard. For example, if the definition has the form (defun fn (x) (declare (xargs :guard (good-input-p x))) (if (not-done-yet x) (... (fn (destr x)) ...) ...)) then in order to admit this definition, ACL2 must prove the appropriate formula asserting that [47m(destr x)[0m is ``smaller than'' [47mx[0m under the assumption [47m(not-done-yet x)[0m but without the assumption [47m(good-input-p x)[0m, even if [47m(not-done-yet x)[0m is true. In essence, it may be necessary to submit instead the following definition. (defun fn (x) (declare (xargs :guard (good-input-p x))) (if (good-input-p x) (if (not-done-yet x) (... (fn (destr x)) ...) ...) nil) But it is unfortunate that when calls of [47mfn[0m are evaluated, for example when [47mfn[0m is applied to an explicit constant during a proof, then a call of [47mgood-input-p[0m must now be evaluated on each recursive call. Fortunately, [47mdefexec[0m provides a way to keep the execution efficient. For the example above we could use the following form. (defexec fn (x) (declare (xargs :guard (good-input-p x))) (mbe :logic (if (good-input-p x) (if (not-done-yet x) (... (fn (destr x)) ...) ...) nil) :exec (if (not-done-yet x) (... (fn (destr x)) ...) ...))) Here ``[47m[mbe][0m'' stands for ``must be equal'' and, roughly speaking, its call above is logically equal to the [47m:logic[0m form but is evaluated using the [47m:exec[0m form when the guard holds. See [mbe]. The effect is thus to define [47mfn[0m as shown in the [47m[defun][0m form above, but to cause execution of [47mfn[0m using the [47m:exec[0m body. The use of [47mdefexec[0m instead of [47m[defun][0m in the example above causes a termination proof to be performed, in order to guarantee that evaluation always theoretically terminates, even when using the [47m:exec[0m form for evaluation. Example: ; Some of the keyword arguments in the declarations below are irrelevant or ; unnecessary, but they serve to illustrate their use. (defexec f (x) (declare (xargs :measure (+ 15 (acl2-count x)) :ruler-extenders :basic :hints (("Goal" :in-theory (disable nth))) :guard-hints (("Goal" :in-theory (disable last))) :guard (and (integerp x) (<= 0 x) (< x 25))) (exec-xargs :test (and (integerp x) (<= 0 x)) :default-value 'undef ; defaults to nil :measure (nfix x) :ruler-extenders :basic :well-founded-relation o<)) (mbe :logic (if (zp x) 1 (* x (f (- x 1)))) :exec (if (= x 0) 1 (* x (f (- x 1)))))) The above example macroexpands to the following. (ENCAPSULATE () (LOCAL (ENCAPSULATE () (SET-IGNORE-OK T) (SET-IRRELEVANT-FORMALS-OK T) (LOCAL (DEFUN F (X) (DECLARE (XARGS :VERIFY-GUARDS NIL :HINTS (("Goal" :IN-THEORY (DISABLE NTH))) :MEASURE (NFIX X) :RULER-EXTENDERS :BASIC :WELL-FOUNDED-RELATION O<)) (IF (AND (INTEGERP X) (<= 0 X)) (IF (= X 0) 1 (* X (F (- X 1)))) 'UNDEF))) (LOCAL (DEFTHM F-GUARD-IMPLIES-TEST (IMPLIES (AND (INTEGERP X) (<= 0 X) (< X 25)) (AND (INTEGERP X) (<= 0 X))) :RULE-CLASSES NIL)))) (DEFUN F (X) (DECLARE (XARGS :MEASURE (+ 15 (ACL2-COUNT X)) :RULER-EXTENDERS :BASIC :HINTS (("Goal" :IN-THEORY (DISABLE NTH))) :GUARD-HINTS (("Goal" :IN-THEORY (DISABLE LAST))) :GUARD (AND (INTEGERP X) (<= 0 X) (< X 25)))) (MBE :LOGIC (IF (ZP X) 1 (* X (F (- X 1)))) :EXEC (IF (= X 0) 1 (* X (F (- X 1))))))) Notice that in the example above, the [47m:[0m[47m[hints][0m in the [47m[local][0m definition of [47mF[0m are inherited from the [47m:hints[0m in the [47m[xargs][0m of the [47mdefexec[0m form. We discuss such inheritance below. CAVEAT: Termination is not considered for calls of [47m[mbe][0m under the top-level call. Moreover, the [47m:exec[0m part of an [47m[mbe][0m call under the [47m:logic[0m part of any superior [47mmbe[0m call is completely ignored. General Form: (defexec fn (var1 ... varn) dcl ... dcl ; optionally, also one documentation string, as for defun (mbe :LOGIC logic-body :EXEC exec-body)) where the syntax is identical to the syntax of [47m[defun][0m where the body is a call of [47mmbe[0m, with the exceptions described below. Thus, [47mfn[0m is the symbol you wish to define and is a new symbolic name and [47m(var1 ... varn)[0m is its list of formal parameters (see [name]). The first exception is that at least one [47mdcl[0m (i.e., [47m[declare][0m form) must specify a [47m:guard[0m, [47mguard[0m. The second exception is that one of the [47mdcl[0ms is allowed to contain an element of the form [47m(exec-xargs ...)[0m. The [47mexec-xargs[0m form, if present, must specify a non-empty [47m[keyword-value-listp][0m each of whose keys is one of [47m:test[0m, [47m:default-value[0m, or one of the standard [47m[xargs][0m keys of [47m:measure[0m, [47m:ruler-extenders[0m, [47m:well-founded-relation[0m, [47m:hints[0m [47m:stobjs[0m, or [47m:dfs[0m. Any of these standard [47mxargs[0m keys that is present in an [47mxargs[0m of some [47mdcl[0m but is not specified in the (possibly nonexistent) [47mexec-xargs[0m form is considered to be specified in the [47mexec-xargs[0m form, as illustrated in the example above for [47m:hints[0m. (So for example, if you want [47m:hints[0m in the final, non-local definition but not in the local definition, then specify the [47m:hints[0m in the [47mxargs[0m but specify [47m:hints nil[0m in the [47mexec-xargs[0m.) If [47m:test[0m is specified and not [47mnil[0m, let [47mtest[0m be its value; otherwise let [47mtest[0m default to [47mguard[0m. If [47m:default-value[0m is specified, let [47mdefault-value[0m be its value; else [47mdefault-value[0m is [47mnil[0m. [47mDefault-value[0m should have the same [signature] as [47mexec-body[0m; otherwise the [47mdefexec[0m form will fail to be admitted. The above General Form's macroexpansion is of the form [47m(PROGN encap final-def)[0m, where [47mencap[0m and [47mfinal-def[0m are as follows. [47mFinal-def[0m is simply the result of removing the [47mexec-xargs[0m declaration (if any) from its [47m[declare][0m form, and is the result of evaluating the given [47mdefexec[0m form, since [47mencap[0m is of the following form. ; encap (ENCAPSULATE () (set-ignore-ok t) ; harmless for proving termination (set-irrelevant-formals-ok t) ; harmless for proving termination (local local-def) (local local-thm)) The purpose of [47mencap[0m is to ensure that the executable version of [47mname[0m terminates on all arguments. Thus, [47mlocal-def[0m and [47mlocal-thm[0m are as follows, where the [47mxargs[0m of the [47m[declare][0m form are the result of adding [47m:VERIFY-GUARDS NIL[0m to the result of removing the [47m:test[0m and (optional) [47m:default-value[0m from the [47mexec-xargs[0m. ; local-def (DEFUN fn formals (DECLARE (XARGS :VERIFY-GUARDS NIL ...)) (IF test exec-body default-value)) ; local-thm (DEFTHM fn-EXEC-GUARD-HOLDS (IMPLIES guard test) :RULE-CLASSES NIL) We claim that if the above [47mlocal-def[0m and [47mlocal-thm[0m are admitted, then all evaluations of calls of [47mfn[0m terminate. The concern is that the use of [47m[mbe][0m in [47mfinal-def[0m allows for the use of [47mexec-body[0m for a call of [47mfn[0m, as well as for subsequent recursive calls, when [47mguard[0m holds and assuming that the guards have been verified for [47mfinal-def[0m. However, by [47mlocal-thm[0m we can conclude in this case that [47mtest[0m holds, in which case the call of [47mfn[0m may be viewed as a call of the version of [47mfn[0m defined in [47mlocal-def[0m. Moreover, since guards have been verified for [47mfinal-def[0m, then guards hold for subsequent evaluation of [47mexec-body[0m, and in particular for recursive calls of [47mfn[0m, which can thus continue to be viewed as calls using [47mlocal=def[0m.") (definductor (loop$-recursion) "Create an induction scheme for a [47mloop$[0m-recursive function [47mDefinductor[0m is a utility provided as part of the community book [47mprojects/apply/top[0m, which should be included in any session dealing with [47m[apply$][0m, [47m[loop$][0m, or [47m[loop$-recursion][0m. [47m(Definductor fn)[0m attempts to create an induction scheme appropriate for the previously defined [47mloop$[0m-recursive function [47mfn[0m and prove an [47m:[0m[47m[induction][0m rule so that certain calls of [47mfn[0m suggest that induction. [31;1mWarning:[0m [47mDefinductor[0m currently handles a very small class of [47mloop$[0m-recursive functions and may produce unhelpful error messages when given a function name outside of that class! We hope to improve it and this documentation as we all get more experience with [47mloop$[0ms and [47mloop$[0m-recursion. Examples: (definductor copy-nat-tree) (definductor copy-nat-tree :measure (my-measure x) :hints (("Goal" :use ...))) General Form: (definductor name &key measure well-founded-relation ruler-extenders hints) where [47mname[0m is the name of a previously admitted [47mloop$[0m-recursive function satisfying the restrictions listed below. When successful it defines a function named [47mname-INDUCTOR[0m that suggests an induction scheme that is supposedly appropriate for [47mname[0m, admits it with a silent proof of its measure theorems, and then proves an [47m:[0m[47minduction[0m rule to associate that scheme with calls of [47mname[0m. When omitted, the optional keyword arguments [47mmeasure[0m, [47mwell-founded-relation[0m, and [47mruler-extenders[0m default to the measure, well-founded relation, and ruler-extender settings used in the admittance of [47mname[0m. The keyword argument [47mhints[0m defaults to [47mnil[0m. Note that an appropriate choice of [47mruler-extenders[0m can improve some induction schemes. See [induction-coarse-v-fine-grained]. Restrictions The given function, [47mname[0m, must satisfy the following restrictions. [31;1mNote:[0m Because we anticipate this utility being further developed in the near future this list may not correspond to the latest implementation! * [47mName[0m must be a symbol naming a previously admitted [47mloop$[0m-recursive function. * Every recursive [47mloop$[0m in the body of [47mname[0m -- that is, every [47mloop$[0m that calls [47mname[0m recursively in the [47mwhen[0m, [47muntil[0m, or [47mbody[0m clauses of the [47mloop$[0m -- must have as its target(s) distinct measured variables or [47mcdr[0m-nests around such variables. * Every recursive [47mloop$[0m must use [47mIN[0m-iteration, not [47mON[0m- or [47mFROM/TO/BY[0m-iteration. While [47mdefinductor[0m can handle [47mloop$[0m containing multiple [47mAS[0m clauses (with targets as described above), it cannot handle [47mloop$[0m such as (loop$ for v in (target x) ...) (loop$ for v on x ...) (loop$ for i from 1 to max ...) To see the inductor function generated, type [47m:pe name-INDUCTOR[0m. To see examples of the use of [47mdefinductor[0m inspect the book [47mprojects/apply/definductor-tests.lisp[0m. To see the definition of [47mdefinductor[0m, see [47mprojects/apply/definductor.lisp[0m. Suggestions for improvements are welcome! We know of many, including allowing the user to specify a different name for the inductor function, improving the error messages, printing out the generated [47mdefun[0m in the event of failure to admit it, and trying to expand the class of [47mloop$[0m-recursive functions that can be successfully handled. We have not yet even looked at inductions for [47mON[0m [47mloop$[0ms and [47mFROM/TO/BY[0m [47mloop$[0ms, so that might be easy. Induction for [47mloop$[0ms over arbitrary target expressions may be infeasible! We just need more examples of [47mloop$[0m-recursive functions and successful (hand-written) induction hints for them.") (define-pc-help (proof-builder) "Define a macro command whose purpose is to print something Example: (define-pc-help pp () (if (goals t) (io? proof-builder nil state (state-stack) (fms0 "~|~y0~|" (list (cons #0 (fetch-term (conc t) (current-addr t)))))) (print-all-goals-proved-message state))) General Form: (define-pc-help name args &rest body) This defines a macro command named [47mname[0m, as explained further below. The [47mbody[0m should (after removing optional declarations) be a form that returns [47mstate[0m as its single value. Typically, it will just print something. What [47m(define-pc-help name args &rest body)[0m really does is to create a call of [47mdefine-pc-macro[0m that defines [47mname[0m to take arguments [47margs[0m, to have the declarations indicated by all but the last form in [47mbody[0m, and to have a body that (via [47mpprogn[0m) first executes the form in the last element of body and then returns a call to the command [47mskip[0m (which will return [47m(mv nil t state)[0m).") (define-pc-macro (proof-builder) "Define a proof-builder macro command A call of [47mdefine-pc-macro[0m defines a sort of macro, which is a tactic that generates [proof-builder] instructions. This topic contains basic information about how to use this utility. For somewhat sophisticated, but commented, examples, see the [community-book] [47mbooks/kestrel/utilities/proof-builder-macros.lisp[0m and associated tests in the same directory, [47mproof-builder-macros-tests.lisp[0m. We begin with the following example. (define-pc-macro ib (&optional term) (value (if term `(then (induct ,term) bash) `(then induct bash)))) The example above captures a common paradigm: one attempts to prove the current goal by inducting and then simplifying the resulting goals. (See [proof-builder-commands] for documentation of the command [47mthen[0m, which is itself a pc-macro command, and commands [47minduct[0m and [47mbash[0m.) Rather than issuing [47m(then induct bash)[0m, or worse yet issuing [47minduct[0m and then issuing [47mbash[0m for each resulting goal, the above definition of [47mib[0m would let you issue [47mib[0m and get the same effect. General Form: (define-pc-macro cmd args dcl ... dcl body) where [47mcmd[0m is the name of the pc-macro that you want to define, [47margs[0m is its list of formal parameters. [47mArgs[0m may include lambda-list keywords [47m&optional[0m and [47m&rest[0m; see [macro-args], but note that here, [47margs[0m may not include [47m&key[0m or [47m&whole[0m. The value of [47mbody[0m should be an [error-triple], of the form [47m(mv erp xxx state)[0m for some [47merp[0m and [47mxxx[0m. If [47merp[0m is [47mnil[0m, then [47mxxx[0m is handed off to the interactive proof-builder's instruction interpreter. Otherwise, evaluation typically halts.") (define-pc-meta (proof-builder) "Define a proof-builder meta command Built-in meta commands of the interactive [proof-builder] include [47mundo[0m and [47mrestore[0m, and others ([47mlisp[0m, [47mexit[0m, and [47msequence[0m); see [proof-builder-commands]. The advanced proof-builder user can define these as well. See ACL2 source file [47mproof-builder-b.lisp[0m for examples, and contact the ACL2 implementors if those examples do not provide sufficient documentation.") (define-trusted-clause-processor (events) "Define a trusted (unverified) goal-level simplifier This [documentation] assumes familiarity with [47m:clause-processor[0m rules; see [clause-processor]. Briefly put, a [3mclause-processor[0m is a user-defined function that takes as input the ACL2 representation of a goal --- a [clause] --- and returns a list of goals (i.e., a list of clauses). A [47m:clause-processor[0m rule is a way to inform ACL2 that a clause-processor has been proved correct and now may be specified in [47m:clause-processor[0m [hints]. Here we describe a utility, [47mdefine-trusted-clause-processor[0m, that provides another way to inform ACL2 that a function is to be considered a clause-processor that can be specified in a [47m:clause-processor[0m hint. You can find examples of correct and incorrect use of this utility in community book [47mbooks/clause-processors/basic-examples[0m. Consider the simple example already presented for [47m:clause-processor[0m rules (again, see [clause-processor]), for a simple clause-processor named [47mnote-fact-clause-processor[0m. Instead of introducing an evaluator and proving a correctness theorem with [47m:rule-classes :clause-processor[0m, we can simply inform ACL2 that we trust the function [47mnote-fact-clause-processor[0m to serve as a clause-processor. (define-trusted-clause-processor note-fact-clause-processor nil :ttag my-ttag) A non-nil [47m:ttag[0m argument generates a [47m[defttag][0m event in order to acknowledge the dependence of the ACL2 session on the (unproved) correctness of this clause-processor. That argument can be omitted if there is currently an active trust tag. Note that the extra [47m[defttag][0m event will be [local] to the [47mdefine-trusted-clause-processor[0m event; that is, its effect will disappear after the [47mdefine-trusted-clause-processor[0m event completes. This point becomes clear if one understands that a call of [47mdefine-trusted-clause-processor[0m expands to a call of [47m[encapsulate][0m, and a [47m[defttag][0m event is essentially [local] within any [47m[encapsulate][0m event, as is any event that sets the [47m[ACL2-defaults-table][0m. See [defttag]. Because we are trusting this clause-processor, rather than having proved it correct, we refer to it as a ``trusted'' clause-processor to contrast with a proved-correct, or ``verified'', clause-processor. Now that the event displayed above has established [47mnote-fact-clause-processor[0m as a (trusted) clause-processor, we can use it in a [47m:clause-processor[0m hint, for example as follows. Notice that the output is identical to that for the corresponding example presented for the verified case (see [clause-processor]), except that the word ``verified'' has been replaced by the word ``trusted''. ACL2 !>(thm (equal (car (cons x y)) x) :hints (("Goal" :clause-processor (note-fact-clause-processor clause '(equal a a))))) [Note: A hint was supplied for the goal above. Thanks!] We now apply the trusted :CLAUSE-PROCESSOR function NOTE-FACT-CLAUSE- PROCESSOR to produce two new subgoals. Subgoal 2 (IMPLIES (EQUAL A A) (EQUAL (CAR (CONS X Y)) X)). But we reduce the conjecture to T, by the :executable-counterpart of IF and the simple :rewrite rule CAR-CONS. Subgoal 1 (EQUAL A A). But we reduce the conjecture to T, by primitive type reasoning. Q.E.D. Summary Form: ( THM ...) Rules: ((:EXECUTABLE-COUNTERPART IF) (:EXECUTABLE-COUNTERPART NOT) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:REWRITE CAR-CONS)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Proof succeeded. ACL2 !> Indeed, if one runs this example first and subsequently verifies the clause-processor, one will see the word ``trusted'' change to ``verified''. The general form is as follows. (define-trusted-clause-processor cl-proc ;;; clause-processor function supporters ;;; see below &key label ;;; optional; cl-proc$label by default ttag ;;; discussed above partial-theory ;;; optional encapsulate event ) We discussed the [47m:ttag[0m argument above, and we will discuss the [47msupporters[0m and [47m:partial-theory[0m arguments later below. Let us turn our attention to the [47mlabel[0m argument and its ramifications for undoing and redundancy. As mentioned above, a successful [47mdefine-trusted-clause-processor[0m event results in an [47m[encapsulate][0m event. If the [47m:label[0m argument is supplied with a non-[47mnil[0m value [47mL[0m, or if [47m:label[0m is omitted and [47mL[0m is the result of adding the suffix [47m"$LABEL"[0m to [47mcl-proc[0m, then the event [47m(deflabel L)[0m will be included under the resulting [47mencapsulate[0m form. Thus, you will be able to undo this [47mdefine-trusted-clause-processor[0m with [47m:[0m[47m[ubt][0m[47m L[0m. Also, because of the criteria for redundant encapsulate events (see [redundant-encapsulate]), the entire form is considered redundant (skipped) if it is identical to one already executed in the current ACL2 [world], with one exception: if [47m:partial-theory[0m is [47mnil[0m or omitted, and also [47m:label nil[0m is supplied explicitly, then the event will not be redundant. If the event is not redundant, then [47mcl-proc[0m must not already be designated as a trusted clause-processor. Note that [47mcl-proc[0m may be defined either in [47m:program[0m-mode or [47m:logic[0m-mode. The [47msupporters[0m argument should be a true list of function symbols in the current ACL2 world. It is important that this list include user-defined functions whose definitions support the correctness of the clause-processor function. Otherwise, [47m[local][0m definitions of those missing supporters can render the use of this clause-processor unsound, as discussed in the paper referenced at the end of the [clause-processor] documentation topic. Below we discuss an additional reason that [47msupporters[0m is critical for soundness, in the case of dependent clause-processors. (Remark. There could have been two notions of supporters: one for functions whose definitions support the correctness of the clause-processor function, and, in the case of dependent clause-processors, one for supporters of the ``promised encapsulate'' discussed below. But for simplicity, a single [47msupporters[0m argument serves both purposes.) [31;1mDependent clause-processors and promised encapsulates[0m: The [47m:partial-theory[0m argument Suppose you want to introduce a clause-processor to reason about a complex hardware simulator that is implemented outside ACL2. Sawada and Reeber had just such a problem, as reported in their FMCAD 2006 paper. Indeed, they used [47m[sys-call][0m to implement a [47m:[0m[47m[program][0m-mode function in ACL2 that can invoke that simulator. (This has been changed to [47m[sys-call*][0m since [47msys-call[0m cannot invoke the OS during proofs; see [sys-call].) In principle one could code the simulator directly in ACL2; but it would be a tremendous amount of work that has no practical purpose, given the interface to the external simulator. So: In what sense can we have a clause-processor that proves properties about a simulator when that simulator is not fully axiomatized in ACL2? Our answer, in a nutshell, is this: The above [47m:partial-theory[0m argument provides a way to write merely some of the [constraint]s on the external tool (or even no constraints at all), with the understanding that such constraints are present implicitly in a stronger ``promised'' [47mencapsulate[0m, for example by exporting the full definition. If a trusted clause-processor is introduced with a non-[47mnil[0m [47m:partial-theory[0m argument, we call it a ``dependent'' clause-processor, because its correctness is dependent on the constraints implicitly introduced by the [47m:partial-theory[0m [47mencapsulate[0m form. The implicit constraints should logically imply the constraints actually introduced by the explicit [47mencapsulate[0m, but they should also be sufficient to justify every possible invocation of the clause-processor in a [47m:clause-processor[0m hint. The user of a [47mdefine-trusted-clause-processor[0m form is making a guarantee --- or, is relying on a guarantee provided by the writer of that form --- that in principle, there exists a so-called ``promised encapsulate'': an [47mencapsulate[0m form with the same [signature] as the [47m:partial-theory[0m [47mencapsulate[0m form associated with the trusted clause-processor, but whose constraints introduced are the aforementioned implicit constraints. There are several additional requirements on a [47m:partial-theory[0m argument. First, it must be an [47m[encapsulate][0m event with non-empty [signature]. Moreover, the functions introduced by that event must be exactly those specified in the signature, and no more. And further still, the [47mdefine-trusted-clause-processor[0m form cannot be executed inside any [47m[encapsulate][0m form with non-empty [signature]; we can think of this situation as attempting to associate more than one [47mencapsulate[0m with the functions introduced in the inner [47mencapsulate[0m. Moreover, soundness depends on inclusion of enough function symbols in the [47msupporters[0m argument, as follows. Let [47mS[0m be the set of specified [47msupporters[0m augmented by the set of function symbols either introduced by, or in a property exported by, the [47m:partial-theory[0m argument, which we call the ``promised encapsulate''. Then every function symbol constrained by the promised encapsulate is in [47mS[0m. The [47m:partial-theory[0m event will (in essence) be executed as part of the evaluation of the [47mdefine-trusted-clause-processor[0m form. Again, a critical obligation rests on the user who provides a [47m:partial-theory[0m: there must exist (in principle at least) a corresponding promised encapsulate form with the same [signature] that could logically be admitted, whenever the above [47mdefine-trusted-clause-processor[0m form is evaluated successfully, that justifies the designation of [47mcl-proc[0m as a clause-processor. See also the paper mentioned above for more about promised encapsulates. A key consequence is that the [constraint]s are unknown for the functions introduced in (the signature of) a [47m:partial-theory[0m [47m[encapsulate][0m form. Thus, functional instantiation (see [functional-instantiation-example]) is disabled for function in the signature of a [47m:partial-theory[0m form. [31;1mA remark on the underlying implementation[0m You can see all of the current trusted clause-processors by issuing the command [47m(table trusted-cl-proc-table)[0m. The resulting alist associates each trusted clause-processor with its supporters. Note that [47mdefine-trusted-clause-processor[0m is actually a macro that generates (among other things) a [47mtable[0m event for extending [47mtrusted-cl-proc-table[0m. You are invited to use [47m:[0m[47m[trans1][0m to see expansions of calls of this macro. In particular, you can see that the [47m:partial-theory[0m argument results in an [47mencapsulate[0m event that includes a call of the form [47m(set-unknown-constraints-supporters f1 ... fk)[0m, which in effect makes that call of [47mencapsulate[0m into a call of [47mpartial-encapsulate[0m with supporters [47m(f1 ... fk)[0m. See [partial-encapsulate]. [31;1mA technique for using raw Lisp to define a trusted clause-processor[0m The following code is intended to give an idea for how one might define the ``guts'' of a trusted clause-processor in raw Lisp. The idea is to stub out functions, such as [47macl2-my-prove below[0m, that you want to define in raw Lisp; and then, load a raw Lisp file to overwrite any such function with the real code. But then we make any such overwritten function untouchable. (This last step is important because otherwise, one can prove [47mnil[0m using a [47m:functional-instance[0m [47m:use[0m hint, by exploiting the fact that this function has executable code for which there is no corresponding definitional axiom.) Note: The point here is only to illustrate the use of raw Lisp, so we do not bother to define or explain functions [47mhint-to-termlist[0m or [47mdisjoin-clause-segments-to-clause[0m, which this example assumes are defined elsewhere; their meanings are not important for this example. (defstub acl2-my-prove (term hint) t) (program) (defttag :my-cl-proc) (progn ; We wrap everything here in a single progn, so that the entire form is ; atomic. That's important because we want the use of push-untouchable to ; prevent anything besides my-clause-processor from calling acl2-my-prove. (progn! (set-raw-mode-on state) (load "my-hint-raw.lsp") ; defines my-prove in raw Lisp (defun acl2-my-prove (term hint) (my-prove term hint))) (defun my-clause-processor (cl hint) (declare (xargs :guard (pseudo-term-listp cl) :mode :program)) (if (acl2-my-prove (disjoin cl) hint) (disjoin-clause-segments-to-clause (pairlis$ (hint-to-termlist hint) nil) cl) (prog2$ (cw "~|~%NOTE: Unable to prove goal with ~ my-clause-processor and indicated hint.~|") (list cl)))) (push-untouchable acl2-my-prove t) )") (defined-constant (pointers) "See [system-utilities].") (definition (rule-classes) "Make a rule that acts like a function definition See [rule-classes] for a general discussion of rule classes and how they are used to build rules from formulas. An example [47m:[0m[47m[corollary][0m formula from which a [47m:definition[0m rule might be built is: Examples: (defthm open-len-twice (implies (true-listp x) (equal (len x) (if (null x) 0 (if (null (cdr x)) 1 (+ 2 (len (cddr x))))))) :rule-classes :definition) ; Same as above, with :controller-alist made explicit: (defthm open-len-twice (implies (true-listp x) (equal (len x) (if (null x) 0 (if (null (cdr x)) 1 (+ 2 (len (cddr x))))))) :rule-classes ((:definition :controller-alist ((len t))))) General Form: (implies hyp (equiv (fn a1 ... an) body)) where [47mequiv[0m is an equivalence relation and [47mfn[0m is a function symbol other than [47m[if][0m, [47m[hide][0m, [47m[force][0m or [47m[case-split][0m. Such rules allow ``alternative'' definitions of [47mfn[0m to be proved as theorems but used as definitions. These rules are not true ``definitions'' in the sense that they (a) cannot introduce new function symbols and (b) do not have to be terminating recursion schemes. They are just conditional rewrite rules that are controlled the same way we control recursive definitions. We call these ``definition rules'' or ``generalized definitions''. Consider the general form above. Generalized definitions are stored much as [47m:[0m[47m[rewrite][0m rules for the function ``defined,'' [47mfn[0m above, but the procedure for applying them is a little different. During rewriting, instances of [47m(fn a1 ... an)[0m are replaced by corresponding instances of [47mbody[0m provided the [47mhyp[0ms can be established, as for a [47m:[0m[47m[rewrite][0m rule; but when applying a [47m:definition[0m rule, the result of rewriting [47mbody[0m must also satisfy the criteria for function expansion. There are two primary criteria, either of which permits expansion. The first is that the ``recursive'' calls of [47mfn[0m in the rewritten body have arguments that already occur in the goal conjecture. The second is that the ``controlling'' arguments to [47mfn[0m are simpler in the rewritten body. The notions of ``recursive call'' and ``controllers'' are complicated by the provisions for mutually recursive definitions. Consider a ``clique'' of mutually recursive definitions. Then a ``recursive call'' is a call to any function defined in the clique and an argument is a ``controller'' if it is involved in the measure that decreases in all recursive calls. These notions are precisely defined by the definitional principle and do not necessarily make sense in the context of generalized definitional equations as implemented here. But because the heuristics governing the use of generalized definitions require these notions, it is generally up to the user to specify which calls in body are to be considered recursive and what the controlling arguments are. This information is specified in the [47m:clique[0m and [47m:controller-alist[0m fields of the [47m:definition[0m rule class. The [47m:clique[0m field is the list of function symbols to be considered recursive calls of [47mfn[0m. In the case of a non-recursive definition, the [47m:clique[0m field is empty; in a singly recursive definition, it should consist of the singleton list containing [47mfn[0m; otherwise it should be a list of all of the functions in the mutually recursive clique with this definition of [47mfn[0m. If the [47m:clique[0m field is not provided it defaults to [47mnil[0m if [47mfn[0m does not occur as a function symbol in [47mbody[0m and it defaults to the singleton list containing [47mfn[0m otherwise. Thus, [47m:clique[0m must be supplied by the user only when the generalized definition rule is to be treated as one of several in a mutually recursive clique. The [47m:controller-alist[0m is an alist that maps each function symbol in the [47m:clique[0m to a mask specifying which arguments are considered controllers. The mask for a given member of the clique, [47mfn[0m, must be a list of [47mt[0m's and [47mnil[0m's of length equal to the arity of [47mfn[0m. A [47mt[0m should be in each argument position that is considered a ``controller'' of the recursion. For a function admitted under the principle of definition, an argument controls the recursion if it is one of the arguments measured in the termination argument for the function. But in generalized definition rules, the user is free to designate any subset of the arguments as controllers. Failure to choose wisely may result in the ``infinite expansion'' of definitional rules but cannot render ACL2 unsound since the rule being misused is a theorem. If the [47m:controller-alist[0m is omitted it can sometimes be defaulted automatically by the system. If the [47m:clique[0m is [47mnil[0m, the [47m:controller-alist[0m defaults to [47mnil[0m. If the [47m:clique[0m is a singleton containing [47mfn[0m, the [47m:controller-alist[0m defaults to the controller alist computed by [47m(defun fn args body)[0m. (The user can obtain some control over this analysis by setting the default ruler-extenders; see [rulers].) If the [47m:clique[0m contains more than one function, the user must supply the [47m:controller-alist[0m specifying the controllers for each function in the clique. This is necessary since the system cannot determine and thus cannot analyze the other definitional equations to be included in the clique. For example, suppose [47mfn1[0m and [47mfn2[0m have been defined one way and it is desired to make ``alternative'' mutually recursive definitions available to the rewriter. Then one would prove two theorems and store each as a [47m:definition[0m rule. These two theorems would exhibit equations ``defining'' [47mfn1[0m and [47mfn2[0m in terms of each other. No provision is here made for exhibiting these two equations as a system of equations. One is proved and then the other. It just so happens that the user intends them to be treated as mutually recursive definitions. To achieve this end, both [47m:definition[0m rules should specify the [47m:clique[0m [47m(fn1 fn2)[0m and should specify a suitable [47m:controller-alist[0m. If, for example, the new definition of [47mfn1[0m is controlled by its first argument and the new definition of [47mfn2[0m is controlled by its second and third (and they each take three arguments) then a suitable [47m:controller-alist[0m would be [47m((fn1 t nil nil) (fn2 nil t t))[0m. The order of the pairs in the alist is unimportant, but there must be a pair for each function in the clique. Inappropriate heuristic advice via [47m:clique[0m and [47m:controller-alist[0m can cause ``infinite expansion'' of generalized definitions, but cannot render ACL2 unsound. Note that the actual definition of [47mfn1[0m has the runic name [47m(:definition fn1)[0m. The runic name of the alternative definition is [47m(:definition lemma)[0m, where [47mlemma[0m is the name given to the event that created the generalized [47m:definition[0m rule. This allows theories to switch between various ``definitions'' of the functions. By default, a [47m:definition[0m rule establishes the so-called ``body'' of a function. The body is used by [47m:expand[0m [hints], and it is also used heuristically by the theorem prover's preprocessing (the initial simplification using ``simple'' rules that is controlled by the [47mpreprocess[0m symbol in [47m:do-not[0m [hints]), induction analysis, and the determination for when to warn about non-recursive functions in rules. The body is also used by some heuristics involving whether a function is recursively defined, and by the [47mexpand[0m, [47mx[0m, and [47mx-dumb[0m commands of the interactive [proof-builder]. See [rule-classes] for a discussion of the optional field [47m:install-body[0m of [47m:definition[0m rules, which controls whether a [47m:definition[0m rule is used as described in the paragraph above. Note that even if [47m:install-body nil[0m is supplied, the rewriter will still rewrite with the [47m:definition[0m rule; in that case, ACL2 just won't install a new body for the top function symbol of the left-hand side of the rule, which for example affects the application of [47m:expand[0m hints as described in the preceding paragraph. Also see [set-body] and see [show-bodies] for how to change the body of a function symbol. Note only that if you prove a definition rule for function [47mfoo[0m, say, [47mfoo-new-def[0m, you will need to refer to that definition as [47mfoo-new-def[0m or as [47m(:DEFINITION foo-new-def)[0m. That is because a [47m:definition[0m rule does not change the meaning of the symbol [47mfoo[0m for [47m:use[0m [hints], nor does it change the meaning of the symbol [47mfoo[0m in theory expressions; see [theories], in particular the discussion there of runic designators. Similarly [47m:[0m[47m[pe][0m [47mfoo[0m and [47m:[0m[47m[pf][0m [47mfoo[0m will still show the original definition of [47mfoo[0m. The definitional principle, [47m[defun][0m, actually adds [47m:definition[0m rules. Thus the handling of generalized definitions is exactly the same as for ``real'' definitions because no distinction is made in the implementation. Suppose [47m(fn x y)[0m is [47m[defun][0m'd to be [47mbody[0m. Note that [47m[defun][0m (or [47m[defuns][0m or [47m[mutual-recursion][0m) can compute the clique for [47mfn[0m from the syntactic presentation and it can compute the controllers from the termination analysis. Provided the definition is admissible, [47m[defun][0m adds the [47m:definition[0m rule [47m(equal (fn x y) body)[0m. Subtopics [Bind-free] To bind free variables of a rewrite, definition, or linear rule [Case-split] Like force but immediately splits the top-level goal on the hypothesis [Force] Identity function used to force a hypothesis [Set-body] Set the definition body [Show-bodies] Show the potential definition bodies [Simple] [47m:[0m[47m[definition][0m and [47m:[0m[47m[rewrite][0m rules used in preprocessing [Syntaxp] Attach a heuristic filter on a rule") (deflabel (events) "Build a landmark Examples: (deflabel interp-section) General Form: (deflabel name) where [47mname[0m is a new symbolic name (see [name]). By virtue of the fact that [47mdeflabel[0m is an event, it marks the current [history] with the [47mname[0m. For example, you may wish to undo back through some label or compute a theory expression (see [theories]) in terms of some labels. [47mDeflabel[0m [events] are never considered redundant. See [redundant-events].") (deflock (parallel-programming) "Define a wrapper macro that provides mutual exclusion in ACL2(p) This [documentation] topic relates to the experimental extension of ACL2 supporting parallel evaluation and proof; see [parallelism]. Example Form: (deflock *my-lock*) General Form: (deflock *symbol*) where [47m*symbol*[0m is a symbol whose first and last characters are both the character [47m#\*[0m. A call of this macro generates a definition of another macro, named [47mwith-<modified-lock-symbol>[0m, where [47m<modified-lock-symbol>[0m is the given symbol with the leading and trailing [47m*[0m characters removed. This newly defined macro will guarantee mutually exclusive execution when called in the body of the raw Lisp definition of a function, as is typically the case for [guard]-verified functions, for [47m:[0m[47m[program][0m mode functions, and for calls of macro [47m[top-level][0m. (See [guard-evaluation-table] for details of how raw Lisp code might not be invoked when guard-checking (see [set-guard-checking]) has value [47m:none[0m or [47m:all[0m.) Note that this macro is also simply the identity when invoked directly in the top-level loop; see [top-level] for a way to avoid this issue, and see [parallelism-at-the-top-level] for a general discussion of this issue for calls of [parallelism] primitives. To see how mutual exclusion is guaranteed, consider the raw Lisp code generated for the macro, [47mwith-<modified-lock-symbol>[0m, that is introduced by a call of [47mdeflock[0m. This code uses a lock (with the given [47m*symbol*[0m as its name), which guarantees that for any two forms that are each in the scope of a call of [47mwith-<modified-lock-symbol>[0m, the forms do not execute concurrently. Note that a call of [47mdeflock[0m expands into the application of [47mprogn[0m to two events, as illustrated below. ACL2 !>:trans1 (deflock *my-cw-lock*) (PROGN (TABLE LOCK-TABLE '*MY-CW-LOCK* T) (DEFMACRO WITH-MY-CW-LOCK (&REST ARGS) (LIST* 'WITH-LOCK '*MY-CW-LOCK* ARGS))) ACL2 !> Thus, [47mdeflock[0m forms are legal embedded event forms (see [embedded-event-form]) for [books] as well as [47m[encapsulate][0m and [47m[progn][0m [events]. The following log shows a lock in action. Recall that locks work as expected in [guard]-verified and [47m:[0m[47m[program][0m mode functions; they do not, however, work in [47m:[0m[47m[logic][0m mode functions that have not been guard-verified, as illustrated below. ACL2 !>(deflock *my-cw-lock*) [[.. output omitted ..]] WITH-MY-CW-LOCK ACL2 !>(defun foo (n) (declare (xargs :guard (natp n) :verify-guards nil)) (plet ((x1 (with-my-cw-lock (cw "~x0" (make-list n)))) (x2 (with-my-cw-lock (cw "~x0" (make-list n))))) (and (null x1) (null x2)))) [[.. output omitted ..]] FOO ACL2 !>(foo 20) (NIL NIL NIL NIL( NIL NIL NIL NIL NIL NILNIL NIL NILNIL NIL NILNIL NIL NILNIL NIL NIL NILNIL NIL NIL NIL NILNIL NIL NILNIL ) NIL NIL NIL NIL NIL NIL NIL NIL) T ACL2 !>(verify-guards foo) [[.. output omitted ..]] FOO ACL2 !>(foo 20) (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL) (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL) T ACL2 !>") (defmacro (macros events programming) "Define a macro Example Defmacros: (defmacro xor (x y) (list 'if x (list 'not y) y)) (defmacro git (sym key) (list 'getprop sym key nil '(quote current-acl2-world) '(w state))) (defmacro one-of (x &rest rst) (declare (xargs :guard (symbol-listp rst))) (cond ((null rst) nil) (t (list 'or (list 'eq x (list 'quote (car rst))) (list* 'one-of x (cdr rst)))))) Example Expansions: term macroexpansion (xor a b) (if a (not b) b) (xor a (foo b)) (if a (not (foo b)) (foo b)) (git 'car 'lemmas) (getprop 'car 'lemmas nil 'current-acl2-world (w state)) (one-of x a b c) (or (eq x 'a) (or (eq x 'b) (or (eq x 'c) nil))) (one-of x 1 2 3) ill-formed (guard violation) General Form: (defmacro name macro-args dcl ... dcl ; optionally, also one documentation string; see below body) where [47mname[0m is a new symbolic name (see [name]), [47mmacro-args[0m specifies the formal parameters of the macro, and [47mbody[0m is a term whose only free variables are the [47mmacro-args[0m. The formal parameters can be specified in a much more general way than is allowed by ACL2 [47m[defun][0m [events]; see [macro-args] for a description of keyword ([47m&key[0m) and optional ([47m&optional[0m) parameters as well as other so-called ``lambda-list keywords'', [47m&rest[0m and [47m&whole[0m. Each [47mdcl[0m is an optional declaration (see [declare]) except that the only [47m[xargs][0m keyword permitted by [47mdefmacro[0m is [47m:[0m[47m[guard][0m. One documentation string may be included between the list of formal parameters and the body, but it is essentially ignored by ACL2. See [documentation] for a discussion of documentation in ACL2. There are two restrictions on [47mbody[0m aside from it simply being a term in [47mmacro-args[0m. Both restrictions relate to ancestral uses of [47m[apply$][0m in [47mbody[0m, i.e., uses of [47mapply$[0m by [47mbody[0m or any function that might be called during the evaluation of [47mbody[0m. First, only badged primitive functions may be applied. See [badge] for a way to obtain the complete list of badged primitives. Second, [47mloop$[0m and [47mlambda$[0m may not be used anywhere in the ancestry of [47mbody[0m. See [47mignored-attachment[0m and [47mprohibition-of-loop$-and-lambda$[0m for more discussion. Note: It is permitted for the value of body to mention [47mapply$[0m, [47mloop$[0m, and [47mlambda$[0m. For compute-intensive applications, see [defmac], which can speed up macroexpansion by introducing an auxiliary [47mdefun[0m. For a variant of [47mdefmacro[0m that automatically quotes arguments by default, but provides a way for calls to evaluate specified arguments, see [defmacroq]. Macroexpansion occurs when a form is read in, i.e., before the evaluation or proof of that form is undertaken. To experiment with macroexpansion, see [trans]. When a form whose [47m[car][0m is [47mname[0m arises as the form is read in, the arguments are bound as described in CLTL pp. 60 and 145, the [guard] is checked, and then the [47mbody[0m is evaluated. The result is used in place of the original form. In ACL2, macros do not have access to the ACL2 state, [47m[state][0m. (If [47m[state][0m or any user-defined stobj (see [stobj]) is a macro argument, it is treated as an ordinary variable, bound at macro-expansion time to a piece of syntax.) This is in part a reflection of CLTL, p. 143, ``More generally, an implementation of Common Lisp has great latitude in deciding exactly when to expand macro calls with a program. ... Macros should be written in such a way as to depend as little as possible on the execution environment to produce a correct expansion.'' In ACL2, the product of macroexpansion is independent of the current environment and is determined entirely by the macro body and the functions and constants it references. It is possible, however, to define macros that produce expansions that refer to [47m[state][0m or other single-threaded objects (see [stobj]) or variables not among the macro's arguments. See the [47mgit[0m example above. For a related utility that does have access to the ACL2 [state], see [make-event]. Subtopics [Defmacro-untouchable] Define an ``untouchable'' macro [Ignored-attachment] Why attachments are sometimes not used [Prohibition-of-loop$-and-lambda$] Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms") (defmacro-last (events) "Define a macro that returns its last argument, but with side effects This is an advanced feature that requires a trust tag. For explanation, including an example, see [return-last].") (defmacro-untouchable (macros events programming defmacro) "Define an ``untouchable'' macro Strictly speaking, macros cannot be untouchable the way functions are untouchable; see [push-untouchable]. However, one can define a macro that is, in effect, untouchable, by using [47mdefmacro-untouchable[0m to introduce a trivial untouchable function into the definition. Consider for example the following definition. (defmacro-untouchable mac (x) (list 'consp x)) Let's look at the single-step macroexpansion of a call of the newly-defined macro, [47mmac[0m. ACL2 !>:trans1 (mac (f a)) (PROG2$ (UNTOUCHABLE-MARKER 'MAC) (CONSP (F A))) ACL2 !> We see that this expansion is just as if we had used [47m[defmacro][0m instead of [47mdefmacro-untouchable[0m, except that a [47m[prog2$][0m wrapper lays down a call of [47muntouchable-marker[0m, which is a built-in untouchable function. In effect, that call makes the macro, [47mmac[0m, untouchable. Of course, you are welcome to write your own variant of [47mdefmacro-untouchable[0m, introducing your own untouchable function. The result would presumably be roughly equivalent to using [47mdefmacro-untouchable[0m; but using [47mdefmacro-untouchable[0m has two advantages. One advantage is that calls of a macro introduced with [47mdefmacro-untouchable[0m should have no Lisp execution overhead caused by the use of [47m[prog2$][0m or [47muntouchable-marker[0m, because of special handling provided by ACL2 for such calls of [47mprog2$[0m as well as inlining of [47muntouchable-marker[0m. The other advantage is that an attempt to use the resulting macro without an active trust tag will generally give a more helpful error message, mentioning the prior use of [47mdefmacro-untouchable[0m as the source of the error.") (defn (defun events) "Definition with [guard] [47mt[0m [47mDefn[0m is [47m[defun][0m with [guard] [47mt[0m. [47mdefn[0m expands to a [47m[defun][0m with an added [47m(declare (xargs :guard t))[0m. If an explicit guard is supplied to [47mdefn[0m, it is conjoined to the added [47mt[0m guard, according to [47m[defun][0m's treatment of multiple guard declarations.") (defnd (defun events) "[disable]d definition with [guard] [47mt[0m [47mDefnd[0m is [47m[defund][0m with [guard] [47mt[0m. [47mdefnd[0m expands to a [47m[defund][0m with an added [47m(declare (xargs :guard t))[0m. If an explicit guard is supplied to [47mdefnd[0m, it is conjoined to the added [47mt[0m guard, according to [47m[defun][0m's treatment of multiple guard declarations.") (defpkg (events packages programming) "Define a new symbol package Example: (defpkg "MY-PKG" (union-eq *acl2-exports* *common-lisp-symbols-from-main-lisp-package*)) General Form: (defpkg "name" term doc-string) where [47m"name"[0m is a non-empty string, none of whose characters is lower case, that names the package to be created; [47mterm[0m is a variable-free expression that evaluates to a list of symbols, where no two distinct symbols in the list may have the same [47m[symbol-name][0m, to be imported into the newly created package; and [47mdoc-string[0m, if non-[47mnil[0m, is an optional string that can provide documentation but is essentially ignored by ACL2. The name of the new package must be ``new'': the host lisp must not contain any package of that name. There are two exceptions to this newness rule, discussed at the end of this documentation. (There is actually an additional argument, book-path, that is used for error reporting but has no logical content. Users should generally ignore this argument, as well as the rest of this sentence: a book-path will be specified for [47m[defpkg][0m events added by ACL2 to the [portcullis] of a book's [certificate]; see [hidden-death-package].) There are two restrictions on [47mterm[0m aside from those mentioned above. Both restrictions relate to ancestral uses of [47m[apply$][0m in [47mterm[0m, i.e., uses of [47mapply$[0m by [47mterm[0m or any function that might be called during the evaluation of [47mterm[0m. First, only badged primitive functions may be applied. See [badge] for a way to obtain the complete list of badged primitives. Second, [47mloop$[0m and [47mlambda$[0m may not be used anywhere in the ancestry of term. See [47mignored-attachment[0m and [47mprohibition-of-loop$-and-lambda$[0m for more discussion. [47mDefpkg[0m forms can be entered at the top-level of the ACL2 [command] loop. They should not occur in [books] (see [certify-book]). After a successful [47mdefpkg[0m it is possible to ``intern'' a string into the package using [47m[intern-in-package-of-symbol][0m. The result is a symbol that is in the indicated package, provided the imports allow it. For example, suppose [47m'my-pkg::abc[0m is a symbol whose [47m[symbol-package-name][0m is [47m"MY-PKG"[0m. Suppose further that the imports specified in the [47mdefpkg[0m for [47m"MY-PKG"[0m do not include a symbol whose [47m[symbol-name][0m is [47m"XYZ"[0m. Then (intern-in-package-of-symbol "XYZ" 'my-pkg::abc) returns a symbol whose [47m[symbol-name][0m is [47m"XYZ"[0m and whose [47m[symbol-package-name][0m is [47m"MY-PKG"[0m. On the other hand, if the imports to the [47mdefpkg[0m does include a symbol with the name [47m"XYZ"[0m, say in the package [47m"LISP"[0m, then (intern-in-package-of-symbol "XYZ" 'my-pkg::abc) returns that symbol (which is uniquely determined by the restriction on the imports list above). See [intern-in-package-of-symbol]. Upon admission of a [47mdefpkg[0m event, the function [47mpkg-imports[0m is extended to compute a list of all symbols imported into the given package, without duplicates. If [47m"MY-PKG"[0m is the name of the new package and [47msymb[0m is the symbol returned by [47m(intern (concatenate 'string "MY-PKG" "-PACKAGE") "ACL2")[0m, then [47msymb[0m denotes the [rewrite] rule added for the package. For example, here is a display of that rule for the event [47m(defpkg "MY-PKG" '(a b))[0m. ACL2 !>:pl (pkg-imports "MY-PKG") (:REWRITE MY-PKG-PACKAGE) New term: '(A B) Hypotheses: <none> Equiv: EQUAL Substitution: NIL .... [47mDefpkg[0m is the only means by which an ACL2 user can create a new package or specify what it imports. That is, ACL2 does not support the Common Lisp functions [47mmake-package[0m or [47mimport[0m. Currently, ACL2 does not support exporting at all. The Common Lisp function [47m[intern][0m is weakly supported by ACL2; see [intern]. A more general form of that function is also provided: see [intern$]. We now explain the two exceptions to the newness rule for package names. The careful experimenter will note that if a package is created with a [47mdefpkg[0m that is subsequently undone, the host lisp system will contain the created package even after the undo. Because ACL2 hangs onto [world]s after they have been undone, e.g., to implement [47m:[0m[47m[oops][0m but, more importantly, to implement error recovery, we cannot actually destroy a package upon undoing it. Thus, the first exception to the newness rule is that [47mname[0m is allowed to be the name of an existing package if that package was created by an undone [47mdefpkg[0m and the newly proposed set of imports is identical to the old one. See [package-reincarnation-import-restrictions]. This exception does not violate the spirit of the newness rule, since one is disinclined to believe in the existence of undone packages. The second exception is that [47mname[0m is allowed to be the name of an existing package if the package was created by a [47mdefpkg[0m with identical set of imports. That is, it is permissible to execute ``redundant'' [47mdefpkg[0m [command]s. The redundancy test is based on the values of the two import forms (comparing them after sorting and removing duplicates), not on the forms themselves. Note that [47mdefpkg[0m performs evaluation in so-called [safe-mode], which can slow down evaluation significantly but checks [guard]s on [primitive]s. Finally, we explain why we require the package name not to contain lower-case characters. We have seen at least one implementation that handled lower-case package names incorrectly. Since we see no need for lower-case characters in package names, which can lead to confusion anyhow (note for example that [47mfoo::bar[0m is a symbol whose [47m[symbol-package-name][0m is [47m"FOO"[0m, not [47m"foo"[0m), we simply disallow them. NOTE: Also see [managing-ACL2-packages] for contributed documentation on managing ACL2 packages. Subtopics [Hidden-death-package] Handling [47m[defpkg][0m [events] that are [47m[local][0m [Hidden-defpkg] Handling defpkg events that are local [Ignored-attachment] Why attachments are sometimes not used [Prohibition-of-loop$-and-lambda$] Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms") (defproxy (events) "Define a non-executable [47m:[0m[47m[program][0m-mode function for attachment This event is provided for those who want to experiment with [47m[defattach][0m using [47m:[0m[47m[program][0m mode functions, and without proof obligations or constraints on cycles in the extended ancestors graph; see [defattach]. If you merely want to define a stub or a non-executable function, see [defstub] or see [defun-nx], respectively. See community book [47mbooks/misc/defproxy-test.lisp[0m for an extended (but simple) example. Example Forms: (defproxy subr1 (* *) => *) (defproxy add-hash (* * hashtable) => (mv * hashtable)) General Form: (defproxy name args-sig => output-sig) where [47mname[0m is a new function symbol and [47m(name . args-sig) => output-sig)[0m is a signature; see [signature]. The macro [47mdefproxy[0m provides a convenient way to introduce a ``proxy'': a [47m:program[0m mode function that can be given attachments for execution (see [defattach]), assuming that there is an active trust tag (see [defttag]). Thus, a [47mdefproxy[0m call expands to a [47m[defun][0m form with the following [47m[xargs][0m [47m[declare][0m form: [47m:non-executable :program[0m. Note that [47m[verify-termination][0m is not permitted for such a function. However, it is permitted to put the proxy function into [47m:[0m[47m[logic][0m mode by use of an [47m[encapsulate][0m event; indeed, this is the way to ``upgrade'' an attachment so that the normal checks are performed and no trust tag is necessary. In order to take advantage of a [47m[defproxy][0m form, one provides a subsequent [47mdefattach[0m form to attach an executable function to the [47mdefproxy[0m-introduced function. When [47m:skip-checks t[0m is provided in a [47m[defattach][0m form, the usual checks for [47mdefattach[0m [events] are skipped, including proof obligations and the check that the extended ancestor relation has no cycles (see [defattach]). There must be an active trust tag (see [defttag]) in order to use [47m:skip-checks t[0m. In that case the use of [47m:skip-checks t[0m is permitted; but note that its use is in fact required if a [47m:[0m[47m[program][0m mode function is involved, and even if a [47m:[0m[47m[logic][0m mode function is involved that has not been [guard]-verified. The following log shows a simple use of defproxy. ACL2 !>(defproxy foo-stub (*) => *) Summary Form: ( DEFUN FOO-STUB ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) FOO-STUB ACL2 !>(foo-stub '(3 4 5)) ACL2 Error in TOP-LEVEL: ACL2 cannot ev the call of undefined function FOO-STUB on argument list: ((3 4 5)) To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !>(defun foo-impl (x) (declare (xargs :mode :program :guard (or (consp x) (eq x nil)))) (car x)) Summary Form: ( DEFUN FOO-IMPL ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO-IMPL ACL2 !>(defttag t) TTAG NOTE: Adding ttag :T from the top level loop. T ACL2 !>(defattach (foo-stub foo-impl) :skip-checks t) Summary Form: ( DEFATTACH (FOO-STUB FOO-IMPL) ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) :ATTACHMENTS-RECORDED ACL2 !>(foo-stub '(3 4 5)) 3 ACL2 !> One can replace this attachment with one that uses [47m:[0m[47m[logic][0m mode functions and does not skip checks. The idea is to reintroduce the proxy function using an [47m[encapsulate][0m form, which does not require redefinition (see [ld-redefinition-action]) to be enabled, and either to put the attachment into [47m:[0m[47m[logic][0m mode with the [guard] verified, as we do in the example below, or else to attach to a different [guard]-verified [47m:[0m[47m[logic][0m mode function. ACL2 !>(defattach (foo-stub nil) :skip-checks t) ; remove attachment Summary Form: ( DEFATTACH (FOO-STUB NIL) ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) :ATTACHMENTS-RECORDED ACL2 !>(encapsulate ((foo-stub (x) t :guard (true-listp x))) (local (defun foo-stub (x) (cdr x))) (defthm foo-stub-reduces-acl2-count (implies (consp x) (< (acl2-count (foo-stub x)) (acl2-count x))))) [[ ... output omitted here ... ]] The following constraint is associated with the function FOO-STUB: (IMPLIES (CONSP X) (< (ACL2-COUNT (FOO-STUB X)) (ACL2-COUNT X))) Summary Form: ( ENCAPSULATE ((FOO-STUB ...) ...) ...) Rules: NIL Warnings: Non-rec Time: 0.02 seconds (prove: 0.01, print: 0.00, other: 0.01) T ACL2 !>(verify-termination foo-impl) Since FOO-IMPL is non-recursive, its admission is trivial. We could deduce no constraints on the type of FOO-IMPL. Computing the guard conjecture for FOO-IMPL.... The guard conjecture for FOO-IMPL is trivial to prove. FOO-IMPL is compliant with Common Lisp. Summary Form: ( DEFUN FOO-IMPL ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Summary Form: ( MAKE-EVENT (VERIFY-TERMINATION-FN ...)) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) FOO-IMPL ACL2 !>(defttag nil) ; optional NIL ACL2 !>(defattach (foo-stub foo-impl)) The guard proof obligation is (IMPLIES (TRUE-LISTP X) (OR (CONSP X) (EQ X NIL))). But we reduce the conjecture to T, by primitive type reasoning. Q.E.D. This concludes the guard proof. We now prove that the attachment satisfies the required constraint. The goal to prove is (IMPLIES (CONSP X) (< (ACL2-COUNT (FOO-IMPL X)) (ACL2-COUNT X))). [[ ... output omitted here ... ]] Q.E.D. Summary Form: ( DEFATTACH (FOO-STUB FOO-IMPL)) Rules: ((:DEFINITION ACL2-COUNT) (:DEFINITION FOO-IMPL) (:ELIM CAR-CDR-ELIM) (:FAKE-RUNE-FOR-LINEAR NIL) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:REWRITE CAR-CONS) (:REWRITE CDR-CONS) (:TYPE-PRESCRIPTION ACL2-COUNT)) Time: 0.02 seconds (prove: 0.01, print: 0.01, other: 0.00) :ATTACHMENTS-RECORDED ACL2 !> We close with some remarks on the checking of [guard]s in the case that [47m[defattach][0m has been called with keyword argument [47m:skip-checks t[0m. We illustrate with examples, where we assume an attachment pair [47m(f . g)[0m created by an event [47m(defattach ... (f g) ... :skip-checks t ...)[0m. A good model for the treatment of [47m:skip-checks t[0m is dependent on whether [47mf[0m was introduced with [47mdefproxy[0m or with [47m[encapsulate][0m: for [47mdefproxy[0m, the normal guard-related checks are treated as skipped, while for [47m[encapsulate][0m, they are assumed to hold. First suppose that [47mf[0m was introduced using [47mdefproxy[0m, and consider the following example. (defproxy f (*) => *) (defun g (x) (car x)) ; not guard-verified; implicit guard of t is too weak (defttag t) ; trust tag needed for :skip-checks t (defattach (f g) :skip-checks t) If we try to evaluate the form [47m(f 3)[0m in ACL2, then the executable-counterpart of [47mf[0m is invoked (see [evaluation]). It calls the executable-counterpart of [47mg[0m, which calls the executable-counterpart of [47m[car][0m, which in turn checks the [guard] of [47m[car][0m and causes a guard violation error (unless we first turn off guard-checking; see [set-guard-checking]). ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(f 3) 1> (ACL2_*1*_ACL2::F 3) 2> (ACL2_*1*_ACL2::G 3) ACL2 Error in TOP-LEVEL: The guard for the function call (CAR X), which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CAR 3). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !> Little changes if we modify the example above by strengthening the guard of [47mg[0m. (defproxy f (*) => *) (defun g (x) (declare (xargs :guard (consp x))) (car x)) (defttag t) ; trust tag needed for :skip-checks t (defattach (f g) :skip-checks t) The result of evaluating [47m(f 3)[0m is as before, except that this time the guard violation occurs at the time that [47mg[0m is called. ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(f 3) 1> (ACL2_*1*_ACL2::F 3) 2> (ACL2_*1*_ACL2::G 3) ACL2 Error in TOP-LEVEL: The guard for the function call (G X), which is (CONSP X), is violated by the arguments in the call (G 3). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set- guard-checking for information about suppressing this check with (set- guard-checking :none), as recommended for new users. ACL2 !> Now consider a slight variation of the example just above, in which [47mf[0m is introduced using [47m[encapsulate][0m instead of using [47mdefproxy[0m. (encapsulate ( ((f *) => *) ) (local (defun f (x) x))) (defun g (x) (declare (xargs :guard (consp x))) (car x)) (defttag t) ; trust tag needed for :skip-checks t (defattach (f g) :skip-checks t) Since [47mf[0m was introduced by [47m[encapsulate][0m instead of by [47mdefproxy[0m, ACL2 assumes that the usual guard properties hold. In particular, it assumes that (informally speaking) the guard of [47mf[0m implies the guard of [47mg[0m; see [defattach] for details. So in this case, ACL2 proceeds under that assumption even though it's actually false, and the result is a raw Lisp error. ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(f 3) 1> (ACL2_*1*_ACL2::F 3) 2> (G 3) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Attempt to take the car of 3 which is not listp. *********************************************** If you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !> If you replace [47mg[0m by its definition in the first example of this series, i.e. with a guard (implicitly) of [47mt[0m, you will see the same error, this time because the [47m[defattach][0m event assumed that [47mg[0m was guard-verified.") (defrec (events) "Introduce a record structure, like a [47mstruct[0m in C. The [47mdefrec[0m macro is built into ACL2 and is frequently used in the ACL2 sources to define basic kinds of structures. Better Alternatives to Defrec While [47mdefrec[0m may be a reasonable choice for writing [program]-mode code, most users would likely be better served by using one of the many, richer alternatives to [defrec] that are available in various books. See for instance macros such as: * The [std::defaggregate] macro from [std/util], * The [defdata] macro, * The [fty::defprod] macro from the [fty] library, and * The [47mdata-structures/structures[0m book. A major reason to favor these macros over [47mdefrec[0m is that they introduce the constructors and accessors for the structure as proper functions, rather than mere macros. This is very helpful when you are trying to use ACL2 to reason about code that works with structures. For instance, it means that your proof goals will involve terms like [47m(employee->position x)[0m instead of [47m(cdddr x)[0m. Another reason is that [47mdefrec[0m does not support putting constraints on the fields of your structure. For instance, you might want to have an [47memployee[0m structure where the [47mname[0m field is always a string. You can't do this with [47mdefrec[0m, but any of the above macros support it. Some of the above macros also have other useful features, e.g., integration with [b*], support for [xdoc] documentation, and so forth. Usage A typical use of [47mdefrec[0m might look like this: (defrec employee ;; name of the structure (name salary . position) ;; fields of the structure nil) ;; "cheap" flag This will result in the introduction of: * A "weak" recognizer function, [47mweak-employee-p[0m, which recognizes cons structures that have the right shape. We call the recognizer [3mweak[0m because it doesn't impose any constraints on the fields, e.g., there is no requirement that the [47mname[0m of an employee must be a string or that the [47msalary[0m must be a number. * A [make] macro that can be used like this: (make employee :name "Jimmy" :salary 0 :position "Unpaid Intern") * A [change] macro that can be used like this: (let ((jimmy (make-employee :name "Jimmy" ...))) (change employee jimmy :salary 300000 :position "Vice President")) * Suitable [access] macros that can be used like this: (let ((jimmy (make-employee :name "Jimmy" ...))) (access employee jimmy :name)) Subtopics [Access] Accessor macro for [defrec] structures. [Change] Mutator macro for [defrec] structures. [Make] Constructor macro for [defrec] structures.") (defrefinement (events) "Prove that [47mequiv1[0m refines [47mequiv2[0m Example: (defrefinement equiv1 equiv2) is an abbreviation for (defthm equiv1-refines-equiv2 (implies (equiv1 x y) (equiv2 x y)) :rule-classes (:refinement)) See [refinement]. General Form: (defrefinement equiv1 equiv2 :package package :event-name event-name :rule-classes rule-classes :instructions instructions :hints hints :otf-flg otf-flg) where [47mequiv1[0m and [47mequiv2[0m are known [equivalence] relations; [47mpackage[0m, if supplied, is one of [47m:current[0m, [47m:equiv1[0m, [47m:equiv2[0m or [47m:legacy[0m; [47mevent-name[0m, if supplied, is a symbol; and all other arguments are as specified in the documentation for [47m[defthm][0m. The [47mdefrefinement[0m macro expands into a call of [47m[defthm][0m. The name of the [47m[defthm][0m event is [47mequiv1-refines-equiv2[0m, unless an [47m:event-name[0m keyword argument is supplied, in which case [47mevent-name[0m is used as the name. The [47mpackage[0m of symbols generated, such as variables and [47m[defthm][0m names, is determined by the [47mpackage[0m argument: if it is not supplied or its value is [47m:current[0m, then the [47m[current-package][0m is used; if its value is [47m:equiv1[0m or [47m:legacy[0m, then the package of [47m:equiv1[0m is used; if its value is [47m:equiv2[0m, then the package of [47m:equiv2[0m is used. The rule-class [47m:[0m[47m[refinement][0m is added to the [47m[rule-classes][0m specified, if it is not already there. All other arguments to the generated [47m[defthm][0m form are as specified by the other keyword arguments above. The term generated for the [47m[defthm][0m event states that [47mequiv1[0m refines [47mequiv2[0m.") (defstobj (events stobj) "Define a new single-threaded object Note: Novices are advised to avoid [47mdefstobj[0m, perhaps instead using community books [std::defaggregate] or [47mbooks/data-structures/structures.lisp[0m. At the least, consider using [47m([0m[47m[set-verify-guards-eagerness][0m[47m 0)[0m to avoid [guard] verification. On the other hand, after you learn to use [47mdefstobj[0m, see [defabsstobj] for another way to introduce single-threaded objects. Example: (defconst *mem-size* 10) ; for use of *mem-size* just below (defstobj st (reg :type (array (unsigned-byte 31) (8)) :initially 0) (p-c :type (unsigned-byte 31) :initially 555) halt ; = (halt :type t :initially nil) (mem :type (array (unsigned-byte 31) (*mem-size*)) :initially 0 :resizable t) (ht :type (hash-table eq 70 integer) :initially 0)) General Form: (defstobj name (field1 :type type1 :element-type etype1 :initially val1 :resizable b1) ... (fieldk :type typek :element-type etypek :initially valk :resizable bk) :renaming doublets :inline flg :congruent-to old-stobj-name :non-memoizable nm-flg :non-executable ne-flg) where [47mname[0m is a new symbol; each [47mfieldi[0m is a symbol; each [47mtypei[0m is either a type-indicator (a [47m[type-spec][0m or [stobj] name), of the form [47m(ARRAY type-indicator (max))[0m, or of one of the forms [47m(HASH-TABLE test)[0m, [47m(HASH-TABLE test size)[0m, [47m(HASH-TABLE test size type-indicator)[0m, [47m(STOBJ-TABLE)[0m, or [47m(STOBJ-TABLE size)[0m; each [47mvali[0m is an object satisfying [47mtypei[0m; and each [47mbi[0m is [47mt[0m or [47mnil[0m. Pairs [47m:element-type etypei[0m, [47m:initially vali[0m, and [47m:resizable bi[0m may be omitted; more on this below. The [47m:renaming doublets[0m argument is optional and allows the user to override the default function names introduced by this event. The [47m:inline flg[0m Boolean argument is also optional and declares to ACL2 that the generated access and update functions for the stobj should be implemented as macros under the hood (which has the effect of inlining the function calls). The optional [47m:congruent-to old-stobj-name[0m argument specifies an existing stobj with exactly the same structure, and is discussed below. The optional [47m:non-memoizable nm-flg[0m and [47m:non-executable ne-flg[0m Boolean arguments are ignored when [47mnm-flg[0m and [47mne-flg[0m are [47mnil[0m, but otherwise: the former instructs ACL2 to lay down faster code for functions that return the new stobj but disallows [memoization] of any function that takes the new stobj as an argument; and the latter avoids actually creating a global stobj (details follow later below). We describe further restrictions on the [47mfieldi[0m, [47mtypei[0m, [47mvali[0m, and on [47mdoublets[0m below. We recommend that you read about single-threaded objects (stobjs) in ACL2 before proceeding; see [stobj]. The effect of this event is to introduce a new single-threaded object (i.e., a ``[stobj]''), named [47mname[0m, and the associated recognizers, creator, accessors, updaters, constants. For fields of [47mARRAY[0m type, this event also introduces length and resize functions. For fields of [47mHASH-TABLE[0m type, this event also introduces boundp, get?, remove, count, clear, and initialization functions. Fields of [47mSTOBJ-TABLE[0m type introduce those functions as well except for the get? function. The Single-Threaded Object Introduced The [47mdefstobj[0m event effectively introduces a new ``live stobj'' object, named [47mname[0m, which has as its initial logical value a list of [47mk[0m elements, where [47mk[0m is the number of ``field descriptors'' provided. This object has mutable updates: that is, the object is actually modified in place, rather than copied, where for an array or hash-table field the update is made to a corresponding raw Lisp array or hash table (respectively). This is only possible because of syntactic restrictions enforced by ACL2 when programming with stobjs, so that after modifying a stobj, its old versions are no longer accessible. The elements are listed in the same order in which the field descriptors appear. If the [47m:type[0m of a field is [47m(ARRAY type-indicator (max))[0m then [47mmax[0m is a non-negative integer or a symbol introduced by [47m[defconst][0m) whose value is a non-negative integer, and the corresponding element of the stobj is initially of length specified by [47mmax[0m. If the [47m:type[0m of a field is [47m(HASH-TABLE test)[0m or [47m(HASH-TABLE test size)[0m, or [47m(HASH-TABLE test size type-indicator)[0m, then: [47mtest[0m is one of the symbols [47mEQ[0m, [47mEQL[0m, [47mHONS-EQUAL[0m, or [47mEQUAL[0m; [47msize[0m, if supplied as above or in [47m(STOBJ-TABLE size)[0m, is nil (handled the same as when size is omitted) or a natural number; and [47mtype-indicator[0m restrict the values that can be stored, as discussed in the next paragraph. The hash-table test is applied when looking up keys in the associated raw Lisp hash table, where [47m[hons-copy][0m is first applied to the key in the [47mHONS-EQUAL[0m case; and the size is a hint to the host Lisp for the initial size of the associated hash table in raw Lisp. (The size really is used only as a hint. Indeed, at least one host Lisp does not support size 0, so ACL2 simply treats size 0 as size 1; and even size 1 may result in a hash table of considerably larger size.) If the value of [47m:type[0m is of the form [47m(ARRAY type-indicator (max))[0m, [47m(HASH-TABLE test size type-indicator)[0m, or just [47mtype-indicator[0m, then [47mtype-indicator[0m is typically a type-spec; see [type-spec]. However, [47mtype-indicator[0m can also be the name of a stobj that was previously introduced (by [47mdefstobj[0m or [47m[defabsstobj][0m). We ignore this ``nested stobj'' case below; see [nested-stobjs] for a discussion of stobjs within stobjs. A field with a [47mSTOBJ-TABLE[0m type is logically an association list whose keys are [stobj] names. ACL2 maintains the execution invariant that each key is mapped to a stobj satisfying that key's recognizer. We say little more here about stobj-tables; see [stobj-table] for relevant discussion. Below, we refer to [3mscalar types[0m as stobj field types that are neither array types, hash-table types, nor stobj-table types. Now consider the keyword value [47m:initially val[0m for a stobj field. If the stobj field is of scalar type, then [47mval[0m is the initial value of the field. For an array type [47m(ARRAY type-indicator (max))[0m, [47mval[0m is the initial value of the elements in the corresponding array. For a [47mHASH-TABLE[0m type, [47mval[0m is the value obtained when looking up a key that is not bound in the hash table; think of it as the default value for lookups. Finally, the [47m:initially[0m keyword is illegal for fields of [47mSTOBJ-TABLE[0m type. Note that the actual representation of the stobj in the underlying Lisp may be quite different; see [stobj-example-2]. For the moment we focus primarily on the logical aspects of the object. In addition, the [47mdefstobj[0m event introduces functions for recognizing and creating the stobj and for recognizing, accessing, and updating its fields. For fields of [47mARRAY[0m type, length and resize functions are also introduced; see [defstobj-element-type] for discussion of the [47m:element-type[0m keyword that may be provided for performance . For fields of [47mHASH-TABLE[0m or [47mSTOBJ-TABLE[0m type, this event also introduces boundp, get? ([47mHASH-TABLE[0m types only), remove, count, clear, and initialization functions, as discussed below. Constants are introduced that correspond to the accessor functions. Restrictions on the Field Descriptions in Defstobj Each field descriptor is of the form: (fieldi :TYPE typei :INITIALLY vali) Note that the type and initial value are given in ``keyword argument'' format and may be given in either order. The [47mtypei[0m and [47mvali[0m ``arguments'' are not evaluated. If omitted, the type defaults to [47mt[0m (unrestricted) and the initial value defaults to [47mnil[0m. Each [47mtypei[0m must be either a [47m[type-spec][0m or else a list of the form [47m(ARRAY type-spec (max))[0m, [47m(HASH-TABLE test)[0m, [47m(HASH-TABLE test size)[0m, [47m(HASH-TABLE test size type-spec)[0m, [47m(STOBJ-TABLE)[0m, or [47m(STOBJ-TABLE size)[0m. (Again, we are ignoring the case of nested stobjs, discussed elsewhere (see [nested-stobjs]), where a type-spec may be replaced by a stobj name.) The latter forms are said to be ``array types'', ``hash-table types'', and stobj-table types (again, not discussed much here; see [stobj-table]). Examples of legal [47mtypei[0m are: (INTEGER 0 31) (SIGNED-BYTE 31) (ARRAY (SIGNED-BYTE 31) (16)) (ARRAY (SIGNED-BYTE 31) (*c*)) ; where *c* has a non-negative integer value (HASH-TABLE HONS-EQUAL 70) (HASH-TABLE EQL NIL (INTEGER 0 *)) (STOBJ-TABLE 70) The [47mtypei[0m describes the objects which are expected to occupy the given field. Those objects in [47mfieldi[0m should satisfy [47mtypei[0m. We are more precise below about what we mean by ``expected.'' Below we present the restrictions on [47mtypei[0m and [47mvali[0m. Remark on [47mSATISFIES[0m. As suggested above, each type indicator must be a legal [type-spec] or a stobj name. But if it is a type-spec involving [47m(SATISFIES pred)[0m, then not only must [47mpred[0m be a unary [47m:[0m[47m[logic][0m mode function symbol, but the type-spec is subject to a form of [guard] verification. For example, the type-spec [47m(SATISFIES evenp)[0m is not legal for a stobj field because the guard generated for [47m(evenp x)[0m is [47m(integerp x)[0m. However, the following is legal. (defun my-evenp (x) (declare (xargs :guard t)) (and (integerp x) (evenp x))) (defstobj st (fld :type (satisfies my-evenp) :initially 4)) The following is also legal, as explained below. (defstobj st (a :type (and integer (satisfies evenp)) :initially 0)) The type-spec displayed immediately above is legal because it generates the term [47m(and (integerp x) (evenp x)[0m), which macroexpands to [47m(if (integerp x) (evenp x) nil)[0m and hence can be trivially guard-verified. To understand this notion of trivial guard verification, first note that every type-spec gives rise to a corresponding term in the variable [47mx[0m, as in the example just above. If the type-spec uses [47mSATISFIES[0m, then the guard proof obligation for that term is subject to the limited simplification used by [47m[verify-guards][0m with option [47m:guard-simplify :limited[0m; see [verify-guards], specifically regarding that option. The requirement is that this limited simplifcation completes the proof, without further simplification or a call to the theorem prover. This restriction to limited simplification is probably not much of a restriction for typical uses of [47mSATISFIES[0m in type-specs. End of Remark on [47mSATISFIES[0m. Scalar Types We first discuss types that are neither array types, hash-table types, nor stobj-table types. We call these ``scalar types.'' When [47mtypei[0m is a [47m[type-spec][0m it restricts the contents, [47mx[0m, of [47mfieldi[0m according to the ``meaning'' formula given in the table for [47m[type-spec][0m. For example, the first [47mtypei[0m above restricts the field to be an integer between 0 and 31, inclusive. The second restricts the field to be an integer between -2^30 and (2^30)-1, inclusive. The initial value, [47mvali[0m, of a field description may be any ACL2 object but must satisfy [47mtypei[0m. Note that [47mvali[0m is not a form to be evaluated but an object. A form that evaluates to [47mvali[0m could be written [47m'vali[0m, but [47mdefstobj[0m does not expect you to write the quote mark. For example, the field description (days-off :initially (saturday sunday)) describes a field named [47mdays-off[0m whose initial value is the list consisting of the two symbols [47mSATURDAY[0m and [47mSUNDAY[0m. In particular, the initial value is NOT obtained by applying the function [47msaturday[0m to the variable [47msunday[0m! Had we written (days-off :initially '(saturday sunday)) it would be equivalent to writing (days-off :initially (quote (saturday sunday))) which would initialize the field to a list of length two, whose first element is the symbol [47mquote[0m and whose second element is a list containing the symbols [47msaturday[0m and [47msunday[0m. Array Types When [47mtypei[0m is of the form [47m(ARRAY type-spec (max))[0m, the field is supposed to be a list of items, initially of length specified by [47mmax[0m, each of which satisfies the indicated [47mtype-spec[0m. [47mMax[0m must be a non-negative integer or a defined constant evaluating to a non-negative integer. Thus, each of (ARRAY (SIGNED-BYTE 31) (16)) (ARRAY (SIGNED-BYTE 31) (*c*)) ; given previous event (defconst *c* 16) restricts the field to be a list of integers, initially of length 16, where each integer in the list is a [47m(SIGNED-BYTE 31)[0m. We sometimes call such a list an ``array'' (because it is represented as an array in the underlying Common Lisp). The elements of an array field are indexed by position, starting at 0. Thus, the maximum legal index of an array field one less than is specified by [47mmax[0m. Note that the value of [47mmax[0m must be less than the Common Lisp constant [47marray-dimension-limit[0m, and also (though this presumably follows) less than the Common Lisp constant [47marray-total-size-limit[0m. Note also that the [47mARRAY[0m type requires that the [47mmax[0m be enclosed in parentheses. This makes ACL2's notation consistent with the Common Lisp convention of describing the (multi-)dimensionality of arrays. But ACL2 currently supports only single dimensional arrays in stobjs. For array fields, the initial value [47mvali[0m must be an object satisfying the [47m[type-spec][0m of the [47mARRAY[0m description. The initial value of the field is a list of [47mmax[0m repetitions of [47mvali[0m. Array fields can be ``resized,'' that is, their lengths can be changed, if [47m:resizable t[0m is supplied as shown in the example and General Form above. The new length must satisfy the same restriction as does [47mmax[0m, as described above. Each array field in a [47mdefstobj[0m event gives rise to a length function, which gives the length of the field, and a resize function, which modifies the length of the field if [47m:resizable t[0m was supplied with the field when the [47mdefstobj[0m was introduced and otherwise causes an error. If [47m:resizable t[0m was supplied and the resize function specifies a new length [47mk[0m, then: if [47mk[0m is less than the existing array length, the array is shortened simply by dropping elements with index at least [47mk[0m; otherwise, the array is extended to length [47mk[0m by mapping the new indices to the initial value (supplied by [47m:initially[0m, else default [47mnil[0m). Array resizing is relatively slow, so we recommend using it somewhat sparingly. See [defstobj-element-type] for how the [47m:element-type[0m field may help with performance. Hash-table Types When [47mtypei[0m is of the form [47m(HASH-TABLE test size type-spec)[0m, where [47msize[0m and [47mtype-spec[0m are optional, the field is logically an association list, initially empty, accessed using function [47m[hons-assoc-equal][0m (which is convenient simply because it has a guard of [47mt[0m, as opposed to other flavors of [47m[assoc][0m). Under the hood in raw Lisp, however, there is a corresponding hash table that represents the same association of keys with values as does the association list. Each key should be comparable with arbitrary objects using the specified [47mtest[0m: thus if [47mtest[0m is [47m[equal][0m then there is no restriction on keys; if [47mtest[0m is [47m[eq][0m or [47m[eql][0m then the keys must be symbols or satisfy [47m[eqlablep][0m, respectively; and if [47mtest[0m is [47m[hons-equal][0m then there is no restriction on keys, but each proposed key is [47m[hons][0med in raw Lisp before it is used (whether for access or update) and before it is put into the underlying hash table. The [47msize[0m defaults to [47mnil[0m, and if supplied, it must be either [47mnil[0m or a non-negative integer, or else a defined constant evaluating to [47mnil[0m or a non-negative integer. When the value is a (non-negative) integer, it may be used by the host Lisp as a hint for how to size the associated hash table in raw Lisp. For a hash-table field, the [47m:initially[0m keyword specifies a default rather than an initial value: it provides the value (default [47mnil[0m) returned by an accessor when a given key is not bound. A hash-table field is associated not only with a recognizer, an accessor, and an updater, but also with the following functions, whose final argument is the stobj name but that may also take a key or, in the case of the ``init'' function, three other arguments, as follows: * a ``boundp'' function to check whether a given key is bound; * a ``get?'' function that, for a given key, returns two values [47m(mv val boundp)[0m, where: if the given key is bound then [47mval[0m is its value and [47mboundp[0m is [47mt[0m, else [47mval[0m is as specified by the [47m:initially[0m keyword ([47mnil[0m by default) and [47mboundp[0m is [47mnil[0m; * a ``remove'' function for removing a given key; * a ``count'' function that returns the number of (distinct) bound keys; * a ``clear'' function that creates a new empty hash table (and logically, the empty alist); * an ``init'' function that takes a given size, rehash-size, and rehash-threshold (and the stobj name) and creates a new empty hash table (and logically, the empty alist) by passing these parameters to the raw Lisp function, [47m(make-hash-table)[0m, that creates a hash table. The clear and init functions both use the [47msize[0m argument, if supplied and not [47mnil[0m, of the type of the field supplied in the [47mdefstobj[0m event. If a non-[47mnil[0m [47msize[0m argument was not supplied in that type, then the size of the hash table depends on the host Lisp. Stobj-table Types As noted above, these are not discussed much here; see [stobj-table]. The Default Function Names To recap, in (defstobj name (field1 :type type1 :initially val1) ... (fieldk :type typek :initially valk) :renaming doublets :inline inline-flag) [47mname[0m must be a new symbol, each [47mfieldi[0m must be a symbol, each [47mtypei[0m must be a [47m[type-spec][0m or [47m(ARRAY type-spec (max))[0m, and each [47mvali[0m must be an object satisfying [47mtypei[0m. Roughly speaking, for each [47mfieldi[0m, a [47mdefstobj[0m introduces a recognizer function, an accessor function, and an updater function. The accessor function, for example, takes the stobj and returns the indicated component; the updater takes a new component value and the stobj and return a new stobj with the component replaced by the new value. But that summary is inaccurate for array, hash-table, and stobj-table fields. The accessor function for an array field does not take the stobj and return the indicated component array, which is a list of length specified by [47mmax[0m. Instead, it takes an additional index argument and returns the indicated element of the array component. Similarly, the updater function for an array field takes an index, a new value, and the stobj, and returns a new stobj with the indicated element replaced by the new value. The accessor and updater functions for a hash-table field are analogous to those for array fields. Thus, the accessor takes an additional key argument and returns the associated value, or nil if the key is not bound. The updater function takes a key, a new value, and the stobj, and returns a new stobj with the indicated element replaced by the new value. See [stobj-table] for a discussion of stobj-table types, which are largely ignored below. These functions --- the recognizer, accessor, and updater, and also length and resize functions in the case of array fields, and boundp, get?, remove, count, clear, and init functions in the case of hash-table fields --- have ``default names.'' The default names depend on the field name, [47mfieldi[0m, and on whether the field is an array field, a hash-table field, or neither (i.e., a scalar field). For clarity, suppose [47mfieldi[0m is named [47mc[0m. The default names are shown below in calls, which also indicate the arities of the functions. In the expressions, we use [47mx[0m as the object to be recognized by field recognizers, [47mi[0m as an array index or the size of a resized array, [47mk[0m as a key (for the logical association list or raw-Lisp hash table associated with the field), [47mv[0m as the ``new value'' to be installed by an updater, and [47mname[0m as the single-threaded object. scalar field array field hash-table field and stobj-table field recognizer (cP x) (cP x) (cP x) accessor (c name) (cI i name) hash-table access: (c-get k name) stobj-table access: (c-get k name default) updater (UPDATE-c v name) (UPDATE-cI i v name) (c-put k v name) length (c-LENGTH name) resize (RESIZE-c i name) boundp (c-boundp k name) get? [For hash-tables only, not stobj-tables] (c-get? k name) remove (c-rem k name) count (c-count name) clear (c-clear name) init (c-init ht-size rehash-size rehash-threshold name) Finally, a recognizer and a creator for the entire single-threaded object are introduced. The creator returns the initial stobj, but may only be used in limited contexts; see [with-local-stobj]. If the single-threaded object is named [47mname[0m, then the default names and arities are as shown below. top recognizer (nameP x) creator (CREATE-name) For example, the event (DEFSTOBJ $S (X :TYPE INTEGER :INITIALLY 0) (A :TYPE (ARRAY (INTEGER 0 9) (3)) :INITIALLY 9) (H :TYPE (HASH-TABLE EQ))) introduces a stobj named [47m$S[0m. The stobj has three fields: [47mX[0m, [47mA[0m, and [47mH[0m. The [47mA[0m field is an array and the [47mA[0m field is a hash table. The [47mX[0m field contains an integer and is initially 0. The [47mA[0m field contains a list of integers, each between 0 and 9, inclusive. Initially, each of the three elements of the [47mA[0m field is 9. This event introduces the following sequence of definitions: (DEFUN XP (X) ...) ; recognizer for X field (DEFUN AP (X) ...) ; recognizer of A field (DEFUN HP (X) ...) ; recognizer of H field (DEFUN $SP ($S) ...) ; top-level recognizer for stobj $S (DEFUN CREATE-$S () ...) ; creator for stobj $S (DEFUN X ($S) ...) ; accessor for X field (DEFUN UPDATE-X (V $S) ...) ; updater for X field (DEFUN A-LENGTH ($S) ...) ; length of A field (DEFUN RESIZE-A (I $S) ...) ; resizer for A field (DEFUN AI (I $S) ...) ; accessor for A field at index I (DEFUN UPDATE-AI (I V $S) ...) ; updater for A field at index I (DEFUN H-GET (K $S) ...) ; accessor for H field at key K (DEFUN H-PUT (K V $S) ...) ; updater for H field at key K (DEFUN H-BOUNDP (K $S) ...) ; t if key k is bound in H, else nil (DEFUN H-GET? (K $S) ...) ; (mv val t) if key is bound in H to val; ; (mv nil nil) if key is not bound in H (DEFUN H-REM (K $S) ...) ; remove key K from field H (DEFUN H-COUNT ($S) ...) ; the number of (distinct) keys in field H (DEFUN H-CLEAR ($S) ...) ; empty the hash table for field H (DEFUN H-INIT (HT-SIZE REHASH-SIZE REHASH-THRESHOLD $S) ...) ; replace the hash table for field H with ; with a new, empty hash table with the ; given hints as described below For the last of these, the values of [47mHT-SIZE[0m, [47mREHASH-SIZE[0m, and [47mREHASH-THRESHOLD[0m are passed to the [47m:size[0m, [47m:rehash-size[0m, and [47m:reash-threshold[0m arguments (respectively) of a call of [47mmake-hash-table[0m in raw Lisp. The [47m:test[0m argument of this function is the one specified in the [47m:type[0m specified in the [47mdefstobj[0m event for the field, in this case [47mEQ[0m from the type [47m(HASH-TABLE EQ)[0m; note however that if the [47m:type[0m specifies the test [47mHONS-EQUAL[0m, then the [47m:test[0m is [47mEQL[0m. Avoiding the Default Function Names If you do not like the default names listed above you may use the optional [47m:renaming[0m doublets to substitute names of your own choosing. Each element of [47mdoublets[0m should be of the form [47m(fn1 fn2)[0m, where [47mfn1[0m is a default name and [47mfn2[0m is your choice for that name. For example (DEFSTOBJ $S (X :TYPE INTEGER :INITIALLY 0) (A :TYPE (ARRAY (INTEGER 0 9) (3)) :INITIALLY 9) :renaming ((X XACCESSOR) (CREATE-$S MAKE$S))) introduces the following definitions (DEFUN XP (X) ...) ; recognizer for X field (DEFUN AP (X) ...) ; recognizer of A field (DEFUN $SP ($S) ...) ; top-level recognizer for stobj $S (DEFUN MAKE$S () ...) ; creator for stobj $S (DEFUN XACCESSOR ($S) ...) ; accessor for X field (DEFUN UPDATE-X (V $S) ...) ; updater for X field (DEFUN A-LENGTH ($S) ...) ; length of A field (DEFUN RESIZE-A (K $S) ...) ; resizer for A field (DEFUN AI (I $S) ...) ; accessor for A field at index I (DEFUN UPDATE-AI (I V $S) ...) ; updater for A field at index I Note that even though the renaming doublets substitutes ``[47mXACCESSOR[0m'' for ``[47mX[0m'' the updater for the [47mX[0m field is still called ``[47mUPDATE-X[0m.'' That is because the renaming is applied to the default function names, not to the field descriptors in the event. Use of the [47m:renaming[0m doublets may be necessary to avoid name clashes between the default names and pre-existing function symbols. Constants [47mDefstobj[0m events also introduce constant definitions (see [defconst]). One constant is introduced for each accessor function by prefixing and suffixing a `[47m*[0m' character on the function name. The value of that constant is the position of the field being accessed. For example, if the accessor functions are [47ma[0m, [47mb[0m, and [47mc[0m, in that order, then the following constant definitions are introduced. (defconst *a* 0) (defconst *b* 1) (defconst *c* 2) These constants are used for certain calls of [47m[nth][0m and [47m[update-nth][0m that are displayed to the user in proof output. For example, for stobj [47mst[0m with accessor functions [47ma[0m, [47mb[0m, and [47mc[0m, in that order, the term [47m(nth '2 st)[0m would be printed during a proof as [47m(nth *c* st)[0m. Also see [term], in particular the discussion there of untranslated terms, and see [nth-aliases-table]. The Effects of a [47mDefstobj[0m Because the stobj functions are introduced as ``sub-events'' of the [47mdefstobj[0m the history commands [47m:[0m[47m[pe][0m and [47m:[0m[47m[pc][0m will not print the definitions of these functions but will print the superior [47mdefstobj[0m event. To see the definitions of these functions use the history command [47m:[0m[47m[pcb!][0m. To see an s-expression containing the definitions that constitute the raw Lisp implementation of the event, evaluate the form (nth 4 (global-val 'cltl-command (w state))) [3mimmediately after[0m the [47mdefstobj[0m event has been processed. Those functions that contain [47m(DECLARE (STOBJ-INLINE-FN T))[0m will generate [47m[defabbrev][0m forms because the [47m:inline[0m keyword of [47mdefstobj[0m was supplied the value [47mt[0m. The rest will generate [47m[defun][0m forms. Evaluation of a [47mdefstobj[0m event [disable]s the [executable-counterpart] of the creator function. This is useful for proofs, since calls of that function always cause an error (albeit one which is handled during proofs). A [47mdefstobj[0m is considered redundant only if it is syntactically identical to a previously executed [47mdefstobj[0m. Note that a redundant [47mdefstobj[0m does not reset the [stobj] fields to their initial values. Performance The [47m:inline[0m keyword argument controls whether or not the functions introduced are inlined (as macros under the hood, in raw Lisp), with the exception of the resize function. If [47m:inline t[0m is provided then these are inlined; otherwise they are not. The advantage of inlining is potentially better performance; there have been contrived examples, doing essentially nothing except accessing and updating array fields, where inlining reduced the time by a factor of 10 or more; and inlining has sped up realistic examples by a factor of at least 2. Inlining may get within a factor of 2 of C execution times for such contrived examples, and perhaps within a few percent of C execution times on realistic examples. A drawback to inlining is that redefinition may not work as expected, much as redefinition may not work as expected for macros: defined functions that call a macro, or an inlined stobj function, will not see a subsequent redefinition of the macro or inlined function. Another drawback to inlining is that because inlined functions are implemented as macros in raw Lisp, tracing (see [trace$]) will not show their calls. These drawbacks are avoided by default, but the user who is not concerned about them is advised to specify [47m:inline t[0m. It can also improve performance to specify [47m:non-memoizable t[0m, which disallows memoization but therefore avoids the cost of certain ``flushing'' operations. See [defstobj-element-type] for performance considerations pertaining to the [47m:element-type[0m field. Specifying Congruent Stobjs Two stobjs are may be considered to be ``congruent'' if they have the same structure, that is, their [47mdefstobj[0m events are identical when ignoring field names. In particular, every stobj is congruent to itself. In order to tell ACL2 that a new stobj [47mst2[0m is indeed to be considered as congruent to an existing stobj [47mst1[0m, the [47mdefstobj[0m event introducing [47mst2[0m is given the keyword argument [47m:congruent-to st1[0m. Congruence is an equivalence relation: when you specify a new stobj to be congruent to an old one, you are also specifying that the new stobj is congruent to all other stobjs that are congruent to the old one. Thus, continuing the example above, if you specify that [47mst3[0m is [47m:congruent-to st2[0m, then [47mst1[0m, [47mst2[0m, and [47mst3[0m will all be congruent to each other. When two stobjs are congruent, ACL2 allows you to substitute one for another in a function call. Any number of stobjs may be replaced with congruent stobjs in the call, provided no two get replaced with the same stobj. The return values are correspondingly modified: if stobj [47mst1[0m is replaced by [47mst2[0m at an argument position, and if [47mst1[0m is returned in the output [signature] of the function, then [47mst2[0m is returned in place of [47mst1[0m. The following example illustrates congruent stobjs. For more examples of how to take advantage of congruent stobjs, and also of how to misuse them, see community book [47mbooks/misc/congruent-stobjs-test.lisp[0m. (defstobj st1 fld1) (defstobj st2 fld2 :congruent-to st1) (defstobj st3 fld3 :congruent-to st2) ; equivalently, :congruent-to st1 (defun f (st1 st2 st3) (declare (xargs :stobjs (st1 st2 st3))) (list (fld2 st1) (fld3 st2) (fld1 st3))) (update-fld1 1 st1) (update-fld1 2 st2) ; notice use of update-fld1 on st2 (update-fld1 3 st3) ; notice use of update-fld1 on st3 (assert-event (equal (f st3 st2 st1) '(3 2 1))) The following example shows an error that occurs when stobj arguments are repeated, i.e., at least two stobj arguments (in this case, three) get replaced by the same stobj. ACL2 !>(f st1 st1 st1) ACL2 Error in TOP-LEVEL: The form ST1 is being used, as an argument to a call of F, where the single-threaded object ST2 was expected, even though these are congruent stobjs. See :DOC defstobj, in particular the discussion of congruent stobjs. Note: this error occurred in the context (F ST1 ST1 ST1). ACL2 !> Specifying Non-executable Stobjs As noted above, if keyword argument [47m:non-executable t[0m is specified then no global stobj for the given name is created. See [add-global-stobj] for a discussion of global stobjs, but in a nutshell, a global stobj is a ``live'', mutable stobj that can be referenced in the top-level loop. So why use this keyword argument? Perhaps you would like to do your computation on several stobjs that are all congruent to a given stobj, [47mst[0m. Then by using [47m:non-executable t[0m to introduce [47mst[0m, you avoid allocating memory for [47mst[0m that you never intend to use. Similarly, you can avoid allocating such memory when your intended use of [47mst[0m is only as a local stobj (see [with-local-stobj]) or as the type of a stobj field of another stobj. But see [add-global-stobj] and [remove-global-stobj] for utilities that change whether or not there is a global stobj for a given name. Subtopics [Defstobj-element-type] Specify the element type for a [stobj] array field") (defstobj-element-type (defstobj) "Specify the element type for a [stobj] array field This topic assumes familiarity with the [47m[defstobj][0m event. It documents the [47m:element-type[0m keyword for a stobj array field. Note that [47m:element-type[0m is only supported for stobj array fields, not other sorts of stobj fields. Consider a stobj array field with [47m:type[0m of the form [47m(array etype (n))[0m, for example, [47m(array bit (8))[0m. Logically, this ``array'' is a list, each of whose elements has the indicated type, [47metype[0m --- in our example, the type, [47mbit[0m (i.e., 0 or 1). In raw Lisp, however, an array is allocated. The Lisp code that allocates that array can specify the type of its elements, and may specify that element type to be [47mbit[0m. But it would also be legal to specify a weaker type. In particular, the type [47mt[0m is a legal type for every object, and this can be specified by including [47m:element-type t[0m in your stobj array field. Perhaps surprisingly, Lisp code may run faster when the element type in a raw Lisp array is [47mt[0m rather than a more restrictive type. The [47m:element-type[0m of a stobj array field may be specified to be [47mt[0m to give this behavior, by using [47m:element-type t[0m. You can do your own experiments to decide whether that is helpful, in particular by considering [community-book] [47mbooks/demos/element-type.lisp[0m. That file starts with the following events and then times reading and writing the stobj array. (defconst *ar-size* (expt 10 8)) (defstobj st1 (ar1 :type (array double-float (*ar-size*)) :element-type t ; Omit this line to compare times with or without it. :initially 0) ; Optional: :inline t) Our own experiments with this file have produced the following results (for both realtime and runtime) with CCL and SBCL on a 2019-era MacBook Pro (2.4 GHz 8-Core Intel Core i9). They suggest the use of [47m:element-type t[0m with read-intensive applications when using CCL. Results may be very different without the use of [47m:inline t[0m, and of course these results may not be indicative of your own experience with various applications, Lisps, and operating systems. (time$ (reads-st1 st1 *ar-size*)) Results: CCL With :element-type t 0.27 seconds (32 bytes allocated) Without :element-type t ; 0.47 seconds (32 bytes allocated) SBCL With :element-type t 0.23 seconds (0 bytes allocated) Without :element-type t 0.21 seconds (0 bytes allocated) (time$ (writes-st1 st1 (to-df 2) *ar-size*)) Results: CCL With :element-type t 1.17 seconds (128 bytes allocated); Without :element-type t 0.27 seconds (128 bytes allocated) SBCL With :element-type t 0.24 seconds realtime (0 bytes allocated) Without :element-type t 0.25 seconds (0 bytes allocated). Currently the legal values for [47m:element-type[0m are [47mt[0m and the default value, which is the element type specified in the [47m:type[0m field of the stobj array field specification. This could change if experiments suggest something different.") (defstub (events) "Stub-out a function symbol Examples: ACL2 !>(defstub subr1 (* * state) => (mv * state)) ACL2 !>(defstub add-hash (* * hashtable) => hashtable) ACL2 !>(defstub inv (*) => * :formals (x) :guard (fieldp x)) General Forms: (defstub name (i1 ... ik) => outputs :kwd1 val1 ... :kwdn valn) ; new style (defstub name (i1 ... ik) outputs :kwd1 val1 ... :kwdn valn) ; old style where [47mname[0m is a new function symbol, and [47m(i1 ... ik)[0m, [47moutputs[0m, [47m:kwdi[0m, and [47mvali[0m must be as follows, respectively. * [3mNew style:[0m [47m((name i1 ... ik) => outputs :kwd1 val1 ... :kwdn valn)[0m is a valid new-style [signature]. * [3mOld style:[0m [47m(name (i1 ... ik) outputs :kwd1 val1 ... :kwdn valn)[0m is a valid old-style [signature]. Also see [signature]. Note that [47m(i1 ... ik)[0m is the list of formal parameters of the newly-defined function symbol, [47mname[0m. Note that while the [47mdefstub[0m syntax resembles a [signature], it is different: [47mname[0m occurs outside the parentheses containing [47m(i1 ... ik)[0m in the [47mdefstub[0m syntax, but inside in the signature syntax. A [47mdefstub[0m macro call expands into an [47m[encapsulate][0m event (see [encapsulate]). Thus, no axioms are available about [47mname[0m but it may be used wherever a function of the given signature is permitted. Exception: if [47moutputs[0m is of the form [47m(mv ...)[0m, then a [47m:[0m[47m[type-prescription][0m rule is introduced stating that [47mname[0m returns a value satisfying [47m[true-listp][0m.") (deftheory (events theories) "Define a theory (to [enable] or [disable] a set of rules) Example: (deftheory interp-theory (set-difference-theories (universal-theory :here) (universal-theory 'interp-section))) General Forms: (deftheory name term) (deftheory name term :redundant-okp flg) where [47mname[0m is a new symbolic name (see [name]), [47mterm[0m is a term that when evaluated will produce a theory (see [theories]), and [47mflg[0m is expected to be Boolean. Except for the variable [47m[world][0m, [47mterm[0m must contain no free variables. [47mTerm[0m is evaluated with [47m[world][0m bound to the current world (see [world]) and the resulting theory is then converted to a [3mrunic theory[0m (see [theories]) and associated with [47mname[0m. Henceforth, this runic theory is returned as the value of the theory expression [47m(theory name)[0m. The value returned is the length of the resulting theory. For example, in the following, the theory associated with [47m'FOO[0m has 60 [rune]s as of ACL2 Version 8.6: ACL2 !>(deftheory foo (union-theories '(binary-append) (theory 'minimal-theory))) Summary Form: ( DEFTHEORY FOO ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) 60 ACL2 !> Note that the theory being defined depends on the context. For example, consider the following (contrived) example book. (in-package "ACL2") (defund foo (x) (consp x)) ; defund disables foo (local (in-theory (enable foo))) (deftheory my-theory (current-theory :here)) (in-theory (disable foo)) (defthm foo-property (implies (consp x) (foo x)) :hints (("Goal" :in-theory (enable my-theory)))) At the time [47mfoo-property[0m is proved admissible during book certification (see [certify-book]), the [47m[local][0m [47m[in-theory][0m event has previously been evaluated, so the [definition] of [47mfoo[0m is [enable]d. Thus, the [47m:in-theory[0m hint on [47mfoo-property[0m will [enable] [47mfoo[0m, and the theorem proves. HOWEVER, when the book is later included (see [include-book]), the [47m[local][0m event is skipped, so the definition of [47mfoo[0m is [disable]d at the time the [theory] [47mmy-theory[0m is defined. Hence, unlike the case for the admissibility pass of the book's certification, that theory does not include the definition of [47mfoo[0m when the book is included. There is, however, a way to ensure that a [theory] defined in a book is the same at [47m[include-book][0m time as it was during the admissibility pass of the book's certification; see [deftheory-static]. Note that a [47mdeftheory[0m event is never redundant unless [47m:redundant-okp t[0m is specified, which supports a limited form of redundancy. See [redundant-events]. Subtopics [Defthy] Define a theory (to [enable] or [disable] a set of rules)") (deftheory-static (events theories) "Define a `static' theory (to [enable] or [disable] a set of rules) This macro provides a variant of [47m[deftheory][0m, such that the resulting theory is the same at [47m[include-book][0m time as it was at [47m[certify-book][0m time. We assume that the reader is familiar with [theories]; see [deftheory]. We begin here by illustrating how [47mdeftheory-static[0m differs from [47m[deftheory][0m. Suppose for example that the following events are the first two events in a book, where that book is certified in the initial ACL2 [world] (see [ground-zero]). (deftheory my-theory (current-theory :here)) (deftheory-static my-static-theory (current-theory :here)) Now suppose we include that book after executing the following event. (in-theory (disable car-cons)) Suppose that later we execute [47m(in-theory (theory 'my-theory))[0m. Then the rule [47mcar-cons[0m will be disabled, because it was disabled at the time the expression [47m(current-theory :here)[0m was evaluated when processing the [47mdeftheory[0m of [47mmy-theory[0m while including the book. However, if we execute [47m(in-theory (theory 'my-static-theory))[0m, then the rule [47mcar-cons[0m will be enabled, because the value of the theory [47mmy-static-theory[0m was saved at the time the book was certified. General Form: (deftheory-static name term) The arguments are handled the same as for [47m[deftheory][0m. Thus, [47mname[0m is a new symbolic name (see [name]), and [47mterm[0m is a term that when evaluated will produce a theory (see [theories]). Except for the variable [47m[world][0m, [47mterm[0m must contain no free variables. [47mTerm[0m is evaluated with [47m[world][0m bound to the current world (see [world]) and the resulting theory is then converted to a [3mrunic theory[0m (see [theories]) and associated with [47mname[0m. Henceforth, this runic theory is returned as the value of the theory expression [47m(theory name)[0m. As for [47m[deftheory][0m, the value returned is the length of the resulting theory. We conclude with an optional discussion about the implementation of [47mdeftheory-static[0m, for those familiar with [47m[make-event][0m. The following macroexpansion of the [47mdeftheory-static[0m form above shows how this works (see [trans1]). ACL2 !>:trans1 (deftheory-static my-static-theory (current-theory :here)) (MAKE-EVENT (LET ((WORLD (W STATE))) (LIST 'DEFTHEORY 'MY-STATIC-THEORY (LIST 'QUOTE (CURRENT-THEORY :HERE))))) ACL2 !> The idea is that upon evaluation of this [47mmake-event[0m form, the first step is to evaluate the indicated [47m[let][0m expression to obtain a form [47m(deftheory my-theory '(...))[0m, where ``[47m(...)[0m'' is a list of all [rune]s in current theory. If this form is in a book being certified, then the resulting [47mdeftheory[0m form is stored in the book's certificate, and is used when the book is included later.") (defthm (events) "Prove and name a theorem Examples: (defthm assoc-of-app (equal (app (app a b) c) (app a (app b c)))) The following nonsensical example illustrates all the optional arguments but is illegal because not all combinations are permitted. See [hints] for a complete list of [hints]. (defthm main (implies (hyps x y z) (concl x y z)) :rule-classes (:REWRITE :GENERALIZE) :instructions (induct prove promote (dive 1) x (dive 2) = top (drop 2) prove) :hints (("Goal" :do-not '(generalize fertilize) :in-theory (set-difference-theories (current-theory :here) '(assoc)) :induct (and (nth n a) (nth n b)) :use ((:instance assoc-of-append (x a) (y b) (z c)) (:functional-instance (:instance p-f (x a) (y b)) (p consp) (f assoc))))) :otf-flg t) General Form: (defthm name term :rule-classes rule-classes :instructions instructions :hints hints :otf-flg otf-flg) where [47mname[0m is a new symbolic name (see [name]), [47mterm[0m is a term alleged to be a theorem, and [47m[rule-classes][0m, [47m[instructions][0m, [47m[hints][0m, and [47m[otf-flg][0m are as described in their respective [documentation]. The keyword arguments above are all optional, however you may not supply both [47m:[0m[47m[instructions][0m and [47m:[0m[47m[hints][0m, since one drives the interactive [proof-builder] and the other drives the theorem prover. If [47m:[0m[47m[rule-classes][0m is not specified, the list [47m(:rewrite)[0m is used; if you wish the theorem to generate no rules, specify [47m:[0m[47m[rule-classes][0m [47mnil[0m. When ACL2 processes a [47mdefthm[0m event, it first tries to prove the [term] using the indicated hints (see [hints]) or [instructions] (see [proof-builder]). If it is successful, it stores the rules described by the rule-classes (see [rule-classes]), proving the necessary corollaries. Subtopics [Defthmd] Prove and name a theorem and then disable it [Otf-flg] Allow more than one initial subgoal to be pushed for induction") (defthmd (defthm events) "Prove and name a theorem and then disable it Use [47mdefthmd[0m instead of [47m[defthm][0m when you want to disable a theorem immediately after proving it. This macro has been provided for users who prefer working in a mode where theorems are only enabled when explicitly directed by [47m:[0m[47m[in-theory][0m. Specifically, the form (defthmd NAME TERM ...) expands to the following, except that some output is inhibited for the [47m[in-theory][0m and [47m[value-triple][0m [events]: (progn (defthm NAME TERM ...) (in-theory (disable NAME)) (value-triple '(:defthmd NAME))). [47mDefthmd[0m events are generally not redundant, because the generated [47m[in-theory][0m event is not redundant. This default can be changed; see [set-in-theory-redundant-okp]. See [defthm] for documentation of [47mdefthm[0m.") (defthy (events theories deftheory) "Define a theory (to [enable] or [disable] a set of rules) See [deftheory]. The [47mdefthy[0m macro is simply a convenient macro for [47mdeftheory[0m that supports a limited notion of redundancy; see [redundant-events]. Specifically: a call [47m(defthy name expr)[0m expands to the corresponding event [47m(deftheory name expr :redundant-okp t)[0m.") (defttag (interfacing-tools events) "Introduce a trust tag (ttag) [31;1mIntroduction[0m. This event is intended for advanced users who, in essence, want to build extensions of ACL2. The typical intended use is to create [books] that extend the functionality of ACL2 in ways not allowed without a so-called ``active trust tag''. A trust tag thus represents a contract: The writer of such a book is guaranteeing that the book extends ACL2 in a ``correct'' way as defined by the writer of the book. The writer of the book will often have a small section of the book in the scope of an active trust tag that can be inspected by potential users of that book: <initial part of book, which does not use trust tags> (defttag :some-ttag) ; install :some-ttag as an active trust tag <various code that requires an active trust tag> (defttag nil) ; remove active trust tag <final part of book, which does not use trust tags> Why might trust tags be needed? The evaluation of certain functions can introduce bugs and even unsoundness, but can be useful in restricted ways that avoid such issues. For example, [47m[sys-call][0m can be used in an unsafe way, for example to overwrite files, or worse; see [sys-call] for a frightening example from Bob Boyer. The following example shows that the function [47m[sys-call][0m is restricted by default, but can be called after installing an active trust tag. ACL2 !>(sys-call "pwd" nil) ACL2 Error in TOP-LEVEL: The SYS-CALL function cannot be called unless a trust tag is in effect. See :DOC defttag. ACL2 !>(defttag t) ; Install :T as an active trust tag. TTAG NOTE: Adding ttag :T from the top level loop. T ACL2 !>(sys-call "pwd" nil) ; print the current directory and return NIL /u/kaufmann NIL ACL2 !>(defttag nil) ; Remove the active trust tag (using value NIL). NIL ACL2 !>(sys-call "pwd" nil) ; Now we get the error again: ACL2 Error in TOP-LEVEL: The SYS-CALL function cannot be called unless a trust tag is in effect. See :DOC defttag. ACL2 !> Of course, using [47m[sys-call][0m with the Linux command [47mpwd[0m is not likely to cause any soundness problems! So suppose we want to create a function that prints the working directory. We might put the following [events] into a book that is to be certified. (in-package "ACL2") (defttag :pwd-ttag) (defun print-working-dir () (declare (xargs :mode :program)) (sys-call "pwd" nil)) (defttag nil) ; optional (books end with this implicitly) We can certify this book with a specification that [47m:pwd-ttag[0m is a legal trust tag: (certify-book "pwd" 0 t :ttags (:pwd-ttag)) One can now use this book by executing [47m[include-book][0m with keyword parameter [47m:ttags (:pwd-ttag)[0m and then calling function [47mprint-working-dir[0m: (include-book "pwd" :ttags (:pwd-ttag)) (print-working-dir) ; working directory is printed to terminal [31;1mDetailed documentation.[0m General Form: (defttag tag-name) where [47mtag-name[0m is a symbol. Note however that if [47mtag-name[0m is not [47mnil[0m, then it is converted to a ``corresponding [keyword]'': a symbol in the [47m"KEYWORD"[0m package with the same [47m[symbol-name][0m as [47mtag-name[0m. Thus, for example, [47m(defttag foo)[0m is equivalent to [47m(defttag :foo)[0m. Moreover, a non-[47mnil[0m symbol with a [47m[symbol-name][0m of [47m"NIL"[0m is illegal for trust tags; thus, for example, [47m(defttag :nil)[0m is illegal. This event introduces or removes a so-called active trust tag (or ``ttag'', pronounced ``tee tag''). An active ttag is a [keyword] symbol that is associated with potentially unsafe evaluation. For example, calls of [47m[sys-call][0m are illegal unless there is an active trust tag. An active trust tag can be installed using a [47mdefttag[0m event. If one introduces an active ttag and then writes definitions that contain calls of [47m[sys-call][0m, presumably in a defensibly ``safe'' way, then responsibility for those calls is attributed to that ttag. This attribution (or blame!) is at the level of [books]; a book's [certificate] contains a list of ttags that are active in that book, or in a book that is included (possibly [local]ly), or in a book included in a book that is included (either inclusion being potentially [local]), and so on. We explain all this in more detail below. [47m(Defttag :tag-name)[0m is essentially equivalent to (table acl2-defaults-table :ttag :tag-name) and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. We say more about the scope of [47mdefttag[0m forms below. Note: This is an event! It does not print the usual event [summary] but nevertheless executes the above [47m[table][0m event and hence changes the ACL2 logical [world], and is so recorded. Although no event summary is printed, it is important to note that the ``TTAG NOTE'', discussed below, is always printed for a non-nil [47m:tag-name[0m (unless deferred; see [set-deferred-ttag-notes]). [31;1mActive ttags.[0m Suppose [47mtag-name[0m names a non-[47mnil[0m symbol. Then [47m(defttag :tag-name)[0m sets [47m:tag-name[0m to be the (unique) ``active ttag.'' There must be an active ttag in order for there to be any mention of certain functions, including [47m[sys-call][0m; evaluate the form [47m(strip-cars *ttag-fns*)[0m to see the full list of such symbols. The macro [47m[progn!][0m similarly requires an active ttag. On the other hand, [47m(defttag nil)[0m removes the active ttag, if any; there is then no active ttag. The scope of a [47mdefttag[0m form in a book being certified or included is limited to subsequent forms in the same book before the next [47mdefttag[0m (if any) in that book. Similarly, if a [47mdefttag[0m form is evaluated in the top-level loop, then its effect is limited to subsequent forms in the top-level loop before the next [47mdefttag[0m in the top-level loop (if any). Moreover, [47m[certify-book][0m is illegal when a ttag is active; of course, in such a circumstance one can execute [47m(defttag nil)[0m in order to allow book certification. [31;1mTtag notes and the ``certifier.''[0m When a [47mdefttag[0m is executed with an argument other than [47mnil[0m, output is printed, starting on a fresh line with: [47mTTAG NOTE[0m. For example: ACL2 !>(defttag :foo) TTAG NOTE: Adding ttag :FOO from the top level loop. :FOO ACL2 !> If the [47mdefttag[0m occurs in an included book, the message looks like this. TTAG NOTE (for included book): Adding ttag :FOO from file /u/smith/acl2/my-book.lisp. The ``[47mTTAG NOTE[0m'' message is always printed on a single line. The intention is that one can search the standard output for all such notes in order to find all [3mdefttag[0m events. In a sense, [3mdefttag[0m events can allow you to define your own system on top of ACL2 (for example, see [progn!]). So in order for someone else (who we might call the ``certifier'') to be confident that your collection of [books] is meaningful, that certifier should certify all the user-supplied books from scratch and check either that no [47m:ttags[0m were supplied to [47m[certify-book][0m, or else look for every [47mTTAG NOTE[0m in the standard output in order to locate all [47mdefttag[0m [events] with non-[47mnil[0m tag name. In this way, the certifier can in principle decide whether to be satisfied that those [47mdefttag[0m events did not allow inappropriate forms in the user-supplied books. In order to eliminate much of the output from [47mTTAG NOTE[0ms, see [set-deferred-ttag-notes]. Note however that the resulting security is somewhat less; therefore, a [47mTTAG NOTE[0m is printed when invoking [47mset-deferred-ttag-notes[0m to defer printing of ttag notes. [31;1mAllowed ttags when certifying and including books.[0m A [47mdefttag[0m form may not be evaluated unless its argument is a so-called ``allowed'' ttag. All ttags are allowed in the interactive top-level loop. However, during [47m[certify-book][0m and [47m[include-book][0m, the set of allowed ttags may be restricted according to the [47m:ttags[0m keyword argument. If this argument is [47mnil[0m then no ttag is allowed, so a [47mdefttag[0m call will fail during book certification or inclusion in this case. This restriction applies even to [47mdefttag[0m forms already evaluated in the so-called certification [world] at the time [47m[certify-book][0m is called. But note that [47m(defttag nil)[0m is always legal. A [47m:ttags[0m argument of [47m[certify-book][0m and [47m[include-book][0m can have value [47m:all[0m, indicating that every ttag is allowed, i.e., no restriction is being placed on the arguments, just as in the interactive top-level loop. In the case of [47minclude-book[0m, an omitted [47m:ttags[0m argument or an argument of [47m:default[0m is treated as [47m:all[0m, except that warnings will occur when the book's [certificate] includes ttags; but for [47mcertify-book[0m, an omitted [47mttags[0m argument is treated as [47mnil[0m. Otherwise, if the [47m:ttags[0m argument is supplied but not [47m:all[0m, then its value is a true list of ttag specifications, each having one of the following forms, where [47msym[0m is a non-[47mnil[0m symbol which is treated as the corresponding [keyword]. (1) [47m:sym[0m (2) [47m(:sym)[0m (3) [47m(:sym x1 x2 ... xk)[0m, where k > 0 and each [47mxi[0m is a string, except that one [47mxi[0m may be [47mnil[0m. In Case (1), [47m(defttag :sym)[0m is allowed to occur in at most one book or else in the top-level loop (i.e., the certification world for a book under certification or a book being included). Case (2) allows [47m(defttag :sym)[0m to occur in an unlimited number of books. For case (3) the [47mxi[0m specify where [47m(defttag :sym)[0m may occur, as follows. The case that [47mxi[0m is [47mnil[0m refers to the top-level loop, while all other [47mxi[0m are filenames, where the [47m".lisp"[0m extension is optional and relative pathnames are considered to be relative to the connected book directory (see [cbd]). Note that the restrictions on [47m(defttag :sym)[0m apply equally to any equivalent for based on the notion of ``corresponding keyword'' discussed above, e.g., [47m(defttag acl2::sym)[0m. An error message, as shown below, illustrates how ACL2 enforces the notion of allowed ttags. Suppose that you call [47m[certify-book][0m with argument [47m:ttags (:foo)[0m, where you have already executed [47m(defttag :foo)[0m in the certification world (i.e., before calling [47m[certify-book][0m). Then ACL2 immediately associates the ttag [47m:foo[0m with [47mnil[0m, where again, [47mnil[0m refers to the top-level loop. If ACL2 then encounters [47m(defttag foo)[0m inside that book, you will get the following error (using the book's absolute pathname, as shown): ACL2 Error in ( TABLE ACL2-DEFAULTS-TABLE ...): The ttag :FOO associated with file /u/smith/work/my-book.lisp is not among the set of ttags permitted in the current context, specified as follows: ((:FOO NIL)). See :DOC defttag. In general the structure displayed by the error message, which is [47m((:FOO NIL))[0m in this case, represents the currently allowed ttags with elements as discussed in (1) through (3) above. In this case, that list's unique element is [47m(:FOO NIL)[0m, meaning that ttag [47m:FOO[0m is only allowed at the top level (as represented by [47mNIL[0m). [31;1mAssociating ttags with books and with the top-level loop.[0m When a book is certified, each form [47m(defttag tag)[0m that is encountered for non-[47mnil[0m [47mtag[0m in that book or an included book is recorded in the generated [certificate], which associates the keyword corresponding to [47mtag[0m with the [full-book-name] of the book containing that [47mdefttag[0m. If such a [47mdefttag[0m form is encountered outside a book, hence in the [portcullis] of the book being certified or one of its included books, then that keyword is associated with [47mnil[0m in the generated [certificate]. Note that the notion of ``included book'' here applies to the recursive notion of a book either included directly in the book being certified or else included in such a book, where we account even for [local]ly included books. For examples of ways to take advantage of ttags, see [hacker], [include-raw], [quicklisp], and more generally [interfacing-tools]. See also [ttags-seen], [progn!], [remove-untouchable], [set-raw-mode], and [sys-call]. Subtopics [Push-untouchable] Add name or list of names to the list of untouchable symbols [Remove-untouchable] Remove names from lists of untouchable symbols [Set-deferred-ttag-notes] Modify the verbosity of [47mTTAG NOTE[0m printing [Set-raw-mode] Enter or exit ``raw mode,'' a raw Lisp environment [Set-raw-mode-on] Enter ``raw mode,'' a raw Lisp environment (requires trust tag) [Set-raw-mode-on!] Enter ``raw mode,'' a raw Lisp environment (adds trust tag) [Untouchable] Function symbols and state globals that cannot be referenced") (defun (events programming) "Define a function symbol Examples: (defun app (x y) (if (consp x) (cons (car x) (app (cdr x) y)) y)) (defun fact (n) (declare (xargs :guard (and (integerp n) (>= n 0)))) (if (zp n) 1 (* n (fact (1- n))))) General Form: (defun fn (var1 ... varn) dcl ... dcl ; optionally, also one documentation string; see below body) where [47mfn[0m is the symbol you wish to define and is a new symbolic name (see [name]), [47m(var1 ... varn)[0m is its list of formal parameters (see [name]), and [47mbody[0m is its body. The definitional axiom is logically admissible provided certain restrictions are met. These are sketched below. See also [mutual-recursion] for how to use [47mdefun[0m to make mutually recursive definitions, including discussion of how the [47m[xargs][0m [declaration]s in one [47mdefun[0m may affect the other definitions. Note that ACL2 does not support the use of [47mlambda-list[0m keywords (such as [47m&optional[0m) in the formals list of functions. We do support some such keywords in macros and often you can achieve the desired syntax by defining a macro in addition to the general version of your function. See [defmacro]. The [3mdeclarations[0m (see [declare]), [47mdcl[0m, are optional. If more than one [47mdcl[0m form appears, they are effectively grouped together as one. Perhaps the most commonly used ACL2 specific declaration is of the form [47m(declare (xargs :guard g :measure m))[0m. This declaration in the [47mdefun[0m of some function [47mfn[0m has the effect of making the ``[guard]'' for [47mfn[0m be the term [47mg[0m and the ``measure'' be the term [47mm[0m. The notion of ``measure'' is crucial to ACL2's definitional principle. The notion of ``guard'' is not, and is discussed elsewhere; see [verify-guards] and see [set-verify-guards-eagerness]. Note that a [47m:measure[0m is not allowed for a non-recursive definition unless it is part of a [47m[mutual-recursion][0m (exception: a measure of [47mnil[0m is treated as though the [47mmeasure[0m was omitted); moreover, if a [47m:measure[0m is supplied, then it must be a legal term. Apart from these restrictions, the [47m:measure[0m is ignored in [47m:[0m[47m[program][0m mode; see [defun-mode]. One documentation string may be included between the list of formal parameters and the body, but it is essentially ignored by ACL2. See [documentation] for a discussion of documentation in ACL2. We now briefly discuss the ACL2 definitional principle, using the following definition form which is offered as a more or less generic example. (defun fn (x y) (declare (xargs :guard (g x y) :measure (m x y))) (if (test x y) (stop x y) (step (fn (d x) y)))) Note that in our generic example, [47mfn[0m has just two arguments, [47mx[0m and [47my[0m, the [guard] and measure terms involve both of them, and the body is a simple case split on [47m(test x y)[0m leading to a ``non-recursive'' branch, [47m(stop x y)[0m, and a ``recursive'' branch. In the recursive branch, [47mfn[0m is called after ``decrementing'' [47mx[0m to [47m(d x)[0m and some step function is applied to the result. Of course, this generic example is quite specific in form but is intended to illustrate the more general case. Provided this definition is admissible under the logic, as outlined below, it adds the following axiom to the logic. Defining Axiom: (fn x y) = (if (test x y) (stop x y) (step (fn (d x) y))) Note that the [guard] of [47mfn[0m has no bearing on this logical axiom. This defining axiom is actually implemented in the ACL2 system by a [47m:[0m[47m[definition][0m rule, namely (equal (fn x y) (if (test a b) (stop a b) (step (fn (d a) b)))). See [definition] for a discussion of how definition rules are applied. Roughly speaking, the rule causes certain instances of [47m(fn x y)[0m to be replaced by the corresponding instances of the body above. This is called ``opening up'' [47m(fn x y)[0m. The instances of [47m(fn x y)[0m opened are chosen primarily by heuristics which determine that the recursive calls of [47mfn[0m in the opened body (after simplification) are more desirable than the unopened call of [47mfn[0m. This discussion has assumed that the definition of [47mfn[0m was admissible. Exactly what does that mean? First, [47mfn[0m must be a previously unaxiomatized function symbol (however, see [ld-redefinition-action]). Second, the formal parameters must be distinct variable names. Third, the [guard], measure, and body should all be terms and should mention no free variables except the formal parameters. Thus, for example, body may not contain references to ``global'' or ``special'' variables; ACL2 constants or additional formals should be used instead. The final conditions on admissibility concern the termination of the recursion. Roughly put, all applications of [47mfn[0m must terminate. In particular, there must exist a binary relation, [47mrel[0m, and some unary predicate [47mmp[0m such that [47mrel[0m is well-founded on objects satisfying [47mmp[0m, the measure term [47mm[0m must always produce something satisfying [47mmp[0m, and the measure term must decrease according to [47mrel[0m in each recursive call, under the hypothesis that all the tests ruling the call are satisfied (see [rulers]). By the meaning of well-foundedness, we know there are no infinitely descending chains of successively [47mrel[0m-smaller [47mmp[0m-objects. Thus, the recursion must terminate. The default well-founded relation is [47m[o<][0m, an ``ordinal less-than'' relation (discussed further below) that reduces to ordinary [47m<[0m on the natural numbers. The default measure term is [47m(acl2-count var)[0m, where [47mvar[0m is a formal parameter that is chosen heuristically: roughly speaking, it is the first formal that is tested along every branch and changed in each recursive call. The only primitive well-founded relation in ACL2 is [47m[o<][0m, which is known to be well-founded on the [47m[o-p][0ms. For the proof of well-foundedness, see [proof-of-well-foundedness]. However it is possible to add new well-founded relations. For details, see [well-founded-relation]. We discuss later how to specify which well-founded relation is selected by [47mdefun[0m and in the present discussion we assume, without loss of generality, that it is [47m[o<][0m on the [47m[o-p][0ms. For example, for our generic definition of [47mfn[0m above, with measure term [47m(m x y)[0m, two theorems must be proved. The first establishes that [47mm[0m produces an ordinal: (o-p (m x y)). The second shows that [47mm[0m decreases in the (only) recursive call of [47mfn[0m: (implies (not (test x y)) (o< (m (d x) y) (m x y))). Observe that in the latter formula we must show that the ``[47mm[0m-size'' of [47m(d x)[0m and [47my[0m is ``smaller than'' the [47mm[0m-size of [47mx[0m and [47my[0m, provided the test, [47m(test x y)[0m, in the body fails, thus leading to the recursive call [47m(fn (d x) y)[0m. See [o<] for a discussion of this notion of ``smaller than.'' It should be noted that the most commonly used ordinals are the natural numbers and that on natural numbers, [47m[o<][0m is just the familiar ``less than'' relation ([47m[<][0m). Thus, it is very common to use a measure [47mm[0m that returns a nonnegative integer, for then [47m(o-p (m x y))[0m becomes a simple conjecture about the type of [47mm[0m and the second formula above becomes a conjecture about the less-than relationship of nonnegative integer arithmetic. The most commonly used measure function is [47m[ACL2-count][0m, which computes a nonnegative integer size for all ACL2 objects. See [ACL2-count]. Probably the most common recursive scheme in Lisp [programming] is when some formal is supposed to be a list and in the recursive call it is replaced by its [47m[cdr][0m. For example, [47m(test x y)[0m might be simply [47m(atom x)[0m and [47m(d x)[0m might be [47m(cdr x)[0m. In that case, [47m(acl2-count x)[0m is a suitable measure because the [47m[ACL2-count][0m of a [47m[cons][0m is strictly larger than the [47m[ACL2-count][0ms of its [47m[car][0m and [47m[cdr][0m. Thus, ``recursion by [47m[car][0m'' and ``recursion by [47m[cdr][0m'' are trivially admitted if [47m[ACL2-count][0m is used as the measure and the definition protects every recursive call by a test insuring that the decremented argument is a [47m[consp][0m. Similarly, ``recursion by [47m[1-][0m'' in which a positive integer formal is decremented by one in recursion, is also trivially admissible. See [built-in-clause] to extend the class of trivially admissible recursive schemes. We now turn to the question of which well-founded relation [47mdefun[0m uses. It should first be observed that [47mdefun[0m must actually select both a relation (e.g., [47m[o<][0m) and a domain predicate (e.g., [47m[o-p][0m) on which that relation is known to be well-founded. But, as noted elsewhere (see [well-founded-relation-rule]), every known well-founded relation has a unique domain predicate associated with it and so it suffices to identify simply the relation here. The [47m[xargs][0m field of a [47m[declare][0m permits the explicit specification of any known well-founded relation with the keyword [47m:well-founded-relation[0m. An example is given below. If the [47m[xargs][0m for a [47mdefun[0m specifies a well-founded relation, that relation and its associated domain predicate are used in generating the termination conditions for the definition. If no [47m:well-founded-relation[0m is specified, [47mdefun[0m uses the [47m:well-founded-relation[0m specified in the [47m[ACL2-defaults-table][0m. See [set-well-founded-relation] to see how to set the default well-founded relation (and, implicitly, its domain predicate). The initial default well-founded relation is [47m[o<][0m (with domain predicate [47m[o-p][0m). This completes the brief sketch of the ACL2 definitional principle. Optionally, see [rulers] for a more detailed discussion of the termination analysis and resulting proof obligations for admissibility, as well as a discussion of the relation to how ACL2 stores induction schemes. See [induction-coarse-v-fine-grained] for a discussion of how well-chosen rulers can affect the induction scheme. On very rare occasions ACL2 will seem to "hang" when processing a definition, especially if there are many subexpressions of the body whose function symbol is [47m[if][0m (or which macroexpand to such an expression). In those cases you may wish to supply the following to [47m[xargs][0m: [47m:normalize nil[0m. This is an advanced feature that turns off certain simplification of [definition] bodies and [guard]s; [normalize]. When a [47mdefun[0m form is submitted, ACL2 sometimes computes and stores a [type-prescription] rule for the function. See [type-prescription-debugging] for relevant discussion. The following example illustrates all of the available declarations, but it is completely nonsensical and it shows only a few of the many [47m:xargs[0m keywords. See [xargs] for a complete list of [47m:xargs[0m keywords; also see [hints]. (defun example (x y z a b c i j) (declare (ignore a b c) (ignorable x y) (irrelevant c) (type integer i j) (optimize (safety 3)) (xargs :guard (symbolp x) :measure (- i j) :hints (("Goal" :do-not-induct t :do-not '(generalize fertilize) :expand ((assoc x a) (member y z)) :restrict ((<-trans ((x x) (y (foo x))))) :hands-off (length binary-append) :in-theory (set-difference-theories (current-theory :here) '(assoc)) :induct (and (nth n a) (nth n b)) :use ((:instance assoc-of-append (x a) (y b) (z c)) (:functional-instance (:instance p-f (x a) (y b)) (p consp) (f assoc))))) :guard-hints (("Subgoal *1/3'" :use ((:instance assoc-of-append (x a) (y b) (z c))))) :mode :logic :verify-guards nil :type-prescription (natp (example x y z a b c i j)))) (example-body x y z i j)) Subtopics [Defn] Definition with [guard] [47mt[0m [Defnd] [disable]d definition with [guard] [47mt[0m [Defun$] Define a function symbol and generate a warrant [Defun-inline] Define a potentially inlined function symbol and associated macro [Defun-mode] Determines whether a function definition is a logical act [Defun-notinline] Define a not-to-be-inlined function symbol and associated macro [Defun-nx] Define a non-executable function symbol [Defund] Define a function symbol and then disable it [Defund-inline] Define a potentially disabled, inlined function symbol and associated macro [Defund-notinline] Define a disabled, not-to-be-inlined function symbol and associated macro [Defund-nx] Define a disabled non-executable function symbol [Mutual-recursion] Define some mutually recursive functions [Rulers] Control for ACL2's termination and induction analyses [Set-bogus-defun-hints-ok] Allow unnecessary [47m(xargs :hints ...)[0m and [measure]s. [Set-bogus-measure-ok] Allow unnecessary [measure]s and [47m(xargs :hints ...)[0m. [Set-ignore-ok] Allow unused formals and locals without an [47mignore[0m or [47mignorable[0m declaration [Set-irrelevant-formals-ok] Allow irrelevant formals in definitions [Set-measure-function] Set the default measure function symbol [Set-well-founded-relation] Set the default well-founded relation [Xargs] Extra arguments, for example to give [hints] to [47m[defun][0m") (defun$ (defun events apply$) "Define a function symbol and generate a warrant [47mDefun$[0m is just a macro that expands to the obvious [47m[defun][0m followed by [47m[defwarrant][0m.") (defun-inline (defun events) "Define a potentially inlined function symbol and associated macro You may be able to improve performance by replacing an event [47m(defun f ...)[0m with a corresponding event [47m(defun-inline f ...)[0m, in order to encourage the host Lisp compiler to inline calls of [47mf[0m. Example Form: (defun-inline lng (x) (declare (xargs :guard (true-listp x))) (if (endp x) 0 (1+ (lng (cdr x))))) General Form: (defun-inline fn (var1 ... varn) dcl ... dcl ; optionally, also one documentation string; as for defun body) satisfying the same requirements as in the General Form for [47m[defun][0m. The effect is to define a macro [47mfn[0m and a function [47mfn$inline[0m (i.e., a symbol in the same package as [47mfn[0m but whose [47m[symbol-name][0m has the suffix [47m"$INLINE"[0m), such that each call of [47mfn[0m expands to a call of the function symbol [47mfn$inline[0m on the same arguments. Moreover, [47m[table][0m [events] are generated that allow the use of [47mfn[0m in [theory] expressions to represent [47mfn$inline[0m and that cause any untranslated (user-level) call of [47mfn$inline[0m to be printed as the corresponding call of [47mfn[0m. The documentation string is an optional string that can provide documentation but is essentially ignored by ACL2. A form [47m(defun-inline f ...)[0m actually defines a function named [47mf$inline[0m and a corresponding macro named [47mf[0m whose calls expand to calls of [47mf$inline[0m, while providing the illusion that there is just the ``function'' [47mf[0m. For example, the Example Form above macroexpands in one step to the following form. (progn (defmacro lng (non-stobj-var0) (list 'lng$inline non-stobj-var0)) (add-macro-fn lng lng$inline) (defun lng$inline (x) (declare (xargs :guard (true-listp x))) (if (endp x) 0 (1+ (lng (cdr x)))))) Note that the above call of [47m[add-macro-fn][0m generates the aforementioned two table events (see [add-macro-fn]), which provide the illusion that we are just defining a function [47mlng[0m, as you can see in the following log: [47mlng[0m appears rather than [47mlng$inline[0m. ACL2 !>(set-gag-mode nil) <state> ACL2 !>(thm (equal (lng (append x y)) (+ (lng x) (lng y))) :hints (("Goal" :in-theory (enable lng)))) [.. output omitted ..] Subgoal *1/2 (IMPLIES (AND (NOT (ENDP X)) (EQUAL (LNG (APPEND (CDR X) Y)) (+ (LNG (CDR X)) (LNG Y)))) (EQUAL (LNG (APPEND X Y)) (+ (LNG X) (LNG Y)))). [.. output omitted ..] Under the hood, ACL2 arranges that every function symbol with suffix [47m"$INLINE"[0m is presented to the compiler as one whose calls we would prefer to inline. Technically: the Common Lisp form [47m(declaim (inline f$inline))[0m is generated for a function symbol [47mf$inline[0m before that symbol's definition is submitted. However, the Common Lisp spec explicitly avoids requiring that the compiler respect this [47mdeclaim[0m form. Fortunately, Common Lisp implementations often do respect it. Also see [defund-inline], see [defun-notinline], and see [defund-notinline]. [3mRemarks[0m. (1) None of these macros (including [47mdefun-inline[0m) is supported for use inside a [47m[mutual-recursion][0m. (2) Every function symbol defined in ACL2 whose [47m[symbol-name][0m has the suffix [47m"$INLINE"[0m is proclaimed to be inline; similarly for [47m"$NOTINLINE"[0m and notinline. These suffix restrictions are explained in a comment in the ACL2 source definition of macro [47mdefun-inline[0m. Note that only the functions themselves are thus proclaimed, not their executable counterparts (also known as *1* functions; see [evaluation]). (3) No special treatment for inlining (or notinlining) is given for function symbols locally defined by [47m[flet][0m, with two exceptions: when explicitly declared [47minline[0m or [47mnotinline[0m by the [47mflet[0m form, and for symbols discussed in (1) and (2) above that, at some point in the current ACL2 session, were defined as function symbols in ACL2 (even if not currently defined because of undoing or being [local]). (4) The function symbol actually being defined by [47m(defun-inline foo ...)[0m is [47mfoo$inline[0m. As mentioned above, one can be oblivious to this fact when writing [theory] expressions or perusing prover output. However, for other purposes (for example, [47m[verify-guards][0m and [47m[defabsstobj][0m [47m:exports[0m) you will need to supply the name of the function symbol rather than the name of the macro; e.g., for the above form [47m(defun-inline foo ...)[0m, you may subsequently issue the event [47m(verify-guards foo$inline)[0m but not [47m(verify-guards foo)[0m. (5) Obscure Remark. Suppose that you certify a book with compilation (the default) in one host Lisp, saving the expansion file. Suppose that you then compile in another host Lisp by using [47m[include-book][0m with argument [47m:load-compiled-file :comp[0m. Then in subsequent sessions, including that book with the second host Lisp will not result in any inline or notinline behavior for functions defined in the book.") (defun-mode (defun) "Determines whether a function definition is a logical act Two ``[defun-mode]s'' are supported, [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m. Roughly speaking, [47m:[0m[47m[program][0m mode allows you to prototype a function for execution without any proof burdens, while [47m:[0m[47m[logic][0m mode allows you to add a new definitional axiom to the logic. The system comes up in [47m:[0m[47m[logic][0m mode. Execution of functions whose [defun-mode] is [47m:[0m[47m[program][0m may render ACL2 unsound! See [defun-mode-caveat]. Note that calls of [47m[local][0m and of many [events] are skipped in [47m:program[0m mode; see [program]. When you define a function in the ACL2 logic, that function can be run on concrete data. But it is also possible to reason deductively about the function because each definition extends the underlying logic with a definitional axiom. To ensure that the logic is sound after the addition of this axiom, certain restrictions have to be met. One restriction is that every function called by the newly defined one must be in [47m:logic[0m mode. (However, see [defun-mode-lambdas] for some clarification concerning [47m[apply$][0m.) But the most challenging restriction is that the system must prove that the recursion in the new definition terminates. Because ACL2 is a [programming] language, you often may wish simply to program in ACL2. For example, you may wish to define your system and test it, without any logical burden. Or, you may wish to define ``utility'' functions --- functions that are executed to help manage the task of building your system but functions whose logical properties are of no immediate concern. Such functions might be used to generate test data or help interpret the results of tests. They might create files or explore the ACL2 database. The termination arguments for such functions are an unnecessary burden provided no axioms about the functions are ever used in deductions. Thus, ACL2 introduces the idea of the ``[defun-mode]'' of a function. The [47m:mode[0m keyword of [47m[defun][0m's [47m[declare][0m [47mxarg[0m allows you to specify the [defun-mode] of a given definition. If no [47m:mode[0m keyword is supplied, the default [defun-mode] is used; see [default-defun-mode]. There are two [defun-mode]s, each of which is written as a keyword: [47m:[0m[47m[program][0m --- logically undefined but executable outside deductive contexts. [47m:[0m[47m[logic][0m --- axiomatically defined as per the ACL2 definitional principle. It is possible to change the [defun-mode] of a function from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m. We discuss this below. We think of functions having [47m:[0m[47m[program][0m mode as ``dangerous'' functions, while functions having [47m:[0m[47m[logic][0m mode are ``safe.'' The only requirement enforced on [47m:[0m[47m[program][0m mode functions is the syntactic one: each definition must be well-formed ACL2. Naively speaking, if a [47m:[0m[47m[program][0m mode function fails to terminate then no harm is done because no axiom is added (so inconsistency is avoided) and some invocations of the function may simply never return. This simplistic justification of [47m:[0m[47m[program][0m mode execution is faulty because it ignores the damage that might be caused by ``mis-guarded'' functions. See [defun-mode-caveat]. We therefore implicitly describe an imagined implementation of [defun-mode]s that is safe and, we think, effective. But please see [defun-mode-caveat]. The default [defun-mode] is [47m:[0m[47m[logic][0m. This means that when you [47m[defun][0m a function the system will try to prove termination. If you wish to introduce a function of a different [defun-mode] use the [47m:mode[0m [47m[xargs][0m keyword. Below we show [47mfact[0m introduced as a function in [47m:[0m[47m[program][0m mode. (defun fact (n) (declare (xargs :mode :program)) (if (or (not (integerp n)) (= n 0)) 1 (* n (fact (1- n))))) No axiom is added to the logic as a result of this definition. By introducing [47mfact[0m in [47m:[0m[47m[program][0m mode we avoid the burden of a termination proof, while still having the option of executing the function. For example, you can type ACL2 !>(fact 3) and get the answer [47m6[0m. If you type [47m(fact -1)[0m you will get a hard lisp error due to ``infinite recursion.'' However, the ACL2 theorem prover knows no axioms about [47mfact[0m. In particular, if the term [47m(fact 3)[0m arises in a proof, the theorem prover is unable to deduce that it is [47m6[0m. From the perspective of the theorem prover it is as though [47mfact[0m were an undefined function symbol of arity [47m1[0m. Thus, modulo certain important issues (see [defun-mode-caveat]), the introduction of this function in [47m:[0m[47m[program][0m mode does not imperil the soundness of the system --- despite the fact that the termination argument for [47mfact[0m was omitted --- because nothing of interest can be proved about [47mfact[0m. Indeed, we do not allow [47mfact[0m to be used in logical contexts such as conjectures submitted for proof. It is possible to convert a function from [47m:[0m[47m[program][0m mode to [47m:[0m[47m[logic][0m mode at the cost of proving that it is admissible. This can be done by invoking (verify-termination fact) which is equivalent to submitting the [47m[defun][0m of [47mfact[0m, again, but in [47m:[0m[47m[logic][0m mode. (defun fact (n) (declare (xargs :mode :logic)) (if (or (not (integerp n)) (= n 0)) 1 (* n (fact (1- n))))) This particular event will fail because the termination argument requires that [47mn[0m be nonnegative. A repaired [47m[defun][0m, for example with [47m[=][0m replaced by [47m[<=][0m, will succeed, and an axiom about [47mfact[0m will henceforth be available. Technically, [47m[verify-termination][0m submits a redefinition of the [47m:[0m[47m[program][0m mode function. This is permitted, even when [47m[ld-redefinition-action][0m is [47mnil[0m, because the new definition is identical to the old (except for its [47m:mode[0m and, possibly, other non-logical properties). See [guard] for a discussion of how to restrict the execution of functions. [Guard]s may be ``verified'' for functions in [47m:[0m[47m[logic][0m mode; see [verify-guards]. Subtopics [Defun-mode-lambdas] :program mode functions in [47m[lambda][0m objects [Logic] To set the default [defun-mode] to [47m:logic[0m [Program] To set the default [defun-mode] to [47m:[0m[47m[program][0m") (defun-mode-caveat (common-lisp) "Potential soundness issue for functions with [defun-mode] [47m:[0m[47m[program][0m See [raw-lisp-error] for a general discussion of raw Lisp errors. Although the discussion below focuses on raw Lisp errors that arise from calls of [47m:[0m[47m[program][0m mode functions, the soundness concerns expressed below apply to all raw Lisp errors. Technically speaking, in the current implementation, the execution of functions having [defun-mode] [47m:[0m[47m[program][0m may damage the ACL2 system in a way that renders it unsound. In practice, we have never seen this happen; so, the explanations below can be viewed as extremely paranoid. Nevertheless, here we document this concern, even if it should be taken with more than a grain of salt. See [defun-mode] for a discussion of [defun-mode]s. That discussion describes an imagined implementation that is slightly different from this one. This note explains that the current implementation is open to unsoundness. For discussion of a different soundness issue that is also related to function execution, see [generalized-booleans]. The execution of a function having [defun-mode] [47m:[0m[47m[program][0m may violate Common Lisp [guard]s on the subroutines used. (This may be true even for calls of a function on arguments that satisfy its [guard], because ACL2 has not verified that its [guard] is sufficient to protect its subroutines.) When a [guard] is violated at runtime all bets are off. That is, no guarantees are made either about the answer being ``right'' or about the continued rationality of the ACL2 system itself. For example, suppose you make the following [47m[defun][0m: (defun crash (i) (declare (xargs :mode :program :guard (integerp i))) (car i)) Note that the declared guard does not in fact adequately protect the subroutines in the body of [47mcrash[0m; indeed, satisfying the guard to [47mcrash[0m will guarantee that the [47m[car][0m expression is in violation of its guard. Because this function is admitted in [47m:[0m[47m[program][0m-mode, no checks are made concerning the suitability of the guard. Furthermore, in the current ACL2 implementation, [47mcrash[0m is executed directly in Common Lisp. Thus if you call [47mcrash[0m on an argument satisfying its guard you will cause an erroneous computation to take place. ACL2 !>(crash 7) Error: Caught fatal error [memory may be damaged] ... There is no telling how much damage is done by this errant computation. In some lisps your ACL2 job may actually crash back to the operating system. In other lisps you may be able to recover from the ``hard error'' and resume ACL2 in a damaged but apparently functional image. THUS, HAVING A FUNCTION WITH [defun-mode] [47m:[0m[47m[program][0m IN YOUR SYSTEM ABSOLVES US, THE ACL2 IMPLEMENTORS, FROM RESPONSIBILITY FOR THE SOUNDNESS OF OUR SYSTEM. Furthermore ACL2 DOES NOT YET PROVIDE ANY MEANS OF REGAINING ASSURANCES OF SOUNDNESS AFTER THE INTRODUCTION OF A FUNCTION IN [47m:[0m[47m[program][0m MODE, EVEN IF IT IS ULTIMATELY CONVERTED TO [47m:[0m[47m[logic][0m MODE (since its execution could have damaged the system in a way that makes it possible to verify its termination and [guard]s unsoundly). Finally, THE VAST MAJORITY OF ACL2 SYSTEM CODE IS IN [47m:[0m[47m[program][0m MODE AND SO ALL BETS ARE OFF FROM BEFORE YOU START! This hopeless state of current affairs will change, we think. We think we have defined our functions ``correctly'' in the sense that they can be converted, without ``essential'' modification, to [47m:[0m[47m[logic][0m mode. We think it very unlikely that a mis-guarded function in [47m:[0m[47m[program][0m mode (whether ours or yours) will cause unsoundness without some sort of hard lisp error accompanying it. We think that ultimately we can make it possible to execute your functions (interpretively) without risk to the system, even when some have [47m:[0m[47m[program][0m mode. In that imagined implementation, code using functions having [47m:[0m[47m[program][0m mode would run more slowly, but safely. These functions could be introduced into the logic ex post facto, whereupon the code's execution would speed up because Common Lisp would be allowed to execute it directly. We therefore ask that you simply pretend that this is that imagined implementation, introduce functions in [47m:[0m[47m[program][0m mode, use them as convenient and perhaps ultimately introduce some of them in [47m:[0m[47m[logic][0m mode and prove their properties. If you use the system this way we can develop (or dismiss) this style of formal system development. BUT BE ON THE LOOKOUT FOR SCREWUPS DUE TO DAMAGE CAUSED BY THE EXECUTION OF YOUR FUNCTIONS HAVING [47m:[0m[47m[program][0m MODE!") (defun-mode-lambdas (defun-mode) ":program mode functions in [47m[lambda][0m objects A rough rule-of-thumb is that all functions mentioned in a [47m:[0m[47m[logic][0m mode [47m[defun][0m must themselves be in [47m:logic[0m mode. If [47mprgm[0m is a [47m:[0m[47m[program][0m mode function then [47m(defun fn (x) (prgm x))[0m is illegal. But there are situations (always involving [47m[apply$][0m) in which [47m:program[0m mode function symbols are allowed to be mentioned in [47m:logic[0m mode [47m[defun][0ms. We explain here. Here are two example terms that mention the badged (see [47m[defbadge][0m) [47m:program[0m mode symbol [47mprgm[0m. (apply$ (lambda$ (e) (prgm e)) (list x)) (loop$ for e in lst collect (prgm e)) Are such terms permitted in the [47mdefun[0m of a [47m:logic[0m mode function? The answer is complicated because it depends on whether the [47mdefun[0m is [47m[loop$][0m recursive and whether the [47mdefun[0m will also try to verify the [47m[guard][0ms of [47mfn[0m. First, a [47m:logic[0m mode function may [47mapply$[0m a quoted [47m:program[0m mode symbol, whether guards are being verified or not. For example, [47m(apply$ 'prgm args)[0m is legal. Here [47mprgm[0m is just a quoted symbol. Since [47mprgm[0m is a [47m:program[0m mode symbol, there are no axioms about it, so during proofs such a call of [47mapply$[0m is not evaluated or expanded. If this form is evaluated at the top-level -- where [47m:program[0m mode functions are evaluable -- [47mapply$[0m checks the guards of [47mprgm[0m just as it would before any [47m:program[0m mode function is called. The situation is more complicated for use of [47m:program[0m mode functions in forms like [47m[lambda$][0m, well-formed quoted [47m[lambda][0m objects, and [47m[loop$][0m. The reason is that in guard-verified code, these forms are generally executed via compiled code and that requires that the [47mloop$[0m and [47mlambda[0m objects be Common Lisp compliant, which in turn implies they must be analyzable by the prover. Since formally [47mloop$[0ms are understood as calls of [scion]s on [47mlambda$[0m expressions it suffices for us to discuss the [47mlambda$[0m case alone. Well-formed quoted [47mLAMBDA[0m objects are treated the same way. So again, suppose you're defining a [47m:logic[0m mode function [47mfn[0m. Suppose [47mfn[0m is not [47mloop$[0m recursive and guards are not being verified during the [47mdefun[0m. Then badged [47m:program[0m mode symbols may be used [47mlambda$[0m forms in the definition of [47mfn[0m. If [47mfn[0m is [47mloop$[0m recursive, i.e., [47m:[0m[47m[loop$-recursion][0m [47mt[0m is declared, then all symbols used as functions in [47mlambda$[0m forms must be in [47m:logic[0m mode. The reason is that the measure conjectures generated must be in [47m:logic[0m mode to be provable. If [47mfn[0m is to be guard-verified, then all symbols used as functions in [47mlambda$[0m forms must be in [47m:logic[0m mode. The reason is that the guard conjectures must be in [47m:logic[0m mode to be provable. When a [47m:program[0m function is permitted in a [47m:logic[0m mode definition the system will print a warning to alert you to the possibility that proofs will fail. For example, the following events are legal (include-book "projects/apply/top" :dir :system) (defun prgm (x) (declare (xargs :mode :program)) (list 'hi x)) (defbadge prgm) (defun fn1 (x) (declare (xargs :mode :logic)) (apply$ 'prgm (list x))) but the last event will print: ACL2 Warning [Problematic-quoted-fns] in ( DEFUN FN1 ...): The definition of FN1 is in :LOGIC mode but mentions the :PROGRAM mode function HELLO in one or more :FN or :EXPR slots. Conjectures about FN1 may not be provable until this program is converted to :LOGIC mode and warranted! See :DOC verify-termination and defwarrant. Uses of [47mprgm[0m in quoted well-formed [47mLAMBDA[0m objects, [47mlambda$[0m forms, and [47mloop$[0m forms will cause similar warning messages to be printed.") (defun-notinline (defun events) "Define a not-to-be-inlined function symbol and associated macro See [defun-inline] for an analogous utility that supports inlining. The present utility is probably far less useful; it tells the compiler [3mnot[0m to inline calls of the function being defined. Also see [defund-notinline] for a variant of this event that disables the newly-defined function symbol. Under the hood, [47m(defun-inline f ...)[0m and [47m(defun-notinline f ...)[0m cause evaluation of Common Lisp forms [47m(declaim (inline f$inline))[0m and [47m(declaim (notinline f$notinline))[0m, respectively. According to the Common Lisp spec, the compiler need not respect the first of these (for [47minline[0m), but it must respect the second of these (for [47mnotinline[0m). Fortunately, Common Lisp implementations often do respect the first of these as well.") (defun-nx (defun events) "Define a non-executable function symbol Example: (defun-nx foo (x state) (declare (xargs :guard t)) (mv-let (a b c) (cons x state) (list a b c b a))) ; Note ``ill-formed'' call of foo just below. (defun bar (state y) (declare (xargs :stobjs state)) (foo state y)) The macro [47mdefun-nx[0m introduces definitions using the [47m[defun][0m macro, always in [47m:[0m[47m[logic][0m mode, such that the calls of the resulting function cannot be evaluated. Such a definition is admitted without enforcing syntactic restrictions for executability, in particular for single-threadedness (see [stobj]) and multiple-values passing (see [mv] and see [mv-let]). After such a definition is admitted, the usual syntactic rules for [47m[state][0m and user-defined [stobj]s are relaxed for calls of the function it defines. Also see [non-exec] for a way to designate subterms of function bodies, or subterms of code to be executed at the top level, as non-executable. The syntax of [47mdefun-nx[0m is identical to that of [47m[defun][0m. A form (defun-nx name (x1 ... xk) ... body) generates the following definition. (defun name (x1 ... xk) (declare (xargs :non-executable t :mode :logic)) ... (prog2$ (throw-nonexec-error 'name (list x1 ... xk)) body)) But [47mdefun-nx[0m does two other things. Before executing the [47mdefun[0m form displayed above, ACL2 arranges that [47mstate[0m is allowed as a formal parameter, by first introducing [47m(set-state-ok t)[0m in a way that is [local] to the generated event. After executing the [47mdefun[0m, the [executable-counterpart] [rune] for [47mname[0m is [disable]d. You can evaluate [47m:trans1 (defun-nx ...)[0m for your [47mdefun-nx[0m form to see its single-step macroexpansion. Note that because of the insertion of the above call of [47mthrow-nonexec-error[0m, no formal is ignored when using [47mdefun-nx[0m. During proofs, the error is silent; it is ``caught'' by the proof mechanism and generally results in the introduction of a call of [47m[hide][0m during a proof. If an error message is produced by evaluating a call of the function on a list of arguments that includes [47mstate[0m or user-defined [47m[stobj][0ms, these arguments will be shown as symbols such as [47m|<state>|[0m in the error message. In the case of a user-defined stobj bound by [47m[with-local-stobj][0m or [47m[stobj-let][0m, the symbol printed will include the suffix [47m{instance}[0m, for example, [47m|<st>{instance}|[0m. It is harmless to include [47m:non-executable t[0m in your own [47m[xargs][0m [47m[declare][0m form; [47mdefun-nx[0m will still lay down its own such declaration, but ACL2 can tolerate the duplication. Note that [47m[defund-nx][0m is also available. It is essentially identical to [47mdefun-nx[0m except that as with [47m[defund][0m, [47mdefund-nx[0m leaves the definition [rune] disabled for the new function symbol. If you use guards (see [guard]), please be aware that even though syntactic restrictions are relaxed for [47mdefun-nx[0m, guard verification proceeds exactly as for [47m[defun][0m. If you want ACL2 to skip a form for purposes of generating guard proof obligations, use the macro [47m[non-exec][0m, which generates a call of [47mthrow-nonexec-error[0m that differs somewhat from the one displayed above. See [non-exec]. See [defun] for documentation of [47mdefun[0m.") (defun-sk (events) "Define a function whose body has an outermost quantifier Examples: (defun-sk exists-x-p0-and-q0 (y z) (exists x (and (p0 x y z) (q0 x y z)))) (defun-sk exists-x-p0-and-q0 (y z) ; equivalent to the above (exists (x) (and (p0 x y z) (q0 x y z)))) (defun-sk forall-x-y-p0-and-q0 (z) (forall (x y) (and (p0 x y z) (q0 x y z))) :strengthen t) General Form: (defun-sk fn (var1 ... varn) dcl_1 dcl_2 ... dcl_k body &key rewrite quant-ok skolem-name thm-name strengthen constrain verbose) where [47mfn[0m is the symbol you wish to define and is a new symbolic [name], [47m(var1 ... varn)[0m is its list of formal parameters, the optional [47mdcl_i[0m forms are [47m[declare][0m forms, and [47mbody[0m is its body, which must be quantified as described below. The other arguments are explained below. For a simple example, see [defun-sk-example]. For a more elaborate example, see [Tutorial4-Defun-Sk-Example]. See [quantifier-tutorial] for a careful beginner's introduction that takes you through typical kinds of quantifier-based reasoning in ACL2. Also see [quantifiers] for an example illustrating how the use of recursion, rather than explicit quantification with [47mdefun-sk[0m, may be preferable. Below we describe the [47mdefun-sk[0m event precisely. First, let us consider the examples above. The first example, again, is: (defun-sk exists-x-p0-and-q0 (y z) (exists x (and (p0 x y z) (q0 x y z)))) It is intended to represent the predicate with formal parameters [47my[0m and [47mz[0m that holds when for some [47mx[0m, [47m(and (p0 x y z) (q0 x y z))[0m holds. In fact [47mdefun-sk[0m is a macro, and the call above adds the following two [events], as shown just below. The first event guarantees that if this new predicate holds of [47my[0m and [47mz[0m, then the term shown, [47m(exists-x-p0-and-q0-witness y z)[0m, is an example of the [47mx[0m that is therefore supposed to exist. (Intuitively, we are axiomatizing [47mexists-x-p0-and-q0-witness[0m to pick a witness if there is one. We comment below on the use of [47m[defun-nx][0m; for now, consider [47mdefun-nx[0m to be [47m[defun][0m.) Conversely, the second event below guarantees that if there is any [47mx[0m for which the term in question holds, then the new predicate does indeed hold of [47my[0m and [47mz[0m. (defun-nx exists-x-p0-and-q0 (y z) (let ((x (exists-x-p0-and-q0-witness y z))) (and (p0 x y z) (q0 x y z)))) (defthm exists-x-p0-and-q0-suff (implies (and (p0 x y z) (q0 x y z)) (exists-x-p0-and-q0 y z))) Now let us look at the third example from the introduction above: (defun-sk forall-x-y-p0-and-q0 (z) (forall (x y) (and (p0 x y z) (q0 x y z)))) The intention is to introduce a new predicate [47m(forall-x-y-p0-and-q0 z)[0m which states that the indicated conjunction holds of all [47mx[0m and all [47my[0m together with the given [47mz[0m. This time, the axioms introduced are as shown below. The first event guarantees that if the application of function [47mforall-x-y-p0-and-q0-witness[0m to [47mz[0m picks out values [47mx[0m and [47my[0m for which the given term [47m(and (p0 x y z) (q0 x y z))[0m holds, then the new predicate [47mforall-x-y-p0-and-q0[0m holds of [47mz[0m. Conversely, the (contrapositive of) the second axiom guarantees that if the new predicate holds of [47mz[0m, then the given term holds for all choices of [47mx[0m and [47my[0m (and that same [47mz[0m). (defun-nx forall-x-y-p0-and-q0 (z) (mv-let (x y) (forall-x-y-p0-and-q0-witness z) (and (p0 x y z) (q0 x y z)))) (defthm forall-x-y-p0-and-q0-necc (implies (not (and (p0 x y z) (q0 x y z))) (not (forall-x-y-p0-and-q0 z)))) The examples above suggest the critical property of [47mdefun-sk[0m: it indeed does introduce the quantified notions that it claims to introduce. Notice that the [47m[defthm][0m event just above, [47mforall-x-y-p0-and-q0-necc[0m, may not be of optimal form as a rewrite rule. Users sometimes find that when the quantifier is [47mforall[0m, it is useful to state this rule in a form where the new quantified predicate is a hypothesis instead. In this case that form would be as follows: (defthm forall-x-y-p0-and-q0-necc (implies (forall-x-y-p0-and-q0 z) (and (p0 x y z) (q0 x y z)))) ACL2 will turn this into one [47m:[0m[47m[rewrite][0m rule for each conjunct, [47m(p0 x y z)[0m and [47m(q0 x y z)[0m, with hypothesis [47m(forall-x-y-p0-and-q0 z)[0m in each case. In order to get this effect, use [47m:rewrite :direct[0m, in this case as follows. (defun-sk forall-x-y-p0-and-q0 (z) (forall (x y) (and (p0 x y z) (q0 x y z))) :rewrite :direct) We now turn to a detailed description of [47mdefun-sk[0m, starting with a discussion of its arguments as shown in the "General Form" above. The third argument, [47mbody[0m, must be of the form (Q bound-vars term) where: [47mQ[0m is the symbol [47m[forall][0m or [47m[exists][0m, in the "ACL2" package; [47mbound-vars[0m is a variable or true list of variables disjoint from [47m(var1 ... varn)[0m and not including [47m[state][0m; and [47mterm[0m is a term. The case that [47mbound-vars[0m is a single variable [47mv[0m is treated exactly the same as the case that [47mbound-vars[0m is [47m(v)[0m. The result of this event is to introduce a ``Skolem function,'' whose name is the keyword argument [47mskolem-name[0m if that is supplied, and otherwise is the result of modifying [47mfn[0m by suffixing "-WITNESS" to its name. The following definition (or a corresponding rule; see the discussion of [47m:constrain[0m below) and one of the following two theorems (as indicated) are introduced for [47mskolem-name[0m and [47mfn[0m in the case that [47mbound-vars[0m (see above) is a single variable [47mv[0m. The name of the [47m[defthm][0m event may be supplied as the value of the keyword argument [47m:thm-name[0m; if it is not supplied, then it is the result of modifying [47mfn[0m by suffixing "-SUFF" to its name in the case that the quantifier is [47m[exists][0m, and "-NECC" in the case that the quantifier is [47m[forall][0m. (defun-nx fn (var1 ... varn) (let ((v (skolem-name var1 ... varn))) term)) (defthm fn-suff ;in case the quantifier is EXISTS (implies term (fn var1 ... varn))) (defthm fn-necc ;in case the quantifier is FORALL (implies (not term) (not (fn var1 ... varn)))) In the [47mforall[0m case, however, the keyword pair [47m:rewrite :direct[0m may be supplied after the body of the [47mdefun-sk[0m form, in which case the contrapositive of the above form is used instead: (defthm fn-necc ;in case the quantifier is FORALL (implies (fn var1 ... varn) term)) This is often a better choice for the "-NECC" rule, provided ACL2 can parse [47mterm[0m as a [47m:[0m[47m[rewrite][0m rule. A second possible value of the [47m:rewrite[0m argument of [47mdefun-sk[0m is [47m:default[0m, which gives the same behavior as when [47m:rewrite[0m is omitted. Otherwise, the value of [47m:rewrite[0m should be the term to use as the body of the [47mfn-necc[0m theorem shown above; ACL2 will attempt to do the requisite proof in this case. If that term is weaker than the default, the properties introduced by [47mdefun-sk[0m may of course be weaker than they would be otherwise. Finally, note that the [47m:rewrite[0m keyword argument for [47mdefun-sk[0m only makes sense if the quantifier is [47mforall[0m; it is thus illegal if the quantifier is [47mexists[0m. Enough said about [47m:rewrite[0m! In the case that [47mbound-vars[0m is a list of at least two variables, say [47m(bv1 ... bvk)[0m, the definition above (with no keywords) is the following instead, but the theorem remains unchanged. (defun-nx fn (var1 ... varn) (mv-let (bv1 ... bvk) (skolem-name var1 ... varn) term)) In order to emphasize that the last element of the list, [47mbody[0m, is a term, [47mdefun-sk[0m checks that the symbols [47m[forall][0m and [47m[exists][0m do not appear anywhere in it. However, on rare occasions one might deliberately choose to violate this convention, presumably because [47m[forall][0m or [47m[exists][0m is being used as a variable or because a macro call will be eliminating ``calls of'' [47m[forall][0m and [47m[exists][0m. In these cases, the keyword argument [47mquant-ok[0m may be supplied a non-[47mnil[0m value. Then [47mdefun-sk[0m will permit [47m[forall][0m and [47m[exists][0m in the body, but it will still cause an error if there is a real attempt to use these symbols as quantifiers. The use of [47m[defun-nx][0m above, rather than [47m[defun][0m, disables certain checks that are required for evaluation, for example in the passing of multiple values. However, there is a price: calls of these defined functions cannot be evaluated; see [defun-nx]. Normally that is not a problem, since these notions involve quantifiers. But if you prefer that [47m[defun][0m be used instead of [47mdefun-nx[0m, you can arrange that using [47m[declare][0m forms, given as the [47mdcl_i[0m as shown above. These will become the [47mdeclare[0m forms in the generated [47m[defun][0m. If the [47m[xargs][0m [declaration] form [47m:non-executable nil[0m is supplied, then [47m[defun][0m will be used in place of [47m[defun-nx][0m. [Guard] verification is performed for [47mdefun-sk[0m events under the same conditions as for [47mdefun[0m events. (An exception, ignored here but discussed in a later paragraph below, occurs when keyword argument [47m:constrain t[0m is supplied.) Thus, by default, guard verification will be attempted exactly when at least one of [47mtype[0m, [47m:guard[0m, or [47m:verify-guards t[0m is specified in a declaration (that is, in some [47mdcl_i[0m. This default behavior can be modified just as it is for [47mdefun[0m; see [47m[set-verify-guards-eagerness][0m. Technical note: such guard verification is implemented through a generated call of [47m[verify-guards][0m after the [47mencapsulate[0m that surrounds the definitions introduced; use [47m:[0m[47m[trans1][0m to see the expansion. [47mDefun-sk[0m is a macro implemented using [47m[defchoose][0m. Hence, it should only be executed in [defun-mode] [47m:[0m[47m[logic][0m; see [defun-mode] and see [defchoose]. You can use the command [47m:[0m[47m[pcb!][0m to see the event generated by a call of the [47mdefun-sk[0m macro. If you want to watch the subsidiary events (including the [47mdefchoose[0m event) as they are being executed, use keyword option [47m:verbose t[0m. An advanced feature is argument [47m:strengthen t[0m, which generates the extra constraint that is generated for the corresponding [47mdefchoose[0m event; see [defchoose]. The name of that generated theorem will be obtained by adding the suffix [47m"-STRENGTHEN"[0m to the function symbol being defined, in the same package. If you find that the rewrite rules introduced with a particular use of [47mdefun-sk[0m are not ideal, even when using the [47m:rewrite[0m keyword discussed above (in the [47mforall[0m case), then at least two reasonable courses of action are available for you. Perhaps the best option is to prove the [47m[rewrite][0m rules you want. If you see a pattern for creating rewrite rules from your [47mdefun-sk[0m events, you might want to write a macro that executes a [47mdefun-sk[0m followed by one or more [47m[defthm][0m events. Another option is to write your own variant of the [47mdefun-sk[0m macro, say, [47mmy-defun-sk[0m, for example by modifying a copy of the definition of [47mdefun-sk[0m from the ACL2 sources. There is one more keyword argument not explained above: [47m:constrain[0m. The default is [47mnil[0m; otherwise this argument must be a symbol, which we call [47mname-def[0m, except that in the case of [47mt[0m, [47mname-def[0m is obtained by adding the suffix [47m"-DEFINITION"[0m to [47mfn[0m. For a non-[47mnil[0m [47m:constrain[0m argument, this [47mname-def[0m is the name of a rule of class [47m:[0m[47m[definition][0m that equates [47m(fn var1 ... varn)[0m with the body of the definition of [47mfn[0m. Furthermore, in this case of a non-[47mnil[0m [47m:constrain[0m value the definition of [47mfn[0m is local to the surrounding [47mencapsulate[0m, which contains a signature for [47mfn[0m. As usual, the simplest way to see the effects of [47m:constrain[0m may be to apply [47m:trans1[0m to your [47mdefun-sk[0m form. Note that constraining the function can make it possible to attach to it (see [defattach]) and to introduce it as a [guard]-verified function. Also note that when [47m:constrain t[0m is specified: the guard of [47mfn[0m will automatically be [47mt[0m, no guard verification will be performed, and [47mfn[0m will nevertheless be a guard-verified (and constrained) function. If you want to represent nested quantifiers, you can use more than one [47mdefun-sk[0m event. For example, in order to represent (forall x (exists y (p x y z))) you can use [47mdefun-sk[0m twice, for example as follows. (defun-sk exists-y-p (x z) (exists y (p x y z))) (defun-sk forall-x-exists-y-p (z) (forall x (exists-y-p x z))) Some distracting and unimportant warnings are inhibited during [47mdefun-sk[0m. Note for ACL2(r) users (see [real]): In ACL2(r), the keyword [47m:CLASSICALP[0m is also supported. Its legal values are [47mt[0m (the default) and [47mnil[0m, and it determines whether or not (respectively) ACL2(r) will consider [47mfn[0m to be a classical function. It must be the case that the value is [47mt[0m (perhaps implicitly, by default) if and only if [47mbody[0m is classical. Note that this way of implementing quantifiers is not a new idea. Hilbert was certainly aware of it in the first half of the 20th century! Also see [conservativity-of-defchoose] for a technical argument that justifies the logical conservativity of the [47m[defchoose][0m event in the sense of the paper by Kaufmann and Moore entitled ``Structured Theory Development for a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2 (2001), pp. 161--203). Subtopics [Defun-sk-example] A simple example using [47m[defun-sk][0m [Exists] Existential quantifier [Forall] Universal quantifier [Quantifier-tutorial] A Beginner's Guide to Reasoning about Quantification in ACL2 [Quantifiers] Issues about quantification in ACL2") (defun-sk-example (defun-sk) "A simple example using [47m[defun-sk][0m For a more thorough, systematic beginner's introduction to quantification in ACL2, see [quantifier-tutorial]. The following example illustrates how to do proofs about functions defined with [47m[defun-sk][0m. The events below can be put into a certifiable book (see [books]). The example is contrived and rather silly, in that it shows how to prove that a quantified notion implies itself, where the antecedent and conclusion are defined with different [47m[defun-sk][0m events. But it illustrates the formulas that are generated by [47m[defun-sk][0m, and how to use them. Thanks to Julien Schmaltz for presenting this example as a challenge. (in-package "ACL2") (encapsulate (((p *) => *) ((expr *) => *)) (local (defun p (x) x)) (local (defun expr (x) x))) (defun-sk forall-expr1 (x) (forall (y) (implies (p x) (expr y)))) (defun-sk forall-expr2 (x) (forall (y) (implies (p x) (expr y))))) ; We want to prove the theorem my-theorem below. What axioms are there that ; can help us? If you submit the command ; :pcb! forall-expr1 ; then you will see the following two key events. (They are completely ; analogous of course for FORALL-EXPR2.) ; (DEFUN FORALL-EXPR1 (X) ; (LET ((Y (FORALL-EXPR1-WITNESS X))) ; (IMPLIES (P X) (EXPR Y)))) ; ; (DEFTHM FORALL-EXPR1-NECC ; (IMPLIES (NOT (IMPLIES (P X) (EXPR Y))) ; (NOT (FORALL-EXPR1 X))) ; :HINTS ; (("Goal" :USE FORALL-EXPR1-WITNESS))) ; We see that the latter has value when FORALL-EXPR1 occurs negated in a ; conclusion, or (therefore) positively in a hypothesis. A good rule to ; remember is that the former has value in the opposite circumstance: negated ; in a hypothesis or positively in a conclusion. ; In our theorem, FORALL-EXPR2 occurs positively in the conclusion, so its ; definition should be of use. We therefore leave its definition enabled, ; and disable the definition of FORALL-EXPR1. ; (thm ; (implies (and (p x) (forall-expr1 x)) ; (forall-expr2 x)) ; :hints (("Goal" :in-theory (disable forall-expr1)))) ; ; ; which yields this unproved subgoal: ; ; (IMPLIES (AND (P X) (FORALL-EXPR1 X)) ; (EXPR (FORALL-EXPR2-WITNESS X))) ; Now we can see how to use FORALL-EXPR1-NECC to complete the proof, by ; binding y to (FORALL-EXPR2-WITNESS X). ; We use defthmd below so that the following doesn't interfere with the ; second proof, in my-theorem-again that follows. (defthmd my-theorem (implies (and (p x) (forall-expr1 x)) (forall-expr2 x)) :hints (("Goal" :use ((:instance forall-expr1-necc (x x) (y (forall-expr2-witness x))))))) ; The following illustrates a more advanced technique to consider in such ; cases. If we disable forall-expr1, then we can similarly succeed by having ; FORALL-EXPR1-NECC applied as a :rewrite rule, with an appropriate hint in how ; to instantiate its free variable. See :doc hints. (defthm my-theorem-again (implies (and (P x) (forall-expr1 x)) (forall-expr2 x)) :hints (("Goal" :in-theory (disable forall-expr1) :restrict ((forall-expr1-necc ((y (forall-expr2-witness x))))))))") (defund (defun events) "Define a function symbol and then disable it Use [47mdefund[0m instead of [47m[defun][0m when you want to [disable] a function immediately after its definition in [47m:[0m[47m[logic][0m mode. This macro has been provided for users who prefer working in a mode where functions are only enabled when explicitly directed by [47m:[0m[47m[in-theory][0m. Specifically, the form (defund NAME FORMALS ...) expands to the following, except that some output is inhibited for the [47m[in-theory][0m event: (progn (defun NAME FORMALS ...) (in-theory (disable NAME)) (value-triple '(:defund NAME))). Only the [47m:[0m[47m[definition][0m rule and, for recursively defined functions, the [47m:[0m[47m[induction][0m rule are disabled for the function. In particular, [47mdefund[0m does not disable either the [47m:[0m[47m[type-prescription][0m or the [47m:[0m[47m[executable-counterpart][0m rule. If the function is defined in [47m:[0m[47m[program][0m mode, either because the [default-defun-mode] is [47m:[0m[47m[program][0m or because [47m:mode :program[0m has been specified in an [47m[xargs][0m form of a [47m[declare][0m form, then no [47m[in-theory][0m event is executed. (More precisely, [47m[in-theory][0m events are ignored when the [default-defun-mode] is [47m:[0m[47m[program][0m, and if [47m:mode :program[0m is specified then [47mdefund[0m does not generate an [47m[in-theory][0m event.) [47mDefund[0m events are generally not redundant, because the generated [47m[in-theory][0m event is not redundant. This default can be changed; see [set-in-theory-redundant-okp]. See [defun] for documentation of [47mdefun[0m.") (defund-inline (defun events) "Define a potentially disabled, inlined function symbol and associated macro [47mDefund-inline[0m is a variant of [47m[defun-inline][0m, the difference being that [47mdefund-inline[0m disables the newly-defined function symbol. See [defun-inline].") (defund-notinline (defun events) "Define a disabled, not-to-be-inlined function symbol and associated macro [47mDefund-notinline[0m is a variant of [47m[defun-notinline][0m, the difference being that [47mdefund-notinline[0m disables the newly-defined function symbol. See [defun-notinline].") (defund-nx (defun events) "Define a disabled non-executable function symbol Use [47mdefund-nx[0m instead of [47m[defun-nx][0m when you want to [disable] the definition of a function symbol immediately after defining it in [47m:[0m[47m[logic][0m mode. In all other respects, [47mdefund-nx[0m has the same behavior as [47mdefun-nx[0m; See [defun-nx] for details. Also see [defund].") (defuns (mutual-recursion) "An alternative to [47m[mutual-recursion][0m Example: (DEFUNS (evenlp (x) (if (consp x) (oddlp (cdr x)) t)) (oddlp (x) (if (consp x) (evenlp (cdr x)) nil))) General Form: (DEFUNS defuns-tuple1 ... defuns-tuplen) is equivalent to (MUTUAL-RECURSION (DEFUN . defuns-tuple1) ... (DEFUN . defuns-tuplen)) In fact, [47mdefuns[0m is the more primitive of the two and [47m[mutual-recursion][0m is just a macro that expands to a call of [47mdefuns[0m after stripping off the [47m[defun][0m at the [47m[car][0m of each argument to [47m[mutual-recursion][0m. We provide and use [47m[mutual-recursion][0m rather than [47mdefuns[0m because by leaving the [47m[defun][0ms in place, [47m[mutual-recursion][0m forms can be processed by the Emacs [47mtags[0m program. See [mutual-recursion].") (defwarrant (apply$ acl2-built-ins) "Issue a warrant for a function so [47m[apply$][0m can use it in proofs It is best to be somewhat familiar with the documentation of [47m[apply$][0m before reading this topic. Before using [47mdefwarrant[0m or a utility like [47m[defun$][0m that relies on it: (include-book "projects/apply/top" :dir :system) Several lemmas in that book are necessary for [47mdefwarrant[0m to prove the theorems it must prove. Badges versus Warrants It is easy to confuse [badge]s, which are issued by [47m[defbadge][0m, with [warrant]s, which are issued by [47mdefwarrant[0m. See the first section of [47m[defbadge][0m for an extended discussion. Requirements of [47mDefwarrant[0m General Form: (defwarrant fn) where [47mfn[0m is a defined function name. This command analyzes the body of [47mfn[0m to determine whether it satisfies certain stringent syntactic and semantic conditions that allow the ACL2 proof theory to be extended so that the prover can simplify forms like [47m(apply$ 'fn ...)[0m. The syntactic conditions include those of [47m[defbadge][0m, which [47mdefwarrant[0m essentially invokes if [47mfn[0m is a [47m:[0m[47m[logic][0m mode function that is not already badged. But below we describe all the conditions checked by [47mdefwarrant[0m since many users use [47mdefwarrant[0m to issue both a badge and a warrant. Basic conditions include that [47mfn[0m is in [47m:[0m[47m[logic][0m-mode and that its justification (i.e., the measure, well-founded relation, and domain predicate used to admit [47mfn[0m) be expressible without any reference to [47m[apply$][0m, [47m[ev$][0m, or [47m[apply$-userfn][0m. [47mDefwarrant[0m imposes some additional conditions on [47mfn[0m, but exactly what those conditions are depends on a certain ``reachability'' test detailed in the section titled [31;1mThe ``Reachability'' Test[0m in [47m[defbadge][0m. Roughly speaking the test is whether [47mapply$[0m is ancestral in [47mfn[0m, meaning [47mapply$[0m is somehow involved in the definition of [47mfn[0m or the functions it calls. If the reachability test succeeds --- colloquially, if [47mfn[0m depends on [47mapply$[0m --- then [47mdefwarrant[0m imposes the following additional conditions in order to issue a warrant. [3m(a)[0m If [47mfn[0m is recursive it must not be part of a mutually recursive clique and its measure must be of type [47m[natp][0m or be a lexicographic combination of natural numbers as defined by the [47mllist[0m function in the Community Books at [47mbooks/ordinals/[0m. [3m(b)[0m Every function called in the body of [47mfn[0m, except [47mfn[0m itself, must already have a [badge] and a warrant. If some subfunction doesn't already have a badge, [47mdefwarrant[0m will call [47m[defbadge][0m and signal an error if that fails. If some subfunction doesn't already have a warrant, [47mdefwarrant[0m will signal an error and suggest that you call [47mdefwarrant[0m on the offending subfunction first. [47mDefwarrant[0m will continue to fail until all subfunctions have badges and warrants. [3m(c)[0m It must be possible for each formal of [47mfn[0m to be assigned one of three [ilk]s, [47m:FN[0m, [47m:EXPR[0m, or [47mNIL[0m, as described below. The basic idea is that a formal can be assigned ilk [47m:FN[0m (or ilk [47m:EXPR[0m) iff it is sometimes passed into a [47m:FN[0m (or [47m:EXPR[0m) slot in the body of [47mfn[0m and is never passed into any other kind of slot. A formal can be be assigned ilk [47mNIL[0m iff it is never passed into a slot of ilk [47m:FN[0m or [47m:EXPR[0m, i.e., if it is used as an ``ordinary'' object. We are more precise below. [3m(d)[0m Every [47m:FN[0m and [47m:EXPR[0m slot of every function called in the body of [47mfn[0m is occupied either by a formal of [47mfn[0m of the same ilk or, in the case of calls of functions other than [47mfn[0m, a quoted [tame] function symbol or quoted tame (preferably well-formed) [47mLAMBDA[0m object. This completes the list of additional restrictions imposed by [47mdefwarrant[0m on [47mfn[0m, when [47mapply$[0m is reachable from [47mfn[0m. If the reachability test fails --- colloquially, if [47mfn[0m does not depend on [47mapply$[0m --- then [47mdefwarrant[0m just checks that [47mfn[0m does not call any of a few functions that [47mapply$[0m is prohibited from running. Among those blacklisted functions are [47m[sys-call][0m and other functions requiring a trust tag. For a list of the blacklisted functions see the value of [47m*blacklisted-apply$-fns*[0m. Note that the restrictions imposed on functions from which [47mapply$[0m cannot be reached are comparatively generous. If [47mfn[0m does not depend on [47mapply$[0m then [47mfn[0m can be warranted despite (a) being defined mutually recursively or with an arbitrary ordinal measure, or (b) calling unbadged or unbadgeable functions. [47mDefwarrant[0m can be relaxed in this case because the warrant constrains [47m(apply$ 'fn ...)[0m to be [47m(fn ...)[0m and [47mfn[0m is a well-defined [47m:logic[0m mode function that is independent of [47mapply$[0m. Thus, in the model of [47mapply$[0m that justifies the whole [47mapply$[0m story, the handling of [47mfn[0m is just a base case. The situation would be more restrictive if the warrant constrained [47m(apply$ 'fn ...)[0m to evaluate the body of [47mfn[0m with [47m[ev$][0m which would possibly raise termination issues. Regardless of whether [47mapply$[0m is reachable, if the requisite conditions are not met, [47mdefwarrant[0m causes an error. If the requisite conditions are met, [47mdefwarrant[0m obtains or constructs the [badge] for [47mfn[0m, setting the arity and out arity appropriately and setting the ilks field to the list of computed ilks (or to [47mT[0m if every formal has ilk [47mNIL[0m). The generated badge is stored for the future use of [47mdefwarrant[0m. See [47m[defbadge][0m for a brief discussion of how ilks are computed. Furthermore, [47mdefwarrant[0m generates the [47m[warrant][0m for [47mfn[0m. The name of that 0-ary function will be [47mAPPLY$-WARRANT-fn[0m. Calls of [47m[apply$][0m on [47m'fn[0m in proof attempts can only be simplified if the warrant hypothesis, [47m(APPLY$-WARRANT-fn)[0m, [3maka[0m ``the warrant,'' is among the hypotheses of the conjecture being proved. The warrant specifies the values of both [47m(badge 'fn)[0m and [47m(apply$ 'fn ...)[0m, including the tameness requirements imposed on [47mapply$[0m. (The warrant explicitly specifies the values of [47m[badge-userfn][0m and [47m[apply$-userfn][0m and then [47m[defwarrant][0m proves rewrite rules to make calls of [47mbadge[0m and [47mapply$[0m simplify accordingly.) If a warrant is issued for [47mfn[0m, then [47mdefwarrant[0m also extends ACL2's evaluation theory (but not its proof theory) so that the warrant hypothesis is assumed true in that theory, allowing calls of [47mbadge[0m and [47mapply$[0m to be evaluated in the evaluation theory (but not in the proof theory). See [47m[warrant][0m for details. You might worry that theorems burdened by warrants are vacuously valid because it might be impossible to satisfy all the warrant hypotheses. You needn't worry about this. [3mThere is a model of [47mapply$[0m[3m and all of its [47m[scion][0m[3ms that makes every warrant issued by [47mdefwarrant[0m[3m valid.[0m The proof of this is sketched in {``Limited Second-Order Functionality in a First-Order Setting'' | http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore and fully fleshed out in the comment titled [47mEssay on Admitting a Model for Apply$ and the Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m. [47mDefwarrant[0m also proves that [47m[fn-equal][0m is a congruence relation for each [47m:FN[0m position of [47mfn[0m. Subtopics [Fn-equal] Equivalence relation on tame functions") (delete-assoc (alists acl2-built-ins) "Deprecated version of [remove1-assoc] See [remove1-assoc].") (delete-file$ (io) "Delete a file This analogue of the Common Lisp function, [47mdelete-file[0m, uses that function under the hood to delete a given file. It returns [47m(mv t state)[0m if deletion succeeds and [47m(mv nil state)[0m otherwise. The [47m[guard][0m of [47mdelete-file$[0m requires that the first argument is a string; the second argument is the ACL2 [47m[state][0m. The logical definition does not actually look at the file and hence is not useful for reasoning. [31;1mFunction: [0m<delete-file$> (defun delete-file$ (file state) (declare (xargs :guard (stringp file) :stobjs state)) (declare (ignore file)) (mv-let (erp val state) (read-acl2-oracle state) (declare (ignore val)) (mv (null erp) state)))") (delete-include-book-dir (books-reference) "Unlink keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m Example Forms: ; Remove association of a directory with :smith for include-book and ld: (delete-include-book-dir :smith) General Form: (delete-include-book-dir kwd) where [47mkwd[0m is a [47m[keywordp][0m. The effect of this event is to modify the meaning of the [47m:dir[0m keyword argument of [47m[include-book][0m and [47m[ld][0m as indicated by the example above, namely by removing association of a directory with the indicated keyword for purposes of the [47m:dir[0m argument of [47m[include-book][0m and [47m[ld][0m. See [47m[add-include-book-dir][0m for how to associate a new directory with a keyword. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. This macro is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [add-include-book-dir] for a discussion of this aspect of both macros. For non-local associations of keywords with directories, see [add-include-book-dir!] and [delete-include-book-dir!]. Note that [47mdelete-include-book-dir[0m may only be used to remove keywords added by calls of [47m[add-include-book-dir][0m, and [47m[delete-include-book-dir!][0m may only be used to remove keywords added by calls of [47m[add-include-book-dir!][0m") (delete-include-book-dir! (books-reference) "Non-[47m[local][0mly unlink keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m Please see [delete-include-book-dir], which has completely analogous syntax and semantics, but is used for removing associations previously placed by [47m[add-include-book-dir][0m. By contrast, [47mdelete-include-book-dir![0m removes associations previously placed by [47m[add-include-book-dir!][0m. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. This macro is essentially a [47m[table][0m event that updates the table [47minclude-book-dir!-table[0m, which associates keywords with absolute pathnames. However, as with [47m[delete-include-book-dir][0m, direct table updates are disallowed; you must use [47mdelete-include-book-dir![0m to remove from the table and [47m[add-include-book-dir!][0m to add to the table. It is illegal to call [47mdelete-include-book-dir![0m in a [47m[local][0m context. For an explanation, see [add-include-book-dir!].") (denominator (numbers acl2-built-ins) "Divisor of a ratio in lowest terms Completion Axiom ([47mcompletion-of-denominator[0m): (equal (denominator x) (if (rationalp x) (denominator x) 1)) [Guard] for [47m(denominator x)[0m: (rationalp x)") (df (numbers acl2-built-ins) "Support for floating-point operations ACL2 supports computation that uses floating-point operations. The basic arithmetic operations ([47m+[0m, [47m-[0m, [47m*[0m, and [47m/[0m) in Common Lisp can be much faster when applied to floating-point numbers than to rational numbers. Moreover, the floating-point operations include transcendental operations such as the sine function. All floating-point computations performed by Common Lisp for ACL2 use [3mdouble-floats[0m, that is, double-precision floating-point numbers. Computation with other precisions (including single-precision) is not supported by ACL2. Note: ACL2 novices are advised to skip this topic and program with ordinary ACL2 rationals rather than taking advantage of ACL2 support for floating-point operations. The syntactic restrictions described below are somewhat like those for single-threaded objects, known as [stobj]s, so although familiarity with stobjs is not assumed, that familiarity may be helpful for understanding ACL2 support for floating-point computations. (But for expressions denoting floating-point computations, unlike those involving stobjs, there is no restriction to single instances and there are no destructive operations.) This topic is organized as follows. The Introduction may suffice for those eager to start playing with ACL2's version of floating-point operations. The second section presents challenges for supporting floating-point operations in ACL2, and the third section outlines how ACL2 addresses those challenges. A key enabler for ACL2 support of floating-point operations is how it restricts their use syntactically, and this is discussed in Section 4. Section 5 discusses guards. Section 6 documents the built-in ACL2 functions and macros that involve floating-point operations. Section 7 makes some remarks on performance. Finally, Section 8 covers more aspects of ACL2 support for floating-point operations by presenting highlights of a substantial file of relevant examples: the [community-book], [47mbooks/demos/floating-point-input.lsp[0m. We conclude in Section 9 with remarks for system programmers. This topic is written for ACL2 users. Implementation-level remarks for developers may be found in a comment in the ACL2 sources entitled ``Essay on Support for Floating-point (double-float, df) Operations in ACL2''. Section 1: Introduction ACL2 differs from Common Lisp by imposing syntactic restrictions on expressions that represent floating-point computations, to ensure that these computations respect the ACL2 axioms. Those expressions are called [3mdf expressions[0m, or [3mdfs[0m for short. ACL2 may also say that such an expression ``returns a result of shape :DF''. With those restrictions, ACL2 supports computations with double-precision floating-point numbers without adding a floating-point data type to the logic. Rather, ACL2 logically treats df expressions as returning rational numbers that are [3mrepresentable[0m by floating-point numbers. For example, there is no floating-point number 1.5 in the ACL2 logic; rather, the Common Lisp value 1.5 represents the rational number 3/2, which is an ACL2 object, and the df expression [47m(to-df 3/2)[0m is provably equal to the constant 3/2 in the logic, even though evaluation of [47m(to-df 3/2)[0m in Common Lisp returns the double-float 1.5. Discussion below further explains dfs in ACL2, but for starters let's consider the following example. (defun f1 (x) (declare (type double-float x)) (df- x)) ACL2 admits this definition so that [47mf1[0m is a [guard]-verified function. The operation [47mdf-[0m is essentially just the negative operation ([47m-[0m), except that [47mdf-[0m is to be applied only to df expressions; this is enforced based on the [47mdouble-float[0m type declaration. Let's look at what happens when we [trace] [47mf1[0m; discussion follows. In the following example, [47mf1[0m is applied to the df expression [47m(to-df 3/2)[0m; the expression [47m(f1 3/2)[0m would be illegal for top-level evaluation because, as noted above, [47mf1[0m expects a df expression, ACL2 !>(trace$ f1 to-df) ((F1) (TO-DF)) ACL2 !>(f1 (to-df 3/2)) 1> (ACL2_*1*_ACL2::TO-DF 3/2) <1 (ACL2_*1*_ACL2::TO-DF 3/2) 1> (ACL2_*1*_ACL2::F1 3/2) 2> (F1 1.5) <2 (F1 -1.5) <1 (ACL2_*1*_ACL2::F1 -3/2) #d-1.5 ACL2 !> Initially, the function [47mto-df[0m is applied to 3/2. The result is logically still 3/2, not 1.5, because the [3mexecutable-counterpart[0m for [47mto-df[0m returns an ACL2 value, not a Common Lisp value. (See [evaluation] for background on executable-counterparts and corresponding raw Lisp functions.) Then 3/2 is passed to the executable-counterpart for [47mf1[0m. The [guard] of [47mf1[0m holds on 3/2 (we'll discuss guards later), so evaluation passes from the executable-counterpart for [47mf1[0m to the raw Lisp function for [47mf1[0m after converting 3/2 to a Common Lisp double-precision floating-point number, 1.5. Then [47mdf-[0m, which is essentially just [47m-[0m in raw Lisp, is applied to obtain -1.5, which is returned by raw-Lisp [47mf1[0m. Then the executable-counterpart for [47mf1[0m converts -1.5 to the corresponding ACL2 object, the rational -3/2, which is ultimately returned to the top-level loop. Remark. The astute reader may have noticed that the executable-counterpart for [47mto-df[0m did not call the raw Lisp function for [47mto-df[0m. That is because [47mto-df[0m is actually a macro in raw Lisp. Section 2: Challenges for supporting floating-point operations in ACL2 In this section we motivate ACL2 restrictions pertaining to floating-point numbers, which are addressed in the section after this one. We start with examples that show why ACL2 cannot allow some common operations to be applied to floating-point numbers. We illustrate using computations in raw Lisp; this is relevant since, as noted above, raw-Lisp computation supports [evaluation] of [guard]-verified code. [31;1mProblem #1[0m: Addition isn't associative on floating-point numbers. We see that immediately with the following raw Lisp examples. ? (+ 0.1 (+ 0.2 0.3)) 0.6 ? (+ (+ 0.1 0.2) 0.3) 0.6000000000000001 ? Yet ACL2 has the following axiom. [31;1mDefinition: [0m<associativity-of-+> (defaxiom associativity-of-+ (equal (+ (+ x y) z) (+ x (+ y z)))) So we can't simply apply [47m+[0m to floating-point numbers in ACL2, because [guard]-verified code leads to raw Lisp computations that would violate this axiom. [31;1mProblem #2[0m: Functions [47mEQUAL[0m and [47m=[0m are logically the same in ACL2 but not in raw Lisp. The following succeeds. (thm (equal (equal x y) (= x y))) Yet the following log shows that raw Lisp can violate that property if we allow double-floats. (In Common Lisp, [47m=[0m compares numeric values while [47mEQUAL[0m distinguishes between rationals and floats and even between floating-point numbers 0.0 and -0.0.) ? (equal 1 1.0) NIL ? (= 1 1.0) T ? (equal 0.0 (- 0.0)) NIL ? (= 0.0 (- 0.0)) T ? Section 3: How the challenges are addressed The following three principles guide support for floating-point computations in ACL2. * (A) Treat floating-point values as rationals. * (B) Put syntactic limitations on floating-point operations. * (C) Use [partial-encapsulate] to axiomatize floating-point operations while supporting evaluation. Let's look at these in turn. [31;1m(A) Treat floating-point values as rationals.[0m The ACL2 logic does not include floating-point numbers. Rather, certain rational numbers can be [3mrepresented by[0m double-precision floating-point numbers, known as double-floats, during computations. We can say that a double-float [3mrepresents[0m a corresponding rational number. Certain expressions denote such [3mrepresentable[0m rational numbers. Those are called [3mdf expressions[0m and we say more about them in our discussion of (B), below. The predicate [47mdfp[0m recognizes those rational numbers that have a floating-point representation. We do not review floating-point numbers here, other than to note that a floating-point number is equal to a binary significand between 1 and 2 times 2 to a power, such as as [47m1.01100 * 2^30[0m. For example, 1/4 is representable but 1/3 is not. ACL2 !>(dfp 1/4) ; represented by the double-float, 0.25d0 T ACL2 !>(dfp 1/3) ; not represented by a double-float NIL ACL2 !> ACL2 provides [47m#d[0m notation (see [sharp-d-reader]) as a way to read floating-point notation as a representable rational, illustrated as follows. ACL2 !>#d0.25 1/4 ACL2 !>#d3.5 7/2 ACL2 !>#d3.1 6980579422424269/2251799813685248 ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (= 3.1 6980579422424269/2251799813685248) T ? Although ACL2 simulates floating-point values with rationals, we see below how raw Lisp computation can actually use floating-point arithmetic on double-precision floating-point numbers. [31;1m(B) Put syntactic limitations on floating-point operations.[0m Here we briefly discuss syntactic restrictions based on the notion mentioned above of [3mdf expression[0m, or [3mdf[0m for short. A more complete discussion is in the section below on Syntactic Restrictions. With those restrictions, ACL2 supports computations with double-precision floating-point numbers without adding a floating-point data type to the logic. Informally, a df expression is one that computes in raw Lisp to a double-float. Let us return to the following example. It uses [47mdf-[0m, which is the negative operation on dfs; that is, [47m(df- x)[0m is analogous to [47m(- x)[0m, but [47mdf-[0m operates on a df and returns a df. ACL2 !>(defun f1 (x) (declare (type double-float x)) (df- x)) Since F1 is non-recursive, its admission is trivial. We observe that the type of F1 is described by the theorem (RATIONALP (F1 X)). We used the :type-prescription rule BINARY-DF+. (F1 :DF) => :DF. Computing the guard conjecture for F1.... The guard conjecture for F1 is trivial to prove. F1 is compliant with Common Lisp. Summary Form: ( DEFUN F1 ...) Rules: ((:TYPE-PRESCRIPTION BINARY-DF+)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) F1 ACL2 !> Notice the signature shown above for [47mf1[0m: (F1 :DF) => :DF This means that the input of [47mf1[0m must be a df expression and [47mf1[0m returns a df expression. ACL2 determines that the input must be a df by virtue of the declaration, [47m(type double-float x)[0m. Calls of [47mf1[0m are determined to be dfs because the body of [47mf1[0m, [47m(df- x)[0m, is a df. One can say that ACL2 engages in a limited form of strong typing to identify certain inputs and outputs of a function symbol as dfs. Those familiar with [stobj]s may notice some similarity to the syntactic restrictions on stobjs. The following example illustrates the requirement that the input of [47mf1[0m be a df. ACL2 !>(f1 3) ACL2 Error [Translate] in TOP-LEVEL: The form 3 represents an ordinary object, but it is being used where a form representing a :DF was expected. See :DOC df. Note: this error occurred in the context (F1 3). ACL2 !> That error can be avoided by converting the input (a rational constant) to a suitable df using the primitive, [47mto-df[0m (discussed later). ACL2 !>(f1 (to-df 3)) #d-3.0 ACL2 !> Notice that the result is displayed using [47m#d[0m notation. But remember that there are no actual floating-point objects in ACL2; [47mf1[0m returns a rational logically, namely -3. However, since the input expression is a df, ACL2 prints the evaluation result using [47m#d[0m notation. (This is analogous to the special printing of [47m<state>[0m when the ACL2 state is returned, and similarly for user-defined stobjs.) To see that the logical value returned is truly 3, note that the following event is admitted by ACL2: [47m(thm (equal (f1 (to-df 3)) -3))[0m. The tracking of dfs avoids Problem #1 above, that addition isn't associative on floating-point numbers. That's because ACL2 does not allow [47m+[0m to be applied to a df, as illustrated by the following example, which complains that the [47m+[0m operation is being supplied a df, namely the call of [47mf1[0m. The notion ``a result of shape :DF'' is synonymous with ``df''. ACL2 !>(+ 5 (f1 (to-df 3))) ACL2 Error [Translate] in TOP-LEVEL: It is illegal to invoke F1 here because of a signature mismatch. This function call returns a result of shape :DF where a result of shape * is required. Note: this error occurred in the context (F1 (TO-DF 3)). ACL2 !> There is however an operation [47mdf+[0m that can be applied to [47m:DF[0m expressions. ACL2 !>(df+ (to-df 5) (f1 (to-df 3))) #d2.0 ACL2 !> In fact [47mdf+[0m automatically converts its arguments satisfying [47mdfp[0m to be dfs, so the following is also legal since [47m5[0m is converted to [47m(to-df 5)[0m. ACL2 !>(df+ 5 (f1 (to-df 3))) #d2.0 ACL2 !> But [47mdf+[0m is not associative; the following fails, as it should. (thm ; FAILS! (implies (and (dfp x) (dfp y) (dfp z)) (equal (df+ (df+ x y) z) (df+ x (df+ y z))))) We return now to Problem #2, that the functions [47mEQUAL[0m and [47m=[0m are logically the same in ACL2 but not in raw Lisp, as seen by evaluation in raw Lisp, where [47m(equal 1 1.0)[0m evaluates to [47mnil[0m but [47m(= 1 1.0)[0m evaluates to [47mt[0m. This problem is avoided by our syntactic tracking of df expressions. The following example shows that [47mequal[0m cannot be called on a df expression. ACL2 !>(equal 1 (to-df 1)) ACL2 Error [Translate] in TOP-LEVEL: It is illegal to invoke TO-DF here because of a signature mismatch. This function call returns a result of shape :DF where a result of shape * is required. Note: this error occurred in the context (TO-DF 1). ACL2 !> One cannot directly test equality of a non-df expression with a df expression, but one can compare equality of two df expressions, as the following example illustrates. (This example also illustrates that addition is commutative on dfs; we will return elsewhere to this point.) ACL2 !>(df= (df+ #d1.2 #d3.4) (df+ #d3.4 #d1.2)) T ACL2 !> [31;1m(C) Use [partial-encapsulate] to axiomatize floating-point operations while supporting evaluation.[0m Next we consider how ACL2 introduces the [3mdf primitives[0m, that is, built-in functions and macros that take or return a df. Their calls may be executed by calling corresponding Common Lisp functions. But axiomatizing these primitives presents a challenge since the Common Lisp language doesn't quite tie down the values returned by floating-point operations. Here is a {relevant quote from the Common Lisp HyperSpec | http://www.lispworks.com/documentation/lw71/CLHS/Body/v_featur.htm} about the presence of a raw Lisp ``feature'', [47m:ieee-floating-point[0m. If present, indicates that the implementation purports to conform to the requirements of IEEE Standard for Binary Floating-Point Arithmetic. ACL2 checks at build time that this feature is present. However, that IEEE standard specifies results of operations with respect to a [3mrounding mode[0m. Probably most or all Common Lisp implementations use [3mround to nearest even[0m as their rounding mode, but this is not guaranteed. We work around this problem to some extent by introducing a constrained rounding function, [47mdf-round[0m, and using it to define the rational function primitives: addition ([47mdf+[0m), subtraction ([47mdf-[0m), multiplication ([47mdf*[0m), and division ([47mdf/[0m). Transcendental functions, such as the sine function, are not as straightforward to define in terms of rounding. Although the sine function, for example, might be defined by rounding a sufficiently large Taylor approximation, transcendental functions are constrained with minimal axioms (at least for now); for example, the sine function is implemented by the constrained function, [47mdf-sin[0m. Over time some of those constraints may be strengthened, or they may even be replaced by definitions in terms of [47mdf-round[0m. Even though the df primitives are constrained (except for the rational primitive functions, which are defined in terms of the constrained function [47mdf-round[0m), ACL2 can evaluate their calls, even during proofs. This is arranged by introducing them with [47m[partial-encapsulate][0m, which allows some of the constraints to be implicit; see [47m[partial-encapsulate][0m. The implicit constraints are based on computation; for example, when ACL2 admits the event [47m(thm (equal (df-sin 0) 0))[0m, an implicit constraint guarantees [47m(equal (df-sin 0) 0)[0m. There are also explicit constraints, which for example allow ACL2 to prove [47m(dfp (df-sin x))[0m. We do not explain further here, but the interested reader is welcome to examine relevant comments in the ACL2 source code, for example in the [47mpartial-encapsulate[0m event that introduces [47mdf-round[0m in ACL2 source file [47mfloat-a.lisp[0m. ACL2 arranges for the host Lisp to evaluate calls of df primitives in [guard]-verified) and [47m:[0m[program]-mode code. For example, such evaluation of a [47mdf-sin[0m call leads to a call of [47msin[0m in Common Lisp. The following log illustrates this point and is discussed below. ACL2 !>(defun f2 (x) (declare (type double-float x)) (df-sin x)) Since F2 is non-recursive, its admission is trivial. We observe that the type of F2 is described by the theorem (RATIONALP (F2 X)). We used the :type-prescription rule RATIONALP-DF-SIN-FN. (F2 :DF) => :DF. Computing the guard conjecture for F2.... The guard conjecture for F2 is trivial to prove. F2 is compliant with Common Lisp. Summary Form: ( DEFUN F2 ...) Rules: ((:TYPE-PRESCRIPTION RATIONALP-DF-SIN-FN)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.00) F2 ACL2 !>(trace$ f2) ((F2)) ACL2 !>(trace! (sin :native t)) TTAG NOTE: Adding ttag :TRACE! from the top level loop. ACL2 !>(f2 (df/ (df-pi) 2)) 1> (ACL2_*1*_ACL2::F2 884279719003555/562949953421312) 2> (F2 1.5707963267948966) 3> (SIN 1.5707963267948966) <3 (SIN 1.0) <2 (F2 1.0) <1 (ACL2_*1*_ACL2::F2 1) #d1.0 ACL2 !> We see at ``[47m1>[0m'' that evaluation arranged to pass a (representable) rational number (roughly, \pi/2) to the executable-counterpart for [47mf2[0m (again, for relevant background see [evaluation]). But at ``[47m2>[0m'', where evaluation was passed to the raw Lisp function for [47mf2[0m, that rational value was converted to the corresponding double-float value, which raw Lisp evaluation passed to the Common Lisp function [47msin[0m, at ``[47m3>[0m''. Common Lisp then returned 1.0 for the raw Lisp applications of [47msin[0m and [47mf2[0m, so that finally, the executable-counterpart for [47mf2[0m returned the rational number, 1. That value was displayed using [47m#d[0m notation because a call of [47mf2[0m is a df. Since rounding (to nearest even, in particular) is not tied down by the Common Lisp language, different host Lisp implementations may give different results. This leads us to the following point of emphasis. When a collection of books is certified (see [certify-book]), the same environment --- in particular the Lisp implementation and operating system --- should be used for all of these books, even those included during certification. Otherwise there is a soundness issue. One might prove, say, [47m(equal (df-sin 1) A)[0m and [47m(equal (df-sin 1) B)[0m for distinct (but close by) numeric values [47mA[0m and [47mB[0m in two different books, certified with ACL2 executables built on different Lisps, and then include those two books to prove a contradiction. Section 4: Syntactic Restrictions We now present more details on the syntactic restrictions pertaining to df expressions (dfs). Our discussion is still informal but it should suffice for the successful use of dfs in ACL2. (Optional technical note for those familiar with ACL2 source function [47mtranslate11[0m: a df is an expression whose translation is made with stobjs-out equal to [47m(:DF)[0m, and the arguments of a function call are those in a [47m:DF[0m position with respect to that function symbol's stobjs-in.) These syntactic restrictions are not applied in theorem and non-executable contexts, in particular not within [defthm], [thm], and [47m[defun-nx][0m events and not within a call of [47m[non-exec][0m. Below we focus on restrictions for a [47m[defun][0m event, including its body, guard, and measure; but these restrictions also apply to [47m[defmacro][0m events, [47m[defconst][0m events, and top-level evaluation. Certain variables may be specified as dfs at the top level in the case of [47mdefun[0m events but not in other cases. For a [47mdefun[0m event, the [3mdeclared dfs[0m consist of all variables [47mvi[0m listed either in a [47m[declare][0m form [47m(type double-float v1 ... vk)[0m or an [47m[xargs][0m declaration [47m:dfs (v1 ... vk)[0m. If [47mk[0m is [47m1[0m then one may write [47m:dfs v1[0m to abbreviate [47m:dfs (v1)[0m. These declared dfs are the [3mknown df variables[0m at the top level of the user-supplied body, guard, and measure of [47mf[0m. The rules below indicate, for a set [47mV[0m of known df variables, when an expression is a df with respect to [47mV[0m; and these rules also speak to legality of certain expressions. Before presenting those rules, we extend the notion of a df expression (again, df for short) to that of a [3mdf{i} expression[0m ([3mdf{i}[0m for short). Such an expression is one that returns multiple values when the ith value is to be considered a df. For example, the expression [47m(mv (to-df x) (df- y) 17)[0m is a df{0} expression and a df{1} expression but not a df{2} expression. Note that an expression that returns a single value might or might not be a df expression, but it is never a df{i} expression for any i; and similarly, an expression that returns multiple values maybe a df{i} expression for various i but it is never a df expression. Here are the rules promised above. They are not complete; for example, they do not cover [47m[stobj-let][0m expressions. But those and other cases should present no surprises in practice. Let [47mu[0m be a user-supplied term (that is, an [3muntranslated[0m term; see [term]). * If [47mu[0m is a variable, then [47mu[0m is a df with respect to [47mV[0m if and only if it is in [47mV[0m. * If [47mu[0m is a constant symbol then it is not a df (with respect to any set). * If [47mu[0m is a [47m[lambda][0m expression, then [47mu[0m is a df with respect to [47mV[0m if and only if the corresponding [47m[let][0m expression is a df with respect to [47mV[0m. * If [47mu[0m is a macro call [47m(m t1 ... tn)[0m, then [47mu[0m is a df with respect to [47mV[0m if and only if the single-step macroexpansion of [47mu[0m is a df with respect to [47mV[0m. * Suppose [47mu[0m is the term [47m(f t1 ... tn)[0m where [47mf[0m is a function symbol. It is required that [47mti[0m is a df with respect to [47mV[0m if and only if the [47mi[0mth formal of [47mf[0m is a declared df of [47mf[0m. An exception to that requirement is when [47mf[0m is [47mdfp[0m, in which case the only restriction on [47mt1[0m is that it is not a stobj name. If [47mf[0m returns a single value then [47mu[0m is a df (respectively, df{i}) with respect to [47mV[0m if and only if the body of [47mf[0m is a df (respectively, df{i}) with respect to [47mV[0m. * Consider [47m(let ((x1 e1) ... (xk ek)) dcl1 ... dclm body)[0m. The rules apply to each [47mei[0m with respect to [47mV[0m, but for [47mbody[0m the rules apply with respect to the following new set of known dfs. First, remove all [47mxi[0m from [47mV[0m except when [47mxi[0m is declared as a df in one of the [47mdcli[0m with a [47mdouble-float[0m type declaration. For any [47mxi[0m not so declared, ACL2 guesses whether or not [47mei[0m is a df with respect to [47mV[0m. If the guess is ``yes'' then add [47mxi[0m as a known df, and if the guess is ``no'' then do not add it. Otherwise, the guess fails to yield an answer, in which case ACL2 can try both ways: first it attempts to treat (technically, translate) [47mei[0m as a non-df and, if that fails, it treats [47mei[0m as a df. (However, the guess almost always works; in particular, for a function call it just looks up the function's signature, except for a recursive call of a function being defined.) * For [47m(mv-let (x1 ... xk) mv-expr dcl1 ... dclm body)[0m, the rules apply to [47mmv-expr[0m and to [47mbody[0m, but for [47mbody[0m the known dfs are modified as follows. ACL2 attempts to determine those i <= k for which [47mmv-expr[0m is a df{i} expression. (Optional technical note for those familiar with ACL2 source function [47mtranslate11[0m: ACL2 attempts to determine suitable stobjs-out for translation of [47mmv-expr[0m.) Then to obtain the known dfs for [47mbody[0m, each [47mxi[0m is initially removed from [47mV[0m except for those [declare]d in some [47mdcli[0m as having type [47mdouble-float[0m, and then those [47mxi[0m for which [47mmv-expr[0m is a df{i} expression are added back as known dfs for translation of [47mbody[0m. Note that ACL2 features that naturally traffic in ordinary ACL2 values may disallow uses of df expressions (much as they disallow uses of [stobj]s). Here are a few examples. * A [table] guard must return an ordinary value, not a df. * A [clause-processor] must return an ordinary value (and perhaps stobjs in the multiple-values case; see [clause-processor]). * A [theory] expression, as well as the argument of [47m[defconst][0m, [47m[defpkg][0m, [47m[syntaxp][0m, or [47m[bind-free][0m, must return an ordinary value, not a df. Section 5: Guards When a [47m[defun][0m event defines a function, the [guard] for that function asserts that [47mdfp[0m holds for each declared df. Here's an example (defun df-10/x (x) (declare (xargs :guard (not (df= 0 x)) :dfs x)) (df/ 10 x)) The generated guard is [47m(and (dfp x) (not (df= 0 x)))[0m. Note that [47m(dfp x)[0m precedes [47m(not (df= 0 x))[0m: the conjuncts generated from the [47m:dfs[0m always precede those that come from [47m:guard[0m specifications. Instead of specifying declared dfs using [47m:dfs[0m [47m[xargs][0m, a better approach (see Section 7: Remarks on performance) is to use [47mdouble-float[0m [47m[type][0m declarations. Here's a variant of the example above that uses this approach; it too is admitted by ACL2. (defun df-10/x (x) (declare (xargs :guard (not (df= 0 x))) (type double-float x)) (df/ 10 x)) Technical remark (feel free to skip it). There is a subtlety here. Unlike [47m:dfs[0m specifications, any [type] declarations are conjoined with [47m:guard[0m specifications in the order of appearance of each. (This is a general aspect of ACL2, not specific to [47mdouble-float[0m types.) So in the example above, the guard is essentially [47m(and (not (df= 0 x)) (dfp x))[0m. It may be surprising that [47m(df= 0 x)[0m can itself be guard-verified without the assumption of [47m(dfp x)[0m. The reason is that ACL2 figures out that [47mx[0m is a declared df, and deduces that since this is legal code, we know that [47m(dfp x)[0m is true. Section 6: Df primitives This section documents the df primitives, which (again) are those built-in functions and macros that take or return a df. A small number of related built-ins are also documented here. These are divided here into the following groups. * Recognizers and conversion functions * Basic arithmetic operations * Other operations In each case, we display a function's signature (as in the example of [47mf2[0m above) and describe its functionality. You can of course use [47m:[0m[47m[pe][0m to see its logical definition. But first we discuss a class of convenient macros. [4mCorresponding df-friendly macros[0m Before we document the df primitive functions, we describe corresponding macros that automatically convert certain constants to df expressions by using a [47mto-df[0m wrapper. We call such a macro the ``corresponding df-friendly macro'' for the given function. Below, we show how that works for [47mbinary-df+[0m and its corresponding df-friendly macro, [47mdf+[0m. The same relationship holds for other df primitive functions and their corresponding df-friendly macros. Consider the following examples of adding two dfs with the function [47mbinary-df+[0m. ACL2 !>(binary-df+ (to-df 3) (to-df 1/2)) #d3.5 ACL2 !>(let ((x (to-df 3))) (binary-df+ x (to-df 1/2))) #d3.5 ACL2 !> The arguments to [47mbinary-df+[0m must be dfs, so it is illegal to remove any call of [47mto-df[0m above. For example, all of the following cause errors. 1. [47m(binary-df+ 3 1/2)[0m [3m; 3 and 1/2 are not dfs[0m 2. [47m(let ((x (to-df 3))) (binary-df+ x 1/2))[0m [3m; 1/2 is not a df[0m 3. [47m(let ((x 3)) (binary-df+ x (to-df 1/2)))[0m [3m; x is not a df[0m However, [47mbinary-df+[0m has a corresponding df-friendly macro, [47mdf+[0m. That macro expands to a call of [47mbinary-df[0m with a call of [47mto-df[0m wrapped around every constant numeric argument that satisfies [47mdfp[0m. The following calls show expansions of [47mdf+[0m calls that correspond to calls from the first two examples above. ACL2 !>:trans1 (df+ 3 1/2) (BINARY-DF+ (TO-DF 3) (TO-DF 1/2)) ACL2 !>:trans1 (df+ x 1/2) (BINARY-DF+ X (TO-DF 1/2)) ACL2 !> So, evaluation succeeds for those two uses of [47mdf+[0m in place of [47mbinary-df+[0m. ACL2 !>(df+ 3 1/2) #d3.5 ACL2 !>(let ((x (to-df 3))) (df+ x 1/2)) #d3.5 ACL2 !> The third example still fails, however, since [47mdf+[0m only wraps [47mto-df[0m around constants. ACL2 !>(let ((x 3)) (df+ x (to-df 1/2))) ACL2 Error [Translate] in TOP-LEVEL: The form X represents an ordinary object, but it is being used where a form representing a :DF was expected. See :DOC df. Note: this error occurred in the context (BINARY-DF+ X (TO-DF 1/2)). ACL2 !> Note that a constant value is only supplied a [47mto-df[0m wrapper when it satisfies [47mdfp[0m, that is, it is a representable rational, as illustrated by the following example. ACL2 !>:trans1 (df+ 1/3 1/4) (BINARY-DF+ 1/3 (TO-DF 1/4)) ACL2 !> The focus above has been on numeric constants, but symbolic constants that start and end with the `[47m*[0m' character, like [47m*c*[0m, are treated somewhat similarly. Such an argument of a df-friendly macro is given a [47mto-df[0m wrapper as well as an assertion that [47mdfp[0m holds. Suppose for example that we submit the following two events. (defconst *good* 1/4) ; 1/4 satisfies dfp. (defconst *bad* 1/3) ; 1/3 does not satisfy dfp. Here is how those arguments are treated when supplied to a df-friendly macro. ACL2 !>:trans1 (df+ *good* *bad*) (BINARY-DF+ (LET ((C *GOOD*)) (ASSERT$ (DFP C) (TO-DF C))) (LET ((C *BAD*)) (ASSERT$ (DFP C) (TO-DF C)))) ACL2 !> Indeed, evaluation of [47m(df+ *good* *bad*)[0m results in an assertion failure. HARD ACL2 ERROR in ASSERT$: Assertion failed: (ASSERT$ (DFP C) (TO-DF C)) But logically, [47m[assert$][0m returns its second argument, so ACL2 can prove the following. (equal (df+ *good* *bad*) (binary-df+ *good* (to-df *bad*))) [4mRecognizers and conversion functions[0m [47m(from-df :DF) => *[0m Converts a df to a numerically equivalent ordinary value. [47m(to-df *) => :DF[0m Converts an ordinary value to a nearby df. This is the identity on any rational that is representable by a floating-point number. [47m(to-dfp *) => *[0m This is logically the same as [47mto-df[0m, but it returns an ordinary value rather than a df. [47m(dfp {* or :DF}) => *[0m Recognizes rationals that can be represented by Lisp double-floats; so, always true when applied to a df. The logical definition of [47m(dfp x)[0m is [47m(and (rationalp x) (= (to-df x) x))[0m. [47m(df-round *) => *[0m Constrained, non-executable rounding function, which converts a rational to a nearby value that satisfies [47mdfp[0m. It is used in the definitions of the basic arithmetic operations. [47m(df-string :DF) => *[0m Produces the floating-point representation, as a string, of the given df value. Examples: ACL2 !>(df-string (to-df 1/4)) "0.25" ACL2 !>(df-string (to-df 1/3)) "0.3333333333333333" ACL2 !> [47m(df-rationalize-fn :DF) => *[0m Calls the Common Lisp function, [47mrationalize[0m, which the Common Lisp HyperSpec says ``returns a rational that approximates the float to the accuracy of the underlying floating-point representation.'' The idea is to produce a ``pretty'' rational that approximates the given df, as illustrated by the following example. ACL2 !>(from-df (to-df 1/10)) 3602879701896397/36028797018963968 ACL2 !>(df-rationalize (to-df 1/10)) 1/10 ACL2 !> [47m(rize *) => *[0m This is a variant of [47mdf-rationalize[0m that operates on rationals instead of dfs, as shown by the following extension of the example just above. ACL2 !>(rize 3602879701896397/36028797018963968) 1/10 ACL2 !> [4mBasic arithmetic operations[0m [47m(binary-df+ :df :df) => :df[0m Adds the two given dfs. Corresponding df-friendly macro: [47m(df+ x y )[0m [47m(binary-df* :df :df) => :df[0m Multiplies the two given dfs. Corresponding df-friendly macro: [47m(df* x y )[0m NOTE: Both [47mdf+[0m and [47mdf*[0m are binary, unlike [47m+[0m and [47m*[0m. An immediate issue is that the failure of associativity could cause a divergence with the logical expansion into a right-associated sum or product, for example in raw Lisp as follows. ? (+ .1 .2 .3) 0.6000000000000001 ? (+ .1 (+ .2 .3)) 0.6 ? [47m(binary-df/ :df :df) => :df[0m Divides the two given dfs, where the second should be non-zero. Corresponding df-friendly macro: [47m(df/ x y )[0m [47m(unary-df- :df) => :df[0m Takes the negative of the given df. Corresponding df-friendly macro: [47m(df- x)[0m [47m(unary-df/ :df) => :df[0m Takes the reciprocal of the given non-zero df. Corresponding df-friendly macro: [47m(df/ x)[0m Also provided is a binary version of the macro [47mdf-[0m. The expansion of [47m(df- term1 term2)[0m is essentially [47m(df+ term1 (df- term2))[0m. These functions are all defined by applying [47mdf-round[0m to the exact mathematical result. Here are their definitions in the ACL2 logic. [31;1mFunction: [0m<binary-df+> (defun binary-df+ (x y) (declare (xargs :guard (and (dfp x) (dfp y)))) (df-round (+ x y))) [31;1mFunction: [0m<binary-df*> (defun binary-df* (x y) (declare (xargs :guard (and (dfp x) (dfp y)))) (df-round (* x y))) [31;1mFunction: [0m<binary-df/> (defun binary-df/ (x y) (declare (xargs :guard (and (dfp x) (dfp y) (not (= y 0))))) (df-round (/ x y))) [31;1mFunction: [0m<unary-df-> (defun unary-df- (x) (declare (xargs :guard (dfp x))) (df-round (- x))) [31;1mFunction: [0m<unary-df/> (defun unary-df/ (x) (declare (xargs :guard (and (dfp x) (not (= x 0))))) (df-round (/ x))) We include the following as a basic arithmetic operation (though some may argue with that classification). [47m(df-abs-fn :df) => :df[0m Return the absolute value of the df input, as a df. Corresponding df-friendly macro: [47m(df-abs x)[0m [4mOther operations[0m These are listed alphabetically. They include the square root function and common transcendental functions. The first two are logarithm functions. [47m(binary-df-log :df :df) => :df[0m Takes the log, where the first argument is the base. Corresponding df-friendly macro: [47m(df-log x y)[0m [47m(unary-df-log :df) => :df[0m Takes the natural log (log base [47me[0m) of the given df. Corresponding df-friendly macro: [47m(df-log x)[0m The following zero-ary functions return floating-point constants. [47m(df-pi) => :df[0m Returns a df approximation to \pi. The constant [47m*df-pi*[0m is defined to be the corresponding rational: [47m(defconst *df-pi* (from-df (df-pi)))[0m. [47m(df0) => :df[0m Returns a df logically equal to 0. [47m(df1) => :df[0m Returns a df logically equal to 1. [47m(df-minus-1) => :df[0m Returns a df logically equal to -1. The remaining functions are listed in alphabetic order. Each has a name of the form [47mdf-NAME-fn[0m where [47mNAME[0m is the name of a corresponding Common Lisp function. Each takes a df argument except for [47mexpt[0m, which takes two df arguments, and each returns a df argument. The guards require not only [47mdfp[0m of each argument but the extra conditions as shown below. Each has a corresponding df-friendly macro, [47mdf-NAME[0m. * [47m(df-acos-fn x)[0m ; guard extra: [47m(df<= (df-abs-fn x) 1)[0m * [47m(df-acosh-fn x)[0m * [47m(df-asin-fn x)[0m * [47m(df-asinh-fn x)[0m * [47m(df-atan-fn x)[0m * [47m(df-atanh-fn x)[0m ; guard extra: [47m(df< (df-abs x) 1)[0m * [47m(df-cos-fn x)[0m * [47m(df-cosh-fn x)[0m * [47m(df-exp-fn x)[0m * [47m(df-expt-fn x y)[0m ; guard extra: [47m(or (df< 0 x) (and (df= 0 x) (df< 0 y)))[0m * [47m(df-sin-fn x)[0m * [47m(df-sinh-fn x)[0m * [47m(df-sqrt-fn x)[0m ; guard extra: [47m(df<= 0 x)[0m * [47m(df-tan-fn x)[0m ; guard extra: [47m(not (df= (df-cos-fn x) 0))[0m * [47m(df-tanh-fn x)[0m ; guard extra: [47m(not (df= (df-cosh-fn x) 0))[0m Section 7: Remarks on performance This section covers just a few aspects of performance pertaining to the use of dfs. Those who use dfs and can provide useful performance tips are welcomed to extend this section. [4mInlining of df primitives[0m Suppose we start ACL2 and then submit the following forms, which define [47mg1[0m in raw Lisp and provide its assembly code. (defun g1 (x y) (declare (type double-float x y)) (df< x y)) (disassemble 'g1) If we repeat this experiment in a new ACL2 session except that we replace [47mdf<[0m with [47m<[0m, we get the same assembly code (at least, when using ACL2 built on CCL or on SBCL as of this writing). This is good; it shows that there is no performance penalty for using [47mdf<[0m. To understand why, first observe that macroexpansion replaces [47mdf<[0m by [47mdf<-fn[0m; then observe that the ACL2 sources include a [47mdeclaim[0m form that declares [47mdf<-fn[0m to be inline. All the df primitive functions are similarly declared inline except for [47mto-df[0m, which we discuss next. Of course, these inlined raw Lisp functions (and macro) cannot generally be [trace]d. [4m[47mTo-df[0m[4m[0m[4m is a macro in raw Lisp[0m Although [47mto-df[0m is a function in the ACL2 logic, it is implemented as a macro in raw Lisp. To see how that benefits performance, consider the following definition. (defun add3 (x) (declare (type double-float x)) (df+ 3 x)) We can see the translation of that [47mdf+[0m call as follows. ACL2 !>(body 'add3 nil (w state)) (BINARY-DF+ (TO-DF '3) X) ACL2 !> Since [47mbinary-df+[0m is inlined in raw Lisp (see above), its call above essentially equivalent in raw lisp to [47m(+ (TO-DF '3) X)[0m. But it would be unfortunate to call to-df at runtime, even if [47mto-df[0m were an inlined function. However, [47mto-df[0m is a macro that expands away its call on a rational argument or quoted rational argument. ? (macroexpand-1 '(TO-DF '3)) 3.0 T ? A key performance tip is that a [47mdefun[0m form should [declare] dfs with a type declaration rather than an [47mxargs :dfs[0m declaration. Here are examples. [4mType declarations are probably preferred[0m This observation is not really specific to the use of dfs. Common Lisp compilers can sometimes take advantage of [47mtype[0m [declaration]s, but they never take advantage of [47mxargs[0m declarations (because those are ignored by the compiler). So just as one may get better performance with a declaration [47m(type (integer 0 *) x)[0m than with [47m(xargs :guard (natp x))[0m, one may get better performance with (declare (type double-float x)) than with [47m(xargs :dfs x)[0m. Section 8: More examples This section, which forms the remainder of this topic, is a synopsis of [community-books] file [47mbooks/demos/floating-point-input.lsp[0m. It may be useful to skip this section and instead read that file; or one could consult that file when an example given below needs more explanation, since other examples in that file may be clarifying. Comments in that file may suffice to explain what is going on, but if not, then corresponding output file [47mbooks/demos/floating-point-log.txt[0m (generated by the [run-script] utility) may be worth a look. Here are the contents of that file (quoting from a comment near its top). ;;; TABLE OF CONTENTS ;;; ----------------- ;;; "Floats" as rationals ;;; Overflow and underflow ;;; An assertion macro ;;; Df-rationalize and rize ;;; More on dfp & to-df (recognizer & generator for representables) ;;; Fun with pi ;;; No support for complex floats ;;; Examples with defined functions ;;; Examples focused on ec-call ;;; We can't prove much ;;; Df stobj fields ;;; Arrays of double-floats ;;; DO loop$ expressions ;;; FOR loop$ expressions ;;; Stobj-let (nested stobjs) ;;; Using apply$ with dfs, including efficiency issues ;;; Encapsulate and signatures ;;; Memoization ;;; Miscellany ;;; Check consistency with values produced in raw Lisp We now hit some highlights of each of those sections that may not have been adequately covered above. See [47mbooks/demos/floating-point-input.lsp[0m for more details, e.g., the use of either [47mE[0m or [47mD[0m as an exponent marker. [3m;;; "Floats" as rationals[0m (assert-event ; 31/10 is not representable, but every #d number that is read without ; error is representable -- hence the equality below is false. (not (equal #d3.1 31/10))) (assert-event (equal #d1d50 #d1.0E50)) ; Both are the same rational. ; The following are not quite equal because the latter is not representable. (assert-event (not (equal #d1d50 (expt 10 50)))) (assert-event (let ((x (to-df #d.1)) (y (to-df #d.2)) (z (to-df #d.3))) (not (df= (df+ (df+ x y) z) (df+ x (df+ y z)))))) [3m;;; Overflow and underflow[0m #d1E310 ; Lisp error (overflow) #d1E-500 ; 0 (underflow) (to-df #d1E-500) ; #d0.0 (underflow) [3m;;; An assertion macro[0m This section just defines a macro, [47ma-e[0m, which checks that its input is true in two ways: by direct evaluation and by proof. [3m;;; Df-rationalize and rize[0m (thm (equal (to-df 1/3) ; Rational representation is on next line. 6004799503160661/18014398509481984)) (df-rationalize (to-df 1/3)) ; result is 1/3 (rize 1/3) ; 1/3; equivalent to (df-rationalize (to-df 1/3)) above [3m;;; More on dfp & to-df (recognizer & generator for representables)[0m (a-e (equal (dfp 1/4) t)) ; 1/4 is representable (a-e (equal (dfp 1/3) nil)) ; 1/3 is not representable (a-e ; to-df maps a rational to one that's representable (equal (dfp (to-df 1/3)) t)) (thm (equal (to-df 'abc) 0)) ; default guard-violating behavior [3m;;; Fun with pi[0m (defconst *2pi* ; See also df-2pi. This is a rational approximation to 2*pi. Note ; that *df-pi* is already defined as a rational approximation to pi. ; Both *df-pi* and *2pi* are ordinary objects, not dfs; defconst ; always creates an ordinary object. (* 2 *df-pi*)) ; Signature shows return of :DF in the following. (defun-inline df-2pi () ; See also *2pi*. Here, however, we return a :df (which is a ; double-float in raw Lisp) rather than an ordinary object. Note that ; since (df-pi) is representable, multiplying it by 2 produces a ; representable rational as well (since that multiplication keeps the ; mantissa and simply doubles the small exponent). (df* 2 (df-pi))) (a-e ; This holds since *df-pi* = (df-pi) and (df-2pi) is just the exact ; product by 2 of (df-pi), as noted above. (equal *2pi* (from-df (df-2pi)))) (df-sin (df-2pi)) ; very near 0, but not 0 (floating-point sin is not exact) [3m;;; No support for complex floats[0m (to-df #c(0 1)) ; guard violation (expects a rational) [3m;;; Examples with defined functions[0m This section of [47mbooks/demos/floating-point-input.lsp[0m has several examples that are worth reading if you have difficulties defining functions that traffic in dfs. In particular, it shows how to use [47mTHE[0m (see [the]) with a [47mdouble-float[0m [type-spec] to assist ACL2 with its syntax checking. [3m;;; Examples focused on ec-call[0m The example below shows the need to add a [47m:dfs[0m argument to [47m[ec-call][0m when the call returns a df. See this section in [47mbooks/demos/floating-point-input.lsp[0m for additional discussion and examples. (defun f6 (x) (declare (xargs :guard (rationalp x))) (ec-call (unary-df- (to-df x)) :dfs-in '(t) :dfs-out '(t))) [3m;;; We can't prove much[0m This section of [47mbooks/demos/floating-point-input.lsp[0m gives some examples of what can be proved about df operations and what cannot be proved. [3m;;; Df stobj fields[0m (defstobj st1 (accum :type double-float :initially 0)) (assert-event (df= (accum st1) 0)) (update-accum (to-df 3) st1) (assert-event (df= (accum st1) 3)) [3m;;; Arrays of double-floats[0m (defstobj st3 ; Here is an array of double-floats. The implementation will, as ; usual, take into account the array element type (here, double-float) ; when reading or writing the array, by generating suitable type ; declarations. ; NOTE: It may be that code runs faster (but using more space) if the raw Lisp ; array is declared to have elements of type t instead of type double-float. ; Such a change might be considered in the future. (ar :type (array double-float (8)) :initially 0)) (defun load-ar (i max lst st3) ; Update the ar field of st3 with the values in lst, starting at position i. [[.. elided here; see books/demos/floating-point-input.lsp ..]]) (load-ar 0 8 (list 3 0 *df-pi* 3/4 -2/3 5 -6 7) st3) (assert-event (and (= (from-df (ari 2 st3)) *df-pi*) (= (from-df (ari 6 st3)) -6) (df= (ari 6 st3) -6) (df< (ari 0 st3) 5))) (defthm dfp-nth-arp ; a useful lemma (implies (and (arp ar) (natp i) (< i (len ar))) (dfp (nth i ar)))) ; We can read dfs and update with dfs. (defun scalar-multiply-ar (i mult st3) (declare (xargs :stobjs st3 :guard (and (natp i) (<= i 8))) (type double-float mult)) (cond ((zp i) st3) (t (let* ((i (1- i)) (old (ari i st3)) (st3 (update-ari i (df* mult old) st3))) (declare (type double-float old)) (scalar-multiply-ar i mult st3))))) (defun scalar-multiply-ar-example (st3) (declare (xargs :stobjs st3)) (scalar-multiply-ar 4 (to-df 4) st3)) (load-ar 0 8 (list 3 0 *df-pi* 3/4 -2/3 5 -6 7) st3) (scalar-multiply-ar-example st3) (assert-event (and (= (from-df (ari 2 st3)) (* 4 *df-pi*)) (= (from-df (ari 6 st3)) -6) (df= (ari 6 st3) -6) (df< (ari 0 st3) 20))) [3m;;; DO loop$ expressions[0m This section of [47mbooks/demos/floating-point-input.lsp[0m continues using the stobj from the preceding section to show how [47mDO[0m [47m[loop$][0m expressions can operate on a stobj array. [3m;;; FOR loop$ expressions[0m ; The following is illegal, because it is illegal to use a df variable (in this ; case, w) in a FOR loop$ expression. Use DO loop$ expressions instead in such ; cases, as illustrated in the preceding section. (let ((w (to-df 7))) (loop$ for v from 1 to 3 sum (from-df (df+ w (to-df v))))) [3m;;; Stobj-let (nested stobjs)[0m This section of [47mbooks/demos/floating-point-input.lsp[0m shows that the [47m[stobj-let][0m utility works properly with dfs. [3m;;; Using apply$ with dfs[0m ; We see in examples below that apply$ works with df arguments. This may seem ; surprising. After all, there is a similar prohibition on stobj arguments ; because a stobj cannot be put into a list; wouldn't such a prohibition ; similarly pertain to df arguments, since they too cannot be put into a list? ; However, ACL2 evaluation of apply$ calls takes place by calling *1* ; functions, and these tolerate ordinary rational inputs where dfs are ; expected. So apply$ accepts rational arguments where dfs are expected, ; provided they satisfy dfp. (defun f0 (x) (declare (xargs :verify-guards nil) (type double-float x)) (df- x)) ; This too is redundant (already included above). (include-book "projects/apply/top" :dir :system) ; "Teach" apply$ about f0: (defwarrant f0) ; Succeeds, since 1/4 satisfies the guard for f0, (dfp x). (assert-event (equal (apply$ 'f0 (list 1/4)) -1/4)) ; Same as above, since the #d quantities are just rationals: (assert-event (equal (apply$ 'f0 (list #d0.25)) #d-0.25)) ; Error: guard violation, since (dfp 1/3) is false. (apply$ 'f0 (list 1/3)) ;;; Efficiency issues when using apply$ with dfs</i></p> [[.. Examples omitted here; see books/demos/floating-point-input.lsp. ..]] [3m;;; Encapsulate and signatures[0m (encapsulate (((f16 *) => :df :formals (x) :guard (rationalp x))) (local (defun f16 (x) (declare (ignore x)) (to-df 0)))) (defstub f19 (:df) => (mv :df :df)) [3m;;; Memoization[0m ; Memoization works fine with dfs; the subtleties when memoizing with stobjs ; don't apply to dfs. [3m;;; Miscellany[0m ; The following defun-sk is accepted, even though y represents an ordinary ; object, because by default the defun-sk function is non-executable. (defun-sk f25 (x) (declare (xargs :dfs (x))) (exists (y) (df< x y))) ;;; Memoize-partial works fine with dfs. [3m;;; Check consistency with values produced in raw Lisp[0m ; This section has tests to check that ACL2 evaluation with dfs agrees with ; corresponding Common Lisp evaluation on double-floats. Section 9: Remarks for system programmers Probably most ACL2 users should skip this section. But those who use ACL2 system utilities (see for example [system-utilities] and [programming-with-state]) may find some remarks here to be useful. The functions [47mtranslate[0m, [47mtranslate1[0m, [47mtranslate-cmp[0m, and [47mtranslate1-cmp[0m all convert a user-level [term] to a translated term. Each of these assumes that no free variable of the user-level term is a df. The function [47mtranslate1-cmp+[0m has an extra argument, [47mknown-dfs[0m, that is a list of free variables that are to be considered to be dfs. Subtopics [Fp] Floating-point and ACL2") (df* (pointers) "See [df].") (df+ (pointers) "See [df].") (df- (pointers) "See [df].") (df-abs (pointers) "See [df].") (df-abs-fn (pointers) "See [df].") (df-acos (pointers) "See [df].") (df-acos-fn (pointers) "See [df].") (df-acosh (pointers) "See [df].") (df-acosh-fn (pointers) "See [df].") (df-asin (pointers) "See [df].") (df-asin-fn (pointers) "See [df].") (df-asinh (pointers) "See [df].") (df-asinh-fn (pointers) "See [df].") (df-atan (pointers) "See [df].") (df-atan-fn (pointers) "See [df].") (df-atanh (pointers) "See [df].") (df-atanh-fn (pointers) "See [df].") (df-cos (pointers) "See [df].") (df-cos-fn (pointers) "See [df].") (df-cosh (pointers) "See [df].") (df-cosh-fn (pointers) "See [df].") (df-exp (pointers) "See [df].") (df-exp-fn (pointers) "See [df].") (df-expt (pointers) "See [df].") (df-expt-fn (pointers) "See [df].") (df-log (pointers) "See [df].") (df-minus-1 (pointers) "See [df].") (df-pi (pointers) "See [df].") (df-rationalize (pointers) "See [df].") (df-round (pointers) "See [df].") (df-sin (pointers) "See [df].") (df-sin-fn (pointers) "See [df].") (df-sinh (pointers) "See [df].") (df-sinh-fn (pointers) "See [df].") (df-sqrt (pointers) "See [df].") (df-sqrt-fn (pointers) "See [df].") (df-string (pointers) "See [df].") (df-tan (pointers) "See [df].") (df-tan-fn (pointers) "See [df].") (df-tanh (pointers) "See [df].") (df-tanh-fn (pointers) "See [df].") (df/ (pointers) "See [df].") (df/=-fn (pointers) "See [df].") (df0 (pointers) "See [df].") (df1 (pointers) "See [df].") (df< (pointers) "See [df].") (df<-fn (pointers) "See [df].") (df<= (pointers) "See [df].") (df= (pointers) "See [df].") (df=-fn (pointers) "See [df].") (df> (pointers) "See [df].") (df>= (pointers) "See [df].") (dfp (pointers) "See [df].") (digit-char-p (characters acl2-built-ins) "The number, if any, corresponding to a given character [47m(digit-char-p ch)[0m is the integer corresponding to the character [47mch[0m in base [47m10[0m. For example, [47m(digit-char-p #\3)[0m is equal to the integer [47m3[0m. More generally, an optional second argument specifies the radix (default [47m10[0m, as indicated above). The [guard] for [47mdigit-char-p[0m (more precisely, for the function [47mour-digit-char-p[0m that calls of this macro expand to) requires its second argument to be an integer between 2 and 36, inclusive, and its first argument to be a character. [47mDigit-char-p[0m is a Common Lisp function, though it is implemented in the ACL2 logic as an ACL2 macro. See any Common Lisp documentation for more information. [31;1mMacro: [0m<digit-char-p> (defmacro digit-char-p (ch &optional (radix '10)) (cons 'our-digit-char-p (cons ch (cons radix 'nil)))) [31;1mFunction: [0m<our-digit-char-p> (defun our-digit-char-p (ch radix) (declare (xargs :guard (and (characterp ch) (integerp radix) (<= 2 radix) (<= radix 36)))) (let ((l (assoc ch '((#\0 . 0) (#\1 . 1) (#\2 . 2) (#\3 . 3) (#\4 . 4) (#\5 . 5) (#\6 . 6) (#\7 . 7) (#\8 . 8) (#\9 . 9) (#\a . 10) (#\b . 11) (#\c . 12) (#\d . 13) (#\e . 14) (#\f . 15) (#\g . 16) (#\h . 17) (#\i . 18) (#\j . 19) (#\k . 20) (#\l . 21) (#\m . 22) (#\n . 23) (#\o . 24) (#\p . 25) (#\q . 26) (#\r . 27) (#\s . 28) (#\t . 29) (#\u . 30) (#\v . 31) (#\w . 32) (#\x . 33) (#\y . 34) (#\z . 35) (#\A . 10) (#\B . 11) (#\C . 12) (#\D . 13) (#\E . 14) (#\F . 15) (#\G . 16) (#\H . 17) (#\I . 18) (#\J . 19) (#\K . 20) (#\L . 21) (#\M . 22) (#\N . 23) (#\O . 24) (#\P . 25) (#\Q . 26) (#\R . 27) (#\S . 28) (#\T . 29) (#\U . 30) (#\V . 31) (#\W . 32) (#\X . 33) (#\Y . 34) (#\Z . 35))))) (cond ((and l (< (cdr l) radix)) (cdr l)) (t nil))))") (digit-to-char (characters acl2-built-ins) "Map a digit to a character Example: ACL2 !>(digit-to-char 8) #\8 For an integer [47mn[0m from 0 to 15, [47m(digit-to-char n)[0m is the character corresponding to [47mn[0m in hex notation, using uppercase letters for digits exceeding 9. If [47mn[0m is in the appropriate range, that result is of course also the binary, octal, and decimal digit. The [guard] for [47mdigit-to-char[0m requires its argument to be an integer between 0 and 15, inclusive. [31;1mFunction: [0m<digit-to-char> (defun digit-to-char (n) (declare (xargs :guard (and (integerp n) (<= 0 n) (<= n 15)))) (case n (1 #\1) (2 #\2) (3 #\3) (4 #\4) (5 #\5) (6 #\6) (7 #\7) (8 #\8) (9 #\9) (10 #\A) (11 #\B) (12 #\C) (13 #\D) (14 #\E) (15 #\F) (otherwise #\0)))") (dimensions (arrays acl2-built-ins) "Return the [47m:dimensions[0m from the [header] of a 1- or 2-dimensional array Example Form: (dimensions 'delta1 a) General Form: (dimensions name alist) where [47mname[0m is arbitrary and [47malist[0m is a 1- or 2-dimensional array. This function returns the dimensions list of the array [47malist[0m. That list will either be of the form [47m(dim1)[0m or [47m(dim1 dim2)[0m, depending on whether [47malist[0m is a 1- or 2-dimensional array. [47mDim1[0m and [47mdim2[0m will be integers and each exceed by 1 the maximum legal corresponding index. Thus, if [47mdimensions[0m returns, say, [47m'(100)[0m for an array [47ma[0m named [47m'delta1[0m, then [47m(aref1 'delta1 a 99)[0m is legal but [47m(aref1 'delta1 a 100)[0m violates the [guard]s on [47m[aref1][0m. [47mDimensions[0m operates in virtually constant time if [47malist[0m is the semantic value of [47mname[0m. See [arrays]. [31;1mFunction: [0m<dimensions> (defun dimensions (name l) (declare (xargs :guard (or (array1p name l) (array2p name l)))) (cadr (assoc-keyword :dimensions (cdr (header name l)))))") (disable (theories theory-functions) "Deletes names from current theory Example: (disable fact (:e fact) associativity-of-app) General Form: (disable name1 name2 ... namek) where each [47mnamei[0m is a runic designator; see [theories]. The result is the theory that contains all the names in the current theory except those listed. Note that this is merely a function that returns a theory. The result is generally a very long list of [rune]s and you will probably regret printing it. For related utilities, see [enable] and see [e/d]. The standard way to ``disable'' a fixed set of names, is as follows; see [hints] and see [in-theory]. :in-theory (disable name1 name2 ... namek) ; in a hint (in-theory (disable name1 name2 ... namek)) ; as an event (local ; often desirable, to avoid exporting from the current context (in-theory (disable name1 name2 ... namek))) Note that all the names are implicitly quoted. If you wish to disable a computed list of names, [47mlst[0m, use the theory expression [47m(set-difference-theories (current-theory :here) lst)[0m. To see the runes currently disabled that are among those created when a function symbol [47mFN[0m is introduced, evaluate [47m(disabledp 'FN)[0m.") (disable-forcing (force) "To disallow forced case-splits General Form: ACL2 !>:disable-forcing ; disallow forced case splits See [force] and see [case-split] for a discussion of forced case splits, which are inhibited by this command. [47mDisable-forcing[0m is actually a macro that [disable]s the [executable-counterpart] of the function symbol [47mforce[0m; see [force]. When you want to use [hints] to turn off forced case splits, use a form such as one of the following (these are equivalent). :in-theory (disable (:executable-counterpart force)) :in-theory (disable (force)) The following example shows how this works. First evaluate these forms. (defstub f1 (x) t) (defstub f2 (x) t) (defaxiom ax (implies (case-split (f2 x)) (f1 x))) (thm (f1 x)) You will see the application of the rule, [47max[0m, in the proof of the [47m[thm][0m call above. However, if you first evaluate [47m(disable-forcing)[0m, then there will be no application of [47max[0m. To restore forced case splitting, see [enable-forcing].") (disable-immediate-force-modep (force) "[force]d hypotheses are not attacked immediately General Form: ACL2 !>:disable-immediate-force-modep This event causes ACL2 to delay [force]d hypotheses to the next forcing round, rather than attacking them immediately. See [immediate-force-modep]. Or for more basic information, first see [force] for a discussion of [force]d case splits. Disable-immediate-force-modep is a macro that [disable]s the [executable-counterpart] of the function symbol [47m[immediate-force-modep][0m. When you want to [disable] this mode in [hints], use a form such as one of the following (these are equivalent). :in-theory (disable (:executable-counterpart immediate-force-modep)) :in-theory (disable (immediate-force-modep))") (disable-ubt (history) "Make it illegal to undo back through the current [command] The utility [47mdisable-ubt[0m is probably only relevant to those who write ACL2-based tools, in particular using [wormhole]s. Its initial application (and perhaps still its only application) is to arrange that inside the [break-rewrite] interactive loop, it is impossible to undo the [ld-keyword-aliases] supporting the [brr-commands]. General Forms: :disable-ubt (disable-ubt) ; same as above (disable-ubt arg) ; same as above if arg is not nil or :disable-ubt where [47marg[0m is evaluated, and if it is supplied and its value is neither [47mnil[0m nor [47m:disable-ubt[0m, then its value satisfies [47m[msgp][0m. In that case, the message is printed after the usual message (except, before ``See :DOC disable-ubt''). The following example illustrates the use of that optional message but, what is more important, it illustrates the effect of [47mdisable-ubt[0m: a [command] that executes it cannot be undone. ACL2 !>(disable-ubt (list "Just a demo: ~x0." (cons #0 17))) Summary Form: ( DISABLE-UBT ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) :DISABLE-UBT ACL2 !>:ubt :x ACL2 Error in :UBT: Can't undo a :disable-ubt event (at command 1). Just a demo: 17. See :DOC disable-ubt. ACL2 !> [47mDisable-ubt[0m is similar to [47m(reset-prehistory t)[0m, as both establish a barrier to undoing. However, for history commands such as [47m:[0m[47m[pcb][0m, command numbers are not changed by [47mdisable-ubt[0m. Like [47m[reset-prehistory][0m, [47mdisable-ubt[0m is never [redundant].") (disabledp (theories) "Determine whether a given name or rune is disabled Examples: :disabledp foo ; returns a list of all disabled runes whose base ; symbol is foo (see [rune]) (disabledp 'foo) ; same as above (i.e., :disabledp foo) :disabledp (:rewrite bar . 1) ; returns t if the indicated rune is ; disabled, else nil (disabledp (:rewrite bar . 1)); same as immediately above (disabledp '(:definition binary-append)) ; returns t if the indicated definition is disabled, else nil (disabledp '(:d append)) ; same as above Also see [pr], which gives much more information about the rules associated with a given event. [47mDisabledp[0m takes one argument, which is a symbol, a [rune], or a runic abbreviation such as [47m(:d append)[0m (see [theories]). In the former case it returns the list of disabled runes associated with that name, in the sense that the rune's ``base symbol'' is that name (see [rune]) or, if the event named is a [47m[defmacro][0m event, then the list of disabled runes associated with the function corresponding to that macro name, if any (see [macro-aliases-table]). In the other cases, where the argument is a [rune] or a runic abbreviation for a rune, [47mdisabledp[0m returns [47mt[0m if the rune is disabled, and [47mnil[0m otherwise. Remark for users of the [break-rewrite] utility. Inside the [47m:[0m[47m[brr][0m loop, the computation performed by [47mdisabledp[0m takes place with respect to the state of the proof that is currently underway, rather than the global state. For example, if you break while the prover is working on Subgoal 3, and the [hints] supplied for the proof specify [47m("Subgoal 3" :in-theory (disable foo))[0m, then [47mdisabled[0m will return the runes associated with [47mfoo[0m, regardless of whether or not those runes are disabled globally.") (disassemble$ (compilation debugging) "Disassemble a function The macro [47mdisassemble$[0m provides a convenient interface to the underlying [47mdisassemble[0m utility of the host Common Lisp implementation, which prints assembly code for a given function symbol at the terminal. If the argument is instead a macro alias for a function symbol (see [macro-aliases-table]), then it prints assembly code for that function symbol instead. [47mDisassemble$[0m works by including the community book [47mbooks/misc/disassemble.lisp[0m, which defines the supporting function [47mdisassemble$-fn[0m, and then by calling that function. Note that the arguments to [47mdisassemble$[0m are evaluated. Also note that [47mdisassemble$[0m is intended as a top-level utility for the ACL2 loop, not to be called in code; for such a purpose, include the above book and call [47mdisassemble$-fn[0m directly. Example Forms: (disassemble$ 'foo) (disassemble$ 'foo :recompile t) General Forms: (disassemble$ form) (disassemble$ form :recompile flg) where [47mform[0m evaluates to a function symbol or a macro alias for a function symbol and [47mflg[0m evaluates to any value. If [47mflg[0m is [47mnil[0m, then the existing definition of that function symbol is disassembled. But if [47mflg[0m is supplied and has a value other than [47mnil[0m or [47m:default[0m, and if that function symbol is defined in the ACL2 loop (not merely in raw Lisp; for example, see [set-raw-mode]), then the disassembly will be based on a recompilation of that ACL2 definition. Normally this recompilation is not necessary, but for some host Lisps, it may be useful; in particular, for CCL the above book arranges that source code information is saved, so that the output is annotated with such information. When recompilation takes place, the previous definition is restored after disassembly is complete. Finally, if [47mflg[0m is omitted or has the value [47m:default[0m --- i.e., in the default case --- then recompilation may take place or not, depending on the host Lisp. The values of [47m(@ host-lisp)[0m for which recompilation takes place by default may be found by looking at the above book, or by including it and evaluating the constant [47m*host-lisps-that-recompile-by-default*[0m. As of this writing, CCL is the only such Lisp (because that is the one for which we can obtain source annotation in the output by recompiling).") (disjoin (pointers) "See [system-utilities].") (disjoin2 (pointers) "See [system-utilities].") (dive-into-macros-table (proof-builder dv) "Right-associated function information for the [proof-builder] Examples: ACL2 !>(dive-into-macros-table (w state)) ((CAT . EXPAND-ADDRESS-CAT) (LXOR . EXPAND-ADDRESS-LXOR) This table associates macro names with functions used by the interactive [proof-builder]'s [47mDV[0m and numeric diving commands (e.g., [47m3[0m) in order to dive properly into subterms. See [proof-builder], in particular the documentation for [47mDV[0m. This table can be extended easily. See [add-dive-into-macro] and also see [remove-dive-into-macro]. The symbol associated with a macro should be a function symbol taking four arguments, in this order: * [47mcar-addr[0m the first number in the list given to the interactive [proof-builder]'s [47mDV[0m command * [47mraw-term[0m the untranslated term into which we will dive * [47mterm[0m the translated term into which we will dive * [47mwrld[0m the current ACL2 logical [world] The function will normally return a list of positive integers, representing the (one-based) address for diving into [47mterm[0m that corresponds to the single-address dive into [47mraw-term[0m by [47mcar-address[0m. However, it can return [47m(cons str alist)[0m, where [47mstr[0m is a string suitable for [47m[fmt][0m and [47margs[0m is the corresponding alist for [47m[fmt][0m. Referring to the example above, [47mexpand-address-cat[0m would be such a function, which will be called on [47mraw-term[0m values that are calls of [47mcat[0m. See the community book [47mbooks/misc/rtl-untranslate.lisp[0m for the definition of such a function. See [table] for a general discussion of tables. Subtopics [Add-dive-into-macro] Associate [proof-builder] diving function with macro name [Remove-dive-into-macro] Removes association of [proof-builder] diving function with macro name") (dmr (debugging break-rewrite accumulated-persistence) "Dynamically monitor rewrites and other prover activity In addition to utilities that allow you to set breakpoints or print rewriting information to the screen --- see [break-rewrite] (also see related utility [with-brr-data]) --- ACL2 provides a utility for watching the activity of the rewriter and some other proof processes, in real time. This utility is called ``dmr'', which is an acronym for ``dynamically monitor rewrites''. The utility comes in two parts: an ACL2 component that frequently updates a file (the ``dmr file'') containing the relevant information, and an Emacs component that frequently updates an Emacs buffer (the ``dmr buffer'') with the contents of that file. Other editors could, in principle, be programmed to display that file; anyone developing such a capability is invited to contribute it to the ACL2 community. The dmr utility can be extremely helpful for expensive proofs, especially when ACL2 is not providing any output to the terminal. The [break-rewrite] and [47m[accumulated-persistence][0m utilities may be a bit easier to use, so you might want to try those first. But the dmr utility can be a very helpful debugging aide, as it can visually give you a sense of where ACL2 is spending its time. The Emacs portion of this utility is already loaded if you load the distributed Emacs file [47memacs-acl2.el[0m from a suitable directory; see [emacs]. Otherwise, load into Emacs the file [47mmonitor.el[0m from that same directory. (You only need to do that once in your Emacs session.) Then each time you want to observe the rewriter in action, invoke the following to see it displayed in a buffer, which we call the ``dmr buffer'': Control-t 1 But first you will need to enable monitoring at the ACL2 level: (dmr-start) Monitoring has some cost. So if you have started it, then at some point you may want to turn it off when not using it. Any time the dmr buffer (generally called [47m"acl2-dmr-<user_name>"[0m) is not visible, Emacs monitoring is turned off. You can also turn off Emacs monitoring explicitly, with: Control-t 2 At the ACL2 level you can disable monitoring as follows: (dmr-stop) [3mInterpreting the dmr buffer display.[0m We explain the dmr buffer display by way of the following example. It is a snapshot of a dmr buffer taken from one of the community books, [47mbooks/workshops/2004/legato/support/proof-by-generalization-mult.lisp[0m. 0. (DEFTHM . WP-ZCOEF-G-MULTIPLIES) 1. SIMPLIFY-CLAUSE 2. Rewriting (to simplify) the atom of literal 18; argument(s) 1 4. Rewriting (to simplify) the expansion; argument(s) 3|2 7. Applying (:DEFINITION WP-ZCOEF-G) * 8. Rewriting (to simplify) the rewritten body; argument(s) 2|1|2|2 * 13. Applying (:REWRITE MOD-ZERO . 2) * 14. Rewriting (to establish) the atom of hypothesis 4 * 15. Applying (:META META-INTEGERP-CORRECT) Each line indicates an ACL2 activity that leads to the activity shown on the line just below it. Moreover, lines are sometimes collapsed to make the display more compact. Consider for example the first few lines. Above, we are proving a theorem named [47mWP-ZCOEF-G-MULTIPLIES[0m. Lines 1 and 2 show the [clause] simplification process invokes the rewriter on the 18th literal. (Recall that a clause is a disjunction of literals; for example the clause [47m{(NOT A), (NOT B), C}[0m would be displayed as [47m(IMPLIES (AND A B) C)[0m.) This 18th literal mentioned on line 2 is a function call [47m(f arg1 ...)[0m, and ``[47margument(s) 1[0m'' indicates that the rewriter, which works inside-out, is considering the first argument (``[47marg1[0m''). Thus the display could instead have shown the following. 2. Rewriting (to simplify) the atom of literal 18 3. Rewriting (to simplify) the first argument 4. Rewriting (to simplify) the expansion; argument(s) 3|2 But it saved space to combine lines 2 and 3. Line 4 suggests that the above [47marg1[0m is a function call that has been opened up because of an [47m:expand[0m hint or, perhaps, an expansion directed explicitly by the prover (as can happen during induction). The annotation ``[47margument(s) 3|2[0m'' then indicates that the rewriter is diving into the third argument of the expansion, and then into the second argument of that. Let us call the result [47mterm7[0m (since it is the one to be considered on line 7). Now consider the next two lines: 7. Applying (:DEFINITION WP-ZCOEF-G) * 8. Rewriting (to simplify) the rewritten body; argument(s) 2|1|2|2 Line 7 is saying that [47mterm7[0m (defined above) is modified by applying the definition of [47mWP-ZCOEF-G[0m to it. Line 8 then says that the body of this definition has been rewritten (with its formals bound to the actuals from [47mterm7[0m) and the rewriter is diving into the subterms of that rewritten body, as indicated. Notice also that line 8 is the first line marked with an asterisk (``[47m*[0m'') in the margin. This line is the first that is different from what was shown the previous time the display was updated (about 1/10 second earlier, by default). When a line is marked with an asterisk, so are all the lines below it; so the lines without an asterisk are those that have been stable since the last display. In this example we may see line 7 marked without an asterisk for a while, which suggests that the rule [47m(:DEFINITION WP-ZCOEF-G)[0m is expensive. (Also see [accumulated-persistence].) In general, a line that persists for awhile without a leading asterisk can suggest why the proof is taking a long time. Finally let us consider line 13 and the two lines below it. The phrase [47m"'Applying (:REWRITE MOD-ZERO . 2)"[0m says that the indicated rewrite rule is being considered for application to the current term. There are very weak criteria for ``Applying'' to be printed: the rule must be enabled, and top-level function symbols much suitably match for the term and the rule. In particular, the ``Applying'' line does not imply that the rule actually matches the term. That said: in the case of line 13, matching clearly was successful, since line 14 indicates an attempt to establish the rule's fourth hypothesis. Finally, note the indentation of line 14 relative to line 13. Extra indentation occurs when an attempt is being made to relieve a hypothesis (i.e., rewrite it to [47mt[0m). In particular, rewrites that will be incorporated directly into a (top-level) literal are all indented just two spaces, starting with the first rewrite directly under a process such as [47mSIMPLIFY-CLAUSE[0m (shown line 1 above). If the indentation is at least the value of raw Lisp variable [47m*dmr-indent-max*[0m (by default, 20), then the indentation is restricted to that column, but ACL2 prints [47m{n}[0m where n is the column that would have been used for indentation if there were no maximum. You can move the cursor around in the dmr buffer even while it is being updated. But emacs will attempt to keep the cursor no later than the first asterisk (``[47m*[0m'') in the margin. Thus, you can move the cursor around in the stable part of the display, and emacs will keep the cursor in that stable part. WARNING: Things could go terribly wrong if the same user runs two different ACL2 sessions with dmr active, because the same file will be written by two different ACL2 processes. WARNING: For dmr to work, emacs and ACL2 need to be run on the same machine because the file used to communicate between ACL2 and emacs is under [47m/tmp[0m. Except, you can probably hack around that restriction by changing [47m*dmr-file-name*[0m in ACL2 (in raw Lisp) and correspondingly in Emacs file [47mmonitor.el[0m. More generally, advanced users are welcome to search for the string User-settable dmr variables in ACL2 files [47minterface-raw.lisp[0m and [47memacs/monitor.el[0m in order to customize their dmr environments. In order to update the dmr file with the latest stack information, interrupt ACL2 and then evaluate: [47m(dmr-flush)[0m. In order to support resumption of the interrupted proof (assuming your host Common Lisp supports resumption), evaluation of [47m(dmr-start)[0m will automatically enable the debugger if it is not already enabled and not fully disabled with value [47m:never[0m (see [set-debugger-enable]). If such automatic enabling takes place, then [47m(dmr-stop)[0m will restore the old setting of the debugger unless, after [47m(dmr-start)[0m enables the debugger but before [47m(dmr-stop)[0m is called, you call [47m[set-debugger-enable][0m (or more precisely: function [47mset-debugger-enable-fn[0m is called). Note for users of the experimental extension ACL2(p) (see [parallelism]): when waterfall-parallelism has been set to a non-[47mnil[0m value (see [set-waterfall-parallelism]), statistics about parallel execution are printed instead of the usual information.") (do$ (loop$ do-loop$) "Definition of [47mdo$[0m [47mDo$[0m is the logical function that interprets [47mdo[0m [47mloop$[0ms. See [do-loop$] for a discussion of [47mdo$[0m. The function takes six arguments but only the first five are relevant to its logical value. * [47mmeasure-fn[0m --- a [47m[lambda][0m object that computes the measure that supposedly decreases (under [47m[l<][0m) on each iteration of the [47mdo-fn[0m and is checked after each iteration, * [47malist[0m --- an alist that binds the variable symbols used in the body and [47mfinally[0m clause (if any) to their values, * [47mdo-fn[0m --- a [47mlambda[0m object that computes the results of one iteration, where the results are represented by a triple consisting of an exit token that indicates where control goes next, the value (if a [47mreturn[0m was executed), and a new [47malist[0m, * [47mfinally-fn[0m--- a [47mlambda[0m object that computes the value of the [47mfinally[0m clause, and * [47mvalues[0m --- the output signature of the value to be returned if the [47mmeasure[0m fails to decrease. [31;1mFunction: [0m<do$> (defun do$ (measure-fn alist do-fn finally-fn values dolia) (declare (xargs :guard (and (apply$-guard measure-fn '(nil)) (apply$-guard do-fn '(nil)) (apply$-guard finally-fn '(nil)) (weak-dolia-p dolia)))) (let* ((stobj-values-p (not (all-nils (true-list-fix values)))) (old-measure-value (and stobj-values-p (apply$ measure-fn (list alist)))) (triple (true-list-fix (apply$ do-fn (list alist)))) (exit-token (car triple)) (val (cadr triple)) (new-alist (caddr triple))) (cond ((eq exit-token :return) val) ((eq exit-token :loop-finish) (let* ((triple (true-list-fix (apply$ finally-fn (list new-alist)))) (exit-token (car triple)) (val (cadr triple))) (if (eq exit-token :return) val nil))) ((l< (lex-fix (apply$ measure-fn (list new-alist))) (lex-fix (if stobj-values-p old-measure-value (apply$ measure-fn (list alist))))) (do$ measure-fn new-alist do-fn finally-fn values dolia)) (t (prog2$ (let ((all-stobj-names (true-list-fix (access dolia dolia :all-stobj-names))) (untrans-measure (access dolia dolia :untrans-measure)) (untrans-do-loop$ (access dolia dolia :untrans-do-loop$))) (er hard? 'do$ "The measure, ~x0, used in the do loop$ ~ statement~%~Y12~%failed to decrease! Recall that do$ tracks ~ the values of do loop$ variables in an alist. The measure is ~ computed using the values in the alist from before and after ~ execution of the body. We cannot print the values of double ~ floats and live stobjs, if any are found in the alist, ~ because they are raw Lisp objects, not ACL2 objects. We ~ print any double float as its corresponding rational and ~ simply print the name of any live stobj (as a ~ string).~%~%Before execution of the do body the alist ~ was~%~Y32.~|After the execution of the do body the alist ~ was~%~Y42.~|Before the execution of the body the measure ~ was~%~x5.~|After the execution of the body the measure ~ was~%~x6.~|~%Logically, in this situation the do$ returns the ~ value of a term whose output signature is ~x7, where the ~ value of any component of type :df is #d0.0 and the value of ~ any stobj component is the last latched value of that stobj." untrans-measure untrans-do-loop$ nil (eviscerate-do$-alist alist all-stobj-names) (eviscerate-do$-alist new-alist all-stobj-names) (if stobj-values-p old-measure-value (apply$ measure-fn (list alist))) (apply$ measure-fn (list new-alist)) values)) (loop$-default-values values new-alist)))))) The last argument is only relevant in the error message printed if the [47mdo$[0m fails to terminate and that message is not part of the returned value.") (do-loop$ (loop$) "Iteration with [47m[loop$][0m using local variables and [stobj]s This topic assumes that you have read the introduction to [47mloop$[0m expressions in ACL2; see [loop$]. Here we give more complete documentation on [47mDO[0m [47mloop$[0m expressions. This discussion is partitioned into the following sections * INFORMAL INTRODUCTION --- examples of [47mDO[0m [47mloop$[0m expressions * SYNTAX --- detailed discussion of the legal syntax * SEMANTICS --- detailed discussion of how [47mDO[0m [47mloop$[0m expressions are translated into calls of the general-purpose function [47m[do$][0m * SIGNALING ERRORS --- how [47mDO[0m [47mloop$[0ms can signal errors For a discussion of proofs about [47mloop$[0ms, see [stating-and-proving-lemmas-about-loop$s]. More examples of [47m[loop$][0m expressions, including [47mDO[0m [47mloop$[0ms, may be found in [community-book] [47mprojects/apply/loop-tests.lisp[0m. INFORMAL INTRODUCTION The most basic [47mDO[0m [47mloop$[0m expressions have the following form. (loop$ WITH v1 = a1 ... WITH vn = an DO body) [31;1mA Basic Example[0m The example [47mloop$[0m expression below initially stores the list [47m(a b c)[0m in the variable [47mx[0m and [47mnil[0m in the variable [47my[0m. Then it iterates, repeatedly popping the first element of [47mx[0m onto [47my[0m until [47mx[0m is empty. Then it returns the final value of [47my[0m. ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (return y)))) (C B A) ACL2 !> This example illustrates the basic operation of [47mDO[0m [47mloop$[0m expressions. * Initially, variables are initialized according to the [47mWITH[0m clauses: for each binding [47mWITH Vi = Ei[0m, we say that [47mVi[0m is a [3m[47mWITH[0m[3m-bound variable[0m, and [47mVi[0m is initially bound to the value of [47mEi[0m. * In this example, [47mx[0m is initially bound to the list [47m(a b c)[0m and [47my[0m is initially bound to [47mnil[0m. * Then, the [3mloop body[0m --- i.e., the term after the [47mDO[0m keyword --- is repeatedly evaluated. An update to [47mWITH[0m-bound variable [47mVj[0m occurs whenever an expression [47m(setq Vj Ej)[0m is encountered while evaluating the loop body, binding [47mVj[0m to the value of [47mEj[0m (which may reference the current values of [47mWITH[0m-bound variables). * In this example, as long is [47mx[0m is a cons, [47my[0m is assigned to [47m(cons (car x) y)[0m and then [47mx[0m is assigned to the [47mcdr[0m of its current value. * Ultimately an expression [47m(RETURN E)[0m should be encountered, in which case the value of [47mE[0m is returned --- where as before, [47mE[0m may reference the current values of [47mWITH[0m-bound variables. * In this example, when [47mx[0m is not a cons (and hence is, in fact, [47mnil[0m), the current value of [47my[0m is returned as the value of the [47mloop$[0m expression. By this point each element of the initial value of [47mx[0m has been pushed onto [47my[0m, so the value [47m(c b a)[0m is returned. Note that [47mprogn[0m is permitted as shown, to connect a sequence of expressions. Indeed, that is how more than one assignment is accomplished; unlike Common Lisp, the [47mDO[0m keyword is followed by exactly one expression, so [47mDO expr1 expr2[0m is illegal in ACL2 but [47mDO (progn expr1 expr2)[0m is fine. Also note that the [47mWITH[0m-bound variables are initialized sequentially: later bindings may reference values of earlier ones, for example as follows. ACL2 !>(loop$ with x = (* 3 4) with y = (* 10 x) do (return (list y))) (120) ACL2 !> See [lp-section-14] of the [47mLoop$[0m Primer for some exercises in writing and executing [47mDO[0m [47mloop$[0ms (with answers in a Community Book). But remember to come back here when you get to the end of that section. [31;1mParallel Assignment Using [47mMv-setq[0m[31;1m[0m ACL2 also supports parallel assignment to two or more variables, using [47mmv-setq[0m. The following is equivalent to the example immediately above. ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (mv-setq (x y) (mv (cdr x) (cons (car x) y)))) (t (return y)))) (C B A) ACL2 !> Thus, the first argument of an [47mmv-setq[0m call is not evaluated, and is a list of distinct variables of length at least 2. The second argument is any expression that returns multiple values consistent with the first argument --- ``consistent'' in the sense that the number of values returned equals the number of variables in the first argument and stobjs must match up. Thus, the rules for [47m(mv-setq vars expr)[0m are the same as for [47m(mv-let vars expr ...)[0m. [31;1mThe [47mFINALLY[0m[31;1m Clause[0m We have seen the [47mloop$[0m keywords [47mWITH[0m and [47mDO[0m. A third [47mloop$[0m keyword, [47mFINALLY[0m, is also supported. Here is a variant of the preceding example that illustrates the use of [47mFINALLY[0m. The iteration stops with the [47m(loop-finish)[0m form this time, rather than with a call of [47mreturn[0m. Execution of [47m(loop-finish)[0m passes control to the [47mFINALLY[0m clause, which is executed just like the [47mDO[0m body but with a single pass, thus determining the value of the [47mloop$[0m --- in this example, returning the final value of [47my[0m. ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (loop-finish))) finally (return y)) (C B A) ACL2 !> This example illustrates that [47m(loop-finish)[0m terminates the iteration, passing control to the [47mFINALLY[0m clause if there is one. The [47mFINALLY[0m clause is evaluated under the current bindings of the [47mWITH[0m-bound variables, just as a [47mDO[0m body is executed (but with a single pass rather than iteration). The value returned by a [47mDO[0m [47mloop$[0m expression is [47mnil[0m when no [47mreturn[0m expression is evaluated (or more generally, a suitable value consistent with the [47m:VALUES[0m keyword discussed below). Here is an example, which illustrates an error that may be easy to commit. ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (loop-finish))) finally (length y)) NIL ACL2 !> Presumably the intention was to return the length of [47my[0m, which in this case would be 3. But then the [47mFINALLY[0m clause should have been [47m(return (length y))[0m. [31;1mThe [47m:VALUES[0m[31;1m Keyword[0m The [47m:VALUES[0m keyword is necessary for a [47mloop$[0m expression that returns a [double-float], a [stobj] or [multiple-value]s. When the [47m:VALUES[0m keyword is used, the syntax is [47m:VALUES (v0 ... vk)[0m, where each [47mvi[0m is either [47mnil[0m, [47m:df[0m, or a stobj name. [47m:VALUES (nil)[0m denotes return of a single ordinary value; [47m:VALUES (s)[0m denotes return of a single value that is a stobj named [47ms[0m; and [47m:VALUES (v0 ... vk)[0m for k > 0 denotes return of k+1 values, where [47mvi[0m is [47mnil[0m if the ith returned value is an ordinary value, [47m:DF[0m if the ith returned value is a double-float, and otherwise [47mvi[0m is the name of the stobj returned as the ith value. You may recognize (v0 ... vk) as an output signature. If the measure supplied to [47mdo$[0m fails to decrease on an iteration, an error is caused and the output signature is used compute a ``default value,'' which is generally a list of k+1 objects (but is a single object when k is 0). The ith object in the default value is [47mnil[0m if [47mvi[0m is [47mnil[0m, is [47m#d0.0[0m if [47mvi[0m is [47m:DF[0m, and is the last latched value of the named stobj otherwise. No stobj name may be duplicated, and [47m:VALUES[0m must appear between the [47mDO[0m loop keyword and the [47mDO[0m body. Let's look at an example. Below we introduce a [stobj] and add a [warrant] for its accessor and updater. Warrants are necessary for functions called in [47mDO[0m bodies and [47mFINALLY[0m clauses in order for those forms to be evaluated. See [loop$] for a discussion of the necessity of such warrants. The two [47mloop$[0m expressions are similar in nature to those above, first without and then with a [47mFINALLY[0m clause; also see the discussion below. All forms below complete successfully. (include-book "projects/apply/top" :dir :system) (defstobj st fld) (defwarrant fld) (defwarrant update-fld) ; Check that (fld st) is currently nil. (assert-event (equal (fld st) nil)) (loop$ with x = '(1 2 3) do :values (st) (cond ((endp x) (return st)) (t (mv-setq (st x) (let ((st (update-fld (cons (car x) (fld st)) st))) (mv st (cdr x))))))) (assert-event (equal (fld st) '(3 2 1))) (update-fld nil st) (assert-event (equal (fld st) nil)) (loop$ with x = '(1 2 3) do :values (st) (cond ((endp x) (loop-finish)) (t (progn (setq st (update-fld (cons (car x) (fld st)) st)) (setq x (cdr x))))) finally (return st)) (assert-event (equal (fld st) '(3 2 1))) These loops are similar to those we saw earlier, but this time, when we pop values from [47mx[0m they go into a stobj. Since we return that stobj, [47mst[0m, the [47m:VALUES[0m is [47m(st)[0m. The fifth argument of the call of [47mdo$[0m generated from these [47mloop$[0ms is [47m'(st)[0m. One might expect [47m:VALUES[0m to be [47mst[0m instead, but [47m:VALUES[0m is always a list; when a single value is returned, [47m:VALUES[0m is a one-element list. Thus, the default for [47m:VALUES[0m is [47m(nil)[0m. Notice that the examples above apply [47msetq[0m to [47mst[0m. This illustrates that a variable assigned by [47msetq[0m or [47mmv-setq[0m must either be declared in a [47mWITH[0m clause or be a known stobj. Of course, here [47mst[0m is a known stobj. In fact, stobjs are not allowed to be declared in [47mWITH[0m clauses (and that is not necessary for assigning to them). Note that it is possible to write [47mDO[0m loops without any [47mWITH[0m clauses, provided a stobj is being manipulated and measured in the body. For example, using the stobj declared in the previous example, (loop$ do :values (st) :measure (acl2-count (fld st)) (if (endp (fld st)) (return st) (if (equal 3 (car (fld st))) (return st) (setq st (update-fld (cdr (fld st)) st))))) is acceptable. In Common Lisp, [47m(loop$ do <body>)[0m loops until a [47mreturn[0m is executed and so to be admissible in ACL2 some [47m:measure[0m must be specified (unless there is [47mreturn[0m on every branch through [47m<body>[0m). If there are no [47mWITH[0m clauses, stobjs are the only objects that might be measured to explain termination, and ACL2 cannot guess effective measures of stobjs. To see some advice about proving inductive theorems about [47mDO[0m loops measured by stobjs, see [stating-and-proving-lemmas-about-loop$s]. [31;1mThe [47mOF-TYPE[0m[31;1m Keyword[0m So far our examples have all involved [47mloop$[0m expressions that are evaluated directed at the ACL2 prompt. These do not require the [47mOF-TYPE[0m keyword described in this section. But [47mloop$[0m expressions may also appear in definitions. When these definitions are to be [guard]-verified, [47mOF-TYPE[0m keyword may be critical. Consider the following example, which searches for an even number in a given list of integers, returning [47mt[0m if one is found and else [47mnil[0m. As usual, we start by including the usual book for reasoning about [47mloop$[0m. (include-book "projects/apply/top" :dir :system) (defun has-evenp (x) (declare (xargs :guard (integer-listp x))) (loop$ with temp of-type (satisfies integer-listp) = x do (cond ((endp temp) (return nil)) ((evenp (car temp)) (return t)) (t (setq temp (cdr temp)))))) We see that the expression immediately following [47mOF-TYPE[0m is a legal [type-spec], in this case expressing that [47m(integer-listp temp)[0m holds for every value of [47mtemp[0m during execution of the [47mloop$[0m. Let's see why this use of [47mOF-TYPE[0m is necessary. When it is omitted, guard verification fails with the following top-level checkpoints. Subgoal 1.2 (IMPLIES (AND (ALISTP ALIST) (NOT (CONSP (CDR (ASSOC-EQ-SAFE 'TEMP ALIST))))) (NOT (CDR (ASSOC-EQ-SAFE 'TEMP ALIST)))) Subgoal 1.1 (IMPLIES (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'TEMP ALIST)))) (INTEGERP (CADR (ASSOC-EQ-SAFE 'TEMP ALIST)))) To understand these checkpoints we need to understand a bit about how ACL2 gives a semantics to [47mDO[0m [47mloop$[0m expressions (as we explain in more detail in the section on Semantics below). In the ACL2 logic, a [47mDO[0m [47mloop$[0m expression is represented as a transformation on an association list, named [47malist[0m, that assigns values to every variable in the expression. This alist is transformed by each iteration through the loop. The value of the variable [47mtemp[0m in [47malist[0m is [47m(assoc-eq-safe 'temp alist)[0m, where [47massoc-eq-safe[0m is just a variant of [47m[assoc][0m whose guard makes no requirements on the alist. The first checkpoint above (Subgoal 1.2) thus says that if the value of [47mtemp[0m is not a cons, then it's [47mnil[0m. That requirement comes from the expression, [47m(endp temp)[0m, since the guard of [47m[endp][0m is that its argument is a cons or [47mnil[0m. The second checkpoint (Subgoal 1.1) says that if the value of [47mtemp[0m is a cons, then its [47mcar[0m is an integer. That requirement comes from the expression [47m(evenp (car temp))[0m, since the guard for [47m[evenp][0m requires its argument to be an integer. When we add the restriction provided by the [47mOF-TYPE[0m keyword that [47mtemp[0m satisfies [47m[integer-listp][0m, the checkpoints each get the added hypothesis [47m(integer-listp (cdr (assoc-eq-safe 'temp alist)))[0m. That allows the guard proof to go through. This addition also imposes that same requirement on the initial alist, but it is discharged because the guard for [47mhas-evenp[0m specifies [47m(integer-listp x)[0m and [47mtemp[0m is initially assigned to [47mx[0m. Importantly, use of the [47mOF-TYPE[0m keyword on a variable imposes a guard proof obligation for every assignment to that variable, that the new value of that variable also satisfies the given type. In this case, this means that under the hypotheses that [47m(endp temp)[0m and [47m(evenp (car temp))[0m are false, and also assuming that [47mtemp[0m satisfies [47minteger-listp[0m --- where here, [47mtemp[0m is [47m(cdr (assoc-eq-safe 'temp alist))[0m --- then [47m(cdr temp[0m) satisfies [47minteger-listp[0m. ACL2 discharges this requirement automatically. [31;1mThe [47m:GUARD[0m[31;1m Keyword[0m Consider the following definition, which is identical to the one for [47mhas-evenp[0m displayed above except that instead of using the [47mOF-TYPE[0m keyword, it uses the [47m:GUARD[0m keyword. (defun has-evenp (x) (declare (xargs :guard (integer-listp x))) (loop$ with temp = x do :guard (integer-listp temp) (cond ((endp temp) (return nil)) ((evenp (car temp)) (return t)) (t (setq temp (cdr temp)))))) This definition is accepted by ACL2 for much the same reason that the preceding one was accepted. The difference is that while the [47mOF-TYPE[0m keyword adds a requirement at every assignment of the variable, the [47m:GUARD[0m imposes the invariant that when the guard holds entering the [47mloop$[0m body, it also holds when the [47mloop$[0m body is next entered. Thus we see the following in the [47mGoal[0m generated for the guard conjecture, where [47mnew-alist[0m is let-bound (not shown here) to the result of updating [47malist[0m after one iteration through the loop, and where [47m(equal exit-flg nil)[0m indicates that another iteration is pending (because neither a [47mreturn[0m nor a [47mloop-finish[0m was executed). (IMPLIES (AND (AND (ALISTP ALIST) (INTEGER-LISTP (CDR (ASSOC-EQ-SAFE 'TEMP ALIST)))) (EQUAL EXIT-FLG NIL)) (AND (ALISTP NEW-ALIST) (INTEGER-LISTP (CDR (ASSOC-EQ-SAFE 'TEMP NEW-ALIST))))) The [47m:guard[0m is generally ignored when it is within the definition's body for a guard-verified or a [47m:[0m[47m[program][0m-mode function. The reason is that in these cases, the [47mloop$[0m expression is converted to a Common Lisp [47mloop[0m expression. (There are exceptions involving [47m[set-guard-checking][0m and [invariant-risk].) However, in other cases the [47m:guard[0m is checked at runtime. Consider the following example. (defun f (lst) (loop$ with x = lst do :guard (consp x) (cond ((consp x) (setq x (cdr x))) (t (return x))))) Here we see a runtime guard violation. ACL2 !>(f '(a b c d)) ACL2 Error [Evaluation] in TOP-LEVEL: The guard for a DO$ form, (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))), has been violated by the following alist: ((X)). See :DOC do-loop$. ACL2 !> As noted in the preceding section (on ``The [47mOF-TYPE[0m Keyword''), a call of [47mdo$[0m transforms an alist with each iteration through the loop. The alist initially binds the symbol [47mX[0m to the list [47m(A B C D)[0m, and each iteration modifies that binding by [47mcdr[0ming the value of [47mX[0m, until finally that value is [47mnil[0m --- and then a guard check fails for the value of [47mX[0m, i.e., [47m(CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))[0m is [47mnil[0m. A more detailed explanation may be found in the final section, ``Semantics''. [31;1mThe [47m:MEASURE[0m[31;1m Keyword[0m The discussion above doesn't address the obvious possibility that a [47mDO[0m [47mloop$[0m may not terminate. Consider the following example, which not only assumes that the usual book has been included as discussed above, but also assumes that the form [47m(defwarrant princ$)[0m has been evaluated. ACL2 !>(loop$ with x = '(100 200 300) do :values (state) (setq state (princ$ (car x) *standard-co* state))) ACL2 Error in TOP-LEVEL: No :MEASURE was provided after the DO operator and we failed to find a likely measure. Please supply a :MEASURE in (LOOP$ WITH X = '(100 200 300) DO :VALUES (STATE) (SETQ STATE (PRINC$ (CAR X) *STANDARD-CO* STATE))). See :DOC loop$. ACL2 !> As suggested by the error message, ACL2 has tried to guess a measure, i.e., a term whose value is expected to decrease on each successive iteration. This notion of ``decrease'' is the expected one when the value of the measure is a natural number: smaller in the sense of [47m<[0m. In general, the measure decreases in the sense of [47mL<[0m when [47mlex-fix[0m is applied to each argument; see [L<]. Of course, no measure decreases in the example above, because the values of the variables don't change with each iteration. We can see what happens when we supply an explicit measure: the body is evaluated, as evidenced by the appearance of [47m100[0m in the output, but then the measure is evaluated and is seen not to have decreased from what it was at the start of the previous iteration. ACL2 !>(loop$ with x = '(100 200 300) do :values (state) :measure (acl2-count x) (setq state (princ$ (car x) *standard-co* state))) 100 HARD ACL2 ERROR in DO$: The measure, (ACL2-COUNT X), used in the do loop$ statement (LOOP$ WITH X = '(100 200 300) DO :VALUES (STATE) :MEASURE (ACL2-COUNT X) (SETQ STATE (PRINC$ (CAR X) *STANDARD-CO* STATE))) failed to decrease! Recall that do$ tracks the values of do loop$ variables in an alist. The measure is computed using the values in the alist from before and after execution of the body. We cannot print the values of double floats and live stobjs, if any are found in the alist, because they are raw Lisp objects, not ACL2 objects. We print any double float as its corresponding rational and simply print the name of any live stobj (as a string). Before execution of the do body the alist was ((X 100 200 300) (STATE . "<state>")). After the execution of the do body the alist was ((X 100 200 300) (STATE . "<state>")). Before the execution of the body the measure was 603. After the execution of the body the measure was 603. Logically, in this situation the do$ returns the value of a term whose output signature is (STATE), where the value of any component of type :df is #d0.0 and the value of any stobj component is the last latched value of that stobj. ACL2 Error [Evaluation] in TOP-LEVEL: Evaluation aborted. To debug see :DOC print- gv, see :DOC trace, and see :DOC wet. ACL2 !> Presumably the following is what was intended. ACL2 !>(loop$ with x = '(100 200 300) do :values (state) :measure (acl2-count x) (if (atom x) (return state) (progn (setq state (princ$ (car x) *standard-co* state)) (setq x (cdr x))))) 100200300<state> ACL2 !> In fact, the [47m:MEASURE[0m can be omitted in this case; ACL2 is able to guess [47m(ACL2-COUNT X)[0m. [Guard] verification requires a proof that the measure does indeed go down in the sense of [47mL<[0m, after applying [47mlex-fix[0m to the arguments; see [L<]. Fortunately, guard verification takes advantage of information specified by [47mOF-TYPE[0m and [47m:GUARD[0m keywords. For example, the following two definitions are admitted (after the usual initial [47minclude-book[0m form), even though termination would not be provable without the [47mOF-TYPE[0m expression in the first and the DO body's [47m:GUARD[0m in the second; consider the case that [47mn[0m is -1. (defun foo (max) (declare (xargs :guard (natp max))) (loop$ with n of-type (satisfies natp) = max do (if (= n 0) (return 'stop) (setq n (- n 1))))) (defun foo (max) (declare (xargs :guard (natp max))) (loop$ with n = max do :guard (natp n) (if (= n 0) (return 'stop) (setq n (- n 1))))) [31;1mA More Complex Example[0m We conclude with an example presented in the documentation for [47m[loop$][0m that illustrates all the features above. Notice that the [47m:GUARD[0m keyword may appear not only in the [47mDO[0m body but also in the [47mFINALLY[0m clause, to specify that the indicated guard holds upon entry to the [47mFINALLY[0m clause. Here we assume that we have already evaluated not only the usual [47minclude-book[0m form, but also the [47mdefstobj[0m and [47mdefwarrant[0m forms above. (defun test-loop$ (i0 max st) (declare (xargs :guard (and (natp i0) (natp max)) :stobjs st)) (loop$ with i of-type (satisfies natp) = i0 with cnt of-type integer = 0 do :measure (nfix (- max i)) :guard (and (natp max) (natp cnt) (stp st)) :values (nil st) ; shape of return; can be omitted when it's (nil) (if (>= i max) (loop-finish) (progn (setq st (update-fld i st)) (mv-setq (cnt i) (mv (+ 1 cnt) (+ 1 i))))) finally :guard (stp st) (return (mv (list 'from i0 'to max 'is cnt 'steps 'and 'fld '= (fld st)) st)))) Notice that any variables bound above the [47mloop$[0m may appear in it, for example, the formal parameters of this function. But only variables that are [47mWITH[0m-bound or declared as [stobj]s may be assigned with [47msetq[0m or [47mmv-setq[0m. The [47m:GUARD[0m of [47m(stp st)[0m is necessary, because ACL2 does not automatically infer that stobj recognizer calls hold inside [47mloop$[0m expressions the way it does in ordinary bodies of [47m[defun][0m forms. We can evaluate the function above, as in the following example. ACL2 !>(test-loop$ 3 8 st) ((FROM 3 TO 8 IS 5 STEPS AND FLD = 7) <st>) ACL2 !> SYNTAX General Form: (LOOP$ WITH var1 OF-TYPE spec1 = init1 ; a WITH declaration WITH var2 OF-TYPE spec2 = init2 ... DO :measure m :guard do-guard :values v do-body FINALLY :guard fin-guard fin-body) where much of that is optional: ``[47mOF-TYPE speci[0m'', ``[47m= initi[0m'' (when ``[47mOF-TYPE speci[0m'' is present), ``[47m:MEASURE m[0m'', the two ``[47m:GUARD[0m ...'' clauses, ``[47m:VALUES v[0m'', and ``[47mFINALLY fin-body[0m''. If the [47m:MEASURE[0m is omitted, ACL2 tries to guess a likely measure using the same heuristic it does with recursive [47m[defun][0ms. If [47m:VALUES[0m is omitted then [47mv[0m defaults to [47m(nil)[0m; it indicates the shape of the return value for the [47mloop$[0m expression. [47mDo-body[0m must be a cons, not an atom, as must each of the following that is supplied: [47mm[0m, [47mdo-guard[0m, [47mv[0m, [47mfin-guard[0m, and [47mfin-body[0m. All ACL2 function symbols in the measure [47mm[0m and the two bodies must be [badge]d so [47m[apply$][0m can handle them. Furthermore, they must be [warrant]ed if proofs are to be done about them or if they are in [logic] mode and are called during evaluation. The [47mdo-body[0m and [47mfin-body[0m positions are to be what we call ``DO-body term''. [31;1mThese are not, in general, normal ACL2 terms! They allow restricted uses of [47mRETURN[0m[31;1m, [47mPROGN[0m[31;1m, [47mSETQ[0m[31;1m, [47mMV-SETQ[0m[31;1m, and [47mLOOP-FINISH[0m[31;1m as described below.[0m In the descriptions below we ignore the distinctions between translated and untranslated terms; see [term]). As usual, the restrictions on return values apply only to code, not to terms occurring in theorem statements. * Every ordinary term that returns a single, non-stobj value * An [47mIF[0m call whose first argument is an ordinary term (which necessarily returns a single, non-stobj value) and whose true and false branches are DO-body terms * A [47mLET[0m, [47mLET*[0m, or [47mMV-LET[0m expression, subject to the following restrictions (unless the term is an ordinary term). * The terms in the bindings are all ordinary terms. * The body is a DO-body term. * No variable bound in the bindings is [47mWITH[0m-bound, a known [stobj], or a variable occurring free in the surrounding DO loop$ expression. * [47m(PROGN term1 term2 ... termk)[0m, where each [47mtermi[0m is a DO-body term; also [47m(PROG2 term1 term2)[0m in that case * [47m(RETURN term)[0m, where [47mterm[0m is an ordinary term * [47m(LOOP-FINISH)[0m, but only in a DO body, not in a [47mFINALLY[0m clause * [47m(SETQ var term)[0m, where the variable [47mvar[0m is declared in a [47mWITH[0m declaration or is a stobj name, and [47mterm[0m is an ordinary term that returns a single value, that value being a stobj of type [47mvar[0m if [47mvar[0m is a stobj * [47m(MV-SETQ (var0 ... varn) term)[0m for two or more distinct variables [47mvari[0m, where each [47mvari[0m is declared in a [47mWITH[0m clause or is a stobj name, and [47mterm[0m is an ordinary term that returns n+1 values, where if [47mvari[0m is a stobj then the ith value returned is of that type Notice that in code, where restrictions on return values are in force, no stobj may be let-bound in a [47mDO[0m body or [47mFINALLY[0m clause. This is due not only to the explicit restriction above for [47mLET[0m, [47mLET*[0m, and [47mMV-LET[0m expressions, but also due to the first condition above, on ordinary terms returning a single, non-stobj value. We conclude this section by discussing some syntactic restrictions. The following restriction applies to [47mloop$[0m expressions meeting the following two conditions: [47m:VALUES[0m specifies something other than the default of [47m(NIL)[0m, and there is at least one [47mloop-finish[0m expression in the [47mloop$[0m body. In that case, there must be a [47mFINALLY[0m clause that ACL2 recognizes as always executing a [47mreturn[0m call. This makes sense, since in Common Lisp, the value returned by a [47mloop[0m is [47mnil[0m when ``falling through'' without executing a [47mreturn[0m; but [47mnil[0m would violate the specified [47m:VALUES[0m in the case above. As noted above, assignments with [47msetq[0m and [47mmv-setq[0m may only set stobj variables and variables declared using [47mWITH[0m. This restriction applies to the innermost [47mloop$[0m that contains the assignment. The following, for example, is illegal because the [47mWITH[0m clause for [47mx[0m is not in the [47mloop$[0m immediately above the assignment to [47mx[0m with [47msetq[0m. (defun do-loop-nested-outer-with-var-bad (lst) (loop$ with x = lst do (return (loop$ with temp = '(1 2 3) do (cond ((endp temp) (return (pairlis$ x x))) (t (progn (setq x (cons (car temp) x)) (setq temp (cdr temp))))))))) However, we expect it to be easy in general to work around this restriction. The following definition, for example, accomplishes what was presumably intended above and is accepted by ACL2. (defun do-loop-nested-outer-with-var (lst) (loop$ with x = lst do (return (loop$ with temp = '(1 2 3) with x = x do (cond ((endp temp) (return (pairlis$ x x))) (t (progn (setq x (cons (car temp) x)) (setq temp (cdr temp))))))))) Every [47mreturn[0m expression in the DO body and (if present) [47mFINALLY[0m clause must return a value or [multiple-value]s consistent with what is specified by the [47m:VALUES[0m keyword (by default, a single ordinary value). Note that this requirement does not tolerate the replacement of a stobj by a stobj that is congruent to it. It is illegal for a [47mloop$[0m expression to be in the scope of function bindings of an [47m[flet][0m or [47m[macrolet][0m expression. As noted above, the measure, body, and [47mFINALLY[0m clauses of a DO [47mloop$[0m must be fully [badge]d. In a function call, it is illegal for a LOOP$ expression to occur in a slot whose [ilk] is not [47mnil[0m. See the section SIGNALING ERRORS, below, for how the syntax described here allows for [47mDO[0m [47mloop$[0ms to manipulate [47m[stobj][0ms and [47m[state][0m, including how to signal errors from within the body of the [47mloop$[0m. SEMANTICS Consider again the initial example in the Informal Introduction above. ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (return y)))) (C B A) ACL2 !> We have seen that after initializing variables using [47mWITH[0m clauses, each iteration of a [47mDO[0m [47mloop$[0m updates those variables by evaluating the body of the loop (i.e., the term after the [47mDO[0m keyword), until a [47mreturn[0m expression is executed to return the current value of a term --- in this case, the current value of the term, [47my[0m. Of course, [47mprogn[0m and [47mreturn[0m are not ACL2 functions! (Recall that the word ``applicative'' is part of what ``ACL2'' abbreviates.) The following term is essentially what is produced from the [47mloop$[0m expression above. We discuss it below. (DO$ ; Measure Function (LAMBDA$ (ALIST) (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST)))) (ACL2-COUNT X))) ; Initial Alist (LIST (CONS 'X '(A B C)) (CONS 'Y NIL)) ; Body Function (LAMBDA$ (ALIST) (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST)))) (IF (CONSP X) (LIST NIL NIL ; irrelevant (LIST (CONS 'X (CDR X)) (LIST* 'Y (CAR X) Y))) (LIST :RETURN Y (LIST (CONS 'X X) (CONS 'Y Y)))))) ... ; Other arguments are omitted here. ) The display above is approximate; in particular, it hides some logically irrelevant clutter such as [47m[declare][0m forms and it shows only arguments of [47mdo$[0m relevant to our discussion of the example above. Also, the display employs user-level syntax (i.e., an [3muntranslated term[0m; see [term]). See also the subsection of [47m[lambda$][0m entitled ``About [47mLambda$[0ms and Prover Output.'' The definition of [47mdo$[0m is given later in this topic, for those who care to explore it, but this discussion is intended to be self-contained. [47mDo$[0m operates by maintaining an alist that maps variables to values, for all variables referenced in the [47mloop$[0m expression --- though only variables that are declared in [47mWITH[0m clauses or are stobjs may be modified. This alist is updated on each iteration by calling [47m[apply$][0m on the ``Body Function'' above, producing a 3-element list [47m(exit-token val new-alist)[0m. If [47mexit-token[0m is [47m:RETURN[0m then [47mval[0m is returned. But if [47mexit-token[0m is [47mnil[0m, then [47mdo$[0m is called recursively with [47mnew-alist[0m as its alist argument. To see [47mdo$[0m in action one can submit the following forms. Here the body of [47mf[0m is just the [47mloop$[0m expression shown above. Notice that [47mf[0m is not [guard]-verified; after submitting [47m(verify-guards f)[0m the [47mloop$[0m expression is evaluated as a Common Lisp [47mloop[0m call rather than using [47mdo$[0m, so there would be no [trace] output. Don't worry about having a precise understanding of the fancy calls of [47m[trace!][0m; the comments there should suffice. (include-book "projects/apply/top" :dir :system) (defun f () (loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (return y))))) ; Store the translated body function so that we can access it later ; with (@ my-body-fn): (trace! (do$ :entry (f-put-global 'my-body-fn (nth 2 arglist) state))) ; Run f to store to my-body-fn as commented above. (f) ; Trace do$ calls and trace calls of apply$ on the body function. (trace! (do$ :notinline t ; include recursive calls :cond (eq traced-fn 'do$) ; skip *1* call :entry (list traced-fn alist)) (apply$ :cond (equal (car arglist) (@ my-body-fn)) :entry (list traced-fn (cadr arglist) ; the alist ))) (f) Here is the trace output from the final call of [47mf[0m above; analysis follows. ACL2 !>(f) 1> (DO$ ((X A B C) (Y))) 2> (APPLY$ (((X A B C) (Y)))) <2 (APPLY$ (NIL NIL ((X B C) (Y A)))) 2> (DO$ ((X B C) (Y A))) 3> (APPLY$ (((X B C) (Y A)))) <3 (APPLY$ (NIL NIL ((X C) (Y B A)))) 3> (DO$ ((X C) (Y B A))) 4> (APPLY$ (((X C) (Y B A)))) <4 (APPLY$ (NIL NIL ((X) (Y C B A)))) 4> (DO$ ((X) (Y C B A))) 5> (APPLY$ (((X) (Y C B A)))) <5 (APPLY$ (:RETURN (C B A) ((X) (Y C B A)))) <4 (DO$ (C B A)) <3 (DO$ (C B A)) <2 (DO$ (C B A)) <1 (DO$ (C B A)) (C B A) ACL2 !> First consider the calls of [47mdo$[0m above. You can see that [47mX[0m is initially bound in the alist to [47m(A B C)[0m, but on successive [47mdo$[0m calls, [47mX[0m is bound to successive [47mcdr[0ms of [47m(A B C)[0m. Meanwhile, the accumulator variable [47mY[0m is initially bound to [47mNIL[0m but at each call of [47mdo$[0m, the next [47mcar[0m of [47m(A B C)[0m is pushed onto the binding of [47mY[0m. Now consider the calls of [47m[apply$][0m. Up until the last call, [47mapply$[0ming the body function results in a triple of the form [47m(mv nil nil new-alist)[0m, where [47mnew-alist[0m is supplied as the alist argument for the next [47mdo$[0m call. The last call of [47mapply$[0m on the body function gives the result [47m(mv :RETURN (C B A) new-alist)[0m, where [47m(C B A)[0m is the value returned by the calls of [47mdo$[0m. Now consider this variant of the above example, which was given above when introducing [47mFINALLY[0m clauses. ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (loop-finish))) finally (return y)) (C B A) ACL2 !> The corresponding [47mdo$[0m call is similar to that of the preceding example, but notice [47m:LOOP-FINISH[0m in place of [47m:RETURN[0m, and notice that we show the fourth argument this time: the function corresponding to the [47mFINALLY[0m clause. (DO$ ; Measure Function (LAMBDA$ (ALIST) (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST)))) (ACL2-COUNT X))) ; Initial Alist (LIST (CONS 'X '(A B C)) (CONS 'Y NIL)) ; Body Function (LAMBDA$ (ALIST) (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST)))) (IF (CONSP X) (LIST NIL NIL ; irrelevant (LIST (CONS 'X (CDR X)) (LIST* 'Y (CAR X) Y))) (LIST :LOOP-FINISH NIL ; irrelevant (LIST (CONS 'X X) (CONS 'Y Y)))))) ; FINALLY function (LAMBDA$ (ALIST) (LET ((X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (Y (CDR (ASSOC-EQ-SAFE 'Y ALIST)))) (LIST :RETURN Y (LIST (CONS 'X X) (CONS 'Y Y))))) ; Values (output signature) '(NIL) ... ; Last argument omitted here. ) Above, we also took the opportunity to show the fifth argument of [47mdo$[0m, which is the output signature of the logical value to be returned should the measure fail to decrease. That output signature is specified with the [47m:VALUES[0m keyword in a [47mdo[0m [47mloop$[0m. If omitted and the [47mloop$[0m returns a single ordinary object, the output signature is [47m(nil)[0m as here. The [47mvalues[0m argument to [47mdo$[0m is passed along unchanged as the function iterates and, should the measure fail to decrease, the signature is used to compute a default answer. However, that default answer is never relevant to evaluations because a hard ACL2 error actually occurs. The default answer may be relevant when reasoning about [47mdo$[0m calls. Since guard verification of a [47mdo[0m [47mloop$[0m guarantees termination, the default answer is never relevant when dealing with guard verified functions containing [47mdo[0m [47mloop$[0ms. Here is the definition of [47m[do$][0m. [31;1mFunction: [0m<do$> (defun do$ (measure-fn alist do-fn finally-fn values dolia) (declare (xargs :guard (and (apply$-guard measure-fn '(nil)) (apply$-guard do-fn '(nil)) (apply$-guard finally-fn '(nil)) (weak-dolia-p dolia)))) (let* ((stobj-values-p (not (all-nils (true-list-fix values)))) (old-measure-value (and stobj-values-p (apply$ measure-fn (list alist)))) (triple (true-list-fix (apply$ do-fn (list alist)))) (exit-token (car triple)) (val (cadr triple)) (new-alist (caddr triple))) (cond ((eq exit-token :return) val) ((eq exit-token :loop-finish) (let* ((triple (true-list-fix (apply$ finally-fn (list new-alist)))) (exit-token (car triple)) (val (cadr triple))) (if (eq exit-token :return) val nil))) ((l< (lex-fix (apply$ measure-fn (list new-alist))) (lex-fix (if stobj-values-p old-measure-value (apply$ measure-fn (list alist))))) (do$ measure-fn new-alist do-fn finally-fn values dolia)) (t (prog2$ (let ((all-stobj-names (true-list-fix (access dolia dolia :all-stobj-names))) (untrans-measure (access dolia dolia :untrans-measure)) (untrans-do-loop$ (access dolia dolia :untrans-do-loop$))) (er hard? 'do$ "The measure, ~x0, used in the do loop$ ~ statement~%~Y12~%failed to decrease! Recall that do$ tracks ~ the values of do loop$ variables in an alist. The measure is ~ computed using the values in the alist from before and after ~ execution of the body. We cannot print the values of double ~ floats and live stobjs, if any are found in the alist, ~ because they are raw Lisp objects, not ACL2 objects. We ~ print any double float as its corresponding rational and ~ simply print the name of any live stobj (as a ~ string).~%~%Before execution of the do body the alist ~ was~%~Y32.~|After the execution of the do body the alist ~ was~%~Y42.~|Before the execution of the body the measure ~ was~%~x5.~|After the execution of the body the measure ~ was~%~x6.~|~%Logically, in this situation the do$ returns the ~ value of a term whose output signature is ~x7, where the ~ value of any component of type :df is #d0.0 and the value of ~ any stobj component is the last latched value of that stobj." untrans-measure untrans-do-loop$ nil (eviscerate-do$-alist alist all-stobj-names) (eviscerate-do$-alist new-alist all-stobj-names) (if stobj-values-p old-measure-value (apply$ measure-fn (list alist))) (apply$ measure-fn (list new-alist)) values)) (loop$-default-values values new-alist)))))) We conclude by returning to an earlier example that illustrates runtime guard-checking. But this time we do some tracing, as indicated. (defun f (lst) (loop$ with x = lst do :guard (consp x) (cond ((consp x) (setq x (cdr x))) (t (return x))))) (trace! (do$ :entry (list traced-fn alist) :notinline t)) (trace$ do-body-guard-wrapper) As before, we have a guard violation. The trace output is explained below. ACL2 !>(f '(a b c d)) 1> (ACL2_*1*_ACL2::DO$ ((X A B C D))) 2> (DO$ ((X A B C D))) 3> (DO-BODY-GUARD-WRAPPER T NIL) <3 (DO-BODY-GUARD-WRAPPER T) 3> (DO-BODY-GUARD-WRAPPER T NIL) <3 (DO-BODY-GUARD-WRAPPER T) 3> (DO-BODY-GUARD-WRAPPER T NIL) <3 (DO-BODY-GUARD-WRAPPER T) 3> (DO$ ((X B C D))) 4> (DO-BODY-GUARD-WRAPPER T NIL) <4 (DO-BODY-GUARD-WRAPPER T) 4> (DO-BODY-GUARD-WRAPPER T NIL) <4 (DO-BODY-GUARD-WRAPPER T) 4> (DO-BODY-GUARD-WRAPPER T NIL) <4 (DO-BODY-GUARD-WRAPPER T) 4> (DO$ ((X C D))) 5> (DO-BODY-GUARD-WRAPPER T NIL) <5 (DO-BODY-GUARD-WRAPPER T) 5> (DO-BODY-GUARD-WRAPPER T NIL) <5 (DO-BODY-GUARD-WRAPPER T) 5> (DO-BODY-GUARD-WRAPPER T NIL) <5 (DO-BODY-GUARD-WRAPPER T) 5> (DO$ ((X D))) 6> (DO-BODY-GUARD-WRAPPER T NIL) <6 (DO-BODY-GUARD-WRAPPER T) 6> (DO-BODY-GUARD-WRAPPER NIL NIL) <6 (DO-BODY-GUARD-WRAPPER NIL) ACL2 Error [Evaluation] in TOP-LEVEL: The guard for a DO$ form, (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))), has been violated by the following alist: ((X)). See :DOC do-loop$. ACL2 !> To understand the trace output above, we first take a look at the translation of the [47mloop$[0m expression above. This time we show the corresponding [47mdo$[0m form with [47m[declare][0m forms included, but as before some parts of this form are simplified, untranslated, or elided. (You can see the exact translation by applying [47m:[0m[47m[trans][0m to the [47mdo$[0m call.) Note that [47mdo-body-guard-wrapper[0m is just an identity function (on its first argument) used by the implementation, but it is handy here for the explanation that follows. (DO$ ;; measure: '(LAMBDA (ALIST) (DECLARE (XARGS :GUARD (DO-BODY-GUARD-WRAPPER (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))) NIL))) ((LAMBDA (X) (ACL2-COUNT X)) (CDR (ASSOC-EQ-SAFE 'X ALIST)))) ;; alist: (LIST (CONS 'X LST)) ;; body: '(LAMBDA (ALIST) (DECLARE (XARGS :GUARD (DO-BODY-GUARD-WRAPPER (AND (ALISTP ALIST) (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))) NIL))) ((LAMBDA (X) (IF (CONSP X) (LIST NIL NIL (LET ((X (CDR X))) (LIST (CONS 'X X)))) (LIST :RETURN X (LIST (CONS 'X X))))) (CDR (ASSOC-EQ-SAFE 'X ALIST)))) .....) Recall that [47mdo$[0m works by repeatedly applying the given lambda to its alist argument, which initially binds [47m'X[0m to [47mLST[0m as shown above. [47mDo$[0m recurs when that application returns a triple [47m(mv nil nil new-alist)[0m, where [47mnew-alist[0m is the alist returned by the body of the [47mloop$[0m expression. But when [47mdo$[0m applies the given [lambda] object, it first checks the [47m:guard[0m of that lambda. We also see that before [47mdo$[0m recurs, it applies its [47mmeasure-fn[0m argument to the input alist and to [47mnew-alist[0m. So let's focus on the following from the end of the trace output above. 5> (DO$ ((X D))) 6> (DO-BODY-GUARD-WRAPPER T NIL) <6 (DO-BODY-GUARD-WRAPPER T) 6> (DO-BODY-GUARD-WRAPPER NIL NIL) <6 (DO-BODY-GUARD-WRAPPER NIL) The first [47mDO-BODY-GUARD-WRAPPER[0m call comes from the guard of the lambda that represents the body of the [47mdo$[0m loop, from the expression [47m(apply$ do-fn (list alist))[0m in the definition of [47mdo$[0m (above). Here [47malist[0m is [47m((X D))[0m, so the conjunct [47m(CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))[0m from that lambda's guard is true. The second call of [47mDO-BODY-GUARD-WRAPPER[0m comes from the expression [47m(apply$ measure-fn (list new-alist))[0m in the definition of [47mdo$[0m. But [47mnew-alist[0m is [47mnil[0m, so the conjunct [47m(CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))[0m from the measure lambda's guard is false, so the guard evaluates to [47mnil[0m. SIGNALING ERRORS We explain the subtleties of error signaling from within [47mDO[0m [47mloop$[0ms by example. To illustrate the full complexity of the situation, our example will involve a [47mDO[0m that is manipulating a [stobj], and we'll verify the guards. The basic idea is that we'll define a function, called [47mtransaction[0m, that either detects and signals an error or updates the stobj, and then we'll write a [47mDO[0m [47mloop$[0m that executes a series of transactions. In fact, you may think of the stobj as representing an account that must maintain a non-negative balance and the transaction as taking an integer and adding it to the balance provided that doesn't produce a negative balance. Managing the signatures of the various functions in body of the [47mloop$[0m and declaring the ``right'' guards takes some experience. After we've presented a correct solution we will show some plausible alternatives and explain why they are unacceptable. Recall that the standard idiom for signaling a ``soft'' error in ACL2 is to call the function [47m[error1][0m, usually via the macro [47m[er][0m. [47mError1[0m returns an [error-triple] of the form [47m(mv t nil state)[0m. So our [47mDO[0m [47mloop$[0m will necessarily manipulate [47mstate[0m in addition to the user's stobj. To admit the functions shown below, first execute these three commands. (include-book "projects/apply/top" :dir :system) (set-state-ok t) (defstobj st (balance :type (satisfies natp) :initially 0)) Note that our stobj has just one field, named [47mbalance[0m, which must be a natural number and is initially 0. Below is the basic [47mtransaction[0m function which may signal an error. Note that two unnecessary lines are commented out as explained in note [1] below. (defun transaction (delta st state) (declare (xargs :stobjs (st state) :guard (and (integerp delta) ; (stp st) ; [1] ; (state-p state) ; [1] (error1-state-p state)))) ; [2] (cond ((< (balance st) (- delta)) (mv-let (erp val state) ; [3] (er soft 'transaction "The stobj's balance is ~x0 but the delta is ~x1, so this ~ transaction is not allowed!" (balance st) delta) (declare (ignore val)) (mv erp st state))) (t (let ((st (update-balance (+ (balance st) delta) st))) (mv nil st state))))) Notes on [47mtransaction[0m: * [1] We don't need to include [47m(stp state)[0m and [47m(state-p state)[0m explicitly in the [47m:guard[0m for the function because they're implicitly included by the [47m:stobjs[0m declaration. * [2] The [47m[er][0m macro expands to a call of the function [47m[error1][0m, and [47merror1[0m requires that its [47m[state][0m argument not only satisfy the recognizer for ACL2 states, [47mstate-p[0m, but also some other conditions to allow formatted printing to certain channels. See [47m:[0m[47m[pe][0m [47merror1-state-p[0m and its subroutine [47mfmt-state-p[0m. By the way, you won't see ``[47m(state-p state)[0m'' in the [47m:guard[0m declaration of [47merror1[0m. But it is implicit in the use of the variable named [47mstate[0m as a formal. To see the full guard of a function, [3mfn[0m, you can do [47m:[0m[47m[args][0m [3mfn[0m or, alternatively, [47m(guard '[0m[3mfn[0m[47m nil (w state))[0m. * [3] We signal an error with the [47mer[0m macro. But the signature of [47mer[0m is [47m(mv * * state)[0m, i.e., the first two values returned are ``ordinary'' objects, not stobjs. But our function, [47mtransaction[0m, must return the (possibly) modified stobj [47mst[0m. So we ``catch'' the error triple generated by [47mer[0m and replace the ordinary [47mval[0m, which in this case is [47mnil[0m, by [47mst[0m. Since we'll use [47mtransaction[0m in a [47mDO[0m [47mloop$[0m, we need a warrant. (defwarrant transaction) The lemma below is not strictly necessary. If we don't prove it here, the guard proof for our [47mloop$[0m takes longer because we have to prove a more complicated instance of this lemma by induction. (defthm dumb-lemma (implies (and lst (integer-listp lst)) (integerp (car lst))) :rule-classes :type-prescription) Finally, we define the function that executes a series of [47mtransaction[0ms on a sequence of integers. But it may detect and signal an error partway through the sequence. Note that several lines are commented out, either because they are optional or because they are prohibited, as explained in the accompanying notes below. (defun transaction-loop (delta-lst st state) (declare (xargs :stobjs (st state) :guard (and (integer-listp delta-lst) ; (stp st) ; See Note [1] above ; (state-p state) ; See Note [1] above (error1-state-p state)) :guard-hints (("Goal" :in-theory (enable error1))))) (loop$ with lst = delta-lst ; with st ; [4] ; with state ; [4] with erp ; [5] do :guard (and (integer-listp lst) (stp st) ; [6] (state-p state) ; [6] (error1-state-p state)) :values (nil st state) (cond ((eq lst nil) (return (mv nil st state))) (t (progn ; [7] (mv-setq (erp st state) (transaction (car lst) st state)) (cond (erp (return (mv erp st state))) (t (setq lst (cdr lst))))))))) Notes on [47mtransaction-loop[0m: * [4] One might think that we need to bind [47mst[0m and [47mstate[0m in [47mWITH[0m clauses because, in the body of the [47mDO[0m [47mloop$[0m, we assign to them, with [47mmv-setq[0m, here, or in other examples, with [47msetq[0m. But ACL2 disallows binding stobj names in [47mWITH[0m clauses. A syntax error is signaled if you try that. * [5] We must bind [47merp[0m in a [47mWITH[0m clause because we assign to it in the body and it is an ordinary object. * [6] One might think that we do not need to include [47m(stp st)[0m and [47m(state-p state)[0m in the [47m:guard[0m of the [47mDO[0m [47mloop$[0m body, for the same reasons we did not have to include them in the [47m:guard[0m of the function itself: might they be implicitly included by virtue of their being stobj names? The answer is no! If a stobj is used in the body of a [47mDO[0m [47mloop$[0m, the [47m:guard[0m for the [47mDO[0m [47mloop$[0m must include the stobj recognizer if guard checking is to succeed. * [7] Finally, the construction (progn (mv-setq (erp st state) <term>) <do-body-term>) used here may seem odd. One might be inclined to write something like this instead: (mv-let (erp st state) <term> <do-body-term>) However, the latter construction is syntactically illegal in the body of a [47mDO[0m [47mloop$[0m. The reason has to do with the precise definition of ``do-body terms'' (see the SYNTAX section above). Recall that do-body terms are term-like but allow very restricted uses of [47mreturn[0m, [47mprogn[0m, [47msetq[0m, [47mmv-setq[0m, and [47mloop-finish[0m and possibly other do-body subterms. Do-body terms are not actually ACL2 terms! To be precise, one might have tried to use the following as the body of the [47mloop$[0m in [47mtransaction-loop[0m. (cond ((eq lst nil) (return (mv nil st state))) (t (mv-let (erp st state) (transaction (car lst) st state) (cond (erp (return (mv erp st state))) (t (setq lst (cdr lst))))))) Note the [47mmv-let[0m. It is syntactically illegal because its final argument, namely the [47mcond[0m-expression, uses [47mreturn[0m and [47msetq[0m where ACL2 function names are required. In writing the above, the user has presumed that an [47mmv-let[0m expression in a do-body term allows the final argument to be a do-body term instead of an ACL2 term. This presumption is incorrect. Instead, use [47mprogn[0m and [47mmv-setq[0m to field the values of a multi-valued function like [47mtransaction[0m and then write the do-body term to process them. Here is a sample session log after introducing the correct definitions above. Note that the balance starts at 0, the user, employing the function [47mtransaction[0m, adds 100 and then attempts to subtract 150. An error is signaled and the balance remains 100. Then the user runs the [47mtransaction-loop[0m function with a starting balance of 100 and attempts to successively subtract 20, then 30, then 55, and then attempts to add 200. The loop terminates with an error on the 55 and leaves the balance at 50, never processing the 200. ACL2 !>(balance st) 0 ACL2 !>(transaction 100 st state) (NIL <st> <state>) ACL2 !>(balance st) 100 ACL2 !>(transaction -150 st state) ACL2 Error in TRANSACTION: The stobj's balance is 100 but the delta is -150, so this transaction is not allowed! (T <st> <state>) ACL2 !>(balance st) 100 ACL2 !>(transaction-loop '(-20 -30 -55 200) st state) ACL2 Error in TRANSACTION: The stobj's balance is 50 but the delta is -55, so this transaction is not allowed! (T <st> <state>) ACL2 !>(balance st) 50 Subtopics [Do$] Definition of [47mdo$[0m") (do-not (hints) "Instruct the theorem prover not to do certain things. See [hints] for documentation about the [47m:do-not[0m keyword for prover [47m:hints[0m. See [do-not-hint] for documentation about the [47mdo-not[0m macro that controls a mechanism for automatically suggesting [47m:do-not[0m and [47m:do-not-induct[0m hints.") (do-not-induct (pointers) "See [hints] for information about the keyword [47m:do-not-induct[0m.") (doc (documentation) "[Documentation] at the terminal The [47m:doc[0m command may be used at the ACL2 prompt to access the ACL2 system [documentation]. Usually (when the [xdoc] system has been included) it can also access other documentation topics defined in the current session, including via included books. However, most users will probably access the ACL2 documentation in other ways; see [documentation]. In particular, consider using the {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}, for topics documented in the ACL2 community [books] or in the ACL2 system (where the latter are rearranged). If you are not happy with the way text is displayed using [47m:doc[0m, see [xdoc::terminal]. Alternatively, consider using the ACL2-Doc Emacs browser; see [ACL2-Doc]. Examples: ACL2 !>:doc DEFTHM ; print documentation of DEFTHM ACL2 !>:doc logical-name ; print documentation of LOGICAL-NAME General Form: ACL2>:doc name Note that links are always printed with respect to the [47m"ACL2"[0m package (that is, as though the current package were [47m"ACL2"[0m). So for example, a link to the present topic will be displayed as [47m[doc][0m, not as [47m[acl2::doc][0m, regardless of the current package or the package of the topic being displayed. Such links can thus take you to topics in the ACL2-Doc Emacs browser (see [ACL2-Doc]). Note that [community-book] [47mxdoc/top[0m redefines [47m:doc[0m (using [add-ld-keyword-alias!]) to invoke the similar macro [47mxdoc[0m, which can access documentation topics defined in books.") (doc-terminal-test-1 (documentation) "Short [31;1mSymbol [47mEQUAL[0m[31;1m and the rest is still bold.[0m") (doc-terminal-test-2 (documentation) "Short [4mStart underline [31;1mStart bold [3mStart italics [47mTYPEWRITER FONT [WHICH ENDS HERE][0m[4m[31;1m[3m Bold italics underlined[0m[4m[31;1m Bold underlined.[0m[4m Underlined[0m Normal text") (documentation (top) "Information about options for downloading and viewing the ACL2 documentation, contributing documentation, and the available tools for documenting your own books. Available Documentation If you are new to ACL2, see the [ACL2-tutorial] for introductory tours, tutorials, and information about textbooks about ACL2. The {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2} also provides many links to academic publications about ACL2, including the ACL2 Workshop series. Beyond these resources, there is a vast [31;1mACL2+Books Manual[0m with reference material covering the ACL2 system itself and also many [community-books]. There are a few ways to access the manual: * [31;1mThe online version (recommended).[0m If you expect to have an internet connection while using the documentation, you may prefer to use the online version of the {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}. * [31;1mA local version.[0m If you sometimes work without an internet connection, you can {download | download/} a local copy of any web-based XDOC manual using the "down arrow" icon at the top of the page. You can alternately build your own copy of the manual; see [3mBuilding the manual[0m in [books-certification]. * [31;1mThe ACL2-Doc Emacs version.[0m If you would like to view the documentation using Emacs instead of a web browser, there is a feature-rich Emacs-based documentation browser provided by the ACL2 system. See [ACL2-doc] for details. While you are using ACL2, you can get documentation at the terminal with the [47m:[0m[47m[doc][0m command, e.g., by typing [47m:doc rewrite[0m. This is often handy, but note that it won't show you any documentation for books that you haven't loaded yet! When you type [47m:DOC <topic>[0m at the terminal for a given [47m<topic>[0m, ACL2 responds with documentation for that topic. Unless you include books that incorporate additional documentation, [47m<topic>[0m must be documentation that is provided with the ACL2 system (not the [community-books]). Documenting Your Books Documentation is written using [xdoc], and may be found in the [community-books]. Everyone is welcome to edit and contribute to that documentation. In particular, you are welcome to edit the book that contains ACL2 system documentation, [47mbooks/system/doc/acl2-doc.lisp[0m. (Please do not edit ACL2 source file [47mdoc.lisp[0m, which is generated from that book. More generally, edit only files under the [47mbooks/[0m directory.) You can also use XDOC to document your own books and to build custom manuals for your organization. [31;1mRemark for Experienced Users[0m. Occasionally it might make sense to add a link to your book's documentation from the ACL2 system documentation, which is in [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m. You are welcome to do so, but in that case, also add to the constant [47m*acl2-broken-links-alist*[0m near the top of that file, as described in a comment in that constant. For example, that constant's value has the following line. (FTY::DEFPROD "[books]/centaur/fty/top.lisp") That line may have been added because in the form [47m(defxdoc defrec ...)[0m in [47macl2-doc.lisp[0m, we find a link to [47mfty::defprod[0m. You can do similarly for your own added link. If your topic is not in the [47m"ACL2"[0m package, such as in the example link [47mfty::defprod[0m above, then add a suitable [47m[include-book][0m form to [47mbooks/system/doc/cert.acl2[0m. For example, that file includes the line (include-book "centaur/fty/portcullis" :dir :system) in order to define the [47m"FTY"[0m package. End of Remark for Experienced Users Other Resources If you want documentation on an ACL2 function or macro that is not documented, there are still several alternatives. ACL2 !>:args fn will print the arguments and some other relevant information about the named function or macro. This information is all gleaned from the definition and hence this is a definitive way to determine if [47mfn[0m is defined as a function or macro. You might also want to type: ACL2 !>:pc fn which will print the [command] that introduced [47mfn[0m. You should see [command-descriptor] for details on the kinds of input you can give the [47m:[0m[47m[pc][0m command. Subtopics [ACL2-doc] A custom Emacs browser for reading ACL2 [documentation] [ACL2-doc-summary] Summary of [ACL2-doc] commands [Args] [47margs[0m, [47m[guard][0m, [47mtype[0m, [47m[constraint][0m, etc., of a function symbol [Broken-link] Placeholder for link to documentation that resides in the community books [Course-materials] Some ACL2 course materials [Doc] [Documentation] at the terminal [Doc-terminal-test-1] Short [Doc-terminal-test-2] Short [Documentation-copyright] Copyright and authorship of documentation [Finding-documentation] Searching the documentation [Loop$-primer] Primer for using [47m[loop$][0m [Operational-semantics] Modeling State Machines [Pointers] Links pointing to relevant documentation topics [Recursion-and-induction] Recursion and Induction") (documentation-copyright (copyright documentation) "Copyright and authorship of documentation There are two manuals associated with ACL2: the ACL2 User's Manual and the ACL2+Books Manual. See [documentation]. The former is distributed with ACL2, you can reach many links into it from the ACL2 home page. The latter may be preferred for routine browsing, since it extends the ACL2 User's Manual with documentation obtained from the [community-books]. The ACL2 User's Manual is the basis for using the [47m:[0m[47m[doc][0m command at the terminal when ACL2 starts up. Its source in the ACL2 [community-books] as file [47mbooks/system/doc/acl2-doc.lisp[0m. Members of the ACL2 community contribute to it, although its original authors are the ACL2 authors. It is copyrighted under the terms of the [47mLICENSE[0m file distributed with ACL2. The ACL2+Books Manual is a mechanically generated mashup derived from both the ACL2 User's Manual and the [community-books]. The ACL2+Books Manual thus has contributions from many authors. At the top of each topic, in a line under the topic name, you will generally find either ``ACL2 Sources'' or the name of a Community Book. In the former case, the text is from the ACL2 User's Manual and is authored, copyrighted, and licensed as per the ACL2 [copyright]. When a book is named, the content was extracted from that book which may be inspected for authorship, copyright, and license terms. There are two standard tools for browsing these manuals, other than using the [47m:[0m[47m[doc][0m command at the terminal. * [31;1mThe ACL2 [Xdoc] Fancy Viewer.[0m This tool, written by Jared Davis, is included with the web-based version of each manual. Information on copyright and licensing are provided in {its LICENSE file | LICENSE}. * [31;1mThe [ACL2-doc] Emacs browser.[0m This tool, authored by Matt Kaufmann and J Strother Moore, is distributed with ACL2 and is licensed under the terms of the [47mLICENSE[0m file distributed with ACL2.") (double-float (pointers) "See [df].") (double-float (pointers) "See [df].") (double-rewrite (rewrite) "Cause a term to be rewritten twice Logically, [47mdouble-rewrite[0m is the [47m[identity][0m function: [47m(double-rewrite x)[0m is equal to [47mx[0m. However, the ACL2 rewriter treats calls of [47mdouble-rewrite[0m in the following special manner. When it encounters a term [47m(double-rewrite u)[0m, it first rewrites [47mu[0m in the current context, and then the rewriter rewrites the result. Such double-rewriting is rarely necessary, but it can be useful when rewriting under non-trivial equivalence relations (see [equivalence]). The following example will illustrate the issue. ; Define an equivalence relation. (defun my-equiv (x y) (equal x y)) (defequiv my-equiv) ; Define a unary function whose argument is preserved by my-equiv. (defun foo (x) (declare (ignore x)) t) (defcong my-equiv equal (foo x) 1) ; Define some other unary functions. (defun g (x) x) (defun h1 (x) x) (defun h2 (x) x) ; Prove some lemmas and then disable the functions above. (defthm lemma-1 (my-equiv (h1 x) (h2 x))) (defthm lemma-2 (foo (h2 x))) (defthm lemma-3 (implies (foo x) (equal (g x) x))) (in-theory (union-theories (theory 'minimal-theory) '(lemma-1 lemma-2 lemma-3 my-equiv-implies-equal-foo-1))) ; Attempt to prove a simple theorem that follows ``obviously'' from the ; events above. (thm (equal (g (h1 a)) (h1 a))) We might expect the proof of this final [47mthm[0m to succeed by the following reasoning. It is immediate from [47mlemma-3[0m provided we can establish [47m(foo (h1 a))[0m. By the [47mdefcong[0m event above, we know that [47m(foo (h1 a))[0m equals [47m(foo (h2 a))[0m provided [47m(my-equiv (h1 a) (h2 a))[0m; but this is immediate from [47mlemma-1[0m. And finally, [47m(foo (h2 a))[0m is true by [47mlemma-2[0m. Unfortunately, the proof fails. But fortunately, ACL2 gives the following useful warning when [47mlemma-3[0m is submitted: ACL2 Warning [Double-rewrite] in ( DEFTHM LEMMA-3 ...): In the :REWRITE rule generated from LEMMA-3, equivalence relation MY-EQUIV is maintained at one problematic occurrence of variable X in hypothesis (FOO X), but not at any binding occurrence of X. Consider replacing that occurrence of X in this hypothesis with (DOUBLE-REWRITE X). See :doc double- rewrite for more information on this issue. We can follow the warning's advice by changing [47mlemma-3[0m to the following. (defthm lemma-3 (implies (foo (double-rewrite x)) (equal (g x) x))) With this change, the proof succeeds for the final [47mthm[0m above. In practice, it should suffice for users to follow the advice given in the ``[47mDouble-rewrite[0m'' warnings, by adding calls of [47mdouble-rewrite[0m around certain variable occurrences. But this can cause inefficiency in large proof efforts. For that reason, and for completeness, it seems prudent to explain more carefully what is going on; and that is what we do for the remainder of this [documentation] topic. Optionally, also see the paper ``Double Rewriting for Equivalential Reasoning in ACL2'' by Matt Kaufmann and J Strother Moore, in the proceedings of the 2006 ACL2 Workshop (paper is published in the {ACM Digital Library | http://portal.acm.org/toc.cfm?id=1217975}); you might also find it for free {here | http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.90.7190&rep=rep1&type=pdf}. [31;1mSuggesting congruence rules.[0m Sometimes the best way to respond to a ``[47mDouble-rewrite[0m'' warning may be to prove a congruence rule. Consider for example this rule. (defthm insert-sort-is-id (perm (insert-sort x) x)) Assuming that [47mperm[0m has been identified as an [equivalence] relation (see [defequiv]), we will get the following warning. ACL2 Warning [Double-rewrite] in ( DEFTHM INSERT-SORT-IS-ID ...): In a :REWRITE rule generated from INSERT-SORT-IS-ID, equivalence relation PERM is maintained at one problematic occurrence of variable X in the right-hand side, but not at any binding occurrence of X. Consider replacing that occurrence of X in the right-hand side with (DOUBLE-REWRITE X). See :doc double-rewrite for more information on this issue. The problem is that the second occurrence of [47mx[0m (the right-hand side of the rule [47minsert-sort-is-id[0m) is in a context where [47mperm[0m is to be maintained, yet in this example, the argument [47mx[0m of [47minsert-sort[0m on the left-hand side of that rule is in a context where [47mperm[0m will not be maintained. This can lead one to consider the possibility that [47mperm[0m could be maintained in that left-hand side occurrence of [47mx[0m, and if so, to prove the following congruence rule. (defcong perm perm (insert-sort x) 1) This will eliminate the above warning for [47minsert-sort-is-id[0m. More important, this [47m[defcong][0m event would probably be useful, since it would allow rewrite rules with equivalence relation [47mperm[0m to operate on the first argument of any call of [47minsert-sort[0m whose context calls for maintaining [47mperm[0m. [31;1mDetails on double-rewrite.[0m The reader who wants these details may first wish to see [equivalence] for relevant review. The ACL2 rewriter takes a number of contextual arguments, including the generated equivalence relation being maintained (see [congruence]) and an association list that maps variables to terms. We call the latter alist the [47munify-subst[0m because it is produced by unifying (actually matching) a pattern against a current term; let us explain this point by returning to the example above. Consider what happens when the rewriter is given the top-level goal of the [47mthm[0m above. (equal (g (h1 a)) (h1 a)) This rewrite is performed with the empty alist ([47munify-subst[0m), and is begun by rewriting the first argument (in that same empty [47munify-subst[0m): (g (h1 a)) Note that the only equivalence relation being maintained at this point is [47mequal[0m. Now, the rewriter notices that the left-hand side of [47mlemma-3[0m, which is [47m(g x)[0m, matches [47m(g (h1 a))[0m. The rewriter thus creates a [47munify-subst[0m binding [47mx[0m to [47m(h1 a)[0m: [47m((x . (h1 a)))[0m. It now attempts to rewrite the hypothesis of [47mlemma-3[0m to [47mt[0m under this [47munify-subst[0m. Consider what happens now if the hypothesis of [47mlemma-3[0m is [47m(foo x)[0m. To rewrite this hypothesis under a [47munify-subst[0m of [47m((x . (h1 a)))[0m, it will first rewrite [47mx[0m under this [47munify-subst[0m. The key observation here is that this rewrite takes place simply by returning the value of [47mx[0m in the [47munify-subst[0m, namely [47m(h1 a)[0m. No further rewriting is done! The efficiency of the ACL2 rewriter depends on such caching of previous rewriting results. But suppose that, instead, the hypothesis of [47mlemma-3[0m is [47m(foo (double-rewrite x))[0m. As before, the rewriter dives to the first argument of this call of [47mfoo[0m. But this time the rewriter sees the call [47m(double-rewrite x)[0m, which it handles as follows. First, [47mx[0m is rewritten as before, yielding [47m(h1 a)[0m. But now, because of the call of [47mdouble-rewrite[0m, the rewriter takes [47m(h1 a)[0m and rewrites it under the empty [47munify-subst[0m. What's more, because of the [47mdefcong[0m event above, this rewrite takes place in a context where it suffices to maintain the equivalence relation [47mmy-equiv[0m. This allows for the application of [47mlemma-1[0m, hence [47m(h1 a)[0m is rewritten (under [47munify-subst[0m = [47mnil[0m) to [47m(h2 a)[0m. Popping back up, the rewriter will now rewrite the call of [47mfoo[0m to [47mt[0m using [47mlemma-2[0m. The example above explains how the rewriter treats calls of [47mdouble-rewrite[0m, but it may leave the unfortunate impression that the user needs to consider each [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m rule carefully, just in case a call of [47mdouble-rewrite[0m may be appropriate. Fortunately, ACL2 provides a ``[Double-rewrite]'' warning to inform the user of just this sort of situation. If you don't see this warning when you submit a ([47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m) rule, then the issue described here shouldn't come up for that rule. Such warnings may appear for hypotheses or right-hand side of a [47m:[0m[47m[rewrite][0m rule, and for hypotheses or full conclusion (as opposed to just the trigger term) of a [47m:[0m[47m[linear][0m rule. If you do see a ``[Double-rewrite]'' warning, then should you add the indicated call(s) of [47mdouble-rewrite[0m? At the time of writing this [documentation], the answer is not clear. Early experiments with double rewriting suggested that it may be too expensive to call [47mdouble-rewrite[0m in every instance where a warning indicates that there could be an advantage to doing so. And at the time of this writing, the ACL2 regression suite has about 1900 such warnings (but note that books were developed before [47mdouble-rewrite[0m or the ``[Double-rewrite]'' warning were implemented), which suggests that one can often do fine just ignoring such warnings. However, it seems advisable to go ahead and add the calls of [47mdouble-rewrite[0m indicated by the warnings unless you run across efficiency problems caused by doing so. Of course, if you decide to ignore all such warnings you can execute the event: [47m([0m[47m[set-inhibit-warnings][0m[47m "Double-rewrite")[0m. Finally, we note that it is generally not necessary to call [47mdouble-rewrite[0m in order to get its effect in the following case, where the discussion above might have led one to consider a call of [47mdouble-rewrite[0m: a hypothesis is a variable, or more generally, we are considering a variable occurrence that is a branch of the top-level [47mIF[0m structure of a hypothesis. The automatic handling of this case, by a form of double rewriting, was instituted in ACL2 Version_2.9 and remains in place with the introduction of [47mdouble-rewrite[0m. Here is a simple illustrative example. Notice that [47mfoo-holds[0m applies to prove the final [47m[thm][0m below, even without a call of [47mdouble-rewrite[0m in the hypothesis of [47mfoo-holds[0m, and that there is no ``[Double-rewrite]'' warning when submitting [47mfoo-holds[0m. (encapsulate (((foo *) => *) ((bar *) => *)) (local (defun foo (x) (declare (ignore x)) t)) (local (defun bar (x) (declare (ignore x)) t)) (defthm foo-holds (implies x (equal (foo x) t))) (defthm bar-holds-propositionally (iff (bar x) t))) (thm (foo (bar y)))") (doublet-listp (pointers) "See [system-utilities].") (dumb-negate-lit (pointers) "See [system-utilities].") (dumb-occur (pointers) "See [system-utilities].") (dumb-occur-var (pointers) "See [system-utilities].") (dynamically-monitor-rewrites (pointers) "See [dmr].") (e/d (theories theory-functions) "Enable/disable rules The macro [47me/d[0m creates theory expressions for use in [47m[in-theory][0m hints and events. It provides a convenient way to [47m[enable][0m and [47m[disable][0m simultaneously, without having to write arcane theory expressions. For related utilities, see [enable] and see [disable]. Examples: (e/d (lemma1 (:e fn))) ; equivalent to (enable lemma1 (:e fn)) (e/d () (lemma)) ; equivalent to (disable lemma) (e/d (lemma1) (lemma2 lemma3)) ; Enable lemma1 then disable lemma2, lemma3. (e/d () (lemma1) (lemma2)) ; Disable lemma1 then enable lemma2. General Form: (e/d enables-0 disables-0 ... enables-n disables-n) where each [47menables-i[0m and [47mdisables-i[0m is a list of runic designators; see [theories], see [enable], and see [disable]. Note that the concluding [47mdisables-n[0m may be omitted. The [47me/d[0m macro takes any number of lists suitable for the [47m[enable][0m and [47m[disable][0m macros. The event (in-theory (e/d (e00 e01 e02 ...) (d00 d01 d02 ...) ... (en0 en1 en2 ...) (dn0 dn1 dn2 ...) creates a theory that is equivalent to the following sequence of [47m[in-theory][0m events. (An analogous similar effect takes place for [47m:in-theory[0m [hints]. (in-theory (enable e00 e01 e02 ...)) (in-theory (disable d00 d01 d02 ...)) ... (in-theory (enable en0 en1 en2 ...)) (in-theory (disable dn0 dn1 dn2 ...))") (early-termination (parallel-programming) "Early termination for [47m[pand][0m and [47m[por][0m. This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. The evaluation of [47m(and expr1 expr2)[0m returns [47mnil[0m if [47mexpr1[0m evaluates to [47mnil[0m, avoiding the evaluation of [47mexpr2[0m. More generally, the evaluation of [47m(and expr1 expr2 ... exprk)[0m terminates with a return value of [47mnil[0m as soon as any [47mexpri[0m evaluates to [47mnil[0m --- no [47mexprj[0m is evaluated in this case for [47mj > i[0m. This so-called ``lazy evaluation'' of [47m[and][0m terms can thus save some computation; roughly speaking, the smaller the [47mi[0m, the more computation is saved. If the above call of [47m[and][0m is replaced by its parallel version, [47m[pand][0m, then there can be even more opportunity for skipping work. The arguments to [47m[pand][0m can be evaluated in parallel, in which case the first such evaluation that returns with a value of [47mnil[0m, if any, causes the remaining such evaluations to abort. Consider the following functions that compute whether a tree is valid (see [granularity] for a discussion of the granularity form). (defun valid-tip (x) (declare (xargs :guard t)) (or (eq x 'A) (eq x 'T) (eq x 'C) (eq x 'G))) (defun pvalid-tree (x depth) (declare (xargs :guard (natp depth))) (if (atom x) (valid-tip x) (pand (declare (granularity (< depth 10))) (pvalid-tree (car x) (1+ depth)) (pvalid-tree (cdr x) (1+ depth))))) We would like to stop execution as soon as any tip is found to be invalid. So, when computing the conjunction of terms by using [47m[pand][0m, once one of those terms evaluates to [47mnil[0m, the computations for the other terms are aborted and the [47m[pand][0m call returns [47mnil[0m. By using [47m[pand][0m, we can in principle attain a speedup factor greater than the number of available cores. The concept of early termination also applies to [47m[por][0m, except that early termination occurs when an argument evaluates to non-[47mnil[0m.") (ec-call (guard acl2-built-ins) "Execute a call in the ACL2 logic instead of raw Lisp The name ``[47mec-call[0m'' represents ``executable-counterpart call.'' This utility is intended for users who are familiar with guards. See [guard] for a general discussion of guards. Logically, [47mec-call[0m behaves like the identity macro; during proofs, [47m(ec-call TERM)[0m is typically replaced quickly by [47mTERM[0m during a proof attempt. However, [47mec-call[0m causes function calls to be evaluated in the ACL2 logic rather than raw Lisp, as explained below. General Forms: (ec-call (fn term1 ... termk)) (ec-call (fn term1 ... termk) :dfs-in 'dfs-in :dfs-out dfs-out) where [47mfn[0m is a known function symbol other than those in the list that is the value of the constant [47m*ec-call-bad-ops*[0m. (But see the Note on Inlining below for an exception pertaining to inlining.) In particular, [47mfn[0m is not a macro. The second form is only relevant for those who use [df]s and is discussed at the end of this topic. Semantically, [47m(ec-call (fn term1 ... termk))[0m equals [47m(fn term1 ... termk)[0m. However, this use of [47mec-call[0m has two effects. (1) [Guard] verification generates no proof obligations from the guard of [47mfn[0m for this call. Indeed, guards need not have been verified for [47mfn[0m. (2) During evaluation, after the arguments of [47mfn[0m are evaluated as usual, the executable-counterpart of [47mfn[0m is called, rather than its submitted version (see [evaluation]). That is, the call of [47mfn[0m is made on its evaluated arguments as though this call is being made in the ACL2 top-level loop, rather than in raw Lisp. In particular, the [guard] of [47mfn[0m is checked, at least by default (see [set-guard-checking]). The use of [47mec-call[0m does not turn off guard-checking, but that can be accomplished by using [47m[with-guard-checking][0m as well. Consider the following example. (defun f1 (x) (declare (xargs :guard t)) (ec-call (nth t x))) This definition is admitted, but evaluation of [47m(f1 '(a b c))[0m nevertheless causes a guard violation (at least, by default). However, if instead we submit the following definition, then there is no guard violation for that call of [47mf1[0m. (defun f1 (x) (declare (xargs :guard t)) (with-guard-checking nil (ec-call (nth t x)))) Note that in the term [47m(ec-call (fn term1 ... termk))[0m, only the indicated call of [47mfn[0m is made in the logic; each [47mtermi[0m is evaluated in the normal manner. If you want an entire term evaluated in the logic, wrap [47mec-call[0m around each function call in the term (other than calls of [47mif[0m and [47mec-call[0m). [31;1mTechnical Remark[0m (probably best ignored). During evaluation of a call of [47m[defconst][0m or [47m[defpkg][0m in raw Lisp, a form [47m(ec-call (fn term1 ... termk))[0m is treated as [47m(fn term1 ... termk)[0m, that is, without calling the executable-counterpart of [47mfn[0m. This situation occurs when loading a compiled file (or expansion file) on behalf of an [47m[include-book][0m event. The reason is technical: executable-counterparts are defined below a book's events in the book's compiled file. End of Technical Remark. Here is another small example. We define [47mfoo[0m recursively but with guard verification inhibited on the recursive call, which is to be evaluated in the ACL2 logic. ACL2 !>(defun foo (x y) (declare (xargs :guard (consp y))) (if (consp x) (cons (car x) (ec-call (foo (cdr x) (cdr y)))) (car y))) The admission of FOO is trivial, using the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). We could deduce no constraints on the type of FOO. Computing the guard conjecture for FOO.... The guard conjecture for FOO is trivial to prove. FOO is compliant with Common Lisp. Summary Form: ( DEFUN FOO ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !>(foo '(2 3 4 5) '(6 7)) ACL2 Error in TOP-LEVEL: The guard for the function call (FOO X Y), which is (CONSP Y), is violated by the arguments in the call (FOO '(4 5) NIL). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !> The error above arises because eventually, [47mfoo[0m recurs down to a value of parameter [47my[0m that violates the guard. This is clear from tracing (see [trace$] and see [trace]). Each call of the executable-counterpart of [47mfoo[0m checks the guard and then invokes the submitted version of [47mfoo[0m (see [evaluation]). The submitted version calls the executable-counterpart on the recursive call. When the guard check fails we get a violation. ACL2 !>(trace$ foo) ((FOO)) ACL2 !>(foo '(2 3 4 5) '(6 7)) 1> (ACL2_*1*_ACL2::FOO (2 3 4 5) (6 7)) 2> (FOO (2 3 4 5) (6 7)) 3> (ACL2_*1*_ACL2::FOO (3 4 5) (7)) 4> (FOO (3 4 5) (7)) 5> (ACL2_*1*_ACL2::FOO (4 5) NIL) ACL2 Error in TOP-LEVEL: The guard for the function call (FOO X Y), which is (CONSP Y), is violated by the arguments in the call (FOO '(4 5) NIL). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !> If we turn off guard errors then we can see the trace as above, but where we avoid calling the raw Lisp function when the guard fails to hold. ACL2 !>:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(foo '(2 3 4 5) '(6 7)) 1> (ACL2_*1*_ACL2::FOO (2 3 4 5) (6 7)) 2> (FOO (2 3 4 5) (6 7)) 3> (ACL2_*1*_ACL2::FOO (3 4 5) (7)) 4> (FOO (3 4 5) (7)) 5> (ACL2_*1*_ACL2::FOO (4 5) NIL) 6> (ACL2_*1*_ACL2::FOO (5) NIL) 7> (ACL2_*1*_ACL2::FOO NIL NIL) <7 (ACL2_*1*_ACL2::FOO NIL) <6 (ACL2_*1*_ACL2::FOO (5)) <5 (ACL2_*1*_ACL2::FOO (4 5)) <4 (FOO (3 4 5)) <3 (ACL2_*1*_ACL2::FOO (3 4 5)) <2 (FOO (2 3 4 5)) <1 (ACL2_*1*_ACL2::FOO (2 3 4 5)) (2 3 4 5) ACL2 > Note on Inlining. Although in general, the form [47m(ec-call (fn term1 ... termk))[0m is only legal if [47mfn[0m is a function symbol, such a form is also legal if [47mfn[0m is introduced with [47m[defun-inline][0m, or with [47m[define][0m using keyword argument [47m:inline t[0m. In those cases, [47mfn[0m is a macro whose calls expand to corresponding calls of [47mfn$INLINE[0m, the symbol in the same package as [47mfn[0m but with the string [47m"$INLINE"[0m added as a suffix to the [47m[symbol-name][0m of [47mfn[0m. We do not however extend this exception to macros in general, even when [47m[add-macro-fn][0m has been invoked. Consider the following example. (encapsulate () (defun foo () nil) (defun bar () t) (defmacro mac () nil) (add-macro-alias mac foo) (local (add-macro-alias mac bar)) (defun h () (ec-call (mac))) (defthm bad (h))) Consider what would happen if this were legal, where [47m(ec-call (mac))[0m used the macro-alias, [47mfoo[0m, for [47mmac[0m. Then in the first pass of the [47m[encapsulate][0m form above, the final [47m[defthm][0m event would prove, since (ec-call (mac)) is treated as (ec-call (bar)). But on the second pass, ACL2 would store [47mbad[0m as a theorem even though [47m(h)[0m would evaluate to [47mnil[0m, since the macro-alias of [47mmac[0m is [47mfoo[0m on the second pass. We conclude with a discussion of the second General Form: (ec-call (fn term1 ... termk) :dfs-in 'dfs-in :dfs-out 'dfs-out) Note that either or both keyword arguments may be omitted, and if both are included then they can be given in either order. See [df] for background on dfs. Here is an example. ACL2 !>(ec-call (binary-df+ (df1) (df1)) :dfs-in '(t t) :dfs-out '(t)) #d2.0 ACL2 !> The keyword arguments indicate, respectively, [47mbinary-df+[0m takes two df arguments and returns a single df value. Without those arguments ACL2 would report an error. The next example illustrates the use of [47m:dfs-out[0m for multiple value returns. First define [47mg[0m as follows. (defun g (x) (mv (df+ (df1) (to-df x)) (- x 1))) The use of [47m:dfs-out[0m below tells ACL2 that the given expression [47m(g 3)[0m returns two values: a df and an ordinary value. In the language of :DOC [df]: [47m(g 3)[0m is a df{0} expression and is not a df{1} expression. Note that the argument of [47mg[0m is an ordinary expression, not a df, so no [47m:dfs-in[0m argument is necessary. ACL2 !>(ec-call (g 3) :dfs-out '(t nil)) (#d4.0 2) ACL2 !> Returning to the second General Form, notice that [47mdfs-in[0m and [47mdfs-out[0m are lists of Booleans, which must be quoted, that indicate for [47mfn[0m which inputs or values (respectively) are dfs. For example, if [47mfn[0m returns a single value, then [47mdfs-out[0m is [47m(t)[0m if the call of [47mfn[0m is a df, else [47mdfs-out[0m is optional but may be supplied as [47m(nil)[0m. If [47mfn[0m returns n values where n is greater than 1, then [47mdfs-out[0m should be a list of length n where for each zero-based index i less than n, the ith element of [47mdfs[0m is [47mt[0m if the ith return value is a df (or more precisely, in the language of :DOC [df], calls of [47mfn[0m are df{i} expressions), else [47mnil[0m. The rules for the [47m:dfs-in[0m argument are analogous for inputs of the call of [47mfn[0m. When there are no df inputs (respectively, outputs) of the call, then [47m:dfs-in[0m (respectively, [47m:dfs-out[0m may be omitted or supplied as [47mnil[0m or [47m'nil[0m.") (efficiency (debugging proof-automation programming) "Efficiency considerations This topic is a grab-bag of ideas for the efficient use of ACL2, including proofs and programming. It is far from complete, and [tips] for using ACL2 effectively may be found throughout the [documentation]. The present topic will, ideally, improve over time, both in its content and in its organization. Please contribute! Here we discuss primarily time efficiency rather than space efficiency. You can time forms using [47m[time$][0m. That may show you that your tweaks to proof scripts or function definitions don't make a noticeable difference! We focus below on some techniques that have a reasonable chance of making a difference. Proof efficiency Perhaps the most basic idea for carrying out proofs efficiently is to use rewriting effectively; see [introduction-to-the-theorem-prover] and, in particular, the sections on rewriting. Here we mention just a few common ways to improve the efficiency of rewriting in ACL2. * Consider minimizing the number of hypotheses of a rule. See [remove-hyps] for a tool that can help with that. * Manage [theories] effectively. See [accumulated-persistence] for a way to identify rules that might best be [disable]d. In particular, it can be useful to disable functions whose expansions generate large case splits (see [splitter]); otherwise, sometimes it can be useful to limit case-splits with [47m[set-case-split-limitations][0m. * When many similar proofs are being performed (for example, for families of similar theorems generated by macros), the tool [removable-runes] may be helpful. Sometimes rewriting is slow for inherent algorithmic reasons. For example, if you have a binary function, [47mop[0m, and you prove the [rewrite] rules [47m(equal (op x y) (op y x)[0m) and [47m(equal (op x (op y z)) (op y (op x z)))[0m, then ACL2 will use an [47mn^2[0m algorithm to put arguments in order, essentially with bubblesort, in a sequence like this: (op d (op c (op b a))) (op d (op c (op a b))) (op d (op a (op c b))) (op d (op a (op b c))) (op a (op d (op b c))) (op a (op b (op d c))) (op a (op b (op c d))) In such a case, you may find it very helpful to create a suitable [meta] rule or a [clause-processor] rule, to implement an [47mn*log(n)[0m algorithm. You may consider creating calls of [47m[hide][0m to avoid exploring terms that are in the expected form. Calls of [47mhide[0m may be removed when ready either with a suitable [47m:expand[0m hint or by enabling a [rewrite] rule [47m(equal (hide x) x)[0m. We conclude this section with ways to tweak the ACL2 system to speed up slow proofs. These can be especially useful if very large terms are involved. One simple thing to try is to turn off the rewrite cache. (set-rw-cache-state nil) Some system behaviors can be modified using [47m[defattach-system][0m --- also see [system-attachments] --- typically by modifying heuristics. You can find all attachments by evaluating [47m(all-attachments (w state))[0m and all built-in such attachments by evaluating [47m(global-val 'attachments-at-ground-zero (w state))[0m, except for a few exceptions (see [defattach]). For most of these, however, you will need to consult the ACL2 source files for relevant information. Here are some key examples of how to modify system behavior. (defun constant-nil-function-arity-2 (x y) (declare (xargs :mode :logic :guard t) (ignore x y)) nil) (defattach-system too-many-ifs-post-rewrite constant-nil-function-arity-2) (defattach-system too-many-ifs-pre-rewrite constant-nil-function-arity-2) (defattach-system quick-and-dirty-srs constant-nil-function-arity-2) In some cases books may provide more sophisticated uses of [47m[defattach-system][0m (or [47m[defattach][0m). For a key example, see [47m[use-trivial-ancestors-check][0m. Another way to speed up system functions can be by using [memoization]. Here is an example from [47mbooks/projects/stateman/stateman22.lisp[0m. (memoize 'acl2::sublis-var1 :condition '(and (null acl2::alist) (consp acl2::form) (eq (car acl2::form) 'HIDE))) See [memoized-prover-fns] for a convenient way to do such memoization that automatically clears memoization tables after each event. (Also see [clear-memoize-table] and [clear-memoize-tables], and see [hons-wash] for another way to clean up after memoization.) Comments in the book [47mbooks/tools/memoize-prover-fns.lisp[0m note a reduction in proof time from 4200 seconds to 49 seconds for one example by memoizing some system functions. Those comments also have some discussion about which system functions to consider memoizing. Perhaps ACL2 users will contribute further documentation on which system functions to memoize for efficiency. The following may be helpful at the level of book certification, and are discussed in :doc certify-book-debug. (set-serialize-character-system nil) (set-bad-lisp-consp-memoize nil) (set-inhibit-output-lst '(proof-tree event)) Programming efficiency Ideas for efficient programming include the use of compilation for host Lisps (other than CCL and SBCL, which compile automatically); see [comp] and [set-compile-fns]. For [logic]-mode functions, verify [guard]s if feasible; otherwise consider using [program]-mode wrappers (see [program-wrapper]). Consider writing recursive definitions using tail recursion when possible. In some cases the use of hash cons, memoization, or fast alists may reduce computation time dramatically; see [hons-and-memoization]. Single-threaded objects (see [stobj]), [arrays], [multiple-value] return, and [47m[mbe][0m are helpful programming constructs provided by ACL2 for efficient execution. Some built-in functions are constructed for efficiency; see for example [47m[cons-with-hint][0m to reduce consing and [read-file-into-string] for obtaining the contents of a file quickly. You might find [47m[type][0m [declaration]s to be useful. In particular, if your host Lisp is GCL then the use of the declaration [47m(signed-byte 64)[0m, or any stronger declaration (e.g., [47m(unsigned-byte 63)[0m, [47m(signed-byte 12)[0m, or [47m(integer 0 100)[0m), can provide dramatic performance improvements in compiled code. You can peruse that code using [disassemble$]. Of course, if a programming technique or construct is useful for efficient execution in Common Lisp and it is supported by ACL2, then it is useful for efficient execution in ACL2. In particular, consider using [47m[type][0m [declaration]s for numbers in place of [47m[xargs][0m [47m:[0m[47m[guard][0m. Miscellaneous efficiency ideas The use of [47m[make-event][0m can sometimes reduce computation time; see for example [using-tables-efficiently] and [defconsts]. You can [profile] functions to see where time is being spent during proofs or when computing with user-defined functions. Sometimes it is even useful to profile virtually all ACL2 source functions, or even virtually all user-defined functions. That can be done as follows --- also see [profile-ACL2] and [profile-all] --- but note that when the problem is slow proofs, then since the results will display time spent in various ACL2 prover routines, those results might not be helpful to most users. (include-book "centaur/memoize/old/profile" :dir :system) (profile-acl2) ; or, (profile-all) to include user-defined functions [[Then run a slow form.]] (memsum) ; shows where time is spent For computations and proofs that may benefit from parallel computation, you could build the variant ACL2(p) of ACL2. See [parallelism].") (eighth (nth acl2-built-ins) "Eighth member of the list See any Common Lisp documentation for details.") (elim (rule-classes) "Make a destructor elimination rule See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. The following example of an [47m:elim[0m rule is an important one, and is built into ACL2. (defaxiom car-cdr-elim (implies (consp x) (equal (cons (car x) (cdr x)) x)) :rule-classes :elim) The class of [47m:elim[0m rules is fundamentally quite different from the more common class of [47m:[0m[47m[rewrite][0m rules. Briefly put, a [47m:rewrite[0m rule replaces instances of its left-hand side with corresponding instances of its right-hand side. But an [47m:elim[0m rule, on the other hand, has the effect of generalizing so-called ``destructor'' function applications to variables. In essence, applicability of a [47m:rewrite[0m rule is based on matching its left-hand side, while applicability of an [47m:elim[0m rule is based on the presence of at least one destructor term. For example, a conjecture about [47m(car x)[0m and [47m(cdr x)[0m can be replaced by a conjecture about new variables [47mx1[0m and [47mx2[0m, as shown in the following example. (Run the command [47m:mini-proveall[0m and search for [47mCAR-CDR-ELIM[0m to see the full proof containing this excerpt.) Subgoal *1/1' (IMPLIES (AND (CONSP X) (TRUE-LISTP (REV (CDR X)))) (TRUE-LISTP (APP (REV (CDR X)) (LIST (CAR X))))). The destructor terms (CAR X) and (CDR X) can be eliminated by using CAR-CDR-ELIM to replace X by (CONS X1 X2), (CAR X) by X1 and (CDR X) by X2. This produces the following goal. Subgoal *1/1'' (IMPLIES (AND (CONSP (CONS X1 X2)) (TRUE-LISTP (REV X2))) (TRUE-LISTP (APP (REV X2) (LIST X1)))). This simplifies, using primitive type reasoning, to Subgoal *1/1''' (IMPLIES (TRUE-LISTP (REV X2)) (TRUE-LISTP (APP (REV X2) (LIST X1)))). The resulting conjecture is often simpler and hence more amenable to proof. The application of an [47m:elim[0m rule thus replaces a variable by a term that contains applications of so-called ``destructor'' functions to that variable. The example above is typical: the variable [47mx[0m is replaced by the term [47m(cons (car x) (cdr x))[0m, which applies a so-called ``constructor'' function, [47m[cons][0m, to applications [47m(car x)[0m and [47m(cdr x)[0m of destructor functions [47m[car][0m and [47m[cdr][0m to that same variable, [47mx[0m. But that is only part of the story. ACL2 then generalizes the destructor applications [47m(car x)[0m and [47m(cdr x)[0m to new variables [47mx1[0m and [47mx2[0m, respectively, and ultimately the result is a simpler conjecture. More generally, the application of an [47m:elim[0m rule replaces a variable by a term containing applications of destructors; there need not be a clear-cut notion of ``constructor.'' But the situation described above is typical, and we will focus on it, giving full details when we introduce the ``General Form'' below. Notice that the situation can be complicated a bit by a rule's hypotheses. For example, the replacement specified by the rule [47mcar-cdr-elim[0m (shown near the beginning of this discussion) is only valid if the variable being replaced is a cons structure. Thus, when ACL2 applies [47mcar-cdr-elim[0m to replace a variable [47mv[0m, it will split into two cases: one case in which [47m(consp v)[0m is true, in which [47mv[0m is replaced by [47m(cons (car v) (cdr v))[0m and then [47m(car v)[0m and [47m(cdr v)[0m are generalized to new variables; and one case in which [47m(consp v)[0m is false. In practice, [47m(consp v)[0m is often provable, perhaps even literally present as a hypotheses; then of course there is no need to introduce the second case. That is why there is no such second case in the example above. You might find [47m:elim[0m rules to be useful whenever you have in mind a data type that can be built up from its fields with a ``constructor'' function and whose fields can be accessed by corresponding ``destructor'' functions. So for example, if you have a ``house'' data structure that represents a house in terms of its address, price, and color, you might have a rule like the following. Example: (implies (house-p x) (equal (make-house (address x) (price x) (color x)) x)) The application of such a rule is entirely analogous to the application of the rule [47mcar-cdr-elim[0m discussed above. We discuss such rules and their application more carefully below. General Form: (implies hyp (equiv lhs x)) where [47mequiv[0m is a known equivalence relation (see [defequiv]); [47mx[0m is a variable symbol; and [47mlhs[0m contains one or more terms (called ``destructor terms'') of the form [47m(fn v1 ... vn)[0m, where [47mfn[0m is a function symbol and the [47mvi[0m are distinct variable symbols, [47mv1[0m, ..., [47mvn[0m include all the variable symbols in the formula, no [47mfn[0m occurs in [47mlhs[0m in more than one destructor term, and all occurrences of [47mx[0m in [47mlhs[0m are inside destructor terms. An [47m:elim[0m rule is available for a given destructor function (in the manner described below) when it is the most recently added [enable]d [47m:elim[0m rule for that function. To use an [47m:elim[0m rule, the theorem prover waits until a conjecture has been maximally simplified. It then searches for an instance of some destructor term [47m(fn v1 ... vn)[0m in the conjecture, where the instance for [47mx[0m is some variable symbol, [47mvi[0m, and every occurrence of [47mvi[0m outside the destructor terms is in an [47mequiv[0m-hittable position. If such an instance is found, then the theorem prover instantiates the [47m:elim[0m formula as indicated by the destructor term matched; splits the conjecture into two goals, according to whether the instantiated hypothesis, [47mhyp[0m, holds; and in the case that it does hold, generalizes all the instantiated destructor terms in the conjecture to new variables and then replaces [47mvi[0m in the conjecture by the generalized instantiated [47mlhs[0m. An occurrence of [47mvi[0m is ``[47mequiv[0m-hittable'' if sufficient congruence rules (see [defcong]) have been proved to establish that the propositional value of the [clause] is not altered by replacing that occurrence of [47mvi[0m by some [47mequiv[0m-equivalent term. If an [47m:elim[0m rule is not applied when you think it should have been, and the rule uses an equivalence relation, [47mequiv[0m, other than [47mequal[0m, it is most likely that there is an occurrence of the variable that is not [47mequiv[0m-hittable. Easy occurrences to overlook are those in the governing hypotheses. If you see an unjustified occurrence of the variable, you must prove the appropriate congruence rule to allow the [47m:elim[0m to fire. Further examples of how ACL2 [47m:elim[0m rules are used may be found in the corresponding discussion of ``Elimination of Destructors'' for Nqthm, in Section 10.4 of A Computational Logic Handbook.") (emacs (acl2-tutorial) "Emacs support for ACL2 Many successful users of ACL2 take advantage of the Emacs editor, for example by running ACL2 in an Emacs shell buffer. If you do so, then you may wish to load the distributed file [47memacs-acl2.el[0m from one of two directories under the main ACL2 directory: [47mbooks/emacs/[0m if you use a recent version of Emacs, or [47memacs/[0m if you use Emacs 24. An easy way to arrange this is to put the load form into your [47m.emacs[0m file; here, [47mDIR[0m denotes your main ACL2 directory. (load "DIR/books/emacs/emacs-acl2.el") ; for recent Emacs versions [31;1m-OR-[0m (load "DIR/emacs/emacs-acl2.el") ; for Emacs 24 The file begins with considerable comments describing what it offers. In particular, the above file provides the ACL2-Doc browser, a convenient tool for viewing, in Emacs, documentation for both the ACL2 system and the documented community books, as well as custom manuals. See [ACL2-Doc]. If you are not comfortable with Emacs, you may prefer to use an Eclipse-based interface; see [ACL2-sedan].") (embedded-event-form (events) "Forms that may be embedded in other [events] Examples: (defun hd (x) (if (consp x) (car x) 0)) (local (defthm lemma23 ...)) (progn (defun fn1 ...) (local (defun fn2 ...)) ...) General Form: An embedded event form is a term, x, such that: * [47mx[0m is a call of an event function other than [47m[defpkg][0m (see [events] for a listing of the event functions); * [47mx[0m is a call of [47m[encapsulate][0m, [47m[progn][0m, [47m[progn!][0m, or [47m[include-book][0m; * [47mx[0m is of the form [47m(LOCAL x1)[0m where [47mx1[0m is an embedded event form; * [47mx[0m is of the form [47m(MAKE-EVENT &)[0m, where [47m&[0m is any term whose expansion is an embedded event (see [make-event]); * [47mx[0m is of the form [47m(SKIP-PROOFS x1)[0m where [47mx1[0m is an embedded event form; * [47mx[0m is of the form [47m(WITH-CBD str x1)[0m, where [47mstr[0m is a string and [47mx1[0m is an embedded event form; * [47mx[0m is of the form [47m(WITH-GUARD-CHECKING-EVENT c x1)[0m or [47m(WITH-GUARD-CHECKING-EVENT (QUOTE c) form)[0m, where [47mc[0m is a member of the list [47m(t nil :nowarn :all :none)[0m and [47mx1[0m is an embedded event form; * [47mx[0m is of the form [47m(WITH-OUTPUT ... x1)[0m, [47m(WITH-PROVER-STEP-LIMIT ... x1 ...)[0m, or [47m(WITH-PROVER-TIME-LIMIT ... x1)[0m, where [47mx1[0m is an embedded event form; * [47mx[0m macroexpands to one of the forms above; or * [intended only for the implementation] [47mx[0m is [47m(RECORD-EXPANSION x1 x2)[0m, where [47mx1[0m and [47mx2[0m are embedded event forms. However, we add the following restrictions for [47m[local][0m contexts. * An embedded event form may not set the [47m[ACL2-defaults-table][0m when in the context of [47m[local][0m. Thus for example, the form (local (table acl2-defaults-table :defun-mode :program)) is not an embedded event form, nor is the form [47m(local (program))[0m, since the latter sets the [47m[ACL2-defaults-table][0m implicitly. An example at the end of the discussion below illustrates why there is this restriction. * A call of [47m[defaxiom][0m is illegal in the context of [47m[local][0m. Without this restriction, one could locally assert a strong axiom like [47m(equal t nil)[0m and then non-locally prove that formula, leaving you in an ACL2 logical [world] in which it appears that the formula is actually provable without such an axiom. * A call of [47m[add-include-book-dir!][0m or [47m[delete-include-book-dir!][0m is illegal in the context of [47m[local][0m. For an explanation, see [add-include-book-dir!]. Only embedded event forms are allowed in a book after its initial [47m[in-package][0m form. See [books]. However, you may find that [47m[make-event][0m allows you to get the effect you want for a form that is not an embedded event form. For example, you can put the following into a book, which assigns the value 17 to [47m[state][0m global variable [47mx[0m: (make-event (er-progn (assign x 17) (value '(value-triple nil))) :check-expansion t) For another use of [47mmake-event[0m to create embedded event forms, see [make-event-example-3]. When an embedded event is executed while [47m[ld-skip-proofsp][0m is [47m'[0m[47m[include-book][0m, those parts of it inside [47m[local][0m forms are ignored. Thus, (progn (defun f1 () 1) (local (defun f2 () 2)) (defun f3 () 3)) will define [47mf1[0m, [47mf2[0m, and [47mf3[0m when [47m[ld-skip-proofsp][0m is [47mnil[0m or [47mt[0m, but will define only [47mf1[0m and [47mf3[0m when [47m[ld-skip-proofsp][0m is [47m'[0m[47m[include-book][0m. [3mDiscussion:[0m [47m[Encapsulate][0m, [47m[progn][0m, and [47m[include-book][0m place restrictions on the kinds of forms that may be processed. These restrictions ensure that the non-local [events] are indeed admissible provided that the sequence of [47m[local][0m and non-local [events] is admissible when proofs are done, i.e., when [47mld-skip-proofs[0m is [47mnil[0m. But [47m[progn!][0m places no such restrictions, hence is potentially dangerous and should be avoided unless you understand the ramifications; so it is illegal unless there is an active trust tag (see [defttag]). [47m[Local][0m permits the hiding of an event or group of [events] in the sense that [47m[local][0m [events] are processed when we are trying to establish the admissibility of a sequence of [events] embedded in [47m[encapsulate][0m forms or in [books], but are ignored when we are constructing the [world] produced by assuming that sequence. Thus, for example, a particularly ugly and inefficient [47m:[0m[47m[rewrite][0m rule might be made [47m[local][0m to an [encapsulate] that ``exports'' a desirable theorem whose proof requires the ugly lemma. To see why we can't allow just anything as an embedded event, consider allowing the form (if (ld-skip-proofsp state) (defun foo () 2) (defun foo () 1)) followed by (defthm foo-is-1 (equal (foo) 1)). When we process the [events] with [47m[ld-skip-proofsp][0m is [47mnil[0m, the second [47m[defun][0m is executed and the [47m[defthm][0m succeeds. But when we process the [events] with [47m[ld-skip-proofsp][0m [47m'[0m[47m[include-book][0m, the second [47m[defun][0m is executed, so that [47mfoo[0m no longer has the same definition it did when we proved [47mfoo-is-1[0m. Thus, an invalid formula is assumed when we process the [47m[defthm][0m while skipping proofs. Thus, the first form above is not a legal embedded event form. If you encounter a situation where these restrictions seem to prevent you from doing what you want to do, then you may find [47mmake-event[0m to be helpful. See [make-event]. [47m[Defpkg][0m is not allowed because it affects how things are read after it is executed. But all the forms embedded in an event are read before any are executed. That is, (encapsulate nil (defpkg "MY-PKG" nil) (defun foo () 'my-pkg::bar)) makes no sense since [47mmy-pkg::bar[0m must have been read before the [47m[defpkg][0m for [47m"MY-PKG"[0m was executed. Finally, let us elaborate on the restriction mentioned earlier related to the [47m[ACL2-defaults-table][0m. Consider the following form. (encapsulate () (local (program)) (defun foo (x) (if (equal 0 x) 0 (1+ (foo (- x)))))) See [local-incompatibility] for a discussion of how [47m[encapsulate][0m processes event forms. Briefly, on the first pass through the [events] the definition of [47mfoo[0m will be accepted in [47m[defun][0m mode [47m:[0m[47m[program][0m, and hence accepted. But on the second pass the form [47m(local (program))[0m is skipped because it is marked as [47m[local][0m, and hence [47mfoo[0m is accepted in [47m[defun][0m mode [47m:[0m[47m[logic][0m. Yet, no proof has been performed in order to admit [47mfoo[0m, and in fact, it is not hard to prove a contradiction from this definition!") (enable (theories theory-functions) "Adds names to current theory Example: (enable fact (:e fact) associativity-of-app) General Form: (enable name1 name2 ... namek) where each [47mnamei[0m is a runic designator; see [theories]. The result is the theory that contains all the names in the current theory plus those listed. Note that this is merely a function that returns a theory. The result is generally a very long list of [rune]s and you will probably regret printing it. For related utilities, see [disable] and see [e/d]. The standard way to ``enable'' a fixed set of names, is as follows; see [hints] and see [in-theory]. :in-theory (enable name1 name2 ... namek) ; in a hint (in-theory (enable name1 name2 ... namek)) ; as an event (local ; often desirable, to avoid exporting from the current context (in-theory (enable name1 name2 ... namek))) Note that all the names are implicitly quoted. If you wish to enable a computed list of names, [47mlst[0m, use the theory expression [47m(union-theories (current-theory :here) lst)[0m. To see the runes currently disabled that are among those created when a function symbol [47mFN[0m is introduced, evaluate [47m(disabledp 'FN)[0m.") (enable-forcing (force) "To allow forced case splits General Form: ACL2 !>:enable-forcing ; allowed forced case splits See [force] and see [case-split] for a discussion of forced case splits, which are turned back on by this command. See [disable-forcing] for an example showing how to turn off forced case splits. [47mEnable-forcing[0m is actually a macro that [enable]s the [executable-counterpart] of the function symbol [47mforce[0m; see [force]. When you want to use [hints] to turn on forced case splits, use a form such as one of the following (these are equivalent). :in-theory (enable (:executable-counterpart force)) :in-theory (enable (force))") (enable-immediate-force-modep (force) "[force]d hypotheses are attacked immediately General Form: ACL2 !>:enable-immediate-force-modep This event causes ACL2 to attack [force]d hypotheses immediately instead of delaying them to the next forcing round. See [immediate-force-modep]. Or for more basic information, first see [force] for a discussion of [force]d case splits. Enable-immediate-force-modep is a macro that [enable]s the [executable-counterpart] of the function symbol [47m[immediate-force-modep][0m. When you want to [enable] this mode in [hints], use a form such as one of the following (these are equivalent). :in-theory (enable (:executable-counterpart immediate-force-modep)) :in-theory (enable (immediate-force-modep))") (enabled-numep (pointers) "See [system-utilities].") (enabled-runep (pointers) "See [system-utilities].") (encapsulate (events) "Hide some [events] and/or constrain some functions [47mEncapsulate[0m provides a way to execute a sequence of [events] and then hide some of the resulting effects. There are two kinds of encapsulations: ``trivial'' and ``non-trivial''. We discuss these briefly before providing detailed [documentation]. A trivial encapsulation is an event of the following form. (encapsulate () ; nil here indicates "trivial" <event-1> ... <event-k>) We use the term ``sub-events'' to refer to [47m<event-1>[0m through [47m<event-k>[0m. Each sub-event [47m<event-i>[0m may be ``[local]'', that is, of the form [47m(local <event-i'>)[0m; the other sub-events are called ``non-local''. When this [47mencapsulate[0m form is submitted to ACL2, it is processed in two passes. On the first pass, each sub-event is printed (by default) and processed in sequence; admission of the [47mencapsulate[0m fails if any [47m<event-i>[0m fails to be admitted. Then a second pass is made after rolling back the logical [world] to what it was just before executing the [47mencapsulate[0m form. In the second pass, only the non-[local] forms [47m<event-i>[0m are evaluated, again in order, and proofs are skipped. For example, the following trivial encapsulation exports a single event, [47mmember-equal-reverse[0m. The lemma [47mmember-revappend[0m is used (as a [rewrite] rule) to prove [47mmember-equal-reverse[0m on the first pass, but since [47mmember-revappend[0m is [local], it is ignored on the second (final) pass. (encapsulate () (local (defthm member-revappend (iff (member-equal a (revappend x y)) (or (member-equal a x) (member-equal a y))) :hints (("Goal" :induct (revappend x y))))) (defthm member-equal-reverse (iff (member-equal a (reverse x)) (member-equal a x)))) Of course, one might prefer to prove these [events] at the top level, rather than within an encapsulation; but the point here is to illustrate that you can have [local] [events] that do not become part of the logical [world]. (Such a capability is also provided at the level of [books]; in particular, see [include-book].) Note that trivial encapsulates must introduce at least one sub-event, or else they are treated as no-ops, with no effect on the logical [world]. Consider the following example. ACL2 !>(encapsulate nil (local (defun f (x) x))) To verify that the encapsulated event correctly extends the current theory we will evaluate it. The theory thus constructed is only ephemeral. Encapsulated Event: ACL2 !>>(LOCAL (DEFUN F (X) X)) Since F is non-recursive, its admission is trivial. We observe that the type of F is described by the theorem (EQUAL (F X) X). Summary Form: ( DEFUN F ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) F End of Encapsulated Event. ACL2 Observation in ( ENCAPSULATE NIL (LOCAL ...) ...): The submitted encapsulate event has created no new ACL2 events, and thus is leaving the ACL2 logical world unchanged. See :DOC encapsulate. Summary Form: ( ENCAPSULATE NIL (LOCAL ...) ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) :EMPTY-ENCAPSULATE ACL2 !> After the above evaluation, we are left in the [world] with which we began. For example, if you evaluate the above form in the initial ACL2 world, you can see the following both before and after that evaluation. ACL2 !>:pbt 0 0:x(EXIT-BOOT-STRAP-MODE) ACL2 !> On the other hand, non-trivial encapsulations provide a way to introduce axioms about new function symbols, without introducing inconsistency and without introducing complete definitions. The following example illustrates how that works. (encapsulate ; The following list has a single signature, introducing a function foo of ; one argument that returns one value. (The list is non-empty, so we call ; this a "non-trivial" encapsulation.) ( ((foo *) => *) ) ; Introduce a ``witness'' (example) for foo, marked as local so that ; it is not exported: (local (defun foo (x) x)) ; Introduce a non-local property to be exported: (defthm foo-preserves-consp (implies (consp x) (consp (foo x)))) ) The form above introduces a new function symbol, [47mfoo[0m, with the indicated property and no definition. In fact, the output from ACL2 concludes as follows. The following constraint is associated with the function FOO: (IMPLIES (CONSP X) (CONSP (FOO X))) To understand this example, we consider how non-trivial encapsulations are processed. The same two passes are made as for trivial encapsulations, and the ([local]) definition of [47mfoo[0m is ignored on the second pass, and hence does not appear in the resulting ACL2 logical [world]. But before the second pass, each [signature] is stored in the [world]. Thus, when the theorem [47mfoo-preserves-consp[0m is encountered in the second pass, [47mfoo[0m is a known function symbol with the indicated signature. If any event fails while evaluating a call of [47mencapsulate[0m, the entire [47mencapsulate[0m call is deemed to have failed, and the logical [world] is rolled back to what it was immediately before the [47mencapsulate[0m call. We now provide detailed documentation. But discussion of redundancy for [47mencapsulate[0m events may be found elsewhere; see [redundant-encapsulate]. Other Examples: (encapsulate (((an-element *) => *)) ; The list of signatures above could also be written ; ((an-element (lst) t)) (local (defun an-element (lst) (if (consp lst) (car lst) nil))) (local (defthm member-equal-car (implies (and lst (true-listp lst)) (member-equal (car lst) lst)))) (defthm thm1 (implies (null lst) (null (an-element lst)))) (defthm thm2 (implies (and (true-listp lst) (not (null lst))) (member-equal (an-element lst) lst)))) (encapsulate () ; empty signature: no constrained functions indicated (local (defthm hack (implies (and (syntaxp (quotep x)) (syntaxp (quotep y))) (equal (+ x y z) (+ (+ x y) z))))) (defthm nthcdr-add1-conditional (implies (not (zp (1+ n))) (equal (nthcdr (1+ n) x) (nthcdr n (cdr x)))))) General Form: (encapsulate (signature ... signature) ev1 ... evn) where each [47m[signature][0m is a well-formed signature, each [47msignature[0m describes a different function symbol, and each [47mevi[0m is an embedded event form (see [embedded-event-form]). Also see [signature], in particular for a discussion of how a signature can assign a [guard] to a function symbol. There must be at least one [47mevi[0m. The [47mevi[0m inside [47m[local][0m special forms are called ``local'' [events] below. [Events] that are not [47m[local][0m are sometimes said to be ``exported'' by the encapsulation. We make the further restriction that no [47m[defaxiom][0m event may be introduced in the scope of an [47mencapsulate[0m (not even by [47mencapsulate[0m or [47m[include-book][0m events that are among the [47mevi[0m). Furthermore, no non-[47m[local][0m [47m[include-book][0m event is permitted in the scope of any [47mencapsulate[0m with a non-empty list of signatures. To be well-formed, an [47mencapsulate[0m event must have the properties that each event in the body (including the [47m[local][0m ones) can be successfully executed in sequence and that in the resulting theory, each function mentioned among the [signature]s was introduced via a [47m[local][0m event and has the [signature] listed. (A utility is provided to assist in debugging failures of such execution; see [redo-flat].) In addition, the body may contain no ``local incompatibilities'' which, roughly stated, means that the [events] that are not [47m[local][0m must not syntactically require symbols defined by [47m[local][0m [47m[events][0m, except for the functions listed in the [signature]s. See [local-incompatibility]. Finally, no non-[47m[local][0m recursive definition in the body may involve in its suggested induction scheme any function symbol listed among the [signature]s. See [subversive-recursions]. Observe that if the [signature]s list is empty, the resulting ``trivial'' [47mencapsulate[0m may still be useful for deriving theorems to be exported whose proofs require lemmas you prefer to hide (i.e., made [47m[local][0m). Whether trivial or not (i.e., whether the signature is empty or not), [47mencapsulate[0m exports the results of evaluating its non-[47m[local][0m [events], but its [47m[local][0m [events] are ignored for the resulting logical [world]. The result of a non-trivial [47mencapsulate[0m event is an extension of the logic in which, roughly speaking, the functions listed in the [signature]s are constrained to have the [signature]s listed and to satisfy the non-[47m[local][0m theorems proved about them. In fact, other functions introduced in the [47mencapsulate[0m event may be considered to have ``[constraint]s'' as well. (See [constraint] for details, which are only relevant to functional instantiation.) Since the [constraint]s were all theorems in the ``ephemeral'' or ``local'' theory, we are assured that the extension produced by [47mencapsulate[0m is sound. In essence, the [47m[local][0m definitions of the constrained functions are just ``witness functions'' that establish the consistency of the [constraint]s. Because those definitions are [47m[local][0m, they are not present in the theory produced by encapsulation. After a non-trivial [47mencapsulate[0m event is admitted, theorems about the constrained function symbols may then be proved --- theorems whose proofs necessarily employ only the [constraint]s. Thus, those theorems may be later functionally instantiated, as with the [47m:functional-instance[0m lemma instance (see [lemma-instance]), to derive analogous theorems about different functions, provided the constraints (see [constraint]) can be proved about the new functions. The [default-defun-mode] for the first event in an encapsulation is the default [defun-mode] ``outside'' the encapsulation. But since [events] changing the [defun-mode] are permitted within the body of an [47mencapsulate[0m, the default [defun-mode] may be changed. However, [defun-mode] changes occurring within the body of the [47mencapsulate[0m are not exported. In particular, the [47m[ACL2-defaults-table][0m after an [47mencapsulate[0m is always the same as it was before the [47mencapsulate[0m, even though the [47mencapsulate[0m body might contain [defun-mode] changing [events], [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m. See [defun-mode]. More generally, after execution of an [47mencapsulate[0m event, the value of [47m[ACL2-defaults-table][0m is restored to what it was immediately before that event was executed. See [ACL2-defaults-table]. We make some remarks on [guard]s and evaluation. Calls of functions introduced in the [signature]s list cannot be evaluated in the ACL2 read-eval-print loop. See [defattach] for a way to overcome this limitation. Moreover, any [47m:[0m[47m[guard][0m supplied in the signature is automatically associated in the [world] with its corresponding function symbol, with no requirement beyond what is required for a legal [signature] other than that all of the guard's function symbols are in [47m:[0m[47m[logic][0m mode with their [guard]s verified. In particular, there need not be any relationship between a guard in a signature and the guard in a [47mlocal[0m witness function. Finally, note that for functions introduced non-[local]ly inside a non-trivial [47mencapsulate[0m event, [guard] verification is illegal unless ACL2 determines that the proof obligations hold outside the [47m[encapsulate][0m event as well. (encapsulate ((f (x) t)) (local (defun f (x) (declare (xargs :guard t)) (consp x))) ;; ERROR! (defun g (x) (declare (xargs :guard (f x))) (car x))) The order of the [events] in the vicinity of an [47mencapsulate[0m is confusing. We discuss it in some detail here because when logical names are being used with theory functions to compute sets of rules, it is sometimes important to know the order in which [events] were executed. (See [logical-name] and see [theory-functions].) What, for example, is the set of function names extant in the middle of an encapsulation? If the most recent event is [47mprevious[0m and then you execute an [47mencapsulate[0m constraining [47man-element[0m with two non-[47m[local][0m [events] in its body, [47mthm1[0m and [47mthm2[0m, then the order of the [events] after the encapsulation is (reading chronologically forward): [47mprevious[0m, [47mthm1[0m, [47mthm2[0m, [47man-element[0m (the [47mencapsulate[0m itself). Actually, between [47mprevious[0m and [47mthm1[0m certain extensions were made to the [world] by the superior [47mencapsulate[0m, to permit [47man-element[0m to be used as a function symbol in [47mthm1[0m. Remark on return value. As with all [events], a call of [47mencapsulate[0m returns an [error-triple], [47m(mv erp val state)[0m, where [47merp[0m is [47mnil[0m when the event is redundant or is successfully admitted. When [47merp[0m is [47mnil[0m, the value [47mval[0m, which is typically printed after a space, is determined as follows. * If the [47mencapsulate[0m event is [redundant], then [47mval[0m is [47m:redundant[0m. * Otherwise, if no new events are introduced, then [47mval[0m is [47m:empty-encapsulate[0m. * Otherwise, if the last sub-event in the final pass of the [47mencapsulate[0m form evaluates to [47m(mv nil '(:return-value x)[0m) for some [47mx[0m, [47mval[0m is [47mx[0m. Note that this can be accomplished by placing the form [47m(value-triple '(:return-value x) :on-skip-proofs t)[0m as the final form in the [47mencapsulate[0m, but since proofs are skipped during that pass, the argument [47m:on-skip-proofs t[0m is necessary for [47mval[0m to be [47mx[0m. * Otherwise, if the list of [signature]s is [47mnil[0m then [47mval[0m is [47mt[0m. * Otherwise, if there is a single signature introducing the function symbol, [47mfn[0m, then [47mval[0m is [47mfn[0m. * Otherwise, [47mval[0m is the list of function symbols introduced in the list of signatures. Remark on implicit [constraint]s (unknown-constraints). See [partial-encapsulate] for a related utility that allows some of the constraints to be unspecified. This is an advanced capability that is useful when one installs special-purpose code, possibly in raw Lisp, using a trust tag (see [defttag]). Remark for ACL2(r) (see [real]). For ACL2(r), [47m[encapsulate][0m can be used to introduce classical and non-classical functions, as determined by the signatures; see [signature]. Those marked as classical (respectively non-classical) must have classical (respectively, non-classical) [47m[local][0m witness functions. A related requirement applies to functional instantiation; see [lemma-instance]. Subtopics [Constraint] Restrictions on certain functions introduced in [47m[encapsulate][0m [events] [Constraint-tracking] Generate markers to indicate origins of constraints [Functional-instantiation] An analogue in ACL2 of higher-order logical reasoning. Functional instantiation allows you to prove theorems ``by analogy'' with previous theorems. See [hints] and see [lemma-instance]. [Infected-constraints] [47m[Events][0m affecting [constraint]s of [47m[encapsulate][0ms [Partial-encapsulate] Introduce functions with some constraints unspecified [Redundant-encapsulate] Redundancy of [47m[encapsulate][0m [events] [Set-constraint-tracking] Generate markers to indicate origins of constraints [Signature] How to specify the arity of a constrained function") (endp (lists acl2-built-ins) "Recognizer for empty lists In the ACL2 logic, [47m(endp x)[0m is the same as [47m(atom x)[0m. See [atom]. Unlike [47m[atom][0m, the [guard] for [47mendp[0m requires that [47mx[0m is a [47m[cons][0m pair or is [47mnil[0m. Thus, [47mendp[0m is typically used as a termination test for functions that recur on a [47m[true-listp][0m argument. See [guard] for general information about [guard]s. [47mEndp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<endp> (defun endp (x) (declare (xargs :guard (or (consp x) (eq x nil)))) (atom x))") (enter-boot-strap-mode (history) "The first millisecond of the Big Bang ACL2 functions, e.g., [47m[if][0m, that show [47menter-boot-strap-mode[0m as their defining [command] are in fact [primitive]s. It is impossible for the system to display defining axioms about these symbols. [47mEnter-boot-strap-mode[0m is a Common Lisp function but not an ACL2 function. It magically creates from [47mnil[0m an ACL2 property list [world] that lets us start the boot-strapping process. That is, once [47menter-boot-strap-mode[0m has created its [world], it is possible to process the [47m[defconst][0ms, [47m[defun][0ms, and [47m[defaxiom][0ms, necessary to bring up the rest of the system. Before that [world] is created, the attempt by ACL2 even to translate a [47m[defun][0m form, say, would produce an error because [47m[defun][0m is undefined. Several ACL2 functions show [47menter-boot-strap-mode[0m as their defining [command]. Among them are [47m[if][0m, [47m[cons][0m, [47m[car][0m, and [47m[cdr][0m. These functions are characterized by axioms rather than definitional equations --- axioms that in most cases are built into our code and hence do not have any explicit representation among the rules and formulas in the system.") (ephemeral-whs (pointers) "See [wormhole-status].") (eq (equal equality-variants acl2-built-ins) "Equality of symbols [47mEq[0m is the function for determining whether two objects are identical (i.e., have the exact same store address in the current von Neumann implementation of Common Lisp). It is the same as [47m[equal][0m in the ACL2 logic. [47mEq[0m is a Common Lisp function. In order to ensure conformance with Common Lisp, the ACL2 [guard] on [47meq[0m requires at least one of the arguments to [47meq[0m to be a symbol. Common Lisp guarantees that if [47mx[0m is a symbol, then [47mx[0m is [47meq[0m to [47my[0m if and only if [47mx[0m is [47m[equal][0m to [47my[0m. Thus, the ACL2 user should think of [47meq[0m as nothing besides a fast means for checking [47m[equal][0m when one argument is known to be a symbol. In particular, it is possible that an [47meq[0m test will not even require the cost of a function call but will be as fast as a single machine instruction. [31;1mFunction: [0m<eq> (defun eq (x y) (declare (xargs :guard (if (symbolp x) t (symbolp y)))) (equal x y))") (eql (equal equality-variants acl2-built-ins) "Test equality (of two numbers, symbols, or [characters]) [47m(eql x y)[0m is logically equivalent to [47m(equal x y)[0m. Unlike [47m[equal][0m, [47meql[0m has a [guard] requiring at least one of its arguments to be a number, a symbol, or a character. Generally, [47meql[0m is executed more efficiently than [47m[equal][0m. For a discussion of the various ways to test against 0, See [zero-test-idioms]. [47mEql[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<eql> (defun eql (x y) (declare (xargs :guard (or (eqlablep x) (eqlablep y)))) (equal x y))") (eqlable-alistp (alists acl2-built-ins) "Recognizer for a true list of pairs whose [47m[car][0ms are suitable for [47m[eql][0m The predicate [47meqlable-alistp[0m tests whether its argument is a [47m[true-listp][0m of [47m[consp][0m objects whose [47m[car][0ms all satisfy [47m[eqlablep][0m. [31;1mFunction: [0m<eqlable-alistp> (defun eqlable-alistp (x) (declare (xargs :guard t)) (cond ((atom x) (equal x nil)) (t (and (consp (car x)) (eqlablep (car (car x))) (eqlable-alistp (cdr x))))))") (eqlable-listp (eqlablep equal lists acl2-built-ins) "Recognizer for a true list of objects each suitable for [47m[eql][0m The predicate [47meqlable-listp[0m tests whether its argument is a [47m[true-listp][0m of objects satisfying [47m[eqlablep][0m. [31;1mFunction: [0m<eqlable-listp> (defun eqlable-listp (l) (declare (xargs :guard t)) (if (consp l) (and (eqlablep (car l)) (eqlable-listp (cdr l))) (equal l nil)))") (eqlablep (equal acl2-built-ins) "The [guard] for the function [47m[eql][0m The predicate [47meqlablep[0m tests whether its argument is suitable for [47m[eql][0m, at least one of whose arguments must satisfy this predicate in Common Lisp. [47m(Eqlablep x)[0m is true if and only if its argument is a number, a symbol, or a character. [31;1mFunction: [0m<eqlablep> (defun eqlablep (x) (declare (xargs :guard t)) (or (acl2-numberp x) (symbolp x) (characterp x))) Subtopics [Eqlable-listp] Recognizer for a true list of objects each suitable for [47m[eql][0m") (equal (basics acl2-built-ins) "True equality [47m(equal x y)[0m is equal to [47mt[0m or [47mnil[0m, according to whether or not [47mx[0m and [47my[0m are the same value. For a discussion of the various idioms for testing against 0, See [zero-test-idioms]. Subtopics [=] Test equality of two numbers [Eq] Equality of symbols [Eql] Test equality (of two numbers, symbols, or [characters]) [Eqlable-listp] Recognizer for a true list of objects each suitable for [47m[eql][0m [Eqlablep] The [guard] for the function [47m[eql][0m [Hons-equal] [47m(hons-equal x y)[0m is a recursive equality check that optimizes when parts of its arguments are [normed].") (equality-variants (programming) "Versions of a function using different equality tests The ACL2 environment includes not only a logic but also a programming language, which is based on Common Lisp. Execution efficiency may be increased by using fast equality tests: [47m[eq][0m for symbols and [47m[eql][0m for numbers, symbols, and characters (see [eqlablep]). Several list-processing functions built into ACL2 thus have three variants, depending on whether the equality function used is [47m[eq][0m, [47m[eql][0m, or [47m[equal][0m; a list is provided below. ACL2 has taken measures to ensure that one can reason about a single logical function even when one uses these different variants. Consider for example the case of list membership. Common Lisp provides a utility for this purposes, [47m[member][0m, which can take a [47m:TEST[0m keyword argument, default [47m[eql][0m. So for example, one might write (member a x :TEST 'eq) if either [47ma[0m is a symbol or [47mx[0m is a list of symbols, so that the fastest equality test ([47m[eq][0m) may be used when comparing [47ma[0m to successive elements of the list, [47mx[0m. One might elsewhere write [47m(member b (foo y))[0m, which is equivalent to [47m(member b (foo y) :TEST 'eql)[0m, for example if [47mb[0m is a number. If one wants to reason about both [47m(member a x :TEST 'eq)[0m and [47m(member b y)[0m, it might be helpful for both calls of [47mmember[0m to be the same logically, even though Common Lisp will execute them differently (using [47m[eq][0m or [47m[eql][0m, respectively). ACL2 arranges that in fact, both references to [47m[member][0m generate calls of [47m[member-equal][0m in the theorem prover. In fact, since [47m[member][0m can take the optional [47m:TEST[0m keyword argument, then in ACL2 it must be defined as a macro, not a function (see [defun]). ACL2 arranges that a call of [47mmember[0m generates a corresponding call of the function [47m[member-equal][0m, regardless of the value of [47mTEST[0m, in a manner that produces [47m[member-equal][0m in prover output. More generally, you can expect ACL2 to treat your use of [47m[member][0m as though you had written [47m[member-equal][0m, for example in the way it stores [47m[rewrite][0m rules and other kinds of rules as well (see [rule-classes]). We say little here about how this is all arranged by ACL2, other than to mention that [47m[mbe][0m is utilized (so, you might see mention in proof logs) of the function [47m[return-last][0m that implements [47m[mbe][0m. Such details, which involve a notion of ``macro alias'' and probably can be ignored by most users, may be found elsewhere; see [equality-variants-details]. As a convenience to the user, the macro [47mmember-eq[0m is provided that expands to a corresponding call of [47mmember[0m with [47m:TEST 'eq[0m, as follows. ACL2 !>:trans1 (member-eq (foo x) (bar y)) (MEMBER (FOO X) (BAR Y) :TEST 'EQ) ACL2 !> For efficiency we recommend using the [47m-equal[0m equality variant, for example [47m[member-equal][0m or [47m([0m[47m[member][0m[47m ... :TEST 'equal)[0m, in certain contexts: [47m[defmacro][0m, [47m[defpkg][0m, [47m[defconst][0m, and [47m[value-triple][0m forms. However, the implementation of equality variants has been designed so that when defining a function, one may choose freely in a definition an equality variant of primitive [47mF[0m, to get efficient execution but where subsequent reasoning is about [47mF-equal[0m. For details about the above recommendation and for a discussion of the implementation, see [equality-variants-details]. The following alphabetical list includes all primitives that have equality variants. Each macro [47mF[0m listed below takes an optional [47m:TEST[0m keyword argument of [47m'eq[0m, [47m'eql[0m, or [47m'equal[0m, where [47m'eql[0m is the default. For each such [47mF[0m, a function [47mF-equal[0m is defined such that for logical purposes (in particular theorem proving), each call of [47mF[0m expands to a corresponding call of [47mF-equal[0m. For convenience, a macro [47mF-eq[0m is also defined, so that a call of [47mF-eq[0m expands to a corresponding call of [47mF[0m with [47m:TEST 'eq[0m. [47m[add-to-set][0m [47m[assoc][0m [47m[intersection$][0m ; (see Note below) [47m[intersectp][0m [47m[member][0m [47m[no-duplicatesp][0m [47mposition-ac[0m [47m[position][0m [47m[put-assoc][0m [47m[rassoc][0m [47m[remove][0m [47m[remove-assoc][0m [47m[remove-duplicates][0m [47m[remove1][0m [47m[remove1-assoc][0m [47m[set-difference$][0m ; (see Note below) [47m[subsetp][0m [47m[union$][0m ; (see Note below) Note: Three of the macros above have names ending with the character, `[47m$[0m': [47m[intersection$][0m, [47m[set-difference$][0m, and [47m[union$][0m. In each case there is a corresponding Common Lisp primitive without the trailing `[47m$[0m': [47mintersection[0m, [47mset-difference[0m, and [47munion[0m. However, Common Lisp does not specify the order of elements in the list returned by those primitives, so ACL2 has its own. Nevertheless, the only use of the trailing `[47m$[0m' is to distinguish the primitives; associated functions and macros, for example [47munion-eq[0m and [47mintersection-equal[0m, do not include the `[47m$[0m' character in their names. We conclude with a brief discussion of [guards]. The expansion of any of the above macros depends on the keyword argument, which generates a function call with a guard suitable for the equality test being used. Consider for example the call [47m(member x lst :test 'eq)[0m, or equivalently, [47m(member-eq x lst)[0m. Expanding these macros leads to a call of [47m[mbe][0m; you can see how that goes by using [47m:[0m[47m[trans1][0m. Ultimately, the guard being checked is that of the function [47mmember-eq-exec[0m, which is as follows. (if (symbolp x) (true-listp lst) (symbol-listp lst)) Care has been taken to ensure that this guard is checked during evaluation and also that it generates suitable proof obligations for guard verification (see [verify-guards]). A guard violation might look something like this: ACL2 !>(member-eq 3 '(4 5)) ACL2 Error in TOP-LEVEL: The guard for the function call (MEMBER-EQ-EXEC$GUARD-CHECK X LST), which is (IF (SYMBOLP X) (TRUE-LISTP LST) (SYMBOL-LISTP LST)), is violated by the arguments in the call (MEMBER-EQ-EXEC$GUARD-CHECK 3 '(4 5)). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> Above, [47mmember-eq-exec$guard-check[0m is a function generated as part of ACL2's expansion of [47mmember[0m with [47m:test 'eq[0m, and this function symbol can be quite reasonably ignored. The important thing is that it refers to the guard for [47mmember-eq-exec[0m, which as the name may suggest is intended to guard the execution of a call of [47m[member-eq][0m, or a call of [47m[member][0m with [47m:test 'eq[0m. The important part of the message above is the guard actually being violated: [47m(IF (SYMBOLP X) (TRUE-LISTP LST) (SYMBOL-LISTP LST))[0m. Subtopics [=] Test equality of two numbers [Eq] Equality of symbols [Eql] Test equality (of two numbers, symbols, or [characters]) [Equality-variants-details] Details about [equality-variants]") (equality-variants-details (equality-variants) "Details about [equality-variants] Here we present details about equality variants, none of which is likely to be important to the majority of ACL2 users. Please see [equality-variants] for relevant background. We begin by presenting [events] that implement the equality variants for [47m[member][0m, as these illustrate the events introduced for all macros having equality variants. The definition of [47m[member][0m, just below, calls the macro [47mlet-mbe[0m, which in turn is just an abbreviation for a combination of [47m[let][0m and [47m[mbe][0m. Here is a simplified version of the definition of this macro. For relevant background, see [47m[mbe][0m. (defmacro let-mbe (bindings &key logic exec) `(let ,bindings (mbe :logic ,logic :exec ,exec))) This use of [47m[let][0m arranges that each argument of a call of [47mmember[0m is evaluated only once. The actual definition of the macro [47mlet-mbe[0m is a bit more complex, in order to guarantee that [guard]s are appropriately checked. For purposes of this discussion we ignore this simplification. (You can find the definition of [47mlet-mbe[0m in ACL2 source file [47maxioms.lisp[0m.) Consider the following definition from ACL2 source file [47maxioms.lisp[0m. Notice that it invokes the macro [47mlet-mbe[0m, discussed above. (defmacro member (x l &key (test ''eql)) (declare (xargs :guard (or (equal test ''eq) (equal test ''eql) (equal test ''equal)))) (cond ((equal test ''eq) `(let-mbe ((x ,x) (l ,l)) :logic (member-equal x l) :exec (member-eq-exec x l))) ((equal test ''eql) `(let-mbe ((x ,x) (l ,l)) :logic (member-equal x l) :exec (member-eql-exec x l))) (t ; (equal test 'equal) `(member-equal ,x ,l)))) Inspection of the definition above shows that every call of [47m[member][0m expands to one that is logically equivalent to the corresponding call of [47m[member-equal][0m, which is defined as follows. (defun member-equal (x lst) (declare (xargs :guard (true-listp lst))) (cond ((endp lst) nil) ((equal x (car lst)) lst) (t (member-equal x (cdr lst))))) The following two definitions model equality variants of [47m[member][0m for tests [47m[eq][0m and [47m[eql][0m, respectively. (defun member-eq-exec (x lst) (declare (xargs :guard (if (symbolp x) (true-listp lst) (symbol-listp lst)))) (cond ((endp lst) nil) ((eq x (car lst)) lst) (t (member-eq-exec x (cdr lst))))) (defun member-eql-exec (x lst) (declare (xargs :guard (if (eqlablep x) (true-listp lst) (eqlable-listp lst)))) (cond ((endp lst) nil) ((eql x (car lst)) lst) (t (member-eql-exec x (cdr lst))))) At this point the user can write [47m(member x y)[0m or [47m(member-equal x y)[0m to call equality variants of [47mmember[0m with test [47meql[0m or [47mequal[0m, respectively. We thus provide the following macro for the [47meq[0m variant. (defmacro member-eq (x lst) `(member ,x ,lst :test 'eq)) [Guard] proof obligations generated by calls of [47mmember[0m will include those based on its use of [47mmbe[0m, and are supported by the following two lemmas. (defthm member-eq-exec-is-member-equal (equal (member-eq-exec x l) (member-equal x l))) (defthm member-eql-exec-is-member-equal (equal (member-eql-exec x l) (member-equal x l))) Finally, the following two events arrange that in certain contexts such as [theories] (including the use of [47m[in-theory][0m in [events] and [hints]), [47m[member-eq][0m and [47m[member][0m are treated as references to [47m[member-equal][0m. (add-macro-alias member-eq member-equal) (add-macro-alias member member-equal) Note however that these events do not affect printing of calls during proofs: calls of [47mmember[0m and [47mmember-eq[0m will be macroexpanded away, leaving you with calls of [47mmember-equal[0m that are displayed in proof output. For a way to change this behavior, see [47m[add-macro-fn][0m. We conclude this topic by exploring the following recommendation made in the [documentation] for [equality-variants]. For efficiency we recommend using the [47m-equal[0m equality variant, for example [47m[member-equal][0m or [47m([0m[47m[member][0m[47m ... :TEST 'equal)[0m, in certain contexts: [47m[defmacro][0m, [47m[defpkg][0m, [47m[defconst][0m, and [47m[value-triple][0m forms. ACL2 relies on the underlying Common Lisp for evaluation. It also processes events in the ACL2 logic. In order to guarantee consistency of its logical and Common Lisp evaluations, ACL2 uses a ``safe mode'' to avoid ill-guarded calls. In particular, consider the use of [47m[mbe][0m in execution of a call of an equality variant of a primitive, [47mF[0m, other than its [47mF-equal[0m variant. The [47m[mbe][0m call discussed above requires a connection to be established between the [47m:logic[0m and [47m:exec[0m forms. For example, if [47mF[0m is called with [47m:TEST 'eql[0m (either explicitly or as the default), then ACL2 will call both [47mF-eql-exec[0m and [47mF-equal[0m, and check that the two results are equal. The following partial log illustrates the point above. We define a macro that calls [47m[member][0m, and when a call of this macro is expanded during processing of a subsequent definition, we see that two membership functions are called on the same arguments. ACL2 !>(defmacro mac (lst) (list 'quote (and (true-listp lst) (member 'c lst :test 'eq)))) Summary Form: ( DEFMACRO MAC ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) MAC ACL2 !>(trace$ member-equal member-eq-exec) ((MEMBER-EQUAL) (MEMBER-EQ-EXEC)) ACL2 !>(defun f () (mac (a b c d))) 1> (ACL2_*1*_ACL2::MEMBER-EQ-EXEC C (A B C D)) 2> (MEMBER-EQ-EXEC C (A B C D)) <2 (MEMBER-EQ-EXEC (C D)) <1 (ACL2_*1*_ACL2::MEMBER-EQ-EXEC (C D)) 1> (ACL2_*1*_ACL2::MEMBER-EQUAL C (A B C D)) 2> (MEMBER-EQUAL C (A B C D)) <2 (MEMBER-EQUAL (C D)) <1 (ACL2_*1*_ACL2::MEMBER-EQUAL (C D)) Since F is non-recursive, its admission is trivial. If performance is an issue then we can avoid such a problem, for example as follows. In a fresh session, let us define a suitable wrapper for calling [47m[member][0m with [47m:TEST 'eq[0m. This time, the trace in our partial log shows that we have avoided calling two membership functions. ACL2 !>(defun mem-eq (x lst) (declare (xargs :guard (if (symbolp x) (true-listp lst) (symbol-listp lst)))) (member x lst :test 'eq)) [[ ... output omitted here ... ]] MEM-EQ ACL2 !>(defmacro mac (lst) (list 'quote (and (true-listp lst) (mem-eq 'c lst)))) Summary Form: ( DEFMACRO MAC ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) MAC ACL2 !>(trace$ member-equal member-eq-exec mem-eq) ((MEMBER-EQUAL) (MEMBER-EQ-EXEC) (MEM-EQ)) ACL2 !>(defun f () (mac (a b c d))) 1> (ACL2_*1*_ACL2::MEM-EQ C (A B C D)) 2> (MEM-EQ C (A B C D)) <2 (MEM-EQ (C D)) <1 (ACL2_*1*_ACL2::MEM-EQ (C D)) Since F is non-recursive, its admission is trivial.") (equivalence (rule-classes) "Mark a relation as an equivalence relation See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Example: (defthm r-equal-is-an-equivalence ; assumes that r-equal has been defined (and (booleanp (r-equal x y)) (r-equal x x) (implies (r-equal x y) (r-equal y x)) (implies (and (r-equal x y) (r-equal y z)) (r-equal x z))) :rule-classes :equivalence) Also see [defequiv]. General Form: (and (booleanp (equiv x y)) (equiv x x) (implies (equiv x y) (equiv y x)) (implies (and (equiv x y) (equiv y z)) (equiv x z))) except that the order of the conjuncts and terms and the choice of variable symbols is unimportant. The effect of such a rule is to identify [47mequiv[0m as an equivalence relation. Note that only Boolean 2-place function symbols can be treated as equivalence relations. See [congruence] and see [refinement] for closely related concepts. The macro form [47m(defequiv equiv)[0m is an abbreviation for a [47m[defthm][0m of rule-class [47m:equivalence[0m that establishes that [47mequiv[0m is an equivalence relation. It generates the formula shown above. See [defequiv]. When [47mequiv[0m is marked as an equivalence relation, its reflexivity, symmetry, and transitivity are built into the system in a deeper way than via [47m:[0m[47m[rewrite][0m rules. More importantly, after [47mequiv[0m has been shown to be an equivalence relation, lemmas about [47mequiv[0m, e.g., (implies hyps (equiv lhs rhs)), when stored as [47m:[0m[47m[rewrite][0m rules, cause the system to rewrite certain occurrences of (instances of) [47mlhs[0m to (instances of) [47mrhs[0m. Roughly speaking, an occurrence of [47mlhs[0m in the [47mkth[0m argument of some [47mfn[0m-expression, [47m(fn ... lhs' ...)[0m, can be rewritten to produce [47m(fn ... rhs' ...)[0m, provided the system ``knows'' that the value of [47mfn[0m is unaffected by [47mequiv[0m-substitution in the [47mkth[0m argument. Such knowledge is communicated to the system via ``congruence lemmas.'' For example, suppose that [47mr-equal[0m is known to be an equivalence relation. The [47m:[0m[47m[congruence][0m lemma (implies (r-equal s1 s2) (equal (fn s1 n) (fn s2 n))) informs the rewriter that, while rewriting the first argument of [47mfn[0m-expressions, it is permitted to use [47mr-equal[0m rewrite-rules. See [congruence] for details about [47m:[0m[47m[congruence][0m lemmas. Interestingly, congruence lemmas are automatically created when an equivalence relation is stored, saying that either of the equivalence relation's arguments may be replaced by an equivalent argument. That is, if the equivalence relation is [47mfn[0m, we store congruence rules that state the following fact: (implies (and (fn x1 y1) (fn x2 y2)) (iff (fn x1 x2) (fn y1 y2))) Another aspect of equivalence relations is that of ``refinement.'' We say [47mequiv1[0m ``refines'' [47mequiv2[0m iff [47m(equiv1 x y)[0m implies [47m(equiv2 x y)[0m. [47m:[0m[47m[refinement][0m rules permit you to establish such connections between your equivalence relations. The value of refinements is that if the system is trying to rewrite something while maintaining [47mequiv2[0m it is permitted to use as a [47m:[0m[47m[rewrite][0m rule any refinement of [47mequiv2[0m. Thus, if [47mequiv1[0m is a refinement of [47mequiv2[0m and there are [47mequiv1[0m rewrite-rules available, they can be brought to bear while maintaining [47mequiv2[0m. See [refinement]. The system initially has knowledge of two equivalence relations, equality, denoted by the symbol [47m[equal][0m, and propositional equivalence, denoted by [47m[iff][0m. [47m[Equal][0m is known to be a refinement of all equivalence relations and to preserve equality across all arguments of all functions. Typically there are five steps involved in introducing and using a new equivalence relation, equiv. (1) Define [47mequiv[0m, (2) prove the [47m:equivalence[0m lemma about [47mequiv[0m, (3) prove the [47m:[0m[47m[congruence][0m lemmas that show where [47mequiv[0m can be used to maintain known relations, (4) prove the [47m:[0m[47m[refinement][0m lemmas that relate [47mequiv[0m to known relations other than equal, and (5) develop the theory of conditional [47m:[0m[47m[rewrite][0m rules that drive equiv rewriting. More will be written about this as we develop the techniques. For now, here is an example that shows how to make use of equivalence relations in rewriting. Among the theorems proved below is (defthm insert-sort-is-id (perm (insert-sort x) x)) Here [47mperm[0m is defined as usual with [47mdelete[0m and is proved to be an equivalence relation and to be a congruence relation for [47m[cons][0m and [47m[member][0m. Then we prove the lemma (defthm insert-is-cons (perm (insert a x) (cons a x))) which you must think of as you would [47m(insert a x) = (cons a x)[0m. Now prove [47m(perm (insert-sort x) x)[0m. The base case is trivial. The induction step is (consp x) & (perm (insert-sort (cdr x)) (cdr x)) -> (perm (insert-sort x) x). Opening [47minsert-sort[0m makes the conclusion be (perm (insert (car x) (insert-sort (cdr x))) x). Apply [47minsert-is-cons[0m to get (perm (cons (car x) (insert-sort (cdr x)) x)). Note that we have proved that [47mperm[0m is a congruence relation for [47mcons[0m. That allows us to apply the induction hypothesis (rewriting [47m(insert-sort (cdr x))[0m to [47m(cdr x)[0m), to make the conclusion be (perm (cons (car x) (cdr x)) x). But we know that [47m(cons (car x) (cdr x))[0m is [47mx[0m, so we get [47m(perm x x)[0m which is trivial, since [47mperm[0m is an equivalence relation. An exercise left to the reader is how this proof will change had we also proved that [47mperm[0m is a congruence relation for [47minsert[0m. Here are the events. (encapsulate (((lt * *) => *)) (local (defun lt (x y) (declare (ignore x y)) nil)) (defthm lt-non-symmetric (implies (lt x y) (not (lt y x))))) (defun insert (x lst) (cond ((atom lst) (list x)) ((lt x (car lst)) (cons x lst)) (t (cons (car lst) (insert x (cdr lst)))))) (defun insert-sort (lst) (cond ((atom lst) nil) (t (insert (car lst) (insert-sort (cdr lst)))))) (defun del (x lst) (cond ((atom lst) nil) ((equal x (car lst)) (cdr lst)) (t (cons (car lst) (del x (cdr lst)))))) (defun mem (x lst) (cond ((atom lst) nil) ((equal x (car lst)) t) (t (mem x (cdr lst))))) (defun perm (lst1 lst2) (cond ((atom lst1) (atom lst2)) ((mem (car lst1) lst2) (perm (cdr lst1) (del (car lst1) lst2))) (t nil))) (defthm perm-reflexive (perm x x)) (defthm perm-cons (implies (mem a x) (equal (perm x (cons a y)) (perm (del a x) y))) :hints (("Goal" :induct (perm x y)))) (defthm perm-symmetric (implies (perm x y) (perm y x))) (defthm mem-del (implies (mem a (del b x)) (mem a x))) (defthm perm-mem (implies (and (perm x y) (mem a x)) (mem a y))) (defthm mem-del2 (implies (and (mem a x) (not (equal a b))) (mem a (del b x)))) (defthm comm-del (equal (del a (del b x)) (del b (del a x)))) (defthm perm-del (implies (perm x y) (perm (del a x) (del a y)))) (defthm perm-transitive (implies (and (perm x y) (perm y z)) (perm x z))) (defequiv perm) (in-theory (disable perm perm-reflexive perm-symmetric perm-transitive)) (defcong perm perm (cons x y) 2) (defcong perm iff (mem x y) 2) (defthm atom-perm (implies (not (consp x)) (perm x nil)) :rule-classes :forward-chaining :hints (("Goal" :in-theory (enable perm)))) (defthm insert-is-cons (perm (insert a x) (cons a x))) (defthm insert-sort-is-id (perm (insert-sort x) x)) (defun app (x y) (if (consp x) (cons (car x) (app (cdr x) y)) y)) (defun rev (x) (if (consp x) (app (rev (cdr x)) (list (car x))) nil)) (defcong perm perm (app x y) 2) (defthm app-cons (perm (app a (cons b c)) (cons b (app a c)))) (defthm app-commutes (perm (app a b) (app b a))) (defcong perm perm (app x y) 1 :hints (("Goal" :induct (app y x)))) (defthm rev-is-id (perm (rev x) x)) (defun == (x y) (if (consp x) (if (consp y) (and (equal (car x) (car y)) (== (cdr x) (cdr y))) nil) (not (consp y)))) (defthm ==-reflexive (== x x)) (defthm ==-symmetric (implies (== x y) (== y x))) (defequiv ==) (in-theory (disable ==-symmetric ==-reflexive)) (defcong == == (cons x y) 2) (defcong == iff (consp x) 1) (defcong == == (app x y) 2) (defcong == == (app x y) 1) (defthm rev-rev (== (rev (rev x)) x))") (equivalent-formulas-different-rewrite-rules (introduction-to-the-theorem-prover) "Logically equivalent formulas can generate radically different rules Consider the rewrite rules that would be generated from the three commands below. In all three cases, the fact being stated relates the [47mn[0mth element of the reverse of [47mx[0m to the [47mn[0mth element of [47mx[0m. In fact, the three formulas are simple rearrangements of each other and are all equivalent. The theorem prover treats all three formulas equivalently when proving them. But the rules generated from them are very different. (defthm nth-rev-1 (implies (and (natp n) (< n (len x))) (equal (nth n (rev x)) (nth (- (len x) (+ 1 n)) x)))) (defthm nth-rev-2 (implies (and (natp n) (< n (len x))) (equal (nth (- (len x) (+ 1 n)) x) (nth n (rev x))))) (defthm nth-rev-3 (implies (and (natp n) (not (equal (nth n (rev x)) (nth (- (len x) (+ 1 n)) x)))) (not (< n (len x))))) Here are the three rewrite rules: [31;1mnth-rev-1[0m: Replace instances of [47m(NTH n (REV x))[0m by [47m(NTH (- (LEN x) (+ 1 n)) x)[0m, if you can establish that [47mn[0m is a natural number less than the length of [47mx[0m. [31;1mnth-rev-2[0m: Replace instances of [47m(NTH (- (LEN x) (+ 1 n)) x)[0m by [47m(NTH n (REV x))[0m, if you can establish that [47mn[0m is a natural number less than the length of [47mx[0m. [31;1mnth-rev-3[0m: Replace instances of [47m(< n (LEN x))[0m by [47mNIL[0m if you can establish that [47mn[0m is a natural number and that [47m(NTH n (REV x))[0m is different from [47m(NTH (- (LEN x) (+ 1 n)) x)[0m. As the driver of ACL2, you have to decide which rule you want [3mwhen you give the command to prove it[0m. If you tell the theorem prover to use both [47mnth-rev-1[0m and [47mnth-rev-2[0m, ACL2 will enter an infinite loop when it sees any term matching either [47mNTH[0m expression. Most users would choose form [47mnth-rev-1[0m of the rule. It eliminates [47mrev[0m from the problem --- at the expense of introducing some arithmetic. But arithmetic is so fundamental it is rarely possible to avoid it and it is likely to be in the problem already since you're indexing into [47m(rev x)[0m. The [47mnth-rev-2[0m form of the rule is ``bad'' because it introduces [47mrev[0m into a problem where it might not have appeared. The [47mnth-rev-3[0m version is ``bad'' because it makes the theorem prover shift its attention from a simple arithmetic inequality to a complicated property of [47mnth[0m and [47mrev[0m, which might not be in the problem. Use your browser's [31;1mBack Button[0m now to return to [introduction-to-rewrite-rules-part-1].") (er (errors acl2-built-ins) "Print an error message and ``cause an error'' See [fmt] for a general discussion of formatted printing in ACL2. All calls of [47mer[0m print formatted strings, just as is done by [47m[fmt][0m. Example Forms: (er hard 'top-level "Illegal inputs, ~x0 and ~x1." a b) (er hard? 'top-level "Illegal inputs, ~x0 and ~x1." a b) (er hard! 'top-level "Illegal inputs, ~x0 and ~x1." a b) (er soft 'top-level "Illegal inputs, ~x0 and ~x1." a b) (er-soft 'top-level "Illegal-inputs" "Illegal inputs, ~x0 and ~x1." a b) The examples above all print an error message to standard output saying that (the values of) [47ma[0m and [47mb[0m are illegal inputs. However, the first three --- which we call [3mhard errors[0m --- abort evaluation after printing an error message (while logically returning [47mnil[0m, though in ordinary evaluation the return value is never seen); while the last two --- so-called [3msoft errors[0m --- return an [error-triple], [47m(mv t nil state)[0m, after printing an error message. The result in each of the two soft error cases can be interpreted as an ``error'' when programming with the ACL2 [47m[state][0m, something most ACL2 users will probably not want to do unless they are building systems of some sort; see [programming-with-state]. If state is not available in the current context then you will probably want to cause a hard error; for example, if you are returning two values, you may write [47m(mv (er hard ...) nil)[0m. The difference between the [47mhard[0m and [47mhard?[0m forms is one of guards. Use [47mhard[0m if you want the call to generate a (clearly impossible) guard proof obligation of (essentially) [47mNIL[0m. But use [47mhard?[0m if you want to be able to call this function in guard-verified code, since the call generates a (trivially satisfied) guard proof obligation of [47mT[0m. The difference between the [47mhard[0m and [47mhard![0m forms is that there are situations in which [47m(er hard ...)[0m returns [47mnil[0m rather than causing an error, while [47m(er hard! ...)[0m will always cause an error (though such errors are sometimes ``caught'', for example during proofs). You will probably be happy using [47mhard[0m rather than considering the use of [47mhard![0m, which is really provided mostly for system implementors; but you can try [47mhard![0m if you are not getting the errors you expect. There is even an additional option, [47mhard?![0m, which avoids guard proof obligations like [47mhard?[0m but ensures errors like [47mhard![0m. [47mEr[0m is a macro, and the examples above expand to calls of ACL2 functions; see below. Also see [illegal], [hard-error], and [error1]. The [47mhard?[0m/[47mhard?![0m forms have expansions that call the function [47m[hard-error][0m, which has a [guard] of [47mT[0m, while the [47mhard[0m/[47mhard![0m forms have expansions that call the function [47m[illegal][0m, which has a guard that is logically [47mNIL[0m. Those generate code that is in [47m:[0m[47m[logic][0m mode, as do variants of [47m(er soft ...)[0m. The soft error forms expand to calls of the function [47m[error1][0m, which necessarily takes [47m[state][0m as an explicit argument since it returns an [error-triple]. The guard for the soft error forms is that of [47m[error1][0m. Note in particular that soft errors require the state to satisfy certain restrictions beyond just the usual [47mstate-p[0m predicate. The general forms of the macros are as follows. Their macroexpansions include code that avoids the printing of error messages when error output is inhibited --- see [set-inhibit-output-lst] --- but here we show only the essential function calls. Note that all arguments are evaluated even when error output is inhibited. General Forms: (er hard ctx fmt-string arg1 arg2 ... argk) ==> {macroexpands, in essence, to:} (ILLEGAL CTX FMT-STRING (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk))) (er hard? ctx fmt-string arg1 arg2 ... argk) ==> {macroexpands, in essence, to:} (HARD-ERROR CTX FMT-STRING (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk))) (er hard! ctx fmt-string arg1 arg2 ... argk) ; logically is same as (er hard ...), but always produces an error (er soft ctx fmt-string arg1 arg2 ... argk) ==> {macroexpands, in essence, to:} (ERROR1 CTX NIL FMT-STRING (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk))) (er-soft ctx summary fmt-string arg1 arg2 ... argk) ==> {macroexpands, in essence, to:} (ERROR1 CTX SUMMARY FMT-STRING (LIST (CONS #\0 ARG1) (CONS #\1 ARG2) ... (CONS #\k ARGk))) See [ctx] for the possible forms of the [47mctx[0m argument. Technical note for raw Lisp programmers only: It is possible to cause hard errors to signal actual raw Lisp errors. See [hard-error].") (er-cmp (pointers) "See [context-message-pair].") (er-hard (errors acl2-built-ins) "Print an error message and ``cause a hard error'' See [er] for relevant background, which is assumed below, and related utilities. General Form: (er-hard context summary str &rest str-args) where context is a legal context (see [ctx]), [47msummary[0m is [47mnil[0m or a string, [47mstr[0m is a string, and [47mstr-args[0m are [47mtsee fmt[0m arguments for [47mstr[0m. Note that [47m(er-hard context summary str ...)[0m is equivalent to [47m(er hard context (cons summary str) ...)[0m. The use of a non-[47mnil[0m [47msummary[0m allows suppression of this error message without suppressing all error output; see [set-inhibit-er]. Calls of [47mer-hard[0m expand much like calls [47m(er hard ...)[0m, in the sense that both expand to calls of the function, [47m[illegal][0m, which has a [guard] equivalent to [47mnil[0m. See [er-hard?] for a similar utility that avoids generating guard obligations. See [47m[er-soft][0m for a similar utility pertaining to ``soft'' errors.") (er-hard? (errors acl2-built-ins) "Print an error message and ``cause a hard error'' See [er-hard] for a nearly identical utility that is aligned with [47m(er hard ...)[0m, generating a [guard] obligation of [47mnil[0m. By contrast, [47m(er-hard? ...)[0m is aligned with [47m(er hard? ...)[0m): these do not generate guard obligations. This distinction is due to the fact that a call of [47m(er-hard ...)[0m macroexpands to a call of the function, [47m[illegal][0m, while a call of [47m(er-hard? ...)[0m macroexpands to a call of the function, [47m[hard-error][0m. General Form: (er-hard? context summary str &rest str-args) Other than the difference in guard obligations generated, as discussed above, [47mer-hard?[0m behaves identically to [47mer-hard[0m. See [er-hard] and for relevant background, see [er].") (er-let* (pointers) "See [programming-with-state].") (er-let*-cmp (pointers) "See [context-message-pair].") (er-progn (errors programming-with-state acl2-built-ins) "Perform a sequence of state-changing ``error triples'' Example: (er-progn (check-good-foo-p (f-get-global 'my-foo state) state) (value (* (f-get-global 'my-foo state) (f-get-global 'bar state)))) This sequencing primitive is only useful when programming with [state], something that very few users will probably want to do. See [state]. [47mEr-progn[0m is used much the way that [47m[progn][0m is used in Common Lisp, except that it expects each form within it to evaluate to an [error-triple] of the form [47m(mv erp val state)[0m. The first such form, if any, that evaluates to such a triple where [47merp[0m is not [47mnil[0m yields the error triple returned by the [47mer-progn[0m. If there is no such form, then the [47mer-progn[0m form returns the value of the last form. General Form: (er-progn <expr1> ... <exprk>) where each [47m<expri>[0m is an expression that evaluates to an error triple (see [programming-with-state]). The above form is essentially equivalent to the following (``essentially'' because in fact, care is taken to avoid variable capture). (mv-let (erp val state) <expr1> (cond (erp (mv erp val state)) (t (mv-let (erp val state) <expr2> (cond (erp (mv erp val state)) (t ... (mv-let (erp val state) <expr{k-1}> (cond (erp (mv erp val state)) (t <exprk>)))))))))") (er-progn-cmp (pointers) "See [context-message-pair].") (er-soft (errors acl2-built-ins) "Print an error message and ``cause a soft error'' See [er] for relevant background, which is assumed below, and related utilities. General Form: (er-soft context summary str &rest str-args) where context is a legal context (see [ctx]), [47msummary[0m is [47mnil[0m or a string, [47mstr[0m is a string, and [47mstr-args[0m are [47mtsee fmt[0m arguments for [47mstr[0m. The use of a non-[47mnil[0m [47msummary[0m allows suppression of this error message without suppressing all error output; see [set-inhibit-er]. See [47m[er-hard][0m for a similar utility pertaining to ``hard'' errors.") (error (pointers) "See [hints] for information about the keyword [47m:error[0m.") (error-triple (errors programming-with-state) "A common ACL2 programming idiom When evaluation returns three values, where the first two are ordinary (non-[stobj]) objects and the third is the ACL2 [state], the result may be called an ``error triple'' or ``error-triple''. If an error triple is [47m(mv erp val state)[0m, we think of [47merp[0m as an error flag and [47mval[0m as the returned value. By default, if the result of evaluating a top-level form is an error triple [47m(mv erp val state)[0m, then that result is not printed if [47merp[0m is non-[47mnil[0m or if [47mval[0m is the keyword [47m:INVISIBLE[0m, and otherwise [47mval[0m is printed with a preceding space. For example: ACL2 !>(+ 3 4) ; ordinary value 7 ACL2 !>(mv nil (+ 3 4) state) ; error triple, error component of nil 7 ACL2 !>(mv t (+ 3 4) state) ; error triple, non-nil error component ACL2 !>(mv nil :invisible state) ; special case for :INVISIBLE ACL2 !> In certain settings, notably when printing evaluation results, multiple values [47m(mv erp val state)[0m may be considered an error triple even when [47mval[0m is a [df] rather than an ordinary object. Here is an example; see [df] for more about how floating-point numbers are simulated in ACL2. ACL2 !>(mv nil (to-df 3) state) #d3.0 ACL2 !> See [programming-with-state] for a discussion of error triples and how to program with them. Also see [ld-error-triples] and see [ld] for a discussion of the value [47m:COMMAND-CONVENTIONS[0m for keyword [47m:LD-POST-EVAL-PRINT[0m.") (error-triples-and-parallelism (parallel-programming) "How to avoid error triples in ACL2(p) This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. ACL2 supports the use of error triples in many features; e.g., [47m[computed-hints][0m. (For background on error triples, see [programming-with-state].) However, ACL2(p) does not support the use of error triples in some of these features (e.g., [47m[computed-hints][0m) while [waterfall-parallelism] is enabled. You may see an error message like the following when running ACL2(p) with [waterfall-parallelism] enabled: ACL2 Error in ( THM ...): Since we are translating a form in ACL2(p) intended to be executed with waterfall parallelism enabled, the form (MY-STATE-MODIFYING-COMPUTED-HINT ID STATE) was expected to represent an ordinary value, not an error triple (mv erp val state), as would be acceptable in a serial execution of ACL2. Therefore, the form returning a tuple of the form (* * STATE) is an error. See :DOC unsupported- waterfall-parallelism-features and :DOC error-triples-and-parallelism for further explanation. In this particular example, the cause of the error was trying to use a computed hint that returned state, which is not allowed when executing the waterfall in parallel (see [unsupported-waterfall-parallelism-features] for other related information). Often, the only reason users need to return state is so they can perform some output during the proof process. In this case, we suggest using one of the state-free output functions, like [47m[cw][0m or [47m[observation-cw][0m. If the user is concerned about the interleaving of their output with other output, these calls can be surrounded with the macro [47m[with-output-lock][0m. Another frequent reason users return state is so they can cause a [47msoft[0m error and halt the proof process. In this case, we suggest instead calling [47m[er][0m with the [47mhard[0m or [47mhard?[0m severity. By using these mechanisms, the user avoids modifying [47m[state][0m, a requirement for much of the code written in ACL2(p). You may encounter other similar error messages when using [computed-hints], [custom-keyword-hints], or [override-hints]. Chances are that you are somehow returning an error triple when an ordinary value is needed. If this turns out not to be the case, please let the ACL2 implementors know.") (error1 (errors acl2-built-ins) "Print an error message and cause a ``soft error'' [47m(Error1 ctx summary str alist state)[0m returns [47m(mv t nil state)[0m. An error message is first printed using the ``context'' [47mctx[0m, as well as the string [47mstr[0m and alist [47malist[0m that are of the same kind as expected by [47m[fmt][0m --- unless error output is inhibited (see [set-inhibit-output-lst] and [with-output]) or [47msummary[0m is non-[47mnil[0m, in which case it is a string, and error output of that type is inhibited (see [set-inhibit-er]). See [fmt]. [47mError1[0m can be interpreted as causing an ``error'' when programming with the ACL2 [47m[state][0m, something most ACL2 users will probably not want to do; see [ld-error-triples] and see [er-progn]. However, [47merror1[0m is a guard verified [47m[logic][0m mode function whose guard is (AND (STATE-P STATE) (STRINGP STR) (ERROR1-STATE-P STATE) (CHARACTER-ALISTP ALIST) (OR (NULL SUMMARY) (STRINGP SUMMARY))) Note in particular that the state must not only satisfy the basic recognizer, [47mstate-p[0m, for ACL2 states but must also satisfy [47merror1-state-p[0m, which includes additional restrictions ensuring that [47merror1[0m can print formatted output to the standard character output channel, [47m[standard-co][0m, interpret the table maintained by [47m[set-inhibit-er][0m, etc. If the complexity of [error1]'s guard discourages you from using it in guard-verified logic mode systems you may wish to cause a [hard-error] with [47m[illegal][0m or the more unified way of signaling errors with the macro [47m[er][0m. As mentioned above, [47merror1[0m always returns [47m(mv t nil state)[0m. But if a call [47m(error1 ctx summary str alist)[0m is encountered during evaluation, then unless output is inhibited as described above, the string [47mstr[0m is first printed using the association list [47malist[0m (as in [47m[fmt][0m). Here is a trivial, contrived example. ACL2 !>(error1 'my-context "Printing 4: ~n0" (list (cons #\0 4)) state) ACL2 Error in MY-CONTEXT: Printing 4: four ACL2 !>") (errors (programming) "Support for causing runtime errors, breaks, assertions, etc. Subtopics [Assert$] Cause a hard error if the given test is false [Assert*] Create a [guard] proof obligation that given test holds [Assert-event] Assert that a given form returns a non-[47mnil[0m value [Break$] Cause an immediate Lisp break [Breaks] Common Lisp breaks [Ctx] Context object for error messages [Ctxp] Recognizer for context objects for error messages [Er] Print an error message and ``cause an error'' [Er-hard] Print an error message and ``cause a hard error'' [Er-hard?] Print an error message and ``cause a hard error'' [Er-progn] Perform a sequence of state-changing ``error triples'' [Er-soft] Print an error message and ``cause a soft error'' [Error-triple] A common ACL2 programming idiom [Error1] Print an error message and cause a ``soft error'' [Hard-error] Print an error message and stop execution [Illegal] Print an error message and stop execution [Set-inhibit-er] Control the error output [Set-inhibit-er!] Control error output non-[47m[local][0mly [Set-warnings-as-errors] Changing [warnings] to hard [errors] (and vice-versa) [Toggle-inhibit-er] Add or delete an error output string from the [47minhibit-er-table[0m [Toggle-inhibit-er!] Toggle an [47minhibit-er-table[0m entry non-[47m[local][0mly [Value-triple] Compute a value, optionally checking that it is not [47mnil[0m") (escape-to-common-lisp (common-lisp) "Escaping to Common Lisp Example: ACL2 !>:Q There is essentially no Common Lisp escape feature in the ACL2 loop (see [lp]). (A potentially unsound exception is raw-mode; see [set-raw-mode].) This is part of the price of purity. To execute a form in Common Lisp as opposed to ACL2, exit [47m[lp][0m with [47m:q[0m, submit the desired forms to the Common Lisp read-eval-print loop, and reenter ACL2 with [47m(lp)[0m. WARNING: Doing so is potentially unsound; see [q].") (ev$ (apply$) "Evaluate a tame expression using [47mapply$[0m When [47m[apply$][0m, actually [47m[apply$-lambda][0m, is asked to apply a [47mLAMBDA[0m object to some arguments it calls [47mev$[0m on the body of the object and an alist binding the formals of the object to the arguments. Roughly put, [47mev$[0m ``works'' by looking up symbols, returning quoted objects, and using [47mapply$[0m to apply function symbols to the results of evaluating their arguments. [47mEv$[0m and its clique-mate [47mev$-list[0m are mutually-recursive with [47mapply$[0m. [47mEv$[0m can only evaluate ``as expected'' on [tame] expressions and requires [47m[warrant][0ms, explicit in the proof theory or implicit in the evaluation theory, to determine [badge]s and thus tameness. See [47m[apply$][0m for details, including the formal definitions of [47mev$[0m and [47mev$-list[0m. For a summary of how the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m [scion]s, see [rewriting-calls-of-apply$-ev$-and-loop$-scions].") (ev$-list (pointers) "See [apply$].") (evaluating_app_on_sample_input (pages_written_especially_for_the_tours) "Evaluating App on Sample Input {IMAGE} (see [The_Associativity_of_App]) {IMAGE} Click here (see [SYMBOLS]) {ICON} (see [A_Tiny_Warning_Sign]) for an explanation of conversion of symbols to upper case. ACL2 !>[31;1m(app nil '(x y z))[0m (X Y Z) ACL2 !>[31;1m(app '(1 2 3) '(4 5 6 7))[0m (1 2 3 4 5 6 7) ACL2 !>[31;1m(app '(a b c d e f g) '(x y z))[0m (A B C D E F G X Y Z) ACL2 !>[31;1m(app (app '(1 2) '(3 4)) '(5 6))[0m (1 2 3 4 5 6) ACL2 !>[31;1m(app '(1 2) (app '(3 4) '(5 6)))[0m (1 2 3 4 5 6) ACL2!>[31;1m(let ((a '(1 2))[0m [31;1m(b '(3 4))[0m [31;1m(c '(5 6)))[0m [31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c))))[0m T {IMAGE} As we can see from these examples, ACL2 functions can be executed more or less as Common Lisp. The last three examples suggest an interesting property of [47mapp[0m. {IMAGE} (see [The_Associativity_of_App])") (evaluation (programming) "Evaluating ACL2 expressions This topic uses examples to expose how ACL2 uses Common Lisp to evaluate expressions. Links are provided to topics that elaborate on aspects of evaluation in ACL2. At a high level, we can say that ACL2 evaluation takes place using the underlying host Common Lisp. But consider the form [47m(car 3)[0m. In Common Lisp this is an error; typically you will be thrown into the Lisp debugger. In the ACL2 read-eval-print loop, however, you may see the following. ACL2 !>(car 3) ACL2 Error in TOP-LEVEL: The guard for the function call (CAR X), which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CAR 3). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> The message suggests that the function [47mcar[0m has a [guard], or precondition, that is violated by the proposed argument, [47m3[0m. So clearly something more is going on here than just evaluation of the form [47m(car 3)[0m in Common Lisp. In fact, every ACL2 function symbol is associated with the following two Common Lisp definitions, as explained below: * the ``executable-counterpart'' definition, sometimes called the ``*1*'' function (pronounced ``star one star''); and * the ``submitted'' definition (sometimes called the ``raw Lisp'' function). We may also speak of the ``executable-counterpart'' and ``submitted'' functions, which are the two functions defined by the ``executable-counterpart'' and ``submitted'' definitions, respectively. Let us explore these two functions in the case of [47mcar[0m. When [47m(car 3)[0m is evaluated in the ACL2 loop, the executable-counterpart of [47mcar[0m is applied to the argument [47m3[0m. That executable-counterpart (which was hand-coded) first checks the guard of [47mcar[0m, which fails for [47m3[0m, leading to the error displayed above. If instead the form to be evaluated by ACL2 is [47m(car '(4 5 6))[0m, the executable-counterpart of [47mcar[0m will first check that the guard of [47mcar[0m holds for the list argument [47m(4 5 6)[0m; then seeing that this is the case, it will apply the Common Lisp function [47mcar[0m --- which we consider to be the ``submitted'' function for [47mcar[0m --- to that list argument, returning [47m4[0m. The example above does not really explain why the submitted function is called ``submitted'', so let us consider the more common case of a defined function, as opposed to a [primitive] like [47mcar[0m. Suppose we define the following functions [47mf[0m and [47mg[0m, each of which has an implicit [guard] (precondition) of [47mt[0m, i.e., the precondition always holds. (defun f (x) (car x)) (defun g (x) (f x)) ACL2 defines two functions named [47m"F"[0m: the executable-counterpart of [47mf[0m, sometimes called ``[47m*1*f[0m'', and the submitted function for [47mf[0m. It also defines two such functions for [47mg[0m. The executable-counterpart is generated by ACL2 to include not only code to check guards, but also code to invoke the executable-counterparts of its callees. (Such invocation can be avoided by a process known as verifying guards, as we explain further below.) We can see what is going on by tracing calls of [47mf[0m (see [trace] for more about tracing); some analysis follows below this display. ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(g '(4 5 6)) 1> (ACL2_*1*_ACL2::G (4 5 6)) 2> (ACL2_*1*_ACL2::F (4 5 6)) <2 (ACL2_*1*_ACL2::F 4) <1 (ACL2_*1*_ACL2::G 4) 4 ACL2 !> It is now perhaps evident why sometimes we call the executable-counterpart functions the ``*1* functions'': the executable-counterpart is actually defined in a special ``*1*'' package that corresponds to the package of the submitted function. The trace above shows that the executable-counterpart of [47mg[0m calls the executable-counterpart of [47mf[0m, rather than calling any submitted function. Such a trace can show us an error caused by applying [47mcar[0m to [47m3[0m. ACL2 !>(g 3) 1> (ACL2_*1*_ACL2::G 3) 2> (ACL2_*1*_ACL2::F 3) ACL2 Error in TOP-LEVEL: The guard for the function call (CAR X), which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CAR 3). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> It is generally more efficient to invoke a submitted functions --- which has as its Common Lisp definition exactly the [47m[defun][0m form submitted to ACL2 --- than it is to invoke an executable-counterpart, which is generated by ACL2 to do auxiliary calculations including guard-checking. So we next modify the example above to show that by performing a process called ``guard verification'', we can avoid *1* function calls, so that submitted functions are invoked instead. This time we supply reasonable guards for [47mf[0m and [47mg[0m, in a fresh ACL2 session. (defun f (x) (declare (xargs :guard (or (consp x) (null x)))) (car x)) (defun g (x) (declare (xargs :guard (consp x))) (f x)) This time, we see that the executable-counterpart of [47mg[0m directly calls the submitted function for [47mg[0m, because [47mg[0m was guard-verified when [47mg[0m was admitted and the value [47m'(4 5 6)[0m for the formal [47mx[0m of [47mg[0m satisfies the guard [47m(consp x)[0m of [47mg[0m. ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(g '(4 5 6)) 1> (ACL2_*1*_ACL2::G (4 5 6)) 2> (G (4 5 6)) 3> (F (4 5 6)) <3 (F 4) <2 (G 4) <1 (ACL2_*1*_ACL2::G 4) 4 ACL2 !> We can also see that because [47m3[0m fails to satisfy the guard of [47mg[0m, a guard violation is signaled by the executable-counterpart of [47mg[0m, rather than (as before) by the executable-counterpart of [47mcar[0m. ACL2 !>(g 3) 1> (ACL2_*1*_ACL2::G 3) ACL2 Error in TOP-LEVEL: The guard for the function call (G X), which is (CONSP X), is violated by the arguments in the call (G 3). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> See if you can predict the corresponding traces if instead, [47mf[0m has a suitable guard and is guard-verified, but [47mg[0m is as in the first example (with an implicit guard of [47mt[0m, and not guard-verified): (defun f (x) (declare (xargs :guard (or (consp x) (null x)))) (car x)) (defun g (x) (f x)) The corresponding trace is as follows; discussion follows. ACL2 !>(g '(4 5 6)) 1> (ACL2_*1*_ACL2::G (4 5 6)) 2> (ACL2_*1*_ACL2::F (4 5 6)) 3> (F (4 5 6)) <3 (F 4) <2 (ACL2_*1*_ACL2::F 4) <1 (ACL2_*1*_ACL2::G 4) 4 ACL2 !>(g 3) 1> (ACL2_*1*_ACL2::G 3) 2> (ACL2_*1*_ACL2::F 3) ACL2 Error in TOP-LEVEL: The guard for the function call (F X), which is (OR (CONSP X) (NULL X)), is violated by the arguments in the call (F 3). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> The traces above show that first, the executable-counterpart of [47mg[0m calls the executable-counterpart of [47mf[0m. This is because [47mg[0m is not guard-verified, so its executable-counterpart can only invoke other executable-counterparts. However, since [47mf[0m is guard-verified, its executable-counterpart invokes its submitted function when the guard is satisfied, for example to generate the call [47m(F (4 5 6))[0m. If the guard for [47mf[0m fails to hold, however, the executable-counterpart for [47mf[0m causes a guard violation error, as shown above for the executable-counterpart call [47m(ACL2_*1*_ACL2::F 3)[0m. See also [guard] and its subtopics, especially, [guards-and-evaluation], for a discussion of guards and their connection to evaluation. Advanced system hackers who want to see the executable-counterpart definition for [47mf[0m may invoke [47m(trace! (oneify-cltl-code :native t))[0m before defining [47mf[0m in ACL2. Subtopics [Guard-checking-inhibited] Avoiding certain warnings when evaluating ACL2 expressions") (evaluator-restrictions (meta) "Some restrictions on the use of evaluators in meta-level rules Note: This topic, which explains some subtleties for evaluators, can probably be skipped by most readers. Rules of class [47m:[0m[47m[meta][0m and of class [47m:[0m[47m[clause-processor][0m are stated using so-called ``evaluator'' functions. Here we explain some restrictions related to evaluators. Below we refer primarily to [47m:meta[0m rules, but the discussion applies equally to [47m:clause-processor[0m rules. In a nutshell, we require that a rule's evaluator does not support any [meta-extract] functions in the rule or any [47m[defaxiom][0m events, and we require that the evaluator not be introduced under a non-trivial encapsulate. We also require that no function has an attachment (see [defattach]) that is both ancestral in the evaluator and also ancestral in the meta or clause-processor functions. We explain these restrictions in detail below, including the notion of one function symbol being ``ancestral in'', also expressed as ``an ancestor of'', in another function symbol. An argument given elsewhere (see [meta], in particular ``Aside for the logic-minded'') explains that the correctness argument for applying metatheoretic simplifiers requires that one be able to ``grow'' an evaluator (see [defevaluator]) to handle all functions in the current ACL2 [world]. Then we may, in essence, functionally instantiate the original evaluator to the new (``grown'') evaluator, provided that the new evaluator satisfies all of the axioms of the original. We therefore require that the evaluator function does not support the formula of any [47m[defaxiom][0m event. This notion of ``support'' (sometimes denoted ``is an ancestor of'') is defined recursively as follows: a function symbol supports a formula if either it occurs in that formula, or else it supports the definition or constraint for some function symbol that occurs in that formula. Moreover, we require that neither the evaluator function nor its list version support [meta-extract] functions if they are used in the proposed [47m:meta[0m theorem. These requirements are necessary in order to carry out the functional instantiation argument alluded to above, as follows (where the reader may find it useful to have some familiarity with the paper ``Structured Theory Development for a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2 (2001), pages 161-203). By the usual conservativity argument, we know that the rule follows logically from the axiomatic events for its supporters. This remains true if we functionally instantiate the evaluator with one corresponding to all the functions symbols of the current session, since none of the definitions of supporters of defaxioms or metafunctions are hit by that functional substitution. Notice though that the argument above depends on knowing that the rule is not itself an axiom about the evaluator! Therefore, we also restrict evaluators so that they are not defined in the scope of a superior [47m[encapsulate][0m event with non-empty signature, in order to avoid an even more subtle problem. The aforementioned correctness argument depends on knowing that the rule is provable from the axioms on the evaluator and metafunction (and hypothesis metafunction, if any). The additional restriction avoids unsoundness! The following events, if allowed, produce a proof that [47m(f x)[0m equals [47mt[0m even though, as shown below, that does not follow logically from the axioms introduced. ; Introduce our metafunction. (defun my-cancel (term) (case-match term (('f ('g)) *t*) (& term))) ; Introduce our evaluator and prove our meta rule, but in the same ; encapsulate! (encapsulate ((f (x) t)) (local (defun f (x) (declare (ignore x)) t)) (defevaluator evl evl-list ((f x))) (defthm correctness-of-my-cancel (equal (evl x a) (evl (my-cancel x) a)) :rule-classes ((:meta :trigger-fns (f))))) ; Prove that (f x) = t. (encapsulate () (local (defstub c () t)) (local (encapsulate () (local (defun g () (c))) (local (in-theory (disable g (g)))) (local (defthm f-g (equal (f (g)) t) :rule-classes nil)) (defthm f-c (equal (f (c)) t) :hints (("Goal" :use f-g :in-theory (e/d (g) (correctness-of-my-cancel)))) :rule-classes nil))) (defthm f-t (equal (f x) t) :hints (("Goal" :by (:functional-instance f-c (c (lambda () x))))) :rule-classes nil)) To see that the term [47m(equal (f x) t)[0m does not follow logically from the axiomatic [events] above, consider following the above definition of [47mmy-cancel[0m with the following [events] instead. ; (defun my-cancel (term) ...) as before, then: (defun f (x) (not x)) (defun g () nil) (defevaluator evl evl-list ((f x) (g))) These events imply the axiomatic events above, because we still have the definition of [47mmy-cancel[0m, we have a stronger [47m[defevaluator][0m event, and we can now prove [47mcorrectness-of-my-cancel[0m exactly as it is stated above. So, the rule [47mf-t[0m is a logical consequence of the chronology of the current session. However, in the current session we can also prove the following rule, which contradicts [47mf-t[0m. (defthm f-not-t (equal (f t) nil) :rule-classes nil) It follows that the current session logically yields a contradiction! Erik Reeber has taken the above example and modified it to prove [47mnil[0m in ACL2 Version_3.1, as follows. (in-package "ACL2") (defun my-cancel (term) (case-match term (('f ('g)) *t*) (('f2 ('g2)) *t*) (& term))) (defun f2 (x) (not x)) (defun g2 () nil) (encapsulate ((f (x) t)) (local (defun f (x) (declare (ignore x)) t)) (defevaluator evl evl-list ((f x) (f2 x) (g2))) (defthm correctness-of-my-cancel (equal (evl x a) (evl (my-cancel x) a)) :rule-classes ((:meta :trigger-fns (f))))) (encapsulate () (local (defstub c () t)) (local (encapsulate () (local (defun g () (c))) (local (in-theory (disable g (g)))) (local (defthm f-g (equal (f (g)) t) :rule-classes nil)) (defthm f-c (equal (f (c)) t) :hints (("Goal" :use f-g :in-theory (e/d (g) (correctness-of-my-cancel)))) :rule-classes nil))) (defthm f-t (equal (f x) t) :hints (("Goal" :by (:functional-instance f-c (c (lambda () x))))) :rule-classes nil)) (defun g () nil) ; Below is the expansion of the following defevaluator, changed slightly as ; indicated by comments. ; (defevaluator evl2 evl2-list ((f x) (f2 x) (g) (g2))) (ENCAPSULATE (((EVL2 * *) => *) ((EVL2-LIST * *) => *)) (SET-INHIBIT-WARNINGS "theory") (LOCAL (IN-THEORY *DEFEVALUATOR-FORM-BASE-THEORY*)) (LOCAL (MUTUAL-RECURSION (DEFUN EVL2 (X A) (DECLARE (XARGS :VERIFY-GUARDS NIL :MEASURE (ACL2-COUNT X) :WELL-FOUNDED-RELATION O< :MODE :LOGIC)) (COND ((SYMBOLP X) (CDR (ASSOC-EQ X A))) ((ATOM X) NIL) ((EQ (CAR X) 'QUOTE) (CAR (CDR X))) ((CONSP (CAR X)) (EVL2 (CAR (CDR (CDR (CAR X)))) (PAIRLIS$ (CAR (CDR (CAR X))) (EVL2-LIST (CDR X) A)))) ((EQUAL (CAR X) 'F) ; changed f to f2 just below (F2 (EVL2 (CAR (CDR X)) A))) ((EQUAL (CAR X) 'F2) (F2 (EVL2 (CAR (CDR X)) A))) ((EQUAL (CAR X) 'G) (G)) ((EQUAL (CAR X) 'G2) (G2)) (T NIL))) (DEFUN EVL2-LIST (X-LST A) (DECLARE (XARGS :MEASURE (ACL2-COUNT X-LST) :WELL-FOUNDED-RELATION O<)) (COND ((ENDP X-LST) NIL) (T (CONS (EVL2 (CAR X-LST) A) (EVL2-LIST (CDR X-LST) A))))))) (DEFTHM EVL2-CONSTRAINT-1 (IMPLIES (SYMBOLP X) (EQUAL (EVL2 X A) (CDR (ASSOC-EQ X A))))) (DEFTHM EVL2-CONSTRAINT-2 (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'QUOTE)) (EQUAL (EVL2 X A) (CADR X)))) (DEFTHM EVL2-CONSTRAINT-3 (IMPLIES (AND (CONSP X) (CONSP (CAR X))) (EQUAL (EVL2 X A) (EVL2 (CADDAR X) (PAIRLIS$ (CADAR X) (EVL2-LIST (CDR X) A)))))) (DEFTHM EVL2-CONSTRAINT-4 (IMPLIES (NOT (CONSP X-LST)) (EQUAL (EVL2-LIST X-LST A) NIL))) (DEFTHM EVL2-CONSTRAINT-5 (IMPLIES (CONSP X-LST) (EQUAL (EVL2-LIST X-LST A) (CONS (EVL2 (CAR X-LST) A) (EVL2-LIST (CDR X-LST) A))))) (DEFTHM EVL2-CONSTRAINT-6 (IMPLIES (AND (NOT (CONSP X)) (NOT (SYMBOLP X))) (EQUAL (EVL2 X A) NIL))) (DEFTHM EVL2-CONSTRAINT-7 (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'F)) (EQUAL (EVL2 X A) ; changed f to f2 just below (F2 (EVL2 (CADR X) A))))) (DEFTHM EVL2-CONSTRAINT-8 (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'F2)) (EQUAL (EVL2 X A) (F2 (EVL2 (CADR X) A))))) (DEFTHM EVL2-CONSTRAINT-9 (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'G)) (EQUAL (EVL2 X A) (G)))) (DEFTHM EVL2-CONSTRAINT-10 (IMPLIES (AND (CONSP X) (EQUAL (CAR X) 'G2)) (EQUAL (EVL2 X A) (G2))))) (defthm f2-t (equal (f2 x) t) :hints (("Goal" :by (:functional-instance f-t (f f2) (evl evl2) (evl-list evl2-list))))) (defthm bug-implies-nil nil :hints (("Goal" :use ((:instance f2-t (x t))))) :rule-classes nil) Finally, we also require that no function has an attachment (see [defattach]) that is both ancestral in the evaluator and also ancestral in the meta or clause-processor functions. (If you don't use [47m[defattach][0m or [47m[apply$][0m --- more specifically, [warrant]s --- then you can ignore this condition.) Without this restriction, the following events prove [47mnil[0m. (in-package "ACL2") (defstub f () t) (defevaluator evl evl-list ((f))) (defun my-meta-fn (x) (if (equal x '(f)) (list 'quote (f)) x)) (defthm my-meta-fn-correct (equal (evl x a) (evl (my-meta-fn x) a)) :rule-classes ((:meta :trigger-fns (f)))) (defun constant-nil () (declare (xargs :guard t)) nil) (defattach f constant-nil) (defthm f-is-nil ; proved using my-meta-fn-correct (equal (f) nil) :rule-classes nil) (defthm contradiction nil :hints (("Goal" :use ((:functional-instance f-is-nil (f (lambda () t)))))) :rule-classes nil) Here is an example that doesn't use [47m[defattach][0m explicitly, but uses [warrant]s, which essentially have attachments so that every call of a warrant evaluates to [47mT[0m. As for the preceding example, these events succeed if we remove the restriction stated above about common ancestors of the evaluator and the meta or clause-processor function. (in-package "ACL2") (include-book "projects/apply/top" :dir :system) (defevaluator evl evl-list ((apply$ fn args))) (encapsulate () (local (defun$ f () (declare (xargs :guard t)) t)) (local (defun my-meta-fn (x) (if (and (equal x '(apply$ 'f 'nil)) (apply$-warrant-f)) *t* x))) (local (defthm my-meta-fn-correct (equal (evl x a) (evl (my-meta-fn x) a)) :rule-classes ((:meta :trigger-fns (apply$))))) (defthm unwarranted-fact-about-quote-f (equal (apply$ 'f nil) t) :rule-classes nil)) (defun$ f () nil) (defthm apply$-warrant-f-false (not (apply$-warrant-f)) :hints (("Goal" :use unwarranted-fact-about-quote-f)) :rule-classes nil) ; But apply$-warrant-f is a function with no non-trivial constraint. (defthm contradiction nil :hints (("Goal" :use (:functional-instance apply$-warrant-f-false (apply$-warrant-f (lambda () t)) (apply$-userfn (lambda (fn args) nil)) (badge-userfn (lambda (fn) '(APPLY$-BADGE 0 1 . T)))))) :rule-classes nil) To see why this restriction is sufficient, see a comment in the ACL2 source code entitled ``; Essay on Correctness of Meta Reasoning.'' One can sometimes work around this restriction; see [transparent-functions].") (evenp (numbers acl2-built-ins) "Test whether an integer is even [47m(evenp x)[0m is true if and only if the integer [47mx[0m is even. Actually, in the ACL2 logic [47m(evenp x)[0m is defined to be true when [47mx/2[0m is an integer. The [guard] for [47mevenp[0m requires its argument to be an integer. [47mEvenp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<evenp> (defun evenp (x) (declare (xargs :guard (integerp x))) (integerp (* x (/ 2))))") (evens (lists acl2-built-ins) "The even-indexed members of a list The call [47m(evens x)[0m returns the restriction of the true-list [47mx[0m to its even-indexed members (with zero-based indexing). Note that if [47mx[0m is a list [47m(k1 a1 k2 a2 ... kn an)[0m that satisfies the predicate [47m[keyword-value-listp][0m, then [47m(evens x)[0m lists the keys [47mki[0m of [47mx[0m. Thus, the following is a theorem. (thm (iff (keyword-value-listp l) (and (true-listp l) (evenp (len l)) (keyword-listp (evens l)))) :hints (("Goal" :induct (keyword-value-listp l)))) [31;1mFunction: [0m<evens> (defun evens (l) (declare (xargs :guard (true-listp l))) (cond ((endp l) nil) (t (cons (car l) (evens (cddr l))))))") (event (pointers) "See [events].") (event-data (pointers) "See [saving-event-data].") (events (acl2) "Functions that extend the logic Any extension of the syntax of ACL2 (i.e., the definition of a new constant or macro), the axioms (i.e., the definition of a function), or the rule database (i.e., the proof of a theorem), constitutes a logical ``event.'' Events change the ACL2 logical world (see [world]). Indeed, the only way to change the ACL2 [world] is via the successful evaluation of an event function. Every time the [world] is changed by an event, a landmark is left on the [world] and it is thus possible to identify the [world] ``as of'' the evaluation of a given event. An event may introduce new logical names. Some events introduce no new names (e.g., [47m[verify-guards][0m), some introduce exactly one (e.g., [47m[defmacro][0m and [47m[defthm][0m), and some may introduce many (e.g., [47m[encapsulate][0m ). ACL2 typically completes processing of an event by printing a [summary]. Unless proofs are skipped (see [ld-skip-proofsp]) or summary output is inhibited (see [set-inhibit-output-lst]), information about the proof attempt (if any) is printed that includes a list of rules used, a summary of warnings, and the number of ``prover steps'' (if any; see [with-prover-step-limit]). A breakdown of the time used is also printed, which by default is runtime (cpu time), but can be changed to realtime (wall clock time); see [get-internal-time]. See [embedded-event-form] for a discussion of events permitted in [books]. Subtopics [Add-custom-keyword-hint] Add a new custom keyword hint [Add-global-stobj] Add a global [stobj] with a given name [Assert-event] Assert that a given form returns a non-[47mnil[0m value [Comp] Compile some ACL2 functions [Defabbrev] A convenient form of macro definition for simple expansions [Defabsstobj] Define a new abstract single-threaded object [Defabsstobj-missing-events] Obtain the [events] needed to admit a [47m[defabsstobj][0m event [Defattach] Execute constrained functions using corresponding attached functions [Defaxiom] Add an axiom [Defchoose] Define a Skolem (witnessing) function [Defcong] Prove [congruence] rule [Defconst] Define a constant [Defequiv] Prove that a function is an [equivalence] relation [Defevaluator] Introduce an evaluator function [Defexec] Attach a terminating executable function to a definition [Define-trusted-clause-processor] Define a trusted (unverified) goal-level simplifier [Deflabel] Build a landmark [Defmacro] Define a macro [Defmacro-last] Define a macro that returns its last argument, but with side effects [Defmacro-untouchable] Define an ``untouchable'' macro [Defn] Definition with [guard] [47mt[0m [Defnd] [disable]d definition with [guard] [47mt[0m [Defpkg] Define a new symbol package [Defproxy] Define a non-executable [47m:[0m[47m[program][0m-mode function for attachment [Defrec] Introduce a record structure, like a [47mstruct[0m in C. [Defrefinement] Prove that [47mequiv1[0m refines [47mequiv2[0m [Defstobj] Define a new single-threaded object [Defstub] Stub-out a function symbol [Deftheory] Define a theory (to [enable] or [disable] a set of rules) [Deftheory-static] Define a `static' theory (to [enable] or [disable] a set of rules) [Defthm] Prove and name a theorem [Defthmd] Prove and name a theorem and then disable it [Defthy] Define a theory (to [enable] or [disable] a set of rules) [Defttag] Introduce a trust tag (ttag) [Defun] Define a function symbol [Defun$] Define a function symbol and generate a warrant [Defun-inline] Define a potentially inlined function symbol and associated macro [Defun-notinline] Define a not-to-be-inlined function symbol and associated macro [Defun-nx] Define a non-executable function symbol [Defun-sk] Define a function whose body has an outermost quantifier [Defund] Define a function symbol and then disable it [Defund-inline] Define a potentially disabled, inlined function symbol and associated macro [Defund-notinline] Define a disabled, not-to-be-inlined function symbol and associated macro [Defund-nx] Define a disabled non-executable function symbol [Embedded-event-form] Forms that may be embedded in other [events] [Encapsulate] Hide some [events] and/or constrain some functions [Evisc-table] Support for abbreviated output [In-arithmetic-theory] Designate theory for some rewriting done for non-linear arithmetic [In-theory] Designate ``current'' theory (enabling its rules) [Include-book] Load the [events] in a file [Local] Hiding an event in an encapsulation or book [Logical-name] A name created by a logical event [Make-event] Evaluate (expand) a given form and then evaluate the result [Memoize] Turn on memoization for a specified function [Mutual-recursion] Define some mutually recursive functions [Name] Syntactic rules on logical names [Partial-encapsulate] Introduce functions with some constraints unspecified [Profile] Turn on profiling for one function [Progn] Evaluate some [events] [Progn!] Evaluate some forms, not necessarily [events] [Project-dir-alist] Support for moving project directories (also [47m:dir[0m arguments) [Redundant-events] Allowing a name to be introduced ``twice'' [Regenerate-tau-database] Regenerate the tau database relative to the current enabled theory [Remove-custom-keyword-hint] Remove a custom keyword hint [Remove-global-stobj] Remove a global [stobj] with a given name [Set-body] Set the definition body [Set-table-guard] Set the [47m:guard[0m for a [table] [Skip-proofs] Skip proofs for a given form --- a quick way to introduce unsoundness [Table] User-managed tables [Theory-invariant] User-specified invariants on [theories] [Unmemoize] Turn off memoization for the specified function [Value-triple] Compute a value, optionally checking that it is not [47mnil[0m [Verify-guards] Verify the [guard]s of a function [Verify-guards+] Verify the [guard]s of a function [Verify-termination] Convert a function from :program mode to :logic mode") (evisc-table (events) "Support for abbreviated output The [47mevisc-table[0m is an ACL2 table (see [table]) whose purpose is to modify the print representations of specified non-[47mnil[0m objects. When a key (some object) is associated with a string value, then that string is printed instead of that key (as an abbreviation). For example, the following log shows how to abbreviate the key [47m(a b c)[0m with the token [47m<my-abc-list>[0m. ACL2 !>(table evisc-table '(a b c) "<my-abc-list>") Summary Form: ( TABLE EVISC-TABLE ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) EVISC-TABLE ACL2 !>'(a b c) <my-abc-list> ACL2 !>'(4 5 a b c) (4 5 . <my-abc-list>) ACL2 !> Every value in this [table] must be either a string or [47mnil[0m, where [47mnil[0m eliminates any association of the key with an abbreviation. Continuing with the log above: ACL2 !>(table evisc-table '(a b c) nil) Summary Form: ( TABLE EVISC-TABLE ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) EVISC-TABLE ACL2 !>'(a b c) (A B C) ACL2 !>'(4 5 a b c) (4 5 A B C) ACL2 !> It can be particularly helpful to use this table to abbreviate a constant introduced by [47m[defconst][0m by prefixing the constant name with [47m"#."[0m, as we now describe. Consider first the following example. (defconst *abc* '(1 2 3 4 5 6 7 8)) (table evisc-table *abc* (concatenate 'string "#." (symbol-name '*abc*))) Then the constant [47m*abc*[0m is printed as follows --- very helpful if its associated structure is significantly larger than the 8-element list of numbers shown above! ACL2 !>*abc* #.*ABC* ACL2 !> What's more, the ACL2 reader will replace [47m#.*C*[0m, where [47m*C*[0m is defined by [47m[defconst][0m, by its value, regardless of [47mevisc-table[0m; see [sharp-dot-reader]. Continuing with the example above, we have: ACL2 !>(cdr (quote #.*ABC*)) (2 3 4 5 6 7 8) ACL2 !> Of course, more care needs to be taken if packages are involved (see [defpkg]), as we now illustrate. ACL2 !>(defpkg "FOO" nil) Summary Form: ( DEFPKG "FOO" ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) "FOO" ACL2 !>(defconst foo::*a* '(1 2 3)) Summary Form: ( DEFCONST FOO::*A* ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO::*A* ACL2 !>(table evisc-table foo::*a* "#.foo::*a*") Summary Form: ( TABLE EVISC-TABLE ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) EVISC-TABLE ACL2 !>foo::*a* #.foo::*a* ACL2 !>'#.foo::*a* #.foo::*a* ACL2 !>(cdr '#.foo::*a*) (2 3) ACL2 !> We conclude by an example showing some extra care that may be important to consider taking. We start with: (defconst |*BaR*| '(3 4)) Then the following works just fine; but try it without the extra code for the [47mmay-need-slashes[0m case and you'll see that the sharp-dot printing is missing. First: (table evisc-table |*BaR*| (let ((x (symbol-name '|*BaR*|))) (if (may-need-slashes x) (concatenate 'string "#.|" x "|") (concatenate 'string "#." x)))) Then: ACL2 !>|*BaR*| #.|*BaR*| ACL2 !> The examples above illustrate how the [47mevisc-table[0m is used when printing evaluation results. More generally, that [table] is used when [47m[fmt][0m (or a related function such as [47m[fms][0m) prints an object using [47m~x[0m [47m~X[0m, [47m~y[0m, [47m~Y[0m, [47m~f[0m, or [47m~F[0m.") (evisc-tuple (io) "Control suppression of details when printing ACL2 output is generally printed in full. However, ACL2 can be directed to abbreviate, or ``eviscerate'', objects before printing them. To ``eviscerate'' an object we replace certain substructures within it by strings that are printed in their stead. Such replacement is made relative to a so-called ``evisc-tuple'', which has four components: [47m(evisc-tuple print-level print-length alist hiding-cars)[0m is the same as the value of [47m(list alist print-level print-length hiding-cars)[0m, and the components are used as follows (with priority order as discussed below). The [47malist[0m component is used to replace any substructure occurring as a key by the corresponding string. The [47mprint-level[0m and [47mprint-length[0m are analogous to Common Lisp variables [47m*print-level*[0m and [47m*print-length*[0m, respectively, and cause replacement of substructures deeper than [47mprint-level[0m by `[47m#[0m' and those longer than [47mprint-length[0m by `[47m...[0m'. Finally, any [47m[consp][0m [47mx[0m that starts with one of the symbols in [47mhiding-cars[0m is printed as [47m<hidden>[0m. The following example illustrates the use of an evisc-tuple that limits the print-level to 3 --- only three descents into list structures are permitted before replacing a subexpression by `[47m#[0m' --- and limits the print-length to 4 --- only the first four elements of any list structure will be printed before replacing its tail by `[47m...[0m'. ACL2 !>(fms "~x0~%" (list (cons #\0 '((a b ((c d)) e f g) u v w x y))) *standard-co* state (evisc-tuple 3 4 nil nil)) ((A B (#) E ...) U V W ...) <state> ACL2 !> Notice that it is impossible to read the printed value back into ACL2, since there is no way for the ACL2 reader to interpret `[47m#[0m' or `[47m...[0m'. To solve this problem, see [set-iprint]. In the above example we pass an evisc-tuple explicitly to a printing function, in this case, [47m[fms][0m (see [fmt]). But ACL2 also does its own printing, for example during a proof attempt. There are global evisc-tuples that control ACL2's printing; see [set-evisc-tuple] and see [without-evisc]. Subtopics [Brr-evisc-tuple] Determines partial suppression of output from [brr-commands]") (eviscerate-hide-terms (io) "To print [47m(hide ...)[0m as [47m<hidden>[0m Example: (assign eviscerate-hide-terms t) (assign eviscerate-hide-terms nil) [47mEviscerate-hide-terms[0m is a [47m[state][0m global variable whose value is either [47mt[0m or [47mnil[0m. The variable affects how terms are displayed by default (but not if you have set the term-evisc-tuple to other than its default; see [set-evisc-tuple]). If [47mt[0m, terms of the form [47m(hide ...)[0m are printed as [47m<hidden>[0m. Otherwise, they are printed normally.") (example-induction-scheme-binary-trees (introduction-to-the-theorem-prover) "Induction on binary trees See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mClassical Induction on Binary Trees[0m: To prove [47m(p x)[0m, for all [47mx[0m, by classical induction on binary tree structures, prove each of the following: [3mBase Case[0m: (implies (atom x) (p x)) [3mInduction Step[0m: (implies (and (not (atom x)) (p (car x)) (p (cdr x))) (p x)) An argument analogous to that given in [example-induction-scheme-on-lists] should convince you that [47m(p x)[0m holds for every object. A function that suggests this induction is: (defun flatten (x) (if (atom x) (list x) (app (flatten (car x)) (flatten (cdr x))))).") (example-induction-scheme-down-by-2 (introduction-to-the-theorem-prover) "Induction downwards 2 steps at a time See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mClassical Induction on Natural Numbers Preserving Parity[0m: Here is another way to decompose natural numbers. To prove [47m(p n)[0m, for all [47mn[0m, prove each of the following: [3mBase Case 1[0m: (implies (zp n) (p n)) [3mBase Case 2[0m: (implies (equal n 1) (p n)) [3mInduction Step[0m: (implies (and (not (zp n)) (not (equal n 1)) (p (- n 2))) (p n)) Base Case 1 establishes that [47mp[0m holds for [47m0[0m (and all objects other than positive naturals). Base Case 2 establishes that [47mp[0m holds for [47m1[0m. The Induction Step establishes that if [47mn[0m is a natural number greater than [47m1[0m, and if [47mp[0m holds for [47mn[0m-2, then [47mp[0m holds for [47mn[0m. Note that we have thus proved that [47m(p n)[0m holds, for all [47mn[0m. For example, [47m(p -7)[0m, [47m(p 'abc)[0m, and [47m(p 0)[0m are all established by Base Case 1. [47m(p 1)[0m is established by Base Case 2. [47m(p 2)[0m is established from [47m(p 0)[0m and the Induction Step. Think about it! [47m(p 3)[0m is established form [47m(p 1)[0m and the Induction Step, etc. A function that suggests this induction is: (defun parity (n) (if (zp n) 'even (if (equal n 1) 'odd (parity (- n 2))))).") (example-induction-scheme-nat-recursion (introduction-to-the-theorem-prover) "Induction on natural numbers See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mClassical Induction on Natural Numbers[0m: Induction is familiar in the arithmetic setting. To prove [47m(p n)[0m, for all [47mn[0m, by classical induction on the construction of the natural numbers, prove each of the following: [3mBase Case[0m: (implies (zp n) (p n)) [3mInduction Step[0m: (implies (and (not (zp n)) (p (- n 1))) (p n)) The Base Case establishes that [47mp[0m holds for [47m0[0m. In fact, because of the definition of [47m[zp][0m {ICON} (see [A_Tiny_Warning_Sign]), it establishes that [47m(p n)[0m holds when [47mn[0m is [47m0[0m and it holds when [47mn[0m is not a natural number. The Induction Step establishes that if [47mn[0m is a natural number other than [47m0[0m, and if [47mp[0m holds for [47mn[0m-1, then [47mp[0m holds for [47mn[0m. The hypothesis [47m(p (- n 1))[0m above is called the [3minduction hypothesis[0m. A function that suggests this induction is (defun nat-recursion (n) (if (zp n) n (nat-recursion (- n 1)))) Similarly, the term [47m(fact n)[0m suggests this induction if [47mfact[0m is defined: (defun fact (k) (if (zp k) 1 (* k (fact (- k 1))))). even though the formal parameter of this definition of [47mfact[0m is [47mk[0m, not [47mn[0m.") (example-induction-scheme-on-lists (introduction-to-the-theorem-prover) "Induction on lists See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mClassical Induction on Lists[0m: To prove [47m(p x)[0m, for all [47mx[0m, by classical induction on the linear list structure, prove each of the following: [3mBase Case[0m: (implies (endp x) (p x)) [3mInduction Step[0m: (implies (and (not (endp x)) (p (cdr x))) (p x)) An argument analogous to that given for natural numbers, [example-induction-scheme-nat-recursion], establishes [47m(p x)[0m for every [47mx[0m. For example, [47m(p -7)[0m, [47m(p 'abc)[0m, and [47m(p nil)[0m are all established by the Base Case. [47m(p '(Friday))[0m follows from [47m(p nil)[0m, given the Induction Step. That sentence bears thinking about! Think about it! Similarly, [47m(p '(Yellow))[0m holds for the same reason. [47m(p '(Thursday Friday))[0m follows from [47m(p '(Friday))[0m and the Induction Step, etc. A function that suggests this induction is (defun app (x y) (if (endp x) y (cons (car x) (app (cdr x) y)))).") (example-induction-scheme-on-several-variables (introduction-to-the-theorem-prover) "Induction on several variables See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mInduction on Several Variables[0m To [47m(p n x)[0m for all [47mn[0m and all [47mx[0m, prove each of the following: [3mBase Case 1[0m: (implies (endp x) (p n x)) [3mBase Case 2[0m: (implies (and (not (endp x)) (zp n)) (p n x)) [3mInduction Step[0m: (implies (and (not (endp x)) (not (zp n)) (p (- n 1) (cdr x))) (p n x)) A function that suggests this induction is (defun nth (n x) (if (endp x) nil (if (zp n) (car x) (nth (- n 1) (cdr x))))).") (example-induction-scheme-upwards (introduction-to-the-theorem-prover) "Induction upwards See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mInduction Upwards[0m: To [47m(p i max)[0m for all [47mi[0m and all [47mmax[0m, prove each of the following: [3mBase Case[0m: (implies (not (and (natp i) (natp max) (< i max))) (p i max)) [3mInduction Step[0m: (implies (and (natp i) (natp max) (< i max) (p (+ i 1) max)) (p i max)) Note that the induction hypothesis is about an [47mi[0m that is [3mbigger[0m than the [47mi[0m in in the conclusion. In induction, as in recursion, the sense of one thing being ``smaller'' than another is determined by an arbitrary measure of all the variables, not the magnitude or extent of some particular variable. A function that suggests this induction is shown below. ACL2 has to be told the measure, namely the difference between [47mmax[0m and [47mi[0m (coerced to a natural number to ensure that the measure is an ordinal). (defun count-up (i max) (declare (xargs :measure (nfix (- max i)))) (if (and (natp i) (natp max) (< i max)) (cons i (count-up (+ 1 i) max)) nil)).") (example-induction-scheme-with-accumulators (introduction-to-the-theorem-prover) "Induction scheme with accumulators See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. To prove [47m(p x a)[0m for all [47mx[0m and all [47ma[0m, prove each of the following: [3mBase Case[0m: (implies (endp x) (p x a)) [3mInduction Step[0m: (implies (and (not (endp x)) (p (cdr x) (cons (car x) a))) (p x a)) Note that in the induction hypothesis we assume [47mp[0m for a smaller [47mx[0m but a larger [47ma[0m. In fact, we could include as many induction hypotheses as we want and use any terms we want in the [47ma[0m position as long as the [47mx[0m position is occupied by a smaller term. A function that suggests this particular induction is shown below. (defun rev1 (x a) (if (endp x) a (rev1 (cdr x) (cons (car x) a)))). A function that suggests a similar induction in which three induction hypotheses are provided, one in which the [47ma[0m position is occupied by [47m(cons (car x) a)[0m, another in which the [47ma[0m position is occupied by some arbitrary term [47mb[0m, and a third in which the [47ma[0m position is occupied by [47ma[0m, is suggested by the term [47m(rev1-modified x a b)[0m where (defun rev1-modified (x a b) (if (endp x) (list x a b) (list (rev1-modified (cdr x) (cons (car x) a) b) (rev1-modified (cdr x) b b) (rev1-modified (cdr x) a b)))) Remember that the value of this term or function is irrelevant to the induction suggested. Because ACL2's definitional principle insists that all the formal parameters play a role in the computation (at least syntactically), it is common practice when defining functions for their induction schemes to return the [47mlist[0m of all the formals (to ensure all variables are involved) and to combine recursive calls on a given branch with [47mlist[0m (to avoid introducing additional case analysis as would happen if [47mand[0m or [47mor[0m or other propositional functions are used). If you tried to prove [47m(p x a)[0m and suggested the induct hint [47m(rev1-modified x a (fact k))[0m, as by (thm (p x a) :hints (("Goal" :induct (rev1-modified x a (fact k))))) the inductive argument would be: [3mBase Case[0m: (implies (endp x) (p x a)) [3mInductive Step[0m: (implies (and (not (endp x)) (p (cdr x) (cons (car x) a)) (p (cdr x) (fact k)) (p (cdr x) a)) (p x a))") (example-induction-scheme-with-multiple-induction-steps (introduction-to-the-theorem-prover) "Induction scheme with more than one induction step See [logic-knowledge-taken-for-granted-inductive-proof] for an explanation of what we mean by the induction [3msuggested[0m by a recursive function or a term. [31;1mSeveral Induction Steps[0m: To [47m(p x i a)[0m for all [47mx[0m, [47mi[0m, and [47ma[0m, prove each of the following: [3mBase Case 1[0m: (implies (zp i) (p x i a)) [3mInduction Step 1[0m: (implies (and (not (zp i)) (equal (parity i) 'even) (p (* x x) (floor i 2) a)) (p x i a)) [3mInduction Step 2[0m: (implies (and (not (zp i)) (not (equal (parity i) 'even)) (p x (- i 1) (* x a))) (p x i a)) A function that suggests this induction is the binary exponentiation function for natural numbers. (defun bexpt (x i a) (cond ((zp i) a) ((equal (parity i) 'even) (bexpt (* x x) (floor i 2) a)) (t (bexpt x (- i 1) (* x a) )))). In order to admit this function it is necessary to know that [47m(floor i 2)[0m is smaller than [47mi[0m in the case above. This can be proved if the community book [47m"arithmetic-5/top"[0m has been included from the ACL2 system directory, i.e., (include-book "arithmetic-5/top" :dir :system) should be executed before defining [47mbexpt[0m.") (example-inductions (introduction-to-the-theorem-prover) "Some examples of induction schemes in ACL2 Here are some pages illustrating various induction schemes suggested by recursive functions. [31;1mClassical Induction on Natural Numbers[0m: see [example-induction-scheme-nat-recursion]. [31;1mInduction Preserving Even/Odd Parity[0m or [31;1mInduction Downwards by 2[0m or [31;1mInduction with Multiple Base Cases[0m: see [example-induction-scheme-down-by-2] for an induction in which the induction hypothesis decreases the induction variable by an amount other than 1. This illustrates that the induction hypothesis can be about whatever term or terms are needed to explain how the formula recurs. The example also illustrates an induction with more than one Base Case. [31;1mClassical Induction on Lists[0m: see [example-induction-scheme-on-lists] for an induction over linear lists, in which we inductively assume the conjecture for [47m(cdr x)[0m and prove it for [47mx[0m. It doesn't matter whether the list is [47mnil[0m-terminated or not; the Base Case addresses all the possibilities. [31;1mClassical Induction on Binary (Cons) Trees[0m: see [example-induction-scheme-binary-trees] for an induction over the simplest form of binary tree. Here the Induction Step provides two hypotheses, one about the left subtree and one about the right subtree. [31;1mInduction on Several Variables[0m: see [example-induction-scheme-on-several-variables] for an induction in which several variables participate in the case analysis and induction hypotheses. [31;1mInduction Upwards[0m: see [example-induction-scheme-upwards] for an induction scheme in which the induction hypothesis is about something ``bigger than'' the induction conclusion. This illustrates that the sense in which the hypothesis is about something ``smaller'' than the conclusion is determined by a measure of all the variables, not the magnitude or extent of some single variable. [31;1mInduction with Auxiliary Variables[0m or [31;1mInduction with Accumulators[0m: see [example-induction-scheme-with-accumulators] for an induction scheme in which one variable ``gets smaller'' but another is completely arbitrary. Such schemes are common when dealing with tail-recursive functions that accumulate partial results in auxiliary variables. This example also shows how to provide several arbitrary terms in a non-inductive variable of a scheme. [31;1mInduction with Multiple Induction Steps[0m: see [example-induction-scheme-with-multiple-induction-steps] for an induction in which we make different inductive hypotheses depending on which case we're in. This example also illustrates the handling of auxiliary variables or accumulators.") (executable-counterpart (rule-classes) "A rule for computing the value of a function This topic is about a type of [rune] that controls evaluation using the executable-counterpart of a function. For discussion of executable-counterparts of functions, see [evaluation]. Example: (:executable-counterpart length) which may be abbreviated in [theory] expressions in either of the following two ways (see [rune]). (:e length) (length) Every [47m[defun][0m introduces at least two rules used by the theorem prover. Suppose [47mfn[0m is the name of a [47m[defun][0m'd function. Then [47m(:definition fn)[0m is the rune (see [rune]) naming the rule that allows the simplifier to replace calls of [47mfn[0m by its instantiated body. [47m(:executable-counterpart fn)[0m is the [rune] for the rule for how to evaluate the function on known constants. When typing [theories] it is convenient to know that [47m(fn)[0m is a runic designator that denotes [47m(:executable-counterpart fn)[0m. See [theories]. If [47m(:executable-counterpart fn)[0m is [enable]d, then when applications of [47mfn[0m to known constants are seen by the simplifier they are computed out by executing the Common Lisp code for [47mfn[0m (with the appropriate handling of [guard]s). Suppose [47mfact[0m is defined as the factorial function. If the executable-counterpart [rune] of [47mfact[0m, [47m(:executable-counterpart fact)[0m, is [enable]d when the simplifier encounters [47m(fact 12)[0m, then that term will be ``immediately'' expanded to [47m479001600[0m. Note that even if subroutines of [47mfn[0m have disabled executable-counterparts, [47mfn[0m will call their Lisp code nonetheless: once an executable-counterpart function is applied, no subsidiary enable checks are made. Such one-step expansions are sometimes counterproductive because they prevent the anticipated application of certain lemmas about the subroutines of the expanded function. Such computed expansions can be prevented by disabling the executable-counterpart [rune] of the relevant function. For example, if [47m(:executable-counterpart fact)[0m is [disable]d, [47m(fact 12)[0m will not be expanded by computation. In this situation, [47m(fact 12)[0m may be rewritten to [47m(* 12 (fact 11))[0m, using the rule named [47m(:definition fact)[0m, provided the system's heuristics permit the introduction of the term [47m(fact 11)[0m. Note that lemmas about multiplication may then be applicable (while such lemmas would be inapplicable to [47m479001600[0m). In many proofs it is desirable to [disable] the executable-counterpart [rune]s of certain functions to prevent their expansion by computation. See [executable-counterpart-theory]. Finally: What do we do about functions that are ``constrained'' rather than defined, such as the following? (See [encapsulate].) (encapsulate (((foo *) => *)) (local (defun foo (x) x))) Does [47mfoo[0m have an executable-counterpart? Yes: since the vast majority of functions have sensible executable-counterparts, it was decided that [31;1mall[0m functions, even such ``constrained'' ones, have executable-counterparts. We essentially ``trap'' when such calls are inappropriate. Thus, consider for example: (defun bar (x) (if (rationalp x) (+ x 1) (foo x))) If the term [47m(bar '3)[0m is encountered by the ACL2 rewriter during a proof, and if the [47m:executable-counterpart[0m of [47mbar[0m is [enable]d, then it will be invoked to reduce this term to [47m'4[0m. However, if the term [47m(bar 'a)[0m is encountered during a proof, then since [47m'a[0m is not a [47m[rationalp][0m and since the [47m:executable-counterpart[0m of [47mfoo[0m is only a ``trap,'' then this call of the [47m:executable-counterpart[0m of [47mbar[0m will result in a ``trap.'' In that case, the rewriter will return the term [47m(hide (bar 'a))[0m so that it never has to go through this process again. See [hide].") (executable-counterpart-theory (theories theory-functions) "[Executable-counterpart] rules as of logical name Examples: (executable-counterpart-theory :here) (executable-counterpart-theory 'lemma3) See [logical-name]. General Form: (executable-counterpart-theory logical-name) Returns the theory containing all the [47m:[0m[47m[executable-counterpart][0m [rune]s, whether [enable]d or not, that existed immediately after [47m[logical-name][0m was introduced. See the documentation for [theories], [logical-name], [executable-counterpart] and [47m[function-theory][0m. You may experience a fencepost problem in deciding which logical name to use. [47m[Deflabel][0m can always be used to mark unambiguously for future reference a particular point in the development of your theory. The order of [events] in the vicinity of an [47m[encapsulate][0m is confusing. See [encapsulate]. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (execution (pointers) "See [evaluation].") (exists (defun-sk) "Existential quantifier The symbol [47mexists[0m (in the ACL2 package) represents existential quantification in the context of a [47m[defun-sk][0m form. See [defun-sk] and see [forall]. See [quantifiers] for an example illustrating how the use of recursion, rather than explicit quantification with [47m[defun-sk][0m, may be preferable.") (exit (good-bye) "Quit entirely out of Lisp Same as [47m[good-bye][0m.") (exit-boot-strap-mode (history) "The end of pre-history [47mExit-boot-strap-mode[0m is the last step in creating the ACL2 [world] in which the user lives. It has [command] number [47m0[0m. [Command]s before it are part of the system initialization and extend all the way back to [47m:[0m[47m[min][0m. [Command]s after it are those of the user. [47mExit-boot-strap-mode[0m is a Common Lisp function but not an ACL2 function. It is called when every [47m[defconst][0m, [47m[defun][0m, etc., in our source code has been processed under ACL2 and the [world] is all but complete. [47mexit-boot-strap-mode[0m has only one job: to signal the completion of the boot-strapping.") (expand (pointers) "See [hints] for information about the keyword [47m:expand[0m.") (explain-giant-lambda-object (apply$) "print data related to a large lambda object Translate will signal an error if it encounters an ``excessively large'' [47m[lambda][0m object. These objects are so large they are difficult to comprehend when printed. So the error message directs you to this documentation topic. To see the [47mlambda[0m object that caused the error, execute (explain-giant-lambda-object) The rest of this documentation topic explains why we detect these objects and what you can do about them. When a [47m[lambda][0m object is translated we [47m[hons-copy][0m it so that it is uniquely represented. This speeds up the performance of the compiled [47mlambda[0m cache (see [47m[print-cl-cache][0m). However, if the number of conses in the [47mlambda[0m object is greater than or equal to [47m(lambda-object-count-max-val)[0m, we cause an error. If this error has been signaled in your session we recommend that you evaluate [47m(explain-giant-lambda-object)[0m, which will tell you more about the excessively large [47mlambda[0m object. The current value of [47m(lambda-object-count-max-val)[0m is 200,000. For reference, the largest function definition in the ACL2 sources (as of Version 8.6) is the [47m[mutual-recursion][0m event defining [47mrewrite[0m and its 51 mutually recursive subfunctions. The total number of conses in that clique is 14,656. There are generally two ways excessively large [47mlambda[0m objects come into existence: (1) they are generated automatically, as by macros, functions, or [47m[make-event][0m, or (2) you wrote a small [47mlambda[0m object but used a big quoted constant in it. (1) If the offending [47mlambda[0m object was built mechanically, we recommend that you redefine the generation process so that it introduces a named function. For example, suppose the [47mlambda[0m object sketched below is excessively large. (lambda (x y) (if (eq x 'FOO1) (my-foo1 y) (if (eq x 'FOO2) (my-foo2 y) ...))) Then perhaps instead of generating that object you could generate the definition (defun my-big-switch (x y) (if (eq x 'FOO1) (my-foo1 y) (if (eq x 'FOO2) (my-foo2 y) ...))) And then use the quite small [47m(lambda$ (x y) (my-big-switch x y))[0m in place of the offending [47mlambda[0m object. Of course, this is not always easy to carry out, since it would also require calling [47m[defwarrant][0m on [47mmy-big-switch[0m and providing that warrant as a hypothesis to any theorem involving the new [47mlambda[0m object. (2) If the offending [47mlambda[0m object just contains large quoted constants perhaps you can bind a variable to the large value outside of the [47mlambda[0m object and pass that variable into the [47mlambda[0m object in a new formal. For example, suppose the term [47m(regression-suite)[0m returns is a list of pairs of sample inputs and correct output for testing some software system whose binary machine code is in the constant declared below. (defconst *system* '(#x488b55f0 #x31ff #xff142570081050 #xf84995b0000 #xf645f801 #xf8573100000 #x807df019 ...)) Then we might wish to execute something like the following. ACL2 !>(loop$ for pair in (regression-suite) always (equal (sim *system* (car pair)) (cdr pair))) which simulates the [47m*system*[0m on every input in the regression suite and compares the result to the known correct answer. The formal translation of this term is (always$ '(lambda (loop$-ivar) (equal (sim '(#x488b55f0 #x31ff #xff142570081050 #xf84995b0000 #xf645f801 #xf8573100000 #x807df019 ...) (car loop$-ivar)) (cdr loop$-ivar))) (regression-suite)) Note that the constant [47m*system*[0m has been rendered as its quoted value and that it is inside of the [47mlambda[0m object. If [47m*system*[0m is a very large constant, that [47mlambda[0m object may be excessively large. But we can avoid that by writing this instead. ACL2 !>(let ((sys *system*)) (loop$ for pair in (regression-suite) always (equal (sim sys (car pair)) (cdr pair)))) which essentially translates to (let ((sys '(#x488b55f0 #x31ff #xff142570081050 #xf84995b0000 #xf645f801 #xf8573100000 #x807df019 dots))) (always$+ '(lambda (loop$-gvars loop$-ivars) (equal (sim (car loop$-gvars) (car (car loop$-ivars))) (cdr (car loop$-ivars)))) (list sys) (loop$-as (list (regression-suite))))) Note that the [47mlambda[0m object no longer contains the large constant. It now refers to a ``global'' variable whose value is that of [47m*system*[0m. The [47mlambda[0m object is quite small. For what it is worth, the largest single object in the ACL2 image (as of Version 8.6) is the value of [47m(w state)[0m, the logical world. Upon starting the system [47m(w state)[0m contains 128,784 elements, but contains multiple pointers to shared substructures (e.g., to tails of itself). The total number of conses is on the order of [47m(expt 10 655)[0m when counted naively, but the total number of distinct conses is 1,875,653. So if you build a [47mlambda[0m object containing the value of [47m(w state)[0m it will be ``excessively large.''") (explain-near-miss (debugging) "show why a rule's pattern and the :target do not match When a near miss break occurs (see [47m[monitor][0m) the user sees a message like this: (1 Breaking (:REWRITE LEMMA) on (F (G A B) A '(A B C D ...)): The pattern in this rule failed to match the target. However, this is considered a NEAR MISS under the break criteria, (:CONDITION 'T :ABSTRACTION ...), specified when this rule was monitored. The following criterion is satisfied. * The :ABSTRACTION pattern provided in your monitor, ..., matches :TARGET. It can be difficult to determine why the pattern of the rule, e.g., the [47m:lhs[0m of a [47m:rewrite[0m rule, fails to match the [47m:target[0m term, especially when large terms, large quoted constants, and [47mlambda[0m expressions are involved. Included among the [47m:[0m[47m[brr-commands][0m is the [47m:explain-near-miss[0m command which is intended to help explain. This command can only operate in a near miss break. If called in another context an error may occur. But in a near miss break, the situation is as follows. The prover has tried to apply a rule that has been monitored with a break criterion meaning ``cause an interactive break when the target term (the term to currently being rewritten) satisfies this criterion but the triggering pattern of the rule fails to match the target term.'' When inside the resulting break, the target term is given by the [47m[brr][0m command [47m:target[0m. The ``triggering pattern'' of the rule in question depends on how the rule was stored (see [47m[rule-classes][0m). The triggering pattern of a [47m:[0m[47m[rewrite][0m rule --- the most common class of rule --- is the left-hand side of the concluding equality and can be obtained from within the break by typing the [47m[brr][0m command [47m:lhs[0m. The triggering pattern for a [47m:[0m[47m[rewrite-quoted-constant][0m rule is its right-hand side, but as explained in [47m[rewrite-quoted-constant][0m, the [47mbrr[0m command [47m:lhs[0m will display it. The triggering pattern for a [47m:[0m[47m[linear][0m rule is displayed by the [47m:[0m[47mmax-term[0m [47mbrr[0m command. The question the user will typically ask in this situation is ``why doesn't the triggering pattern match the target?'' To understand the answer you have to understand how the ACL2 matching algorithm works. The matching algorithm is given two terms, [47mt1[0m and [47mt2[0m, and attempts to find a substitution [47ms[0m on the variables in [47mt1[0m such that when [47mt1[0m is instantiated with [47ms[0m the result is [47mt2[0m, i.e., [47mt1/s[0m = [47mt2[0m. Note that only the variables in the pattern, [47mt1[0m, can be instantiated by [47ms'[0m. In the case of a near miss break, no such substitution was found. The [47m:explain-near-miss[0m command reruns the matching algorithm on the triggering pattern and the target, expecting failure and collecting information about where the failure occurred. The output is intended to be self-explanatory. The message displays the pattern in question and the target term, but it also displays a version of the pattern in which the first unmatchable subterm is replaced by the expression [47m<pat>[0m. That [47m<pat>[0m is displayed in lowercase whereas the rest of the pattern and target are in uppercase. It marks where the matching broke down. The message goes on to show the mismatched subterms from the pattern and the target, the substitution that was computed to match everything up to [47m<pat>[0m and what the [47m<pat>[0m subterm of the pattern is when instantiated with that substitution. So, for example, suppose the rule's [47m:lhs[0m and the current [47m:target[0m are as shown below. Then here is what [47m:explain-near-miss[0m would print. The ACL2 match algorithm attempted to match :LHS with :TARGET by finding a substitution, s, such that :LHS/s = :TARGET. That attempt failed when trying to match the subterm of :LHS marked <pat> in :LHS' below. :LHS: (F X (G X Y) (H X)) :LHS': (F X (G <pat> Y) (H X)) :TARGET: (F A (G B A) (H A)) Below we show the substitution, s, computed prior to the failure; the subterm of :LHS we're calling <pat>; the instantiated subterm, <pat>/s; and the corresponding subterm, <tar>, of :TARGET. s: ((X A)) <pat>: X <pat>/s: A <tar>: B For the rewriter to get past this failure the match algorithm must be able to extend substitution s to s' so that <pat>/s' is equal to <tar> and our match algorithm could not find such an extension. Note that the substitution [47ms[0m binds [47mX[0m to [47mA[0m to match the first argument of the [47mF[0m-expression in the [47m:LHS[0m to the corresponding argument in the [47m:TARGET[0m. Then it tries to match [47m(G X Y)[0m with [47m(G B A)[0m. It fails on the first argument of that subterm, where [47m<pat>[0m is shown in [47m:LHS'[0m, because [47mX[0m has been bound to [47mA[0m and [47mA[0m and [47mB[0m are different. (Remember: only the variables of the pattern can be bound by the substitution.) When [47m<pat>[0m and its corresponding subterm [47m<tar>[0m are ``large'' but unequal quoted constants or [47mlambda[0m expressions, [47m:explain-near-miss[0m will call [47m[compare-objects][0m on those objects. It can be hard to spot how two large constants differ and [47mcompare-objects[0m points out the differences between two [47mcons[0m trees. [47m:Explain-near-miss[0m considers an object ``large'' if the number of conses in it is 30 or greater. The command [47m:explain-near-miss+[0m is like [47m:explain-near-miss[0m except it never eviscerates any term and runs [47mcompare-objects[0m whenever the failure is on two distinct quoted objects or [47mlambda[0m expressions regardless of their sizes. But note that [47mcompare-objects[0m is not run by either version of [47mexplain-near-miss[0m when the failure is of the most common kinds: * (a) a variable in the pattern has already been bound in the substitution (i.e., bound earlier in the matching process) to a term that is not identical to the corresponding term in the target, or * (b) a term in the pattern has a different function symbol than the corresponding term the target. So do not expect the [47mcompare-objects[0m output to appear often!") (explode-atom (characters acl2-built-ins) "Convert any [atom] into a [character-listp] that contains its printed representation, rendering numbers in your choice of print base. [47m(explode-atom x print-base)[0m prints the atom [47mx[0m as a list of characters, using some [print-base-p] to decide what base to print numbers in. Examples: (explode-atom 15 10) --> (#\1 #\5) ; 15 in decimal (explode-atom 15 16) --> (#\F) ; 15 in hex (explode-atom "foo" 10) --> (#\f #\o #\o) (explode-atom 'acl2::foo 10) --> (#\F #\O #\O) ; note: no package See also [explode-nonnegative-integer], [str::numbers], and [printing-to-strings]. [31;1mFunction: [0m<explode-atom> (defun explode-atom (x print-base) (declare (xargs :guard (and (atom x) (print-base-p print-base)))) (cond ((rationalp x) (cond ((integerp x) (cond ((< x 0) (cons #\- (explode-nonnegative-integer (- x) print-base nil))) (t (explode-nonnegative-integer x print-base nil)))) (t (append (explode-atom (numerator x) print-base) (cons #\/ (explode-nonnegative-integer (denominator x) print-base nil)))))) ((complex-rationalp x) (list* #\# #\C #\( (append (explode-atom (realpart x) print-base) (cons #\Space (append (explode-atom (imagpart x) print-base) '(#\))))))) ((characterp x) (list x)) ((stringp x) (coerce x 'list)) ((symbolp x) (coerce (symbol-name x) 'list)) (t (coerce "SOME BAD ATOM" 'list))))") (explode-nonnegative-integer (characters numbers acl2-built-ins) "The list of [characters] in the radix-r form of a number Examples: ACL2 !>(explode-nonnegative-integer 925 10 nil) (#9 #2 #5) ACL2 !>(explode-nonnegative-integer 325 16 nil) (#3 #9 #D) For a non-negative integer [47mn[0m, [47m(explode-nonnegative-integer n r nil)[0m is the list of [characters] in the radix-[47mr[0m (base-[47mr[0m) representation of [47mn[0m. The [guard] for [47mexplode-nonnegative-integer[0m requires the first argument to be a nonnegative integer and second argument to be a valid radix for ACL2 (2, 8, 10, or 16). See also [explode-atom], [str::numbers], and [printing-to-strings]. [31;1mFunction: [0m<explode-nonnegative-integer> (defun explode-nonnegative-integer (n print-base ans) (declare (xargs :guard (and (integerp n) (>= n 0) (print-base-p print-base)))) (cond ((or (zp n) (not (print-base-p print-base))) (cond ((null ans) '(#\0)) (t ans))) (t (explode-nonnegative-integer (floor n print-base) print-base (cons (digit-to-char (mod n print-base)) ans)))))") (expt (numbers acl2-built-ins) "Exponential function [47m(Expt r i)[0m is the result of raising the number [47mr[0m to the integer power [47mi[0m. The [guard] for [47m(expt r i)[0m is that [47mr[0m is a number and [47mi[0m is an integer, and furthermore, if [47mr[0m is [47m0[0m then [47mi[0m is nonnegative. When the type requirements of the [guard] aren't met, [47m(expt r i)[0m first coerces [47mr[0m to a number and [47mi[0m to an integer. [47mExpt[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that [47mr[0m can be a complex number; this is consistent with Common lisp. [31;1mFunction: [0m<expt> (defun expt (r i) (declare (xargs :guard (and (acl2-numberp r) (integerp i) (not (and (eql r 0) (< i 0)))))) (cond ((zip i) 1) ((= (fix r) 0) 0) ((> i 0) (* r (expt r (+ i -1)))) (t (* (/ r) (expt r (+ i 1))))))") (extend-pathname (io acl2-built-ins) "Extend a relative pathname to an absolute pathname [47mExtend-pathname[0m is a [47m:[0m[47m[program][0m mode function that takes a directory name as specified below and a filename (a string), and returns a corresponding pathname for the given file that is relative to the specified directory. If the filename is already an absolute pathname then the return value is that filename, unchanged. General Form: (extend-pathname dir filename state) where [47mdir[0m is either a string, representing an absolute pathname for a directory, or a keyword, representing a project directory (see [project-dir-alist]); filename is a string representing a relative or absolute pathname; and [47mstate[0m is the ACL2 [state]. The following examples illustrate the behavior of [47mextend-pathname[0m. Examples (comments added) ACL2 !>(extend-pathname "~/temp" "foo.lisp" state) ; where the user is "bubba" here and in the remaining examples "/home/bubba/temp/foo.lisp" ACL2 !>(extend-pathname "~/temp/" "foo.lisp" state) ; the final / is optional for the directory name "/home/bubba/temp/foo.lisp" ACL2 !>(extend-pathname "~/temp/" "no-such-file" state) ; name of non-existent file is still extended "/home/bubba/temp/no-such-file" ACL2 !>(extend-pathname "." "no-such-file" state) ; THIS IS NOT SUPPORTED, because the first argument is a relative pathname, ; not an absolute pathname; but in this case a reasonable answer happens to ; be provided. See the next example for how to do this properly. ; Here we assume that the current working directory is "/home/joe" "/home/joe/no-such-file" ACL2 !>(extend-pathname (canonical-pathname "." t state) "no-such-file" state) ; As above, but the first argument is first turned into an absolute pathname, ; which makes the call a supported one. "/home/joe/no-such-file" ACL2 !>(extend-pathname (cbd) "no-such-file" state) ; assumes that the connected book directory (see :DOC cbd) is "/data/santa" "/data/santa/no-such-file" ACL2 !>(extend-pathname :system "no-such-file" state) ; assumes that system books directory is "/data/acl2/books" "/data/acl2/books/no-such-file" ACL2 !>(extend-pathname "/data/acl2" "~/temp/foo.lisp" state) ; directory is ignored when filename is already absolute "/home/bubba/temp/foo.lisp" ACL2 !>(extend-pathname :system "~/temp/foo.lisp" state) ; directory is ignored when filename is already absolute "/home/bubba/temp/foo.lisp" Note that when the indicated file exists, [47mextend-pathname[0m resolves symbolic links by using [47m[canonical-pathname][0m. If you don't want symbolic links to be resolved there are simpler alternatives; for example, see [oslib::catpath].") (extend-pe-table (history) "Replace [events] displayed by [history] commands Example Form: (extend-pe-table all-natp (all-p natp)) General Form: (extend-pe-table event-name form) where [47mevent-name[0m is the name of an existing event and [47mform[0m is to be displayed by [history] commands in place of the actual event that introduced [47mevent-name[0m. We motivate and illustrate this utility with the following example. Suppose you develop a macro to define the notion that each element of a list satisfies a given predicate, as follows. (defmacro all-p (pred) (declare (xargs :guard (symbolp pred))) (let ((name (intern$ (concatenate 'string "ALL-" (symbol-name pred)) (symbol-package-name pred)))) `(defun ,name (lst) (if (atom lst) t (and (,pred lst) (,name (cdr lst))))))) So for example, after evaluating [47m(all-p natp)[0m, you see the following. ACL2 !>:pe all-natp L 2:x(ALL-P NATP) >L (DEFUN ALL-NATP (LST) (IF (ATOM LST) T (AND (NATP LST) (ALL-NATP (CDR LST))))) ACL2 !> So far so good. But suppose that instead, you introduce this event within a call of [47m[progn][0m, as follows. (progn (defun f1 (x) x) (defun f2 (x) x) (all-p natp)) Then when we ask to see the event introducing [47mall-natp[0m, we will not see any use of the macro [47mall-p[0m. ACL2 !>:pe all-natp 2:x(PROGN (DEFUN F1 # ...) (DEFUN F2 # ...) ...) >L (DEFUN ALL-NATP (LST) (IF (ATOM LST) T (AND (NATP LST) (ALL-NATP (CDR LST))))) ACL2 !> Perhaps we therefore prefer that [history] commands display the event for [47mall-natp[0m as [47m(all-p natp)[0m, rather than as the generated [47m[defun][0m event. Of course, in this simple example that might not be important; but it is easy to imagine examples where a small macro invocation generates a large, ugly primitive event that is best not viewed by any user! A solution is to associate the name [47mall-natp[0m with the form that introduced this name, as follows. (extend-pe-table all-natp (all-p natp)) After evaluating this form, we see the desired call of [47mall-natp[0m. In essence, [47m:[0m[47m[pe][0m and other [history] commands consider the defining event for [47mall-natp[0m to be [47m(all-p natp)[0m rather than the actual [47mdefun[0m form that introduced [47mall-natp[0m. ACL2 !>:pe all-natp 2 (PROGN (DEFUN F1 # ...) (DEFUN F2 # ...) ...) >L (ALL-P NATP) ACL2 !> As mentioned above, other [history] commands are sensitive to the result of evaluating a call of [47mextend-pe-table[0m. For example: ACL2 !>:pcb all-natp 2 (PROGN (DEFUN F1 # ...) (DEFUN F2 # ...) ...) L (DEFUN F1 (X) ...) L (DEFUN F2 (X) ...) L (ALL-P NATP) ACL2 !> Note that [47mextend-pe-table[0m actually associates the indicated form with the most recent event introducing the given event name. Consider the following example (output elided as shown). ACL2 !>(encapsulate () (program) (all-p alistp)) [[.. elided ..]] T ACL2 !>:pe all-alistp 4:x(ENCAPSULATE NIL ...) >P (DEFUN ALL-ALISTP (LST) (IF (ATOM LST) T (AND (ALISTP LST) (ALL-ALISTP (CDR LST))))) ACL2 !>(extend-pe-table all-alistp (all-p alistp)) Summary Form: ( TABLE PE-TABLE ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) PE-TABLE ACL2 !>:pe all-alistp 4 (ENCAPSULATE NIL ...) >P (ALL-P ALISTP) ACL2 !>(verify-termination all-alistp) [[.. elided ..]] ALL-ALISTP ACL2 !>:pe all-alistp L 6:x(VERIFY-TERMINATION ALL-ALISTP) >L (DEFUN ALL-ALISTP (LST) (IF (ATOM LST) T (AND (ALISTP LST) (ALL-ALISTP (CDR LST))))) Additional events for the logical name ALL-ALISTP: 4 (ENCAPSULATE NIL ...) >PL (ALL-P ALISTP) ACL2 !>(extend-pe-table all-alistp (:termination-verified (all-p alistp))) Summary Form: ( TABLE PE-TABLE ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) PE-TABLE ACL2 !>:pe all-alistp L 6 (VERIFY-TERMINATION ALL-ALISTP) >L (:TERMINATION-VERIFIED (ALL-P ALISTP)) Additional events for the logical name ALL-ALISTP: 4 (ENCAPSULATE NIL ...) >PL (ALL-P ALISTP) ACL2 !> Note that by using [47m:[0m[47m[pe!][0m, in place of [47m:[0m[47m[pe][0m, you can avoid using the information that was provided by [47mextend-pe-table[0m. ACL2 !>:pe! all-alistp L 6 (VERIFY-TERMINATION ALL-ALISTP) >L (DEFUN ALL-ALISTP (LST) (IF (ATOM LST) T (AND (ALISTP LST) (ALL-ALISTP (CDR LST))))) Additional events for the logical name ALL-ALISTP: 4 (ENCAPSULATE NIL ...) >PL (DEFUN ALL-ALISTP (LST) (IF (ATOM LST) T (AND (ALISTP LST) (ALL-ALISTP (CDR LST))))) ACL2 !> In the examples above we invoked [47mextend-pe-table[0m explicitly. It might have been better, however, to ``bake in'' such calls by way of the macro itself, as follows. (defmacro all-p (&whole form pred) (declare (xargs :guard (symbolp pred))) (let ((name (intern$ (concatenate 'string "ALL-" (symbol-name pred)) (symbol-package-name pred)))) `(progn (defun ,name (lst) (if (atom lst) t (and (,pred lst) (,name (cdr lst))))) (extend-pe-table ,name ,form)))) Then in a fresh session, after defining [47mall-p[0m as shown immediately above, we can obtain the following (edited) log. ACL2 !>(all-p natp) [[.. elided ..]] ACL2 !>:pe all-natp 2:x(ALL-P NATP) ACL2 !> We close with two remarks. First, note that the indicated event must have already been defined at the time [47mextend-pe-table[0m is invoked. Second --- in case an advanced user wishes to extend directly the underlying table, [47mpe-table[0m --- we mention that this table associates each key, an event name, with an association list that maps so-called absolute event numbers with events to display. So for example, we can remove all custom printing of events for the name [47mall-natp[0m as follows. (table pe-table 'all-natp nil)") (extend-world (world) "Install an extension of a given ACL2 [world] See [world] for relevant background on ACL2 property list worlds. Here we discuss how to install an extension of a user-defined world, that is, a world other than the one named [47m'current-acl2-world[0m, which is maintained by the ACL2 system. Also see [retract-world] for a similar utility that instead installs an initial segment of a named world. General Form: (extend-world name wrld) where [47mname[0m is a symbol intended to name the given ACL2 property list world, [47mworld[0m. Consider the following example. ACL2 !>(let* ((wrld0 nil) (wrld1 (putprop 'my-sym1 'my-key1 'my-val1-old wrld0)) (wrld2 (putprop 'my-sym2 'my-key2 'my-val2 wrld1)) (wrld3 (putprop 'my-sym1 'my-key1 'my-val1 wrld2))) (assign my-w (extend-world 'my-world wrld3))) ((MY-SYM1 MY-KEY1 . MY-VAL1) (MY-SYM2 MY-KEY2 . MY-VAL2) (MY-SYM1 MY-KEY1 . MY-VAL1-OLD)) ACL2 !>(getprop 'my-sym1 'my-key1 nil 'my-world (@ my-w)) MY-VAL1 ACL2 !> The first top-level form sets the value of [47m[state][0m global [47mmy-w[0m to the world obtained by extending the empty world three times, as shown. The second top-level form returns the most recent [47m'my-key1[0m property of the symbol [47m'my-sym1[0m. This second computation is efficient, because [47mextend-world[0m has [3minstalled[0m the value of [47mmy-w[0m as the world that is current for the name [47m'my-world[0m. See [world].") (extended-metafunctions (meta) "State and context sensitive metafunctions General Form of an Extended :Meta theorem: (implies (and (pseudo-termp x) ; this hyp is optional (alistp a) ; this hyp is optional (ev (hyp-fn x mfc state) a) ; this hyp is optional ; meta-extract hyps may also be included (see below) ) (equiv (ev x a) (ev (fn x mfc state) a))) where the restrictions are as described in the [documentation] for [47m[meta][0m where [47mstate[0m is literally the symbol [47mSTATE[0m, and [47mx[0m, [47ma[0m, [47mmfc[0m, and [47mstate[0m are distinct variable symbols. A [47m:meta[0m theorem of the above form installs [47mfn[0m as a metatheoretic simplifier with hypothesis function [47mhyp-fn[0m, exactly as for vanilla metafunctions. The only difference is that when the metafunctions are applied, some contextual information is passed in via the [47mmfc[0m argument and the ACL2 [47m[state][0m is made available. See [meta] for a discussion of vanilla flavored metafunctions. This documentation assumes you are familiar with the simpler situation, in particular, how to define a vanilla flavored metafunction, [47mfn[0m, and its associated hypothesis metafunction, [47mhyp-fn[0m, and how to state and prove metatheorems installing such functions. Defining extended metafunctions requires that you also be familiar with many ACL2 implementation details. This documentation is sketchy on these details; see the ACL2 source code or email the [ACL2-help] list if you need more help. To test your extended metafunctions outside of proof attempts, see [trust-mfc]. Additional hypotheses are supported, called ``meta-extract hypotheses'', that allow metafunctions to depend on the validity of certain terms extracted from the context or the logical [world]. These hypotheses provide an even more advanced form of metatheorem so we explain them elsewhere; see [meta-extract]. The metafunction context, [47mmfc[0m, is a list containing many different data structures used by various internal ACL2 functions. Generally, your extended metafunction will take [47mmfc[0m as its second formal and pass it into the functions mentioned below. However, advanced users who want other access to [47mmfc[0m may wish to see the documentation for [mfc]. The ACL2 [47mstate[0m is well-documented (see [state]). Below we present expressions below that can be useful in defining extended metafunctions. Some of these expressions involve keyword arguments, [47m:forcep[0m and [47m:ttree[0m, which are optional and in most cases are fine to omit, and which we explain after we present the useful expressions. [47m(mfc-clause mfc)[0m: returns the current goal, in clausal form. A clause is a list of ACL2 terms, implicitly denoting the disjunction of the listed terms. The [clause] returned by [47mmfc-clause[0m is the clausal form of the translation (see [trans]) of the goal or subgoal on which the rewriter is working. When a metafunction calls [47mmfc-clause[0m, the term, [47mterm-mf[0m, being rewritten by the metafunction has resulted from an attempt to rewrite some term, [47mterm-cl[0m, in this clause. These could be the same term, but that need not be the case: for example, [47mterm-mf[0m could be a term to which the rewriter has backchained while trying to rewrite [47mterm-cl[0m, or [47mterm-mf[0m could arise from the right-hand side of a rewrite rule applied to [47mterm-cl[0m. [47m(mfc-ancestors mfc)[0m: returns an alist whose keys are the negations of the backchaining hypotheses being pursued. In particular, [47m(null (mfc-ancestors mfc))[0m will be true exactly when rewriting is on part of the current goal. Exception: An element of this alist whose key is of the form [47m(:binding-hyp hyp unify-subst)[0m indicates that [47mhyp[0m has been encountered as a hypothesis of the form [47m(equal var term)[0m or [47m(equiv var (double-rewrite-term))[0m, in each case binding variable [47mvar[0m to the result of rewriting [47mterm[0m under [47munify-subst[0m. [47m(mfc-rdepth mfc)[0m: returns the remaining stack depth for calls of the rewriter (by default, [47m*default-rewrite-stack-limit*[0m at the top level; see [rewrite-stack-limit]). When this is 0, no further calls of the rewriter can be made without error. [47m(mfc-type-alist mfc)[0m: returns the type-alist governing the occurrence of the term, [47mx[0m, being rewritten by the metafunction. A type-alist is an association list, each element of which is of the form [47m(term ts . ttree)[0m. Such an element means that the term [47mterm[0m has the [type-set] [47mts[0m; see [type-alist]. The [47mttree[0m component is probably irrelevant here. All the terms in the type-alist are in translated form (see [trans]). The [47mts[0m are numbers denoting finite Boolean combinations of ACL2's primitive types (see [type-set]). The type-alist includes not only information gleaned from the conditions governing the term being rewritten but also that gleaned from forward chaining from the (negations of the) other literals in the clause returned by [47mmfc-clause[0m. [47m(mfc-unify-subst mfc)[0m: returns [47mnil[0m except when evaluating a [47m[syntaxp][0m or [47m[bind-free][0m hypothesis, in which case, returns the unifying substitution present at the start of that evaluation. [47m(mfc-world mfc)[0m: returns the ACL2 logical [47m[world][0m. [47m(mfc-ts term mfc state :forcep forcep :ttreep ttreep)[0m: returns the [47mtype-set[0m of [47mterm[0m in the current context; see [type-set]. [47m(mfc-rw term obj equiv-info mfc state)[0m: returns the result of rewriting [47mterm[0m in the current context, [47mmfc[0m, with objective [47mobj[0m and the equivalence relation described by [47mequiv-info[0m. [47mObj[0m should be [47mt[0m, [47mnil[0m, or [47m?[0m, and describes your objective: try to show that [47mterm[0m is true, false, or anything. [47mEquiv-info[0m is either [47mnil[0m, [47mt[0m, a function symbol [47mfn[0m naming a known equivalence relation, or a list of congruence rules. [47mNil[0m means return a term that is [47mequal[0m to [47mterm[0m. [47mT[0m means return a term that is propositionally equivalent (i.e., in the [47miff[0m sense) to [47mterm[0m, while [47mfn[0m means return a term [47mfn[0m-equivalent to [47mterm[0m. The final case, which is intended only for advanced users, allows the specification of generated equivalence relations, as supplied to the [47mgeneqv[0m argument of [47mrewrite[0m. Generally, if you wish to establish that [47mterm[0m is true in the current context, use the idiom (equal (mfc-rw term t t mfc state) *t*) The constant [47m*t*[0m is set to the internal form of the constant term [47mt[0m, i.e., [47m't[0m. [47m(mfc-rw+ term alist obj equiv-info mfc state)[0m: if [47malist[0m is [47mnil[0m then this is equivalent to [47m(mfc-rw term obj equiv-info mfc state)[0m. However, the former takes an argument, [47malist[0m, that binds variables to terms, and returns the result of rewriting [47mterm[0m under that [47malist[0m, where this rewriting is as described for [47mmfc-rw[0m above. The function [47mmfc-rw+[0m can be more efficient than [47mmfc-rw[0m, because the terms in the binding alist have generally already been rewritten, and it can be inefficient to rewrite them again. For example, consider a rewrite rule of the following form. (implies (and ... (syntaxp (... (mfc-rw `(bar ,x) ...) ...)) ...) (equal (... x ...) ...)) Here, [47mx[0m is bound in the conclusion to the result of rewriting some term, say, [47mtm[0m. Then the above call of [47mmfc-rw[0m will rewrite [47mtm[0m, which is probably unnecessary. So a preferable form of the rule above may be as follows, so that [47mtm[0m is not further rewritten by [47mmfc-rw+[0m. (implies (and ... (syntaxp (... (mfc-rw+ '(bar v) `((v . ,x)) ...) ...)) ...) (equal (... x ...) ...)) However, you may find that the additional rewriting done by [47mmfc-rw[0m is useful in some cases. [47m(mfc-ap term mfc state)[0m: returns [47mt[0m or [47mnil[0m according to whether linear arithmetic can determine that [47mterm[0m is false. To the cognoscenti: returns the contradiction flag produced by linearizing [47mterm[0m and adding it to the [47mlinear-pot-lst[0m. [47m(mfc-relieve-hyp hyp alist rune target bkptr mfc state)[0m: returns [47mt[0m or [47mnil[0m according to whether the indicated hypothesis term, [47mhyp[0m, can be relieved (proved) under the giving variable bindings, [47malist[0m. Note that this function returns [47mnil[0m if [47mhyp[0m has free variables (see [free-variables]). Here, [47mhyp[0m is the hypothesis of the indicated [47m[rune][0m at (one-based) position [47mbkptr[0m, and [47mtarget[0m is an instantiated term to which [47mrune[0m is being applied. Note that no indication is returned for whether any assumptions have been generated by [47m[force][0m or [47m[case-split][0m. (If you need such a feature, feel free to request it of the ACL2 implementors.) We explain the [47m:forcep[0m and [47m:ttreep[0m keyword arguments provided in some expressions, as promised above. Their defaults are [47m:same[0m and [47mnil[0m, respectively. A value of [47m:same[0m for [47m:forcep[0m means that forcing will be allowed if and only if it is allowed in the current rewriting environment; see [force]. A value of [47mt[0m or [47mnil[0m for [47m:forcep[0m overrides this default and allows or disallows forcing, respectively. By default these functions return a single value, [47mval[0m, but if [47m:ttreep[0m is [47mt[0m then they return [47m(mv val ttree)[0m, where [47mttree[0m is the tag-tree (see [ttree]) returned by the indicated operation, with an input tag-tree of [47mnil[0m). During the execution of a metafunction by the theorem prover, the expressions above compute the results specified. Typically, you should imagine that there are no axioms about the [47mmfc-[0m function symbols: treat them as uninterpreted function symbols. There is an advanced feature, meta-extract hypotheses, that can avoid this logical weakness in some cases when proving [47m:[0m[47m[meta][0m rules; see [meta-extract]. But we assume for the rest of the present [documentation] topic that you do not use meta-extract hypotheses. Thus, in the proof of the correctness of a metafunction, no information is available about the results of these functions: you should [3muse these functions for heuristic purposes only[0m. For example, your metafunction may use these functions to decide whether to perform a given transformation, but the transformation must be sound regardless of the value that your metafunction returns. We illustrate this below. It is sometimes possible to use the hypothesis metafunction, [47mhyp-fn[0m, to generate a sufficient hypothesis to justify the transformation. The generated hypothesis might have already been ``proved'' internally by your use of [47mmfc-ts[0m or [47mmfc-rw[0m, but the system will have to prove it ``officially'' by relieving it. We illustrate this below also. We conclude with a script that defines, verifies, and uses several extended metafunctions. This script is based on one provided by Robert Krug, who was instrumental in the development of this style of metafunction and whose help we gratefully acknowledge. ; Here is an example. I will define (foo i j) simply to be (+ i j). ; But I will keep its definition disabled so the theorem prover ; doesn't know that. Then I will define an extended metafunction ; that reduces (foo i (- i)) to 0 provided i has integer type and the ; expression (< 10 i) occurs as a hypothesis in the clause. ; Note that (foo i (- i)) is 0 in any case. (defun foo (i j) (+ i j)) (defevaluator eva eva-lst ((foo i j) (unary-- i) ; I won't need these two cases until the last example below, but I ; include them now. (if x y z) (integerp x))) (set-state-ok t) (defun metafn (x mfc state) (cond ((and (consp x) (equal (car x) 'foo) (equal (caddr x) (list 'unary-- (cadr x)))) ; So x is of the form (foo i (- i)). Now I want to check some other ; conditions. (cond ((and (ts-subsetp (mfc-ts (cadr x) mfc state) *ts-integer*) (member-equal `(NOT (< '10 ,(cadr x))) (mfc-clause mfc))) (quote (quote 0))) (t x))) (t x))) (defthm metafn-correct (equal (eva x a) (eva (metafn x mfc state) a)) :rule-classes ((:meta :trigger-fns (foo)))) (in-theory (disable foo)) ; The following will fail because the metafunction won't fire. ; We don't know enough about i. (thm (equal (foo i (- i)) 0)) ; Same here. (thm (implies (and (integerp i) (< 0 i)) (equal (foo i (- i)) 0))) ; But this will work. (thm (implies (and (integerp i) (< 10 i)) (equal (foo i (- i)) 0))) ; This won't, because the metafunction looks for (< 10 i) literally, ; not just something that implies it. (thm (implies (and (integerp i) (< 11 i)) (equal (foo i (- i)) 0))) ; Now I will undo the defun of metafn and repeat the exercise, but ; this time check the weaker condition that (< 10 i) is provable ; (by rewriting it) rather than explicitly present. (ubt 'metafn) (defun metafn (x mfc state) (cond ((and (consp x) (equal (car x) 'foo) (equal (caddr x) (list 'unary-- (cadr x)))) (cond ((and (ts-subsetp (mfc-ts (cadr x) mfc state) *ts-integer*) (equal (mfc-rw `(< '10 ,(cadr x)) t t mfc state) *t*)) ; The mfc-rw above rewrites (< 10 i) with objective t and iffp t. The ; objective means the theorem prover will try to establish it. The ; iffp means the theorem prover can rewrite maintaining propositional ; equivalence instead of strict equality. (quote (quote 0))) (t x))) (t x))) (defthm metafn-correct (equal (eva x a) (eva (metafn x mfc state) a)) :rule-classes ((:meta :trigger-fns (foo)))) (in-theory (disable foo)) ; Now it will prove both: (thm (implies (and (integerp i) (< 10 i)) (equal (foo i (- i)) 0))) (thm (implies (and (integerp i) (< 11 i)) (equal (foo i (- i)) 0))) ; Now I undo the defun of metafn and change the problem entirely. ; This time I will rewrite (integerp (foo i j)) to t. Note that ; this is true if i and j are integers. I can check this ; internally, but have to generate a hyp-fn to make it official. (ubt 'metafn) (defun metafn (x mfc state) (cond ((and (consp x) (equal (car x) 'integerp) (consp (cadr x)) (equal (car (cadr x)) 'foo)) ; So x is (integerp (foo i j)). Now check that i and j are ; ``probably'' integers. (cond ((and (ts-subsetp (mfc-ts (cadr (cadr x)) mfc state) *ts-integer*) (ts-subsetp (mfc-ts (caddr (cadr x)) mfc state) *ts-integer*)) *t*) (t x))) (t x))) ; To justify this transformation, I generate the appropriate hyps. (defun hyp-fn (x mfc state) (declare (ignore mfc state)) ; The hyp-fn is run only if the metafn produces an answer different ; from its input. Thus, we know at execution time that x is of the ; form (integerp (foo i j)) and we know that metafn rewrote ; (integerp i) and (integerp j) both to t. So we just produce their ; conjunction. Note that we must produce a translated term; we ; cannot use the macro AND and must quote constants! Sometimes you ; must do tests in the hyp-fn to figure out which case the metafn ; produced, but not in this example. `(if (integerp ,(cadr (cadr x))) (integerp ,(caddr (cadr x))) 'nil)) (defthm metafn-correct (implies (eva (hyp-fn x mfc state) a) (equal (eva x a) (eva (metafn x mfc state) a))) :rule-classes ((:meta :trigger-fns (integerp)))) (in-theory (disable foo)) ; This will not be proved. (thm (implies (and (rationalp x) (integerp i)) (integerp (foo i j)))) ; But this will be. (thm (implies (and (rationalp x) (integerp i) (integerp j)) (integerp (foo i j)))) Subtopics [Metafunction-context] A structure that holds data supporting extended meta reasoning [Trust-mfc] A macro that supports testing of extended metafunctions)") (extended-syntaxp (pointers) "See [syntaxp].") (external-format (pointers) "See [character-encoding].") (extra-info (guard) "Sources of measure, guard, or constraint proof obligations [47m(Extra-info x y)[0m always returns [47mt[0m by definition. See [guard-debug] and see [measure-debug] for a discussion of this function, which is useful for debugging failures from attempts to prove measure conjectures or to verify [guard]s. See [set-constraint-tracking] to see how [47mextra-info[0m can help in debugging failures to prove constraint obligations generated by [47m:functional-instance[0m [hints] (see [lemma-instance]).") (f-boundp-global (programming-with-state acl2-built-ins) "Check whether a global variable in [47m[state][0m has a value Examples: (f-boundp-global 'y state) General Form: (f-boundp-global s state) where [47ms[0m evaluates to a symbol. Note that this executes more efficiently when [47ms[0m is a constant of the form [47m'sym[0m. This value returned is [47mt[0m or [47mnil[0m according to whether a value is assigned to the given symbol in the ACL2 [state]. Also see related utilities [47m[f-get-global][0m, [47m[f-put-global][0m, and [47m[makunbound-global][0m.") (f-get-global (programming-with-state acl2-built-ins) "Get the value of a global variable in [47m[state][0m Examples: (+ (f-get-global 'y state) 1) (f-put-global 'a (aset1 'ascii-map-array (f-get-global 'a state) 66 'Upper-case-B) state) General Form: (f-get-global 'symbol state) where [47msymbol[0m is any symbol to which you have [47m[assign][0med a global value. The macro [47m[@][0m is closely related to [47mf-get-global[0m: [47m(@ var)[0m macroexpands to [47m(f-get-global 'var state)[0m. The macro [47m[f-put-global][0m makes it convenient to set the value of a symbol. The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of [47m[state][0m. Thus, you may use these globals to hang onto useful data structures even though you may undo back past where you computed and saved them.") (f-put-global (programming-with-state acl2-built-ins) "Assign to a global variable in [47m[state][0m Examples: (f-put-global 'x (expt 2 10) state) (f-put-global 'a (aset1 'ascii-map-array (@ a) 66 'Upper-case-B) state) General Form: (f-put-global (quote symbol) term state) where [47msymbol[0m is any symbol (with certain enforced exclusions to avoid overwriting ACL2 system ``globals'') and [47mterm[0m is any ACL2 term that could be evaluated at the top-level. [47mF-put-global[0m evaluates the term, stores the result as the value of the given symbol in the [47mglobal-table[0m of [47m[state][0m, and returns the new [47mstate[0m. (Note: the actual implementation of the storage of this value is much more efficient than this discussion of the logic might suggest.) The macro [47m[assign][0m is closely related to [47mf-put-global[0m: [47m(assign var val)[0m macroexpands to [47m(f-put-global 'var val state)[0m. The macros [47m[@][0m and [47m[f-get-global][0m give convenient access to the value of such globals. The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of [47m[state][0m. Thus, you may use these globals to hang onto useful data structures even though you may undo back past where you computed and saved them.") (failed-forcing (force debugging) "How to deal with a proof [failure] in a forcing round See [forcing-round] for a background discussion of the notion of forcing rounds. When a proof fails during a forcing round it means that the ``gist'' of the proof succeeded but some ``technical detail'' failed. The first question you must ask yourself is whether the [force]d goals are indeed theorems. We discuss the possibilities below. If you believe the [force]d goals are theorems, you should follow the usual methodology for ``fixing'' failed ACL2 proofs, e.g., the identification of key lemmas and their timely and proper use as rules. See [failure], see [gag-mode], and see [proof-tree]. The rules designed for the goals of forcing rounds are often just what is needed to prove the [force]d hypothesis at the time it is [force]d. Thus, you may find that when the system has been ``taught'' how to prove the goals of the forcing round no forcing round is needed. This is intended as a feature to help structure the discovery of the necessary rules. If a hint must be provided to prove a goal in a forcing round, the appropriate ``goal specifier'' (the string used to identify the goal to which the hint is to be applied) is just the text printed on the line above the formula, e.g., [47m"[1]Subgoal *1/3''"[0m. See [goal-spec]. If you solve a forcing problem by giving explicit [hints] for the goals of forcing rounds, you might consider whether you could avoid forcing the assumption in the first place by giving those [hints] in the appropriate places of the main proof. This is one reason that we print out the origins of each [force]d assumption. An argument against this style, however, is that an assumption might be [force]d in hundreds of places in the main goal and proved only once in the forcing round, so that by delaying the proof you actually save time. We now turn to the possibility that some goal in the forcing round is not a theorem. There are two possibilities to consider. The first is that the original theorem has insufficient hypotheses to ensure that all the [force]d hypotheses are in fact always true. The ``fix'' in this case is to amend the original conjecture so that it has adequate hypotheses. A more difficult situation can arise and that is when the conjecture has sufficient hypotheses but they are not present in the forcing round goal. This can be caused by what we call ``premature'' forcing. Because ACL2 rewrites from the inside out, it is possible that it will [force] hypotheses while the context is insufficient to establish them. Consider trying to prove [47m(p x (foo x))[0m. We first rewrite the formula in an empty context, i.e., assuming nothing. Thus, we rewrite [47m(foo x)[0m in an empty context. If rewriting [47m(foo x)[0m [force]s anything, that [force]d assumption will have to be proved in an empty context. This will likely be impossible. On the other hand, suppose we did not attack [47m(foo x)[0m until after we had expanded [47mp[0m. We might find that the value of its second argument, [47m(foo x)[0m, is relevant only in some cases and in those cases we might be able to establish the hypotheses [force]d by [47m(foo x)[0m. Our premature forcing is thus seen to be a consequence of our ``over eager'' rewriting. Here, just for concreteness, is an example you can try. In this example, [47m(foo x)[0m rewrites to [47mx[0m but has a [force]d hypothesis of [47m(rationalp x)[0m. [47mP[0m does a case split on that very hypothesis and uses its second argument only when [47mx[0m is known to be rational. Thus, the hypothesis for the [47m(foo x)[0m rewrite is satisfied. On the false branch of its case split, [47mp[0m simplifies to [47m(p1 x)[0m which can be proved under the assumption that [47mx[0m is not rational. (defun p1 (x) (not (rationalp x))) (defun p (x y)(if (rationalp x) (equal x y) (p1 x))) (defun foo (x) x) (defthm foo-rewrite (implies (force (rationalp x)) (equal (foo x) x))) (in-theory (disable foo)) The attempt then to do [47m(thm (p x (foo x)))[0m [force]s the unprovable goal [47m(rationalp x)[0m. Since all ``formulas'' are presented to the theorem prover as single terms with no hypotheses (e.g., since [47m[implies][0m is a function), this problem would occur routinely were it not for the fact that the theorem prover expands certain ``simple'' definitions immediately without doing anything that can cause a hypothesis to be [force]d. See [simple]. This does not solve the problem, since it is possible to hide the propositional structure arbitrarily deeply. For example, one could define [47mp[0m, above, recursively so that the test that [47mx[0m is rational and the subsequent first ``real'' use of [47my[0m occurred arbitrarily deeply. Therefore, the problem remains: what do you do if an impossible goal is [force]d and yet you know that the original conjecture was adequately protected by hypotheses? One alternative is to disable forcing entirely. See [disable-forcing]. Another is to [disable] the rule that caused the [force]. A third alternative is to prove that the negation of the main goal implies the [force]d hypothesis. For example, (defthm not-p-implies-rationalp (implies (not (p x (foo x))) (rationalp x)) :rule-classes nil) Observe that we make no rules from this formula. Instead, we merely [47m:use[0m it in the subgoal where we must establish [47m(rationalp x)[0m. (thm (p x (foo x)) :hints (("Goal" :use not-p-implies-rationalp))) When we said, above, that [47m(p x (foo x))[0m is first rewritten in an empty context we were misrepresenting the situation slightly. When we rewrite a literal we know what literal we are rewriting and we implicitly assume it false. This assumption is ``dangerous'' in that it can lead us to simplify our goal to [47mnil[0m and give up --- we have even seen people make the mistake of assuming the negation of what they wished to prove and then via a very complicated series of transformations convince themselves that the formula is false. Because of this ``tail biting'' we make very weak use of the negation of our goal. But the use we make of it is sufficient to establish the [force]d hypothesis above. A fourth alternative is to weaken your desired theorem so as to make explicit the required hypotheses, e.g., to prove (defthm rationalp-implies-main (implies (rationalp x) (p x (foo x))) :rule-classes nil) This of course is unsatisfying because it is not what you originally intended. But all is not lost. You can now prove your main theorem from this one, letting the [47m[implies][0m here provide the necessary case split. (thm (p x (foo x)) :hints (("Goal" :use rationalp-implies-main)))") (failure (debugging) "How to deal with a failure to admit an event There are many reasons why an event can fail to be admitted. Generally, an error message will explain the failure, sometimes pointing to documentation that is specific to the relevant issue. There are tools that can sometimes help: for example, to debug failures of [47m[encapsulate][0m or [47m[progn][0m events, as well as [47m[certify-book][0m failures, see [redo-flat]. However, proof failures are typically not as trivial to debug as, for example, syntactic errors (such as spelling errors in the name of a function). Fortunately, ACL2 offers a variety of techniques for dealing with proof failures, and some are discussed below. Also see relevant subtopics of the topic, [debugging]. Some frequently-used tools for proof debugging that are discussed in those subtopics include [accumulated-persistence], [break-rewrite], [with-brr-data], [cgen], and [proof-builder]. Also see [nil-goal] for ideas about how to proceed when the prover generates a goal of [47mNIL[0m. We turn now to the problem of dealing with proof failures. When ACL2 gives up it does not mean that the submitted conjecture is invalid, even if the last formula ACL2 printed in its proof attempt is manifestly false. Since ACL2 sometimes [generalize]s the goal being proved, it is possible it adopted an invalid subgoal as a legitimate (but doomed) strategy for proving a valid goal. Nevertheless, conjectures submitted to ACL2 are often invalid and the proof attempt often leads the careful reader to the realization that a hypothesis has been omitted or that some special case has been forgotten. It is good practice to ask yourself, when you see a proof attempt fail, whether the conjecture submitted is actually a theorem. If you think the conjecture is a theorem, then you must figure out from ACL2's output what you know that ACL2 doesn't about the functions in the conjecture and how to impart that knowledge to ACL2 in the form of rules. The ``key checkpoint'' information printed at the end of the [summary] provides a fine place to start. See [the-method] for a general discussion of how to prove theorems with ACL2, and see [introduction-to-the-theorem-prover] for a more detailed tutorial. Also see [set-gag-mode] for discussion of key checkpoints and an abbreviated output mode that focuses attention on them. You may find it most useful to start by focusing on key checkpoints that are not under a proof by induction, if any, both because these are more likely to suggest useful lemmas and because they are more likely to be theorems; for example, generalization may have occurred before a proof by induction has begun. If you need more information than is provided by the key checkpoints --- although this should rarely be necessary --- then you can look at the full proof, perhaps with the aid of certain utilities: see [pso], [set-gag-mode], and [proof-tree]. System hackers may want to consider using the utility, [47m[checkpoint-list][0m. Again, see [the-method] for a general discussion of how to prove theorems with ACL2, and see [introduction-to-the-theorem-prover] for a more detailed tutorial. See also the book ``Computer-Aided Reasoning: An Approach'' (Kaufmann, Manolios, Moore), as well as the discussion of how to read Nqthm proofs and how to use Nqthm rules in ``A Computational Logic Handbook'' by Boyer and Moore (Academic Press, 1988). If the failure occurred during a forcing round, see [failed-forcing]. Subtopics [Useless-runes-failures] Failures caused by [useless-runes]") (fake-rune (pointers) "See [rune].") (fancy-string-reader (reader) "A friendly syntax for strings literals that have backslashes and quotes. Examples: ACL2 !> #{"""Hello, World!"""} "Hello, World!" ACL2 !> #{"""<img src="hello.png"/>"""} "<img src=\"hello.png\"/>" ACL2 !> #{"""C:\ACL2\axioms.lisp"""} "C:\\ACL2\\axioms.lisp" String literals in ACL2 and Common Lisp source code files are usually written as text strings within quote marks. For instance, the 5-character string whose contents are [47mHello[0m is normally written as [47m"Hello"[0m. Usually this syntax is fine, but things can get tricky when you want to write a string whose contents include [47m"[0m marks. For example, if you wanted to write down a string whose contents were: <img src="hello.png"/> then you would need to escape the quote marks within it using backslash characters, e.g., as follows: "<img src=\"hello.png\"/>" But using [47m\[0m as a special character means we also need a special way to write backslashes. For instance, if we want to write a string literal whose contents are: C:\ACL2\axioms.lisp Then we would need to write something a string literal such as: "C:\\ACL2\\axioms.lisp" In certain cases, such as when writing long [documentation] strings, the extra escaping can be tedious and error-prone. To simplify this, ACL2 provides an alternate [47m#{"""..."""}[0m syntax for string literals. This syntax has no special characters, so nothing needs to be escaped. The end of the string is recognized by the unusual character sequence [47m"""}[0m. In the rare case that you need to have the sequence [47m"""}[0m in your string, you can instead use [47m"""\}[0m. If you need to have the sequence [47m"""\}[0m, you can use [47m"""\\}[0m. In general, when a substring contains three doublequotes followed by 1 or more backslashes and a right curlybrace, it just removes one of the backslashes.") (fargn (pointers) "See [system-utilities].") (fargs (pointers) "See [system-utilities].") (fast-alist (pointers) "See [fast-alists].") (fast-alist-clean (fast-alists acl2-built-ins) "[47m(fast-alist-clean alist)[0m can be used to eliminate "shadowed pairs" from a fast alist. This [documentation] topic assumes familiarity with fast alists; see [fast-alists]. See [47m[fast-alist-clean!][0m, [47m[fast-alist-fork][0m, and [47m[fast-alist-fork!][0m for related utilities. Logically, [47m(fast-alist-clean alist)[0m is defined as follows: [31;1mFunction: [0m<fast-alist-clean> (defun fast-alist-clean (alist) (declare (xargs :guard t)) (fast-alist-fork alist (if (consp alist) (cdr (last alist)) alist))) The result is thus a corresponding fast alist, with the order reversed and with atoms and shadowed pairs removed, as per the definition above; see [fast-alist-fork] for details. Moreover, if [47malist[0m is not a fast alist, then [47m(fast-alist-clean alist)[0m is executed in raw Lisp by calling [47mfast-alist-fork[0m as indicated above. However, if [47malist[0m is a fast alist, then a special definition under the hood provides a different handling of associated hash tables. After running [47m(fast-alist-clean alist)[0m to obtain a result, [47mcleaned-alist[0m, the hash table that had been associated with [47malist[0m will now be associated with [47mcleaned-alist[0m instead. This saves the expense of creating a new hash table, but there is still the expense of copying the alist, as for [47m[fast-alist-fork][0m. However, unlike [47mfast-alist-fork[0m, there is no need to free the input alist. Note that the final [47mcdr[0m is preserved, so that the name is preserved for use by [47m[fast-alist-summary][0m (also see [hons-acons]).") (fast-alist-clean! (fast-alists acl2-built-ins) "[47m(fast-alist-clean! alist)[0m is an alternative to [47m[fast-alist-clean][0m that produces a [normed] result. Logically this function is just [47mfast-alist-clean[0m; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, this is the same as [47mfast-alist-clean[0m except that it uses something like [47m[hons-acons!][0m instead of [47m[hons-acons][0m. You generally [31;1mshould not use[0m this function unless you really know what you're doing and understand the drawbacks discussed in [47m[hons-acons!][0m.") (fast-alist-discipline (pointers) "See [slow-alist-warning].") (fast-alist-fork (fast-alists acl2-built-ins) "[47m(fast-alist-fork alist ans)[0m can be used to eliminate "shadowed pairs" from an alist or to copy [fast-alists]. This [documentation] topic assumes familiarity with fast alists; see [fast-alists]. See [47m[fast-alist-fork!][0m, [47m[fast-alist-clean][0m, and [47m[fast-alist-clean!][0m for related utilities. Logically, [47m(fast-alist-fork alist ans)[0m is defined as follows: [31;1mFunction: [0m<fast-alist-fork> (defun fast-alist-fork (alist ans) (declare (xargs :guard t)) (cond ((atom alist) ans) ((atom (car alist)) (fast-alist-fork (cdr alist) ans)) ((hons-assoc-equal (car (car alist)) ans) (fast-alist-fork (cdr alist) ans)) (t (fast-alist-fork (cdr alist) (cons (car alist) ans))))) The alist argument need not be a fast alist. Typically ans is set to nil or some other atom. In this case, shrinking produces a new, fast alist which is like alist except that (1) any "malformed," atomic entries have been removed, (2) all "shadowed pairs" have been removed, and (3) incidentally, the surviving elements have been reversed. This can be useful as a way to clean up any unnecessary bindings in alist, or as a way to obtain a "deep copy" of a fast alist that can extended independently from the original while maintaining discipline. Note that fast-alist-fork is potentially expensive, for the following two reasons. * The alist is copied, dropping any shadowed pairs. This process will require a hash table lookup for each entry in the alist; and it will require creating a new alist, which uses additional memory. * Unless ans is a fast alist that is stolen (see below), a new hash table is created, which uses additional memory. This hash table is populated in time that is linear in the number of unique keys in the alist. When ans is not an atom, good discipline requires that it is a fast alist. In this case, [47mfast-alist-fork[0m steals the hash table for ans and extends it with all of the bindings in alist that are not in ans. From the perspective of [47m[hons-assoc-equal][0m, you can think of the resulting alist as being basically similar to [47m(append ans alist)[0m, but in a different order. Note that when ans is not a fast alist (e.g., ans is an atom) then such stealing does not take place. A common idiom is to replace an alist by the result of shrinking it, in which case it is best to free the input alist, for example as follows. (let ((alist (fast-alist-free-on-exit alist (fast-alist-fork alist nil)))) ...) See [fast-alist-free-on-exit] and see [fast-alist-free]. Subtopics [Hons-shrink-alist] Deprecated feature") (fast-alist-fork! (fast-alists acl2-built-ins) "[47m(fast-alist-fork! alist ans)[0m is an alternative to [47m[fast-alist-fork][0m that produces a [normed] result. Logically this function is just [47mfast-alist-fork[0m; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, this is the same as [47mfast-alist-fork[0m except that it uses something like [47m[hons-acons!][0m instead of [47m[hons-acons][0m. You generally [31;1mshould not use[0m this function unless you really know what you're doing and understand the drawbacks discussed in [47m[hons-acons!][0m. Subtopics [Hons-shrink-alist!] Deprecated feature") (fast-alist-free (fast-alists acl2-built-ins) "[47m(fast-alist-free alist)[0m throws away the hash table associated with a fast alist. Logically, this function is the identity; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mfast-alist-free[0m removes the hash table associated with this alist, if one exists. This effectively converts the alist into an ordinary alist. Also see [fast-alist-free-on-exit]. When the host Lisp is CCL or SBCL, the associated hash table may be freed up automatically by the garbage collector when the corresponding alist is no longer referenced. (To trigger garbage collection manually, see [gc$].) But for Lisp implementations other than CCL and SBCL this is not the case so, to avoid memory leaks, you should use [47mfast-alist-free[0m to free up associated hash tables that will no longer be used. You may find [47m[fast-alist-summary][0m useful in tracking down alists that were not properly freed. It is safe to call [47mfast-alist-free[0m on any argument, including fast alists that have already been freed and objects which are not alists at all. [31;1mFunction: [0m<fast-alist-free> (defun fast-alist-free (alist) (declare (xargs :guard t)) alist) Subtopics [Flush-hons-get-hash-table-link] Deprecated feature") (fast-alist-free-on-exit (fast-alists acl2-built-ins) "Free a fast alist after the completion of some form. Logically, [47m(fast-alist-free-on-exit alist form)[0m is the identity and returns [47mform[0m. Also see [fast-alist-free]. Under the hood, this essentially expands to: (prog1 form (fast-alist-free alist)) In other words, [47malist[0m is not freed immediately, but instead remains a fast alist until the form completes. This may be useful when you are writing code that uses a fast alist but has many return points. See also the macro [47mfast-alists-free-on-exit[0m defined in the community book [47m"books/centaur/misc/hons-extra.lisp"[0m, which can be used to free several alists. The community book [47m"books/centaur/misc/hons-extra.lisp"[0m extends the [b*] macro with the [47mfree-on-exit[0m pattern binder. That is, after executing [47m(include-book "centaur/misc/hons-extra.lisp" :dir :system)[0m, the form (b* (... ((free-on-exit a b c)) ...) ...) causes [47ma[0m, [47mb[0m, and [47mc[0m to be freed when the [47mb*[0m completes, but they remain fast alists until then.") (fast-alist-len (fast-alists acl2-built-ins) "[47m(fast-alist-len alist)[0m counts the number of unique keys in a fast alist. Logically this function counts how many elements would remain in the alist were we to shrink it with [47m[fast-alist-fork][0m. Good discipline requires that the alist is a fast alist. Under the hood, when the alist is a fast alist we can simply call the underlying Common Lisp function [47mhash-table-count[0m on the associated hash table, which is very fast and doesn't require us to actually shrink the alist. [31;1mFunction: [0m<fast-alist-len> (defun fast-alist-len (alist) (declare (xargs :guard t)) (len (fast-alist-fork alist nil)))") (fast-alist-summary (fast-alists acl2-built-ins) "[47m(fast-alist-summary)[0m prints some basic statistics about any current fast alists. Logically, [47mfast-alist-summary[0m just returns nil; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, this function gathers and prints some basic statistics about the current fast alists. It may be useful for identifying fast alists that should have been freed with [47m[fast-alist-free][0m. [31;1mFunction: [0m<fast-alist-summary> (defun fast-alist-summary nil (declare (xargs :guard t)) nil)") (fast-alists (alists programming hons-and-memoization) "Alists with hidden hash tables for faster execution The implementation of fast alists is, in many ways, similar to that of ACL2 arrays. Logically, [47m[hons-acons][0m is just like [47macons[0m, and [47m[hons-get][0m is similar to [47m[assoc-equal][0m. But under the hood, hash tables are associated with these alists, and, when a certain [31;1mdiscipline[0m is followed, these functions execute with hash table speeds. What is this discipline? Each [47mhons-acons[0m operation "steals" the hash table associated with the alist that is being extended. Because of this, one must be very conscious of which object is the most recent extension of an alist and use that extension exclusively. The only penalty for a failure to keep track of the most recent extension is a loss of execution speed, not of correctness, and perhaps the annoyance of some [47m[slow-alist-warning][0ms. Maintaining discipline may require careful passing of a fast alist up and down through function calls, as with any single threaded object in an applicative setting, but there is [31;1mno syntactic enforcement[0m that insists you only use the most recent extension of an alist as there is for single threaded objects ([47m[stobj][0ms). Also, even with perfectly proper code, discipline can sometimes be lost due to user interrupts and aborts. Performance Notes See [hons-acons] for how the final [47m[cdr][0m of a fast alist can be used as a size hint or as a name for reports printed by calling [47m[fast-alist-summary][0m. The keys of fast alists are always [normed]. Why? In Common Lisp, equal-based hashing is relatively slow, so to allow the use of eql-based hash tables, [47m[hons-acons][0m and [47m[hons-get][0m always [47m[hons-copy][0m the keys involved. Since alist keys are frequently atoms, this norming activity may often be so fast that you do not need to think about it. But if you are going to use large structures as the keys for your fast alist, this overhead can be significant, and you may want to ensure that your keys are normed ahead of time. There is [31;1mno automatic mechanism[0m for reclaiming the hash tables that are associated with alists. Because of this, to avoid memory leaks, you should call [47m[fast-alist-free][0m to remove the hash table associated with alists that will no longer be used. Subtopics [Cons-subtrees] Build a fast alist whose keys are the subtrees of X [Fast-alist-clean] [47m(fast-alist-clean alist)[0m can be used to eliminate "shadowed pairs" from a fast alist. [Fast-alist-clean!] [47m(fast-alist-clean! alist)[0m is an alternative to [47m[fast-alist-clean][0m that produces a [normed] result. [Fast-alist-fork] [47m(fast-alist-fork alist ans)[0m can be used to eliminate "shadowed pairs" from an alist or to copy [fast-alists]. [Fast-alist-fork!] [47m(fast-alist-fork! alist ans)[0m is an alternative to [47m[fast-alist-fork][0m that produces a [normed] result. [Fast-alist-free] [47m(fast-alist-free alist)[0m throws away the hash table associated with a fast alist. [Fast-alist-free-on-exit] Free a fast alist after the completion of some form. [Fast-alist-len] [47m(fast-alist-len alist)[0m counts the number of unique keys in a fast alist. [Fast-alist-summary] [47m(fast-alist-summary)[0m prints some basic statistics about any current fast alists. [Hons-acons] [47m(hons-acons key val alist)[0m is the main way to create or extend [fast-alists]. [Hons-acons!] [47m(hons-acons! key val alist)[0m is an alternative to [47m[hons-acons][0m that produces [normed], fast alists. [Hons-assoc-equal] [47m(hons-assoc-equal key alist)[0m is [31;1mnot fast[0m; it serves as the logical definition for [47m[hons-get][0m. [Hons-get] [47m(hons-get key alist)[0m is the efficient lookup operation for [fast-alists]. [Make-fast-alist] [47m(make-fast-alist alist)[0m creates a fast-alist from the input alist, returning [47malist[0m itself or, in some cases, a new object equal to it. [Slow-alist-warning] Warnings/errors issued when [47m[fast-alists][0m are used inefficiently [With-fast-alist] [47m(with-fast-alist name form)[0m causes [47mname[0m to be a fast alist for the execution of [47mform[0m. [With-stolen-alist] [47m(with-stolen-alist name form)[0m ensures that [47mname[0m is a fast alist at the start of the execution of [47mform[0m. At the end of execution, it ensures that [47mname[0m is a fast alist if and only if it was originally. That is, if [47mname[0m was not a fast alist originally, its hash table link is freed, and if it was a fast alist originally but its table was modified during the execution of [47mform[0m, that table is restored. Note that any extended table created from the original fast alist during [47mform[0m must be manually freed.") (fast-cert (certify-book include-book) "A mode for faster, but possibly unsound, book certification See [certify-book] and [include-book] for background on certifying and including [books]. By default, [47m[certify-book][0m includes a ``Step 3'' that does a [local-incompatibility] check. That check can be expensive for some ``industrial-size'' books if there are [local] events early in the book or in its [portcullis] commands. Fast-cert mode provides a way to avoid the [local-incompatibility] check. There are the following two drawbacks to using ACL2 with fast-cert mode enabled (as described further below). * It may be unsound! See Section ``Unsoundness'' below. * Therefore, after a book is certified with fast-cert mode enabled, then any subsequent attempt to include that book will consider it to be uncertified unless the [47m[include-book][0m event is executed with fast-cert mode enabled. See Section ``Effects of fast-cert mode...'' below. Example Forms: (set-fast-cert t state) ; enter fast-cert active mode (set-fast-cert nil state) ; disable fast-cert mode (set-fast-cert :accept state) ; enter fast-cert accept mode General Form: (set-fast-cert expr state) where if [47mexpr[0m evaluates to [47mval[0m, then: if [47mval[0m is [47mt[0m then fast-cert mode becomes (or remains) active; if [47mval[0m is [47mnil[0m, then fast-cert mode becomes (or remains) disabled; and otherwise [47mval[0m must be [47m:accept[0m. In the last case, ACL2 behaves as though fast-cert mode is disabled --- we also say ``not enabled'' for ``disabled'' --- but books can be considered certified even if they were certified with fast-cert mode enabled. We say more about these three modes in Section ``Fast-cert modes'' below. Another way to enter fast-cert mode is to set environment variable [47mACL2_FAST_CERT[0m to a non-empty value before starting ACL2. The case-insensitive value, [47m"accept"[0m, causes [47m(set-fast-cert :accept state)[0m to be evaluated at startup; otherwise, a non-empty value causes [47m(set-fast-cert t state)[0m to be evaluated at startup. We turn now to sections that include those promised above. Fast-cert modes There are the following fast-cert modes. * [31;1mActive[0m: entered with [47m(set-fast-cert t state)[0m. When ACL2 is in this mode, the [local-incompatibility] check is skipped when certifying a book, and the book's [certificate] marks it as a ``fast-cert book''. * [31;1mDisabled[0m: entered with [47m(set-fast-cert nil state)[0m, though this is the default mode. In this mode the usual [local-incompatibility] checks are performed during book certification, and every fast-cert book (as defined just above) is considered to be uncertified. * [31;1mAccept[0m: entered with [47m(set-fast-cert :accept state)[0m. When ACL2 is in this mode, [local-incompatibility] checks are performed just as when fast-cert mode is disabled, but a fast-cert book is treated as certified just like any other book. Fast-cert mode is considered to be ``enabled'' exactly when it is not disabled, that is, when fast-cert mode is active or accept. The discussion above leaves open the question of whether a book that is certified in accept mode is marked as a fast-cert book. That happens only if at least one fast-cert book has been included during the session, either before the book's certification began or during evaluation of the book's events. It is always legal to change fast-cert mode from disabled to enabled (using [47mset-fast-cert[0m). It is legal to change fast-cert mode from enabled to disabled provided there has been no attempt during the session to include a fast-cert book while fast-cert mode is enabled. Potential for unsoundness Consider the proof of [47mnil[0m constructed by the following two books. ;;; fast-cert-unsound-sub.lisp (in-package "ACL2") (local (defun f () t)) (defun g () (f)) (defthm g-is-t (equal (g) t)) ;;; fast-cert-unsound.lisp (in-package "ACL2") (defun f () nil) (include-book "fast-cert-unsound-sub") (thm nil :hints (("Goal" :use g-is-t))) Now execute the following commands to prove [47mnil[0m! (set-fast-cert t state) (certify-book "fast-cert-unsound-sub") :u (certify-book "fast-cert-unsound") To see what went wrong, consider what happens if we try this without first evaluating [47m(set-fast-cert t state)[0m. In that case, we can see that an attempt to certify [47m"fast-cert-unsound-sub"[0m fails the [local-incompatibility] check. * Step 3: That completes the admissibility check. Each form read was an embedded event form and was admissible. We now retract back to the initial world and try to include the book; see :DOC local-incompatibility. ACL2 Error [Translate] in ( DEFUN G ...): The symbol F (in package "ACL2") has neither a function nor macro definition in ACL2. Please define it. See :DOC near-misses. Note: this error occurred in the context (F). That is, the attempt in Step 3 to include [47m"fast-cert-unsound-sub.lisp"[0m fails the local-incompatibility check because the definition of [47mf[0m is [local], hence skipped, so the definition of [47mg[0m is illegal. Without the use of fast-cert mode, the local-incompatibility check would catch this problem. (Technical note: if the book is certified while fast-cert mode is active, then when we subsequently include [47m"fast-cert-unsound-sub"[0m when fast-cert mode is enabled, there is --- perhaps surprisingly --- no error. That is because the translation (see [term]) of the definition of [47mg[0m is cached in the book's [certificate].) Note that unsoundness can occur even when fast-cert is in accept mode, not just in active mode. That's because one may include a book in accept mode that was certified in a previous session while fast-cert was in active mode, and that book could prove [47mnil[0m as in the example above. In short, unsoundness can occur when fast-cert mode is enabled (i.e., fast-cert is in accept or active mode). Unsoundness when fast-cert mode is enabled is probably rare in practice. But because unsoundness is possible with fast-cert mode enabled, a ``[47mTTAG NOTE[0m'' message is printed when fast-cert mode is enabled, for example as follows when fast-cert mode transitions from disabled to active. ACL2 !>(set-fast-cert t state) TTAG NOTE: Fast-cert mode is active (see :DOC fast-cert). T ACL2 !> The message above may seem a bit misleading, since there is no actual trust tag (ttag) involved. The ``[47mTTAG NOTE[0m'' message is simply ACL2's way of conveying that there is a trust issue --- typically with the use of [47m[defttag][0m but also when entering fast-cert mode. We conclude this section by mentioning other potential sources of unsoundness when fast-cert mode is enabled. There are probably yet others, but again, it is probably rare for fast-cert mode to exhibit unsoundness. These behaviors are due to avoiding the [local-incompatibility] check during certification when fast-cert mode is active. * Hidden [47m[defpkg][0m events are not recorded in a book's [certificate] when fast-cert mode is active. See [hidden-death-package]. * Information about sub-books that is normally recorded in a [certificate], including the [book-hash] values in the [portcullis] and the [keep], is omitted by certification when fast-cert mode is active. This prevents ACL2 from noticing when sub-books are uncertified or have changed since the time of the parent book's certification. Here are some necessary checks that may be omitted when the local-incompatibility check is skipped. * A non-local [congruence] rule needs its alleged equivalence relation to be an equivalence relation non-locally. Generally this means that the supporting [47m[defequiv][0m event must be non-local. * A non-local rule of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m needs its evaluators to be evaluators non-locally. * A [47m[defattach][0m event imposes requirements on function symbols to be [guard]-verified. So if a [47mdefattach[0m event is non-local, each necessary guard verification status must hold non-locally. Because of potential unsoundness when fast-cert mode is enabled, especially as explained in the item above regarding status of books that are included in a parent book, it is strongly recommended that you eventually certify your collection of books with fast-cert mode disabled. Otherwise there is no sort of guarantee that your proofs are valid! Interactions involving fast-cert mode * When a book is successfully certified with fast-cert mode active, its [certificate] records this fact. Let's call such a certificate (or book) a ``fast-cert certificate'' (or ``fast-cert book''); otherwise it is a ``normal`` certificate (or ``normal book''). * When a book is successfully certified with fast-cert in accept mode, the book is a normal book only if no fast-cert book is included before or during certification. * When [47minclude-book[0m is performed on a book with a valid fast-cert certificate, that book is considered to be certified if fast-cert mode is enabled and otherwise is considered to be uncertified. * When [47minclude-book[0m is performed on a book with a valid normal certificate, that book is considered to be certified regardless of whether or not fast-cert mode is enabled at [47minclude-book[0m time. * When [provisional-certification] is used during [47mcertify-book[0m while fast-cert mode is active, then fast-cert is treated as being in accept mode; in particular, the local-incompatibility check) is performed in the normal way. * Normally [47mcertify-book[0m warns about functions that have not had their [guard]s verified. This message is suppressed when fast-cert mode is active, because local [47minclude-book[0m forms in the certification world can make that message very long. * When a fast-cert book is included while fast-cert mode is enabled, then the rest of that ACL2 session must have fast-cert mode enabled. This restriction guarantees that any book then certified during that session will be given a fast-mode certificate. * It is illegal to call [47mset-fast-cert[0m during [47mmake-event[0m expansion (see [make-event]). There is also an explicit check to prohibit calls of [47mset-fast-cert[0m during [47mcertify-book[0m, though that is probably unnecessary because of the [47mmake-event[0m restriction unless that restriction is subverted using a trust tag. See [fast-cert-anomalies] for some possibly surprising (and more obscure) consequences of using fast-cert mode. Fast-cert mode and [47m[save-exec][0m The motivation for adding fast-cert mode was to provide faster certification based on executables created with [47m[save-exec][0m. We illustrate with an example, which starts by [local]ly including a book that brings in many definitions and rules (it may take about a minute to include) and then saving an executable. The initial (non-local) [47minclude-book[0m forms below might not be necessary for all uses of the executable. (include-book "centaur/sv/portcullis" :dir :system) (include-book "std/util/define" :dir :system) (local (include-book "centaur/sv/top" :dir :system)) :q (save-exec "sv-top" "Locally includes centaur/sv/top") Now suppose we want to create a book that is based on a tiny part of what is provided by the book included above, as follows (comments omitted here). (in-package "SV") (define name-p (x) :parents (name) (or (stringp x) (integerp x) (eq x :self) (and (consp x) (eq (car x) :anonymous)))) (define name-fix ((x name-p)) :parents (name) :returns (xx name-p) :hooks nil (mbe :logic (if (name-p x) x '(:anonymous)) :exec x) /// (defthm name-fix-when-name-p (implies (name-p x) (equal (name-fix x) x)))) We now invoke the resulting executable, [47m./sv-top[0m. ; Start ./sv-top, then: (set-fast-cert t state) (certify-book "name" ? t :ttags :all) In this little example, the certification time has been cut in half with fast-cert mode active. In many cases the reduction may be less than that, but in large industrial examples the reduction might be much, much greater --- -- especially when the book contains time-consuming events, in particular [47minclude-book[0m events. Subtopics [Fast-cert-anomalies] Potentially surprising consequences of using [fast-cert] mode") (fast-cert-anomalies (fast-cert) "Potentially surprising consequences of using [fast-cert] mode See [fast-cert] for relevant background. This topic discusses some surprises one may encounter when using fast-cert mode. When fast-cert mode was developed in February 2023, a call of ``[47mmake[0m'' was made with ``[47mACL2_FAST_CERT=t[0m'' and target ``[47mregression-everything[0m'', to certify the [community-books] with fast-cert mode active. There were only two failures (out of thousands of books), both of which are discussed below along with their fixes. There is no plan to continue to test certification of the community books with fast-cert mode enabled, but we expect future failures to continue to be rare. Example 1 Community book [47msystem/tests/early-load-of-compiled/ttag.lisp[0m has certified regardless of whether or not fast-cert mode is used. However, when it was certified with fast-cert mode active, a later attempt to include the book failed. That failure was due to the way ACL2 handles raw-Lisp redefinition (using a trust tag), as explained in a comment in the book. To avoid this problem, the form [47m(set-fast-cert nil state)[0m is in file [47mttag.acl2[0m in the same directory. Key events in the book are as follows, in this order; the first forces a [local-incompatibility] check, and you can see comments in [47mttag.lisp[0m for why that is crucial. (local (defun loc (x) x)) (defun ttag-f (x) (declare (xargs :guard t)) x) ; An assertion is here of (equal (ttag-f 3) 3), to be evaluated during both ; certify-book and include-book, basically of the form: (make-event ...) ; asserts (equal (ttag-f 3) 3) (progn! (set-raw-mode t) (defun ttag-f (x) (cons x x))) Example 2 The second example is rather subtle. Our starting point is the following, from community book [47mrtl/rel9/support/lib2.delta1/add-new-proofs.lisp[0m. ; Matt K. addition: The following lemma, natp-lamz, is not normally necessary. ; But with fast-cert mode active, we need it for the proof of lam1_alt-is-lam1. ; See :DOC fast-cert-anomalies if you want an explanation. (local (defthm natp-lamz (natp (lamz a b e)) :rule-classes :type-prescription)) To see why this lemma is needed when certifying in fast-cert mode, let us start by re-creating the environment where the definition of [47mlamz[0m has been introduced. We assume here that the sub-books that are included were certified with fast-cert mode active. (set-fast-cert t state) ; so that sub-books are included as certified (ld "rtl/rel9/support/lib2.delta1/add-new-proofs.lisp" :dir :system ;; to speed things up: :ld-skip-proofsp t) We see that the built-in [type-prescription] rule for [47mlamz[0m says only that [47mlamz[0m returns a rational number, not necessarily a non-negative integer. ACL2 !>:pr lamz Rune: (:TYPE-PRESCRIPTION LAMZ) Enabled: T Hyps: T Term: (LAMZ A B E) Backchain-limit-lst: NIL Basic-ts: *TS-RATIONAL* Vars: NIL Corollary: (RATIONALP (LAMZ A B E)) ... If we do the same experiment when sub-books were certified with fast-cert mode disabled, the [47m:[0m[47m[pr][0m output will instead show a built-in [type-prescription] rule for [47mlamz[0m saying that [47mlamz[0m returns a non-negative integer. This discrepancy in that built-in rule explains why the additional lemma above, [47mnatp-lamz[0m, was necessary when certifying the [community-books] with fast-cert mode active. So now let us investigate why certifying books with fast-cert mode active weakens the built-in type-prescription rule for [47mlamz[0m. After running the [47mset-fast-cert[0m and [47m[ld][0m commands displayed above, we see where [47mlamz[0m is defined. ACL2 !>:pe lamz d 2 (LOCAL (INCLUDE-BOOK "../lib2/top")) [Included books, outermost to innermost: "/Users/kaufmann/acl2/acl2/books/rtl/rel9/support/lib2/top.lisp" "/Users/kaufmann/acl2/acl2/books/rtl/rel9/support/lib2/add.lisp" ] >L (DEFUN LAMZ (A B E) (LNOT (LIOR A (LNOT B (1+ E)) (1+ E)) (1+ E))) ACL2 !> But we need to work harder to find the real source of the definition of [47mlamz[0m. In [47mrtl/rel9/support/lib2/add.lisp[0m we see that the definition of [47mlamz[0m is preceded by [47m(set-enforce-redundancy t)[0m as well as [47m(local (include-book "base"))[0m. When we invoke [47m:ubt 1[0m and then [47m(include-book "base")[0m, we can evaluate [47m:pe lamz[0m to see that [47mlamz[0m is defined in [47mrtl/rel9/support/lib1/add.lisp[0m, which contains [47m(set-enforce-redundancy t)[0m and the local event, [47m(local (include-book "../support/top"))[0m. So we include [3mthat[0m book after invoking [47m:ubt 1[0m, then (again) invoke [47m:pe lamz[0m, and finally find the true source of the definition of [47mlamz[0m: [47mrtl/rel9/support/support/lextra.lisp[0m. So now consider what happens when we start ACL2 and evaluate the following commands. For now, assume that we have used ACL2 fast-cert mode disabled to certify all books being included. We use [47m:ld-skip-proofsp 'include-book[0m to simulate what happens when including the book. ; with fast-cert mode disabled (ld "rtl/rel9/support/support/lextra.lisp" :dir :system :ld-skip-proofsp 'include-book) :ubt lamz (defun lamz (a b e) (lnot (lior a (lnot b (1+ e)) (1+ e)) (1+ e))) Then [47m:pr lamz[0m shows a [47m:type-prescription[0m rule for [47mlamz[0m that this function returns a non-negative integer. That is explained in part by the following output, which mentions a rule stating that [47mlnot[0m returns a non-negative integer, which was used to compute the built-in type for [47mlamz[0m that it returns a non-negative integer. We used the :type-prescription rule LNOT-NONNEGATIVE-INTEGER-TYPE. Now repeat the same experiment but where we assume that fast-cert mode has been active for all book certification and we start with [47m(set-fast-cert t state)[0m. This time there is no such output about [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m. Aha! The culprit is the following form near the top of [47m"rtl/rel9/support/support/lextra.lisp"[0m. (local (in-theory (current-theory 'lextra0-start))) That form disables the [47m:type-prescription[0m rule [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m, which is necessary for computing a non-negative integer (i.e., [47mnatp[0m) type for the built-in [47m:type-prescription[0m rule for [47mlamz[0m. By contrast, without fast-cert mode active, the world is rolled back past local events for the local-incompatibility check, and then when events in the book are processed during the [47minclude-book[0m phase of certification, the rule [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m is available for computing the built-in type-prescription for [47mlamz[0m, which is stored in the book's [certificate]. But with fast-cert mode active, the world is not rolled back, so the built-in type-prescription for lamz remains as originally computed, where the rule [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m is disabled. Indeed, if you read the certificate file for the [47mlextra.lisp[0m book above, you'll see that the [47m:TYPE-PRESCRIPTION[0m entry for [47mlamz[0m indicates a rational type when books are certified with fast-cert mode active but a non-negative integer type when certified with fast-cert mode disabled. You can read that certificate file as follows. (read-file (concatenate 'string (system-books-dir state) "rtl/rel9/support/support/lextra.cert") state)") (fc-report (forward-chaining-reports) "To report on the forward chaining activity in the most recent proof Example: (fc-report 15) General Form: (fc-report k) where [47mk[0m is the number of some forward chaining report printed in the most recent event. See [forward-chaining-reports] for details.") (fcons-term (pointers) "See [system-utilities].") (fcons-term* (pointers) "See [system-utilities].") (fdefun-mode (pointers) "See [system-utilities].") (ffn-symb (pointers) "See [system-utilities].") (ffn-symb-p (pointers) "See [system-utilities].") (ffnnamep (pointers) "See [system-utilities].") (ffnnamep-lst (pointers) "See [system-utilities].") (fifth (nth acl2-built-ins) "Fifth member of the list See any Common Lisp documentation for details.") (file-length$ (io) "The size of a file in bytes This analogue of the Common Lisp function, [47mfile-length[0m, uses that function under the hood to compute efficiently the number of bytes [47mB[0m in the specified file if that number can be determined, returning [47m(mv B state)[0m; otherwise it returns [47m(mv nil state)[0m. The [47m[guard][0m of [47mfile-length$[0m requires that the first argument is a string; the second argument is the ACL2 [47m[state][0m. The logical definition does not actually look at the file and hence is not useful for reasoning about the number of bytes in the file. [31;1mFunction: [0m<file-length$> (defun file-length$ (file state) (declare (xargs :guard (stringp file) :stobjs state)) (declare (ignore file)) (mv-let (erp val state) (read-acl2-oracle state) (mv (and (null erp) (natp val) val) state)))") (file-reading-example (tutorial5-miscellaneous-examples) "Example of reading files in ACL2 This example illustrates the use of ACL2's [io] primitives to read the forms in a file. See [io]. This example provides a solution to the following problem. Let's say that you have a file that contains s-expressions. Suppose that you want to build a list by starting with [47mnil[0m, and updating it ``appropriately'' upon encountering each successive s-expression in the file. That is, suppose that you have written a function [47mupdate-list[0m such that [47m(update-list obj current-list)[0m returns the list obtained by ``updating'' [47mcurrent-list[0m with the next object, [47mobj[0m, encountered in the file. The top-level function for processing such a file, returning the final list, could be defined as follows. Notice that because it opens a channel to the given file, this function modifies [state] and hence must return [state]. Thus it actually returns two values: the final list and the new [state]. (defun process-file (filename state) (mv-let (channel state) (open-input-channel filename :object state) (mv-let (result state) (process-file1 nil channel state) ;see below (let ((state (close-input-channel channel state))) (mv result state))))) The function [47mprocess-file1[0m referred to above takes the currently constructed list (initially, [47mnil[0m), together with a channel to the file being read and the [state], and returns the final updated list. Notice that this function is tail recursive. This is important because many Lisp compilers will remove tail recursion, thus avoiding the potential for stack overflows when the file contains a large number of forms. (defun process-file1 (current-list channel state) (mv-let (eofp obj state) (read-object channel state) (cond (eofp (mv current-list state)) (t (process-file1 (update-list obj current-list) channel state))))) As an exercise, you might want to add [guard]s to the functions above and verify the guards (see [verify-guards]). See [args] or make a call of the form [47m(guard 'your-function nil (w state))[0m to see the guard of an existing function.") (file-write-date$ (io) "The write-date of a file as a natural number This analogue of the Common Lisp function, [47mfile-write-date[0m, uses that function under the hood to compute the write date [47mD[0m as a natural number if the write date can be determined, returning [47m(mv D state)[0m; otherwise it returns [47m(mv nil state)[0m. That number is, quoting the Common Lisp HyperSpec, the number of seconds ``measured as an offset from the beginning of the year 1900 (ignoring leap seconds)''. The [47m[guard][0m of [47mfile-write-date$[0m requires that the first argument is a string; the second argument is the ACL2 [47m[state][0m. The logical definition does not actually look at the file and hence is not useful for reasoning about the write date. This utility provides a reasonable way to determine whether a file exists, like Common Lisp's [47mprobe-file[0m, according to whether [47mD[0m is non-[47mnil[0m in when [47m(mv D state)[0m is returned. [31;1mFunction: [0m<file-write-date$> (defun file-write-date$ (file state) (declare (xargs :guard (stringp file) :stobjs state) (ignorable file)) (mv-let (erp val state) (read-acl2-oracle state) (mv (and (null erp) (posp val) val) state)))") (finalize-event-user (output-controls) "User-supplied code to complete [events], e.g., with extra [summary] output This utility is intended for system hackers, not standard ACL2 users. ACL2 prints summaries at the conclusions of processing [events] (unless summaries are inhibited; see [set-inhibit-output-lst] and also see [set-inhibited-summary-types]). You may arrange for processing to take place just after the [summary], by defining a function with argument list [47m(ctx body state)[0m that returns one value, namely [47mstate[0m. We describe [47mctx[0m and [47mbody[0m at the end below, but you may simply prefer to ignore these arguments.) Your function should normally be a [guard]-verified [47m:[0m[47m[logic][0m mode function with no guard other than that provided by the input requirement on [47m[state][0m, that is, [47m(state-p state)[0m; but later below we discuss how to avoid this requirement. You then attach (see [defattach]) your function to the function [47mfinalize-event-user[0m. The following example illustrates how this all works. (defun finalize-event-user-test (ctx body state) (declare (xargs :stobjs state) (ignore ctx body)) (cond ((and (boundp-global 'abbrev-evisc-tuple state) (open-output-channel-p *standard-co* :character state)) (pprogn (if (eq (f-get-global 'abbrev-evisc-tuple state) :DEFAULT) (princ$ "Abbrev-evisc-tuple has its default value." *standard-co* state) (princ$ "Abbrev-evisc-tuple has been modified." *standard-co* state)) (newline *standard-co* state))) (t state))) (defattach-system finalize-event-user finalize-event-user-test) After admission of the two events above, an event [summary] will conclude with extra printout, for example: Note: Abbrev-evisc-tuple has its default value. If the attachment function (above, [47mfinalize-event-user-test[0m) does not meet all the requirements stated above, then you can use the [47m:skip-checks[0m argument of [47m[defattach][0m to get around the requirement, as illustrated by the following example. (defun finalize-event-user-test2 (ctx body state) (declare (xargs :stobjs state :mode :program) (ignore ctx body)) (observation 'my-test "~|Value of term-evisc-tuple: ~x0~|" (f-get-global 'term-evisc-tuple state))) (defttag t) ; needed for :skip-checks t (defattach-system (finalize-event-user finalize-event-user-test2) :skip-checks t) So for example: ACL2 !>(set-term-evisc-tuple (evisc-tuple 2 7 nil nil) state) (:TERM) ACL2 !>(defconst *foo6* '(a b c)) Summary Form: ( DEFCONST *FOO6* ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Observation in MY-TEST: Value of term-evisc-tuple: (NIL 2 7 NIL) *FOO6* ACL2 !> Note that (as of this writing) the macro [47m[observation][0m expands to a call of a [47m:[0m[47m[program][0m-mode function. Thus, the trick shown above involving [47m:skip-checks[0m allows the use of [47m:program[0m-mode functions; for example, you can print with [47m[fmt][0m. See community book [47mbooks/misc/defattach-bang.lisp[0m for a variant of [47m[defattach][0m that uses [47m[ec-call][0m to avoid issues of [guard] verification. Also see [initialize-event-user], which discusses the handling of [state] globals by that utility as well as by [47mfinalize-event-user[0m. Finally, as promised above, we briefly describe the arguments [47mctx[0m and [47mbody[0m. These are the arguments passed to the call of macro [47mwith-ctx-summarized[0m under which [47mfinalize-event-user[0m (or [47minitialize-event-user[0m) was called. Thus, they are unevaluated expressions. For example, system function [47mdefthm-fn1[0m has a body of the following form. (with-ctx-summarized (cons 'defthm name) (let ((wrld (w state)) (ens (ens state)) ..... Thus, when [47minitialize-event-user[0m and [47mfinalize-event-user[0m are called on behalf of [47m[defthm][0m, [47mctx[0m is the s-expression (cons 'defthm name) while [47mbody[0m is the following s-expression (with most code elided). (let ((wrld (w state)) (ens (ens state)) ..... You might find it helpful to use [47m[trace$][0m to get a sense of [47mctx[0m and [47mbody[0m, for example, [47m(trace$ finalize-event-user)[0m.") (find-rules-of-rune (rune) "Find the rules named rune General Form: (find-rules-of-rune rune wrld) This function finds all the rules in [47mwrld[0m with [47m:[0m[47m[rune][0m rune. It returns a list of rules in their internal form (generally as described by the corresponding [47mdefrec[0m). Deciphering these rules is difficult since one cannot always look at a rule object and decide what kind of record it is without exploiting many system invariants (e.g., that [47m:[0m[47m[rewrite][0m runes only name rewrite-rules). At the moment this function returns [47mnil[0m if the rune in question is a [47m:[0m[47m[refinement][0m rune, because there is no object representing [47m:[0m[47m[refinement][0m rules. ([47m:[0m[47m[refinement][0m rules cause changes in the [47m'coarsenings[0m properties.) In addition, if the rune is an [47m:[0m[47m[equivalence][0m rune, then congruence rules with that rune will be returned --- because [47m:[0m[47m[equivalence][0m lemmas generate some congruence rules --- but the fact that a certain function is now known to be an equivalence relation is not represented by any rule object and so no such rule is returned. (The fact that the function is an equivalence relation is encoded entirely in its presence as a [47m'coarsening[0m of [47m[equal][0m.)") (finding-documentation (documentation) "Searching the documentation The [47m:[0m[47m[doc][0m command will display, at the terminal, [documentation] topics defined in ACL2 or in [books] that have already been included. But how can you find documentation for books that are not included in the current ACL2 session? The [xdoc] {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html} includes documentation for both the ACL2 system and the [community-books]. For more information on this manual and how to view it, see [documentation].") (first (nth acl2-built-ins) "First member of the list See any Common Lisp documentation for details.") (first-keyword (pointers) "See [system-utilities].") (first-n-ac (pointers) "See [take].") (fix (numbers acl2-built-ins) "Coerce to a number [47mFix[0m simply returns any numeric argument unchanged, returning [47m0[0m on a non-numeric argument. Also see [nfix], see [ifix], and see [rfix] for analogous functions that coerce to a natural number, an integer, and a rational number, respectively. See [the-number] for a variant of [47mfix[0m whose guard specifies a numeric argument. [47mFix[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<fix> (defun fix (x) (declare (xargs :guard t)) (if (acl2-numberp x) x 0))") (fix-pkg (pointers) "See [system-utilities].") (fix-true-list (lists acl2-built-ins) "Coerce to a true list [47mFix-true-list[0m is a macro that expands to a call of [47m[true-list-fix][0m with the same argument. [31;1mMacro: [0m<fix-true-list> (defmacro fix-true-list (x) (cons 'true-list-fix (cons x 'nil)))") (flambda-applicationp (pointers) "See [system-utilities].") (flambdap (pointers) "See [system-utilities].") (flatten-ands-in-lit (pointers) "See [system-utilities].") (flawed_induction_candidates_in_app_example (pages_written_especially_for_the_tours) "Flawed Induction Candidates in App Example Induction on [31;1ma[0m is unflawed: every occurrence of [31;1ma[0m in the conjecture (equal (app (app [31;1ma[0m b) c) (app [31;1ma[0m (app b c))) is in a position being recursively decomposed! Now look at the occurrences of [47mb[0m. The first (shown in [31;1mbold[0m below) is in a position that is held constant in the recursion of [47m(app a b)[0m. It would be ``bad'' to induct on [47mb[0m here. (equal (app (app a [31;1mb[0m) c) (app a (app b c)))") (flet (basics acl2-built-ins) "Local binding of function symbols See [macrolet] for an analogous utility for defining macros locally. Example Form: ; The following evaluates to (mv 7 10): (flet ((f (x) (+ x 3)) (g (x) (declare (type integer x)) (* x 2))) (mv (f 4) (g 5))) General Forms: (flet (def1 ... defk) body) (flet (def1 ... defk) declare-form1 .. declare-formk body) where [47mbody[0m is a term, and each [47mdefi[0m is a definition as in [47m[defun][0m but with the leading [47mdefun[0m symbol omitted. See [defun], but see [declare] for the declarations permitted directly under the [47mdefi[0m. On the other hand, regarding the [47mdeclare-formi[0m (if any are supplied): each must be of the form [47m(declare decl1 ... decln)[0m, where each [47mdecli[0m is of the form [47m(inline g1 ... gm)[0m or [47m(notinline g1 ... gm)[0m, and each [47mgi[0m is defined by some [47mdefi[0m. The innermost [47mflet[0m or [47m[macrolet][0m binding of a symbol, [47mf[0m, above a call of [47mf[0m, is the one that provides the definition of [47mf[0m for that call. Note that neither [47mflet[0m nor [47mmacrolet[0m provide recursion: that is, the definition of [47mf[0m in an [47mflet[0m or [47mmacrolet[0m binding of [47mf[0m is ignored in the body of that binding. Consider the following example. ; Give a global definition of f: (defun f (x) (+ x 3)) ; Evaluate an expression using a local binding of f: (flet ((f (x) (cons x (f (1+ x))))) (f 4)) In the above term [47m(cons x (f (1+ x)))[0m, [47mf[0m refers to the global definition of [47mf[0m above the [47mflet[0m expression. However, [47m(f 4)[0m refers to the [47mflet[0m-binding of [47mf[0m, [47m(f (x) (cons x (f x)))[0m. The result of the [47mflet[0m expression is thus obtained by evaluating [47m(f 4)[0m where [47m(f 4)[0m is [47m(cons 4 (f (1+ 4)))[0m, where the latter call of [47mf[0m refers to the global definition; thus we have [47m(cons 4 (f 5))[0m, which evaluates to [47m(4 . 8)[0m. Although [47mflet[0m behaves in ACL2 essentially as it does in Common Lisp, ACL2 imposes the following restrictions and qualifications. * Every [47m[declare][0m form for a local definition ([47mdef1[0m through [47mdefk[0m, above) must be an [47mignore[0m, [47mignorable[0m, or [47mtype[0m expression. Such [47mtype[0m declarations affect evaluation and [guard]-checking in a way that is completely analogous to such declarations that occur between the formal parameters and the body in a [47m[defun][0m form. * Each [47mdefi[0m must bind a different function symbol. * Each [47mdefi[0m must bind a symbol that is a legal name for an ACL2 function symbol. In particular, the symbol may not be in the keyword package or the main Lisp package. Moreover, the symbol may not be a built-in ACL2 function or macro. * Every variable occurring in the body of a [47mdefi[0m must be a formal parameter of that [47mdefi[0m. (This restriction is not enforced in Common Lisp.) * If the [47mflet[0m-binding [47mdefi[0m is in the body of a function [47mf[0m, then the [stobj] inputs for [47mdefi[0m are implicitly those of its inputs that are declared [stobj] inputs of [47mf[0m. * When an expression [47m(flet (... defi ...) ...)[0m occurs in the body of a [47mDO[0m [47m[loop$][0m expression, nevertheless constructs such as [47mPROGN[0m and [47mSETQ[0m that ACL2 permits in [47mDO[0m [47mloop$[0m bodies are not permitted in [47mdefi[0m (unless they occur within the scope of a [47mDO[0m [47mloop$[0m expression in that body). (This restriction is only for ACL2; for example, it may be reasonable to call [47mRETURN[0m in such situations but ACL2 does not allow that.) [47mFlet[0m bindings are evaluated in parallel. Consider the following example. (defun f (x) x) (flet ((f (x) (cons x x)) (g (x) (f x))) (g 3)) The binding of [47mg[0m refers to the global value of [47mf[0m, not the [47mflet[0m-binding of [47mf[0m. Thus, the [47mflet[0m expression evaluates to 3. Compare the [47mflet[0m expression above to the following one, which instead evaluates to [47m(3 . 3)[0m. (defun f (x) x) (flet ((f (x) (cons x x))) (flet ((g (x) (f x))) (g 3))) Under the hood, ACL2 translates [47mflet[0m bindings to [47m[lambda][0m expressions (see [term]), throwing away the [47minline[0m and [47mnotinline[0m declarations (if any). The following example illustrates this point. ACL2 !>:trans (flet ((f (x) (cons x x)) (g (x y) (+ x y))) (declare (inline f)) (f (g 3 4))) ((LAMBDA (X) (CONS X X)) ((LAMBDA (X Y) (BINARY-+ X Y)) '3 '4)) => * ACL2 !> [47mFlet[0m is part of Common Lisp. See any Common Lisp documentation for more information. We conclude by pointing out an important aspect of [47mflet[0m shared by ACL2 and Common Lisp: The binding is lexical, not dynamic. That is, the [47mflet[0m binding of a function symbol only applies to calls of that function symbol in the body of the [47mflet[0m, not other calls made in the course of evaluation. Consider the following example. Suppose we define: (defun f (x) x) (defun g (x) (f x)) (defun h (x) (flet ((f (x) (cons x x))) (g x))) Then evaluation of [47m(h 3)[0m results in [47m3[0m, not in the [47mcons[0m pair [47m(3 . 3)[0m, because the [47mflet[0m binding of [47mf[0m only applies to calls of [47mf[0m that appear in the body of that [47mflet[0m. In this case, only [47mg[0m is called in the body of that [47mflet[0m.") (floating-point (pointers) "See [df].") (floor (numbers acl2-built-ins) "Division returning an integer by truncating toward negative infinity Example Forms: ACL2 !>(floor 14 3) 4 ACL2 !>(floor -14 3) -5 ACL2 !>(floor 14 -3) -5 ACL2 !>(floor -14 -3) 4 ACL2 !>(floor -15 -3) 5 [47m(Floor i j)[0m returns the result of taking the quotient of [47mi[0m and [47mj[0m and returning the greatest integer not exceeding that quotient. For example, the quotient of [47m-14[0m by [47m3[0m is [47m-4 2/3[0m, and the largest integer not exceeding that rational number is [47m-5[0m. The [guard] for [47m(floor i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real], in ACL2(r)) numbers and [47mj[0m is non-zero. [47mFloor[0m is a Common Lisp function. See any Common Lisp documentation for more information. However, note that unlike Common Lisp, the ACL2 [47mfloor[0m function returns only a single value, that is, the quotient of the division, while the remainder is returned by [47m[mod][0m. [31;1mFunction: [0m<floor> (defun floor (i j) (declare (xargs :guard (and (real/rationalp i) (real/rationalp j) (not (eql j 0))))) (let* ((q (* i (/ j))) (n (numerator q)) (d (denominator q))) (cond ((= d 1) n) ((>= n 0) (nonnegative-integer-quotient n d)) (t (+ (- (nonnegative-integer-quotient (- n) d)) -1)))))") (flush-compress (arrays acl2-built-ins) "Flush the under-the-hood array for the given name Example Form: (flush-compress 'my-array) General Form: (flush-compress name) where [47mname[0m is a symbol. Recall that [47m(compress1 nm alist)[0m associates an under-the-hood raw Lisp one-dimensional array of name [47mnm[0m with the given association list, [47malist[0m, while [47m(compress2 nm alist)[0m is the analogous function for two-dimensional arrays; see [compress1] and see [compress2]. The only purpose of [47mflush-compress[0m, which always returns [47mnil[0m, is to remove the association of any under-the-hood array with the given name, thus eliminating slow array accesses (see [slow-array-warning]). It is not necessary if the return values of [47m[compress1][0m and [47m[compress2][0m are always used as the ``current'' copy of the named array, and thus [47mflush-compress[0m should rarely, if ever, be needed in user applications. Nevertheless, we provide the following contrived example to show how [47mflush-compress[0m can be used to good effect. Comments have been added to this log to provide explanation. ACL2 !>(assign a (compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (0 . zero) (1 . one)))) ((:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 15 :DEFAULT UNINITIALIZED :NAME DEMO) (0 . ZERO) (1 . ONE)) ACL2 !>(aref1 'demo (@ a) 0) ZERO ; As expected, the above evaluation did not cause a slow array warning. Now ; we associate a different under-the-hood array with the name 'demo. ACL2 !>(compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (0 . zero))) ((:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 15 :DEFAULT UNINITIALIZED :NAME DEMO) (0 . ZERO)) ; The following array access produces a slow array warning because (@ a) is ; no longer associated under-the-hood with the array name 'demo. ACL2 !>(aref1 'demo (@ a) 0) ********************************************************** Slow Array Access! A call of AREF1 on an array named DEMO is being executed slowly. See :DOC slow-array-warning ********************************************************** ZERO ; Now we associate under-the-hood, with array name 'demo, an alist equal to ; (@ a). ACL2 !>(compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (0 . zero) (1 . one))) ((:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 15 :DEFAULT UNINITIALIZED :NAME DEMO) (0 . ZERO) (1 . ONE)) ; The following array access is still slow, because the under-the-hood array ; is merely associated with a copy of (@ a), not with the actual object ; (@ a). ACL2 !>(aref1 'demo (@ a) 0) ********************************************************** Slow Array Access! A call of AREF1 on an array named DEMO is being executed slowly. See :DOC slow-array-warning ********************************************************** ZERO ; So we might try to fix the problem by recompressing. But this doesn't ; work. It would work, by the way, if we re-assign a: ; (assign a (compress1 'demo (@ a))). That is why we usually will not need ; flush-compress. ACL2 !>(compress1 'demo (@ a)) ((:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 15 :DEFAULT UNINITIALIZED :NAME DEMO) (0 . ZERO) (1 . ONE)) ACL2 !>(aref1 'demo (@ a) 0) ********************************************************** Slow Array Access! A call of AREF1 on an array named DEMO is being executed slowly. See :DOC slow-array-warning ********************************************************** ZERO ; Finally, we eliminate the warning by calling flush-compress before we call ; compress1. The call of flush-compress removes any under-the-hood ; association of an array with the name 'demo. Then the subsequent call of ; compress1 associates the object (@ a) with that name. (Technical point: ; compress1 always associates the indicated name with the value that it ; returns. In this case, what compress1 returns is (@ a), because (@ a) is ; already, logically speaking, a compressed array1p (starts with a :header ; and the natural number keys are ordered). ACL2 !>(flush-compress 'demo) NIL ACL2 !>(compress1 'demo (@ a)) ((:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 15 :DEFAULT UNINITIALIZED :NAME DEMO) (0 . ZERO) (1 . ONE)) ACL2 !>(aref1 'demo (@ a) 0) ZERO ACL2 !> [31;1mFunction: [0m<flush-compress> (defun flush-compress (name) (declare (xargs :guard t)) (declare (ignore name)) nil)") (flush-hons-get-hash-table-link (fast-alist-free acl2-built-ins) "Deprecated feature Deprecated. Alias for [47m[fast-alist-free][0m.") (fms (io acl2-built-ins) "[47m(fms str alist co-channel state evisc) => state[0m See [fmt] for further explanation, including documentation of the tilde-directives.") (fms! (io acl2-built-ins) "[47m(fms! str alist co-channel state evisc) => state[0m This function is nearly the same as [47m[fms][0m, but [47mfms![0m avoids inserting backslash (\) characters when forced to print past the right margin. Use [47mfms![0m if you want to be able to read the forms back in.") (fms!-to-string (pointers) "See [printing-to-strings].") (fms-to-string (pointers) "See [printing-to-strings].") (fmt (io acl2-built-ins) "Formatted printing ACL2 provides the functions [47mfmt[0m, [47m[fmt1][0m, and [47m[fms][0m as substitutes for Common Lisp's [47mformat[0m function. Also see [fmt!], see [fmt1!], and see [fms!] for versions of these functions that write forms to files in a manner that allows them to be read, by avoiding using backslash ([47m\[0m) to break long lines. There are also analogues of these functions that return a string without taking [47m[state][0m as an argument; see [printing-to-strings]. A convenient macro, [47mfmx[0m, is described below; also see [cw] and see [fmx-cw]. All three print a given string under an alist pairing character objects with values, interpreting certain ``tilde-directives'' in the string. [47mChannel[0m must be a character output channel (e.g., [47m[*standard-co*][0m). General Forms: result (fms string alist channel state evisc-tuple) ; state (fmt string alist channel state evisc-tuple) ; (mv col state) (fmt1 string alist column channel state evisc-tuple) ; (mv col state) [47m[Fms][0m and [47mfmt[0m print an initial newline to put [47mchannel[0m in column [47m0[0m; [47m[Fmt1][0m requires the current column as input. Columns are numbered from [47m0[0m. The current column is the column into which the next character will be printed. (Thus, the current column number is also the number of [characters] printed since the last newline.) The [47mcol[0m returned by [47mfmt[0m and [47m[fmt1][0m is the current column at the conclusion of the formatting. [47mEvisc-tuple[0m must be either [47mnil[0m (meaning no abbreviations are used when objects are printed) or an ``evisceration tuple''; see [evisc-tuple]. We list the tilde-directives below. The notation is explained after the chart. ~xx pretty print vx (maybe after printing a newline) ~yx pretty print vx starting in current column; end with newline ~Xxy like ~xx but use vy as the evisceration tuple ~Yxy like ~yx but use vy as the evisceration tuple ~@x if vx is a string, "str", recursively format "str" if vx is ("str" . a), recursively format "str" under a+ ~#x~[...~/...~/ ... ~/...~] cases on vx ^ ^ ... ^ if 0<=vx<=k, choose vxth alternative 0 1 ... k if vx is a list of length 1, case 0; else 1 ~*x iterator: vx must be of the form ("str0" "str1" "str2" "str3" lst . a); if lst is initially empty, format "str0" under a+; otherwise, bind #\* successively to the elements of lst and then recursively format "stri" under a+, where i=1 if there is one element left to process, i=2 if there are two left, and i=3 otherwise. ~&x print elements of vx with ~x, separated by commas and a final ``and'' ~vx print elements of vx with ~x, separated by commas and a final ``or'' ~nx if vx is a small positive integer, print it as a word, e.g., seven; if vx is a singleton containing a small positive integer, print the corresponding ordinal as a word, e.g., seventh ~Nx like ~nx but the word is capitalized, e.g., Seven or Seventh ~tx tab out to column vx; newline first if at or past column vx ~cx vx is (n . w), print integer n right justified in field of width w ~fx print object vx flat over as many lines as necessary ~Fx same as ~f, except that subsequent lines are indented to start one character to the right of the first character printed ~sx if vx is a symbol, print vx, breaking on hyphens (unless the symbol would normally be printed with surrounding vertical bar characters (|), in which case print as with ~fx); if vx is a string, print the characters in it, breaking on hyphens; else vx is a number, to be printed using the current print-base and print-radix ~Sx same as ~s, except that margins are ignored (hence no breaking on hyphens and no breaking when the column exceeds the value of the hard right-margin) ~ tilde space: print a space ~_x print vx spaces ~ tilde newline: skip following whitespace ~% output a newline ~| output a newline unless already on left margin ~~ print a tilde ~- if close to right margin, output a hyphen and newline; else skip this char If [47mx[0m is a character, then [47mvx[0m is the value of [47m#\x[0m under the current alist. Consider for example the discussion above for [47m~y[0m, ``[47m~yx pretty print vx[0m'', applied to the following expression: [47m(fmt "HELLO ~y7" (list (cons #\7 'world)) *standard-co* state nil)[0m. Then in this example: [47m#\x[0m is 7; and [47mvx[0m is the value of character [47m#\7[0m under the given alist, which is the symbol, [47mWORLD[0m. Thus, ACL2 will print [47mHELLO WORLD[0m. When we say ``format [47mstr[0m under [47ma+[0m'' we mean: process the given string under an alist obtained by appending [47ma[0m to the current alist. The following example illustrates how this works. ACL2 !>(fms "~@0" (list (cons #\0 (cons "~x0 ~@1" (list (cons #\0 'abc)))) (cons #\1 "-- and now: ~x0 again~%")) *standard-co* state nil) ABC -- and now: ABC again <state> ACL2 !> Note: [47m~p[0m, [47m~q[0m, [47m~P[0m, and [47m~Q[0m are also currently supported, but are deprecated and generally avoided in this manual. These are respectively the same as [47m~x[0m, [47m~y[0m, [47m~X[0m, and [47m~Y[0m, except that their arguments may be expected to be terms, preferably untranslated (user-level) terms, since at one time there was the possibility that they could be printed using infix notation in certain environments. Infix printing is no longer supported, however. ACL2's formatting functions print to the indicated channel, keeping track of which column they are in. [47m[Fmt1][0m can be used if the caller knows which column the channel is in (i.e., how many [characters] have been printed since the last newline). Otherwise, [47mfmt[0m or [47m[fms][0m must be used, both of which output a newline so as to establish the column position at [47m0[0m. Unlike Common Lisp's [47mformat[0m routine, [47mfmt[0m and its relatives break the output into lines so that, by default, an attempt is made to avoid printing past column [47m77[0m (the value of constant [47m*fmt-hard-right-margin-default*[0m), except when using [47m~S[0m. See [set-fmt-hard-right-margin] for a discussion of how linebreaks are inserted and how to change the relevant default settings. A right margin of 40 is used for pretty printing with [47m~y[0m, [47m~Y[0m, [47m~q[0m, and [47m~Q[0m and can be changed to a positive integer [47mN[0m with [47m(set-ppr-flat-right-margin N state)[0m. The formatting functions scan the string from left to right, printing each successive character unless it is a tilde [47m(~)[0m. Upon encountering tildes the formatters take action determined by the character or [characters] immediately following the tilde. The typical tilde-directive is a group of three successive [characters] from the string being printed. For example, [47m~x0[0m is a 3 character [47mtilde-directive[0m. The first character in a tilde-directive is always the tilde character itself. The next character is called the ``command'' character. The character after that is usually taken as the name of a ``format variable'' that is bound in the alist under which the string is being printed. Format variables are, by necessity, [characters]. The objects actually printed by a tilde-directive are the objects obtained by looking up the command's format variables in the alist. Typical format variable names are [47m0[0m, [47m1[0m, [47m2[0m, ..., [47m9[0m, [47ma[0m, [47mb[0m, [47mc[0m, etc., and if a tilde-directive uses the format variable [47m0[0m, as in [47m~x0[0m, then the character [47m#\0[0m must be bound in the alist. Some tilde commands take no arguments and others take more than one, so some directives are of length two and others are longer. It should be noted that this use of [characters] in the string to denote arguments is another break from Common Lisp's [47mformat[0m routine. In Common Lisp, the directives refer implicitly to the ``next item to be printed.'' But in ACL2 the directives name each item explicitly with our format variables. The following text contains examples that can be evaluated. To make this process easier, we use a macro, [47mfmx[0m. It takes up to eleven arguments, the first of which is a format string, [47mstr[0m, and the others of which are taken as the values of format variables; for similar utilities that do not take or return [state], see [cw] and [fmx-cw]. The variables used are [47m#\0[0m through [47m#\9[0m. The macro constructs an appropriate alist, [47ma[0m, and then evaluates [47m(fmt` str a 0 *standard-co* state nil)[0m. Thus, (fmx "~%Here is v0, ~x0, and here is v1, ~x1." (cons 'value 0) (cons 'value 1)) is just an abbreviation for (fmt1 "~%Here is v0, ~x0, and here is v1, ~x1." (list (cons #\0 (cons 'value 0)) (cons #\1 (cons 'value 1))) 0 *standard-co* state nil) which returns [47m(mv 53 state)[0m after printing, on a separate line, Here is v0, (VALUE . 0), and here is v1, (VALUE . 1). We now devote special attention to three of the tilde-directives whose use is non-obvious. [3mThe Case Statement[0m [47m~#x[0m is essentially a ``case statement'' in the language of [47mfmt[0m. The proper form of the statement is ~#x~[case-0~/case-1~/ ... ~/case-k~], where each of the [47mcase-i[0m is a format string. In the most common use, the variable [47mx[0m has an integer value, [47mvx[0m, between [47m0[0m and [47mk[0m, inclusive. The effect of formatting the directive is to format [47mcase-vx[0m. For example (fmx "Go ~#0~[North~/East~/South~/West~].~%" 1) will print ``Go East.'' followed by a newline and will return [47m(mv 0 state)[0m, while if you change the [47m1[0m above to [47m3[0m (the maximum legal value), it will print ``Go West.'' In order to make it easier to print such phrases as ``there are seven cases'' requiring agreement between subject and verb based on the number of elements of a list, the case statement allows its variable to take a list as its value and selects [47mcase-0[0m if the list has length [47m1[0m and [47mcase-1[0m otherwise. (let ((cases '(a b c))) (fmx "There ~#0~[is ~n1 case~/are ~n1 cases~]." cases (length cases))) will print ``There are three cases.'' but if you change the [47m'(a b c)[0m above simply to [47m'(a)[0m it will print ``There is one case.'' and if you change it to [47mnil[0m it will print ``There are zero cases.'' [3mIndirection[0m Roughly speaking, [47m~@[0m will act as though the value of its argument is a format string and splice it into the current string at the current position. It is often used when the phrase to be printed must be computed. For example, (let ((ev 'DEFUN)) (fmx "~x0 is an event~@1." 'foo (if (member-eq ev '(defun defstub encapsulate)) " that may introduce a function symbol" ""))) will print ``[47mfoo[0m is an event that may introduce a function symbol,'' but if the value of [47mev[0m is changed from [47m'[0m[47m[defun][0m to [47m'[0m[47m[defthm][0m, it prints ``[47mfoo[0m is an event.'' The [47m~@[0m directive ``splices'' in the computed phrase (which might be empty). Of course, this particular example could be done with the case statement ~#1~[~/ that may introduce a function symbol~] where the value of [47m#\1[0m is appropriately computed to be [47m0[0m or [47m1[0m. If the argument to [47m~@[0m is a pair, it is taken to be a format string [47m[cons][0med onto an alist, i.e., [47m("str" . a)[0m, and the alist, [47ma[0m, is used to extend the current one before [47m"str"[0m is recursively processed. This feature of [47mfmt[0m can be used to pass around ``phrases'' that contain computed contextual information in [47ma[0m. The most typical use is as ``error messages.'' For example, suppose you are writing a function which does not have access to [47m[state][0m and so cannot print an error message. It may nevertheless be necessary for it to signal an error to its caller, say by returning two results, the first of which is interpreted as an error message if non-[47mnil[0m. Our convention is to use a [47m~@[0m pair to represent such messages. For example, the error value might be produced by the code: (cons "Error: The instruction ~x0 is illegal when the stack is ~x1.~%" (list (cons #\0 (current-instruction st)) (cons #\1 (i-stack st)))) If the [47mcurrent-instruction[0m and [47mi-stack[0m (whatever they are) are [47m'(popi 3)[0m and [47m'(a b)[0m when the [47m[cons][0m above is evaluated, then it produces '("Error: The instruction ~x0 is illegal when the stack is ~x1.~%" (#\0 POPI 3) (#\1 A B)) and if this pair is made the value of the [47mfmt[0m variable [47m0[0m, then [47m~@0[0m will print Error: The instruction (POPI 3) is illegal when the stack is (A B). For example, evaluate (let ((pair '("~%Error: The instruction ~x0 is illegal when the stack is ~x1.~%" (#\0 POPI 3) (#\1 A B)))) (fmx "~@0" pair)). Thus, even though the function that produced the ``error'' could not print it, it could specify exactly what error message and data are to be printed. This example raises another issue. Sometimes it is desirable to break lines in your format strings so as to make your source code more attractive. That is the purpose of the [47mtilde-newline[0m directive. The following code produces exactly the same output as described above. (let ((pair '("Error: The instruction ~x0 ~ is illegal when the stack is ~ ~x1.~%" (#\0 POPI 3) (#\1 A B)))) (fmx "~%~@0" pair)). Finally, observe that when [47m~@0[0m extends the current alist, [47malist[0m, with the one, [47ma[0m, in its argument, the bindings from [47ma[0m are added to the front of [47malist[0m, overriding the current values of any shared variables. This ensures that the variable values seen by the recursively processed string, [47m"str"[0m, are those from [47ma[0m, but if [47m"str"[0m uses variables not bound in [47ma[0m, their values are as specified in the original alist. Intuitively, variables bound in [47ma[0m are local to the processing of [47m("str" . a)[0m but [47m"str"[0m may use ``global variables.'' The example above illustrates this because when the [47m~@0[0m is processed, [47m#\0[0m is bound to the error message pair. But when the [47m~x0[0m in the error string is processed, [47m#\0[0m is bound to the illegal instruction. [3mIteration[0m The [47m~*[0m directive is used to process each element of a list. For example, (let ((lst '(a b c d e f g h))) ; a true-list whose elements we exhibit (fmx "~*0" `("Whoa!" ; what to print if there's nothing to print "~x*!" ; how to print the last element "~x* and " ; how to print the 2nd to last element "~x*, " ; how to print all other elements ,lst))) ; the list of elements to print will print ``[47mA, B, C, D, E, F, G and H![0m''. Try this example with other true list values of [47mlst[0m, such as [47m'(a b)[0m, [47m'(a)[0m, and [47mnil[0m. The tilde-directives [47m~&0[0m and [47m~v0[0m, which take a true list argument and display its elements separated by commas and a final ``and'' or ``or,'' are implemented in terms of the more general [47m~*[0m. The [47m~*[0m directive allows the 5-tuple to specify in its final [47m[cdr][0m an alist with which to extend the current one before processing the individual elements. We often use [47m~*[0m to print a series of phrases, separated by suitable punctuation, whitespace and noise words. In such use, the [47m~*[0m handles the separation of the phrases and each phrase is generally printed by [47m~@[0m. Here is a complex example. In the [47m[let*][0m, below, we bind phrases to a list of [47m~@[0m pairs and then we create a [47m~*[0m 5-tuple to print out the conjunction of the phrases with a parenthetical ``finally!'' if the series is longer than 3. (let* ((phrases (list (list "simplifying with the replacement rules ~&0" (cons #\0 '(rewrite-rule1 rewrite-rule2 rewrite-rule3))) (list "destructor elimination using ~x0" (cons #\0 'elim-rule)) (list "generalizing the terms ~&0" (cons #\0 '((rev x) (app u v)))) (list "inducting on ~x0" (cons #\0 'I)))) (5-tuple (list "magic" ; no phrases "~@*" ; last phrase "~@*, and~#f~[~/ (finally!)~] " ; second to last phrase "~@*, " ; other phrases phrases ; the phrases themselves (cons #\f (if (>(length phrases) 3) 1 0))))) ;print ``finally''? (fmx "We did it by ~*0." 5-tuple)) This [47m[let*][0m prints We did it by simplifying with the replacement rules REWRITE-RULE1, REWRITE-RULE2 and REWRITE-RULE3, destructor elimination using ELIM- RULE, generalizing the terms (REV X) and (APP U V), and (finally!) inducting on I. You might wish to try evaluating the [47m[let*][0m after removing elements of phrases. Most of the output produced by ACL2 is produced via [47mfmt[0m statements. Thus, inspection of the source code will yield many examples. A complicated example is the code that explains the simplifier's work. See [47m:[0m[47m[pc][0m [47msimplify-clause-msg1[0m. An ad hoc example is provided by the function [47mfmt-doc-example[0m, which takes two arguments: an arbitrary true list and [47m[state][0m. To see how [47mfmt-doc-example[0m works, [47m:[0m[47m[pe][0m [47mfmt-doc-example[0m. (fmt-doc-example '(a b c d e f g h i j k l m n o p) state) will produce the output Here is a true list: (A B C D E F G H I J K L M N O P). It has 16 elements, the third of which is C. We could print each element in square brackets: ([A], [B], [C], [D], [E], [F], [G], [H], [I], [J], [K], [L], [M], [N], [almost there: O], [the end: P]). And if we wished to itemize them into column 15 we could do it like this 0123456789012345 0 (zeroth) A 1 (first) B 2 (second) C 3 (third) D 4 (fourth) E 5 (fifth) F 6 (sixth) G 7 (seventh) H 8 (eighth) I 9 (ninth) J 10 (tenth) K 11 (eleventh) L 12 (twelfth) M 13 (thirteenth) N 14 (14th) O 15 (15th) P End of example. and return [47m(mv 15 state)[0m. Finally, we should remind the reader that [47mfmt[0m and its subfunctions, most importantly [47mfmt0[0m, are written entirely in ACL2. We make this comment for two reasons. First, it illustrates the fact that quite low level code can be efficiently written in the language. Second, it means that as a last resort for documentation purposes you can read the source code without changing languages.") (fmt! (io acl2-built-ins) "[47m(fmt! str alist co-channel state evisc) => state[0m This function is nearly the same as [47m[fmt][0m, but [47mfmt![0m avoids inserting backslash (\) characters when forced to print past the right margin. Use [47mfmt![0m if you want to be able to read the forms back in.") (fmt!-to-string (pointers) "See [printing-to-strings].") (fmt-hard-right-margin (pointers) "See [set-fmt-hard-right-margin].") (fmt-soft-right-margin (pointers) "See [set-fmt-hard-right-margin].") (fmt-to-comment-window (cw io acl2-built-ins) "Print to the comment window General Form: (fmt-to-comment-window fmt-string alist col evisc-tuple print-base-radix) where these arguments are as described for [47m[fmt1][0m (see [fmt]) except that the last argument is as described for [47m[cw-print-base-radix][0m. See [cw] for important background. Calls of the macro [47mcw[0m expand to calls of the function [47mfmt-to-comment-window[0m whose final three arguments are [47m0[0m, [47mnil[0m, and [47mnil[0m. For variants of [47mfmt-to-comment-window[0m that provide readable output (suffix [47m"!"[0m) and are never inhibited (suffix [47m"+"[0m), see [fmt-to-comment-window!], [fmt-to-comment-window+], and [fmt-to-comment-window!+]. Function [47mfmt-to-comment-window[0m is similar to [47mfmt1[0m (see [fmt]), except that the channel is [47m[*standard-co*][0m and the ACL2 [47m[state][0m is neither an input nor an output, and moreover, an additional argument specifies the print-base and optionally the print-radix. That additional argument is treated the same as the first argument of [47mcw-print-base-radix[0m; see [cw-print-base-radix]. An analogous function, [47mfmt-to-comment-window![0m, prints with [47m[fmt!][0m instead of [47m[fmt][0m, in order to avoid insertion of backslash (\) characters for margins; also see [cw!], a macro that expands to a call of [47mfmt-to-comment-window![0m. Note that even if you change the value of [47m[ld][0m special [47mstandard-co[0m (see [standard-co]), [47mfmt-to-comment-window[0m will print to [47m[*standard-co*][0m, which is the original value of [47m[standard-co][0m.") (fmt-to-comment-window! (cw io acl2-built-ins) "Print readably to the comment window See [cw] for important background. This is nearly the same as [47m[fmt-to-comment-window][0m, but [47mfmt-to-comment-window![0m avoids inserting backslash (\) characters when forced to print past the right margin. Use [47mfmt-to-comment-window![0m if you want to be able to read the forms back in.") (fmt-to-comment-window!+ (cw io acl2-built-ins) "Print readably and uninhibited to the comment window See [cw] for important background. This is nearly the same as [47m[fmt-to-comment-window][0m, but [47mfmt-to-comment-window!+[0m always produces readable output (like [47m[fmt-to-comment-window!][0m), even when the [47mCOMMENT[0m output type is inhibited (like [47m[fmt-to-comment-window+][0m).") (fmt-to-comment-window+ (cw io acl2-built-ins) "Print uninhibited to the comment window See [cw] for important background. This is nearly the same as [47m[fmt-to-comment-window][0m, but [47mfmt-to-comment-window+[0m always produces output, even when the [47mCOMMENT[0m output type is inhibited (see [set-inhibit-output-lst]).") (fmt-to-string (pointers) "See [printing-to-strings].") (fmt1 (io acl2-built-ins) "[47m(fmt1 str alist col co-channel state evisc) => (mv col state)[0m See [fmt] for further explanation, including documentation of the tilde-directives.") (fmt1! (io acl2-built-ins) "[47m(fmt1! str alist col channel state evisc) => (mv col state)[0m This function is nearly the same as [47m[fmt1][0m, but [47mfmt1![0m avoids inserting backslash (\) characters when forced to print past the right margin. Use [47mfmt1![0m if you want to be able to read the forms back in.") (fmt1!-to-string (pointers) "See [printing-to-strings].") (fmt1-to-string (pointers) "See [printing-to-strings].") (fmx (io acl2-built-ins) "[47m(fmx str &rest args) => state[0m See [fmt] for further explanation, including documentation of the tilde-directives.") (fmx!-cw (pointers) "See [fmx-cw].") (fmx-cw (io acl2-built-ins) "[47m(fmx-cw str &rest args) => state[0m [47mFmx-cw[0m is a variant of [47mcw[0m: both take the same arguments and have the same behavior on well-formed input, and both return [47mnil[0m. See [cw] for documentation on how to use both utilities. Unlike [47mcw[0m, which has a [guard] of [47mt[0m, [47mfmx-cw[0m has a non-trivial guard that can catch errors in the use of tilde-directives. Here is an example of such a guard violation, where the corresponding call of [47mcw[0m would instead cause a hard error. ACL2 !>(fmx-cw "Hello ~s0." '(world)) ACL2 Error in TOP-LEVEL: Guard violation for FMX-CW-FN: Illegal Fmt Syntax. The tilde-s directive at position 6 of the string below is illegal because its variable evaluated to (WORLD), which is not a symbol, a string, or a number. "Hello ~s0." ACL2 !> Thus, call [47mfmx-cw[0m instead of [47mcw[0m in the body of [47m:[0m[47m[logic][0m mode definition when you want its [guard] verification to help ensure the absence of runtime errors from that call. Note that if you call [47mfmx-cw[0m in a definition, the guard proof may benefit from the lemma, [47mfmx-cw-msg-1-opener[0m, found in [community-book] [47mbooks/system/fmx-cw.lisp[0m. The variant [47mfmx!-cw[0m avoids the insertion of backslash () characters when forced to print past the right margin. Thus, use [47mfmx!-cw[0m instead of [47mfmx-cw[0m if you want the output to be machine-readable.") (fn-equal (apply$ defwarrant) "Equivalence relation on tame functions [47mFn-equal[0m is an equivalence relation on tame functions. It holds between [47mfn1[0m and [47mfn2[0m iff both are tame functions and [47m(apply$ fn1 args)[0m is [47m(apply$ fn2 args)[0m, for all [47margs[0m. A [47mdefun-sk[0m event is used to express the universally quantified condition. [47m[defwarrant][0m proves that [47mfn-equal[0m is a congruence relation for every argument position of ilk [47m:FN[0m. Ideally one can substitute one functional object for an equivalent one in functional positions. For example, [47mfn-equal[0m holds between [47m'(LAMBDA (X) X)[0m and [47m'IDENTITY[0m, so one would hold that [47m(collect$ '(LAMBDA (X) X) lst)[0m could be rewritten to [47m(collect$ 'IDENTITY lst)[0m since the first argument of [47mcollect$[0m (as defined in the [introduction-to-apply$]) has ilk [47m:FN[0m. Unfortunately, because these are quoted constants, ACL2's rewriter will not rewrite one to the other! We regard [47mfn-equal[0m as a reminder to us --- or a challenge to users! --- to find a way to handle functional equivalence in the rewriter.") (fn-rune-nume (pointers) "See [system-utilities].") (fn-symb (pointers) "See [system-utilities].") (fncall-term (pointers) "See [meta-extract].") (for-loop$ (loop$) "Iteration with [47m[loop$][0m over an interval of integers or a list This topic assumes that you have read the introduction to [47mloop$[0m expressions in ACL2; see [loop$]. Here we give more complete documentation on [47mFOR[0m [47mloop$[0m expressions, beginning with informal discussion and then continuing with detailed syntax (General Form) and semantics. For a discussion of proofs about [47mloop$[0ms, see [stating-and-proving-lemmas-about-loop$s]. Examples of [47m[loop$][0m expressions, including [47mFOR[0m [47mloop$[0ms, may be found in [community-book] [47mprojects/apply/loop-tests.lisp[0m. The only allowed iteration clauses are [47mIN[0m, where the variable ranges over the elements of the given true list; [47mON[0m, where the variable ranges over the tails of the given true-list; and [47mFROM/TO/BY[0m, where the variable ranges over the integers between two bounds, stepping by a positive integer increment (or by 1 if no [47mBY[0m clause is provided). You may have as many iteration clauses as you wish, connected with [47mAS[0m. Each must introduce a unique iteration variable and that variable may be optionally followed by an [47mOF-TYPE[0m [type-spec] specification. [47mOF-TYPE[0m is a Common Lisp feature that allows the compiler to optimize operations on the variable in question. Here is an example. (loop$ for v of-type (and integer (not (satisfies zerop))) from 1 to 100 sum (/ 1 v)) Here is that same example with a more concise type specification. (loop$ for v of-type (integer 1 *) from 1 to 100 sum (/ 1 v)) After all of the iteration clauses, you may have a termination test, signaled by [47mUNTIL[0m, and/or a conditional test, signaled by [47mWHEN[0m. If both are provided, the [47mUNTIL[0m test must come first. Iteration stops when the [47mUNTIL[0m test is satisfied. The conditional test determines whether the loop body is executed for the current value of the iteration variables. Between the [47mUNTIL[0m symbol and the expression to be tested, and between the [47mWHEN[0m symbol and its expression, you may include a [47m:GUARD[0m clause. This is useful if [guard] verification requires an invariant relating multiple iteration variables. An example of a guarded [47mUNTIL[0m clause is (loop$ for u in lst1 as v in lst2 until :guard (invariantp u v) (test u v) collect (body u v)) ACL2 supports only five operators in [47mFOR[0m [47mloop$[0ms: [47mSUM[0m, [47mCOLLECT[0m, [47mALWAYS[0m, [47mTHEREIS[0m and [47mAPPEND[0m. We anticipate adding other Common Lisp operators eventually. The special symbols noted above, sometimes called ``[47mFOR[0m [47mloop$[0m keywords'' or just ``[47mloop$[0m keywords'' may be in any package. These are [47mFOR[0m, [47mIN[0m, [47mON[0m, [47mFROM[0m, [47mTO[0m, [47mBY[0m, [47mOF-TYPE[0m, [47mWHEN[0m, [47mUNTIL[0m, [47mSUM[0m, [47mCOLLECT[0m, [47mALWAYS[0m, [47mTHEREIS[0m, and [47mAPPEND[0m. Between the operator, e.g., [47mSUM[0m or [47mCOLLECT[0m, and the [47mloop$[0m body you may include a [47m:GUARD[0m clause as in (loop$ for u in lst1 as v in lst2 collect :guard (invariantp u v) (body u v)) This is sometimes necessary in the verification of the [guard]s for the [47mloop$[0m body because Common Lisp's [47mOF-TYPE[0m clauses do not permit you to relate one variable to another. See [lp-section-6] of the [47mLoop$[0m Primer for some exercises in writing [47mFOR[0m [47mLoop$[0ms (with answers in a Community Book). But remember to come back here when you get to the end of that section. General Form The syntax of Common Lisp [47mloop[0m expressions is extremely complicated. Rather than try to write the abstract syntax of ACL2's [47mloop$[0m expressions in the same formal style, we take a different approach, which is workable because [47mloop$[0m allows fewer options. First we introduce the syntax of a ``target clause,'' a ``type-spec,'' and the ``operators.'' Then we describe the most elaborate form of a [47mloop$[0m expression in terms of these elements and ordinary ACL2 terms. Every legal [47mloop$[0m expression can be produced by omitting certain optional elements from the most elaborate [47mloop$[0m form. So we conclude the syntactic description of [47mloop$[0m by listing the elements that can be omitted. A [3mtarget clause[0m has one of four forms * [47mIN[0m [3mlist-expr[0m * [47mON[0m [3mexpr[0m * [47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m * [47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m [47mBY[0m [3mstep-expr[0m where [3mlist-expr[0m is a term (which is expected to evaluate to a true list), [3mexpr[0m is a term, [3mlo-expr[0m and [3mhi-expr[0m are terms (which are expected to evaluate to integers), and [3mstep-expr[0m is a term (which is expected to evaluate to a positive integer). The legal [3mtype-specs[0m are listed in [47m[type-spec][0m. The legal [3moperators[0m are [47mSUM[0m, [47mCOLLECT[0m, [47mALWAYS[0m, [47mTHEREIS[0m, and [47mAPPEND[0m. The most elaborate [47mloop$[0m expression is of the form [47m(LOOP$ FOR [0m[3mv1[0m[47m OF-TYPE [0m[3mspec1 target1[0m [47mAS [0m [3mv2[0m[47m OF-TYPE [0m[3mspec2 target2[0m ... [47mAS [0m [3mvn[0m[47m OF-TYPE [0m[3mspecn targetn[0m [47mUNTIL :GUARD [0m[3mguard1 until-expr[0m [47mWHEN [0m [47m:GUARD [0m[3mguard2 when-expr[0m ; Note the [47mALWAYS[0m/[47mTHEREIS[0m Exceptions below! [3mop[0m[47m :GUARD [0m[3mguard3 body-expr[0m[47m)[0m where each [3mvi[0m is a legal variable symbol and they are all distinct, each [3mtype-speci[0m is a [47m[type-spec][0m, each [3mtargeti[0m is a target clause, each [3mguardi[0m, [3muntil-expr[0m, and [3mwhen-expr[0m is a term, [3mop[0m is an operator, and [3mbody-expr[0m is a term. Furthermore, [3muntil-expr[0m, [3mwhen-expr[0m, and [3mbody-expr[0m must be [tame]! [3mThe [47mALWAYS[0m[3m/[47mTHEREIS[0m[3m Exception:[0m Common Lisp prohibits loops with both a [47mWHEN[0m clause and either an [47mALWAYS[0m or a [47mTHEREIS[0m operator. For example, if you are tempted to use [47mWHEN[0m [3mp[0m with [47mALWAYS[0m [3mq[0m you can instead write [47mALWAYS[0m [47m(implies [0m[3mp q[0m[47m)[0m or, if you want to evaluate [47mq[0m only when [47mp[0m is true, you can write [47mALWAYS[0m [47m(if [0m[3mp q[0m [47mt)[0m. The following elements may be omitted. * any line beginning with [47mAS[0m, [47mUNTIL[0m or [47mWHEN[0m, * any [47mOF-TYPE[0m [3mspeci[0m, and * any [47m:GUARD[0m [3mguardi[0m. As noted above, the [47mFOR[0m [47mloop$[0m keywords (as used above) may be in any package. These are [47mFOR[0m, [47mIN[0m, [47mON[0m, [47mFROM[0m, [47mTO[0m, [47mBY[0m, [47mOF-TYPE[0m, [47mWHEN[0m, [47mUNTIL[0m, [47mSUM[0m, [47mCOLLECT[0m, [47mALWAYS[0m, [47mTHEREIS[0m, and [47mAPPEND[0m. We give names to certain classes of the syntactic entities above. The [3mv1[0m, ..., [3mvn[0m are called the [3miteration variables[0m. The [3mspec1[0m, ..., [3mspecn[0m are called [3mtype specs[0m, each corresponds to a certain iteration variable, and each gives rise to a [3mtype term[0m about its variable in the sense that ``[47mX OF-TYPE (SATISFIES NATP)[0m'' gives rise to the type term [47m(NATP X)[0m and ``[47mI OF-TYPE INTEGER[0m'' gives rise to the type term [47m(INTEGERP I)[0m. The terms involved in the target expressions, e.g., the [3mlist-expr[0m and [3mexpr[0m in ``[47mIN[0m [3mlist-expr[0m'' and ``[47mON[0m [3mexpr[0m'' and the [3mlo-expr[0m, [3mhi-expr[0m and optional [3mstep-expr[0m in the ``[47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m [47mBY[0m [3mstep-expr[0m'' targets are called [3mtarget terms[0m. Finally, the [3muntil-expr[0m, [3mwhen-expr[0m, and [3mbody-expr[0m are called [3miterative forms[0m. We distinguish the target terms from the iterative forms because they are handled very differently at evaluation time. When a [47mloop$[0m is evaluated, the target terms are evaluated just once. But the iterative forms are evaluated multiple times as the iteration variables range over the values of the targets. A [47mFOR[0m [47mloop$[0m expression with just one iteration variable and in which the iterative forms mention no free variable other than the iteration variable is called a [3msimple [47mloop$[0m[3m[0m (or, sometimes, a [3msimple loop[0m). An example of a simple loop is (loop$ for x in lst when (evenp x) collect (+ 1 (sq x))) A [47mFOR[0m [47mloop$[0m expression is called a [3mfancy [47mloop$[0m[3m[0m if it is not simple. Both of the following [47mloop$[0ms are fancy. (loop$ for x in xlst as y on ylst collect (expr x y)) (loop$ for x in xlst collect (expr x z)) The first is fancy because it has two iteration variables. The second is fancy because the body freely uses the variable [47mz[0m which is not the iteration variable. The free variables cannot be [stobj]s or [df]s, since the translation of the [47mloop$[0m will put them into a list; see discussion of the semantics, below. In such cases you may wish to use [47mDO[0m [47mloop$[0m expressions (see [do-loop$]) instead. Semantics [47mFOR[0m [47mloop$[0m expressions are translated into calls of [scion]s, with the [47mUNTIL[0m and [47mWHEN[0m clauses translated into preprocessors of the targets. But which scions are used depend on whether the loop is simple or fancy. Recall that a fancy loop is one that has either or both of the following characteristics: (a) there is one or more [47mas[0m clauses, and/or (b) one of the iterative forms (the [47mUNTIL[0m, [47mWHEN[0m or loop body expression) refers to variables other than an iteration variable. If the [47mloop$[0m expression is simple, the simple scions are used; otherwise the fancy scions are used. loop$ simple fancy keyword scion scion ______________________________________________ SUM sum$ sum$+ COLLECT collect$ collect$+ ALWAYS always$ always$+ THEREIS thereis$ thereis$+ APPEND append$ append$+ UNTIL until$ until$+ WHEN when$ when$+ We deal with simple [47mloop$[0ms first. Semantics of Simple Loop$s For example, the simple [47mloop$[0m (loop$ for x in lst collect (+ 1 (sq x))) translates to (a term equivalent to) (collect$ (lambda$ (x) (declare (ignorable x)) (+ 1 (sq x))) lst). [31;1mNote:[0m The actual translation is tagged with various markers that play a role in evaluation but which are logically irrelevant and which are removed during proof. In this discussion we will not display the marked-up translations but logically equivalent terms instead. You can see the actual translations for yourself with [47m[trans][0m. In the translation the target term, [47mlst[0m, appears as an ordinary subterm of the translation. But the iterative form, [47m(+ 1 (sq x))[0m, becomes the body of a [47m[lambda$][0m expression, which means its translation becomes a component of a quoted [47mLAMBDA[0m object. When the [47mcollect$[0m is evaluated, the target term is evaluated once but the iterative form is evaluated once for each element of the value of the target. [47mUNTIL[0m and [47mWHEN[0m clauses are handled by preprocessing the target. E.g., (loop$ for x in lst until (> x 100) when (evenp x) collect (+ 1 (sq x))) becomes (collect$ (lambda$ (x) (declare (ignorable x)) (+ 1 (sq x))) (when$ (lambda$ (x) (declare (ignorable x)) (evenp x)) (until$ (lambda$ (x) (declare (ignorable x)) (> x 100)) lst))) So from a logical perspective, the presence of an [47mUNTIL[0m and/or [47mWHEN[0m clause in a [47mcollect[0m iteration over [47mlst[0m ``copies'' the target value. The [47muntil$[0m copies [47mlst[0m until encountering the first element on which its functional argument is true. The [47mwhen$[0m then copies that (shortened?) target, keeping only the elements that satisfy its functional argument. Finally, the [47mcollect$[0m then applies its functional argument and collects all the values. [47mON[0m and [47mFROM/TO/BY[0m targets are handled by listing all the elements in the given target. For example, (loop$ for x on lst collect (expr x)) which maps [47mx[0m over successive non-empty tails of [47mlst[0m and collects the value of [47mexpr[0m has the logical meaning (collect$ (lambda$ (x) (expr x)) (tails lst)) where, for example, [47m(tails '(1 2 3))[0m is [47m((1 2 3) (2 3) (3))[0m. Spiritually similarly, (loop$ for i from 1 to max by step collect (expr x)) logically becomes (collect$ (lambda$ (x) (expr x)) (from-to-by 1 max step)) where, for example, [47m(from-to-by 1 10 2)[0m is [47m(1 3 5 7 9)[0m. Similar translations are done for the other operators, e.g., [47mSUM[0m and [47mALWAYS[0m. The advantage of this translation style is that it allows compositional reasoning. We discuss this further below. The following example illustrates basic [guard] proof obligations, in particular showing that [47mWHEN[0m clauses do not help with verifying guards for the [47mloop$[0m bodies. (Similarly, [47mUNTIL[0m clauses do not help either.) The basic problem is that ACL2 requires that [47m[lambda][0m objects be guard verifiable in isolation, not confined to the context in which a particular [47mlambda[0m object appears. Consider the following. (include-book "projects/apply/top" :dir :system) (defun$ sq (n) (declare (xargs :guard (natp n))) (* n n)) (defun foo (lst) (declare (xargs :guard (nat-listp lst))) (loop$ for x of-type (satisfies nat-listp) on lst when (consp x) sum (sq (car x)))) Guard verification fails for [47mfoo[0m. The summary says that a goal of [47mNIL[0m was generated. Using [47m:[0m[47m[pso][0m we can see that the [47mNIL[0m goal came from: Subgoal 1.2 (IMPLIES (NAT-LISTP LOOP$-IVAR) (INTEGERP (CAR LOOP$-IVAR))). Let's see what is going on by looking at the following simplified translation of the [47mloop$[0m expression. (sum$ '(lambda (loop$-ivar) (declare (type (satisfies nat-listp) loop$-ivar)) (sq (car loop$-ivar))) (when$ '(lambda ...) (tails lst))) Notice that the [47mlambda[0m object supplied to [47msum$[0m cannot be guard verified in isolation: [47mnil[0m satisfies the [47m:guard[0m and [47m(car nil)[0m violates the guard of [47msq[0m. The following modification, which adds a [47m:guard[0m directive after the [47mSUM[0m op keyword, solves the problem. (defun foo (lst) (declare (xargs :guard (nat-listp lst))) (loop$ for x of-type (satisfies nat-listp) on lst when (consp x) sum :guard (consp x) ; note new :guard (sq (car x)))) This new [47m:guard[0m may feel redundant, coming as it does after the [47mwhen (consp x)[0m clause. But it is necessary given the compositional semantics. A simplified translation of the [47mdefun[0m above shows that the application [47m(sq (car x))[0m is protected by a suitable guard in the [47mlambda[0m object. (sum$ '(lambda (loop$-ivar) (declare (type (satisfies nat-listp) loop$-ivar) (xargs :guard (consp loop$-ivar))) (sq (car loop$-ivar))) (when$ '(lambda ...) (tails lst))) Naively we might have expected that the guard proof obligation for the [47mloop$[0m body [47m(sq (car x))[0m could assume the [47mWHEN[0m clause, but that expectation would be wrong because of the compositional semantics we use and the fact that [47m[lambda][0m objects must be guard-verifiable on their own. The reason for the latter requirement is that our implementation caches guard-verified [47mlambda[0m objects for evaluation in raw Lisp, which may take place in other contexts different from that in which the [47mlambda[0m first appeared. See [print-cl-cache]. Semantics of Fancy Loop$s An example of a fancy [47mloop$[0m is (loop$ for x in xlst as y in ylst collect (expr x y z)) This loop exhibits both characteristics (a) and (b): it has an [47mAS[0m clause and the variable [47mz[0m appears in the loop body. Either characteristic is sufficient to classify the loop as fancy. So fancy scions are used. Here is its semantic counterpart, i.e., its simplified translation. (collect$+ (lambda$ (loop$-gvars loop$-ivars) (declare (xargs :guard (and (true-listp loop$-gvars) (equal (len loop$-gvars) 1) (true-listp loop$-ivars) (equal (len loop$-ivars) 2)))) (let ((z (car loop$-gvars)) (x (car loop$-ivars)) (y (car (cdr loop$-ivars)))) (declare (ignorable x y)) (expr x y z))) (list z) (loop$-as (list xlst ylst))) Before we show the definition of [47mcollect$+[0m, note that the arguments above to [47mcollect$+[0m are (i) a [47mlambda$[0m expression that handles the evaluation of the iterative form, in this case [47m(expr x y z)[0m, where [47mx[0m and [47my[0m are iteration variables and [47mz[0m is a ``global'' variable not among the iteration variables; (ii) the list of values of the ``global'' variables, in this case the list containing [47mz[0m; and (iii) a target list constructed by [47mloop$-as[0m from the various targets provided in the [47mloop$[0m, in this case [47mxlst[0m and [47mylst[0m, supplying values for iteration variables [47mx[0m and [47my[0m respectively. For example, [47m(loop$-as (list '(a b c d e) '(1 2 3)))[0m is [47m((a 1) (b 2) (c 3))[0m. These tuples contain successive corresponding values of [47mx[0m and [47my[0m. The definition of [47mcollect$+[0m is essentially (defun collect$+ (fn loop$-gvars lst) (if (endp lst) nil (cons (apply$ fn (list loop$-gvars (car lst))) (collect$+ fn loop$-gvars (cdr lst))))) We have omitted the guard and an [47m[mbe][0m form that make it run more efficiently. All the fancy [47mloop$[0m scions are defined analogously. Inspection of the [47mlambda$[0m expression above reveals that it takes a list of global variable values and a list of iteration variable values, unpacks them with a [47mlet[0m that binds the global variables, here just [47mz[0m, to their values and binds the iteration variables, here [47mx[0m and [47my[0m, to the corresponding pair of values from the target, and then evaluates the [47mloop$[0m body, [47m(expr x y z)[0m. The names of the formals for the [47mlambda$[0m expressions generated by fancy [47mloop$[0m expressions are always [47mloop$-gvars[0m and [47mloop$-ivars[0m, for ``[47mloop$[0m global variables'' and ``[47mloop$[0m iteration variables.'' [47mUNTIL[0m and [47mWHEN[0m clauses in a fancy [47mloop$[0m are handled exactly as they are in simple [47mloop$[0ms, except that the fancy scions are used since the target list is a list of tuples of iteration variable values and the [47mUNTIL[0m and [47mWHEN[0m forms may refer to global variables. See [lp-section-10] of the [47mLoop$[0m Primer for a step-by-step discussion of the evaluation of the formal semantics of an example of a fancy [47mLoop$[0m. But remember to come back here when you get to the end of that section. Special Guard Conjectures for [47mFOR[0m [47mloop$[0ms Since every [47mloop$[0m expands to a call of a [47mloop$[0m scion on a lambda object and a target, one would expect that [guard] verification would generate the guard conjectures for that scion and target. Indeed, it does. In particular, the lambda object must have the correct number of formals (which is guaranteed by translation) and the target must satisfy [47m[true-listp][0m. But in addition to the expected guard conjectures, we generate some special ones for the terms produced by translating [47mFOR[0m [47mloop$[0m expressions. We discuss the reasons in the next section, but here we just state what the special conjectures are. We limit ourselves to a simple [47mloop$[0m. Fancy [47mloop$[0ms generalize in the obvious way. The two classes of ``special guard conjectures'' for [47mFOR[0m [47mloop$[0m expressions are as follows. * First, every element (or tail, in the case of [47mON[0m [47mloop$[0ms)) satisfies the type-spec, if any, and the [47mloop$[0m body's [47m:GUARD[0m, if any. * Second, the [47mloop$[0m body produces a value acceptable to the [47mloop$[0m operator, e.g., the body of a [47mSUM[0m [47mloop$[0m produces a number and the body of an [47mAPPEND[0m [47mloop$[0m produces a true list. See [lp-section-8] of the [47mLoop$[0m Primer for some exercises in converting recursive functions to guard verified functions using [47mFOR[0m [47mloop$[0ms rather than recursion (with answers in a Community Book). But remember to come back here when you get to the end of that section. Discussion of Why LOOP$s Have Special Guards All of the simple [47mloop$[0m scions have the same guard, namely (AND (APPLY$-GUARD FN '(NIL)) (TRUE-LISTP LST)), and all the fancy [47mloop$[0m scions have the same guard, namely (AND (APPLY$-GUARD FN '(NIL NIL)) (TRUE-LISTP LOOP$-GVARS) (TRUE-LIST-LISTP LST)). In addition to the normal guard conjectures that would be generated by calls of these scions, ACL2 generates some special guard conjectures because the normal guard conjectures are insufficient to guarantee the error-free execution of the corresponding Common Lisp [47mloop[0m expressions. For example, the simplified translation of the body of (defun foo (lst) (declare (xargs :guard (foo-guardp lst))) (loop$ for x of-type (satisfies spec) on lst sum (expr x))) is as follows. (One might expect the second argument of the [47msum$[0m call to be [47m(tails lst)[0m, and of course that is what it equals, logically; the change is to support guards, as discussed in the Technical Note below.) (sum$ (lambda$ (loop$-ivar) (declare (type (satisfies spec) loop$-ivar)) (expr loop$-ivar)) (tails (prog2$ (let ((loop$-last-cdr (last-cdr lst))) (declare (type (satisfies spec) loop$-last-cdr)) loop$-last-cdr) lst))) Prior to the provision for special guards, the normal guard conjectures generated for [47mfoo[0m would be (and (implies (foo-guardp lst) ; [1] (apply$-guard (lambda$ (loop$-ivar) (expr loop$-ivar)) '(nil))) (implies (foo-guardp lst) ; [2] (true-listp (tails lst))) (implies (spec loop$-ivar) (expr-guardp loop$-ivar))) ; [3] (implies (foo-guardp lst) ; [4] (let ((loop$-last-cdr (last-cdr lst))) (spec loop$-last-cdr))) Conjectures [1] and [2] stem from the guard for [47msum$[0m and establish that the guard for [47mfoo[0m implies that [47msum$[0m is passed a function object of one argument and a true-list. Conjecture [3] establishes that the guard on the [47mlambda$[0m implies the guard of its body. Conjecture [4] says that the final tail of [47mlst[0m (which is [47mnil[0m if [47mlst[0m is a true list; see [last-cdr]) satisfies [47mspec[0m. At first [4] may be surprising, but inspection of Common Lisp reveals that even though [47m(expr x)[0m is never called on the final tail of [47mlst[0m, implementations running with high safety settings check that the final tail satisfies [47mspec[0m. If you see a runtime guard violation involving variable [47mloop$-last-cdr[0m, you can reasonably assume that you are seeing case [4] above. A guard proof failure involving a call of [47m[last-cdr][0m may also be from [4]. (Technical Note. The production of [4] is accomplished as follows for an expression [47m(loop for var of-type type-spec on lst ...)[0m: for the translation to a scion call, the target term, [47mlst[0m, is replaced by the following expression (simplifying slightly). (prog2$ (let ((loop$-last-cdr (last-cdr lst))) (declare (type type-spec loop$-last-cdr)) loop$-last-cdr) lst) The [47m[declare][0m form causes formula [4] above to be generated as a guard proof obligation. End of Technical Note.) The guard proof obligation shown as [4] above, for an expression [47m(loop$ for ... on ...)[0m, has a variant for an expression [47m(loop$ for n from i to j by k ...)[0m, where ``[47mby k[0m'' may be implicit if [47mk[0m is [47m1[0m. Instead of the requirement in [4] above that the bound variable [47mloop$-last-cdr[0m satisfy the [47mtype-spec[0m, variables [47mloop$-lo[0m, [47mloop$-hi[0m, and [47mloop$-by[0m, which are bound respectively to [47mi[0m, [47mj[0m, and [47mk[0m, are required to satisfy the [47mtype-spec[0m. A fourth requirement is that the last value tested must also satisfy the [47mtype-spec[0m. That last value tested is [47m(+ loop$-lo loop$-by (* loop$-by (floor (- loop$-hi loop$-lo) loop$-by)))[0m. If you see a runtime guard violation involving variable [47mloop$-lo[0m, [47mloop$-hi[0m, [47mloop$-by[0m, or [47mloop$-final[0m, you can reasonably assume that you are seeing this variant of [4]. But consider the raw Lisp [47mloop[0m generated by the [47mloop$[0m in the raw Lisp definition of [47mfoo[0m, (loop for x of-type (satisfies spec) on lst sum (expr x)). For this [47mloop[0m to execute without error we need to know that [5] every non-empty tail of [47mlst[0m satisfies [47mspec[0m, and [6] every non-empty tail [47mx[0m of [47mlst[0m is such that [47m(expr x)[0m returns a number. So when ACL2's guard verification process encounters a [47msum$[0m like that in the logical [47mdefun[0m of [47mfoo[0m, it generates two additional guard conjectures as described above. These are as mentioned above: [5] every element (or tail) satisfies the type-spec, and [6] the value of the [47mloop$[0m body is acceptable to the [47mloop$[0m operator. (implies (and (warrant ...) ; see below ; [5] (foo-guardp lst) (member-equal newv (tails lst))) (spec newv)) (implies (and (warrant ...) ; see below ; [6] (foo-guardp lst) (member-equal newv (tails lst))) (acl2-numberp (apply$ (lambda$ (loop$-ivar) (expr loop$-ivar)) (list newv)))) Notice the addition of hypotheses above of the form [47m(warrant ...)[0m. ACL2 adds such [3m[warrant] hypotheses[0m for function symbols that might be [47m[apply$][0m'd during evaluation of a scion call (in this case, [47msum$[0m). In general, you may notice that ACL2 generates such ``special'' guard conjectures for all calls of [47mFOR[0m [47mloop$[0m scions, whether or not they stemmed from uses of [47mloop$[0m. [47mFROM/TO/BY[0m targets require that the bounds and step all satisfy the [47mOF-TYPE[0m specification, and the [47mAPPEND[0m operator requires that the loop body generate a [47m[true-listp][0m (instead of an [47m[ACL2-numberp][0m as required by the [47mSUM[0m operator). The Compromise Between Reasoning and Efficiency The translation of [47mloop$[0m expressions into formal terms reflects a compromise between facilitating compositional reasoning and efficient execution. One sign of that compromise is our use of scions to handle [47mUNTIL[0m and [47mWHEN[0m clauses. As noted above, by translating (loop$ for x in lst until ... when ... collect ...) into (collect$ ... (when$ ... (until$ ... lst))) we're forcing the evaluation of the formal semantics to copy the target twice before collecting. But it gives us the ability to reason compositionally about [47mcollect$[0m, [47mwhen$[0m, and [47muntil$[0m. We could have defined a version of [47mcollect$[0m that took three [47mlambda$[0m expressions, one to terminate the collection, one to filter for the elements we're interested in, and one to transform those elements into the values we wish to collect. This would avoid copying upon evaluation but make it more difficult to reason. Another example of compositionality is to consider a simple [47mloop$[0m over the [47mIN[0m target [47m(append a b)[0m. There are 8 different ways you can do a simple [47mCOLLECT[0m over an [47m(append a b)[0m target, (loop$ for x in (append a b) collect (expr x)) (loop$ for x on (append a b) collect (expr x)) (loop$ for x in (append a b) until (stop x) collect (expr x)) (loop$ for x on (append a b) until (stop x) collect (expr x)) (loop$ for x in (append a b) when (test x) collect (expr x)) (loop$ for x on (append a b) when (test x) collect (expr x)) (loop$ for x in (append a b) until (stop x) when (test x) collect (expr x)) (loop$ for x on (append a b) until (stop x) when (test x) collect (expr x)) Similarly, there are 8 ways to [47mSUM[0m over an [47m(append a b)[0m target, 8 ways to [47mAPPEND[0m over an [47m(append a b)[0m, and 4 ways each to [47mALWAYS[0m or [47mTHEREIS[0m over an [47m(append a b)[0m target. Thus, there are 32 different simple [47mloop$[0ms over [47m(append a b)[0m. And you can arrange to distribute the simple [47mloop$[0m over the [47m(append a b)[0m with just seven rewrite rules. (equal (collect$ fn (append a b)) (append (collect$ fn a) (collect$ fn b))) (equal (sum$ fn (append a b)) (+ (sum$ fn a) (sum$ fn b))) (equal (always$ fn (append a b)) (and (always$ fn a) (always$ fn b))) (equal (thereis$ fn (append a b)) (or (thereis$ fn a) (thereis$ fn b))) (equal (append$ fn (append a b)) (append (append$ fn a) (append$ fn b))) (equal (until$ fn (append a b)) (if (exists$ fn a) (until$ fn a) (append a (until$ fn b)))) (equal (when$ fn (append a b)) (append (when$ fn a) (when$ fn b))) Thus, you can reason about [47mWHEN[0m and [47mUNTIL[0m clauses without having to consider how they are used in the superior [47mloop$[0m expression. To deal with fancy [47mloop$[0m you need seven more rewrite rules, one for each fancy [47mloop$[0m scion. But since every simple [47mloop$[0m can be expressed by an appropriate use of fancy scions, we could have translated every [47mFOR[0m [47mloop$[0m to fancy scions. We chose to break compositionality here because we think simple [47mloop$[0ms are most common and wanted to keep their semantics simple. I.e., we compromised. By the way, if you want the prover to convert every simple scion to its fancy counterpart you could prove rewrite rules like that below. (defthm convert-collect$-to-collect$+ (implies (ok-fnp fn) (equal (collect$ fn lst) (collect$+ `(lambda (loop$-gvars loop$-ivars) (,fn (car loop$-ivars))) nil (loop$-as (list lst))))) :hints (("[1]Goal" :expand ((tamep (cons fn '(x))) (tamep (cons fn '((car loop$-ivars))))))))") (forall (defun-sk) "Universal quantifier The symbol [47mforall[0m (in the ACL2 package) represents universal quantification in the context of a [47m[defun-sk][0m form. See [defun-sk] and see [exists]. See [quantifiers] for an example illustrating how the use of recursion, rather than explicit quantification with [47m[defun-sk][0m, may be preferable.") (force (rewrite linear type-prescription definition meta) "Identity function used to force a hypothesis [47mForce[0m is the identity function: [47m(force x)[0m is equal to [47mx[0m. However, for rules of many classes (see [rule-classes]), a hypothesis of the form [47m(force term)[0m is given special treatment, as described below. This treatment takes place for rule classes [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[meta][0m (actually in that case, the result of evaluating the hypothesis metafunction call), and [47m:[0m[47m[forward-chaining][0m. When a hypothesis of a conditional rule (of one of the classes listed above) has the form [47m(force hyp)[0m, it is logically equivalent to [47mhyp[0m but has a pragmatic effect. In particular, when the rule is considered, the needed instance of the hypothesis, [47mhyp'[0m, may be assumed if the usual process fails to prove it or its negation. In that situation, if the rule is eventually applied, then a special case is generated, requiring the system to prove that [47mhyp'[0m is true in the current context. The proofs of all such ``forced assumptions'' are, by default, delayed until the successful completion of the main goal. See [forcing-round] and see [immediate-force-modep]. Note that the only time that ACL2 gives special treatment to calls of [47mforce[0m is when it is considering the hypotheses of a conditional rule, as discussed above. In particular, when the rewriter encounters a subterm of the goal currently being simplified, a call of [47mforce[0m is not treated specially. For example, if you provide a [47m:use[0m hint (see [hints]) that replaces a goal [47mG[0m by the goal (implies (implies (and ... (force HYP) ...) concl) G) then the rewriter will not give any special treatment to [47m(force HYP)[0m. Instead, it will first rewrite [47mHYP[0m to, say, [47mHYP'[0m; and then, using the fact that [47mforce[0m is the identity function, the rewriter will return [47mHYP'[0m as the rewritten value for [47m(force HYP)[0m. Forcing is generally used on hypotheses that are always expected to be true, as is commonly the case for [guard]s of functions. All the power of the theorem prover is brought to bear on a forced hypothesis and no backtracking is possible. Forced goals can be attacked immediately (see [immediate-force-modep]) or in a subsequent forcing round (see [forcing-round]). Also see [case-split] for a related utility. If the [47m:[0m[47m[executable-counterpart][0m of the function [47mforce[0m is [disable]d, then no hypothesis is forced. For more on enabling and disabling forcing, see [enable-forcing] and see [disable-forcing]. It sometimes happens that a conditional rule is not applied because some hypothesis, [47mhyp[0m, could not be relieved, even though the required instance of [47mhyp[0m, [47mhyp'[0m, can be shown true in the context. This happens when insufficient resources are brought to bear on [47mhyp'[0m at the time we try to relieve it. A sometimes desirable alternative behavior is for the system to assume [47mhyp'[0m, apply the rule, and to generate explicitly a special case to show that [47mhyp'[0m is true in the context. This is called ``forcing'' [47mhyp[0m. It can be arranged by restating the rule so that the offending hypothesis, [47mhyp[0m, is embedded in a call of [47mforce[0m, as in [47m(force hyp)[0m. By using the [47m:[0m[47m[corollary][0m field of the [47m[rule-classes][0m entry, a hypothesis can be forced without changing the statement of the theorem from which the rule is derived. Technically, [47mforce[0m is just a function of one argument that returns that argument. It is generally [enable]d and hence evaporates during simplification. But its presence among the hypotheses of a conditional rule causes case splitting to occur if the hypothesis cannot be conventionally relieved. Since a forced hypothesis must be provable whenever the rule is otherwise applicable, forcing should be used only on hypotheses that are expected always to be true. A particularly common situation in which some hypotheses should be forced is in ``most general'' [type-prescription] lemmas. If a single lemma describes the ``expected'' type of a function, for all ``expected'' arguments, then it is probably a good idea to force the hypotheses of the lemma. Thus, every time a term involving the function arises, the term will be given the expected type and its arguments will be required to be of the expected type. In applying this advice it might be wise to avoid forcing those hypotheses that are in fact just type predicates on the arguments, since the application of [type-prescription] lemmas generally has fairly thorough knowledge of the types of all terms (see [type-prescription] for relevant background). [47mForce[0m can have the additional benefit of causing the ACL2 typing mechanism to interact with the ACL2 rewriter to establish the hypotheses of [type-prescription] rules. See [type-reasoning] for relevant background for the following explanation. If type reasoning alone is insufficient to prove some instance of a hypothesis, then the instance will not be proved by type reasoning and a [type-prescription] rule with that hypothesis will be inapplicable in that case. But by embedding such hypotheses in [47mforce[0m expressions you can effectively cause the type system to ``punt'' them to the rest of the theorem prover. Of course, as already noted, this should only be done on hypotheses that are ``always true.'' In particular, if rewriting is required to establish some hypothesis of a [type-prescription] rule, then the rule will be found inapplicable because the hypothesis will not be established by type reasoning alone. The ACL2 rewriter uses the type reasoning system as a subsystem. It is therefore possible that the type system will force a hypothesis that the rewriter could establish. Before a forced hypothesis is reported out of the rewriter, we try to establish it by rewriting. This makes the following surprising behavior possible: A [type-prescription] rule fails to apply because some true hypothesis is not being relieved. The user changes the rule so as to [31;1mforce[0m the hypothesis. The system then applies the rule but reports no forcing. How can this happen? The type system ``punted'' the forced hypothesis to the rewriter, which established it. The discussion above may give the impression that a forcing round only takes place because of a failure to relieve a forced hypothesis. A notable exception, however, is due to [linear-arithmetic]. Consider the following example: (implies (not (equal 0 x)) (or (< 0 x) (< x 0))) This is not a theorem; in particular, it fails when [47mx[0m is [47mnil[0m. What is missing is the hypothesis, [47m(acl2-numberp x)[0m. If you try to prove the displayed formula above and you look at the proof using [47m:[0m[47m[pso][0m, you'll see the following. But forced simplification reduces this to T, using the :executable- counterpart of FORCE and linear arithmetic. Thus, no specific rule created this forcing round (see also [forcing-round]). Rather, ACL2 was able to prove the goal using linear arithmetic, but it needed to force the assumption that [47mx[0m is a number. This is clear when we look at output for the forcing round: [1]Goal, below, will focus on (ACL2-NUMBERP X), which was forced in Goal' by the linearization of (EQUAL 0 X). Finally, we should mention that the rewriter is never willing to force when there is an [47m[if][0m term present in the goal being simplified. Since [47m[and][0m terms and [47m[or][0m terms are merely abbreviations for [47m[if][0m terms, they also prevent forcing. Note that [47m[if][0m terms are ultimately eliminated using the ordinary flow of the proof (but see [set-case-split-limitations]), allowing [47mforce[0m ultimately to function as intended. Moreover, forcing can be disabled, as described above; also see [disable-forcing]. [31;1mFunction: [0m<force> (defun force (x) (declare (xargs :guard t)) x) Subtopics [Disable-forcing] To disallow forced case-splits [Disable-immediate-force-modep] [force]d hypotheses are not attacked immediately [Enable-forcing] To allow forced case splits [Enable-immediate-force-modep] [force]d hypotheses are attacked immediately [Failed-forcing] How to deal with a proof [failure] in a forcing round [Forcing-round] A section of a proof dealing with [force]d assumptions [Immediate-force-modep] When the [executable-counterpart] is [enable]d, [force]d hypotheses are attacked immediately") (forced (pointers) "See [force].") (forcing-round (force) "A section of a proof dealing with [force]d assumptions If ACL2 ``[force]s'' some hypothesis of some rule to be true, it is obliged later to prove the hypothesis. See [force]. ACL2 delays the consideration of [force]d hypotheses until the main goal has been proved. It then undertakes a new round of proofs in which the main goal is essentially the conjunction of all hypotheses [force]d in the preceding proof. Call this round of proofs the ``Forcing Round.'' Additional hypotheses may be [force]d by the proofs in the Forcing Round. The attempt to prove these hypotheses is delayed until the Forcing Round has been successfully completed. Then a new Forcing Round is undertaken to prove the recently [force]d hypotheses and this continues until no hypotheses are [force]d. Thus, there is a succession of Forcing Rounds. The Forcing Rounds are enumerated starting from 1. The Goals and Subgoals of a Forcing Round are printed with the round's number displayed in square brackets. Thus, [47m"[1]Subgoal 1.3"[0m means that the goal in question is Subgoal 1.3 of the 1st forcing round. To supply a hint for use in the proof of that subgoal, you should use the goal specifier [47m"[1]Subgoal 1.3"[0m. See [goal-spec]. When a round is successfully completed --- and for these purposes you may think of the proof of the main goal as being the 0th forcing round --- the system collects all of the assumptions [force]d by the just-completed round. Here, an assumption should be thought of as an implication, [47m(implies context hyp)[0m, where context describes the context in which hyp was assumed true. Before undertaking the proofs of these assumptions, we try to ``clean them up'' in an effort to reduce the amount of work required. This is often possible because the [force]d assumptions are generated by the same rule being applied repeatedly in a given context. By delaying and collecting the [47mforced[0m assumptions until the completion of the ``main goal'' we gain two advantages. First, the user gets confirmation that the ``gist'' of the proof is complete and that all that remains are ``technical details.'' Second, by delaying the proofs of the [force]d assumptions ACL2 can undertake the proof of each assumption only once, no matter how many times it was [force]d in the main goal. In order to indicate which proof steps of the previous round were responsible for which [force]d assumptions, we print a sentence explaining the origins of each newly [force]d goal. For example, [1]Subgoal 1, below, will focus on (GOOD-INPUTP (XTRANS I)), which was forced in Subgoal 14, above, by applying (:REWRITE PRED-CRUNCHER) to (PRED (XTRANS I) I), and Subgoal 28, above, by applying (:REWRITE PRED-CRUNCHER) to (PRED (XTRANS I) I). In this entry, ``[1]Subgoal 1'' is the name of a goal which will be proved in the next forcing round. On the next line we display the [force]d hypothesis, call it [47mx[0m, which is [47m(good-inputp (xtrans i))[0m in this example. This term will be the conclusion of the new subgoal. Since the new subgoal will be printed in its entirety when its proof is undertaken, we do not here exhibit the context in which [47mx[0m was [force]d. The sentence then lists (possibly a succession of) a goal name from the just-completed round and some step in the proof of that goal that [force]d [47mx[0m. In the example above we see that Subgoals 14 and 28 of the just-completed proof [force]d [47m(good-inputp (xtrans i))[0m by applying [47m(:rewrite pred-cruncher)[0m to the term [47m(pred (xtrans i) i)[0m. If one were to inspect the theorem prover's description of the proof steps applied to Subgoals 14 and 28 one would find the word ``[force]d'' (or sometimes ``forcibly'') occurring in the commentary. Whenever you see that word in the output, you know you will get a subsequent forcing round to deal with the hypotheses [force]d. Similarly, if at the beginning of a forcing round a [rune] is blamed for causing a [force] in some subgoal, inspection of the commentary for that subgoal will reveal the word ``[force]d'' after the rule name blamed. Most [force]d hypotheses come from within the prover's simplifier. When the simplifier encounters a hypothesis of the form [47m(force hyp)[0m it first attempts to establish it by rewriting [47mhyp[0m to, say, [47mhyp'[0m. If the truth or falsity of [47mhyp'[0m is known, forcing is not required. Otherwise, the simplifier actually [force]s [47mhyp'[0m. That is, the [47mx[0m mentioned above is [47mhyp'[0m, not [47mhyp[0m, when the [force]d subgoal was generated by the simplifier. Once the system has printed out the origins of the newly [force]d goals, it proceeds to the next forcing round, where those goals are individually displayed and attacked. At the beginning of a forcing round, the [enable]d structure defaults to the global [enable]d structure. For example, suppose some [rune], [47mrune[0m, is globally [enable]d. Suppose in some event you [disable] the [rune] at [47m"Goal"[0m and successfully prove the goal but [force] [47m"[1]Goal"[0m. Then during the proof of [47m"[1]Goal"[0m, [rune] is [enable]d ``again.'' The right way to think about this is that the [rune] is ``still'' [enable]d. That is, it is [enable]d globally and each forcing round resumes with the global [enable]d structure.") (formals (pointers) "See [system-utilities].") (formula (history world acl2-built-ins) "The formula of a name or [rune] The ACL2 system function, [47mformula[0m, returns the [term] associated with a given [rune] or symbolic name, returning [47mnil[0m if there is no such term. Note that a non-[47mnil[0m result will be an ACL2 ``translated'' term (see [term]). Most ACL2 users probably will have no reason to know about this function. But here we document this function for those who write system-level tools, since they might find this interface to the ACL2 logical [world] to be useful. When ACL2 is given a [47m:use[0m or [47m:by[0m hint, it looks for the [term] stored in the ACL2 logical [world] that is associated with the name given in the hint, which is a symbol or a [rune]. (See [lemma-instance].) The utility used to find that term is [47mformula[0m, which ACL2 invokes as follows. (formula x t wrld) ; for :use hints (formula x nil wrld) ; for :by hints The second argument can affect whether or not to use a normalized version of the term (in particular, a definition body) associated with [47mx[0m; see [normalize]. The value is [47mt[0m for [47m:use[0m [hints] because normalizing a term simplifies it, which is often desirable. But for a [47m:by[0m hint, the non-normalized version of the term is used in order to increase the chance that the necessary subsumption test will succeed. Even if the second argument is [47mt[0m, normalization might not take place. In the unlikely case that you need to know more precisely the effect of supplying [47mt[0m, see the source code for [47mformula[0m. Here are some examples. Note that [47m(w state)[0m returns the current ACL2 logical [world]. First let us submit a few [events]. (defun f1 (x) (cons 3 x)) (defun f2 (x y) (implies x y)) (defthm one-rule (and (equal (* 2 y) (+ y y)) (equal (* 3 y) (+ y y y)))) (defthm two-rules t :rule-classes ((:rewrite :corollary (equal (* 2 y) (+ y y))) (:rewrite :corollary (equal (* 3 y) (+ y y y))))) Then: ACL2 !>(formula 'f1 nil (w state)) (EQUAL (F1 X) (CONS '3 X)) ACL2 !>(formula 'f1 t (w state)) (EQUAL (F1 X) (CONS '3 X)) ACL2 !>(formula 'f2 nil (w state)) (EQUAL (F2 X Y) (IMPLIES X Y)) ACL2 !>(formula 'f2 t (w state)) (EQUAL (F2 X Y) (IF X (IF Y 'T 'NIL) 'T)) ACL2 !>(formula 'one-rule nil (w state)) (IF (EQUAL (BINARY-* '2 Y) (BINARY-+ Y Y)) (EQUAL (BINARY-* '3 Y) (BINARY-+ Y (BINARY-+ Y Y))) 'NIL) ACL2 !>(equal (formula 'one-rule nil (w state)) (formula 'one-rule t (w state))) T ACL2 !>(formula 'two-rules nil (w state)) 'T ACL2 !>(formula 'two-rules t (w state)) 'T ACL2 !>(formula '(:rewrite two-rules . 1) nil (w state)) (EQUAL (BINARY-* '2 Y) (BINARY-+ Y Y)) ACL2 !>(formula '(:rewrite two-rules . 2) nil (w state)) (EQUAL (BINARY-* '3 Y) (BINARY-+ Y (BINARY-+ Y Y))) ACL2 !>(formula 'no-such-rule nil (w state)) NIL ACL2 !>") (forward-chaining (rule-classes) "Make a rule to forward chain when a certain trigger arises See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Examples: (defthm p-and-r-forward ; When (p a) appears in a formula to be (implies (and (p x) (r x)) ; simplified, try to establish (p a) and (q (f x))) ; (r a) and, if successful, add (q (f a)) :rule-classes :forward-chaining) ; to the known assumptions. (defthm p-and-r-forward ; as above with most defaults filled in (implies (and (p x) (r x)) (q (f x))) :rule-classes ((:forward-chaining :trigger-terms ((p x)) :corollary (implies (and (p x) (r x)) (q (f x))) :match-free :all))) To specify the triggering terms provide a non-empty list of terms as the value of the [47m:trigger-terms[0m field of the rule class object. General Form: Any theorem, provided an acceptable triggering term exists. The structure of this documentation is as follows. First we give a brief overview of forward chaining and contrast it to backchaining (rewriting). Then we lay out the syntactic restrictions on [47m:forward-chaining[0m rules. Then we give more details about the process and point to a tool to assist you in debugging your [47m:forward-chaining[0m rules. [3mOverview and When to Use Forward Chaining[0m Forward chaining is performed as part of the simplification process: before the goal is rewritten a [3mcontext[0m is established. The context tells the theorem prover what may be assumed during rewriting, in particular, to establish hypotheses of rewrite rules. Forward chaining is used to extend the context before rewriting begins. For example, the [47m:forward-chaining[0m rule [47m(implies (p x) (p1 x))[0m would add [47m(p1 A)[0m to the context, where [47mA[0m is some term, if [47m(p A)[0m is already in the context. Forward chaining and backchaining are duals. If a rewrite rule requires that [47m(p1 A)[0m be established and [47m(p A)[0m is known, it could be done either by making [47m(implies (p x) (p1 x))[0m a [47m:forward-chaining[0m rule or a [47m:rewrite[0m rule. Which should you choose? As a rule of thumb, if a conclusion like [47m(p1 A)[0m is expected to be widely needed, it is better to derive it via forward chaining because then it is available ``for free'' during the rewriting after paying the one-time cost of forward chaining. Alternatively, if [47m(p1 A)[0m is a rather special hypothesis of key importance to only a few rewrite rules, it is best to derive it only when needed through backchaining. Thus forward chaining is pro-active and backward chaining (rewriting) is reactive. The following example illustrates that forward chaining may be indispensable in a scenario with [free-variables], whose handling is quite weak with rewrite rules. (defstub p0 (x) t) (defstub p1 (x) t) (defstub p2 (y) t) (defaxiom p0-implies-p1 (implies (p0 x) (p1 x)) :rule-classes :forward-chaining) (defaxiom p1-implies-p2 (implies (p1 x) (p2 y))) ; ACL2 proves the following, but only because p0-implies-p1 is a ; :forward-chaining rule. If p0-implies-p1 is instead a :rewrite ; rule, then the proof fails for the following event. (thm (implies (p0 x) (p2 y))) [3mSyntactic Restrictions[0m Forward chaining rules are generated from the corollary term (see [rule-classes]) as follows. First, every [47m[let][0m expression is expanded away (hence, so is every [47m[let*][0m and [47m[lambda][0m expression), and trivial ``guard holders'' are removed; see [guard-holders]. If the resulting term has the form [47m(implies hyp concl)[0m, then [47mconcl[0m is treated as a conjunction, with one forward chaining rule with hypothesis [47mhyp[0m created for each conjunct. In the other case, where the corollary term is not an [47m[implies][0m, we process it as we process the conclusion in the first case. Note that unlike rewrite rules, a nested implication is not folded into a single implication. Consider for example the following term. (implies (p1 x) (implies (p2 x) (p3 x))) Although this term is parsed for a rewrite rule as [47m(implies (and (p1 x) (p2 x)) (p3 x))[0m, that is not the case when this term is parsed for a forward-chaining rule, in which case [47m(p1 x)[0m is treated as the hypothesis and [47m(implies (p2 x) (p3 x))[0m is treated as the conclusion. The [47m:trigger-terms[0m field of a [47m:forward-chaining[0m rule class object should be a non-empty list of terms, if provided, and should have certain properties described below. If the [47m:trigger-terms[0m field is not provided, it defaults to the singleton list containing the ``atom'' of the first hypothesis of the formula. (The atom of [47m(not x)[0m is [47mx[0m; the atom of any other term is the term itself.) If there are no hypotheses and no [47m:trigger-terms[0m were provided, an error is caused. A triggering term is acceptable if it is not a variable, a quoted constant, a lambda application, a [47m[let][0m- (or [47m[let*][0m-) expression, or a [47m[not][0m-expression, and every variable symbol in the conclusion of the theorem either occurs in the hypotheses or occurs in the trigger. [3mMore Details about Forward Chaining[0m [47m:Forward-chaining[0m rules are used by the simplifier [3mbefore[0m it begins to rewrite the literals of the goal. (Forward chaining is thus carried out from scratch for each goal.) If any term in the goal is an instance of a trigger of some forward chaining rule, we try to establish the hypotheses of that forward chaining theorem (from the negation of the goal). To relieve a hypothesis we only use type reasoning (see [TYPE-REASONING]), evaluation of ground terms, and presence among our known assumptions. We do not use rewriting. So-called free variables in hypotheses are treated specially; see [free-variables]. If all hypotheses are relieved, and certain heuristics approve of the newly derived conclusion, we add the instantiated conclusion to our known assumptions. Since this might introduce new terms into the assumptions, forward chaining is repeated. Heuristic approval of each new addition is necessary to avoid infinite looping as would happen with the rule [47m(implies (p x) (p (f x)))[0m, which might otherwise forward chain from [47m(p A)[0m to [47m(p (f A))[0m to [47m(p (f (f A)))[0m, etc. [3mCaution[0m. Forward chaining does not actually add terms to the goals displayed during proof attempts. Instead, it extends an associated [3mcontext[0m, called ``assumptions'' in the preceding paragraph, that ACL2 builds from the goal currently being proved. (For insiders: forward chaining extends the [47m[type-alist][0m.) The context starts out with ``obvious'' consequences of the negation of the goal. For example, if the goal is (implies (and (p A) (q (f A))) (c A)) then the context notes that [47m(p A)[0m and [47m(q (f A))[0m are non-[47mnil[0m and [47m(c A)[0m is [47mnil[0m. Forward chaining is then used to expand the context. For example, if a forward chaining rule has [47m(f x)[0m as a trigger term and has body [47m(implies (p x) (r (f x)))[0m, then the context is extended by binding [47m(r (f A))[0m to non-[47mnil[0m, provided the heuristics approve of this extension. Note however that since [47m(r (f A))[0m is put into the context, not the goal, you will not see it in the goal formula. Furthermore, the assumption added to the context is just the instantiation of the conclusion of the rule, with no simplification or rewriting applied. Thus, for example, if it contains an enabled non-recursive function symbol it is unlikely ever to match a (rewritten) term arising during subsequent simplification of the goal. However, forward-chaining does support the linear arithmetic reasoning package. For example, suppose that forward-chaining puts [47m(< (f x) (g x))[0m into the context. Then this inequality also goes into the linear arithmetic database, together with suitable instances of linear lemmas whose trigger term is a call of [47mg[0m. See [linear]. Debugging [47m:forward-chaining[0m rules can be difficult since their effects are not directly visible on the goal being simplified. Tools are available to help you discover what forward chaining has occurred see [forward-chaining-reports]. Subtopics [Case-split] Like force but immediately splits the top-level goal on the hypothesis [Forward-chaining-reports] To see reports about the forward chaining process") (forward-chaining-reports (forward-chaining debugging) "To see reports about the forward chaining process Debugging forward-chaining rules can be hard because their effects are not directly visible on the goal. In this documentation we tell you how to get reports on the forward chaining activity occurring in your proof attempts. This documentation is written in several parts. The first part is an introduction for the first-time user of forward chaining reports. The next two parts describe how to read reports. The last part describes how to monitor forward chaining activity only for selected runes, etc. We recommend the new user of these reports read everything! [3mA Quick Introduction to Forward Chaining Reports[0m Caution: The reporting mechanism maintains some state, and if you have already used forward chaining reporting in a session, the directions below may not work as advertised! To return to the default forward chaining reporting state, execute this form at the top level: (reset-fc-reporting) You can get a report about all forward chaining activity in subsequent proofs by doing: (set-fc-criteria t) Options will be discussed later that allow you to monitor the activity caused by particular [47m:forward-chaining[0m rules or terms. Then do a proof that is expected to cause some forward chaining. In the proof output you will see lines like this: (Forward Chaining on behalf of PREPROCESS-CLAUSE: (FC-Report 1)) This is the only difference you should see in the proof output. After the proof attempt has terminated, you can execute: (fc-report k) for any [47mk[0m printed during the immediately preceding proof attempt. That will print a much longer report describing the activity that occurred during the [47mk[0mth use of forward chaining in that proof attempt. If you want to see these reports in real time (embedded in the proof output), do this before invoking the prover: (set-fc-report-on-the-fly t) Collecting the data used to generate these reports slows down the prover. If you no longer wish to see such reports, do (set-fc-criteria nil) [3mHow To Read FC Reports[0m The report printed by [47m(fc-report k)[0m is of the form: Forward Chaining Report [3mk[0m: Caller: [3mtoken[0m Clause: ([3mlit1[0m [3mlit2[0m ... [3mlitn[0m) Number of Rounds: [3mm[0m Contradictionp: [3mbool[0m Activations: ([3mact1[0m [3mact2[0m ...) This report means that the [3mk[0mth use of forward chaining in the most recent proof attempt was done on behalf of [3mtoken[0m (see below). The initial context (set of assumptions) consisted of the negations of the literals listed in the [clause] shown and the initial candidate trigger terms are all those appearing in that clause. This invocation of forward chaining proceeded to do [3mm[0m rounds of successive extensions of the initial context and ultimately either reached a contradiction ([3mbool[0m = [47mT[0m) or returned an extended context ([3mbool[0m = [47mNIL[0m). Note that reaching a contradiction from the negations of all the literals in a clause is ``good'' because it means the clause is true. The report concludes with the final status of all the forward chaining rules fired during the process. We explain how to read one of these activation reports in the next section. Forward chaining is done on behalf of many proof techniques in the system. Each is associated with a [3mtoken[0m. The main proof technique that uses forward chaining is [47mSIMPLIFY-CLAUSE[0m. This is the call of forward chaining that sets up the context used by the rewriter to relieve hypotheses during backchaining. Another common caller of forward chaining is [47mPREPROCESS-CLAUSE[0m, the first process in the ACL2 waterfall (see [hints-and-the-waterfall]). Forward chaining often proves ``near propositional'' goals (those depending just on boolean implications between basic predicates). Other tokens you may see include [47mINDUCT[0m, which uses forward chaining to set up a context for applying [47m:[0m[47m[induction][0m rules, and the definitional principle (and related utilities such as [47m[verify-termination][0m and [47m[verify-guards][0m) which uses forward chaining during the construction of both measure conjectures and guard conjectures. When used this way, the [3mtoken[0m is [47mdefun-or-guard-verification[0m. [3mHow to Read Activation Reports[0m The forward chaining report concludes with a list of activation reports. Activations: ([3mact1[0m [3mact2[0m ...) Each [3macti[0m is of the form: ([3mrune[0m (:TRIGGER [3minst-trig[0m) ((:UNIFY-SUBST [3msubst[0m) (:DISPOSITION [3moutcome-part1[0m [3moutcome-part2[0m [3minst-term[0m)) ...) where the [47m...[0m indicates that the rest of the report consists of more of those tuples listing a [47m:UNIFY-SUBST[0m and [47m:DISPOSITION[0m. We call each tuple a [3mdisposition[0m of the activation and each disposition describes a substitution [3msubst[0m identifying the final instantiation of the rule and how the activation fared. Suppose there are [3mn[0m dispositions. (If the rule in question contains no free variables, [3mn[0m will be 1.) This activation report means that during the forward chaining process in question, the [47m:[0m[47m[forward-chaining][0m [rune] [3mrune[0m was fired due to the presence in the evolving context of the trigger term [3minst-trig[0m. (Note that [3minst-trig[0m is an instantiation of the trigger term of the named rule. That is, the variable symbols you see in [3minst-trig[0m are those of the clause printed in the forward chaining report.) The activation of [3mrune[0m by [3minst-trig[0m proceeded to split [3mn[0m ways as different choices were made for the [free-variables] occurring among the hypotheses. Each of those [3mn[0m choices gave rise to a different substitution [3msubst[0m, and each succeeded or failed as described by the corresponding [47m:DISPOSITION[0m. The [47m:DISPOSITION[0m of an activation is described in three parts, [3moutcome-part1[0m, [3moutcome-part2[0m, and [3minst-term[0m. [3mOutcome-part1[0m is either [47mSUCCESS[0m or [47mBLOCKED[0m, meaning that the instance given by [3msubst[0m either succeeded in the sense that all of its instantiated hypotheses were found in the context, or failed because some instantiated hypothesis was not found. If [47moutcome-part1[0m is [47mSUCCESS[0m then [3minst-term[0m is the instantiated conclusion produced by the rule. [3mOutcome-part2[0m is [47mAPPROVED[0m if the instantiated conclusion was acceptable to our heuristics designed to prevent looping and not already known in the evolving context. [3mOutcome-part2[0m is [47mREJECTED[0m if the instantiated conclusion was not approved by our heuristics. [3mOutcome-part2[0m is [47mREDUNDANT[0m if the instantiated conclusion was approved by the heuristics but already known true in the current evolving context. If [47mAPPROVED[0m, the truth of the instantiated conclusion is added to the evolving context. Otherwise, it is not. If [47moutcome-part1[0m is [47mBLOCKED[0m then [47moutcome-part2[0m is one of three possible things: [47mFALSE[0m, in which case [3minst-term[0m is an instantiated hypothesis of the rule that is assumed false in the current context, [47mUNRELIEVED-HYP[0m, in which case [3minst-term[0m is an instantiated hypothesis whose truth value is not determined by the context, or [47mUNRELIEVED-HYP-FREE[0m, in which case [3minst-term[0m is an oddly instantiated hypothesis whose truth value is not determined by the context and which also contains free variables. In the last case, the ``odd'' instantiation was by the substitution [3msubst[0m but extended so that free variables in the hypothesis are renamed to start with the prefix [47mUNBOUND-FREE-[0m to draw your attention to them. Note: All of the terms printed in the report are instantiated with the relevant unifying substitution (possibly extended to bind free variables). [3mSpecifying the Tracking Criteria[0m During a proof attempt, the forward chaining module stores information about the activations satisfying certain criteria. The [3mcriteria[0m is a list of triples. Each triple consists of a forward chaining rune, an instantiated trigger term, and an instantiated conclusion to watch for. However, any or all of the components of such a triple may be [47mt[0m and that is given special significance. An activation [47msatisfies[0m a criteria if it satisfies at least one of the triples. An activation satisfies a triple if it satisfies all three of the components. Every activation satisfies the component [47mt[0m. An activation satisfies a rune if the activation describes a firing of the named rule. An activation satisfies an instantiated trigger term if the activation was created by that trigger being present in the context. An activation satisfies an instantiated conclusion if the activation [3mcould[0m produce the instantiated conclusion (with the right choice of any free variables). Thus, the criteria is interpreted as a disjunction of conjunctions, making it possible to track a specific set of runes, triggers, and conclusions. For example, here is a triple that might appear in the criteria: ((:FORWARD-CHAINING ALISTP-FORWARD-TO-TRUE-LISTP) t t). This triple would cause every activation of the given rule to be tracked. However, the triple ((:FORWARD-CHAINING ALISTP-FORWARD-TO-TRUE-LISTP) (ALISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S)))) t) would only track activations of that rule fired by the specific term shown as the second element of the triple. Furthermore (t (ALISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S)))) t) would track any forward chaining rule triggered by that term, and (t t (TRUE-LISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S))))) would track any rule fired by any trigger that might lead to the specific term given as the third component above. Note: The condition on how an activation satisfies an instantiated conclusion is a little subtle. Consider the activation of the forward chaining rule (implies (and (symbol-listp x) (equal (len x) (len y))) (true-listp (make-bindings x y))) triggered by [47m(SYMBOL-LISTP VARS)[0m arising in the current context. This activation [3mcould[0m produce the specific conclusion shown in the last triple above, if it just happened that [47m(TOP-N (OP1 INST) (STACK S))[0m were chosen as the binding of the free variable [47my[0m. Thus, the activation of this rule triggered by [47m(SYMBOL-LISTP VARS)[0m satisfies the last triple above. Observe that the triple (t t t) is satisfied by every activation of any rule by any trigger term producing any conclusion. The function [47mset-fc-criteria[0m sets the criteria describing which activations are to be tracked. For example, if you execute: (set-fc-criteria ((:FORWARD-CHAINING LEMMA1) t t) ((:FORWARD-CHAINING LEMMA2) (ALISTP (BASIC-MAPPER A B)) t) (t t (TRUE-LISTP (DLT D)))), the system would track all activations of the forward-chaining rule [47mLEMMA1[0m, plus those activations of forward-chaining rule [47mLEMMA2[0m triggered by the term given in the second triple, plus any activation of any rule that might derive [47m(TRUE-LISTP (DLT D))[0m. Because criteria generally mention variable symbols used in a specific conjecture, it is probably best to reconsider your criteria every time you want to track forward chaining. If the criteria is [47mnil[0m, then nothing is tracked. Setting the criteria to [47mnil[0m is the way you turn off tracking and reporting of forward chaining activity. You may do this either by [47m(set-fc-criteria)[0m or by [47m(set-fc-criteria nil)[0m. (Technically the second form is an odd use of [47mset-fc-criteria[0m, which expects any supplied arguments to be triples; if the ``triple'' [47mnil[0m is the only one supplied, we take it to mean that the entire criteria should be [47mnil[0m.) To track every forward chaining activation you may set the criteria with either [47m(set-fc-criteria (t t t))[0m or use the abbreviation [47m(set-fc-criteria t)[0m. If, when you read a forward chaining report, you see no mention of an activation you have in mind, e.g., of a certain rune or deriving a certain conclusion, and you have set the criteria correctly, then the activation never happened. (This is akin to using [47m:[0m[47m[brr][0m and [47m:[0m[47m[monitor][0m to monitor the application of a rewrite rule and then seeing no interactive break.) For some relevant functions to help you manage criteria and when the full reports are printed see [47m[fc-report][0m, [47m[show-fc-criteria][0m, [47m[set-fc-criteria][0m, [47m[reset-fc-reporting][0m, and [47m[set-fc-report-on-the-fly][0m. Subtopics [Fc-report] To report on the forward chaining activity in the most recent proof [Reset-fc-reporting] Reset the forward-chaining tracking state to its initial configuration [Set-fc-criteria] To set the tracking criteria for forward chaining reports [Set-fc-report-on-the-fly] To determine when forward-chaining reports are printed [Show-fc-criteria] Print the forward-chaining tracking criteria") (fourth (nth acl2-built-ins) "Fourth member of the list See any Common Lisp documentation for details.") (fp (df) "Floating-point and ACL2 ACL2 supports computation that uses floating-point operations; see [df]. If you are using an older Lisp, an attempt to build ACL2 may fail with an error complaining that ``feature :ieee-floating-point is missing'' [from the Lisp's [47m*features*[0m]. [31;1mTHIS ERROR INDICATES THAT ACL2 MAY BE UNSOUND WHEN BUILT ON THAT LISP![0m If however you believe that your Lisp properly supports IEEE floating-point operations even though that feature is missing (e.g., quite possibly with older versions of CCL), you can avoid that build-time error by setting environment variable [47mACL2_FP_OK[0m to any non-empty string. You might want to do that in a script that invokes your Lisp.") (fquotep (pointers) "See [system-utilities].") (free-variables (rule-classes rewrite) "Free variables in rules As described elsewhere (see [rule-classes]), ACL2 rules are treated as implications for which there are zero or more hypotheses [47mhj[0m to prove. In particular, rules of class [47m:[0m[47m[rewrite][0m may look like this: (implies (and h1 ... hn) (fn lhs rhs)) Variables of [47mhi[0m are said to occur [3mfree[0m in the above [47m:rewrite[0m rule if they do not occur in [47mlhs[0m or in any [47mhj[0m with [47mj<i[0m. (To be precise, here we are only discussing those variables that are not in the scope of a [47m[let][0m/[47m[let*][0m/[47mlambda[0m that binds them.) We also refer to these as the [3mfree variables[0m of the rule. ACL2 may issue a warning or error when there are free variables in a rule, as described below. (Variables of [47mrhs[0m may be considered free if they do not occur in [47mlhs[0m or in any [47mhj[0m. But we do not consider those in this discussion.) In general, the [3mfree variables[0m of rules are those variables occurring in their hypotheses (not [47m[let][0m/[47m[let*][0m/[47mlambda[0m-bound) that are not bound when the rule is applied. For rules of class [47m:[0m[47m[linear][0m and [47m:[0m[47m[forward-chaining][0m, variables are bound by a trigger term. (See [rule-classes] for a discussion of the [47m:trigger-terms[0m field). For rules of class [47m:[0m[47m[type-prescription][0m, variables are bound by the [47m:typed-term[0m field. See [free-variables-examples] for more examples of how this all works, including illustration of how the user can exercise some control over it. In particular, see [free-variables-examples-rewrite] for an explanation of output from the [break-rewrite] facility in the presence of rewriting failures involving free variables, as well as an example exploring ``binding hypotheses'' as described below. Let us discuss the method for relieving hypotheses of [rewrite] rules with free variables. Similar considerations apply to [linear] and [forward-chaining] rules, and [type-prescription] rules. Note that the [47m:match-free[0m mechanism discussed below does not apply to [type-prescription] rules. See [free-variables-type-prescription] for a discussion of how to control free-variable matching for [type-prescription] rules. We begin with an example. Does the proof of the [47m[thm][0m below succeed? (defstub p2 (x y) t) (defaxiom p2-trans (implies (and (p2 x y) (p2 y z)) (equal (p2 x z) t)) :rule-classes ((:rewrite :match-free :all))) (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) Consider what happens when the proof of the [47mthm[0m is attempted. The ACL2 rewriter attempts to apply rule [47mp2-trans[0m to the conclusion, [47m(p2 a d)[0m. So, it binds variables [47mx[0m and [47mz[0m from the left-hand side of the conclusion of [47mp2-trans[0m to terms [47ma[0m and [47md[0m, respectively, and then attempts to relieve the hypotheses of [47mp2-trans[0m. The first hypothesis of [47mp2-trans[0m, [47m(p2 x y)[0m, is considered first. Variable [47my[0m is free in that hypothesis, i.e., it has not yet been bound. Since [47mx[0m is bound to [47ma[0m, the rewriter looks through the context for a binding of [47my[0m such that [47m(p2 a y)[0m is true, and it so happens that it first finds the term [47m(p2 a b)[0m, thus binding [47my[0m to [47mb[0m. Now it goes on to the next hypothesis, [47m(p2 y z)[0m. At this point [47my[0m and [47mz[0m have already been bound to [47mb[0m and [47md[0m; but [47m(p2 b d)[0m cannot be proved. So, in order for the proof of the [47m[thm][0m to succeed, the rewriter needs to backtrack and look for another way to instantiate the first hypothesis of [47mp2-trans[0m. Because [47m:match-free :all[0m has been specified, backtracking does take place. This time [47my[0m is bound to [47mc[0m, and the subsequent instantiated hypothesis becomes [47m(p2 c d)[0m, which is true. The application of rule [47m(p2-trans)[0m succeeds and the theorem is proved. If instead [47m:match-free :all[0m had been replaced by [47m:match-free :once[0m in rule [47mp2-trans[0m, then backtracking would not occur, and the proof of the [47m[thm][0m would fail. Next we describe in detail the steps used by the rewriter in dealing with free variables. The ACL2 rewriter uses the following sequence of steps to relieve a hypothesis with free variables, except that steps (1) and (3) are skipped for [47m:forward-chaining[0m rules and step (3) is skipped for [47m:type-prescription[0m rules. First, if the hypothesis is of the form [47m(force hyp0)[0m or [47m(case-split hyp0)[0m, then replace it with [47mhyp0[0m. (1) Suppose the hypothesis has the form [47m(equiv var term)[0m where [47mvar[0m is free and no variable of [47mterm[0m is free, and either [47mequiv[0m is [47m[equal][0m or else [47mequiv[0m is a known [equivalence] relation and [47mterm[0m is a call of [47m[double-rewrite][0m. We call this a ``binding hypothesis.'' Then bind [47mvar[0m to the result of rewriting [47mterm[0m in the current context. (2) Look for a binding of the free variables of the hypothesis so that the corresponding instance of the hypothesis is known to be true in the current context. (3) Search all [47m[enable][0md, hypothesis-free rewrite rules of the form [47m(equiv lhs rhs)[0m, where [47mlhs[0m has no variables (other than those bound by [47m[let][0m, [47m[let*][0m, or [47mlambda[0m), [47mrhs[0m is known to be true in the current context, and [47mequiv[0m is typically [47mequal[0m but can be any equivalence relation appropriate for the current context (see [congruence]); then attempt to bind the free variables so that the instantiated hypothesis is [47mlhs[0m. For cases (2) and (3), the first instance found may ultimately fail because the remaining hypotheses are not all relieved under the extended bindings. In that case, should the attempt to relieve hypotheses fail, or should the search continue to find other instances for (2) or (3)? The answer depends on which of two options is in force for the so-called ``match-free'' of the rule. Below we discuss how to specify these two options as ``[47m:once[0m'' or ``[47m:all[0m'' (the default), respectively. Suppose that the original hypothesis is a call of [47m[force][0m or [47m[case-split][0m, where forcing is enabled (see [enable-forcing]) . Also suppose that one of the following two cases applies: no instances are found for (2) and also none for (3), or else the ``match-free'' option for the rule is [47m:all[0m (as discussed below) and all attempts ultimately fail for (2) and (3) (because the remaining hypotheses are not all relieved). Then the current hypothesis is relieved but in the resulting split-off goals, all free variables are bound to unusual names that call attention to this odd situation. Is it better to specify [47m:once[0m or [47m:all[0m? We believe that [47m:all[0m is generally the better choice because of its greater power, provided the user does not introduce a large number of rules with free variables, which has been known to slow down the prover due to combinatorial explosion in the search (Steps (2) and (3) above). Either way, it is good practice to put the ``more substantial'' hypotheses first, so that the most likely bindings of free variables will be found first (in the case of [47m:all[0m) or found at all (in the case of [47m:once[0m). For example, a rewrite rule like (implies (and (p1 x y) (p2 x y)) (equal (bar x) (bar-prime x))) may never succeed if [47mp1[0m is nonrecursive and enabled, since we may well not find calls of [47mp1[0m in the current context. If however [47mp2[0m is disabled or recursive, then the above rule may apply if the two hypotheses are switched. For in that case, we can hope for a match of [47m(p2 x y)[0m in the current context that therefore binds [47mx[0m and [47my[0m; then the rewriter's full power may be brought to bear to prove [47m(p1 x y)[0m for that [47mx[0m and [47my[0m. Moreover, the ordering of hypotheses can affect the efficiency of the rewriter. For example, the rule (implies (and (rationalp y) (foo x y)) (equal (bar x) (bar-prime x))) may well be sub-optimal. Presumably the intention is to rewrite [47m(bar x)[0m to [47m(bar-prime x)[0m in a context where [47m(foo x y)[0m is explicitly known to be true for some rational number [47my[0m. But [47my[0m will be bound first to the first term found in the current context that is known to represent a rational number. If the 100th such [47my[0m that is found is the first one for which [47m(foo x y)[0m is known to be true, then wasted work will have been done on behalf of the first 99 such terms [47my[0m --- unless [47m:once[0m has been specified, in which case the rule will simply fail after the first binding of [47my[0m for which [47m(rationalp y)[0m is known to be true. Thus, a better form of the above rule is almost certainly the following. (implies (and (foo x y) (rationalp y)) (equal (bar x) (bar-prime x))) [3mSpecifying `once' or `all'.[0m As noted above, the following discussion applies only to [rewrite], [linear], and [forward-chaining] rules. See [free-variables-type-prescription] for a discussion of analogous considerations for [type-prescription] rules. One method for specifying [47m:once[0m or [47m:all[0m for free-variable matching is to provide the [47m:match-free[0m field of the [47m:rule-classes[0m of the rule, for example, [47m(:rewrite :match-free :all)[0m. See [rule-classes]. However, there are global events that can be used to specify [47m:once[0m or [47m:all[0m; see [set-match-free-default] and see [add-match-free-override]. Here are some examples. (set-match-free-default :once) ; future rules without a :match-free field ; are stored as :match-free :once (but this ; behavior is local to a book) (add-match-free-override :once t) ; existing rules are treated as ; :match-free :once regardless of their ; original :match-free fields (add-match-free-override :once (:rewrite foo) (:rewrite bar . 2)) ; the two indicated rules are treated as ; :match-free :once regardless of their ; original :match-free fields [3mSome history.[0m Before Version 2.7 the ACL2 rewriter performed Step (2) above first. More significantly, it always acted as though [47m:once[0m had been specified. That is, if Step (2) did not apply, then the rewriter took the first binding it found using either Steps (1) or (3), in that order, and proceeded to relieve the remaining hypotheses without trying any other bindings of the free variables of that hypothesis. Subtopics [Add-match-free-override] Set [47m:match-free[0m value to [47m:once[0m or [47m:all[0m in existing rules [Free-variables-examples] Examples pertaining to free variables in rules [Free-variables-type-prescription] Matching for free variable in [type-prescription] rules [Set-match-free-default] Provide default for [47m:match-free[0m in future rules [Set-match-free-error] Control error vs. warning when [47m:match-free[0m is missing") (free-variables-examples (free-variables) "Examples pertaining to free variables in rules The examples in the two sub-topics of this topic illustrate the handling of free variables in rules of class [47m:[0m[47m[rewrite][0m (see [free-variables-examples-rewrite]) and of class [47m:[0m[47m[forward-chaining][0m (see [free-variables-examples-forward-chaining]), respectively. These implicitly illustrate [free-variables] handling in rules of class [47m:[0m[47m[linear][0m as well. Also see [free-variables] and see [rule-classes]. Subtopics [Free-variables-examples-forward-chaining] Examples pertaining to free variables in [forward-chaining] rules [Free-variables-examples-rewrite] Examples pertaining to free variables in [rewrite] rules") (free-variables-examples-forward-chaining (free-variables-examples) "Examples pertaining to free variables in [forward-chaining] rules The following examples illustrate ACL2's handling of free variables in [forward-chaining] rules, as well as user control over how such free variables are handled. See [free-variables] for a background discussion. ; First let us introduce a transitive operation, op, and prove a ; forward-chaining rule stating the transitivity of op. (encapsulate (((op * *) => *)) (local (defun op (x y) (< x y))) (defthm transitivity-of-op (implies (and (op x y) (op y z)) (op x z)) :rule-classes :forward-chaining)) ; The following theorem is proved by forward chaining, using the above rule. (thm (implies (and (op u v) (op v w) (op v a)) (op u w))) ; The proof of the theorem just above succeeds because the term (op u v) ; triggers the application of forward-chaining rule transitivity-of-op, ; binding x to u and y to v. Free variable z of that rule is bound to both w ; and to a, resulting in the addition of both (op u w) and (op u a) to the ; context. However, (op v a) happens to be at the front of the context, so ; if only one free-variable binding had been allowed, then z would have only ; been bound to a, not to w, as we now illustrate. (add-match-free-override :once (:forward-chaining transitivity-of-op)) (thm ; FAILS! (implies (and (op u v) (op v w) (op v a)) (op u w))) :ubt! 1 ; Starting over, this time we prove transitivity-of-op as a :match-free :once ; forward-chaining rule. Note that the presence of :match-free eliminates ; the free-variables warning that we got the first time. (encapsulate (((op * *) => *)) (local (defun op (x y) (< x y))) (defthm transitivity-of-op (implies (and (op x y) (op y z)) (op x z)) :rule-classes ((:forward-chaining :match-free :once)))) (thm ; FAILS! (implies (and (op u v) (op v w) (op v a)) (op u w))) ; Notice that if we swap the order of the last two hypotheses the theorem ; goes through, because this time (op v w) is first in the context. (thm ; SUCCEEDS! (implies (and (op u v) (op v a) (op v w)) (op u w))) :u ; Now let's try setting the default to :once. (set-match-free-default :once) ; We still get a free-variables warning when we admit this forward-chaining rule. (encapsulate (((op * *) => *)) (local (defun op (x y) (< x y))) (defthm transitivity-of-op (implies (and (op x y) (op y z)) (op x z)) :rule-classes ((:forward-chaining)))) ; This theorem fails -- as it should. (thm ; FAILS! (implies (and (op u v) (op v w) (op v a)) (op u w))) ; But if we convert this rule (or here, all possible rules) to :all rules, ; then the proof succeeds. (add-match-free-override :all t) (thm ; SUCCEEDS! (implies (and (op u v) (op v w) (op v a)) (op u w))) ; Now let's test a relatively slow :all case (the next thm below). :ubt! 1 (encapsulate (((op1 *) => *) ((op3 * * *) => *)) (local (defun op1 (x) (declare (ignore x)) t)) (local (defun op3 (x0 x1 x2) (declare (ignore x0 x1 x2)) t)) (defthm op1-op3-property (implies (and (op1 x0) (op1 x1) (op1 x2)) (op3 x0 x1 x2)) :rule-classes ((:forward-chaining :match-free :all)))) ; The following succeeds, but takes a little time (about a second in one run). (thm (implies (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5) (op1 a6) (op1 a7) (op1 a8) (op1 a9) (op1 a10) (op1 a11) (op1 a12) (op1 a13) (op1 a14) (op1 a15) (op1 a16) (op1 a17) (op1 a18) (op1 a19) (op1 a20)) (op3 a5 a6 a0))) (add-match-free-override :once t) ; The same theorem now fails because of the add-match-free-override, but is ; more than an order of magnitude faster. (thm (implies (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5) (op1 a6) (op1 a7) (op1 a8) (op1 a9) (op1 a10) (op1 a11) (op1 a12) (op1 a13) (op1 a14) (op1 a15) (op1 a16) (op1 a17) (op1 a18) (op1 a19) (op1 a20)) (op3 a5 a6 a0))) ; A slight variant succeeds in a negligible amount of time (still with the ; :once override above). (thm (implies (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5) (op1 a6) (op1 a7) (op1 a8) (op1 a9) (op1 a10) (op1 a11) (op1 a12) (op1 a13) (op1 a14) (op1 a15) (op1 a16) (op1 a17) (op1 a18) (op1 a19) (op1 a20)) (op3 a5 a20 a20))) ; Reality check: This shouldn't give a free-variables warning, and everything ; should work great since there are no free variables with this trigger term. :ubt! 1 (encapsulate (((op1 *) => *) ((op7 * * * * * * *) => *)) (local (defun op1 (x) (declare (ignore x)) t)) (local (defun op7 (x0 x1 x2 x3 x4 x5 x6) (declare (ignore x0 x1 x2 x3 x4 x5 x6)) t)) (defthm op1-op7-property (implies (and (op1 x0) (op1 x1) (op1 x2) (op1 x3) (op1 x4) (op1 x5) (op1 x6)) (op7 x0 x1 x2 x3 x4 x5 x6)) :rule-classes ((:forward-chaining :trigger-terms ((op7 x0 x1 x2 x3 x4 x5 x6)))))) ; The following then succeeds, and very quickly. (thm (implies (and (op1 a0) (op1 a1) (op1 a2) (op1 a3) (op1 a4) (op1 a5) (op1 a6)) (op7 a4 a6 a5 a6 a6 a6 a6)))") (free-variables-examples-rewrite (free-variables-examples) "Examples pertaining to free variables in [rewrite] rules The following examples illustrate ACL2's handling of free variables in [rewrite] rules, as well as user control over how such free variables are handled. See [free-variables] for a background discussion. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Example 1 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defstub p2 (x y) t) ; introduce unconstrained function ; Get warning because of free variable. This would be an error if you had ; first executed (set-match-free-error t) in order to force yourself to ; specify :match-free (illustrated later, below). (defaxiom p2-trans (implies (and (p2 x y) (p2 y z)) (p2 x z))) ; Succeeds. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) ; The following causes an error because p2-trans is not a rune. (add-match-free-override :once p2-trans) ; After the following, the rewrite rule p2-trans will only allow one ; attempt per hypothesis to bind free variables. (add-match-free-override :once (:rewrite p2-trans)) ; Now this same theorem fails to be proved. Here's why. The ; context for proving (p2 a d) happens to include the hypotheses in ; reverse order. So when the first hypothesis of p2-trans, namely ; (p2 x y), is relieved, where x is bound to a (as we are attempting ; to rewrite the current literal (p2 a d)), we find (p2 a b) in the ; context before (p2 a c) and hence y is bound to b. The ; instantiated second hypothesis of p2-trans is thus (p2 b d), and ; the proof fails. Before the add-match-free-override form above, ; the proof succeeded because the rewriter was allowed to backtrack ; and find the other binding for the first hypothesis of p2-trans, ; namely, y bound to c. Then the instantiated second hypothesis of ; p2-trans is (p2 c d), which is known to be true in the current ; context. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) ; Return to original behavior for binding free variables. (add-match-free-override :all t) ; Succeeds once again. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) (u) ; undo (add-match-free-override :all t) ; This is an error, since no further arguments should appear after ; :clear. (add-match-free-override :clear t) ; Return all rules to original behavior for binding free variables, ; regardless of which previous add-match-free-override forms have ; been executed. (add-match-free-override :clear) ; This succeeds just as it did originally. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) (ubt! 'p2-trans) ; back to the start, except retain the defstub ; Require that :match-free be specified for :linear and :rewrite rules with ; free variables. (set-match-free-error t) ; Fails because :match-free is missing. (defaxiom p2-trans (implies (and (p2 x y) (p2 y z)) (p2 x z))) ; Fails because :match-free must be followed by :once or :all. (defaxiom p2-trans (implies (and (p2 x y) (p2 y z)) (p2 x z)) :rule-classes ((:rewrite :match-free nil))) ; Succeeds, this time with no warning at all. (defaxiom p2-trans (implies (and (p2 x y) (p2 y z)) (p2 x z)) :rule-classes ((:rewrite :match-free :once))) ; Fails because we only bind once (see earlier long comment). (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) ; Treat p2-trans as though `:match-free :all' had been specified. (add-match-free-override :all (:rewrite p2-trans)) ; Succeeds since more than one binding is allowed for p2-trans. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) (u) (u) ; Specify that future :linear and :rewrite rules with free variables ; that do not have :match-free specified are treated as though ; `:match-free :once' were specified. (set-match-free-default :once) ; Succeeds without error since `:match-free' is specified, as described ; above. But there is a warning, since :match-free is not specified for this ; :rewrite rule. (defaxiom p2-trans (implies (and (p2 x y) (p2 y z)) (p2 x z))) ; Fails since only single bindings are allowed for p2-trans. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) ; Treat p2-trans as though `:match-free :all' had been specified. (add-match-free-override :all t) ; Succeeds. (thm (implies (and (p2 a c) (p2 a b) (p2 c d)) (p2 a d))) ; Test searching of ground units, i.e. rewrite rules without variables on the ; left side of the conclusion, for use in relieving hypotheses with free ; variables. This is a very contrived example. (ubt! 1) ; back to the start (encapsulate (((p1 *) => *) ((p2 * *) => *) ((p3 *) => *) ((a) => *) ((b) => *)) (local (defun p1 (x) x)) (local (defun p2 (x y) (list x y))) (local (defun p3 (x) x)) (local (defun a () 0)) (local (defun b () 0))) ; Allow default of :match-free :all (form may be omitted). (set-match-free-error nil) (defaxiom ax1 (implies (and (p2 x y) (p1 y)) (p3 x))) (defaxiom p2-a-b (p2 (a) (b))) (defaxiom p2-a-a (p2 (a) (a))) (defaxiom p1-b (p1 (b))) ; Succeeds; see long comment below on next attempt to prove this ; theorem. (thm (implies (p2 (a) y) (p3 (a)))) ; Now ax1 will only relieve hypothesis (p2 x y) for one binding of y: (add-match-free-override :once t) ; Fails when ax1 attempts to rewrite the conclusion to true, because ; the most recent ground unit for hypothesis (p2 x y) with x bound ; to (a) is rule p2-a-a, which binds y to (a). If more than one ground ; unit could be used then we would backtrack and apply rule p2-a-b, ; which binds y to (b) and hence hypothesis (p1 y) of ax1 is ; relieved by rule p1-b. (thm (implies (p2 (a) y) (p3 (a)))) ; Return rules to original :match-free behavior. (add-match-free-override :clear) ; Succeeds once again. (thm (implies (p2 (a) y) (p3 (a)))) ; Just for kicks, change the behavior of a built-in rule irrelevant ; to the proof at hand. (add-match-free-override :once (:rewrite string<-l-trichotomy)) ; Still succeeds. (thm (implies (p2 (a) y) (p3 (a)))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Example 2 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; The next example illustrates the use of the [break-rewrite] facility to get information about handling of free variables by the rewriter. Explanation is given after this (edited) transcript. Input begins on lines with a prompt (search for ``ACL2''); the rest is output. ACL2 !>(encapsulate ((p1 (u x) t) (bad (x) t) (p2 (x y z) t) (bar (x y) t) (foo (x y) t) (poo (x y) t) (prop (u) t)) (local (defun p1 (u x) (declare (ignore u x)) nil)) (local (defun bad (x) (declare (ignore x)) nil)) (local (defun p2 (x y z) (declare (ignore x y z)) nil)) (local (defun bar (x y) (declare (ignore x y)) nil)) (local (defun foo (x y) (declare (ignore x y)) nil)) (local (defun poo (x y) (declare (ignore x y)) nil)) (local (defun prop (u) (declare (ignore u)) t)) (defthm foo-poo (implies (syntaxp (equal y 'y3)) (equal (foo x y) (poo x y)))) (defthm lemma-1 (implies (and (p1 u x) (bad x) (p2 x y z) (bar x y) (equal x x) ; admittedly silly! (foo x y)) (prop u)) :rule-classes ((:rewrite :match-free :all)))) ; [[ output omitted ]] Summary Form: ( ENCAPSULATE ((P1 ...) ...) ...) Rules: NIL Warnings: Subsume and Non-rec Time: 0.08 seconds (prove: 0.00, print: 0.01, other: 0.06) T ACL2 !>:brr t The monitored runes are: NIL T ACL2 !>:monitor (:rewrite lemma-1) t (((:REWRITE LEMMA-1) 'T)) ACL2 !>(thm (implies (and (p1 u0 x1) (bad x1) (bad x3) (bar x3 y1) (bar x3 y3) (p1 u0 x2) (p1 u0 x3) (p2 x3 y1 z1) (p2 x3 y3 z1)) (prop u0))) (1 Breaking (:REWRITE LEMMA-1) on (PROP U0): 1 ACL2 >:eval 1x (:REWRITE LEMMA-1) failed because :HYP 1 contains free variables. The following display summarizes the attempts to relieve hypotheses by binding free variables; see :DOC free-variables. [1] X : X1 Failed because :HYP 3 contains free variables Y and Z, for which no suitable bindings were found. [1] X : X2 Failed because :HYP 2 rewrote to (BAD X2). [1] X : X3 [3] Z : Z1 Y : Y1 Failed because :HYP 6 rewrote to (FOO X3 Y1). [3] Z : Z1 Y : Y3 Failed because :HYP 6 rewrote to (POO X3 Y3). 1 ACL2 >:unify-subst U : U0 1 ACL2 > The [47m:eval[0m command above asks the rewriter to attempt to apply the rewrite rule [47mlemma-1[0m to the term [47m(prop u0)[0m, shown just above the line with [47m:eval[0m. As we can see at the end, the variable [47mu[0m in the conclusion of [47mlemma-1[0m is being bound to the variable [47mu0[0m in the conjecture. The first hypothesis of [47mlemma-1[0m is [47m(p1 u x)[0m, so the rewriter looks for some [47mx[0m for which [47m(p1 u0 x)[0m is known to be true. It finds [47mx1[0m, and then goes on to consider the second hypothesis, [47m(bad x)[0m. Since the theorem we are proving has [47m(bad x1)[0m in the hypothesis and [47mx[0m is currently bound to [47mx1[0m, the rewriter is satisfied and moves on to the third hypothesis of [47mlemma-1[0m, [47m(p2 x y z)[0m. However, [47mx[0m is bound to [47mx1[0m and there are no instances of [47my[0m and [47mz[0m for which [47m(p2 x1 y z)[0m is known in the current context. All of the above analysis is summarized in the first part of the output from [47m:eval[0m above: [1] X : X1 Failed because :HYP 3 contains free variables Y and Z, for which no suitable bindings were found. Thus, the binding of [47mx[0m to [47mx1[0m on behalf of the first hypothesis has failed. The rewriter now backs up to look for other values of [47mx[0m that satisfy the first hypothesis, and finds [47mx2[0m because our current theorem has a hypothesis of [47m(p1 u0 x2)[0m. But this time, the second hypothesis of [47mlemma-1[0m, [47m(bad x)[0m, is not known to be true for [47mx[0m; that is, [47m(bad x2)[0m does not rewrite to [47mt[0m; in fact, it rewrites to itself. That explains the next part of the output from [47m:eval[0m above: [1] X : X2 Failed because :HYP 2 rewrote to (BAD X2). The rewriter now backs up again to look for other values of [47mx[0m that satisfy the first hypothesis, and finds [47mx3[0m because our current theorem has a hypothesis of [47m(p1 u0 x3)[0m. This time, the second hypothesis of [47mlemma-1[0m is not a problem, and moreover, the rewriter is able to bind [47my[0m and [47mz[0m to [47my1[0m and [47mz1[0m, respectively, in order to satisfy the third hypothesis, [47m(p2 x y z)[0m: that is, [47m(p2 x2 y1 z1)[0m is known in the current context. That explains more of the above output from [47m:eval[0m: [1] X : X3 [3] Z : Z1 Y : Y1 Unfortunately, the sixth hypothesis, [47m(foo x y)[0m, rewrites to itself under the above bindings: Failed because :HYP 6 rewrote to (FOO X3 Y1). So the rewriter looks for other bindings to satisfy the third hypothesis and finds these. [3] Z : Z1 Y : Y3 This time, the sixth hypothesis can be rewritten under the above bindings, from [47m(foo x3 y3)[0m to [47m(poo x3 y3)[0m by lemma [47mfoo-poo[0m, but still not to [47mt[0m. Failed because :HYP 6 rewrote to (POO X3 Y3). There are no more free variable bindings to try, so this concludes the output from [47m:eval[0m. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Example 3 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; The next pair of examples illustrates so-called ``binding hypotheses'' (see [free-variables]) and explores some of their subtleties. The first shows binding hypotheses in action on a simple example. The second shows how binding hypotheses interact with equivalence relations and explains the role of [47m[double-rewrite][0m. Our first example sets up a theory with two user-supplied rewrite rules, one of which has a binding hypothesis. Below we explain how that binding hypothesis contributes to the proof. ; Define some unary functions. (defun f (x) (declare (ignore x)) t) (defun g (x) x) (defun h (x) x) (defun k (x) x) ; Prove some simple lemmas. Note the binding hypothesis in g-rewrite. (defthm f-k-h (f (k (h x)))) (defthm g-rewrite (implies (and (equal y (k x)) ; binding hypothesis (f y)) (equal (g x) y))) ; Restrict to a theory that includes the above lemmas but avoids the above ; definitions. (in-theory (union-theories (theory 'minimal-theory) '(f-k-h g-rewrite))) ; Prove a theorem. (thm (equal (g (h a)) (k (h a)))) Let us look at how ACL2 uses the above binding hypothesis in the proof of the preceding [47mthm[0m form. The rewriter considers the term [47m(g (h a))[0m and finds a match with the left-hand side of the rule [47mg-rewrite[0m, binding [47mx[0m to [47m(h a)[0m. The first hypothesis binds [47my[0m to the result of rewriting [47m(k x)[0m in the current context, where the variable [47mx[0m is bound to the term [47m(h a)[0m; thus [47my[0m is bound to [47m(k (h a))[0m. The second hypothesis, [47m(f y)[0m, is then rewritten under this binding, and the result is [47mt[0m by application of the rewrite rule [47mf-k-h[0m. The rule [47mg-rewrite[0m is then applied under the already-mentioned binding of [47mx[0m to [47m(h a)[0m. This rule application triggers a recursive rewrite of the right-hand side of [47mg-rewrite[0m, which is [47my[0m, in a context where [47my[0m is bound (as discussed above) to [47m(k (h a))[0m. The result of this rewrite is that same term, [47m(k (h a))[0m. The original call of [47mequal[0m then trivially rewrites to [47mt[0m. We move on now to our second example, which is similar but involves a user-defined equivalence relation. You may find it helpful to review [47m:equivalence[0m rules; see [equivalence]. Recall that when a hypothesis is a call of an equivalence relation other than [47mequal[0m, the second argument must be a call of [47m[double-rewrite][0m in order for the hypothesis to be treated as a binding hypothesis. That is indeed the case below; an explanation follows. ; Define an equivalence relation. (defun my-equiv (x y) (equal x y)) (defequiv my-equiv) ; introduces rule MY-EQUIV-IS-AN-EQUIVALENCE ; Define some unary functions (defun f (x) (declare (ignore x)) t) (defun g (x) x) (defun h1 (x) x) (defun h2 (x) x) ; Prove some simple lemmas. Note the binding hypothesis in lemma-3. (defthm lemma-1 (my-equiv (h1 x) (h2 x))) (defthm lemma-2 (f (h2 x))) (defthm lemma-3 (implies (and (my-equiv y (double-rewrite x)) ; binding hypothesis (f y)) (equal (g x) y))) ; Restrict to a theory that includes the above lemmas but avoids the above ; definitions. (in-theory (union-theories (theory 'minimal-theory) '(lemma-1 lemma-2 lemma-3 my-equiv-is-an-equivalence))) ; Prove a theorem. (thm (equal (g (h1 a)) (h2 a))) The proof succeeds much as in the first example, but the following observation is key: when ACL2 binds [47my[0m upon considering the first hypothesis of [47mlemma-3[0m, it rewrites the term [47m(double-rewrite x)[0m in a context where it need only preserve the equivalence relation [47mmy-equiv[0m. At this point, [47mx[0m is bound by applying [47mlemma-3[0m to the term [47m(g (h1 a))[0m; so, [47mx[0m is bound to [47m(h1 a)[0m. The rule [47mlemma-1[0m then applies to rewrite this occurrence of [47mx[0m to [47m(h2 a)[0m, but only because it suffices to preserve [47mmy-equiv[0m. Thus [47my[0m is ultimately bound to [47m(h2 a)[0m, and the proof succeeds as one would expect. If we tweak the above example slightly by disabling the user's [equivalence] [rune], then the proof of the [47m[thm][0m form fails because the above rewrite of [47m(double-rewrite x)[0m is done in a context where it no longer suffices to preserve [47mmy-equiv[0m as we dive into the second argument of [47mmy-equiv[0m in the first hypothesis of [47mlemma-3[0m; so, [47mlemma-1[0m does not apply this time. (in-theory (union-theories (theory 'minimal-theory) '(lemma-1 lemma-2 lemma-3))) ; Proof fails in this case! (thm (equal (g (h1 a)) (h2 a)))") (free-variables-type-prescription (free-variables) "Matching for free variable in [type-prescription] rules We assume familiarity with the issue of dealing with free variables in hypotheses; see [free-variables]. By default, starting with Version 4.3, ACL2 attempts all possible matches for free variables. Consider the following example. (defstub f1 (x) t) (defstub f2 (x y) t) (defstub f3 (y) t) (defaxiom f1-prop (implies (and (f2 x y) ; <-- y is free in this hypothesis (f3 y)) (f1 x)) ; <-- (f1 x) is the type-term (type is `non-nil') :rule-classes :type-prescription) ; Succeeds: (thm (implies (and (f2 a b) (f3 b)) (f1 a))) ; The following fails unless we try more than one match for free variables in ; hypotheses. (thm (implies (and (f2 a b) (f2 a c) (f2 a d) (f3 b)) (f1 a))) There may be times when you want to match only the first free variable. In that case, you can write a function of two arguments, the [3mtype-prescription[0m [rune] being applied and the current ACL2 world, that prohibits multiple matching for those times. Your function is then `attached' to the built-in constrained function, [47moncep-ts[0m. The following examples are intended to explain how this works. First, let us disallow all multiple matching of free variables (i.e., implement the behavior often referred to as ``[47m:match-free :once[0m''; see [free-variables]). (defun oncep-tp-always (rune wrld) (declare (ignore rune wrld) (xargs :mode :logic :guard t)) t) (defattach-system oncep-tp oncep-tp-always) The second [47mthm[0m form above will now fail, because only one free-variable match is permitted for the first hypothesis of rule [47mf1-prop[0m above. Now suppose that instead, we want to disallow multiple matches for free variables in hypotheses of type-prescription rules [3mexcept[0m for the rule [47mf1-prop[0m above. With the following events, the second [47mthm[0m form above once again succeeds. (defun oncep-tp-always-except-f1-prop (rune wrld) (declare (ignore wrld) (xargs :mode :logic :guard (and (consp rune) (consp (cdr rune)) (symbolp (cadr rune))))) (not (eq (base-symbol rune) 'f1-prop))) (defattach-system oncep-tp oncep-tp-always-except-f1-prop) In general, your [47m[defattach][0m event will attach a function symbol to [47moncep-tp[0m. The [guard] of that function symbol must be implied by the guard of [47moncep-tp[0m: ACL2 !>:args oncep-tp Function ONCEP-TP Formals: (RUNE WRLD) Signature: (ONCEP-TP * *) => * Guard: (AND (PLIST-WORLDP WRLD) (CONSP RUNE) (CONSP (CDR RUNE)) (SYMBOLP (CADR RUNE))) Guards Verified: T Defun-Mode: :logic Type: built-in (or unrestricted) ONCEP-TP ACL2 !>") (free_variables_in_top-level_input (pages_written_especially_for_the_tours) "Free Variables in Top-Level Input ACL2 !>[31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c))))[0m ACL2 Error in TOP-LEVEL: Global variables, such as C, B, and A, are not allowed. See :DOC ASSIGN and :DOC @. ACL2 does not allow ``global variables'' in top-level input. There is no ``top-level binding environment'' to give meaning to these variables. Thus, expressions involving no variables can generally be evaluated, ACL2 !>[31;1m(equal (app (app '(1 2) '(3 4)) '(5 6))[0m [31;1m(app '(1 2) (app '(3 4) '(5 6))))[0m (1 2 3 4 5 6) but expressions containing variables cannot. There is an exception to this rule. References to ``single-threaded objects'' may appear in top-level forms. See [stobj] {ICON} (see [A_Tiny_Warning_Sign]). A single-threaded object is an ACL2 object, usually containing many fields, whose use is syntactically restricted so that it may be given as input only to certain functions and must be returned as output by certain functions. These restrictions allow single- threaded objects to be efficiently manipulated. For example, only a single copy of the object actually exists, even though from a logical perspective one might expect the object to be ``copied on write.'' The most commonly used single-threaded object in ACL2 is the ACL2 system state, whose current value is always held in the variable [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign]). ACL2 provides a way for you to use [47mstate[0m to save values of computations at the top-level and refer to them later. See [assign] {ICON} (see [A_Tiny_Warning_Sign]) and [@] {ICON} (see [A_Tiny_Warning_Sign]).") (frequently-asked-questions-by-newcomers (introduction-to-the-theorem-prover) "Some questions newcomers frequently ask This FAQ is for people who've read through all the other sections of the tutorial introduction to the theorem prover (see [introduction-to-the-theorem-prover] and all the links from it that are not marked with the little warning sign (``{ICON} (see [A_Tiny_Warning_Sign])''). Do not expect to understand our answers if you haven't taken the time to read through the tutorial. In the answers below you will see more links into the hypertext reference manual. While such links were marked ``{ICON} (see [A_Tiny_Warning_Sign])'' in the tutorial, they are not marked that way here. When you enter the reference manual be prepared to explore and assemble a mini-course on the topic of interest, not a quick fix. [31;1mQ[0m. How do I find something in the [31;1mACL2 documentation[0m? [31;1mA[0m. Try the ``Jump to'' or ``Search'' boxes at the {ACL2+Books Manual | https://acl2.org/doc/index.html}. [31;1mQ[0m. How does the theorem prover work? [31;1mA[0m. We really don't think you need to know much about the inner workings of the prover to become an effective user. That doesn't mean the system is self-explanatory! It means that stuff you need to learn is not how the theorem prover works but how to interact with it! That is what [introduction-to-the-theorem-prover] is about. However, if you want the most basic overview of the prover, see [architecture-of-the-prover]. [31;1mQ[0m. How do I [31;1mdefine a new function[0m? [31;1mA[0m. See [defun]. [31;1mQ[0m. How do I [31;1mdefine a new predicate[0m? [31;1mA[0m. See [defun]. [31;1mQ[0m. How do I [31;1mdefine a new relation[0m? [31;1mA[0m. See [defun]. [31;1mQ[0m. How do I define a [31;1mfunction or predicate that takes a varying number of arguments[0m? [31;1mA[0m. You can't. However, see [defmacro] to learn how to define a macro that takes a varying number of arguments and expands into an arbitrary term that you compute. [31;1mQ[0m. How do I define a [31;1mmacro that is sensitive to the state[0m? [31;1mA[0m. You can't. However, advanced users should consider [47m[make-event][0m. [31;1mQ[0m. How do I define [31;1mmutually recursive[0m functions? [31;1mA[0m. See [mutual-recursion]. However, you should realize that when two functions, say [47mf[0m and [47mg[0m, are mutually recursive, properties of [47mf[0m generally have to be stated simultaneously with properties of [47mg[0m, since inductive proofs about one function require inductive hypotheses about the other. Furthermore, ACL2 does not know how to do inductions for mutually recursive functions and must be told. See [mutual-recursion-proof-example]. [31;1mQ[0m. How do I declare the [31;1mtype signature of a function[0m? [31;1mA[0m. You can't. ACL2 is a syntactically untyped language and all functions are defined on all objects in the ACL2 universe. We recommend that the new user get used to this and only then explore the use of ACL2 to express and enforce a type regime. In ACL2, the [3mguard[0m of a function is akin to the type signature of a function in typed languages. However, ACL2 guards may be arbitrary terms, not just type conditions, they only concern the inputs to the function (not its result), and do not affect the axiom defining the function --- all functions are defined on every combination of objects. You may, of course, prove theorems that establish that every function called in a definition or theorem is supplied with input satisfying its guards (which necessarily involves describe the outputs too). These formulas are called [3mguard conjectures[0m and the process of proving them is called [3mguard verification[0m. Since guards are arbitrary ACL2 formulas, the ``type regimes'' one tends to enforce in ACL2 can be much for flexible and expressive than those in most programming languages. However, that expressibility also means guard verification can be challenging (indeed undecidable). On the other hand, if one limits oneself to simple type-like guards, lemmas can be proved that make most guard verification fully automatic and one can configure ACL2 to do guard verification automatically at [47mdefun[0m-time. One may also delay guard verification until ``the right'' lemmas have been proved. By doing guard verification one can make functions execute faster by allowing the code to avoid runtime checks. This is especially valuable to industrial users who have large models used both in verification and as simulation engines for designed artifacts. In addition, guard verification can give you the assurance that you are using your functions within their intended domains and hence is a form of functional specification and verification. However, all these advantages aside, it is remarkably easy to drift away from the simplest type regimes and write a guard that raises deep mathematical problems. New users should not try to confront these problems until they are comfortable with the theorem prover and with lemma development. Therefore, we [31;1mstrongly[0m recommend that you forget about types and guards and get used to reasoning about total functions. When you do decide to learn about them, be prepared for a complex story involving specification, execution efficiency, and proof management. See [guard]. [31;1mQ[0m. How do I tell [47mdefun[0m [31;1mwhat measure to use[0m? [31;1mA[0m. See [xargs], specifically [47m:measure[0m. [31;1mQ[0m. I specified a measure that always returns a natural number but ACL2 is acting like it's not a natural number. [31;1mA[0m. There are two likely problems. The most likely one is that your measure isn't really always a natural! Suppose the formals of your [47mdefun[0m are [47mx[0m and [47my[0m and your measure is [47m(m x y)[0m. Suppose the recursive calls of your function are protected by tests that ensure that [47mx[0m and [47my[0m are naturals. Then you might assume [47mx[0m and [47my[0m are naturals in the measure. But ACL2 has to prove [47m(o-p (m x y))[0m, where [47m[o-p][0m is the predicate that recognizes ordinals (and naturals are ordinals). Note that the theorem doesn't have any hypotheses! You might intuitively think that your measure has to be an ordinal just under the conditions that lead to recursive calls. That's not what ACL2 enforces. It has to be an ordinal, always. So you must change your specified measure. For example, consider wrapping [47m[nfix][0m around it or around its uses of [47mx[0m and [47my[0m to coerce those quantities to naturals. The second most likely explanation is that your measure returns a natural, always, but ACL2 doesn't know that and it takes induction to prove. This might happen if [47mm[0m involves some recursive functions. In this case, prove [47m(natp (m x y))[0m before your [47mdefun[0m. Perhaps you should consider making the [47mnatp[0m lemma a [47m:[0m[47m[type-prescription][0m lemma to make ACL2's typing algorithm aware of it. [31;1mQ[0m. How do I tell [47mdefun[0m [31;1mwhat well-founded relation to use[0m? [31;1mA[0m. See [xargs], specifically [47m:well-founded-relation[0m. [31;1mQ[0m. How do I show that a [31;1mrelation is well-founded[0m? [31;1mA[0m. Prove a theorem establishing that there is an order preserving embedding into the ordinals and store it with [47m:rule-classes[0m [47m:well-founded-relation[0m [well-founded-relation-rule]. [31;1mQ[0m. What is an [31;1mordinal[0m? What does it mean to be [31;1mwell-founded[0m? [31;1mA[0m. Ordinals are an extension of the natural numbers used to ensure that a process can't go on forever. Like naturals, they can be added, multiplied, and exponentiated. There is a sense of one ordinal being less than another. Unlike the naturals, each of which is finite, the ordinals include infinite objects. Now imagine ``standing'' on an ordinal and ``stepping'' to a smaller one. Like the naturals, this ``walk down the ordinals'' can't go on forever, even if you start on an infinite ordinal. That is because the ordinals are [3mwell-founded[0m. See [47m[o-p][0m for more information about ordinals in ACL2 and about well-foundedness. See [ordinals] for a deeper discussion and a discussion of books that can help configure ACL2 to reason about ordinals. [31;1mQ[0m. How can provide [31;1mhints for the termination proofs[0m in [47mdefun[0m? [31;1mA[0m. See [xargs], specifically [47m:hints[0m (for the termination proofs) and [47m:guard-hints[0m (for the guard verification proofs). [31;1mQ[0m. How do I define a [31;1mconstant[0m (something like a [31;1mglobal variable[0m)? [31;1mA[0m. See [defconst]. But remember that as an applicative programming language, ACL2 does not have global variables! You can define a symbol to have a fixed value and use the symbol sort of like a global variable in function definitions: you may refer to the value of the symbol in your functions without passing the variable in as formal parameter. But you may not ever change the value of the symbol! [31;1mQ[0m. How do I save the value of a top-level computation for future use? [31;1mA[0m. See [assign] and see [@]. [31;1mQ[0m. How do I introduce [31;1mnew syntactic form[0m or [31;1mabbreviation[0m? [31;1mA[0m. See [defmacro]. [31;1mQ[0m. How can create and modify an array? [31;1mA[0m. ACL2 is a functional language, so it is impossible to destructively modify an existing object; technically, all ``updates'' to objects must be implemented by ``copy-on-write'' semantics. That said, ACL2 provides support for [arrays], provided you use them in a restricted way. They give you constant-time access and change under the use restrictions. [31;1mQ[0m. How do I read from or write to a file? How do I do IO? [31;1mA[0m. To manipulate files, your function must have [47m[state][0m as an argument, so you should read about the restrictions that imposes. For input/output facilities, see [io]. [31;1mQ[0m. How do I define a [31;1mstructure that can be destructively modified[0m? [31;1mA[0m. ACL2 is an [3mapplicative programming language[0m. You can't modify objects arbitrarily! You basically have to ``copy on write,'' which means you construct new objects from old ones, making the changes you want in the new one. If the [47mcar[0m of some object is [47m1[0m at one moment and [47m2[0m later, then the basic logical axiom [47m(car x)[0m = [47m(car x)[0m is violated! However, if the only reference to the old object, e.g., [3mx[0m, was to pass it to the code that copied and ``changed'' it, then ACL2 can re-use the old object to produce the new one and the axioms would not object. Such syntactic restrictions can make [3mx[0m a modifiable structure but they will impose a heavy burden on you as a programmer: if pass such an [3mx[0m to a function and the function modifies it, then you must pass [3mx[0m only to that function and you must return the modified value and use it henceforth. Such objects are said to be [3msingle threaded[0m. See [defstobj]. [31;1mQ[0m. How do I write a universal quantifier? An existential quantifier? How can I say ``for all'' or ``there exists''? [31;1mA[0m You can't literally write quantifiers. But ACL2 has the power of full first order logic with quantification. See [quantifiers]. [31;1mQ[0m. How do I introduce an undefined or uninterpreted function symbol? Can I constrain it to have certain properties? [31;1mA[0m. See [encapsulate]. [31;1mQ[0m. How can I hide a lemma? I want to prove a lemma temporarily to use in another proof but I don't want the lemma around thereafter. [31;1mA[0m. One way to get a similar effect is to prove the lemma and then disable it with an [47m(in-theory (disable ...))[0m event; see [in-theory]. Another way is to put the lemma and the theorem that needs it into an [47m[encapsulate][0m and wrap a [47m[local][0m around the lemma. [31;1mQ[0m. What is an [31;1mevent[0m? [31;1mA[0m. An [3mevent[0m is a command that adds information to the ACL2 database (the ``logical world''), like [47mdefun[0m or [47mdefthm[0m. See [events]. [31;1mQ[0m. How do I say that I [31;1mdo not want a rewrite rule[0m generated from a theorem? [31;1mA[0m. The command (defthm [3mname[0m [3mformula[0m :rule-classes nil) will attempt to prove [3mformula[0m and, if successful, give [3mformula[0m the name [3mname[0m, which you may use in hints as a theorem, but it will build no rules from the formula. [31;1mQ[0m. How do I say that I want a formula to be [31;1mstored as a rewrite rule[0m? [31;1mA[0m. The command (defthm [3mname[0m [3mformula[0m) will attempt to prove [3mformula[0m and, if successful, it will give [3mformula[0m the name [3mname[0m and generate a rewrite rule from it, with the runic name [47m(:rewrite [0m[3mname[0m)]. It could happen that [3mformula[0m generates more than one rewrite rule, e.g., this happens if the conclusion is an [47mAND[0m. In this case, each conjunctive branch through the conclusion generates a rule named [47m(:rewrite [0m[3mname[0m[47m . i)[0m, for [3mi[0m=1,2,... For more details, see [rewrite]. [31;1mQ[0m. How do I say that I want a formula to be [31;1mstored as a rewrite rule[0m [31;1mand some other kinds of rules[0m? [31;1mA[0m. The command (defthm [3mname[0m [3mformula[0m :rule-classes ([3m:class1[0m ... [3mclassk[0m)) will attempt to prove [3mformula[0m and, if successful, it will give [3mformula[0m the name [3mname[0m and generate a rule of each [3m:classi[0m specified. Each [3m:classi[0m should either be a keyword, like [47m:REWRITE[0m or [47m:GENERALIZE[0m, naming a rule class (see [rule-classes]), or else should be a list that starts with a rule class and then lists the relevant modifiers. Be sure to include [47m:REWRITE[0m among the rule classes if you want the formula to generate a rewrite rule. It doesn't do that automatically if you explicitly specify [47m:rule-classes[0m! [31;1mQ[0m. How do I [31;1mrearrange[0m the shape of a formula before generating a rule from it? [31;1mA[0m. See [rule-classes] and read about the [47m:corollary[0m modifier. [31;1mQ[0m. What is a [31;1mtype-prescription[0m? [31;1mA[0m. ACL2 has an algorithm for determining the type of object returned by a term, where a type is one of the Common Lisp primitive datatypes such as natural, integer, Boolean, cons, true-listp, etc. Rules provided by you can influence this algorithm. See [type-prescription]. [31;1mQ[0m. How do [31;1mrewrite rules work[0m? [31;1mA[0m. Re-read the tutorial sections: [introduction-to-rewrite-rules-part-1] and [introduction-to-rewrite-rules-part-2]. [31;1mQ[0m. How do I [31;1msee what's in the database[0m? [31;1mA[0m. You can't look at the entire database with user-friendly tools. You can print the command that introduced a particular name, print the entire sequence of user commands, print the commands in the region between two commands, print all the rewrite rules that apply to a given term or function symbol, and many other options. See [history]. If you have loaded a book from another user, you might wish to read the source file. For example, the source file for [47m(include-book "arithmetic-5/top" :dir :system)[0m is the file named [47marithmetic-5/top.lisp[0m on the [47macl2-sources/books/[0m directory where ever your ACL2 sources are installed. Often, books are well-documented by comments by their authors. Some books have [47mReadme[0m or [47mREADME[0m files on the same directory. [31;1mQ[0m. How do I [31;1mundo[0m a command? [31;1mA[0m. See [history], especially see [u] (``undo'') and see [ubt] (``undo back through''). [31;1mQ[0m. What [31;1mrewrite rules match[0m a given term? [31;1mA[0m. See [pl]. [31;1mQ[0m. What were those [31;1mquestions to ask when looking at key checkpoints[0m? [31;1mA[0m. See [introduction-to-key-checkpoints]. [31;1mQ[0m. How do I figure out [31;1mwhy a rewrite rule won't fire[0m? [31;1mA[0m. If you activate rewrite rule monitoring (see [brr]) and then install a monitor (see [monitor]) on the rule in question, ACL2 will enter an interactive break whenever the pattern of the rule is matched against a target in a proof. So after installing the monitor, re-try the proof and then interact with the rewriter via break commands (see [brr-commands]). Like all trace and break packages, you have to know what you're doing to use the break rewrite facility, so read the material in the reference manual. If no interactive break happens after you've installed the monitor on your rule and re-tried the proof, it means no suitable target ever arose. Don't forget to turn off monitoring when you're done as it slows down the system. [31;1mQ[0m. [31;1mWhy is a proof taking so long?[0m [31;1mA[0m. Unexpectedly poor performance on simple problems is usually a sign of cyclic rewriting or combinatoric explosion. See [dmr] and see [accumulated-persistence]. [31;1mQ[0m. How do I tell ACL2 [31;1mwhat induction to do[0m for a particular formula? [31;1mA[0m. When issuing the [47mdefthm[0m command for the formula, supply an [47m:induct[0m hint: (defthm [3mname[0m [3mformula[0m :hints (("Goal" :induct (f x1 ... xn)))) where [47mf[0m is a function that recurs the way you want the induction to unfold and [47mx1 ... xn[0m are the relevant variables in [3mformula[0m. You usually have to define [47mf[0m appropriately for each formula that needs an induct hint, though sometimes you can re-use an earlier [47mf[0m or one of the functions in the formula itself. It doesn't matter what value [47m(f x1 ... xn)[0m returns. All that matters is how it recurs. The termination analysis for [47mf[0m justifies the induction done. See [hints], especially the section on [47m:induct[0m hints; also see [induction]. [31;1mQ[0m. ACL2 doesn't know [31;1msimple arithmetic[0m that can simplify the term [47m(+ 1 -1 x)[0m. [31;1mA[0m. You should load an arithmetic book whenever you're dealing with an arithmetic problem. The simplest arithmetic book is typically loaded with the event [47m(include-book "arithmetic/top-with-meta" :dir :system)[0m. If you're using [47mfloor[0m and [47mmod[0m or non-linear arithmetic like [47m(* x y)[0m you should use [47m(include-book "arithmetic-5/top" :dir :system)[0m. See also the discussion of arithmetic books under the ``Lemma Libraries and Utilities'' link of the ACL2 home page, and see [community-books]. [31;1mQ[0m. ACL2 is not using an [31;1marithmetic lemma[0m that I proved. [31;1mA[0m. Lemmas concluding with arithmetic inequalities, like (implies (member e x) (< (len (delete e x)) (len x))) are not good rewrite rules because they rarely match targets because of intervening arithmetic operators. For example, the above conclusion doesn't match [47m(< (LEN (DELETE E X)) (+ 1 (LEN X)))[0m. You should store such lemmas as [47m:linear[0m rules by using the command: (defthm len-delete (implies (member e x) (< (len (delete e x)) (len x))) :rule-classes :linear) See [linear]. [31;1mQ[0m. What is a [31;1mlinear rule[0m? [31;1mA[0m. See [linear]. [31;1mQ[0m. How do I make ACL2 [31;1mtreat a relation as an equality[0m? [31;1mA[0m. We assume you mean to treat the relation as an equivalence, i.e., replace one term by another when they are equivalent under your relation. See [equivalence], see [congruence], and see [refinement]. [31;1mQ[0m. One of my rewrite rules has a [31;1mhypothesis that doesn't rewrite[0m to true. What do I do? [31;1mA[0m. Prove a rewrite rule that establishes that hypothesis under the relevant assumptions from the context of the intended target. Alternatively, undo the rule and restate it with a [47m[force][0m around the problematic hypothesis, making ACL2 assume the hypothesis when the rule is applied and raising the truth of the hypothesis as an explicit subgoal of the proof. See also [47m[case-split][0m. Of course, you should always state the strongest rewrite rules you can think of, eliminating hypotheses or shifting them to the right-hand side inside of [47mIF[0ms; see [strong-rewrite-rules]. [31;1mQ[0m. How do I make ACL2 ``guess'' the [31;1mright instantiation of a free variable[0m? [31;1mA[0m. You can provide a [47m:restrict[0m hint that names the problematic lemma and provides an instantiation of the free variable. See [hints], specifically [47m:restrict[0m. You could alternatively give a hint that [47m:uses[0m the rule and provides the appropriate instantiation in full. See [hints], specifically [47m:use[0m. Recall that ACL2 guesses free variable instantiations by matching the problematic hypothesis to the assumptions in the context of the target. If the appropriate assumption is present but ACL2 is finding another one, try undoing the problematic rule and proving it again, specifying the [47m:match-free :all[0m modifier of the [47m:rewrite[0m or [47m:linear[0m rule class. See [rule-classes]. Alternatively, undo and prove the problematic rule again and use a [47m[bind-free][0m form to compute the appropriate instantiation. [31;1mQ[0m. How can I make ACL2 do a [31;1mcase split[0m to prove a certain subgoal? [31;1mA[0m. See [hints], specifically [47m:cases[0m. [31;1mQ[0m. How can I [31;1mprevent ACL2 from using a rewrite rule[0m? [31;1mA[0m. See [hints], specifically [47m:in-theory (disable ...)[0m. If the use of the rule is problematic in only one subgoal and the lemma is needed in other subgoals, disable the lemma only in the problematic subgoal by specifying the subgoal name (e.g., [47m"Subgoal 1/3.2.1"[0m) as the goal specifier in the hint. If the rule isn't needed anywhere in the proof, you could use the specifier [47m"Goal"[0m. If you don't think the rule will ever be needed for a while, you could globally disable it with the event [47m(in-theory (disable ...))[0m (see [in-theory]) executed before the first problematic proof. If the rule has never been used or must always be disabled, undo it and prove it again with [47m:[0m[47m[rule-classes][0m [47mnil[0m. [31;1mQ[0m. How can I prevent ACL2 from running a definition on constants? I tried disabling the function but that didn't work. [31;1mA[0m. If you have a function named [47mf[0m then disabling [47mf[0m will disable the definitional axiom about [47mf[0m. But ACL2 has another kind of rule about [47mf[0m, telling it how to evaluate [47mf[0m. The [rune] of this rule is [47m(:executable-counterpart f)[0m. Try disabling that, as in the [47m:[0m[47m[hints][0m [47m(([0m... [47m:in-theory (disable (:executable-counterpart f)) ...c[))[0m. [31;1mQ[0m. How can I make ACL2 [31;1muse a rule[0m in a proof? [31;1mA[0m. See [hints], specifically [47m:use[0m. [31;1mQ[0m. How can I make ACL2 expand a function call in a proof? [31;1mA[0m. You can give an [47m:[0mSee [expand] hint. [31;1mQ[0m. ACL2 sometimes aborts the proof attempt before showing me all of the subgoals. How can I make it just keep going instead of aborting early? [31;1mA[0m. See [otf-flg], which stands for Onward Thru the Fog FLaG. [31;1mQ[0m. How can I [31;1mcompute when I want a rule to fire[0m? [31;1mA[0m. See [syntaxp]. [31;1mQ[0m. How can I add [31;1mpragmatic advice to a lemma after it has been proved[0m? For example, how can add a forced hypothesis, a backchain limit, or a [47msyntaxp[0m test? [31;1mA[0m. You can't. You can undo the lemma, restate it appropriately, and prove it again. This produces the cleanest database. Alternatively, you can prove the restated lemma under a new name --- a task that should be easy since the old version is in the database and will presumably make the proof trivial --- and then disable the old name. [31;1mQ[0m. How can I [31;1mstop ACL2 from rewriting a term[0m? [31;1mA[0m. If you need rewriting done but want to prevent some particular terms from being rewritten, see [hints], specifically [47m:hands-off[0m. Alternatively, consider embedding the problematic term in a [47m[hide][0m. Users sometime develop special theories (see [theory]) containing just the rules they want and then use hints to switch to those theories on the appropriate subgoals. [31;1mQ[0m. Can I [31;1mcompute which subgoals a hint refers to[0m? [31;1mA[0m. Yes, see [computed-hints]. This topic is for advanced users but knowing that it is possible might come in handy someday. [31;1mQ[0m. I want the rewriter to [31;1malways use one theory and then switch to another[0m so that it doesn't use my most complicated before until doing the simple things. [31;1mA[0m. This is possible but is something for the advanced user. It can be done using a form of [computed-hints]. See [using-computed-hints-7]. [31;1mQ[0m. Is there a way to attach [31;1mthe same hint to every defthm[0m? [31;1mA[0m. See [default-hints]. [31;1mQ[0m. How can I just tell ACL2 the proof steps? [31;1mA[0m. See [verify] and see [proof-builder]. [31;1mQ[0m. How can I write [31;1mmy own simplifier[0m? [31;1mA[0m. See [meta]. [31;1mQ[0m. How can I add an axiom or just assume some lemma without proof? [31;1mA[0m. This is very dangerous but is a good strategy for exploring whether or not a certain set of lemmas (and their rules) is sufficient to prove your goal. See [defaxiom] and see [skip-proofs]. [31;1mQ[0m. How can redefine a user-defined function? [31;1mA[0m. This is tricky. What if you've already proved theorems about the old definition and then wish to change it? There are several options. See [ld-redefinition-action] (and note specifically the discussion of updater function for it, [47mset-ld-redefinition-action[0m); also see [redef], see [redef!], see [redef+], and see [redef-]. [31;1mQ[0m. How do I [31;1mchange a function from[0m [47m:program[0m [31;1mmode to[0m [47m:logic[0m [31;1mmode[0m? [31;1mA[0m. See [verify-termination]. [31;1mQ[0m. How do I [31;1mchange the guards[0m on a function? [31;1mA[0m. You can't. Undo it and redefine it. [31;1mQ[0m. What is [31;1mprogram mode[0m? [31;1mA[0m. See [program]. [31;1mQ[0m. What does the ACL2 [31;1mprompt[0m mean? [31;1mA[0m. See [introduction-to-a-few-system-considerations] or, specifically, see [prompt]. [31;1mQ[0m. What is [31;1mlogic mode[0m? [31;1mA[0m. See [logic]. [31;1mQ[0m. How do I [31;1mget into or out of[0m [47m:program[0m [31;1mmode?[0m [47m:Logic[0m [31;1mmode?[0m [31;1mA[0m. See [program] and see [logic]. You can enter these modes temporarily for a particular [47m[defun][0m by using [47m(declare (xargs :mode :program))[0m or [47m(declare (xargs :mode :logic))[0m after the list of formal parameters to the definition. [31;1mQ[0m. How do I quit from ACL2? [31;1mA[0m. This varies depending on the interface you're using. See [introduction-to-a-few-system-considerations]. [31;1mQ[0m. How do I [31;1mload a file[0m of definitions and theorems created by someone else? [31;1mA[0m. See [include-book]. [31;1mQ[0m. How do I [31;1mcreate my own book[0m of definitions and theorems? [31;1mA[0m. See [books]. [31;1mQ[0m. Where are the books referenced by [31;1m:dir :system[0m on my machine? [31;1mA[0m. If your ACL2 is installed on the directory [3mdir[0m[47m/acl2-sources[0m and you follow the standard [installation] instructions, then the books are typically the files under the directory [3mdir[0m[47m/acl2-sources/books/[0m. [31;1mQ[0m. How can I find out [31;1mwhat books are available[0m? [31;1mA[0m. Go to the ACL2 home page, [47mhttp://www.cs.utexas.edu/u/moore/acl2/[0m and look at the link labeled ``Lemma Libraries and Utilities.'' [31;1mQ[0m. How do I [31;1mproduce my own book[0m? [31;1mA[0m. See [books]. [31;1mQ[0m. What is a [31;1mdecision procedure[0m? What [31;1mdecision procedures does ACL2 have[0m? [31;1mA[0m. A [3mdecision procedure[0m is an algorithm that given enough time and space can determine, for all the formulas in a certain syntactic class of formulas, whether the formula is a theorem or not. The most well-known decision procedure is for propositional calculus: by testing a formula under all the combinations Boolean assignments to the variables, one can decide if a propositional formula is a theorem. The syntactic class consists of all formulas you can write using just variables, constants, and compositions of the functions [47mand[0m, [47mor[0m, [47mnot[0m, [47mimplies[0m, [47miff[0m, and [47mif[0m. There are, of course, an exponential number of different assignments so the algorithm can be slow. ACL2 contains a propositional decision procedure based on symbolic normalization that can be faster than trying all the combinations of truth values --- but is not guaranteed to be faster. ACL2 also contains an optional [bdd] procedure. ACL2 also contains a decision procedure for rational arithmetic involving variables, rational constants, addition, multiplication by rational constants, equality, and the various versions of arithmetic inequality ([47m<[0m, [47m<=[0m, [47m>=[0m, and [47m>[0m). It can be extended with [47m:[0m[47m[linear][0m lemmas. ACL2 is complete for equality over uninterpreted (e.g., undefined and unconstrained) function symbols using an algorithm based on transitive closure of equivalence classes under functional substitutivity. Finally, you can make ACL2 use other decision procedures, even ones implemented outside of ACL2; see [clause-processor]. [31;1mQ[0m. ACL2 has the [31;1mchange of variable[0m trick ([31;1mdestructor elimination[0m) that it does to get rid of [47m(CAR X)[0m and [47m(CDR X)[0m by replacing [47mx[0m by [47m(CONS A B)[0m. Is there a way to make ACL2 do that for other terms? [31;1mA[0m. Yes. See [elim]. [31;1mQ[0m. How can I [31;1mprevent destructor elimination[0m? [31;1mA[0m. See [hints], specifically [47m:do-not '(eliminate-destructors)[0m. [31;1mQ[0m. How can I [31;1mprevent cross-fertilization[0m? [31;1mA[0m. See [hints], specifically [47m:do-not '(fertilize)[0m. [31;1mQ[0m. How can I [31;1mprevent generalization[0m? [31;1mA[0m. See [hints], specifically [47m:do-not '(generalize)[0m. [31;1mQ[0m. How can I make ACL2 [31;1mimpose a restriction on a new variable[0m introduced by destructor elimination or generalization? [31;1mA[0m. See [generalize]. [31;1mQ[0m. What [31;1mrule classes[0m are there? [31;1mA[0m. See [rule-classes]. [31;1mQ[0m. What is a [31;1mtheory[0m? [31;1mA[0m. See [theories]. [31;1mQ[0m. How are [31;1mhints inherited by the children of a subgoal[0m? [31;1mA[0m. See [hints-and-the-waterfall]. [31;1mQ[0m. How do I use ACL2 under [31;1mEmacs[0m? [31;1mA[0m. See [emacs]. [31;1mQ[0m. How do I use ACL2 under [31;1mEclipse[0m? [31;1mA[0m. See [ACL2-Sedan]. [31;1mQ[0m. How do I interrupt the prover? [31;1mA[0m. The keyboard sequence for interrupting a running process depends your operating system, host Common Lisp, and user interface (e.g., Emacs, Eclipse, etc.). But perhaps a few examples will help you discover what you need to know. If your host Common Lisp is GCL or Allegro and you are typing directly to the Common Lisp process, then you can interrupt a computation by typing ``ctrl-c'' (hold down the Control key and hit the ``c'' key once). But other Lisps may require some other control sequence. If you are typing to an Emacs process which is running the GCL or Allegro Common Lisp process in a shell buffer, you should type ctrl-c ctrl-c --- that is, you have to type the previously mentioned sequence twice in succession. If you are running the ACL2 Sedan, you can use the [3mInterrupt Session[0m button on the tool bar. The environment you enter when you interrupt depends on various factors and basically you should endeavor to get back to the top level ACL2 command loop, perhaps by typing some kind of Lisp dependent ``abort'' command like [47m:q[0m or [47m:a[0m. You can usually determine what environment you're in by paying attention to the prompt. [31;1mQ[0m. What is the [31;1mACL2 loop[0m? [31;1mA[0m. That is the name given to the interactive environment ACL2 provides, a ``read-eval-print loop'' in which the user submits successive commands by typing ACL2 expressions and keyword commands. See [introduction-to-a-few-system-considerations]. [31;1mQ[0m. What is [31;1mraw lisp[0m? [31;1mA[0m. That is our name for the host Common Lisp in which ACL2 is implemented. See [introduction-to-a-few-system-considerations]. There is an ACL2 mode named [3mraw mode[0m which is different from ``raw lisp.'' See [set-raw-mode]. [31;1mQ[0m. Can I get a tree-like view of a proof? [31;1mA[0m. See [proof-tree] for an Emacs utility that displays proof trees and allows you to navigate through a proof from the proof tree. The ACL2 Sedan also supports proof trees and you should see the ACL2s documentation on that topic. [31;1mQ[0m. I used the earlier Boyer-Moore theorem prover, Nqthm. How is ACL2 different? [31;1mA[0m. See [nqthm-to-ACL2]. If you are reading this as part of the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (from-df (pointers) "See [df].") (fsubcor-var (pointers) "See [system-utilities].") (full-book-name (books-reference) "Book naming conventions assumed by ACL2 See [pathname] for background on ACL2 pathnames. ACL2 defines a ``full-book-name'' to represent an absolute filename of a book. This is typically a ``full-book-name string'' or simply ``full-book-string'': an absolute filename for the book. At the end of this topic we mention a second representation, the [3m[sysfile][0m; but until then, our discussion of full-book-names is restricted to the special (but common) case of full-book-strings. A full-book-name string may be divided into contiguous sections: a ``directory string'', a ``familiar name'' and an ``extension''. See [pathname] for the definitions of ``absolute,'' ``filename string,'' and other notions pertaining to naming files. Below we exhibit the three sections of one such string: "/usr/home/smith/project/arith.lisp" "/usr/home/smith/project/" ; directory string "arith" ; familiar name ".lisp" ; extension The sections are marked by the rightmost slash and rightmost dot, as shown below. "/usr/home/smith/project/arith.lisp" | | slash dot | | "/usr/home/smith/project/" ; directory string "arith" ; familiar name ".lisp" ; extension The directory string includes (and terminates with) the rightmost slash. The extension includes (and starts with) the rightmost dot. The dot must be strictly to the right of the slash so that the familiar name is well-defined and nonempty. We conclude by discussing the other representation of full-book-names as promised above: the sysfile, which is a pair of the form [47m(:kwd . "relpath")[0m where [47m:kwd[0m is a [keyword] and [47m"relpath"[0m is a relative pathname string. See [sysfile] for a discussion of sysfiles. Here, we simply remark that sysfiles are used primarily by the implementation; as an ACL2 user you might never see one. Sysfiles are used for full-book-names in [certificate] files and in various data structures in the ACL2 logical [world].") (function-symbolp (pointers) "See [system-utilities].") (function-theory (theories theory-functions) "Function symbol rules as of logical name Examples: (function-theory :here) (function-theory 'lemma3) See [logical-name]. General Form: (function-theory logical-name) Returns the theory containing all the [47m:[0m[47m[definition][0m [rune]s, whether [enable]d or not, that existed immediately after [47m[logical-name][0m was introduced. See the documentation for [theories], [logical-name] and [47m[executable-counterpart-theory][0m. You may experience a fencepost problem in deciding which logical name to use. [47m[Deflabel][0m can always be used to mark unambiguously for future reference a particular point in the development of your theory. The order of [events] in the vicinity of an [47m[encapsulate][0m is confusing. See [encapsulate]. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (functional-instantiation (encapsulate) "An analogue in ACL2 of higher-order logical reasoning. Functional instantiation allows you to prove theorems ``by analogy'' with previous theorems. See [hints] and see [lemma-instance]. Subtopics [Functional-instantiation-example] A small proof demonstrating functional instantiation [Functional-instantiation-in-ACL2r] Additional requirements for [47m:functional-instance[0m hints in ACL2(r) [Lemma-instance] An object denoting an instance of a theorem") (functional-instantiation-example (functional-instantiation tutorial5-miscellaneous-examples) "A small proof demonstrating functional instantiation The example below demonstrates the use of functional instantiation, that is, the use of a generic result in proving a result about specific functions. In this example we constrain a function to be associative and commutative, with an identity or ``root,'' on a given domain. Next, we define a corresponding function that applies the constrained associative-commutative function to successive elements of a list. We then prove that the latter function gives the same value when we first reverse the elements of the list. Finally, we use functional instantiation to derive the corresponding result for the function that multiplies successive elements of a list. The details of the proof (such as the [47m[in-theory][0m event and particulars of the lemmas) are not the point here. Rather, the point is to demonstrate the interaction of [47m[encapsulate][0m [events] and [47m:functional-instance[0m [lemma-instance]s. Of course, if you are interested in details then you may find it helpful to run these [events] through ACL2. Also see [constraint] for more about [47m:functional-instance[0m and see [lemma-instance] for general information about the use of previously-proved lemmas. It may also be helpful to see [47m[set-constraint-tracking][0m or to run the script below after doing [47m(set-constraint-tracking t)[0m. (in-package "ACL2") (encapsulate (((ac-fn * *) => *) ((ac-fn-domain *) => *) ((ac-fn-root) => *)) (local (defun ac-fn (x y) (+ x y))) (local (defun ac-fn-root () 0)) (local (defun ac-fn-domain (x) (acl2-numberp x))) (defthm ac-fn-comm (equal (ac-fn x y) (ac-fn y x))) (defthm ac-fn-assoc (equal (ac-fn (ac-fn x y) z) (ac-fn x (ac-fn y z)))) (defthm ac-fn-id (implies (ac-fn-domain x) (equal (ac-fn (ac-fn-root) x) x))) (defthm ac-fn-closed (and (ac-fn-domain (ac-fn x y)) (ac-fn-domain (ac-fn-root))))) ;;;;;;;;;;;;;;;;;;;;;;; ; End of encapsulate. ; ;;;;;;;;;;;;;;;;;;;;;;; ; Define a ``fold'' function that iteratively applies ac-fn over a list. (defun ac-fn-list (x) (if (atom x) (ac-fn-root) (ac-fn (car x) (ac-fn-list (cdr x))))) ; Recognize lists all of whose elements are in the intended domain. (defun ac-fn-domain-list (x) (if (atom x) t (and (ac-fn-domain (car x)) (ac-fn-domain-list (cdr x))))) ; Define a list reverse function. (defun rev (x) (if (atom x) nil (append (rev (cdr x)) (list (car x))))) ; The following is needed for proving ac-fn-list-append, which is ; needed for proving ac-fn-list-rev. (defthm ac-fn-list-closed (ac-fn-domain (ac-fn-list x))) ; Needed for proving ac-fn-list-rev: (defthm ac-fn-list-append (implies (and (ac-fn-domain-list x) (ac-fn-domain-list y)) (equal (ac-fn-list (append x y)) (ac-fn (ac-fn-list x) (ac-fn-list y))))) ; Needed for proving ac-fn-list-rev: (defthm ac-fn-domain-list-rev (equal (ac-fn-domain-list (rev x)) (ac-fn-domain-list x))) ; The following is a good idea because without it, the proof attempt ; for ac-fn-list-rev (see just below) fails with the term (HIDE ; (AC-FN-LIST NIL)). It is often a good idea to disable ; executable-counterparts of functions that call constrained ; functions. (in-theory (disable (:executable-counterpart ac-fn-list))) (defthm ac-fn-list-rev (implies (ac-fn-domain-list x) (equal (ac-fn-list (rev x)) (ac-fn-list x)))) ; Our goal now is to apply functional instantiation to ac-fn-list-rev ; in order to prove the corresponding theorem, times-list-rev, based ; on * instead of ac-fn. (defun times-list (x) (if (atom x) 1 (* (car x) (times-list (cdr x))))) (defun number-listp (x) (if (atom x) t (and (acl2-numberp (car x)) (number-listp (cdr x))))) ; The following relies on the following built-in rules for * (whose ; statements correspond directly to their names): commutativity-of-*, ; associativity-of-*, and unicity-of-1. (defthm times-list-rev (implies (number-listp x) (equal (times-list (rev x)) (times-list x))) :hints (("Goal" :use ((:functional-instance ac-fn-list-rev ;; Instantiate the generic functions: (ac-fn *) (ac-fn-root (lambda () 1)) (ac-fn-domain acl2-numberp) ;; Instantiate the other relevant functions: (ac-fn-list times-list) (ac-fn-domain-list number-listp))))))") (functional-instantiation-in-acl2r (functional-instantiation) "Additional requirements for [47m:functional-instance[0m hints in ACL2(r) This documentation topic relates to ACL2(r), the modification of ACL2 that supports the real numbers (see [real]). See [hints] and see [lemma-instance] for a discussion of [47m:use[0m hints that employ the [47m:functional-instance[0m keyword. Here, we document additional requirements for such hints that applies to ACL2(r). We assume familiarity with lemma instances; see [lemma-instance]. (1) When functionally instantiating a non-classical formula, it is illegal to use pseudo-lambda expressions in a lemma instance. (2) A classical function symbol must be bound either to a classical function symbol or to a lambda (or, if allowed, pseudo-lambda) expression with a classical body. Similarly, a non-classical function symbol must be bound either to a non-classical function symbol or to a lambda (or, if allowed, pseudo-lambda) expression with a non-classical body.") (functions_for_manipulating_these_objects (pages_written_especially_for_the_tours) "Functions for Manipulating these Objects {IMAGE} (see [Modeling_in_ACL2]) Consider a typical ``stack'' of control frames. {IMAGE} Suppose the model required that we express the idea of ``the most recent frame whose return program counter points into [47mMAIN[0m.'' The natural expression of this notion involves [31;1mfunction application[0m --- ``fetch the [47mreturn-pc[0m of this frame'' [31;1mcase analysis[0m --- ``[31;1mif[0m the pc is [47mMAIN[0m, [31;1mthen[0m ...'' [31;1miteration[0m or [31;1mrecursion[0m --- ``pop this frame off and repeat.'' The designers of ACL2 have taken the position that a [31;1mprogramming[0m [31;1mlanguage[0m is the natural language in which to define such notions, [31;1mprovided[0m the language has a mathematical foundation so that models can be analyzed and properties derived logically. Common Lisp is the language supported by ACL2. To be precise, a small applicative subset of Common Lisp is the language supported by ACL2. {IMAGE} (see [Modeling_in_ACL2])") (further-information-on-rewriting (introduction-to-the-theorem-prover) "A grab bag of advice and information on rewriting In the following paragraphs we give some links to advanced topics, marked with ``{ICON} (see [A_Tiny_Warning_Sign])''. If you are reading this topic as part of the tutorial on the theorem prover, do not follow these links upon your first reading. Just take note of the existence of the facilities and ideas mentioned. [Arithmetic]: If your goal theorem involves even trivial arithmetic, such as adding or subtracting [47m1[0m, we recommend that you do (include-book "arithmetic/top-with-meta" :dir :system) which loads into ACL2 all the rules in one of the so-called ACL2 ``community books'' (see [community-books]). ([3mBooks[0m are certified files of definitions, lemmas, etc., usually prepared by other ACL2 users and explicitly shared with the community. The ACL2 [installation] instructions suggest downloading the community books.) The book "top-with-meta" is the most elementary and most widely used arithmetic book. Other community books include "arithmetic-5/top" and various hardware and floating-point arithmetic books; if including "arithmetic/top-with-meta" isn't sufficient, you could try [47m(include-book "arithmetic-5/top" :dir :system)[0m. [31;1mRules Concluding with Arithmetic Inequalities[0m: If you are tempted to create a rewrite rule with an arithmetic inequality as its conclusion or left-hand side, think again. Inequalities such as (<= (len (delete e x)) (len x)) make poor left-hand sides for rewrite rules. For example, the inequality above does not match the target (<= (LEN (DELETE E X)) (+ 1 (LEN X))) even though it is sufficient to prove the target (given some simple arithmetic). We recommend that if you have a theorem that establishes an arithmetic inequality, you make it a [3mlinear[0m rule. See [linear] {ICON} (see [A_Tiny_Warning_Sign]). [31;1mRearranging Formulas Before Making Rules[0m: It is possible to rearrange the propositional structure of a proved formula before processing it as a rule. This allows you to state a theorem one way ``for publication'' and rearrange it to be stored as a more effective rule. See [introduction-to-the-database] (a tutorial topic you'll come to later) and its discussion of the concept of [47mcorollary[0m. Also, see the discussion of [47mcorollary[0m in [47m[rule-classes][0m {ICON} (see [A_Tiny_Warning_Sign]). [31;1mRewriting with New Equivalence Relations[0m: You may introduce new [3mequivalence[0m relations, like ``set-equal'' or ``is-a-permutation'' and cause the rewriter to replace equivalents by equivalents in suitable contexts, where you use [3mcongruence[0m rules to inform ACL2 of where these more relaxed notions of equivalence may be used; see [equivalence] {ICON} (see [A_Tiny_Warning_Sign]) and see [congruence] {ICON} (see [A_Tiny_Warning_Sign]). [31;1mPragmatic Advice to Control Rules[0m: You may attach various [3mpragmas[0m to a rule that allow you rather fine heuristic control over whether and how the rule is applied. For example, you may mark a hypothesis to be [3mforced[0m (see [force] {ICON} (see [A_Tiny_Warning_Sign])) meaning that the rule is to be applied even if that hypothesis is not relieved --- but if the proof is successful the system will turn its attention to all forced subgoals. You may similarly mark a hypothesis so as to cause a case split, allowing the relief of the hypothesis on one branch and spawning another branch explicitly denying the hypothesis; see [case-split] {ICON} (see [A_Tiny_Warning_Sign]). You may add a bogus hypothesis that looks at the intended application of the rule and decides whether to apply the rule or not, performing an arbitrary computation on the syntactic context of the application; see [syntaxp] {ICON} (see [A_Tiny_Warning_Sign]). By providing a [47m:match-free[0m modifier to the [47m:rewrite[0m rule declaration in your rule-classes, you may tell ACL2 to try all or only the first free variable value it guesses (see [rule-classes] {ICON} (see [A_Tiny_Warning_Sign])). You may provide a bogus hypothesis that computes from the syntactic environment the values to guess for the free variables in a rule; see [bind-free] {ICON} (see [A_Tiny_Warning_Sign]). You may mark a term so that the rewriter does not dive into it; see [hide] {ICON} (see [A_Tiny_Warning_Sign]). [31;1mProgramming Your Own Rewriter[0m: If you cannot find a way to use rewrite rules to make the transformations you desire, you might investigate the use of [3mmetafunctions[0m. A metafunction is just a little theorem prover of your own design. It takes as input a list structure representing a term and returns a list structure representing a term. If you can prove that the meaning of the input and output terms are equivalent, you can extend the ACL2 simplifier to call your metafunction. See [meta] {ICON} (see [A_Tiny_Warning_Sign]). [31;1mThe Order in which Targets are Rewritten[0m: The rewriter sweeps through terms ``inside-out'' otherwise known as ``left-most innermost first''. Thus, before trying to apply rewrite rules to [47m([0m[3mf a1 ... an[0m[47m)[0m, rules are applied to the [3mai[0m. This has the good effect of normalizing the [3mai[0m. This fact might help you understand why sometimes your rules ``don't seem to fire.'' For example, suppose you have a rule for rewriting [47m(len (rev x))[0m to [47m(len x)[0m and suppose you wish to prove a theorem about [47m(LEN (REV (CONS A B)))[0m. Suppose [47mrev[0m is defined in terms of [47mappend[0m, as shown in [programming-knowledge-taken-for-granted]. Then you might see a checkpoint in which the [47m(LEN (REV ...))[0m above has been simplified to [47m(LEN (APPEND (REV B) (LIST A)))[0m instead of to [47m(LEN (CONS A B))[0m. Why wasn't your rule about [47m(len (rev x))[0m applied? The reason is that [47m(REV (CONS A B))[0m rewrote to [47m(APPEND (REV B) (LIST A))[0m before rules were applied to [47m(LEN (REV ...))[0m. You need a rule about [47m(len (append x y))[0m, as you will see from the checkpoint. [31;1mThe Order in which Rules are Tried[0m: The rewriter tries the most recently proved rules first. For example, suppose [47mf[0m, [47mg[0m, and [47mh[0m are functions defined so that the following two theorems are provable and suppose you executed the following two events in the order shown: (defthm rule1 (equal (f (g x)) (h 1 x))) (defthm rule2 (equal (f (g x)) (h 2 X))) Then if rewrite rules are applied to [47m(F (G A))[0m, the result will be [47m(H 2 A)[0m, because the latter rule, [47mrule2[0m, is applied first. It is generally best not to have conflicting rules or, at least, to understand how such conflicts are resolved. The system will warn you when you propose a rule that conflicts with an existing one. If you were reading this topic as part of the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-rewrite-rules-part-2].") (future-work-related-to-the-tau-system (introduction-to-the-tau-system) "Some tau system problems that we hope someone will address The tau system is inexpressive compared to modern polymorphic type systems --- something that may be unavoidable in an untyped first-order language. However, we believe its effectiveness could be greatly increased by the development of some additional tools. We also believe that most of these tools could be provided by ACL2 users creating certified community books that exploit the basic tools already provided. It is likely the initial attempts to create such books will show the inadequacy of some of the current algorithms and data structures in the tau system and might point the way to improvements. As implementors of ACL2 our preference is to support the improvement of the core algorithms and data structures and provide customizable hooks allowing users to exploit them by developing effective and convenient interfaces. However, we want the further elaboration and optimization of the tau system to be based on user experience not just speculation. Some tools we [3mthink[0m might help are listed below. We invite volunteers and further suggestions. [3mA tau-centric signature notation[0m for use in function definitions, exploited by a macro replacing [47mdefun[0m so that input-output relationships phrased in tau terms are proved as [47m:tau-system[0m rules immediately after functions are introduced: We have, for example, experimented with a book defining a macro that allows the definition of the function [47map[0m (append) accompanied by a signature rule. Subsequent [47mdefsig[0m events can add other signatures in the same notation. (defsig ap (true-listp * true-listp ==> true-listp) (x y) (if (consp x) (cons (car x) (ap (cdr x) y)) y)) (defsig ap (integer-listp * integer-listp ==> integer-listp)) This experimental book provides succinct syntax for all tau signatures. For example, that book parses the signature (NATP (/= 3 5 7) (< 16) * TRUE-LISTP ==> BOOLEANP * INTEGER-LISTP * NATP) to be the signature of a function with two inputs and three outputs. The first input must be a natural number, different from 3, 5, and 7, and less than 16. The second input must be a true list. The first output is a boolean, the second a list of integers, and the third a natural. To express this signature for function [47mfn[0m as a formula requires significantly more typing by the user: (IMPLIES (AND (NATP X) (NOT (EQUAL X 3)) (NOT (EQUAL X 5)) (NOT (EQUAL X 7)) (< X 16) (TRUE-LISTP Y)) (AND (BOOLEANP (MV-NTH 0 (FN X Y))) (INTEGER-LISP (MV-NTH 1 (FN X Y))) (NATP (MV-NTH 2 (FN X Y))))) We suspect that the provision of some succinct tau-centric notation (not necessarily the one above) for signatures at definition-time will mean users get more benefit from the tau system. [3mSome tau inference mechanisms[0m: This phrase suggests two different improvements. One is to implement a mechanism that adds or completes signatures for function definitions by exploiting knowledge of commonly used recursive schemas and the signatures of the subroutines in the body. For example, the definition of [47map[0m above rather obviously has the signature (integer-listp * integer-listp ==> integer-listp) and many others just based on the two recursive schemas that (a) collect certain elements from lists and (b) check that all elements have a certain property. The other ``tau inference'' improvement is to implement a mechanism for inferring relations between user-defined Booleans, perhaps by exploiting example generation, testing, and knowledge of recursive schemas. For example, it is fairly obvious that [47m[symbol-alistp][0m implies [47m[alistp][0m. Making the user state these relations invites omissions that render the tau system very unpredictable. [3mA tau assistant[0m: It would be useful to have a way to find out what tau rules are missing. Given a term that the user believes should ``obviously'' have some tau (``type'') what rules might be added to make the tau algorithm compute that expected tau? For example, if [47m(g x)[0m is known to satisfy [47mP[0m and [47m(f x)[0m is known to satisfy [47mR[0m when its argument satisfies [47mS[0m: g : T ==> P f : S ==> R then if the user asserts that [47m(f (g x))[0m ``ought'' to have tau [47mR[0m, one plausible suggestion is the simple tau rule that [47m(P x)[0m implies [47m(S x)[0m. Such assistance --- while still confronting an undecidable problem --- might be easier to implement within the tau framework than more generally in ACL2. (Many users have wanted such an assistant to suggest lemmas for the rewriter.)") (gag-mode (output-controls) "Verbosity of proof output Please see [set-gag-mode] for an explanation of gag-mode, which can take any of the following values: (gag-mode) ; generally evaluates to t, nil, or :goals") (gc$ (miscellaneous acl2-built-ins) "Invoke the garbage collector This function is provided so that the user can call the garbage collector of the host Lisp from inside the ACL2 loop. Specifically, a call of [47mgc$[0m is translated into a call of a function below on the same arguments. Allegro CL: excl:gc CCL ccl::gc CLISP ext:gc CMU Common Lisp system::gc GCL si::gbc [default argument list: (t)] LispWorks hcl::gc-generation [default argument list: (7) for 64-bit OS, else (3)] SBCL sb-ext:gc The arguments, if any, are as documented in the underlying Common Lisp. It is up to the user to pass in the right arguments, although we may do some rudimentary checks. Also see [gc-verbose]. Evaluation of a call of this macro always returns [47mnil[0m. To include [47mgc$[0m in a book, one can use [47mvalue-triple[0m: (value-triple (gc$)) Subtopics [Gc-verbose] Control printing from the garbage collector") (gc-strategy (miscellaneous acl2-built-ins) "The garbage collection strategy The form [47m(gc-strategy state)[0m provides the value the current garbage collection strategy if that notion is supported by the underlying host lisp (currently, CCL only). The logical story is that [47mgc-strategy[0m reads its value from the [47moracle[0m field of the ACL2 [47m[state][0m. The return value is thus a triple of the form [47m(mv erp val state)[0m, where [47merp[0m will always be [47mnil[0m in practice, and logically, [47mval[0m is the top of the acl2-oracle field of the state (see [47m[read-ACL2-oracle][0m) and the returned state has the updated (popped) acl2-oracle. For more information, see [set-gc-strategy].") (gc-verbose (gc$) "Control printing from the garbage collector General Form: (gc-verbose arg &optional arg2) Garbage collection (gc) is performed by every Lisp implementation; see [gc$]. However, different ACL2 builds might see more or fewer messages. This macro is intended to provide an interface for controlling the verbosity, which is off if the (first) argument evaluates to [47mnil[0m and otherwise is on. The second (optional) argument is currently ignored except when the host Common Lisp implementation is CCL, where it specifies verbosity for EGC. The above functionality is only supported for the following host Common Lisp implementations: CCL, CMUCL, and GCL. Otherwise, the only effect of this macro is to print a notice that it is not supported. You are welcome to contact the ACL2 developers if you would like to help in adding such support for another host Common Lisp. Evaluation of a call of this macro always returns [47mnil[0m.") (gcl (miscellaneous) "Tips on building and using ACL2 based on Gnu Common Lisp See the [installation] instructions for basic information about building ACL2 on top of GCL, including information about where to fetch GCL. Here, we provide some tips that may be useful. 1. You can place forms to evaluate at start-up into file [47minit.lsp[0m in the directory where you are starting ACL2 (GCL), or into file [47macl2-init.lsp[0m in your home directory. For example, in order to evaluate both of the lisp forms mentioned in 2 below, you could put them both into [47minit.lsp[0m in the current directory or in [47m~/acl2-init.lsp[0m (either way, without [47m(lp)[0m or [47m:q[0m): (setq si::*optimize-maximum-pages* nil) (si::allocate 'cons 75000 t) Note that if you want to put ACL2 patches in this file, you should precede them with (in-package "ACL2"). 2. Suppose you run out of space, for example with an error like this: Error: The storage for CONS is exhausted. Currently, 59470 pages are allocated. Use ALLOCATE to expand the space. The following suggestion from Camm Maguire will minimize the heap size, at the cost of more garbage collection time. :q ; exit the ACL2 loop (setq si::*optimize-maximum-pages* nil) (lp) ; re-enter the ACL2 loop A second thing to try, suggested by several people, is to preallocate more pages before the run, e.g.: :q ; exit the ACL2 loop (si::allocate 'cons 75000 t) (lp) ; re-enter the ACL2 loop Also see [reset-kill-ring] for a suggestion on how to free up space. 3. Windows users have seen this error: cc1.exe: unrecognized option `-fno-zero-initialized-in-bss' Camm Maguire suggests that a solution may be to evaluate the following in GCL before building ACL2. (in-package 'compiler) (let* ((x `-fno-zero-initialized-in-bss') (i (search x *cc*))) (setq *cc* (concatenate 'string (subseq *cc* 0 i) (subseq *cc* (+ i (length x)))))) 4. It is possible to profile using ACL2 built on GCL. See file [47msave-gprof.lsp[0m in the ACL2 source directory. 5. Some versions of GCL may have garbage-collector bugs that, on rare occasions, cause ACL2 (when built on GCL) to break. If you run into this, a solution may be to execute the following: :q (si::sgc-on nil) (lp) Alternatively, put [47m(si::sgc-on nil)[0m in your [47m~/acl2-init.lsp[0m file. A full regression test and found that this decreased performance by about 10%. But even with that, GCL is probably one of the faster Common Lisp implementations for ACL2 on Linux. Performance figures may often be found by following the ``Recent changes'' link on the ACL2 home page. 6. GCL operations on numbers can sometimes be sped up, perhaps by up to two orders of magnitude, by suitable [47m[declare][0m forms (also see [type-spec]). The following example, developed with Warren Hunt and Serita Nelesen, illustrates the use of such declarations. (This was some years ago, and the sizes of 28 and 29 can probably be increased now that Lisp implementations are 64-bit, with larger bounds on so-called fixnums.) ; File iplus.lisp: ; Operations on naturals together with positive infinity (represented as -1). ; After (ld "iplus.lisp"), escape to raw Lisp with :q and then evaluate ; (disassemble 'big-test). You should see lots of arithmetic operations ; in C code, but no calls of C functions CMPmake_fixnum or number_plus. (in-package "ACL2") (defmacro i-max () (expt 2 (1- 28))) (defmacro i+ (x y) `(the (signed-byte 28) (let ((x ,x) (y ,y)) (declare (type (signed-byte 28) x y)) (cond ((or (< x 0) (< y 0)) -1) (t (let ((result (the (signed-byte 29) (+ x y)))) (declare (type (signed-byte 29) result)) (cond ((>= result (i-max)) -1) (t (the (signed-byte 28) result))))))))) (defmacro imin (x y) `(the (signed-byte 28) (let ((x ,x) (y ,y)) (declare (type (signed-byte 28) x y)) (cond ((< x 0) (cond ((< y 0) -1) (t y))) ((< y 0) x) (t (the (signed-byte 28) (min x y))))))) (defun big-test (x y z) (declare (type (signed-byte 28) x y z)) (imin (i+ x y) (i+ y (imin x z)))) 7. You may want to set environment variable [47mGCL_MEM_MULTIPLE[0m when running regression tests using ACL2 built on GCL, to keep memory from exceeding what is available. Consider dividing 1.0 by the number of threads; so for example, for 4 threads (i.e., using ``[47m-j 4[0m'' in your [47mmake[0m command), you may want to specify [47mGCL_MEM_MULTIPLE=0.25[0m. But you can probably run with more threads (e.g., perhaps 20 threads or more on a 64 MB machine) by instead doing a ``pooled memory run'', which may be performed as in the following example (bash syntax), as suggested by Camm Maguire. Warning: the use of [47mHOME[0m may change soon if it hasn't already. HOME=/tmp ACL2=$(pwd)/saved_acl2 GCL_MULTIPROCESS_MEMORY_POOL=t \ make -j 20 regression-fresh (Technical explanation: The reason for setting [47mHOME[0m to directory [47m/tmp[0m is to keep a so-called ``pool file'' local, since otherwise it will be on your home directory, which may be updated too infrequently if on a shared file system.)") (gcs (pointers) "See [get-command-sequence].") (geneqv (introduction-to-the-theorem-prover break-rewrite) "the rewriter's generated equivalence relation As the rewriter descends through a term, rewriting the subterms, it uses [congruence] rules to determine which [equivalence]s may be used to rewrite one subterm to another while ensuring that each rewrite maintains a given equivalence. Generally speaking multiple equivalences may be used to rewrite subterms. A ``generated equivalence'' or ``geneqv'' (pronounced ``genequiv'') is the way we encode which equivalences may be used by the rewriter at any given subterm position. The outline of this discussion is as follows. * Basic Support for Equivalence Relations: a review of equivalence relations, refinement, and congruence * Salient Facts about the ACL2 Rewriter: a review of how the rewriter works * Using Congruence Rules to Generate Acceptable Equivalences for Subterms: an illustration of how congruence rules are used to determine the equivalences the rewriter is permitted to use * Debugging Tools: How to see what equivalences are permitted while rewriting the current target and how to see how the set evolved as the rewriter descended from the top-level goal. Basic Support for Equivalence Relations If you do not know what the following ACL2 macro forms do, you should see their documentation. ; prove and store that eqv is an equivalence relation: (defequiv eqv) ; prove and store that the equivalence relation eqv1 ; refines the equivalence relation eqv2 (defrefinement eqv1 eqv2) ; prove and store that the equivalence relation eqv1 is a congruence relation ; for the kth argument of the function f, preserving the equivalence relation ; eqv2. (defcong eqv1 eqv2 (f x1 ... xn) k) An example of the last form is (defcong set-equal iff (member e x) 2) which essentially expands to (defthm set-equal-implies-iff-member-2 (implies (set-equal x y) (iff (member e x) (member e y))) :rule-classes (:congruence)) (ACL2 actually generates a different variable name in place of [47my[0m above.) Helpful documentation topics include [equivalence], [refinement], [congruence], [47m[defequiv][0m, [47m[defrefinement][0m, and [47m[defcong][0m. Salient Facts about the ACL2 Rewriter * Goals, which are represented as clauses, are simplified by rewriting each literal in turn, assuming the other literals false. * When a term is rewritten (under some assumptions) the rewriter is given an [equivalence] relation to maintain, i.e., the output of the rewriter must be equivalent in that sense to the input, under the assumptions. * The initial equivalence relation to be maintained while rewriting a literal is [47m[iff][0m. * Each [47m:[0m[47m[rewrite][0m rule in ACL2 effectively concludes with a term of the form [47m(eqv lhs rhs)[0m, where [47meqv[0m is an equivalence relation. Such a rule may be used to replace instances of [47mlhs[0m by the corresponding instance of [47mrhs[0m, and maintains the equivalence relation [47meqv[0m. But the rule is only applicable if [47meqv[0m [3mrefines[0m the equivalence relation to be maintained by rewrite. See [refinement]. * If the term to be rewritten is a function call, [47m(fn a1 ... ak)[0m, the rewriter rewrites each [47mai[0m to, say, [47mai'[0m, before applying rules to [47m(fn a1' ... ak[0m'). To be more precise, when the ACL2 rewriter is asked to rewrite [47m(fn a1 ... an)[0m maintaining some equivalence [47meqv[0m, it first rewrites each [47mai[0m, maintaining an equivalence generated from the congruence rules about how to rewrite the [47mi[0mth argument of [47mfn[0m maintaining [47meqv[0m. Suppose each [47mai[0m is thus rewritten to some other term [47mai'[0m. That is, [47m(fn a1 ... an)[0m is transformed to [47m(fn a1' ... an[0m') which is known to be [47meqv[0m-equivalent to [47m(fn a1 ... an)[0m. Then the rewriter applies all the [47meqv[0m rules it knows to [47m(fn b1 ... bn)[0m. * How the rewriter uses the known [congruence] rules to determine the equivalence relation to be maintained while rewriting each [47mai[0m is illustrated below. * [47mEqual[0m refines all equivalence relations. * [47mEqual[0m maintains all equivalence relations across all argument positions of all functions. Using Congruence Rules to Generate Acceptable Equivalences for Subterms In this section show how ACL2 generates the equivalence relation it will maintain when diving into subterms. We do so by discussing a couple of contrived examples. The actual script for these examples is in [47mbooks/demos/geneqv.lisp[0m. Our examples use the following functions. * [47mLen[0m is an ACL2 primitive that determines the number of elements in a list. * [47m(perm x y)[0m determines whether [47mx[0m is a permutation of [47my[0m, i.e., whether each element that occurs in either [47mx[0m or [47my[0m occurs in both the same number of times. For example [47m(perm '(A B A C) '(C B A A))[0m is true, but [47m(perm '(A B A C) '(A B B C))[0m is false. * [47m(pairwise-iff x y)[0m determines whether corresponding elements of [47mx[0m and [47my[0m are propositionally equivalent (i.e., [47mIFF[0m-equivalent). For example, [47m(pairwise-iff '(T NIL T) '(1 NIL A))[0m is true (since both [47m1[0m and [47mA[0m are non-[47mNIL[0m and thus propositionally equivalent to [47mT[0m), but [47m(pairwise-iff '(T NIL T) '(1 NIL NIL))[0m is false. * Both [47mperm[0m and [47mpairwise-iff[0m can be proved to be [equivalence] relations. * Both [47mperm[0m and [47mpairwise-iff[0m are congruence relations for the first argument of [47mlen[0m that maintain [47mequal[0mity of [47mlen[0m. (defthm perm-implies-equal-len-1 (implies (perm x y) (equal (len x) (len y))) :rule-classes (:congruence)) (defthm pairwise-iff-implies-equal-len-1 (implies (pairwise-iff x y) (equal (len x) (len y))) :rule-classes (:congruence)) Now consider proving (defthm example-thm-1 (equal (len (isort (norml x))) (len x)) :rule-classes nil) Before we start you should understand that there are many ways to prove this little theorem. The most straightforward is just to prove that [47m(len (isort x))[0m is [47m(len x)[0m and to prove [47m(len (norml x))[0m is [47m(len x)[0m. In this case, where the functions involved are [47misort[0m and [47mnorml[0m, those theorems are easy to prove. But for some functions in those roles of a problem like this it is easier to appeal to the properties of certain equivalence relations. That's what we'll do here. If you run the [47mdefthm[0m above, the prover (after preprocessing) eventually calls the rewriter on the [47mequal[0m term, requiring it to maintain [47miff[0m. The rewriter then dives into the two arguments, rewriting [47m(len (isort (norml x)))[0m first, maintaining [47mequal[0mity. The rewriter then dives into the first argument of the [47mlen[0m term, [47m(isort (norml x))[0m. The congruence rule [47mperm-implies-equal-len-1[0m above tells it that [47mequal[0mity of the [47mlen[0m term is maintained if the first argument is rewritten maintaining the [47mperm[0m equivalence. In addition, the congruence rule [47mpairwise-iff-implies-equal-len-1[0m tells it that [47mequal[0mity of the [47mlen[0m term is also maintained if the first argument is rewritten maintaining the [47mpairwise-iff[0m equivalence. Thus, when rewriting [47m(isort (norml x))[0m the rewriter can use any rewrite rule that maintains [47mperm[0m, any rewrite rule that maintains [47mpairwise-iff[0m, and, of course, any rewrite rule that maintains [47mequal[0m. In addition, of course, it can use any rewrite rule that maintains a refinement of any of these equivalence relations. This ``generated equivalence'' or ``geneqv'' is denoted by a set containing the named equivalence relations and the justifying congruence rules. The geneqv just derived is represented internally as ((5658 PAIRWISE-IFF :CONGRUENCE PAIRWISE-IFF-IMPLIES-EQUAL-LEN-1) (5651 PERM :CONGRUENCE PERM-IMPLIES-EQUAL-LEN-1)) Ignoring the two numbers, we see two pairs, each naming an equivalence relation and the [rune] that justifies its use here. The numbers are session-specific indices uniquely associated with the two runes that allow ACL2 to determine quickly if the runes are enabled. Note that we do not include an entry for [47mEQUAL[0m since it maintains every equivalence relation in every argument position of every function. Indeed, if you see a geneqv of [47mNIL[0m it means [47mEQUAL[0m is the only acceptable equivalence relation in that context. Debugging tools in ACL2 typically display the geneqv above as ((PAIRWISE-IFF PAIRWISE-IFF-IMPLIES-EQUAL-LEN-1) (PERM PERM-IMPLIES-EQUAL-LEN-1)) or even (PAIRWISE-IFF PERM). We discuss debugging tools that display geneqvs below. But what does this geneqv buy us during this proof? Recall where we were in the proof discussed above. We're rewriting [47m(isort (norml x))[0m maintaining [47m(PAIRWISE-IFF PERM)[0m. If the user had proved the following two rewrite rules (defthm perm-isort ; isort preserves perm (perm (isort X) X)) (defthm pairwise-iff-norml ; norml preserves pairwise-iff (pairwise-iff (norml x) x)) then the rewriter would replace [47m(isort (norml x))[0m by [47m(norml x)[0m using the first rule, since [47mperm[0m is a refinement of the geneqv, and then the rewriter would rewrite that and replace it by [47mx[0m using the second rule, since [47mpairwise-iff[0m is also a refinement of the geneqv. Note that neither of these replacements preserve [47mequal[0mity, but they are permitted because they preserve the [47mequal[0mity of the [47mlen[0ms. Thus, [47m(equal (len (isort (norml x))) (len x))[0m has been simplified to [47m(equal (len x) (len x))[0m which further simplifies to [47mt[0m and the proof is done. The Community Book [47m"books/demos/geneqv-test-book.lisp"[0m (which executes the commands in books/demos/geneqv-test-input.lsp) contains this and other examples. Debugging Tools Generated equivalence relations are never mentioned or displayed in the prover output. But of course they are crucial since they determine which rewrite rules can be used. If a rule was expected to be used in a proof or proof attempt but was not used it might be because the rule's equivalence relation failed to be a refinement of the geneqv in effect when the intended target was encountered. If [47m[brr][0m is enabled and a [47m[monitor][0med rule is tried by the rewriter but does not fire because it failed the refinement test, a [break-rewrite] interactive break occur. See [refinement-failure] for some advice for how you might respond to such a failure. From within a break-rewrite break the [47m[brr-commands][0m [47m:path[0m will print the ``path'' from the current top-level goal down to the call of the rewriter on current [47m:target[0m term. Like a call stack, the path is composed of ``frames,'' most of which describe calls of the rewriter but some of which are calls of other system functions (like the [47m[linear-arithmetic][0m procedure) that orchestrate other calls to the rewriter. As of Version 8.6, each frame of the [47m:path[0m that describes the attempt to apply a particular rewrite rule will display the name of the equivalence relation used by the rule (unless that name is [47mequal[0m). Every frame describing a call of the rewriter includes the geneqv to be maintained as the target is rewritten (unless the geneqv is [47mnil[0m which denotes the [47mequal[0mity relation). The noted exceptions are intended to shorten the output in the most common cases: rewriting with [47mequal[0m and maintaining equality. In addition, from within such a break the brr-command [47m:geneqv[0m will print the geneqv for the current target.") (generalize (rule-classes) "Make a rule to restrict generalizations See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Example: (defthm integer-listp-rev (implies (integer-listp x) (integer-listp (rev x))) :rule-classes :generalize) General Form: any theorem To use a [47m:generalize[0m rule, the system waits until it has decided to generalize some term, [47mterm[0m, by replacing it with some new variable [47mv[0m. If any [47m:generalize[0m formula can be instantiated so that some non-variable subterm becomes [47mterm[0m, then that instance of the formula is added as a hypothesis. Thus for the example above, if the term [47m(rev x2)[0m is generalized to the variable [47mrv[0m during a proof, then the following is added as a hypothesis when generalizing to a new goal. (implies (integer-listp x2) (integer-listp rv)) At the moment, the best description of how ACL2 [47m:generalize[0m rules are used may be found in the discussion of ``Generalize Rules,'' page 248 of A Computational Logic Handbook, or ``Generalization,'' page 132 of ``Computer-Aided Reasoning: An Approach.'' Also see [introduction-to-the-theorem-prover] for detailed tutorial on using ACL2 to prove theorems, which includes some discussion of generalization.") (generalized-booleans (common-lisp) "Potential soundness issues related to ACL2 predicates The discussion below outlines a potential source of unsoundness in ACL2. Although to our knowledge there is no existing Lisp implementation in which this problem can arise, nevertheless we feel compelled to explain this situation. Consider for example the question: What is the value of [47m(equal 3 3)[0m? According to the ACL2 axioms, it's [47mt[0m. And as far as we know, based on considerable testing, the value is [47mt[0m in every Common Lisp implementation. However, according the Common Lisp draft proposed ANSI standard, any non-[47mnil[0m value could result. Thus for example, [47m(equal 3 3)[0m is allowed by the standard to be [47m17[0m. The Common Lisp standard specifies (or soon will) that a number of Common Lisp functions that one might expect to return Boolean values may, in fact, return arbitrary values. Examples of such functions are [47m[equal][0m, [47m[rationalp][0m, and [47m[<][0m; a much more complete list is given below. Indeed, we dare to say that every Common Lisp function that one may believe returns only Booleans is, nevertheless, not specified by the standard to have that property, with the exceptions of the functions [47mnot[0m and [47mnull[0m. The standard refers to such arbitrary values as ``generalized Booleans,'' but in fact this terminology makes no restriction on those values. Rather, it merely specifies that they are to be viewed, in an informal sense, as being either [47mnil[0m or not [47mnil[0m. This situation is problematic for ACL2, which axiomatizes these functions to return Booleans. The problem is that because (for efficiency and simplicity) ACL2 makes very direct use of compiled Common Lisp functions to support the execution of its functions, there is in principle a potential for unsoundness due to these ``generalized Booleans.'' For example, ACL2's [47m[equal][0m function is defined to be Common Lisp's [47mequal[0m. Hence if in Common Lisp the form [47m(equal 3 3)[0m were to evaluate to 17, then in ACL2 we could prove (using the [47m:[0m[47m[executable-counterpart][0m of [47m[equal][0m) [47m(equal (equal 3 3) 17)[0m. However, ACL2 can also prove [47m(equal (equal x x) t)[0m, and these two terms together are contradictory, since they imply (instantiating [47mx[0m in the second term by [47m3[0m) that [47m(equal 3 3)[0m is both equal to [47m17[0m and to [47mt[0m. To make matters worse, the standard allows [47m(equal 3 3)[0m to evaluate to [3mdifferent[0m non-[47mnil[0m values every time. That is: [47mequal[0m need not even be a function! Fortunately, no existing Lisp implementation takes advantage of the flexibility to have (most of) its predicates return generalized Booleans, as far as we know. We may implement appropriate safeguards in future releases of ACL2, in analogy to (indeed, probably extending) the existing safeguards by way of guards (see [guard]). For now, we'll sleep a bit better knowing that we have been up-front about this potential problem. The following list of functions contains all those that are defined in Common Lisp to return generalized Booleans but are assumed by ACL2 to return Booleans. In addition, the functions [47m[ACL2-numberp][0m and [47m[complex-rationalp][0m are directly defined in terms of respective Common Lisp functions [47mnumberp[0m and [47mcomplexp[0m. /= < = alpha-char-p atom char-equal char< char<= char> char>= characterp consp digit-char-p endp eq eql equal evenp integerp keywordp listp logbitp logtest lower-case-p minusp oddp plusp rationalp standard-char-p string-equal string< string<= string> string>= stringp subsetp symbolp upper-case-p zerop") (generalizing-key-checkpoints (introduction-to-the-theorem-prover) "Getting rid of unnecessary specificity Suppose [47mMEMBER[0m determines whether its first argument is a member of its second, and [47mSUBSETP[0m determines whether every element of its first argument is a member of its second. Suppose that you're trying to prove some Main Theorem and are told the formula below is a key checkpoint. What should you do? Key Checkpoint: (IMPLIES (AND (CONSP A) (INTEGERP (CAR A)) (MEMBER (CAR A) B) (SUBSETP (CDR A) B) (NOT (SUBSETP (CDR A) (APPEND B C)))) (MEMBER (CAR A) C)) The key observation is that the fourth hypothesis implies the negation of the fifth. Writing it in the contrapositive: (IMPLIES (AND ... (SUBSETP (CDR A) B) ...) (SUBSETP (CDR A) (APPEND B C))) In fact, that is more complicated than it needs to be. A ``correct'' response to the key checkpoint above is to prove (defthm subsetp-append (implies (subsetp a b) (subsetp a (append b c)))). A still better response is to prove this: (defthm subsetp-append-2 (implies (or (subsetp a b) (subsetp a c)) (subsetp a (append b c)))). This version is better because it handles both of the possibilities regarding whether [47ma[0m is a subset of the arguments of the [47mappend[0m. It would be nice if we could think of a ``strong'' version, one in which [47m(SUBSETP a (APPEND b c))[0m is rewritten to some clearly simpler term, but nothing comes to mind. In any case, if you cannot see any obvious simplification of the individual terms in the Key Checkpoint, you should ask yourself whether there are connections between the various propositional parts (as here, with the fourth and fifth hypotheses). It is a good heuristic to look for relations between parts with the same top-level function symbol (as here, with [47mSUBSETP[0m). It is also a good heuristic to throw out parts of the formula that seem disconnected (as here, with the terms involving [47m(CAR A)[0m). This discussion suggests several ``modes'' of looking at key checkpoints and the idea of trying the modes in sequence: (1) look for simplifiable combinations of function symbols within propositional components, (2) look for relations between propositional components, and (3) throw out irrelevant or weakly connected components. In all cases you are bringing to bear your intuitions about the [3msemantics[0m of the terms. That is, you're not just slinging symbols. You should be looking out for obvious truths about individual parts of the checkpoints... truths that are obvious to you but not to ACL2! Ultimately the three ``modes'' are the same and we do not really recommend adhering to the given sequence. You're just looking for simpler theorems that, in combination, imply the checkpoint. Keeping the ``modes'' in mind may help focus your attention so you consider all the plausible possibilities. After a little experience you'll find yourself looking for all these things simultaneously as part ``cleaning up'' the checkpoints. When your main goal theorems are harder than these, your main concern will be looking at a Key Checkpoint and asking yourself ``why is this true?'' But you don't want to do that until you've cleaned it up ``locally'' as much as possible and sometimes --- more often than you might think --- local considerations can prove many of your checkpoints. If you have been working your way through the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-key-checkpoints].") (gentle-introduction-to-acl2-programming (start-here) "A Gentle Introduction to ACL2 Programming A Gentle Introduction to ACL2 Programming [3mby[0m J Strother Moore Abstract ACL2 is a logic and programming language in which you can model computer systems, together with a tool to help you prove properties of those models. ``ACL2'' denotes ``A Computational Logic for Applicative Common Lisp''. The ACL2 programming language is a subset of [3mside-effect free[0m Common Lisp. Mathematically speaking, all ACL2 programs are functions. When two calls of a function supply the same objects as inputs the calls return the same results. If all you want to do is define ACL2 functions and run them, you don't need to know how to use ACL2 as a theorem prover. This introduction is all you need. Getting Started If you haven't installed ACL2 on your machine, do so, by following the instructions at ``Obtaining, Installing, and License'' on the {ACL2 Home Page | https://www.cs.utexas.edu/users/moore/acl2}. As those instructions make clear, to run ACL2 you'll need a Common Lisp implementation. The instructions name several suitable ones. In addition to the [installation] instructions, the Home Page has a wealth of documentation. You should visit ``The User's Manuals''. There you'll see several versions of the manual, depending on whether you want information about utilities developed by users. But we recommend that newcomers just look at the basic ``ACL2 User's Manual''. Explore it briefly just so you know how to find more information. For example, type ``defun'' into the Jump to box and hit return. You'll see details of how to define functions and there are many links in that discussion to related topics. But don't try to understand [47mdefun[0m by reading all that. The manual is basically for users who are looking for technical information about features they basically know how to use. Having learned how to explore the manual, put it aside for now and focus on this document! The interface to the ACL2 system is a read-eval-print loop. It prints a prompt. You type some command and hit return. It reads and evaluates your command. It prints the results. And then it prompts you for your next input. You could use ACL2 with no other interface. But most users prefer an environment in which they can prepare a command by editing the text before submitting it. We use an Emacs shell buffer for that. Other users use ACL2s (see [ACL2-SEDAN]), which is an Eclipse plug-in. This guide doesn't discuss the interface further and we just assume you can submit commands and see the output. The examples we provide are from our Emacs interface. ACL2 is implemented (largely) in ACL2. That is, almost all the system code is written in the ACL2 subset of Common Lisp. The examples provided here were prepared under ACL2 Version 8.5. Your output should be logically equivalent though the text may look a little different. Now fire up your ACL2. You should see a prompt that looks like this ACL2 !> Type ``:program'' and a return. ACL2 !>:program ACL2 p!> The [47m:program[0m command tells ACL2 that subsequent definitions should merely be treated as ACL2 programs and not admitted into the logic. (To admit a program into the logic requires proving that the program terminates. We do not want to deal with proofs of any sort in this guide, so we'll stay in [47m:program[0m mode.) Now type ``[47m(+ 2 2)[0m''. You should see the answer, [47m4[0m printed on the next line. This illustrates the basic behavior of ACL2's read-eval-print loop. The display below shows several other examples too. ACL2 !>:program ACL2 p!>(+ 2 2) 4 ACL2 p!>(+ 1 2 3 4) 10 ACL2 p!>(car '(hello world)) HELLO ACL2 p!>(cdr '(hello world)) (WORLD) ACL2 p!>(cons 'hello '(world)) (HELLO WORLD) ACL2 p!> Sometimes computations cause errors, most commonly due to type violations or resource limitations. See the sections Type Errors and Stack Overflow below. Here is an ACL2 program that takes a linear list of numbers and constructs a linear list of their squares. We've annotated it with Lisp comments. ACL2 ignores the comments. We'll explain the syntax later. For now we'll just interpret what this whole definition means. (defun square-all (x) ; Make a list of the squares of the elements of the list x. (cond ((endp x) ; If x is empty, nil) ; return the empty list. (t ; Otherwise, (cons (* (car x) (car x)) ; square the first element and (square-all (cdr x)))))) ; cons it onto the front of ; the squares of the rest. If you aren't sure what a ``linear list'' is just hang in and we'll get to it. But you've probably figured out that [47mnil[0m is the empty list, that [47mcons[0m constructs a list by ``adding'' an element to the front of another list, that [47mcar[0m returns the first element of a non-empty list, and that [47mcdr[0m returns all but the first element of a non-empty list. Those deductions are right, as far as they go. Here is what it looks like if you submit the [47msquare-all[0m definition to the read-eval-print loop. We have omitted most of the previous commands and their output, and we have omitted the comments we included in the display above. ACL2 !>:program ... ACL2 p!>(cons 'hello '(world)) (HELLO WORLD) ACL2 p!>(defun square-all (x) (cond ((endp x) nil) (t (cons (* (car x) (car x)) (square-all (cdr x)))))) Summary Form: ( DEFUN SQUARE-ALL ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) SQUARE-ALL ACL2 p!> Once [47msquare-all[0m is defined we can run it. Here are some tests. ACL2 p!>(square-all '(1 2 3 4 5)) (1 4 9 16 25) ACL2 p!>(square-all nil) NIL ACL2 p!>(square-all '(-9 3/4 #c(0 5))) (81 9/16 -25) ACL2 p!> Data Types ACL2 supports five very simple but rather abstract types of data: * numbers, * characters, * strings, * symbols (which includes the two Booleans [47mT[0m and [47mNIL[0m), and * pairs or ``conses''. Objects of each type are distinct. That is, no number is a character or a string or a symbol or a pair. Etc. All of these objects are ``first class'' in the sense that you can pass them in as values to functions, return them as values from functions, and store them in lists and trees. Many operators are provided for each type. Each operator is a [3mfunction[0m. [3mNo ACL2 operator or function can modify, mutate, or otherwise alter the objects passed in as arguments.[0m Since you're probably more familiar with conventional programming languages than functional (side-effect free) ones, let's talk operationally for a moment. (This is a disservice to you! The operational view is more complicated than the abstract mathematical view!) ACL2 is implemented on top of a von Neumann architecture. So what happens ``behind the scenes'' when the ACL2 function [47mcons[0m is called on [47m4[0m and [47m5[0m? Mathematically it returns the pair < [47m4[0m, [47m5[0m > which is printed in ACL2 as [47m(4 . 5)[0m. But operationally, some memory is allocated for a new object, then the representations of 4 and 5 are stored in two fields (called the [3mcar[0m and [3mcdr[0m fields) of that object, that region of memory is effectively tagged to indicate that it represents a [47mcons[0m pair, and a pointer to the newly allocated object is returned as the result of the call of [47mcons[0m. When that result is printed by ACL2 it appears as [47m(4 . 5)[0m. The italicized sentence above means [3mnothing you can do in ACL2 will change the contents of that newly allocated memory.[0m In most programming languages you could invoke some procedure or method to overwrite the contents of the [3mcar[0m field of that object, changing it from [47m4[0m to [47m3[0m. No such procedure or method exists in ACL2. The object returned by that call of [47mcons[0m will print as the pair [47m(4 . 5)[0m --- will [3mbe[0m the pair [47m(4 . 5)[0m --- for as long as you have access to the pointer returned by that call of [47mcons[0m. ACL2 expressions are just nests of function calls. For example [47m(factors (+ x (* 3 y)))[0m calls the function [47mfactors[0m on the value of [3mx+3y[0m. (We define [47mfactors[0m below to return the list of prime factors of its input.) The functions [47m+[0m and [47m*[0m are examples of functions that operate on numbers. Before we discuss ACL2 expressions further we must discuss the important issue of how you write down constants of each of the five types. A few examples suffice to illustrate the common ways to enter numeric constants: [47m123[0m, [47m22/7[0m and [47m#c(3 5)[0m. Note that ACL2 provides ``infinitely precise'' rational numbers like [47m1/3[0m and [47m22/7[0m. These are not floating point numbers; we don't provide floating point numbers. The rational [47m2/3[0m could also be written [47m4/6[0m --- they are two different ways of writing the same number. The ACL2 number [47m#c(3 5)[0m is more conventionally written as the complex number [3m3+5i[0m. ACL2 also supports writing numeric constants in binary, octal and hexadecimal notation, but we do not use that here. We will list some operations on numbers later. Here are examples of how to write character objects: [47m#\A[0m and [47m#\a[0m and [47m#\Space[0m. Character objects are primarily used to build up strings. While ACL2 provides functions for manipulating character objects (e.g., to recover their ASCII codes) we won't be using them here. Strings are delimited by the double quote mark, e.g., [47m"This is an error message."[0m Again, there are functions more manipulating strings but we won't use them in this guide. This leaves us with symbols and conses. Two symbols are easy to understand because they have counterparts in most programming languages: [47mT[0m is a symbol but it is also ACL2's Boolean ``true'' object. [47mNIL[0m is a symbol and is ACL2's Boolean ``false'' object. When an ACL2 predicate is said to be false, we mean the predicate returns [47mNIL[0m. When an ACL2 predicate is said to be true, it usually means it returns [47mT[0m, but more precisely it means it returns anything but [47mNIL[0m. Oddly, Lisp and ACL2 also use the symbol [47mNIL[0m as the ``empty list''. Before we discuss other ACL2 functions however we must deal at length with symbols and conses. Many first-time Lisp programmers do not really understand the idea of symbols as data or the idea of lists and trees as data. Symbols Symbols are sequences of alphabetic letters, signs and digits. So [47mX[0m, [47mX*[0m, and [47mABC23[0m are symbols. So are [47mCAR[0m, [47mIF[0m, and [47mTRUE-LISTP[0m. Note that dashes and other signs do not ``break'' symbols into pieces. [47mTRUE-LISTP[0m is one symbol, not two symbols separated by a minus sign. Technically, a symbol can contain any sequence of characters and there are rules for writing symbols down so as to distinguish them from other constants. Using certain ``escape'' conventions you can actually write symbols containing spaces and parentheses, symbols composed entirely of digits, and symbols with other ``weird'' characters. But we will not go into these conventions in this introduction. We will limit ourselves to symbols that ``look like'' what you probably expect. Most often, symbols start with an alphabetic character and then contain just alphabetic characters, signs and digits. The first space, newline or parenthesis you encounter while reading a symbol marks the end of the symbol and isn't part of it. All programming languages (except binary machine code) have symbols at the syntactic level. Symbols are used to denote variables, functions, operations, keywords, etc., in the syntax of most programming languages. This is true in ACL2 too. But ACL2 is a little different in that it also provides symbols as data objects. That is, in addition to familiar data objects like numbers and strings, ACL2 provides symbols as a kind of data structure that can be manipulated. For example, a symbol can be converted to a string object, or decomposed into its constituent characters, or several symbols can be concatenated to create a longer symbol. But in this introduction we will just pass symbols around, compare them to other objects, and create lists (conses) containing symbols as elements. As noted, [47mT[0m and [47mNIL[0m are symbols with special significance. They are our ``Booleans'' data objects and [47mNIL[0m is used as the ``empty list''. Symbols are more complicated than described above because in addition to their names they belong to ``packages.'' For example, there might be a symbol named [47mABS[0m in a package named [47m"MATH"[0m and a symbol named [47mABS[0m in a package named [47m"VECTORS"[0m. There is always one ``current package'' in ACL2 --- you can select any package as the current package. If [47m"MATH"[0m were the current package, then when you write [47mABS[0m you denote the symbol [47mABS[0m in the [47m"MATH"[0m package. If you mean the symbol [47mABS[0m in the [47m"VECTORS"[0m package you would have to write [47mVECTORS::ABS[0m. We will not use packages here. There is a special package called the [47m"KEYWORD"[0m package. The symbol [47mABS[0m in the [47m"KEYWORD"[0m package can, of course, be written [47mKEYWORD::ABS[0m. But special syntactic sugar also allows us to write [47m:ABS[0m for that symbol. When we write symbols, case is unimportant (unless that previously mentioned ``escape'' convention is used). When reading a symbol all characters are all uppercased. That is, ACL2 reads the symbol [47mx[0m as [47mX[0m. The symbol [47mThe[0m is read as [47mTHE[0m and [47mTrue-Listp[0m is read as [47mTRUE-LISTP[0m. Thus, the choice of whether to write a symbol in uppercase, lowercase, or some mixture of cases is just a stylistic one. ACL2 p!>'(Here is a list of SymBols!) (HERE IS A LIST OF SYMBOLS!) ACL2 p!>'(This list contains a |Weird Symbol|) (THIS LIST CONTAINS A |Weird Symbol|) ACL2 p> ACL2 provides ways to construct symbols from strings, ways to construct strings from lists of character objects, and ways to construct character objects from integers. But elementary ACL2 programs rarely construct new symbols, strings and characters dynamically. The symbols, strings and characters manipulated during most program executions are entered initially in the input data (e.g., by reading a command line or input file). Therefore, we do not bother to describe how to ``create'' symbols, strings and characters and none of our examples create these objects dynamically. Lists We first discuss how to write down ``cons pairs'' and `` list objects''. Later we will describe the operations on them. There are many ways to write the same list constant. This should not be surprising; the same thing is true of numeric constants. Consider the fact that [47m123[0m, [47m000123[0m, [47m+0123[0m, [47m246/2[0m and [47m#b1111011[0m are all ways to write down the same numeric constant. The form you choose when writing a numeric constant is up to you and is often chosen to emphasize some aspect of the data. For example, I might pad an integer with insignificant 0s to emphasize that it fits in a field of six digits, or I might unnecessarily write a + sign on the only positive integer in a data set. Like numbers in other programming languages, lists are so common in ACL2 that there are many ways to write the same list constant but the choice of ``style'' is just that: stylistic. Most programming languages support the idea of some kind of record structure with fields containing other objects. The only such record structure in ACL2 is the [3mordered pair[0m or [3mcons pair[0m. A cons pair is just a pair of two objects. Sometimes we call a cons pair a ``list pair'' or a ``dotted pair'' or simply a ``list.'' Any two objects may be put together into a cons pair. The cons pair containing the integer [47m1[0m and the integer [47m2[0m might be drawn as: * / \ 1 2 or might be written in Cartesian coordinate notation as <[47m1[0m,[47m2[0m>. But in ACL2 it is written as the object [47m(1 . 2)[0m. This is a single cons object in ACL2, with two integer objects as constituents. The left-hand constituent is called the [3mcar[0m of the pair. The right-hand constituent is called the [3mcdr[0m. The tree we might draw as * / \ 1 * / \ 2 3 or write in coordinate notation as <[47m1[0m, <[47m2[0m, [47m3[0m>>, in ACL2 is written the object [47m(1 . (2 . 3))[0m. The car of this object is the integer [47m1[0m. The cdr of this object is the object [47m(2 . 3)[0m. Similarly, * / \ / \ * * / \ / \ 1 2 3 4 or <<[47m1[0m, [47m2[0m>,<[47m3[0m, [47m4[0m>> is written [47m((1 . 2) . (3 . 4))[0m. Suppose [3mx[0m is the cons object just mentioned. Then the car of [3mx[0m is the object [47m(1 . 2)[0m and the cdr is the object [47m(3 . 4)[0m. Obviously, the car of the car of [3mx[0m is [47m1[0m. The cdr of the car of [3mx[0m is [47m2[0m, etc. The notation we are using to write list objects is called [3mdot notation[0m. It is a straightforward translation of the familiar coordinate notation in which parentheses replace the brackets and a dot replaces the comma. But there are other ways to write these conses. This should not be surprising. How many ways can you think of to write the number [47m5[0m? There are an infinite number! [47m5[0m, [47m05[0m, [47m005[0m, [47m+000005[0m, etc., not to mention possibly [47m#B101[0m and others. Those are all just ``syntactic sugar'' for denoting one familiar object. The sugars above might be described as ``you can add a leading [47m0[0m'' and ``you can add a single leading plus sign on a positive number.'' Similarly, ACL2 has two rules that allow us to write cons pairs in a variety of ways. The first rule provides a special way to write trees like: * / \ 1 nil namely, you can write [47m(1 . nil)[0m or you can write [47m(1)[0m. That is: if a cons pair has [47mNIL[0m as its cdr, you can drop the ``dot'' and the [47mNIL[0m. The second rule provides a special way to write a cons pair that contains another cons pair in the cdr. The rule allows us to write [47m([0m[3mx[0m [47m. (...))[0m as [47m([0m[3mx[0m [47m...)[0m. That is, when the cdr is a cons, you can drop the dot and the pair of balanced parentheses following it. Thus, the tree * / \ 1 * / \ 2 * / \ 3 nil can be written in any of the following ways. (1 . (2 . (3 . nil))) (1 . (2 . (3))) (1 . (2 3)) (1 2 3) It can also be written in many other ways, e.g., [47m(1 2 . (3 . nil))[0m and [47m(1 . (2 3))[0m. Binary trees that terminate in [47mnil[0m on the right-most branch, such as the one above, are often called [3mlinear lists[0m. The [3melements[0m of a list are the successive cars along the ``cdr chain.'' That is, the elements are the car, the car of the cdr, the car of the cdr of the cdr, etc. The elements of the list above are [47m1[0m, [47m2[0m, and [47m3[0m, in that order. If we let [3mx[0m denote that tree, i.e., let [3mx[0m be [47m(1 2 3)[0m, then the car of [3mx[0m is [47m1[0m. The cdr of [3mx[0m is the linear list [47m(2 3)[0m. The car of the cdr of [3mx[0m is thus [47m2[0m. The cdr of the cdr of [3mx[0m is the linear list [47m(3)[0m. The car of the cdr of the cdr of [3mx[0m is [47m3[0m. And the ``third cdr'' of [3mx[0m is [47mnil[0m. The linear list [47m(A (B C D) E)[0m has three elements. [47mB[0m is not an element of that list, it is an element of an element. The following is a linear list of pairs. * / \ * \ / \ \ A 1 * / \ * \ / \ \ B 2 * / \ * \ / \ \ C 3 nil This list can be written [47m((A . 1) (B . 2) (C . 3))[0m. In full dot notation it is written ((A . 1) . ((B . 2) . ((C . 3) . NIL))). By the way, lists such as the one above are so common they have a name. They are called [3massociation lists[0m or [3malists[0m and are used as keyed tables. The list above associates the key [47mA[0m with the value [47m1[0m, the key [47mB[0m with the value [47m2[0m, etc. Later we show functions for manipulating alists. Lists are often used to represent more elaborate data structures. For example, an ``account'' might consist of a name, an id number, a balance and a list of transactions, laid out like this: * / \ / \ / \ * * / \ / \ / \ / \ name id bal trans An example of an account object might be (("John Smith" . 123456789) ; Name and id . (1254 . ; balance in cents ((DEPOSIT (1 21 1999) 1000) ; transactions (WITHDRL (1 30 1999) 850) (WITHDRL (2 5 1999) 215)))) Rather than refer to these four components in terms of the [47mcar[0m and [47mcdr[0m of the account object most programmers would define functions with application-specific names like [47maccount-name[0m, [47maccount-id[0m, etc. Instead of building each account object with a nest of [47mcons[0m expressions they would define [47m(make-account name id bal trans)[0m to do the consing. Expressions We've seen that the basic idiom for defining a new function in ACL2 is to write (defun f (v1 ... vn) body) where [47mf[0m is the name of the function, the [47mvi[0m are its input parameters, and [47mbody[0m is an expression that computes the value of the function in terms of the parameters. The [3mn[0m parameters must be distinct variable names and we say that [3mn[0m is the [3marity[0m of the new function [47mf[0m. But what are expressions? With a few exceptions, an expression is either * a variable symbol, * a constant expression, * a call of a function of arity [3mn[0m on [3mn[0m argument expressions (sometimes called the [3mactuals[0m). Variable symbols are written in the same way that symbol objects are written, except [47mT[0m, [47mNIL[0m, and keywords may not be used as variable symbols. Examples of variable symbols are thus [47mX[0m, [47mk[0m, [47mtemp3[0m, and [47minit-val[0m. There are two kinds of constant expressions: those that can just be written as ordinary objects and those that must be quoted. Character objects, strings, numbers, [47mT[0m, [47mNIL[0m, and keywords are of the first kind. They may be used as constant expressions without any additional signifying mark. All other symbols and all list objects must be preceded by a single quote mark (') to be used as constants in an expression. Examples of constant expressions of the first kind are thus [47m#\Space[0m, [47m"EOF Error"[0m, [47m128[0m, [47mT[0m, [47mNIL[0m, and [47m:element[0m. Constant expressions of the second kind include [47m'X[0m, [47m'HELLO[0m, and [47m'(MON WED FRI)[0m. Function calls are written by writing an open parenthesis, the name of the function and the [3mn[0m argument expressions, all separated by whitespace, followed by a close parenthesis. For example [47m(cons (* (car x) (car x)) (square-all (cdr x)))[0m is a function call of the function [47mcons[0m on two argument expressions. The first argument is a call of [47m*[0m on two expressions, both of which are calls of [47mcar[0m on the variable symbol [47mx[0m. The second argument to the call of [47mcons[0m is [47m(square-all (cdr x))[0m, which is a call of [47msquare-all[0m on a call of [47mcdr[0m on [47mx[0m. Consider the list object [47m(CAR X)[0m, which we can draw as * / \ CAR \ * / \ X NIL. This object can be written as [47m(CAR X)[0m. But that is also the way we write the expression that denotes a call of the function [47mCAR[0m on [47mX[0m. So if we want to use that object in an expression we have to quote it to make it clear we mean the object rather than the expression. We have said that an expression is either a variable, a constant, or a function call of a function symbol of arity [47mn[0m on [47mn[0m argument expressions. But there are exceptions to this simple characterization of expressions. One exception is that some functions appear to take varying numbers of arguments. For example, ACL2 allows [47m+[0m and [47m*[0m to take more than two arguments. So [47m(+ (* x x) (* 2 x y) (* y y))[0m is allowed. We'll note other such functions when we use them here. Another exception is a special notation for nested if-then-else expressions described below. These exceptions are actually facilitated by a [3mmacro[0m facility allowing the user to define new notation, but we will not discuss macros here even though we will use and explain some macros in our examples. Finally, ACL2 permits calls of unnamed functions, called [3mlambda expressions[0m, but we won't use them explicitly in this introduction. The reason we say ``explicitly'' is that we will use so-called [47mlet[0m expressions to introduce some local temporary variables and ACL2 understands [47mlet[0m expressions as applications of lambda expressions. We'll explain when we introduce [47mlet[0m. An example expression is (cons (cons 'square-all (cons x nil)) (cons '= (cons (square-all x) nil))) provided [47msquare-all[0m has been defined as a function of arity 1. Note that case is actually unimportant in symbols, whether they are function or variable names or data objects. Unless special conventions are employed all symbols are read in uppercase. Expressions have [3mvalues[0m computed with respect to an environment assigning values to variable symbols. For example, if [47msquare-all[0m is defined as previously shown and [47mx[0m has the value [47m(1 2 3)[0m then the value of the expression above is ((SQUARE-ALL (1 2 3)) = (1 4 9)). Here is the algorithm for determining the value of an expression in an environment. The value of a variable is just looked up in the environment. The value of a constant expression is the obvious object. The value of a call of a defined function is computed by (a) evaluating the [3mn[0m argument expressions to obtain a sequence of [3mn[0m objects, (b) creating a new environment in which the function's [3mn[0m parameters are assigned those respective objects, and then (c) evaluating the body expression of the function in that new environment. The value of a call of a primitive function, like [47m*[0m or [47mcons[0m, is determined by running special code on the values of the arguments. For example, suppose we have added this definition (defun sq (x) (* x x)) and we are in an environment where [47mx[0m has value [47m5[0m. Then here is an annotated computation of the value of [47m(sq (+ 1 x))[0m. (sq (+ 1 x)) = ; evaluate argument of sq, when x = 5 (sq 6) = ; evaluate body of sq, when x = 6 36. Primitive Functions The ACL2 system starts up with over eight thousand known functions, 32 of which are primitive (defined by special code rather than definitions). The rest are defined. Here is a brief summary of a few useful primitives. We have biased this list to encourage merely integer arithmetic and list processing. Some of the functions mentioned below are not actually primitive but are defined as simple compositions of primitives. For example, [47m(natp x)[0m is defined to be [47m(and (integerp x) (<= 0 x))[0m. Other ``functions'' mentioned below are actually macros that expand into primitive expressions. * [47m(EQUAL x y)[0m --- [47mt[0m if [47mx[0m and [47my[0m are the same object and [47mnil[0m otherwise * [47m(IF x y z)[0m --- [47my[0m if [47mx[0m is non-[47mNIL[0m and [47mz[0m if [47mx[0m is [47mNIL[0m. Put more colloquially, [47m(IF x y z)[0m means ``if [47mx[0m is true, return [47my[0m, otherwise return [47mz[0m'' * [47m(COND (p1 x1) (p2 x2) ... (T xn))[0m --- an abbreviation for (IF p1 x1 (IF p2 x2 (IF ... ... y))) * [47m(AND x1 ... xn)[0m --- [47mxn[0m if each [47mxi[0m is non-[47mnil[0m, and [47mnil[0m otherwise * [47m(OR x1 ... xn)[0m --- [47mxi[0m for the first [47mxi[0m that is non-[47mnil[0m, [47mnil[0m otherwise * [47m(NOT x)[0m --- [47mt[0m if [47mx[0m is [47mnil[0m and [47mnil[0m otherwise * [47m(NATP x)[0m --- [47mt[0m if [47mx[0m is a non-negative integer and [47mnil[0m otherwise * [47m(INTEGERP x)[0m --- [47mt[0m if [47mx[0m is an integer and [47mnil[0m otherwise * [47m(RATIONALP x)[0m --- [47mt[0m if [47mx[0m is a rational number and [47mnil[0m otherwise * [47m(ZP x)[0m --- [47mnil[0m if [47mx[0m is a positive integer and [47mt[0m otherwise * [47m(+ x1 ... xn)[0m --- sum of the [47mxi[0m * [47m(* x1 ... xn)[0m --- product of the [47mxi[0m * [47m(- x y)[0m --- [47mx[0m minus [47my[0m * [47m(/ x y)[0m --- quotient of [47mx[0m divided by [47my[0m * [47m(< x y)[0m --- [47mt[0m if [47mx[0m is less than [47my[0m and [47mnil[0m otherwise * [47m(<= x y)[0m --- [47mt[0m if [47mx[0m is less than or equal to [47my[0m and [47mnil[0m otherwise * [47m(CONSP x)[0m --- [47mt[0m if [47mx[0m is a cons pair and [47mnil[0m otherwise * [47m(ATOM x)[0m --- [47mt[0m if [47mx[0m is a not cons pair and [47mnil[0m otherwise * [47m(ENDP x)[0m --- [47mt[0m if [47mx[0m is [47mnil[0m or a not cons pair and [47mnil[0m otherwise * [47m(CONS x y)[0m --- the ordered pair whose left-hand component is [47mx[0m and whose right-hand component is [47my[0m * [47m(CAR x)[0m --- left-hand component of [47mx[0m if [47mx[0m is a cons pair and [47mnil[0m otherwise * [47m(CDR x)[0m --- right-hand component of [47mx[0m if [47mx[0m is a cons pair and [47mnil[0m otherwise * [47m(CADR x)[0m --- [47m(CAR (CDR X))[0m * [47m(CDDR x)[0m --- [47m(CDR (CDR X))[0m * [47m(LIST x1 x2 ... xn)[0m --- [47m(CONS x1 (CONS x2 ... (CONS xn NIL)))[0m * [47m(LIST* x1 x2 ... xn)[0m --- [47m(CONS x1 (CONS x2 ... xn))[0m * [47m(SYMBOLP x)[0m --- [47mt[0m if [47mx[0m is a symbol and [47mnil[0m otherwise * [47m(STRINGP x)[0m --- [47mt[0m if [47mx[0m is a string and [47mnil[0m otherwise * [47m(CHARACTERP x)[0m --- [47mt[0m if [47mx[0m is a character and [47mnil[0m otherwise You can learn more about these functions by executing them on some sample data. For example, the value of [47m(AND T 23 33)[0m is [47m33[0m, [47m(+ 1 2 3)[0m is [47m6[0m, [47m(ZP 0)[0m is [47mT[0m but [47m(ZP 3)[0m is false (i.e., [47mNIL[0m). [47m(LIST 1 (+ 2 2) (+ 3 3))[0m has the value [47m(1 4 6)[0m but [47m(LIST* 1 (+ 2 2) (+ 3 3))[0m has the value [47m(1 4 . 6)[0m. Perhaps more interestingly, the value of [47m(EQUAL (CONS (- 6 1) 7) (CONS 5 (+ 5 2)))[0m is [47mT[0m. ``Behind the scenes'' those two calls of [47mCONS[0m return two different pointers to two different newly allocated regions of memory, but the [3mcar[0m and [3mcdr[0m fields of both objects are the same, namely [47m5[0m and [47m7[0m respectively. ACL2 cannot tell those two pointers apart. Operationally, [47mEQUAL[0m checks equality recursively down to the tips of both objects. But logically, both [47mCONS[0m expressions here return the pair [47m(5 . 7)[0m. Common Patterns of Recursion Most of your function definitions in ACL2 will fall into certain common schemes. Here is an informal description of the three most common schemes. We define the function [47mvisit[0m several different ways to illustrate common recursions. (In ACL2 you are not allowed to define a function more than one way; there is no ``overriding,'' ``hiding,'' or ``overloading.'' These multiple definitions are just a device for illustrating a lot of definitions without burdening you with many different names.) Visiting every element of a linear list (defun visit (lst ...) (cond ((endp lst) ...) ; [3mNo elements left to process.[0m (t . ; [3mSome elements to process:[0m . . (car lst) ; [3mdo something with this element[0m (visit (cdr lst) ...) ; [3mand visit the rest.[0m . . .))) We illustrate this scheme in the next section. Visiting every node and leaf in a binary tree (defun visit (tree ...) (cond ((atom tree) ...) ; [3mThe tree is a leaf: do something.[0m (t . ; [3mThe tree is an interior node:[0m . tree ; [3mdo something with it,[0m . (visit (car tree) ...) ; [3m visit nodes in left branch, and[0m . (visit (cdr tree) ...) ; [3m visit nodes in right branch.[0m . .))) Visiting every element of a linear list is just the special case of exploring a binary tree in which we visit only the successive subtrees along the [47mcdr[0m chain and consider the [47mcar[0m of each such subtree as the ``data,'' or element, to be processed. We illustrate this recursion below. Visiting all the natural numbers from n to 0 (defun visit (n ...) (cond ((zp n) ...) ; [3mN ``is'' 0: finish up![0m (t . ; [3mN is a positive integer:[0m . n ; [3mdo something with it, and[0m . (visit (- n 1) ...) ; [3mvisit the naturals below it.[0m . . .))) The reason ``is'' is in quotation marks above is that [47m(zp n)[0m is true if either [47mn[0m is 0 or [47mn[0m is not a natural number. For example, [47m(zp -3)[0m and [47m(zp 1/3)[0m both return true! So when [47m(zp n)[0m is true you don't [3mreally[0m know [47mn[0m is 0 but you do know there is nothing more to do, if you're thinking of [47mn[0m as a natural number. When [47m(zp n)[0m is false, you [3mknow[0m [47mn[0m is a positive integer. The predicate [47mzp[0m is just a convenient way to recur through natural numbers and guarantees to halt the recursion even if you call the function on ``unexpected'' input, whether numeric or not. Computing Results When you define a recursive function you often have the choice of computing the results ``on the way up'' or ``on the way down.'' Suppose [47mx[0m is a linear list of numbers and you wish to sum them. Here are two ways: (defun sum-up (x) (cond ((endp x) 0) (t (+ (car x) (sum-up (cdr x)))))) (defun sum-down (x temp) (cond ((endp x) temp) (t (sum-down (cdr x) (+ (car x) temp))))) For example [47m(sum-up '(1 2 3 4))[0m is [47m10[0m and [47m(sum-down '(1 2 3 4) 7)[0m is [47m17[0m. Both definitions fit within the ``visiting every element of a linear list'' recurrence scheme. Note that [47msum-up[0m takes a list of numbers and returns their sum while [47msum-down[0m takes a list of numbers and some initial value and adds the numbers in the list to the initial value. Of course, [47m(sum-up x)[0m is equal to [47m(sum-down x 0)[0m --- but only because the operation of addition is insensitive to the order in which the additions are done. In many applications, the [47msum-up[0m style is clearer, as it is obvious how each element of the list is contributing to the final value. In particular, each element is handled in exactly the same way regardless of what elements came before. In the [47msum-down[0m style, the value of the temporary variable can, in principle, be used to affect the processing of subsequent elements. Information about the previous elements is being passed down. In more complicated functions written in the [47msum-down[0m style, one must carefully inspect how [47mtemp[0m is used to determine if it is just the final answer or is being used to direct the computation. Of course, sometimes information about the elements already visited is necessary to decide how to process subsequent ones, in which case the [47msum-down[0m style might be the appropriate choice. Finally, when these two functions are compiled in a straightforward way, the recursion in [47m sum-up[0m may a call stack while the recursion in [47m sum-down[0m does not: [47msum-down[0m is [3mtail recursive[0m. This means that the value of the recursive call is returned as the final answer and there is no need for the execution engine to ``remember'' to come back after the call to ``do something.'' In [47msum-up[0m the execution engine must ``remember'' to add the two intermediate results together. Tail recursive calls can be compiled as simple jumps or ``gotos'' and often result in faster executions and use of no additional stack space. But all such considerations depend critically on the sophistication of the compiler. Saving Intermediate Results ACL2 is applicative so it does not have assignment statements. But it is possible to use ``local variables'' to save intermediate results. Here is a function that computes x^4 + y^4, i.e., the sum of the fourth powers of [47mx[0m and [47my[0m. (defun x4y4 (x y) (let ((x2 (* x x)) ; Let x2 be x^2 and, ``simultaneously,'' (y2 (* y y))) ; let y2 be y^2. (+ (* x2 x2) ; Compute x^4 by squaring x^2 and (* y2 y2)))) ; add it to y^4 computed similarly. For example, [47m(x4y4 2 3)[0m is [47m16[0m + [47m81[0m or [47m97[0m. The [47mlet[0m expression has two parts, a list of variable bindings followed by a body. The bindings are written as a list of elements. Each element lists a variable name and a term. The terms are evaluated in parallel and then all the variables are bound to the values of the corresponding terms. Then the body is evaluated. The value of the body is the value of the [47mlet[0m. [47mLet[0m expressions are formalized in ACL2 as applications of anonymous functions. For example, [47m(let ((v1 a1) (v2 a2)) (g v1 v2))[0m is actually transformed into [47m((lambda (v1 v2) (g v1 v2)) a1 a2)[0m where the [47mlambda[0m expression is an anonymous function with two parameters, [47mv1[0m and [47mv2[0m, and body [47m(g v1 v2)[0m. The terms [47ma1[0m and [47ma2[0m that determine the values of the local variables in the [47mlet[0m become the argument expressions on which the anonymous function is called. While [47mlet[0m binds its variables in parallel, [47mlet*[0m binds its variables sequentially. The expression (let* ((x2 (* x x)) ; Let x2 be x^2, and then (x4 (* x2 x2)) ; let x4 be x2^2, and then (x8 (* x4 x4))) ; let x8 be x4^2. x8) ; Return x8. computes [47mx[0m^8. Here is an example of a common use of [47mlet[0m. Suppose you wish to find the length of the longest branches in a binary tree. The function [47mdepth[0m does that. It is an example of the ``visit every node in a binary tree'' scheme. (defun depth (x) (cond ((atom x) 0) (t (let ((left-depth (depth (car x))) (right-depth (depth (cdr x)))) (if (< left-depth right-depth) (+ 1 right-depth) (+ 1 left-depth)))))) Just to illustrate the definition and list notation, consider the tree * / \ / \ * * / \ / \ a * e * / \ / \ b * f g / \ c d The longest branches in this tree have length four and terminate in either [47mc[0m or [47md[0m. This tree can be written ((a . (b . (c . d))) . (e . (f . g))) or equivalently as [47m((a b c . d) e f . g)[0m. The expression [47m(depth '((a b c . d) e f . g))[0m has value 4. We could have defined this function this way: (defun depth (x) (cond ((atom x) 0) (t (if (< (depth (car x)) (depth (cdr x))) (+ 1 (depth (cdr x))) (+ 1 (depth (car x))))))) But this would execute less efficiently because after recurring into both the car and cdr of [47mx[0m to determine which is deepest it recurs into one of them again to return the answer. The use of [47mlet[0m eliminates this duplication of effort by saving the results of the earlier calls. Still a third way to define [47mdepth[0m might be (defun depth (x) (cond ((atom x) 0) (t (+ 1 (max (depth (car x)) (depth (cdr x))))))) where [47m(max i j)[0m is defined to be [47m(if (< i j) j i)[0m. This definition executes almost as efficiently as the first one. The values of the two recursive calls are passed to the subroutine [47mmax[0m. [47mMax[0m uses [47mi[0m twice and [47mj[0m twice but now that ``duplication of effort'' only requires looking up the values of variables, just as in the [47mlet[0m case. Sample Definitions Functions on Linear Lists The next several functions all illustrate the ``visiting every element of a linear list'' recurrence scheme. (defun mem (e x) ; Return t or nil according to whether e is an element of x. (cond ((endp x) nil) ((equal e (car x)) t) (t (mem e (cdr x))))) Equivalently: (defun mem (e x) (if (endp x) nil (if (equal e (car x)) t (mem e (cdr x))))) or even (defun mem (e x) (and (not (endp x)) (or (equal e (car x)) (mem e (cdr x))))) (Recall our caveat about multiple definitions of the same function. If you want to try one of these definitions in ACL2, fine. If you want to try all three, you'll have to give them distinct names.) For all three of the above definitions, the following examples hold: ACL2 p!>(mem 'd '(a b c d e f g)) T ACL2 p!>(mem 'd '(a b c e f g)) NIL ACL2 p!> Here is a function to concatenate two lists together: (defun app (x y) (if (endp x) ;;; If x is exhausted, y ;;; then return y (cons (car x) ;;; else, cons the first element of x onto (app ;;; the list obtained by recursively appending (cdr x) ;;; the rest of x y)))) ;;; to y. Here are some examples of [47mapp[0m. ACL2 p!>(app '(1 2 3) '(a b c d)) (1 2 3 A B C D) ACL2 p!>(app '(1 2 3) nil) (1 2 3) ACL2 p!>(app (app '(1 2 3) '(4 5 6)) '(7 8 9)) (1 2 3 4 5 6 7 8 9) ACL2 p!> Here is a function to find the first pair in an alist (if any) that binds a given key. (defun lookup (key alist) (cond ((endp alist) nil) ;;; If alist empty, return nil, ((equal key (car (car alist))) ;;; elseif the first pair contains key, (car alist)) ;;; then return the first pair, (t (lookup key (cdr alist))))) ;;; else look in the rest of alist. Here are some examples. ACL2 p!>(lookup 'b '((a . 1)(b . 2) (c . 3))) (B . 2) ACL2 p!>(lookup 'd '((a . 1)(b . 2) (c . 3))) NIL ACL2 p!>(lookup 'b '((a . 1)(b . 2) (b . 3))) (B . 2) ACL2 p!> Note that only the first binding of the key matters. Here is a function to ``change'' the value of a key in an alist. Note that it does not modify the alist but produces a new alist. (defun store (key val alist) (cond ((endp alist) ;;; If alist is empty, (list (cons key val))) ;;; then return an alist with one binding, ((equal key (caar alist)) ;;; elseif the first pair binds key, (cons (cons key val) ;;; then add the new binding to (cdr alist))) ;;; the rest of the alist, (t (cons (car alist) ;;; else cons this pair onto the result (store ;;; of recursively putting a new binding key val ;;; of key to val in (cdr alist)))))) ;;; the rest of alist. ACL2 p!>(store 'b 7 '((a . 1) (b . 2) (c . 3))) ((A . 1) (B . 7) (C . 3)) ACL2 p!>(store 'x 26 '((a . 1) (b . 2))) ((A . 1) (B . 2) (X . 26)) ACL2 p!>(store 'c 3 '((a . 1) (b . 2) (x . 26))) ((A . 1) (B . 2) (X . 26) (C . 3)) It is important to recall that ACL2 is functional (side-effect free)! Despite its name, [47mstore[0m does not change the alist it is given but returns a new one. Consider ACL2 p!>(let* ((alist1 '((a . 1) (b . 2) (c . 3))) (alist2 (store 'b 7 alist1))) (list (lookup 'b alist1) (lookup 'b alist2))) ((B . 2) (B . 7)) ACL2 p!> The above expression binds [47malist1[0m to an alist in which [47mb[0m is associated with 2. Then it uses [47mstore[0m to bind [47mb[0m in [47malist1[0m to the new value [47m7[0m and calls the result [47malist2[0m. Then it returns the list containing the values of looking up [47mb[0m in each of the alists. You might think the answer would be [47m((B . 7) (B . 7))[0m and it [3mwould be if[0m [47mstore[0m actually changed [47malist1[0m to create [47malist2[0m. But in fact [47malist1[0m is not changed. The answer is [47m((B . 2) (B . 7))[0m. Functions on Binary Trees Here is a function to count the number of tips of a binary tree. This function illustrates the ``visiting every node of a binary tree'' scheme. (defun count-tips (x) (cond ((atom x) 1) ;;; X is a tip: it counts 1. (t (+ (count-tips (car x)) ;;; X is a node: sum the counts (count-tips (cdr x)))))) ;;; of the left and right subtrees. The function above does the computation ``on the way up.'' Here is a version that does it ``on the way down.'' (defun count-tips (x temp) (cond ((atom x) (+ 1 temp)) ;;; X is a tip: add its count to temp. (t ;;; Otherwise, x is a node: Read the ;;; nest of two calls below inside-out: ;;; Count the tips in (car x) and add ;;; that into temp. Use the result as ;;; temp when you count the tips in ;;; (cdr x). (count-tips (cdr x) (count-tips (car x) temp))))) This function has one tail recursive call. Let [47mx[0m be the tree * / \ / \ * * / \ / \ a * e * / \ / \ b * f g / \ c d which we can write as [47m'((a b c . d) e f . g)[0m. Then [47m(count-tips x)[0m is [47m7[0m (here we mean to use the first version of the definition). Similarly, [47m(count-tips x 0)[0m is also [47m7[0m (here we mean to use the second version). Mutual Recursion ACL2 requires that subroutines be defined before they are used in other definitions. So what do you do if you have two functions, [3mf[0m and [3mg[0m, and [3mf[0m calls [3mg[0m and [3mg[0m calls [3mf[0m? You define them together. This is called [3mmutual recursion[0m. The example below shows a very inefficient way to factor a number into a list of primes. (mutual-recursion (defun factors (n) ; Collect the prime factors of n. (factors-below n (- n 1))) (defun factors-below (n m) ; Return the prime factors of n that are less than or equal to m. (cond ((or (zp m) (equal m 1)) (list n)) ((integerp (/ n m)) (app (factors (/ n m)) (factors m))) (t (factors-below n (- m 1))))) ) We can read this as follows. To determine the [47mfactors[0m of [3mn[0m, call [47mfactors-below[0m on [3mn[0m and [3mn-1[0m to collect all the factors of [3mn[0m less than or equal to [3mn-1[0m. To find all the factors of [3mn[0m less than or equal to [3mm[0m, consider three cases. First, if [3mm[0m is 0 or 1, return the list containing just [3mn[0m. Second, if [3mn/m[0m is an integer (i.e., [3mm[0m divides [3mn[0m), then use [47mapp[0m to concatenate the factors of [3mn/m[0m to the factors of [3mm[0m. Third (and otherwise), find the factors of [3mn[0m below [3mm-1[0m. We can run [47mfactors[0m. For example [47m(factors 12)[0m returns [47m(2 2 3)[0m. If we call [47m(factors 123456789)[0m the computation takes a while (27 seconds on my laptop) and returns [47m(3 3 3607 3803)[0m. [47m(Factors (- (expt 2 31) 1))[0m takes about 500 seconds and returns [47m(2147483647)[0m. Returning and Using Multiple Values It is sometimes useful to define functions that return more than one result. Here is an example of a function that produces and uses multiple values. The function explores a binary tree and counts (in its second argument, [47mnodes[0m) how many cons nodes it sees and counts (in its third argument, [47mtips[0m) how many tips it sees. It returns both numbers as a list of length 2 (without actually creating the intermediate lists). (defun node-and-tip-count (x nodes tips) (cond ((atom x) ;;; X is a tip. Return a vector (list) of (mv nodes ;;; two results: the number of nodes seen (+ 1 tips)) ;;; and the number of tips seen (plus 1 for x). ) (t ;;; X is a cons node. (mv-let (nodes-in-car tips-in-car) (node-and-tip-count (car x) nodes tips) ;;; The two lines above locally bind the variables ;;; nodes-in-car and tips-in-car to the number of ;;; nodes and tips, respectively, computed by the ;;; recursive call of this function on (car x) ;;; and the current running counts of nodes and tips. ;;; Then, below, we count the number of nodes and ;;; tips in (cdr x), starting with the counts for ;;; the car (and adding one for the node x). (node-and-tip-count (cdr x) (+ 1 nodes-in-car) tips-in-car))))) For example, (node-and-tip-count '((a . b) . (c . d)) 0 0) = (3 4) Thus, the tree in question has 3 cons nodes and 4 (non-cons) tips. If you want to use multiple values you should read the ACL2 documentation on that topic. Type Errors The ACL2 programming language is untyped. Objects have types that can be checked at runtime with predicates like [47mintegerp[0m, [47mconsp[0m, etc., but there is no syntactic typing. Any function can be applied to any object and ACL2 comes up with some value. It does this by defaulting ill-typed inputs to default values of the expected type. For example, [47m+[0m expects its arguments to be numbers. If you supply a non-numeric input to [47m+[0m it will use [47m0[0m instead. Thus, the value of [47m(+ 3 T)[0m is [47m3[0m. [47mCar[0m and [47mcdr[0m expect their arguments to be either a cons pair or [47mnil[0m. (A special case in Lisp is that [47mcar[0m and [47mcdr[0m return [47mnil[0m on [47mnil[0m.) If called on objects of the wrong type, [47mcar[0m and [47mcdr[0m default the argument to [47mnil[0m. But when you start up ACL2, the read-eval-print loop is configured to check types as it evaluates. Errors are signaled if types are violated. However, if you want it to just plow into ill-typed data and get whatever result the defaults produce, you can use the [47m:set-guard-checking nil[0m command as shown in the session below. ACL2 p!>(+ 2 2) 4 ACL2 p!>(+ 2 T) ACL2 Error in TOP-LEVEL: The guard for the function call (BINARY-+ X Y), which is (AND (ACL2-NUMBERP X) (ACL2-NUMBERP Y)), is violated by the arguments in the call (BINARY-+ 2 T). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 p!>:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 p>(+ 2 T) 2 ACL2 p>(CAR 'ABC) NIL ACL2 p> Note that the prompt changes after the [47m:set-guard-checking[0m command above. The exclamation mark ([47m![0m) in the standard prompt indicates that types are being checked. Stack Overflow Sometimes a computation will consume more space than your machine has. For example, the following function constructs a list of [47mn[0m [47mnil[0ms. (defun nils (n) (if (zp n) nil (cons nil (nils (- n 1))))) We can run it on small values of [47mn[0m. (nils 10) = (nil nil nil nil nil nil nil nil nil nil) So that we don't have to read long lists of [47mnil[0ms below we just take the length of the result with the ACL2 function [47mlen[0m. ACL2 p!>(len (nils 10)) 10 ACL2 p!>(len (nils 100)) 100 ACL2 p!>(len (nils 1000)) 1000 ACL2 p!>(len (nils 10000)) 10000 ACL2 p!>(len (nils 100000)) 100000 ACL2 p!>(len (nils 1000000)) 1000000 ACL2 p!>(len (nils 10000000)) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Stack overflow on value stack. ... :q ACL2 p!> But that last test, where we attempt to produce a list of ten million [47mnil[0ms, causes a stack overflow in the Common Lisp configuration I'm running. (If your Lisp causes a Lisp error and enters an interactive break you'll need to exit the break to return to ACL2. Exactly how you do that depends on what Common Lisp you're running. For example, in GCL and CCL, you type [47m:q[0m followed by return, but in Allegro CL you type [47m:reset[0m followed by return, and in CMU CL you type [47mq[0m followed by return.) If you are interested in doing ``large'' calculations with ACL2 you will have to learn about how to compile definitions and how to use declarations to optimize code. Those topics are beyond the scope of this document. However, often you can just code up a more efficient algorithm. For example, the following tail-recursive version of [47mnils[0m won't overflow the stack. (defun nils (n ans) (if (zp n) ans (nils (- n 1) (cons nil ans)))) So now ACL2 p!>(len (nils 10000000 nil)) 10000000 ACL2 p!>(len (nils 100000000 nil)) 100000000 ACL2 p!>(len (nils 1000000000 nil)) 1000000000 ACL2 p!> Of course, it will eventually use up all the memory. The tests above sort of suggest we're interested in the question ``Does [47m(nils n nil)[0m always return a list of length [47mn[0m?'' If that is the question, then (a) you'll never answer it by running all possible tests, and (b) you are using exactly the right tool! The ACL2 system includes a theorem prover. Below we show the commands you need to execute to answer the question in the affirmative. We've elided the output from these commands. ACL2 p!>:logic ACL2 !>(verify-termination nils) ... ACL2 !>(defthm lemma-about-nils (implies (natp n) (equal (len (nils n ans)) (+ n (len ans))))) ... ACL2 !>(defthm main-theorem-about-nils (implies (natp n) (equal (len (nils n nil)) n))) ... That is, switch back into logic mode, admit [47mnils[0m to the logic by proving termination, prove the general theorem that [47m(nils n ans)[0m returns a list whose length is [47mn[0m plus the length of [47mans[0m, when [47mn[0m is natural number, and then prove the main theorem. Your job as an ACL2 ``theorem prover driver'' is to think of the commands. The prover does the work to complete each of those steps. So maybe you should learn to prove theorems about your functions? If so, see ``Recursion and Induction''. Conclusion You should be ready at this point to use ACL2 as a programming language to implement lots of simple list processing algorithms. Remember to go to the ACL2 User's Manual on the {ACL2 Home Page | https://www.cs.utexas.edu/users/moore/acl2} to learn about other functions and features. If you need advice, check out the ACL2 Help list under the Mailing Lists link. The users who have volunteered to help are very responsive. One final piece of advice: it is always best to code the simplest algorithm you can. Do not needlessly complicate your code. Optimize for performance only after confirming that the straightforward implementation is too inefficient for your application.") (genvar (pointers) "See [system-utilities].") (get-brr-local (pointers) "See [system-utilities].") (get-check-invariant-risk (pointers) "See [set-check-invariant-risk].") (get-command-sequence (history) "Return list of [command]s that are between two [command] descriptors Examples: (get-command-sequence 4 12) :gcs 4 12 ; same as above (get-command-sequence 4 :x) :gcs 4 :x ; same as above See [pcs] for a utility that prints abbreviated information about the [command]s that are between two command descriptors. The utility [47mget-command-sequence[0m --- or simply [47mgcs[0m, so that you can just type [47m:gcs[0m at the prompt --- has the same syntax but instead of printing, it simply returns the corresponding list of commands. More precisely, it returns an [error-triple] [47m(mv erp val state)[0m such that if [47merp[0m is not [47mnil[0m, then [47mval[0m is the desired list of commands.") (get-cpu-time (programming-with-state acl2-built-ins read-run-time) "Read elapsed cpu time [47m(Get-cpu-time state)[0m returns the elapsed cpu time in seconds since the start of the current ACL2 session. See [read-run-time] for further documentation. [31;1mFunction: [0m<get-cpu-time> (defun get-cpu-time (state) (declare (xargs :stobjs state)) (read-run-time state))") (get-defun-event (pointers) "See [system-utilities].") (get-enforce-redundancy (redundant-events) "Query the [world] on whether redundancy is being enforced See [set-enforce-redundancy] for relevant background. For a given world, [47mwrld[0m --- typically, [47m(w state)[0m --- the value of [47m(get-enforce-redundancy wrld)[0m is [47mnil[0m, [47mt[0m, or [47m:warn[0m according to the most recent call of [47mset-enforce-redundancy[0m, [47mnil[0m by default.") (get-event (pointers) "See [system-utilities].") (get-event-data (system-utilities output-controls) "Obtain data stored after at the conclusion of an event Warning: This is a low-level system utility that may change somewhat over time. For more details, see the ACL2 source code. Evaluation of the form [47m(get-event-data key state)[0m returns the value of [47mkey[0m in an association list, which we call an [3mevent-data alist[0m. Such an alist is the value of [state] global variable [47mlast-event-data[0m. (See [programming-with-state] for a discussion of state global variables.) An event-data alist contains certain information stored at the conclusion of the immediately preceding event, some of which corresponds to the event's [summary]. We anticipate continuing to support at least the following keys, each with value [47mVAL[0m as follows. * [47mABORT-CAUSES[0m: [47mVAL[0m is a list of reasons why the proof aborted. In particular, if the value [47mINTERRUPT[0m is in the list, then the proof was interrupted (typically with Control-C). * [47mEVENT[0m: the [event]. * [47mFORM[0m: [47mVAL[0m is the ``context'' for the event, printed in the summary, [warnings], and [errors]. * [47mHINT-EVENTS[0m: [47mVAL[0m is as in the corresponding field of the event summary. * [47mNAMEX[0m: [47mVAL[0m is 0, a single name, or a list of names; see comments in ACL2 source function [47maccess-event-tuple-namex[0m. * [47mPROVER-STEPS-COUNTED[0m: [47mVAL[0m is as in the corresponding field of the event summary. Note: This value can be obtained using [47m[last-prover-steps][0m. * [47mRULES[0m: [47mVAL[0m is as in the corresponding field of the event summary. * [47mSPLITTER-RULES[0m: [47mVAL[0m represents the corresponding field of the event summary, as the list [47m(case-split immed-forced if-intro)[0m. * [47mSYSTEM-ATTACHMENTS[0m: [47mVAL[0m lists the pairs [47m(f . g)[0m for which [47mf[0m is a system function with attachment [47mg[0m ([defattach]), which differs from the attachment to [47mf[0m when ACL2 starts up. * [47mTIME[0m: [47mVAL[0m represents the corresponding field of the event summary, as the list [47m(prove print proof-tree other)[0m. * [47mWARNINGS[0m: [47mVAL[0m is as in the corresponding field of the event summary.") (get-guard-checking (redundant-events) "Get the status most recently installed by [47m[set-guard-checking][0m See [set-guard-checking] for relevant background. The value returned by [47m(get-guard-checking)[0m is [47mt[0m by default, but is the value most recently installed for [guard]-checking, typically supplied as the argument of a call of [47m[set-guard-checking][0m.") (get-in-theory-redundant-okp (pointers) "See [set-in-theory-redundant-okp].") (get-internal-time (programming acl2-built-ins) "Runtime vs. realtime in ACL2 timings The ACL2 system provides utilities that deal with elapsed time. These are most visibly used in reporting the time summaries when completing evaluation of [events]. For utilities that return elapsed cpu or run time, see [read-run-time], [get-cpu-time], and [get-real-time]. Other time-related utilities include [with-prover-time-limit], [time-tracker], [time-tracker-tau], see [pstack]. By default, these utilities all use an underlying notion of run time provided by the host Common Lisp implementation: specifically, the Common Lisp functions [47mget-internal-run-time[0m for cpu time (or a slight variant if the host Lisp is a version of GCL that precedes 2.7.0) and [47mget-internal-real-time[0m for real (wall clock) time. While the latter is specified to measure elapsed time, the former is left to the implementation, which might well only measure time spent in the Lisp process. Consider the following example, which is a bit arcane but basically sleeps for 2 seconds. (defttag t) ; to allow sys-call (make-event (prog2$ (sys-call "sleep" '("2")) (value '(value-triple nil)))) A typical time [summary] might be as follows, drastically under-reporting the actual elapsed (real, wall clock) time. Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) However, you can instruct ACL2 to switch to using elapsed time (real time), in summaries and elsewhere, by evaluating the following form. (assign get-internal-time-as-realtime t) To return to using runtime: (assign get-internal-time-as-realtime nil) While the above example is rather silly, the issue becomes significant in time summaries for proofs that call out to external tools (see [sys-call] and see [clause-processor]). Note that a function [47mget-internal-time[0m is defined in raw Lisp but is not available inside the ACL2 loop. However, the expression [47m(read-run-time state)[0m provides an interface to this function that is available inside the ACL2 loop; see [read-run-time], and also see [get-cpu-time] and [get-real-time].") (get-output-stream-string$ (pointers) "See [io].") (get-persistent-whs (wormhole) "Make a wormhole's status visible outside the wormhole General Form: (get-persistent-whs name state) [47mName[0m should be the name of a wormhole (see [wormhole]). This function returns an [error-triple] of the form [47m(mv nil s state)[0m, where [47ms[0m is the persistent-whs of the named wormhole (i.e., the status of of wormhole stored outside of the ACL2 state). The status is obtained by reading the oracle in the ACL2 [47m[state][0m with [47m[read-ACL2-oracle][0m. Recall that the status of a wormhole is some ACL2 object largely determined by the author of the wormhole. It is always treated as a pair whose [47mcar[0m is the ``entry code'' ([47m:enter[0m or [47m:skip[0m) or, more precisely, is either [47m:skip[0m or not [47m:skip[0m, the latter case being treated like [47m:enter[0m. But the [47mcdr[0m of the status can be whatever the author of the wormhole chooses to hold the data of the wormhole. When a wormhole is entered its persistent status, aka its persistent-whs, is used to configure the state of the read-eval-print loop the user sees inside the wormhole. In particular, upon entry the persistent-whs is moved to the value of the state global variable [47m'wormhole-status[0m and is thus accessible via [47m(f-get-global 'wormhole-status state)[0m. We call this copy of the status the ephemeral-whs because when the wormhole is exited the ephemeral-whs is moved to the [47mpersistent-whs[0m and the state global [47m'wormhole-status[0m is restored to whatever value it had when the wormhole was entered. See [47m[wormhole-status][0m for a discussion of these two senses of the status of a wormhole. See also [wormhole-programming-tips].") (get-real-time (programming-with-state acl2-built-ins read-run-time) "Read elapsed real time [47m(Get-real-time state)[0m returns [47m(mv rtime state)[0m where [47mrtime[0m is the elapsed real (wall clock) time in seconds since the start of the current ACL2 session. See [read-run-time] for further documentation. [31;1mFunction: [0m<get-real-time> (defun get-real-time (state) (declare (xargs :stobjs state)) (read-run-time state))") (get-register-invariant-risk (pointers) "See [set-register-invariant-risk].") (get-serialize-character (pointers) "See [with-serialize-character].") (get-skipped-proofs-p (pointers) "See [system-utilities].") (getenv$ (programming-with-state acl2-built-ins) "Read an environment variable [47m(Getenv$ str state)[0m, where [47mstr[0m is a string, reads the value of environment variable [47mstr[0m, returning a value of [47mnil[0m if none is found or if the read fails. (Exception: if the value is not a legal ACL2 string, say because it contains a character with [47m[char-code][0m exceeding 255, then an error is signaled.) The logical story is that [47mgetenv$[0m reads its value from the [47moracle[0m field of the ACL2 [47m[state][0m. The return value is thus a triple of the form [47m(mv erp val state)[0m, where [47merp[0m will always be [47mnil[0m in practice, and logically, [47mval[0m is the top of the acl2-oracle field of the state (see [47m[read-ACL2-oracle][0m) and the returned state has the updated (popped) acl2-oracle. Example: (getenv$ "PWD" state) ==> (mv nil "/u/joe/work" state) Also see [setenv$]. [31;1mFunction: [0m<getenv$> (defun getenv$ (str state) (declare (xargs :stobjs state :guard (stringp str))) (declare (ignore str)) (read-acl2-oracle state))") (getprop (world acl2-built-ins) "Access fast property lists General form: (getprop symb key default world-name world-alist) See [getpropc] for a convenient abbreviation, and see [world] for discussion of both utilities [47mgetprop[0m and [47m[putprop][0m. Also see community book [47mbooks/misc/getprop.lisp[0m for an example that illustrates the use of ACL2 utilities [47mgetprop[0m and [47mputprop[0m to take advantage of under-the-hood Lisp (hashed) property lists. [31;1mMacro: [0m<getprop> (defmacro getprop (symb key default world-name world-alist) (if (equal world-name ''current-acl2-world) (cons 'fgetprop (cons symb (cons key (cons default (cons world-alist 'nil))))) (cons 'sgetprop (cons symb (cons key (cons default (cons world-name (cons world-alist 'nil))))))))") (getpropc (world acl2-built-ins) "Access fast property lists General form: (getpropc symb key &optional default world-alist) where [47mdefault[0m is [47mnil[0m if omitted, and [47mworld-alist[0m is [47m(w state)[0m if omitted. This is a convenient abbreviation for the common case in which [47m[getprop][0m is used for system programming, with [47m'current-acl2-world[0m as the (implicit, for [47mgetpropc[0m) world-name. [31;1mMacro: [0m<getpropc> (defmacro getpropc (symb key &optional default (world-alist '(w state))) (cons 'getprop (cons symb (cons key (cons default (cons ''current-acl2-world (cons world-alist 'nil)))))))") (getting-started (pointers) "See [ACL2-tutorial].") (git-quick-start (about-acl2) "Git quick start guide. The {ACL2 GitHub repository | https://github.com/acl2/acl2} contains the ``bleeding edge'' ACL2 source code and [community-books], available between ACL2 releases (see [RELEASE-NOTES]). Here we provide minimal instructions for working with the ACL2 GitHub repo. Many git tutorials are available elsewhere on the web (e.g., {at GitHub | https://docs.github.com/en/get-started}). For non-contributors (to use ACL2 without contributing changes): Start by obtaining the ACL2 GitHub repository (this command makes a directory called [47macl2[0m that contains the current contents of the [47mmaster[0m branch): git clone https://github.com/acl2/acl2 Later, to update your copy to get the latest changes: cd acl2 git pull Once you have ACL2, you will probably want to certify some books (see [books-certification]). For infrequent contributors: For those only planning on contributing a few times per year (or less), see [github-commit-code-using-pull-requests]. For frequent contributors: For those contributing on a monthly or weekly basis, see [github-commit-code-using-push]. Subtopics [Github-commit-code-using-pull-requests] How to commit code to the books using pull requests. [Github-commit-code-using-push] How to commit code to the books using direct push access.") (github-commit-code-using-pull-requests (git-quick-start) "How to commit code to the books using pull requests. This guide is for contributors who will commit to the repository rarely (e.g., a few times a year). If you find yourself committing more often, see [github-commit-code-using-push]. If you do not plan to commit your own changes, see [git-quick-start] instead. A nice result of using pull requests is that all changes will be peer-reviewed before being committed. Also, we sometimes call this method the [3mFork and Pull[0m method. (A) GETTING STARTED 1. Go to {https://github.com/acl2/acl2 | https://github.com/acl2/acl2} and click on the [47mfork[0m button on the top-right. Fork the repository into your GitHub space. This will create a new repository at [47mhttps://github.com/<your-github-username>/acl2[0m. 2. In your working space on your computer, create a [47mclone[0m of your GitHub repository and [47mcd[0m into it: git clone https://github.com/<your-github-username>/acl2 cd acl2 3. Add the main ACL2 repository as a git remote: git remote add upstream https://github.com/acl2/acl2 (B) UPDATING The following commands will update your directory to match the latest contents of the main ACL2 repository on GitHub. git fetch --all git merge -m "Merge." remotes/upstream/master (C) CONTRIBUTING Make Changes and Test Them 1. Before beginning your edits, update, as in (B) above. 2. Build an executable. make update LISP=<your_lisp> 3. Make book changes. See the guidelines in the [how-to-contribute] topic (e.g., about updating the book release notes). 4. Run a regression. (make -j 8 regression) >& make-regression.log Note that the [47m-j 8[0m option specifies the use of 8 hardware threads; feel free to omit it or use a more suitable number (especially if your computer has other than 8 hardware threads). 5. Look for failures, as indicated by [47m**[0m in the log. fgrep -a '**' make-regression.log 6. If there were failures, then go back to Step 3 above to make appropriate changes and re-test. 7. Commit your changes. First do [47mgit status[0m to see the list of all new/changed files: git status Ensure that none of the reported additions/changes was unintentional. Next, do [47mgit add[0m to add each file you want to commit (normally, everything reported by [47mgit status[0m, to match what was tested in the regression above): git add <file1> <file2> ... Now commit your changes locally: git commit -m '<some message, with descriptive first line>' The [47m-m ...[0m option is a log message, where the first line is a summary of your changes and additional lines give more details. You can replace the [47m-m ...[0m option by [47m-F <filename>[0m, where [47m<filename>[0m is the name of a file that contains your log message. 8. Merge in remote changes, if any, by updating again as in (B) above. If the merge changed anything, go back to Step 4 above to ensure that your changes are compatible with the remote changes you just obtained. If the merge did not change anything, continue to the next step (Contribute Your Changes). In rare cases, you may get a merge conflict (concurrent changes to the same files), in which case you will need to resolve the conflict by editing files and committing them (see the [47mgit commit[0m command above in Step 7). Then go back to Step 4 above to test that everything is working. Contribute Your Changes The following command will update your fork on GitHub. git push You now need to create a [3mpull request[0m, where you request that changes from your fork be accepted into the main ACL2 repository. To achieve this: 1. Go to [47mhttps://github.com/<your-github-username>/acl2[0m. 2. Click the [47mNew pull request[0m button (you can search for it with your browser). 3. In the drop-down box labeled "base" (next to the box labeled "base fork"), change the value from "master" to "testing". 4. Click [47mCreate pull request[0m. 5. Put a description of your changes in the comments section. You may want to quote text from your commit log messages. 6. Click [47mCreate pull request[0m. At this point, the main ACL2 repository maintainers will be notified, check that things seem to be in order, and then either request modifications or adopt your changes.") (github-commit-code-using-push (git-quick-start) "How to commit code to the books using direct push access. This guide is for contributors who commit to the repository often (e.g., monthly or weekly). Such contributors will typically begin with the [github-commit-code-using-pull-requests] method, and after they are familiar with the process and community, will switch to this method. If you do not plan to commit your own changes, see [git-quick-start] instead. (A) GETTING STARTED Start by obtaining an up-to-date copy of the web-based GitHub repository (this command makes a directory called [47macl2[0m that contains the current contents of the [47mmaster[0m branch). git clone https://github.com/acl2/acl2 cd acl2 (B) UPDATING The following commands will update your directory to match the latest contents of the main ACL2 repository on GitHub. git fetch --all git merge -m "Merge." remotes/origin/master (C) CONTRIBUTING To join the {GitHub project | https://github.com/acl2/acl2/}, please send email to one of the following individuals. * Eric Smith ([47meric.smith@kestrel.edu[0m) * David Rager ([47mragerdl@gmail.com[0m) * Sol Swords ([47msswords@gmail.com[0m) After you have joined the project, you can proceed as follows when you are ready to contribute. Make Changes and Test Them 1. Before beginning your edits, update, as in (B) above. 2. Build an executable. make update LISP=<your_lisp> 3. Make book changes. See the guidelines in the [how-to-contribute] topic (e.g., about updating the book release notes). 4. Run a regression. (make -j 8 regression) >& make-regression.log Note that the [47m-j 8[0m option specifies the use of 8 hardware threads; feel free to omit it or use a more suitable number (especially if your computer has other than 8 hardware threads). 5. Look for failures, as indicated by [47m**[0m in the log. fgrep -a '**' make-regression.log 6. If there were failures, then go back to Step 3 above to make appropriate changes and re-test. 7. Commit your changes. First do [47mgit status[0m to see the list of all new/changed files: git status Ensure that none of the reported additions/changes was unintentional. Next, do [47mgit add[0m to add each file you want to commit (normally, everything reported by [47mgit status[0m, to match what was tested in the regression above): git add <file1> <file2> ... Now commit your changes locally: git commit -m '<some message, with descriptive first line>' The [47m-m ...[0m option is a log message, where the first line is a summary of your changes and additional lines give more details. You can replace the [47m-m ...[0m option by [47m-F <filename>[0m, where [47m<filename>[0m is the name of a file that contains your log message. 8. Merge in remote changes, if any, by updating again as in (B) above. If the merge changed anything, go back to Step 4 above to ensure that your changes are compatible with the remote changes you just obtained. If the merge did not change anything, continue to the next step (Contribute Your Changes). In rare cases, you may get a merge conflict (concurrent changes to the same files), in which case you will need to resolve the conflict by editing files and committing them (see the [47mgit commit[0m command above in Step 7). Then go back to Step 4 above to test that everything is working. Contribute Your Changes The following command will update the main ACL2 repository on GitHub. git push origin testing This will cause your changes to be merged into the [47mtesting[0m branch. From there, they will be automatically merged into [47mmaster[0m if the automated regression testing system successfully tests them. Note: If you are changing someone else's files, or would like someone to review your changes, you might consider making a pull request instead of pushing directly.") (goal-spec (hints output-controls) "To indicate where a hint is to be used Examples: "Goal" "goal" "Subgoal *1/3''" "subgoal *1/3''" "[2]Subgoal *1/3''" When [hints] are given to the theorem prover, a goal-spec is provided to specify the goal to which the [hints] are to be applied. The [hints] provided are carried along innocuously until the named goal arises. When it arises, the [hints] are ``activated'' for that goal and its descendants. A legal goal specification may be extracted from the theorem prover's output. Certain lines clearly label formulas, as in Subgoal *1/3.2' (IMPLIES ... ...) and these lines all give rise to goal specifications. In general, these lines all start either with ``Goal'' or ``Subgoal'' or else with those words preceded by a number in square brackets, as in [1]Subgoal *1/3.2' (IMPLIES ... ...). A goal specification may be obtained by deleting any surrounding whitespace from such a line and embedding the text in string quotation marks. Thus "[1]Subgoal *1/3.2'" is the goal specifier for the goal above. As noted, a hint is applied to a goal when the hint's goal specification matches the name ACL2 assigns to the goal. The matching algorithm is case-insensitive. Thus, alternative goal specifications for the goal above are [47m"[1]subgoal *1/3.2'"[0m and [47m"[1]SUBGOAL *1/3.2'"[0m. The matching algorithm does not tolerate non-case discrepancies. Thus, [47m"[1]Subgoal*1/3.2'"[0m and [47m" [1]Subgoal *1/3.2'"[0m are unacceptable. Sometimes a formula is given two names, e.g., Subgoal *1/14.2' (IMPLIES ... ...) Name the formula above *1.1. It is the first name (the one that starts with ``Goal'' or ``Subgoal'') and not the second which constitutes a legal goal-spec. Roughly speaking, when the system prints the line containing the goal specification, it activates any [hints] that are attached to that goal-spec. Consider the example above. Suppose [47mSubgoal *1/14.2'[0m could be proved by using a certain lemma instance. Then the appropriate entry in the [hints] would be: ("Subgoal *1/14.2'" :use ...) This might surprise you because the system appears to do nothing to [47m*1/14.2'[0m besides push it for a subsequent induction. But actually between the time the system printed the goal-spec line and the time it decides to push the goal, you can think of the system as trying everything it has. So a [47muse[0m hint activated when [47mSubgoal *1/14.2'[0m arises is just what you want. But what if you want to give an [47m:induct[0m hint? By the time induction is tried, the formula has been given the name [47m*1.1[0m. Well, this is one you just have to remember: ("Subgoal *1/14.2'" :induct ...). When the above hint is activated the [47m:induct[0m directive short-circuits the rest of the processing and sends immediately the formula into the pool of goals to prove by induction. The induct hint is attached to the formula in the pool and when the time comes to turn our attention to that goal, the induct advice is followed. You can probably figure out the naming conventions for goals after seeing some examples in prover output. Let's discuss the use of the character [47m'[0m for a suffix. If a goal has a single subgoal then a prime is added; e.g., if [47m"Subgoal 3.2"[0m has a single subgoal then it is named [47m"Subgoal 3.2'"[0m rather than [47m"Subgoal 3.2.1"[0m. If in turn that goal has a single subgoal, it is named [47m"Subgoal 3.2''"[0m; and so on. When four or more primes would be generated, say, [47mn[0m primes, then the suffix is [47m"'n'"[0m; e.g., continuing the preceding example we get [47m"Subgoal 3.2'''"[0m, [47m"Subgoal 3.2'4'"[0m, [47m"Subgoal 3.2'5'"[0m, and so on. If any of these generates at least two subgoals then any ``prime'' suffix is dropped; for example, if [47m"Subgoal 3.2'5'"[0m has two subgoals then they are named [47m"Subgoal 3.2.2"[0m and [47m"Subgoal 3.2.1"[0m. We conclude by emphasizing a point made above, that a hint is applied to a goal when the hint's goal specification matches the name ACL2 assigns to the goal. If there is no such match, then the hint is ignored. Consider the following example. (thm (equal (append (append x y) z) (append x y z)) :hints (("Subgoal *1/" :in-theory nil))) Normally, [47m:in-theory[0m hints are inherited by subgoals (see [hints-and-the-waterfall]), so you might expect that the empty theory is used in [47mSubgoal *1/2[0m and [47mSubgoal *1/1[0m. But in fact, since there is no subgoal printed that is labeled [47mSubgoal *1/[0m, the above [47m:in-theory[0m hint is ignored. The above example is in contrast to the following, where the hint makes the proof fail, because there really is a [47mSubgoal *1/[0m in the proof this time. (thm (implies (and (not (endp x)) (not (endp (cdr x)))) (equal (append (append x y) z) (append x y z))) :hints (("Subgoal *1/" :in-theory nil))) Subtopics [Clause-identifier] The internal form of a [goal-spec]") (good-bye (basics acl2-built-ins) "Quit entirely out of Lisp Examples: ACL2 !>(good-bye) ; [ACL2 is exited] ACL2 !>(good-bye 3) ; [ACL2 is exited with Unix exit status 3] Note: Your entire session will disappear forever when you evaluate [47m(good-bye)[0m. The command [47m(good-bye)[0m quits not only out of the ACL2 [command] loop, but in fact quits entirely out of the underlying Lisp. Thus, there is no going back! You will [31;1mnot[0m be able to re-enter the [command] loop after typing [47m(good-bye)[0m! All your work will be lost!!! This command may not work in some underlying Common Lisp implementations. In such cases, there is no harm in trying; ACL2 will let you know how to proceed if it cannot exit. In some systems, typing [47mcontrol-d[0m at the top-level ACL2 prompt ([47mcontrol-c control-d[0m if inside emacs) will call this function. The optional argument for [47mgood-bye[0m (default 0) indicates the Unix (Linux) exit status. If it is not an integer, it will be treated as 0. If you merely want to exit the ACL2 [command] loop, use [47m:q[0m instead. (That can be risky; see [q]). We conclude with the following technical remark, to be ignored unless you are trying to do things in raw Lisp that involve quitting the session. The mechanism that ACL2 and Lisp use for quitting the session is slightly involved. In particular, if you trace the underlying raw Lisp function [47mexit-lisp[0m, you may see that it is called twice; the second call happens while cleaning up from an [47munwind-protect[0m call. Subtopics [Exit] Quit entirely out of Lisp [Quit] Quit entirely out of Lisp") (granularity (parallel-programming) "Limit the amount of parallelism This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. Some function calls are on arguments whose evaluation time is long enough to warrant parallel execution, while others are not. A granularity form can be used to make appropriate restrictions on the use of parallelism. For example, consider the Fibonacci function. Experiments have suggested that execution time can be reduced if whenever the argument is less than 27, a serial version of the Fibonacci function is called. One way to utilize this information is to write two definitions of the Fibonacci function, one serial and one parallel. (defun fib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (binary-+ (fib (- x 1)) (fib (- x 2)))))) (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) ((< x 27) (binary-+ (fib (- x 1)) (fib (- x 2)))) (t (pargs (binary-+ (pfib (- x 1)) (pfib (- x 2))))))) We realize quickly that writing both of these function definitions is cumbersome and redundant. This problem can be avoided by using a [47mgranularity[0m declaration with a parallelism primitive. This form ensures that a call is parallelized only if resources are available and the granularity form evaluates to a non-[47mnil[0m value at the time of the call. Below is a definition of the Fibonacci function using a granularity form. (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (pargs (declare (granularity (>= x 27))) (binary-+ (pfib (- x 1)) (pfib (- x 2))))))) A granularity form can reference an extra formal parameter that describes the call depth of the function the user is parallelizing. Consider for example the following parallel [47mmergesort[0m function, based on Davis's Ordered Sets library. It splits the data into symmetric chunks for computation, so we increment the [47mdepth[0m argument during the recursive call on both the [47mcar[0m and [47mcdr[0m. (include-book "finite-set-theory/osets/sets" :dir :system) (defun set::pmergesort-exec (x depth) (declare (xargs :mode :program)) (cond ((endp x) nil) ((endp (cdr x)) (set::insert (car x) nil)) (t (mv-let (part1 part2) (set::split-list x nil nil) (pargs (declare (granularity (< depth 2))) (set::union (set::pmergesort-exec part1 (1+ depth)) (set::pmergesort-exec part2 (1+ depth)))))))) A less intrusive method (i.e., not requiring an extra formal parameter like the [47mdepth[0m argument just above), which however can be less efficient, involves analyzing the data itself for structural properties. For example: (defun some-depth-exceeds (x n) (declare (xargs :guard (natp n))) (if (atom x) nil (if (zp n) t (or (some-depth-exceeds (car x) (1- n)) (some-depth-exceeds (cdr x) (1- n)))))) (defun valid-tip (x) (declare (xargs :guard t)) (or (eq x 'A) (eq x 'T) (eq x 'C) (eq x 'G))) (defun pvalid-tree (x) (declare (xargs :guard t)) (if (atom x) (valid-tip x) (pand (declare (granularity (some-depth-exceeds x 3))) (pvalid-tree (car x)) (pvalid-tree (cdr x))))) If you experiment with calls of [47mpvalid-tree[0m, you are likely to find that the ``speedup'' it provides over a corresponding serial version is, in fact, a slowdown! The problem is likely that [47msome-depth-exceeds[0m is an expensive function to run repeatedly. Instead of the approach above, it is often handy to add an extra formal parameter in order to allow for more efficient granularity forms, as we have done above in the definition of [47mSET::pmergesort-exec[0m.") (gratuitous-lambda-object-restrictions (apply$) "Enforcement of logically unnecessary restrictions on [47m:FN[0m slots When a form is submitted to the ACL2's read-eval-print loop the terms in it are translated (``macroexpanded'') into ACL2's internal form, in which abbreviations like [47m(cadr x)[0m are expanded away and constants are always quoted. See [term] for details of the internal form. But translation also enforces a logically unnecessary restriction in argument positions of [ilk] [47m:FN[0m. If a quoted [47mconsp[0m object whose [47mcar[0m is the symbol [47mLAMBDA[0m occurs in a [47m:FN[0m slot, translate insists that the object satisfy [47m[well-formed-lambda-objectp][0m. Well-formedness implies tameness, so any [47mLAMBDA[0m object that passes this translate-time test will have the ``expected behavior'' under [47mapply$[0m. If a quoted ill-formed ``LAMBDA-like'' object is passed into a [47m:FN[0m slot, an error is signaled. This is logically unnecessary because, like all ACL2 functions, [47mapply$[0m can be called on any objects. Indeed, ill-formed [47mLAMBDA[0m-like objects induce some kind of default behavior by [47mapply$[0m and can, sometimes, deliver non-erroneous values. But ground [47mapply$[0m terms can be evaluated more quickly on well-formed [47mLAMBDA[0m objects than on ill-formed ones. See for example the discussion of performance in [47m[print-cl-cache][0m. So this restriction is really motivated by a desire to encourage the exclusive use of well-formed [47mLAMBDA[0m objects. Why would you want to call [47mapply$[0m on ill-formed input? The answer is that you might be trying to explore the semantics of [47mapply$[0m by example. Since this is a time-honored methodology, we have made it possible to circumvent the translate-time check if you insist on feeding an ill-formed object into a [47m:FN[0m slot. Soundness is not imperiled but execution may slow down. [3mWarning[0m: Using an ill-formed [47mLAMBDA[0m object in a [47m:FN[0m slot in a [47mdefun[0m will make it impossible to warrant the newly defined function because it will not pass the stringent tests necessary to analyze its ilks. See [47m[defwarrant][0m. Basically these bypasses are intended primarily for top-level input to ACL2's read-eval-print loop. There are two ways to bypass the check. Bypass 1 is to construct the object in place rather than supply a quoted constant. This can be as simple as consing a [47mLAMBDA[0m onto the rest of your ill-formed constant. This, of course, costs one cons at eval-time. Bypass 2 is to cons the ill-formed object together in a [47m[defconst][0m and then use the defined constant symbol in the [47m:FN[0m slot. We illustrate these and other points below. ; Here we show the error that occurs if you use an ill-formed ; LAMBDA object in a :FN slot. ACL2 !>(apply$ '(lambda (t) (cons t t)) '(a)) ACL2 Error in TOP-LEVEL: The second element of a well-formed LAMBDA object or lambda$ term must be a true list of distinct legal variable symbols and (T) is not. See :DOC gratuitous-lambda-object-restrictions for a workaround if you really mean to have an ill-formed LAMBDA-like constant in your code. Note: this error occurred in the context (APPLY$ '(LAMBDA (T) (CONS T T)) '(A)). ; Bypass 1: Cons the ill-formed object together in place. ACL2 !>(apply$ (cons 'lambda '((t) (cons t t))) '(a)) (A . A) ; Bypass 1 (more attractive but perhaps too subtle): Use ; backquote. This looks prettier, indeed, it is almost ; unnoticeable! But it does more eval-time consing. ACL2 !>(apply$ `(lambda (t) (cons t t)) '(a)) (A . A) ; Bypass 2: Use defconst first. No runtime consing. ACL2 !>(defconst *my-ill-formed-lambda* `(lambda (t) (cons t t))) ...output elided... ACL2 !>(apply$ *my-ill-formed-lambda* '(a)) (A . A) ; You can, of course, use these bypasses when defining new ; functions. ACL2 !>(defun foo (x) (apply$ *my-ill-formed-lambda* (list x))) ...successful defun output elided... ; You can then execute the new function, possibly slowly. ACL2 !>(foo 'b) (B . B) ; But you can't warrant the new function because defwarrant ; can't determine the ilks. ACL2 !>(defwarrant foo) ACL2 Error in DEFWARRANT: FOO will not be warranted because a :FN slot in its body is occupied by a quoted cons object, '(LAMBDA (T) (CONS T T)), that is not a well-formed, fully-translated, closed ACL2 lambda object. ... ; Thus, you can't apply$ 'foo either. ACL2 !>(apply$ 'foo '(c)) ACL2 Error in TOP-LEVEL: The value of APPLY$-USERFN is not specified on FOO because FOO has not been warranted. By the way, [47m:FN[0m slots are treated differently in another way by translate: [47m[lambda$][0m terms are [3monly[0m allowed in [47m:FN[0m slots. This restriction is necessary for ACL2's correct operation. [47mLambda$[0m expands differently in the logic than it does in the underlying Common Lisp. If [47mlambda$[0m terms were allowed to occur anywhere, this difference could be detected by the difference between proved behavior and computed behavior and could be used to render ACL2 unsound.") (ground-zero (theories theory-functions) "[enable]d rules in the [startup] theory ACL2 concludes its initialization [47m(boot-strapping)[0m procedure by defining the theory [47mground-zero[0m; see [theories]. In fact, this theory is just the theory defined by [47m(current-theory :here)[0m at the conclusion of initialization; see [current-theory]. Note that by evaluating the event (in-theory (current-theory 'ground-zero)) you can restore the current theory to its value at the time you started up ACL2.") (gthm (history guard-formula-utilities) "The [guard] theorem for a given function symbol This utility (pronounced ``gee-thumb'') generates the [guard] theorem (i.e., guard proof obligation) for a given function symbol, as would be generated by a [47m:[0m[47m[guard-theorem][0m [lemma-instance] in a [47m:[0m[use] hint. Example Forms: :gthm FN (gthm 'FN) ; equivalent to the above (gthm 'FN :limited nil) ; equivalent to the above (gthm 'FN :limited t) ; include guard-debug info (gthm 'FN nil) ; avoid any simplification General Forms: :gthm FN ; equivalent to (gthm 'FN) (gthm x &optional simplify guard-debug) where [47mFN[0m is a function symbol and [47mx[0m evaluates to a function symbol. Evaluation returns the guard theorem as a user-level (untranslated) [47m[term][0m. The optional argument [47msimplify[0m, described below, is [47m:limited[0m by default. The optional argument [47mguard-debug[0m is [47mnil[0m by default; when non-[47mnil[0m, the guard theorem is modified as with the option [47m:guard-debug[0m for [47m[verify-guards][0m; see [guard-debug]. See [lemma-instance] for how to provide the result of [47m:gthm[0m as a [47m:guard-theorem[0m prover hint. Also see [guard-formula-utilities] for related utilities. Normally one will evaluate [47m:gthm FN[0m or equivalently (see [keyword-commands]), the form [47m(gthm 'FN)[0m. In this case the guard theorem may be partially simplified before it is returned, by using a form of ``subsumption'' to eliminate redundancy and by deleting tautologies as well as instances of [built-in-clause] rules that come with ACL2. The [47msimplify[0m argument should be [47mnil[0m to avoid such simplification; that is, use [47m(gthm 'FN nil)[0m. See also [guard-simplification] for discussion of simplification done for various guard formula utilities. Note that the result from evaluating [47m(gthm x simplify guard-debug)[0m is an [3muntranslated[0m term, that is, a user-level term; see [term]. The corresponding call [47m(guard-theorem x simplify guard-debug (w state) state)[0m returns a translated term.") (guarantees-of-the-top-level-loop (soundness ld) "Guarantees provided by top-level evaluation We often refer to the ``top-level loop,'' or just ``the loop'' when the context is understood. The loop is the interactive read-eval-print loop with which the user interacts to issue commands, query the ACL2 logical world, test functions, conjectures, and systems, etc. This documentation topic mainly addresses the logical guarantees of the loop. For practical advice about interacting with and configuring the loop see [47m[ld][0m. [47mLd[0m is the ACL2 implementation of the loop (as a macro that calls a [47m[state][0m-using function with many parameters which may be set by the user). [47mLd[0m is called initially when ACL2 is fired up. But here we are concerned with what it means, logically, when a term [3mtm[0m evaluates without error to a value [3mv[0m in the loop. We do not formalize macroexpansion here, but rather, we deal with so-called ``translated'' [term]s, where macros and constants have been expanded away. We also do not discuss here how ACL2 evaluates expressions; see [evaluation] for such discussion. (Those interested in implementation issues may also read the long comment in ACL2 source file [47minterface-raw.lisp[0m that is labeled ``Essay on Evaluation in ACL2''.) See [soundness] for a more general discussion of soundness-related issues (including, for example, interrupts and trust tags). A Strawman Proposal on the Meaning of Top-Level Evaluation One might like to think that for any term, [3mtm[0m, a non-erroneous interaction like ACL2 !>[3mtm[0m [3mv[0m means that the formula (equal [3mtm[0m '[3mv[0m) is a theorem and can be proved by the prover. For example, let [47msq[0m be a :logic mode function that squares its argument. (For the sake of a later example, let us also make the [guard] of [47msq[0m be [47mt[0m and verify the guard by fixing (with [47m[rfix][0m) the argument to be a rational, but those aspects of [47msq[0m are irrelevant in our immediate use of it below.) (defun sq (x) (declare (xargs :guard t :verify-guards t)) (let ((x (rfix x))) (* x x))) then the evaluation ACL2 !>(sq 3) 9 suggests that [47m(equal (sq 3) 9)[0m is a theorem and that is indeed provable by the ACL2 theorem prover. But the situation is quite subtle and deserves further discussion. That is what this topic is about. [31;1mSpoiler Alert[0m: We will not give logical semantics to every non-erroneous evaluation in this discussion. We only hint at how it can be done for many terms. Furthermore, even for those terms whose evaluations do correspond to theorems, the logical theory in which those theorems can be proved is not the theory supported by the ACL2 prover but an extension of it. We ultimately describe below the so-called [3mevaluation theory[0m which is an extension of ACL2's [3mproof theory[0m. So this documentation topic discusses two logical theories. Because any theory in which proofs are done might be called the ``proof theory'' and in this section we need to clearly distinguish between the two theories being discussed, we'll refer to the theory supported by the ACL2 theorem prover as the [3mprover's theory[0m. Problems Raised by [47m:Program[0m Mode Functions Suppose [47mprog-sq[0m is defined as a [47m:[0m[47m[program][0m mode function that squares its argument. Then the top-level evaluation ACL2 !>(prog-sq 3) 9 clearly should not suggest (equal (prog-sq 3) 9) is a theorem. [47m:Program[0m mode functions are not defined in the prover's theory. ([47m:Program[0m mode functions may not terminate and any naive attempt to add their definitions to the prover's theory as axioms could result in unsoundness.) The top-level loop has the ability to evaluate [47m:program[0m mode expressions but it is ``magic,'' unsupported by proof. (Non-termination by the evaluator can't manifest unsoundness: such computations just never produce an answer.) The evaluation of [47m:program[0m mode expressions is supported in the loop primarily as a way to execute commands like [47m[defun][0m and [47m[defthm][0m. But it is also a convenience that allows ACL2 to be used as a [programming] language (e.g., to prototype a system one might eventually admit to the logic and prove theorems about). Therefore, when attempting to define the logical meaning of top-level evaluations we might restrict our attention to [47m:[0m[47m[logic][0m mode terms only. But this is not sufficient for several reasons. [47m:Program[0m mode functions raise another problem discussed below in connection with [47mapply$[0m. Problems Raised by Single-Threaded Objects Evaluation of terms involving single-threaded objects or ``[stobj]s'' raise problems, even if the terms involved are in [47m:logic[0m mode. Here is a top-level evaluation sequence ACL2 !>(defstobj st fld) ... ST ACL2 !>(update-fld 3 st) <st> ACL2 !>(update-fld (sq (fld st)) st) <st> ACL2 !>(fld st) 9 but the strawman conjecture from the last evaluation, [47m(equal (fld st) 9)[0m, is not a theorem. However, a related formula is a theorem and can be proved by the prover. (implies (stp st) (let* ((st (update-fld 3 st)) (st (update-fld (sq (fld st)) st))) (equal (fld st) 3))) This reminds us that the top-level loop tracks changes to each ``live'' stobj and records them in the ACL2 [47m[state][0m. Those changes must be reflected in any suggested theorems. Problems Raised by Apply$ [47m[Apply$][0m calls [47m[apply$-userfn][0m to handle the application of user-defined function symbols. [47mApply$-userfn[0m is undefined but might be constrained by [47m[warrant][0m hypotheses (see [47m[defwarrant][0m). Recall that warrants link the functions approved by [47mdefwarrant[0m to their names and constrain [47m(apply$ 'fn (list a1 ... an))[0m to be [47m(fn a1 ... an)[0m under certain [47m[tame][0mness conditions. As noted at the bottom of the discussion of [47m[defwarrant][0m, there is a model of the prover's theory in which all warrants issued by [47mdefwarrant[0m are true. The top-level loop assumes that all those warrants are true. But the prover's theory does not, because explicit warrant hypotheses are essential to avoiding the so-called ``local problem'' (see [31;1mLesson 12[0m of [introduction-to-apply$]). One might wonder why we have warrants at all, aside from the local problem. The key reason is that inconsistency can result from non-terminating recursion if we had the following axiom schema [31;1mUnsound Axiom Schema[0m: (equal (apply$ '[3mf[0m (list a1 ... an)) ([3mf[0m a1 ... an)) for every defined function [3mf[0m. See the [47mrussell[0m example in [introduction-to-apply$]. So warrants and the restrictions enforced by [47m[defwarrant][0m keep the prover's theory consistent. One might then ask ``how do we get away with letting the top-level loop [47mapply$[0m all badged [47m:program[0m mode functions?'' The answer is simple: [47m:program[0m mode functions are not axiomatized so we don't have a theory to worry about! To illustrate the difference between the behavior of the top-level loop and the prover, suppose the function [47msq[0m, defined above, has been warranted. (defwarrant sq) and then consider the top-level evaluation ACL2 !>(apply$ 'sq '(3)) 9 This is possible because the warrant for [47msq[0m is assumed true in the top-level loop and that warrant tells the loop that [47m(apply$ 'sq '(3))[0m = [47m(sq 3)[0m. However, [47m(equal (apply$ 'sq '(3)) '9)[0m is not a theorem in the prover's theory. Instead, this is a theorem (implies (warrant sq) (equal (apply$ 'sq '(3)) '9)) where [47m(warrant sq)[0m is just a convenient abbreviation for [47m(force (apply$-warrant-sq))[0m. Thus, to extend the strawman conjecture to functions in which [47mapply$[0m is ancestral would require tracking the warrants relevant to the execution path (or punting and collecting all warrants) and amending the conjecture to add those warrants as hypotheses to the equality. But [47mapply$[0m introduces another source of complexity: mixed-mode functions (see [mixed-mode-functions]). Recall the [47m:program[0m mode function [47mprog-sq[0m which squares its argument. We can assign a badge to [47mprog-sq[0m and then define a [47m:logic[0m mode function that [47mapply$[0ms it! (defbadge prog-sq) (defun logic-sq (x) (declare (xargs :mode :logic)) (apply$ 'prog-sq (list x))) Since the top-level loop can evaluate applications of [47m:program[0m mode symbols we see the following evaluation. ACL2 !>(logic-sq 3) 9 Note that [47m(logic-sq 3)[0m is a [47m:logic[0m mode term and [47mlogic-sq[0m can even be warranted with [47mdefwarrant[0m. But neither (equal (logic-sq 3) '9) nor (implies (warrant logic-sq) (equal (logic-sq 3) '9)) is a theorem in the prover's theory because [47mprog-sq[0m is undefined in that theory. For what it is worth, the prover can prove (implies (warrant logic-sq) (equal (logic-sq 3) (apply$ 'prog-sq '(3)))) This example contradicts the suggestion, just above, that if we properly considered warrants we could give logical meaning to evaluations of [47m:logic[0m mode terms involving [47mapply$[0m. Problems Raised by Constrained Functions Constrained functions raise problems if they have been given attachments (see [47m[defattach][0m). The top-level loop uses attachments to compute values consistent with the constraints, but the prover's theory does not. Attachments are useful for building and testing instances of models consistent with the constraints. For example, let [47m(nonneg-rat x)[0m be constrained to return some nonnegative rational. (encapsulate (((nonneg-rat *) => *)) (local (defun nonneg-rat (x) (declare (ignore x)) 0)) (defthm nonneg-rat-constraint (and (rationalp (nonneg-rat x)) (<= 0 (nonneg-rat x))))) It is impossible to evaluate [47m(nonneg-rat 3)[0m in the top-level loop. But we can attach another function to it provided we can prove that function always returns a nonnegative rational. Since [47msq[0m, as defined above to [47mrfix[0m its argument as a rational, satisfies that constraint, we can attach [47msq[0m to [47mnonneg-rat[0m. (defattach nonneg-rat sq) and then we can ``evaluate'' calls of [47mnonneg-rat[0m in the loop, getting results that are consistent with its constraint (but overly specific!). ACL2 !>(nonneg-rat 3) 9 But of course the strawman conjecture [47m(equal (nonneg-rat 3) '9)[0m is not a theorem of the prover's theory. The Prover's Theory The ACL2 logic formalizes an applicative (functional and side-effect free) extension of a subset of Common Lisp (see [common-lisp]). It is described in chapter 6 of {Computer-Aided Reasoning: An Approach | http://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html}, by Kaufmann, Manolios, and Moore, as an extension of quantifier-free first-order logic with equality (section 6.1). The syntax is that of translated [term]s though the user is allowed to use a more flexible syntax which can be extended by defining constant symbols and macros (see [47m[defconst][0m and [47m[defmacro][0m). To see the formal translation of such a term use the command [47m:[0m[47m[trans][0m. In section 6.2 of the book, axioms are added to characterize the basic data objects of numbers (integers, rationals, and complex rationals), characters, strings, symbols, and ordered pairs. In section 6.3, the ordinals up to epsilon-0 are constructed from ordered pairs and integers; a well-founded ``less than'' relation is also defined. But the book's construction of the ordinals is now obsolete. A new representation was implemented after the book was published. See [ordinals]. In Section 6.4, a conservative Principle of Definition (see [47m[defun][0m and [47m[defuns][0m or [47m[mutual-recursion][0m) is introduced, allowing the addition of axioms defining new function symbols. In Section 6.5, a Principle of Induction up to epsilon-0 is described. Induction and recursion are duals: every admissible recursive function suggests an induction and vice versa and this duality is used by the ACL2 prover to select an often appropriate induction scheme for a conjecture. See [induction] and [47m[hints][0m for ways to influence this selection. Finally, in section 6.6, the book introduces [47m[encapsulate][0m to introduce constrained functions and functional instantiation (a derived rule of inference akin to second order instantiation), and a variety of other ways of conservatively adding new function symbols. The ACL2 prover proves theorems in the extension of the above theory obtained by adding the axioms introduced by [events] successfully carried out in the user's session. The most common such axiom-adding events are [47m[defun][0m, [47m[defchoose][0m, and [47m[encapsulate][0m, which all conservatively extend the theory by the addition of axioms about new function symbols. But [47mdefun[0m is just a special case of [47mdefuns[0m which adds a mutually recursive clique of new names (see also [47m[mutual-recursion][0m). [47m[Defstobj][0m and [47m[defabsstobj][0m add recognizers, constructors, and accessors for single-threaded objects (aka ``[stobj]s'') but logically just use [47mdefun[0m to add new functions and then syntactically restrict their use in code. Finally, we provide a means of adding an arbitrary formula as an axiom, [47m[defaxiom][0m, but [3mstrongly discourage its use[0m. There are many other events that add axioms, e.g., [47m[defun-nx][0m and [47m[defun-sk][0m but these are defined as macros that expand into the primitives just listed. In addition, there is a facility for including files of previously admitted events, [47m[include-book][0m. Note that an event of the form [47m(skip-proofs EV)[0m does not introduce any axioms other that those added by the event, [47mEV[0m. However, this [47m[skip-proofs][0m event does assume that all proof obligations introduced by [47mEV[0m are indeed provable in the prover's theory. Given a user's session, we call the above described theory the [3mprover's theory[0m. Now recall the strawman proposal for what evaluation in the top-level loop means, i.e., that the evaluation ACL2 !>[3mtm[0m [3mv[0m might mean that the formula (equal [3mtm[0m '[3mv[0m) is a theorem. We have illustrated with [47m:program[0m mode functions, uses of [47mapply$[0m, and of constrained functions that this strawman conjecture is [3mnot[0m necessarily a theorem of the prover's theory! However, there is a theory in which many of these conjectures are theorems. The Evaluation Theory The [3mevaluation theory[0m is obtained from the prover's theory as follows. * Instead of treating stobj names as variables, the evaluation theory treats them as abbreviations for the ``current value'' of the stobj, specifically, the constant obtained by composing the sequence of all updates to the stobj's fields carried out so far in the top-level loop. Thus, for example, in the evaluation theories created by this sequence of top-level evaluations ACL2 !>(defstobj st fld) ; [1] ST ACL2 !>(update-fld 3 st) ; [2] <st> ACL2 !>(update-fld (* (fld st) (fld st)) st) ; [3] <st> [47mst[0m is an abbreviation for [47m(NIL)[0m after evaluation [1], an abbreviation for [47m(3)[0m after evaluation [2], and an abbreviation for [47m(9)[0m after evaluation [3]. * Every warrant created by [47mdefwarrant[0m is assumed true as an axiom. * For every [47m(defattach f g)[0m event in the prover's theory the axiom (i.e., constraints) on [47mf[0m is replaced by the axiom [47m(equal (f ...) (g ...))[0m in the evaluation theory. (Of course this replacement also takes place when using the more general form for [47m[defattach][0m, [47m(defattach ... (f g ...) ...)[0m.) Given the restrictions enforced by [47mdefun[0m, [47mdefstobj[0m, [47mdefwarrant[0m, [47mapply$[0m, [47mencapsulate[0m, and [47mdefattach[0m, the evaluation theory is consistent if the prover's theory is consistent and free of [47mdefaxiom[0m events. (Those interested in reading a proof of this claim are welcome to read the ``Essay on Defattach'' in ACL2 source file [47mother-events.lisp[0m.) Furthermore, the top-level evaluation ACL2 !>[3mtm[0m [3mv[0m means that (equal [3mtm[0m '[3mv[0m) is a theorem in the evaluation theory provided * [3mtm[0m is a [47m:logic[0m mode term, and * every symbol that reaches the first argument of any [47mapply$-userfn[0m in the execution of [3mtm[0m is in [47m:logic[0m mode. The ACL2 prover cannot generally prove these theorems, since it operates in the prover's theory. However, as noted, there are often ways to encode the conjectures into ACL2 formulas that are provable --- in particular, by adding suitable warrant hypotheses --- though the ACL2 system does not provide tools for doing so. Some Examples of Top-Level Evaluations In this section we illustrate some consequences of the guarantee that for any term, [3mtm[0m, satisfying certain restrictions, if [3mtm[0m evaluates to a value [3mv[0m, then the term (equal [3mtm[0m '[3mv[0m) is a theorem of the evaluation theory. Each command below is enumerated and after the entire sequence we make observations about the results and implications. It might also help to read the section [31;1mTop-Level Evaluation of Apply$[0m in the documentation for [47m[apply$][0m, which describes how [47mapply$[0m is implemented in the top-level loop. ACL2 !>(include-book "projects/apply/top" :dir :system) ... ACL2 !>(defun my-cons (x y) ; [1] (declare (xargs :mode :program)) (cons x y)) ... ACL2 !>(defbadge my-cons) ; [2] MY-CONS now has the badge (APPLY$-BADGE 2 1 . T) but has no warrant. T ACL2 !>(apply$ 'my-cons '(3 4)) ; [3] (3 . 4) ACL2 !>(thm (equal (my-cons 3 4) '(3 . 4))) ; [4] ... ******** FAILED ******** ACL2 !>(verify-termination my-cons) ; [5] ... ACL2 !>(apply$ 'my-cons '(3 4)) ; [6] ACL2 Error in TOP-LEVEL: The value of APPLY$-USERFN is not specified on MY-CONS because MY-CONS has not been warranted. ACL2 !>(defwarrant my-cons) ; [7] MY-CONS is now warranted by APPLY$-WARRANT-MY-CONS, with badge (APPLY$-BADGE 2 1 . T). ACL2 !>(apply$ 'my-cons '(3 4)) ; [8] (3 . 4) ACL2 !>ACL2 !>(thm (equal (my-cons 3 4) '(3 . 4))) ; [9] ... ******** FAILED ******** ACL2 !>(thm ;[10] (implies (warrant my-cons) (equal (my-cons 3 4) '(3 . 4)))) ... Q.E.D. ... Proof succeeded. In events [1] and [2] [47mmy-cons[0m is introduced as a badged [47m:program[0m mode function. Command [3] shows that we can [47mapply$[0m [47m'my-cons[0m in the top-level loop and get the ``expected'' value. This is ``magic'' on several levels! There is no axiom in the evaluation theory defining [47mmy-cons[0m and there is no warrant connecting the symbol [47m'my-cons[0m to the function [47mmy-cons[0m. The failure of the first [47mthm[0m command, [4], shows that the prover's theory knows nothing of the behavior of [47mapply$[0m on [47m'my-cons[0m. After converting [47mmy-cons[0m to [47m:logic[0m mode with [47m[verify-termination][0m in [5] we can no longer evaluate the application of [47mmy-cons[0m at the top-level, as shown by [6]! This is surprising because one might expect ACL2 to be able to do more with a [47m:logic[0m mode function than its [47m:program[0m mode counterpart. But in the evolving evaluation theory as of [6], [47mmy-cons[0m is a [47m:logic[0m mode function with no warrant and so logically speaking [47m(apply$ 'my-cons ...)[0m is undefined. Computing a value for it at [6] would violate the guarantee that values of [47m:logic[0m mode terms can be proved correct in the evaluation theory --- i.e., that the computed value can be derived logically. Such a derivation is impossible without a warrant. However, after [47mdefwarrant[0m, in [7], confirms that it is sound to issue a warrant (linking the symbol [47m'my-cons[0m to the function [47mmy-cons[0m via [47mapply$[0m), the evaluation of the [47m'my-cons[0m term in [8] succeeds. The [47mdefwarrant[0m soundly extends the proof theory by adding a definition for the warrant function for [47mmy-cons[0m and extends the evaluation theory by assuming the warrant for [47mmy-cons[0m is true. This latter extension is also sound. However, [9] shows that we still cannot prove (in the prover's theory) that the evaluation of the [47mapply$[0m term is correct, because we did not provide the warrant as a hypothesis. However, if we amend the conjecture to include the warrant, as in [10], the proof (in the prover's theory) succeeds. While all warrants are assumed true in the evaluation theory, they must be made explicit as hypotheses for proofs in the prover's theory. This is the mechanism whereby ACL2 can avoid the ``local problem'' illustrated in [31;1mLesson 12[0m of [introduction-to-apply$] and discussed more thoroughly in {``Limited Second-Order Functionality in a First-Order Setting'' | http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore.") (guard (programming xargs) "Restricting the domain of a function NOTE: Novices are often best served by avoiding guards. The ACL2 system provides a mechanism for restricting a function to a particular domain. Such restrictions are called ``guards.'' A definition's guard has no effect on the logical axiom added when that definition is accepted by ACL2. Moreover, the guard has NO EFFECT on the proof that a recursive definition is admissible --- informally, that it terminates). (See [mbt] for a discussion of one way to use the guard explicitly to assist with that proof while avoiding execution overhead.) Guards can be useful as a specification device or for increasing execution efficiency. To make such a restriction, use the [47m:guard[0m keyword (see [xargs]) or, especially if you want the host Lisp compiler to use this information, use [47mtype[0m declarations (see [declare]; also see [xargs] for a discussion of the [47m:split-types[0m keyword). The general issue of guards and guard verification is discussed in the topics listed below. To begin further discussion of guards, see [guard-introduction]. That section directs the reader to further sections for more details. To see just a summary of some [command]s related to guards, see [guard-quick-reference]. For a discussion of the use of proof to verify the absence of guard violations, see [verify-guards]. Subtopics [Ec-call] Execute a call in the ACL2 logic instead of raw Lisp [Extra-info] Sources of measure, guard, or constraint proof obligations [Guard-checking-inhibited] Avoiding certain warnings when evaluating ACL2 expressions [Guard-debug] Generate markers to indicate sources of [guard] proof obligations [Guard-evaluation-examples-log] Log showing combinations of [defun-mode]s and [guard]-checking [Guard-evaluation-examples-script] A script to show combinations of [defun-mode]s and [guard]-checking [Guard-evaluation-table] A table that shows combinations of [defun-mode]s and [guard]-checking [Guard-example] A brief transcript illustrating [guard]s in ACL2 [Guard-formula-utilities] Utilities that show guard proof obligations [Guard-holders] Remove trivial calls from a [term] [Guard-introduction] Introduction to [guard]s in ACL2 [Guard-miscellany] Miscellaneous remarks about guards [Guard-quick-reference] Brief summary of guard checking and guard verification [Guard-theorem-example] How to use a previously-proved [guard] theorem [Guards-and-evaluation] The relationship between guards and evaluation [Guards-for-specification] Guards as a specification device [Invariant-risk] Potential slowdown for [program]-mode updates to [stobj]s or [arrays] [Mbe] Attach code for execution [Non-exec] Mark code as non-executable [Print-gv] Print a form whose evaluation caused a guard violation [Program-only] Functions that cannot be in [logic] mode [Safe-mode] A mode that avoids [guard] violations on [primitive]s [Set-check-invariant-risk] Affect certain [program]-mode updates to [stobj]s or [arrays] [Set-guard-checking] Control checking [guard]s during execution of top-level forms [Set-guard-msg] Specify what is printed when a [guard] is violated [Set-print-gv-defaults] Set default keyword values for [47m[print-gv][0m [Set-register-invariant-risk] Avoid [invariant-risk] checking for specified functions [Set-verify-guards-eagerness] The eagerness with which [guard] verification is tried. [The] Special form for execution efficiency or run-time type checks [Verify-guards] Verify the [guard]s of a function [With-guard-checking] Suppress or enable guard-checking for a form [With-guard-checking-error-triple] Suppress or enable guard-checking for a form [With-guard-checking-event] Suppress or enable guard-checking for an event form") (guard-checking (pointers) "See [set-guard-checking].") (guard-checking-inhibited (evaluation guard) "Avoiding certain warnings when evaluating ACL2 expressions ACL2 sometimes omits the checking of [guard]s on recursive calls of functions. This omission is signaled by a warning like the one shown below. ACL2 !>(factorial 3) ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited for some recursive calls for FACTORIAL and perhaps other functions; see :DOC guard-checking-inhibited. 6 ACL2 !> This behavior can occur for a recursively-defined [logic]-mode function with a guard other than [47mt[0m whose guards have not been verified, when [guard-checking] has its default value, [47mt[0m. (Exceptions may occur, for example when the function is being traced.) No further such message is printed (for any function) before the next top-level form is submitted. To check guards on all recursive calls: (set-guard-checking :all) To leave the current behavior unchanged except for inhibiting such messages: (set-guard-checking :nowarn)") (guard-debug (guard debugging) "Generate markers to indicate sources of [guard] proof obligations ACL2 guard verification (see [guard]) is often best avoided by beginning users of ACL2. When guard verification is employed, it can generate numerous goals, some of which may not be theorems if the definition being processed has bugs. It can be difficult to find such bugs. This [documentation] topic explains a capability provided by ACL2 to help find such bugs. For a similar utility appropriate for proving [measure] conjectures (that is, for termination proofs), see [measure-debug]. We begin with the following example. Although it is contrived and a bit simplistic, it illustrates how the guard-debug utility works. (defun length-repeat (x) (length (append x x))) (verify-guards length-repeat :guard-debug t) The output produces two top-level key checkpoints, as follows. Subgoal 2 (IMPLIES (EXTRA-INFO '(:GUARD (:BODY LENGTH-REPEAT)) '(APPEND X X)) (TRUE-LISTP X)) Subgoal 1 (IMPLIES (AND (EXTRA-INFO '(:GUARD (:BODY LENGTH-REPEAT)) '(LENGTH (APPEND X X))) (NOT (TRUE-LISTP (APPEND X X)))) (STRINGP (APPEND X X))) The upper subgoal (numbered 2) says that the body of the definition of [47mlength-repeat[0m contains a call [47m(APPEND X X)[0m, which is the source of the goal. In this case, that makes sense: the [guard] for a call [47m(append arg1 arg2)[0m is [47m(true-listp arg1)[0m, which in this case is [47m(TRUE-LISTP X)[0m. The lower subgoal (numbered 1) says that the same definition contains the call [47m(LENGTH (APPEND X X))[0m, which generates the proof obligation that if [47m(APPEND X X)[0m does not satisfy [47mtrue-listp[0m, then it must satisfy [47mstringp[0m. That proof obligation comes directly from the [guard] for [47m[length][0m. Of course, the example above is a bit obvious. But for large definitional bodies such information can be very helpful. Note that guard-debug can be specified not only in [47m[verify-guards][0m events but also in [47m[xargs][0m [47m[declare][0m forms of [47m[defun][0m events. We now describe the guard-debug utility in some detail. [47m(Extra-info x y)[0m always returns [47mt[0m by definition. However, if [guard] verification takes place with a non-[47mnil[0m setting of [47mguard-debug[0m (see below), then the goals generated for guard verification can include hypotheses that are calls of [47mextra-info[0m. Typically, such a hypothesis is of the following form: (extra-info '(:guard (:body F)) '(G ARG1 ... ARGk)) The above form indicates that the goal in which it occurs was generated to verify that the [guard] of the function [47mF[0m is satisfied by the arguments [47mARG1[0m through [47mARGk[0m, where the term [47m(G ARG1 ... ARGk)[0m occurs in the body of the function [47mF[0m whose guard verification is in progress. If however the above call of [47mG[0m occurs in the guard of [47mF[0m instead of the body of [47mF[0m, then [47m:body[0m is replaced by [47m:guard[0m above: (extra-info '(:guard (:guard F)) '(G ARG1 ... ARGk)) If the same proof obligation (goal [clause]) arises from more than one occurrence of the same call, then a single goal will be generated, which has several [47mextra-info[0m hypotheses added to show the multiple sources of that proof obligation. All rules (see [rune]) associated with [47mextra-info[0m are [disable]d by default, so that hypotheses of the form described above are not simplified to [47mt[0m. These hypotheses are intended to ride along for free: you can generally expect the proof to have the same structure whether or not the [47m:guard-debug[0m option is supplied, though on rare occasions the proofs may diverge. It remains to explain the notion of a [47mguard-debug[0m setting of [47mt[0m, that is, to explain how to obtain the additional hypotheses described above. If guards are being verified during processing of a [47m[defun][0m event (whether or not inside a call of [47m[mutual-recursion][0m), then one specifies [47m:guard-debug t[0m in an [47m[xargs][0m declaration of a [47m[declare][0m form; see [xargs]. If however the guard verification is on behalf of a [47m[verify-guards][0m call, whether for a definition or a theorem, then one specifies the keyword argument [47m:guard-debug t[0m. Also see [print-gv] for a utility for debugging guard violations, in contrast to the above guard-debug mechanism, which is for debugging failed proofs arising from guard verification.") (guard-evaluation-examples-log (guard) "Log showing combinations of [defun-mode]s and [guard]-checking See [guard-evaluation-examples-script] for a script that shows the interaction of [defun-mode]s with the value set by [47m[set-guard-checking][0m. Here, we present a log resulting from running this script. It may also be helpful to see [evaluation]. See [set-guard-checking] for discussion of the interaction between [defun-mode]s and [guard]-checking that is illustrated by this script. Also see [guard-evaluation-table] for a succinct table, with associated discussion, that covers in detail the interactions illustrated here. ACL2 !>(defun fact (x) (declare (xargs :guard (integerp x) :mode :program)) (if (posp x) (* x (fact (1- x))) 1)) Summary Form: ( DEFUN FACT ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 !>(trace$ fact) ((FACT)) ACL2 !>:set-guard-checking t Guard-checking-on already has value T. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the :program function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the :program function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:u 0:x(EXIT-BOOT-STRAP-MODE) ACL2 >(defun fact (x) (declare (xargs :guard t :mode :program)) (if (posp x) (* x (fact (1- x))) 1)) Summary Form: ( DEFUN FACT ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 >(trace$ fact) ((FACT)) ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:u 0:x(EXIT-BOOT-STRAP-MODE) ACL2 >(defun fact (x) (declare (xargs :guard (integerp x) :verify-guards nil :mode :logic)) (if (posp x) (* x (fact (1- x))) 1)) For the admission of FACT we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). The non-trivial part of the measure conjecture is [[output omitted here]] Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 >(trace$ fact) ((FACT)) ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(fact 2) [[Comment added to the log: Normally you would get a message about guard-checking being inhibited on recursive calls. However, when a function is traced the guard-checking is done on recursive calls unless the guards have been verified (see :DOC verify-guards). ]] 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard- checking for information about suppressing this check with (set-guard- checking :none), as recommended for new users. ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard- checking for information about suppressing this check with (set-guard- checking :none), as recommended for new users. ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) [[Comment added to the log: In spite of the warning above, guards are checked here on self-recursive calls, because the function is traced. ]] 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >(verify-guards fact) Computing the guard conjecture for FACT.... The guard conjecture for FACT is trivial to prove, given the :compound- recognizer rule POSP-COMPOUND-RECOGNIZER, primitive type reasoning and the :type-prescription rule FACT. FACT is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS FACT) Rules: ((:COMPOUND-RECOGNIZER POSP-COMPOUND-RECOGNIZER) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:TYPE-PRESCRIPTION FACT)) Warnings: None Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) FACT ACL2 >(trace$ fact) ((FACT)) ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard- checking for information about suppressing this check with (set-guard- checking :none), as recommended for new users. ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard- checking for information about suppressing this check with (set-guard- checking :none), as recommended for new users. ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:u L 1:x(DEFUN FACT (X) ...) ACL2 >:u 0:x(EXIT-BOOT-STRAP-MODE) ACL2 >(defun fact (x) (declare (xargs :guard (integerp x) :mode :logic)) (if (posp x) (* x (fact (1- x))) 1)) For the admission of FACT we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). The non-trivial part of the measure conjecture is [[output omitted here]] Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 >(trace$ fact) ((FACT)) ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard- checking for information about suppressing this check with (set-guard- checking :none), as recommended for new users. ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) ACL2 Error in TOP-LEVEL: The guard for the function symbol FACT, which is (INTEGERP X), is violated by the arguments in the call (FACT T). See :DOC trace for a useful debugging utility. See :DOC set-guard- checking for information about suppressing this check with (set-guard- checking :none), as recommended for new users. ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:u 0:x(EXIT-BOOT-STRAP-MODE) ACL2 >(defun fact (x) (declare (xargs :guard t :verify-guards nil :mode :logic)) (if (posp x) (* x (fact (1- x))) 1)) For the admission of FACT we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). The non-trivial part of the measure conjecture is [[output omitted here]] Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 >(trace$ fact) ((FACT)) ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (ACL2_*1*_ACL2::FACT 1) 3> (ACL2_*1*_ACL2::FACT 0) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 1) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >(verify-guards fact) Computing the guard conjecture for FACT.... The guard conjecture for FACT is trivial to prove, given the :compound- recognizer rule POSP-COMPOUND-RECOGNIZER and the :type-prescription rule FACT. FACT is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS FACT) Rules: ((:COMPOUND-RECOGNIZER POSP-COMPOUND-RECOGNIZER) (:TYPE-PRESCRIPTION FACT)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT [[Note added to log: No need to trace fact again after verify-guards.]] ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 !>:set-guard-checking :all Leaving guard checking on, but changing value to :ALL. ACL2 !>(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 !>(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >:set-guard-checking nil Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(fact 2) 1> (ACL2_*1*_ACL2::FACT 2) 2> (FACT 2) 3> (FACT 1) 4> (FACT 0) <4 (FACT 1) <3 (FACT 1) <2 (FACT 2) <1 (ACL2_*1*_ACL2::FACT 2) 2 ACL2 >(fact t) 1> (ACL2_*1*_ACL2::FACT T) 2> (FACT T) <2 (FACT 1) <1 (ACL2_*1*_ACL2::FACT 1) 1 ACL2 >") (guard-evaluation-examples-script (guard) "A script to show combinations of [defun-mode]s and [guard]-checking Below is a script that illustrates the combination of [defun-mode]s --- [47m:[0m[47m[program][0m mode, [47m:[0m[47m[logic][0m mode without [guard]s verified, and [47m:[0m[47m[logic][0m mode with [guard]s verified --- with values from [47m[set-guard-checking][0m --- [47mt[0m (the default), [47m:all[0m, [47m:none[0m, and [47mnil[0m. (It does not illustrate the value [47m:nowarn[0m, which is the same as [47mt[0m except for inhibiting a warning.) The script also illustrates cases where the guard is not, or is, [47mt[0m. See [guard-evaluation-examples-log] for result of running this script. Before presenting the script below, we give some instructions in case you want to run it yourself. See [set-guard-checking] for discussion of the interaction between [defun-mode]s and [guard]-checking that is illustrated by this script. Also see [guard-evaluation-table] for a succinct table, with associated discussion, that covers in detail the interactions illustrated here. The script mentions the running of ``Tracing Code''. The code is the following sequence of commands. (trace$ fact) :set-guard-checking t (fact 2) (fact t) :set-guard-checking :all (fact 2) (fact t) :set-guard-checking :none (fact 2) (fact t) :set-guard-checking nil (fact 2) (fact t) If you want to run the script yourself, you may find it handy to use the following Emacs keyboard macro for running the tracing code in 2-window mode, with the cursor in the window with the script and ACL2 running in the other window. The [47mdefine-key[0m command is optional, in case you want to put that keyboard macro on a key --- though in that case you'll need to have defined [47mctl-t-keymap[0m, which happens automatically if you load file [47memacs-acl2.el[0m; see :DOC emacs. (fset 'step-guard-script [?C-a ?C- ?C-e ?M-w ?C-a ?C-n ?C-x ?o ?M-> ?C-y return ?C-x ?o]) (define-key ctl-t-keymap "r" 'step-guard-script) The script follows. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Program mode ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun fact (x) (declare (xargs :guard (integerp x) :mode :program)) (if (posp x) (* x (fact (1- x))) 1)) ; Run the Tracing Code here. It shows execution in raw Lisp in the t and nil ; cases of :set-guard-checking, but not in the :all or :none cases. We get a ; guard violation for argument t in the case :set-guard-checking t. :u (defun fact (x) (declare (xargs :guard t :mode :program)) (if (posp x) (* x (fact (1- x))) 1)) ; Run the Tracing Code here. It should give the same results as above, ; except that we no longer get a guard violation in the case ; :set-guard-checking t. :u ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Logic mode, guard other than t ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun fact (x) (declare (xargs :guard (integerp x) :verify-guards nil :mode :logic)) (if (posp x) (* x (fact (1- x))) 1)) ; Run the Tracing Code here. It should give guard violations for (fact t) ; with guard-checking set to t or :all. It should never run in raw Lisp, ; because we have not verified guards. In the t case, we can get a warning ; about avoiding the guard check on recursive calls, but only if we do not ; trace the function, fact. (verify-guards fact) ; Run the Tracing Code here. The results should be as described just above, ; except that now we go into raw Lisp for (fact 2) with guard-checking other ; than :none. :u :u ; The following definition is the same as above, except that guards are ; verified. (defun fact (x) (declare (xargs :guard (integerp x) :mode :logic)) (if (posp x) (* x (fact (1- x))) 1)) ; Run the Tracing Code here. We should get the same traces as in the ; immediately preceding case, since guards had been verified in both cases. :u ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Logic mode, guard t ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun fact (x) (declare (xargs :guard t :verify-guards nil :mode :logic)) (if (posp x) (* x (fact (1- x))) 1)) ; Run the Tracing Code here. We should never go in to raw Lisp, because ; guards have not been verified. We will see the same traces for (fact 2) as ; with the (integerp x) guard above with :verify-guards nil specified, except ; that even without tracing, there is no warning for :set-guard-checking t ; about recursive calls. And, there are no guard violations for (fact t), of ; course, since posp (necessarily, if we are to verify guards) has a guard of ; t. (verify-guards fact) ; Run the Tracing Code here. You shouldn't see any surprises. Note however ; that if we back up to the start (using :u :u) and then define fact as just ; above but without :verify-guards nil, then the :none setting will allow us ; to go into raw Lisp: although :none generally avoids execution of raw Lisp ; counterparts, it allows this when the guard is T and guards have been ; verified.") (guard-evaluation-table (guard) "A table that shows combinations of [defun-mode]s and [guard]-checking See [set-guard-checking] for an introduction to the topic discussed here. Also see [guard] for a general discussion of guards, and see [guard-evaluation-examples-script] for a script that illustrates combinations presented below. Note: The default setting for guard-checking (that is, the initial value for [state] global [47m(@ guard-checking-on)[0m) is [47mT[0m. The table below illustrates the interaction of the [defun-mode] with the value supplied to [47m[set-guard-checking][0m. The first row considers functions defined in [47m:[0m[47m[program][0m mode; the other two consider functions defined in [47m:[0m[47m[logic][0m mode. The columns correspond to four values of state global [47m'guard-checking-on[0m, as supplied to [47m[set-guard-checking][0m. (A fifth value, [47m:nowarn[0m, is similar to [47mt[0m but suppresses warnings; a remark with details for system hackers is at the end of this topic.) Note that [47m'guard-checking-on[0m is set to [47mnil[0m during proofs but is set to [47mt[0m during [47m[certify-book][0m, and [47m[include-book][0m, regardless of how this variable has been set in the top-level loop (see the ``Essay on Guard Checking'' in source file [47mother-events.lisp[0m if you are interested in a rationale). Below this table, we make some comments about its entries, ordered by row and then by column. For example, when we refer to ``b2'' we are discussing the execution of a [47m:[0m[47m[logic][0m mode function whose guards have not been verified, after having executed [47m:[0m[47m[set-guard-checking][0m[47m :all[0m. guard-checking-on: (1)t (2):all (3):none (4)nil (a) :program a1 a2 a3 a4 (b) guards not verified b1 b2 b3 b4 (c) guards verified c1 c2 c3 c4 a1. Check the [guard] upon entry, then use the raw Lisp code if the guard checks (else cause an error). This is a common setting when one wants a little guard checking but also wants the efficiency of raw Lisp. But note that you can get raw Lisp errors. For example, if you make the definition [47m(defun foo (x) (car x))[0m in [47m:[0m[47m[program][0m mode and execute [47m:[0m[47m[set-guard-checking][0m[47m t[0m, and then execute [47m(foo 3)[0m, you will likely get an error from the call [47m(car 3)[0m made in raw Lisp. a2. For built-in (predefined) functions, see a1 instead. Otherwise: Check the [guard], without exception. Thus, we never run the raw Lisp code in this case. This can be useful when testing [47m:[0m[47m[program][0m mode functions, but you may want to run [47m:[0m[47m[comp][0m[47m t[0m or at least [47m:[0m[47m[comp][0m[47m :exec[0m in this case, so that the execution is done using compiled code. a3. For built-in (predefined) functions, see a4 instead. Otherwise: Do not check the [guard]. For [47m:[0m[47m[program][0m mode functions, we never run the raw Lisp code in this case; so if you care about efficiency, see the comment in a2 above about [47m:[0m[47m[comp][0m. This combination is useful if you are using ACL2 as a programming language and do not want to prove theorems about your functions or suffer [guard] violations. In this case, you can forget about any connection between ACL2 and Common Lisp. a4. Run the raw Lisp code without checking [guard]s at all. Thus, for [47m:[0m[47m[program][0m mode functions, the [47mnil[0m setting is often preferable to the [47m:none[0m setting because you get the efficiency of raw Lisp execution. However, with [47mnil[0m you can therefore get hard Lisp errors as in a1 above. b1. Guards are checked at the top-level, though not at self-recursive calls. We never run the raw Lisp code in this case; guards would need to be verified first. b2. Unlike the [47mt[0m setting, guards are checked even on self-recursive calls. But like the [47mt[0m setting, we do not run the raw Lisp code. Use this setting if you want guards checked on each recursive call in spite of the cost of doing so. b3, b4. Execution avoids the raw Lisp code and never checks guards. The [47mnil[0m and [47m:none[0m settings behave the same in this case (i.e., for [47m:[0m[47m[logic][0m mode functions whose guards have not been verified), except that recursive calls are never inlined for [47m:none[0m and tracing (see [trace]) will show recursive calls for [47m:none[0m but not for [47mnil[0m. c1, c2. Guards are checked. If the checks pass, evaluation takes place using the raw Lisp code. If the checks fail, we get a guard violation. Either way, we do not execute ``in the logic''; we only execute using the raw Lisp code. Note that [47mt[0m and [47m:all[0m behave the same in this case, (i.e. for [47m:[0m[47m[logic][0m mode functions whose [guard]s have been verified). c3, c4. For the [47m:none[0m and [47mnil[0m settings, [47m:[0m[47m[logic][0m mode functions whose guards have been verified will never cause guard violations. However, with [47mnil[0m and for built-in functions in [47m:logic[0m mode, guards are still checked: if the check succeeds, then evaluation is done using the raw Lisp code, and if not, it is done by the ``logic'' code, including self-recursive calls (though unlike the [47mt[0m case, we will not see a warning about this). But with [47m:none[0m for user-defined functions, no guard checking is done, and the only time the raw Lisp code will be executed is when the guard is [47mt[0m and guards are verified at the time the executable-counterpart of the function is defined (i.e., when the function is admitted unless it is later defined again and compiled using [47m:[0m[47m[comp][0m). Thus, if you use [47m:none[0m and you want a function [47m(foo x)[0m with guard [47m(g x)[0m to execute using raw Lisp code, you can write a ``wrapper''function with a guard of [47mt[0m: (defun foo-wrap (x) (declare (xargs :guard t)) (if (g x) (foo x) 'do-not-case)) If you want the speed of executing raw Lisp code and you have non-trivial guards on functions that you want to call at the top-level, use [47mnil[0m rather than [47m:none[0m. Remark for system hackers. As noted above, a fifth value, [47m:nowarn[0m, is similar to [47mt[0m but suppresses warnings. Only the four values in the column headers above and [47m:nowarn[0m are legal for [47m[set-guard-checking][0m, [47m[with-guard-checking][0m, [47m[with-guard-checking-error-triple][0m, and [47m[with-guard-checking-event][0m. Behavior is technically undefined if you set [state] global [47mguard-checking-on[0m directly to other than those five values, say using [47m[assign][0m, [47m[f-put-global][0m, or [47m[state-global-let*][0m. However, as of this writing (in August 2021), such a value will cause the same behavior as value [47m:nowarn[0m. End of Remark.") (guard-example (tutorial5-miscellaneous-examples guard) "A brief transcript illustrating [guard]s in ACL2 This note addresses the question: what is the use of [guard]s in ACL2? Although we recommend that beginners try to avoid [guard]s for a while, we hope that the summary here is reasonably self-contained and will provide a helpful introduction to guards in ACL2. For a more systematic discussion, see [guard]. For a summary of that topic, see [guard-quick-reference]. Before we get into the issue of [guard]s, let us note that there are two important ``modes'': [defun-mode] --- ``Does this [defun] add an axiom (`logic mode') or not (`:program mode')?'' (See [defun-mode].) Only [logic] mode functions can have their ``[guard]s verified'' via mechanized proof; see [verify-guards]. [47m[set-guard-checking][0m --- ``Should runtime [guard] violations signal an error ([47m:all[0m, and usually with [47mt[0m or [47m:nowarn[0m) or go undetected ([47mnil[0m, [47m:none[0m)? The question relates to the use of Common Lisp to evaluate expressions; see [set-guard-checking]. Examples of prompts Here are some examples of the relation between the ACL2 [prompt] and the ``modes'' discussed above. Also see [default-print-prompt]. The first examples all have [47m[ld-skip-proofsp][0m equal to [47mnil[0m; that is, proofs are [3mnot[0m skipped. ACL2 !> ; logic mode with guard checking on ACL2 > ; logic mode with guard checking off ACL2 p!> ; program mode with guard checking on ACL2 p> ; program mode with guard checking off Here are some examples with [47m[default-defun-mode][0m equal to [47m:logic[0m. ACL2 > ; guard checking off, ld-skip-proofsp nil ACL2 s> ; guard checking off, ld-skip-proofsp t ACL2 !> ; guard checking on, ld-skip-proofsp nil ACL2 !s> ; guard checking on, ld-skip-proofsp t Sample session ACL2 !>(+ 'abc 3) ACL2 Error [Evaluation] in TOP-LEVEL: The guard for the function call (BINARY-+ X Y), which is (AND (ACL2-NUMBERP X) (ACL2-NUMBERP Y)), is violated by the arguments in the call (BINARY-+ 'ABC 3). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !>:set-guard-checking nil [[.. output elided ..]] ACL2 >(+ 'abc 3) 3 ACL2 >(< 'abc 3) T ACL2 >(< 3 'abc) NIL ACL2 >(< -3 'abc) T ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(defun sum-list (x) (declare (xargs :guard (integer-listp x) :verify-guards nil)) (cond ((endp x) 0) (t (+ (car x) (sum-list (cdr x)))))) The admission of SUM-LIST is trivial, using the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). We observe that the type of SUM-LIST is described by the theorem (ACL2-NUMBERP (SUM-LIST X)). We used primitive type reasoning. Summary Form: ( DEFUN SUM-LIST ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.03) SUM-LIST ACL2 !>(sum-list '(1 2 3)) ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited for some recursive calls, including SUM-LIST; see :DOC guard-checking- inhibited. 6 ACL2 !>(sum-list '(1 2 abc 3)) ACL2 Error [Evaluation] in TOP-LEVEL: The guard for the function call (SUM-LIST X), which is (INTEGER-LISTP X), is violated by the arguments in the call (SUM-LIST '(1 2 ABC 3)). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !>:set-guard-checking nil [[.. output elided ..]] ACL2 >(sum-list '(1 2 abc 3)) 6 ACL2 >(defthm sum-list-append (equal (sum-list (append a b)) (+ (sum-list a) (sum-list b)))) *1 (the initial Goal, a key checkpoint) is pushed for proof by induction. Perhaps we can prove *1 by induction. Three induction schemes are suggested by this conjecture. Subsumption reduces that number to two. However, one of these is flawed and so we are left with one viable candidate. [[.. output elided ..]] *1 is COMPLETED! Thus key checkpoint Goal is COMPLETED! Q.E.D. Summary Form: ( DEFTHM SUM-LIST-APPEND ...) Rules: ((:DEFINITION BINARY-APPEND) (:DEFINITION ENDP) [[.. output elided ..]] (:TYPE-PRESCRIPTION SUM-LIST)) Time: 0.01 seconds (prove: 0.01, print: 0.00, other: 0.00) Prover steps counted: 470 SUM-LIST-APPEND Guard verification for functions See [declare], and [xargs], and [verify-guards] for related background, though we intend what follows to be self-explanatory. Declare Form Guards Verified? (declare (xargs :mode :program ...)) no (declare (xargs :guard g)) yes (declare (xargs :guard g :verify-guards nil)) no (declare (xargs ...<no :guard>...)) no ACL2 >:pe sum-list L 1 (DEFUN SUM-LIST (X) (DECLARE (XARGS :GUARD (INTEGER-LISTP X) :VERIFY-GUARDS NIL)) (COND ((ENDP X) 0) (T (+ (CAR X) (SUM-LIST (CDR X)))))) ACL2 >(verify-guards sum-list) Computing the guard conjecture for SUM-LIST.... The non-trivial part of the guard conjecture for SUM-LIST, given the [[.. output elided ..]] Q.E.D. That completes the proof of the guard theorem for SUM-LIST. SUM-LIST is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS SUM-LIST) Rules: ((:DEFINITION ENDP) [[.. output elided ..]] (:TYPE-PRESCRIPTION SUM-LIST)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Prover steps counted: 115 SUM-LIST ACL2 >:pe sum-list LV 1 (DEFUN SUM-LIST (X) (DECLARE (XARGS :GUARD (INTEGER-LISTP X) :VERIFY-GUARDS NIL)) (COND ((ENDP X) 0) (T (+ (CAR X) (SUM-LIST (CDR X)))))) ACL2 >:set-guard-checking t Turning guard checking on, value T. ACL2 !>(sum-list '(1 2 abc 3)) ACL2 Error [Evaluation] in TOP-LEVEL: The guard for the function call (SUM-LIST X), which is (INTEGER-LISTP X), is violated by the arguments in the call (SUM-LIST '(1 2 ABC 3)). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !>:set-guard-checking nil [[.. output elided ..]] ACL2 >(sum-list '(1 2 abc 3)) 6 ACL2 > We continue this demo by tracing [47msum-list[0m. (See [trace$].) The calls shown below of [47mACL2_*1*_ACL2::SUM-LIST[0m are calls of the logical version, or [3mexecutable-counterpart[0m, of [47msum-list[0m; also see [evaluation]. Note that the guard-checking value is still [47mnil[0m. So the logical version of [47msum-list[0m calls the Common Lisp [47msum-list[0m function when the [guard] of ``list of integers'' is true of its input, i.e., its input satisfies [47m[integer-listp][0m; but otherwise, evaluation continues using its executable-counterpart. ACL2 >(trace$ sum-list) ((SUM-LIST)) ACL2 >(sum-list '(1 2 abc 3)) 1> (ACL2_*1*_ACL2::SUM-LIST (1 2 ABC 3)) 2> (ACL2_*1*_ACL2::SUM-LIST (2 ABC 3)) 3> (ACL2_*1*_ACL2::SUM-LIST (ABC 3)) 4> (ACL2_*1*_ACL2::SUM-LIST (3)) 5> (SUM-LIST (3)) 6> (SUM-LIST NIL) <6 (SUM-LIST 0) <5 (SUM-LIST 3) <4 (ACL2_*1*_ACL2::SUM-LIST 3) <3 (ACL2_*1*_ACL2::SUM-LIST 3) <2 (ACL2_*1*_ACL2::SUM-LIST 5) <1 (ACL2_*1*_ACL2::SUM-LIST 6) 6 ACL2 > Guard verification for theorems For a theorem to be guard-verified, its statement should be executable without error in Common Lisp. The following is thus not guard-verifiable, since its evaluation can cause an error if [47mA[0m and [47mB[0m are not both lists of numbers. ACL2 >:pe sum-list-append 2 (DEFTHM SUM-LIST-APPEND (EQUAL (SUM-LIST (APPEND A B)) (+ (SUM-LIST A) (SUM-LIST B)))) ACL2 >(verify-guards sum-list-append) Computing the guard conjecture for SUM-LIST-APPEND.... The non-trivial part of the guard conjecture for SUM-LIST-APPEND, given the :type-prescription rule SUM-LIST, is Goal (AND (TRUE-LISTP A) (INTEGER-LISTP A) (INTEGER-LISTP (APPEND A B)) (INTEGER-LISTP B)). ******** FAILED ******** ACL2 > Perhaps surprisingly, a [47m[defthm][0m event with statement (implies (and (integer-listp a) (integer-listp b)) (equal (sum-list (append a b)) (+ (sum-list a) (sum-list b)))) is still not guard-verifiable. The reason is that [47m[implies][0m is a function, so its arguments are both always evaluated --- in particular, its second argument is evaluated even if its first argument evaluates to [47mnil[0m. Here is a way to fix that problem. ACL2 >(defthm common-lisp-sum-list-append (if (and (integer-listp a) (integer-listp b)) (equal (sum-list (append a b)) (+ (sum-list a) (sum-list b))) t) :rule-classes nil) Q.E.D. Summary Form: ( DEFTHM COMMON-LISP-SUM-LIST-APPEND ...) Rules: ((:REWRITE SUM-LIST-APPEND)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Prover steps counted: 23 COMMON-LISP-SUM-LIST-APPEND ACL2 >(verify-guards common-lisp-sum-list-append) Computing the guard conjecture for COMMON-LISP-SUM-LIST-APPEND.... The non-trivial part of the guard conjecture for COMMON-LISP-SUM-LIST-APPEND, given the :forward-chaining rules ACL2-NUMBER-LISTP-FORWARD-TO-TRUE-LISTP, INTEGER-LISTP-FORWARD-TO-RATIONAL-LISTP and RATIONAL-LISTP-FORWARD-TO-ACL2-NUMBER-LISTP and the :type-prescription rules ACL2-NUMBER-LISTP, INTEGER-LISTP, RATIONAL-LISTP and SUM-LIST, is Goal (IMPLIES (AND (INTEGER-LISTP A) (INTEGER-LISTP B)) (INTEGER-LISTP (APPEND A B))). [[.. output elided ..]] Q.E.D. That completes the proof of the guard theorem for COMMON-LISP-SUM-LIST-APPEND. COMMON-LISP-SUM-LIST-APPEND is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS COMMON-LISP-SUM-LIST-APPEND) Rules: ((:DEFINITION BINARY-APPEND) [[.. output elided ..]] (:TYPE-PRESCRIPTION SUM-LIST)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Prover steps counted: 565 COMMON-LISP-SUM-LIST-APPEND ACL2 > Guard verification fails when the theorem is for ``code'' that cannot even be parsed (or ``translated''; see [term]) as executable code. ACL2 >(defthm foo (consp (mv x y))) Q.E.D. The storage of FOO depends upon primitive type reasoning. Summary Form: ( DEFTHM FOO ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 >(verify-guards foo) ACL2 Error in ( VERIFY-GUARDS FOO): The guards for FOO cannot be verified because its formula has the wrong syntactic form for evaluation, perhaps due to multiple-value or stobj restrictions. See :DOC verify-guards. Summary Form: ( VERIFY-GUARDS FOO) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Error [Failure] in ( VERIFY-GUARDS FOO): See :DOC failure. ******** FAILED ******** ACL2 >") (guard-formula-utilities (guard) "Utilities that show guard proof obligations See [verify-guards] and see [guard] for discussions of guards. Here we discuss several utilities that provide the proof obligations for guards, and briefly compare what is offered by each. Of course, see the documentation of each utility for details. The first pair of utilities captures formulas produced during guard verification. [47m[Verify-guards-formula][0m: Use this to see what the corresponding [47m[verify-guards][0m event prints, but without following through with a proof attempt. This utility is only for output, without returning an interesting value. [47m[Guard-obligation][0m: This function is a programmatic version of the macro, [47m[verify-guards-formula][0m. It provides the guard obligation as a set of [clause]s, along with other information. The second pair of utilities captures the formula provided when a [47m:guard-theorem[0m is supplied for a [47m:use[0m hint. [47m[Gthm][0m: This macro returns a user-level (``untranslated'') representation of the [term] that is generated for a [47m:guard-theorem[0m [lemma-instance]. Options control whether or not simplification and [guard-debug] are used. [47m[Guard-theorem][0m: This utility is like [gthm], except that it is a function rather than a macro and it returns a translated term (a [47m[termp][0m). We conclude by contrasting these two pairs of utilities. * The first pair can take as input as either a function symbol or a term; for the second pair a function symbol (not a term) is required. * The level of simplification differs between the two pairs. See [guard-simplification] for a detailed explanation; here are highlights. The first pair simplifies (by default) with respect to the [current-theory] before producing the guard proof obligation formula, as is typically done when verifying guards; but the second pair only performs the theory-independent simplification done for a [47m:guard-theorem[0m specified in a [47m:use[0m hint, or if a suitable option is supplied, no simplification at all. * The two pairs differ in their output [signature]s: in particular, the utilities in the first pair return multiple values while those in the second pair return a single value. Subtopics [Gthm] The [guard] theorem for a given function symbol [Guard-obligation] The guard proof obligation [Guard-simplification] Levels of simplification for [guard] proof obligations [Guard-theorem] Use a previously-proved [guard] theorem [Guard-theorem-example] How to use a previously-proved [guard] theorem [Verify-guard-implication] [Guard] implication for [47m[memoize][0m keyword [47m:invoke[0m [Verify-guards-formula] View the guard proof obligation, without proving it") (guard-hints (pointers) "See [xargs] for information about the keyword [47m:guard-hints[0m.") (guard-holder (pointers) "See [guard-holders].") (guard-holders (rule-classes term guard) "Remove trivial calls from a [term] For many [rule-classes], the process of converting terms to rules includes the removal of certain trivial calls from the term. Such removal is performed in some other settings as well, including [hints] processing, generating proof obligations for [guard]s and termination, and the storing of induction schemes and [constraint]s. In all such cases, the resulting term is provably equivalent to the input term. A common example is to replace the term [47m(prog2$ term1 term2)[0m by the term [47mterm2[0m. But [47m(prog2$ term1 term2)[0m is really an abbreviation for (i.e., macroexpands to) the term [47m(return-last 'progn term1 term2)[0m; so a more accurate explanation, at the level of proper ACL2 [term]s, is that the call of function [47m[return-last][0m is replaced by its last argument. ACL2 identifies certain such transformations, from a term to a trivial simplification of it, such that the input and output are provably equal. We historically have referred to the process of making such replacements as ``removing guard holders.'' (For a discussion of the connection to guards, see the ``Essay on the Removal of Guard Holders'' in the ACL2 sources.) The process of removing guard-holders includes the transformations below. That process is also applied to each argument of a function call and to the bodies of [lambda] expressions (see [term]), usually including quoted lambda expressions that appear in an argument position with [ilk] [47m:FN[0m (see [apply$]). (return-last term0 term1 term2) ==> term2 (mv-list n term) ==> term (cons-with-hint x y) ==> (cons x y) (the-check guard x y) ==> y (from-df x) ==> x (to-df 'r) ==> 'r ; only when r satisfies dfp (df0) ==> 0 (df1) ==> 1 (do$ x1 x2 x3 x4 x5 'u1) ==> (do$ x1 x2 x3 x4 x5 'nil) ; only when u1 is non-nil ; For replacing a term (the type term) by term: ((lambda (y) (the-check guard x y)) val) ==> val ; For replacing equality aliases; for example, this transforms ; the macroexpansion of (member x y) to (member-equal x y): (('LAMBDA (f1 ... fk) ('RETURN-LAST ''MBE1-RAW exec logic)) a1 ... ak) ==> logic ; For other than measure theorems and induction schemes, remove lambda ; applications that are ``trivial'' in either of the following two senses. ; For replacing a term (let ((v term)) v) by term: (('LAMBDA (v) v) term) ==> term ; When each formal is equal to the corresponding actual: (('LAMBDA (f1 ... fk) body) f1 ... fk) ==> body Because of how [47m[mbe][0m and [47m[ec-call][0m are defined in terms of [47m[return-last][0m, the expressions [47m(mbe :logic l :exec e)[0m and [47m(ec-call (f t1 ... tk))[0m are effectively transformed by removing guard holders into [47ml[0m and [47m(f t1 ... tk)[0m, respectively. The final two classes of simplification above (removal of ``trivial'' lambda applications) may be removed by executing the following form, which is [47m[local][0m to an [47m[encapsulate][0m form and to [books]. (defattach-system remove-guard-holders-lamp constant-nil-function-arity-0) Here is how to restore the default behavior. (defattach-system remove-guard-holders-lamp constant-t-function-arity-0) Note that by default, guard-holders are not removed inside calls of [47m[hide][0m. You can however cause them to be removed inside such calls after all, as was the case through Version 8.2, as follows. (defattach-system ; generates (local (defattach ...)) remove-guard-holders-blocked-by-hide-p constant-nil-function-arity-0)") (guard-introduction (guard) "Introduction to [guard]s in ACL2 Most users can probably profit by avoiding dealing with guards most of the time. If they seem to get in the way, they can be ``turned off'' using the command [47m:[0m[47m[set-guard-checking][0m [47mnil[0m; for more about this, see [set-guard-checking]. For more about guards in general, see [guard]. The guard on a function symbol is a formula about the formals of the function. To see the guard on a function, use the keyword command [47m:[0m[47m[args][0m. See [args]. To specify the guard on a function at [47mdefun-time[0m, use the [47m:[0m[47m[guard][0m [47mxarg[0m (See [xargs]) or [47mtype[0m declarations (see [declare]). The latter may be preferable if you want the host Lisp compiler to use this information. Guards can be seen as having either of two roles: (a) they are a specification device allowing you to characterize the kinds of inputs a function ``should'' have, or (b) they are an efficiency device allowing logically defined functions to be executed directly in Common Lisp. Briefly: If the guards of a function definition are ``verified'' (see [verify-guards]), then the evaluation of a call of that function on arguments satisfying its guard will have the following property: All subsequent function calls during that evaluation will be on arguments satisfying the guard of the called function. The consequence of this fact for (a) is that your specification function is well-formed, in the sense that the values returned by this function on appropriate arguments only depend on the restrictions of the called functions to their intended domains. The consequence of this fact for (b) is that in the ACL2 system, when a function whose guards have been verified is called on arguments that satisfy its guard, then the raw lisp function defined by this function's [47m[defun][0m event is used to evaluate the call. Note however that even when the user-supplied [47m[defun][0m is not used, ACL2 uses a corresponding executable-counterpart function that generally performs, we expect, nearly as well as submitted function; see [evaluation] for relevant background on these two functions. See [comp] to see how [compilation] can speed up both kinds of execution. Let us turn next to the issue of the relationship between guards and evaluation. See [guards-and-evaluation].") (guard-miscellany (guard) "Miscellaneous remarks about guards The discussion of guards concludes here with a few miscellaneous remarks. (Presumably you found this documentation by following a link; see [guards-for-specification].) For further information related to guards other than what you find under ``[guard],'' see any of the following documentation topics: [guard-example], [47m[set-verify-guards-eagerness][0m, [47m[set-guard-checking][0m, [47m[verify-guards][0m, and (for a discussion of keyword [47m:split-types[0m) [47m[xargs][0m. [47m[Defun][0m can be made to try to verify the guards on a function. This is controlled by the ``[defun-mode]'' of the [47m[defun][0m; see [defun-mode]. The [defun-mode] is either as specified with the [47m:mode[0m [47mxarg[0m of the [47m[defun][0m or else defaults to the default [defun-mode]. See [default-defun-mode]. If the [defun-mode] of the [47m[defun][0m is [47m:[0m[47m[logic][0m and either a [guard] is specified explicitly or [47m:[0m[47m[verify-guards][0m [47mt[0m is specified in the [47m[xargs][0m, then we attempt to verify the guards of the function. Otherwise we do not. (But see [set-verify-guards-eagerness] for how to modify this behavior.) It is sometimes impossible for the system to verify the guards of a recursive function at definition time. For example, the guard conjectures might require the invention and proof of some inductively derived property of the function (as often happens when the value of a recursive call is fed to a guarded subroutine). So sometimes it is necessary to define the function using [47m:verify-guards nil[0m then to state and prove key theorems about the function, and only then have the system attempt guard verification. Post-[47m[defun][0m guard verification is achieved via the event [47m[verify-guards][0m. See [verify-guards]. It should be emphasized that guard verification affects only two things: how fast ACL2 can evaluate the function and whether the function is executed correctly by raw Common Lisp, without guard violations. Since ACL2 does not use the raw Common Lisp definition of a function to evaluate its calls unless that function's guards have been verified, the latter effect is felt only if you run functions in raw Common Lisp rather than via ACL2's command loop. Guard verification does not otherwise affect the theorem prover or the semantics of a definition. If you are not planning on running your function on ``big'' inputs and you don't care if your function runs correctly in raw Common Lisp (e.g., you have formalized some abstract mathematical property and just happened to use ACL2 as your language), there is no need to suffer through guard verification. Often users start by not doing guard verification and address that problem later. Sometimes you are driven to it, even in mathematical projects, because you find that you want to run your functions particularly fast or in raw Common Lisp. Finally, we note that ACL2 collects up [guard]s from [47m[declare][0m forms in order of appearance. So for example, the [47m[declare][0m form (declare (xargs :guard (foo x)) (type string x) will generate the guard [47m(and (foo x) (stringp x))[0m, while the form (declare (type string x) (xargs :guard (foo x)) will generate the guard [47m(and (stringp x) (foo x))[0m. The only exceptions to this rule are that all [47m:stobjs[0m and [47m:dfs[0m declarations will be treated as through they precede all [47m:guard[0m and [47mtype[0m declarations.") (guard-msg-table (pointers) "See [set-guard-msg].") (guard-obligation (guard-formula-utilities) "The guard proof obligation See [verify-guards], and see [guard] for a discussion of guards. [47mGuard-obligation[0m is a low-level function for use in system programs, not typically appropriate for most ACL2 users. A corresponding user-level utility is [verify-guards-formula]; also see [guard-formula-utilities] for related utilities. Example Forms: (guard-obligation 'foo nil t t 'top-level state) (guard-obligation '(if (consp x) (foo (car x)) t) nil nil t 'my-fn state) General Forms: (guard-obligation name rrp guard-debug guard-simplify ctx state) (guard-obligation term rrp guard-debug guard-simplify ctx state) where the first argument is either the name of a function or theorem or is a non-variable term that may be in untranslated form; [47mrrp[0m (``return redundant p'') is non-[47mnil[0m when it is permissible to return a value of [47m'redundant[0m in the first (name) case (and is irrelevant in the term case); [47mguard-debug[0m is typically [47mnil[0m but may be [47mt[0m (see [guard-debug]); [47mguard-simplify[0m is typically [47mt[0m but may be [47m:limited[0m (see [verify-guards]); [47mctx[0m is a context (typically, a symbol used in error and warning messages); and [47m[state][0m references the ACL2 [state]. If you want to obtain the formula but you don't care about the so-called ``tag tree'': (mv-let (erp val) (guard-obligation x nil guard-debug guard-simplify 'top-level state) (if erp ( .. code for handling error case, e.g., name is undefined .. ) (let ((cl-set (cadr val))) ; to be proved for guard verification ( .. code using cl-set, which is a list of clauses, implicitly conjoined, each of which is viewed as a disjunction .. )))) The form [47m(guard-obligation x rrp guard-debug guard-simplify ctx state)[0m evaluates to a pair [47m(mv erp val)[0m, where [47merp[0m is [47mnil[0m unless there is an error. (Actually, this is a context-message pair; see the source code's ``Essay on Context-message Pairs''for relevant information.) Suppose [47merp[0m is [47mnil[0m. Then [47mval[0m is the keyword [47m:redundant[0m if the corresponding [47m[verify-guards][0m event would be redundant and [47mrrp[0m is not [47mnil[0m; see [redundant-events]. Otherwise, [47mval[0m is a tuple [47m(list* names cl-set ttree)[0m, where: [47mnames[0m is [47m(cons :term xt)[0m if [47mx[0m is not a variable, where [47mxt[0m is the translated form of [47mx[0m; and otherwise is a list containing [47mx[0m along with, if [47mx[0m is defined in a [47mmutual-recursion[0m, any other functions defined in the same [47m[mutual-recursion][0m nest; [47mcl-set[0m is a list of lists of terms, viewed as a conjunction of [clause]s (each viewed (as a disjunction); and [47mttree[0m is an assumption-free tag-tree that justifies cl-set. (The notion of ``tag-tree'' may probably be ignored except for system developers.) [47mGuard-obligation[0m is typically used for function names or non-variable terms, but as for [47m[verify-guards][0m, it may also be applied to theorem names. See the source code for [47m[verify-guards-formula][0m for an example of how to use [47mguard-obligation[0m.") (guard-quick-reference (guard) "Brief summary of guard checking and guard verification For a careful introduction to guards, see [guard]. [31;1mI. GUARD CHECKING DURING EXECUTION[0m [3mEffect[0m Guards on definitions are checked at execution time (except for guards on subsidiary calls of recursive or mutually recursive functions). [3mWhen does it happen[0m By default, guards are checked for all forms submitted at the top level. [3mTo disable[0m [47m:set-guard-checking nil[0m ; skip raw Lisp if there is a guard violation [47m:set-guard-checking :none[0m ; skip guard checking entirely [3mTo (re-)enable[0m [47m:set-guard-checking t[0m See [set-guard-checking] for more options. [31;1mII. GUARD VERIFICATION[0m [3mEffect[0m A proof is attempted of the obligations arising from the guards of subsidiary functions in a [47m[defun][0m, [47m[defthm][0m, or [47m[defaxiom][0m event. In the case of a [47mdefun[0m, the guard itself is also verified (under an implicit guard of [47mt[0m). [3mWhen does it happen[0m Only names of defined functions, [47m[defthm][0ms, and [47m[defaxiom][0ms are subject to guard verification. Guard verification may occur when functions are defined (using [47m[defun][0m), but it requires an explicit call of [47m[verify-guards][0m in order to verify guards for [47m[defthm][0ms and [47m[defaxiom][0ms. Constrained functions (see [encapsulate]) may not have their guards verified. [47m(verify-guards foo ...)[0m causes guard verification for the [47m[defun][0m, [47m[defthm][0m, or [47m[defaxiom][0m named by [47mfoo[0m, if it has not already been successfully done. The default [defun-mode] (see [default-defun-mode]) must be [47m:[0m[47m[logic][0m, or else this event is ignored. [47m(defun foo ...)[0m causes guard verification of [47mfoo[0m if and only if the following two conditions are both met. First, foo is processed in [47m:[0m[47m[logic][0m mode (either by setting mode [47m:[0m[47m[logic][0m globally, or by including [47m:mode :logic[0m in the [47m[xargs][0m declaration). Second, at least one of the following sub-conditions is met. Also see [xargs], and see [set-verify-guards-eagerness] for how to change this behavior. 1. The [47m[xargs][0m declaration specifies a [47m:[0m[47m[guard][0m. 2. There is at least one [47mtype[0m declaration (see [declare]). 3. The [47m[xargs][0m declaration specifies [47m:[0m[47m[stobj][0m[47ms[0m. 4. The [47m[xargs][0m declaration specifies [47m:[0m[47m[verify-guards][0m [47mt[0m. [47m(verify-termination foo ...)[0m causes guard verification of [47mfoo[0m if [47mfoo[0m is a function currently defined in [47m:[0m[47m[program][0m mode and the criteria for guard verification of a [47m[defun][0m form are met, as discussed above. The default [defun-mode] (see [default-defun-mode]) must be [47m:[0m[47m[logic][0m, or else this event is ignored.") (guard-simplification (guard-formula-utilities) "Levels of simplification for [guard] proof obligations ACL2 provides several features for obtaining the proof obligations generated for [guard] verification. Each of these features can be invoked with an argument that controls the level of simplification to be applied before returning those proof obligations. This topic examines those simplification levels. It starts by splitting the features into two groups; then continues by explaining the three levels of simplification; and finally, makes the key point that one group allows the top two levels of simplification and the other group allows the bottom two levels. These features can be partitioned into two groups, which we reference below as the ``[31;1mAT[0m'' and ``[31;1mAFTER[0m'' groups, as follows. These correspond respectively to the two groups discussed in the documentation topic, [guard-formula-utilities], for capturing formulas produced either during guard verification or when a [47m:guard-theorem[0m is supplied for a [47m:use[0m hint. * Simplification [31;1mAT[0m guard-verification time: * the [47m[xargs][0m keyword [47m:guard-simplify[0m, * the [47m[guard-obligation][0m utility, and * the [47m[verify-guards-formula][0m utility. * Simplification [31;1mAFTER[0m guard-verification time: * the [47m:[0m[47m[gthm][0m utility, and * the [47m:[0m[47m[guard-theorem][0m [lemma-instance] (and related low-level utility, [47mguard-theorem[0m. Each feature above has an argument (possibly optional) that controls the level of simplification. Each such argument can take any of three values, as follows. But [31;1mNOTE[0m: [47mT[0m and [47m:LIMITED[0m are the only legal values for the ``AT'' (first) group, and [47m:LIMITED[0m and [47mNIL[0m are the only legal values for the ``AFTER'' (second) group. * [47mT[0m: Full simplification, which is the default behavior for [47m[verify-guards][0m * [47m:LIMITED[0m: Reduced simplification, skipping simplifications that depend on the set of currently [enable]d rules * [47mNIL[0m: No simplification The key point of this topic is the following specification of the values allowed for the simplification argument, for the features in each group. For features in the [31;1mAT[0m group, [47mT[0m and [47m:LIMITED[0m are the legal values. For features in the [31;1mAFTER[0m group, [47m:LIMITED[0m and [47mNIL[0m are the legal levels. Let's see why this is reasonable and discuss whether the missing value for each group might be allowed in the future. First consider the [31;1mAFTER[0m group. A [47m:[0m[47m[guard-theorem][0m [47m:use[0m hint obtains the [guard] theorem proved for a previously guard-verified function. The [47m[current-theory][0m at the time of that [47m:use[0m hint may be very different from what it was at guard-verification time. Thus, when processing that hint it would be misleading to allow the current [theory] to participate in simplification that produces the guard theorem, since the result could be very different from the guard theorem generated during the earlier guard verification. That is why the value [47mT[0m is not allowed for the simplification argument of a [47m:[0m[47m[guard-theorem][0m hint. Instead, the default is [47m:LIMITED[0m. The [47m[gthm][0m utility provides a way to show the formula that would be provided by a [47m:guard-theorem[0m lemma instance, so [47mgthm[0m also disallows [47mT[0m, and its default is also [47m:LIMITED[0m. Note that the utility [47m[verify-guards-formula][0m is more appropriate than [47mgthm[0m to view the formula to be proved if one is about to verify guards for a function. (If [47mgthm[0m were to be used for that purpose too, then [47mT[0m might be allowed as a simplification argument; but that could lead to confusion, in particular about the default.) Now consider the [31;1mAT[0m group, which relates to guard verification. [47mT[0m is a reasonable default: it is generally useful to maximize simplification while generating the guard theorem before attempting its proof. But one may prefer more control, by avoiding simplification until the proof is attempted. [47m:LIMITED[0m has proved to be a good compromise: it limits simplification to basic operations, in particular avoiding goals that are subsumed by other goals or are instances of trivial [built-in-clause] rules. If the need arises to support [47mNIL[0m as a simplification value, perhaps ACL2 will change to support that.") (guard-theorem (lemma-instance guard-formula-utilities hints) "Use a previously-proved [guard] theorem See [lemma-instance] for a discussion of [47m:guard-theorem[0m lemma instances, as illustrated in the topic [guard-theorem-example]. The function [47mguard-theorem[0m is a low-level system utility that returns a translated [term]. It is essentially the functional version of the [47mgthm[0m macro, which however returns an untranslated term. See [gthm]. Subtopics [Guard-theorem-example] How to use a previously-proved [guard] theorem") (guard-theorem-example (lemma-instance guard hints guard-theorem guard-formula-utilities) "How to use a previously-proved [guard] theorem See [lemma-instance] for a discussion of [47m:guard-theorem[0m lemma instances, and see [gthm] for a related user-level query utility. In this topic, we illustrate the use of such lemma instances to take advantage of a [guard] theorem already proved for an existing definition, when attempting to admit a new definition. The following example is contrived but should get the idea across. Suppose that the event displayed just below was previously executed, for example when including a book. The [47m[mbe][0m call generates a guard proof obligation, but there is only one thing to know about that for this example: without the local lemma shown, the guard proof fails for [47mf1[0m. (encapsulate () (local (defthm append-revappend (equal (append (revappend x y) z) (revappend x (append y z))))) (defun f1 (x y) (declare (xargs :guard (and (true-listp x) (true-listp y)))) (mbe :logic (append (reverse x) y) :exec (revappend x y)))) Now suppose that later, we wish to admit a function with the same guard and body. Since the lemma [47mappend-revappend[0m above is [local], guard verification will likely fail. However, we can tell the prover to use the guard theorem already proved for [47mf1[0m, as follows; then the guard verification proof succeeds. (defun f2 (x y) (declare (xargs :guard (and (true-listp x) (true-listp y)) :guard-hints (("Goal" :use ((:guard-theorem f1)))))) (mbe :logic (append (reverse x) y) :exec (revappend x y))) See [termination-theorem-example] for an example use of the analogous lemma instance type, [47m:termination-theorem[0m. That topic also includes discussion of the use of event names in prover output.") (guards (pointers) "See [guard].") (guards-and-evaluation (guard) "The relationship between guards and evaluation For relevant background see [evaluation]. The guard has no effect on the logical axiom added by the definition of a function. It does, however, have consequences for how calls of that function are evaluated in ACL2. We begin by explaining those consequences, when ACL2 is in its default ``mode,'' i.e., as originally brought up. In subsequent discussion we'll consider other ways that guards can interact with evaluation. For more about guards in general, see [guard]. For in-depth discussion of the interaction between the [defun-mode] and guard checking, see [set-guard-checking], see [guard-evaluation-table], see [guard-evaluation-examples-script], and see [guard-evaluation-examples-log]. Also see [generalized-booleans] for discussion about a subtle issue in the evaluation of certain Common Lisp functions. [3mGuards and evaluation I: the default[0m Consider the following very simple definition. (defun foo (x) (cons 1 (cdr x))) First consider how raw Common Lisp behaves when evaluating calls of this function. To evaluate [47m(foo x)[0m for some expression [47mx[0m, first [47mx[0m is evaluated to some value [47mv[0m, and then [47m(cons 1 (cdr x))[0m is evaluated with [47mx[0m bound to [47mv[0m. For example, if [47mv[0m is [47m(cons 'a 3)[0m, then Common Lisp computes [47m(cons 1 3)[0m. But if (for example) [47mv[0m is a number, e.g., [47m7[0m, then there is no way to predict what Common Lisp might do. Some implementations would cause ``sensible'' errors, others might return nonsense, still others might crash the host machine. The results tend toward the catastrophic if the call of [47mfoo[0m in question is in compiled code. Now by default, ACL2 evaluates calls of [47mfoo[0m exactly as Common Lisp does, except that it uses guards to check the ``legality'' of each function call. So for example, since [47m(cdr x)[0m has a guard of [47m(or (consp x) (equal x nil))[0m, the call [47m(foo 7)[0m would cause a ``guard violation,'' as illustrated below. ACL2 !>(foo 7) ACL2 Error in TOP-LEVEL: The guard for the function symbol CDR, which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CDR 7). ACL2 !> Thus, the relation between evaluation in ACL2 and evaluation in Common Lisp is that the two produce the very same results, provided there is no guard violation. [3mGuards and evaluation II:[0m [47m:[0m[47m[set-guard-checking][0m. The ACL2 logic is a logic of total functions. That is, every application of a function defined has a completely specified result. See the [documentation] for each individual primitive for the specification of what it returns when its guard is violated; for example, see [cdr]. The presence of guards thus introduces a choice in the sense of evaluation. When you type a form for evaluation do you mean for guards to be checked or not? Put another way, do you mean for the form to be evaluated in Common Lisp (if possible) or in the ACL2 logic? Note: If Common Lisp delivers an answer, it will be the same as in the logic, but it might be erroneous to execute the form in Common Lisp. For example, the ACL2 logic definition of [47m[cdr][0m implies that the [47m[cdr][0m of an [atom] is [47mnil[0m; see [cdr]. So: should [47m(cdr 7)[0m cause a guard violation error or return [47mnil[0m? The top-level ACL2 loop has a variable which controls which sense of execution is provided. By default, ``guard checking'' is on, by which we mean that guards are checked at runtime, in the sense already described. To allow execution to proceed in the logic when there is a guard violation, do [47m:[0m[47m[set-guard-checking][0m[47m nil[0m; or evaluate [47m:[0m[47m[set-guard-checking][0m[47m :none[0m to skip guard checking entirely. To turn ``guard checking'' back on, execute the top-level form [47m:[0m[47m[set-guard-checking][0m[47m t[0m. The status of guard checking reflected in the [prompt]; guard-checking is ``on'' when the [prompt] contains an exclamation mark (also see [default-print-prompt]). For example, ACL2 !> means guard checking is on and ACL2 > means guard checking is off. The exclamation mark can be thought of as ``barring'' certain computations. The absence of the mark suggests the absence of error messages or unbarred access to the logical axioms. Thus, for example ACL2 !>(car 'abc) will signal an error, while ACL2 >(car 'abc) will return [47mnil[0m. To return to our previous example: with guard checking off, [47m(foo 7)[0m evaluates to [47m(cons 1 nil)[0m. Also see [set-guard-checking]. [3mGuards and evaluation III: guard verification[0m Consider the definition of [47mfoo[0m given above, but modified so that a reasonable guard of [47m(consp x)[0m is specified, as shown below. (defun foo (x) (declare (xargs :guard (consp x))) (cons 1 (cdr x))) We say ``reasonable guard'' above because if [47mx[0m is such that [47m(consp x)[0m holds, then the call of [47m[cdr][0m in the evaluation of [47m(foo x)[0m will not cause a guard violation. Thus, it ``should'' be legal to evaluate [47m(foo x)[0m, for any such [47mx[0m, simply by evaluating this form in raw Common Lisp. The [47m[verify-guards][0m event has been provided for this purpose. Details may be found elsewhere; see [verify-guards]. Briefly, for any defined function [47mfn[0m, the event [47m(verify-guards fn)[0m attempts to check the condition discussed above, that whenever [47mfn[0m is called on arguments that satisfy its guard, the evaluation of this call will proceed without any guard violation. (Moreover, the guard itself should be evaluable without any guard violation.) If this check is successful, then future calls of this sort will be evaluated in raw Common Lisp. Returning to our example above, the [47m(verify-guards foo)[0m will succeed because the guard [47m(consp x)[0m of [47mfoo[0m implies the guard generated from the call [47m(cdr x)[0m in the body of the definition, namely, [47m(or (consp x) (equal x nil))[0m (see [cdr]). Then the evaluation of [47m(foo (cons 'a 3))[0m will take place in raw Common Lisp, because [47m(cons 'a 3)[0m satisfies the guard of [47mfoo[0m. This ability to dive into raw Common Lisp hinges on the proof that the guards you attach to your own functions are sufficient to ensure that the guards encountered in the body are satisfied. This is called ``guard verification.'' Once a function has had its guards verified, then ACL2 can evaluate the function somewhat faster (but see ``Guards and evaluation V: efficiency issues'' below). Perhaps more importantly, ACL2 can also guarantee that the function will be evaluated correctly by any implementation of Common Lisp (provided the guard of the function is satisfied on the input). That is, if you have verified the guards of a system of functions and you have determined that they work as you wish in your host ACL2 (perhaps by proving it, perhaps by testing), then they will work identically in any Common Lisp. There is a subtlety to our treatment of evaluation of calls of functions whose guards have been verified. If the function's guard is not satisfied by such a call, then no further attempt is made to evaluate any call of that function in raw lisp during the course of evaluation of that call. This is obvious if guard checking is on, because an error is signaled the first time its guard is violated; but in fact it is also true when guard checking is off. See [guard-example] for an example. [3mGuards and evaluation IV: functions having :program mode[0m Strictly speaking, functions in [47m:[0m[47m[program][0m mode (see [defun-mode]) do not have definitions in the ACL2 logic. So what does it mean to evaluate calls of such functions in ACL2? In general we treat [47m:[0m[47m[program][0m functions much as we treat [47m:[0m[47m[logic][0m functions whose guards have been verified, except that when no error occurs then the corresponding raw Lisp function is always called. (We say ``in general'' because there are exceptions, discussed in the ``Aside'' just below.) Note that when the guard of a function in [47m:[0m[47m[logic][0m mode is violated, there is still a value that the ACL2 logic proves is equal to the given call. But the same cannot be said for a function in [47m:[0m[47m[program][0m mode. Nevertheless, for the sake of convenience we go ahead and evaluate the corresponding raw Lisp function except in the situation where the guard is violated and guard-checking is on, aside from the following: [31;1mAside[0m. There are exceptions to the use of raw Lisp, discussed just above, to evaluate calls of [47m:[0m[47m[program][0m mode functions. The primary one is that after [47m:[0m[47m[set-guard-checking][0m[47m :none[0m, evaluation of user-defined [47m:[0m[47m[program][0m mode function calls is done in the ACL2 logic, not in raw Lisp. The more obscure exception is that during expansion of macros and [47m[make-event][0m forms, and during evaluation of [47m[defconst][0m forms, ACL2 enters a ``safe mode'' in which this escape to raw Lisp is prevented. The following example illustrates how the user can experiment directly with safe mode, though it is preferred to use [47m:[0m[47m[set-guard-checking][0m[47m :none[0m if you are happy to skip all guard checking and evaluate forms in the logic. ACL2 !>(defun foo (x) (declare (xargs :mode :program :guard t)) (car x)) Summary Form: ( DEFUN FOO ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !>(foo 3) Error: Attempt to take the car of 3 which is not listp. [condition type: SIMPLE-ERROR] Restart actions (select using :continue): 0: Return to Top Level (an "abort" restart). 1: Abort entirely from this process. [1] ACL2(2): :pop ACL2 !>(assign safe-mode t) T ACL2 !>(foo 3) ACL2 Error in TOP-LEVEL: The guard for the function symbol CAR, which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CAR 3). See :DOC trace for a useful debugging utility. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !>(assign safe-mode nil) NIL ACL2 !>(foo 3) Error: Attempt to take the car of 3 which is not listp. [condition type: SIMPLE-ERROR] Restart actions (select using :continue): 0: Return to Top Level (an "abort" restart). 1: Abort entirely from this process. [1] ACL2(2): The other exception occurs after [47m[set-guard-checking][0m can be called with a value of [47m:all[0m; see [set-guard-checking]. [31;1mEnd of aside.[0m Thus, as with [47m:[0m[47m[logic][0m functions: when a guard has been satisfied on a call of a function with [47m:[0m[47m[program][0m mode, no subsidiary guard checking will be done. Notice that by treating functions in [47m:[0m[47m[program][0m mode like functions whose guards have been verified, we are using raw lisp to compute their values when their guards are met. We do not check guards any further once raw lisp is invoked. This can lead to hard lisp errors if the guards are not appropriate, as illustrated below. ACL2 >:program ACL2 p>(defun foo (x) (declare (xargs :guard t)) (cons 1 (cdr x))) Summary Form: ( DEFUN FOO ...) Rules: NIL Warnings: None Time: 0.02 seconds (prove: 0.00, print: 0.00, proof tree: 0.00, other: 0.02) FOO ACL2 p>(foo 3) Error: 3 is not of type LIST. Fast links are on: do (use-fast-links nil) for debugging Error signalled by CDR. Broken at COND. Type :H for Help. ACL2>> See [defun-mode-caveat]. However, here is a way to get ACL2 to do run-time guard checking for user-defined [47m:[0m[47m[program][0m mode functions. With this method, ACL2 will evaluate calls of user-defined [47m:program[0m mode functions in a manner that follows their ACL2 definitions. Simply execute the following in the ACL2 loop to put ACL2 into a ``safe mode.'' (f-put-global 'safe-mode t state) Let us revisit the example above, using safe mode. Notice that the guard of [47m[cdr][0m is now being checked, because the executable-counterpart of [47mfoo[0m is being called even though the [guard] is [47mt[0m. ACL2 !>(f-put-global 'safe-mode t state) <state> ACL2 !>:program ACL2 p!>(defun foo (x) (declare (xargs :guard t)) (cons 1 (cdr x))) Summary Form: ( DEFUN FOO ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 p!>(foo 3) ACL2 Error in TOP-LEVEL: The guard for the function symbol CDR, which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CDR 3). See :DOC trace for a useful debugging utility. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 p!> If we go back into ``unsafe'' mode, then we once again see a raw Lisp error, as we now illustrate. ACL2 p!>(f-put-global 'safe-mode nil state) <state> ACL2 p!>(foo 3) Error: 3 is not of type LIST. Fast links are on: do (si::use-fast-links nil) for debugging Error signalled by CDR. Broken at COND. Type :H for Help. ACL2>> [3mGuards and evaluation V: efficiency issues[0m We have seen that by verifying the guards for a [47m:[0m[47m[logic][0m function, we arrange that raw lisp is used for evaluation of calls of such functions when the arguments satisfy its guard. This has several apparent advantages over the checking of guards as we go. First, the savings is magnified as your system of functions gets deeper: the guard is checked upon the top-level entry to your system and then raw Common Lisp does all the computing. Second, if the raw Common Lisp is compiled (see [compilation]), enormous speed-ups are possible. Third, if your Common Lisp or its compiler does such optimizations as [47mtail-recursion[0m removal, raw Common Lisp may be able to compute your functions on input much ``bigger'' than ACL2 can. The first of these advantages is quite important if you have complicated guards. However, the other two advantages are probably not very important, as we now explain. When a function is defined in [47m:[0m[47m[logic][0m mode, its [47m[defun][0m is executed in raw Common Lisp; we call this the ``submitted'' definition of the function. However, a corresponding executable-counterpart also executed. (See [evaluation] for an introduction to submitted and executable-counterpart definitions.) The executable-counterpart is a [47m[defun][0m in raw lisp that checks guards at runtime and escapes to the submitted definition if the guard holds of the arguments and the function has already had its guards verified. Otherwise the executable-counterpart evaluates the body of the function by calling the executable-counterpart of each subroutine. Now it is true that [compilation] often speeds up execution significantly. However, the [47m:[0m[47m[comp][0m command (see [comp]) compiles both of the raw lisp definitions associated with a function. Also, we have attempted to arrange that for every tail recursion removal done on the actual [47m[defun][0m, a corresponding tail recursion removal is done on the executable-counterpart definition. We believe that in most cases, the executable-counterpart executes almost as fast as the submitted definition, at least if the evaluation of the guards is fast. So, the main advantage of guard verification is probably that it lets you know that the submitted function may be executed safely in raw lisp, returning the value predicted by the ACL2 logic, whenever its arguments satisfy its guard. We envision the development of systems of applicative lisp functions that have been developed and reasoned about using ACL2 but which are intended for evaluation in raw Common Lisp (perhaps with only a small ``core'' of ACL2 loaded), so this advantage of guard verification is important. Nevertheless, guard verification might be important for optimal efficiency when the functions make use of type declarations. For example, at this writing, the GCL implementation of Common Lisp can often take great advantage of [47m[declare][0m forms that assign small integer types to formal parameters. Note that while type declarations contributed to the guard by default, they can be proved from the guard instead; see [xargs] for a discussion of the [47m:split-types[0m keyword. To continue the discussion of guards, see [guards-for-specification] to read about the use of guards as a specification device.") (guards-for-specification (guard) "Guards as a specification device A use of guard verification that has nothing to do with efficiency is as a way to gain confidence in specifications. This use has the feel of ``types'' in many traditional [programming] languages, though guards allow much greater expressiveness than most systems of types (and unfortunately, as a result they are not syntactically checkable). For more discussion of guards in general, see [guard]. Suppose you have written a collection of function definitions that are intended to specify the behavior of some system. Perhaps certain functions are only intended to be called on certain sorts of inputs, so you attach guards to those functions in order to ``enforce'' that requirement. And then, you verify the guards for all those functions. Then what have you gained, other than somewhat increased efficiency of execution (as explained above), which quite possibly isn't your main concern? You have gained the confidence that when evaluating any call of a (specification) function whose arguments satisfy that function's guard, all subsequent function calls during the course of evaluation will have this same property, that the arguments satisfy the guard of the calling function. The rest of this topic addresses those who wish to understand [guard]s from a proof-theoretic perspective instead of (or in addition to) the evaluation perspective given above. In logical terms, we can say that the equality of the original call with the returned value is provable from weakened versions of the definitions, where each definitional axiom is replaced by an implication whose antecedent is the requirement that the arguments satisfy the guard and whose consequent is the original axiom. For example, (defun foo (x) (declare (xargs :guard (consp x))) (cons 1 (cdr x))) originally generates the axiom (equal (foo x) (cons 1 (cdr x))) but in fact, when evaluation involves no guard violation then the following weaker axiom suffices in the justification of the evaluation. (implies (consp x) (equal (foo x) (cons 1 (cdr x)))) So for example, suppose we evaluate [47m(foo '(a b c))[0m and get [47m'(1 b c)[0m. Then of course the equality of these two terms is provable from the original axiom. The point here is that it's even provable from the weaker axiom. If you are following links to read this documentation as a hypertext style document, then please see [guard-miscellany]. This concludes our discussion of guards with miscellaneous remarks, and also contains pointers to related topics.") (guards_in_acl2 (pages_written_especially_for_the_tours) "Guards Common Lisp functions are partial; they are not defined for all possible inputs. But ACL2 functions are total. Roughly speaking, the logical function of a given name in ACL2 is a [31;1mcompletion[0m of the Common Lisp function of the same name obtained by adding some arbitrary but ``natural'' values on arguments outside the ``intended domain'' of the Common Lisp function. ACL2 requires that every ACL2 function symbol have a ``guard,'' which may be thought of as a predicate on the formals of the function describing the intended domain. The guard on the primitive function [47m[car][0m {ICON} (see [A_Tiny_Warning_Sign]), for example, is [47m(or (consp x) (equal x nil))[0m, which requires the argument to be either an ordered pair or [47mnil[0m. We will discuss later how to specify a guard for a defined function; when one is not specified, the guard is [47mt[0m which is just to say all arguments are allowed. [31;1mBut guards are entirely extra-logical[0m: they are not involved in the axioms defining functions. If you put a guard on a defined function, the defining axiom added to the logic defines the function on [31;1mall[0m arguments, not just on the guarded domain. So what is the purpose of guards? The key to the utility of guards is that we provide a mechanism, called ``guard verification,'' for checking that all the guards in a formula are true. See [verify-guards]. This mechanism will attempt to prove that all the guards encountered in the evaluation of a guarded function are true every time they are encountered. For a thorough discussion of guards, see the paper [km97] in the ACL2 [bibliography].") (guessing_the_type_of_a_newly_admitted_function (pages_written_especially_for_the_tours) "Guessing the Type of a Newly Admitted Function When a function is admitted to the logic, ACL2 tries to ``guess'' what type of object it returns. This guess is codified as a term that expresses a property of the value of the function. For [47mapp[0m the term is (OR (CONSP (APP X Y)) (EQUAL (APP X Y) Y)) which says that [47mapp[0m returns either a cons or its second argument. This formula is added to ACL2's rule base as a [47m[type-prescription][0m {ICON} (see [A_Tiny_Warning_Sign]) rule. Later we will discuss how rules are used by the ACL2 theorem prover. The point here is just that when you add a definition, the database of rules is updated, not just by the addition of the definitional axiom, but by several new rules. You should now return to the Walking Tour (see [Revisiting_the_Admission_of_App]).") (guiding_the_acl2_theorem_prover (pages_written_especially_for_the_tours) "Guiding the ACL2 Theorem Prover {IMAGE} (see [ACL2_as_an_Interactive_Theorem_Prover_{cont}]) Now that you have seen the theorem prover in action you might be curious as to how you guide it. {IMAGE} Look at the picture above. It is meant to suggest that [3mQ[0m is an important lemma needed for the proof of [3mP[0m. Note that to lead the prover to the proof of [3mP[0m the user first proves [3mQ[0m. In a way, the formulation and proof of [3mQ[0m is a hint to the prover about how to prove [3mP[0m. The user usually doesn't think of [3mQ[0m or recognize the need to prove it separately until he or she sees the theorem prover [31;1mfail[0m to prove [3mP[0m without it ``knowing'' [3mQ[0m. The way the user typically discovers the need for [3mQ[0m is to look at failed proofs. {IMAGE} (see [ACL2_as_an_Interactive_Theorem_Prover_{cont}])") (hands-off (pointers) "See [hints] for information about the keyword [47m:hands-off[0m.") (hands-off-lambda-objects-theory (theories theory-functions rewrite) "how to specify no modification of lambda objects The enabled status of two [47mrewrite-lambda-modep[0m runes are used as flags to determine the action taken when eligible [47mlambda[0m objects are encountered by the ACL2 rewriter. See [rewrite-lambda-object] and [47m[rewrite-lambda-object-actions][0m. To prevent the rewriter even considering changing a quoted [47mlambda[0m object, the rune [47m(:executable-counterpart rewrite-lambda-modep)[0m must be disabled in the then-current theory. The 0-ary function [47mhands-off-lambda-objects-theory[0m returns such a theory. In fact, diving into eligible quoted [47mlambda[0m object constants to rewrite the body is the default action when ACL2 starts up. See [rewriting-versus-cleaning-up-lambda-objects] for why you might want to change the default action when eligible [47mlambda[0m objects are encountered by the rewriter. The expression [47m(hands-off-lambda-objects-theory)[0m macroexpands to the theory expression (e/d nil ((:executable-counterpart rewrite-lambda-modep))) which is a theory equal to the current theory except that the executable-counterpart rune of [47mrewrite-lambda-modep[0m is disabled. This expansion is suitable for use in an [47m[in-theory][0m event or [47m:in-theory[0m hint (see [47m:[0m[47m[hints][0m). This rune is initially enabled, so eligible [47mlambda[0m object bodies are either rewritten or syntactically cleaned by default (depending on the status of [47m(:definition rewrite-lambda-modep)[0m) until and unless some event (e.g., an [47m[in-theory][0m or [47m[include-book][0m) or a superior local subgoal hint changes the status of this rune. For example, if [47mlambda[0m object rewriting is active and you wish it not to be (so that [47mlambda[0m objects remain unchanged) in [47mSubgoal 3[0m of some proof, you could use the [47m:[0m[47m[hints][0m ("Subgoal 3" :in-theory (hands-off-lambda-objects-theory)) Note that if you also wish to enable or disable other runes in the same subgoal you must construct an appropriate theory. For example, if in [47mSubgoal 3[0m of some proof you wanted to enable [47mLEMMA1[0m and disable [47mLEMMA2[0m in a theory that will also specify syntactic cleaning of [47mlambda[0m objects, you might write ("Subgoal 3" :in-theory (set-difference-theories (union-theories (hands-off-lambda-objects-theory) '(LEMMA1)) '(LEMMA2))) Some users might prefer ("Subgoal 3" :in-theory (e/d (LEMMA1) ((:executable-counterpart rewrite-lambda-modep) LEMMA2))) See [theories] for general information about theories and how to create and use them.") (hard-error (errors acl2-built-ins) "Print an error message and stop execution [47m(Hard-error ctx str alist)[0m causes evaluation to halt with a short message using the ``context'' [47mctx[0m. An error message is first printed using the string [47mstr[0m and alist [47malist[0m that are of the same kind as expected by [47m[fmt][0m. See [fmt]. Also see [er] for a macro that provides a unified way of signaling errors. [47mHard-error[0m has a guard of [47mt[0m. Also see [illegal] for a similar capability which however has a guard of [47mnil[0m that supports static checking using [47m[guard][0m verification, rather than using dynamic (run-time) checking. This distinction is illustrated elsewhere: see [prog2$] for examples. Semantically, [47mhard-error[0m ignores its arguments and always returns [47mnil[0m. But if a call [47m(hard-error ctx str alist)[0m is encountered during evaluation, then the string [47mstr[0m is printed using the association list [47malist[0m (as in [47m[fmt][0m), after which evaluation halts immediately. Here is a trivial, contrived example. ACL2 !>(cons 3 (hard-error 'my-context "Printing 4: ~n0" (list (cons #\0 4)))) HARD ACL2 ERROR in MY-CONTEXT: Printing 4: four ACL2 Error in TOP-LEVEL: Evaluation aborted. ACL2 !> Technical note for raw Lisp programmers only. It is possible to cause hard errors to signal actual raw Lisp errors, simply by evaluating the following form in raw Lisp: [47m(setq *hard-error-is-error* t)[0m. Indeed, any non-[47mnil[0m value for [47m*hard-error-is-error*[0m will cause [47mhard-error[0m or [47m[illegal][0m --- or indeed [47m(er hard ...)[0m, [47m(er hard! ...)[0m, or [47m(er hard? ...)[0m --- to produce a Lisp error whose condition, when printed with [47mformat[0m directive [47m~a[0m, is the same error message that ACL2 would otherwise print. Below is a sample log, closely based on an example provided by Jared Davis. ACL2 !>(defun f (x) (er hard 'f "F got bad input ~x0.~%" x)) Since F is non-recursive, its admission is trivial. We observe that the type of F is described by the theorem (EQUAL (F X) NIL). We used the :type-prescription rule ILLEGAL. Summary Form: ( DEFUN F ...) Rules: ((:TYPE-PRESCRIPTION ILLEGAL)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) F ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (defun run-f () (let ((*hard-error-is-error* t)) (handler-case (f 3) (error (condition) (format t "Got the following error: ~a~%" condition))))) RUN-F ? (run-f) Got the following error: HARD ACL2 ERROR in F: F got bad input 3. NIL ? Note that when a raw Lisp error occurs because [47m*hard-error-is-error*[0m is non-[47mnil[0m, the error message will not use [iprinting]. The reason is that the implementation does not make values of iprint indices available after the message is printed; so it would be misleading or an error to read [47m#@i#[0m after that return. [31;1mFunction: [0m<hard-error> (defun hard-error (ctx str alist) (declare (xargs :guard t)) (declare (ignore ctx str alist)) nil)") (hash-tables (pointers) "See [defstobj].") (header (arrays acl2-built-ins) "Return the header of a 1- or 2-dimensional array Example Form: (header 'delta1 a) General Form: (header name alist) where [47mname[0m is arbitrary and [47malist[0m is a 1- or 2-dimensional array. This function returns the header of the array [47malist[0m. The function operates in virtually constant time if [47malist[0m is the semantic value of [47mname[0m. See [arrays]. [31;1mFunction: [0m<header> (defun header (name l) (declare (xargs :guard (or (array1p name l) (array2p name l)))) (prog2$ name (assoc-eq :header l)))") (heavy-linear-p (linear-arithmetic system-attachments) "Extend the use of [linear-arithmetic] during rewriting This topic concerns an advanced control for the ACL2 prover. This zero-ary attachable system function supports extending the usual use of [linear-arithmetic] during rewriting, specifically with the test (first) argument of a call of [47mIF[0m. To get this additional power, possibly at considerable loss of efficiency, evaluate [47m(defattach-system heavy-linear-p constant-t-function-arity-0)[0m. To restore the default behavior, evaluate [47m(defattach-system heavy-linear-p constant-nil-function-arity-0)[0m.") (|HEY_WAIT!__IS_ACL2_TYPED_OR_UNTYPED{Q}| (pages_written_especially_for_the_tours) "Hey Wait! Is ACL2 Typed or Untyped? The example ACL2 !>[31;1m(app 7 27)[0m ACL2 Error in TOP-LEVEL: The guard for the function symbol ENDP, which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (ENDP 7). illustrates the fact that while ACL2 is an untyped language the ACL2 evaluator can be configured so as to check ``types'' at runtime. We should not say ``types'' here but ``guards.'' See [Guards_in_ACL2] for a discussion of guards. The guard on [47m[endp][0m {ICON} (see [A_Tiny_Warning_Sign]) requires its argument to be a true list. Since 7 is not a true list, and since ACL2 is checking guards in this example, an error is signaled by ACL2. How do you know ACL2 is checking guards? Because the prompt tells us (click here (see [About_the_Prompt])) with its ``!''.") (hidden-death-package (packages defpkg) "Handling [47m[defpkg][0m [events] that are [47m[local][0m This documentation topic explains a little bit about certain errors users may see when attempting to evaluate a [47m[defpkg][0m event. In brief, if you see an error that refers you to this topic, you are probably trying to admit a [47m[defpkg][0m event, and you should change the name of the package to be introduced by that event. Recall that [47mdefpkg[0m events introduce axioms, for example as follows. ACL2 !>(defpkg "PKG0" '(a b)) Summary Form: ( DEFPKG "PKG0" ...) Rules: NIL Warnings: None Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) "PKG0" ACL2 !>:pr! "PKG0" Rune: (:REWRITE PKG0-PACKAGE) Enabled: T Hyps: T Equiv: EQUAL Lhs: (PKG-IMPORTS "PKG0") Rhs: '(A B) Backchain-limit-lst: NIL Subclass: ABBREVIATION ACL2 !> Consider a [47m[defpkg][0m event that is introduced during evaluation of an [47m[include-book][0m event, where that [47minclude-book[0m event occurs [local]ly inside a surrounding [47m[encapsulate][0m event or another [47minclude-book[0m event. In that case, traces of the axiom added by the [47mdefpkg[0m event will disappear after the surrounding event is admitted. If ACL2 were to allow the same package name to be defined subsequently with a different set of imports, that could cause inconsistencies. See [package-reincarnation-import-restrictions] for relevant discussion, or see the ``Essay on Hidden Packages'' in source file [47maxioms.lisp[0m.. In order to prevent unsoundness, ACL2 maintains the following invariant. Let us say that a [47mdefpkg[0m event is ``hidden'' if it is in support of the current logical [world] but is not present in that world as an event, because it is [47m[local][0m as indicated above. We maintain the invariant that all [47m[defpkg][0m [events], even if ``hidden'', are tracked under-the-hood in the current logical [world]. Sometimes this property causes [47m[defpkg][0m events to be written to the [portcullis] of a book's [certificate] (see [books]). This invariant guarantees that if you then try to define a package in a manner inconsistent with its earlier definition --- specifically, with a different imports list --- you will see an error because of the tracking discussed above. (By the way, this topic's name comes from Holly Bell, who heard "hidden death package" instead of "hidden defpkg". The description seemed to fit. Thanks, Holly!)") (hidden-defpkg (packages defpkg) "Handling defpkg events that are local See [hidden-death-package]") (hide (rewrite) "Hide a term from the rewriter [47mHide[0m is actually the [identity] function: [47m(hide x) = x[0m for all [47mx[0m. However, terms of the form [47m(hide x)[0m are ignored by the ACL2 rewriter, except when explicit [47m:expand[0m [hints] are given for such terms (see [hints]) or when rewrite rules explicitly about [47mhide[0m are available. An [47m:expand[0m hint that removes all calls of [47mhide[0m is: :expand ((:free (x) (hide x))) The above hint can be particularly useful when ACL2's equality heuristics apply [47mhide[0m to an equality after substituting it into the rest of the goal, if that goal (or a subgoal of it) fails to be proved. Another common case, described below, is when [47mhide[0m is added by the simplifier because an attempted execution of the term failed. In this case, an [47m:expand[0m hint as described above will have no effect because the execution will just fail again; the [47mhide[0m will be re-inserted; and the hapless user will find themselves questioning their own sanity. [47mHide[0m terms are generally ignored not only by the rewriter but by other ACL2 procedures, including the induction heuristics and (by default) removal of [guard-holders]. Sometimes the ACL2 simplifier inserts [47mhide[0m terms into a proof attempt out of the blue, as it were. Why and what can you do about it? Suppose you have a constrained function, say [47mconstrained-fn[0m, and you define another function, say [47manother-fn[0m, in terms of it, as in: (defun another-fn (x y z) (if (big-hairy-test x y z) (constrained-fn x y z) t)) Suppose the term [47m(another-fn 1 2 3)[0m arises in a proof. Since the arguments are all constants, ACL2 may try to reduce such a term to a constant by executing the definition of [47manother-fn[0m. However, after a possibly extensive computation (because of [47mbig-hairy-test[0m) the execution fails because of the unevaluable call of [47mconstrained-fn[0m. To avoid subsequent attempts to evaluate the term, ACL2 embeds it in a [47mhide[0m expression. Often that expression will use a call of [47m[comment][0m, where [47m(comment x y)[0m is logically just [47my[0m, to tell you the problematic constrained function, in this case by rewriting the original expression to the following; see [comment]. (Near the end of this topic we discuss how to avoid the call of [47mcomment[0m.) (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN" (another-fn 1 2 3))) You might think this rarely occurs since all the arguments of [47manother-fn[0m must be constants. You would be right except for one special case: if [47manother-fn[0m takes no arguments, i.e., is a constant function, then every call of it fits this case. Thus, if you define a function [47mf[0m of no arguments in terms of a constrained function [47mg[0m, you may often see [47m(f)[0m rewrite to: (hide (comment "Failed attempt to call constrained function G" (f))). We do not hide the term if the [executable-counterpart] of the function is [disable]d --- because we do not try to evaluate it in the first place. Thus, to prevent the insertion of a [47mhide[0m term into the proof attempt, you can globally disable the executable-counterpart of the offending defined function, e.g., (in-theory (disable (:executable-counterpart another-fn))). It is conceivable that you cannot afford to do this: perhaps some calls of the offending function must be computed while others cannot be. One way to handle this situation is to leave the executable-counterpart enabled, so that [47mhide[0m terms are introduced on the calls that cannot be computed, but prove explicit [47m:[0m[47m[rewrite][0m rules for each of those [47mhide[0m terms. For example, suppose that in the proof of some theorem, thm, it is necessary to leave the executable-counterpart of [47manother-fn[0m enabled but that the call [47m(another-fn 1 2 3)[0m arises in the proof and cannot be computed. Thus the proof attempt will introduce the term [47m(hide (comment ".." (another-fn 1 2 3)))[0m mentioned above. Suppose that you can show that [47m(another-fn 1 2 3)[0m is [47m(constrained-fn 1 2 3)[0m and that such a step is necessary to the proof. Unfortunately, proving the rewrite rule (defthm thm-helper (equal (another-fn 1 2 3) (constrained-fn 1 2 3))) would not help the proof of thm because the target term is hidden inside the [47mhide[0m. However, (defthm thm-helper (equal (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN" (another-fn 1 2 3))) (constrained-fn 1 2 3))) would be applied in the proof of thm and is the rule you should prove. Now to prove [47mthm-helper[0m you need to use the two ``tricks'' which have already been discussed. First, to eliminate the [47mhide[0m term in the proof of [47mthm-helper[0m you should include a hint to [47m:expand[0m that term. Second, to prevent the [47mhide[0m term from being reintroduced when the system tries and fails to evaluate [47m(another-fn 1 2 3)[0m you should include the hint [47m:in-theory[0m [47m(disable (:executable-counterpart another-fn))[0m. Thus, [47mthm-helper[0m will actually be: (defthm thm-helper (equal (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN" (another-fn 1 2 3))) (constrained-fn 1 2 3)) :hints (("Goal" :expand (hide (comment "Failed attempt to call constrained function CONSTRAINED-FN" (another-fn 1 2 3))) :in-theory (disable (:executable-counterpart another-fn))))) See [eviscerate-hide-terms] for how to affect the printing of [47mhide[0m terms. Finally, note that you can avoid the generation of [47m[comment][0m calls inside the generated call of [47mhide[0m, as was the case through ACL2 Version 8.2, as follows. (defattach-system ; generates (local (defattach ...)) hide-with-comment-p constant-nil-function-arity-0) After evaluation of this event, our running example [47m(another-fn 1 2 3)[0m would generate [47m(hide (another-fn 1 2 3))[0m rather than a term of the form [47m(hide (comment "..." (another-fn 1 2 3)))[0m. In some cases such backward compatibility might also be achieved as follows; also see [guard-holders]. (defattach-system ; generates (local (defattach ...)) remove-guard-holders-blocked-by-hide-p constant-nil-function-arity-0) [31;1mFunction: [0m<hide> (defun hide (x) (declare (xargs :guard t)) x) Subtopics [Comment] Variant of [47m[prog2$][0m to help debug evaluation failures during proofs") (hints (miscellaneous) "Advice to the theorem proving process Examples: The following :hints value is nonsensical. Nevertheless, it illustrates all of the available hint keywords except the ``custom keywords'' (see [custom-keyword-hints]) definable by the user. :hints (("Goal" :do-not-induct t :do-not '(generalize fertilize) :expand ((assoc x a) :lambdas (:free (y) (:with member (member y z)))) :restrict ((<-trans ((x x) (y (foo x))))) :hands-off (length binary-append) :in-theory (set-difference-theories (current-theory :here) '(assoc)) :induct (list (nth n a) (nth n b)) :use ((:instance assoc-of-append (x a) (y b) (z c)) (:functional-instance (:instance p-f (x a) (y b)) (p consp) (f assoc))) :bdd (:vars (c a0 b0 a1 b1) :prove nil :bdd-constructors (cons)) :clause-processor (:function cl-proc :hint (my-hint clause)) :instructions (:x :prove) :cases ((true-listp a) (consp a)) :by (:instance rev-rev (x (cdr z))) :nonlinearp t :backchain-limit-rw 3 :reorder (4 7 2) :case-split-limitations (20 10) :no-op t :no-thanks t :error ("Bad value ~x0." 123) :or (hint-kwd-alist-1 ... hint-kwd-alist-k) :rw-cache-state nil :backtrack (my-computed-hint clause processor clause-list))) Many of these hints affect the how the prover operates not only on the goal to which they are applied but also on its subgoals (and its subgoals' subgoals, etc.; for a deeper explanation see [hints-and-the-waterfall]). The following hints, however, have a specific effect only on the goal to which they are applied: [47m:bdd[0m, [47m:by[0m, [47m:cases[0m, [47m:clause-processor[0m, [47m:error[0m, [47m:induct[0m, [47m:or[0m, and [47m:use[0m. For example, suppose that you specify both a [47m:cases[0m hint and an [47m:expand[0m hint for [47m"Goal"[0m. Then the [47m:cases[0m hint will immediately result in subgoals, without calling the ACL2 rewriter; the [47m:expand[0m hint will be used by the rewriter in subsequent goals. A very common hint is the [47m:use[0m hint, which is described below. In general it takes as its value a list of ``lemma instances'' (see [lemma-instance]), but it allows special cases, including a single lemma name. In each case, a goal [47mG[0m is replaced by a new goal [47m(IMPLIES P G)[0m, where [47mP[0m is the theorem specified by the (conjunction of the) lemma instances provided. Here are some examples. ; Attach :use hint to the top-level goal G, which is named "Goal", ; replacing it by (implies P G) where P is the statement of lemma23: :hints (("Goal" :use lemma23)) ; Equivalent to the above, using the trivial instance (i.e., with the empty ; substitution) of lemma23: :hints (("Goal" :use ((:instance lemma23)))) ; Attach :use hint to the named subgoal, where the indicated lemma is used ; with the substitution that maps x to 17 and y to (foo z): :hints (("[1]Subgoal *1/1.2'" :use ((:instance lemma23 (x 17) (y (foo z)))))) ; Equivalent to the above: ACL2 allows you to omit the outer parentheses if ; there is only one lemma used. :hints (("[1]Subgoal *1/1.2'" :use (:instance lemma23 (x 17) (y (foo z))))) ACL2 also provides ``custom keyword'' hints (see [custom-keyword-hints]) and even more general ``computed hints'' for the advanced user (see [computed-hints]). Not documented in this topic are such hints implemented in books; for an example of so-called [47m:consider[0m hints, see [consideration]. When the ACL2 prover encounters a goal [47m"G"[0m, then the first hint of the form [47m("G" :kwd1 val1 ...)[0m is applied to that goal. This usually means that all hints for the goal [47m"G"[0m after the first such hint are ignored, and ACL2 produces a warning about that. (Note however that [47m("G")[0m is simply dropped; such an empty hint is considered not to be there, for purposes of this discussion.) If there are default hints (see [set-default-hints]) then this behavior applies to the user-supplied list of [47m:hints[0m followed by the default hints; see [hints-and-the-waterfall] for a detailed discussion of how hints fit into the ACL2 waterfall, which in particular has a ``slightly tricky example'' illustrating the unusual case when a goal can be encountered more than once, thus applying more than one hint on that goal. Also see [override-hints] for an advanced feature that can modify the ``first hint'' behavior described above. For examples of the sophisticated use of hints, primarily for experts, see community book [47mbooks/hints/basic-tests.lisp[0m. Duplicate hint keywords are prohibited in a hint; for example, the hint [47m("Goal" :induct t :induct t)[0m is illegal. Also, certain hint keywords are incompatible within a given hint, for example, in [47m("Goal" :use nth :induct t)[0m. These restrictions for duplicates and compatibility apply not only for explicit hints but also for hints that are generated by computed hints or [override-hints]; for example, the command [47m(add-override-hints '((append '(:use nth :induct t) keyword-alist)))[0m will cause subsequent proof attempts to fail because [47m:use[0m and [47m:induct[0m are incompatible keywords. Here is the full list of incompatibilities for hint keywords on a given goal. * It is illegal to use two or more keywords from the following list, except that [47m:use[0m and [47m:cases[0m may be used together: [47m(:induct :use :cases :by :bdd :clause-processor :or)[0m. * It is illegal to use [47m:reorder[0m with either [47m:or[0m or [47m:induct[0m. Background: [47mHints[0m are allowed in all [events] that use the theorem prover. During [47m[defun][0m [events] there are two different uses of the theorem prover: one to prove termination and another to verify the [guard]s. To pass a hint to the theorem prover during termination proofs, use the [47m:hints[0m keyword in the [47m[defun][0m's [47m[xargs][0m declaration. To pass a hint to the theorem prover during the [guard] verification portion of admitting a [47m[defun][0m, use the [47m:guard-hints[0m keyword in the [47m[defun][0m's [47m[xargs][0m declaration. The [47m[verify-guards][0m event and the [47m[defthm][0m event also use the theorem prover. To pass hints to them, use the [47m:hints[0m keyword argument to the event. General Form of Common :hints: ((goal-spec :key1 val1 ... :keyn valn) ... (goal-spec :key1 val1 ... :keyn valn)) where [47m[goal-spec][0m is as described elsewhere (see [goal-spec]) and the keys and their respective values are shown below with their interpretations. We also provide ``computed hints'' but discuss them separately; see [computed-hints]. The hint keywords below are considered in alphabetical order. [47m:backchain-limit-rw[0m [47mValue[0m is a natural number or [47mnil[0m, indicating the level of backchaining for [rewrite], [meta], and [linear] rules. This overrides, for the current goal and (as with [47m:[0m[47m[in-theory][0m hints) descendant goals, the default [backchain-limit] (see [set-backchain-limit]). [47m:backtrack[0m This is an advanced hint. You can probably accomplish its effect by the use of ordinary computed hints; see [computed-hints]. But if you are an expert, read on. (See [hints-and-the-waterfall] for some relevant background.) [47mValue[0m is a computed hint, which is an expression that evaluates either to [47mnil[0m --- indicating that the [47m:backtrack[0m hint is to have no effect --- or to a non-empty alternating list of [47m:keyi vali[0m pairs, as expected for a hint. However, unlike ordinary computed hints, [47m:backtrack[0m hints are evaluated [31;1mafter[0m a goal has been processed to yield zero or more subgoals, not before. Moreover, variables [47mPROCESSOR[0m and [47mCLAUSE-LIST[0m are allowed, but variable [47mSTABLE-UNDER-SIMPLIFICATIONP[0m is not. We explain in more detail below, but first consider the following simple example. First we define a standard list reversal function: (defun rev (x) (if (consp x) (append (rev (cdr x)) (cons (car x) nil)) nil)) Now we prove: (thm (true-listp (rev x))) The successful proof includes the following output. Subgoal *1/1' (IMPLIES (AND (CONSP X) (TRUE-LISTP (REV (CDR X)))) (TRUE-LISTP (APPEND (REV (CDR X)) (LIST (CAR X))))). The destructor terms (CAR X) and (CDR X) can be eliminated by using CAR-CDR-ELIM to replace X by (CONS X1 X2), (CAR X) by X1 and (CDR X) by X2. This produces the following goal. Subgoal *1/1'' (IMPLIES (AND (CONSP (CONS X1 X2)) (TRUE-LISTP (REV X2))) (TRUE-LISTP (APPEND (REV X2) (LIST X1)))). But suppose that we attach a [47m:backtrack[0m hint to the goal above at which destructor elimination was applied: (thm (true-listp (rev x)) :hints (("Subgoal *1/1'" :backtrack (quote (:do-not '(eliminate-destructors)))))) Then when ACL2 applies destructor elimination as displayed above, this time the [47m:backtrack[0m hint applies, evaluating to [47m(:do-not '(eliminate-destructors))[0m. Since this list is not [47mnil[0m, the prover decides not to keep the new subgoal, and instead supplies this [47m:do-not[0m hint before attacking the goal again. In this example, ACL2 happens to use a technique later in its ``waterfall'' arsenal than destructor elimination, namely, generalization: Subgoal *1/1' (IMPLIES (AND (CONSP X) (TRUE-LISTP (REV (CDR X)))) (TRUE-LISTP (APPEND (REV (CDR X)) (LIST (CAR X))))). [Note: A hint was supplied for the goal above, because of a :backtrack hint that is preventing destructor elimination. Thanks!] We generalize this conjecture, replacing (REV (CDR X)) by RV. This produces Subgoal *1/1'' (IMPLIES (AND (CONSP X) (TRUE-LISTP RV)) (TRUE-LISTP (APPEND RV (LIST (CAR X))))). We now provide a careful explanation of how [47m:backtrack[0m hints work, but we suggest that you keep the example above in mind. If ``[47m:backtrack form[0m'' is part of the hint that has been selected for a goal, then [47mform[0m is evaluated when one of ACL2's [clause] processors successfully applies to the current goal to produce a list of subgoals. This evaluation takes place in an environment just like that for any computed hint (see [computed-hints]), with the following exceptions. First, the variable [47mSTABLE-UNDER-SIMPLIFICATIONP[0m is not allowed to occur free in [47mform[0m, but instead the following new variables are allowed to occur free and are bound for this evaluation as follows: [47mPROCESSOR[0m is bound to the processor in the list [47m*preprocess-clause-ledge*[0m that has applied to the goal, and [47mCLAUSE-LIST[0m is bound to the list of clauses (each a list of literals that is implicitly disjoined) returned by that clause processor. Second, the variables [47mHIST[0m and [47mPSPV[0m are bound to the history and pspv returned by the clause processor, [31;1mnot[0m the ones that were passed to the clause processor. If this evaluation returns an error, then the proof aborts, as for any computed hint whose evaluation returns an error. If this evaluation returns [47mnil[0m, then the [47m:backtrack[0m hint has no effect, and the goal is replaced by the list of goals (the value of [47mCLAUSE-LIST[0m described above), as usual. Otherwise, the clause processor is deemed to have failed, and the goal clause is tried again starting at the top of the waterfall after selecting the hint returned by the above evaluation. That hint will normally be an alternating list of hint keywords and their values, but if it is a custom keyword hint (see [custom-keyword-hints]), then it will be handled in the usual manner but with the first three variables above bound to the symbol [47m:OMITTED[0m. Of course, if the new hint includes a value for [47m:BACKTRACK[0m then this process can loop; care should be taken to keep that from happening. A final note about [47m:BACKTRACK[0m hints: since these are a form of computed hints, [override-hints] (if any) are applied to their evaluation result just as with any computed hint. That is, the backtrack hint is successively modified with each override-hint, to produce a final hint that is actually used (or, ignored if that final hint is [47mnil[0m). See [override-hints]. [47m:[0m[47m[bdd][0m This hint indicates that ACL2's built-in ordered binary decision diagrams (BDDs) with rewriting are to be used to prove or simplify the goal. See [bdd] for an introduction to the ACL2 BDD algorithm. [47mValue[0m is a list of even length, such that every other element, starting with the first, is one of the keywords [47m:vars[0m, [47m:bdd-constructors[0m, [47m:prove[0m, or [47m:literal[0m. Each keyword that is supplied should be followed by a value of the appropriate form, as shown below; for others, a default is used. Although [47m:vars[0m must always be supplied, we expect that most users will be content with the defaults used for the other values. [47m:vars[0m --- A list of ACL2 variables, which are to be treated as Boolean variables. The prover must be able to check, using [type-reasoning], that each of these variables is Boolean in the context of the current goal. Note that the prover will use very simple heuristics to order any variables that do not occur in [47m:vars[0m (so that they are ``greater than'' the variables that do occur in [47m:vars[0m), and these heuristics are often far from optimal. In addition, any variables not listed may fail to be assumed Boolean by the prover, which is likely to seriously impede the effectiveness of ACL2's BDD algorithm. Thus, users are encouraged [3mnot[0m to rely on the default order, but to supply a list of variables instead. Finally, it is allowed to use a value of [47mt[0m for [47mvars[0m. This means the same as a [47mnil[0m value, except that the BDD algorithm is directed to fail unless it can guarantee that all variables in the input term are known to be Boolean (in a sense discussed elsewhere; see [bdd-algorithm]). [47m:literal[0m --- An indication of which part of the current goal should receive BDD processing. Possible values are: :all treat entire goal as a single literal (the default) :conc process the conclusion n process the hypothesis with index n (1, 2, ...) [47m:bdd-constructors[0m --- When supplied, this value should be a list of function symbols in the current ACL2 [world]; it is [47m(cons)[0m by default, unless [47m:bdd-constructors[0m has a value in the [47m[ACL2-defaults-table][0m by default, in which case that value is the default. We expect that most users will be content with the default. See [bdd-algorithm] for information about how this value is used. [47m:prove[0m --- When supplied, this value should be [47mt[0m or [47mnil[0m; it is [47mt[0m by default. When the goal is not proved and this value is [47mt[0m, the entire proof will abort. Use the value [47mnil[0m if you are happy to the proof to go on with the simplified term. [47m:by[0m [47mValue[0m is a [lemma-instance], [47mnil[0m, or a new event name. If the value is a [lemma-instance] (see [lemma-instance]), then it indicates that the goal (when viewed as a clause) is either equal to the proposition denoted by the instance, or is subsumed by that proposition when both are viewed as clauses. To view a formula as a clause, union together the negations of the hypotheses and add the conclusion. For example, (IMPLIES (AND (h1 t1) (h2 t2)) (c t1)) may be viewed as the clause {~(h1 t1) ~(h2 t2) (c t1)}. Clause [47mc1[0m is ``subsumed'' by clause [47mc2[0m iff some instance of [47mc2[0m is a subset of [47mc1[0m. For example, the clause above is subsumed by [47m{~(h1 x) (c x)}[0m, which when viewed as a formula is [47m(implies (h1 x) (c x))[0m. Note that if the value is the name of a function symbol introduced by [47m[defun][0m, then the original form of the body of that definition is used. This behavior differs from that provided by a [47m:use[0m hint, which uses the normalized (simplified) body; see [normalize]. If the value is [47mnil[0m or a new name, the prover does not even attempt to prove the goal to which this hint is attached. Instead the goal is given a ``bye'', i.e., it is skipped and the proof attempt continues as though the goal had been proved. If the prover terminates without error then it reports that the proof would have succeeded had the indicated goals been proved and it prints an appropriate [defthm] form to define each of the [47m:by[0m names. The ``name'' [47mnil[0m means ``make up a name.'' Here is an example (admittedly contrived for illustration purposes). ACL2 !>(thm (equal (append (append x y) z) (append x y z)) :hints (("Subgoal *1/2'" :by nil))) Name the formula above *1. [[... output omitted here ...]] [Note: A hint was supplied for the goal below. Thanks!] Subgoal *1/2' (IMPLIES (AND (CONSP X) (EQUAL (APPEND (APPEND (CDR X) Y) Z) (APPEND (CDR X) Y Z))) (EQUAL (APPEND (APPEND X Y) Z) (APPEND X Y Z))). But we have been asked to pretend that this goal is subsumed by the yet-to-be-proved |THM Subgoal *1/2'|. Subgoal *1/1 [[... proof goes on; further output omitted here ...]] The system does not attempt to check the uniqueness of the [47m:by[0m names (supplied or made up), since by the time those goals are proved the namespace will be cluttered still further. Therefore, the final list of ``appropriate'' [47m[defthm][0m forms may be impossible to admit without some renaming by the user. If you must invent new names, remember to substitute the new ones for the old ones in the [47m:by[0m hints themselves. [47m:[0m[47m[case-split-limitations][0m [47mValue[0m is the same as for [47m[set-case-split-limitations][0m. The simplifier will behave as though the value had instead been supplied to [47mset-case-split-limitations[0m; see [set-case-split-limitations]. This behavior will persist through subgoals unless overridden by another [47m:CASE-SPLIT-LIMITATIONS[0m hint. [47m:cases[0m [47mValue[0m is a non-empty list of terms. For each term in the list, a new goal is created from the current goal by assuming that term; and also, in essence, one additional new goal is created by assuming all the terms in the list false. We say ``in essence'' because if the disjunction of the terms supplied is a tautology, then that final goal will be a tautology and hence will in fact never actually be created. [47m:[0m[47m[clause-processor][0m [47mValue[0m specifies the application of a user-defined simplifier to the current goal. See [clause-processor], which provides necessary background and hint syntax. Also see [define-trusted-clause-processor] for a discussion of ``trusted clause-processors'': goal-level simplifiers that may be external to ACL2 and do not need to be proved correct in ACL2. You can see all current [47m:clause-processor[0m rules by issuing the command [47m(print-clause-processor-rules)[0m, and you can see the names of all trusted clause-processors by issuing the command [47m(table trusted-cl-proc-table)[0m. [47m:do-not[0m [47mValue[0m is a term having at most the single free variable [47m[world][0m, which when evaluated (with [47m[world][0m bound to the current ACL2 logical [world]) produces a list of symbols that is a subset of the list (preprocess ;propositional logic, simple rules simplify ;as above plus rewriting, linear arithmetic eliminate-destructors fertilize ;use of equalities generalize eliminate-irrelevance). The hint indicates that the ``processes'' named should not be used at or below the goal in question. Thus, to prevent generalization and fertilization, say, include the hint :do-not '(generalize fertilize) If [47mvalue[0m is a single symbol, as in :do-not generalize, it is taken to be [47m'(value)[0m. See also [do-not-hint] for a way to automatically provide [47m:do-not[0m hints across several theorems. [47m:do-not-induct[0m [47mValue[0m indicates whether [induction] is permitted under the specified goal. The legal values are [47mt[0m, [47m:otf-flg-override[0m, [47m:otf[0m, [47mnil[0m, or a non-keyword symbol other than [47mt[0m or [47mnil[0m. The default is [47mnil[0m, meaning that induction is permitted as usual. A non-[47mnil[0m value prohibits the use of induction to prove the indicated goal or any of its subgoals, as described below. If [47mvalue[0m is [47mt[0m or [47m:otf-flg-override[0m, then the attempt to apply [induction] to the indicated goal or any subgoal under the indicated goal will immediately cause the theorem prover to report [failure], except that if [47m:otf-flg t[0m is specified (see [otf-flg]) and [47mvalue[0m is [47mt[0m, then the proof will continue until the time at which the goal pushed for induction is finally encountered and causes failure. The latter behavior is also what occurs if [47mvalue[0m is [47m:otf[0m. See however the [47m:induct[0m hint below. If [47mvalue[0m is a non-keyword symbol other than [47mt[0m or [47mnil[0m, the theorem prover will skip every subgoal under the indicated goal (giving it a ``bye'', as with a ``[47m:by[0m'' hint) that would otherwise be attacked with induction. This will cause the theorem prover to fail eventually, printing every subgoal thus skipped in the form of an event to prove, each with a name based on the value of the [47m:do-not-induct[0m hint that caused that subgoal to be skipped. [31;1mRemarks.[0m (1) An [47m:induct[0m hint is applied to a goal even if a [47m:do-not-induct[0m hint is in effect for that goal. Consider the following examples. (thm (equal (append (append x y) z) (append x y z)) :hints (("Goal" :induct t :do-not-induct t))) (thm (and (equal (append (append x y) z) (append x y z)) (equal (append (append u v) w) (append u v w))) :hints (("Goal" :do-not-induct t) ("Subgoal 2" :induct t))) In the first of these, the [47m:do-not-induct[0m hint has no effect on the proof; instead, the [47m:induct[0m hint forces an induction that allows the proof to succeed (without any sub-inductions). The second of these illustrates that even though [47m:do-not-induct[0m can stop sub-inductions, its effect is overridden by [47m:induct[0m. For the proof of that second example, ACL2 immediately splits into two subgoals. Then in spite of the top-level [47m:do-not-induct[0m hint, the proof is allowed to proceed past Subgoal 2, which requires induction, because of the hint [47m:induct t[0m. However, the proof halts after Subgoal 1 because of the [47m:do-not-induct[0m hint that has been established ``above'' it, at [47m"Goal"[0m. (For more about the way hints are processed, see [hints-and-the-waterfall].) (2) For an advanced example of the use of value [47m:otf[0m for [47m:do-not-induct[0m combined with [override-hints], see community book [47mbooks/hints/basic-tests.lisp[0m. [47m:error[0m [47mValue[0m is typically a ``fmt message'' to be printed by the [47m[fmt][0m tilde-directive ~@ but may be any object. The effect of this hint is to cause an error when the hint is translated. There is no reason to include an [47m:ERROR[0m hint in any user-typein, since it will only cause an error when the form is evaluated. [47m:ERROR[0m hints are useful in the definition of functions that generate custom keyword hints (see [custom-keyword-hints]) and computed hints (see [computed-hints]). For example, if you wish to define a custom keyword hint [47m:my-hint val[0m and you wish the hint to signal an error if there is something inappropriate about [47mval[0m in the context of the hint, use the following code to generate the hint (list :ERROR (cons "Your specified value, ~x0, is inappropriate" (list (cons #0 val)))) which is equivalent to (list :ERROR (msg "Your specified value, ~x0, is inappropriate" val)) which, if [47mval[0m has the value [47m123[0m, would evaluate to the hint (:ERROR ("Your specified value, ~x0, is inappropriate" (#0 . 123))). Note that any time an [47m:ERROR[0m keyword is produced during hint processing, including iterations of the expansions of custom keyword hints or of [override-hints], an error will occur. [47m:expand[0m [47mValue[0m is a true list of terms, each of which is of one of the forms [47m(let ((v1 t1)...) b)[0m or [47m(fn t1 ... tn)[0m, where [47mfn[0m is a defined function symbol with formals [47mv1, ..., vn,[0m and [47mbody[0m [47mb[0m. Such a term is said to be ``expandable:'' it can be replaced by the result of substituting the [47mti[0m's for the [47mvi[0m's in [47mb[0m. The terms listed in the [47m:expand[0m hint are expanded when they are encountered by the simplifier while working on the specified goal or any of its subgoals. (There is no separate ``expand'' process.) We permit [47mvalue[0m to be a single such term instead of a singleton list. [31;1mRemarks[0m: (0) Note that in the event that a [47m:definition[0m rule has been admitted for [47mfn[0m, then by default, the body [47mb[0m is determined by the (most recently admitted such) rule rather than the original definition of [47mfn[0m; see [definition]. (1) Allowed are ``terms'' of the form [47m(:free (var1 var2 ... varn) pattern)[0m where the indicated variables are distinct and [47mpattern[0m is a term. Such ``terms'' indicate that we consider the indicated variables to be instantiatable, in the following sense: whenever the simplifier encounters a term that can be obtained from [47mpattern[0m by instantiating the variables [47m(var1 var2 ... varn)[0m, then it expands that term. (2) Also allowed are ``terms'' of the form [47m(:with name term)[0m, where [47mname[0m is a function symbol, a macro name that denotes a function symbol (see [macro-aliases-table]), or a [rune]. The corresponding [definition] rule or (less often) [47m[rewrite][0m rule is then used in place of the current body for the function symbol of [47mterm[0m; see [show-bodies] and see [set-body]. If the rule is of the form [47m(implies hyp (equiv lhs rhs))[0m, then after matching [47mlhs[0m to the current term in a context that is maintaining equivalence relation [47mequiv[0m, ACL2 will replace the current term with [47m(if hyp rhs (hide term))[0m, or just [47mrhs[0m if the rule is just [47m(equal lhs rhs)[0m. (3) A combination of both [47m:free[0m and [47m:with[0m, as described above, is legal. (4) The term [47m:LAMBDAS[0m is treated specially. It denotes the list of all lambda applications (i.e., [47m[let][0m expressions) encountered during the proof. Conceptually, this use of [47m:LAMBDAS[0m tells ACL2 to treat lambda applications as a notation for substitutions, rather than as function calls whose opening is subject to the ACL2 rewriter's heuristics (specifically, not allowing lambda applications to open when they introduce ``too many'' if terms). [47m:hands-off[0m [47mValue[0m is a true list of function symbols or lambda expressions, indicating that under the specified goal applications of these functions are not to be rewritten. Note however that subterms will still be rewritten; see [hide] if that is not what is intended. (The community book [47mbooks/clause-processors/autohide.lisp[0m from Jared Davis may also be helpful in that case.) [47mValue[0m may also be a single function symbol or lambda expression instead of a list. [47m:[0m[47m[in-theory][0m [47mValue[0m is a ``theory expression,'' i.e., a term having at most the single free variable [47m[world][0m which when evaluated (with [47m[world][0m bound to the current ACL2 logical world (see [world])) will produce a theory to use as the current theory for the goal specified. See [theories]. Note that an [47m:[0m[47m[in-theory][0m hint will always be evaluated relative to the current ACL2 logical [world], not relative to the theory of a previous goal. Consider the following example. (defthm prop (p (f (g x))) :hints (("Goal" :in-theory (disable f)) ("Subgoal 3" :in-theory (enable g)))) Consider in particular the theory in effect at [47mSubgoal 3[0m. This call of the [47m[enable][0m macro enables [47mg[0m relative to the [47m[current-theory][0m of the current logical [world], [3mnot[0m relative to the theory produced by the hint at [47mGoal[0m. Thus, the [47m[disable][0m of [47mf[0m on behalf of the hint at [47mGoal[0m will be lost at [47mSubgoal 3[0m, and [47mf[0m will be enabled at [47mSubgoal 3[0m if was enabled globally when [47mprop[0m was submitted. [47m:induct[0m [47mValue[0m is either [47mt[0m or a term that is not an atom or a quoted constant. The value [47mt[0m indicates that the system use induction immediately by applying its induction heuristic to the specified goal (without trying simplification, etc.). Otherwise, the system should apply induction immediately, but it should analyze [47mvalue[0m rather than the goal to generate its [induction] scheme. Either way (i.e., for value [47mt[0m or not), merging and the other [induction] heuristics are applied. Thus, if [47mvalue[0m contains several mergeable [induction]s, the ``best'' will be created and chosen. E.g., the [47m:induct[0m hint (list (nth i a) (nth j a)) suggests simultaneous [induction] on [47mi[0m, [47mj[0m, and [47ma[0m. When the selected induction scheme is suggested by just one term the induction is announced with a message like ``[47mWe will induct according to a scheme suggested by[0m'' the term in question. But if several terms are involved in the suggestion, either because they suggested the same scheme or because their suggestions were merged with others to form the selected scheme, the announcement includes the phrase ``[47mwhile accommodating[0m'' the other terms. Furthermore, as noted in [induction-heuristics], the induction mechanism communicates to the simplifier, passing to it the list of all the terms being accommodated. The simplifier preferentially expands those terms during the subsequent proof attempt. Thus, if the prover automatically selects an induction that accommodates terms besides the one suggesting and justifying the induction, and you want to give an [47m:induct[0m hint that causes the same behavior, your hint should include the term suggesting the induction and all of the accommodated terms. We typically do this with a hint like [47m:induct (list term0 term1 ... termk)[0m. If both an [47m:induct[0m and a [47m:do-not-induct[0m hint are supplied for a given goal then the indicated [induction] is applied to the goal and the [47m:do-not-induct[0m hint is inherited by all subgoals generated. [47m:[0m[47m[instructions][0m [47mValue[0m is a list of interactive [proof-builder] instructions; see [instructions]. Unlike other hint keywords described here, this one is actually a custom keyword hint (see [custom-keyword-hints]) that generates a suitable [47m:[0m[47m[clause-processor][0m hint. [47m:no-op[0m [47mValue[0m is any object and is irrelevant. This hint has no effect, although unlike an empty hint such as [47m("Goal")[0m, it is not dropped. Thus, [47m("Goal" :no-op t)[0m will shadow any later (or default) hint on [47m"Goal"[0m, but [47m("Goal")[0m will not. Unlike other hint keywords, multiple occurrences of the keyword [47m:no-op[0m are tolerated. [47m:no-thanks[0m [47mValue[0m is any object. This hint does nothing, except that if [47mvalue[0m is non-[47mnil[0m then the usual ``[Note: A hint was supplied... Thanks!]'' is not printed. [47m:nonlinearp[0m [47mValue[0m is [47mt[0m or [47mnil[0m, indicating whether [non-linear-arithmetic] is active. The default value is [47mnil[0m. See [non-linear-arithmetic]. [47m:or[0m [47mValue[0m is a list [47m(kwd-val-listp-1 ... kwd-val-listp-k)[0m, where each [47mkwd-val-listp-i[0m is a list satisfying [47m[keyword-value-listp][0m, i.e., an alternating list of keywords and values. This hint causes an attempt to prove the specified goal using hints [47mkwd-val-listp-i[0m in sequence (first [47mkwd-val-listp-1[0m, then [47mkwd-val-listp-2[0m, and so on), until the first of these succeeds. If none succeeds, then the prover proceeds after heuristically choosing the ``best'' result, taking into account the goals pushed in each case for proof by induction. The following (contrived but illustrative example illustrates how [47m:or[0m hints work. ACL2 !>(thm (f x) :hints (("Goal" :expand ((nth x 3)) :or ((:in-theory (disable car-cons)) (:use cdr-cons :in-theory (enable append))) :do-not '(generalize)))) [Note: A hint was supplied for the goal above. Thanks!] The :OR hint for Goal gives rise to two disjunctive branches. Proving any one of these branches would suffice to prove Goal. We explore them in turn, describing their derivations as we go. --- Subgoal D2 ( same formula as Goal ). The first disjunctive branch (of 2) for Goal can be created by applying the hint: ("Subgoal D2" :EXPAND ((NTH X 3)) :IN-THEORY (DISABLE CAR-CONS) :DO-NOT '(GENERALIZE)). [Note: A hint was supplied for the goal above. Thanks!] Normally we would attempt to prove this formula by induction. However, we prefer in this instance to focus on the original input conjecture rather than this simplified special case. We therefore abandon our previous work on this conjecture and reassign the name *1 to the original conjecture. (See :DOC otf-flg.) [Note: Thanks again for the hint.] --- Subgoal D1 ( same formula as Goal ). The second disjunctive branch (of 2) for Goal can be created by applying the hint: ("Subgoal D1" :EXPAND ((NTH X 3)) :USE CDR-CONS :IN-THEORY (ENABLE APPEND) :DO-NOT '(GENERALIZE)). [Note: A hint was supplied for the goal above. Thanks!] ACL2 Warning [Use] in ( THM ...): It is unusual to :USE the formula of an enabled :REWRITE or :DEFINITION rule, so you may want to consider disabling (:REWRITE CDR-CONS) in the hint provided for Subgoal D1. See :DOC using-enabled-rules. We augment the goal with the hypothesis provided by the :USE hint. The hypothesis can be obtained from CDR-CONS. We are left with the following subgoal. Subgoal D1' (IMPLIES (EQUAL (CDR (CONS X Y)) Y) (F X)). By the simple :rewrite rule CDR-CONS we reduce the conjecture to Subgoal D1'' (F X). ... and so on. This example illustrates how ACL2 processes [47m:or[0m hints in general. For each [47mi[0m from 1 to [47mk[0m, a so-called ``disjunctive'' subgoal is created by splicing [47mkwd-val-listp-i[0m into the other hint values (if any) supplied for the given goal, in order. A corresponding subgoal is created for each [47mi[0m, numbered in the usual manner (hence, counting down) except that the ``[47mD[0m'' is prefixed to each resulting goal. [47m:reorder[0m [47mValue[0m is a list of positive integers without duplicates, corresponding to the numbering of subgoals generated for the [goal-spec] [47m"G"[0m, say [47m"G.k"[0m down to [47m"G.1"[0m. Those subgoals are reordered so that if [47mvalue[0m is [47m(n1 n2 ... nk)[0m, then the goal now numbered [47m"G.k"[0m will be the goal originally numbered [47m"G.n1"[0m; the goal now numbered [47m"G.k-1"[0m will be the goal formerly numbered [47m"G.n2"[0m; and so on, down the list of [47mni[0m, after which the goals not yet printed are printed in their original order. Note that reordering for subgoals of a goal to be proved by induction, such as [47m*1[0m, is not supported. [47m:restrict[0m This hint, originally suggested by Bishop Brock, sometimes allows rules with free variables (see [free-variables]) to be applied successfully by the rewriter, thus avoiding the clutter, case-splitting, and theory management (disabling) that can occur with [47m:use[0m hints. Warning: This is a sophisticated hint that may be most appropriate for experienced ACL2 users. In particular, [47m:restrict[0m hints are ignored by the preprocessor, so you might find it useful to give the hint [47m:do-not '(preprocess)[0m when using any [47m:restrict[0m hints, at least if the rules in question are abbreviations (see [simple]). [47mValue[0m is an association list. Its members are of the form [47m(x subst_1 subst_2 ...)[0m, where: [47mx[0m is either (1) a [rune] whose [47m[car][0m is [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m or (2) an event name corresponding to one or more such [rune]s; and [47m(subst_1 subst_2 ...)[0m is a non-empty list of substitutions, i.e., of association lists pairing variables with terms. First consider the case that [47mx[0m is a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m [rune]. Recall that without this hint, the rule named [47mx[0m is used by matching its left-hand side (call it [47mlhs[0m) against the term currently being considered by the rewriter, that is, by attempting to find a [3mmatching substitution[0m, [47ms[0m, such that the instantiation of [47mlhs[0m using [47ms[0m is equal to that term. If however the [47m:restrict[0m hint contains [47m(x subst_1 subst_2 ...)[0m, then this behavior will be modified by restricting [47ms[0m so that it must extend [47msubst_1[0m; and if there is no such [47ms[0m, then [47ms[0m is restricted so that it must extend [47msubst_2[0m; and so on, until such [47ms[0m is produced --- or, the list of substitutions is exhausted without producing a matching substitution, in which case the rewrite or definition rule named [47mx[0m is not applied to that term. Finally, if [47mx[0m is an event name corresponding to one or more [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m [rune]s (that is, [47mx[0m is the ``base symbol'' of such [rune]s; see [rune]), say [rune]s [47mr1[0m, ... [47mrn[0m, then the meaning is the same except that [47m(x subst_1 subst_2 ...)[0m is replaced by [47m(rj subst_1 subst_2 ...)[0m for each [47mj[0m. Once this replacement is complete, the hint may not contain two members whose [47m[car][0m is the same [rune]. Note that the substitutions in [47m:restrict[0m hints refer to the variables actually appearing in the goals, not to the variables appearing in the rule being restricted. The following example, supplied by Mihir Mehta, illustrates the use of [47m:restrict[0m to handle free variables (in this case, a single free variable [47my[0m). The call of [47m[thm][0m below fails without the indicated [47m:restrict[0m hint. (defthm subsetp-trans (implies (and (subsetp x y) (subsetp y z)) (subsetp x z))) (defthm subsetp-evens (subsetp-equal (evens l) l)) (thm (subsetp (evens (evens l)) l) :hints (("Goal" :restrict ((subsetp-trans ((y (evens l)))))))) Here is another example, this one supplied by Bishop Brock. Suppose that the database includes the following rewrite rule, which is probably kept [disable]d. (We ignore the question of how to prove this rule.) cancel-<-*$free: (implies (and (rationalp x) (rationalp y) (rationalp z)) (equal (< y z) (if (< x 0) (> (* x y) (* x z)) (if (> x 0) (< (* x y) (* x z)) (hide (< y z)))))) Then ACL2 can prove the following theorem (unless other rules get in the way), essentially by multiplying both sides by [47mx[0m. (thm (implies (and (rationalp x) (< 1 x)) (< (/ x) 1)) :hints (("Goal" :in-theory (enable cancel-<-*$free) :restrict ((cancel-<-*$free ((x x) (y (/ x)) (z 1))))))) The [47m:restrict[0m hint above says that the variables [47mx[0m, [47my[0m, and [47mz[0m in the rewrite rule [47mcancel-<-*$free[0m above should be instantiated respectively by [47mx[0m, [47m(/ x)[0m, and [47m1[0m. Thus [47m(< y z)[0m becomes [47m(< (/ x) 1)[0m, and this inequality is replaced by the corresponding instance of the right-hand-side of [47mcancel-<-*$free[0m. Since the current conjecture assumes [47m(< 1 x)[0m, that instance of the right-hand side simplifies to (< (* x (/ x)) (* x 1)) which in turn simplifies to [47m(< 1 x)[0m, a hypothesis in the present theorem. [47m:rw-cache-state[0m [47mValue[0m is an element of the list constant [47m*legal-rw-cache-states*[0m: [47m:atom[0m (the default), [47mnil[0m, [47mt[0m, or [47m:disabled[0m. This hint applies to the indicated goal and all its descendants, to set the so-called ``rw-cache-state'' to the indicated value; see [set-rw-cache-state]. [47m:use[0m Examples of [47m:USE[0m hints are shown near the top of this documentation topic. [47mValue[0m is a [lemma-instance] or a true list of [lemma-instance]s, indicating that the propositions denoted by the instances be added as hypotheses to the specified goal: that is, the [47m:use[0m hint replaces a goal, [47mG[0m, by the new goal, [47m(IMPLIES P G)[0m, where [47mP[0m is the theorem specified by the (conjunction of the) lemma instances provided. The [47m:instance[0m form of a [lemma-instance] permits you to instantiate the free variables of previously proved theorems any way you wish, even allowing for differences in [packages]; see [lemma-instance] for details. These new hypotheses participate fully in all subsequent rewriting, etc. If the goal in question is in fact an instance of a previously proved theorem, you may wish to use [47m:by[0m (documented above). Sometimes [theories] are helpful when employing [47m:use[0m hints; see [minimal-theory]. If the value is the name of a function symbol introduced by [47m[defun][0m, then the normalized (simplified) body of that definition is used; see [normalize]. This behavior differs from that provided by a [47m:by[0m hint, where the original body of the definition is used. Subtopics [Computed-hints] Computing advice to the theorem proving process [Custom-keyword-hints] User-defined hints [Default-hints] A list of hints added to every proof attempt [Do-not] Instruct the theorem prover not to do certain things. [Goal-spec] To indicate where a hint is to be used [Guard-theorem] Use a previously-proved [guard] theorem [Guard-theorem-example] How to use a previously-proved [guard] theorem [Hints-and-the-waterfall] How [hints] fit into the ACL2 proof waterfall [Lemma-instance] An object denoting an instance of a theorem [Override-hints] A list of hints given priority in every proof attempt [Termination-theorem] Use a (functional instance of a) previously-proved measure theorem [Termination-theorem-example] How to use a previously-proved measure theorem [Using-computed-hints] How to use computed hints") (hints-and-the-waterfall (hints) "How [hints] fit into the ACL2 proof waterfall Below we describe the flow of an ACL2 proof attempt, with special attention to how [hints] are applied during a proof. For most ACL2 users, only one point is important to take away from this [documentation] topic: you may specify hints during a proof (see [hints]; perhaps also see [computed-hints] and see [default-hints]), and they can be expected to behave intuitively. See [the-method] for a summary of how to interact with the ACL2 prover; see [introduction-to-the-theorem-prover] for a more detailed tutorial; and see [hints] for an introduction to ACL2 hints, including detailed [documentation] for specific hint types. The remainder of this topic serves as a reference in case one needs a deeper understanding of the workings of ACL2's handling of hints. Also, for examples of the sophisticated use of hints, primarily for experts, see community book [47mbooks/hints/basic-tests.lisp[0m. First, we describe the ACL2 ``waterfall''. Then, we describe how hints are handled by the waterfall. [31;1mThe Waterfall.[0m The ACL2 [3mwaterfall[0m is the heart of the ACL2 prover. It attempts to prove a given goal and either completes the proof, fails, or produces goals to be proved by induction or forcing rounds. The waterfall comprises a series of [3msteps[0m, such as simplification or generalization, each of which attempts to replace a given goal by zero or more subgoals whose provability implies provability of that goal. Note that every proof by induction starts a new trip through the waterfall, as does every forcing round; and these occur only after all preceding trips through the waterfall are complete. Let us see in more detail how the waterfall works. Each goal considered by the ACL2 prover passes through a series of proof processes, called the ``waterfall processes'', as stored in the constant [47m*preprocess-clause-ledge*[0m. The top process applies top-level hints, including [47m:use[0m hints; the next is a lightweight ``preprocess'' simplifier for ``simple'' rules (see [simple]); that is followed by the main ACL2 simplifier and then the ``settled-down'' process described further below; and finally ACL2 attempts (in this order) destructor elimination, fertilization (heuristic use of equalities), generalization, and elimination of irrelevance. See [architecture-of-the-prover] for more information on these processes. Each process may ``hit'', creating zero or more child goals that are each then handled at the top of the waterfall; or it may ``miss'', in which case the next process in the above sequence is considered. If all processes miss, then a ``push'' process defers the goal until it is later considered for proof by induction. When all goals have been thus handled, the goal most recently pushed for proof by induction is considered, and the process repeats. We next describe the two additional ways in which control can be returned to the top of the waterfall. When the simplification process is attempted unsuccessfully for a goal, the goal is deemed to have ``settled down''. This notion of ``settled down'' is handled, as follows, by the next waterfall process after simplification: the ``settled-down'' process. If some ancestor of the goal (possibly the goal itself) has previously settled down, then the ``settled-down'' process is deemed to have missed on the goal. Otherwise it hits on the goal, the effect being that the goal makes a new pass through all the waterfall processes. (Other processes can then notice that settling down has occurred and modify their heuristics accordingly.) For example, suppose that [47m"Goal"[0m simplifies to [47m"Subgoal 2"[0m (among others), and [47m"Subgoal 2"[0m simplifies to [47m"Subgoal 2.3"[0m (among others), which in turn is not further simplified. Then the ``settled-down'' process hits on [47m"Subgoal 2.3"[0m, but it does not hit not on any of its children or their children (and so on), because each of those has an ancestor, [47m"Subgoal 2.3"[0m, that has already been marked as ``settled-down''. The next proof process after settled-down is normally destructor elimination. However, if a computed hint is suitable (in a sense described below; also see [computed-hints], especially the discussion of [47mstable-under-simplificationp[0m), then that hint is selected as control is returned to the top of the waterfall. A subtlety is that in this case, if the most recent hit had been from settling down, then the prover ``changes its mind'' and considers that the goal has not yet settled down after all as it continues through the waterfall. Each time a goal is considered at the top of the waterfall, then before passing through the proof processes as described above, ACL2 searches for a relevant hint to select unless it has already been provided a hint in the ``[47mstable-under-simplificationp[0m'' case mentioned above. We turn now to a more thorough discussion of how hints are selected and applied. [31;1mThe handling of hints.[0m In the discussion below we will ignore forcing rounds, as each forcing round is simply treated as a new proof attempt that uses the list of hints provided at the start of the proof. When the theorem prover is called by [47m[thm][0m or [events] such as [47m[defthm][0m, [47m[defun][0m, and [47m[verify-guards][0m, it gathers up the hints that have been supplied, often provided as a [47m:[0m[47m[hints][0m argument, but for example using a [47m:guard-hints[0m argument for [guard] verification proofs. (ACL2(r) users (see [real]) may also employ [47m:std-hints[0m.) It then appends these to the front of the list of default hints (see [default-hints]). The resulting list becomes the initial value of the list of ``pending hints'', one of two critical lists maintained by the theorem prover to manage hints. The other critical list is a list of ``hint settings''; the two lists are maintained as follows. When a goal is first considered, a hint is selected from the list of pending hints if any is found to apply, as described below. If a hint is selected, then it takes effect and is removed from the pending hints. Except: if the selected hint is a computed hint with value [47mt[0m specified for [47m:computed-hint-replacement[0m, then it is not removed; and if that value is a list of hints, then that list is appended to the front of the list of pending hints after the selected hint is removed (also see [computed-hints]). The selected hint is also used to update the hint settings, as described below. The list of hint settings associates hint keywords with values. It is passed from the current goal to its children (and hence the children's children, and so on), though modified by hints selected from pending hints, as described below. This list is maintained so that when a goal is pushed for proof by induction, the hint settings are applied at the start of the proof by induction. Note that the list of hint settings is not re-applied to descendants of a goal in the current waterfall; a hint is applied only when it is selected (and also perhaps later as just described, through the stored hint settings at the start of a proof by induction). For example, if the hint selected for [47m"Subgoal 3"[0m includes [47m:in-theory (enable foo)[0m, then the hint settings are correspondingly updated when processing [47m"Subgoal 3"[0m, and they persist at subgoals such as [47m"Subgoal 3.2"[0m and [47m"Subgoal 3.2.1"[0m (unless overridden by hints on those goals); but the theory specifying [47mfoo[0m is not re-installed at every such subgoal. When a hint is selected, the list of hint settings is updated so that for each keyword [47m:kwd[0m and associated value [47mval[0m from the hint, [47m:kwd[0m is associated with [47mval[0m in the hint settings, discarding any previous association of [47m:kwd[0m with a value in the hint settings. Except, certain ``top-level'' hints are never saved in the hint settings: [47m:use[0m, [47m:cases[0m, [47m:by[0m, [47m:bdd[0m, [47m:or[0m, and [47m:clause-processor[0m. For example, suppose that we specify the following hints, with no default hints. (("Goal" :expand ((bar x y))) ("Subgoal 3" :in-theory (enable foo))) These hints then become the initial list of pending hints. When the proof attempt begins, the prover encounters the top-level goal ([47m"Goal"[0m) and pulls the [47m"Goal"[0m hint from the pending hints, so that the list of hint settings contains a value only for keyword [47m:expand[0m. This hint setting will remain for all children of the top-level goal as well, and their children, and so on, and will be inherited by induction --- in other words, it will remain throughout the entire proof. Now consider what happens when the proof reaches [47m"Subgoal 3"[0m. At this point there is only one pending hint, which is in fact attached to that subgoal. Therefore, this hint is pulled from the pending hints (leaving that list empty), and the hint settings are extended by associating the [47m:in-theory[0m keyword with the theory represented by [47m(enable foo)[0m. That theory is immediately installed until the prover finishes addressing [47m"Subgoal 3"[0m, its children, their children, and so on; and until that completion is reached, the [47m:in-theory[0m keyword remains associated with the [47m(enable foo)[0m in the hint settings, although of course there is no re-installation of the theory at any ensuing child goal. When finally [47m"Subgoal 3"[0m and its descendants have been completed and the prover is about to consider [47m"Subgoal 2"[0m, the [47m:in-theory[0m association is removed from the hint settings and the global theory is re-installed. However, the list of pending hints remains empty. It remains to describe how a hint is selected for a goal. When a goal is first considered (hence at the top of the waterfall), the list of pending hints is scanned, in order, until one of the hints is suitable for the goal. An explicit hint [47m(goal-name :kwd1 val1 ... :kwdn valn)[0m is suitable if [47mgoal-name[0m is the name of the current goal and there is at least one keyword. A computed hint is suitable if it evaluates to a non-[47mnil[0m value. As indicated earlier in this documentation topic, an exception occurs when a computed hint is selected after simplification fails (the ``[47mstable-under-simplificationp[0m'' case): in that case, the goal returns to the top of the waterfall with that hint as the selected hint, and no additional search for a hint to select is made at that time. The following slightly tricky example illustrates handling of hints. ACL2 !>(set-default-hints '(("Goal" :do-not '(preprocess)))) (("Goal" :DO-NOT '(PREPROCESS))) ACL2 !>(set-gag-mode nil) <state> ACL2 !>(thm (equal (append (append x y) z) (append x y z)) :hints (("Goal" :in-theory (disable car-cons)))) ACL2 Warning [Hints] in ( THM ...): The goal-spec "Goal" is explicitly associated with more than one hint. All but the first of these hints may be ignored. If you intended to give all of these hints, consider combining them into a single hint of the form ("Goal" :kwd1 val1 :kwd2 val2 ...). See :DOC hints and :DOC hints-and-the-waterfall; community book books/hints/merge-hint.lisp might also be helpful. [Note: A hint was supplied for the goal above. Thanks!] [Note: A hint was supplied for the goal above. Thanks!] Name the formula above *1. The warning above is printed because [47m"Goal"[0m is associated with two pending hints: one given by the [47m[set-default-hints][0m call and one supplied by the [47m:[0m[47m[hints][0m keyword of the [47m[thm][0m form. The [47m:in-theory[0m hint is selected first because user-supplied hints are ahead of default hints in the list of pending hints; we then get the first ``Note'' above. The goal progresses through the waterfall without any proof process applying to the goal; in particular, it cannot be further simplified. After the simplification process, a ``settled-down'' process applies, as discussed above, immediately causing another trip through the waterfall. Since the [47m:in-theory[0m hint was earlier removed from the list of pending hints when it was applied, the default ([47m:do-not[0m) hint is now the only pending hint. That hint is applied, resulting in the second ``Note'' above. Again, more examples may be found in the community book [47mbooks/hints/basic-tests.lisp[0m. A particularly tricky but informative example in that book is the one related to [47mnonlinearp-default-hint[0m. Also see [override-hints] for an advanced feature that allows modification of the hint selected for a goal.") (history (acl2) "Functions to display or change contents of the logical [world] ACL2 keeps track of the [command]s that you have executed that have extended the logic or the rule database, as by the definition of macros, functions, etc. Using the facilities in this section you can review the sequence of commands executed so far. For example, you can ask to see the most recently executed command (by issuing [47m:[0m[47m[pc][0m [47m:x[0m), or the preceding 10 commands (by issuing [47m:[0m[47m[pbt][0m [47m:x-10[0m), or the command that introduced a given function symbol, [47mfn[0m (by issuing [47m:pc fn[0m). You can also undo back through some previous command (see [ubt]), restoring the logical [world] to what it was before the given command. The annotations printed in the margin in response to some of these commands (including `P', `L', `V', `D', `d', 'M', and 'm') are explained in the documentation for [47m:[0m[47m[pc][0m. Several technical terms are used in the documentation of the history commands. You must understand these terms to use the commands. These terms are documented with [documentation] entries of their own. See [command], see [events], see [command-descriptor], and see [logical-name]. Subtopics [Command] Forms you type at the top-level, but... [Command-descriptor] An object describing a particular [command] typed by the user [Disable-ubt] Make it illegal to undo back through the current [command] [Enter-boot-strap-mode] The first millisecond of the Big Bang [Exit-boot-strap-mode] The end of pre-history [Extend-pe-table] Replace [events] displayed by [history] commands [Formula] The formula of a name or [rune] [Get-command-sequence] Return list of [command]s that are between two [command] descriptors [Gthm] The [guard] theorem for a given function symbol [Ld-history] Saving and querying command history [Oops] Undo a [47m:u[0m or [47m:[0m[47m[ubt][0m [Pbt] Print the [command]s back through a [command] descriptor [Pc] Print the [command] described by a [command] descriptor [Pcb] Print the [command] block described by a [command] descriptor [Pcb!] Print in full the [command] block described by a [command] descriptor [Pcs] Print the sequence of [command]s between two [command] descriptors [Pe] Print the events named by a logical name [Pe!] Print events as with [47m[pe][0m but ignoring the [pe-table] [Pf] Print the formula corresponding to the given name [Pl] Print the rules for the given name or term [Pl2] Print rule(s) for the given form [Pr] Print the rules stored by the event with the given name [Pr!] Print rules stored by the command with a given command descriptor [Puff] Replace a compound [command] by its immediate subevents [Puff*] Replace a compound [command] by its subevents [Reset-kill-ring] Save memory by resetting and perhaps resizing the kill ring used by [47m[oops][0m [Reset-prehistory] Reset the prehistory [Tau-database] To see the tau database as a (very large) object [Tthm] The [measure] (termination) theorem for a given function symbol [U] Undo last [command], without a query [Ubt] Undo the [command]s back through a [command] descriptor [Ubt!] Undo [command]s, without a query or an error [Ubt-prehistory] Undo the [command]s back through the last [47m[reset-prehistory][0m event [Ubt?] Undo [command]s, with queries as appropriate [Ubu] Undo the [command]s back up to (not including) a [command] descriptor [Ubu!] Undo [command]s, without a query or an error [Ubu?] Undo [command]s, with queries as appropriate [Undo] Undoing and perhaps redefining") (hons (programming hons-and-memoization acl2-built-ins) "[47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m. In the logic, [47mhons[0m is just [47m[cons][0m; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mhons[0m does whatever is necessary to ensure that its result is [normed]. What might this involve? Since the car and cdr of any normed cons must be normed, we need to [47m[hons-copy][0m x and y. This requires little work if x and y are already normed, but can be expensive if x or y contain large, un-normed cons structures. After that, we need to check whether any normed cons equal to [47m(x . y)[0m already exists. If so, we return it; otherwise, we need to construct a new cons for [47m(x . y)[0m and install it as the normed version of [47m(x . y)[0m. Generally speaking, these extra operations make [47mhons[0m much slower than [47mcons[0m, even when given normed arguments. [31;1mFunction: [0m<hons> (defun hons (x y) (declare (xargs :guard t)) (cons x y)) Subtopics [Hons-clear] [47m(hons-clear gc)[0m is a drastic garbage collection mechanism that clears out the underlying Hons Space. [Hons-clear!] A version of [47m[hons-clear][0m for [parallel] execution [Hons-copy] [47m(hons-copy x)[0m returns a [normed] object that is equal to X. [Hons-copy-persistent] [47m(hons-copy-persistent x)[0m returns a [normed] object that is equal to X and which will be re-normed after any calls to [47m[hons-clear][0m. [Hons-equal] [47m(hons-equal x y)[0m is a recursive equality check that optimizes when parts of its arguments are [normed]. [Hons-equal-lite] [47m(hons-equal-lite x y)[0m is a non-recursive equality check that optimizes if its arguments are [normed]. [Hons-note] Notes about [hons], especially pertaining to expensive resizing operations [Hons-resize] [47m(hons-resize ...)[0m can be used to manually adjust the sizes of the hash tables that govern which ACL2 Objects are considered [normed]. [Hons-summary] [47m(hons-summary)[0m prints basic information about the sizes of the tables in the current Hons Space. [Hons-wash] [47m(hons-wash)[0m is like [47m[gc$][0m but can also garbage collect [normed] objects (CCL and GCL Only). [Hons-wash!] A version of [47m[hons-wash][0m for [parallel] execution [Normed] Normed objects are ACL2 Objects that are "canonical" or "unique" in a certain sense.") (hons-acons (fast-alists acl2-built-ins) "[47m(hons-acons key val alist)[0m is the main way to create or extend [fast-alists]. Logically, [47mhons-acons[0m is like [47m[acons][0m except that its guard does not require [47m[alistp][0m; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, two things are done differently. First, the key is copied with [47m[hons-copy][0m; this lets us use EQL-based hash tables instead of EQUAL-based hash tables for better performance. Second, assuming there is a valid hash table associated with this alist, we destructively update the hash table by binding key to val. The hash table will no longer be associated with alist, but will instead be associated with the new alist returned by [47mhons-acons[0m. Hash Table Creation A new hash table is created by [47mhons-acons[0m whenever alist is an atom. Unlike ordinary [47macons[0m, we do not require that alist be nil, and in fact you may wish to use a non-nil value for one of two reasons. 1. As a size hint By default, the new hash table will be given a quite modest default capacity of 60 elements. As more elements are added, the table may need to be resized to accommodate them, and this resizing has some runtime cost. When a natural number is used as a fast alist's name, we interpret it as a size hint. For example, [47m(hons-acons 'foo 'bar 1000)[0m instructs us to use 1000 as the initial size for this hash table and binds 'foo to 'bar. The resulting table should not need to be resized until more than 1000 elements are added. We ignore size hints that request fewer than 60 elements. Because of hash collisions, hash tables typically need to have a larger size than the actual number of elements they contain. The hash tables for fast alists are told to grow when they reach 70% full. So, an easy rule of thumb might be: multiply the expected number of elements you need by 1.5 to keep your hash tables about 2/3 full. 2. As an alist name We also frequently use a symbol for alist, and think of this symbol as the name of the new alist. We have found that naming alists can be valuable for two reasons: First, the name can be helpful in identifying fast alists that should have been freed, see [47m[fast-alist-summary][0m. Second, names can sometimes be used to avoid a subtle and insidious table-stealing phenomenon that occurs when using fast-alists that are themselves normed; see [47m[hons-acons!][0m. At the moment, there is no way to simultaneously name a fast alist and also give it a size hint. We may eventually allow strings to include embedded name and size components, but for now we have not implemented this capability. [31;1mFunction: [0m<hons-acons> (defun hons-acons (key val alist) (declare (xargs :guard t)) (cons (cons key val) alist))") (hons-acons! (fast-alists acl2-built-ins) "[47m(hons-acons! key val alist)[0m is an alternative to [47m[hons-acons][0m that produces [normed], fast alists. Logically, [47mhons-acons![0m is like [47m[acons][0m except that its guard does not require [47m[alistp][0m; we leave it enabled and would think it odd to ever prove a theorem about it. Ordinarily, [fast-alists] are constructed with [47m[hons-acons][0m instead of [47mhons-acons![0m. In such alists, the keys are honsed, but the conses that make up the "spine" of the alist itself are ordinary conses. In other words, it is basically correct to say: (hons-acons key val alist) == (cons (cons (hons-copy key) val) alist) In contrast, when [47mhons-acons![0m is used, the conses making up the alist itself are also normed. That is, (hons-acons! key val alist) == (hons (hons key val) alist) Generally, you [31;1mshould not use[0m [47mhons-acons![0m unless you really know what you're doing. Drawback 1. [47mhons-acons![0m requires you to [47m[hons-copy][0m all of the values that are being stored in the fast alist. If you are storing large values, this may be expensive. Drawback 2. It can be more difficult to maintain the proper discipline when using [47mhons-acons![0m. For instance, consider the following: (let ((al1 (hons-acons 1 'one (hons-acons 2 'two nil))) (al2 (hons-acons 1 'one (hons-acons 2 'two nil)))) ...) Here, both al1 and al2 are valid fast alists and they can be extended independently without any trouble. But if these alists had instead been constructed with [47mhons-acons![0m, then since both al1 and al2 are equal, normed conses, they will literally be [47m[eq][0m and hence will refer to precisely the same hash table. In other words, [47mhons-acons![0m makes it relatively easy to [31;1minadvertently[0m steal the hash table associated with some other fast alist. This problem can be alleviated somewhat by uniquely naming alists; see the discussion in [47m[hons-acons][0m for details. Despite these drawbacks, [47mhons-acons![0m is the typical way to generate a fast alist that is normed (but also, for example, see [fast-alist-fork!]). It is not adequate to [47m[hons-copy][0m a fast alist that was generated by ordinary [47m[hons-acons][0m calls, because this would produce an EQUAL-but-not-EQ object, and this new object would not be associated with the fast alist's hash table. [31;1mFunction: [0m<hons-acons!> (defun hons-acons! (key val alist) (declare (xargs :guard t)) (cons (cons key val) alist))") (hons-and-memoization (acl2) "Hash cons, function memoization, and applicative hash tables This topic describes the hash cons, function memoization, and applicative hash tables features available in ACL2, sometimes called the ``[hons-enabled]'' features. Bob Boyer and Warren Hunt, and later Jared Davis and Sol Swords, have developed a canonical representation for ACL2 data objects and a function memoization mechanism to facilitate reuse of previously computed results. This facility includes procedures to read and print ACL2 expressions in such a way that repetition of some ACL2 objects is eliminated, thereby permitting a kind of on-the-fly file compression. The implementation does not alter the semantics of ACL2 except to add a handful of definitions. We historically gave the name ``ACL2(h)'' to the experimental extension of the ACL2 system including hash cons, function memoization, and fast association lists (applicative hash tables). These features, which we call the ``[hons-enabled]'' features, are now present in ACL2. The hons-enabled features are optimized for Clozure Common Lisp (CCL) and to some extent, GNU Common Lisp (GCL ANSI); but they are also supported in every ACL2 build. Power users who want to take advantage of the [hons-enabled] features of ACL2 might find it helpful to consult the document [47mcentaur/README.html[0m in the ACL2 community books. Much of the documentation for the remainder of this topic is taken from the paper ``Function Memoization and Unique Object Representation for ACL2 Functions'' by Robert S. Boyer and Warren A. Hunt, Jr., which has appeared in the Sixth International Workshop on the ACL2 Theorem Prover and Its Applications, ACM Digital Library, 2006. In the implementation of the ACL2 logic, ACL2 data objects are represented by Common Lisp objects of the same type, and the ACL2 pairing operation is internally implemented by the Common Lisp [47m[cons][0m function. In Common Lisp, [47mcons[0m is guaranteed to provide a new pair, distinct from any previously created pair. We have defined a new ACL2 function [47m[hons][0m that is logically identical to the ACL2 [47mcons[0m function, but whose implementation usually reuses an existing pair if its components are identical to the components of an existing pair. A record of ACL2 HONS objects is kept, and when an ACL2 function calls [47mhons[0m ACL2 searches for an existing identical pair before allocating a new pair; this operation been called ``hash consing''. It appears that hash consing was first conceived by A. P. Ershov in 1957, to speed up the recognition of common subexpressions. Ershov showed how to collapse trees to minimal DAGs by traversing trees bottom up, and he used hashing to eliminate the re-evaluation of common subexpressions. In his 1973 PhD dissertation L. Peter Deutsch describes a program verifier that uses hash cons to represent terms and his rewriter operated on hash consed terms. Later, Eiichi Goto implemented a Lisp system with a built-in hash consing operation: his h-CONS cells were rewrite protected and free of duplicate copies, and Goto used this hash consing operation to facilitate the implementation of a symbolic algebra system he developed. Memoizing functions also has a long history. In 1967, Donald Michie proposed using memoized functions to improve the performance of machine learning. Rote learning was improved by a learning function not forgetting what it had previously learned; this information was stored as memoized function values. The use of hash consing has appeared many times. For instance, Henry Baker used hash consing to improve the performance of the well-known Boyer rewriting benchmark. Baker used both hash consing and function memoization to improve the speed of the Takeuchi function, exactly in the spirit of our implementation, but without the automated, system-wide integration we report here. The ACL2 implementation permits memoization of user-defined functions. During execution a user may enable or disable function memoization on an individual function basis, may clear memoization tables, and may even keep a stack of memoization tables. This facility takes advantage of our implementation where we keep one copy of each distinct ACL2 data object. Due to the functional nature of ACL2, it is sufficient to have at most one copy of any data structure; thus, a user may arrange to keep data canonicalized. This implementation extends to the entire ACL2 system the benefits enjoyed by BDDs: canonicalization, memoization, and fast equality check. We have defined various algorithms using these features, and we have observed, in some cases, substantial performance increases. For instance, we have implemented unordered set intersection and union operations that operate in time roughly linear in the size of the sets. Without using arrays, we defined a canonical representation for Boolean functions using ACL2 objects. We have investigated the performance of rewriting and tree consensus algorithms to good effect, and we believe function memoization offers interesting opportunities to simplify algorithm definition while simultaneously providing performance improvements. We recommend that users focus at first on the logical definitions of [47m[hons][0m and other primitives rather than their underlying Common Lisp implementations. Integrated with this memoization system is a performance monitoring system, which can provide real-time feedback on the operation and usefulness of [47m[hons][0m and function memoization. For a more detailed description of these tools, please see the ACL2 2006 workshop paper mentioned above. The Fibonacci function is a small example that demonstrates the utility of function memoization. The following definition exhibits a runtime that is exponential in its input argument. (defun fib (x) (declare (xargs :guard (natp x))) (mbe :logic (cond ((zp x) 0) ((= x 1) 1) (t (+ (fib (- x 1)) (fib (- x 2))))) :exec (if (< x 2) x (+ (fib (- x 1)) (fib (- x 2)))))) Below we show how the ACL2 [47m[time$][0m utility can measure the time to execute a call to the [47mfib[0m function (with some editing to avoid noise from the underlying Common Lisp implementation). [47m[Memoize][0m is actually an ACL2 macro that expands to a call of the ACL2 function used to identify a function for memoization; see [memoize]. This function also accepts a well-formed term that must be true in order for the system to memoize a call of the memoized function; to ensure that an instance of the term is safe for evaluation in Common Lisp, a check is performed that if the [guard] of the memoized function is satisfied, then this instance will execute without error. ACL2 !>(time$ (fib 40)) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.99 seconds realtime, 0.98 seconds runtime ; (1,296 bytes allocated). 102334155 ACL2 !>(memoize 'fib) Summary Form: ( TABLE MEMOIZE-TABLE ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) Summary Form: ( PROGN (TABLE MEMOIZE-TABLE ...) ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) FIB ACL2 !>(time$ (fib 40)) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.00 seconds realtime, 0.00 seconds runtime ; (2,864 bytes allocated). 102334155 ACL2 !>(time$ (fib 100)) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.00 seconds realtime, 0.00 seconds runtime ; (7,024 bytes allocated). 354224848179261915075 ACL2 !>(unmemoize 'fib) We see that once the function [47mfib[0m is identified as a function for which function calls should be memoized, the execution times are substantially reduced. Finally, we can prevent [47mfib[0m from being further memoized; in fact, [47m[unmemoize][0m erases the previously memoized values. The implementation of hash consing, memoization, and applicative hash tables involves several facets: canonical representation of ACL2 data, function memoization, and the use of Lisp hash tables to improve the performance of association list operations. We discuss each of these in turn, and we mention some subtle interrelationships. Although it is not necessary to understand the discussion in this section, it may permit some users to better use this implementation. This discussion may be confusing for some ACL2 users as it makes references to Lisp implementation features. The ACL2 system is actually implemented as a Lisp program that is layered on top of a Common Lisp system implementation. ACL2 data constants are implemented with their corresponding counterparts in Common Lisp; that is, ACL2 cons pairs, strings, characters, numbers, and symbols are implemented with their specific Common Lisp counterparts. This choice permits a number of ACL2 primitive functions to be implemented with their corresponding Common Lisp functions, but there are indeed differences. ACL2 is a logic, and as such, it does not specify anything to do with physical storage or execution performance. When ACL2 is used, the knowledgeable user can write functions to facilitate the reuse of some previously computed values. Recall the three mechanisms under discussion: hash consing, function memoization, and fast association list operations. The function memoization mechanism takes advantage of the canonical representation of data objects provided by the [47m[hons][0m operation as does the fast association list operation mechanism. Each time [47mhons[0m is invoked, its arguments are themselves converted, if necessary, to uniquely represented objects. The ACL2 universe is recursively closed under the [47mcons[0m pairing operation and the atoms. Hash consing ([47m[hons][0m) is logically identical to [47mcons[0m, but a set of tables is used to record each [47mhons[0m pair. When a [47mhons[0m pair is requested, the implementation checks, in the current set of tables, whether the requested pair already exists. If not, a new pair is created and a record of that pair is made; otherwise, a reference to the previously created pair is returned. Thus, any data object created with [47mhons[0m has a unique representation, as does every subcomponent. We also arrange for strings to have a unique representation --- only one copy of each different string is kept --- and when any previously unseen string is an argument to [47mhons[0m, we add the string to a unique table of strings. A system-wide benefit of having a canonical representation for data is that equality comparisons between any two data objects can be done in constant time. The definition of [47m[hons][0m in no way changes the operation of [47mcons[0m --- [47mhons[0m creates a [47mcons[0m pair. When asked to create a [47mhons[0m, the implementation checks to see if there is a [47mcons[0m with the same [47m[car][0m and [47m[cdr][0m as the [47mhons[0m being requested. Thus, the only difference between the results of a [47mhons[0m call and a corresponding [47mcons[0m call is a notation in some invisible (to the ACL2 logic) tables where we record which [47mcons[0m elements are also [47mhons[0m elements. Since a [47mhons[0m is nothing but a [47mcons[0m, the operation of [47mcar[0m and [47mcdr[0m is unchanged. In fact, the implementation is designed so that at any time it is safe to clear the table identifying which [47mcons[0m elements are also considered [47mhons[0m elements. User-defined functions with defined and verified guards can be memoized. When a function is memoized, a user-supplied condition restricts the domain when memoization is attempted. When the condition is satisfied, memoization is attempted (assuming that memoization for the function is presently enabled); otherwise, the function is just evaluated. Each memoized function has a hash table that is used to keep track of a unique list of function arguments paired with their values. If appropriate, for each function the corresponding table is checked to see if a previous call with exactly the same arguments already exists in the table: if so, then the associated value is returned; if not, then the function is evaluated and a new key-value pair is added to the table of memoized values so that some future call will benefit from the memoization. With ACL2 user functions memoization can be dynamically enabled and disabled. There is an ACL2 function that clears a specific memoization table. And finally, just as with the [47mhons[0m table, a stack of these function memoization tables is maintained; that is, it is possible to memoize a function, use it a bit, set the memoized values aside, start a new table, use it, and then return to the original table. We next discuss the fast lookup operation for association lists. When a pair is added to an association list using the functions [47m[hons-acons][0m or [47m[hons-acons!][0m, the system also records the key-value pair in an associated hash table. As long as a user only used these two functions when placing key-value pairs on an association list, the key-value pairs in the corresponding hash table will be synchronized with the key-value pairs in the association list. Later, if [47m[hons-get][0m is used to look up a key, then instead of performing a linear search of the association list we consult the associated hash table. If a user does not strictly follow this discipline, then a linear search may be required. In some sense, these association lists are much like ACL2 arrays, but without the burden of explicitly naming the arrays. The ACL2 array [47m[compress1][0m function is analogous to the functions [47m[fast-alist-clean][0m and [47m[fast-alist-clean!][0m. There are user-level ACL2 functions that allow the associated hash tables to be cleared and removed. As mentioned above, the [hons-enabled] features are optimized for CCL and GCL. See [ccl-updates] for easy instructions for obtaining the latest version of CCL. REFERENCES Baker, Henry G., The Boyer Benchmark at Warp Speed. ACM Lisp Pointers V,3 (Jul-Sep 1992), pages 13-14. Baker, Henry G., A Tachy 'TAK'. ACM Lisp Pointers Volume 3, July-September, 1992, pages 22-23. Robert S. Boyer and Warren A. Hunt, Jr., Function Memoization and Unique Object Representation for ACL2 Functions, in the Sixth International Workshop on the ACL2 Theorem Prover and Its Applications, ACM Digital Library, 2006. L.P. Deutsch. An Interactive Program Verifier. Tech. Rept. CSL-73-1, Xerox Palo Alto Research Center, May, 1973. A. P. Ershov. On Programming of Arithmetic Operations. In the Communications of the ACM, Volume 118, Number 3, August, 1958, pages 427-430. Eiichi Goto, Monocopy and Associative Algorithms in Extended Lisp, TR-74-03, University of Tokyo, 1974. Richard P. Gabriel. Performance and Evaluation of Lisp Systems. MIT Press, 1985. Donald Michie. Memo functions: a Language Feature with Rote Learning Properties. Technical Report MIP-R-29, Department of Artificial Intelligence, University of Edinburgh, Scotland, 1967. Donald Michie. Memo Functions and Machine Learning. In Nature, Volume 218, 1968, pages 19-22. Subtopics [Fast-alists] Alists with hidden hash tables for faster execution [Hons] [47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m. [Hons-enabled] Hash cons, function memoization, and applicative hash tables [Memoize] Turn on memoization for a specified function [Number-subtrees] [47m(number-subtrees x)[0m returns the number of distinct subtrees of X, in the sense of [47m[equal][0m [Unmemoize] Turn off memoization for the specified function") (hons-assoc-equal (fast-alists acl2-built-ins) "[47m(hons-assoc-equal key alist)[0m is [31;1mnot fast[0m; it serves as the logical definition for [47m[hons-get][0m. The definition of [47mhons-assoc-equal[0m is similar to that of [47m[assoc-equal][0m, except that (1) it does not require [47m[alistp][0m as a guard, and (2) it "skips over" any non-conses when its alist argument is malformed. We typically leave [47mhons-get[0m enabled and reason about [47mhons-assoc-equal[0m instead. One benefit of this approach is that it avoids certain "false" discipline warnings that might arise from execution during theorem proving. [31;1mFunction: [0m<hons-assoc-equal> (defun hons-assoc-equal (key alist) (declare (xargs :guard t)) (cond ((atom alist) nil) ((and (consp (car alist)) (hons-equal key (caar alist))) (car alist)) (t (hons-assoc-equal key (cdr alist)))))") (hons-clear (hons acl2-built-ins) "[47m(hons-clear gc)[0m is a drastic garbage collection mechanism that clears out the underlying Hons Space. Logically, [47mhons-clear[0m just returns nil; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mhons-clear[0m brutally (1) clears all the tables that govern which conses are [normed], then (2) optionally garbage collects, per the [47mgc[0m argument, then finally (3) re-norms the keys of [47m[fast-alists][0m and persistently normed conses; see [hons-copy-persistent]. Notes. * The hash tables making up the Hons Space retain their sizes after being cleared. If you want to shrink them, see [47m[hons-resize][0m. * CCL and GCL users might prefer [47m[hons-wash][0m, which is relatively efficient and allows for the garbage collection of normed conses without impacting their normed status. * It is not recommended to interrupt this function. Doing so may cause persistently normed conses and fast alist keys to become un-normed, which might lead to less efficient re-norming and/or violations of the fast-alist discipline. * (For ACL2(p) users only; see [parallelism]) If parallel execution is enabled (see [set-parallel-execution]), as it is by default in ACL2(p), then [47mhons-clear[0m may be a no-op (other than to print a warning), in order to avoid thread-unsafe behavior. (However, In CCL you are unlikely to see this restriction unless you are running more than one thread.) To get around this restriction, you can instead use [47m[hons-clear!][0m, which however requires a [trust-tag]. [31;1mFunction: [0m<hons-clear> (defun hons-clear (gc) (declare (xargs :guard t)) (declare (ignore gc)) nil)") (hons-clear! (hons acl2-built-ins) "A version of [47m[hons-clear][0m for [parallel] execution This function is only of interest to ACL2(p) users; see [parallelism], because for ACL2 it suffices to use [47m[hons-clear][0m. However, if parallel execution is enabled (see [set-parallel-execution]), as it is by default in ACL2(p), then [47mhons-clear[0m may be a no-op (other than to print a warning), in order to avoid thread-unsafe behavior. If you are not concerned about thread safety, for example when you want to call [47mhons-clear[0m directly in the top-level loop, you can use [47mhons-clear![0m, which does not check for parallelism violations. However, [47mhons-clear![0m requires a trust tag; see [defttag].") (hons-copy (hons acl2-built-ins) "[47m(hons-copy x)[0m returns a [normed] object that is equal to X. In the logic, [47mhons-copy[0m is just the identity function; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mhons-copy[0m does whatever is necessary to produce a [normed] version of X. What might this involve? If X is a symbol, character, or number, then it is already normed and nothing is done. If X is a string, we check if any normed version of X already exists. If so, we return the already-normed version; otherwise, we install X as the normed version for all strings that are [47m[equal][0m to X. If X is a cons, we must determine if there is a normed version of X, or recursively construct and install one. Norming large cons trees can become expensive, but there are a couple of cheap cases. In particular, if X is already normed, or if large subtrees of X are already normed, then not much needs to be done. The slowest case is norming some large ACL2 cons structure that has no subtrees which are already normed. Note that running [47mhons-copy[0m on an object that was created with [47m[cons][0m is often slower than just using [47m[hons][0m directly when constructing the object. [31;1mFunction: [0m<hons-copy> (defun hons-copy (x) (declare (xargs :guard t)) x)") (hons-copy-persistent (hons acl2-built-ins) "[47m(hons-copy-persistent x)[0m returns a [normed] object that is equal to X and which will be re-normed after any calls to [47m[hons-clear][0m. Logically [47mhons-copy-persistent[0m is the identity; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mhons-copy-persistent[0m is virtually identical to [47m[hons-copy][0m. The only difference is that when [47m[hons-clear][0m is used, any persistently normed conses are automatically re-normed, and this re-norming can be carried out more efficiently than, say, an ordinary [47m[hons-copy][0m. [31;1mFunction: [0m<hons-copy-persistent> (defun hons-copy-persistent (x) (declare (xargs :guard t)) x)") (hons-enabled (hons-and-memoization) "Hash cons, function memoization, and applicative hash tables ACL2 supports hash cons, function memoization, and applicative hash tables; see [hons-and-memoization]. These are sometimes called the ``hons-enabled features'' of ACL2.") (hons-equal (hons equal acl2-built-ins) "[47m(hons-equal x y)[0m is a recursive equality check that optimizes when parts of its arguments are [normed]. In the logic, [47mhons-equal[0m is just [47m[equal][0m; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, when [47mhons-equal[0m encounters two arguments that are both normed, it becomes a mere [47m[eql][0m check, and hence avoids the overhead of recursively checking large cons structures for equality. Note. If [47mhons-equal[0m is given arguments that do not contain many normed objects, it can actually be much slower than [47m[equal][0m! This is because it checks to see whether its arguments are normed at each recursive step, and so you are repeatedly paying the price of such checks. Also see [hons-equal-lite], which only checks at the top level whether its arguments are normed. [31;1mFunction: [0m<hons-equal> (defun hons-equal (x y) (declare (xargs :guard t)) (equal x y)) Subtopics [Hons-equal-lite] [47m(hons-equal-lite x y)[0m is a non-recursive equality check that optimizes if its arguments are [normed].") (hons-equal-lite (hons hons-equal) "[47m(hons-equal-lite x y)[0m is a non-recursive equality check that optimizes if its arguments are [normed]. In the logic, [47mhons-equal-lite[0m is just [47m[equal][0m; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mhons-equal-lite[0m checks whether its arguments are normed, and if so it effectively becomes a [47m[eql][0m check. Otherwise, it immediately calls [47m[equal][0m to determine if its arguments are equal. The idea here is to strike a useful balance between [47mequal[0m and [47m[hons-equal][0m. If both arguments happen to be normed, we get to use a very fast equality comparison. Otherwise, we just get out of the way and let [47mequal[0m do its work, without the extra overhead of recursively checking whether the subtrees of x and y are normed. [31;1mFunction: [0m<hons-equal-lite> (defun hons-equal-lite (x y) (declare (xargs :guard t)) (equal x y))") (hons-get (fast-alists acl2-built-ins) "[47m(hons-get key alist)[0m is the efficient lookup operation for [fast-alists]. Logically, [47mhons-get[0m is just an alias for [47m[hons-assoc-equal][0m; we typically leave it enabled and prefer to reason about [47mhons-assoc-equal[0m instead. One benefit of this approach is that it helps to avoids "false" discipline warnings that might arise from execution during theorem proving. Under the hood, when [47malist[0m is a fast alist that is associated with a valid hash table, [47mhons-get[0m first norms [47mkey[0m using [47m[hons-copy][0m, then becomes a [47mgethash[0m operation on the hidden hash table. Otherwise [47mhons-get[0m simply invokes [47m[hons-assoc-equal][0m, which is similar (in definition and in performance) to [47m[assoc-equal][0m, on [47mkey[0m and [47malist[0m. [31;1mFunction: [0m<hons-get> (defun hons-get (key alist) (declare (xargs :guard t)) (hons-assoc-equal key alist))") (hons-note (hons) "Notes about [hons], especially pertaining to expensive resizing operations Certain ``Hons-Notes'' are printed to the terminal to report implementation-level information about the management of [hons] structures. Some of these may be low-level and of interest mainly to system developers. But below we discuss what users can learn from a particular hons-note, ``ADDR-LIMIT reached''. In short: If you are seeing a lot of such hons-notes, then you may be using a lot of memory. (Maybe you can reduce that memory; for certain BDD operations, for example (as defined in community books [47mbooks/centaur/ubdds/[0m), variable ordering can make a big difference.) By way of background: The ADDR-HT is the main hash table that lets us look up [normed] conses, i.e., [hons]es. It is an ordinary Common Lisp hash table, so when it starts to get too full the Lisp will grow it. It can get really big. (It has been seen to take more than 10 GB of memory just for the hash table's array, not to mention the actual conses!) Hons-Notes may be printed when the ADDR-HT is getting really full. This growth can be expensive and can lead to memory problems. Think about what it takes to resize a hash table: (1) allocate a new, bigger array (2) rehash elements, copying them into the new array (3) free the old array Until you reach step (3) and a garbage collection takes place, you have to have enough memory to have both the old and new arrays allocated. If the old array was 10 GB and we want to allocate a new one that's 15 GB, this can get pretty bad. Also, rehashing the elements is expensive time-wise when there are lots of elements. Since resizing a hash table is expensive, we want to avoid it. There's a [47m[hons-resize][0m command for this. You may want your books to start with something like the following. (value-triple (set-max-mem (* 30 (expt 2 30)))) ; 30 GB heap (value-triple (hons-resize :addr-ht #u_100_000_000)) ; 100M honses Basically, if you roughly know how many honses your book will need, you can just get them up front and then never to resize. The Hons-Notes about ``ADDR-LIMIT reached'' are basically there to warn you that the ADDR-HT is being resized. This can help you realize that your [47m[hons-resize][0m command had too small of an ADDR-HT size, or might suggest that your book should have a [47m[hons-resize][0m command. There are also commands like [47m([0m[47m[hons-summary][0m[47m)[0m, [set-max-mem], and defined in community book [47mbooks/centaur/misc/memory-mgmt-logic.lisp[0m, [47m(hons-analyze-memory nil)[0m. These can show you how many honses you currently have, how much space they are taking, and that sort of thing. (A nice trick is to call [47m[hons-summary][0m at the end of a book, to get an idea of how many honses you should ask for in your [47m[hons-resize][0m command).") (hons-resize (hons acl2-built-ins) "[47m(hons-resize ...)[0m can be used to manually adjust the sizes of the hash tables that govern which ACL2 Objects are considered [normed]. General form: (hons-resize [:str-ht size] [:nil-ht size] [:cdr-ht size] [:cdr-ht-eql size] [:addr-ht size] [:other-ht size] [:sbits size] [:fal-ht size] [:persist-ht size]) Example: (hons-resize :str-ht 100000 :addr-ht (expt 2 27)) Logically, [47mhons-resize[0m just returns nil; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, [47mhons-resize[0m can be used to change the sizes of certain hash tables in the Hons Space. All arguments are optional. The size given to each argument should either be nil (the default) or a natural number. A natural number indicates the newly desired size for the hash table, whereas nil means "don't resize this table." Any non-natural argument is regarded as nil. You may wish to call this function for two reasons. 1. Improving Performance by Resizing Up Since the hash tables in the Hons Space automatically grow as new objects are normed, [47mhons-resize[0m is unnecessary. But automatic growth can be slow because it is incremental: a particular hash table might be grown dozens of times over the course of your application. Using [47mhons-resize[0m to pick a more appropriate initial size may help to reduce this overhead. 2. Reducing Memory Usage by Resizing Down Resizing can also be used to shrink the hash tables. This might possibly be useful immediately after a [47m[hons-clear][0m to free up memory taken by the hash tables themselves. (Of course, the tables will grow again as you create new normed objects.) Advice for using [47mhons-resize[0m. Note that hash tables that are already close to the desired size, or which have too many elements to fit into the desired size, will not actually be resized. This makes resizing relatively "safe." Note that the [47m[hons-summary][0m function can be used to see how large and how full your hash tables are. This may be useful in deciding what sizes you want to give to [47mhons-resize[0m. Note that [47mhons-resize[0m operates by (1) allocating new hash tables, then (2) copying everything from the old hash table into the new table. Because of this, for best performance you should ideally call it when the hash tables involved are minimally populated, i.e., at the start of your application, or soon after a [47m[hons-clear][0m.") (hons-shrink-alist (fast-alist-fork acl2-built-ins) "Deprecated feature Deprecated. Alias for [47m[fast-alist-fork][0m.") (hons-shrink-alist! (fast-alist-fork! acl2-built-ins) "Deprecated feature Deprecated. Alias for [47m[fast-alist-fork!][0m.") (hons-summary (hons acl2-built-ins) "[47m(hons-summary)[0m prints basic information about the sizes of the tables in the current Hons Space. Logically, [47mhons-summary[0m just returns nil; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, this function gathers and prints some basic information about the sizes of the tables in the Hons Space. This information may be useful for deciding if you want to garbage collect using functions such as [47m[hons-clear][0m or [47m[hons-wash][0m. It may also be useful for determining good initial sizes for the Hons Space hash tables for your particular computation; see [hons-resize]. For information about [fast-alists], see [fast-alist-summary]. [31;1mFunction: [0m<hons-summary> (defun hons-summary nil (declare (xargs :guard t)) nil)") (hons-wash (hons acl2-built-ins) "[47m(hons-wash)[0m is like [47m[gc$][0m but can also garbage collect [normed] objects (CCL and GCL Only). Logically, [47mhons-wash[0m just returns nil; we leave it enabled and would think it odd to ever prove a theorem about it. Under the hood, in CCL and GCL, [47mhons-wash[0m runs a garbage collection after taking special measures to allow normed conses to be collected. In Lisps other than CCL, [47mhons-wash[0m does nothing. This is because the efficient implementation of [47mhons-wash[0m is specific to the "static honsing" scheme which requires CCL-specific features. Why is this function needed? Ordinarily, it is not possible to garbage collect any normed conses. This is because the Hons Space includes pointers to any normed conses, and hence Lisp's garbage collector thinks these objects are live. To correct for this, [47mhons-wash[0m (1) clears out these pointers, (2) runs a garbage collection, then (3) re-norms any previously-normed conses which have survived the garbage collection. Notes. * It is not recommended to interrupt this function. Doing so may cause persistently normed conses and fast alist keys to become un-normed, which might lead to less efficient re-norming and/or violations of the fast-alist discipline. * (For ACL2(p) users only; see [parallelism]) If parallel execution is enabled (see [set-parallel-execution]), as it is by default in ACL2(p), then [47mhons-wash[0m may be a no-op (other than to print a warning), in order to avoid thread-unsafe behavior. (However, In CCL you are unlikely to see this restriction unless you are running more than one thread.) To get around this restriction, you can instead use [47m[hons-wash!][0m, which however requires a [trust-tag]. [31;1mFunction: [0m<hons-wash> (defun hons-wash nil (declare (xargs :guard t)) nil)") (hons-wash! (hons acl2-built-ins) "A version of [47m[hons-wash][0m for [parallel] execution This function is only of interest to ACL2(p) users; see [parallelism], because for ACL2 it suffices to use [47m[hons-wash][0m. However, if parallel execution is enabled (see [set-parallel-execution]), as it is by default in ACL2(p), then [47mhons-wash[0m may be a no-op (other than to print a warning), in order to avoid thread-unsafe behavior. If you are not concerned about thread safety, for example when you want to call [47mhons-wash[0m directly in the top-level loop, you can use [47mhons-wash![0m, which does not check for parallelism violations. However, [47mhons-wash![0m requires a trust tag; see [defttag].") (how-to-contribute (about-acl2 community) "Guide to contributing code to ACL2. The main way to contribute code to ACL2 is to open a pull request (PR) to the {ACL2 GitHub repository | https://github.com/acl2/acl2}. First create a personal fork of the repository and commit your changes/additions there. Then open a PR to merge your changes into the main ACL2 repository. Please ensure your PR follows these guidelines: Required: Make Changes Only Within the [47mbooks/[0m Directory While the community is invited to submit contributions to the Community Books (see [COMMUNITY-BOOKS]), source files outside of the [47mbooks/[0m directory should not be modified, except by system maintainers. Suggestions for system changes can be emailed to {Matt Kaufmann | mailto:kaufmann@cs.utexas.edu}. (Prospective system developers should see the [developers-guide].) New developments that do not clearly belong in an existing directory are often put into the [47mprojects[0m subdirectory of [47mbooks/[0m. Required: Avoid Problematic Constructs Avoid introducing code that may fail on machines/environments other than your own. In particular, avoid the following: * Dependence on any files not included in your PR. In particular, any book that depends on an external tool, such as an SMT solver, should include an appropriate [build::cert_param]. * Dependence on environment variables that will not be set in other users' environments. * Use of absolute pathnames (e.g., mentions of your home directory). These are likely to cause problems for other users. To bring in other Community Books, use the [47m:dir :system[0m option of [47m[include-book][0m. * Constructs with timeouts that cause proof attempts to be aborted after a short time. These may cause failures on slower or heavily loaded machines. Required: Check the Build Before making your PR, you should run a regression to ensure that your changes/additions do not break the build. To do so, run the following [47mmake[0m command in the ``books'' directory: make -j 8 regression (Note: the [47m-j 8[0m option in the above command is only illustrative. It instructs [47mmake[0m to use 8 hardware threads. You may use a higher or lower number to align with your system. See [books-certification] for an extended discussion on community book certification.) Required: Change the Base Branch of your PR to [47mtesting[0m When opening your PR to merge changes into the main ACL2 repository, set the base branch to the [47mtesting[0m branch (or similar) ([3mnot[0m the [47mmaster[0m branch). Once your PR is accepted into the [47mtesting[0m branch, it will be tested and merged automatically into the [47mmaster[0m branch if all tests pass. Suggested: Follow Best Practices for ACL2 Code See best-practices for recommended code practices. Suggested: Document Your New Books Consider creating documentation using the [47m[xdoc][0m system. Then, to ensure your new topics appear in the manual, ensure they are included by [47mbooks/doc/top.lisp[0m, perhaps via another book that it includes, such as [47mbooks/projects/top-doc.lisp[0m. Suggested: Update the Release Notes Consider adding some high-level information about your changes to the Community Books' release notes --- i.e., the appropriate [release-notes-books] XDOC topic in [47mbooks/doc/relnotes.lisp[0m. Resources for Git/GitHub For those new to Git (the version control system) or GitHub (the platform on which the ACL2 Git repository is hosted), see [git-quick-start]. Frequent Contributors Frequent contributors may request to join the {ACL2 GitHub project | https://github.com/acl2/acl2}. Such contributors may push directly to various testing branches without opening a PR (although it is still good practice to open a PR when modifying a widely used book or one primarily authored by someone else). To request to join the project, email one of the following individuals: * Eric Smith ([47meric.smith@kestrel.edu[0m) * David Rager ([47mragerdl@gmail.com[0m) * Sol Swords ([47msswords@gmail.com[0m) See also the [community] topic for other ways to connect with the ACL2 community, and ways to get help.") (|HOW_LONG_DOES_IT_TAKE_TO_BECOME_AN_EFFECTIVE_USER{Q}| (pages_written_especially_for_the_tours) "How Long Does It Take to Become an Effective User? {IMAGE} (see [Other_Requirements]) We expect that a talented undergraduate majoring in computer science (or perhaps mathematics) will probably take several weeks to become an effective ACL2 user. The time will depend, of course, on that student's familiarity with logic (or formal methods) and Lisp programming, as well as willingness to read and study the ACL2 User's Manual. Of course, it is critical to do some projects in order to gain proficiency. (Hence access to an ACL2 implementation is also a requirement, for example by downloading and installing following links from the ACL2 home page.) But it is critical to start with ``toy'' projects before tackling a ``grand challenge.'' {IMAGE} (see [Other_Requirements])") (how_to_find_out_about_acl2_functions (pages_written_especially_for_the_tours) "How To Find Out about ACL2 Functions {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions_{cont}]) Most ACL2 primitives are documented. Here is the definition of [47mapp[0m again, with the documented topics highlighted. {ICON} (see [A_Tiny_Warning_Sign]) All of the links below lead into the ACL2 User's Manual. So follow these links if you wish, but use your [31;1mBack Button[0m to return here! ([defun] app (x y) ([cond] (([endp] x) y) (t ([cons] ([car] x) (app ([cdr] x) y))))) By following the link on [endp] {ICON} (see [A_Tiny_Warning_Sign]) we see that it is a Common Lisp function and is defined to be the same as [atom] {ICON} (see [A_Tiny_Warning_Sign]), which recognizes non-conses. But [47mendp[0m has a guard. Since we are ignoring guards for now, we'll ignore the guard issue on [47mendp[0m. So this definition reads ``to [47mapp[0m [47mx[0m and [47my[0m: if [47mx[0m is an atom, return [47my[0m; otherwise, [47mapp[0m [47m(cdr x)[0m and [47my[0m and then cons [47m(car x)[0m onto that.'' {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions_{cont}])") (|HOW_TO_FIND_OUT_ABOUT_ACL2_FUNCTIONS_{CONT}| (pages_written_especially_for_the_tours) "How To Find Out about ACL2 Functions (cont) {IMAGE} (see [The_Admission_of_App]) The ACL2 documentation is also available in Emacs, via the ACL2-Doc browser (see [ACL2-Doc]) {ICON} (see [A_Tiny_Warning_Sign]), allowing you to explore the hyperlinked documentation in the comfort of a text editor that can also interact with ACL2. In addition, runtime images of ACL2 have the hyperlinked text as a large ACL2 data structure that can be explored with ACL2's [31;1m:doc[0m command. If you have ACL2 running, try the command [31;1m:doc endp[0m. Another way to find out about ACL2 functions, if you have an ACL2 image available, is to use the command [47m:[0m[47m[args][0m {ICON} (see [A_Tiny_Warning_Sign]) which prints the formals, type, and guard of a function symbol. Of course, the ACL2 documentation can also be printed out as a very long book but we do not recommend that! See the ACL2 Home Page to download the Postscript. Now let's continue with [47mapp[0m. {IMAGE} (see [The_Admission_of_App])") (i-am-here (ld) "A convenient marker for use with [47m[rebuild][0m or [47m[ld][0m Example Input File for Rebuild: (defun fn1 (x y) ...) (defthm lemma1 ...) (defthm lemma2 ...) (i-am-here) The following lemma won't go through. I started typing the hint but realized I need to prove a lemma first. See the failed proof attempt in foo.bar. I'm going to quit for the night now and resume tomorrow from home. (defthm lemma3 ... :hints (("Goal" :use (:instance ??? ... By putting an [47m(i-am-here)[0m form at the ``frontier'' of an evolving file of [command]s, you can use [47m[rebuild][0m to load the file up to the [47m(i-am-here)[0m. [47mI-am-here[0m simply returns an [error-triple] that indicates an error, and any form that ``causes an error'' will do the same job. Note that the text of the file after the [47m(i-am-here)[0m need not be machine readable.") (i-close (real) "ACL2(r) test for whether two numbers are infinitesimally close [47m(I-close x y)[0m is true if and only if [47mx-y[0m is an infinitesimal number. This predicate is only defined in ACL2(r) (see [real]).") (i-large (real) "ACL2(r) recognizer for infinitely large numbers [47m(I-large x)[0m is true if and only if [47mx[0m is non-zero and [47m1/x[0m is an infinitesimal number. This predicate is only defined in ACL2(r) (see [real]).") (i-limited (real) "ACL2(r) recognizer for limited numbers [47m(I-limited x)[0m is true if and only if [47mx[0m is a number that is not infinitely large. This predicate is only defined in ACL2(r) (see [real]).") (i-small (real) "ACL2(r) recognizer for infinitesimal numbers [47m(I-small x)[0m is true if and only if [47mx[0m is an infinitesimal number (possibly 0). This predicate is only defined in ACL2(r) (see [real]).") (identity (basics acl2-built-ins) "The identity function [47m(Identity x)[0m equals [47mx[0m; what else can we say? [47mIdentity[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<identity> (defun identity (x) (declare (xargs :guard t)) x)") (if (basics acl2-built-ins) "If-then-else function [47m(if x y z)[0m is equal to [47my[0m if [47mx[0m is any value other than [47mnil[0m, and is equal to [47mz[0m if [47mx[0m is [47mnil[0m. Only one of [47my[0m, [47mz[0m is evaluated when [47m(if x y z)[0m is evaluated. [47mIf[0m has a [guard] of [47mt[0m. [47mIf[0m is part of Common Lisp. See any Common Lisp documentation for more information.") (if* (bdd) "For conditional rewriting with BDDs The function [47mIF*[0m is defined to be [47m[if][0m, but it is used in a special way by ACL2's [bdd] package. [31;1mFunction: [0m<if*> (defun if* (x y z) (if x y z)) As explained elsewhere (see [bdd-algorithm]), ACL2's [bdd] algorithm gives special treatment to [term]s of the form [47m(IF* TEST TBR FBR)[0m. In such cases, the algorithm simplifies [47mTEST[0m first, and the result of that simplification must be a constant (normally [47mt[0m or [47mnil[0m, but any non-[47mnil[0m explicit value is treated like [47mt[0m here). Otherwise, the algorithm aborts. Thus, [47mIF*[0m may be used to implement a sort of conditional rewriting for ACL2's [bdd] package, even though this package only nominally supports unconditional rewriting. The following contrived example should make this point clear. Suppose that we want to prove that [47m(nthcdr (length x) (append x y))[0m is equal to [47my[0m, but that we would be happy to prove this only for lists having length 4. We can state such a theorem as follows. (let ((x (list x0 x1 x2 x3))) (equal (nthcdr (length x) (append x y)) y)) If we want to prove this formula with a [47m:[0m[47m[bdd][0m hint, then we need to have appropriate rewrite rules around. First, note that [47mLENGTH[0m is defined as follows (try [47m:[0m[47m[pe][0m [47m[length][0m): (length x) = (if (stringp x) (len (coerce x 'list)) (len x)) Since [bdd]-based rewriting is merely very simple unconditional rewriting (see [bdd-algorithm]), we expect to have to prove a rule reducing [47m[stringp][0m of a [47m[cons][0m: (defthm stringp-cons (equal (stringp (cons x y)) nil)) Now we need a rule to compute the [47mLEN[0m of [47mX[0m, because the definition of [47mLEN[0m is recursive and hence not used by the [bdd] package. (defthm len-cons (equal (len (cons a x)) (1+ (len x)))) We imagine this rule simplifying [47m(LEN (LIST X0 X1 X2 X3))[0m in terms of [47m(LEN (LIST X1 X2 X3))[0m, and so on, and then finally [47m(LEN nil)[0m should be computed by execution (see [bdd-algorithm]). We also need to imagine simplifying [47m(APPEND X Y)[0m, where still [47mX[0m is bound to [47m(LIST X0 X1 X2 X3)[0m. The following two rules suffice for this purpose (but are needed, since [47m[append][0m, actually [47m[binary-append][0m, is recursive). (defthm append-cons (equal (append (cons a x) y) (cons a (append x y)))) (defthm append-nil (equal (append nil x) x)) Finally, we imagine needing to simplify calls of [47m[nthcdr][0m, where the first argument is a number (initially, the length of [47m(LIST X0 X1 X2 X3)[0m, which is 4). The second lemma below is the traditional way to accomplish that goal (when not using BDDs), by proving a conditional rewrite rule. (The first lemma is only proved in order to assist in the proof of the second lemma.) (defthm fold-constants-in-+ (implies (and (syntaxp (quotep x)) (syntaxp (quotep y))) (equal (+ x y z) (+ (+ x y) z)))) (defthm nthcdr-add1-conditional (implies (not (zp (1+ n))) (equal (nthcdr (1+ n) x) (nthcdr n (cdr x))))) The problem with this rule is that its hypothesis makes it a conditional [rewrite] rule, and conditional rewrite rules are not used by the [bdd] package. (See [bdd-algorithm] for a discussion of ``BDD rules.'') (Note that the hypothesis cannot simply be removed; the resulting formula would be false for [47mn = -1[0m and [47mx = '(a)[0m, for example.) We can solve this problem by using [47mIF*[0m, as follows; comments follow. (defthm nthcdr-add1 (equal (nthcdr (+ 1 n) x) (if* (zp (1+ n)) x (nthcdr n (cdr x))))) How is [47mnthcdr-add1[0m applied by the [bdd] package? Suppose that the [bdd] computation encounters a [term] of the form [47m(NTHCDR (+ 1 N) X)[0m. Then the [bdd] package will apply the [rewrite] rule [47mnthcdr-add1[0m. The first thing it will do when attempting to simplify the right hand side of that rule is to attempt to simplify the term [47m(ZP (1+ N))[0m. If [47mN[0m is an explicit number (which is the case in the scenario we envision), this test will reduce (assuming the executable-counterparts of [47m[zp][0m and [47m[binary-+][0m are [enable]d) to [47mt[0m or to [47mnil[0m. In fact, the lemmas above (not including the lemma [47mnthcdr-add1-conditional[0m) suffice to prove our goal: (thm (let ((x (list x0 x1 x2 x3))) (equal (nthcdr (length x) (append x y)) y)) :hints (("Goal" :bdd (:vars nil)))) If we execute the following form that disables the definition and executable-counterpart of the function [47m[zp][0m (in-theory (disable zp (zp))) before attempting the proof of the theorem above, we can see more clearly the point of using [47mIF*[0m. In this case, the prover makes the following report. ACL2 Error in ( THM ...): Unable to resolve test of IF* for term (IF* (ZP (+ 1 N)) X (NTHCDR N (CDR X))) under the bindings ((X (CONS X0 (CONS X1 (CONS X2 #)))) (N '3)) -- use SHOW-BDD to see a backtrace. If we follow the advice above, we can see rather clearly what happened. See [show-bdd]. ACL2 !>(show-bdd) BDD computation on Goal yielded 21 nodes. ------------------------------ BDD computation was aborted on Goal, and hence there is no falsifying assignment that can be constructed. Here is a backtrace of calls, starting with the top-level call and ending with the one that led to the abort. See :DOC show-bdd. (LET ((X (LIST X0 X1 X2 X3))) (EQUAL (NTHCDR (LENGTH X) (APPEND X Y)) Y)) alist: ((Y Y) (X3 X3) (X2 X2) (X1 X1) (X0 X0)) (NTHCDR (LENGTH X) (APPEND X Y)) alist: ((X (LIST X0 X1 X2 X3)) (Y Y)) (IF* (ZP (+ 1 N)) X (NTHCDR N (CDR X))) alist: ((X (LIST* X0 X1 X2 X3 Y)) (N 3)) ACL2 !> Each of these term-alist pairs led to the next, and the test of the last one, namely [47m(ZP (+ 1 N))[0m where [47mN[0m is bound to [47m3[0m, was not simplified to [47mt[0m or to [47mnil[0m. What would have happened if we had used [47m[if][0m in place of [47mIF*[0m in the rule [47mnthcdr-add1[0m? In that case, if [47mZP[0m and its [executable-counterpart] were disabled then we would be put into an infinite loop! For, each time a term of the form [47m(NTHCDR k V)[0m is encountered by the BDD package (where k is an explicit number), it will be rewritten in terms of [47m(NTHCDR k-1 (CDR V))[0m. We would prefer that if for some reason the term [47m(ZP (+ 1 N))[0m cannot be decided to be [47mt[0m or to be [47mnil[0m, then the BDD computation should simply abort. Even if there were no infinite loop, this kind of use of [47mIF*[0m is useful in order to provide feedback of the form shown above whenever the test of an [47mIF[0m term fails to simplify to [47mt[0m or to [47mnil[0m.") (if-intro (pointers) "See [splitter].") (iff (basics acl2-built-ins) "Logical ``if and only if'' [47mIff[0m is the ACL2 biconditional, ``if and only if''. [47m(iff P Q)[0m means that either [47mP[0m and [47mQ[0m are both false (i.e., [47mnil[0m) or both true (i.e., not [47mnil[0m). [31;1mFunction: [0m<iff> (defun iff (p q) (declare (xargs :guard t)) (if p (if q t nil) (if q nil t)))") (ifix (numbers acl2-built-ins) "Coerce to an integer [47mIfix[0m simply returns any integer argument unchanged, returning [47m0[0m on a non-integer argument. Also see [nfix], see [rfix], see [realfix] and see [fix] for analogous functions that coerce to a natural number, a rational number, a real, and a number, respectively. [47mIfix[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<ifix> (defun ifix (x) (declare (xargs :guard t)) (if (integerp x) x 0))") (ignorable (pointers) "See [declare].") (ignore (pointers) "See [declare].") (ignored-attachment (defattach defconst defmacro defpkg) "Why attachments are sometimes not used Attachments provide a way to execute constrained functions. But in some cases, ACL2 will not permit such execution. We discuss this issue briefly here. For more information about attachments, see [defattach]. We illustrate this issue with the following example, discussed below. (encapsulate () (defstub foo () t) (defn foo-impl-1 () t) (defattach foo foo-impl-1) (defn foo-impl-2 () nil) (local (defattach foo foo-impl-2)) (defmacro mac () (foo)) ; nil in the first pass, t in the second pass (defun bar () (mac)) ; nil in the first pass, t in the second pass (defthm bar-is-nil (equal (bar) nil)) ) Here, a non-executable function [47mfoo[0m is introduced with no constraints, and is provided two contradictory implementations, [47mfoo-impl-1[0m and [47mfoo-impl-2[0m. A function, [47mbar[0m, is defined using a macro, [47mmac[0m, whose expansion depends on which of [47mfoo-impl-1[0m or [47mfoo-impl-2[0m is attached to [47mfoo[0m. If ACL2 were to allow this, then as indicated by the comments above, [47m(bar)[0m would be defined to be [47mnil[0m on the first pass of the [47m[encapsulate][0m form, where [47mfoo[0m is attached to [47mfoo-impl-2[0m; but [47m(bar)[0m would be defined to be [47mt[0m on the second pass, where [47mfoo[0m is attached to [47mfoo-impl-1[0m because the second [47m[defattach][0m call is [47m[local][0m. Thus, after execution of the [47mencapsulate[0m form, [47m(bar)[0m would be provably equal to [47mt[0m even though there would be a theorem, [47mbar-is-nil[0m --- proved during the first pass of the [47mencapsulate[0m --- saying that [47m(bar)[0m is [47mnil[0m! Fortunately, ACL2 does not permit this to happen. The example above produces the following output. ACL2 !>>(DEFUN BAR NIL (MAC)) ACL2 Error in ( DEFUN BAR ...): In the attempt to macroexpand the form (MAC), evaluation of the macro body caused the following error: ACL2 cannot ev the call of undefined function FOO on argument list: NIL Note that because of logical considerations, attachments (including FOO-IMPL-2) must not be called in this context. We see, then, the importance of disallowing evaluation using attachments during macroexpansion. ACL2 is careful to avoid attachments in situations, like this one, where using attachments could be unsound. We conclude with an example illustrating how [47m[make-event][0m can be used to work around the refusal of ACL2 to use attachments during macroexpansion. The idea is that [47m[make-event][0m expansions are stored, and this avoids the issue of [47m[local][0m attachments. In particular, for the example below, the second [47m[defattach][0m affects the body of [47mf2[0m even though that [47m[defattach][0m is [47m[local][0m, because the expansion of the corresponding [47m[make-event][0m is saved during the first pass of [47m[certify-book][0m, when full admissibility checks are done. Then even after including the book, the definition of [47mf2[0m will be based on the second ([47m[local][0m) [47m[defattach][0m form below. (in-package "ACL2") (defun body-1 (name formals body) (declare (ignore name)) `(if (consp ,(car formals)) ,body nil)) (defun body-2 (name formals body) (declare (ignore name)) `(if (acl2-numberp ,(car formals)) ,body t)) (defmacro defun+ (name formals body) `(make-event (if (foo) ; attachable stub '(defun ,name ,formals ,(body-1 name formals body)) '(defun ,name ,formals ,(body-2 name formals body))))) ;;; (defun+ f1 (x y) (cons x y)) ; fails because foo has no attachment (defstub foo () t) (defn foo-true () t) (defn foo-false () nil) (defattach foo foo-true) (defun+ f1 (x y) (cons x y)) (local (defattach foo foo-false)) (defun+ f2 (x y) (cons x y)) (assert-event (equal (f1 3 t) nil)) (assert-event (equal (f2 3 t) (cons 3 t)))") (ilk (apply$) "Indicator of how an argument is used The [3milk[0m of the ith argument of a [47m[badge][0md function symbol [47mfn[0m is one of three tokens with the following meanings. * [47m:FN[0m - the ith argument is used exclusively as a function object by [47mfn[0m; informally this means that the argument is passed only into slots of ilk [47m:FN[0m in the definition of [47mfn[0m and that on some (syntactic) execution paths reaches the first argument of a call of [47m[apply$][0m. * [47m:EXPR[0m - the ith argument is used exclusively as a expression object by [47mfn[0m; informally this means that the argument is passed only into slots of ilk [47m:EXPR[0m in the definition of [47mfn[0m and that on some (syntactic) execution paths reaches the first argument of a call of [47m[ev$][0m. * [47mNIL[0m - the ith argument is never used as a function or expression object in the definition of [47mfn[0m. See [47m[badge][0m for more details. The [3milks[0m of all the arguments of [47mfn[0m are stored in the [47m[badge][0m of [47mfn[0m. If each ilk of [47mfn[0m is [47mNIL[0m the [47m[badge][0m stores a [47mT[0m as the ``list'' of ilks. The [47m[badge][0m of [47mfn[0m is computed by a successful call of [47m[defwarrant][0m on [47mfn[0m. Ilks are used by the various notions of [tame]ness controlling whether [47m[apply$][0m and [47m[ev$][0m can properly interpret a quoted function or expression object.") (ilks (pointers) "See [ilk].") (illegal (errors acl2-built-ins) "Print an error message and stop execution [47m(Illegal ctx str alist)[0m causes evaluation to halt with a short message using the ``context'' [47mctx[0m. An error message is first printed using the string [47mstr[0m and alist [47malist[0m that are of the same kind as expected by [47m[fmt][0m. See [fmt], and see [prog2$] for an example of how to use a related function, [47m[hard-error][0m (see [hard-error]). Also see [er] for a macro that provides a unified way of signaling errors. The difference between [47millegal[0m and [47m[hard-error][0m is that the former has a guard of [47mnil[0m while the latter has a [47m[guard][0m of [47mt[0m. Thus, you may want to use [47millegal[0m rather than [47mhard-error[0m when you intend to do [47m[guard][0m verification at some point, and you expect the guard to guarantee that the [47millegal[0m call is never executed. See [prog2$] for an example. Technical note for raw Lisp programmers only: It is possible to cause hard errors to signal actual raw Lisp errors. See [hard-error]. [31;1mFunction: [0m<illegal> (defun illegal (ctx str alist) (declare (xargs :guard (hard-error ctx str alist))) (hard-error ctx str alist))") (illegal-state (defabsstobj) "Illegal ACL2 state See [set-absstobj-debug] for background on invariance violations for abstract [stobj]s. In short, they may occur when execution does not complete for certain atomic operations. Such violations cause the following error message to be printed. ACL2 Error in CHK-ABSSTOBJ-INVARIANTS: Possible invariance violation for an abstract stobj! **PROCEED AT YOUR OWN RISK.** To proceed, evaluate the following form. :CONTINUE-FROM-ILLEGAL-STATE See :DOC set-absstobj-debug. At this point, the only way to get ACL2 to evaluate further input is to submit the form [47m:CONTINUE-FROM-ILLEGAL-STATE[0m, as noted above --- or more generally, the form it actually represents, [47m(CONTINUE-FROM-ILLEGAL-STATE)[0m, which may need to be written as [47m(ACL2::CONTINUE-FROM-ILLEGAL-STATE)[0m if the [47m[current-package][0m is other than [47m"ACL2"[0m. There is actually one exception: [47m:[0m[47m[q][0m is accepted, to pop out of the current call of [47m[ld][0m. To get a bit more information from the error message displayed above, see [set-absstobj-debug]. See [community-book] file [47mbooks/system/tests/abstract-stobj-nesting/nested-abstract-stobjs-input.lsp[0m, Examples 3 and 4, for relevant examples. Technical note. An illegal-state is entered when ACL2 sets the [47mld[0m special, [47m[ld-pre-eval-print][0m, to the value [47m:illegal-state[0m.") (imagpart (numbers acl2-built-ins) "Imaginary part of a complex number Completion Axiom ([47mcompletion-of-imagpart[0m): (equal (imagpart x) (if (acl2-numberp x) (imagpart x) 0)) [Guard] for [47m(imagpart x)[0m: (acl2-numberp x)") (immed-forced (pointers) "See [splitter].") (immediate-force-modep (force) "When the [executable-counterpart] is [enable]d, [force]d hypotheses are attacked immediately Also see [disable-immediate-force-modep] and see [enable-immediate-force-modep]. This function symbol is defined simply to provide a [rune] which can be [enable]d and [disable]d. Enabling (:executable-counterpart immediate-force-modep) causes ACL2 to attack [force]d hypotheses immediately instead of delaying them to the next forcing round. Example Hints :in-theory (disable (:executable-counterpart immediate-force-modep)) ; delay forced hyps to forcing round :in-theory (enable (:executable-counterpart immediate-force-modep)) ; split on forced hyps immediately See [force] for background information. When a [47m[force][0md hypothesis cannot be established a record is made of that fact and the proof continues. When the proof succeeds a ``forcing round'' is undertaken in which the system attempts to prove each of the [force]d hypotheses explicitly. However, if the [rune] [47m(:executable-counterpart immediate-force-modep)[0m is [enable]d at the time the hypothesis is [force]d, then ACL2 does not delay the attempt to prove that hypothesis but undertakes the attempt more or less immediately.") (implicate (pointers) "See [system-utilities].") (implies (basics acl2-built-ins) "Logical implication [47mImplies[0m is the ACL2 implication function. [47m(implies P Q)[0m means that either [47mP[0m is false (i.e., [47mnil[0m) or [47mQ[0m is true (i.e., not [47mnil[0m). [31;1mFunction: [0m<implies> (defun implies (p q) (declare (xargs :guard t)) (if p (if q t nil) t))") (improper-consp (lists acl2-built-ins) "Recognizer for improper (non-[47mnil[0m-terminated) non-empty lists [47mImproper-consp[0m is the function that checks whether its argument is a non-empty list that ends in other than [47mnil[0m. See [proper-consp] and also see [true-listp]. [31;1mFunction: [0m<improper-consp> (defun improper-consp (x) (declare (xargs :guard t)) (and (consp x) (not (true-listp x))))") (in-arithmetic-theory (events) "Designate theory for some rewriting done for non-linear arithmetic We assume familiarity with [theories]; in particular, see [in-theory] for the normal way to set the current theory. Here, we discuss an analogous event that pertains only to non-linear arithmetic (see [non-linear-arithmetic]). Example: (in-arithmetic-theory '(lemma1 lemma2)) General Form: (in-arithmetic-theory term) where [47mterm[0m is a term that when evaluated will produce a theory (see [theories]). Except for the variable [47m[world][0m, [47mterm[0m must contain no free variables. [47mTerm[0m is evaluated with the variable [47m[world][0m bound to the current [world] to obtain a theory and the corresponding runic theory (see [theories]) is then used by non-linear arithmetic (see [non-linear-arithmetic]). Warning: If [47mterm[0m involves macros such as [47m[enable][0m and [47m[disable][0m you will probably not get what you expect! Those macros are defined relative to the [47m[current-theory][0m. But in this context you might wish they were defined in terms of the ``[47mCURRENT-ARITHMETIC-THEORY[0m'' which is not actually a defined function. We do not anticipate that users will repeatedly modify the arithmetic theory. We expect [47mterm[0m most often to be a constant list of runes and so have not provided ``arithmetic theory manipulation functions'' analogous to [47m[current-theory][0m and [47m[enable][0m. See [non-linear-arithmetic].") (in-package (packages acl2-built-ins) "Select current package Example: (in-package "MY-PKG") General Form: (in-package str) where [47mstr[0m is a string that names an existing ACL2 package, i.e., one of the initial packages such as [47m"KEYWORD"[0m or [47m"ACL2"[0m or a package introduced with [47m[defpkg][0m. For a complete list of the known packages created with [47m[defpkg][0m, evaluate (strip-cars (known-package-alist state)). See [defpkg]. An ACL2 book (see [books]) must contain a single [47min-package[0m form, which must be the first form in that book.") (in-tau-intervalp (tau-system acl2-built-ins) "Boolean membership in a tau interval General Form: (in-tau-intervalp e x) Here, [47mx[0m should be an interval (see [47m[tau-intervalp][0m). This function returns [47mt[0m or [47mnil[0m indicating whether [47me[0m, which is generally but not necessarily a number, is an element of interval [47mx[0m. By that is meant that [47me[0m satisfies the domain predicate of the interval and lies between the two bounds. Suppose [47mx[0m is an interval with the components [3mdom[0m, [3mlo-rel[0m, [3mlo[0m, [3mhi-rel[0m and [3mhi[0m. Suppose [47m(<? [0m[3mrel u v[0m[47m)[0m means [47m(< [0m[3mu v[0m[47m)[0m when [3mrel[0m is true and [47m(<= [0m[3mu v[0m[47m)[0m otherwise, with appropriate treatment of infinities. Then for [47me[0m to be in interval [47mx[0m, it must be the case that [47me[0m satisfies the domain predicate [3mdom[0m (where where [3mdom[0m=[47mnil[0m means there is no restriction on the domain) and [47m(<? [0m[3mlo-rel lo[0m[47m e)[0m and [47m(<? [0m[3mhi-rel[0m[47m e [0m[3mhi[0m[47m)[0m. [Note: ``Appropriate treatment of infinities'' is slightly awkward if both infinities are represented by the same object, [47mnil[0m. However, this is handled by coercing [47me[0m to a number [3mafter[0m checking that it is in the domain. By this trick, ``[47m<?[0m'' is presented with at most one ``infinity'' and it is always negative when in the first argument and positive when in the second.] Note that every element in an [47mINTEGERP[0m interval is contained in the analogous [47mRATIONALP[0m interval (i.e., the interval obtained by just replacing the domain [47mINTEGERP[0m by [47mRATIONALP[0m). That is because every integer is a rational. Similarly, every rational is an ACL2 number. Note that an interval in which the relations are weak and the bounds are equal rationals is the ``unit'' or ``identity'' interval containing exactly that rational. Note that an interval in which the relations are strong and the bounds are equal rationals is empty: it contains no objects. Note that the interval [47m(make-tau-interval nil nil nil nil nil)[0m is the ``universal interval:'' it contains all ACL2 objects. It contains all numbers because they satisfy the non-existent domain restriction and lie between minus infinity and plus infinity. It contains all non-numbers because the interval contains [47m0[0m and ACL2's inequalities coerce non-numbers to [47m0[0m. The universal interval is useful if you are defining a bounder (see [bounders]) for a function and do not wish to address a certain case: return the universal interval. Recall that [47m[make-tau-interval][0m constructs intervals. Using [47mmake-tau-interval[0m we give several self-explanatory examples of [47min-tau-intervalp[0m: (in-tau-intervalp 3 (make-tau-interval 'INTEGERP nil 0 nil 10)) = t (in-tau-intervalp 3 (make-tau-interval 'RATIONALP nil 0 nil 10)) = t (in-tau-intervalp 3 (make-tau-interval NIL nil 0 nil 10)) = t (in-tau-intervalp -3 (make-tau-interval 'INTEGERP nil 0 nil 10)) = nil (in-tau-intervalp 30 (make-tau-interval 'INTEGERP nil 0 nil 10)) = nil (in-tau-intervalp 3/5 (make-tau-interval 'INTEGERP nil 0 nil 10)) = nil (in-tau-intervalp 3/5 (make-tau-interval 'RATIONALP nil 0 nil 10)) = t (in-tau-intervalp #c(3 5) (make-tau-interval 'RATIONALP nil 0 nil 10)) = nil (in-tau-intervalp #c(3 5) (make-tau-interval 'ACL2-NUMBERP nil 0 nil 10)) = t (in-tau-intervalp 'ABC (make-tau-interval NIL nil 0 nil 10)) = t") (in-theory (events theories) "Designate ``current'' theory (enabling its rules) Example: (in-theory (set-difference-theories (universal-theory :here) '(flatten (:executable-counterpart flatten)))) General Form: (in-theory term) where [47mterm[0m is a term that when evaluated will produce a theory (see [theories]). Except for the variable [47m[world][0m, [47mterm[0m must contain no free variables. [47mTerm[0m is evaluated with the variable [47m[world][0m bound to the current [world] to obtain a theory and the corresponding runic theory (see [theories]) is then made the current theory. Thus, immediately after the [47min-theory[0m, a rule is [enable]d iff its rule name is a member of the runic interpretation (see [theories]) of some member of the value of [47mterm[0m. See [theory-functions] for a list of the commonly used theory manipulation functions. Note that it is often useful to surround [47min-theory[0m [events] with [47mlocal[0m, that is, to use [47m(local (in-theory ...))[0m. This use of [47m[local][0m in [47m[encapsulate][0m events and [books] will prevent the effect of this theory change from being exported outside the context of that [47mencapsulate[0m or book. Also see [hints] for a discussion of the [47m:in-theory[0m hint, including some explanation of the important point that an [47m:in-theory[0m hint will always be evaluated relative to the current ACL2 logical [world], not relative to the theory of a previous goal. [47m[In-theory][0m returns an [error-triple]. When the return is without error, the value is of the form [47m(mv nil (:NUMBER-OF-ENABLED-RUNES k) state)[0m where [47mk[0m is the length of the new current theory. This value of [47mk[0m is what is printed when an [47min-theory[0m event evaluates without error at the top level.") (include-book (books-reference books-tour events) "Load the [events] in a file Examples: ; Include using relative pathnames: (include-book "my-arith") (include-book "/../../my-arith") ; Include using absolute pathname: (include-book "/home/smith/my-arith") ; Include a community book: (include-book "arithmetic/top-with-meta" :dir :system) ; Include a project book: (include-book "my-subdir/my-book" :dir :my-project) General Form: (include-book file :load-compiled-file action :uncertified-okp t/nil/:ignore-certs ; [default t] :defaxioms-okp t/nil ; [default t] :skip-proofs-okp t/nil ; [default t] :ttags ttags ; [default nil] :dir directory) where [47mfile[0m is a book-name without the [47m".lisp"[0m extension. See [books] for general information, see [book-name] for information about book-names, and see [pathname] for information about file names. [47mAction[0m is one of [47mt[0m, [47mnil[0m, [47m:default[0m, [47m:warn[0m, or [47m:comp[0m; these values are explained below, and the default is [47m:default[0m. The three [47m-okp[0m keyword arguments, which default to [47mt[0m, determine whether errors or warnings are generated under certain conditions explained below; when the argument is [47mt[0m, warnings are generated. The [47m:dir[0m argument, if supplied, is a keyword that represents an absolute [pathname] for a directory, to be used instead of the current book directory (see [cbd]) for resolving the given [47mfile[0m argument to an absolute pathname. In particular, by default [47m:dir :system[0m resolves the given [47mfile[0m using the [47mbooks/[0m directory of your ACL2 installation; see ``Books Directory'' below. To define other keywords that can be used with [47m:dir[0m, see [add-include-book-dir], [add-include-book-dir!], and [project-dir-alist]. If the book has no [certificate], if its certificate is invalid (say, because its [book-hash] shows that books have changed after their certification), or if the certificate was produced by a different [version] of ACL2, a warning is printed and the book is included anyway; see [certificate]. This can lead to serious errors, perhaps mitigated by the presence of a [47m.port[0m file from an earlier certification; see [uncertified-books]. If the portcullis of the [certificate] (see [portcullis]) cannot be raised in the host logical [world], an error is caused and no change occurs to the logic. Otherwise, the non-[47m[local][0m [events] in file are assumed. Then the [keep] of the [certificate] is checked to ensure that the correct files were read; see [keep]. A warning is printed if uncertified [books] were included. Even if no warning is printed, [47minclude-book[0m places a burden on you; see [certificate]. If you use [guard]s, please note [47minclude-book[0m is executed as though [47m(set-guard-checking t)[0m has been evaluated; see [set-guard-checking]. If you want to run with different guard-checking, consider using [47mld[0m instead, or in addition; see [ld]. The value of [47m:load-compiled-file[0m controls whether a compiled file for the given [47mfile[0m is loaded by [47minclude-book[0m. Note that this keyword applies only to the given [47mfile[0m, not to any included sub-books. In order to skip loading all compiled files, for the given [47mfile[0m as well as all included sub-books --- for example, to avoid Lisp errors such as ``Wrong FASL version'' --- use [47m(set-compiler-enabled nil state)[0m; see [compilation]. Otherwise, if keyword argument [47m:load-compiled-file[0m is missing or its value is the keyword [47m:default[0m, then it is treated as [47m:warn[0m. If its value is [47mnil[0m, no attempt is made to load the compiled file for the book provided. In order to load the compiled file, it must be more recent than the book's [certificate] (except in raw mode, where it must be more recent than the book itself; see [set-raw-mode]). For non-[47mnil[0m values of [47m:load-compiled-file[0m that do not result in a loaded compiled file, ACL2 proceeds as follows. Note that a load of a compiled file or expansion file aborts partway through whenever an [47m[include-book][0m form is encountered for which no suitable compiled or expansion file can be loaded. For much more detail, see [book-compiled-file]. [47mt[0m: Cause an error if the compiled file is not loaded. This same requirement is imposed on every [47m[include-book][0m form evaluated during the course of evaluation of the present [47minclude-book[0m form, except that for those subsidiary [47minclude-book[0ms that do not themselves specify [47m:load-compiled-file t[0m, it suffices to load the expansion file (see [book-compiled-file]). [47m:warn[0m: An attempt is made to load the compiled file, and a warning is printed if that load fails to run to completion. [47m:comp[0m: A compiled file is loaded as with value [47mt[0m, except that if a suitable ``expansion file'' exists but the compiled file does not, then the compiled file is first created. See [book-compiled-file]. The three [47m-okp[0m arguments, [47m:uncertified-okp[0m, [47mdefaxioms-okp[0m, and [47mskip-proofs-okp[0m, determine the system's behavior when the book or any sub-book is found to be uncertified, when the book or any sub-book is found to contain [47m[defaxiom][0m events, and when the book or any sub-book is found to contain [47m[skip-proofs][0m events, respectively. All three default to [47mt[0m, which means it is ``ok'' for the condition to arise. In this case, a warning is printed but the processing to load the book is allowed to proceed. When one of these arguments is [47mnil[0m and the corresponding condition arises, an error is signaled and processing is aborted. [31;1mExceptions[0m: [47m:uncertified-okp t[0m is ignored if the [47minclude-book[0m is being performed on behalf of a [47m[certify-book][0m, and [47m:uncertified-okp :ignore-certs[0m is an advanced option explained later in this topic. The keyword argument [47m:ttags[0m may normally be omitted. A few constructs, used for example if you are building your own system based on ACL2, may require it. See [defttag] for an explanation of this argument. [47mInclude-book[0m is similar in spirit to [47m[encapsulate][0m in that it is a single event that ``contains'' other [events], in this case the [events] listed in the file named. [47mInclude-book[0m processes the non-[47m[local][0m event forms in the file, assuming that each is admissible. [47m[Local][0m [events] in the file are ignored. You may use [47minclude-book[0m to load several [books], creating the logical [world] that contains the definitions and theorems of all of them. If any non-[47m[local][0m event of the book attempts to define a [name] that has already been defined --- and the book's definition is not syntactically identical to the existing definition --- the attempt to include the book fails, an error message is printed, and no change to the logical [world] occurs. See [redundant-events] for the details. When a book is included, the default [defun-mode] (see [default-defun-mode]) for the first event is always [47m:[0m[47m[logic][0m. That is, the default [defun-mode] ``outside'' the book --- in the environment in which [47minclude-book[0m was called --- is irrelevant to the book. [Events] that change the [defun-mode] are permitted within a book (provided they are not in [47m[local][0m forms). However, such changes within a book are not exported, i.e., at the conclusion of an [47minclude-book[0m, the ``outside'' default [defun-mode] is always the same as it was before the [47minclude-book[0m. Unlike every other event in ACL2, [47minclude-book[0m puts a burden on you. Used improperly, [47minclude-book[0m can be unsound in the sense that it can create an inconsistent extension of a consistent logical [world]. A certification mechanism is available to help you carry this burden --- but it must be understood up front that even certification is no guarantee against inconsistency here. The fundamental problem is one of file system security. See [certificate] for a discussion of the security issues. At the beginning of execution of an [47minclude-book[0m form, even before executing [portcullis] [command]s, the value of [47m[ACL2-defaults-table][0m is restored to the value it had at startup. After execution of an [47minclude-book[0m form, the value of [47m[ACL2-defaults-table][0m is restored to what it was immediately before that [47minclude-book[0m form was executed. See [ACL2-defaults-table]. An advanced option is [47m:uncertified-okp :ignore-certs[0m. This tells ACL2 to ignore all [certificate] files while including the book and its sub-books, thus treating all these books as uncertified. This option may be useful when writing a [47m.acl2x[0m file for the first ``run'' of a ``two-runs approach'' to certification; see [set-write-ACL2x]. Note however that ordinary certification (the second ``run'') will then fail unless care is taken to avoid [47m:uncertified-okp :ignore-certs[0m during that second certification run. Finally (and speaking in general, not particularly about a [47m[certify-book][0m context), we emphasize that the option [47m:uncertified-okp :ignore-certs[0m applies when including all sub-books, not only for the current book. In particular, a subsidiary [47minclude-book[0m call specifying [47m:uncertified-okp nil[0m will fail, because the superior [47m:ignore-certs[0m value causes the subsidiary book to be treated as uncertified, which conflicts with the requirement of [47m:uncertified-okp nil[0m. [31;1mBooks Directory.[0m We refer to the ``books directory'' of an executable image as the full pathname string of the directory associated with [47minclude-book[0m keyword option [47m:dir :system[0m for that image. By default, it is the [47mbooks/[0m subdirectory of the directory where the sources reside and the executable image is thus built). If those books reside elsewhere, the environment variable [47mACL2_SYSTEM_BOOKS[0m can be set to the directory under which they reside. In most cases, your ACL2 executable is a small script in which you can set this environment variable just above the line on which the actual ACL2 image is invoked, for example: export ACL2_SYSTEM_BOOKS ACL2_SYSTEM_BOOKS=/home/acl2/4-0/acl2-sources/books If you follow suggestions in the [installation] instructions, these books will be the ACL2 community books; see [community-books]. For another way to set the system books directory, which also permits similar handling for other directories, see [project-dir-alist]. This concludes the guided tour through [books]. See [set-compile-fns] for a subtle point about the interaction between [47minclude-book[0m and on-the-fly [compilation]. See [certify-book] for a discussion of how to certify a book. Subtopics [Fast-cert] A mode for faster, but possibly unsound, book certification") (incompatible (theories) "Declaring that two rules should not both be [enable]d Example: (theory-invariant (incompatible (:rewrite left-to-right) (:rewrite right-to-left))) General Form: (incompatible rune1 rune2) where [47mrune1[0m and [47mrune2[0m are two specific [rune]s. The arguments are not evaluated. [47mInvariant[0m is just a macro that expands into a term that checks that not both [rune]s are enabled. See [theory-invariant]. Also see [incompatible!] for a variant that insists the arguments are indeed runes, not merely having the shapes of runes.") (incompatible! (theories) "Declaring that two rules must exist and should not both be [enable]d This variant of [47mincompatible[0m causes an error if either of its arguments is not a [rune], by calling [47m[active-or-non-runep][0m instead of [47m[active-runep][0m. See [incompatible] and see [theory-invariant].") (induct (pointers) "See [hints] for information about the keyword [47m:induct[0m.") (induction (rule-classes) "Make a rule that suggests a certain induction Example: (defthm recursion-by-sub2-induction-rule t :rule-classes ((:induction :pattern (* 1/2 i) :condition (and (integerp i) (>= i 0)) :scheme (recursion-by-sub2 i)))) In ACL2, as in Nqthm, the functions in a conjecture ``suggest'' the inductions considered by the system. Because every recursively defined function must be admitted with a justification in terms of a measure that decreases in a well-founded way on a given set of ``controlling'' arguments, every recursive definition suggests a dual induction scheme that ``unwinds'' the function from a given application. The case analysis in the induction scheme suggested by a function call is determined by the case analysis used to prove termination. That case analysis chooses a subset of the tests governing recursive calls and then generates base cases for the combinations of tests that do not lead to recursive calls and induction steps for the combinations that do. See [rulers] and [induction-coarse-v-fine-grained]. For example, since [47m[append][0m (actually [47m[binary-append][0m, but we'll ignore the distinction here) decomposes its first argument by successive [47m[cdr][0ms as long as it is a cons, the induction scheme suggested by [47m(append x y)[0m has a base case supposing [47mx[0m to be an atom (i.e., not a cons) and then has an induction step in which the induction hypothesis is obtained by replacing [47mx[0m by [47m(cdr x)[0m. This substitution decreases the same measure used to justify the definition of [47m[append][0m. Observe that an induction scheme is suggested by a recursive function application only if the controlling actuals are distinct variables, a condition that is sufficient to ensure that the ``substitution'' used to create the induction hypothesis is indeed a substitution and that it drives down a certain measure. In particular, [47m(append (foo x) y)[0m does not suggest an induction unwinding [47m[append][0m because the induction scheme suggested by [47m(append x y)[0m requires that we substitute [47m(cdr x)[0m for [47mx[0m and we cannot do that if [47mx[0m is not a variable symbol. Once ACL2 has collected together all the suggested induction schemes it massages them in various ways, combining some to simultaneously unwind certain cliques of functions and vetoing others because they ``flaw'' others. We do not further discuss the induction heuristics here; the interested reader should see [induction-heuristics]. However, unlike Nqthm, ACL2 provides a means by which the user can elaborate the rules under which function applications suggest induction schemes. Such rules are called [47m:induction[0m rules. The definitional principle automatically creates an [47m:induction[0m rule, named [47m(:induction fn)[0m, for each admitted recursive function, [47mfn[0m. It is this rule that links applications of [47mfn[0m to the induction scheme it suggests. Disabling [47m(:induction fn)[0m will prevent [47mfn[0m from suggesting the induction scheme derived from its recursive definition (with an exception for induction schemes by way of user-defined induction rules, as discussed at the end below). It is possible for the user to create additional [47m:induction[0m rules by using the [47m:induction[0m rule class in [47m[defthm][0m. Technically we are ``overloading'' [47m[defthm][0m by using it in the creation of [47m:induction[0m rules because no theorem need be proved to set up the heuristic link represented by an [47m:induction[0m rule. However, since [47m[defthm][0m is generally used to create rules and rule-class objects are generally used to specify the exact form of each rule, we maintain that convention and introduce the notion of an [47m:induction[0m rule. An [47m:induction[0m rule can be created from any lemma whatsoever. General Form of an :induction Lemma or Corollary: T General Form of an :induction rule-class: (:induction :pattern pat-term :condition cond-term :scheme scheme-term) where [47mpat-term[0m, [47mcond-term[0m, and [47mscheme-term[0m are all terms, [47mpat-term[0m is the application of a function symbol, [47mfn[0m, [47mscheme-term[0m is the application of a function symbol, [47mrec-fn[0m, that suggests an induction, and, finally, every free variable of [47mcond-term[0m and [47mscheme-term[0m is a free variable of [47mpat-term[0m. We actually check that [47mrec-fn[0m is either recursively defined --- so that it suggests the induction that is intrinsic to its recursion --- or else that another [47m:induction[0m rule has been proved linking a call of [47mrec-fn[0m as the [47m:pattern[0m to some scheme. The induction rule created is used as follows. When an instance of the [47m:pattern[0m term occurs in a conjecture to be proved by induction and the corresponding instance of the [47m:condition[0m term is known to be non-[47mnil[0m (by [type-reasoning] alone), the corresponding instance of the [47m:scheme[0m term is created and the rule ``suggests'' the induction, if any, suggested by that term. (Analysis of that term may further involve induction rules, though the applied rule is removed from consideration during that further analysis, in order to avoid looping.) If [47mrec-fn[0m has a recursive definition, then the definition's dual induction scheme is suggested (i.e., unwinding the function). (Remark. Unlike [47m:induct[0m [hints], the [47m:scheme[0m of an [47m:induction[0m rule only introduces induction schemes based on the top-level function symbol of the indicated term, not of any of its subterms. End of Remark.) Consider, for example, the example given above, (:induction :pattern (* 1/2 i) :condition (and (integerp i) (>= i 0)) :scheme (recursion-by-sub2 i)). In this example, we imagine that [47mrecursion-by-sub2[0m is the function: (defun recursion-by-sub2 (i) (if (and (integerp i) (< 1 i)) (recursion-by-sub2 (- i 2)) t)) Observe that this function recursively decomposes its natural number argument by subtracting [47m2[0m from it repeatedly and stops when the argument is [47m1[0m or less. The value of the function is irrelevant; it is its induction scheme that concerns us. The induction scheme suggested by [47m(recursion-by-sub2 i)[0m is (and (implies (not (and (integerp i) (< 1 i))) ; base case (:p i)) (implies (and (and (integerp i) (< 1 i)) ; induction step (:p (- i 2))) (:p i))) We can think of the base case as covering two situations. The first is when [47mi[0m is not an integer. The second is when the integer [47mi[0m is less than or equal to [47m1[0m. In the base case we must prove [47m(:p i)[0m without further help. The induction step deals with those natural numbers [47mi[0m greater than [47m1[0m, and inductively assumes the conjecture for [47mi-2[0m while proving it for [47mi[0m. Let us call this scheme ``induction on [47mi[0m by twos.'' Suppose the above [47m:induction[0m rule has been added. Then an occurrence of, say, [47m(* 1/2 k)[0m in a conjecture to be proved by induction would suggest, via this rule, an induction on [47mk[0m by twos, provided [47mk[0m was known to be a nonnegative integer. This is because the induction rule's [47m:pattern[0m is matched in the conjecture, its [47m:condition[0m is satisfied, and the [47m:scheme[0m suggested by the rule is that derived from [47m(recursion-by-sub2 k)[0m, which is induction on [47mk[0m by twos. Similarly, the term [47m(* 1/2 (length l))[0m would suggest no induction via this rule, even though the rule ``fires'' because it creates the [47m:scheme[0m [47m(recursion-by-sub2 (length l))[0m which suggests no inductions unwinding [47mrecursion-by-sub2[0m (since the controlling argument of [47mrecursion-by-sub2[0m in this [47m:scheme[0m is not a variable symbol). Continuing this example one step further illustrates the utility of [47m:induction[0m rules. We could define the function [47mrecursion-by-cddr[0m that suggests the induction scheme decomposing its [47m[consp][0m argument two [47m[cdr][0ms at a time. We could then add the [47m:induction[0m rule linking [47m(* 1/2 (length x))[0m to [47m(recursion-by-cddr x)[0m and arrange for [47m(* 1/2 (length l))[0m to suggest induction on [47ml[0m by [47m[cddr][0m. Observe that [47m:induction[0m rules require no proofs to be done. Such a rule is merely a heuristic link between the [47m:pattern[0m term, which may occur in conjectures to be proved by induction, and the [47m:scheme[0m term, from which an induction scheme may be derived. Hence, when an [47m:induction[0m rule-class is specified in a [47m[defthm][0m event, the theorem proved is irrelevant. The easiest theorem to prove is, of course, [47mt[0m. Thus, we suggest that when an [47m:induction[0m rule is to be created, the following form be used: (defthm name T :rule-classes ((:induction :pattern pat-term :condition cond-term :scheme scheme-term))) The name of the rule created is [47m(:induction name)[0m. When that [rune] is [disable]d the heuristic link between [47mpat-term[0m and [47mscheme-term[0m is broken. Note that if [47mfn[0m is defined recursively and [47m(:induction fn)[0m is [disable]d, then normally the induction scheme for [47mfn[0m will not be available during a proof. However, the induction scheme for [47mfn[0m is available, even if it is disabled, when it is indicated by application of a user-defined [47m:induction[0m rule. So for the [47m:induction[0m rule above, [47mrecursion-by-sub2-induction-rule[0m: even if [47m(:induction recursion-by-sub2)[0m is disabled, nevertheless the induction scheme for [47mrecursion-by-sub2[0m will be available to apply to the instantiated [47m:scheme-term[0m. Subtopics [Induction-depth-limit] The maximum number permitted of nested inductions [Set-induction-depth-limit!] Set the induction-depth-limit non-[47m[local][0mly") (induction-coarse-v-fine-grained (rulers) "advice on case explosion in complex inductions Recursive functions suggest inductions based on the case analysis in the function definition and the positions of recursive calls within that case analysis. That analysis is done when termination is proved. Key parts of that analysis are the notions of governing tests and ruling tests. By using the so-called ``ruler-extenders'' feature of termination analysis you can sometimes choose between ``coarse-grained'' and ``fine-grained'' inductions. The former have few cases but may provide multiple and sometimes irrelevant induction hypotheses. The latter provide more cases, each targeted at a given output, and tend to provide only induction hypotheses needed for that output. See [rulers] for a discussion of ruler-extenders. Governing versus Ruling Tests Roughly speaking, a test [3mgoverns[0m a recursive call if the test must be true for control to reach that call. The [3mruling[0m tests are a subset of the governing tests and are the ones that determine the case analysis of any suggested induction. For example, if we are analyzing a definition of [47m(fn x)[0m and the body is [47m(if (not (consp x)) (h nil) (h (fn (cdr x))))[0m then [47m(consp x)[0m governs the recursive call and it also rules the call. But if the body were [47m(h (if (not (consp x)) nil (fn (cdr x))))[0m then [47m(consp x)[0m governs the recursive call but may not rule it. It would be considered a ruler if the symbol [47mh[0m were on the ``ruler-extenders'' list --- the list of symbols that allow further collection of rulers from inside terms that begin with those symbols. The default setting of ruler-extenders is [47m(if mv-list return-last)[0m. That means that termination (and induction) analysis stops looking for ruling tests when a term is encountered that does not begin with one of these listed symbols. For example, under the default ruler-extenders, when the analysis encounters a term that starts with a [47mlambda[0m expression, that term is considered a tip of the tree. ([47mLambda[0m expressions are relevant because they are introduced by the macroexpansion of [47m[let][0m and [47m[let*][0m expressions, which arise frequently in interesting recursive functions because they facilitate [3mcode sharing[0m by allowing the computation of intermediate results used on multiple output branches.) When the analysis encounters a term considered a tip, the rulers collected so far are used to rule [3mall[0m the recursive calls in that tip. So at a tip, the analysis collects all the recursive calls occurring in that tip and forms measure conjectures and, eventually, induction hypotheses about them, using the rulers as the hypotheses of those conjectures. So the user can influence the determination of the rulers by setting the ``ruler-extenders'' in effect when the function is admitted. The global default ruler-extenders can be set by the event [47mset-ruler-extenders[0m or specified locally in a [47mdefun[0m by the [47m[xargs][0m keyword [47m:ruler-extenders[0m. See [rulers] for the details. Coarse versus Fine Induction Case Analysis Most often, users think about ruler-extenders only in the context of [3mfailed[0m termination proofs: inspection of the measure conjectures reveal that an important governing hypothesis was curiously omitted, the user consults the documentation or appeals for help from other users, and is reminded of ruler-extenders. One could argue that users forget about ruler-extenders because the default setting for ruler-extenders is so often the ``right'' one. But sometimes even a function that is successfully admitted under the default setting would benefit from selecting a non-default setting for ruler-extenders. Sometimes you may feel that the prover is struggling with an induction suggested by a function, even though the function that suggested the induction is the one you expected to be selected, and for most simple recursive functions the induction suggested is the ``perfect'' induction for that function. This problem of the prover struggling to simplify the induction steps might arise most commonly with functions that have [47m[let*][0m bindings that contain [47mif[0m-expressions, some of which contain recursive calls. For example, the following artificial example raises the possibility of this problem. (defun fn (x y) (if (consp x) (let* ((y1 (if (consp (car x)) (fn (car x) (cons 'car y)) y)) (y2 (if (consp (cdr x)) (fn (cdr x) (cons 'cdr y1)) y1))) (cons y1 y2)) y)) Recall that [47mlet*[0m expressions are translated into nested [47mlambda[0m expressions, so the formal definition of [47mfn[0m is (defun fn (x y) (if (consp x) ((lambda (y1 x) ((lambda (y2 y1) (cons y1 y2)) (if (consp (cdr x)) (fn (cdr x) (cons 'cdr y1)) y1) y1)) (if (consp (car x)) (fn (car x) (cons 'car y)) y) x) y)) So, the entire [47mlet*[0m above, i.e., the formal term starting with the first [47mlambda[0m expression, is a tip ruled only by [47m(consp x)[0m. The [47mif[0ms within it are not considered even though their tests govern (but do not rule) the subsequent recursions. The recursive calls in that tip are (fn (car x) (cons 'car y)) and (fn (cdr x) (cons 'cdr (if (consp (car x)) (fn (car x) (cons 'car y)) y))). The default measure in this definition is [47m(acl2-count x)[0m. The measure conjectures are easy to prove because [47m(consp x)[0m implies [47m(acl2-count (car x))[0m and [47m(acl2-count (cdr x))[0m are both less than [47m(acl2-count x)[0m. Since there are no more recursive calls in the definition, [47mfn[0m is admitted. Now consider how the prover would attempt to prove [47m(p (fn x y))[0m by the induction suggested by [47mfn[0m. The induction argument, shown below, has one base case and one induction step. The induction step has two induction hypotheses. (and (implies (not (consp x)) (p (fn x y))) (implies (and (consp x) (p (fn (car x) (cons 'car y))) (p (fn (cdr x) (cons 'cdr (if (consp (car x)) (fn (car x) (cons 'car y)) y))))) (p (fn x y)))). [31;1mNote[0m: Here and throughout this documentation topic we freely rearrange the formulas we display to make it easier to compare different induction schemes. For example, when the prover attempts to prove [47m(p (fn x y))[0m it lists the conjuncts above in the opposite order, i.e., the base case occurs last. It can be hard to compare induction schemes from similar functions because ACL2's methods of generating induction schemes does not preserve the order of tips. The prover attempts to reduce each of these two conjuncts to [47mT[0m by simplification. The base case is generally simple. So consider the induction step, the second implication above, which we abbreviate here as (implies (and (consp x) [3mind-hyp1[0m [3mind-hyp2[0m) [3mind-concl[0m) where, [3mind-hyp1[0m, the first induction hypothesis, is [47m(p (fn (car x) (cons 'car y)))[0m, etc. See [introduction-to-the-theorem-prover] for more details of how the rewriter works. When rewriting the formula above it basically proceeds left-to-right, innermost first, keeping track of what can be assumed given the context in which terms occur. Thus, by the time the rewriter gets to the induction conclusion, [3mind-concl[0m, the two induction hypotheses will have been rewritten, making them easier to find and identify as true if they occur in the rewriting of the conclusion. But rewriting [3mind-hyp1[0m here will involve rewriting [47m(fn (car x) (cons 'car y))[0m, which is completely irrelevant to half of the proof of [3mind-concl[0m. In particular, inspection of [47mfn[0m reveals that the first recursive call of [47mfn[0m is only relevant if [47m(consp (car x))[0m is true. But we know nothing about [47m(car x)[0m in this induction step. Furthermore, rewriting a call of a recursive function can be very expensive since it requires (a) rewriting the actual expressions, then (b) rewriting the body of the function under a substitution replacing the function's formals by the rewritten actuals, and then (c) heuristically deciding whether the rewritten body is preferable to the call, given the subterms occurring elsewhere in the goal. Another way to describe the unfortunate induction scheme above is that it ``coarse,'' because it provides a simple case analysis, which necessitates lumping all the possibly relevant induction hypotheses into a single case (in this particular example). When the induction conclusion opens, after the induction hypotheses have all been simplified, it will cause further splitting, (e.g., on [47m(consp (car x))[0m), and in some of those subgoals some of the simplified induction hypotheses will be irrelevant (but still burden the simplification process if the cases are not proved immediately). Depending on how hard it is to rewrite irrelevant induction hypotheses --- which depends not just on the function, like [47mfn[0m, suggesting the induction but also on the conjecture being proved --- it might be more efficient to have a finer-grained case analysis so that the only induction hypotheses in a given case are those on a given execution path. A finer-grained induction scheme is generated, in the case of [47mfn[0m, by arranging for [47mlambda[0m expressions [3mnot[0m to stop the collection of rulers. This can be done by adding the keyword [47m:lambdas[0m to the ruler-extenders. The presence of that keyword means ``keep collecting rulers as you dive into [3many[0m term beginning with a [47mlambda[0m expression.'' (By the way, normally [47m:ruler-extenders[0m expects a list but if you specify the single keyword [47m:lambdas[0m it denotes the list [47m(if :lambdas mv-list return-last)[0m.) Again, see [47mrulers[0m for details. If we had defined [47mfn[0m as shown below we would get the finer induction analysis shown subsequently. (defun fn (x y) (declare (xargs :ruler-extenders :lambdas)) (if (consp x) (let* ((y1 (if (consp (car x)) (fn (car x) (cons 'car y)) y)) (y2 (if (consp (cdr x)) (fn (cdr x) (cons 'cdr y1)) y1))) (cons y1 y2)) y)) Note that [47mfn[0m can be admitted without extending the rulers --- we have already demonstrated that. We are including [47m:lambdas[0m here precisely to get a finer case analysis for induction. The induction generated is shown below. We have slightly simplified the induction by replacing [47m(if [0m[3ma b c[0m[47m)[0m by [3mb[0m when [3ma[0m is among the hypotheses in the case analysis, and by replacing [47m(if [0m[3ma b c[0m[47m)[0m by [3mc[0m when [47m(not [0m[3ma[0m[47m)[0m is among the hypotheses. This simplification is actually not done by induction analysis but by the first simplification. (and (implies (not (consp x)) (p (fn x y))) (implies (and (consp x) (not (consp (car x))) (not (consp (cdr x)))) (p (fn x y))) (implies (and (consp x) (not (consp (car x))) (consp (cdr x)) (p (fn (cdr x) (cons 'cdr y)))) (p (fn x y))) (implies (and (consp x) (consp (car x)) (not (consp (cdr x))) (p (fn (car x) (cons 'car y)))) (p (fn x y))) (implies (and (consp x) (consp (car x)) (consp (cdr x)) (p (fn (car x) (cons 'car y))) (p (fn (cdr x) (cons 'cdr (fn (car x) (cons 'car y)))))) (p (fn x y)))) Note that the case analysis here steers the [47m(fn x y)[0m in the conclusion down exactly one path and the only hypotheses provided in each induction step concern recursive calls on that path. The finer case analysis gives us two base cases and four induction steps, one of which has two induction hypotheses. We'll encounter terms of the form [47m(p (fn ...))[0m nine times in using this scheme, instead of just four such terms in the first scheme we showed. It may seem surprising that this scheme ever leads to faster proofs than the earlier one. But it can. Whether it does depends, as mentioned above, on the complexity of rewriting the recursive calls involved and the conjecture being proved. [31;1mNote[0m: The ruler-extenders may include arbitrary function symbols and the keyword [47m:lambdas[0m as above. But it can also be set to [47m:all[0m which makes all the governors be rulers, i.e., collection of rulers dives through all function symbols. We focus here on diving through [47mlambda[0m expressions because they are by far the most common ``function symbol'' (other than [47mif[0m) under which one finds additional tests and recursive calls. In the next section we'll discuss a theorem that makes use of these insights and demonstrates that the finer scheme can lead to faster proofs. An Actual Example of Coarse versus Fine Induction Schemes The ACL2 prettyprinter is implemented with the function [47mppr[0m. It is basically the composition of two functions, [47mppr1[0m, which takes the object to be printed and computes a ``ppr tuple'' describing how much to indent each subexpression and where to break the lines, and [47mppr2[0m, which actually prints. To admit [47mppr[0m as a logic mode function we have to prove termination and verify the guards of all the functions involved. To verify the guards, we have to prove that [47mppr1[0m returns a [47mppr-tuple-p[0m. You can see the definitions of [47mppr1[0m and [47mppr-tuple-p[0m and their mutually recursive peers by using the [47m:[0m[47m[pe][0m command, e.g., [47m:pe ppr1[0m. We'll focus here on [47mppr1[0m, which is mutually recursive with [47mppr1-lst[0m. To prove anything interesting about a function in a mutually recursive clique you generally have to simultaneously prove analogous theorems about every function in the clique. That is most often done by defining a ``flagged'' function which can recur as any function in the clique according to a flag. The community book [47mbooks/tools/flag[0m provides a convenient way to do that. Since that book facilitates the introduction of the flagged function, it allows the generated definition to be processed with a user-supplied ruler-extenders. A good demonstration of the ``coarse'' and ``fine'' induction schemes for [47mppr1[0m can be found in the community book [47mbooks/demos/ppr1-experiments[0m. We summarize the contents of that book here. The book proves that [47mppr1[0m returns a [47mppr-tuple-p[0m and [47mppr1-lst[0m returns a [47mppr-tuple-lst-p[0m. In fact, it does that proof seven times, under coarse and fine inductions and variations on some hints. The coarse induction is obtained by admitting a flagged version of [47mppr1[0m/[47mppr1-lst[0m under the default ruler-extenders. The fine induction is obtained by admitting a differently named flagged version of [47mppr1[0m/[47mppr1-lst[0m with [47m:ruler-extenders :lambdas[0m. The coarse induction, generated under the default ruler-extenders, has 76 cases. Six are base cases. The other 70 are induction steps with varying numbers of induction hypotheses as given in the sketch below. (76 ;; 76 cases in the induction scheme (0 . 6) ;; no induction hyps in 6 cases, i.e., Base Cases (1 . 8) ;; 1 induction hyp in 8 cases (2 . 2) ;; 2 induction hyps in 2 cases (3 . 16) ;; 3 induction hyps in 16 cases (4 . 32) ;; 4 induction hyps in 32 cases (8 . 4) ;; 8 induction hyps in 4 cases (9 . 8)) ;; 9 induction hyps in 8 cases The fine induction, generated under the [47m:lambdas[0m ruler-extension, can be similarly sketched. (256 ;; 256 cases in the induction scheme (0 . 6) ;; no induction hyps in 6 cases, i.e., Base Cases (1 . 8) ;; 1 induction hyp in 8 cases (2 . 82) ;; 2 induction hyps in 82 cases (3 . 80) ;; 3 induction hyps in 80 cases (4 . 80)) ;; 4 induction hyps in 80 cases The induction generated under the [47m:all[0m ruler-extensions is identical to the fine induction for [47mppr1[0m and [47mppr1-lst[0m. (No governing [47mif[0ms are hidden under function calls other than [47mif[0m and [47mlambda[0m expressions in those two functions.) Regardless of which induction scheme we use, the proof that [47mppr1[0m returns a [47mppr-tuple-p[0m and that [47mppr1-lst[0m returns a [47mppr1-tuple-lst-p[0m fails without a certain hint: we have to tell the prover to expand the calls of [47mppr1[0m and [47mppr1-lst[0m in the conclusions of the induction steps. If you try to prove the theorem without the hint the first checkpoint makes clear that you need the hint. (This is not an uncommon problem in inductive proofs about mutually recursive functions.) But in the most basic like-for-like comparison of the successful proof of the theorem by each induction scheme augmented by an [47m:expand[0m hint, the coarse induction takes 2,165 seconds and the fine induction takes 65 seconds. See scenarios 1 and 3 in the next section. Comparing Several Optimizations After noticing the performance differences between the coarse and fine inductions we spent some time trying to further optimize the proof. We compared seven different combinations of approaches. We discuss them here. See the [47mbooks/demos/ppr1-experiments[0m for the details of each hint, etc. The times reported below were originally recovered from the [47m.cert.out[0m file after certification of the book in September, 2023, using the development copy of ACL2 slated to become Version 8.6, running in CCL on a Macbook Pro. Inspect the [47m.cert.out[0m file for more recent results. As mentioned previously, a common situation with inductive proofs about complicated mutually recursive functions is that the calls in the conclusion aren't always automatically opened by ACL2's heuristics. So it is not unusual in such proofs to provide a hint that explicitly expands the [47mppr1[0m and [47mppr1-lst[0m calls in the conclusion. In these experiments we provide that hint two ways, either as part of fairly sophisticated computed hint or with an [47m:expand[0m hint on [47m"Goal"[0m. If you try to prove this theorem with no hint it fails. We will also be experimenting with the enabled status of [47mppr1[0m and [47mppr1-lst[0m. The seven scenarios are specified by saying which induction scheme is used, whether [47mppr1[0m and [47mppr1-lst[0m are enabled or disabled by default, and what hints are provided. There are three basic hints to chose from. * [47mcomputed[0m --- when a subgoal becomes stable, open [47mppr1[0m and [47mppr1-lst[0m in the conclusion, and when any subgoal of that becomes stable again, enable [47mppr1[0m and [47mppr1-lst[0m and let ACL2's heuristics take over. This hint only makes sense if [47mppr1[0m and [47mppr1-lst[0m are initially disabled. * [47mcomputed'[0m --- like [47mcomputed[0m but skips the first stable opening of [47mppr1[0m and [47mppr1-lst[0m. That is handled instead by an [47m:expand[0m hint. * [47m:expand[0m --- a traditional [47m:expand[0m hint to open [47mppr1[0m and [47mppr1-lst[0m terms as they appear in induction conclusions. The expand hint is :expand ((:free (print-base print-radix width rpc state eviscp) (ppr1 x print-base print-radix width rpc state eviscp)) (:free (print-base print-radix width rpc pair-keywords-p state eviscp) (ppr1-lst lst print-base print-radix width rpc pair-keywords-p state eviscp))) which allows the non-controller arguments of [47mppr1[0m and [47mppr1-lst[0m to be any terms but insists that the controllers, [47mx[0m and [47mlst[0m, respectively, be those particular variable names. In addition, we sometimes avail ourselves of special-purpose lemmas. * [47mNIL lem[0m --- rewrites [47m(ppr1-lst nil ...)[0m to [47mnil[0m. * [47mMAX hack[0m --- lemmas about [47mMAX[0m allowing us to disable [47mMAX[0m We try seven different combinations, numbered 1-7, but listed below in descending order of proof times. n induction status hints proof time 1 coarse enabled :expand 2165.19 2 coarse disabled computed 207.49 6 fine disabled computed 82.29 3 fine enabled :expand 65.00 4 fine disabled computed + :expand 62.86 5 fine disabled computed' + :expand + NIL lem 61.58 7 fine disabled computed + :expand + MAX hack 55.14 Note that scenarios 1 and 3 are a direct comparison of coarse and fine induction with exactly the same hint. The coarse induction took 2165.19 seconds and the fine induction took 65.00, despite the fact that the coarse induction had 76 cases to deal with and the fine induction had 256. The most likely reason the coarse induction performed poorly is that there were 8 induction steps that had 9 induction hypotheses each, even though no case ever actually required more than 4 induction hypotheses. Scenario 2 shows that much time is saved by disabling [47mppr1[0m and [47mppr1-lst[0m and expanding them (when stable) with the computed hint. Note that since the computed hint first expands them in the conclusion and lets the resulting subgoals stabilize before enabling [47mppr1[0m and [47mppr1-lst[0m, the calls of [47mppr1[0m and [47mppr1-lst[0m in the induction hypotheses do not expand until the relevant case analysis is exposed by expanding the conclusion. Scenarios 4, 5, 6, and 7, attempt to improve upon the time seen in scenario 3. We see that the best performance in this particular problem is to use the fine induction case analysis, keep the relevant recursive functions disabled by default, use an [47m:expand[0m hint to open them in the conclusion but also have a computed hint that expands them in the conclusions if a stable subgoal arises, and only enable those functions if they're still in the subsequently stable subgoals. The [47mMAX hack[0m saves another 10% by avoiding case splits caused by the many occurrences of [47mMAX[0m in [47mppr1[0m. However, it should be noted that the major source of improvement is the use of the fine induction scheme. The fact that there is only a 10% further improvement achieved by the various other hints suggests it may not be worth the effort! Coding the computed hint took time and thought, compared to just using an [47m:expand[0m hint. And it was a lot easier to leave [47mppr1[0m and [47mppr1-lst[0m enabled and let ACL2 decide when to expand them than it was to disable them and control their expansion by hints and lemmas. One take-home lesson for us was that ACL2's heuristics for opening recursive functions are pretty good! Ignoring scenario 7 --- where the additional improvement came from a completely different source, namely, avoiding the expansion of [47mMAX[0m expressions --- the difference between the easiest thing to do (scenario 3) and the fastest method that focused on manually controlling [47mppr1[0m and [47mppr1-lst[0m (scenario 5) was less than 4 seconds. So, as usual with all kinds of performance optimization, don't get sucked down the rabbit hole! Take the easy wins and get on with the rest of your project! Conclusion Of course, whether fine induction schemes will improve other proofs just depends on how many irrelevant induction hypotheses are present and how complicated it is to simplify the terms in the theorem. If you are proving something about a recursive function that contains [47mlet*[0m expressions in which some of the bindings conditionally make recursive calls, be alert to the possibility that adjusting ruler-extenders to include [47m:lambdas[0m may give better inductive performance. If you witness the prover engaged in fairly deep case splits, even as it seems always to prove the resulting cases, you might look for ways to get a finer induction case analysis.") (induction-depth-limit (induction) "The maximum number permitted of nested inductions ACL2 may limit the number of levels of induction. Consider for example a subgoal with this [goal-spec]: Subgoal *1.2.3.1.2.3.1.2.3/7'11' This represents nine levels of induction. By default, that is the maximum permitted, since proofs rarely succeed with more than a few levels of induction. (Indeed, one is well served by relying on only one level of induction, avoiding nested inductions in favor of proving suitable [rewrite] rules. See [the-method].) Thus, if ACL2 would otherwise attempt to push the subgoal indicated above for later proof by induction, the overall proof would fail because that would cause the maximum nesting depth of 9 to be exceeded. To see the current limit: (induction-depth-limit (w state)) This limit is always a natural number, with one exception: it can be [47mnil[0m, which means that there is no limit on the nesting depth of inductions. Note that an explicit [47m:induct[0m hint (see [hints]) will cause an induction to occur, regardless of the induction-depth-limit. Of course, if we have already reached the induction-depth-limit at the point the [47m:induct[0m hint is applied, then any attempt to push a subgoal for induction will fail (unless it too has an associated [47m:induct[0m hint). To change the limit, see [set-induction-depth-limit]. For another way to limit the lengths of proof attempts, see [47m[set-subgoal-loop-limits][0m. Subtopics [Set-induction-depth-limit] Set the [induction-depth-limit]") (induction-heuristics (rule-classes) "How ACL2 selects induction schemes This topic is for those curious about induction heuristics in ACL2. It is not necessary to understand those heuristics to be able to use ACL2 successfully. ACL2's heuristics for generating an induction scheme for a conjecture are very similar to Nqthm's and can trace their roots all the way back to the Edinburgh Pure Lisp Theorem Prover, the first prover to support induction in a general setting. For a detailed description of how ACL2 generates induction schemes see {``ACL2 Induction Heuristics.'' | http://www.cs.utexas.edu/users/moore/publications/acl2-induction-heuristics.pdf} That paper is intended for a general audience familiar with induction but not necessarily familiar with theorem provers or ACL2. However, it can also serve as a guided tour through that part of the ACL2 source code that creates and selects induction schemes.") (infected-constraints (encapsulate) "[47m[Events][0m affecting [constraint]s of [47m[encapsulate][0ms Here we explain briefly the two kinds of [47m"Infected"[0m [warnings] that are sometimes printed near the end of the output from [47m[encapsulate][0m [events]. Also see [constraint] for a more complete discussion of constraints produced by [47mencapsulate[0m events, and see [subversive-recursions] for a more complete discussion of the second kind of [47m"Infected"[0m warning mentioned below, in the last example. An [47m"Infected"[0m warning indicates that an event introducing a function symbol inside [47mencapsulate[0m event affects the constraint exported for the function introduced in the [signature] list of that [47mencapsulate[0m. That function is typically introduced with [47m[defun][0m, but it could be introduced in a signature list of a subsidiary [47mencapsulate[0m event or in a [47m[defchoose][0m event. Below we'll discuss the case of [47mdefun[0m, but the others are completely analogous for an [47m"Infected"[0m warning. Let's compare the following three examples. [31;1mEXAMPLE 1[0m. (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (cons x x))) (defun foo (x) (sig-fn x)) (defthm foo-prop (consp (foo x)))) In Example 1 above, ACL2 warns us that the [47mdefun[0m event is having an effect on the constraint of another function (more on that below). ACL2 Warning [Infected] in ( ENCAPSULATE (((SIG-FN * ...) ...) ...) ...): Note that the definitional equation for FOO infects the constraint of this encapsulation.... Indeed, just above that warning we see that the definitional equation for [47mfoo[0m is part of the constraint not only on [47mfoo[0m but also on [47msig-fn[0m. The following constraint is associated with both of the functions FOO and SIG-FN: (AND (EQUAL (FOO X) (SIG-FN X)) (CONSP (FOO X))) The warning message suggests the desirability of moving the definition out of the [47mencapsulate[0m, if possible. That is not possible above: the definition of [47mfoo[0m cannot be moved before the [47mencapsulate[0m because it depends syntactically on [47msig-fn[0m, and it cannot be moved after the [47mencapsulate[0m because it depends syntactically on [47mfoo-prop[0m. By contrast, in the next two examples the [47mdefun[0m of [47mfoo[0m can be moved before, respectively after, the [47mencapsulate[0m. In these simple cases, ACL2 in effect does that for us automatically, and the constraint for [47msig-fn[0m doesn't mention [47mfoo[0m or vice-versa. In other cases, you might want to think about how to move the relevant [47mdefun[0m (for [47mfoo[0m, in this case) manually. [31;1mEXAMPLE 2[0m (moving the definition of [47mfoo[0m before the [47mencapsulate[0m). (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (cons x x))) (defun foo (x) x) (defthm foo-prop (equal (foo x) (car (sig-fn x))))) [31;1mEXAMPLE 3[0m (moving the definition of [47mfoo[0m after the [47mencapsulate[0m). (encapsulate (((sig-fn *) => *)) (local (defun sig-fn (x) (cons x x))) (defun foo (x) (sig-fn x)) (defthm foo-prop (consp (sig-fn x))) ) We now turn to a second kind of [47m"Infected"[0m warning for a [47mdefun[0m form inside an [47mencapsulate[0m form. This type of warning indicates that in addition to the effect on constraints discussed above, ACL2 refuses to store an induction scheme or a built-in [type-prescription] rule for the [47mdefun[0m. Consider the following example. [31;1mEXAMPLE 4[0m. (encapsulate (((f *) => *)) (local (defun f (x) (cdr x))) (defthm f-prop (equal (f nil) nil)) (defun g (x) (if (consp x) (g (f x)) x))) As in Example 1 above, the exported constraint is on both function symbols that have been introduced, reported as follows by ACL2. The following constraint is associated with both of the functions G and F: (AND (EQUAL (F NIL) NIL) (EQUAL (G X) (IF (CONSP X) (G (F X)) X))) But this time, in addition, no induction scheme is stored for [47mg[0m, nor is any built-in [type-prescription] rule stored for [47mg[0m, as indicated by a warning that begins as follows. ACL2 Warning [Infected] in ( ENCAPSULATE (((F * ...) ...) ...) ...): Note that G is ``subversive.'' See :DOC infected-constraints.... Note that if [47mf[0m and [47mg[0m had been similarly defined at the top level instead of within an [47mencapsulate[0m, a type-prescription rule would be added asserting that ``the type of G is described by the theorem [47m(NOT (CONSP (G X)))[0m.'' But there is no such rule introduced in this ``subversive'' case. Indeed, this ``theorem'' is not actually a theorem after evaluating the [47mencapsulate[0m, as it does not even follow from the stronger axiom (stronger, that is, than the constraint displayed above) that both [47mf[0m and [47mg[0m are the identity function. See [subversive-recursions] for more details, including criteria for when this ``subversive'' situation arises and what might be done to address it. Also see [constraint] for a general discussion of constraints introduced by an [47m[encapsulate][0m event.") (initialize-event-user (output-controls) "User-supplied code to initiate [events] This utility is intended for system hackers, not standard ACL2 users. See [finalize-event-user] to see how to supply code to be run at the end of [events]. We assume familiarity with [47mfinalize-event-user[0m; here we focus on how to supply code for the beginning as well as the end of events. As with [finalize-event-user], you attach your own function of argument list [47m(ctx qbody state)[0m to [47minitialize-event-user[0m. (See [finalize-event-user] for discussion of [47mctx[0m and [47mbody[0m.) The attachment should return [47mstate[0m and have a trivial guard, requiring (implicitly) only that [47mstate[0m satisfies [47mstate-p[0m unless you use trust tags to avoid that requirement. For example: (defattach-system initialize-event-user initialize-event-user-test) Why would you want to do this? Presumably you are building a system on top of ACL2 and you want to track your own data. For example, suppose you want to save the time in some [state] global variable, [47mmy-time[0m. You could do the following. (defun my-init (ctx body state) (declare (xargs :stobjs state :guard-hints (("Goal" :in-theory (enable read-run-time)))) (ignore ctx body)) (mv-let (seconds state) (read-run-time state) (f-put-global 'start-time seconds state))) (defun my-final (ctx body state) (declare (xargs :stobjs state :guard-hints (("Goal" :in-theory (enable read-run-time)))) (ignore ctx body)) (mv-let (seconds state) (read-run-time state) (prog2$ (if (boundp-global 'start-time state) (cw "Time: ~x0 seconds~%" (- seconds (fix (@ start-time)))) (cw "BIG SURPRISE!~%")) (f-put-global 'end-time seconds state)))) (defattach-system initialize-event-user my-init) (defattach-system finalize-event-user my-final) Here is an abbreviated log, showing the time being printed at the end. ACL2 !>(thm (equal (append (append x y) x y x y x y x y) (append x y x y x y x y x y))) *1 (the initial Goal, a key checkpoint) is pushed for proof by induction. .... ACL2 Error in ( THM ...): See :DOC failure. ******** FAILED ******** Time: 869/100 seconds ACL2 !>") (inline (pointers) "See [defun-inline].") (installation (acl2 about-acl2) "Installing ACL2 See the [installation-instructions] for steps to install ACL2 on Unix-like systems (Linux, macOS, and FreeBSD). If you encounter problems installing ACL2, or need more information, see [installation-support]. See [copyright] for information about copyright, license, and authorship of the ACL2 system, and see [acknowledgments] for sponsorship information. For a variant of ACL2 that supports reasoning about the real numbers, see [real]. See [mailing-lists] for information about mailing lists for ACL2 users, including how to post and how to access archives. ACL2 may be exported to any countries except those subject to embargoes under various laws administered by the Office of Foreign Assets Control (``OFAC'') of the U. S. Department of the Treasury. For more information about getting started with ACL2, see [start-here]. Also see [using-ACL2] for information about running ACL2 and about its [documentation]. Subtopics [Installation-instructions] ACL2 installation instructions for Unix-like systems [Obtaining-common-lisp] Obtaining Common Lisp [Installation-support] Additional support for ACL2 installation [Using-ACL2] Using ACL2") (installation-instructions (installation) "ACL2 installation instructions for Unix-like systems These instructions describe how to install ACL2 on ``Unix-like systems'', including Linux, macOS (with Intel or ARM processors), and FreeBSD. To install ACL2 on Windows, see [windows-installation]. ACL2 installations include both the ACL2 system and the open-source ACL2 libraries developed by the ACL2 community, called the Community Books (see [COMMUNITY-BOOKS]). 1. Decide which of the following you want to install: * The [31;1mlatest ACL2 release[0m (version 8.6 (see [NOTE-8-6])). The release is stable and very well tested but does not include any improvements or fixes made since October, 2024. It may be appropriate if you do not need the very latest tools and libraries and do not plan to contribute to the [community-books]. A pre-built binary distribution (see [PRE-BUILT-BINARY-DISTRIBUTIONS]) of the release may be available for your platform, which can let you avoid following these installation instructions. * The [31;1mlatest development snapshot[0m from GitHub (likely at most a few days old). Development snapshots are only minimally tested and may (rarely) have problems. However, they provide the latest iteration of ACL2 and the [community-books]. Use a development snapshot if you plan to contribute (see [GITHUB-COMMIT-CODE-USING-PULL-REQUESTS]) additions or changes to the [community-books], or if you plan to update your copy of ACL2 later. Pre-built binary distributions of development snapshots are generally not available. 2. Obtain a Common Lisp implementation if you don't already have one; see [obtaining-common-lisp]. (Note: Some of the [community-books] depend on [Quicklisp], and those are only guaranteed to work with CCL or SBCL.) 3. Depending on your decision in Step 1, download ACL2 by doing either of the following: * [31;1mFor the latest ACL2 release[0m (version 8.6): 1. Change to a directory that does not already contain a subdirectory called [47macl2-8.6[0m. 2. Download { [47macl2-8.6.tar.gz[0m | https://github.com/acl2-devel/acl2-devel/releases/download/8.6/acl2-8.6.tar.gz} to that directory. 3. Execute the following: tar xfz acl2-8.6.tar.gz cd acl2-8.6 The new subdirectory [47macl2-8.6[0m should now be your shell's current directory. * [31;1mOr, for the latest development snapshot[0m: 1. Change to a directory that does not already contain a subdirectory named [47macl2[0m. 2. Execute the following: git clone https://github.com/acl2/acl2 cd acl2 The new subdirectory [47macl2[0m should now be your shell's current directory. 4. Compile ACL2: make LISP=<your_command_to_run_lisp> where [47m<your_command_to_run_lisp>[0m is a command that runs your selected Common LISP and is not merely a shell alias. The default for [47m<your_command_to_run_lisp>[0m is [47mccl[0m. [31;1mNote:[0m You will need GNU Make (preferably newer than Version 3.82). This will create an executable script named [47msaved_acl2[0m (in the current directory) that can be used to run ACL2. 5. Optionally, test ACL2 as follows: ./saved_acl2 :mini-proveall (quit) You should see "Mini-proveall completed successfully." a few lines above the bottom of the output. 6. Certify some books, for example with make basic or something fancier such as the following. (time nice make -j 8 ACL2=/u/smith/bin/acl2 basic) >& make-basic.log This may take only a few minutes, depending your [47m-j[0m value, your machine, and your host Common Lisp. The resulting log should contain no occurrences of the string ``CERTIFICATION FAILED''; a normal exit (status 0) should guarantee this. If you want further options or additional explanation (e.g., you can certify many more books with [47mmake regression[0m, and there is a discussion of avoiding root login), see [books-certification]. You now have an executable script called [47msaved_acl2[0m and access to certified community books. Enjoy! And please consider contributing to the ACL2 libraries; see [how-to-contribute].") (installation-support (installation) "Additional support for ACL2 installation To install ACL2, it will generally suffice to see the [installation-instructions]. You should read the subtopics below only if those instructions were somehow not sufficient. They provide alternate and additional information for obtaining and installing ACL2 and associated libraries. Subtopics [Creating-executable] Creating or obtaining an executable image [Running-ACL2-without-executable] Running ACL2 without building an executable image [Summary-of-ACL2-system-distribution] Summary of ACL2 system distribution [Windows-installation] Installing ACL2 on Windows") (instructions (proof-builder) "Instructions to the interactive proof-builder See [proof-builder] for an introduction to the interactive ``proof-builder'' goal manager, which supports much more direct control of the proof process than is available by direct calls to the prover (as are normally made using [47m[defthm][0m or [47m[thm][0m). In brief, typical use is to evaluate the form [47m(verify SOME-GOAL)[0m, where [47mSOME-GOAL[0m is a formula (i.e., term) that you would like to prove. Various commands (instructions) are available at the resulting prompt; see [proof-builder-commands]. When the proof is completed, suitable invocation of the [47mexit[0m command will print out a form containing an [47m:instructions[0m field that provides the instructions that you gave interactively, so that this form can be evaluated non-interactively. Thus, also see [defthm] for the role of [47m:instructions[0m in place of [47m:[0m[47m[hints][0m. As illustrated by the following example, the value associated with [47m:instructions[0m is a list of interactive [proof-builder] commands. Example: (defthm associativity-of-append (equal (append (append x y) z) (append x (append y z))) :instructions (:induct (:dv 1) (:dv 1) :x :up :x (:dv 2) := (:drop 2) :top (:dv 2) :x :top :s :bash)) See [proof-builder-commands] for a list of supported interactive proof-builder instructions and links to their documentation. Below, we describe a capability for supplying [47m:instructions[0m as [47m:[0m[47m[hints][0m. The most basic utilities for directing the discharge of a proof obligation are [47m:[0m[47m[hints][0m and (less commonly) [47m:instructions[0m. Individual instructions may call the prover with [47m:hints[0m; in that sense, prover hints may occur inside instructions. We now describe how, on the other hand, instructions may occur inside hints. ACL2 supports [47m:instructions[0m as a hints keyword. The following example forms the basis for our running example. This example does not actually need hints, but imagine that the inductive step --- which is "Subgoal *1/2" --- was difficult. You could submit that goal to [47m[verify][0m, do an interactive proof, submit [47m(exit t)[0m to obtain the list of [47m:instructions[0m, and then paste in those instructions. When you submit the resulting event, you might see the following. Below we'll explain the hint processing. ACL2 !>(thm (equal (append (append x y) z) (append x (append y z))) :hints (("Subgoal *1/2" :instructions (:promote (:dv 1) (:dv 1) :x :up :x (:dv 2) := (:drop 2) :top (:dv 2) :x :top :s)))) Name the formula above *1. Perhaps we can prove *1 by induction. Three induction schemes are suggested by this conjecture. Subsumption reduces that number to two. However, one of these is flawed and so we are left with one viable candidate. We will induct according to a scheme suggested by (BINARY-APPEND X Y). This suggestion was produced using the :induction rule BINARY-APPEND. If we let (:P X Y Z) denote *1 above then the induction scheme we'll use is (AND (IMPLIES (AND (NOT (ENDP X)) (:P (CDR X) Y Z)) (:P X Y Z)) (IMPLIES (ENDP X) (:P X Y Z))). This induction is justified by the same argument used to admit BINARY-APPEND. When applied to the goal at hand the above induction scheme produces two nontautological subgoals. [Note: A hint was supplied for the goal below. Thanks!] Subgoal *1/2 (IMPLIES (AND (NOT (ENDP X)) (EQUAL (APPEND (APPEND (CDR X) Y) Z) (APPEND (CDR X) Y Z))) (EQUAL (APPEND (APPEND X Y) Z) (APPEND X Y Z))). But the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC replaces this goal by T. Subgoal *1/1 (IMPLIES (ENDP X) (EQUAL (APPEND (APPEND X Y) Z) (APPEND X Y Z))). By the simple :definition ENDP we reduce the conjecture to Subgoal *1/1' (IMPLIES (NOT (CONSP X)) (EQUAL (APPEND (APPEND X Y) Z) (APPEND X Y Z))). But simplification reduces this to T, using the :definition BINARY-APPEND and primitive type reasoning. That completes the proof of *1. Q.E.D. Summary Form: ( THM ...) Rules: ((:DEFINITION BINARY-APPEND) (:DEFINITION ENDP) (:DEFINITION NOT) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:INDUCTION BINARY-APPEND)) Time: 0.02 seconds (prove: 0.01, print: 0.01, other: 0.00) Proof succeeded. ACL2 !> To understand how the [47m:instructions[0m supplied above were processed, view the interactive proof-builder instruction interpreter as a ``clause-processor'': a function that takes an input goal and returns a list of goals (which can be the empty list). Such a function has the property that if all goals in that returned list are theorems, then so is the input goal. This view of the interactive proof-builder instruction interpreter as a clause-processor leads to the following crucial observation. [31;1mIMPORTANT![0m. Each call of the interactive proof-builder instruction interpreter is treated as a standalone clause-processor that is insensitive to the surrounding prover environment. In particular: * The interactive proof-builder's theory is not sensitive to [47m:in-theory[0m [hints] already processed in the surrounding proof. Indeed, the current theory for which proof-builder commands are processed is just the current theory of the ACL2 logical [world], i.e., the value of [47m(current-theory :here)[0m. Moreover, references to [47m(current-theory :here)[0m in a proof-builder [47min-theory[0m command, even implicit references such as provided by [47m[enable][0m and [47m[disable][0m expressions, are also references to the current theory of the ACL2 logical [world]. * The [rune]s used during an [47m:instructions[0m hint are not tracked beyond that hint, hence may not show up in the [summary] of the overall proof. Again, think of the [47m:instructions[0m hint as a [clause-processor] call, which has some effect not tracked by the surrounding proof other than for the child goals that it returns. We continue now with our discussion of the interactive proof-builder instruction interpreter as a clause-processor. In the example above, the input goal ([47m"Subgoal *1/2"[0m) was processed by the proof-builder instruction interpreter. The result was the empty goal stack, therefore proving the goal, as reported in the output, which we repeat here. [Note: A hint was supplied for the goal below. Thanks!] Subgoal *1/2 (IMPLIES (AND (NOT (ENDP X)) (EQUAL (APPEND (APPEND (CDR X) Y) Z) (APPEND (CDR X) Y Z))) (EQUAL (APPEND (APPEND X Y) Z) (APPEND X Y Z))). But the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC replaces this goal by T. [31;1mRemark.[0m This brief remark can probably be ignored, but we include it for completeness. The [47m:CLAUSE-PROCESSOR[0m message above may be surprising, since the hint attached to [47m"Subgoal *1/2"[0m is an [47m:instructions[0m hint, not a [47m:clause-processor[0m hint. But [47m:instructions[0m is actually a custom keyword hint (see [custom-keyword-hints]), and may be thought of as a macro that expands to a [47m:[0m[47m[clause-processor][0m hint, one that specifies [47mproof-builder-cl-proc[0m as the clause-processor function. The keen observer may notice that the clause-processor is referred to as ``trusted'' in the above output. Normally one needs a trust tag (see [defttag]) to install a trusted clause-processor, but that is not the case for the built-in clause-processor, [47mproof-builder-cl-proc[0m. Finally, we note that [47m:instructions[0m [hints] are ``spliced'' into the hints as follows: the appropriate [47m:[0m[47m[clause-processor][0m hint replaces the [47m:instructions[0m hint, and the other hints remain intact. It may seems surprising that one can thus, for example, use [47m:instructions[0m and [47m:in-theory[0m together; but although the [47m:in-theory[0m hint will have no effect on execution of the [47m:instructions[0m (see first bullet above), the [47m:in-theory[0m hint will apply in the usual manner to any child goals (see [hints-and-the-waterfall]). End of Remark. Now consider the case that the supplied instructions do not prove the goal. That is, suppose that the execution of those instructions results in a non-empty goal stack. In that case, the resulting goals become children of the input goals. The following edited log provides an illustration using a modification of the above example, this time with a single instruction that splits into two cases. ACL2 !>(thm (equal (append (append x y) z) (append x (append y z))) :hints (("Subgoal *1/2" :instructions ((:casesplit (equal x y)))))) [[ ... output omitted ... ]] Subgoal *1/2 (IMPLIES (AND (NOT (ENDP X)) (EQUAL (APPEND (APPEND (CDR X) Y) Z) (APPEND (CDR X) Y Z))) (EQUAL (APPEND (APPEND X Y) Z) (APPEND X Y Z))). We now apply the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC to produce two new subgoals. Subgoal *1/2.2 [[ ... output omitted ... ]] Subgoal *1/2.1 [[ ... output omitted ... ]] We have seen that an [47m:instructions[0m hint may produce zero or more subgoals. There may be times where you wish to insist that it produce zero subgoals, i.e., that it prove the desired goal. The interactive proof-builder's `[47mfinish[0m' command works nicely for this purpose. For example, the following form is successfully admitted, but if you delete some of the commands (for example, the [47m:s[0m command at the end), you will see an informative error message. (thm (equal (append (append x y) z) (append x (append y z))) :hints (("Subgoal *1/2" :instructions ((finish :promote (:dv 1) (:dv 1) :x :up :x (:dv 2) := (:drop 2) :top (:dv 2) :x :top :s))))) If an :instructions hint of the form [47m((finish ...))[0m fails to prove the goal, the clause-processor is deemed to have caused an error. Indeed, any ``failure'' of a supplied proof-builder instruction will be deemed to cause an error. In this case, you should see an error message such as the following: Saving proof-builder error state; see :DOC instructions. To retrieve: (RETRIEVE :ERROR1) In this case, you can evaluate the indicated [47m[retrieve][0m command in the ACL2 read-eval-print loop, to get to the point of failure. You may have noticed that there is no output from the interactive proof-builder in the examples above. This default behavior prevents confusion that could arise from use of proof-builder commands that call the theorem prover such as [47mprove[0m, [47mbash[0m, [47msplit[0m, and [47minduct[0m. These commands produce output for what amounts to a fresh proof attempt, which could confuse attempts to understand the surrounding proof log. You can override the default behavior by providing a command of the form [47m(comment inhibit-output-lst VAL)[0m where [47mVAL[0m is either the keyword [47m:SAME[0m (indicating that no change should be made to which output is inhibited) or else is a legal value for inhibited output; see [set-inhibit-output-lst]. The following two variants of the immediately preceding [47mTHM[0m form will each produce output from the interactive proof-builder commands, assuming in the first variant that output hasn't already been inhibited. (thm (equal (append (append x y) z) (append x (append y z))) :hints (("Subgoal *1/2" :instructions ((comment inhibit-output-lst :same) (:casesplit (equal x y)))))) (thm (equal (append (append x y) z) (append x (append y z))) :hints (("Subgoal *1/2" :instructions ((comment inhibit-output-lst (proof-tree)) (:casesplit (equal x y)))))) Note that such a [47mcomment[0m instruction must be provided explicitly (i.e., not by way of a proof-builder [macro-command]) as the first instruction, in order to have the effect on inhibited output that is described above. The following contrived example gives a sense of how one might want to use [47m:instructions[0m within [47m:[0m[47m[hints][0m. If you submit the following theorem (thm (implies (true-listp x) (equal (reverse (reverse x)) x))) then you will see the following checkpoint printed with the [summary]. Subgoal *1/3'' (IMPLIES (AND (CONSP X) (EQUAL (REVAPPEND (REVAPPEND (CDR X) NIL) NIL) (CDR X)) (TRUE-LISTP (CDR X))) (EQUAL (REVAPPEND (REVAPPEND (CDR X) (LIST (CAR X))) NIL) X)) This suggests proving the following theorem. Here we state it using [47m[defthmd][0m, so that it is immediately disabled. Normally disabling would be unnecessary, but for our contrived example it is useful to imagine disabling it, say because we are following a methodology that tends to keep [rewrite] rules disabled. (defthmd revappend-revappend (equal (revappend (revappend x y) z) (revappend y (append x z)))) We might then enter the interactive [proof-builder] to prove the original theorem interactively, as follows. ACL2 !>(verify (implies (true-listp x) (equal (reverse (reverse x)) x))) ->: bash ***** Now entering the theorem prover ***** Goal' ([ A key checkpoint: Goal' (IMPLIES (TRUE-LISTP X) (EQUAL (REVAPPEND (REVAPPEND X NIL) NIL) X)) Goal' is subsumed by a goal yet to be proved. ]) Q.E.D. Creating one new goal: (MAIN . 1). The proof of the current goal, MAIN, has been completed. However, the following subgoals remain to be proved: (MAIN . 1). Now proving (MAIN . 1). ->: th ; show current goal ("th" for "theorem") *** Top-level hypotheses: 1. (TRUE-LISTP X) The current subterm is: (EQUAL (REVAPPEND (REVAPPEND X NIL) NIL) X) ->: p ; show current subterm only (EQUAL (REVAPPEND (REVAPPEND X NIL) NIL) X) ->: 1 ; dive to first argument ->: p (REVAPPEND (REVAPPEND X NIL) NIL) ->: sr ; show-rewrites 1. REVAPPEND-REVAPPEND (disabled) New term: (REVAPPEND NIL (APPEND X NIL)) Hypotheses: <none> Equiv: EQUAL 2. REVAPPEND New term: (AND (CONSP (REVAPPEND X NIL)) (REVAPPEND (CDR (REVAPPEND X NIL)) (LIST (CAR (REVAPPEND X NIL))))) Hypotheses: <none> Equiv: EQUAL ->: (r 1) ; rewrite with rule #1 above Rewriting with REVAPPEND-REVAPPEND. ->: p (REVAPPEND NIL (APPEND X NIL)) ->: top ; move to the top of the conclusion, making it the current subterm ->: p (EQUAL (REVAPPEND NIL (APPEND X NIL)) X) ->: prove ; finish the proof ***** Now entering the theorem prover ***** Q.E.D. *!*!*!*!*!*!* All goals have been proved! *!*!*!*!*!*!* You may wish to exit. ->: (exit t) ; the argument, t, causes :instructions to be printed (DEFTHM T (IMPLIES (TRUE-LISTP X) (EQUAL (REVERSE (REVERSE X)) X)) :INSTRUCTIONS (:BASH (:DV 1) (:REWRITE REVAPPEND-REVAPPEND) :TOP :PROVE)) NIL ACL2 !>(thm (IMPLIES (TRUE-LISTP X) (EQUAL (REVERSE (REVERSE X)) X)) :hints (("Goal" :INSTRUCTIONS ; copy what was printed above: (:BASH (:DV 1) (:REWRITE REVAPPEND-REVAPPEND) :TOP :PROVE)))) Goal' Q.E.D. Q.E.D. Q.E.D. Summary Form: ( THM ...) Rules: NIL Hint-events: ((:CLAUSE-PROCESSOR PROOF-BUILDER-CL-PROC)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Proof succeeded. ACL2 !> Finally we present an even more contrived example, based on the one above. This example illustrates that there is actually no limit imposed on the nesting of [47m:instructions[0m within [47m:[0m[47m[hints][0m within [47m:instructions[0m, and so on. Notice the indication of nesting levels: ``[47m1>[0m'' to ``[47m<1[0m'' for output from nesting level 1, and ``[47m2>[0m'' to ``[47m<2[0m'' for output from nesting level 2. (thm (implies (true-listp x) (equal (reverse (reverse x)) x)) :hints (("Goal" :instructions ((comment inhibit-output-lst :same) (:prove :hints (("Goal" :in-theory (disable append)) ("Subgoal *1/3''" :instructions ((comment inhibit-output-lst :same) :bash (:dv 1) (:rewrite revappend-revappend))))))))) Here is an edited version of the resulting log. [Note: A hint was supplied for the goal above. Thanks!] [[1> Executing proof-builder instructions]] ->: (COMMENT INHIBIT-OUTPUT-LST :SAME) ->: (:PROVE :HINTS (("Goal" :IN-THEORY (DISABLE APPEND)) ("Subgoal *1/3''" :INSTRUCTIONS ((COMMENT INHIBIT-OUTPUT-LST :SAME) :BASH (:DV 1) (:REWRITE REVAPPEND-REVAPPEND))))) ***** Now entering the theorem prover ***** [[ ... output omitted ... ]] [Note: A hint was supplied for the goal below. Thanks!] Subgoal *1/3'' (IMPLIES (AND (CONSP X) (EQUAL (REVAPPEND (REVAPPEND (CDR X) NIL) NIL) (CDR X)) (TRUE-LISTP (CDR X))) (EQUAL (REVAPPEND (REVAPPEND (CDR X) (LIST (CAR X))) NIL) X)). [[2> Executing proof-builder instructions]] ->: (COMMENT INHIBIT-OUTPUT-LST :SAME) ->: :BASH ***** Now entering the theorem prover ***** [Note: A hint was supplied for the goal above. Thanks!] But we have been asked to pretend that this goal is subsumed by the yet-to-be-proved |PROOF-BUILDER Goal|. Q.E.D. Creating one new goal: (MAIN . 1). The proof of the current goal, MAIN, has been completed. However, the following subgoals remain to be proved: (MAIN . 1). Now proving (MAIN . 1). ->: (:DV 1) ->: (:REWRITE REVAPPEND-REVAPPEND) Rewriting with REVAPPEND-REVAPPEND. [[<2 Completed proof-builder instructions]] We now apply the trusted :CLAUSE-PROCESSOR function PROOF-BUILDER-CL-PROC to produce one new subgoal. Subgoal *1/3''' [[ ... output omitted ... ]] [[<1 Completed proof-builder instructions]] The nesting levels are independent of whether or not output is enabled; for example, if the first [47m(comment ...)[0m form below is omitted, then we will see only the output bracketed by ``[47m2>[0m'' to ``[47m<2[0m''. Note also that these levels are part of the error states saved for access by [47m[retrieve][0m (as indicated above); for example, a failure at level 1 would be associated with symbol [47m:ERROR1[0m as indicated above, while a failure at level 2 would be associated with symbol [47m:ERROR2[0m.") (int= (numbers acl2-built-ins) "Test equality of two integers [47m(int= x y)[0m is logically equivalent to [47m(equal x y)[0m. Unlike [47m[equal][0m, [47mint=[0m requires its arguments to be integers (or else causes a [guard] violation; see [guard]). [47mInt=[0m is intended to execute more efficiently on integers than [47m[equal][0m or [47m[=][0m, though this may not be true for all host Lisps. [31;1mMacro: [0m<int=> (defmacro int= (i j) (list 'eql (if (integerp i) i (list 'the 'integer i)) (if (integerp j) j (list 'the 'integer j))))") (integer-length (numbers acl2-built-ins) "Number of bits in two's complement integer representation For non-negative integers, [47m(integer-length i)[0m is the minimum number of bits needed to represent the integer. Any integer can be represented as a signed two's complement field with a minimum of [47m(+ (integer-length i) 1)[0m bits. The [guard] for [47minteger-length[0m requires its argument to be an integer. [47mInteger-length[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<integer-length> (defun integer-length (i) (declare (xargs :guard (integerp i))) (if (zip i) 0 (if (= i -1) 0 (+ 1 (integer-length (floor i 2))))))") (integer-listp (numbers lists acl2-built-ins) "Recognizer for a true list of integers The predicate [47minteger-listp[0m tests whether its argument is a true list of integers. [31;1mFunction: [0m<integer-listp> (defun integer-listp (l) (declare (xargs :guard t)) (cond ((atom l) (eq l nil)) (t (and (integerp (car l)) (integer-listp (cdr l))))))") (integer-range-p (numbers acl2-built-ins) "Recognizer for integers between two bounds. The predicate [47m(integer-range-p lower upper x)[0m tests whether [47mx[0m is an integer greater than or equal to [47mlower[0m and less than [47mupper[0m. [31;1mFunction: [0m<integer-range-p> (defun integer-range-p (lower upper x) (declare (type integer lower upper)) (and (integerp x) (<= lower x) (< x upper)))") (integerp (numbers acl2-built-ins) "Recognizer for whole numbers [47m(integerp x)[0m is true if and only if [47mx[0m is an integer.") (interesting-applications (acl2-tutorial) "Some industrial examples of ACL2 use ACL2 is an interactive system in which you can model digital artifacts and guide the system to mathematical proofs about the behavior of those models. It has been used at such places as AMD, Centaur, IBM, and Rockwell Collins to verify interesting properties of commercial designs. It has been used to verify properties of models of microprocessors, microcode, the Sun Java Virtual Machine, operating system kernels, other verifiers, and interesting algorithms. Here we list just a few of the industrially-relevant results obtained with ACL2. Reading the list may help you decide you want to learn how to use ACL2. If you do decide you want to learn more, we recommend that you take the [tours] after you leave this page. ACL2 was used at [31;1mMotorola Government Systems[0m to certify several microcode programs for the [31;1mMotorola CAP digital signal processor[0m, including a comparator sort program that is particularly subtle. In the same project, ACL2 was used to model the CAP at both the pipelined architectural level and the instruction set level. The architectural model was bit- and cycle-accurate: it could be used to predict every bit of memory on every cycle. The models were proved equivalent under certain hypotheses, the most important being a predicate that analyzed the microcode for certain pipeline hazards. This predicate defined what the hazards were, syntactically, and the equivalence of the two models established the correctness of this syntactic characterization of hazards. Because ACL2 is a functional programming language, the ACL2 models and the hazard predicate could be executed. ACL2 executed a microcode interpreter several times faster than the hardware simulator could execute it --- with assurance that the answers were equivalent. In addition, the ACL2 hazard predicate was executed on over fifty microcode programs written by Motorola engineers and extracted from the ROM mechanically. Hazards were found in some of these. (See, for example, Bishop Brock and Warren. A. Hunt, Jr. ``Formal analysis of the Motorola CAP DSP.'' In [3mIndustrial-Strength Formal Methods[0m. Springer-Verlag, 1999.) ACL2 was used at [31;1mAdvanced Micro Devices[0m (AMD) to verify the compliance of the [31;1mAMD Athlon[0m's (TM) elementary floating point operations with their IEEE 754 specifications. This followed ground-breaking work in 1995 when ACL2 was used to prove the correctness of the microcode for floating-point division on the [31;1mAMD K5[0m. The AMD Athlon work proved addition, subtraction, multiplication, division, and square root compliant with the IEEE standard. Bugs were found in RTL designs. These bugs had survived undetected in hundreds of millions of tests but were uncovered by ACL2 proof attempts. The RTL in the fabricated Athlon FPU has been mechanically verified by ACL2. Similar ACL2 proofs have been carried out for every major AMD FPU design fabricated since the Athlon. (See for example, David Russinoff. ``A mechanically checked proof of correctness of the AMD5K86 floating-point square root microcode''. [3mFormal Methods in System Design[0m Special Issue on Arithmetic Circuits, 1997.) ACL2 was used at [31;1mIBM[0m to verify the floating point divide and square root on the [31;1mIBM Power 4[0m. (See Jun Sawada. ``Formal verification of divide and square root algorithms using series calculation''. In [3mProceedings of the ACL2 Workshop 2002[0m, Grenoble, April 2002.) ACL2 was used to verify floating-point addition/subtraction instructions for the [31;1mmedia unit[0m from [31;1mCentaur Technology[0m's 64-bit, X86-compatible microprocessor. This unit implements over one hundred instructions, with the most complex being floating-point addition/subtraction. The media unit can add/subtract four pairs of floating-point numbers every clock cycle with an industry-leading two-cycle latency. The media unit was modeled by translating its Verilog design into an HDL deeply embedded in the ACL2 logic. The proofs used a combination of AIG- and BDD-based symbolic simulation, case splitting, and theorem proving. (See Warren A. Hunt, Jr. and Sol Swords. ``Centaur Technology Media Unit Verification''. In [3mCAV '09: Proceedings of the 21st International[0m [31;1mConference on Computer Aided Verification[0m, pages 353--367, Berlin, Heidelberg, 2009. Springer-Verlag.) [31;1mRockwell Collins[0m used ACL2 to prove information flow properties about its [31;1mAdvanced Architecture MicroProcessor 7 Government Version (AAMP7G)[0m, a Multiple Independent Levels of Security (MILS) device for use in cryptographic applications. The AAMP7G provides MILS capability via a verified secure hardware-based separation kernel. The AAMP7G's design was proved to achieve MILS using ACL2, in accordance with the standards set by EAL-7 of the Common Criteria and Rockwell Collins has received National Security Agency (NSA) certification for the device based on this work. (See Matthew M. Wilding, David A. Greve, Raymond J. Richards, and David S. Hardin. ``Formal Verification of Partition Management for the AAMP7G Microprocessor''. In [3mDesign and Verification of Microprocessor Systems for High-Assurance Applications[0m, David S. Hardin, ed., pages 175--191, Springer US, 2010.) Key properties of the [31;1mSun Java Virtual Machine[0m and its [31;1mbytecode verifier[0m were verified in ACL2. Among the properties proved were that certain invariants are maintained by [31;1mclass loading[0m and that the bytecode verifier ensures that execution is safe. In addition, various [31;1mJVM bytecode programs[0m have been verified using this model of the JVM. (See Hanbing Liu. [3mFormal Specification and[0m [3mVerification of a JVM and its Bytecode Verifier[0m. PhD thesis, University of Texas at Austin, 2006.) The [31;1mBoyer-Moore fast string searching algorithm[0m was verified with ACL2, including a model of the JVM bytecode for the search algorithm itself (but not the preprocessing). (See J S. Moore and Matt Martinez. ``A mechanically checked proof of the correctness of the Boyer-Moore fast string searching algorithm.'' In [3mEngineering Methods and Tools for Software Safety and Security[0m pages 267--284. IOS Press, 2009.) ACL2 was used to verify the fidelity between an [31;1mACL2-like theorem prover[0m and a simple (``trusted by inspection'') [31;1mproof checker[0m, thereby establishing (up to the soundness of ACL2) the soundness of the ACL2-like theorem prover. This project was only part of a much larger project in which the resulting ACL2 proof script was then hand-massaged into a script suitable for the ACL2-like theorem prover to process, generating a formal proof of its fidelity that has been checked by the trusted proof checker. (See Jared Davis. [3mMilawa: A Self-Verifying Theorem Prover[0m. Ph.D. Thesis, University of Texas at Austin, December, 2009.) These are but a few of the interesting projects carried out with ACL2. Many of the authors mentioned above have versions of the papers on their web pages. Also see publications and see the presentations in each of the ACL2 Workshops.") (interfacing-tools (top) "Libraries and tools for doing basic file i/o (see [STD/IO]), using raw Common Lisp libraries (see [QUICKLISP]), working with the operating system (see [OSLIB]), and interfacing with other programs (see [BRIDGE]). Subtopics [Command-line] Handling of command-line arguments when ACL2 is invoked [Defttag] Introduce a trust tag (ttag) [Io] Input/output facilities in ACL2 [Save-exec] Save an executable image and a wrapper script [Startup-banner] Modifying the ACL2 startup banner [Sys-call] Make a system call to the host operating system") (intern (symbolp packages acl2-built-ins) "Create a new symbol in a given package [47m(intern symbol-name symbol-package-name)[0m returns a symbol with the given [47m[symbol-name][0m and the given [47m[symbol-package-name][0m. We restrict Common Lisp's [47mintern[0m so that the second argument is either the symbol *main-lisp-package-name*, the value of that constant, or is one of "ACL2", "ACL2-INPUT-CHANNEL", "ACL2-OUTPUT-CHANNEL", or "KEYWORD". To avoid that restriction, see [intern$]. In ACL2 [47mintern[0m is actually implemented as a macro that expands to a call of a similar function whose second argument is a symbol. Invoke [47m:pe intern[0m to see the definition, or see [intern-in-package-of-symbol]. To see why [47mintern[0m is so restricted consider [47m(intern "X" "P")[0m. In particular, is it a symbol and if so, what is its [47m[symbol-package-name][0m? One is tempted to say ``yes, it is a symbol in the package [47m"P"[0m.'' But if package [47m"P"[0m has not yet been defined, that would be premature because the imports to the package are unknown. For example, if [47m"P"[0m were introduced with (defpkg "P" '(COMMON-LISP::X)) then in Common Lisp [47m(symbol-package-name (intern "X" "P"))[0m returns [47m"COMMON-LISP"[0m. The obvious restriction on [47mintern[0m is that its second argument be the name of a package known to ACL2. We cannot express such a restriction (except, for example, by limiting it to those packages known at some fixed time, as we do). Instead, we provide [47m[intern-in-package-of-symbol][0m which requires a ``witness symbol'' for the package instead of the package. The witness symbol is any symbol (expressible in ACL2) and uniquely specifies a package necessarily known to ACL2.") (intern$ (symbolp packages acl2-built-ins) "Create a new symbol in a given package [47mIntern$[0m is a macro that behaves the same as the macro [47m[intern][0m, except for weakening the restriction to a fixed set of package names so that any package name other than [47m""[0m is legal. See [intern]. Note that if you evaluate a call [47m(intern$ x y)[0m for which there is no package with name [47my[0m that is known to ACL2, you will get an error. [47m(Intern$ x y)[0m expands to: (intern-in-package-of-symbol x (pkg-witness y)) See [intern-in-package-of-symbol] and see [pkg-witness].") (intern-in-package-of-symbol (symbolp packages acl2-built-ins) "Create a symbol with a given name Completion Axiom ([47mcompletion-of-intern-in-package-of-symbol[0m): (equal (intern-in-package-of-symbol x y) (if (and (stringp x) (symbolp y)) (intern-in-package-of-symbol x y) nil)) [Guard] for [47m(intern-in-package-of-symbol x y)[0m: (and (stringp x) (symbolp y)) Intuitively, [47m(intern-in-package-of-symbol x y)[0m creates a symbol with [47m[symbol-name][0m [47mx[0m [intern]ed in the package containing [47my[0m. More precisely, suppose [47mx[0m is a string, [47my[0m is a symbol with [47m[symbol-package-name][0m [47mpkg[0m and that the [47m[defpkg][0m event creating [47mpkg[0m had the list of symbols [47mimports[0m as the value of its second argument. Then [47m(intern-in-package-of-symbol x y)[0m returns a symbol, [47mans[0m, the [47m[symbol-name][0m of [47mans[0m is [47mx[0m, and the [47m[symbol-package-name][0m of [47mans[0m is [47mpkg[0m, unless [47mx[0m is the [47m[symbol-name][0m of some member of [47mimports[0m with [47m[symbol-package-name][0m [47mipkg[0m, in which case the [47m[symbol-package-name][0m of [47mans[0m is [47mipkg[0m. Because [47m[defpkg][0m requires that there be no duplications among the [47m[symbol-name][0ms of the imports, [47mintern-in-package-of-symbol[0m is uniquely defined. For example, suppose [47m"MY-PKG"[0m was created by (defpkg "MY-PKG" '(ACL2::ABC COMMON-LISP::CAR)). Let [47mw[0m be [47m'my-pkg::witness[0m. Observe that (symbolp w) is t ; w is a symbol (symbol-name w) is "WITNESS" ; w's name is "WITNESS" (symbol-package-name w) is "MY-PKG" ; w is in the package "MY-PKG" The construction of [47mw[0m illustrates one way to obtain a symbol in a given package: write it down as a constant using the double-colon notation. But another way to obtain a symbol in a given package is to create it with [47mintern-in-package-of-symbol[0m. (intern-in-package-of-symbol "XYZ" w) is MY-PKG::XYZ (intern-in-package-of-symbol "ABC" w) is ACL2::ABC (intern-in-package-of-symbol "CAR" w) is COMMON-LISP::CAR (i.e., ACL2::CAR) (intern-in-package-of-symbol "car" w) is MY-PKG::|car|") (interrupts (pointers) "See [abort-soft].") (intersection$ (lists acl2-built-ins) "Elements common to the given lists General Forms: (intersection$ l1 l2 ... lk) (intersection$ l1 l2 ... lk :test 'eql) ; same as above (intersection$ l1 l2 ... lk :test 'eq) ; same, but eq is equality test (intersection$ l1 l2 ... lk :test 'equal) ; same, but equal is equality test [47m(Intersection$ x y)[0m equals a list that contains the [47mmember[0ms of [47mx[0m that are also [47mmember[0ms of [47my[0m. More precisely, the resulting list is the result of deleting from [47mx[0m those members that are not members of [47my[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing members of the two lists. [47mIntersection$[0m need not take exactly two arguments, though it must take at least one argument: [47m(intersection$ x)[0m is [47mx[0m, [47m(intersection$ x y z ... :test test)[0m is [47m(intersection$ x (intersection$ y z ... :test test) :test test)[0m, and if [47m:TEST[0m is not supplied, then [47m(intersection$ x y z ...)[0m is [47m(intersection$ x (intersection$ y z ...))[0m. For the discussion below we restrict ourselves, then, to the cases [47m(intersection$ x y)[0m and [47m(intersection$ x y :test test)[0m. The [guard] for a call of [47mintersection$[0m (in the two cases just above) depends on the test. In all cases, both arguments must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then one of the arguments must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mintersection$[0m and its variants: [47m(intersection-eq x lst)[0m is equivalent to [47m(intersection$ x lst :test 'eq)[0m; [47m(intersection-equal x lst)[0m is equivalent to [47m(intersection$ x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mintersection-equal[0m. Note that [47mintersection-eq[0m can take any positive number of arguments, in analogy to [47mintersection$[0m; indeed, [47m(intersection-eq ...)[0m expands to [47m(intersection$ ... :test 'eq)[0m. However, [47mintersection-equal[0m is a function, not a macro, and takes exactly two arguments. [47mIntersection$[0m is similar to the Common Lisp primitive [47mintersection[0m. However, Common Lisp does not specify the order of elements in the result of a call of [47mintersection[0m. [31;1mFunction: [0m<intersection-equal> (defun intersection-equal (l1 l2) (declare (xargs :guard (and (true-listp l1) (true-listp l2)))) (cond ((endp l1) nil) ((member-equal (car l1) l2) (cons (car l1) (intersection-equal (cdr l1) l2))) (t (intersection-equal (cdr l1) l2))))") (intersection-eq (pointers) "See [intersection$].") (intersection-equal (pointers) "See [intersection$].") (intersection-theories (theories theory-functions) "Intersect two [theories] Example: (intersection-theories (current-theory :here) (theory 'arith-patch)) General Form: (intersection-theories th1 th2) where [47mth1[0m and [47mth2[0m are theories (see [theories]). To each of the arguments there corresponds a runic theory. This function returns the intersection of those two runic [theories], represented as a list and ordered chronologically. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (intersectp (lists acl2-built-ins) "Test whether two lists intersect General Forms: (intersectp l1 l2) (intersectp l1 l2 :test 'eql) ; same as above (eql as equality test) (intersectp l1 l2 :test 'eq) ; same, but eq is equality test (intersectp l1 l2 :test 'equal) ; same, but equal is equality test [47m(Intersectp l1 l2)[0m returns [47mt[0m if [47ml1[0m and [47ml2[0m have a [47m[member][0m in common, else it returns [47mnil[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing members of the two lists. The [guard] for a call of [47mintersectp[0m depends on the test. In all cases, both arguments must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then one of the arguments must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mintersectp[0m and its variants: [47m(intersectp-eq x lst)[0m is equivalent to [47m(intersectp x lst :test 'eq)[0m; [47m(intersectp-equal x lst)[0m is equivalent to [47m(intersectp x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mintersectp-equal[0m. [31;1mFunction: [0m<intersectp-equal> (defun intersectp-equal (x y) (declare (xargs :guard (and (true-listp x) (true-listp y)))) (cond ((endp x) nil) ((member-equal (car x) y) t) (t (intersectp-equal (cdr x) y))))") (intersectp-eq (pointers) "See [intersectp].") (intersectp-equal (pointers) "See [intersectp].") (introduction-to-a-few-system-considerations (introduction-to-the-theorem-prover) "The mechanics of interaction with the theorem prover ACL2 is implemented in Common Lisp. There are many different Common Lisps and they differ in details relating to interacting with the system. We sometimes refer to the host Common Lisp as ``raw Lisp.'' The new user is advised not to operate in raw Lisp as it is possible to, say, redefine ACL2 system facilities like [47mdefthm[0m. Most people use Emacs (see [Emacs] {ICON} (see [A_Tiny_Warning_Sign])) or the ACL2 Sedan (Eclipse) interface (see [ACL2-Sedan] {ICON} (see [A_Tiny_Warning_Sign])). They provide protection against certain common mistakes, e.g., trying to edit a block of input text after the operating system has buffered it up and sent it to the Lisp reader which is parsing it as you type. More on this below. In addition, the Sedan provides helpful syntax checking and a disciplined approach to the stack of lemmas generated by The Method. But the variety of interfaces to the variety of Lisps mean that there is great variation in what one must type to interact with ACL2. The best example is perhaps trying to interrupt a running proof. For most host Common Lisp implementations, if you are typing directly to the Common Lisp process, then you can interrupt a computation by typing ``ctrl-c'' (hold down the Control key and hit the ``c'' key once). If you are typing to an Emacs process which is running ACL2 in a shell buffer, you should type ctrl-c ctrl-c. If you are running the ACL2 Sedan, you can use the [3mInterrupt Session[0m button on the tool bar. The environment you enter when you interrupt depends on various factors and normally, you will be put back into the top level ACL2 command loop. If not, then you may be in a Lisp break, and you can probably get back into the ACL2 command loop by using an ``abort'' command that depends on the host Common Lisp (e.g., [47m:q[0m for GCL and CCL). You can usually determine what environment you're in by paying attention to the prompt, which we discuss below. The ACL2 ``interactive loop'' is called [47m[lp][0m ({ICON} (see [A_Tiny_Warning_Sign])) and is generally invoked automatically from your Common Lisp when you start up the ACL2 process. [47mLP[0m is just a special case of an ACL2 function called [47m[ld][0m {ICON} (see [A_Tiny_Warning_Sign]), which the user can call from within the ACL2 interactive loop to enter the loop recursively. New users don't have to know this except that it helps explain why some commands have the string ``[47m-ld-[0m'' in their names! ACL2 presents itself as a ``read-eval-print'' loop: you're repeatedly prompted for some type-in, which is read, evaluated, and may cause some printing. The prompt tells you something about ACL2's state. In the standard environment, the prompt is ACL2 !> The ``[47mACL2[0m'' tells you that the symbols you use in your command are those defined in the standard ACL2 namespace (or, in the jargon of Lisp, the ``current package,'' see [current-package] {ICON} (see [A_Tiny_Warning_Sign])). You could create a new namespace (see [defpkg] {ICON} (see [A_Tiny_Warning_Sign])) and set the current package to it (see [in-package] {ICON} (see [A_Tiny_Warning_Sign])). The next part of the prompt above (``[47m![0m''), the exclamation mark) tells you that before ACL2 evaluates your type-in it will check to see whether [47m[guard][0ms ({ICON} (see [A_Tiny_Warning_Sign])) are respected, i.e., whether the functions used in your command are being supplied arguments in their ``expected domains.'' If evaluation is allowed by the guards, it proceeds exactly according to the ACL2 axioms; if evaluation is not allowed, an error is signaled. ACL2 event commands check their arguments thoroughly at run-time, regardless of Lisp's notion of ``expected domains.'' If the exclamation mark is missing from the prompt, ACL2 > then evaluation occurs strictly according to the ACL2 axioms, without regard for any declared guards. You can switch between these two prompts by typing ACL2 !>:set-guard-checking nil to turn guard checking off and ACL2 >:set-guard-checking t to turn it on. Try typing [47m(car 7)[0m to each prompt. If there is a ``[47mp[0m'' in the prompt, ACL2 p!> with or without the exclamation mark: ACL2 p> it means you are in [47m:[0m[47m[program][0m ({ICON} (see [A_Tiny_Warning_Sign])) mode rather than [47m:[0m[47m[logic][0m ({ICON} (see [A_Tiny_Warning_Sign])) mode. In [47m:program[0m mode, [47mdefun[0m just defines Common Lisp programs that you can evaluate, but it adds no axioms and you cannot use such defined functions in theorems or invoke [47mdefthm[0m. [47m:Program[0m mode is often used to prototype a model. Most commands are just typical parenthesized Lisp expressions, like ACL2 !>(defthm rev-rev (implies (true-listp x) (equal (rev (rev x)) x))) but some are typed as keywords followed by a certain number of arguments. For example, to undo the last event you may type ACL2 !>:u or to undo back through the introduction of [47mrev[0m you may type ACL2 !>:ubt rev The first is equivalent to evaluating [47m(u)[0m and the second is equivalent to evaluating [47m(ubt 'rev)[0m. See [keyword-commands] {ICON} (see [A_Tiny_Warning_Sign]). So if you see a sentence like ``to turn on the break rewrite facility, execute [47m:brr t[0m,'' we mean type ACL2 !>:brr t or equivalently ACL2 !>(brr t) If you see a prompt that doesn't look like those above you are probably not typing commands to the standard ACL2 read-eval-print loop! If you've somehow called [47mLD[0m recursively, the prompt ``gets deeper,'' e.g., ACL2 !>> and you can pop out one level with [47m:[0m[47m[q][0m {ICON} (see [A_Tiny_Warning_Sign]) (for ``quit'') or pop to the outermost ACL2 loop with [47m:[0m[47mabort![0m {ICON} (see [A_Tiny_Warning_Sign]). If you are in the outermost call of the ACL2 interactive loop and you type [47m:q[0m, you pop out into raw lisp, which carries some risk; see [q]. The prompt in raw Lisp is generally different from the ACL2 prompt but that is outside our our control and varies from Lisp to Lisp. See [prompt]. To get back into the ACL2 interactive loop from raw lisp, evaluate [47m(LP)[0m. If you see a prompt that looks like an ACL2 prompt but has a number in front of it, e.g., 1 ACL2 > then you're talking to the break rewrite facility (and you are 1 level deep in the example above). Presumably at earlier time in this session you enabled that facility, with [47m:brr t[0m, installed a monitor on some rule, invoked the prover, entered the break, and forgot. Everything you have done (e.g., lemmas you might have proved with [47mdefthm[0m) inside that break will be lost when you exit the break. Since the break rewrite facility is ``ours'' we can tell you how to exit it! To exit our breaks and return to the top-level ACL2 loop, execute [47m:[0m[47m[abort!][0m. If you discover you've been working in a [47mbrr[0m break, exit, turn off the break facility with [47m:brr nil[0m, and redo whatever [47mdefun[0ms and [47mdefthm[0ms you did while in that break. Users of the Emacs interface may occasionally type commands directly in the [47m*shell*[0m buffer running ACL2. This can be ``dangerous'' for two reasons. One is that if you type an event, like a [47mdefun[0m or [47mdefthm[0m, directly to the shell, it will not be recorded in your ``script'' buffer and you may forget it in your final script. The other is that if you attempt to edit a multi-line command on any but the most recent line, e.g., to correct the spelling of [47mdefthm[0m below after you've typed the ``[47m(implies (true-listp x)[0m'' you will confuse the Lisp parser because it has already read ``[47m(defthm rev-rev[0m''. ACL2 !>(defthm rev-rev (implies (true-listp x) This usually provokes the raw Lisp to enter a low level error break from which you must abort, possibly reenter the ACL2 loop, and re-type the corrected command from scratch. Another common mistake when using interfaces other than the ACL2 Sedan is to type an ill-formed ACL2 expression containing dots or commas, which also often provokes a break into the raw Lisp's error handler. The fundamental lesson is that you should pay attention to the prompt and learn what the different prompts mean --- or use the ACL2 Sedan. If you have been working your way through the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (introduction-to-apply$ (apply$) "Background knowledge on how to use [47m[apply$][0m, [47m[defwarrant][0m, etc. Background and Organization [47mApply$[0m is the ACL2 version of LISP's [47mapply[0m function. It takes a ``function'' and a list of argument values, applies the function to the arguments, and returns the result. For example, [47m(apply$ 'expt (list 2 8))[0m returns 256. A good introduction to the basic ideas and challenges of adding [47mapply$[0m to ACL2 is the paper {``Limited Second-Order Functionality in a First-Order Setting'' | http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore, [3mJournal of Automated Reasoning[0m, Springer, [31;1m64[0m, pp 391-422, 2018. We refer to the paper simply as ``the paper.'' Some aspects of the paper are no longer accurate because the implementation of [47mapply$[0m has matured since 2018. But as a basic introduction, rather than a reference guide or user's manual, the paper is a good place to start. It provides motivations and challenges, succinct and precise definitions of relevant concepts, lots of examples, a model and meta-level proof that the extended theory is consistent, and a discussion of the limitations and of related work. The model described in the paper is illustrated concretely in the certified books under [47mbooks/projects/apply-model/[0m. See the [47mREADME[0m file there. The current documentation topic takes a slightly more informal approach but covers much of the same ground. In particular, after some preliminary remarks we coach you through a few simple simple exercises involving [47mapply$[0m and related concepts. During these exercises we draw your attention to some basic lessons to keep in mind. At the end of this topic we list some simple challenge problems. This topic links to reference-level documentation for [47m[apply$][0m and those other concepts. But if you are just getting started with [47mapply$[0m we recommend that you work your way through this topic, including doing the examples described below, without following all the links. Challenges and Basic Solutions The unreachable goal of this work is to allow the ACL2 user to pass `functions' as objects and to apply them. That goal is unreachable because ACL2 remains a first order system. However, we can identify a certain syntactic class of ordinary ACL2 objects, called the `[tame] functions' (which are in fact [3mnot[0m functions but are merely symbols and list expressions) and we can allow names of functions with certain tameness properties to be passed around and used as functions. By the way, in this documentation topic we tend to display certain symbols sometimes in uppercase and sometimes in lowercase. They denote the same symbol. But we use uppercase when we're using the symbol as a quoted constant to be passed to [47mapply$[0m and we use lowercase when we're using the symbol as a function symbol in a term. ``Tameness'' imposes strict rules on how functional arguments are used. We'll discuss it further below. The fundamental question raised by [47mapply$[0m is ``How can [47mapply$[0m know the correspondence between an ordinary ACL2 object, like a symbol or a list, and the ACL2 function the user means to apply?'' For example, if the user defines the function [47mmy-append[0m, how can [47mapply$[0m know that [47m(apply$ 'MY-APPEND (list a b))[0m should expand to [47m(my-append a b)[0m? The ACL2 primitives can be built in. The logical definition of [47mapply$[0m includes a big case split that recognizes about 800 ACL2 primitives, so that for example: (apply$ 'car (list a)) = (car a) and (apply$ 'assoc-equal (list a b)) = (assoc-equal a b). But user-defined functions are problematic because once [47mapply$[0m has been defined in the ACL2 sources it cannot be extended to handle new symbols. Intuitively, if you have defined the [47mn[0m-ary function [47mfoo[0m then you would expect [47m(apply$ 'foo (list a1...an))[0m to be [47m(foo a1...an)[0m. One way to arrange that might be to leave [47mapply$[0m undefined on the symbol [47mfoo[0m but to assume, as by a new axiom or hypothesis, forall a1...an : (apply$ 'foo (list a1...an)) = (foo a1...an). It will turn out that using new axioms for this purpose is a bad idea. Hiding the link between [47mapply$[0m and new symbols in axioms raises a problem with ACL2's notion of [47m[local][0m. This is called ``the [47mLOCAL[0m problem'' and we illustrate it later in this doc topic. But for that reason, the suppositions extending [47mapply$[0m will take the form of hypotheses to be added to conjectures in which the behavior of [47mapply$[0m on new symbols is important. These hypotheses are called ``[47m[warrant][0ms.'' Warrant (Merriam-Webster): (noun) a commission or document giving authority to do something.... In our case, a warrant for [47mfn[0m gives [47mapply$[0m permission to apply [47mfn[0m under some circumstances, by asserting a universally quantified conditional equality about [47mapply$[0m's behavior on [47m'fn[0m. It also tells [47mapply$[0m and the [tame]ness predicates things like how many arguments [47mfn[0m takes and how it uses them by asserting the [47m[badge][0m of [47m'fn[0m. The [47mbadge[0m of [47mfn[0m is an ACL2 object that contains various tokens interpretable by [47mapply$[0m and the tameness predicates. But there is a fundamental logical problem: it is not always possible to satisfy such suppositions. There may be no way that [47mapply$[0m could handle [47mfn[0m. An example of a [47mfn[0m for which that hypothesis is unsatisfiable is (defun russell (x y) (not (apply$ x (list y y)))). This definition of [47mrussell[0m is not recursive: it does not call itself. So this definition is admissible. But if we had a warrant for [47mapply$[0m and that [47mwarrant[0m were as simple as forall x,y : (apply$ 'russell (list x y)) = (russell x y) then we would have this classical problem with self-reference: (russell 'russell 'russell) = {def russell} (not (apply$ 'russell (list 'russell 'russell))) = {warrant russell} (not (russell 'russell 'russell)) which is contradictory. This problem is addressed by introducing the notion of ``tameness.'' Tameness is a syntactic property of terms and functions that implies that it is ok to ``extend'' [47mapply$[0m to handle them. It should be pretty clear that if the user defines an ACL2 function that in no way depends on [47mapply$[0m, e.g., a function like: (defun sq (x) (* x x)) then the hypothesis forall x : (apply$ 'SQ (list x)) = (sq x) is satisfiable: we could have introduced [47msq[0m before [47mapply$[0m and then defined [47mapply$[0m in the first place to handle that particular symbol. [47mSq[0m is a particularly simple example of a tame function. One challenge in this work has been to extend the notion of tameness so that it includes a lot of what a normal ACL2 programmer might want in [47mapply$[0m while maintaining the soundness of the resulting theory. For example, consider the following function, which maps a given function over a list and collects the results. (defun my-collect$ (fn lst) (if (endp lst) nil (cons (apply$ fn (list (car lst))) (my-collect$ fn (cdr lst))))) Our definition of tameness considers [47m(my-collect$ 'SQ lst)[0m to be a tame expression, even though [47mmy-collect$[0m calls [47mapply$[0m. The reason we can allow this is that in this particular call of [47mmy-collect$[0m the function to be applied is itself tame. But if [47m(my-collect$ 'SQ lst)[0m is a tame expression, then [47m'(LAMBDA (LST) (MY-COLLECT$ 'SQ LST))[0m is a tame function and thus (my-collect$ '(LAMBDA (LST) (MY-COLLECT$ 'SQ LST)) z) is a tame expression. So, for example, at the top-level of ACL2 one can do this: ACL2 !>(my-collect$ '(LAMBDA (LST) (MY-COLLECT$ 'SQ LST)) '((1 2 3) (4 5 6) (7 8 9))) ((1 4 9) (16 25 36) (49 64 81)) Of course, this presumes we have defined [47msq[0m and [47mmy-collect$[0m and have analyzed them to make sure they have the appropriate tameness properties. (Note that [47mmy-collect$[0m is not tame, but the way it uses its ``functional'' argument is crucial to the tameness of [47m(my-collect$ 'SQ lst)[0m.) To use [47mapply$[0m to full advantage we need to have analyzed every relevant function definition so we know which arguments are treated like functions and whether they are used in accordance with our restrictions. So if you're defining a function you intend to [47mapply$[0m it is convenient to define it with the new command [47m[defun$][0m, which is just an ordinary [47m[defun][0m followed by a [47m[defwarrant][0m command. If you've already defined the function and then realize you wish to [47mapply$[0m it, you can call [47mdefwarrant[0m yourself. [47mDefwarrant[0m analyzes a [47m:[0m[47m[logic][0m mode definition and produces a badge and a warrant, if possible. Also relevant is the [47m[defbadge][0m command which issues a badge for a function (if possible) but does not issue a warrant. Its primary purpose is to allow [47m:[0m[47mprogram[0m mode functions to be analyzed and badged so they can be safely executed by [47mapply$[0m at the top-level ACL2 loop. But the present discussion focuses primarily on the logical machinery, which requires warrants. We explain further via an annotated example, starting from scratch but from the basic background just sketched. For many additional examples, see [community-books] [47mbooks/projects/apply/report.lisp[0m which is a certified book containing the examples in the paper. [31;1mNote carefully:[0m the directory [47mbooks/projects/apply-model/[0m, mentioned earlier in conjunction with the paper, is different from the directory [47mbooks/projects/apply/[0m just mentioned! The former directory concerns the logical foundations of [47mapply$[0m as they stood when the paper was written. The latter is more directly relevant to ACL2 users and provides useful lemmas about [47mapply$[0m as it is axiomatized and implemented today. It also includes many example theorems. Exercises and Lessons To get started, fire up your ACL2 and define two ordinary ACL2 functions, one that squares its argument and the other that reverses its argument. We show the ACL2 prompt below in front of each form we expect you to execute. ACL2 !>(defun sq (x) (* x x)) ACL2 !>(defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) [31;1mLesson 0:[0m Learn about [47mapply$[0m by reading this tutorial introduction. But this tutorial mentions many undefined concepts: tameness, warrants, badges, ilks. These concepts are intertwined with [47mapply$[0m and warrants through mutual recursion, constraints, rewrite rules, etc.. So we decided not to try to define them here as we go along, though the links provided do provide definitive descriptions. So please tolerate the use of undefined words here --- we'll try to give you a sense of what they mean. [31;1mLesson 1:[0m To use [47mapply$[0m, be sure to include the following book of lemmas. These lemmas are important not just to proving theorems about [47mapply$[0m but to defining functions that use [47mapply$[0m. ACL2 !>(include-book "projects/apply/top" :dir :system) [31;1mLesson 2:[0m To allow [47mapply$[0m to ``work'' on a function symbol the symbol must be ``warranted.'' Actually, of course, you can pass anything to [47mapply$[0m and the axioms will reduce it to some value: ACL2 is untyped and all functions are total! But [47mapply$[0m won't work in the logic as you expect if the first argument to [47mapply$[0m is not warranted! (And [47mapply$[0m won't work as you expect for top-level evaluation if its first argument is not at least badged.) To issue warrants (and badges) for [47msq[0m and [47mrev[0m do: ACL2 !>(defwarrant sq) ACL2 !>(defwarrant rev) [47m[Defwarrant][0m checks that its argument, [3mfn[0m, is a defined function symbol that satisfies certain restrictions on how it uses its arguments, restrictions that enable us to define the tameness predicates and that allow [47mapply$[0m to ``work'' without causing logical contradictions. [47mDefwarrant[0m causes an error if [3mfn[0m does not obey our rules. But if [47mdefwarrant[0m does not cause an error it produces a ``badge'' for [3mfn[0m that describes which formals are treated as ``functions.'' Henceforth, we'll say such formals have ``[ilk]'' [47m:FN[0m. In addition to computing a badge, non-erroneous calls of [47mdefwarrant[0m introduce a ``[47m[warrant][0m function'' for [3mfn[0m. The warrant function for [3mfn[0m is a 0-ary function named [47mapply$-warrant-[0m[3mfn[0m. A call of the warrant function, i.e., the term [47m(apply$-warrant-[0m[3mfn[0m[47m)[0m is called the ``warrant'' for [3mfn[0m and if the warrant for [3mfn[0m is included among the hypotheses of a conjecture then [47m(apply$ '[0m[3mfn[0m[47m (list a1 ... an))[0m can expand to [47m([0m[3mfn[0m[47m a1 ... an)[0m, provided the [47mai[0m meet the tameness requirements required by [3mfn[0m's badge. [31;1mLesson 3:[0m We'll say more about tameness, badges, and warrants later. You already know that warrants can only be issued for [47m:logic[0m mode functions because the function symbol is used as a function in the logical definition of the warrant. But you might as well learn four major limitations of [47mapply$[0m: (i) [47mApply$[0m does not take [47m[state][0m or [stobj] arguments and so cannot call any function that takes [47mSTATE[0m or [47mstobj[0m arguments. (ii) [47mApply$[0m cannot call a function whose measure, well-founded relation, or domain predicate depends on [47mapply$[0m. (iii) [47mApply$[0m cannot call a function that itself uses [47mapply$[0m unless that function's measure is a natural number or a lexicographic combination of naturals formed with [47mllist[0m as defined in the Community Books at [47mbooks/ordinals/[0m. (iv) [47mApply$[0m cannot call a function that itself uses [47mapply$[0m if that function was defined mutually recursively. Another way of saying all this is that [47mdefwarrant[0m will cause an error if you try to warrant a function violating (i), (ii), (iii) or (iv). [31;1mLesson 4:[0m If you want to define a function and immediately call [47mdefwarrant[0m on it you can use the handy macro [47mdefun$[0m. We'll use [47mdefun$[0m freely below. [31;1mLesson 5:[0m You can define functions that take warranted ``functions'' as arguments and [47mapply$[0m them. Here is a function that applies its first argument to every element of its second argument and collects the results. We sometimes call functions like [47mmy-collect$[0m ``mapping functions'' because they map another function over some range. We would call them ``functionals'' except that suggests ACL2 is higher-order and it is not! So we most often call them [scion]s of [47mapply$[0m. In ordinary English usage, a ``scion'' is a descendant of an important family or individual; our scions are ``descendants'' of [47mapply$[0m and inherit its power and restrictions. ACL2 !>(defun$ my-collect$ (fn lst) (if (endp lst) nil (cons (apply$ fn (list (car lst))) (my-collect$ fn (cdr lst))))) In this definition, the first argument has ilk [47m:FN[0m because it is used exclusively as a ``function:'' it reaches the first argument of [47mapply$[0m and is untouched otherwise. The second argument has ilk [47mNIL[0m and we say it's ``ordinary.'' It is [3mnever[0m used as a function. Note: We define [47mmy-collect$[0m with [47mdefun$[0m simply to illustrate [47mdefun$[0m. Unless we mean to pass [47mmy-collect$[0m to [47mapply$[0m or to some scion in the future, there is no reason to have a warrant for [47mmy-collect$[0m. Had we defined [47mmy-collect$[0m with the ordinary [47mdefun[0m and realized later that we want to pass [47m'MY-COLLECT$[0m into a slot of ilk [47m:FN[0m, we could get a warrant for [47mmy-collect$[0m by calling [47m(defwarrant my-collect$)[0m. Actually, the function [47mcollect$[0m is pre-defined in ACL2 and behaves like [47mmy-collect$[0m. We chose to introduce [47mmy-collect$[0m simply to illustrate that new scions can be introduced and used. Here's another useful pre-defined scion. You won't need to define it in your ACL2 session to use it. (defun$ always$ (fn lst) (if (endp lst) t (and (apply$ fn (list (car lst))) (always$ fn (cdr lst))))) It checks that every element of [47mlst[0m satisfies its [47m:FN[0m argument [47mfn[0m. The reason that both [47mcollect$[0m and [47malways$[0m are pre-defined is that they are part of the support for the [47m[loop$][0m statment. [31;1mLesson 6:[0m You can run scions on warranted function symbols: ACL2 !>(my-collect$ 'SQ '(1 -2 3 -4)) (1 4 9 16) ACL2 !>(my-collect$ 'rev '((1 2 3) (4 5 6) (7 8 9))) ((3 2 1) (6 5 4) (9 8 7)) You might wonder why you can run [47mmy-collect$[0m on [47m'SQ[0m --- which evaluates [47mapply$[0m on [47m'SQ[0m --- without explicitly acknowledging the warrant that links [47m(apply$ 'SQ (list a))[0m to [47m(sq a)[0m. The reason is that evaluation in ACL2's top-level read-eval-print loop assumes all existing warrants are provided. Warrants only become important when we start dealing with proofs. [31;1mLesson 7:[0m You can run scions on tame quoted [47mLAMBDA[0m objects. These [47mLAMBDA[0m objects can even include calls of scions, provided they are tame. ACL2 !>(my-collect$ (lambda$ (x) (CONS 'SQUARES (MY-COLLECT$ 'SQ x))) '((1 2 3) (4 5 6))) ((SQUARES 1 4 9) (SQUARES 16 25 36)) Note that the ``function symbols'' in the ``body'' of a quoted [47mLAMBDA[0m object may reach [47mapply$[0m as the [47mLAMBDA[0m object is applied. [47mLAMBDA[0m objects are just quoted list expressions that start with the symbol [47mLAMBDA[0m and look like lambda-expressions. But quoted [47mLAMBDA[0m objects have to have fully translated bodies and meet other restrictions so [47mapply$[0m can interpret them. You cannot use macros like [47m+[0m or [47mcond[0m and must you quote all constants. We urge you not to try to type quoted [47mLAMBDA[0m objects by hand! Instead, we provide a macro, [47m[lambda$][0m, that allows you to write lambda expressions in untranslated form. [31;1mLesson 8:[0m There are three very similar looking but very different notions used in this documentation: lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions. Read carefully! See [47m[lambda][0m for some definitions and disambiguation help. The [47mLAMBDA[0m objects reaching [47mapply$[0m must be fully translated (and tame) to be handled correctly. The special macro [47mlambda$[0m will translate for you. ; Don't type quoted LAMBDA objects like this! ACL2 !>(my-collect$ '(LAMBDA (x) (IF (< x '0) (BINARY-* '10 x) (SQ x))) '(1 -2 3 -4)) (1 -20 9 -40) ; Type this instead! ACL2 !>(my-collect$ (lambda$ (x) (if (< x 0) (* 10 x) (sq x))) '(1 -2 3 -4)) (1 -20 9 -40) [31;1mLesson 9:[0m Almost all ACL2 primitives are known to [47mapply$[0m. For a complete list of the built-ins evaluate (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP APPLY$ EV$) (strip-cars *badge-prim-falist*)) You can freely use these ACL2 primitives with [47mapply$[0m and in your [47mlambda$[0m expressions, without warrants. [31;1mLesson 10:[0m You can prove and use theorems about scions. ACL2 !>(defthm my-collect$-append (equal (my-collect$ fn (append a b)) (append (my-collect$ fn a) (my-collect$ fn b)))) ACL2 !>(thm (equal (my-collect$ (lambda$ (x) (* x x)) (append c d)) (append (my-collect$ (lambda$ (x) (* x x)) c) (my-collect$ (lambda$ (x) (* x x)) d)))) Notice that the lemma [47mmy-collect$-append[0m talks about an arbitrary [47mfn[0m. The definition of [47mapply$[0m is completely irrelevant to this theorem! Once [47mmy-collect$-append[0m has been proved can be instantiated with anything for [47mfn[0m. This is demonstrated when the [47mthm[0m above is proved: the proof is just to rewrite with [47mmy-collect$-append[0m. Notice that the only function being [47mapply$[0m'd in the [47mthm[0m above is the primitive multiplication function, which is built into apply$. [31;1mLesson 11:[0m But when your theorems depend on the behavior of [47mapply$[0m on particular user-defined functions, you will need to provide hypotheses stipulating the behavior of [47mapply$[0m on those values. Those hypotheses are the [3mwarrants[0m for the (non-primitive) function symbols involved. Here is an example: Recall the function [47msq[0m defined and warranted above. We might wish to prove that if [47mlst[0m is a list of integers then [47m(my-collect$ 'SQ lst)[0m is a list of natural numbers. We can use [47malways$[0m to express the notions of ``list of integers'' and ``list of naturals.'' We could try to state the conjecture this way: ACL2 !>(thm (implies (always$ 'INTEGERP lst) (always$ 'NATP (my-collect$ 'SQ lst)))). But the attempt to prove that formula will fail because it depends on the fact that the [47msq[0m of an integer is a natural [3mand on the assumption that[0m [47m(apply$ 'SQ (list x))[0m [3mis[0m [47m(sq x)[0m. That assumption is what the [3mwarrant[0m for [47msq[0m tells us. Thus, the warrant for [47msq[0m is required as a hypothesis! The following theorem can be proved. ACL2 !>(defthm all-natp-collect$-sq (implies (and (warrant sq) (always$ 'INTEGERP lst)) (always$ 'NATP (collect$ 'SQ lst)))) Note that we don't need to provide warrants for [47mintegerp[0m or [47mnatp[0m because they are ACL2 primitives and thus built into the behavior of [47mapply$[0m. But we must provide the warrant for [47msq[0m because we know the proof depends on [47m(apply$ 'sq (list x1 ...))[0m simplifying to [47m(sq x1)[0m. The macro form [47m(warrant f1 ... fk)[0m expands to the conjunction of the warrants for the [47mfi[0ms. That is (warrant f1 ... fk) = (and (apply$-warrant-f1) ... (apply$-warrant-fk)). If you attempt a proof and it fails, and you see among the checkpoints terms of the form [47m(apply$ 'fn (list a1 ... an))[0m, then you probably forgot to call [47mdefwarrant[0m on [47mfn[0m and [47mapply$[0m doesn't know what to do with that symbol! If, on the other hand, you see a [forcing-round] checkpoint that is attempting to prove a warrant, like [47m(apply$-warrant-fn)[0m, then you probably forgot to add the warrant for [47mfn[0m to the hypotheses of the conjecture you're trying to prove. [31;1mLesson 12:[0m Warrants solve the ``[47mLOCAL[0m problem.'' Imagine the trouble we'd be in if the theorem above did not require a warrant on [47msq[0m. We could get away with this: (encapsulate nil (local (defun sq (x) (* x x))) (defthm unwarranted-all-natp-collect$-sq (implies (always$ 'INTEGERP lst) (always$ 'NATP (collect$ 'SQ lst))))) (defun sq (x) (* x x x)) (thm (implies (always$ 'INTEGERP lst) (always$ 'NATP (collect$ 'SQ lst)))) This would be a disaster because the final [47mthm[0m is invalid since [47m(sq -2)[0m here is [47m-8[0m and yet the [47mthm[0m is trivially proved by appealing to the unwarranted theorem exported from the encapsulate. If we could prove the unwarranted theorem we could export it because it does not mention or depend on the locally defined function [47msq[0m, it just mentions the constant symbol [47m'SQ[0m. Fortunately, we cannot actually prove the unwarranted version of the theorem because there is no [3ma priori[0m connection between [47m(apply$ 'SQ (list x))[0m and [47m(sq x)[0m. And if we add the warrant for [47msq[0m to the [47mdefthm[0m in the encapsulate we can prove the theorem but then we cannot export it because the warrant ancestrally depends on locally defined function [47msq[0m. [31;1mLesson 13:[0m While we may have given the impression that we've provided a convenient fragment of second-order functionality in ACL2 its limitations will annoy you! For example, when ACL2 tries to use the lemma (defthm all-natp-collect$-sq (implies (and (warrant sq) (always$ 'INTEGERP lst)) (always$ 'NATP (collect$ 'SQ lst)))) it just employs its usual first-order matching algorithm. Thus, the lemma won't apply to (always$ 'NATP (collect$ (lambda$ (x) (* x x)) lst)) because the constant symbol [47m'SQ[0m is not the same as the constant list generated by translating [47mlambda$[0m expression, [47m[47m'(LAMBDA (X) (BINARY-* X X))[0m[47m[0m, even though they are equivalent if understood as functions. See the discussion at [47m[fn-equal][0m. [31;1mLesson 14:[0m Recall Lesson 0! Before you start to use [47mapply$[0m outside of this simple demo script, we advise you to read the documentation for [47mapply$[0m. [31;1mAn Advanced Lesson:[0m We conclude this tutorial by defining one of the most useful scions and proving a couple of theorems illustrating its flexibility: [47mfoldr[0m. ACL2 !>(defun$ foldr (lst fn init) (if (endp lst) init (apply$ fn (list (car lst) (foldr (cdr lst) fn init))))) Note that [47mfoldr[0m maps over the list in its first argument, applying its second argument to two things: successive elements of the list and the result of recursively calling itself on the rest of the list. It returns its third argument when the list is empty. When its functional argument is [47mCONS[0m [47mfoldr[0m is just the concatenation of its other two arguments: ACL2 !>(defthm foldr-cons (equal (foldr x 'CONS y) (append x y))) We do not need a warrant for [47mcons[0m because it is built into [47mapply$[0m. In fact, the built-ins don't have warrants but if you unnecessarily list a primitive in a [47mwarrant[0m expression, like [47m(warrant foldr cons)[0m, it just ignores the primitives that are built into [47mapply$[0m. By supplying a certain [47mlambda[0m expression we can use [47mfoldr[0m to reverse its first argument: ACL2 !>(defthm foldr-can-be-rev (implies (warrant foldr) (equal (foldr x (lambda$ (x y) (FOLDR y 'CONS (CONS x nil))) nil) (rev x)))) Note that the [47mlambda$[0m expression calls [47mFOLDR[0m. Because of this, we must provide the warrant for [47mfoldr[0m since that inner [47mfoldr[0m will be applied by the outer [47mfoldr[0m. This illustrates an important point made in Lesson 7 above: scions can apply other scions, including themselves, as long as the applications are tame. Some Practice Problems There is no better way to learn than to practice. So here are a few challenge problems. The answers can be found in [47mbooks/projects/apply/answers-to-doc-intro-to-apply.lisp[0m. [31;1mProblem 1[0m: Assume [47mfn[0m is a binary relation. Define [47m(insert$ e lst fn)[0m to insert [47me[0m into the list [47mlst[0m in front of the first element, [47md[0m, in [47mlst[0m such that [47m(fn e d)[0m is true. [31;1mProblem 2[0m: Define [47m(sort$ lst fn)[0m to be an insertion sort algorithm for the binary relation [47mfn[0m, e.g., to successively insert each element into the recursively sorted remaining elements. (Note: There is no assurance that [47msort$[0m will actually produce a list ordered by [47mfn[0m because we don't know that [47mfn[0m is an ordering relation.) [31;1mProblem 3[0m: Study the four examples below, which illustrate perhaps surprising properties of our ``insertion sort'' function. (If your definitions don't have these properties you should back up and redefine your functions as we vaguely described above!) (defthm examples-of-sort$ (and (equal (sort$ '(1 3 -7 0 23) '<) '(-7 0 1 3 23)) (equal (sort$ '(1 3 -7 0 23) (lambda$ (x y) t)) '(1 3 -7 0 23)) (equal (sort$ '(1 3 -7 0 23) (lambda$ (x y) nil)) '(23 0 -7 3 1)) (equal (sort$ '(1 a 2 x b 3 4 y c) (lambda$ (x y) (symbolp x))) '(a x b y c 4 3 2 1))) :rule-classes nil) [31;1mProblem 4[0m: Prove the following theorem suggested especially by the last example above. To state this theorem we first introduce the familiar reverse function, [47mrev[0m. (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) and we use the pre-defined function [47m(when$ fn lst)[0m which computes the elements of [47mlst[0m satisfying the unary-function [47mfn[0m, in the order in which they occur, e.g., [47m(when$ '(1 a 2 b) 'symbolp)[0m is [47m'(a b)[0m. Prove (defthm sort$-lambda-symbolp (implies (true-listp lst) (equal (sort$ lst (lambda$ (x y) (symbolp x))) (append (when$ 'symbolp lst) (rev (when$ (lambda$ (x y) (not (symbolp x))) lst)))))) Lemmas will be needed. [31;1mProblem 5[0m: Define [47m(orderedp$ lst fn)[0m to check whether [47mfn[0m holds between each adjacent pair of elements in [47mlst[0m. Test your function with (defthm examples-of-orderedp$ (and (orderedp$ '(1 3 5 7) '<) (not (orderedp$ '(1 3 3 5 7) '<))) :rule-classes nil) [31;1mProblem 6[0m: You might hope that [47m(orderedp$ (sort$ lst fn) fn)[0m is a theorem. But it is not as is easily shown by the example [47m(orderedp$ (sort$ '(3 1 5 3 7) '<) '<)[0m. If you try to prove the conjecture and inspect the output you'll see that the proof fails because we do not know that [47m(or (fn x y) (fn y x))[0m is true. That is, we don't know that [47mfn[0m is [3mStrongly Connected[0m. How could we, since the conjecture is claimed for all [47mfn[0m? Unfortunately, it is awkward to state that [47mfn[0m is a strongly connected relation in ACL2's first-order quantifier-free language. This is a good example of the limitations of ACL2's support for second-order functions! But we can prove versions of the conjecture for concrete strongly connected [47mfn[0ms. The relation named [47mbefore-dayp[0m, below, is strongly connected, as demonstrated by the events following its definition. Carry out these events. (defun beforep (x y lst) (if (and (member x lst) (member y lst)) (member y (member x lst)) t)) (defun before-dayp (x y) (beforep x y '(mon tue wed thu fri sat sun))) (defthm before-dayp-strongly-connected (implies (not (before-dayp x y)) (before-dayp y x))) (in-theory (disable before-dayp)) Now, prove the version of [47m(orderedp$ (sort$ lst fn) fn)[0m for the instance in which [47mfn[0m is [47m'before-dayp[0m.") (introduction-to-hints (introduction-to-the-theorem-prover) "How to provide hints to the theorem prover We assume you've read [introduction-to-rewrite-rules-part-1], [introduction-to-key-checkpoints], and [introduction-to-the-database]. You may give the theorem prover a hint that is specific to a particular subgoal generated during a proof attempt. Of course, you learn the name of the subgoal by inspecting the key checkpoints or other proof output. You are not expected to anticipate the need for hints at specific subgoals; instead, you usually deduce that a hint is required because the subgoals is not proved but you see that existing rules and context make it provable. The most common hint is to enable and/or disable a particular rule on some particular subgoal. (defthm [3mname[0m [3mformula[0m :hints (("Subgoal *1/3.2''" :in-theory (disable nth-nthcdr)))) The hint above tells the rewriter that just before it begins to work on [47mSubgoal *1/3.2''[0m it should switch to a local theory in which all of the rules generated from the event [47mnth-nthcdr[0m are disabled. That local theory remains the one in use for all descendant subgoals generated from the one named, until and unless one of those descendant subgoals has an [47m:in-theory[0m hint associated with it. There are many kinds of hints besides [47m:in-theory[0m and in general, after each subgoal name, you can give various forms of advice and list various adjustments you wish to make to the context in which the prover is operating when it begins addressing the subgoal named. The top-level goal is always named [47mGoal[0m. Thus (defthm [3mname[0m [3mformula[0m :hints (("Goal" ...[3mhints1[0m...) ("Subgoal *1/3.2''" ...[3mhints2[0m...))) has the effect of using [3mhints1[0m for the top-level goal and all of its children throughout the entire proof, except for [47mSubgoal *1/3.2''[0m and its children, where [3mhints2[0m is used instead. There are a few hints which ``take effect'' exactly on the subgoal to which they are attached and are not inherited by their descendants. Here is an incomplete list of some of the more common hints; we note the ones that do not pass on their effects to their descendants. We recommend that you not follow the advanced links (marked ``{ICON} (see [A_Tiny_Warning_Sign])'') below until you have read the entire tutorial. See [in-theory] {ICON} (see [A_Tiny_Warning_Sign]) for how to enable and/or disable rules. The new theory is computed by a ``theory expression'' (see [theories] {ICON} (see [A_Tiny_Warning_Sign])) such as [47m(disable nth-nthcdr)[0m and typically makes adjustments such as additions or deletions to the global current theory. All the relevant new theories are computed before the proof begins. Thus, in (defthm [3mname[0m [3mformula[0m :hints (("Goal" :in-theory (disable rule1)) ("Subgoal *1/3.2''" (disable rule2)))) the theory mentioned for [47mGoal[0m is the global current theory minus [47mrule1[0m, while the theory mentioned for its descendant, [47mSubgoal *1/3.2''[0m, is the global current theory minus [47mrule2[0m. In particular, if both [47mrule1[0m and [47mrule2[0m are enabled in the global current theory, then [47mrule1[0m is enabled during the processing of [47mSubgoal *1/3.2''[0m because it was not removed explicitly there. See [use] {ICON} (see [A_Tiny_Warning_Sign]) for how to force the theorem prover to take note of particular instances of particular theorems; in particular, the instances are created and added as hypotheses to the subgoal in question. The hint is not inherited by the descendants of the subgoal (since the formula being proved has been modified by the hint). If the rule you are using (with a [47m:use[0m hint) is an enabled rewrite rule, it might interfere with the added hypothesis --- by rewriting itself to [47mT[0m --- and thus often you will both [47m:use ...[0m and [47m:in-theory (disable ...)[0m. See [expand] {ICON} (see [A_Tiny_Warning_Sign]) for how to tell the theorem prover to expand one or more function calls whenever encountered. See [cases] {ICON} (see [A_Tiny_Warning_Sign]) for how to force the theorem prover to do a case split to prove the subgoal under each of an exhaustive list of cases given in the hint. This hint takes action specifically at the named subgoal and is not passed down to its children. See [induct] {ICON} (see [A_Tiny_Warning_Sign]) for how to tell the theorem prover to go immediately into induction for the subgoal in question, and to use the induction scheme suggested by the hint rather than the one suggested by the terms in the subgoal itself. This hint is not inherited by its descendants. See [hints] {ICON} (see [A_Tiny_Warning_Sign]) for a complete list of all hints, and see [hints-and-the-waterfall] {ICON} (see [A_Tiny_Warning_Sign]) for a more thorough description of how the effects of hints at a subgoal are inherited by the descendants. If you are reading this as part of the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (introduction-to-key-checkpoints (introduction-to-the-theorem-prover) "What questions to ask at key checkpoints We assume you've read about rewrite rules; see [introduction-to-rewrite-rules-part-1]. When a proof attempt fails, ACL2 prints some [3mkey checkpoints[0m. These are formulas that we think you should look at. There are two kinds printed: key checkpoints [3mbefore an induction[0m, and key checkpoints [3munder a top-level induction[0m. (Key checkpoints under deeper inductions and checkpoints that aren't considered ``key'' may exist in the proof attempt, but ACL2 doesn't print them at the end of failed proofs because you shouldn't be distracted by them.) Below is a list of questions to ask yourself about the key checkpoints. Initially, we recommend just picking one key checkpoint [3mbefore[0m an induction (perhaps the simplest looking one) and asking these questions. These questions may lead you to look at other key checkpoints. As you gain more experience you'll elaborate and generalize this advice. [31;1m(1) Do you believe this formula is a theorem?[0m If you don't think it is, it's pointless to try to prove it! You should reconsider your top-level formula in light of the special case suggested by this key checkpoint. [31;1m(2) Can it be simplified?[0m Is there some combination of function symbols in it that could be eliminated or simplified by exploiting some simpler fact? By a ``simpler fact'' we mean a theorem about a few of the symbols in this formula. For an example of this see [dealing-with-key-combinations-of-function-symbols]. Don't think about the deep question ``how can I prove the checkpoint?'' until you've got it into its simplest form. [31;1m(3) Is the simpler fact already in the database?[0m If there is some simpler fact that would help clean up the checkpoint but you believe the simpler fact is already in the database, you can use [47m:[0m[47m[pl][0m {ICON} (see [A_Tiny_Warning_Sign]), [47m:[0m[47m[pc][0m {ICON} (see [A_Tiny_Warning_Sign]), [47m:[0m[47m[pbt][0m {ICON} (see [A_Tiny_Warning_Sign]), and other [3mhistory[0m commands to inspect the database; (see [history] {ICON} (see [A_Tiny_Warning_Sign])). But if you find the allegedly relevant simpler fact in the database, you must ask: [31;1mwhy wasn't it used?[0m There are four principal reasons: (3a) it is disabled --- so enable it; you'll learn how when you read the coming sections on [introduction-to-the-database] and [introduction-to-hints]. (3b) its left-hand side doesn't match the target --- so improve the rule by generalizing its left-hand side or prove a new rule for this situation; if you decide to remove the old rule from the database, see [3mundo[0m commands in [history] {ICON} (see [A_Tiny_Warning_Sign]). (3c) it is an [47mIFF[0m rule but the target doesn't occur propositionally --- so see if you you can strengthen the rule to an [47mEQUAL[0m rule or weaken the context of the target by changing the conjecture to use the target propositionally; if you decide to remove the old rule from the database, see [3mundo[0m commands in [history] {ICON} (see [A_Tiny_Warning_Sign]). (3d) the hypotheses of the rule cannot be relieved for this occurrence of the target; this can be caused by the rule's hypotheses being too strong (requiring more than they should), or by the hypotheses of the current conjecture being too weak (you forgot some key hypothesis), or by ACL2 not having the rules it needs to prove that the conjecture's hypotheses really do imply the rule's. Tools are available ([47m:[0msee [brr] {ICON} (see [A_Tiny_Warning_Sign])) help you figure out why the rule failed, so use them and improve the rule, or the current conjecture, or the database as appropriate. [31;1m(4) If the simpler fact is not already known, prove it.[0m This means you must create a new [47mdefthm[0m event with appropriate [3mrule-classes[0m to store your new theorem so that it will be used. See [dealing-with-key-combinations-of-function-symbols]. Then you must start using The Method recursively to prove your new lemma. [31;1m(5) Otherwise, is this formula something you'd prove by induction?[0m If you can't simplify it, it may be because you ``need this fact to prove this fact,'' in which case, induction is the right thing to do. But first, remember that in order for a formulas to be provable by induction, it must be very general. Why must it be general? Because in an inductive proof, the main thing you have to work with is the induction hypothesis, which is an instance of the theorem you're proving. If the theorem is not general enough, you won't be able to assume an instance that will help you. ACL2 may try induction even on formulas that are not general enough. Don't assume that the formula is ripe for induction just because ACL2 found an induction to do! Before you ``approve'' a formula for induction, ask whether it is perhaps a special case of some more general theorem. See [generalizing-key-checkpoints] now and then come back here. If you found a generalization, you should probably be proving that formula instead of this one. So formulate the appropriate [47mdefthm[0m and use The Method recursively to prove it. [31;1m(6) If the formula is right for induction, did ACL2 do an induction for it?[0m You can answer that without looking at the proof. Just see if there are any key checkpoints after induction. If not, why didn't ACL2 induct? Perhaps you told ACL2 not to induct! Perhaps no term in the conjecture suggests an appropriate induction? You could remedy this by extending ACL2's induction analysis by adding to the database. Or you could just tell ACL2 what induction to do for this formula. You'll learn about both later (when you read coming sections of the tutorial). [31;1m(7) If ACL2 did do an induction, was it the right one?[0m You can find the induction scheme used by reading the first induction message in the output log after you submitted the conjecture to ACL2. But most often you will realize the ``wrong'' induction was done just by looking at the post-induction key checkpoints, keeping in mind that each is supposed to be a natural special case of the theorem you're proving. Is the case analysis inappropriate? Are induction hypotheses missing? If so, you should look at the induction scheme. If you determine the wrong induction was done, extend ACL2's induction analysis or tell it which induction to do, which you'll learn about in the coming sections of the tutorial. For more advice about looking at post-induction key checkpoints, see [post-induction-key-checkpoints] now and then come back here. [31;1m(8) If the post-induction key checkpoints seems plausible,[0m [31;1mthen repeat the questions above for each one of them,[0m [31;1mperhaps starting with the simplest.[0m In any case, after successfully taking whatever action you've decided on, e.g., proving some new lemma and adding it as a rule: [31;1mStart over trying to prove your main conjecture.[0m This is important! Do not just scroll back to the key checkpoints generated the last time you tried to prove it. Instead, re-generate them in the context of your new, improved database and hints. You will be following this general outline almost all of the time that you're interacting with ACL2. You will not often be asking ``Why is ACL2 making me think about this subgoal? What did ACL2 do to get here? How does ACL2 work?'' Two other ideas are helpful to keep in mind. [31;1mIs a key checkpoint unexpectedly complicated?[0m Pay special attention to the case where the complication seems to be the introduction of low-level details you thought you'd dealt with or by the introduction of symbols you didn't expect to see in this proof. These can be signs that you ought to disable some rules in the database (e.g., a definition of a complicated function about which you've proved all the necessary lemmas or some lemma that transforms the problem as was appropriate for some other proof). [31;1mDoes the theorem prover just hang up, printing nothing?[0m If this happens, you must interrupt it. How you interrupt the prover is dependent on which Common Lisp and which interface you're using. But most Common Lisps treat control-c as a console interrupt. If you're in Emacs running ACL2 as a shell process, you must type control-c control-c. If you're in ACL2s, hit the [3mInterrupt Session[0m button. Interrupting ACL2 can leave you in an interactive loop similar in appearance but different from ACL2's top-level! So pay careful attention to the prompt and see [breaks] {ICON} (see [A_Tiny_Warning_Sign]). Once you've regained control from the ``runaway'' theorem prover, there are several tools you can use to find out what it is doing in real-time. Generally speaking, when the theorem prover goes silent for a very long time it is either in some kind of rewrite loop caused by rules that cause it to flip back and forth between various supposedly normal forms, or else it has split the problem into a huge number of cases and suffering a combinatoric explosion. See [dmr] {ICON} (see [A_Tiny_Warning_Sign]) and, perhaps, see [accumulated-persistence] {ICON} (see [A_Tiny_Warning_Sign]). If you are reading this as part of the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (introduction-to-programming-in-acl2-for-those-who-know-lisp (programming introduction-to-the-theorem-prover) "Introduction to programming in ACL2 for Lisp users The [documentation] topic, [ACL2-built-ins], as well as its parent topic, [programming], are starting points for a rich collection of primitives and features in the ACL2 programming language. In the present topic (below) we give a succinct introduction to that language for those who are already reasonably familiar with Common Lisp, or perhaps another Lisp. Follow the hyperlinks if you want to drill down; for example, we mention multiple values below but say very little about them, instead providing links to topics that explain their handling in a little more depth. The [47m[documentation][0m for ACL2 and its [community-books] provides a rich set of topics for further exploration. This particular topic is intended to serve only as a brief introduction to programming in ACL2 for those who know Lisp, especially Common Lisp. Supplementary reading that may interest a few readers includes ``{A Precise Description of the ACL2 Logic | http://www.cs.utexas.edu/users/moore/publications/km97a.pdf}'' (Matt Kaufmann and J Moore, April, 1998). Applicative Common Lisp The ACL2 (``A Computational Logic for Applicative Common Lisp'') programming language is essentially a subset of Common Lisp --- albeit with some useful extensions --- that is [3mapplicative[0m: the value returned by a function depends only on its inputs, not state. (There is an ACL2 notion of [state], introduced briefly below; but that state must be passed as an explicit argument.) Many commonly-used functions and special forms in the applicative subset of Common Lisp are also in ACL2, such as (to name just a very few) [47m[car][0m, [47m[cons][0m, [47m[nth][0m, [47m[append][0m, [47m[let][0m, and [47m[let*][0m. A few others are not directly included in ACL2 because they have incomplete specifications in Common Lisp, such as [47m[pairlis][0m; according to the Common Lisp HyperSpec: ``The new pairs may appear in the resulting association list in either forward or backward order.'' Many such functions tend to have close analogues in ACL2, named by concatenating [47m"$"[0m to the Common Lisp name; for example, ACL2 has [47m[pairlis$][0m, [47m[union$][0m, and even [47m[random$][0m. Yet other Common Lisp functions, for example [47mformat[0m, are not available in ACL2 but have useful alternatives in ACL2; for example, see [47m[fmt][0m. See [ACL2-built-ins] for a much more comprehensive list of functions, macros, and special forms provided by the ACL2 programming language. In particular, a search through that documentation topic for `[47m$[0m' will show you utilities like [47mpairlis$[0m that are based on related Common Lisp utilities. In the ACL2 read-eval-print loop, you can define functions and macros with [47m[defun][0m and [47m[defmacro][0m just as in Common Lisp, with some restrictions (see for example [name]) and also some additional [47m[declare][0m forms. Data types Only certain Lisp data types are supported for programming in ACL2: numbers that are either rational numbers or complex numbers with rational coefficients (see [numbers-introduction]); the [characters] constructed with [47m(code-char n)[0m for [47mn[0m from 0 to 255; [strings] formed from those characters; [symbols] whose [47m[symbol-name][0m and [47m[symbol-package-name][0m are ACL2 strings; and objects constructed from others using [47m[cons][0m. In particular, arrays are not directly supported as an ACL2 datatype (except for strings). However, ACL2 supports an applicative notion of array, which is logically an association list but has an associated Lisp array that provides fast reads in single-threaded programs. See [arrays]. If your code creates an array and does many more reads to it than writes, or even if there are rarely two writes to the same index (as when writes are primarily to initialize the array), then ACL2 arrays may perform well. Otherwise you may get significantly better performance, avoiding the consing done by writes (to build the association list), by using a different sort of representation of arrays in ACL2: [3msingle-threaded objects[0m, or [3mstobjs[0m; see [stobj]. Structures can be simulated in ACL2 using suitable macros. For a simple such macro that is built into ACL2, together with alternatives to it, see [defrec]. Program and logic modes If you are using ACL2 as a programming language but you do not intend to prove anything about your code, at least not at first, then you might be well-served by using [program] mode. In this mode, ACL2 will admit the definition if syntactic checks succeed, in particular without requiring a proof of termination for recursive definitions. You can specify the mode directly in a declaration (see [xargs] for how to specify [47m:program[0m in a [declare] form), or you can set the default [defun-mode] to [47m:program[0m (see [default-defun-mode] and see [program]). When you are ready to reason about your functions, you can use [47m:[0m[47m[logic][0m mode instead, or you can convert a program-mode function to logic-mode with [47m[verify-termination][0m. Connection to Common Lisp Many Common Lisp functions should only be applied to certain types of objects: for example, [47m[car][0m should only be applied to a cons pair or [47mnil[0m. Every ACL2 function has a [3mguard[0m, which specifies the intended domain of the function; see [guard]. For example, the guard for [47mcar[0m is [47m(OR (CONSP X) (EQUAL X NIL))[0m. See [args] for a utility that provides this and other information about a given function symbol. Beginning ACL2 programmers should probably ignore guards, at least initially. Otherwise, see [xargs] for how to specify a guard; also see [verify-guards]. Multiple values The analogues of Common Lisp utilities [47mmultiple-value-bind[0m and [47mvalues[0m are [47m[mv-let][0m and [47m[mv][0m, respectively. Also see [b*] for an alternative to [47m[let*][0m that can be convenient in the presence of multiple values. State ACL2 provides a notion of [3mstate[0m that is useful for certain kinds of programming. As mentioned above, the state must be passed explicitly because of the applicative nature of ACL2; indeed, it must be passed as the variable, [47mstate[0m, i.e., the symbol in the [47m"ACL2"[0m package whose [47m[symbol-name][0m is [47m"STATE"[0m. This is a rather complex notion, perhaps best avoided by beginning ACL2 programmers. To learn about the ACL2 state, see [state], which points to a topic, [programming-with-state], that discusses many utilities for reading and writing the ACL2 state. More help ACL2 does not provide [47mapropos[0m. However, you can search the documentation to find substring matches. For example, if you type [47mprinc[0m into the ``[47mJump to[0m'' box in the web-based manual, or if you type the command [47mi[0m [for ''index''] into the [ACL2-doc] Emacs-based documentation browser, you will find [47m[princ$][0m. The ``[47mJump to[0m'' box in the web-based manual matches on prefixes, but the [47mi[0m command in [ACL2-doc] matches on any substring. Another way for Lisp programmers to get answers to ``How do I do this in ACL2'' questions is to query the acl2-help mailing list. You can sign up via a link on the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/}. Moreover, that could be a good place to request or suggest improvements to this documentation topic! Also see [history] for some ways to query the current session. Finally, here are a few specific alternatives to Common Lisp utilities. * [47mdescribe[0m: see [47m[doc][0m * [47mfboundp[0m and other utilities to provide information about functions, macros, and special operators: see [47m[args][0m * [47mformat[0m: see [47m[fmt][0m, which has links to related functions that perform formatted printing * [47mlist-all-packages[0m: see [47m[in-package][0m; also see the description of [47mknown-package-alist[0m in [system-utilities] * [47msetq[0m: see [47m[assign][0m, but perhaps first look at the documentation topics for [state] and [programming-with-state] * [47msymbol-plist[0m: see [47m[props][0m, [47m[getprop][0m, and [47m[putprop][0m * [47mwith-open-file[0m: see [io]") (introduction-to-rewrite-rules-part-1 (introduction-to-the-theorem-prover) "Introduction to ACL2's notion of rewrite rules This topic is an introduction to rewrite rules in ACL2 and is intended for the newcomer to ACL2. The slightly more experienced user might benefit from reading [random-remarks-on-rewriting] instead. Rewrite rules make ACL2 replace one term by another. This is done by the rewriter, which is part of ACL2's simplifier. The rewriter sweeps through the goal formula trying all the [rewrite], [definition], and [meta] rules it knows, in order from the most recently submitted rule to the oldest, until it finds one to apply. Here's an example. Just pretend that you have made a rewrite rule from the formula below. (implies (and (natp i) (< i (len a))) (equal (put i v (append a b)) (append (put i v a) b))) Then every time the rewriter sees a target term that [3mmatches[0m (put i v (append a b)) it considers the rule, with the variables [47mi[0m, [47mv[0m, [47ma[0m, and [47mb[0m of the rule [3mbound[0m to whatever terms matched them in the target, say the terms [3mi[0m, [3mv[0m, [3ma[0m, and [3mb[0m. To consider the rule, the rewriter first tries to establish (``relieve'') the hypotheses. In particular, it rewrites: (natp [3mi[0m) ; [3mhyp 1[0m and (< [3mi[0m (len [3ma[0m)). ; [3mhyp 2[0m If both hypotheses rewrite to true, then the rule [3mfires[0m and replaces the target by: (append (put [3mi[0m [3mv[0m [3ma[0m) [3mb[0m). In short, rewrite rules direct ACL2 to rearrange the terms in the goal formulas. We are more precise later, but for now we turn to the question of how do you make a rewrite rule from a formula? The answer is, you prove the formula with the [47mdefthm[0m command. Recall that (defthm [3mname[0m [3mformula[0m ...) commands ACL2 to try to prove [3mformula[0m and, if successful, build it into the database as a rule according to your specification in the [3mrule-classes[0m argument of the ... part of the command. To make it easy for you to generate rewrite rules, [47mdefthm[0m has a simple heuristic: if you don't tell it what kind of rule to generate from [3mformula[0m, it generates a rewrite rule! Thus, if this command (defthm [3mname[0m [3mformula[0m) is successful, ACL2 will have a new rewrite rule in the database, even though you did not [3mexplicitly[0m tell it to add a rule. A common mistake for new users is to forget that the above command adds a rewrite rule. This often results in a tangle of rules that lead nowhere or to infinite rewriting that you will have to interrupt. It is also good to remember that the command [3monly[0m adds a rule. It does not magically make ACL2 aware of all the mathematical consequences of the formula: it just makes a rewrite rule. When you prove a theorem with [47mdefthm[0m you are [3mprogramming[0m ACL2. Being careless in your statement of lemmas is tantamount to being careless in your programming. ACL2 can generate rewrite rules from formulas that look like this: (IMPLIES (AND [3mhyp1[0m ... [3mhypk[0m) ([3meqv[0m [3mlhs[0m [3mrhs[0m)) where [3meqv[0m is either [47mEQUAL[0m or [47mIFF[0m, and [3mlhs[0m is not a variable symbol, not a constant, and not a call of the function [47mIF[0m, and not a call of an abbreviation (``macro'') that expands to any of these. So illegal [3mlhs[0m include [47mX[0m, [47m0[0m, [47m(IF X Y Y)[0m, and [47m(OR p q)[0m. The last is illegal because [47mOR[0m is just an abbreviation for a certain [47mIF[0m-expression. Technical Note: This tutorial introduction to the theorem prover takes liberties with the truth! We are trying to give you a useful predictive model of the system without burdening you with all the details, which are discussed in the ACL2 User's Manual. For example, using directives in the rule-classes you can rearrange the proved formula into the form you want your rule to take, and you can make ACL2 take advantage of equivalence relations [3meqv[0m other than just [47mEQUAL[0m and [47mIFF[0m. But we'll ignore these fine points for now. We call the [3mhyp[0m terms the [3mhypotheses[0m of the rule. We call [3mlhs[0m the [3mleft-hand side[0m of the rule, and we call [3mrhs[0m the [3mright-hand side[0m of the rule. If the conclusion of the rule is an [47mEQUAL[0m term we call it an [3mequality[0m rule. Otherwise, it is a [3mpropositional equivalence[0m rule. If there are no hypotheses, [3mk[0m=0, we say the rule is an [3munconditional[0m rewrite rule; otherwise it is [3mconditional[0m. ACL2 allows several special cases of the shapes above. See [special-cases-for-rewrite-rules], but come back here and continue. A rewrite rule makes ACL2 seek out occurrences of terms that match the left-hand side of the rule and replace those occurrences using the right-hand side, provided all the hypotheses rewrite to true in the context of the application of the rule. That is, the left-hand side is treated as a [3mpattern[0m that triggers the rule. The hypotheses are [3mconditions[0m that have to be proved in order for the rule to fire. The right-hand side is the [3mreplacement[0m and is put into the formula where the pattern occurred. Now for some clarifications. ACL2 only considers enabled rules. And ACL2 will use a propositional rule to replace a target only if the target occurs in a propositional place in the formula. Generally that means it occurs in the argument of a propositional connective, like [47mAND[0m, [47mOR[0m, [47mNOT[0m, [47mIMPLIES[0m, and [47mIFF[0m, or in the test of an [47mIF[0m. When we say that the left-hand side of the rule must [3mmatch[0m the target we mean that we can instantiate the variables in the rule to make the left-hand side identical to the target. To [3mrelieve[0m or establish the hypotheses of the rule, ACL2 just applies other rewrite rules to try to prove the instantiated hypotheses from the assumptions governing the occurrence of the target. When ACL2 replaces the target, it replaces it with the instantiated right-hand side of the rule and then applies rewrite rules to that. If a hypothesis has variables that do not occur in the left-hand side of the rule, then the pattern matching process won't find values for those variables. We call those [3mfree variables[0m. They must be instantiated before ACL2 can relieve that hypothesis. To instantiate them, ACL2 has to guess values that would make the hypothesis true in this context, i.e., true given the assumptions of the goal theorem. So if you're trying to prove (IMPLIES (AND (TRUE-LISTP A) (MEMBER (CAR P) A) (MEMBER (CDR P) A)) ...) and the target you're rewriting is in the ``...'' part of the formula, the rewriter knows that [47m(TRUE-LISTP A)[0m [47m(MEMBER (CAR P) A)[0m and [47m(MEMBER (CDR P) A)[0m are true. So if a rewrite rule is considered and the rule has [47m(member e x)[0m as a hypothesis, where [47me[0m is a free variable but [47mx[0m was bound to [47mA[0m in the pattern matching, then it will guess that [47me[0m must be [47m(CAR P)[0m or [47m(CDR P)[0m, even though there are many other possibilities that would make [47m(MEMBER e A)[0m true. Of course, whatever guess it makes must also satisfy all the other hypotheses that mention [47me[0m in the rule. It simply isn't very imaginative at guessing! The most predictable rewrite rules have no free variables. You can add pragmatic advice to help ACL2 with free variables, telling it to try all the possibilities it finds, to try just the first, or even to compute a ``creative'' guess. It is possible to make the rewriting process loop forever, e.g., by rewriting [3malpha[0m to [3mbeta[0m with one set of rules and rewriting [3mbeta[0m to [3malpha[0m with another. Even a single rule can make the process loop; we'll show you an example of that later in the tutorial. ACL2 can handle commutativity rules without looping. It uses [47m(equal (+ x y) (+ y x))[0m to replace [47m(+ B A)[0m by [47m(+ A B)[0m, but not vice versa. (It is sensitive to alphabetic ordering when dealing with [3mpermutative[0m rules.) Logically equivalent formulas can generate radically different rewrite rules! Rearranging the propositional structure of the formula or swapping the left and right sides of an equality --- while having no effect on the mathematical meaning of a formula --- can have a drastic impact on the pragmatic meaning as a rule. To see an illustration of this, see [equivalent-formulas-different-rewrite-rules]. Developing an effective set of rewrite rules is key to success at using ACL2. We'll look more at this later in the tutorial. If you are working your way through the tutorial for the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover]. If you are reading just about how to make effective rewrite rules, go on to [introduction-to-rewrite-rules-part-2].") (introduction-to-rewrite-rules-part-2 (introduction-to-the-theorem-prover) "How to arrange rewrite rules You should design your rewrite rules to canonicalize the terms in your problem, that is, your rules should drive terms into some normal form so that different but equivalent terms are rewritten into the preferred shape, making equivalent terms identical. You are very familiar with this idea from algebra, where you learned to normalize polynomials. Thus, when you see [3m(2x + 6)(3x - 9)[0m you automatically normalize it, by ``multiplying out and collecting like terms,'' to get [3m(6x^2 - 54)[0m. This normalization strategy allows you to recognize equivalent terms presented differently, such as [3m6(x^2 - 9)[0m. The ACL2 user is responsible for making up the rules. (Standard ``books'' --- files of ACL2 definitions and theorems --- can often provide rules for some sets of functions, e.g., arithmetic.) This is a heavy burden on you but it means you are in charge of your own normal forms. For example, if you use the function [47mnthcdr[0m, which returns the [47mn[0mth [47mcdr[0m of a list, you might see both [47m(cdr (nthcdr i x))[0m and [47m(nthcdr i (cdr x))[0m. These two expressions are equivalent but not identical. You will want to decide which you want to see and prove the rewrite rule that converts the other to that preferred form. Most good users develop an implicit ordering on terms and rewrite ``heavy'' terms to ``lighter'' ones. This ensures that there are no loops in their rewrite rules. But this ordering changes according to the user and the problem. Generally, the lightest terms are primitives such as [47mIF[0m, [47mEQUAL[0m, arithmetic, etc. Functions defined without explicit recursion tend to be ignored because they are just expanded away (but see below). Recursively defined functions tend to be heavier than any other recursive function used in their definitions, so, for example, if [47mrev[0m is defined in terms of [47mappend[0m, [47mrev[0m is heavier than [47mappend[0m. But the size and subtlety of recursively defined functions also affects their place in the ordering. But rewrite rules are surprisingly subtle. Recall that a rewrite rule can be made from a formula of this form: (IMPLIES (AND [3mhyp1[0m ... [3mhypk[0m) ([3meqv[0m [3mlhs[0m [3mrhs[0m)) where [3meqv[0m is either [47mEQUAL[0m or [47mIFF[0m, and [3mlhs[0m is a call of a function other than [47mIF[0m. In such a rule, [3mlhs[0m is the pattern responsible for triggering the rule, the [3mhypi[0m are conditions which must be satisfied by the context of the target being rewritten, and [3mrhs[0m is the replacement. The replacement only happens if the rule is enabled, the pattern matches, the conditions are satisfied, and (in the case of an [47mIFF[0m rule) the target occurs propositionally. There are other heuristic restrictions that we won't discuss here. So how should you phrase a theorem in order to make it an effective rule? General Principles: * [31;1mStrengthen the Formula[0m: The fewer hypotheses a formula has the better the rewrite rule formed from it. The more general the left-hand side the better the rule. The fewer free variables in the hypothesis, the better. The idea is to form a rule that fires predictably. Later in this tutorial you'll get some practice formulating strong rules. * [31;1mChoosing the Conclusion[0m: If a lemma is an implication, you have to choose what the conclusion will be. (You'll also have to ``orient'' that conclusion by choosing a left-hand side and a right-hand side, but we discuss that below). You can swap the conclusion and any hypothesis by negating both, producing a different conclusion. There are generally two (possibly conflicting) heuristics for deciding which part of the formula should be the conclusion: [3mChoosing the Conclusion Heuristic 1[0m: Can you make the conclusion be an [47mEQUAL[0m or [47mIFF[0m expression that has a ``heavy term'' on one side? That will make a rule that replaces the heavy term with a lighter one. We discuss this situation more below. [3mChoosing the Conclusion Heuristic 2[0m: Can you make the conclusion be a non-propositional term that contains all the variables mentioned in the hypotheses? By ``non-propositional'' we mean a term that is not just the propositional combination (e.g., with [47mAND[0m or [47mOR[0m) of other terms but instead some call of some ``heavy'' function? If your conclusion contains all the variables mentioned in the hypotheses, matching it will instantiate all the variables in the hypotheses. That way ACL2 will not have to guess instantiations of unbound variables when it tries to relieve the hypotheses. It is not very good at guessing. * [31;1mOrienting the Conclusion[0m: If the conclusion is an [47mEQUAL[0m or an [47mIFF[0m, you have to decide which is the left-hand side and which is the right. If the conclusion is [47m(NOT[0m [3mlhs[0m[47m)[0m, then the left-hand side is [3mlhs[0m and the right-hand side is [47mNIL[0m. If the conclusion is not an [47mEQUAL[0m, an [47mIFF[0m, or a [47mNOT[0m then the conclusion itself will be the left-hand side and the right-hand side will be [47mT[0m. If your lemma was created by looking at Key Checkpoints while using The Method, the left-hand side should match some term in that checkpoint. Remember, the left-hand side is the ``trigger'' that will make the rule fire. It is the pattern that ACL2 will be looking for. * [31;1mPay attention to the free variables[0m: Look at the variables that occur in the pattern (the left-hand side) and compare them to the variables that occur in the hypotheses. Does some hypothesis contain a variable, say [3mv[0m, that is not in the pattern? We call [3mv[0m a [3mfree variable[0m because it will not be assigned a value (``bound'') by the process of pattern matching. ACL2 will have to guess a value for [3mv[0m. If some hypothesis contains [3mv[0m as a free variable, ask whether more than one hypothesis contains [3mv[0m? ACL2 uses the first hypothesis containing a free [3mv[0m to guide its guess for [3mv[0m. To ``guess'' a value for [3mv[0m, ACL2 uses that hypothesis as a pattern and tries to match it against the assumptions in the checkpoint formula being proved. This means that key hypotheses must be in normal form, to match the rewritten assumptions of the goal. It also means that you should reorder the hypotheses to put the most unusual hypothesis containing a free [3mv[0m first in the list of conjuncts. For example, if [47mv[0m is free in two hypotheses, [47m(natp v)[0m and [47m(member (nthcdr v a) b)[0m, then we recommend putting the [47mmember[0m term first. There are likely to be many terms in the goal satisfying the [47mnatp[0m hypothesis --- or none if [47mnatp[0m has expanded to an integer inequality --- while there are likely to be few terms satisfying the [47mmember[0m hypothesis, especially if [47ma[0m and [47mb[0m are bound by the left-hand side of the rule. Here are some (possibly conflicting) heuristics for choosing the left-hand side: [3mChoose a Left-Hand Side that Occurs in a Key Checkpoint[0m: If you use the Method you will tend to do this anyway, because you'll see terms in the Key Checkpoints that you want to get rid of. But many moderately experienced users ``look ahead'' to how the proof will go and formulate a few anticipatory rules with the idea of guiding ACL2 down the preferred path to the proof. When you do that, you risk choosing left-hand sides that won't actually arise in the problem. So when you formulate anticipatory rules, pay special attention to the functions and terms you put in the left-hand sides. The next few paragraphs deal with specific cases. [3mAvoid Non-Recursive Functions in the Left-Hand Side[0m: If the left-hand side contains a call of a defined function whose definition is not recursive, then it will almost never match any target in the formula being rewritten unless the function is disabled. Suppose for example you have defined [47mSQ[0m so that [47m(SQ x)[0m is [47m(* x x)[0m. Suppose you considered choosing a left-hand side like [47m(+ (SQ x) (SQ y))[0m. Suppose you hoped it would hit the target [47m(+ (SQ A) (SQ B))[0m in some formula. But when ACL2 simplifies the formula, it will first rewrite that target to (+ (* A A) (* B B)) by expanding the definition of [47mSQ[0m, since it could do so without introducing any recursive calls. But now the target won't match your rule. By choosing a left-hand side that occurs in a Key Checkpoint (and is not one of a handful of abbreviations ACL2 uses in its output like [47mAND[0m, [47mNOT[0m), you'll avoid this problem since [47mSQ[0m will have already been expanded before the Key Checkpoint is printed. [3mDisable Non-Recursive Functions[0m: If you insist on a left-hand side that contains calls of non-recursive functions, remember to disable those non-recursive functions after you've proved all the rules you want about them. By disabling [47mSQ[0m you can prevent ACL2 from expanding the definition as it did above. Sometimes you will define a function non-recursively to formalize some concept that is common in your application and you will want to create a sort of algebra of rules about the function. By all means do so, so you can conduct your formal reasoning in terms of the concepts you're informally manipulating. But after proving the required laws, disable the non-recursive concept so that ACL2 just uses your laws and not the messy definition. [3mChoose a Left-Hand Side Already in Simplest Form[0m: This is a generalization of the advice above. If any rule will rewrite your left-hand side, it will prevent your rule from matching any target. For example, if you write a left-hand side like [47m(foo (car (cons x y)))[0m then it would never match any target! The reason is that even if [47m(FOO (CAR (CONS A B)))[0m did occur in some goal formula, before ACL2 would try your rule about [47mfoo[0m it will use the obvious rule about [47mCAR[0m and [47mCONS[0m to transform your imagined target to [47m(FOO A)[0m. Thus, your rule would not match. So you have to keep in mind [3mall your other rules[0m when you choose a left-hand side (and when you choose the hypotheses to guide free variable selection). If you always choose a pattern that matches a term in a Key Checkpoint, you avoid this problem. Also see [community-books] example [47mbooks/demos/knuth-bendix-problem-1.lisp[0m. [3mMake Sure the Left-Hand Side is ``Heavier'' than the Right[0m: Sometimes this is obvious, as when you choose [47m(REV (REV x))[0m for the left-hand side and [47mx[0m for the right. But what do you about [47m(REV (APPEND x y))[0m versus [47m(APPEND (REV y) (REV x))[0m? Most of the time we choose to drive the heaviest function (in this case [47mREV[0m) down toward the variables, lifting the lighter function ([47mAPPEND[0m) up so that we can reason about the lighter function's interaction with the surrounding ``matrix'' of the formula. So we'd rewrite [47m(REV (APPEND x y))[0m to [47m(APPEND (REV y) (REV x))[0m, not vice versa. [3mAlternative Ways to Talk About the Same Thing[0m: If your problem and specification use two different ways to talk about the same thing, choose one form and rewrite the other into that form. For example, the ACL2 built-in [47mnth[0m returns the nth element of a list, and the built-in function [47mnthcdr[0m returns the nth [47mcdr[0m of a list. They are defined independently. But [47m(nth n x)[0m is the same thing as [47m(car (nthcdr n x))[0m. Since [47mnth[0m can be expressed in terms of [47mnthcdr[0m but not vice versa, it is clear we should prove [47m(equal (nth n x) (car (nthcdr n x)))[0m as a rewrite rule if both [47mnth[0m and [47mnthcdr[0m are involved in the problem. [3mDon't Let Computational Efficiency Dictate the Terms[0m: If you have two functions that are equivalent (perhaps one was defined to be computationally more efficient), prove their equivalence as a rewrite rule that eliminates the more complicated function. An extreme example would be a model that uses a sophisticated data structure (like a balanced binary tree, red-black tree, ordered array, or hash table) to implement something simple like an association of keys to values. By proving the equivalence as stated you can eliminate the messy function early and do the bulk of your reasoning in terms of its simple specification. The best ACL2 users become very good at keeping all these things in mind when designing their rewrite rules. Practice makes perfect. Don't be afraid during your learning of ACL2 to undo the rules you first invented and try to make better ones. Finally, be patient! There will be times when you think to yourself ``Why should I spend my time thinking of rules that guide ACL2? I know the proof!'' There are two reasons. First, you may ``know'' the proof but you may well be wrong and part-way through this whole exercise you may realize that you're missing a major hypothesis or special case that breaks your whole conception of the problem. The proof is in the details. Second, most of the time the library of rules you develop in this process will be used over and over again on variants of the main problem in the months and years ahead. This is sometimes called the [3mproof maintenance[0m problem. Theorems don't suffer bit rot! But the artifacts you're modeling change and you will need to prove new versions of old theorems. A good general purpose library makes this much easier. We now recommend that you practice inventing strong rules; see [strong-rewrite-rules]. For advice on handling specific kinds of formulas and definitions, see [specific-kinds-of-formulas-as-rewrite-rules]. For more information about the rewriter works and how rules are created, see [further-information-on-rewriting]. If you are working your way through the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m to return to [introduction-to-the-theorem-prover].") (introduction-to-the-database (introduction-to-the-theorem-prover) "How to update the database We assume you've read [introduction-to-rewrite-rules-part-1] and [introduction-to-key-checkpoints]. The theorem prover's heuristics are influenced by the database of rules and the enabled/disabled status of the rules. You can think of the database as a [3mglobal[0m hint, potentially affecting all parts of a proof attempt. However, in addition to the ``global hint,'' it is possible to give [3mlocal[0m hints that affect the theorem prover's behavior on specific subgoals. We discuss the database here and discuss local hints later in the tutorial. The theorem prover's ``database'' is called the [3mACL2 world[0m. You change the world by issuing commands called [3mevents[0m. The most common events are [47mdefun[0m for defining new functions (and predicates) and [47mdefthm[0m for proving new theorems. Both add rules to the database. Here are some commonly used events. We recommend that upon the first reading of this tutorial you do not follow the links shown below! The links take you into the hypertext reference manual, where it is easy to get lost unless you're looking for detail about one specific feature. See [defun] {ICON} (see [A_Tiny_Warning_Sign]) to define a new function or predicate symbol. Definitional axioms are just a kind of [47mrewrite[0m rule, but [47mdefun[0m may also add rules affecting the determination of the type of a term and rules affecting the induction analysis. When you issue a [47mdefun[0m command you will always supply the [3mname[0m of the function or predicate, the list of [3mformal parameters[0m, [3mv1,...vn[0m, and the [3mbody[0m: (defun [3mname[0m ([3mv1 ... vn[0m) [3mbody[0m) If the event is accepted, a [3mdefinitional axiom[0m is added to the world, [47m([0m[3mname[0m [3mv1...vn[0m[47m)[0m=[3mbody[0m, stored as a special kind of unconditional rewrite rule. However, the [47mdefun[0m event may require theorems to be proved. Specifically, [3mmeasure theorems[0m must be proved to establish that recursively defined functions always terminate, by proving that an [3mordinal[0m measure of the formal parameters decreases in a [3mwell-founded[0m way in every recursive call. In addition, if [3mguards[0m are being used to declare the [3mexpected domain[0m of the newly defined function, [3mguard theorems[0m might be proved to establish that all functions stay within their expected domains. In any case, you may provide additional information to the [47mdefun[0m event, coded as part of the [47mdeclaration[0m that Common Lisp allows: (defun [3mname[0m ([3mv1 ... vn[0m) (declare (xargs ...)) [3mbody[0m) The [47mxargs[0m (``extra arguments to [47mdefun[0m'') entry may specify, among other things, the measure to use in the termination proof, hints for use by the prover during the termination proof, the guard of the new function, and hints for use by the prover during the guard verification step. See [defthm] {ICON} (see [A_Tiny_Warning_Sign]) to prove a theorem and to add it as a rule of one or more specified rule-classes. When you issue a [47mdefthm[0m command you always specify a [3mname[0m for the theorem you're trying to prove and a [3mformula[0m stating the theorem. You may optionally supply some local hints as we describe later in the tutorial. You may also optionally supply some [3mrule classes[0m indicating how you want your formula stored as a rule, after it is proved. We discuss the [47mdefthm[0m [3mrule classes[0m below. See [in-theory] {ICON} (see [A_Tiny_Warning_Sign]) to enable or disable rules. Rules have names derived from the names you give to functions and theorems, e.g., [47m(:REWRITE LEFT-IDENTITY-OF-FOO . 2)[0m for the second rewrite rule you created from the theorem named [47mLEFT-IDENTITY-OF-FOO[0m. Rule names are called [3mrunes[0m. A [3mtheory[0m is just a set (list) of runes. The [3mcurrent theory[0m is the list of enabled runes and the [47min-theory[0m event can add runes to or delete runes from the current theory. See [include-book] {ICON} (see [A_Tiny_Warning_Sign]) to change the world by loading a certified file of other events. The most common use of [47minclude-book[0m is to load ``community books'' --- books written by other ACL2 users who have released them for distribution to the community. The most common books loaded are probably the arithmetic books: ; * for the most elementary arithmetic, needed for any problem ; that involves even simple addition and multiplication like ; [47m(+ x (* 2 y) -3)[0m: (include-book "arithmetic/top-with-meta" :dir :system) ; * for more complicated arithmetic involving non-linear terms like ; [47m(* x y)[0m, [47m(expt x (+ i j))[0m, and [47mfloor[0m and [47mmod[0m (include-book "arithmetic-5/top" :dir :system) But for a complete list of system books, see [books] {ICON} (see [A_Tiny_Warning_Sign]). See [certify-book] {ICON} (see [A_Tiny_Warning_Sign]) to certify a file of events for reuse later. See [defconst] {ICON} (see [A_Tiny_Warning_Sign]) to define a new constant, allowing you to write a symbol, e.g., [47m*weekdays*[0m in place of some object, e.g., [47m'(MON TUE WED THU FRI)[0m in formulas. See [defmacro] {ICON} (see [A_Tiny_Warning_Sign]) to define a new syntactic abbreviation. The macro facility in Lisp is quite powerful, allowing you to [3mcompute[0m the form to which some type-in expands. For example, the primitive macro [47mCOND[0m is defined so that [47m(COND ((P X) 1)((Q X) 2)(T 3))[0m expands to [47m(IF (P X) 1 (IF (Q X) 2 3))[0m. See [defstobj] {ICON} (see [A_Tiny_Warning_Sign]) to introduce a [3msingle-threaded object[0m that your functions may modify ``destructively'' provided they follow strict syntactic rules. See [events] {ICON} (see [A_Tiny_Warning_Sign]) for a complete list of the ACL2 events. There are events to allow mutually recursive definitions, to introduce some new function symbols constrained to satisfy given axioms, to allow the temporary introduction of a ``local'' event to help prove some goal theorem and then disappear, to provide the power of first-order quantification and a choice operator, and many other features. There are also commands that allow you to inspect the world, e.g., to print the command that introduced a given name, to show all the commands back to a certain one, undo the last command or more generally roll-back to an earlier command. See [history] {ICON} (see [A_Tiny_Warning_Sign]). [31;1mThe Defthm Rule-Classes[0m We've already discussed the key role that rules play in controlling the behavior of the system. New rules are introduced primarily with the [47mdefthm[0m event, though [47mdefun[0m and other events may introduce rules. To prove [3mformula[0m and generate, say a [47m:rewrite[0m rule and a [47m:generalize[0m rule from it, you would write (defthm [3mname[0m [3mformula[0m :rule-classes (:rewrite :generalize)) If you wanted to rearrange the shape of the formula before generating the [47m:rewrite[0m rule you could provide a [47m:corollary[0m modifier to the [47m:rewrite[0m rule class: (defthm [3mname[0m [3mformula[0m :rule-classes ((:rewrite :corollary ...) :generalize)). There are many classes of rules, affecting different parts of the system. Each class is denoted by a keyword, e.g., [47m:REWRITE[0m, [47m:LINEAR[0m, etc. You are responsible for specifying the class(es) of rules to be generated from a given formula and several different rules (possibly of different classes) may be derived from a single formula. Each class admits optional modifiers that allow you finer control over each rule. Each class admits the [47m:corollary[0m modifier with which you can rearrange the formula before a rule of that class is generated. This allows you to state a theorem in its most elegant form for publication purposes but store it as a rule with the most appropriate hypotheses and conclusion. Other modifiers tend to be specific to certain rule classes, but for example, [47m:rewrite[0m rule modifiers include an optional limit on the depth of backchaining and options for handling free variables. We give some links below to other classes of rules. However, we recommend that you not follow these links upon your first reading of this tutorial! See [rewrite] {ICON} (see [A_Tiny_Warning_Sign]) for a description of how to create a rewrite rule. See [linear] {ICON} (see [A_Tiny_Warning_Sign]) for a description of how to store theorems concluding with arithmetic inequalities. The trouble with storing (<= (len (delete e x)) (len x)) as a rewrite rule is that it only matches instances of that inequality and thus fails to match (<= (LEN (DELETE E X)) (+ 1 (LEN X))) ACL2 contains an extensible linear arithmetic decision procedure and by storing inequalities as [47m:linear[0m rules you can make that decision procedure aware of the basic inequalities between non-primitive numerically valued terms. See [equivalence] {ICON} (see [A_Tiny_Warning_Sign]), see [congruence] {ICON} (see [A_Tiny_Warning_Sign]), and see [refinement] {ICON} (see [A_Tiny_Warning_Sign]) to learn how to introduce a new equivalence relation to the rewriter. For example, suppose you define [47mset-equal[0m so that it returns t precisely if its two arguments are lists containing the same elements, regardless of order or number of occurrences. Note that under this sense of ``equivalence'', [47m(rev x)[0m is the identity function and [47mappend[0m is commutative, for example. (set-equal (rev x) x) (set-equal (append x y) (append y x)) You can make ACL2 use these two theorems as [47m:rewrite[0m rules to replace instances of [47m(REV x)[0m and [47m(APPEND x y)[0m by [47mset-equal[0m terms, even though the results are not actually [47mEQUAL[0m. This is possible provided the target occurs in a context admitting [47mset-equal[0m as a congruence relation. For example, the congruence rule: (implies (set-equal a b) (iff (member e a) (member e b))) gives the rewriter permission to use the above [47mset-equal[0m rules as rewrite rules in the second argument of any [47mmember[0m expression being used in a propositional way. See [elim] {ICON} (see [A_Tiny_Warning_Sign]) for a description of how to make the system adopt a ``change of variable'' tactic that can trade in [3mdestructor[0m functions for [3mconstructor[0m functions. In analogy with how ACL2 eliminates [47m(CAR X)[0m and [47m(CDR X)[0m by replacing [47mX[0m with [47m(CONS A B)[0m, you can make it eliminate other destructors. For example, the community book [47m"arithmetic-5/top"[0m provides an [47melim[0m rule that eliminates [47m(floor x y)[0m and [47m(mod x y)[0m by replacing [47mx[0m by [47m(+ r (* y q))[0m, so that the [47mfloor[0m expression becomes [47mq[0m and the [47mmod[0m expression becomes [47mr[0m. When introducing your own [47melim[0m rules you will probably also need to introduce [47mgeneralize[0m rules (see below) so that the new variables are appropriately constrained. See [generalize] {ICON} (see [A_Tiny_Warning_Sign]) for a description of how you can make ACL2 restrict the new variables it introduces when generalizing. ACL2 will sometimes replace a term by a new variable and with [47mgeneralize[0m rules you can ensure that the new variable symbol has certain properties of the term it replaces. See [induction] {ICON} (see [A_Tiny_Warning_Sign]) for a description of how to tailor the inductions suggested by a term. Most of the time when ACL2 chooses the ``wrong'' induction, the easiest fix is with a local [47m:induct[0m hint (see below). But if the same problem arises repeatedly in several theorems, you might want to ``educate'' ACL2's induction heuristic. For a complete list of rule-classes, See [rule-classes] {ICON} (see [A_Tiny_Warning_Sign]). If you are reading this as part of the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (introduction-to-the-tau-system (tau-system) "A decision procedure for runtime types This doc topic is the main source of information about the tau system and discusses the general idea behind the procedure and how to exploit it. [3mA ``Type-Checker'' for an Untyped Language[0m Because ACL2 is an untyped language it is impossible to type check it. All functions are total. An [3mn[0m-ary function may be applied to any combination of [3mn[0m ACL2 objects. The syntax of ACL2 stipulates that [47m([0m[3mfn a1...an[0m[47m)[0m is a well-formed term if [3mfn[0m is a function symbol of [3mn[0m arguments and the [3mai[0m are well-formed terms. No mention is made of the ``types'' of terms. That is what is meant by saying ACL2 is an untyped language. Nevertheless, the system provides a variety of monadic Boolean function symbols, like [47m[natp][0m, [47m[integerp][0m, [47m[alistp][0m, etc., that recognize different ``types'' of objects at runtime. Users typically define many more such recognizers for domain-specific ``types.'' Because of the prevalence of such ``types,'' ACL2 must frequently reason about the inclusion of one ``type'' in another. It must also reason about the consequences of functions being defined so as to produce objects of certain ``types'' when given arguments of certain other ``types.'' Because the word ``type'' in computer science tends to imply syntactic or semantic restrictions on functions, we avoid using that word henceforth. Instead, we just reason about monadic Boolean predicates. You may wish to think of ``tau'' as synonymous with ``type'' but without any suggestion of syntactic or semantic restrictions. [3mDesign Philosophy[0m The following basic principles were kept in mind when developing tau checker and may help you exploit it. (1) The tau system is supposed to be a lightweight, fast, and helpful decision procedure for an elementary subset of the logic focused on monadic predicates and function signatures. (2) Most subgoals produced by the theorem prover are not in any decidable subset of the logic! Thus, decision procedures fail to prove the vast majority of the formulas they see and will be net time-sinks if tried too often no matter how fast they are. Tau reasoning is used by the prover as part of [47mpreprocess-clause[0m, one of the first proof techniques the system tries. The tau system filters out ``obvious'' subgoals. The tau system is only tried when a goal first enters the waterfall and when a goal is stable under simplification. (3) The tau system is ``benign'' in the sense that the only way it contributes to a proof is to eliminate (prove!) subgoals. It does not rewrite, simplify, or change formulas. Tau reasoning is not used by the rewriter. The tau system either eliminates a subgoal by proving it or leaves it unchanged. (4) It is impossible to infer automatically the relations between arbitrary recursively defined predicates and functions. Thus, the tau system's knowledge of tau relationships and function signatures is gleaned from theorems stated by the user and proved by the system. (5) Users wishing to build effective ``type-checkers'' for their models must learn how rules affect the tau system's behavior. There are two main forms of tau rules: those that reveal inclusion/exclusion relations between named tau predicates, e.g., that 16-bit naturals are also 32-bit naturals, (implies (n16p x) (n32p x)), and signatures for all relevant functions, e.g., writing a 32-bit natural to a legal slot in a register file produces a register file: (implies (and (natp n) (< n 16) (n32p val) (register-filep regs)) (register-filep (update-nth n val regs))). For a complete description of acceptable forms see [47m:[0m[47m[tau-system][0m. (6) The tau system is ``greedy'' in its efforts to augment its database. Its database is potentially augmented when rules of [3many[0m [47m:rule-class[0m (see [47m:[0m[47m[rule-classes][0m) are proved. For example, if you make a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[type-prescription][0m rule which expresses a relationship between one tau and another (e.g., that [47m(P x)[0m implies [47m(Q x)[0m), ACL2 will build it into the tau database. The rule-class [47m:[0m[47m[tau-system][0m can be used to add a rule to the tau database without adding any other kind of rule. (7) Greediness is forced into the design by benignity: the tau system may ``know'' some fact that the rewriter does not, and because tau reasoning is not used in rewriting, that missing fact must be conveyed to the rewriter through some other class of rule, e.g., a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[type-prescription][0m or [47m:[0m[47m[forward-chaining][0m rule. By making the tau system greedy, we allow the user to program the rewriter and the tau system simultaneously while keeping them separate. However, this means you must keep in mind the effects of a rule on [3mboth[0m the rewriter and the tau system and use [47m:[0m[47m[tau-system][0m rules explicitly when you want to ``talk'' just to the tau system. (8) Tau rules are built into the database with as much preprocessing as possible (e.g., the system transitively closes inclusion/exclusion relationships at rule-storage time) so the checker can be fast. (9) For speed, tau does not track dependencies and is not sensitive to the enabled/disabled status (see [47m[enable][0m and [47m[disable][0m) of rules, other than [executable-counterpart] rules. Once a fact has been built into the tau database, the only way to prevent that fact from being used is by disabling the entire tau system, by disabling [47m(:[0m[47m[executable-counterpart][0m[47m tau-system)[0m. If any tau reasoning is used in a proof, the rune [47m(:[0m[47m[executable-counterpart][0m[47m tau-system)[0m is reported in the [summary]. For a complete list of all the runes in the tau database, evaluate [47m(get-tau-runes (w state))[0m. Any of these associated theorems could have been used. These design criteria are not always achieved! For example, the tau system's ``greediness'' can be turned off (see [47m[set-tau-auto-mode][0m), the tau database can be regenerated from scratch to ignore disabled rules (see [47m[regenerate-tau-database][0m), and disabling the [executable-counterpart] of a tau predicate symbol will prevent the tau system from trying to run the predicate on constants. The tau system's benignity can be frustrating since it might ``know'' something the rewriter does not. More problematically, the tau system is not always ``fast'' and not always ``benign!'' The typical way tau reasoning can slow a proof down is by evaluating expensive tau predicates on constants. The typical way tau reasoning can hurt a previously successful proof is by proving some subgoals (!) and thus causing the remaining subgoals to have different [clause-identifier]s, thus making explicit hints no longer applicable. We deal with such problems in [47m[dealing-with-tau-problems][0m. [3mTechnical Details[0m The tau system consists of both a database and an algorithm for using the database. The database contains theorems that match certain schemas allowing them to be stored in the tau database. Roughly speaking the schemas encode ``inclusion'' and ``exclusion'' relations, e.g., that [47mnatp[0m implies [47mintegerp[0m and that [47mintegerp[0m implies not [47mconsp[0m, and they encode ``signatures'' of functions, e.g., theorems that relate the output of a function to the input, provided only tau predicates are involved. By ``tau predicates'' we mean the application of a monadic Boolean-valued function symbol, the equality of something to a quoted constant, an arithmetic ordering relation between something and a rational constant, or the logical negation of such a term. Here are some examples of tau predicates: (natp i) (not (consp x)) (equal y 'MONDAY) (not (eql 23 k)) (< 8 max) (<= max 24) Synonyms for [47m[equal][0m include [47m[=][0m, [47m[eq][0m, and [47m[eql][0m. Note that negated equalities are also allowed. The arithmetic ordering relations that may be used are [47m[<][0m, [47m[<=][0m, [47m[>=][0m, and [47m[>][0m. One of the arguments to every arithmetic ordering relation must be an integer or rational constant for the term to be treated as a tau predicate. A ``tau'' is a data object representing a set of signed (positive or negative) tau predicates whose meaning is the conjunction of the literals in the set. When we say that a term ``has'' a given tau we mean the term satisfies all of the recognizers in that tau. The tau algorithm is a decision procedure for the logical theory described (only) by the rules in the database. The algorithm takes a term and a list of assumptions mapping subterms (typically variable symbols) to tau, and returns the tau of the given term. When the system is called upon to decide whether a term satisfies a given monadic predicate, it computes the tau of the term and asks whether the predicate is in that set. More generally, to determine if a term satisfies a tau, [3ms[0m, we compute a tau, [3mr[0m, for the term and ask whether [3ms[0m is a subset of [3mr[0m. To determine whether a constant, [3mc[0m, satisfies tau [3ms[0m we apply each of the literals in [3ms[0m to [3mc[0m. Evaluation might, of course, be time-consuming for complex user-defined predicates. The tau database contains rules derived from definitions and theorems stated by the user. See [47m:[0m[47m[tau-system][0m for a description of the acceptable forms of tau rules. To shut off the greedy augmentation of the tau database, see [set-tau-auto-mode]. This may be of use to users who wish to tightly control the rules in the tau database. To add a rule to the tau database without adding any other kind of rule, use the rule class [47m:[0m[47m[tau-system][0m. There are some slight complexities in the design related to how we handle events with both [47m:tau-system[0m corollaries and corollaries of other [47m:rule-classes[0m, see [47m[set-tau-auto-mode][0m. To prevent tau reasoning from being used, disable the [47m:[0m[47m[executable-counterpart][0m of [47mtau-system[0m, i.e., execute (in-theory (disable (:executable-counterpart tau-system))) or, equivalently, (in-theory (disable (tau-system))) To prevent tau from being used in the proof of a particular subgoal, locally disable the [47m:[0m[47m[executable-counterpart][0m of [47mtau-system[0m with a local [47m:in-theory[0m hint (see [hints]). The event command [47m[tau-status][0m is a macro that can be used to toggle both whether tau reasoning is globally enabled and whether the tau database is augmented greedily. For example, the event (tau-status :system nil :auto-mode nil) prevents the tau system from being used in proofs and prevents the augmentation of the tau database by rules other than those explicitly labeled [47m:[0m[47m[tau-system][0m. To see what the tau system ``knows'' about a given function symbol see [tau-data]. To see the entire tau database, see [tau-database]. To regenerate the tau database using only the runes listed in the current enabled theory, see [regenerate-tau-database]. Subtopics [Dealing-with-tau-problems] Some advice on dealing with problems caused by the tau system [Future-work-related-to-the-tau-system] Some tau system problems that we hope someone will address [Regenerate-tau-database] Regenerate the tau database relative to the current enabled theory") (introduction-to-the-theorem-prover (acl2-tutorial) "How the theorem prover works --- level 0 Software is complex, and ACL2 is a piece of software that is used to analyze software --- adding another layer of complexity. Furthermore, instead of being limited to static analysis for certain fixed properties, ACL2 allows you --- indeed, forces you --- to formalize the problem and the questions. It ``knows'' nothing inherent about your problem before you start to interact with it. But it can be used to help answer the most complicated questions you can ask about software. All this is to say that it is not the kind of tool that you just install and then start to use effectively. So OK, you've installed it or confirmed that you can invoke it. Good for you. Now you have to learn how to use it! Your success ultimately comes down to your understanding of your problem domain and your appropriate exploitation of ACL2's strengths and avoidance of its weaknesses. So put aside the idea of sitting down and interacting with it. Instead, learn about it. We assume you know some of the industrial applications (see [INTERESTING-APPLICATIONS]) of ACL2. Realizing that such things can be done may sustain you during the long learning curve! We also assume you have taken both the Flying Tour (see [A_Flying_Tour_of_ACL2]) and the Walking Tour (see [A_Walking_Tour_of_ACL2]). The tours give you a good overview of the whole system where this tutorial focuses on how to use the prover itself. If you haven't visited these links, please do so now. This tutorial will take you several hours --- maybe several days --- to work through. Do not breeze through it as you might a blog. [3mThink[0m your way through it. [3mRemember[0m what you read. Do not take short cuts. If you start to use ACL2 before you really know how, it will only frustrate you. We recommend that you read this tutorial with an HTML browser so that you can see which links you've followed and which you have not. To give you a sense of what is in store, here is a map of this document. But don't navigate through it from here! Read it linearly, following the links when the text directs you to. [introduction-to-the-theorem-prover] [introduction-to-rewrite-rules-part-1] [special-cases-for-rewrite-rules] [equivalent-formulas-different-rewrite-rules] [introduction-to-key-checkpoints] [dealing-with-key-combinations-of-function-symbols] [generalizing-key-checkpoints] [post-induction-key-checkpoints] [introduction-to-rewrite-rules-part-2] [strong-rewrite-rules] [practice-formulating-strong-rules] [practice-formulating-strong-rules-1] [practice-formulating-strong-rules-2] [practice-formulating-strong-rules-3] [practice-formulating-strong-rules-4] [practice-formulating-strong-rules-5] [practice-formulating-strong-rules-6] [specific-kinds-of-formulas-as-rewrite-rules] [further-information-on-rewriting] [introduction-to-the-database] [introduction-to-hints] [introduction-to-a-few-system-considerations] [introductory-challenges] [introductory-challenge-problem-1] [introductory-challenge-problem-2] [introductory-challenge-problem-3] [3m(there are others but at least do a few)[0m [frequently-asked-questions-by-newcomers] If any of the links above are marked as ``visited'' by your browser, use your browser's tools menu to mark all links as unvisited. As you can see, we really think you'll get the most out of this document if you take it seriously. As you read, you will see some links to ``advanced'' topics. These are marked with a tiny warning sign, ``{ICON} (see [A_Tiny_Warning_Sign])''. They lead out of this linear tutorial and into ACL2's hypertext reference manual. We recommend that you [3mnot[0m visit any of these advanced links until you have read the entire tutorial at least once. After you finish this tutorial material, we recommend that you look at the ACL2 Demos, at the ``Demos'' link of the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2}. Many users of ACL2 have bought the book [3mComputer-Aided Reasoning: An Approach[0m, Kaufmann, Manolios, and Moore, Kluwer Academic Publishers, June, 2000 which is { available in paperback | https://www.lulu.com/shop/j-moore-and-panagiotis-manolios-and-matt-kaufmann/computer-aided-reasoning-an-approach/paperback/product-1p52nnn.html} from Lulu for approximately $22 (as of 2025). That book contains hundreds of exercises in programming, proof, and using The Method described here to prove theorems. Solutions to the exercises are online, as are {appendices | http://link.springer.com/content/pdf/bbm%3A978-1-4615-4449-4%2F1.pdf} that focus on some practical usage aspects. See pubs::pubs-books, which also includes information about its companion (also available on Lulu) describing applications of ACL2, some of which are from industry. Using ACL2 is akin to having a partner in the theorem proving enterprise. It will do some of the work and you will do some of the work. It can't really be any other way because theorem proving is undecidable. You bring a quirky, error-prone, creative insight to the problem, and ACL2 brings accuracy, logic, and perseverance. Here we describe a ``model'' of how the system works and introduce some of the ideas and terminology you'll use repeatedly when interacting with it. This article is about the [3mtheorem prover[0m itself, not the programming language and not the logic. We assume you know enough about the ACL2 programming language that you can define simple functions, run them, and read and write ACL2 constants and terms. For some examples of what we'll take for granted about ACL2 programming, see [programming-knowledge-taken-for-granted]. If you want a brief tutorial on the ACL2 programming language see [gentle-introduction-to-ACL2-programming]. We also assume you know enough about logic to understand, for example, the words we use to talk about formulas and proofs. To see some examples of what we'll take for granted about your knowledge of logic terminology, see [logic-knowledge-taken-for-granted]. If you want an introduction to the ACL2 logic work your way through [recursion-and-induction]. When you give the theorem prover a goal formula to prove, it tries to prove it by breaking it down into subgoals, each of which must be proved in order to prove the original goal. This breaking apart of the goal is done by various [3mproof techniques[0m built into ACL2. Different proof techniques break the formula apart in different ways. For example, the [3msimplifier[0m rips apart the propositional structure to isolate the various cases and applies rewrite rules to simplify the subterms of the formula, while the [3minduction[0m [3mengine[0m will attempt to break the goal into some base cases and some induction steps. The theorem prover's behavior is affected by a [3mdatabase[0m of [3mrules[0m derived from axioms, definitions, and previously proved theorems. The database also records the [3menabled status[0m of each rule; only enabled rules are seen by the prover and you can set the status of a rule. There are many other user-settable switches and parameters affecting the behavior of the prover; you'll learn about some of them later. You guide the theorem prover most of the time simply by identifying lemmas for it to prove. (A [3mlemma[0m is just a theorem that you think is useful in the proofs of other theorems.) Why does this guide the theorem prover? Because every time you get the system to prove a theorem, it turns the theorem into a rule (unless you tell it not to) and stores the rule in the database. That changes how the prover behaves subsequently. But [3myou[0m determine the kind of rule ACL2 stores. To learn to ``drive'' the theorem prover you have to learn how various rules affect the system's behavior and how it turns proved formulas into rules. But before we discuss this, we discuss a more mathematical activity: how do you figure out the lemmas ACL2 will need in order for it to prove interesting theorems? ACL2 can often help you in this activity, if you use it in the right way. Here is the way we recommend you use ACL2. [31;1mThe Method[0m. (1) you present ACL2 with the goal conjecture to prove (2) typically, it fails to prove it (or you abort its attempt), but it prints some [3mKey Checkpoints[0m (3) you look at the Key Checkpoints and decide that you know a fact that will help; this tutorial will present some helpful questions to keep in mind (4) you formalize your knowledge as a formula, along with directions for how ACL2 should turn the formula into a rule; this tutorial will tell you about the most commonly used rule, the [3mrewrite[0m rule (5) you recursively apply The Method to get ACL2 to prove your formula and to store it as the kind of rule you specified (6) go to step (1) Caveat: This approach simply won't work on some theorems! Basically, this is a ``troubleshooting'' approach, where you're letting ACL2 determine the basic strategy and you're just helping with the subgoals. But for some theorems, ACL2's approach will be misguided and no amount of troubleshooting will salvage its strategy. You'll have a sense that this is happening when it happens because the formulas ACL2 presents to you will raise issues that feel irrelevant to you. The basic truth is that if you think a formula is always true there are usually strong intuitive reasons behind your belief. If you were asked to defend your belief, you'd start to explain your reasons and with training you can turn that into a proof. So when ACL2's formulas present you with things you haven't thought of either (a) you'll have an ``Ah ha!'' moment when you realize you hadn't considered that case or (b) you'll realize that ACL2's approach is different from your intuitive ``proof.'' But, surprisingly often, the troubleshooting approach to finding proofs works quite well, especially as you rein in your expectations and develop a sense of what ACL2 can handle on its own. Of course, if you can decompose the proof into a couple of main lemmas before you start, so much the better: write down your sequence of lemmas, thinking about the rules you want them to generate, and get ACL2 to prove each of them before giving it the main theorem. This [3mproof planning[0m approach will gradually become an integral part of your use of The Method. The only mechanized help we can offer with The Method, aside from the theorem prover itself, are tools to help you manage the stack of subgoals it generates when, in step (5) you recursively apply The Method to a lemma. There are both Emacs and Eclipse tools available. To use The Method you have to read the Key Checkpoints printed at the very end of [3mfailed[0m proof attempts, just after the line that reads: The key checkpoint goals, below, may help you to debug this failure. Most users do not read the output from successful proofs and do not read the output [3mduring[0m a proof --- they just let it stream by as a sort of gestalt meter on the theorem prover's progress or lack thereof. For example, you'll be able to tell it is in a loop and needs to be interrupted. You will respond to most Key Checkpoints by formulating new lemmas for the system to prove and store as rules designed by you to alter ACL2's behavior so that it proves the Key Checkpoints. You will give each lemma a [3mname[0m and write some [3mformula[0m to express the mathematical idea. You'll command ACL2 to prove it by typing: (defthm [3mname[0m [3mformula[0m ...) In the ``...'' you may provide two other kinds of information: [3mhints[0m for how to prove [3mformula[0m and directives, called [3mrule-classes[0m, for how to convert [3mformula[0m into a rule after it has proved [3mformula[0m. Note that [3myou[0m are in charge of determining what kind of rule ACL2 generates! There are over a dozen different types of rules with many opportunities to specialize each type. But the most common kind of rule you'll want to generate is a [3mrewrite[0m rule. We recommend that you read the following topics in the following order, without skipping anything except links into the ACL2 User's Manual, which are marked by the little warning sign, ``{ICON} (see [A_Tiny_Warning_Sign])''. (1) See [introduction-to-rewrite-rules-part-1] to read about the use and design of rewrite rules. (2) See [introduction-to-key-checkpoints] to see how to use The Method to help you design rules. (3) See [introduction-to-rewrite-rules-part-2] for general guidance on how to turn formulas into effective rules. (4) See [introduction-to-the-database] to see how to issue commands that build different kinds of rules and that affect the enabled status of existing rules. (5) See [introduction-to-hints] to see how to give the prover hints for how to prove specific theorems or even subgoals of specific proof attempts. (6) See [introduction-to-a-few-system-considerations] for a few words about system aspects of interacting with ACL2. (7) See [introductory-challenges] for a graduated sequence of good challenge problems for the new user to tackle. [31;1mDo not skip this section![0m It is here that you [3mreally[0m learn how to use ACL2 --- by using it. (8) See [frequently-asked-questions-by-newcomers] for a list of questions that new users frequently ask, answered mainly by providing links into the ACL2 User's Manual. We recommend that you skim through these questions and remember that you can find the answers here later. We are very interested in receiving suggestions for how to improve this FAQ and this tutorial. See the ACL2 home page, specifically the link ``Mailing Lists''. Please read all of the material cited above (skipping only the ACL2 User's Manual links (``{ICON} (see [A_Tiny_Warning_Sign])'')) before you try to use ACL2 on problems of your own. By this point you should have read, at least, the following topics from this tutorial introduction to the theorem prover: [introduction-to-the-theorem-prover] [introduction-to-rewrite-rules-part-1] [special-cases-for-rewrite-rules] [equivalent-formulas-different-rewrite-rules] [introduction-to-key-checkpoints] [dealing-with-key-combinations-of-function-symbols] [generalizing-key-checkpoints] [post-induction-key-checkpoints] [introduction-to-rewrite-rules-part-2] [strong-rewrite-rules] [practice-formulating-strong-rules] [practice-formulating-strong-rules-1] [practice-formulating-strong-rules-2] [practice-formulating-strong-rules-3] [practice-formulating-strong-rules-4] [practice-formulating-strong-rules-5] [practice-formulating-strong-rules-6] [specific-kinds-of-formulas-as-rewrite-rules] [further-information-on-rewriting] [introduction-to-the-database] [introduction-to-hints] [introduction-to-a-few-system-considerations] [introductory-challenges] [introductory-challenge-problem-1] [introductory-challenge-problem-2] [introductory-challenge-problem-3] [3m(there are others but at least do a few)[0m [frequently-asked-questions-by-newcomers] We also recommend that you look at the ACL2 Demos mentioned in the [ACL2-tutorial]. Thank you for spending the time to get acquainted with the basics of the ACL2 theorem prover. Don't hesitate to send further questions to the ACL2 Help address on the ``Mailing Lists'' link of the ACL2 home page. [31;1mEnd of Tutorial Introduction to the Theorem Prover[0m Below is a list of all of the topics cited on this page. Subtopics [Architecture-of-the-prover] A simple overview of how the prover works [Dealing-with-key-combinations-of-function-symbols] How to get rid of key combinations of function symbols [Equivalent-formulas-different-rewrite-rules] Logically equivalent formulas can generate radically different rules [Example-induction-scheme-binary-trees] Induction on binary trees [Example-induction-scheme-down-by-2] Induction downwards 2 steps at a time [Example-induction-scheme-nat-recursion] Induction on natural numbers [Example-induction-scheme-on-lists] Induction on lists [Example-induction-scheme-on-several-variables] Induction on several variables [Example-induction-scheme-upwards] Induction upwards [Example-induction-scheme-with-accumulators] Induction scheme with accumulators [Example-induction-scheme-with-multiple-induction-steps] Induction scheme with more than one induction step [Example-inductions] Some examples of induction schemes in ACL2 [Frequently-asked-questions-by-newcomers] Some questions newcomers frequently ask [Further-information-on-rewriting] A grab bag of advice and information on rewriting [Geneqv] the rewriter's generated equivalence relation [Generalizing-key-checkpoints] Getting rid of unnecessary specificity [Introduction-to-a-few-system-considerations] The mechanics of interaction with the theorem prover [Introduction-to-hints] How to provide hints to the theorem prover [Introduction-to-key-checkpoints] What questions to ask at key checkpoints [Introduction-to-programming-in-ACL2-for-those-who-know-lisp] Introduction to programming in ACL2 for Lisp users [Introduction-to-rewrite-rules-part-1] Introduction to ACL2's notion of rewrite rules [Introduction-to-rewrite-rules-part-2] How to arrange rewrite rules [Introduction-to-the-database] How to update the database [Introductory-challenge-problem-1] Challenge problem 1 for the new user of ACL2 [Introductory-challenge-problem-1-answer] Answer to challenge problem 1 for the new user of ACL2 [Introductory-challenge-problem-2] Challenge problem 2 for the new user of ACL2 [Introductory-challenge-problem-2-answer] Answer to challenge problem 2 for the new user of ACL2 [Introductory-challenge-problem-3] Challenge problem 3 for the new user of ACL2 [Introductory-challenge-problem-3-answer] Answer to challenge problem 3 for the new user of ACL2 [Introductory-challenge-problem-4] Challenge problem 4 for the new user of ACL2 [Introductory-challenge-problem-4-answer] Answer to challenge problem 4 for the new user of ACL2 [Introductory-challenges] Challenge problems for the new ACL2 user [Logic-knowledge-taken-for-granted] Background knowledge in ACL2 logic for theorem prover tutorial [Logic-knowledge-taken-for-granted-base-case] A brief explanation of base cases [Logic-knowledge-taken-for-granted-equals-for-equals] Substitution of equals for equals [Logic-knowledge-taken-for-granted-evaluation] Evaluation during proofs [Logic-knowledge-taken-for-granted-inductive-proof] A brief explanation of induction [Logic-knowledge-taken-for-granted-instance] A brief explanation of substitution instances [Logic-knowledge-taken-for-granted-propositional-calculus] A brief explanation of propositional calculus [Logic-knowledge-taken-for-granted-q1-answer] The inductive step of the [47mrev-rev[0m proof --- Answer to Question 1 [Logic-knowledge-taken-for-granted-q2-answer] The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2 [Logic-knowledge-taken-for-granted-q3-answer] The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2 [Logic-knowledge-taken-for-granted-rewriting] A brief explanation of rewriting from the logical perspective [Logic-knowledge-taken-for-granted-rewriting-repeatedly] Further information on expanding definitions via rewriting [Post-induction-key-checkpoints] Reading post-induction key checkpoints [Practice-formulating-strong-rules] A few simple checkpoints suggesting strong rules [Practice-formulating-strong-rules-1] Rules suggested by [47m(TRUE-LISTP (APPEND (FOO A) (BAR B)))[0m [Practice-formulating-strong-rules-2] Rules suggested by [47m(TRUE-LISTP (REV (FOO A)))[0m [Practice-formulating-strong-rules-3] Rules suggested by [47m(MEMBER (FOO A) (APPEND (BAR B) (MUM C)))[0m [Practice-formulating-strong-rules-4] Rules suggested by [47m(SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))[0m [Practice-formulating-strong-rules-5] Rules suggested by [47m(SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))[0m [Practice-formulating-strong-rules-6] Rules suggested by [47m(MEMBER (FOO A) (NATS-BELOW (BAR B)))[0m [Programming-knowledge-taken-for-granted] Background knowledge in ACL2 programming for theorem prover tutorial [Refinement-failure] what to do when a rewrite rule fails the refinement check [Special-cases-for-rewrite-rules] Convenient short forms for rewrite rule formulas [Specific-kinds-of-formulas-as-rewrite-rules] Advice about how to handle commonly occurring formulas as rewrite rules [Strong-rewrite-rules] Formulating good rewrite rules") (introductory-challenge-problem-1 (introduction-to-the-theorem-prover) "Challenge problem 1 for the new user of ACL2 Start in a fresh ACL2, either by restarting your ACL2 image from scratch or executing :ubt! 1 which will undo everything since the first user event. Then define this function: (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) Then use The Method to prove: (defthm triple-rev (equal (rev (rev (rev x))) (rev x))) When you've solved this problem, compare your answer to ours; see [introductory-challenge-problem-1-answer]. Then, use your browser's [31;1mBack Button[0m to return to [introductory-challenges].") (introductory-challenge-problem-1-answer (introduction-to-the-theorem-prover) "Answer to challenge problem 1 for the new user of ACL2 This answer is in the form of an ACL2 script sufficient to lead ACL2 to a proof. (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) ; Trying [47mtriple-rev[0m at this point produces a key checkpoint containing ; [47m(REV (APPEND (REV (CDR X)) (LIST (CAR X))))[0m, which suggests: (defthm rev-append (equal (rev (append a b)) (append (rev b) (rev a)))) ; And now [47mtriple-rev[0m succeeds. (defthm triple-rev (equal (rev (rev (rev x))) (rev x))) ; An alternative, and more elegant, solution is to prove the [47mrev-rev[0m ; instead of [47mrev-append[0m: ; (defthm rev-rev ; (implies (true-listp x) ; (equal (rev (rev x)) x))) ; [47mRev-rev[0m is also discoverable by The Method because it is ; suggested by the statement of [47mtriple-rev[0m itself: [47mrev-rev[0m ; simplifies a simpler composition of the functions in [47mtriple-rev[0m. ; Both solutions produce lemmas likely to be of use in future proofs ; about [47mrev[0m. Use your browser's [31;1mBack Button[0m now to return to [introductory-challenge-problem-1].") (introductory-challenge-problem-2 (introduction-to-the-theorem-prover) "Challenge problem 2 for the new user of ACL2 Start in a fresh ACL2, either by restarting your ACL2 image from scratch or executing [47m:ubt! 1[0m. Use The Method to prove (defthm subsetp-reflexive (subsetp x x)) When you've solved this problem, compare your answer to ours; see [introductory-challenge-problem-2-answer]. Then, use your browser's [31;1mBack Button[0m to return to [introductory-challenges].") (introductory-challenge-problem-2-answer (introduction-to-the-theorem-prover) "Answer to challenge problem 2 for the new user of ACL2 This answer is in the form of a script sufficient to lead ACL2 to a proof. ; Trying [47msubsetp-reflexive[0m at this point produces the key checkpoint: ; (IMPLIES (AND (CONSP X) ; (SUBSETP (CDR X) (CDR X))) ; (SUBSETP (CDR X) X)) ; which suggests the generalization: (defthm subsetp-cdr (implies (subsetp a (cdr b)) (subsetp a b))) ; And now [47msubsetp-reflexive[0m succeeds. (defthm subsetp-reflexive (subsetp x x)) ; A weaker version of the lemma, namely the one in which we ; add the hypothesis that [47mb[0m is a [47mcons[0m, is also sufficient. ; (defthm subsetp-cdr-weak ; (implies (and (consp b) ; (subsetp a (cdr b))) ; (subsetp a b))) ; But the [47m(consp b)[0m hypothesis is not really necessary in ; ACL2's type-free logic because [47m(cdr b)[0m is [47mnil[0m if [47mb[0m is ; not a [47mcons[0m. For the reasons explained in the tutorial, we ; prefer the strong version. Use your browser's [31;1mBack Button[0m now to return to [introductory-challenge-problem-2].") (introductory-challenge-problem-3 (introduction-to-the-theorem-prover) "Challenge problem 3 for the new user of ACL2 Start in a fresh ACL2, either by restarting your ACL2 image from scratch or executing [47m:ubt! 1[0m. Define the following functions and use The Method to prove the theorem at the bottom: (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) (defun dupsp (x) ; does x contain duplicate elements? (if (endp x) nil (if (member (car x) (cdr x)) t (dupsp (cdr x))))) (defthm dupsp-rev (equal (dupsp (rev x)) (dupsp x))) When you've solved this problem, compare your answer to ours; see [introductory-challenge-problem-3-answer]. Then, use your browser's [31;1mBack Button[0m to return to [introductory-challenges].") (introductory-challenge-problem-3-answer (introduction-to-the-theorem-prover) "Answer to challenge problem 3 for the new user of ACL2 This answer is in the form of a script sufficient to lead ACL2 to a proof. ; Trying [47mdupsp-rev[0m at this point produces the key checkpoint: ; (IMPLIES (AND (CONSP X) ; (NOT (MEMBER (CAR X) (CDR X))) ; (EQUAL (DUPSP (REV (CDR X))) ; (DUPSP (CDR X)))) ; (EQUAL (DUPSP (APPEND (REV (CDR X)) (LIST (CAR X)))) ; (DUPSP (CDR X)))) ; which suggests the lemma ; (defthm dupsp-append ; (implies (not (member e x)) ; (equal (dupsp (append x (list e))) ; (dupsp x)))) ; However, attempting to prove that, produces a key checkpoint ; containing [47m(MEMBER (CAR X) (APPEND (CDR X) (LIST E)))[0m. ; So we prove the lemma: (defthm member-append (iff (member e (append a b)) (or (member e a) (member e b)))) ; Note that we had to use [47miff[0m instead of [47mequal[0m since ; [47mmember[0m is not a Boolean function. ; Having proved this lemma, we return to [47mdupsp-append[0m and succeed: (defthm dupsp-append (implies (not (member e x)) (equal (dupsp (append x (list e))) (dupsp x)))) ; So now we return to [47mdups-rev[0m, expecting success. But it fails ; with the same key checkpoint: ; (IMPLIES (AND (CONSP X) ; (NOT (MEMBER (CAR X) (CDR X))) ; (EQUAL (DUPSP (REV (CDR X))) ; (DUPSP (CDR X)))) ; (EQUAL (DUPSP (APPEND (REV (CDR X)) (LIST (CAR X)))) ; (DUPSP (CDR X)))) ; Why wasn't our [47mdupsp-append[0m lemma applied? We have two choices here: ; (1) Think. (2) Use tools. ; Think: When an enabled rewrite rule doesn't fire even though the ; left-hand side matches the target, the hypothesis couldn't be ; relieved. The [47mdups-append[0m rule has the hypothesis [47m(not ; (member e x))[0m and after the match with the left-hand side, [47me[0m ; is [47m(CAR X)[0m and [47mx[0m is [47m(REV (CDR X))[0m. So the system ; couldn't rewrite [47m(NOT (MEMBER (CAR X) (REV (CDR X))))[0m to true, ; even though it knows that [47m(NOT (MEMBER (CAR X) (CDR X)))[0m from ; the second hypothesis of the checkpoint. Obviously, we need to ; prove [47mmember-rev[0m below. ; Use tools: We could enable the ``break rewrite'' facility, with ; ACL2 !>:brr t ; and then install an unconditional monitor on the rewrite rule ; [47mdupsp-append[0m, whose rune is (:REWRITE DUPSP-APPEND), with: ; :monitor (:rewrite dupsp-append) t ; Then we could re-try our main theorem, dupsp-rev. At the resulting ; interactive break we type :eval to evaluate the attempt to relieve the ; hypotheses of the rule. ; (1 Breaking (:REWRITE DUPSP-APPEND) on ; (DUPSP (BINARY-APPEND (REV #) (CONS # #))): ; 1 ACL2 >:eval ; 1x (:REWRITE DUPSP-APPEND) failed because :HYP 1 rewrote to ; (NOT (MEMBER (CAR X) (REV #))). ; Note that the report above shows that hypothesis 1 of the rule ; did not rewrite to T but instead rewrote to an expression ; involving [47m(member ... (rev ...))[0m. Thus, we're led to the ; same conclusion that Thinking produced. To get out of the ; interactive break we type: ; 1 ACL2 >:a! ; Abort to ACL2 top-level ; and then turn off the break rewrite tool since we won't need it ; again right now, with: ; ACL2 !>:brr nil ; In either case, by thinking or using tools, we decide to prove: (defthm member-rev (iff (member e (rev x)) (member e x))) ; which succeeds. Now when we try to prove dups-rev, it succeeds. (defthm dupsp-rev (equal (dupsp (rev x)) (dupsp x))) Use your browser's [31;1mBack Button[0m now to return to [introductory-challenge-problem-3].") (introductory-challenge-problem-4 (introduction-to-the-theorem-prover) "Challenge problem 4 for the new user of ACL2 Start in a fresh ACL2, either by restarting your ACL2 image from scratch or executing [47m:ubt! 1[0m. This problem is much more open ended than the preceding ones. The challenge is to define a function that collects exactly one copy of each element of a list and to prove that it returns a subset of the list with no duplications. (Is this all that one might want to prove? It is a good idea to think about that question, for any application; an answer for this example is at the end of this topic.) [31;1mHint[0m: We recommend that you read this hint to align your function names with our solution, to make comparisons easier. Our answer is shown in see [introductory-challenge-problem-4-answer]. In that page you'll see a definition of a function [47mcollect-once[0m and the proofs of two theorems: (defthm main-theorem-1-about-collect-once (subsetp (collect-once x) x)) (defthm main-theorem-2-about-collect-once (not (dupsp (collect-once x)))) The function [47mdupsp[0m is as defined in see [introductory-challenge-problem-3]. This is quite easy. Then, we define a tail-recursive version of the method based on the pseudo-code: a = nil; while (x not empty) { a = if (member (car x) a) then a else (cons (car x) a); x = (cdr x); } return a; We formalize this with the function [47mwhile-loop-version[0m, where [47m(while-loop-version x nil)[0m is the ``semantics'' of the code above. I.e., the function [47mwhile-loop-version[0m captures the while loop in the pseudo-code above and returns the final value of [47ma[0m, and it should be invoked with the initial value of [47ma[0m being [47mnil[0m. We prove [47m(while-loop-version x nil)[0m returns a subset of [47mx[0m that contains no duplications. Furthermore, we do it two ways: first ``indirectly'' by relating [47mwhile-loop-version[0m to [47mcollect-once[0m, and second (``directly'') without using [47mcollect-once[0m. Both of these proofs are much harder than the [47mcollect-once[0m approach, involving about a dozen lemmas each. Compare your solutions to ours at see [introductory-challenge-problem-4-answer]. Then, use your browser's [31;1mBack Button[0m to return to [introductory-challenges]. We conclude this topic by returning to the question posed earlier above: Is this all that one might want to prove? Notice that we didn't prove that every element of the given list is indeed an element of the returned list, which could be formalized as follows. (thm (subsetp x (collect-once x)))") (introductory-challenge-problem-4-answer (introduction-to-the-theorem-prover) "Answer to challenge problem 4 for the new user of ACL2 This topic solves a challenge problem presented elsewhere; see [introductory-challenge-problem-4]. This answer is in the form of a script sufficient to lead ACL2 to a proof, with a brief prologue. We wish to collect one copy of each element in x. We'll actually define the method two ways, primitive recursively and tail-recursively, the latter method being analogous to the program: a = nil; while (x not empty) { a = if (member (car x) a) then a else (cons (car x) a); x = (cdr x); } return a; We'll prove the two ``equivalent'' and we'll prove that they return a subset of [47mx[0m that contains no duplications. This page is organized into four sections. (A) We will start by proving that the primitive recursive version correct: it returns a subset of its argument that is duplication free. This will be straightforward. (B) Then we'll define the [47mwhile[0m-loop version and we will prove it ``equivalent'' to the primitive recursive version. This will be challenging primarily because the two methods collect their answers in different orders; even stating the relationship between the two is interesting. Proving it will involve a few lemmas. But once we prove their ``equivalence'' the correctness of the [47mwhile[0m-loop version will be straightforward from the correctness of the primitive recursive version. (C) We will disable the rules we prove about the [47mwhile[0m-loop version and prove it correct directly, without exploiting the primitive recursive version. This requires leading the theorem prover more carefully because reasoning about tail-recursive functions that accumulate results is sometimes delicate. (D) Lessons learned --- a narrative that summarizes what we learn from these examples. We follow The Method, which, recall, involves us in recursive attempts to prove lemmas. We use a notation to indicate our sequence of proof attempts. Here is an example (although in actual use we print things across multiple lines). The number in bracket indicates our ``stack depth''. The ``key term'' is some term from a Key Checkpoint in the failed proof which is responsible for our subsequent action. Sometimes instead of a Key Term we just give an English explanation of what we're thinking. [0] (defthm main ...) Failed! Key Term: ... [1] (defthm lemma-1 ...) Succeeded! [0] (defthm main ...) Failed! Key Term: ... [1] (defthm lemma-2 ...) Failed! Key Term: ... [2] (defthm lemma-2a ...) Succeeded! [2] (defthm lemma-2b ...) Succeeded! [1] (defthm lemma-2 ...) Succeeded! [0] (defthm main ...) Succeeded! The rest of this page is just a re-playable script. ; ----------------------------------------------------------------- ; Section A: The Primitive Recursive Version and Its Correctness ; The property of having duplications is defined as: (defun dupsp (x) (if (endp x) nil (if (member (car x) (cdr x)) t (dupsp (cdr x))))) ; The primitive recursive method of collecting one copy of each element is: (defun collect-once (x) (if (endp x) nil (if (member (car x) (cdr x)) (collect-once (cdr x)) (cons (car x) (collect-once (cdr x)))))) ; [0] (defthm main-theorem-1-about-collect-once (subsetp (collect-once x) x)) ; Succeeded! ; [0] ; (defthm main-theorem-2-about-collect-once ; (not (dupsp (collect-once x)))) ; Failed! ; Key Term: (MEMBER (CAR X) (COLLECT-ONCE (CDR X))) ; [1] (defthm member-collect-once (iff (member e (collect-once a)) (member e a))) ; Succeeded! ; [0] (defthm main-theorem-2-about-collect-once (not (dupsp (collect-once x)))) ; Succeeded! ; That was really easy! ;----------------------------------------------------------------- ; Section B: The While-Loop Version and Its Correctness -- ; presented in two parts: its equivalence to the primitive recursive ; version and then its correctness proved via that equivalence ; The tail-recursive, or while-loop version, is defined as follows. The ; function below is the loop itself and it ought to be called with a = nil to ; implement the initialization of a in the pseudo-code above. (defun while-loop-version (x a) (if (endp x) a (while-loop-version (cdr x) (if (member (car x) a) a (cons (car x) a))))) ; We wish to prove that the two are equivalent. But they are actually ; very different. For example, ; (collect-once '(2 4 1 3 1 2 3 4)) = (1 2 3 4) ; (while-loop-version '(2 4 1 3 1 2 3 4) nil) = (3 1 4 2) ; Things get a little more complicated if a is non-nil: ; (while-loop-version '(2 4 1 3 1 2 3 4) '(2 2 4 4)) = (3 1 2 2 4 4) ; Several observations help explain what is happening. (1) Collect-once ; collects the last occurrence of each element, in the order of their last ; occurrences. So, for example, since the last occurrence of 2 precedes the ; last occurrence of 3 in '(2 4 1 3 1 2 3 4)), then the collected 2 precedes ; the collected 3 in the answer. But while-loop-version collects the first ; occurrence of each element, in the reverse order of that occurrence. So it ; adds 2 to its accumulator first and adds 3 last, making 3 precede 2 in the ; answer. ; (2) The while-loop-version does not collect anything already in a and indeed ; just adds stuff to the front of a, returning everything initially in a plus ; one occurrence of everything in x not in a. ; To state the relationship that holds between these two we have to define two ; other functions. ; This is our familiar list reverse function... (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) ; And this function ``removes'' from x all the elements in y, i.e., copies x ; while dropping the elements of y. (defun list-minus (x y) (if (endp x) nil (if (member (car x) y) (list-minus (cdr x) y) (cons (car x) (list-minus (cdr x) y))))) ; The specific equivalence we're really interested in is ; (equal (while-loop-version x nil) ; (collect-once (rev x))) ; But we will not be able to prove that by induction because it has the ; constant nil where we need a variable, a, in order to admit an appropriate ; inductive instance. So we will attack the most general problem. What is ; (while-loop-version x a) equal to, in terms of collect-once? ; The most general relationship between the two collection functions is: ; (equal (while-loop-version x a) ; (append (collect-once (list-minus (rev x) a)) a)) ; This formula bears thinking about! If you're like us, you won't believe it ; until it is proved! ; [0] ; (defthm general-equivalence ; (equal (while-loop-version x a) ; (append (collect-once (list-minus (rev x) a)) a))) ; Failed! ; Key term in checkpoint: ; (LIST-MINUS (APPEND (REV (CDR X)) (LIST (CAR X))) A) ; [1] (defthm list-minus-append (equal (list-minus (append a b) c) (append (list-minus a c) (list-minus b c)))) ; Succeeded! ; [0] ; (defthm general-equivalence ; (equal (while-loop-version x a) ; (append (collect-once (list-minus (rev x) a)) a))) ; Failed! ; Key term in checkpoint: ; (COLLECT-ONCE (APPEND (LIST-MINUS (REV (CDR X)) A) (LIST (CAR X)))) ; [1] ; (defthm collect-once-append ; (equal (collect-once (append a b)) ; (append (list-minus (collect-once a) b) ; (collect-once b)))) ; Failed! ; Key term: ; (MEMBER (CAR A) (APPEND (CDR A) B)) ; [2] (defthm member-append (iff (member e (append a b)) (or (member e a) (member e b)))) ; Succeeded! ; [1] (defthm collect-once-append (equal (collect-once (append a b)) (append (list-minus (collect-once a) b) (collect-once b)))) ; Succeeded! ; [0] ; (defthm general-equivalence ; (equal (while-loop-version x a) ; (append (collect-once (list-minus (rev x) a)) a))) ; Failed! ; Key term: ; (APPEND (APPEND (LIST-MINUS (COLLECT-ONCE (LIST-MINUS (REV (CDR X)) A)) ; [1] (defthm assoc-append (equal (append (append a b) c) (append a (append b c)))) ; Succeeded! ; [0] ; (defthm general-equivalence ; (equal (while-loop-version x a) ; (append (collect-once (list-minus (rev x) a)) a))) ; Failed! ; Key term: ; (LIST-MINUS (COLLECT-ONCE (LIST-MINUS (REV (CDR X)) A)) ...) ; This key term makes us think of the lemma to move the LIST-MINUS inside the ; COLLECT-ONCE. But when that's done, we will have two LIST-MINUS terms ; nestled together and we will want to combine them into one. Call these two ; lemmas (a) and (b). ; [1] (a) ; (defthm list-minus-collect-once ; (equal (list-minus (collect-once x) a) ; (collect-once (list-minus x a)))) ; Failed! ; Key term: ; (MEMBER (CAR X) (LIST-MINUS (CDR X) A)) ; [2] (A pretty fact) (defthm member-list-minus (iff (member e (list-minus x a)) (and (member e x) (not (member e a))))) ; Succeeded! ; [1] (a) (defthm list-minus-collect-once (equal (list-minus (collect-once x) a) (collect-once (list-minus x a)))) ; Succeeded! ; [1] (b) (defthm list-minus-list-minus (equal (list-minus (list-minus x a) b) (list-minus x (append b a)))) ; Succeeded! ; [0] (defthm general-equivalence (equal (while-loop-version x a) (append (collect-once (list-minus (rev x) a)) a))) ; Succeeded! ; That completes the proof of the ``equivalence'' of the two methods. ; Now we prove (1) that the result of while-loop-version is a subset, and (2) ; that it contains no duplications. We prove the two conjuncts separately. ; [0] (defthm main-theorem-1-about-while-loop (subsetp (while-loop-version x nil) x)) ; Succeeded! ; But the theorem prover works harder to do the proof above than one might have ; expected because it doesn't turn into an instance of ; main-theorem-1-about-collect-once because of the presence of the rev term. ; However, we're content that ACL2 managed to do the proof on its own. ; [0] (defthm main-theorem-2-about-while-loop (not (dupsp (while-loop-version x nil)))) ; So we see that the proof of correctness of while-loop-version isn't hard, ; after we establish the relationship with the primitive recursive version. ; But finding and proving the relationship is fairly challenging. ; ----------------------------------------------------------------- ; Section C: A Direct Proof of the Correctness of the While-Loop Version ; Some would consider the proof in Section B ``indirect'' because we first showed ; how while-loop-version could be expressed as a collect-once and then proved ; our main theorems about while-loop-version, which means those main proofs ; were conducted in terms of collect-once, not while-loop-version. ; It is interesting to compare this proof with the ``direct'' one in which ; we don't use collect-once at all and reason only about while-loop-version. ; So to do that comparison, let's disable all the lemmas we've proved about ; while-loop-version and try to prove the two main theorems above about ; while-loop-version. (in-theory (disable general-equivalence main-theorem-1-about-while-loop main-theorem-2-about-while-loop)) ; [0] ; (defthm main-theorem-1-about-while-loop-redux ; (subsetp (while-loop-version x nil) x)) ; Failed! [Well, the truth is below...] ; We don't even submit this event above because we recognize that it is not ; general enough to permit proof by induction. We need to deal with the nil in ; the second argument of while-loop-version. Experience with induction tells ; us this should be a variable, so we can assume an appropriate inductive ; instance. Therefore, we adopt this subgoal immediately: ; [1] ; (defthm main-lemma-1-about-while-loop-version ; (subsetp (while-loop-version x a) (append x a))) ; Failed! ; Key Term: Does the wrong induction. ; [1] ; (defthm main-lemma-1-about-while-loop-version ; (subsetp (while-loop-version x a) (append x a)) ; :hints (("Goal" :induct (while-loop-version x a)))) ; Failed! Two key terms are suggested ; Key term: (IMPLIES (AND ... (SUBSETP (WHILE-LOOP-VERSION (CDR X) A) (APPEND (CDR X) A))) ; (SUBSETP (WHILE-LOOP-VERSION (CDR X) A) (CONS ... (APPEND (CDR X) A)))) ; Key term: (SUBSETP A A) ; So we'll prove both before trying again. ; [2] (defthm subsetp-cons (implies (subsetp a b) (subsetp a (cons e b)))) ; Succeeded! ; [2] (defthm subsetp-reflexive (subsetp a a)) ; Succeeded! ; [1] ; (defthm main-lemma-1-about-while-loop-version ; (subsetp (while-loop-version x a) (append x a)) ; :hints (("Goal" :induct (while-loop-version x a)))) ; Failed! ; Key Term: ; (IMPLIES (AND ... ; (SUBSETP (WHILE-LOOP-VERSION (CDR X) (CONS (CAR X) A)) ; (APPEND (CDR X) (CONS (CAR X) A)))) ; (SUBSETP (WHILE-LOOP-VERSION (CDR X) (CONS (CAR X) A)) ; (CONS (CAR X) (APPEND (CDR X) A)))) ; We'd be done if we could rewrite the ; (APPEND (CDR X) (CONS (CAR X) A)) ; to ; (CONS (CAR X) (APPEND (CDR X) A)) ; These two terms are not equal! But they are ``set-equal'' and this kind of ; rewriting is possible using user-defined equivalences and congruence rules. ; But the new user should not dive into congruences yet. So we will do this ; with ordinary lemmas: ; The plan then is to prove the rewrite rule ; (iff (subsetp a (append b (cons e c))) ; (subsetp a (cons e (append b c)))) ; in order to rewrite the first call of SUBSETP shown in the key term above ; to the second call. ; Consider the first half of this bi-implication: ; (implies (subsetp a (append b (cons e c))) ; hyp1 ; (subsetp a (cons e (append b c)))) ; concl ; Notice that if we knew ; (subsetp (append b (cons e c)) (cons e (append b c))) ; hyp2 ; then we could use hyp1 and hyp2 together with the transitivity of ; subsetp to get concl. ; The proof in the other direction is comparable but requires the ; (subsetp (cons e (append b c)) (append b (cons e c))) ; Thus, our plan is prove ; (a) transitivity of subsetp ; (b) (subsetp (append b (cons e c)) (cons e (append b c))) ; (c) (subsetp (cons e (append b c)) (append b (cons e c))) ; in order to prove ; (d) (iff (subsetp a (append b (cons e c))) ; (subsetp a (cons e (append b c)))) ; [2] (a) (defthm trans-subsetp (implies (and (subsetp a b) (subsetp b c)) (subsetp a c))) ; Succeeded! ; [2] (b) (defthm append-cons-v-cons-append-1 (subsetp (append b (cons e c)) (cons e (append b c)))) ; Succeeded! ; [2] (c) (defthm append-cons-v-cons-append-2 (subsetp (cons e (append b c)) (append b (cons e c)))) ; Succeeded! ; [2] (d) (defthm subsetp-append-cons-cons-append (iff (subsetp a (append b (cons e c))) (subsetp a (cons e (append b c))))) ; Succeeded! ; [1] (defthm main-lemma-1-about-while-loop-version (subsetp (while-loop-version x a) (append x a)) :hints (("Goal" :induct (while-loop-version x a)))) ; Succeeded! ; [0] ; (defthm main-theorem-1-about-while-loop-version ; (subsetp (while-loop-version x nil) x)) ; Failed! [But the truth is below...] ; But we don't submit this because we don't expect it to be proved ; from the main lemma just proved: they don't match! But ; note that if we instantiated the main lemma, replacing a by nil, ; we get: ; (subsetp (while-loop-version x nil) (append x nil)) ; and we could simplify the (append x nil) to x in this context, with ; another congruence rule -- if we were using them. So let's prove ; first that we can simplify (append x nil) inside a subsetp: ; [1] (defthm subsetp-append-nil (iff (subsetp x (append y nil)) (subsetp x y))) ; Succeeded! ; and then just tell ACL2 how to use the lemma to get the main theorem. Note ; that we give a hint to instantiate main-lemma-1... but we also disable ; main-lemma-1... because otherwise it will rewrite itself away! Once the ; instance of main-lemma-1... is sitting around as a hypothesis, ; subsetp-append-nil will rewrite the (append x nil) to x for us and finish the ; proof. ; [0] (defthm main-theorem-1-about-while-loop-version (subsetp (while-loop-version x nil) x) :hints (("Goal" :use (:instance main-lemma-1-about-while-loop-version (x x) (a nil)) :in-theory (disable main-lemma-1-about-while-loop-version)))) ; Succeeded! ; Recall that the main-theorem-1... just proved is just half of what we want. ; We also want: ; [0] ; (defthm main-theorem-2-about-while-loop-version ; (not (dupsp (while-loop-version x nil)))) ; Failed! [But the truth is below...] ; But, again, we don't submit that because the nil makes it not general enough for ; induction. Instead we go immediately to: ; [1] (defthm main-lemma-2-about-while-loop-version (implies (not (dupsp a)) (not (dupsp (while-loop-version x a))))) ; Succeeded! ; This time we know our main-lemma-2... will match (there's no (append x nil) ; in there to mess things up) and so we can complete the proof with: ; [0] (defthm main-theorem-2-about-while-loop-version (not (dupsp (while-loop-version x nil)))) ; Succeeded! ;----------------------------------------------------------------- ; Section D: Lessons Learned ; The most obvious lesson is that it is easier to reason about the primitive ; recursive collect-once than about the while-loop-version. Thus, if your only ; need is for a function that collects one occurrence of each element of a list ; and you don't care about the order in which you collect them and you don't ; need it to be very sparing of stack space when it executes, then use the ; primitive recursive definition and don't even think about while loops! ; So why might you be driven to while-loop-version? One possibility is that ; the list you wish to process is very long and the primitive recursive version ; would produce a stack overflow. In ACL2, that would mean the list would have ; to be several thousand long. Is your application really so demanding? ; Another possibility is that you are modeling in Lisp a while loop expressed ; in some other programming language. In that case, the fidelity of your model to ; the artifact being modeled is important and you should use while-loop-version. ; Another possibility is that for some reason order matters and you really are ; interested in collecting the first occurrence rather than the last. Of ; course this is most likely to be relevant in more interesting applications ; where the occurrences are somehow distinguishable. ; If you are forced to deal with the while-loop-version the question is do you ; do an indirect proof as in Section B or a direct proof as in Section C? ; The indirect proof involved 10 theorems and the direct proof involved 11. ; That is not a significant difference. ; But our sense is that the indirect proof is easier to find, once you figure ; out the basic shape of the relation between while-loop-version and ; collect-once. In particular, we had to give the theorem prover two hints ; in the direct proof (versus no hints in the indirect proof). One of our ; hints was about what induction to do and the other was about how to use a ; previously proved instance of a lemma involving an accumulator. ; Furthermore, we had to think carefully about the use of the transitivity of ; subsetp and we had to hack our way around rewriting (append a (cons e b)) ; to (cons e (append a b)) in a subsetp-expression. ; Some of these ``set'' problems could have been handled a lot more elegantly ; by defining set-equal as an equivalence relation and proving the congruence ; rules to allow the rewriting of set-equal terms to set-equal terms inside ; certain expressions like subsetp and member. However, that involves a lot ; of overhead in the form of congruence rules showing that set-equality is ; maintained by replacement of set-equals by set-equals in various argument ; positions of the various functions. See :doc congruence. In general, we ; find congruence-based reasoning extremely neat and powerful when the ; appropriate infrastructure has been built up. But because the ; infrastructure is ``heavy'' we tend not to invest in it for small projects. ; In summary, different users might take home different lessons about whether ; a direct or indirect proof is better here. This is in part due to the ; complexity of the functional relationship between collect-once and ; while-loop-version, which additionally involved append, list-minus, and rev. ; Had the relationship been simpler, the indirect proof would have been ; preferred. ; An undeniable lesson, however, is that it is helpful to know both styles of ; proof and to be able to explore both as needed in your applications. Use your browser's [31;1mBack Button[0m now to return to [introductory-challenge-problem-4].") (introductory-challenges (introduction-to-the-theorem-prover) "Challenge problems for the new ACL2 user Do each of the problems. In each case, start with a fresh ACL2 (or undo all effects of previous events with [47m:ubt! 1[0m). This may require that you ``re-discover'' the same lemma more than once in different problems, but recognizing the need for something you used in some previous project is part of the training. We recommend that you follow The Method and consult the documentation as needed --- but that you not look at our answers until you're well and truly baffled! See [introductory-challenge-problem-1] (Answer: [introductory-challenge-problem-1-answer]) See [introductory-challenge-problem-2] (Answer: [introductory-challenge-problem-2-answer]) See [introductory-challenge-problem-3] (Answer: [introductory-challenge-problem-3-answer]) See [introductory-challenge-problem-4] (Answer: [introductory-challenge-problem-4-answer]) In addition to these explicit challenge problems designed for beginners, the ACL2 documentation has many example solutions to problems (not always phrased in the question/answer format here). If you are looking for other examples, you should consider [annotated-ACL2-scripts] (Answer: the answers are given in the examples) When you've done the problems and compared your solutions to ours, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (invariant-risk (programming advanced-features guard debugging) "Potential slowdown for [program]-mode updates to [stobj]s or [arrays] You may see a warning like this: ACL2 Warning [Invariant-risk] in MY-FUNCTION: Invariant-risk has been detected for a call of function MY-FUNCTION (as possibly leading to an ill-guarded call of UPDATE-FLD); see :DOC invariant-risk. Such warnings indicate potential slowdown due to aggressive protection by ACL2 against either: * writing a value of the wrong type to a [stobj] field; or * performing an out-of-bounds write to an ACL2 [array]. Whenever a [47m:[0m[47m[program][0m-mode function call can perhaps lead to such a write, [guard]-checking is performed by ACL2, even though the normal expectation is to execute without such checks in Common Lisp; see [evaluation]. Consider the following example. (defstobj st (fld :type integer :initially 0)) (defun f (n st) (declare (xargs :stobjs st :guard (integerp n))) (update-fld n st)) ; This :program-mode wrapper for f fails to require (integerp n): (defun g (n st) (declare (xargs :stobjs st :mode :program)) (f n st)) ; Produces an invariant-risk warning: (g 3 st) ; Produces an invariant-risk warning and a guard violation: (g 'a st) Each of the two calls of [47mg[0m produces an [47m"Invariant-risk"[0m warning, and indeed [guard]s are checked for the ensuing calls of [47mf[0m, causing a guard violation for the second call of [47mg[0m. We may say that such [47m:[0m[47m[program][0m-mode functions have invariant-risk. Because of how the ``aggressive protection'' discussed above is implemented, recursive calls of invariant-risk functions are not traced; see [trace$]. There are two general methods for avoiding such warnings: at runtime with [47m[set-check-invariant-risk][0m, and at definition time with [47m[set-register-invariant-risk][0m. We describe each briefly below. For more information follow the links just above to their respective documentation topics. For yet more detail about invariant-risk see [invariant-risk-details]. For tools that may help find sources of invariant-risk, see [community-book] [47mbooks/std/system/invariant-risk.lisp[0m. Controlling runtime checking for invariant-risk You can avoid seeing warnings like the one displayed above (without affecting the check that is actually performed) by evaluating either one of the following forms. (set-check-invariant-risk t) (set-inhibit-warnings "invariant-risk") You can also replace such warnings by errors: (set-check-invariant-risk :error) Evaluate [47m(get-check-invariant-risk state)[0m to see the current setting for invariant-risk checking. For details, including a dangerous way to remove invariant-risk checking completely at runtime, see [set-check-invariant-risk]. Eliminating invariant-risk checking done by specific functions On occasion you may define functions that you know avoid invariant-risk danger, even though ACL2 designates those functions as having invariant-risk. Rather than removing invariant-risk checking for [3mall[0m functions at runtime with [47m[set-check-invariant-risk][0m, it is probably much safer to remove it only for the functions in a given book or [47m[encapsulate][0m event. See [set-register-invariant-risk] for how to do that. Subtopics [Invariant-risk-details] More details about [invariant-risk] [Set-check-invariant-risk] Affect certain [program]-mode updates to [stobj]s or [arrays] [Set-register-invariant-risk] Avoid [invariant-risk] checking for specified functions") (invariant-risk-details (invariant-risk) "More details about [invariant-risk] This topic, which may be unnecessary for most ACL2 users, expands on the documentation for [invariant-risk]. See that topic and see [evaluation] for relevant background. We refer below to the following example, which is slightly expanded from the one in the documentation for [invariant-risk]. (defstobj st (fld :type integer :initially 0)) (defun f1 (n st) (declare (xargs :stobjs st :guard (integerp n))) (update-fld n st)) (defun f2 (n st) (declare (xargs :stobjs st :guard (integerp n))) (f1 n st)) ; This :program-mode wrapper for f fails to require (integerp n): (defun g (n st) (declare (xargs :stobjs st :mode :program)) (f2 n st)) ; Trace f1 and f2 and their *1* functions. (This is optional.) (trace$ f1 f2 g) ; Produces an invariant-risk warning; only *1* functions are called. (g 3 st) ; Produces an invariant-risk warning and a guard violation: (g 'a st) ; Defeat invariant-risk checking (risky; uses a trust tag): (set-check-invariant-risk nil) ; No warning because *1* functions are not called. (g 3 st) ; No warning because *1* functions are not called. (g 'a st) ; Non-integer field value! (assert-event (equal (fld st) 'a)) To understand invariant-risk, consider the case that a [stobj] updater (such as [47mupdate-fld[0m above) is called on ill-guarded arguments. In that case the resulting ACL2 [state] could be ill-formed, as in the example above: after turning off invariant-risk checking, the stobj [47mst[0m is defined to have an integer field yet winds up with a symbol in that field. ACL2 arranges invariant-risk checking by installing special code in the executable-counterpart of a [47m:[0m[47m[program][0m-mode function to prevent it from calling its corresponding submitted function. It does this when the [47m:program[0m-mode function has a non-nil [47m'invariant-risk[0m property; in the example above, note: ACL2 !>(getpropc 'g 'invariant-risk) UPDATE-FLD ACL2 !> When the function symbol [47mg[0m was defined, it inherited this property from [47mf2[0m, which in turn inherited it from [47mf1[0m, which in turn inherited it from the stobj updater, [47mupdate-fld[0m. However, the aforementioned special code is only installed for [47m:program[0m mode functions, hence not for [47mf1[0m or [47mf2[0m. Consider for example the following trace, from the call of [47m(g 3)[0m made above before turning off invariant-risk checking. 1> (ACL2_*1*_ACL2::G 3 |<st>|) ACL2 Warning [Invariant-risk] in G: Invariant-risk has been detected for a call of function G (as possibly leading to an ill-guarded call of UPDATE-FLD); see :DOC invariant-risk. 2> (ACL2_*1*_ACL2::F2 3 |<st>|) 3> (F2 3 |<st>|) 4> (F1 3 |<st>|) <4 (F1 |<st>|) <3 (F2 |<st>|) <2 (ACL2_*1*_ACL2::F2 |<st>|) <1 (ACL2_*1*_ACL2::G |<st>|) <st> ACL2 !> This trace illustrates that even though [47mf2[0m has the [47m'invariant-risk[0m property, its executable-counterpart has permission to call its submitted function because [47mf2[0m is a guard-verified [47m:logic[0m-mode function. As an optimization, ACL2 avoids setting the [47m'invariant-risk[0m property on [47m:[0m[47m[logic][0m mode functions whose [guard] is [47mt[0m or, more generally, a conjunction of [stobj] recognizer calls. For example, the call of [47m(bar 3 st)[0m below does not cause an invariant-risk warning. (progn (defstobj st (reg :type (array (unsigned-byte 31) (8)) :initially 0)) (defun foo (i st) (declare (xargs :guard t :stobjs st)) (if (eql i 0) (update-regi i 3 st) st)) (defun bar (i st) (declare (xargs :stobjs st :mode :program)) (foo i st))) (bar 3 st) This optimization can hold even if the function is originally submitted without guard verification (typically, using [xargs] declaration [47m:verify-guards nil[0m), but only if its guards are verified before defining the [47m:program[0m-mode wrapper (e.g., [47mbar[0m above). Thus we see an invariant-risk warning in the call of [47mbar[0m below. (progn (defstobj st (reg :type (array (unsigned-byte 31) (8)) :initially 0)) (defun foo (i st) (declare (xargs :guard t :stobjs st :VERIFY-GUARDS NIL)) (if (eql i 0) (update-regi i 3 st) st)) (defun bar (i st) (declare (xargs :stobjs st :mode :program)) (foo i st)) (verify-guards foo) ; avoid invariant-risk by moving before bar ) (bar 3 st) ; invariant-risk Here is code that will return a list of all [47m:program[0m-mode functions subject to invariant-risk checking that are user-defined (not built into ACL2). :q ; go into raw Lisp (let (ans (wrld (w *the-live-state*))) (dolist (p (list-all-packages)) (do-symbols (sym p) (when (and (getpropc sym 'invariant-risk) (programp sym wrld) (not (getpropc sym 'predefined))) (push sym ans)))) ans) To see exactly the executable-counterpart code generated for a [47m:program[0m-mode function with invariant-risk, evaluate [47m(trace! (oneify-cltl-code :native t))[0m before submitting its definition.") (invisible-fns-table (loop-stopper) "Functions that are invisible to the [loop-stopper] algorithm Examples: ACL2 !>(invisible-fns-table (w state)) ((binary-+ unary--) (binary-* unary-/) (unary-- unary--) (unary-/ unary-/)) Among other things, the setting above has the effect of making [47m[unary--][0m ``invisible'' for the purposes of applying permutative [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees. Also see [add-invisible-fns] and see [remove-invisible-fns], which manage macro aliases (see [macro-aliases-table]), as well as see [set-invisible-fns-table]. See [table] for a general discussion of tables. The ``invisible functions [table]'' is an alist with elements of the following form, where [47mfn[0m is a function symbol and the [47mufni[0m are unary function symbols in the current ACL2 [world], and [47mk[0m is at least 1. (fn ufn1 ufn2 ... ufnk) This [table] thus associates with certain function symbols, e.g., [47mfn[0m above, a set of unary functions, e.g., the [47mufni[0m above. The [47mufni[0m associated with [47mfn[0m in the invisible functions table are said to be ``invisible with respect to [47mfn[0m.'' If [47mfn[0m is not the [47m[car][0m of any pair in the [47malist[0m, then no function is invisible for it. Thus for example, setting the invisible functions alist to [47mnil[0m completely eliminates the consideration of invisibility. The notion of invisibility is involved in the use of the [47m:[0m[47m[loop-stopper][0m field of [47m:[0m[47m[rewrite][0m rules to prevent the indefinite application of permutative rewrite rules. Roughly speaking, if rewrite rules are being used to permute [47marg[0m and (ufni arg) inside of a nest of [47mfn[0m calls, and [47mufni[0m is invisible with respect to [47mfn[0m, then [47marg[0m and [47m(ufni arg)[0m are considered to have the same ``weight'' and will be permuted so as to end up as adjacent tips in the [47mfn[0m nest. See [loop-stopper].") (io (interfacing-tools state programming) "Input/output facilities in ACL2 Example: (mv-let (channel state) (open-input-channel "foo.lisp" :object state) (mv-let (eofp obj state) (read-object channel state) (. . (let ((state (close-input-channel channel state))) (mv final-ans state))..))) Also see [std/io] and [file-reading-example]. For advanced ways to control printing, see [print-control]. For a discussion of formatted printing, see [fmt]. To control ACL2 abbreviation (``evisceration'') of objects before printing them, see [set-evisc-tuple], see [without-evisc], and see [set-iprint]. To redirect output to a file, see [output-to-file]. ACL2 supports input and output facilities equivalent to a subset of those found in Common Lisp. ACL2 does not support random access to files (with one exception: see [read-file-into-string]) or bidirectional streams. In Common Lisp, input and output are to or from objects of type [47mstream[0m. In ACL2, input and output are to or from objects called ``channels,'' which are actually symbols. Although a channel is a symbol, one may think of it intuitively as corresponding to a Common Lisp stream. Channels are in one of two ACL2 packages, [47m"ACL2-INPUT-CHANNEL"[0m and [47m"ACL2-OUTPUT-CHANNEL"[0m. When one ``opens'' a file one gets back a channel whose [47m[symbol-name][0m is the file name passed to ``open,'' postfixed with [47m-n[0m, where [47mn[0m is a counter that is incremented every time an open or close occurs. There are three channels which are open from the beginning and which cannot be closed: acl2-input-channel::standard-character-input-0 acl2-input-channel::standard-object-input-0 acl2-input-channel::standard-character-output-0 All three of these are really Common Lisp's [47m*standard-input*[0m or [47m*standard-output*[0m, appropriately. For convenience, three global variables are bound to these rather tedious channel names: *standard-ci* *standard-oi* *standard-co* Common Lisp permits one to open a stream for several different kinds of [47mio[0m, e.g. character or byte. ACL2 permits an additional type called ``object''. In ACL2 an ``io-type'' is a keyword, either [47m:character[0m, [47m:byte[0m, or [47m:object[0m. When one opens a file, one specifies a type, which determines the kind of io operations that can be done on the channel returned. The types [47m:character[0m and [47m:byte[0m are familiar. Type [47m:object[0m is an abstraction not found in Common Lisp. An [47m:object[0m file is a file of Lisp objects. One uses [47mread-object[0m or [47mread-object-with-case[0m (see below) to read from [47m:object[0m files and [47m[print-object$][0m, its more flexible variant [47m[print-object$+][0m, or [47mprint-object$-preserving-case[0m (see below; also, [47mprint-object$-fn[0m) to print to [47m:object[0m files. (The reading and printing are really done with the Common Lisp [47mread[0m and printing functions. For those familiar with [47mread[0m, we note that the [47mrecursive-p[0m argument is [47mnil[0m.) The function [47mread-object-suppress[0m is logically the same as [47mread-object[0m except that [47mread-object-suppress[0m throws away the second returned value, i.e. the value that would normally be read, simply returning [47m(mv eof state)[0m; under the hood, [47mread-object-suppress[0m avoids errors, for example those caused by encountering symbols in packages unknown to ACL2. The functions [47mread-object-with-case[0m is defined logically simply to be [47mread-object[0m, while the function [47mprint-object$-preserving-case[0m and macro [47m[print-object$+][0m are defined logically simply to be [47mprint-object$[0m. However, these variants generally do I/O differently (except that when the host Lisp is GCL, [47mprint-object$-preserving-case[0m behaves the same as [47mprint-object$[0m). For [47mread-object-with-case[0m the value that is read is affected by an extra argument, namely, the second argument: the [3mmode[0m. The mode is one of the keywords [47m:upcase[0m, [47m:downcase[0m, [47m:preserve[0m, or [47m:invert[0m, where [47m:upcase[0m gives the same behavior as [47mread-object[0m, and the other three modes are handled according to the specification for the Common Lisp function, [47mreadtable-case[0m (see for example {the Common Lisp HyperSpec's documentation for ``Examples of Effect of Readtable Case on the Lisp Reader'' | http://www.lispworks.com/documentation/HyperSpec/Body/23_aba.htm}). The function [47mprint-object$-preserving-case[0m is somewhat analogous: it is defined logically to be [47mprint-object$[0m and it has the same behavior, except that symbols are printed without adding escapes merely because of lowercase letters; for example, the symbol in the current package with name [47m"abc"[0m will be printed as [47mabc[0m, not as [47m|abc|[0m. But note that [47mprint-object$-preserving-case[0m may still insert vertical bars, depending on the host Lisp, because different Lisp implementations choose to escape symbols differently. Consider the symbol typically printed as [47m|1u|[0m. Using [47mprint-object$-preserving-case[0m, this prints simply as [47m1u[0m in CCL and Allegro CL, but it is printed as [47m|1u|[0m in SBCL, LispWorks, and CMUCL --- at least in the implementations that we tested! [47mFile-name[0m arguments are strings (except for the [47m:STRING[0m case discussed below). ACL2 does not support the Common Lisp type [47m[pathname][0m; rather, the underlying host Lisp will interpret the given string as a pathname. If the string represents a relative pathname, it will be elaborated to a full pathname using the connected book directory; see [cbd]. You can do that elaboration yourself with a directory [47mdir[0m using [47m(extend-pathname dir file-name state)[0m; see [extend-pathname]. For the [47mfile-name[0m argument of the output-related functions listed below, ACL2 supports a special value, [47m:STRING[0m. For this value, the channel connects (by way of a Common Lisp output string stream) to a string rather than to a file: as characters are written to the channel they can be retrieved by using [47mget-output-stream-string$[0m. Here are the names, formals and output descriptions of the ACL2 io functions. Input Functions: (open-input-channel (file-name io-type state) (mv channel state)) (open-input-channel-p (channel io-type state) boolean) (close-input-channel (channel state) state) (read-char$ (channel state) (mv char/nil state)) ; nil for EOF (peek-char$ (channel state) char/nil) (read-byte$ (channel state) (mv byte/nil state)) ; nil for EOF (read-object (channel state) (mv eof-read-flg obj-read state)) (read-object-with-case (channel mode state) (mv eof-read-flg obj-read state)) (read-object-suppress (channel state) (mv eof-read-flg state)) (read-file-into-string (file-name &key..) string/nil) ; macro (reads state) Output Functions: (open-output-channel (file-name io-type state) (mv channel state)) (open-output-channel! (file-name io-type state) (mv channel state)) (open-output-channel-p (channel io-type state) boolean) (close-output-channel (channel state) state) (princ$ (obj channel state) state) (write-byte$ (byte channel state) state) (print-object$ (obj channel state) state) (print-object$+ (obj channel &key ...) state) (print-object$-preserving-case (obj channel state) state) (print-object$-fn (obj serialize-character channel state) state) (fms (string alist channel state evisc-tuple) state) (fms! (string alist channel state evisc-tuple) state) (fmt (string alist channel state evisc-tuple) (mv col state)) (fmt! (string alist channel state evisc-tuple) (mv col state)) (fmt1 (string alist col channel state evisc-tuple) (mv col state)) (fmt1! (string alist col channel state evisc-tuple) (mv col state)) (cw (string arg0 arg1 ... argn) nil) (get-output-stream-string$ (channel state &optional (close-p 't) (ctx ''get-output-stream-string$)) (mv erp string state)) Note that [47mopen-output-channel[0m and [47mopen-output-channel![0m will attempt to create directories as needed (but this is not the case for [47mopen-input-channel[0m). For example, the following can succeed in writing to the indicated file by creating subdirectory [47m"dir4"[0m if that directory does not already exist. (mv-let (channel state) (open-output-channel "dir4/foo4" :object state) (pprogn (fms "Here: ~x0" (list (cons #\0 (make-list 10))) channel state nil) (close-output-channel channel state))) The ``formatting'' functions are particularly useful; see [fmt] and see [cw]. In particular, [47m[cw][0m prints to a ``comment window'' and does not involve the ACL2 [47m[state][0m, so many may find it easier to use than [47m[fmt][0m and its variants. The functions [47m[fms!][0m, [47m[fmt!][0m, and [47m[fmt1!][0m are the same as their respective functions without the ``[47m![0m,'' except that the ``[47m![0m'' functions are guaranteed to print forms that can be read back in (at a slight readability cost). When one enters ACL2 with [47m(lp)[0m, input and output are taken from [47m[*standard-oi*][0m to [47m[*standard-co*][0m. Because these are synonyms for [47m*standard-input*[0m and [47m*standard-output*[0m, one can drive ACL2 io off of arbitrary Common Lisp streams, bound to [47m*standard-input*[0m and [47m*standard-output*[0m before entry to ACL2. The macro [47mget-output-stream-string$[0m returns the string accumulated into the given channel. By default, a call of this macro closes the supplied output channel. However, a third argument is optional (default [47mt[0m), and if it evaluates to [47mnil[0m then the channel remains open. The fourth argument is an optional context, which generally evaluates to a symbol, for error reporting. The following example illustrates. ACL2 !> (mv-let (channel state) (open-output-channel :string :object state) (pprogn (print-object$-fn 17 nil channel state) (print-object$-fn '(a b (c d)) nil channel state) (er-let* ((str1 (get-output-stream-string$ channel state nil))) ; keep the channel open (pprogn (print-object$-fn 23 nil channel state) (print-object$-fn '((e f)) nil channel state) (er-let* ; close the channel ((str2 (get-output-stream-string$ channel state))) (value (cons str1 str2))))))) (" 17 (A B (C D))" . " 23 ((E F))") ACL2 !> Also see [printing-to-strings] for a discussion of formatted printing functions such as [47mfmt-to-string[0m that do not take a channel or [47m[state][0m argument and return a string. By default, symbols are printed in upper case when vertical bars are not required, as specified by Common Lisp. See [set-print-case] for how to get ACL2 to print symbols in lower case. By default, numbers are printed in radix 10 (base 10). See [set-print-base-radix] for how to get ACL2 to print numbers in radix 2, 8, or 16. To see the [guard] of an IO function, or indeed any function, see [args] or call the function [47mguard[0m; but some built-in functions (including some IO functions) will print the result using the variable [47mSTATE-STATE[0m. While that is logically correct, if you want to execute the guard then you should replace that variable by [47mSTATE[0m and also replace each built-in function symbol of the form [47mxxx-p1[0m by corresponding function symbol [47mxxx-p[0m. Consider the following example. ACL2 !>:args princ$ Function PRINC$ Formals: (X CHANNEL STATE-STATE) Signature: (PRINC$ * * STATE) => STATE Guard: (AND (OR (ACL2-NUMBERP X) (CHARACTERP X) (STRINGP X) (SYMBOLP X)) (STATE-P1 STATE-STATE) (SYMBOLP CHANNEL) (OPEN-OUTPUT-CHANNEL-P1 CHANNEL :CHARACTER STATE-STATE)) Guards Verified: T Defun-Mode: :logic Type: (CONSP (PRINC$ X CHANNEL STATE-STATE)) Documentation available via :DOC PRINC$ ACL2 !>(untranslate (guard 'princ$ nil (w state)) t (w state)) (AND (OR (ACL2-NUMBERP X) (CHARACTERP X) (STRINGP X) (SYMBOLP X)) (STATE-P1 STATE-STATE) (SYMBOLP CHANNEL) (OPEN-OUTPUT-CHANNEL-P1 CHANNEL :CHARACTER STATE-STATE)) ACL2 !> If you want to execute the guard for [47m[princ$][0m, then according to the suggestion above, you should consider the guard for [47m(princ$ x channel state)[0m to be as follows. (AND (OR (ACL2-NUMBERP X) (CHARACTERP X) (STRINGP X) (SYMBOLP X)) (STATE-P STATE) (SYMBOLP CHANNEL) (OPEN-OUTPUT-CHANNEL-P CHANNEL :CHARACTER STATE)) For example, we can check the guard for a given value and channel as follows. ACL2 !>(let ((x 3) (channel *standard-co*)) (AND (OR (ACL2-NUMBERP X) (CHARACTERP X) (STRINGP X) (SYMBOLP X)) (STATE-P STATE) (SYMBOLP CHANNEL) (OPEN-OUTPUT-CHANNEL-P CHANNEL :CHARACTER STATE))) T ACL2 !> Comment for advanced users: Function [47m[open-output-channel!][0m is identical as a function to [47mopen-output-channel[0m, except that the former may be called even during [47m[make-event][0m expansion and [47m[clause-processor][0m [hints], but requires that there is an active trust tag (see [defttag]). Finally, we note that the [std/io] library contains useful file io functions whose definitions illustrate some of the features described above, as does the definition of [47m[write-list][0m in [community-book] [47mbooks/misc/file-io.lisp[0m. Subtopics [*standard-ci*] An ACL2 character-based analogue of CLTL's [47m*standard-input*[0m [*standard-co*] The ACL2 analogue of CLTL's [47m*standard-output*[0m [*standard-oi*] An ACL2 object-based analogue of CLTL's [47m*standard-input*[0m [Character-encoding] How bytes are parsed into characters [Cw] Print to the comment window [Cw!] Print readably to the comment window [Cw!+] Print readably and uninhibited to the comment window [Cw+] Print uninhibited to the comment window [Cw-print-base-radix] Print to the comment window in a given print-base [Cw-print-base-radix!] Print to the comment window in a given print-base [Delete-file$] Delete a file [Evisc-tuple] Control suppression of details when printing [Eviscerate-hide-terms] To print [47m(hide ...)[0m as [47m<hidden>[0m [Extend-pathname] Extend a relative pathname to an absolute pathname [File-length$] The size of a file in bytes [File-write-date$] The write-date of a file as a natural number [Fms] [47m(fms str alist co-channel state evisc) => state[0m [Fms!] [47m(fms! str alist co-channel state evisc) => state[0m [Fmt] Formatted printing [Fmt!] [47m(fmt! str alist co-channel state evisc) => state[0m [Fmt-to-comment-window] Print to the comment window [Fmt-to-comment-window!] Print readably to the comment window [Fmt-to-comment-window!+] Print readably and uninhibited to the comment window [Fmt-to-comment-window+] Print uninhibited to the comment window [Fmt1] [47m(fmt1 str alist col co-channel state evisc) => (mv col state)[0m [Fmt1!] [47m(fmt1! str alist col channel state evisc) => (mv col state)[0m [Fmx] [47m(fmx str &rest args) => state[0m [Fmx-cw] [47m(fmx-cw str &rest args) => state[0m [Msg] Construct a ``message'' suitable for the [47m~@[0m directive of [47m[fmt][0m [Msgp] Recognizer for a ``message'' [Newline] Print a newline to a given output channel [Observation] Print an observation [Open-output-channel!] When trust tags are needed to open output channels [Output-controls] Methods for controlling the output produced by the ACL2 prover [Output-to-file] Redirecting output to a file [Ppr-special-syms] A [table] to control indentation for pretty-printing [Princ$] Print an atom [Print-base-p] Recognizer for print bases that are understood by functions such as [explode-nonnegative-integer] and [explode-atom]. [Print-control] Advanced controls of ACL2 printing [Print-object$] Print an object to an open object output channel [Print-object$+] Print an object to an open output channel in a specified manner [Printing-to-strings] Printing to strings instead of files or standard output [Probe-file] Determine whether a file exists [Proofs-co] The proofs character output channel [Read-file-into-string] The contents of a file (or part of it) as a string [Serialize] Routines for saving ACL2 objects to files, and later restoring them [Set-evisc-tuple] Control suppression of details when printing [Set-fmt-hard-right-margin] Set the right margin for formatted output [Set-fmt-soft-right-margin] Set the soft right margin for formatted output [Set-iprint] Control whether abbreviated output can be read back in [Set-print-base] Control radix in which numbers are printed [Set-print-base-radix] Control radix in which numbers are printed and printing of the radix [Set-print-case] Control whether [symbols] are printed in upper case or in lower case [Set-print-radix] Control printing of the radix for numbers [Standard-co] The character output channel to which [47m[ld][0m prints [Standard-oi] The standard object input ``channel'' [Trace-co] The [trace] character output channel [Without-evisc] Print output in full [Wof] Direct standard output and proofs output to a file") (io? (pointers) "See [system-utilities].") (iprint (pointers) "See [set-iprint].") (iprinting (pointers) "See [set-iprint].") (irrelevant-formals (programming) "Formals that are used but only insignificantly Let [47mfn[0m be a function of [47mn[0m arguments. Let [47mx[0m be the [47mi[0mth formal of [47mfn[0m. We say [47mx[0m is ``irrelevant in [47mfn[0m'' if [47mx[0m does not occur in either the [guard] or the measure for [47mfn[0m, and the value of [47m(fn a1...ai...an)[0m is independent of [47mai[0m. The easiest way to define a function with an irrelevant formal is simply not to use the formal anywhere in its definition. Such formals are said to be ``ignored'' by Common Lisp and a special declaration is provided to allow ignored formals. ACL2 makes a distinction between ignored and irrelevant formals. Note however that if a variable is [47m[declare][0md [47mignore[0md or [47mignorable[0m, or if it occurs free in an [47m[xargs][0m term associated with [47m:[0m[measure], [47m:[0m[guard], or [47m:[0m[47m[split-types][0m, then it will not be reported as irrelevant. An example of an irrelevant formal is [47mx[0m in the definition of [47mfact[0m below. (defun fact (i x) (declare (xargs :guard (and (integerp i) (<= 0 i)))) (if (zp i) 1 (* i (fact (1- i) (cons i x))))). Observe that [47mx[0m is only used in recursive calls of [47mfact[0m; it never ``gets out'' into the result. ACL2 can detect some irrelevant formals by a closure analysis on how the formals are used; let us call these the ``clearly irrelevant formals.'' For example, if the [47mi[0mth formal is only used in the [47mi[0mth argument position of recursive calls, then it is clearly irrelevant. This is how [47mx[0m is used above. It is possible for a formal to appear only in recursive calls but not be clearly irrelevant, or even irrelevant at all. For example, [47mx[0m is [31;1mnot[0m irrelevant below, even though it only appears in the recursive call. (defun fn (i x y) (if (zp i) y (fn (1- i) y x))) The following examples show the relevance of [47mx[0m. ACL2 !>(fn 1 3 0) 3 ACL2 !>(fn 1 4 0) 4 ACL2 !> The key observation for the definition of [47mfn[0m is that while [47mx[0m only appears in a recursive call, it appears in the argument position for a formal that is not clearly irrelevant, namely [47my[0m's. Establishing that a formal is irrelevant, in the sense defined above, can be an arbitrarily hard problem because it requires theorem proving. For example, is [47mx[0m irrelevant below? (defun test (i j k x) (if (p i j k) 0 x)) Note that the value of [47m(test i j k x)[0m is independent of [47mx[0m --- thus making [47mx[0m irrelevant --- precisely if [47m(p i j k)[0m is a theorem. ACL2's syntactic analysis of a definition to determine the ``clearly irrelevant'' formals does not guarantee to notice all irrelevant formals. We regard the presence of irrelevant formals as an indication that something is wrong with the definition. By default, ACL2 causes an error on such definitions. In most cases the best remedy for such an error is to recode the definition so as to eliminate the irrelevant formals. Another option is to [47m[declare][0m the irrelevant formals, for example as follows. (defun fact (i x) (declare (irrelevant x)) (if (zp i) 0 (* i (fact (1- i) (cons i x))))) Note that an [47mirrelevant[0m declaration is only legal for a [47m[defun][0m form, not in other contexts that allow declarations ([47m[let][0m, etc.). To turn off the checking of irrelevant formals globally (though we do not recommend avoiding those checks), see [set-irrelevant-formals-ok]. In that case ACL2 will ignore every [47mirrelevant[0m declaration. But otherwise, and by default, if you provide an [47mirrelevant[0m declaration (see [declare]), then it must specify exactly the formals that ACL2 determines to be irrelevant, what we call the ``clearly irrelevant'' formals above: any formal declared irrelevant that is not clearly irrelevant will cause an error.") (keep (books-tour) "How we know if [47m[include-book][0m read the correct files The certificate (see [certificate] for general information) of a certified file contains a [portcullis] and a keep. These names come from castle lore. The keep is the strongest and usually tallest tower of a castle from which the entire courtyard can be surveyed by the defenders. The keep of a book is a list of file names and [book-hash] values used after the book has been included, to determine if the files read were (up to book-hash) those certified. Once the [portcullis] is open, [47m[include-book][0m can enter the book and read the event forms therein. The non-[47m[local][0m event forms are in fact executed, extending the host theory. That may read in other [books]. When that has been finished, the keep of the [certificate] is inspected. The keep is a list indicating all of the included books (hereditarily through all sub-books) in the certified book (including the certified book itself) together with the [book-hash] values for those [books] at the time of certification. We compare the book-hash values of the [books] just included to those of the [books] stored in the keep. If differences are found then we know that the book or one of its sub-books has been changed since certification. See [include-book] to continue the guided tour through [books].") (keyword (pointers) "See [keywordp].") (keyword-commands (ld) "How keyword commands like [47m:u[0m and [47m:pbt[0m are processed Examples: user type-in form evaluated :pc 5 (ACL2::PC '5) :pcs app rev (ACL2::PCS 'app 'rev) :length (1 2 3) (ACL2::LENGTH '(1 2 3)) :quit (ACL2::QUIT) ; Note: avoid optional argument When a keyword, [47m:key[0m, is read as a command, ACL2 determines whether the symbol with the same name in the [47m"ACL2"[0m package, [47macl2::key[0m, is a function or simple macro of n arguments. If so, ACL2 reads [47mn[0m more objects, [47mobj1[0m, ..., [47mobjn[0m, and then acts as though it had read the following form (for a given [47mkey[0m): (ACL2::key 'obj1 ... 'objn) Thus, by using the keyword command hack you avoid typing the parentheses, the [47m"ACL2"[0m package name, and the quotation marks. See [ld-keyword-aliases] for how to customize this behavior. Note the generality of this hack. Any function or macro in the [47m"ACL2"[0m package can be so invoked, not just ``commands.'' Indeed, there is no such thing as a distinguished class of commands. Users may take advantage of the keyword command hack by defining functions and macros in the [47m"ACL2"[0m package. The one caveat is that when the keyword hack is used to invoke a macro, only the required arguments for that macro are read before calling that macro: none of the [47m&optional[0m, [47m&rest[0m, [47m&body[0m, or [47m&key[0m arguments are read for that call. The macro is thus called with only its required arguments. The following log illustrates this caveat. ACL2 !>:set-iprint t ACL2 Query (:SET-IPRINT): Action (T, NIL, RESET, RESET-ENABLE, SAME, Q or ?): ACL2 Observation in SET-IPRINT: Iprinting has been enabled. ACL2 !> What happened? First, the command [47m:set-iprint[0m was read. Since the macro [47m[set-iprint][0m has no required arguments, the ACL2 evaluator was then called on the form [47m(set-iprint)[0m, that is, calling the macro on no arguments. [47mSet-iprint[0m is defined to query the ACL2 user when its first argument is omitted. The log shows that query, which is set up to read the next form from the input stream. That form was available immediately: the form [47mt[0m that had been supplied by the user. So the query returned immediately and the [47mset-iprint[0m call was completed.") (keyword-listp (lists keywordp acl2-built-ins) "Recognizer for true lists of keywords The call [47m(keyword-listp x)[0m return [47mt[0m when [47mx[0m is a true-list whose members are all [keyword]s, else returns [47mnil[0m.") (keyword-value-listp (keywordp lists acl2-built-ins) "Recognizer for true lists whose even-position elements are keywords [47m(Keyword-value-listp l)[0m is true if and only if [47ml[0m is a list of even length of the form [47m(k1 a1 k2 a2 ... kn an)[0m, where each [47mki[0m is a keyword. To list the keys [47mki[0m and values [47mai[0m of [47ml[0m evaluate [47m(evens l)[0m and [47m(odds l)[0m, respectively. [31;1mFunction: [0m<keyword-value-listp> (defun keyword-value-listp (l) (declare (xargs :guard t)) (cond ((atom l) (null l)) (t (and (keywordp (car l)) (consp (cdr l)) (keyword-value-listp (cddr l)))))) Subtopics [Assoc-keyword] Look up key in a [47m[keyword-value-listp][0m") (keywordp (symbols acl2-built-ins) "Recognizer for keywords [47m(Keywordp x)[0m is true if and only if [47mx[0m is a keyword, i.e., a symbol in the "KEYWORD" package. Such symbols are typically printed using a colon (:) followed by the [47m[symbol-name][0m of the symbol. [47mKeywordp[0m has a [guard] of [47mt[0m. [47mKeywordp[0m is a Common Lisp function. See any Common Lisp documentation for more information. The following log may be illuminating. ACL2 !>(intern "ABC" "KEYWORD") :ABC ACL2 !>(symbol-name ':ABC) "ABC" ACL2 !>(symbol-package-name ':ABC) "KEYWORD" ACL2 !> [31;1mFunction: [0m<keywordp> (defun keywordp (x) (declare (xargs :guard t)) (and (symbolp x) (equal (symbol-package-name x) "KEYWORD"))) Subtopics [Keyword-listp] Recognizer for true lists of keywords [Keyword-value-listp] Recognizer for true lists whose even-position elements are keywords") (known-package-alist (pointers) "See [system-utilities].") (kwote (term acl2-built-ins) "Quote an arbitrary object For any object [47mx[0m, [47m(kwote x)[0m returns the two-element list whose elements are the symbol [47mquote[0m and the given [47mx[0m, respectively. The guard of [47m(kwote x)[0m is [47mt[0m. [31;1mFunction: [0m<kwote> (defun kwote (x) (declare (xargs :guard t)) (mbe :logic (list 'quote x) :exec (cond ((eq x nil) *nil*) ((eq x t) *t*) ((eql x 0) *0*) ((eql x 1) *1*) ((eql x -1) *-1*) (t (list 'quote x)))))") (kwote-lst (term acl2-built-ins) "Quote an arbitrary true list of objects The function [47mkwote-lst[0m applies the function [47mkwote[0m to each element of a given list. The guard of [47m(kwote-lst lst)[0m is [47m(true-listp lst)[0m. [31;1mFunction: [0m<kwote-lst> (defun kwote-lst (lst) (declare (xargs :guard (true-listp lst))) (cond ((endp lst) nil) (t (cons (kwote (car lst)) (kwote-lst (cdr lst))))))") (l< (term apply$) "Ordering on naturals or lists of naturals The function [47ml<[0m is a straightforward ordering relation that compares two objects, each of which is a natural number or a list of natural numbers. It may be convenient to apply [47mlex-fix[0m to two objects before comparing them with [47ml<[0m. Below are the relevant definitions. [31;1mFunction: [0m<l<> (defun l< (x y) (declare (xargs :guard (and (lexp x) (lexp y)))) (or (< (len x) (len y)) (and (= (len x) (len y)) (if (atom x) (< x y) (d< x y))))) [31;1mFunction: [0m<lexp> (defun lexp (x) (declare (xargs :guard t)) (or (natp x) (and (consp x) (nat-listp x)))) [31;1mFunction: [0m<d<> (defun d< (x y) (declare (xargs :guard (and (nat-listp x) (nat-listp y)))) (and (consp x) (consp y) (or (< (car x) (car y)) (and (= (car x) (car y)) (d< (cdr x) (cdr y)))))) [31;1mFunction: [0m<lex-fix> (defun lex-fix (x) (declare (xargs :guard t)) (cond ((atom x) (nfix x)) (t (nfix-list x)))) [31;1mFunction: [0m<nfix-list> (defun nfix-list (list) (declare (xargs :guard t)) (if (consp list) (cons (nfix (car list)) (nfix-list (cdr list))) nil))") (lambda (term apply$) "Lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions The word ``lambda'' occurs in several different contexts in ACL2. When we are being precise our meanings are as outlined below. * lambda expression -- This phrase is used to describe the syntactic entity beginning with the symbol [47mlambda[0m that is allowed to occupy the ``function'' position in an ACL2 [term]. Lambda expressions are most often created when [47mlet[0m expressions are translated into their formal counterparts. We provide an example below. * [47mLAMBDA[0m object -- An ACL2 list constant interpreted as a ``function'' by [47m[apply$][0m. [47mLAMBDA[0m objects may be written in terms by quoting them. However, we urge the user to introduce [47mLAMBDA[0m objects into terms by using the built-in macro [47m[lambda$][0m. We provide examples below. * [47mlambda$[0m expressions -- These are untranslated terms beginning with the macro symbol [47mlambda$[0m. They expand during translation to quoted [47mLAMBDA[0m objects. We provide examples below. These three phrases are very similar but mean very different things. You should read carefully when you see us talk about lambda things! Unfortunately, we're not always as precise as we might be so you might have to disambiguate our usage by context. If you see places in the documentation where you think we've messed up, please bring them to our attention! About Lambda Expressions Consider the function [47modd-evenp[0m, defined with (defun odd-evenp (x) (if (zp x) -1 (let ((ans (odd-evenp (- x 1)))) (* (+ ans 1) (- ans 1))))) Distracting Aside: Can you see why we gave this function this name? Hint: We might have named it ``weird [47mevenp[0m.'' The translated body of [47modd-evenp[0m is (if (zp x) '-1 ((lambda (ans) (binary-* (binary-+ ans '1) (binary-+ '-1 ans))) (odd-evenp (binary-+ '-1 x)))) The syntactic entity in the function position of the term in the false branch, namely (lambda (ans) (binary-* (binary-+ ans '1) (binary-+ '-1 ans))) is a lambda expression. Lambda expressions are integral to the formal representation of terms. They are the formal mechanism by which local variables are introduced and thus allow repeated references to intermediate results without causing recomputation. In ACL2 they obey the rules of Common Lisp. In particular, while defining a recursive function it is allowed to call the function recursively within the lambda expression, e.g., to temporarily save the value of a recursive call for repeated use. (This is not illustrated by [47modd-evenp[0m where the recursive call is outside of the lambda expression.) For more details on the formal representation of ACL2 terms, see [term]. About [47mLAMBDA[0m Objects Prior to Version 8.0 when [47mapply$[0m was introduced, ``lambda expression'' was the only phrase the ACL2 developers used mentioning the word ``lambda.'' Some Community Books introduced various terms or objects mentioning the word but that is beyond the scope of this documentation. Because ``lambda'' occurred in no other context before [47mapply$[0m we are not confident that every reference to what we are now calling ``lambda expressions'' were called by that precise phrase in old documentation. If you see a place where we refer to these entities by another phrase, please let us know! When [47m[apply$][0m was introduced, [47mLAMBDA[0m objects became a formally supported concept in the ACL2 implementation and we started using ``[47mLAMBDA[0m objects'' to refer to them. A [47mLAMBDA[0m object is generally a list, either of the form [47m(LAMBDA vars body)[0m or [47m(LAMBDA vars dcl body)[0m. There are additional restrictions on [47mvars[0m, [47mdcl[0m, and [47mbody[0m that we discuss later. But [47mapply$[0m treats any [47mconsp[0m object and tries to extract those components by rudimentary pattern matching. An example of a [47mLAMBDA[0m object is the list of length three [47m(LAMBDA (x) (BINARY-+ '1 X))[0m. Generally speaking when [47mLAMBDA[0m objects occur in translated terms they are [47mquote[0md, as in (collect$ '(LAMBDA (X) (BINARY-+ '1 X)) lst) To highlight the fact that these objects are constants, we try to write them in UPPERCASE and [47mtypewriter[0m font in this documentation. For the same reason, we generally write ``[47mLAMBDA[0m object'' rather than ``lambda object.'' But of course there's no difference between the symbol [47mLAMBDA[0m and the symbol [47mlambda[0m. Furthermore, [47mLAMBDA[0m objects need not be quoted. From a logical perspective they could just be consed up because they are just ordinary ACL2 list constants. Their ``lambda'' status comes from being treated as functions by [47mapply$[0m. So one could write (collect$ (list 'lambda '(x) '(binary-+ '1 x)) lst) and we would say that the value of the term in the first argument of [47mcollect$[0m is a [47mLAMBDA[0m object. Beware, however, that consing up [47mLAMBDA[0m objects defeats the [ilk] analysis in [47m[defwarrant][0m and the [tame]ness analysis of [47mapply$[0m and hence prevents functions containing such terms from being [47mapply$[0md. According to the definitional axiom defining [47m[apply$][0m, any object satisfying [47mconsp[0m is treated as a [47mLAMBDA[0m object. [47mApply$[0m uses ``accessor'' functions to extract the ``formals'' and ``body'' of the object and proceeds to [47m[ev$][0m the body in an alist binding the formals. But [47mev$[0m insists that the expression object being evaluated be [tame] or else assigns it a default value. This insistence on tameness is due to fundamental logical reasons; otherwise, [47mapply$[0m would allow us to prove [47mNIL[0m. So axiomatically [47mapply$[0m operates as ``naively expected'' only on [47mtamep-lambdap[0m objects. One consequence of this, which we expect will be a minor inconvenience, is that unlike ACL2's lambda expressions [47mapply$[0m's [47mLAMBDA[0m objects, when used in definitions of new functions, may not include recursive calls of the function being defined because they fail the tameness test. But wait! There's more. Execution efficiency of [47mapply$[0m imposes some non-logical restrictions. These restrictions come from ACL2's execution story with respect to Common Lisp, and from the Common Lisp compiler. To execute [47mLAMBDA[0m objects most efficiently they must be well-formed, which is a concept even stronger than tameness. Among other requirements, well-formed [47mLAMBDA[0m objects obey the ACL2 and Common Lisp rules on variable names (not every symbol is a legal variable), on the use of free variables, on the body being a fully translated formal term, that the declarations, if any, be meaningful to the Common Lisp compiler, etc. You can read about well-formedness in [47m[well-formed-lambda-objectp][0m if you want, but we don't encourage beginners to go there! Note: Even well-formedness is not enough to guarantee execution of compiled code. The [47mLAMBDA[0m object must also be guard verified (see [47m[verify-guards][0m for a discussion) and its guard must be satisfied by the arguments to which it is applied. Note: A peculiar aspect of [47mLAMBDA[0m objects is that they can be written as legal ACL2 constants [3mbefore[0m they are well-formed [47mLAMBDA[0m objects, e.g., by referring to undefined functions, [47m:program[0m mode functions, unbadged functions, etc. They are, after all, just arbitrary quoted objects and any value in ACL2 can be quoted. An ill-formed [47mLAMBDA[0m object can [3mbecome[0m well-formed if the world is appropriately extended, e.g., the appropriate [47mdefun[0ms or [47mdefwarrant[0ms are made. Perhaps worse, they can be well-formed and then [3mbecome[0m ill-formed by an undo. So at runtime [47mapply$[0m has to check that the function symbol or [47mLAMBDA[0m object is appropriate. There is a sophisticated cache behind the execution machinery for [47mLAMBDA[0m objects in the evaluation theory. See [47m[print-cl-cache][0m. About Lambda$ Expressions Rather than force users to type well-formed [47mLAMBDA[0m objects as quoted constants, ACL2 provides a macro allowing you to enter [47mLAMBDA[0m objects by typing something that looks like a lambda expression but which is properly translated and generates well-formed results (or causes a translation error). That macro -- which is not really a defined macro but is built into ACL2's translation mechanism -- is called [47m[lambda$][0m and uses of it in terms are called ``[47mlambda$[0m expressions.'' [47mLambda$[0m expressions may only be used in argument slots of [ilk] [47m:FN[0m. An example of a [47mlambda$[0m expression is the first argument of [47mcollect$[0m in (collect$ (lambda$ (x) (+ 1 x)) lst) That [47mlambda$[0m expression essentially translates to the quoted well-formed [47mLAMBDA[0m object '(LAMBDA (X) (BINARY-+ '1 X)) Note that the body is fully translated, unlike its appearance in the [47mlambda$[0m expression. We say ``essentially'' because [47mlambda$[0m always add a [47m(DECLARE (IGNORABLE v1 ... vn))[0m that includes every formal. In addition, except when translating in theorems, [47mlambda$[0m tags the translated body with a [47m[return-last][0m expression to indicate it came from a [47mlambda$[0m. Despite these differences, the meaning of the translated [47mlambda$[0m is the simple quoted [47mLAMBDA[0m object shown. [47mLambda$[0m expressions never appear in a fully translated term. All the [47mlambda$[0m objects will have been translated into quoted [47mLAMBDA[0m objects. The body of a [47mlambda$[0m expression must return a single value that is neither a [stobj] nor a [df]. The following example illustrates this point. (defun$ f1 (x) (declare (xargs :guard t)) (mv x x)) ; ERROR! The body of the lambda$ returns two values. (defun f2 (y) (declare (xargs :guard t)) (apply$ (lambda$ (x) (f1 x)) (list y))) ; Succeeds. (defun f2 (y) (declare (xargs :guard t)) (apply$ '(lambda (x) (f1 x)) (list y))) Finally, to see how a [47mlambda$[0m expression translates, see [47m[translam][0m.") (lambda$ (apply$) "Lambda object constructor for use with [47mapply$[0m [47mLambda$[0m is a built-in ACL2 ``macro'' that allows you to enter well-formed fully-translated quoted [47mLAMBDA[0m objects in argument positions of ilk [47m:FN[0m. We urge you to use [47mlambda$[0m instead of trying to type quoted [47mLAMBDA[0m objects meant for use by [47mapply$[0m. We explain and document [47mlambda$[0m below. Intuitively, a quoted [47mLAMBDA[0m object is a quoted constant like '(LAMBDA (X) (BINARY-+ '1 X)) e.g., a quoted constant beginning with the symbol [47mLAMBDA[0m and listing some formal variables, possibly some declarations, and a fully translated body satisfying various rules. [47m[Apply$][0m can handle quoted [47mLAMBDA[0m objects provided they have the right basic shape and all the listed formals are symbols and the bodies are [tame]. But it is difficult to type fully translated bodies and, for runtime efficiency, it is important that the quoted [47mLAMBDA[0m objects satisfy additional (logically unnecessary) well-formedness restrictions allowing faster guard checking and compilation. One should strive to always enter ``well-formed [47mLAMBDA[0m objects.'' The details of well-formedness may be found in [47m[well-formed-lambda-objectp][0m but our hope is that mastering those details is unnecessary because ACL2 provides a built-in ``macro,'' [47mlambda$[0m, for constructing quoted well-formed [47mLAMBDA[0m objects. We urge you to use [47mlambda$[0m instead of typing quoted [47mLAMBDA[0m objects! That is, write [47m(lambda$ (x) (+ 1 x))[0m instead of [47m'(LAMBDA (X) (BINARY-+ '1 X))[0m. [47mLambda$[0m [3mterms may only appear in argument slots of ilk[0m [47m:FN[0m! Examples: (lambda$ (x y) (append x (list y))) (lambda$ (n lst str) (declare (type integer n) (type string str) (xargs :guard (and (posp n) (true-listp lst) (< (- n 1) (length lst))))) (nth (- n 1) lst)) General Form: (lambda$ vars dcl* body) where the [47mlambda$[0m expression occurs in an argument position of ilk [47m:FN[0m, [47mvars[0m is a list of distinct variable names, [47mdcl*[0m is zero or more [47mDECLARE[0m forms as described below, and [47mbody[0m is a term returning the appropriate number of values, which is currently always 1 except when used in the translation of an expression of the form [47m(loop$ ... DO ...)[0m. [47mBody[0m must satisfy the same restrictions one would expect in a non-recursive [47m[defun][0m event with the same formals, declarations and body. In particular, [47mbody[0m should contain no free variables other than those listed in [47mvars[0m. [47mLambda$[0m always adds a declaration that every formal is ignorable and, hence, we prohibit you from adding [47mignore[0m or [47mignorable[0m declarations in the [47mlambda$[0m expression itself. [47mLambda$[0m expands to a well-formed quoted [47mLAMBDA[0m object or else causes a translate-time error. The allowed [47mDECLARE[0m forms in [47mlambda$[0m are [47mtype[0m and [47mxargs[0m. Furthermore, the only [47m[xargs][0m keywords allowed are [47m:guard[0m and [47m:split-types[0m. The other [47mXARGS[0m keywords, such as [47m:measure[0m, [47m:hints[0m or [47m:guard-hints[0m, play no role. About [47mLambda$[0ms and Prover Output The translated form of a [47mlambda$[0m expression is a quoted [47m[lambda][0m object. For example, [47m(collect$ (lambda$ (x) (+ 1 x)) lst)[0m translates to (COLLECT$ '(LAMBDA (X) (DECLARE (IGNORABLE X)) (RETURN-LAST 'PROGN '(LAMBDA$ (X) (+ 1 X)) (BINARY-+ '1 X))) LST) The [47mlambda$[0m has been replaced by a quoted [47mlambda[0m. The prover tries to print each quoted [47mlambda[0m object (that occurs an argument position of [ilk] :[47mFN[0m) as a [47mlambda$[0m expression that is (provably) functionally equal (see [47m[fn-equal][0m) to the original [47mlambda[0m object assuming the necessary warrants. If the quoted [47mlambda[0m object was produced by the expansion of a [47mlambda$[0m expression and has not been simplified by subsequent rewriting, it will print as the original [47mlambda$[0m expression. This can be unfortunate if the original [47mlambda$[0m expression was itself produced by a macro and contains logically irrelevant (but operationally important) tags. This phenomenon occurs most often when [47m[do-loop$][0ms are involved. Furthermore, since you are allowed to type in quoted [47mlambda[0m objects directly, you may --- or may not --- see them printed by the prover as [47mlambda$[0m expressions, depending on whether a suitable [47mlambda$[0m is found. If a quoted [47mlambda[0m object contains a reference to a function symbol for which no [47m[warrant][0m has been issued there is probably no provably equivalent [47mlambda$[0m. The main lessons here are * you should use [47mlambda$[0m rather than quoted [47mlambda[0m objects in your prover input, * you should make sure to warrant every user-defined function in your [47mlambda$[0m expressions, and * if you see a quoted [47mlambda[0m object rather than a [47mlambda$[0m expression in your prover output, that quoted [47mlambda[0m object probably involves unwarranted symbols which will make it impossible to prove anything interesting about it. If you do not want the prover output to give special treatment to quoted [47mlambda[0m objects in :[47mFN[0m slots, do (defattach-system (untranslate-lambda-object-p constant-nil-function-arity-0)) With this attachment, the prover will print all quoted [47mlambda[0m objects as it would any other quoted constant. You will see what is actually there. One drawback is that the resulting formulas cannot always be read back in and translated because of a prohibition on ``counterfeiting'' expansions of [47mlambda$[0m. See [gratuitous-lambda-object-restrictions]. About Guard Verification of Lambda Objects Quoted [47mLAMBDA[0m objects, whether produced by hand (don't!) or by [47mlambda$[0m may have guards. If the [47mLAMBDA[0m object is well-formed its guard plays the same role the guard of a defined function symbol plays when the object is [47mapply$[0md. If the guard can be verified to imply the guards of the body (which we call [3mguard verification[0m), and if the guard holds of the actuals to which the object is applied (which we call [3mguard checking[0m), a compiled version of the object is run. Otherwise, depending on how [47m[set-guard-checking][0m has been configured, either an error is signaled or the object is interpreted under the axioms defining [47mapply$[0m and [47mev$[0m. [47mApply$[0m caches its investigations into guard verification (but not guard checking) and compilation. We discuss the cache in [47m[print-cl-cache][0m. When a guarded quoted [47mLAMBDA[0m object is used in a [47m:FN[0m slot of a function definition, its guards are verified as part of the guard verification step of [47mdefun[0m or [47mverify-guards[0m. If that guard verification fails, checkpoints will be printed and you can use [47m:guard-hints[0m or [47m:hints[0m in the [47mdefun[0m or [47mverify-guards[0m events to supply the necessary guidance. When successful, the guard verified [47mLAMBDA[0m objects in the [47mdefun[0m are recorded in the cache. But unlike defined function symbols, whose guards may be verified at [47mdefun[0m-time or at [47mverify-guards[0m-time, quoted [47mLAMBDA[0m expressions may be introduced without an associated event. For example, the user may simply type ACL2 !>(apply$ (lambda$ (x) (declare (type (satisfies natp) x)) (* x x)) '(5)) giving [47mapply$[0m a [47mLAMBDA[0m object never before seen. So [47mapply$[0m must be ready to verify the guards of a quoted [47mLAMBDA[0m object before attempting to apply it. This is in contrast to what happens when [47mapply$[0m is given a quoted function symbol. ([47mApply$[0m can just look up whether a function symbol has been guard verified.) To try to verify the guards of a quoted [47mLAMBDA[0m expression, [47mapply$[0m limits itself to tau reasoning (see [introduction-to-the-tau-system]). The idea is not to spend too much time making the decision as to whether compiled code can be used or not. In addition, we don't want top-level evaluation, as shown in the user type-in above, to provoke full-blown theorem proving. Interpreting small quoted [47mLAMBDA[0m objects can be done relatively quickly. After all, when the interpreter reaches a guard verified function symbol inside the [47mLAMBDA[0m body it runs compiled code. It's only the body itself that is interpreted. But the tau system is pretty weak and so will be unable to verify some non-trivial guard conjectures, which will mean the [47mLAMBDA[0m object is interpreted. If the [47mLAMBDA[0m object is very large or is being being used often, e.g., to map over a large object and check some property, you might really want to invest the time to verify its guards. This can be done with [47m[verify-guards][0m, which as of Version 8.1 takes [47mLAMBDA[0m objects and [47mlambda$[0m terms and updates the cache. E.g., (verify-guards (lambda$ (x) (declare (type (satisfies natp) x)) (* x x))) While this functionality is available to you, deciding that you need to use it is problematic. [47mApply$[0m prints no warning that it has failed to verify the guards of a [47mLAMBDA[0m object and is running interpreted code. However, the utility [47m[print-cl-cache][0m provides basic information about the cache and its documentation may help you discover which [47mLAMBDA[0m objects in use are unverified.") (lambda-applicationp (pointers) "See [system-utilities].") (lambda-body (pointers) "See [system-utilities].") (lambda-formals (pointers) "See [system-utilities].") (last (lists acl2-built-ins) "The last [47m[cons][0m (not element) of a list [47m(Last l)[0m is the last [47m[cons][0m of a list, [47ml[0m. Here are examples. ACL2 !>(last '(a b . c)) (B . C) ACL2 !>(last '(a b c)) (C) [47m(Last l)[0m has a [guard] of [47m(listp l)[0m; thus, [47ml[0m need not be a [47m[true-listp][0m. [47mLast[0m is a Common Lisp function. See any Common Lisp documentation for more information. Unlike Common Lisp, we do not allow an optional second argument for [47mlast[0m. [31;1mFunction: [0m<last> (defun last (l) (declare (xargs :guard (listp l))) (if (atom (cdr l)) l (last (cdr l))))") (last-cdr (lists acl2-built-ins) "The last [47m[cdr][0m of a list [47m(Last-cdr x)[0m is [47mx[0m if [47mx[0m is an [47m[atom][0m, and otherwise is the last [47m[cdr][0m of a list. Here are examples. ACL2 !>(last-cdr '(a b . c)) C ACL2 !>(last-cdr '(a b c)) NIL [47m(Last-cdr x)[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<last-cdr> (defun last-cdr (x) (declare (xargs :guard t)) (if (atom x) x (cdr (last x))))") (last-prover-steps (set-prover-step-limit with-prover-step-limit programming-with-state acl2-built-ins) "The number of prover steps most recently taken For discussions of prover step limits, See [set-prover-step-limit] and see [with-prover-step-limit]. The [summary] printed for an [event] typically includes a line showing the prover steps counted, for example as follows. Prover steps counted: 7240 The value of the form [47m(last-prover-steps state)[0m indicates the number of prover steps taken, in the sense described below, for the most recent context in which an event [summary] would normally be printed. Note that the value of [47m(last-prover-steps state)[0m is updated for all [events], and more generally, for all forms that are set up to print a [summary], such as calls of [47m[thm][0m or [47m[certify-book][0m --- regardless of whether or not summary output is inhibited (see [set-inhibit-output-lst] and see [set-inhibited-summary-types]). In particular, the value is updated (typically to [47mnil[0m) for [47m[table][0m [events], even when no summary is printed; for example, the value is updated to [47mnil[0m for [47mtable[0m events such as [47m([0m[47m[logic][0m[47m)[0m, [47m([0m[47m[program][0m[47m)[0m, and even calls of [47m[set-prover-step-limit][0m. The value of [47m(last-prover-steps state)[0m is determined as follows, based on the most recent summary context (as described above): [47mnil[0m, if no prover steps were taken, e.g., with [47m(thm (equal x x))[0m; else, the (positive) number of steps taken, if the number of steps did not exceed the starting limit; else, the negative of the starting limit. Note that the ``most recently completed event'' in this sense includes compound events. Consider the following example. (progn (thm (equal (append (append x y) z) (append x y z))) (thm (equal (car (cons x y)) x))) The summaries show (in some ACL2 versions, at least) 435 steps for the first call of [47mthm[0m and 7 steps for the second call of [47mthm[0m, with 442 steps thus shown in the summary for the entire [47mprogn[0m call. Subsequent evaluation of [47m(last-prover-steps state)[0m returns 442. On the other hand, suppose that [47m(set-prover-step-limit 440)[0m is evaluated immediately before evaluating the [47mprogn[0m call above. Then the summaries show the following for the two [47mthm[0m calls and the [47mprogn[0m call, in order as follows. Prover steps counted: 435 Prover steps counted: More than 5 Prover steps counted: More than 440 Since the most recently completed event is the [47mprogn[0m call, then [47m(last-prover-steps state)[0m returns -440. We conclude with two remarks for advanced users who wish to invoke [47mlast-prover-steps[0m in the development of utilities that track prover steps. Remark 1. Suppose that you want to write a utility that takes some action based on the number of prover steps performed by the first event that is generated within a sequence of events, for example the number of prover steps taken to admit [47mf1[0m in the following example. (progn (defun f1 ...) (defun f2 ...)) A solution is to record the steps taken by the first [47m[defun][0m before executing subsequent events, as follows (see [make-event]). (progn (defun f1 ...) (make-event (pprogn (f-put-global 'my-step-count (last-prover-steps state) state) (value '(value-triple nil)))) (defun f2 ...)) Remark 2. It is possible to write utilities that are treated as [events] for purposes of the discussion above; that is, their calls can be followed by evaluating [47m(last-prover-steps state)[0m as described above. For an example of how to do this using the ACL2 system macro [47mwith-ctx-summarized[0m, see the implementation of [47m[prove$][0m in [community-book] [47mbooks/tools/prove-dollar.lisp[0m.") (ld (miscellaneous) "The ACL2 read-eval-print loop, file loader, and [command] processor Examples: (LD "foo.lisp") ; read and evaluate each form in file ; "foo.lisp", in order (LD "foo.lisp" :ld-pre-eval-print t) ; as above, but print each form to standard ; character output just before it is evaluated General Form: (LD standard-oi ; open obj in channel, stringp file name ; to open and close, or list of forms ; Optional keyword arguments: :dir ... ; directory spec if standard-oi is a string :standard-co ... ; open char out or file to open and close :proofs-co ... ; open char out or file to open and close :current-package ... ; known package name :useless-runes ... ; :write/:read/:read?/n/-n/nil ; (-100 < n < 0 or 0 < n <= 100) ; (see [useless-runes]) :ld-skip-proofsp ... ; nil, 'include-book, or t ; (see [ld-skip-proofsp]) :ld-redefinition-action ... ; nil or '(:a . :b) :ld-prompt ... ; nil, t, or some prompt printer fn :ld-missing-input-ok ... ; nil, t, :warn, or warning message :ld-pre-eval-filter ... ; :all, :query, or some new name :ld-pre-eval-print ... ; nil, t, or :never :ld-post-eval-print ... ; nil, t, or :command-conventions :ld-evisc-tuple ... ; nil or '(alist nil nil level length) :ld-error-triples ... ; nil or t :ld-error-action ... ; :return!, :return, :continue, :error, ; or (:exit N) :ld-query-control-alist ... ; alist supplying default responses :ld-verbose ...) ; nil or t :ld-always-skip-top-level-locals ; nil or t :ld-user-stobjs-modified-warning ...) ; nil, t, or :same [47mLd[0m is the top-level ACL2 read-eval-print loop. (When you call [47m[lp][0m, a little initialization is done in raw Common Lisp and then [47mld[0m is called.) [47mLd[0m is also a general-purpose ACL2 file loader and a [command] interpreter. [47mLd[0m is actually a macro that expands to a function call involving [47m[state][0m. [47mLd[0m returns an ``error triple'' [47m(mv erp val state)[0m as explained below. (For much more on error triples, see [programming-with-state].) See [rebuild] for a variant of [47mld[0m that skips proofs. See [output-to-file] for examples showing how to redirect output to a file. The arguments to [47mld[0m, except for [47m:dir[0m, all happen to be global variables in [47m[state][0m (see [state] and see [programming-with-state]). For example, [47m'[0m[47m[current-package][0m and [47m'[0m[47m[ld-verbose][0m are global variables, which may be accessed via [47m(@ current-package)[0m and [47m(@ ld-verbose)[0m. When [47mld[0m is called, it ``binds'' these variables. By ``binds'' we actually mean the variables are globally set but restored to their old values on exit. Because [47mld[0m provides the illusion of [state] global variables being bound, they are generally called ``[47mld[0m specials'' (after the Lisp convention of calling a variable ``special'' if it is referenced freely after having been bound). (We say ``generally'' because technically, [47mcurrent-package[0m and [47museless-runes[0m are not considered to be [47mld[0m specials.) Note that all arguments but the first are passed via keyword. Any variable not explicitly given a value in a call retains its pre-call value, with the exception of [47m:[0m[47m[ld-error-action][0m, which generally defaults to [47m:return![0m if not explicitly specified. Just as an example to drive the point home: If [47m[current-package][0m is [47m"ACL2"[0m and you typed (ld *standard-oi* :current-package "MY-PKG") you would find yourself in (an inner) read-eval-print loop in which the [current-package] was [47m"MY-PKG"[0m. You could operate there as long as you wished, changing the current package at will. But when you typed [47m:[0m[47m[q][0m you would return to the outer read-eval-print loop where the current package would still be [47m"ACL2"[0m. Roughly speaking, [47mld[0m repeatedly reads a form from [47m[standard-oi][0m, evaluates it, and prints its result to [47m[standard-co][0m. It does this until the form is [47m:[0m[47m[q][0m or evaluates to an error triple whose value component is [47m:[0m[47m[q][0m, or until the input channel or list is emptied. However, [47mld[0m has many bells and whistles controlled by the [47mld[0m specials. Each such special is documented individually. For example, see the documentation for [47m[standard-oi][0m, [47m[current-package][0m, [useless-runes], [47m[ld-pre-eval-print][0m, etc. A more precise description of [47mld[0m is as follows. In the description below we use the [47mld[0m specials as variables, e.g., we say ``a form is read from [47m[standard-oi][0m.'' By this usage we refer to the current value of the named [state] global variable, e.g., we mean ``a form is read from the current value of [47m'[0m[47m[standard-oi][0m.'' This technicality has an important implication: If while interacting with [47mld[0m you change the value of one of the [47mld[0m specials, e.g., [47m'[0m[47m[standard-oi][0m, you will change the behavior of [47mld[0m, e.g., subsequent input will be taken from the new value. Three [47mld[0m specials are treated as channels: [47m[standard-oi][0m is treated as an object input channel and is the source of forms evaluated by [47mld[0m; [47m[standard-co][0m and [47m[proofs-co][0m are treated as character output channels and various flavors of output are printed to them. However, the supplied values of these specials need not actually be channels; several special cases are recognized. If the supplied value of one of these is in fact an open channel of the appropriate type, that channel is used and is not closed by [47mld[0m. If the supplied value of one of these specials is a string, the string is treated as a file name in (essentially) Unix syntax (see [pathname]) and a channel of the appropriate type is opened to/from that file. Any channel opened by [47mld[0m during the binding of the [47mld[0m specials is automatically closed by [47mld[0m upon termination. If [47m[standard-co][0m and [47m[proofs-co][0m are strings that represent the same file, only one channel to that file is opened and is used for both. As a special convenience, when [47m[standard-oi][0m is a string and the [47m:dir[0m argument is provided and not [47mnil[0m, we look up [47m:dir[0m just as is done for [47m[include-book][0m; also see [47m[add-include-book-dir][0m, [47m[add-include-book-dir!][0m, and [47m[project-dir-alist][0m. Thus a suitable directory is prepended to create the filename. Note that [47mstandard-oi[0m must be a string that is a relative pathname, not an absolute pathname. For example, one can write [47m(ld "arithmetic/top-with-meta.lisp" :dir :system)[0m to [47mld[0m that particular [community-books] library. (Of course, for certified [books] you should almost always use [47m[include-book][0m instead of [47mld[0m.) If [47m:dir[0m is not specified, then a relative pathname is resolved using the connected book directory; see [cbd]. If you want to load a list of forms, then consider prepending a call of [47m[set-cbd][0m to that list rather than using [47m:dir[0m, which is not supported when [47mstandard-oi[0m is a list. Several other alternatives are allowed for [47m[standard-oi][0m. If [47m[standard-oi][0m is a true list then it is taken as the list of forms to be processed. If [47m[standard-oi][0m is a list ending in an open channel, then [47mld[0m processes the forms in the list and then reads and processes the forms from the channel. Analogously, if [47m[standard-oi][0m is a list ending a string, an object input channel from the named file is opened and [47mld[0m processes the forms in the list followed by the forms in the file. That channel is closed upon termination of [47mld[0m. In the cases that a string is to be converted to an object input channel --- that is, when [47m[standard-oi][0m is a string or is a list ending in a string --- an error occurs by default if the conversion fails, presumably because the file named by the string does not exist. However, if keyword argument [47m:ld-missing-input-ok[0m is [47mt[0m, then [47mld[0m immediately returns without error in this case, but without reading or executing any forms, as though [47mstandard-oi[0m is [47mnil[0m and keyword arguments [47m:ld-verbose[0m and [47m:ld-prompt[0m both have value [47mnil[0m. The other legal values for [47m:ld-missing-input-ok[0m are [47mnil[0m, which gives the default behavior, and [47m:warn[0m, which behaves the same as [47mt[0m except that a warning is printed, which contains the same information as would be printed for the default error described above. The remaining [47mld[0m specials are handled more simply and generally have to be bound to one of a finite number of tokens described in the [47m:[0m[47m[doc][0m entries for each [47mld[0m special. Should any [47mld[0m special be supplied an inappropriate value, an error message is printed. Next, if [47m[ld-verbose][0m is [47mt[0m, [47mld[0m prints the message ``ACL2 loading name'' where [47mname[0m names the file or channel from which forms are being read. At the conclusion of [47mld[0m, it will print ``Finished loading name'' if [47m[ld-verbose][0m is [47mt[0m. One may generally omit [47mld-user-stobjs-modified-warning[0m except when calling [47mld[0m in the body of a definition. In that case this keyword argument is required, and the value [47mt[0m is recommended. With that value, a warning will generally be printed if a user-defined [stobj] is modified by the call of [47mld[0m; value [47mnil[0m avoids such warnings, and value [47m:same[0m causes the value to be inherited from the existing value (generally from a superior call of [47mld[0m). A discussion of these warnings is highly recommended reading before you give a value other than [47mt[0m; see [user-stobjs-modified-warnings]. Finally, [47mld[0m repeatedly executes the ACL2 read-eval-print step, which may be described as follows. A [prompt] is printed to [47m[standard-co][0m if [47m[ld-prompt][0m is non-[47mnil[0m. The format of the [prompt] is determined by [47m[ld-prompt][0m. If it is [47mt[0m, the default ACL2 [prompt] is used. If it is any other non-[47mnil[0m value then it is treated as an ACL2 function that will print the desired [prompt]. See [ld-prompt]. In the exceptional case where [47mld[0m's input is coming from the terminal [47m(*standard-oi*)[0m but its output is going to a different sink (i.e., [47m[standard-co][0m is not [47m[*standard-co*][0m), we also print the [prompt] to the terminal. [47mLd[0m then reads a form from [47m[standard-oi][0m. If the object read is a keyword, [47mld[0m constructs a ``keyword command form'' by possibly reading several more objects. See [keyword-commands]. This construction process is sensitive to the value of [47m[ld-keyword-aliases][0m. See [ld-keyword-aliases]. Otherwise, the object read is treated as the command form. (Technical Aside. Some special handling takes place when [47mld[0m is called in the scope of [47m[local][0m, as in [47m(local (ld <C>))[0m for a command, [47m<C>[0m. In that case, after [47m<C>[0m is evaluated, then if the result is an [error-triple] and [47m<C>[0m is not already of the form [47m(local <C0>)[0m, then when the command is stored in the ACL2 [world] it is stored as [47m(local <C>)[0m instead of [47m<C>[0m. See [ld-history] for a similar treatment of local commands. End of Technical Aside.) [47mLd[0m next decides whether to evaluate or skip this form, depending on [47m[ld-pre-eval-filter][0m. Initially, the filter must be either [47m:all[0m, [47m:query[0m, or a new name. If it is [47m:all[0m, it means all forms are evaluated. If it is [47m:query[0m, it means each form that is read is displayed and the user is queried. Otherwise, the filter is a name and each form that is read is evaluated as long as the name remains new, but if the name is ever introduced then no more forms are read and [47mld[0m terminates. See [ld-pre-eval-filter]. If the form is to be evaluated, then [47mld[0m first prints the form to [47m[standard-co][0m, if [47m[ld-pre-eval-print][0m is [47mt[0m. With this feature, [47mld[0m can process an input file or form list and construct a script of the session that appears as though each form was typed in. See [ld-pre-eval-print]. [47mLd[0m then evaluates the form, with [47m[state][0m bound to the current [state]. The result is some list of (multiple) values. If a [state] is among the values, then [47mld[0m uses that [state] as the subsequent current [state]. Depending on [47m[ld-error-triples][0m, [47mld[0m may interpret the result as an ``error.'' See [ld-error-triples]. We first discuss [47mld[0m's behavior if no error signal is detected (either because none was sent or because [47mld[0m is ignoring them because [47m[ld-error-triples][0m is [47mnil[0m). In the case of a non-erroneous result, [47mld[0m does two things: First, if the logical [world] in the now current [state] is different than the [world] before execution of the form, [47mld[0m adds to the [world] a ``[command] landmark'' containing the form evaluated. See [command-descriptor]. Second, [47mld[0m prints the result to [47m[standard-co][0m, but only if [47m[ld-post-eval-print][0m is not [47mnil[0m. The result is printed as a list of (multiple) values unless [47m[ld-post-eval-print][0m is [47m:command-conventions[0m, [47m[ld-error-triples][0m is [47mt[0m, and the result is an [error-triple], i.e., of the form [47m(mv * * state)[0m. In that case, only the non-erroneous ``value'' component of the result is printed. See [ld-post-eval-print]. Whenever [47mld[0m prints anything (whether the input form, a query, or some results) it ``eviscerates'' it if [47mld-evisc-tuple[0m is non-[47mnil[0m. Essentially, evisceration is a generalization of Common Lisp's use of [47m*print-level*[0m and [47m*print-length*[0m to hide large substructures. See [evisc-tuple] and also see [set-iprint]. We now return to the case of a form whose evaluation signals an error. In this case, [47mld[0m first restores the ACL2 logical [world] to what it was just before the erroneous form was evaluated. Thus, a form that partially changes the [world] (i.e., begins to store properties) and then signals an error, has no effect on the [world]. You may see this happen on [command]s that execute several [events] (e.g., an [47m[encapsulate][0m or a [47m[progn][0m of several [47m[defuns][0m): even though the output makes it appear that the initial [events] were executed, if an error is signaled by a later event the entire block of [events] is discarded. After rolling back, [47mld[0m takes an action determined by [47m[ld-error-action][0m. If the action is [47m:continue[0m, [47mld[0m merely iterates the read-eval-print step. Note that nothing suggestive of the value of the ``erroneous'' form is printed. If the action is [47m:return[0m, [47mld[0m terminates normally; similarly if the action is [47m:return![0m, but a special value is returned that can cause superior [47mld[0m commands to terminate; see [ld-error-action] for details. If the action is [47m:error[0m, [47mld[0m terminates signaling an error to its caller. If its caller is in fact another instance of [47mld[0m and that instance is watching out for error signals, the entire [world] created by the inner [47mld[0m will be discarded by the outer [47mld[0m if the inner [47mld[0m terminates with an error. Note that if the action is [47m(:exit N)[0m, then there is no rolling back, because ACL2 quits immediately with exit status [47mN[0m. [47mLd[0m returns an error triple, [47m(mv erp val state)[0m. [47mErp[0m is [47mt[0m or [47mnil[0m indicating whether an error is being signaled. If no error is signaled, [47mval[0m is the ``reason'' [47mld[0m terminated and is one of [47m:exit[0m (meaning [47m:[0m[47m[q][0m was read), [47m:eof[0m (meaning the input source was exhausted), [47m:error[0m (meaning an error occurred but has been suppressed), [47m:filter[0m (meaning the [47m[ld-pre-eval-filter][0m terminated [47mld[0m), [47m:missing-input[0m (meaning that the specified input file is missing, in the case that keyword [47m:ld-missing-input-ok[0m has a non-[47mnil[0m value so that an error is avoided), or a cons pair whose first component is the symbol [47m:STOP-LD[0m, which typically indicates that an error occurred while the value of variable [47m'[0m[47m[ld-error-action][0m was [47m:RETURN![0m. See [ld-error-action] for details of this last case. Subtopics [A!] To return to the top-level of ACL2's command loop [Abort!] To return to the top-level of ACL2's command loop [Calling-ld-in-bad-contexts] Errors caused by calling [47m[ld][0m in inappropriate contexts [Current-package] The package used for reading and printing [Default-print-prompt] The default [prompt] printed by [47m[ld][0m [Guarantees-of-the-top-level-loop] Guarantees provided by top-level evaluation [I-am-here] A convenient marker for use with [47m[rebuild][0m or [47m[ld][0m [Keyword-commands] How keyword commands like [47m:u[0m and [47m:pbt[0m are processed [Ld-always-skip-top-level-locals] Determines whether [47m[ld][0m skips [47m[local][0m top-level forms [Ld-error-action] Determines [47m[ld][0m's response to an error [Ld-error-triples] Determines whether a form caused an error during [47m[ld][0m [Ld-evisc-tuple] Determines whether [47m[ld][0m suppresses details when printing [Ld-history] Saving and querying command history [Ld-keyword-aliases] Abbreviation of some keyword commands [Ld-missing-input-ok] Determine whether [47m[ld][0m causes an error for a missing file [Ld-post-eval-print] Determines whether and how [47m[ld][0m prints the result of evaluation [Ld-pre-eval-filter] Determines which forms [47m[ld][0m evaluates [Ld-pre-eval-print] Determines whether [47m[ld][0m prints the forms to be [47meval[0m'd [Ld-prompt] Determines the [prompt] printed by [47m[ld][0m [Ld-query-control-alist] How to default answers to queries [Ld-redefinition-action] To allow redefinition without [undoing] [Ld-skip-proofsp] How carefully ACL2 processes your [command]s [Ld-verbose] Determines whether [47m[ld][0m prints ``ACL2 Loading ...'' [Lp] The Common Lisp entry to ACL2 [P!] To pop up (at least) one level of ACL2's command loop [Prompt] The prompt printed by [47m[ld][0m [Rebuild] A convenient way to reconstruct your old [state] [Redef] A common way to set [ld-redefinition-action] [Redef!] A common way to set [ld-redefinition-action] [Redef+] System hacker's redefinition [command] [Redef-] Turn off system hacker's redefinition [command] [Reset-ld-specials] Restores initial settings of the [47m[ld][0m specials [Stobj-attachment-restrictions] Restrictions on attachments to supporters of [stobj] primitives [Wormhole] [47m[ld][0m without [47m[state][0m --- a short-cut to a parallel universe") (ld-always-skip-top-level-locals (ld) "Determines whether [47m[ld][0m skips [47m[local][0m top-level forms [47mLd-always-skip-top-level-locals[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-always-skip-top-level-locals state)[0m and the updater is [47m(set-ld-always-skip-top-level-locals val state)[0m. The value of [47mld-always-skip-top-level-locals[0m must be either [47mnil[0m or [47mt[0m. The initial value of [47mld-always-skip-top-level-locals[0m is [47mnil[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, is controlled by various flags that control its behavior, and [47mld-always-skip-top-level-locals[0m is one of them. When the value is [47mt[0m, [47m[local][0m [events] are skipped when they are at the top level in the following sense: they are not evaluated in the scope of either a call of [47m[certify-book][0m, [47m[include-book][0m, or [47m[encapsulate][0m, or else during [47m[make-event][0m expansion.") (ld-error-action (ld) "Determines [47m[ld][0m's response to an error [47mLd-error-action[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-error-action state)[0m and the updater is [47m(set-ld-error-action val state)[0m. [47mLd-error-action[0m must be [47m:continue[0m, [47m:return[0m, [47m:return![0m, [47m:error[0m, or [47m(:exit N)[0m for some natural number [47mN[0m. The initial value of [47mld-error-action[0m is [47m:continue[0m, which means that the top-level ACL2 [command] loop (see [47m[lp][0m) will not exit when an error is caused by [47muser-typein[0m. But the default value for [47mld-error-action[0m on calls of [47m[ld][0m is [47m:return![0m, with one exception: in the case that the value of [47m[ld][0m special [47mld-error-action[0m is [47m(:exit N)[0m, the default remains that value. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-error-action[0m is one of them. Suppose that [47m[ld-error-triples][0m is [47mt[0m and a form evaluates to an [error-triple] [47m(mv erp val state)[0m. If the ``error component'', [47merp[0m, is non-[47mnil[0m, then an error is said to have occurred. If an error occurs, [47m[ld][0m's action depends on [47mld-error-action[0m. If it is [47m:continue[0m, [47m[ld][0m just continues processing the forms in [47m[standard-oi][0m. If it is [47m:return[0m or [47m:return![0m, [47m[ld][0m stops and returns as though it had emptied the channel. If it is [47m:error[0m, [47m[ld][0m stops and returns, signaling an error to its caller by returning an error triple with non-[47mnil[0m error component, and reverting the logical [world] to its value just before that call of [47m[ld][0m. If it is [47m(:exit N)[0m, then ACL2 quits with exit status [47mN[0m. Later in this topic we discuss another case in which an error is said to have occurred: when the value component of an error triple is of the form [47m(:STOP-LD . x)[0m. To see this effect of [47m:ERROR[0m for [47mld-error-action[0m, consider the following example. (ld '((defun f (x) x) (defun bad (x)) (defun g (x) x))) When the [47m[defun][0m of [47mbad[0m fails (because its body is missing), evaluation of the [47mld[0m call stops; thus, the [47m[defun][0m of [47mg[0m is not evaluated. The definition of [47mf[0m will be removed from the logical [world] before the call of [47mld[0m returns. However, by default each user call of [47mld[0m is made with a [47mld-error-action[0m of [47m:RETURN![0m (not [47m:ERROR[0m). In the common case that all nested calls of [47mld[0m inside the ACL2 loop are made this way, an error will not roll back the logical [world]. However, it will still halt evaluation of forms for the current call of [47mld[0m and any parent calls of [47mld[0m (other than the call made on behalf of [47mlp[0m that entered the ACL2 loop in the first place), as though there were no more forms to evaluate. We have already discussed the behavior of [47mld[0m when an error occurs. But there is another case when [47mld[0m can stop processing more forms: when [47mld-error-action[0m is not [47m:CONTINUE[0m, [47m[ld-error-triples][0m is [47mt[0m, and evaluation of a form returns an error triple [47m(mv nil val state)[0m, where [47mnil[0m is the error component and whose ``value component'', [47mval[0m is a [47m[cons][0m pair whose [47m[car][0m is the symbol [47m:STOP-LD[0m. Let [47mval[0m be the pair [47m(:STOP-LD . x)[0m. If [47mld-error-action[0m is of the form [47m(:EXIT N)[0m, then ACL2 quits with exit status [47mN[0m. Otherwise (i.e., when [47mld-error-action[0m is [47m:RETURN[0m, [47m:RETURN![0m, or [47m:ERROR[0m), the call of [47mld[0m returns the error triple [47m(mv nil (:STOP-LD n . x) state)[0m, where [47mn[0m is the value of [47m[state][0m global variable [47m'ld-level[0m at the time of termination. The following example illustrates how this works. (ld '((defun f1 (x) x) (ld '((defun f2 (x) x) (mv nil '(:STOP-LD my-error more-info) state) (defun g2 (x) x))) (defun g1 (x) x))) The outer call of [47mld[0m returns the value (:STOP-LD 2 3 MY-ERROR MORE-INFO) and leaves us in a world the includes definitions for [47mf1[0m and [47mf2[0m, but no definition for [47mg1[0m or [47mg2[0m since neither of their two [47mdefun[0m forms was evaluated. The value of [47m[state][0m global [47m'ld-level[0m is incremented from 1 to 2 when the outer [47mld[0m is entered and then again to 3 when the inner [47mld[0m is entered. When the inner [47mld[0m encounters the error triple [47m(mv nil (:STOP-LD my-error more-info) state)[0m, it sees [47m:STOP-LD[0m in the [47mcar[0m of the value component and pushes the current value of [47m'ld-level[0m, 3, onto the [47m[cdr][0m of that value, to return the value triple [47m(mv nil (:STOP-LD my-error 3 more-info) state)[0m. The outer of [47mld[0m then sees this value and returns [47m(mv nil (:STOP-LD my-error 2 3 more-info) state)[0m, since its current value of [47m'ld-level[0m is 2 after the inner [47mld[0m exits. That concludes our discussion of how these special [47m:STOP-LD[0m values are handled; but how are they created? While they can be created directly by evaluation results as suggested in the example above, that is not the standard way. Rather, [47mld[0m returns an error triple [47m(mv nil (:STOP-LD n) state)[0m, where [47mn[0m is the value of variable [47mld-level[0m at the time of termination, when the following conditions hold: an error occurs, [47mld-error-action[0m is [47mRETURN![0m (which is the default), and [47m[ld-error-triples][0m is [47mt[0m (the default). The following example, which is a bit similar to the preceding one, illustrates both creation and handling of the special [47m:STOP-LD[0m values. (ld '((defun f1 (x) x) (ld '((defun f2 (x) x) (ld '((defun f3 (x) x) (defun bad (x)) ; ERROR -- missing the body (defun g3 (x) x))) (defun g2 (x) x))) (defun g1 (x) x))) The result is that [47mf1[0m, [47mf2[0m, and [47mf3[0m are defined, but none of [47mg1[0m, [47mg2[0m, or [47mg3[0m is defined. Let's see why. The innermost call of [47m[ld][0m has a default [47m:ld-error-action[0m of [47m:RETURN![0m (as do the other calls). So when the definition of [47mbad[0m fails, then the innermost [47mld[0m returns [47m(mv nil (:STOP-LD 4) state)[0m. The middle [47mld[0m sees this value, and since its [47m:ld-error-action[0m is not [47m:CONTINUE[0m (because it has the default value of [47m:RETURN![0m), it returns before considering the definition of [47mg2[0m, with value [47m(mv nil (:STOP-LD 3 4) state)[0m. The topmost call of [47mld[0m similarly sees the [47m:STOP-LD[0m; stops evaluation of forms, without defining [47mg1[0m; and returns [47m(mv nil (:STOP-LD 2 3 4) state)[0m.") (ld-error-triples (ld) "Determines whether a form caused an error during [47m[ld][0m [47mLd-error-triples[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-error-triples state)[0m and the updater is [47m(set-ld-error-triples val state)[0m. [47mLd-error-triples[0m must be either [47mt[0m or [47mnil[0m. The initial value of [47mld-error-triples[0m is [47mt[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-error-triples[0m is one of them. If this variable has the value [47mt[0m then when a form evaluates to an [error-triple] [47m(mv erp val state)[0m such that [47merp[0m is non-[47mnil[0m, then an error is deemed to have occurred. When an error occurs in evaluating a form, [47m[ld][0m rolls back the ACL2 [world] to the configuration it had at the conclusion of the last error-free form. Then [47m[ld][0m takes the action determined by [47m[ld-error-action][0m.") (ld-evisc-tuple (ld) "Determines whether [47m[ld][0m suppresses details when printing [47mLd-evisc-tuple[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-evisc-tuple state)[0m and an updater is [47m(set-ld-evisc-tuple val state)[0m, although the use of [47m[set-evisc-tuple][0m is preferred for updating. [47mLd-evisc-tuple[0m must be either [47mnil[0m, which is its initial value, or a legal evisc-tuple: see [set-evisc-tuple]. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-evisc-tuple[0m is one of them. [47m[Ld][0m may print the forms it is evaluating and/or the results of evaluation. Depending on the value of [47mld-evisc-tuple[0m [47m[ld][0m may ``eviscerate'' objects before printing them. See [set-evisc-tuple] for a discussion of evisceration and of how other evisc-tuples affect the printing of error messages and warnings, as well as other output not from [47mld[0m.") (ld-history (ld history) "Saving and querying command history See [ld] for background on the ACL2 read-eval-print loop. The present topic pertains to a history kept for commands issued to that loop, which we call an ``ld-history'' (pronounced ``ell dee history''). Here are some things to keep in mind when reading this topic. * Each entry in the history includes the input command, the value returned, and other information, as explained further below. * This is about commands, not events: that is, we are concerned with forms that are submitted for evaluation to the top-level loop. See [command]. * An entry is saved for every command submitted by the user, even if it doesn't change the ACL2 [world] --- e.g., [47m(+ 3 4)[0m --- and even if it undoes commands --- e.g., [47m:[0m[47mubt[0m. * Keyword commands are turned into s-expressions before saving an entry; see [keyword-commands]. For example, the input [47m:ubt :x[0m is stored in an entry as the input [47m(ubt ':x)[0m. * When an entry is saved for a command [47mC[0m that is evaluated in the context of a call of [47m[local][0m, where [47mC[0m evaluates to an [error-triple], then [47mC[0m is stored in the entry as [47m(local C)[0m unless [47mC[0m is already a call of [47mlocal[0m. (Technical Aside: This behavior supports local [portcullis] commands.) * The ld-history saves entries not only for commands issued in the original top-level loop, but also for commands issued in (recursive) calls of [47m[ld][0m --- but not during [47m[make-event][0m expansion. * Entries are generally saved even when there are errors. However, entries are not saved for commands that exit with raw Lisp errors. Also see [community-books] file [47mbooks/demos/ld-history-input.lsp[0m for examples. The output from calling [47m[ld][0m on that file (by calling the [47m[run-script][0m tool in [47mbooks/demos/ld-history-book.acl2[0m) is in [community-books] file [47mbooks/demos/ld-history-log.txt[0m. The ld-history is a stack, represented as a list with the most recent commands at the front. But by default ACL2 is in [3msingle-entry mode[0m, where the list is kept at length 1: an entry is saved in the ld-history only for the most recent command, and the previous entry is discarded. We now describe relevant utilities, including one that can switch to [3mmultiple-entry mode[0m, where all entries are kept until a utility is called explicitly to discard old entries. Note that the mode is determined by the length of the ld-history: single-entry mode when length 1, multiple-entry mode when length 2 or more. * [47m(ld-history state)[0m This utility returns a list of structures, denoted ``ld-history entries'', with the most recent one first. By default, this list has length 1, but that can be changed; see [47madjust-ld-history[0m below. Each entry in the list is recognized by the following predicate. [31;1mNOTE[0m: This query is evaluated before the ld-history stored in the ACL2 state is updated with a new entry, based on the current command; so the previous command will be at the top of the returned stack, not the current command. (In particular, submitting the form [47m(ld-history state)[0m at the ACL2 prompt does not put that form at the front of the returned list.) * [47m(weak-ld-history-entry-p x)[0m This function returns [47mt[0m if [47mx[0m has the shape of an entry in the ld-history list, else [47mnil[0m. * Here are accessors for an ld-history entry, which we think of as returning its fields. The formal parameter [47mentry[0m below is an entry in (i.e., member of) [47m(ld-history state)[0m; an example call is thus [47m(ld-history-entry-input (car (ld-history state)))[0m. * [47m(ld-history-entry-input entry)[0m The user input * [47m(ld-history-entry-error-flg entry)[0m Non-[47mnil[0m when there was an error translating the user input * [47m(ld-history-entry-stobjs-out/value entry)[0m When [47m(ld-history-entry-error-flg entry)[0m is [47mnil[0m, this is a cons whose [47mcar[0m is the [stobjs-out] --- a list whose length is the number of values returned, with [47mnil[0m in each position except when occupied by a symbol indicating a returned [stobj] for that position --- and whose [47mcdr[0m is the returned value in the single-value case, but is the list of returned values in the [multiple-value] case. * [47m(ld-history-entry-stobjs-out entry)[0m When [47m(ld-history-entry-error-flg entry)[0m is [47mnil[0m, this is the stobjs-out as described above; otherwise this is [47mnil[0m. * [47m(ld-history-entry-value entry)[0m When [47m(ld-history-entry-error-flg entry)[0m is [47mnil[0m, this is the value or values as described above; otherwise this is [47mnil[0m. * [47m(ld-history-entry-user-data entry)[0m This is [47mnil[0m by default. However, code can be provided to compute this field, as discussed below. * [47m(adjust-ld-history x state)[0m [47mX[0m is [47mt[0m, [47mnil[0m, or an integer. The result is an [error-triple] [47m(mv nil value state)[0m, where [47mvalue[0m and the effect are as follows, and where if there is no change (i.e., the effect is a no-op) then [47mvalue[0m is [47m(:no-change :length N)[0m where [47mN[0m is the current length of the ld-history. * [47mT[0m: Change to multiple-entry mode, where an entry is saved for every command, not just the most recent command. There is no change if already in multiple-entry mode; otherwise the returned [47mvalue[0m is [47m(:saving-ld-history t)[0m. * [47mNIL[0m: Change to single-entry mode, where an entry is saved only for the most recent command. There is no change if already in single-entry mode; otherwise the returned [47mvalue[0m is [47m(:saving-ld-history nil)[0m, and all old entries will be discarded (to produce a single-element ld-history). * Positive integer [47mk[0m: Replace the current ld-history by its first [47mk[0m entries, except there is no change if in single-entry mode or if [47mk[0m is not less than the length of the current ld-history. Note that by ``current ld-history'' we refer to the ld-history in effect at the time [47madjust-ld-history[0m is invoked, which does not include the current command being evaluated. (Thus, even if [47mk[0m is 1, multiple-entry mode will be preserved: the ld-history will have 2 entries immediately after the current command completes.) The returned [47mvalue[0m is [47m(:ld-history-truncated :old-length LEN :new-length k)[0m, where [47mLEN[0m is the length of the current ld-history before the change. * Negative integer [47m-k[0m: This is intended to specify removal of the oldest [47mk[0m entries from the current ld-history. Thus, it is treated identically to argument [47mk2[0m where [47mk2[0m is the sum of [47m-k[0m and the length of the current ld-history, but only if that sum is positive; else there is no change. For example, suppose that [47m-k[0m is -3. If the current ld-history, [47mh[0m, has length 2 or 3, then there is no change; but if [47mh[0m has length 10, then it is to be replaced by [47m(take 7 h)[0m and the length will actually thus be 8 after the current command completes. Note that a call of [47madjust-ld-history[0m is not an [event] that can be placed directly in [books] or [47m[encapsulate][0m forms. Remark. If [47m(adjust-ld-history n state)[0m is evaluated while in multiple-entry mode, where n is a positive integer less than the current length of the ld-history, then the new ld-history after returning to the prompt will have length [47mn+1[0m. That's essentially because it will have length [47mn[0m immediately after that call of [47madjust-ld-history[0m is evaluated, and then a new entry for the current command (which could be that call itself, if that's what was submitted at the prompt) will be pushed onto the ld-entry just before returning to the prompt. We say ``essentially'' because there is a Special Case: when [47mn[0m is 1 then a 2-element list of entries [47m(e1 e2)[0m is created where [47me2[0m has fields that are all [47mnil[0m; then when the new entry [47me[0m is pushed onto the ld-history, [47me2[0m is dropped so that the new ld-history is [47m(e e1)[0m. This special-case trick is also used in multiple-entry mode when [47mn[0m is [47m-k[0m where [47mk[0m is one less than the length of the current ld-history, since that is treated the same as [47m(adjust-ld-history 1 state)[0m; and this trick is also used when [47m(adjust-ld-history t state)[0m switches from single-entry mode to multiple-entry mode. End of Remark. Finally we discuss the user-data field of a ld-history entry, which (as noted above) has default [47mnil[0m. It is accessed using [47m(ld-history-entry-user-data entry)[0m. It is set automatically when the ld-history is extended with a new entry: the function call [47m(set-ld-history-entry-user-data input error-flg stobjs-out/value state)[0m, is executed where the actuals are the other fields of the entry as indicated, e.g., the first actual is the input field of the new entry (as returned by the function, [47mld-history-entry-input[0m). Although [47mset-ld-history-entry-user-data[0m returns [47mnil[0m by default, this can be changed by providing your own function with a [47m:[0m[47m[guard][0m of [47mt[0m and the same formal parameters (which however may be renamed, other than [47mstate[0m). To make that change, define a function, which here we call [47mmy-user-data[0m, and then attach it to [47mset-ld-history-entry-user-data[0m, as follows. (defun my-set-user-data (input error-flg stobjs-out/value state) (declare (xargs :guard t)) ...) (defattach-system set-ld-history-entry-user-data my-set-user-data) The following example illustrates how to store the length of the ACL2 [world] in the user-data. Note that the [world] present in the [state] at the time the user-data is set, computed as [47m(w state)[0m, is almost the final world produced by the command --- it is missing just one triple, a so-called command marker. (defun my-world-length (input error-flg stobjs-out/value state) (declare (xargs :guard t :stobjs state) (ignore input error-flg stobjs-out/value)) (len (w state))) (defattach-system set-ld-history-entry-user-data my-world-length) A subsequent inspection of the stored user-data shows the length of the current world, for example as follows. ACL2 !>(ld-history-entry-user-data (car (ld-history state))) 125914 ACL2 !> Notice that we used [47m[len][0m, not [47m[length][0m, since the [47m:[0m[47m[guard][0m specified for our function needs to be [47mt[0m. Alternative definitions, which however are less efficient, are as follows. (defun my-world-length (input error-flg stobjs-out/value state) (declare (xargs :guard t :stobjs state) (ignore input error-flg stobjs-out/value)) (and (true-listp (w state)) (length (w state)))) (defun my-world-length (input error-flg stobjs-out/value state) (declare (xargs :guard t :stobjs state) (ignore input error-flg stobjs-out/value)) (ec-call (length (w state)))) Here is how to restore the original behavior, i.e., the default where the user-data is set to [47mnil[0m. (defattach-system set-ld-history-entry-user-data set-ld-history-entry-user-data-default)") (ld-history-entry-error-flg (pointers) "See [ld-history].") (ld-history-entry-input (pointers) "See [ld-history].") (ld-history-entry-stobjs-out (pointers) "See [ld-history].") (ld-history-entry-stobjs-out/value (pointers) "See [ld-history].") (ld-history-entry-user-data (pointers) "See [ld-history].") (ld-history-entry-value (pointers) "See [ld-history].") (ld-keyword-aliases (ld) "Abbreviation of some keyword commands Examples: (set-ld-keyword-aliases '((:q 0 q-fn) (:e 0 exit-acl2-macro)) state) (ld-keyword-aliases state) ; current value of the ld-keyword-aliases table [47mLd-keyword-aliases[0m is the name of a ACL2 table (see [table]) and also the name of a function of [47mstate[0m that returns the value of this table. That value must be an alist, each element of which is of the form [47m(:keyword n fn)[0m, where [47m:keyword[0m is a keyword, [47mn[0m is a nonnegative integer, and [47mfn[0m is a function symbol of arity [47mn[0m, a macro symbol, or a [47mlambda[0m expression of arity [47mn[0m. When [47mkeyword[0m is typed as an [47m[ld][0m command, [47mn[0m more forms are read, [47mx1, ..., xn[0m, and the form [47m(fn 'x1 ... 'xn)[0m is then evaluated. The initial value of the [47mld-keyword-aliases[0m [table] is [47mnil[0m. ACL2 provides functions to modify the [47mld-keyword-aliases[0m table, as follows. [47m(Set-ld-keyword-aliases val state)[0m: sets the table to [47mval[0m, which must be a legal alist as described above. This is an event that may go into a book (see [events]), but its effect will be [local] to that book. [47mSet-ld-keyword-aliases![0m is the same as [47mset-ld-keyword-aliases[0m, except that its effect is not [local]. Indeed, the form [47m(set-ld-keyword-aliases val state)[0m is equivalent to the form [47m(local (set-ld-keyword-aliases! val state)[0m. [47m(Add-ld-keyword-alias key val state)[0m: modifies the table by binding the keyword [47mkey[0m to [47mval[0m, which must be a legal value as described above. This is an event that may go into a book (see [events]), but its effect will be [local] to that book. [47mAdd-ld-keyword-alias![0m is the same as [47madd-ld-keyword-alias[0m, except that its effect is not [local]. Indeed, the form [47m(add-ld-keyword-alias key val state)[0m is equivalent to the form [47m(local (add-ld-keyword-alias! key val state)[0m. Consider the first example above: (set-ld-keyword-aliases '((:q 0 q-fn) (:e 0 exit-acl2-macro)) state) With this event, [47m:[0m[47m[q][0m is redefined to have the effect of executing [47m(q-fn)[0m, so for example if you have defined [47mq-fn[0m with (defmacro q-fn () '(er soft 'q "You un-bound :q and now we have a soft error.")) then [47m:[0m[47m[q][0m will cause an error, and if you have defined (defmacro exit-acl2-macro () '(exit-ld state)) then [47m:e[0m will cause the effect (it so happens) that [47m:[0m[47m[q][0m normally has. If you prefer [47m:e[0m to [47m:[0m[47m[q][0m for exiting the ACL2 loop, you might even want to put such definitions of [47mq-fn[0m and [47mexit-acl2-macro[0m together with the [47mset-ld-keyword-aliases[0m form above into your [47m"acl2-customization.lsp"[0m file; see [ACL2-customization]. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-keyword-aliases[0m is one of them. [47mLd-keyword-aliases[0m affects how keyword commands are parsed. Generally speaking, [47m[ld][0m's command interpreter reads ``[47m:fn x1 ... xn[0m'' as ``[47m(fn 'x1 ... 'xn)[0m'' when [47m:fn[0m is a keyword and [47mfn[0m is the name of an [47mn[0m-ary function; see [keyword-commands]. But this parse is overridden, as described above, for the keywords bound in the [47mld-keyword-aliases[0m [table].") (ld-missing-input-ok (ld) "Determine whether [47m[ld][0m causes an error for a missing file [47mLd-missing-input-ok[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-missing-input-ok state)[0m and the updater is [47m(set-ld-missing-input-ok val state)[0m. The value of [47mld-missing-input-ok[0m must be either [47mnil[0m, [47mt[0m, or [47m:warn[0m. The initial value of [47mld-missing-input-ok[0m is [47mnil[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, is controlled by various flags that control its behavior, and [47mld-missing-input-ok[0m is one of them. In brief, the first argument of [47mld[0m can indicate a file from which to read input. If the file does not exist, it is an error by default, but [47mld[0m becomes essentially a no-op if [47mt[0m or [47m:warn[0m is supplied for [47m:ld-missing-input-ok[0m, where [47m:warn[0m prints a warning. Also see [ld].") (ld-post-eval-print (ld) "Determines whether and how [47m[ld][0m prints the result of evaluation [47mLd-post-eval-print[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-post-eval-print state)[0m and the updater is [47m(set-ld-post-eval-print val state)[0m. [47mLd-post-eval-print[0m must be either [47mt[0m, [47mnil[0m, or [47m:command-conventions[0m. The initial value of [47mld-post-eval-print[0m is [47m:command-conventions[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-post-eval-print[0m is one of them. If this global variable is [47mt[0m, [47m[ld][0m prints the result. In the case of a form that produces a multiple value, [47m[ld][0m prints the list containing all the values (which, logically speaking, is what the form returned). If [47mld-post-eval-print[0m is [47mnil[0m, [47m[ld][0m does not print the values. This is most useful when [47m[ld][0m is used to load a previously processed file. Finally, if [47mld-post-eval-print[0m is [47m:command-conventions[0m and also [47mld-error-triples[0m is [47mt[0m, then [47m[ld][0m prints the result but treats ``error triples'' specially. An ``error triple'' (see [error-triple]) is a result, [47m(mv erp val state)[0m, that consists of two ordinary values and [47m[state][0m. Many ACL2 functions use such triples to signal errors. The convention is that if [47merp[0m (the first value) is [47mnil[0m, then the function is returning [47mval[0m (the second value) as its conventional single result and possibly side-effecting [state] (as with some output). If [47merp[0m is not [47mnil[0m, then an error has been caused, [47mval[0m is irrelevant and the error message has been printed in the returned [state]. Example ACL2 functions that follow this convention include [47m[defun][0m and [47m[in-package][0m. If such ``error producing'' functions are evaluated while [47mld-post-eval-print[0m is set to [47mt[0m, then you would see them producing lists of length 3. This is disconcerting to users accustomed to Common Lisp (where these functions produce single results but sometimes cause errors or side-effect [state]). For more information about error triples, see [programming-with-state]. When [47mld-post-eval-print[0m is [47m:command-conventions[0m and a form produces an error triple [47m(mv erp val state)[0m as its value, [47m[ld][0m prints nothing if [47merp[0m is non-[47mnil[0m and otherwise [47m[ld][0m prints just [47mval[0m. Because it is a misrepresentation to suggest that just one result was returned, [47m[ld][0m prints the value of the global variable [47m'triple-print-prefix[0m before printing [47mval[0m. [47m'triple-print-prefix[0m is initially [47m" "[0m, which means that when non-erroneous error triples are being abbreviated to [47mval[0m, [47mval[0m appears one space off the left margin instead of on the margin. In addition, when [47mld-post-eval-print[0m is [47m:command-conventions[0m and the value component of an error triple is the keyword [47m:invisible[0m then [47m[ld][0m prints nothing. This is the way certain commands (e.g., [47m:[0m[47m[pc][0m) appear to return no value. By printing nothing when an error has been signaled, [47m[ld][0m makes it appear that the error (whose message has already appeared in [state]) has ``thrown'' the computation back to load without returning a value. By printing just [47mval[0m otherwise, we suppress the fact that [state] has possibly been changed.") (ld-pre-eval-filter (ld) "Determines which forms [47m[ld][0m evaluates [47mLd-pre-eval-filter[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-pre-eval-filter state)[0m and the updater is [47m(set-ld-pre-eval-filter val state)[0m. [47mLd-pre-eval-filter[0m must be either [47m:all[0m, [47m:query[0m, or a new name that could be defined (e.g., by [47m[defun][0m or [47m[defconst][0m). (There is actually a value that may on rare occasions be set by the ACL2 system, [47m:illegal-state[0m; we ignore that value here, but the curious reader is welcome to see [illegal-state].) The initial value of [47mld-pre-eval-filter[0m is [47m:all[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-pre-eval-filter[0m is one of them. If the filter is [47m:all[0m, then every form read is evaluated. If the filter is [47m:query[0m, then after a form is read it is printed to [47m[standard-co][0m and the user is asked if the form is to be evaluated or skipped. If the filter is a new name, then all forms are evaluated until that name is introduced, at which time [47m[ld][0m terminates normally. The [47m:all[0m filter is, of course, the normal one. [47m:Query[0m is useful if you want to replay selected [command]s in some file. The new name filter is used if you wish to replay all the [command]s in a file up through the introduction of the given one.") (ld-pre-eval-print (ld) "Determines whether [47m[ld][0m prints the forms to be [47meval[0m'd [47mLd-pre-eval-print[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-pre-eval-print state)[0m and the updater is [47m(set-ld-pre-eval-print val state)[0m. [47mLd-pre-eval-print[0m must be either [47mt[0m, [47mnil[0m, or [47m:never[0m. The initial value of [47mld-pre-eval-print[0m is [47mnil[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-pre-eval-print[0m is one of them. If this global variable is [47mt[0m, then before evaluating the form just read from [47m[standard-oi][0m, [47m[ld][0m prints the form to [47m[standard-co][0m. If the variable is [47mnil[0m, no such printing occurs. The [47mt[0m option is useful if you are reading from a file of [command]s and wish to assemble a complete script of the session in [47m[standard-co][0m. The value [47m:never[0m of [47mld-pre-eval-print[0m is rarely used. During the evaluation of [47m[encapsulate][0m and of [47m[certify-book][0m forms, subsidiary events are normally printed, even if [47mld-pre-eval-print[0m is [47mnil[0m. Thus for example, when the user submits an [47m[encapsulate][0m form, all subsidiary events are generally printed even in the default situation where [47mld-pre-eval-print[0m is [47mnil[0m. But occasionally one may want to suppress such printing. In that case, [47mld-pre-eval-print[0m should be set to [47m:never[0m. As described elsewhere (see [set-inhibit-output-lst]), another way to suppress such printing is to execute [47m(set-inhibit-output-lst lst)[0m where [47mlst[0m evaluates to a list including [47m'prove[0m and [47m'event[0m.") (ld-prompt (ld) "Determines the [prompt] printed by [47m[ld][0m [47mLd-prompt[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-prompt state)[0m and the updater is [47m(set-ld-prompt val state)[0m. [47mLd-prompt[0m must be either [47mnil[0m, [47mt[0m, or a function symbol that, when given an open output character channel and [state], prints the desired [prompt] to the channel and returns two values: the number of [characters] printed and the [state]. The initial value of [47mld-prompt[0m is [47mt[0m. The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from [47m[standard-oi][0m, evaluates them and prints the result to [47m[standard-co][0m. Note that the ACL2 top-level loop (see [47m[lp][0m) results from an invocation of [47m[ld][0m. However, there are various flags that control [47m[ld][0m's behavior and [47mld-prompt[0m is one of them. [47mLd-prompt[0m determines whether [47m[ld][0m prints a [prompt] before reading the next form from [47m[standard-oi][0m. If [47mld-prompt[0m is [47mnil[0m, [47m[ld][0m prints no [prompt]. If [47mld-prompt[0m is [47mt[0m, the default [prompt] printer is used, which displays information that includes the current package, default [defun-mode], [guard] checking status (on or off), and [47m[ld-skip-proofsp][0m; see [default-print-prompt]. If [47mld-prompt[0m is neither [47mnil[0m nor [47mt[0m, then it should be a function name, [47mfn[0m, such that [47m(fn channel state)[0m will print the desired [prompt] to [47mchannel[0m in [47m[state][0m and return [47m(mv col state)[0m, where [47mcol[0m is the number of [characters] output (on the last line output). You may define your own [prompt] printing function, [47mfn[0m, and install it with [47m(set-ld-prompt 'fn state)[0m. However, a trust tag must be active (see [defttag]) when you set [47mld-prompt[0m to other than [47mt[0m or [47mnil[0m (with two exceptions: the functions [47mbrr-prompt[0m and [47mwormhole-prompt[0m, which print the prompt in the [break-rewrite] loop and the general [wormhole] loop, respectively). If you supply an inappropriate [prompt] function, i.e., one that causes an error or does not return the correct number and type of results, the following odd [prompt] will be printed instead: Bad Prompt See :DOC ld-prompt> which will lead you to this message. You should either call [47m[ld][0m appropriately next time or assign an appropriate value to [47mld-prompt[0m.") (ld-query-control-alist (ld) "How to default answers to queries [47mLd-query-control-alist[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-query-control-alist state)[0m and the updater is [47m(set-ld-query-control-alist val state)[0m. Roughly speaking, [47mld-query-control-alist[0m is either [47mnil[0m (meaning all queries should be interactive), [47mt[0m (meaning all should default to the first accepted response), or an alist that pairs query ids to keyword responses. The alist may end in either [47mt[0m or [47mnil[0m, indicating the default value for all ids not listed explicitly. Formally, the [47mld-query-control-alist[0m must satisfy [47mld-query-control-alistp[0m. The initial [47mld-query-control-alist[0m is [47mnil[0m, which means all queries are handled interactively. When an ACL2 query is raised, a unique identifying symbol is printed in parentheses after the word ``Query''. This symbol, called the ``query id,'' can be used in conjunction with [47mld-query-control-alist[0m to prevent the query from being handled interactively. By ``handled interactively'' we mean that the query is printed to [47m[*standard-co*][0m and a response is read from [47m[*standard-oi*][0m. The alist can be used to obtain a ``default value'' for each query id. If this value is [47mnil[0m, then the query is handled interactively. In all other cases, the system handles the query without interaction (although text may be printed to [47m[standard-co][0m to make it appear that an interaction has occurred; see below). If the default value is [47mt[0m, the system acts as though the user responded to the query by typing the first response listed among the acceptable responses. If the default value is neither [47mnil[0m nor [47mt[0m, then it must be a keyword and one of the acceptable responses. In that case, the system acts as though the user responded with the given keyword. Next, we discuss how the [47mld-query-control-alist[0m assigns a default value to each query id. It assigns each id the first value paired with the id in the alist, or, if no such pair appears in the alist, it assigns the final [47m[cdr][0m of the alist as the value. Thus, [47mnil[0m assigns all ids [47mnil[0m. [47mT[0m assigns all ids [47mt[0m. [47m'((:filter . nil) (:sysdef . :n) . t)[0m assigns [47mnil[0m to the [47m:filter[0m query, [47m:n[0m to the [47m:sysdef[0m query, and [47mt[0m to all others. It remains only to discuss how the system prints text when the default value is not [47mnil[0m, i.e., when the query is handled without interaction. In fact, it is allowed to pair a query id with a singleton list containing a keyword, rather than a keyword, and this indicates that no printing is to be done. Thus for the example above, [47m:sysdef[0m queries would be handled noninteractively, with printing done to simulate the interaction. But if we change the example so that [47m:sysdef[0m is paired with [47m(:n)[0m, i.e., if [47mld-query-control-alist[0m is [47m'((:filter . nil) (:sysdef :n) . t)[0m, then no such printing would take place for [47msysdef[0m queries. Instead, the default value of [47m:n[0m would be assigned ``quietly''.") (ld-redefinition-action (ld) "To allow redefinition without [undoing] The present topic discusses redefining functions, macros, and constants, using a mechanism that may be convenient but also may be unsafe or unsound. See [undo] for what is often a better way to carry out redefinition. [47mLd-redefinition-action[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-redefinition-action state)[0m and the updater is [47m(set-ld-redefinition-action val state)[0m. [31;1mWARNING![0m If [47mld-redefinition-action[0m is non-[47mnil[0m then ACL2 is liable to be made unsafe or unsound, or behave in unexpected ways. For example, redefining a macro or inlined function, [47mf[0m, that is called in the body of another function, [47mg[0m, may not cause the new version of [47mf[0m to be called by [47mg[0m. In addition, for some Lisps, in particular GCL Version 2.7.0 or later, the return type [47mTP[0m inferred for the original definition of [47mf[0m might cause mishandling of the return value from [47mf[0m as [47mg[0m still expects that value's type to be [47mTP[0m. Redefinition should be viewed as a way to facilitate unsafe, but potentially useful, hacking. The keyword command [47m:[0m[47m[redef][0m will set [47mld-redefinition-action[0m to a convenient setting allowing unsound redefinition. See below. When [47mld-redefinition-action[0m is [47mnil[0m, redefinition is prohibited. In that case, an error message is printed upon any attempt to introduce a name that is already in use. There is one exception to this rule. It is permitted to redefine a function symbol in [47m:[0m[47m[program][0m mode to be a function symbol in [47m:[0m[47m[logic][0m mode provided the formals and body remain the same. This is the standard way a function ``comes into'' logical existence. Throughout the rest of this discussion we exclude from our meaning of ``redefinition'' the case in which a function in [47m:[0m[47m[program][0m mode is identically redefined in [47m:[0m[47m[logic][0m mode. At one time, ACL2 freely permitted the [signature]-preserving redefinition of [47m:[0m[47m[program][0m mode functions but it no longer does. See [redefining-programs]. When [47mld-redefinition-action[0m is non-[47mnil[0m, you are allowed to redefine a name that is already in use. [31;1mThe system may be rendered unsound[0m by such an act. It is important to understand how dangerous redefinition is. Suppose [47mfn[0m is a function symbol that is called from within some other function, say [47mg[0m. Suppose [47mfn[0m is redefined so that its arity changes. Then the definition of [47mg[0m is rendered syntactically ill-formed by the redefinition. This can be devastating since the entire ACL2 system assumes that terms in its database are well-formed. For example, if ACL2 executes [47mg[0m by running the corresponding function in raw Common Lisp the redefinition of [47mfn[0m may cause raw lisp to break in irreparable ways. As Lisp programmers we live with this all the time by following the simple rule: after changing the syntax of a function don't run any function that calls it via its old syntax. This rule also works in the context of the evaluation of ACL2 functions, but it is harder to follow in the context of ACL2 deductions, since it is hard to know whether the database contains a path leading the theorem prover from facts about one function to facts about another. Finally, of course, even if the database is still syntactically well-formed there is no assurance that all the rules stored in it are valid. For example, theorems proved about [47mg[0m survive the redefinition of [47mfn[0m but may have crucially depended on the properties of the old [47mfn[0m. In summary, we repeat the warning: [31;1mall bets are off if you set[0m [47mld-redefinition-action[0m to [31;1mnon[0m-[47mnil[0m. ACL2 provides some enforcement of the concern above, by disabling [47m[certify-book][0m if any [world]-changing [events] exist in the certification [world] that were executed with a non-[47mnil[0m value of [47m'ld-redefinition-action[0m. (This value is checked at the end of each top-level command, but the value does not change during evaluation of embedded event forms; see [embedded-event-form].) If at any point in a session you wish to see the list of all names that have been redefined, see [redefined-names]. That said, we'll give you enough rope to hang yourself. When [47mld-redefinition-action[0m is non-[47mnil[0m, it must be a pair, [47m(a . b)[0m. The value of [47ma[0m determines how the system interacts with you when a redefinition is submitted. The value of [47mb[0m allows you to specify how the property list of the redefined name is to be ``renewed'' before the redefinition. There are several dimensions to the space of possibilities controlled by part a: Do you want to be queried each time you redefine a name, so you can confirm your intention? (We sometimes make typing mistakes or simply forget we have used that name already.) Do you want to see a warning stating that the name has been redefined? Do you want ACL2 system functions given special protection from possible redefinition? Below are the choices for part a: [47m:query[0m --- every attempt to redefine a name will produce a query. The query will allow you to abort the redefinition or proceed. It will will also allow you to specify the part [47mb[0m for this redefinition. [47m:Query[0m is the recommended setting for users who wish to dabble in redefinition. [47m:warn[0m --- any user-defined function may be redefined but a post-redefinition warning is printed. The attempt to redefine a system name produces a query. If you are prototyping and testing a big system in ACL2 this is probably the desired setting for part [47ma[0m. [47m:doit[0m --- any user-defined function may be redefined silently (without query or warning) but when an attempt is made to redefine a system function, a query is made. This setting is recommended when you start making massive changes to your prototyped system (and tire of even the warning messages issued by [47m:warn[0m). In support of our own ACL2 systems [programming] there are two other settings. We suggest ordinary users not use them. [47m:warn![0m --- every attempt to redefine a name produces a warning but no query. Since ACL2 system functions can be redefined this way, this setting should be used by the only-slightly-less-than supremely confident ACL2 system hacker. [47m:doit![0m --- this setting allows any name to be redefined silently (without query or warnings). ACL2 system functions are fair game. This setting is reserved for the supremely confident ACL2 system hacker. (Actually, this setting is used when we are loading massively modified versions of the ACL2 source files.) Part [47mb[0m of [47mld-redefinition-action[0m tells the system how to ``renew'' the property list of the name being redefined. There are two choices: [47m:erase[0m --- erase all properties stored under the name, or [47m:overwrite[0m --- preserve existing properties and let the redefining overwrite them. It should be stressed that neither of these [47mb[0m settings is guaranteed to result in an entirely satisfactory state of affairs after the redefinition. Roughly speaking, [47m:erase[0m returns the property list of the name to the state it was in when the name was first introduced. Lemmas, type information, etc., stored under that name are lost. Is that what you wanted? Sometimes it is, as when the old definition is ``completely wrong.'' But other times the old definition was ``almost right'' in the sense that some of the work done with it is still (intended to be) valid. In that case, [47m:overwrite[0m might be the correct [47mb[0m setting. For example if [47mfn[0m was a function and is being re-[47m[defun][0m'd with the same [signature], then the properties stored by the new [47m[defun][0m should overwrite those stored by the old [47m[defun][0m but the properties stored by [47m[defthm][0ms will be preserved. In addition, neither setting will cause ACL2 to erase properties stored under other symbols! Thus, if [47mFOO[0m names a rewrite rule which rewrites a term beginning with the function symbol [47mBAR[0m and you then redefine [47mFOO[0m to rewrite a term beginning with the function symbol [47mBAZ[0m, then the old version of [47mFOO[0m is still available (because the rule itself was added to the rewrite rules for [47mBAR[0m, whose property list was not cleared by redefining [47mFOO[0m). The [47mb[0m setting is only used as the default action when no query is made. If you choose a setting for part a that produces a query then you will have the opportunity, for each redefinition, to specify whether the property list is to be erased or overwritten. The keyword command [47m:[0m[47m[redef][0m sets [47mld-redefinition-action[0m to the pair [47m(:query . :overwrite)[0m. Since the resulting query will give you the chance to specify [47m:erase[0m instead of [47m:overwrite[0m, this setting is quite convenient. But when you are engaged in heavy-duty prototyping, you may wish to use a setting such as [47m:warn[0m or even [47m:doit[0m. For that you will have to invoke a form such as: (set-ld-redefinition-action '(:doit . :overwrite) state) . [47m[Encapsulate][0m causes somewhat odd interaction with the user if redefinition occurs within the encapsulation because the [encapsulate]d event list is processed several times. For example, if the redefinition action causes a query and a non-local definition is actually a redefinition, then the query will be posed twice, once during each pass. C'est la vie. Finally, it should be stressed again that redefinition is dangerous because not all of the rules about a name are stored on the property list of the name. Thus, redefinition can render ill-formed terms stored elsewhere in the database or can preserve now-invalid rules. See [redundant-events], in particular the section ``Note About Unfortunate Redundancies,'' for more discussion of potential pitfalls of redefinition.") (ld-skip-proofsp (ld) "How carefully ACL2 processes your [command]s Examples: ACL2 !>(set-ld-skip-proofsp t state) T ACL2 !s>(set-ld-skip-proofsp nil state) NIL ACL2 !>(set-ld-skip-proofsp 'include-book state) INCLUDE-BOOK ACL2 !s> A global variable in the ACL2 [47m[state][0m, called [47m'ld-skip-proofsp[0m, determines the thoroughness with which ACL2 processes your [command]s. This variable may take on one of three values: [47mt[0m, [47mnil[0m or [47m'[0m[47m[include-book][0m. When [47mld-skip-proofsp[0m is non-[47mnil[0m, the system skips all proofs, which of course can render the system unsound. The form [47m(set-ld-skip-proofsp flg state)[0m is the general-purpose way of setting [47mld-skip-proofsp[0m. This global variable is an ``[47m[ld][0m special,'' which is to say, you may call [47m[ld][0m in such a way as to ``bind'' this variable for the dynamic extent of the [47m[ld][0m. When [47mld-skip-proofsp[0m is non-[47mnil[0m, the default [prompt] displays the character [47ms[0m. Thus, the [prompt] ACL2 !s> means that the default [defun-mode] is [47m:[0m[47m[logic][0m (otherwise the character [47mp[0m, for [47m:[0m[47m[program][0m, would also be printed; see [default-print-prompt]) but ``proofs are being skipped.'' Observe that there are two legal non-[47mnil[0m values, [47mt[0m and [47m'[0m[47m[include-book][0m. When [47mld-skip-proofsp[0m is [47mt[0m, ACL2 skips all proof obligations but otherwise performs all other required analysis of input [events]. When [47mld-skip-proofsp[0m is [47m'[0m[47m[include-book][0m, ACL2 skips not only proof obligations but all analysis except that required to compute the effect of successfully executed [events]. To explain the distinction, let us consider one particular event, say a [47m[defun][0m. Very roughly speaking, a [47m[defun][0m event normally involves a check of the syntactic well-formedness of the submitted definition, the generation and proof of the termination conditions, and the computation and storage of various rules such as a [47m:[0m[47m[definition][0m rule and some [47m:[0m[47m[type-prescription][0m rules. By ``normally'' above we mean when [47mld-skip-proofsp[0m is [47mnil[0m. How does a [47m[defun][0m behave when [47mld-skip-proofsp[0m is non-[47mnil[0m? If [47mld-skip-proofsp[0m is [47mt[0m, then [47m[defun][0m performs the syntactic well-formedness checks and computes and stores the various rules, but it does not actually carry out the termination proofs. If [47mld-skip-proofsp[0m is [47m'[0m[47m[include-book][0m, [47m[defun][0m does not do the syntactic well-formedness check nor does it carry out the termination proof. Instead, it merely computes and stores the rules under the assumption that the checks and proofs would all succeed. Observe that a setting of [47m'[0m[47m[include-book][0m is ``stronger'' than a setting of [47mt[0m in the sense that [47m'[0m[47m[include-book][0m causes [47m[defun][0m to assume even more about the admissibility of the event than [47mt[0m does. As one might infer from the choice of name, the [47m[include-book][0m event sets [47mld-skip-proofsp[0m to [47m'[0m[47m[include-book][0m when processing the [events] in a book being loaded. Thus, [47m[include-book][0m does the minimal work necessary to carry out the effects of every event in the book. The syntactic checks and proof obligations were, presumably, successfully carried out when the book was certified. A non-[47mnil[0m value for [47mld-skip-proofsp[0m also affects the system's output messages. Event summaries (the paragraphs that begin ``[Summary]'' and display the event forms, rules used, etc.) are not printed when [47mld-skip-proofsp[0m is non-[47mnil[0m. Warnings and observations are printed when [47mld-skip-proofsp[0m is [47mt[0m but are not printed when it is [47m'[0m[47m[include-book][0m. Intuitively, [47mld-skip-proofsp[0m [47mt[0m means skip just the proofs and otherwise do all the work normally required for an event; while [47mld-skip-proofsp[0m [47m'[0m[47m[include-book][0m is ``stronger'' and means do as little as possible to process [events]. In accordance with this intuition, [47m[local][0m [events] are processed when [47mld-skip-proofsp[0m is [47mt[0m but are skipped when [47mld-skip-proofsp[0m is [47m'[0m[47m[include-book][0m. The ACL2 system itself uses only two settings, [47mnil[0m and [47m'[0m[47m[include-book][0m, the latter being used only when executing the [events] inside of a book being included. The [47mld-skip-proofsp[0m setting of [47mt[0m is provided as a convenience to the user. For example, suppose one has a file of [events]. By loading it with [47m[ld][0m with [47mld-skip-proofsp[0m set to [47mt[0m, the [events] can all be checked for syntactic correctness and assumed without proof. This is a convenient way to recover a state lost by a system crash or to experiment with a modification of an [events] file. The foregoing discussion is actually based on a lie. [47mld-skip-proofsp[0m is allowed two other values, [47m'initialize-acl2[0m and [47m'include-book-with-locals[0m. The first causes behavior similar to [47mt[0m but skips [47m[local][0m [events] and avoids some error checks that would otherwise prevent ACL2 from properly booting. The second is identical to [47m'[0m[47m[include-book][0m but also executes [47m[local][0m [events]. These additional values are not intended for use by the user, but no barriers to their use have been erected. User-defined tools may temporarily modify the global setting of [47mld-skip-proofsp[0m; for example, see [remove-hyps]. We close by reminding the user that ACL2 is potentially unsound if [47mld-skip-proofsp[0m is set by the user. Indeed, direct setting of [47mld-skip-proofsp[0m is illegal within a book (except during [47m[make-event][0m expansion). We provide access to it simply to allow experimentation and rapid reconstruction of lost or modified logical [world]s.") (ld-user-stobjs-modified-warning (pointers) "See [user-stobjs-modified-warnings].") (ld-verbose (ld) "Determines whether [47m[ld][0m prints ``ACL2 Loading ...'' [47mLd-verbose[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(ld-verbose state)[0m and the updater is [47m(set-ld-verbose val state)[0m. [47mLd-verbose[0m must be [47mt[0m, [47mnil[0m or a string or [47m[consp][0m suitable for [47m[fmt][0m printing via the [47m~@[0m command. The initial value of [47mld-verbose[0m is a [47m[fmt][0m message that prints the system books directory. Note: [47mLd-verbose[0m has no effect on proofs. See [set-gag-mode] and see [set-inhibit-output-lst] for how to control the size of proof output. Before processing the forms in [47m[standard-oi][0m, [47m[ld][0m may print a header. The printing of this header is controlled by [47mld-verbose[0m. If [47mld-verbose[0m is [47mnil[0m, no header is printed. If it is [47mt[0m, [47m[ld][0m prints the message ACL2 loading <file> where [47m<file>[0m is the input channel supplied to [47m[ld][0m. A similar message is printed when [47m[ld][0m completes. If [47mld-verbose[0m is neither [47mt[0m nor [47mnil[0m then it is presumably a header and is printed with the [47m~@[0m [47m[fmt][0m directive before [47m[ld][0m begins to read and process forms. In this case the [47m~@[0m [47m[fmt][0m directive is interpreted in an environment in which [47m#\b[0m is the system books directory, [47m#\v[0m is the ACL2 version string, [47m#\l[0m is the level of the current recursion in [47m[ld][0m and/or [47m[wormhole][0m, and [47m#\c[0m is the connected book directory [47m(cbd)[0m.") (legal-constantp (pointers) "See [system-utilities].") (legal-variablep (pointers) "See [system-utilities].") (lemma-instance (hints functional-instantiation) "An object denoting an instance of a theorem Lemma instances are the objects one provides via [47m:use[0m and [47m:by[0m [hints] to bring to the theorem prover's attention some previously proved or easily provable fact. A typical use of the [47m:use[0m hint is given below. The value specified is a list of five lemma instances. :use (reverse-reverse (:type-prescription app) (:instance assoc-of-app (x a) (y b) (z c)) (:functional-instance p-f (p consp) (f flatten)) (:instance (:theorem (equal x x)) (x (flatten a)))) Observe that an event name can be a lemma instance. The [47m:use[0m hint allows a single lemma instance to be provided in lieu of a list, as in: :use reverse-reverse or :use (:instance assoc-of-app (x a) (y b) (z c)) A lemma instance denotes a formula which is either known to be a theorem or which must be proved to be a theorem before it can be used. To use a lemma instance in a particular subgoal, the theorem prover adds the formula as a hypothesis to the subgoal before the normal theorem proving heuristics are applied. A lemma instance, or [47mlmi[0m, is of one of the following forms: (1) [47mname[0m, where [47mname[0m names a previously proved theorem, axiom, or definition and denotes the formula (theorem) of that name. (2) [47mrune[0m, where [47mrune[0m is a [rune] (see [rune]) denoting the [47m:[0m[47m[corollary][0m justifying the rule named by the [rune]. (3) [47m(:theorem term)[0m, where [47mterm[0m is any term alleged to be a theorem. Such a lemma instance denotes the formula [47mterm[0m. But before using such a lemma instance the system will undertake to prove [47mterm[0m. (4) [47m(:instance lmi (v1 t1) ... (vn tn))[0m, where [47mlmi[0m is recursively a lemma instance, the [47mvi[0m's are distinct variables, and the [47mti[0m's are terms. Such a lemma instance denotes the formula obtained by instantiating the formula [47mF[0m denoted by [47mlmi[0m, normally by replacing each [47mvi[0m by [47mti[0m in [47mF[0m and requiring that each [47mvi[0m must be bound in [47mF[0m. There are two exceptions. If the keyword [47m:extra-bindings-ok[0m is inserted immediately after the lemma instance in order to remove that requirement, as follows, then that requirement is ignored: [47m(:instance lmi :extra-bindings-ok (v1 t1) ... (vn tn))[0m. Otherwise there is the following exception pertaining to [packages]: if one or more variables [47mvi[0m do not occur in [47mF[0m, but for each such [47mvi[0m exactly one variable [47mv[0m with the same [47m[symbol-name][0m as [47mvi[0m occurs in [47mF[0m and no other [47mvj[0m with the same [47msymbol-name[0m as [47mv[0m is bound in the substitution, then the pair [47m(vi ti)[0m is replaced by the pair [47m(v ti)[0m in the substitution. (5) [47m(:functional-instance lmi (f1 g1) ... (fn gn))[0m, where [47mlmi[0m is recursively a lemma instance and each [47mfi[0m is an ``instantiable'' function symbol of arity [47mni[0m and [47mgi[0m is a function symbol, a macro alias for a function symbol [47mgi'[0m (see [macro-aliases-table]) in which case we treat [47mgi[0m as [47mgi'[0m, or a pseudo-lambda expression of arity [47mni[0m. An instantiable function symbol is any defined or constrained function symbol except the primitives [47m[not][0m, [47m[member][0m, [47m[implies][0m, and [47m[o<][0m, and a few others, as listed by the constant [47m*non-instantiable-primitives*[0m. These are built-in in such a way that we cannot recover the [constraint]s on them. (Special case: a function introduced in the [47m:partial-theory[0m of a dependent clause-processor is not instantiable; see [define-trusted-clause-processor].) A pseudo-lambda expression is an expression of the form [47m(lambda (v1 ... vn) body)[0m where the [47mvi[0m are distinct variable symbols and [47mbody[0m is any term. No [3ma priori[0m relation is imposed between the [47mvi[0m and the variables of [47mbody[0m, i.e., [47mbody[0m may ignore some [47mvi[0m's and may contain ``free'' variables. However, we do not permit [47mv[0m to occur freely in [47mbody[0m if the functional substitution is to be applied to any formula ([47mlmi[0m or the [constraint]s to be satisfied) in a way that inserts [47mv[0m into the scope of a binding of [47mv[0m by [47m[let][0m or [47m[mv-let][0m (or, [47m[lambda][0m). If you happen to violate this restriction, an informative error message will be printed. That message will list for you the potentially illegal choices for [47mv[0m in the context in which the functional substitution is offered. A [47m:functional-instance[0m lemma instance denotes the formula obtained by functionally instantiating the formula denoted by [47mlmi[0m, replacing [47mfi[0m by [47mgi[0m. However, before such a lemma instance can be used, the system will generate proof obligations arising from the replacement of the [47mfi[0m's by the [47mgi[0m's in constraints that ``support'' the lemma to be functionally instantiated; see [constraint]. One might expect that if the same instantiated constraint were generated on behalf of several events, then each of those instances would have to be proved. However, for the sake of efficiency, ACL2 stores the fact that such an instantiated constraint has been proved, unless the proof was done inside an [47m[encapsulate][0m event that either has a non-empty [signature] list or is ``empty'' (stores no events), and then avoids re-proving that constraint in future [events]. See [functional-instantiation-example] for an example of the use of [47m:functional-instance[0m (so-called ``functional instantiation''). See [47m[set-constraint-tracking][0m for help figuring out where subgoals generated by [47m:functional-instance[0m hints came from. Note that ACL2(r) (see [real]) imposes additional requirements for functional instantiation. See [functional-instantiation-in-ACL2r]. (6) [47m(:termination-theorem name)[0m or [47m(:termination-theorem! name)[0m, where [47mname[0m is a function symbol in [logic] mode. Such a lemma instance denotes the termination theorem previously proved for [47mname[0m, possibly modified as discussed in the next paragraph. If no such theorem exists --- for example, if the definition of [47mname[0m is not recursive --- then the lemma instance is illegal in the case of [47m:termination-theorem[0m, but denotes [47mT[0m in the case of [47m:termination-theorem![0m. If [47mname[0m is defined as part of a mutually-recursive clique of definitions (see [mutual-recursion]), then the lemma instance refers to the termination theorem proved for the entire clique. See [termination-theorem-example] and see [tthm]. Consider the application of [47m:termination-theorem f[0m while attempting to prove the termination theorem for a function, [47mg[0m. For now suppose that neither [47mf[0m nor [47mg[0m is defined using [47m[mutual-recursion][0m. Suppose that [47mf[0m and [47mg[0m have the same number of formal parameters. Then every call of [47mf[0m in the termination theorem for [47mf[0m will be replaced by a call of [47mg[0m on the same arguments (except, recursively, [47mf[0m is also replaced by [47mg[0m in those arguments). The analogous replacement also takes place for mutually recursive definitions, as follows. In the case that [47mf[0m was introduced with [47m(mutual-recursion (defun f1 ...) ... (defun fk ...))[0m and similarly [47mg[0m is being introduced with [47m(mutual-recursion (defun g1 ...) ... (defun gk ...))[0m, where for each [47mi[0m from [47m1[0m to [47mk[0m the number of formal parameters is the same for [47mfi[0m and [47mgi[0m, then the functional substitution [47m((f1 . g1) ... (fk . gk))[0m is applied to the termination theorem for the [47mfi[0m. (Logical justification in a nutshell: the termination proof for the [47mfi[0m took place before adding their definitional equations to the current theory, where the [47mfi[0m were thus stubs with no axioms.) Note that unlike normal [functional-instantiation], here there is no proof obligation. However, the restriction applies from (5) above that the functions [47mfi[0m are instantiable; when that fails, then the replacement of each [47mfi[0m by [47mgi[0m will not take place. Finally, note that an optional second argument to [47m:termination-theorem[0m specifies an explicit functional substitution [47m((f1 g1) ... (fn gn))[0m, which is to be applied to the termination theorem for [47mf[0m. If that argument is supplied, then there will be no attempt to derive a functional substitution automatically, as described in the preceding paragraph. (7) [47m(:guard-theorem name)[0m or [47m(:guard-theorem name simplify)[0m, where [47mname[0m is a [guard]-verified function symbol (hence, in particular, is in [logic] mode). Such a lemma instance denotes the guard theorem previously proved for [47mname[0m, where by default [47msimplify[0m is [47m:limited[0m, which enables certain simplifications as documented elsewhere; see [gthm]. Otherwise [47msimplify[0m should be [47mnil[0m, to avoid all such simplification. If [47mname[0m is defined as part of a mutually-recursive clique of definitions (see [mutual-recursion]), then the lemma instance refers to the guard theorem proved for the entire clique. See [guard-theorem-example] and see [gthm]. Obscure case for [definition]s. If the lemma instance refers to a [47m:definition[0m [rune], then it refers to the [47m[corollary][0m formula of that rune, which can be a normalized (simplified) form of the definition body; see [normalize]. However, if the hint is a [47m:by[0m hint and the lemma instance is based on a name (i.e., a symbol), rather than a rune, then the formula is the original formula of the event, as shown by [47m:[0m[47m[pe][0m, rather than the normalized version, as shown by [47m:[0m[47m[pf][0m. This is as one would expect: If you supply the name of an event, you expect it to refer to the original event. For [47m:use[0m hints we use the simplified ([normalize]d) form instead, which is reasonable since one would expect simplification during the proof that re-traces the normalization done at the time the rule was created. We conclude with remarks on (6) and (7). The termination theorem actually used is an unsimplified version of what was originally proved for the indicated function; the guard theorem is, by default, partially simplified. That is: while in general, the termination theorem is simplified before being given to the prover, nevertheless the unsimplified theorem is what is actually used for [47m:termination-theorem[0m lemma instances; for [47m:guard-theorem[0m, some simplification is done that is independent of the theory, by using a form of ``subsumption'' to eliminate redundancy and by deleting tautologies as well as instances of [built-in-clause] rules that come with ACL2. Also see [guard-formula-utilities] and [guard-simplification]. Moreover, the [47m:[0m[47m[measure-debug][0m and [47m:[0m[47m[guard-debug][0m keywords for [47m[xargs][0m are ignored when generating the termination or guard theorem. You can see the termination or guard theorem for an existing function symbol [47mFN[0m by evaluating the form [47m(termination-theorem 'FN (w state))[0m or [47m(guard-theorem 'FN simplify guard-debug (w state) state)[0m, respectively. In the former case, failure is indicated by a result of the form [47m(FAILED . msg)[0m, where [47mmsg[0m is a message suitable for [47m[fmt][0m; see [msg]. Also see [make-termination-theorem]. Why do we avoid simplification for [47m:termination-theorem[0m, as described in the preceding paragraph? The reason is that it could in principle strengthen the theorem, which is sound when admitting the original function but not for lemma instances. Future work might try to allow simplification at lemma-instance time, by ensuring that simplification never strengthens the theorem. Alternatively, simplification might be checked for each usage to be equivalence-preserving by defining a suitable macro based on [47m[make-event][0m. For now, by avoiding simplification we guarantee that the theorem we are using is truly a theorem. The theorem being used might not be exactly the theorem originally proved, for example because of the use of [case-split-limitations], which depends on the current logical [world]; but we expect the two theorems to be logically equivalent. Subtopics [Guard-theorem] Use a previously-proved [guard] theorem [Guard-theorem-example] How to use a previously-proved [guard] theorem [Termination-theorem] Use a (functional instance of a) previously-proved measure theorem [Termination-theorem-example] How to use a previously-proved measure theorem") (len (lists acl2-built-ins) "Length of a list [47mLen[0m returns the length of a list. A Common Lisp function that is appropriate for both strings and proper lists is [47mlength[0m; see [length]. The guard for [47mlen[0m is [47mt[0m. (Low-level implementation note. ACL2 provides a highly-optimized implementation of [47mlen[0m, which is tail-recursive and fixnum-aware, that differs from its simple ACL2 definition.) [31;1mFunction: [0m<len> (defun len (x) (declare (xargs :guard t)) (if (consp x) (+ 1 (len (cdr x))) 0))") (length (lists strings acl2-built-ins) "Length of a string or proper list [47mLength[0m is the function for determining the length of a sequence. In ACL2, the argument is required to be either a [47m[true-listp][0m or a string. For a similar function that is logically defined to be equal to zero on any atom, including any string, see [47m[len][0m. [47mLength[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<length> (defun length (x) (declare (xargs :guard (if (true-listp x) t (stringp x)))) (if (stringp x) (len (coerce x 'list)) (len x)))") (let (basics acl2-built-ins) "Binding of lexically scoped (local) variables Introduction Example (let ((x (* x x)) (y (* 2 x))) (list x y)) If the form above is executed in an environment in which [47mx[0m has the value [47m-2[0m, then the result is [47m'(4 -4)[0m. [47mLet[0m expressions bind variables so that their ``local'' values, the values they have when the ``body'' of the [47mlet[0m is evaluated, are possibly different than their ``global'' values, the values they have in the context in which the [47mlet[0m expression appears. In the [47mlet[0m expression above, the local variables bound by the [47mlet[0m are [47mx[0m and [47my[0m. They are locally bound to the values delivered by the two forms [47m(* x x)[0m and [47m(* 2 x)[0m, respectively, that appear in the ``bindings'' of the [47mlet[0m. The body of the [47mlet[0m is [47m(list x y)[0m. Suppose that the [47mlet[0m expression above occurs in a context in which [47mx[0m has the value [47m-2[0m. (The global value of [47my[0m is irrelevant to this example.) For example, one might imagine that the [47mlet[0m form above occurs as the body of some function, [47mfn[0m, with the formal parameter [47mx[0m and we are evaluating [47m(fn -2)[0m. To evaluate the [47mlet[0m above in a context in which [47mx[0m is [47m-2[0m, we first evaluate the two forms specifying the local values of the variables. Thus, [47m(* x x)[0m is evaluated and produces [47m4[0m (because [47mx[0m is [47m-2[0m) and [47m(* 2 x)[0m is evaluated and produces [47m-4[0m (because [47mx[0m is [47m-2[0m). Then [47mx[0m and [47my[0m are bound to these values and the body of the [47mlet[0m is evaluated. Thus, when the body, [47m(list x y)[0m is evaluated, [47mx[0m is [47m4[0m and [47my[0m is [47m-4[0m. Thus, the body produces [47m'(4 -4)[0m. Note that the binding of [47my[0m, which is written after the binding of [47mx[0m and which mentions [47mx[0m, nevertheless uses the global value of [47mx[0m, not the new local value. That is, the local variables of the [47mlet[0m are bound ``in parallel'' rather than ``sequentially.'' In contrast, if the example [47mlet*[0m form: (let* ((x (* x x)) (y (* 2 x))) (list x y)) is evaluated when the global value of [47mx[0m is [47m-2[0m, then the result is [47m'(4 8)[0m, because the local value of [47my[0m is computed after [47mx[0m has been bound to [47m4[0m. [47m[Let*][0m binds its local variables ``sequentially.'' General [47mlet[0m forms (let ((var1 term1) ... (varn termn)) body) and (let ((var1 term1) ... (varn termn)) (declare ...) ... (declare ...) body) where the [47mvari[0m are distinct variables, the [47mtermi[0m are terms involving only variables bound in the environment containing the [47mlet[0m, and [47mbody[0m is a term involving only the [47mvari[0m plus the variables bound in the environment containing the [47mlet[0m. Each [47mvari[0m must be used in [47mbody[0m or else [declare]d ignored. In ACL2 the only [47m[declare][0m forms allowed for a [47mlet[0m form are [47mignore[0m, [47mignorable[0m, and [47mtype[0m. See [declare]. A [47mlet[0m form is evaluated by first evaluating each of the [47mtermi[0m, obtaining for each a [47mvali[0m. Then, each [47mvari[0m is bound to the corresponding [47mvali[0m and [47mbody[0m is evaluated. Actually, [47mlet[0m forms are just abbreviations for certain uses of [47mlambda[0m notation. In particular (let ((var1 term1) ... (varn termn)) (declare ...) body) is equivalent to ((lambda (var1 ... varn) (declare ...) body) term1 ... termn). [47m[Let*][0m forms are used when it is desired to bind the [47mvari[0m sequentially, i.e., when the local values of preceding [47mvarj[0m are to be used in the computation of the local value for [47mvari[0m. General [47mlet*[0m forms: (let* ((var1 term1) ... (varn termn)) body) and (let* ((var1 term1) ... (varn termn)) (declare (ignore x1 ... xm)) body) where the [47mvari[0m are variables (not necessarily distinct), the [47mtermi[0m are terms involving only variables bound in the environment containing the [47m[let*][0m and those [47mvarj[0m such that [47mj<i[0m, and [47mbody[0m is a term involving only the [47mvari[0m plus the variables bound in the environment containing the [47m[let*][0m. Each [47mvari[0m must be used either in some subsequent [47mtermj[0m or in [47mbody[0m, except that in the second form above we make an exception when [47mvari[0m is among the [47mxk[0m, in which case [47mvari[0m must not be thus used. Note that [47m[let*][0m does not permit the inclusion of any [47m[declare][0m forms other than one as shown above. In the second general form above, every [47mxk[0m must be among the [47mvari[0m, and furthermore, [47mxk[0m may not equal [47mvari[0m and [47mvarj[0m for distinct [47mi[0m, [47mj[0m. The first [47m[let*][0m above is equivalent to (let ((var1 term1)) ... (let ((varn termn)) body)...) Thus, the [47mtermi[0m are evaluated successively and after each evaluation the corresponding [47mvari[0m is bound to the value of [47mtermi[0m. The second [47m[let*][0m is similarly expanded, except that each for each [47mvari[0m that is among the [47m(x1 ... xm)[0m, the form [47m(declare (ignore vari))[0m is inserted immediately after [47m((vari termi))[0m. Each [47m(vari termi)[0m pair in a [47mlet[0m or [47m[let*][0m form is called a ``binding'' of [47mvari[0m and the [47mvari[0m are called the ``local variables'' of the [47mlet[0m or [47m[let*][0m. The common use of [47mlet[0m and [47m[let*][0m is to save the values of certain expressions (the [47mtermi[0m) so that they may be referenced several times in the body without suggesting their recomputation. [47mLet[0m is part of Common Lisp. See any Common Lisp documentation for more information.") (let* (basics acl2-built-ins) "Binding of lexically scoped (local) variables Examples (let* ((x (* x x)) (y (* 2 x))) (list x y)) (let* ((x (* x x)) (y (* 2 x)) (x (* x y)) (a (* x x))) (declare (ignore a)) (list x y)) If the forms above are executed in an environment in which [47mx[0m has the value [47m-2[0m, then the respective results are [47m'(4 8)[0m and [47m'(32 8)[0m. See [let] for a discussion of both [47m[let][0m and [47mlet*[0m, or read on for a briefer discussion. The difference between [47m[let][0m and [47mlet*[0m is that the former binds its local variables in parallel while the latter binds them sequentially. Thus, in [47mlet*[0m, the term evaluated to produce the local value of one of the locally bound variables is permitted to reference any locally bound variable occurring earlier in the binding list and the value so obtained is the newly computed local value of that variable. See [let]. In ACL2 the only [47m[declare][0m forms allowed for a [47mlet*[0m form are [47mignore[0m, [47mignorable[0m, and [47mtype[0m. See [declare]. Moreover, no variable declared [47mignore[0md or [47mignorable[0m may be bound more than once. A variable with a type declaration may be bound more than once, in which case the type declaration is treated by ACL2 as applying to each binding occurrence of that variable. It seems unclear from the Common Lisp spec whether the underlying Lisp implementation is expected to apply such a declaration to more than one binding occurrence, however, so performance in such cases may depend on the underlying Lisp. [47mLet*[0m is a Common Lisp macro. See any Common Lisp documentation for more information.") (let-mbe (pointers) "See [equality-variants-details].") (lex-fix (pointers) "See [l<].") (lexorder (<< acl2-built-ins) "Total order on ACL2 objects [47mLexorder[0m is a non-strict total order, a ``less than or equal,'' on ACL2 objects. Also see [alphorder], the restriction of [47mlexorder[0m to atoms; the notion of ``non-strict total order'' is defined there. [47mLexorder[0m has a guard of [47mt[0m. For [47mlexorder[0m, an [atom] and a [cons] are ordered so that the [atom] comes first, and two [cons]es are ordered so that the one with the recursively smaller [47m[car][0m comes first, with the [47m[cdr][0ms being compared only if the [47m[car][0ms are equal. [47mLexorder[0m compares two atoms by using [47m[alphorder][0m. [31;1mFunction: [0m<lexorder> (defun lexorder (x y) (declare (xargs :guard t)) (cond ((atom x) (cond ((atom y) (alphorder x y)) (t t))) ((atom y) nil) ((equal (car x) (car y)) (lexorder (cdr x) (cdr y))) (t (lexorder (car x) (car y)))))") (lexp (pointers) "See [l<].") (linear (rule-classes) "Make some arithmetic inequality rules See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Example: (defthm length-member-leq-length If inequality reasoning begins to (implies (and (eqlablep e) consider how (length (member a b)) (true-listp x)) compares to any other term, add to (<= (length (member e x)) the set of known inequalities the fact (length x))) that it is no larger than (length b), :rule-classes :linear) provided (eqlablep a) and (true-listp b) rewrite to t. General Form: (and ... (implies (and ...hi...) (implies (and ...hk...) (and ... (rel lhs rhs) ...))) ...) We process the [47m:[0m[47m[corollary][0m formula of one [47m:linear[0m rule class object to create one or more [47m:linear[0m rules. The first step is to flatten the [47m[and][0m and [47m[implies][0m structure of the formula, transforming it into a conjunction of formulas, each of the form (implies (and h1 ... hn) (rel lhs rhs)) where no hypothesis is a conjunction and the term [47m(rel lhs rhs)[0m is a call of one of the inequality relations [47m[<][0m, [47m[<=][0m, [47m[>][0m, or [47m[>=][0m; the negation of such a call; a call of [47m[=][0m or [47m[equal][0m; or a negated call of [47m[/=][0m. Note that we refer to all of these terms as ``inequalities'' below, even the equalities. If necessary, the hypothesis of such a conjunct may be vacuous. We create a [47m:linear[0m rule for each such conjunct, if possible, and otherwise cause an error. To create a [47m:linear[0m rule from a term (i.e., from a single such conjunct), we apply the following sequence of transformations (as well as macroexpansion, which removes calls of [47m[<=][0m, [47m[>][0m, and [47m[>=][0m). 1. Remove [guard-holders] such as [47m[prog2$][0m from the term to obtain [47m(implies hyp concl)[0m, where [47mhyp[0m is [47mt[0m in the case of an unconditional rule. 2. If [47mconcl[0m is [47m(not (not concl2))[0m, replace [47mconcl[0m by [47mconcl2[0m. 3. For the resulting [47mconcl[0m, replace [47m[=][0m and [47m[/=][0m by [47m[equal][0m and [47mnot equal[0m, respectively. Each rule has one or more ``trigger terms'' which may be specified by the user using the [47m:trigger-terms[0m field of the rule class or which may be defaulted to values chosen by the system. We discuss the determination of trigger terms after discussing how linear rules are used. [47m:Linear[0m rules are used by an arithmetic decision procedure during rewriting. See [linear-arithmetic] and see [non-linear-arithmetic]. Here we assume that the reader is familiar with the material described in [47m[linear-arithmetic][0m. Recall that we eliminate the unknowns of an inequality in term-order, largest unknowns first. (See [term-order].) In order to facilitate this strategy, we store the inequalities in ``linear pots''. For purposes of the present discussion, let us say that an inequality is ``about'' its largest unknown. Then, all of the inequalities about a particular unknown are stored in the same linear pot, and the pot is said to be ``labeled'' with that unknown. This storage layout groups all of the inequalities which are potential candidates for cancellation with each other into one place. It is also key to the efficient operation of [47m:linear[0m rules. If the arithmetic decision procedure has stabilized and not yielded a contradiction, we scan through the list of linear pots examining each label as we go. If the trigger term of some [47m:linear[0m rule can be instantiated to match the label, we so instantiate that rule and attempt to relieve the hypotheses with general-purpose rewriting. If we are successful, we rewrite each of the two terms being compared by the conclusion (which is an equality or inequality), under the substitution produced by the rule's instantiation. We then add the resulting equality or inequality to our set of inequalities. This may let cancellation continue. Note: Problems may arise if you explicitly store a linear lemma under a trigger term that, when instantiated, is not the largest unknown in the instantiated concluding inequality. Suppose for example you store the linear rule [47m(<= (fn i j) (/ i (* j j)))[0m under the trigger term [47m(fn i j)[0m. Then when the system ``needs'' an inequality about [47m(fn a b)[0m, (i.e., because [47m(fn a b)[0m is the label of some linear pot, and hence the largest unknown in some inequality), it will appeal to the rule and deduce [47m(<= (fn a b) (/ a (* b b)))[0m. However, the largest unknown in this inequality is [47m(/ a (* b b))[0m and hence it will be stored in a linear pot labeled with [47m(/ a (* b b))[0m. The original, triggering inequality which is in a pot about [47m(fn a b)[0m will therefore not be canceled against the new one. It is generally best to specify as a trigger term one of the ``maximal'' terms of the polynomial, as described below. We now describe how the trigger terms are determined. Most of the time, the trigger terms are not specified by the user and are instead selected by the system. However, the user may specify the terms by including an explicit [47m:trigger-terms[0m field in the rule class, e.g., General Form of a Linear Rule Class: (:LINEAR :COROLLARY formula :TRIGGER-TERMS (term1 ... termk)) Each [47mtermi[0m must be a term and must not be a variable, quoted constant, lambda application, [47mlet-expression[0m or [47mif-expression[0m. In addition, each [47mtermi[0m must be such that if all the variables in the term are instantiated and then the hypotheses of the corollary formula are relieved (possibly instantiating additional free variables), then all the variables in the concluding inequality are instantiated. We generate a linear rule for each conjunctive branch through the corollary and store each rule under each of the specified triggers. Thus, if the corollary formula contains several conjuncts, the variable restrictions on the [47mtermi[0m must hold for each conjunct. If [47m:trigger-terms[0m is omitted the system computes a set of trigger terms. Each conjunct of the corollary formula may be given a unique set of triggers depending on the variables that occur in the conjunct and the addends that occur in the concluding inequality. In particular, the trigger terms for a conjunct is the list of all ``maximal addends'' in the concluding inequality after replacing, where possible based on the [current-theory], ground subterms (those that have no free variables) with their values. The ``addends'' of [47m(+ x y)[0m and [47m(- x y)[0m are the union of the addends of [47mx[0m and [47my[0m. The addends of [47m(- x)[0m and [47m(* n x)[0m, where [47mn[0m is a rational constant, is just [47m{x}[0m. The addends of an inequality are the union of the addends of the left- and right-hand sides. The addends of any other term, [47mx[0m, is [47m{x}[0m. A term is maximal for a conjunct [47m(implies hyps concl)[0m of the corollary if (a) the term is a non-variable, non-quote, non-lambda application, non-[47m[let][0m and non-[47m[if][0m expression, (b) the term contains enough variables so that when they are instantiated and the hypotheses are relieved (which may bind some free variables; see [free-variables]) then all the variables in [47mconcl[0m are instantiated, and (c) no other addend is always ``bigger'' than the term, in the technical sense described below. Note that the notion of ``enough variables'' in (b) is affected by hypotheses that are calls of [47mbind-free[0m; see [bind-free]. The technical notion referenced above depends on the notion of [3mfn-count[0m, the number of function symbols in a term, and [3mpseudo-fn-count[0m, which is essentially the number of function symbols implicit in a constant (see [term-order], specifically the discussion of ``pseudo-function application count'' at the end). We say [47mterm1[0m is always bigger than [47mterm2[0m if all instances of [47mterm1[0m have a larger fn-count (actually lexicographic order of fn-count and pseudo-fn-count) than the corresponding instances of [47mterm2[0m. This is equivalent to saying that the fn-count of [47mterm1[0m is larger than that of [47mterm2[0m (by ``fn-count'' here we mean the lexicographic order of fn-count and pseudo-fn-count) and the variable bag for [47mterm2[0m is a subbag of that for [47mterm1[0m. For example, [47m(/ a (* b b))[0m is always bigger than [47m(fn a b)[0m because the first has two function applications and [47m{a b}[0m is a subbag of [47m{a b b}[0m, but [47m(/ a (* b b))[0m is not always bigger than [47m(fn a x)[0m. We conclude by noting that linear rules are useless when all of the polynomial's terms are provably non-numeric. If ACL2 determines that to be the case for one or more of the conclusions, then it causes an error, except when [47m:trigger-terms[0m is supplied explicitly by the user. Subtopics [Backchain-limit] Limiting the effort expended on relieving hypotheses [Bind-free] To bind free variables of a rewrite, definition, or linear rule [Case-split] Like force but immediately splits the top-level goal on the hypothesis [Force] Identity function used to force a hypothesis [Linear-arithmetic] A description of the linear arithmetic decision procedure [Non-linear-arithmetic] Non-linear Arithmetic [Syntaxp] Attach a heuristic filter on a rule") (linear-arithmetic (linear) "A description of the linear arithmetic decision procedure ACL2 incorporates a rational linear arithmetic decision procedure. When the ACL2 prover attempts to simplify a goal, it first constructs a data structure, called the ``linear pot list'' (see [linear]), that records inequalities derived from the current goal, as an early step in the simplification process. The linear pot list is constructed as follows: first, it is seeded with equalities and inequalities about arithmetic terms occurring in the goal to be proved; then, it is extended by instantiating [47m:[0m[47m[linear][0m lemmas about terms already in the pot list. The resulting pot list is then supplied to the decision procedure when the rewriter is trying to establish or refute an arithmetic equality or inequality. This happens, for example, when an inequality occurs as a hypothesis of a rule being applied by the rewriter. (For discussion of the rewriter in general, see [introduction-to-rewrite-rules-part-1] and [introduction-to-rewrite-rules-part-2].) We describe the procedure very roughly here. Fundamental to the procedure is the notion of a linear polynomial inequality. A ``linear polynomial'' is a sum of terms, each of which is the product of a rational constant and an ``unknown.'' The ``unknown'' is permitted to be [47m1[0m simply to allow a term in the sum to be constant. Thus, an example linear polynomial is [47m3*x + 7*a + 2[0m; here [47mx[0m and [47ma[0m are the (interesting) unknowns. However, the unknowns need not be variable symbols. For example, [47m(length x)[0m might be used as an unknown in a linear polynomial. Thus, another linear polynomial is [47m3*(length x) + 7*a[0m. A ``linear polynomial inequality'' is an inequality (either [47m[<][0m or [47m[<=][0m) relation between two linear polynomials. Note that an equality may be considered as a pair of inequalities; e.q., [47m3*x + 7*a + 2 = 0[0m is the same as the conjunction of [47m3*x + 7*a + 2 <= 0[0m and [47m0 <= 3*x + 7*a + 2[0m. Certain linear polynomial inequalities can be combined by cross-multiplication and addition to permit the deduction of a third inequality with fewer unknowns. If this deduced inequality is manifestly false, a contradiction has been deduced from the assumed inequalities. For example, suppose we have two assumptions p1: 3*x + 7*a < 4 p2: 3 < 2*x and we wish to prove that, given [47mp1[0m and [47mp2[0m, [47ma < 0[0m. As suggested above, we proceed by assuming the negation of our goal p3: 0 <= a. and looking for a contradiction. Our first step will be to eliminate the variable [47mx[0m. To that end, we cross-multiply based on the coefficients of [47mx[0m in the two inequalities. By multiplying [47mp1[0m by [47m2[0m and [47mp2[0m by [47m3[0m, and then adding the respective sides, we deduce the intermediate result p4: 6*x + 14*a + 9 < 8 + 6*x which, after cancellation, is: p4: 14*a + 1 < 0. If we then cross-multiply and add [47mp3[0m to [47mp4[0m, we get p5: 1 <= 0, a contradiction. Thus, we have proved that [47mp1[0m and [47mp2[0m imply the negation of [47mp3[0m. All of the unknowns of an inequality must be eliminated by cancellation in order to produce a constant inequality. We can choose to eliminate the unknowns in any order, but we eliminate them in term-order, largest unknowns first. (See [term-order].) That is, two polys are canceled against each other only when they have the same largest unknown. For instance, in the above example we see that [47mx[0m is the largest unknown in each of [47mp1[0m and [47mp2[0m, and [47ma[0m in [47mp3[0m and [47mp4[0m. Now suppose that this procedure does not produce a contradiction but instead yields a set of nontrivial inequalities. A contradiction might still be deduced if we could add to the set some additional inequalities allowing further cancellations. That is where [47m:linear[0m lemmas come in. When the set of inequalities has stabilized under cross-multiplication and addition and no contradiction is produced, we search the database of [47m:[0m[47m[linear][0m rules for rules about the unknowns that are candidates for cancellation (i.e., are the largest unknowns in their respective inequalities). See [linear] for a description of how [47m:[0m[47m[linear][0m rules are used. See also [47m[non-linear-arithmetic][0m for a description of an extension to the linear-arithmetic procedure described here. Subtopics [Heavy-linear-p] Extend the use of [linear-arithmetic] during rewriting") (lisp-programmer-introduction (pointers) "See [introduction-to-programming-in-ACL2-for-those-who-know-lisp].") (list (lists acl2-built-ins) "Build a list [47mList[0m is the macro for building a list of objects. For example, [47m(list 5 6 7)[0m returns a list of length 3 whose elements are [47m5[0m, [47m6[0m, and [47m7[0m respectively. Also see [list*]. If a call of [47mlist[0m results in an error due to too many arguments, consider using [47m[list$][0m. [47mList[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mMacro: [0m<list> (defmacro list (&rest args) (list-macro args)) [31;1mFunction: [0m<list-macro> (defun list-macro (lst) (declare (xargs :guard t)) (if (consp lst) (cons 'cons (cons (car lst) (cons (list-macro (cdr lst)) nil))) nil))") (list$ (lists acl2-built-ins) "Build a list [47mList$[0m is a macro that is virtually interchangeable with [47m[list][0m. The only difference is that when the host Lisp is [gcl] with GCL version at least 2.7.0, [47mlist[0m may cause an error when given too many arguments (generally, more than 63). In such cases, [47mlist$[0m may be used in place of [47mlist[0m, since [47mlist$[0m has no restriction on the number of arguments.") (list* (lists acl2-built-ins) "Build a list [47mList*[0m is the Common Lisp macro for building a list of objects from given elements and a tail. For example, [47m(list* 5 6 '(7 8 9))[0m equals the list [47m'(5 6 7 8 9)[0m. Also see [list]. [47mList*[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<list*> (defmacro list* (&rest args) (declare (xargs :guard (consp args))) (list*-macro args)) [31;1mFunction: [0m<list*-macro> (defun list*-macro (lst) (declare (xargs :guard (and (true-listp lst) (consp lst)))) (if (endp (cdr lst)) (car lst) (cons 'cons (cons (car lst) (cons (list*-macro (cdr lst)) nil)))))") (listp (lists conses acl2-built-ins) "Recognizer for (not necessarily proper) lists [47m(listp x)[0m is true when [47mx[0m is either a [47m[cons][0m pair or is [47mnil[0m. [47mListp[0m has no [guard], i.e., its [guard] is [47mt[0m. [47mListp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<listp> (defun listp (x) (declare (xargs :guard t)) (or (consp x) (equal x nil)))") (lists (programming) "Lists of objects, the classic Lisp data structure. Subtopics [ACL2-number-listp] Recognizer for a true list of numbers [Add-to-set] Add a symbol to a list [Append] [concatenate] zero or more lists [Atom-listp] Recognizer for a true list of [atom]s [Boolean-listp] Recognizer for a true list of booleans [Butlast] All but a final segment of a list [Character-listp] Recognizer for a true list of characters [Concatenate] Concatenate lists or strings together [Count] Count the number of occurrences of an item in a string or true-list [Endp] Recognizer for empty lists [Eqlable-listp] Recognizer for a true list of objects each suitable for [47m[eql][0m [Evens] The even-indexed members of a list [Fix-true-list] Coerce to a true list [Improper-consp] Recognizer for improper (non-[47mnil[0m-terminated) non-empty lists [Integer-listp] Recognizer for a true list of integers [Intersection$] Elements common to the given lists [Intersectp] Test whether two lists intersect [Keyword-listp] Recognizer for true lists of keywords [Keyword-value-listp] Recognizer for true lists whose even-position elements are keywords [Last] The last [47m[cons][0m (not element) of a list [Last-cdr] The last [47m[cdr][0m of a list [Len] Length of a list [Length] Length of a string or proper list [List] Build a list [List$] Build a list [List*] Build a list [Listp] Recognizer for (not necessarily proper) lists [Make-list] Make a list of a given size [Member] Membership predicate [Merge-sort-lexorder] Sort a list [Nat-listp] Recognizer for a true list of natural numbers [No-duplicatesp] Check for duplicates in a list [Nth] The nth element (zero-based) of a list [Nthcdr] Final segment of a list [Odds] The odd-indexed members of a list [Pairlis] See [pairlis$] [Pairlis$] Zipper together two lists [Pairlis-x1] Cons a given element to each member of a list [Pairlis-x2] Cons each element of a list with a given element [Pos-listp] Recognizer for a true list of positive integers [Position] Position of an item in a string or a list [Proper-consp] Recognizer for proper ([47mnil[0m-terminated) non-empty lists [Rational-listp] Recognizer for a true list of rational numbers [Real-listp] ACL2(r) recognizer for a true list of real numbers [Remove] Remove all occurrences [Remove-duplicates] Remove duplicates from a string or a list [Remove1] Remove first occurrences, testing using [47m[eql][0m [Revappend] Concatenate the [reverse] of one list to another [Reverse] Reverse a list or string [Search] Search for a string or list in another string or list [Set-difference$] Elements of one list that are not elements of another [Standard-char-listp] Recognizer for a true list of standard characters [String-listp] Recognizer for a true list of strings [Subseq] Subsequence of a string or list [Subsetp] Test if every [47m[member][0m of one list is a [47m[member][0m of the other [Substitute] Substitute into a string or a list, using [47m[eql][0m as test [Symbol-listp] Recognizer for a true list of symbols [Take] Initial segment (first n elements) of a list [True-list-listp] Recognizer for true (proper) lists of true lists [True-listp] Recognizer for proper ([47mnil[0m-terminated) lists [Union$] A list that contains exactly the elements of the given lists [Update-nth] Modify a list by putting the given value at the given position") (live-stobj-in-proof (raw-lisp-error) "Error messages about ``live'' [stobj]s during proofs It is possible to see an error like the following. (This error is probably very rare, and perhaps can only occur during a proof.) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: A live stobj (for stobj ST) was unexpectedly encountered when evaluating a call of the function, ST-INIT. See :DOC live-stobj-in-proof. *********************************************** The solution is generally to [disable] the [executable-counterpart] of the offending function. It may well be that the only way to get an unexpected ``live'' [stobj] is by the use of [47m[swap-stobjs][0m, as suggested by the example shown below (essentially provided by Sol Swords) --- which results in a different error message, shown below, than the one above. First introduce a pair of congruent [stobj]s. (defstobj st (fld)) (defstobj st1 (fld1) :congruent-to st) Now define a function that ``initializes'' the stobj [47mst[0m by creating a new stobj [47mst1[0m and swapping the two (see [swap-stobjs]). (defun st-init (st) (declare (xargs :stobjs (st))) (with-local-stobj st1 (mv-let (st1 st) (swap-stobjs st1 st) st))) Here is a proof attempt that results in a raw Lisp error due to a live stobj being introduced by [47m[swap-stobjs][0m. ACL2 !>(thm (not (equal (st-init '(1)) '(nil)))) *********************************************** Note: SWAP-STOBJS has been called on stobjs named ST1 and ST, where the value of ST1 is a live stobj but the value of ST is not. This is an error, as such calls are unsupported; see :DOC swap-stobjs. Advanced users may find it helpful to evaluate the form (set-debugger-enable :bt) to see a backtrace of calls leading to this error; see :DOC set-debugger-enable. Will attempt to exit the proof in progress; otherwise, the next interrupt will abort the proof. For an immediate abort see :DOC abort-soft. *********************************************** The message above might explain the error. If not, and if you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) Summary Form: ( THM ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) *** Note: No checkpoints to print. *** ACL2 Error [Failure] in ( THM ...): See :DOC failure. ******** FAILED ******** ACL2 !> In fact, that formula is not a theorem! Through Version 8.6, ACL2 mistakenly proved this alleged theorem by evaluating the indicated call of [47mst-init[0m to obtain an actual Lisp array, because of how ACL2 handles [stobj]s in Lisp. But now ACL2 produces the error displayed just above. The error is avoided if we [disable] the [executable-counterpart] of the offending function, [47mst-init[0m. Indeed, the following theorem, which contradicts the false claim above and disables the offending executable-counterpart, shows that the logical value of [47m(st-init '(1))[0m is indeed [47m'(nil)[0m. (thm (equal (st-init '(1)) '(nil)) :hints(("Goal" :in-theory (disable (:e st-init)))))") (local (events) "Hiding an event in an encapsulation or book Examples: (local (defthm hack1 (implies (and (acl2-numberp x) (acl2-numberp y) (equal (* x y) 1)) (equal y (/ x))))) (local (defun double-naturals-induction (a b) (cond ((and (integerp a) (integerp b) (< 0 a) (< 0 b)) (double-naturals-induction (1- a) (1- b))) (t (list a b))))) General Form: (local ev) where [47mev[0m is an event form. If the current default [defun-mode] (see [default-defun-mode]) is [47m:[0m[47m[logic][0m and [47m[ld-skip-proofsp][0m is [47mnil[0m or [47mt[0m, then [47m(local ev)[0m is equivalent to [47mev[0m. But if the current default [defun-mode] is [47m:[0m[47m[program][0m or if [47m[ld-skip-proofsp][0m is [47m'[0m[47m[include-book][0m, then [47m(local ev)[0m is a [47mno-op[0m. Thus, if such forms are in the event list of an [47m[encapsulate][0m event or in a book, they are processed when the encapsulation or book is checked for admissibility in [47m:[0m[47m[logic][0m mode but are skipped when extending the host [world]. Such [events] are thus considered ``local'' to the verification of the encapsulation or book. The non-local [events] are the ones ``exported'' by the encapsulation or book. See [encapsulate] for a thorough discussion. Also see [local-incompatibility] for a discussion of a commonly encountered problem with such event hiding: you can't make an event local if its presence is required to make sense of a non-local one. Note that [events] that change the default [defun-mode], and in fact any [events] that set the [47m[ACL2-defaults-table][0m, are disallowed inside the scope of [47mlocal[0m. See [embedded-event-form].") (local-incompatibility (miscellaneous) "When non-local [events] won't replay in isolation Sometimes a ``[47m[local][0m incompatibility'' is reported while attempting to embed some [events], as in an [47m[encapsulate][0m or [47m[include-book][0m. This is generally due to the use of a locally defined name in a non-local event or the failure to make a witnessing definition [47m[local][0m. (But see the Remark at the end of this topic about a related issue with guard-checking.) [47m[Local][0m incompatibilities may be detected while trying to execute the strictly non-[local] [events] of an [47m[encapsulate][0m or [47m[certify-book][0m call. For example, [47mencapsulate[0m operates by first executing all the [events] (local and non-local) with [47m[ld-skip-proofsp][0m [47mnil[0m, to confirm that they are all admissible. Then it attempts merely to assume the non-local ones to create the desired theory, by executing the [events] with [47m[ld-skip-proofsp][0m set to [47m'include-book[0m. [47mCertify-book[0m does something similar, so that when [47m[include-book][0m assumes the non-local events in the book, we are confident that the previously successful certification has performed the necessary admissibility check. How can a sequence of [events] admitted with [47m[ld-skip-proofsp][0m [47mnil[0m fail when [47m[ld-skip-proofsp][0m is [47m'include-book[0m? The key observation is that in the latter case only the non-local [events] are processed. The [47m[local][0m ones are skipped and so the non-local ones must not depend upon them. Two typical mistakes are suggested by the detection of a [47m[local][0m incompatibility: (1) a locally defined function or macro was used in a non-[47m[local][0m event (and, in the case of [47m[encapsulate][0m, was not included among the [signature]s) and (2) the witnessing definition of a function that was included among the [signature]s of an [47m[encapsulate][0m was not made [47m[local][0m. An example of mistake (1) would be to include among your [encapsulate]d [events] both a local definition of [47mf[0m and a non-local theorem about [47mf[0m, for example as follows. (encapsulate () (local (defun f (x) x)) (defun g (x) x) (defthm f-is-g (equal (f x) (g x))) ) In this case, either the [47m[defthm][0m should be made [47m[local][0m or, if we want to export the [47mdefthm[0m, then the [47m[defun][0m of [47mf[0m should be made non-local. Similar analysis holds if the events in the [47mencapsulate[0m call above are instead in a book. An example of mistake (2) would be to include [47m((fn *) => *)[0m among your [signature]s and then to write [47m(defun fn (x) ...)[0m in your [events], instead of [47m(local (defun fn ...))[0m, as shown in the example below. In essence, this is an error because [47mfn[0m is exported twice: once by the signature and once by the [47mdefun[0m. (encapsulate ( ((fn *) => *) ) (defun fn (x) x) ) One subtle aspect of [47m[encapsulate][0m is that if you constrain any member of a mutually recursive clique you must define the entire clique locally and then you must constrain those members of it you want axiomatized non-locally. Errors due to [47m[local][0m incompatibility should never occur in the inclusion of a fully certified book. Certification ensures against it. Therefore, if [47m[include-book][0m reports an incompatibility, we claim that earlier in the processing of the [47m[include-book][0m a warning was printed advising you that some book was uncertified. If this is not the case --- if [47m[include-book][0m reports an incompatibility and there has been no prior warning about lack of certification --- please report it to the ACL2 implementors. When a [47m[local][0m incompatibility is detected during the second pass of an [47m[encapsulate][0m or [47m[certify-book][0m, the logical [world] is restored to what it was immediately before that call was evaluated. Note that for [47mcertify-book[0m, local incompatibility could be caused by an event that is local either in the certification world (see [portcullis]) or in the book itself. ACL2 checks during [47mcertify-book[0m for local incompatibility by rolling back the world --- back through the first portcullis command that generates a local event, or if there is none, then back through the first local event in the book (with the general exception of those inside an [47mencapsulate[0m, but see final Remark below) --- and then including the book. But all that is skipped in the absence of either kind of local event. See [fast-cert] for a way to skip the local incompatibility check, although that may compromise soundness. Here is a subtle example of [47m[local][0m incompatibility. The problem is that in order for [47mfoo-type-prescription[0m to be admitted using the specified [47m:typed-term[0m [47m(foo x)[0m, the conclusion [47m(my-natp (foo x))[0m depends on [47mmy-natp[0m being a [compound-recognizer]. This is fine on the first pass of the [47m[encapsulate][0m, during which lemma [47mmy-natp-cr[0m is admitted. But [47mmy-natp-cr[0m is skipped on the second pass because it is marked [47m[local][0m, and this causes [47mfoo-type-prescription[0m to fail on the second pass. (defun my-natp (x) (declare (xargs :guard t)) (and (integerp x) (<= 0 x))) (defun foo (x) (nfix x)) (encapsulate () (local (defthm my-natp-cr (equal (my-natp x) (and (integerp x) (<= 0 x))) :rule-classes :compound-recognizer)) (defthm foo-type-prescription (my-natp (foo x)) :hints (("Goal" :in-theory (enable foo))) :rule-classes ((:type-prescription :typed-term (foo x))))) [31;1mRemark[0m. We conclude by remarking that for ``local incompatibility'' in the case of [47mcertify-book[0m, the notion of ``local'' is a bit more comprehensive than the name suggests, in that it can involve [guard]-checking in the following situation. For example, in a fresh ACL2 session evaluate the [command] [47m(set-guard-checking :none)[0m followed by [47m(table foo 0 (car 3))[0m. Then any attempt to certify a book should fail, since subsequent inclusion of that book would fail with a [guard] violation; that's because the [47mset-guard-checking[0m call was not saved in the [certificate] file, hence was not evaluated when evaluating [47m(car 3)[0m while attempting to include the book. The example above may be helpful while reading the following general explanation of how local incompatibility incorporates the setting of guard-checking. Suppose you are evaluating [command]s directly in the top-level read-eval-print loop. One of those commands might be a call of [47m[set-guard-checking][0m that weakens guard-checking from its default behavior, i.e., [47m(set-guard-checking VAL)[0m where [47mVAL[0m is other than [47mt[0m, [47m:nowarn[0m, or [47m:all[0m. This command does not change the logical [world], so it will not be part of the book's [portcullis] commands. In that sense, it is like a [local] portcullis command. ACL2 notices this case and insists that any portcullis event evaluated with guard-checking that is weaker than the default must be rolled back during the check for local incompatibilities.") (logand (numbers acl2-built-ins) "Bitwise logical `and' of zero or more integers When integers are viewed in their two's complement representation, [47mlogand[0m returns their bitwise logical `and'. In ACL2 [47mlogand[0m is a macro that expands into calls of the binary function [47mbinary-logand[0m, except that [47m(logand)[0m expands to [47m-1[0m and [47m(logand x)[0m expands to [47m(the integer x)[0m. The [guard] for [47mbinary-logand[0m requires its arguments to be integers. [47mLogand[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mMacro: [0m<logand> (defmacro logand (&rest args) (cond ((null args) -1) ((null (cdr args)) (cons 'the (cons 'integer (cons (car args) 'nil)))) (t (xxxjoin 'binary-logand args)))) [31;1mFunction: [0m<binary-logand> (defun binary-logand (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (cond ((zip i) 0) ((zip j) 0) ((eql i -1) j) ((eql j -1) i) (t (let ((x (* 2 (logand (floor i 2) (floor j 2))))) (+ x (cond ((evenp i) 0) ((evenp j) 0) (t 1)))))))") (logandc1 (numbers acl2-built-ins) "Bitwise logical `and' of two ints, complementing the first When integers are viewed in their two's complement representation, [47mlogandc1[0m returns the bitwise logical `and' of the second with the bitwise logical `not' of the first. The [guard] for [47mlogandc1[0m requires its arguments to be integers. [47mLogandc1[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logandc1> (defun logandc1 (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (logand (lognot i) j))") (logandc2 (numbers acl2-built-ins) "Bitwise logical `and' of two ints, complementing the second When integers are viewed in their two's complement representation, [47mlogandc2[0m returns the bitwise logical `and' of the first with the bitwise logical `not' of the second. The [guard] for [47mlogandc2[0m requires its arguments to be integers. [47mLogandc2[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logandc2> (defun logandc2 (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (logand i (lognot j)))") (logbitp (numbers acl2-built-ins) "The [47mi[0mth bit of an integer For a nonnegative integer [47mi[0m and an integer [47mj[0m, [47m(logbitp i j)[0m is a Boolean, which is [47mt[0m if and only if the value of the [47mi[0mth bit is [47m1[0m in the two's complement representation of [47mj[0m. [47m(Logbitp i j)[0m has a [guard] that [47mi[0m is a nonnegative integer and [47mj[0m is an integer. [47mLogbitp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logbitp> (defun logbitp (i j) (declare (xargs :guard (and (integerp j) (integerp i) (>= i 0)))) (oddp (floor (ifix j) (expt 2 (nfix i)))))") (logcount (numbers acl2-built-ins) "Number of ``on'' bits in a two's complement number [47m(Logcount x)[0m is the number of ``on'' bits in the two's complement representation of [47mx[0m. [47m(Logcount x)[0m has a [guard] of [47m(integerp x)[0m. [47mLogcount[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logcount> (defun logcount (x) (declare (xargs :guard (integerp x))) (cond ((zip x) 0) ((< x 0) (logcount (lognot x))) ((evenp x) (logcount (nonnegative-integer-quotient x 2))) (t (1+ (logcount (nonnegative-integer-quotient x 2))))))") (logeqv (numbers acl2-built-ins) "Bitwise logical equivalence of zero or more integers When integers are viewed in their two's complement representation, [47mlogeqv[0m returns their bitwise logical equivalence. In ACL2 [47mlogeqv[0m is a macro that expands into calls of the binary function [47mbinary-logeqv[0m, except that [47m(logeqv)[0m expands to [47m-1[0m and [47m(logeqv x)[0m expands to [47m(the integer x)[0m. The [guard] for [47mbinary-logeqv[0m requires its arguments to be integers. [47mLogeqv[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mMacro: [0m<logeqv> (defmacro logeqv (&rest args) (cond ((null args) -1) ((null (cdr args)) (cons 'the (cons 'integer (cons (car args) 'nil)))) (t (xxxjoin 'binary-logeqv args)))) [31;1mFunction: [0m<binary-logeqv> (defun binary-logeqv (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (logand (logorc1 i j) (logorc1 j i)))") (logic (defun-mode) "To set the default [defun-mode] to [47m:logic[0m Example: ACL2 p!>:logic ACL2 !> Typing the keyword [47m:logic[0m sets the default [defun-mode] to [47m:logic[0m. Functions defined in [47m:logic[0m mode are logically defined. See [defun-mode]. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. See [defun-mode] for a discussion of the [defun-mode]s available and what their effects on the logic are. See [default-defun-mode] for a discussion of how the default [defun-mode] is used. This event is equivalent to [47m(table acl2-defaults-table :defun-mode :logic)[0m, and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs. See [ACL2-defaults-table]. Recall that the top-level form [47m:logic[0m is equivalent to [47m(logic)[0m; see [keyword-commands]. Thus, to change the default [defun-mode] to [47m:logic[0m in a book, use [47m(logic)[0m, which is an embedded event form, rather than [47m:logic[0m, which is not a legal form for [books]. See [embedded-event-form].") (logic-fns-list-listp (termp acl2-built-ins) "Recognizer for when a given list of lists of [term]s calls only [47m:[0m[47m[logic][0m-mode function symbols For a list [47mx[0m of lists of [term]s in [world] [47mwrld[0m, [47m(logic-fns-list-listp x wrld)[0m is true if and only if every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in [47mwrld[0m. Unlike [47m[logic-term-list-listp][0m, [47mlogic-fns-list-listp[0m does not check that [47mx[0m is a list of lists of terms; rather, [47mlogic-fns-list-listp[0m should only be applied to such lists. See [47m[defun-mode-lambdas][0m for some clarifications of how [47m:program[0m mode functions are allowed in certain [47m:logic[0m mode terms. [31;1mFunction: [0m<logic-fns-list-listp> (defun logic-fns-list-listp (x wrld) (declare (xargs :guard (and (plist-worldp wrld) (pseudo-term-list-listp x)))) (cond ((endp x) t) (t (and (logic-fns-listp (car x) wrld) (logic-fns-list-listp (cdr x) wrld)))))") (logic-fns-listp (termp acl2-built-ins) "Recognizer for when a given list of [term]s calls only [47m:[0m[47m[logic][0m-mode function symbols For a list [47mx[0m of [term]s in [world] [47mwrld[0m, [47m(logic-fns-listp x wrld)[0m is true if and only if every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in [47mwrld[0m. Unlike [47m[logic-term-listp][0m, [47mlogic-fns-listp[0m does not check that [47mx[0m is a list of terms; rather, [47mlogic-fns-listp[0m should only be applied to such lists. See [47m[defun-mode-lambdas][0m for some clarifications of how [47m:program[0m mode functions are allowed in certain [47m:logic[0m mode terms. [31;1mFunction: [0m<logic-fns-listp> (defun logic-fns-listp (lst wrld) (declare (xargs :guard (and (plist-worldp wrld) (pseudo-term-listp lst)))) (cond ((endp lst) t) (t (and (logic-fnsp (car lst) wrld) (logic-fns-listp (cdr lst) wrld)))))") (logic-fnsp (termp acl2-built-ins) "Recognizer for when a given [term] calls only [47m:[0m[47m[logic][0m-mode function symbols For a [term] [47mx[0m in [world] [47mwrld[0m, [47m(logic-fnsp x wrld)[0m is true if and only if every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in [47mwrld[0m. Unlike [47m[logic-termp][0m, [47mlogic-fnsp[0m does not check that [47mx[0m is a term; rather, [47mlogic-fnsp[0m should only be applied to terms. See [47m[defun-mode-lambdas][0m for some clarifications of how [47m:program[0m mode functions are allowed in certain [47m:logic[0m mode terms. [31;1mFunction: [0m<logic-fnsp> (defun logic-fnsp (term wrld) (declare (xargs :guard (and (plist-worldp wrld) (pseudo-termp term)))) (cond ((variablep term) t) ((fquotep term) t) ((flambdap (ffn-symb term)) (and (logic-fnsp (lambda-body (ffn-symb term)) wrld) (logic-fns-listp (fargs term) wrld))) ((programp (ffn-symb term) wrld) nil) (t (logic-fns-listp (fargs term) wrld))))") (logic-knowledge-taken-for-granted (introduction-to-the-theorem-prover) "Background knowledge in ACL2 logic for theorem prover tutorial You might think that in order to use the theorem prover you have to know the mathematical logic supported by ACL2. But you need to know a lot less about it than you might think. Technically, a theorem is a formula that can be derived from axioms by using rules of inference. Thus, to do a proof you have to know (a) the syntax of formulas, (b) the axioms, and (c) the rules of inference. Traditionally, these things are spelled out in excruciating detail in treatments of mathematical logic --- and for good reason. The whole point of proving theorems is that it is a way to determine that a formula is ``always true'' (under some model of the axioms). By ``always true'' we actually mean what logicians mean when they say the formula is [3mvalid[0m: true in the model, for all possible values of the variables. Here by ``model of the axioms'' we mean an understanding of the meaning of the various function symbols so that the axioms are true for all values of the variables. If the variables in your conjecture can take on an infinite number of values, proof is often the [31;1monly[0m way to determine that a conjecture is ``always true.'' So if proof is being used to determine that a questionable formula is always true the proof must be carried out flawlessly. Thus, the (a) syntax, (b) axioms, and (c) rules of inference must be described precisely and followed to the letter. But formal mathematical logic was invented to explain how people reason. To the extent that logic mimics human reasoning, proofs can be seen as just extremely carefully crafted arguments. Given that ACL2 is responsible for following the rules ``to the letter,'' your main job is ``explain'' the big leaps. To use the theorem prover you must understand (a) the syntax, because you must be able to write formulas flawlessly. But you don't have to know (b) the axioms and (c) the rules of inference at nearly the same level of precision, as long as you understand the basic structure and language of proofs. Below is part of a proof of a certain theorem. You ought to be able to understand the following. Since what we describe is a proof of one case of the formula, we hope that you're [3mconvinced[0m that the formula holds for that case. Read this and follow the links to confirm that you understand what happens. Be sure to then use your browser's [31;1mBack Button[0m to return to this page and continue. [31;1mAn Annotated Proof of[0m (implies (true-listp z) (equal (rev (rev z)) z)) ``We will prove that reversing the reverse of a [47mtrue-listp[0m yields the original list. The formula stating this is above. We will prove it by induction (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF]) on the list structure of [47mz[0m. The base case (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-BASE-CASE]) of the induction is: (implies (endp z) (implies (true-listp z) (equal (rev (rev z)) z))). This formula is equivalent, by propositional calculus (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]), to (implies (and (endp z) (true-listp z)) (equal (rev (rev z)) z)) Rewriting (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING]) with the definition of [47mendp[0m produces: (implies (and (not (consp z)) (true-listp z)) (equal (rev (rev z)) z)) Rewriting repeatedly (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING-REPEATEDLY]) starting with the definition of [47mtrue-listp[0m produces: (implies (and (not (consp z)) (equal z nil)) (equal (rev (rev z)) z)) Then using the second [3mhypothesis[0m, just substituting equals for equals (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EQUALS-FOR-EQUALS]), we get (implies (and (not (consp z)) (equal z nil)) (equal (rev (rev nil)) nil)) Since the [3mconclusion[0m involves no variables, we can evaluate (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EVALUATION]) it, getting (implies (and (not (consp z)) (equal z nil)) T) But this is an instance (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of the tautology (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]) [47m(implies p T)[0m. Thus, the base case is proved.'' Now it is time for a little quiz. There are just three questions. [31;1mQ1[0m: The case above was the Base Case of an inductive proof of (implies (true-listp z) (equal (rev (rev z)) z)) in which we did induction on the structure of the linear list [47mz[0m. What is the Induction Step? That is, what do you have to prove besides the Base Case to complete this inductive proof? Below are four commonly given answers; choose one. Then look here (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q1-ANSWER]) to find out if you're right. [3mInduction Step -- Choice (i)[0m: (implies (not (endp z)) (implies (true-listp z) (equal (rev (rev z)) z))) [3mInduction Step -- Choice (ii)[0m: (implies (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z))) [3mInduction Step -- Choice (iii)[0m: (implies (and (not (endp z)) (equal (rev (rev (cdr x))) (cdr x))) (implies (true-listp z) (equal (rev (rev z)) z))) [3mInduction Step -- Choice (iv)[0m: (implies (and (not (endp z)) (implies (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z)))) (implies (true-listp z) (equal (rev (rev z)) z))) [31;1mQ2[0m: To prove the Induction Step we must prove one or more of the goals below. Which combinations are sufficient to imply the Induction Step? Decide what is required and then look here (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q2-ANSWER]) to find out if you're right. To help you, the Induction Step is of the form: [3mInduction Step[0m: (implies (and [3mc[0m (implies [3mp'[0m [3mq'[0m)) (implies [3mp[0m [3mq[0m)) and beside each candidate subgoal we show its structure in those terms. [3mSubgoal (i)[0m: (implies (and (not (endp z)) ; (implies (and [3mc[0m (true-listp z)) ; [3mp[0m) (true-listp (cdr z))) ; [3mp'[0m) [3mSubgoal (ii)[0m: (implies (and (not (endp z)) ; (implies (and [3mc[0m (true-listp z) ; [3mp[0m (equal (rev (rev (cdr z))) (cdr z))) ; [3mq'[0m) (equal (rev (rev z)) z)) ; [3mq[0m) [3mSubgoal (iii)[0m: (implies (and (not (endp z)) ; (implies (and [3mc[0m (equal (rev (rev (cdr z))) (cdr z))) ; [3mq'[0m) (equal (rev (rev z)) z)) ; [3mq[0m) [3mSubgoal (iv)[0m: (implies (and (not (endp z)) ; (implies (and [3mc[0m (true-listp (cdr z)) ; [3mp'[0m (equal (rev (rev (cdr z))) (cdr z))) ; [3mq'[0m) (equal (rev (rev z)) z)) ; [3mq[0m) [31;1mQ3[0m: Suppose you know the theorem [3mTheorem[0m: (implies (p (f x)) (equal (g (h x)) x)) and you wish to rewrite the target [47m(g (h a))[0m to [47ma[0m in [3mGoal Conjecture[0m: (implies (and (q (f a)) (r a)) (s (g (h a)))) What must you prove to relieve the hypothesis of [3mTheorem[0m? After you've thought about it, look here (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q3-ANSWER]) for our answer. [31;1mEnd of the Quiz[0m If this page made sense, you're ready to read the introduction to the theorem prover. If you are reading this as part of the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover].") (logic-knowledge-taken-for-granted-base-case (introduction-to-the-theorem-prover) "A brief explanation of base cases According to the sentence, the conjecture being proved is ``reversing the reverse of a [47mtrue-listp[0m yields the original list.'' The formula corresponding to this conjecture is: (implies (true-listp z) (equal (rev (rev z)) z)). We're also told that this is an inductive proof. Evidently we're doing an induction on the structure of the list [47mz[0m. Then the [3mBase Case[0m is the formula: (implies (endp z) (implies (true-listp z) (equal (rev (rev z)) z))). Now use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-equals-for-equals (introduction-to-the-theorem-prover) "Substitution of equals for equals Anytime you have an equality hypothesis relating two terms, e.g., (equal [3mlhs[0m [3mrhs[0m) it is legal to substitute one for the other anyplace else in the formula. Doing so does not change the truth value of the formula. You can use a [3mnegated equality[0m this way [3mprovided[0m it appears in the conclusion. For example, it is ok to transform (implies (true-listp x) (not (equal x 23))) to (implies (true-listp 23) (not (equal x 23))) by substitutions of equals for equals. That is because, by propositional calculus (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]), we could rearrange the formulas into their [3mcontrapositive[0m forms: (implies (equal x 23) (not (true-listp x))) and (implies (equal x 23) (not (true-listp 23))) and see the equality as a hypothesis and the substitution of [47m23[0m for [47mx[0m as sensible. Sometimes people speak loosely and say ``substitution of equals for equals'' when they really mean ``substitutions of equivalents for equivalents.'' Equality, as tested by [47mEQUAL[0m, is only one example of an equivalence relation. The next most common is propositional equivalence, as tested by [47mIFF[0m. You can use propositional equivalence hypotheses to substitute one side for the other [3mprovided[0m the target term occurs in a propositional place, as discussed at the bottom of propositional calculus (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]). Now use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-evaluation (introduction-to-the-theorem-prover) "Evaluation during proofs Any time you are proving a formula and see a subterm in the formula that contains no variables, you can just evaluate the subterm. This is familiar from algebra: It is not uncommon to rearrange a polynomial to collect all the constants and then add them up: (3x + 2 + 7y + 2) = (3x + 7y + (2 + 2)) = (3x + 7y + 4). That last step is just evaluation. It happens often in ACL2 proofs because theorems involve constants and defined functions and when those constants ``drift into the maw'' of a function, the function call can be eliminated and replaced by a new constant. ACL2 does this automatically; you don't have to tell it. In fact, there are a few occasions where you might prefer it [3mnot[0m evaluate and those are the ones you have to look out for! They'll be obvious when they happen because you'll see a mysterious constant crop up in the proof. Evaluation is legal because it is just the repeated use of unconditional rewriting to replace definitions by their instantiated bodies until no function calls remain. Now use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-inductive-proof (introduction-to-the-theorem-prover) "A brief explanation of induction We start by showing classical induction on the natural numbers in an ACL2 setting before turning to a more general treatment of induction. [31;1mClassical Induction on Natural Numbers[0m: Induction is familiar in the arithmetic setting. Let [47m(p n)[0m denote some formula involving the variable [47mn[0m (and perhaps some other variables which we don't exhibit). Then to prove [47m(p n)[0m, for all [47mn[0m, by classical induction on the construction of the natural numbers, prove each of the following: [3mBase Case[0m: (implies (zp n) (p n)) [3mInduction Step[0m: (implies (and (not (zp n)) (p (- n 1))) (p n)) The Base Case establishes that [47mp[0m holds for [47m0[0m. In fact, because of the definition of [47m[zp][0m {ICON} (see [A_Tiny_Warning_Sign]), it establishes that [47m(p n)[0m holds when [47mn[0m is [47m0[0m and it holds when [47mn[0m is not a natural number. The Induction Step establishes that if [47mn[0m is a natural number other than [47m0[0m, and if [47mp[0m holds for [47mn[0m-1, then [47mp[0m holds for [47mn[0m. The hypothesis [47m(p (- n 1))[0m above is called the [3minduction hypothesis[0m. Note that if the Base Case and Induction Step are valid, then we know [47m(p n)[0m, for all [47mn[0m. You can convince yourself of this by picking any object and asking ``how do I know [47mp[0m holds for this object?'' For example, [47m(p -7)[0m, [47m(p 'abc)[0m, and [47m(p 0)[0m are all established by the Base Case. What about [47m(p 1)[0m? That follows from [47m(p 0)[0m, given the Induction Step. Why? To prove [47m(p 1)[0m using the Induction Step, you have to establish [47m(not (zp 1))[0m, which is true, and [47m(p (- 1 1))[0m, which is [47m(p 0)[0m, which is true by the Base Case. So [47m(p 1)[0m is true. Similar reasoning proves [47m(p 2)[0m from from [47m(p 1)[0m, etc. Clearly, for every natural number other than [47m0[0m we could reason like this to show that [47mp[0m holds. Since the Base Case handled all the objects that are not natural numbers, and handled [47m0[0m, we know [47m(p n)[0m, for all [47mn[0m. There is a duality between recursion and induction that ACL2 exploits. The fact that the Base and Induction steps above are sufficient to prove [47mp[0m for all objects is related to the fact that the following recursion defines a total, terminating function: (defun nat-recursion (n) (if (zp n) n (nat-recursion (- n 1)))) When this function is admitted we have to prove that if [47m(zp n)[0m does not hold, then [47m(- n 1)[0m is smaller, in some sense, than [47mn[0m. This sense of ``smaller'' is determined by some [3mmeasure[0m of the arguments. That measure must return an ordinal (see [ordinals] {ICON} (see [A_Tiny_Warning_Sign])), but the most common measures return natural numbers, which are among the ordinals. Furthermore, that measure should ensure that the terms in the recursive calls are smaller than the formals, i.e., the measure of [47m(- n 1)[0m must be smaller than the measure of [47mn[0m, when the recursive branches are taken. This sense of ``smaller'' must be [3mwell-founded[0m: it must be impossible to have an infinitely descending chain of smaller things. This is true of the less-than relation on the ordinals (see [47m[o<][0m {ICON} (see [A_Tiny_Warning_Sign])). Well-foundedness means that eventually any recursion must ``bottom out'' because things can't keep getting smaller forever. The recursion in [47mnat-recursion[0m [31;1msuggests[0m the induction shown above: the Base Case is defined by the [47mif[0m branch that does not lead to a recursive call. The Induction Step is defined by the other branch. The induction hypothesis is defined by what we recur on, i.e., [47m(- n 1)[0m. The theorems proved when [47mnat-recursion[0m is introduced [3mjustify[0m the classical induction scheme noted above. Every recursively defined ACL2 function suggests a legal induction and vice versa. Furthermore, every call of a recursively defined function on distinct variable symbols also suggests a legal induction: just take the induction suggested by the function's recursive definition after renaming the formal parameters to be the variables in the call. For example, it should be clear that [47m(nat-recursion a)[0m suggests a Base Case defined by [47m(zp a)[0m, and induction step defined by [47m(not (zp a))[0m and an induction hypothesis about [47m(- a 1)[0m. Note that the term [47m(fact n)[0m suggests the same classical induction on natural numbers shown above, where [47mfact[0m is defined as follows (even though we've used the formal parameter [47mk[0m below). (defun fact (k) (if (zp k) 1 (* k (fact (- k 1))))) The induction suggested by a term like [47m(fact n)[0m is insensitive to the name of the formal parameter used in the [47mdefun[0m. The induction suggested by a function or term is insensitive to the value returned by the function or term. It doesn't matter what the function returns in its ``base case'' (e.g., [47m1[0m in [47mfact[0m) or what the function ``does'' to its recursive call (e.g., multiply by [47mk[0m in the [47mdefun[0m of [47mfact[0m). All that matters is (i) how the [47mif[0m structure breaks down the cases on [47mk[0m, (ii) which branches lead to recursion, and (iii) what arguments are passed to the recursive calls. Those things determine (i) the case analysis of the induction scheme, (ii) which cases are Base Cases and which are Induction Steps, and (iii) what the induction hypotheses are. For a selection of common inductions schemes in ACL2 (e.g., on the structure of natural numbers, lists, and trees and on several variables at once, multiple base cases, multiple induction hypotheses, multiple induction steps, etc.) check this link (see [EXAMPLE-INDUCTIONS]). Every legal ACL2 induction corresponds to an admissible recursive function and vice versa. Similarly, every legal ACL2 induction corresponds to a call of a recursively defined function on distinct variables. ACL2 chooses which induction to do by looking at the terms that occur in the conjecture. For many elementary theorems, ACL2 chooses the right induction by itself. You may occasionally need to tell it what induction to do. You do that by showing it a term that suggests the induction you want. We'll explain how you communicate this to ACL2 later. If you understand how recursive functions suggest inductions, then you know what you need to know to use ACL2. The main point of this discussion of induction is familiarize you with the basic terms: [3mBase Case[0m (of which there may be several), [3mInduction Step[0m (of which there may be several), [3mInduction Hypothesis[0m (of which there may be several in each Induction Step), [3mmeasure[0m and [3mwell-founded relation[0m [3mjustifying[0m an induction, and the induction [3msuggested[0m by a term or recursive function definition. Furthermore, every Induction Hypothesis is always an instance (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of the conjecture being proved: each induction hypothesis is obtained from the conjecture being proved by applying a [3msubstitution[0m replacing variables by terms. If you are reviewing the material taken for granted about logic while working your way through the introduction to the theorem prover, please use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-instance (introduction-to-the-theorem-prover) "A brief explanation of substitution instances Let [3mp[0m and [3mq[0m be terms or formulas (there is no difference in ACL2). Then we say [3mp[0m is an [3minstance[0m or [3msubstitution instance[0m of [3mq[0m if and only if [3mp[0m can be obtained from [3mq[0m by uniformly replacing the variables of [3mq[0m by terms. Sometimes we call [3mp[0m the [3mtarget[0m and [3mq[0m the [3mpattern[0m because by choosing appropriate replacements we can make the pattern [3mmatch[0m many different targets. For example, the following [3mtarget[0m is an instance of the given [3mpattern[0m: [3mtarget[0m: (APP (APP (REV A) (REV B)) (REV C)) [3mpattern[0m: (APP (APP x y ) (REV z)) The replacement or [3msubstitution[0m used in this match of the pattern to the target is: [3mvariable in pattern[0m [3mreplacement term[0m x (REV A) y (REV B) z C Such substitutions are usually written this way in ACL2: ((x (REV A)) (y (REV B)) (z C)). Please use your browser's [31;1mBack Button[0m to return to the page that mentioned ``instance.''") (logic-knowledge-taken-for-granted-propositional-calculus (introduction-to-the-theorem-prover) "A brief explanation of propositional calculus It is impossible in this short introduction to teach you propositional calculus if you don't already know it! A typical use of propositional calculus is to observe that (implies (endp z) (implies (true-listp z) (equal (rev (rev z)) z))) is equivalent to: (implies (and (endp z) (true-listp z)) (equal (rev (rev z)) z)) If this is surprising and you know propositional calculus, then the problem might be our notation. We're exploiting the tautology [3m(p ---> (q ---> r)) <---> ((p & q) ---> r)[0m where [3m--->[0m and [3m<--->[0m are meant to be the traditional arrows denoting logical implication and logical equivalence. If you don't know propositional calculus, we'll say just a few things to help ease your journey. A [3mpropositional formula[0m, in ACL2, is any formula written entirely in terms of variable symbols, [47mT[0m, [47mNIL[0m, and the propositional functions [47mAND[0m, [47mOR[0m, [47mNOT[0m, [47mIMPLIES[0m, and [47mIFF[0m. The ``tautology'' above in traditional notation is this propositional formula in ACL2: (IFF (IMPLIES P (IMPLIES Q R)) (IMPLIES (AND P Q) R)). If you have a formula like (implies [3mhyp[0m [3mconcl[0m) then we say that formula is an [3mimplication[0m, that [3mhyp[0m is the [3mhypothesis[0m, and that [3mconcl[0m is the conclusion. If the hypothesis is an [47mand[0m expression, as in (implies (and [3mhyp1[0m [3mhyp2[0m ...) [3mconcl[0m) then we call [3mhyp1[0m is the [3mfirst hypothesis[0m, [3mhyp2[0m is the [3msecond hypothesis[0m, etc. If a term is of the form (and [3mterm1[0m [3mterm2[0m ...) we say it is a [3mconjunction[0m and that [3mterm1[0m is the [3mfirst conjunct[0m, [3mterm2[0m is the [3msecond conjunct[0m, etc. We treat an [47mor[0m-term analogously but call it a [3mdisjunction[0m and its arguments are [3mdisjuncts[0m. A [3mtautology[0m is any propositional formula that can be proved by testing it under all combinations of Boolean assignments to its variables. We give an example of such a [3mtruth-table proof[0m below, but hasten to add that ACL2 does not generally use truth tables to recognize tautologies. It primarily uses [normalization] and BDDs to recognize tautologies, which can be seen as a mix of symbolic manipulation and case analysis. Many tautologies have names, but ACL2 doesn't refer to them by name because it derives them from first principles. We list a few here because we sometimes use the names in our documentation; more importantly, you should look at these formulas and convince yourself that they're always true for all Boolean values of the variables: [3mDouble Negation[0m: (iff (not (not p)) p) [3mDeMorgan[0m: (iff (not (and p q)) (or (not p) (not q))) [3mDistributivity[0m: (iff (and p (or q r)) (or (and p q) (and p r))) [3mPromotion[0m: (iff (implies p (implies q r)) (implies (and p q) r)) [3mImplicative Disjunction[0m: (iff (implies p q) (or (not p) q)) [3mContrapositive[0m: (iff (implies p q) (implies (not q) (not p))) [3mGeneralized Contrapositive[0m: (iff (implies (and p r) q) (implies (and p (not q)) (not r))) There are, of course, many others, even with these same names! For example, there is a dual version of DeMorgan showing how [47mnot[0m distributes over [47mor[0m, a dual version of Distributivity for [47mor[0m over [47mand[0m, etc. Dealing with propositional calculus will not generally be a problem for you because it is decidable and ACL2 has procedures that decide propositional formulas. However, propositional calculus can lead to exponential explosion and can thus explain why ACL2 has ``gone out to lunch.'' In addition, sometimes if you are curious as to [3mwhy[0m ACL2 is working on a certain subgoal the reason can be traced back to propositional calculus. The most common example of this is that to prove a formula of the form (implies (implies p1 q1) (implies p2 q2)) propositional calculus will convert it to (and (implies (and p2 (not p1)) q2) (implies (and p2 q1) q2)) Many users are surprised that the first conjunct above does not have [47mq1[0m as a hypothesis. If you ever stare at an ACL2 goal and say to yourself ``A hypothesis is missing!'' the chances are that propositional calculus is ``to blame.'' In particular, if you are trying to prove that [47m(implies p1 q1)[0m implies something, you must deal with the case that [47m(implies p1 q1)[0m is true because [47mp1[0m is false. Think about it. Now we illustrate the truth table method for deciding tautologies, even though that is not what ACL2 generally uses. Consider the formula called Promotion above: (IFF (IMPLIES P (IMPLIES Q R)) (IMPLIES (AND P Q) R)) The formula above is a tautology. It contains three variables, [47mP[0m, [47mQ[0m, and [47mR[0m, and so there are 8 combinations of Boolean assignments to them. If we let [3mformula1[0m: (IMPLIES P (IMPLIES Q R)) [3mformula2[0m: (IMPLIES (AND P Q) R) then we wish to test the formula [47m(IFF [0m[3mformula1 formula2[0m[47m)[0m: P Q R [3mformula1[0m [3mformula2[0m (IFF [3mformula1[0m [3mformula2[0m) --------- T T T T T T T T NIL NIL NIL T T NIL T T T T T NIL NIL T T T NIL T T T T T NIL T NIL T T T NIL NIL T T T T NIL NIL NIL T T T So we see that the formula always returns [47mT[0m and is thus a tautology. Recall that in the original example at the top of this page we were trying to prove the formula (implies (endp z) (implies (true-listp z) (equal (rev (rev z)) z))) This formula is an instance (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of (implies p (implies q r)). The substitution required by the match is [3msigma[0m: ((p (endp z)) (q (true-listp z)) (r (equal (rev (rev z)) z))) Since we know the tautology: (iff (implies p (implies q r)) (implies (and p q) r)). is always true no matter what Boolean values [47mp[0m, [47mq[0m, and [47mr[0m have, then we know this instance of it (obtained by applying the substitution [3msigma[0m above) is always true: (iff (implies (endp z) [3mformula1'[0m (implies (true-listp z) (equal (rev (rev z)) z))) (implies (and (endp z) [3mformula2'[0m (true-listp z)) (equal (rev (rev z)) z))). Thus, if we're trying to prove [3mformula1'[0m it is permitted to try to prove [3mformula2'[0m instead, because they return the same truthvalue. This sketch of propositional reasoning in ACL2 is a little suspect because we didn't address the possibility that the substitution might replace the propositional variables by non-propositional terms. But the tautology was verified only on Boolean values for those variables. This actually works out because in ACL2 all propositional testing is done against [47mnil[0m and any non-[47mnil[0m value, including [47mt[0m, is as good as another. However, the tautology allows us to replace one formula by the other only in contexts in which we just care about propositional truth, i.e., whether the formula is [47mnil[0m or not. When we prove a formula in ACL2 we are really establishing that it never returns [47mnil[0m, i.e., no matter what the values of the variables, the value of the formula is non-[47mnil[0m. A very simple example of this is with Double Negation. (iff (not (not p)) p) is a tautology. This means that if we were trying to prove (implies (not (not p)) ...) we could transform it to (implies p ...). But if we were trying to prove: (equal (not (not p)) p) we could not prove it by using Double Negation! The formula above claims that [47m(not (not p))[0m and [47mp[0m have identical values. They do not! For example, [47m(not (not 3))[0m is [47mt[0m, not [47m3[0m. However, [47m(not (not 3))[0m and [47mt[0m are propositionally equivalent (i.e., satisfy [47miff[0m) because one is as good as the other in a test. [3mThat[0m is what Double Negation says. As long as you only use propositional formulas in propositional places this aspect of ACL2 should not affect you. Now please use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-q1-answer (introduction-to-the-theorem-prover) "The inductive step of the [47mrev-rev[0m proof --- Answer to Question 1 The correct answer to Question 1 in [logic-knowledge-taken-for-granted] is [3mChoice (iv)[0m. The Induction Step of the inductive proof of (implies (true-listp z) (equal (rev (rev z)) z)) for an induction on the linear list [47mz[0m is: [3mInduction Step[0m: (implies (and (not (endp z)) (implies (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z)))) (implies (true-listp z) (equal (rev (rev z)) z))) The second hypothesis above is the [3minduction hypothesis[0m. The conclusion above is the formula we are trying to prove. Each induction hypothesis is [3malways[0m an instance (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of the formula being proved, i.e., it is obtained from the formula being proved by uniformly replacing the variables in the formula with terms. Notice how the induction hypothesis above is the same as the induction conclusion, except that all the [47mz[0ms have been replaced by [47m(cdr z)[0m. If you thought the right answer was [3mInduction Step -- Choice (i)[0m: (implies (not (endp z)) (implies (true-listp z) (equal (rev (rev z)) z))) then perhaps you didn't understand that we're doing an inductive proof. Certainly if you prove the Base Case already discussed and you prove [3mChoice (i)[0m above, then you will have proved the goal conjecture, but you would have done it by simple case analysis: prove it when [47m(endp z)[0m and prove it when [47m(not (endp z))[0m. While logically valid, you probably can't prove [3mChoice (i)[0m directly because you have no induction hypothesis to work with. If you thought the right answer was: [3mInduction Step -- Choice (ii)[0m: (implies (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z))) then perhaps you misunderstand the difference between the [3mInduction Step[0m and the [3mInduction Hypothesis[0m. The Induction [3mStep[0m is the ``other half'' of the main proof, balancing the Base Case. The Induction [3mHypothesis[0m is just a hypothesis you get to use during the Induction Step. The question Q1 asked what is the Induction Step. If you thought the right answer was: [3mInduction Step -- Choice (iii)[0m: (implies (and (not (endp z)) (equal (rev (rev (cdr x))) (cdr x))) ; [3m``induction hyp''[0m (implies (true-listp z) (equal (rev (rev z)) z))) then you are making the most common mistake newcomers make to induction. You are giving yourself an ``induction hypothesis'' that is not an instance of the conjecture you're proving. This alleged induction hypothesis says that [47m(rev (rev (cdr x)))[0m is [47m(cdr x)[0m, whereas the correct induction hypothesis says those two terms are equal [3mif[0m [47m(true-listp (cdr x))[0m. This alleged induction hypothesis is a stronger claim than we're trying to prove. It turns out that by making this mistake you can ``prove'' conjectures that are not always true! Remember: the induction hypothesis is always an instance of the conjecture you're proving, not just some piece of it. Of course, ACL2 ``knows'' this and will never make this mistake. But we remind you of it because there may be times when you intuit a different hypothesis and don't understand why ACL2 doesn't use it. If this doesn't make sense, perhaps you should read about induction (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF]) again. When you understand why [3mChoice (iv)[0m is the correct answer, use your browser's [31;1mBack Button[0m to return to [logic-knowledge-taken-for-granted] and go to question Q2.") (logic-knowledge-taken-for-granted-q2-answer (introduction-to-the-theorem-prover) "The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2 The correct answer to Question 2 in [logic-knowledge-taken-for-granted] is [3mSubgoal (i)[0m plus any one of the other other three. For your reference, the four choices were: [3mSubgoal (i)[0m: (implies (and (not (endp z)) (true-listp z)) (true-listp (cdr z))) [3mSubgoal (ii)[0m: (implies (and (not (endp z)) (true-listp z) (equal (rev (rev (cdr z))) (cdr z))) (equal (rev (rev z)) z)) [3mSubgoal (iii)[0m: (implies (and (not (endp z)) (equal (rev (rev (cdr z))) (cdr z))) (equal (rev (rev z)) z)) [3mSubgoal (iv)[0m: (implies (and (not (endp z)) (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z))) (equal (rev (rev z)) z)) In particular, it is wrong to think the Induction Step of the proof of (implies (true-listp z) (equal (rev (rev z)) z)) can be established by proving just [3mSubgoal (ii)[0m, [3mSubgoal (iii)[0m, [3mSubgoal (iv)[0m, or combinations of those three. You must also prove [3mSubgoal (i)[0m or something like it! The Inductive Step for the conjecture above is [3mInduction Step[0m: (implies (and (not (endp z)) ; [3mInduction Hypothesis[0m: (implies (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z)))) ; [3mInduction Conclusion[0m: (implies (true-listp z) (equal (rev (rev z)) z))) Note that the Inductive Hypothesis is an implication: (implies (true-listp (cdr z)) (equal (rev (rev (cdr z))) (cdr z))) This hypothesis can be true two different ways. The ``normal'' way --- the way everybody remembers --- is that [47m(true-listp (cdr z))[0m is true and thus [47m(equal (rev (rev (cdr z))) (cdr z))[0m is true. But the way many people forget is that [47m(true-listp (cdr z))[0m is false. You must prove the Induction Step even in this ``forgettable'' case. In this case, the Induction Step simplifies to [3mInduction Step[0m: (implies (and (not (endp z)) (not (true-listp (cdr z)))) (implies (true-listp z) (equal (rev (rev z)) z))) By Promotion (see the list of tautologies in our discussion of propositional calculus (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS])) this is [3mInduction Step'[0m: (implies (and (not (endp z)) (not (true-listp (cdr z))) (true-listp z)) (equal (rev (rev z)) z)) Using the Contrapositive and rearranging the order of the hypotheses (see propositional calculus (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]) again), this is [3mInduction Step''[0m: (implies (and (not (endp z)) (true-listp z) (not (equal (rev (rev z)) z))) (true-listp (cdr z))) Notice that [3mSubgoal (i)[0m implies [3mInduction Step''[0m: [3mSubgoal (i)[0m: (implies (and (not (endp z)) (truelistp z)) (truelistp (cdr z))) Every inductive proof of an implication raises a case like this. If we denote the conjecture [47m(implies p q)[0m as [47mp ---> q[0m, then the Induction Step will look like this: ( c & (p' ---> q')) ---> (p ---> q) where [47mc[0m is the test that determines the inductive step, (e.g., [47m(not (endp z))[0m) and [47mp'[0m and [47mq'[0m are inductive instances of [47mp[0m and [47mq[0m. Promotion produces ( c & p & (p' ---> q')) ---> q It is then very common to prove that [47mp[0m implies [47mp'[0m, [3m(i)[0m: (c & p) ---> p' and then prove that [47mq'[0m implies [47mq[0m, [3m(ii)[0m: (c & p & q') ---> q These correspond exactly to our choices [3mSubgoal (i)[0m and [3mSubgoal (ii)[0m. It is sometimes helpful to remember this diagram: (c & (p' ---> q') ^ | | | | v --> (p ---> q ) When you understand why [3mSubgoals (i)[0m and [3m(ii)[0m are sufficient, use your browser's [31;1mBack Button[0m to return to [logic-knowledge-taken-for-granted] and go to question Q3.") (logic-knowledge-taken-for-granted-q3-answer (introduction-to-the-theorem-prover) "The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2 The correct answer to Question 3 in [logic-knowledge-taken-for-granted] is that you need to prove [3mSubgoal to Relieve Hyp 1[0m: (implies (and (q (f a)) (r a)) (p (f a))) in order to use [3mTheorem[0m: (implies (p (f x)) (equal (g (h x)) x)) to rewrite the target [47m(g (h a))[0m to [47ma[0m in [3mGoal Conjecture[0m: (implies (and (q (f a)) (r a)) (s (g (h a)))) If you don't see why, re-read the discussion of rewriting (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING]) again. Forgetting about the need to relieve hypotheses is a common mistake in informal proofs. ACL2 won't forget to relieve them. But if you forget about the need to do it, you may be confused when ACL2 doesn't see the ``proof'' you see! Now use your browser's [31;1mBack Button[0m to return to the end of quiz in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-rewriting (introduction-to-the-theorem-prover) "A brief explanation of rewriting from the logical perspective First we give two examples of rewriting. Then we give a rather detailed description. We recommend you read the description, even if you understand the two examples, just so that you learn our terminology. [31;1mExample 1[0m: Suppose your goal conjecture is: [3mGoal Conjecture[0m: (implies (and (endp z) (true-listp z)) (equal (rev (rev z)) z)) Then you can use the following theorem (actually the definitional axiom introduced by the [47mdefun[0m of [47mendp[0m): [3mDefinitional Axiom[0m: endp (equal (endp x) (not (consp x))). to [3mrewrite[0m the [3mGoal Conjecture[0m to [3mRewritten Goal Conjecture[0m: (implies (and (not (consp z)) (true-listp z)) (equal (rev (rev z)) z)) Note that in this example, rewriting replaced the call of [47mendp[0m by its body after instantiating its body with the actuals from the call. This is sometimes just called [3mexpanding[0m the definition of [47mendp[0m. (The notions of [3mformal[0m, [3mbody[0m, [3mcall[0m, and [3mactuals[0m are discussed in [programming-knowledge-taken-for-granted].) Expanding a definition is an example of [3munconditional[0m rewriting. All definitions in ACL2 are just bare equalities relating a call of the function on its formals to its body. Any time you use an equality theorem, whether a definitional equality or something more general like (equal (append (append x y) z) (append x (append y z))) to replace an instance of one side by the corresponding instance of the other in a goal conjecture, we call that [3munconditional[0m rewriting with the equality. [31;1mExample 2[0m: Suppose your goal conjecture is: [3mGoal Conjecture[0m: (implies (and (subsetp a b) (true-listp b) (member e a)) (< (len (rm e b)) (len b))). This conjecture may be read ``if [47ma[0m is a subset of the [47mtrue-listp[0m [47mb[0m and [47me[0m is a member of [47ma[0m, then the result of removing [47me[0m from [47mb[0m has a shorter length than [47mb[0m.'' You can use the following theorem: [3mTheorem[0m: (implies (member u v) (equal (len (rm u v)) (- (len v) 1))) to [3mrewrite[0m the [3mGoal Conjecture[0m to [3mRewritten Goal Conjecture[0m: (implies (and (subsetp a b) (true-listp b) (member e a)) (< (- (len b) 1) (len b))). To do this you must know that the following subgoal is provable: [3mSubgoal to Relieve Hyp 1[0m: (implies (and (subsetp a b) (true-listp b) (member e a)) (member e b)). This is an example of [3mconditional[0m rewriting. In order to use the [3mTheorem[0m we had to establish that its hypotheses are satisfied. That is called [3mrelieving the hypotheses[0m and was done by proving the [3mSubgoal to Relieve Hyp 1[0m. Conditional rewriting is the most commonly used proof technique in ACL2. Unconditional rewriting is just a special case, where there are no hypotheses to relieve. Expanding a definition is just another special case, where there are no hypotheses to relieve and the pattern is easy to match because it is a call of a function on distinct variables. This page discusses [3mrewriting[0m from the logical perspective. It is important that you are familiar with the notions of a [3mtarget[0m term being an instance (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of a [3mpattern[0m term. We often say the pattern [3mmatches[0m the target. These notions involve a corresponding [3msubstitution[0m of terms for variables. All these notions are discussed in the link for ``instance (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE])'' above and we recommend you read it before continuing. Then use your browser's [31;1mBack Button[0m to come back here. You should also be aware of the terms introduced in our discussion of propositional calculus (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]). [3mRewriting[0m is a fundamental rule of inference in our system. The rule allows you to use a theorem, i.e., an axiom, lemma, or definition, to replace one term by another in the goal conjecture you're trying to prove. Suppose you have a theorem that is of the form (or can be put into the form): [3mTheorem[0m: (implies (and [3mhyp1[0m ... [3mhypk[0m) (equal [3mpattern[0m [3mreplacement[0m)) From the logical perspective we don't care how the theorem was actually written when it was proved. It might have no hypotheses (in which case the [3mhypi[0m could just be [47mt[0m), or it could have been written in a different but equivalent propositional style, [47m(or (not[0m [3mhyp1[0m[47m) ...)[0m, or the equality could have been written the other way around, [47m(equal [0m[3mreplacement[0m [3mpattern[0m[47m)[0m. Such syntactic details don't matter. Just take a theorem and use propositional calculus to rearrange it equivalently into this form for the purposes of this one rewrite step. Suppose some target term, [3mtarget[0m that occurs in your goal conjecture is an instance of [3mpattern[0m. Let the corresponding substitution be [3msigma[0m. If [3msigma[0m does not contain a binding for every variable that occurs in [3mTheorem[0m, then extend [3msigma[0m to [3msigma'[0m by adding one binding for each such variable. (This is necessary only if [3mpattern[0m does not contain every variable in [3mTheorem[0m.) Let [3mreplacement'[0m be the result of instantiating [3mreplacement[0m with [3msigma'[0m. Let [3mhypi'[0m be the result of instantiating [3mhypi[0m with [3msigma'[0m. Then the [31;1mRewrite Rule of Inference[0m tells us it is permitted to replace that occurrence of [3mtarget[0m in the goal by [3mreplacement'[0m --- [31;1mif you can prove[0m each [3mhypi'[0m in this context. We make this last condition clear in a moment. The justification for this is that [3mTheorem[0m is true for all values of the variables. Hence, it is true for the values specified by [3msigma'[0m. If the [3mhypi'[0m are true, then the target is really equal to [3mreplacement'[0m. But it is always permitted to replace something by something it's equal to. Rewriting thus involves several steps: (1) Finding a [3mtarget[0m and a [3mtheorem[0m to use to rewrite it to some more desirable [3mreplacement[0m. (2) Instantiating [3mpattern[0m in the (rearranged) theorem to match [3mtarget[0m. (3) Extending [3msigma[0m to [3msigma'[0m to bind all the variables in [3mTheorem[0m. (4) Establishing that the [3msigma'[0m instances of each of the [3mhypi[0m hold. This is called [3mrelieving the hypotheses[0m of the theorem and is discussed in greater detail below. (5) Replacing the occurrence of [3mtarget[0m in the goal conjecture by the [3msigma'[0m instance of [3mreplacement[0m, provided all the hypotheses are relieved. Step (4) above, [3mrelieving the hypotheses[0m, requires first identifying the ``context'' of the target in the goal conjecture. To do this, use propositional calculus to rearrange the goal conjecture so the occurrence of [3mtarget[0m is in the conclusion and let [3mcontext[0m be the hypothesis. [3mRearranged Conjecture[0m: (implies [3mcontext[0m (... [3mtarget[0m ...)) To relieve the hypotheses you must then prove each of the following subgoals: [3mSubgoal to Relieve Hyp i[0m: (implies [3mcontext[0m [3mhypi'[0m). It is important to note that this description of rewriting with [3mTheorem[0m describes the process from a strictly logical perspective. The syntax of the theorem and the goal don't matter. You're free to use propositional calculus to rearrange them to put them into the appropriate forms to fit the descriptions given. Clearly, if you have a candidate Theorem in the ``wrong'' form and but it can be rearranged with propositional calculus into the ``right'' form, then that rearranged theorem is also a [3mTheorem[0m and can be used as described. But in the actual implementation of ACL2, the syntactic form of a proved [3mTheorem[0m affects how it is used by rewriting. If a proved theorem takes the form of an implication concluding with an equality, ACL2 treats the left-hand side of the equality as [3mpattern[0m and the right-hand side as [3mreplacement[0m, unless you tell it otherwise. We'll discuss this later. Furthermore, being from the logical perspective this discussion of rewriting does not address (a) how you extend [3msigma[0m to [3msigma'[0m --- any extension will do provided it allows you to relieve the hypotheses. The ACL2 theorem prover uses certain heuristics which we'll discuss later, including methods by which you can guide the system in the selection. Crucially, it does not discuss whether it is a [3mgood idea[0m to do a particular rewrite! For example, the definitional equality: (equal (len x) (if (endp x) 0 (+ 1 (len (cdr x))))) may be used repeatedly, endlessly, to replace [47m(len a)[0m by an ever growing sequence of terms: (len a) = (if (endp a) 0 (+ 1 (len (cdr a)))) = (if (endp a) 0 (+ 1 (if (endp (cdr a)) 0 (+ 1 (len (cdr (cdr a))))))) = ... The ACL2 implementation of rewriting uses certain heuristics and you can guide the system in its choices. We'll discuss this later. Now use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-knowledge-taken-for-granted-rewriting-repeatedly (introduction-to-the-theorem-prover) "Further information on expanding definitions via rewriting We assume you've read about ``instances (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE])'' and picked up our basic terminology including the ideas of [3mmatching[0m a [3mpattern[0m term to a [3mtarget[0m term, obtaining a [3msubstitution[0m and how to [3minstantiate[0m a term with a substitution. We use these notions below without further citation. In addition, we assume you've read about ``rewriting (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING])'' where we introduced the idea of treating a theorem (axiom, definition, or lemma) as a [3mconditional rewrite[0m rule and replaced one term by an equivalent one provided we can [3mrelieve the hypotheses[0m. Suppose you're trying to prove [3mformula1[0m and you transform it to [3mformula2[0m by rewriting. What happened? [3mformula1[0m: (implies (and (not (consp z)) (true-listp z)) (equal (rev (rev z)) z)) [3mformula2[0m: (implies (and (not (consp z)) (equal z nil)) (equal (rev (rev z)) z)) Evidently we replaced [47m(true-listp z)[0m by [47m(equal z nil)[0m. But how did that happen? What really happened was the sequential application of several unconditional rewrites and the use of replacement of equals by equals. The definition of [47mtrue-listp[0m is: (defun true-listp (x) (if (consp x) (true-listp (cdr x)) (equal x nil))). By rewriting once with the definition of [47mtrue-listp[0m, we transform [3mformula1[0m to: [3mformula1'[0m: (implies (and (not (consp z)) (if (consp z) (true-listp (cdr z)) (equal z nil))) (equal (rev (rev z)) z)). Note how the call of [47mtrue-listp[0m has been replaced by the entire body of [47mtrue-listp[0m. Next, note that the first hypothesis above is that [47m(consp z)[0m is false. That is, [47m(not (consp z))[0m is the same as [47m(equal (consp z) nil)[0m. Thus, replacement of equals by equals means we can transform [3mformula1'[0m to [3mformula1''[0m: (implies (and (not (consp z)) (if nil (true-listp (cdr z)) (equal z nil))) (equal (rev (rev z)) z)). (We will explore replacement of equals by equals later.) Furthermore, we know the basic axiom about [47mif[0m: [3mAxiom[0m if-nil: (if nil x y) = y. Rewriting with this particular axiom, using [47m(if nil x y)[0m as the pattern and [47my[0m as the replacement, will transform [3mformula1''[0m to [3mformula2[0m: (implies (and (not (consp z)) (equal z nil)) (equal (rev (rev z)) z)). Often when we say we derived one formula from another by ``expansion'' and or by ``rewriting'' we take many rewrite steps, as here. We typically use hypotheses of the formula without noting ``replacement of equals by equals'' as when we replaced [47m(consp z)[0m by [47mnil[0m, and we typically omit to mention the use of basic axioms like [47mif-nil[0m above. Now use your browser's [31;1mBack Button[0m to return to the example proof in [logic-knowledge-taken-for-granted].") (logic-term-list-listp (termp acl2-built-ins) "Recognizer for lists of lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols This predicate strengthens [47m(term-list-listp x wrld)[0m, as it also requires [47m(logic-fns-list-listp x wrld)[0m, i.e., that every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in the [world], [47mwrld[0m. [31;1mFunction: [0m<logic-term-list-listp> (defun logic-term-list-listp (x w) (declare (xargs :guard (plist-worldp-with-formals w))) (and (term-list-listp x w) (logic-fns-list-listp x w)))") (logic-term-listp (termp acl2-built-ins) "Recognizer for lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols This predicate strengthens [47m(term-listp x wrld)[0m, as it also requires [47m(logic-fns-listp x wrld)[0m, i.e., that every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in the [world], [47mwrld[0m. [31;1mFunction: [0m<logic-term-listp> (defun logic-term-listp (x w) (declare (xargs :guard (plist-worldp-with-formals w))) (and (term-listp x w) (logic-fns-listp x w)))") (logic-termp (termp acl2-built-ins) "Recognizer for [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols This predicate strengthens [47m(termp x wrld)[0m, as it also requires [47m(logic-fnsp x wrld)[0m, i.e., that every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in the [world], [47mwrld[0m. [31;1mFunction: [0m<logic-termp> (defun logic-termp (x wrld) (declare (xargs :guard (plist-worldp-with-formals wrld))) (and (termp x wrld) (logic-fnsp x wrld)))") (logical-name (events world) "A name created by a logical event Examples: assoc caddr + "ACL2-USER" :here A logical name is either a name introduced by some event, such as [47m[defun][0m, [47m[defthm][0m, or [47m[defpkg][0m, or else is the keyword [47m:here[0m, which refers to the most recent such event. See [events]. Every logical name is either a symbol or a package name (a string). For the syntactic rules on names, see [name]. The symbols name functions, macros, constants, axioms, theorems, labels, and [theories]. The strings name packages. We permit the keyword symbol [47m:here[0m to be used as a logical name denoting the most recently completed event. Logical names are used primarily in the theory manipulation functions, e.g., [47m[universal-theory][0m and [47m[current-theory][0m with which you may obtain some standard [theories] as of some point in the historical past. The reference points are the introductions of logical names, i.e., the past is determined by the [events] it contains. One might ask, ``Why not discuss the past with the much more flexible language of [command] descriptors?'' (See [command-descriptor].) The reason is that inside of such [events] as [47m[encapsulate][0m or macro [command]s that expand to [47m[progn][0ms of [events], [command] descriptors provide too coarse a grain. When logical names are used as referents in theory expressions used in [books], one must consider the possibility that the defining event within the book in question becomes redundant by the definition of the name prior to the assumption of the book. See [redundant-events].") (logicp (pointers) "See [system-utilities].") (logior (numbers acl2-built-ins) "Bitwise logical inclusive or of zero or more integers When integers are viewed in their two's complement representation, [47mlogior[0m returns their bitwise logical inclusive or. In ACL2 [47mlogior[0m is a macro that expands into calls of the binary function [47mbinary-logior[0m, except that [47m(logior)[0m expands to [47m0[0m and [47m(logior x)[0m expands to [47m(the integer x)[0m. The [guard] for [47mbinary-logior[0m requires its arguments to be integers. [47mLogior[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mMacro: [0m<logior> (defmacro logior (&rest args) (cond ((null args) 0) ((null (cdr args)) (cons 'the (cons 'integer (cons (car args) 'nil)))) (t (xxxjoin 'binary-logior args)))) [31;1mFunction: [0m<binary-logior> (defun binary-logior (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (lognot (logand (lognot i) (lognot j))))") (lognand (numbers acl2-built-ins) "Bitwise logical `nand' of two integers When integers are viewed in their two's complement representation, [47mlognand[0m returns their bitwise logical `nand'. The [guard] for [47mlognand[0m requires its arguments to be integers. [47mLognand[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<lognand> (defun lognand (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (lognot (logand i j)))") (lognor (numbers acl2-built-ins) "Bitwise logical `nor' of two integers When integers are viewed in their two's complement representation, [47mlognor[0m returns the bitwise logical `nor' of the first with the second. The [guard] for [47mlognor[0m requires its arguments to be integers. [47mLognor[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<lognor> (defun lognor (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (lognot (logior i j)))") (lognot (numbers acl2-built-ins) "Bitwise not of a two's complement number [47m(lognot i)[0m is the two's complement bitwise [47m`not'[0m of the integer [47mi[0m. [47mLognot[0m is actually defined by coercing its argument to an integer (see [ifix]), negating the result, and then subtracting [47m1[0m. The [guard] for [47mlognot[0m requires its argument to be an integer. [47mLognot[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<lognot> (defun lognot (i) (declare (xargs :guard (integerp i))) (+ (- (ifix i)) -1))") (logorc1 (numbers acl2-built-ins) "Bitwise logical inclusive or of two ints, complementing the first When integers are viewed in their two's complement representation, [47mlogorc1[0m returns the bitwise logical inclusive or of the second with the bitwise logical `not' of the first. The [guard] for [47mlogorc1[0m requires its arguments to be integers. [47mLogorc1[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logorc1> (defun logorc1 (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (logior (lognot i) j))") (logorc2 (numbers acl2-built-ins) "Bitwise logical inclusive or of two ints, complementing the second When integers are viewed in their two's complement representation, [47mlogorc2[0m returns the bitwise logical inclusive or of the first with the bitwise logical `not' of the second. The [guard] for [47mlogorc2[0m requires its arguments to be integers. [47mLogorc2[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logorc2> (defun logorc2 (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (logior i (lognot j)))") (logtest (numbers acl2-built-ins) "Test if two integers share a `1' bit When integers [47mx[0m and [47my[0m are viewed in their two's complement representation, [47m(logtest x y)[0m is true if and only if there is some position for which both [47mx[0m and [47my[0m have a `1' bit in that position. The [guard] for [47mlogtest[0m requires its arguments to be integers. [47mLogtest[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<logtest> (defun logtest (x y) (declare (xargs :guard (and (integerp x) (integerp y)))) (not (zerop (logand x y))))") (logxor (numbers acl2-built-ins) "Bitwise logical exclusive or of zero or more integers When integers are viewed in their two's complement representation, [47mlogxor[0m returns their bitwise logical exclusive or. In ACL2 [47mlogxor[0m is a macro that expands into calls of the binary function [47mbinary-logxor[0m, except that [47m(logxor)[0m expands to [47m0[0m and [47m(logxor x)[0m expands to [47m(the integer x)[0m. The [guard] for [47mbinary-logxor[0m requires its arguments to be integers. [47mLogxor[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mMacro: [0m<logxor> (defmacro logxor (&rest args) (cond ((null args) 0) ((null (cdr args)) (cons 'the (cons 'integer (cons (car args) 'nil)))) (t (xxxjoin 'binary-logxor args)))) [31;1mFunction: [0m<binary-logxor> (defun binary-logxor (i j) (declare (xargs :guard (and (integerp i) (integerp j)))) (lognot (logeqv i j)))") (loop$ (acl2-built-ins programming) "Iteration with an analogue of the Common Lisp [47mloop[0m macro [47mLoop$[0m is the ACL2 analogue of the Common Lisp's iteration primitive, [47mloop[0m. This topic introduces the two classes of ACL2 [47mloop$[0m expressions, [47mFOR[0m [47mloop$[0ms and [47mDO[0m [47mloop$[0ms; see [for-loop$] and [do-loop$] (respectively) for their full documentation. [47mLoop$[0m was introduced into ACL2 in Version 8.2 (May, 2019), over 20 years after ACL2 was first released. So there are many experienced ACL2 users who have never used [47mloop$[0m. The [47mLoop$[0m Primer, see [loop$-primer], is textbook-style introduction, meant to be read linearly and may be a good starting place for you. The primer follows a ``monkey-see monkey-do'' approach, showing lots of examples. Sample proofs are worked out in detail and then the reader is challenged to apply those lessons to exercises. Solutions to the exercises are provided in books among the Community Books. Depending on your preferred learning style and familiarity with [47mloop$[0m and ACL2 in general, you might want to work your way through the primer (see [loop$-primer]) instead of bouncing around the hypertext user's manual. The Introduction below is followed by a discussion of types and guards. For a discussion of how to state effective lemmas about [47mloop$[0ms and how to prove inductive theorems about [47mloop$[0ms see [stating-and-proving-lemmas-about-loop$s]. Also, for a summary of how the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m [scion]s, see [rewriting-calls-of-apply$-ev$-and-loop$-scions]. But before we get started we emphasize a few key points. * As noted, The Loop$ Primer (see [loop$-primer]) may be a good place to start if you're using ACL2 [47mloop$[0ms for the first time. * The Table of Contents of the Loop$ Primer (see [lp-section-0]) lists some sensible entry points to the primer. You'll see sections devoted to examples, sample proofs, exercises, etc. Keep the primer in mind as an additional resource. For example, you might visit [47mLoop$[0m Primer Section 6 ([lp-section-6]) for some exercises on writing [47mloop$[0ms and, when you get to the end, ignore the ``Now go to [lp-section-7],'' and use your browser's Back key to return to the general hypertext user's manual. * [31;1mMany examples[0m of [47m[loop$][0m expressions may be found in [community-book] [47mprojects/apply/loop-tests.lisp[0m. * The semantics of [47mloop$[0m involve [47mapply$[0m. Therefore, before using [47mloop$[0m, it is [31;1mstrongly recommended[0m that you include the same book as is typically included when using [47m[apply$][0m, as follows. (include-book "projects/apply/top" :dir :system) * ACL2 [47mloop$[0m statements are executed as Common Lisp [47mloop[0m statements after the relevant [guard] conjectures are proved. Common Lisp [47mloop[0m statements generally execute much faster than equivalent (tail-recursive) functions. * [31;1mWarning:[0m [47mLoop$[0m implements only a modest part of the functionality of Common Lisp's [47mloop[0m. Aside from the simple fact that [47mloop$[0m allows only a limited subset of the syntax of [47mloop[0m, the main restriction is that the subexpressions of the [47mloop$[0m expression that are evaluated repeatedly must be [tame]! These expressions include not only the loop body but, if present, the [47mUNTIL[0m test, the [47mWHEN[0m test, and the [47mFINALLY[0m clause (all discussed below). Thus, all the function symbols used in these expressions must be [badge]d (see [47m[defbadge][0m and [47m[defwarrant][0m). Further restrictions are enforced for [47m[defun][0m'd functions in which recursive calls appear in [47mloop$[0m bodies, but we say little about that in this documentation topic; see [loop$-recursion]. We recommend that users unfamiliar with [47mloop$[0m acquaint themselves with the material below and in [for-loop$] before wading into [47mloop$-recursion[0m! Introduction to [47mloop$[0m As noted above, there are two classes of [47mloop$[0m expressions. These are identified as follows. * [47mFOR[0m loop$ expressions: (loop$ FOR ...) * [47mDO[0m loop$ expressions: (loop$ WITH ... DO ...) Below we introduce these two classes of [47mloop$[0m expressions. For full documentation see the topic for each class: see [for-loop$] for [47mFOR[0m [47mloop$[0ms and [do-loop$] for [47mDO[0m [47mloop$[0ms. In particular various restrictions are discussed in those topics, but for now we mention just the following. While [47mFOR[0m [47mloop$[0m expressions are often more convenient to use than [47mDO[0m [47mloop$[0m expressions, their [47mUNTIL[0m, [47mWHEN[0m, and body expressions are not permitted to reference [47m[state][0m or [stobj]s, and they always return a single value. [47mDO[0m [47mloop$[0m expressions do not have these restrictions, but they may not use the idioms of [47mFOR[0m [47mloop$[0ms, like ``[47mFOR x IN ...[0m'' or ``[47mUNTIL p[0m''. ACL2's [47mloop$[0m is considerably more restrictive than Common Lisp's [47mloop[0m, but when an ACL2 [47mloop$[0m expression is translated without error it has the same meaning as the corresponding Common Lisp [47mloop[0m. [47mLoop$[0m supports [47m:[0m[47m[guard][0m expressions (discussed below) in certain places and these are ignored by Common Lisp. Next we present some [47mFOR[0m [47mloop$[0m examples. They illustrate the three supported forms of [47mFOR[0m [47mloop$[0m iteration: the use of [47mIN[0m, to iterate over elements of a list; the use of [47mON[0m, to iterate over the non-empty tails of a list; and the use of [47mFROM .. TO[0m, to iterate over a range of integers (optionally with [47mBY[0m to specify the increment at each step). These examples also illustrate the use of [47mWHEN[0m to restrict which iterations are considered and the use of [47mUNTIL[0m to terminate early. Additional keywords illustrated are [47mOF-TYPE[0m to specify types and [47mAS[0m to specify additional iteration variables. They also illustrate some of the operations permitted at each iteration, such as [47mSUM[0m and [47mCOLLECT[0m. ACL2 !>(loop$ for x in '(1 2 3) sum (* x x)) 14 ACL2 !>(loop$ for x in '(1 2 3) collect (* x x)) (1 4 9) ACL2 !>(loop$ for x on '(1 2 3) collect x) ((1 2 3) (2 3) (3)) ACL2 !>(loop$ for x of-type integer from -10 to 10 by 2 collect x) (-10 -8 -6 -4 -2 0 2 4 6 8 10) ACL2 !>(loop$ for i from 1 to 10 as x in '(a b c d e f g) collect (cons i x)) ((1 . A) (2 . B) (3 . C) (4 . D) (5 . E) (6 . F) (7 . G)) ACL2 !>(loop$ for i from 1 to 10 as x in '(a b c d e f g) until (> i 6) collect (cons i x)) ((1 . A) (2 . B) (3 . C) (4 . D) (5 . E) (6 . F)) ACL2 !>(loop$ for i from 1 to 10 as x in '(a b c d e f g) until (> i 6) when (evenp i) collect (cons i x)) ((2 . B) (4 . D) (6 . F)) Finally we present two [47mDO[0m [47mloop$[0m examples. We explore them further in the documentation specific to [47mDO[0m [47mloop$[0m expressions; see [do-loop$]. Our first [47mDO[0m [47mloop$[0m example shows iteration with the indicated initial values for local variables [47mx[0m and [47my[0m. They are modified at each iteration through the loop until [47mx[0m is empty, at which point the value of [47my[0m is returned. (See [do-loop$] for more thorough explanations.) ACL2 !>(loop$ with x = '(a b c) with y = nil do (cond ((consp x) (progn (setq y (cons (car x) y)) (setq x (cdr x)))) (t (return y)))) (C B A) ACL2 !> Our second example of a [47mDO[0m [47mloop$[0m expression illustrates more features than the first. Also, it illustrates the use of a [47mloop$[0m expression inside a definition, which is allowed for both [47mFOR[0m [47mloop$[0ms and [47mDO[0m [47mloop$[0ms. We see here that [stobj]s and [multiple-value] returns are allowed for [47mDO[0m [47mloop$[0ms, where the [47m:VALUES[0m keyword specifies the shape of the return. We also see here the use of the optional [47m:GUARD[0m keyword of a [47mloop$[0m expression (legal for both classes of [47mloop$[0ms, as discussed further below) and the optional [47m:MEASURE[0m keyword of a [47mDO[0m [47mloop$[0m expression. But notice the [47m[defwarrant][0m events below! They are required because the functions [47mfld[0m and [47mupdate-fld[0m are not system primitives. They are introduced by the user's [47m[defstobj][0m event below. This is in contrast to the [47mDO[0m [47mloop$[0m in our first example above where no warrants are required because all the functions in that example are primitive. The semantics of [47mloop$[0m involve [47mapply$[0m and thus [47mloop$[0ms inherit the restrictions imposed on [47mapply$[0m and its [scion]s. Among those restrictions are that (a) unwarranted [47m:logic[0m mode functions cannot be [47mapply$[0m'd in the top-level read-eval-print loop and (b) proofs about the applications of unwarranted functions are impossible. Restriction (a) means you cannot even execute a [47m:logic[0m mode [47mloop$[0m containing unwarranted functions. Restriction (b) means you can't verify the [guard]s of such [47mloop$[0m. This last point obviates the main reason for using [47mloop$[0m: its fast execution as a Common Lisp loop once guards are verified. Now here is our second example. (defstobj st fld) (include-book "projects/apply/top" :dir :system) ; needed for defwarrant (defwarrant fld) (defwarrant update-fld) (defun test-loop$ (i0 max st) (declare (xargs :guard (and (natp i0) (natp max)) :stobjs st)) (loop$ with i of-type (satisfies natp) = i0 with cnt of-type integer = 0 do :measure (nfix (- max i)) :guard (and (natp max) (natp cnt) (stp st)) :values (nil st) ; shape of return; can be omitted when it's (nil) (if (>= i max) (loop-finish) (progn (setq st (update-fld i st)) (mv-setq (cnt i) (mv (+ 1 cnt) (+ 1 i))))) finally :guard (stp st) (return (mv (list 'from i0 'to max 'is cnt 'steps 'and 'fld '= (fld st)) st)))) ACL2 !>(test-loop$ 3 8 st) ((FROM 3 TO 8 IS 5 STEPS AND FLD = 7) <st>) ACL2 !> Both classes of [47mloop$[0m expressions ([47mFOR[0m and [47mDO[0m [47mloop$[0ms) rely heavily on the ACL2 built-in function, [47m[apply$][0m: in each iteration through the loop, a [lambda] object based on the body of the [47mloop$[0m is given as the function argument of [47mapply$[0m. Similarly, the [47mUNTIL[0m and [47mWHEN[0m clauses of [47mFOR[0m [47mloop$[0ms and the [47m:measure[0m and [47mFINALLY[0m clauses of [47mDO[0m [47mloop$[0ms are translated into [47mlambda[0m objects. The functions in all those [47mlambda[0m objects must be warranted to evaluate the [47mloop$[0m and/or prove its properties (including its guards) because logically the application of an unwarranted function is undefined. (However, recall from [guarantees-of-the-top-level-loop] that [47m:program[0m mode functions do not need warrants, just badges, for execution in the evaluation theory.) The documentation for [47m[apply$][0m illustrates a simple [47mdefun[0m that is inadmissible because the measure theorem cannot be proved without a warrant and warrants cannot be assumed during the proofs of the measure conjectures. The same issue arises when one of the functions critically involved in a measure conjecture is defined using a [47mloop$[0m whose body involves a user-defined function. For a simple example of this issue and how to work around it, see [community-book] [47mbooks/demos/measure-and-warrant.lisp[0m. Types and guards in [47mloop$[0m expressions In this section we document basic aspects of the [47mOF-TYPE[0m and [47m:GUARD[0m keywords in [47m[loop$][0m expressions. See [for-loop$] and [do-loop$] for detailed documentation on guards for [47mFOR[0m and [47mDO[0m [47mloop$[0m expressions, respectively. [47mLoop$[0m expressions execute fastest when they are [guard] verified. But the [47mloop$[0m body raises interesting guard verification problems, as do the [47mUNTIL[0m and [47mWHEN[0m tests of a [47mFOR[0m [47mloop$[0m, because they are executed for many different values of the iteration variables. The [47mFINALLY[0m clause of a [47mDO[0m [47mloop$[0m raises a similar concern, since the values of its variables may be modified repeatedly by execution of the [47mloop$[0m body. It may be necessary to provide type information or even stronger invariants to verify guards for [47mloop$[0ms. We now provide a few examples illustrating the handling of guards in [47mloop$[0m. The first example below is an acceptable [47mloop$[0m expression but cannot be guard verified, as would be necessary if it appeared in a [47m[defun][0m that was to be guard verified. The problem is that [47m(+ 1 x)[0m requires [47mx[0m to be numeric and, in general, we don't know anything about the value of [47mx[0m here. (Actually, because the target range is just a constant below, ACL2 could deduce information about each value [47mx[0m takes on, but it doesn't.) The second example can be guard verified and has the advantage of being standard Common Lisp, so compilers might optimize the handing of [47m(+ 1 x)[0m. The third example can also be guard verified but since the [47m:GUARD[0m directive used here is ignored by Common Lisp it does not inform the compiler, so this example might execute more slowly than the previous one. The last example shows the syntax and use of the ACL2-specific addition to [47mloop$[0m: the [47m:GUARD[0m directive protecting, in this case, the [47mloop$[0m body. [47m:GUARD[0m is useful when you wish to add more guard information than can be expressed with the Common Lisp [47mOF-TYPE[0m directive. The [47mOF-TYPE[0m and [47m:GUARD[0m directives are conjoined to form the actual guard protecting the [47mloop$[0m body. ACL2 !>(loop$ for x in '(1 2 3) collect (+ 1 x)) (2 3 4) ACL2 !>(loop$ for x of-type integer in '(1 2 3) collect (+ 1 x)) (2 3 4) ACL2 !>(loop$ for x in '(1 2 3) collect :guard (integerp x) (+ 1 x)) (2 3 4) ACL2 !>(let ((max 10)) (loop$ for x of-type integer in '(1 2 3) collect :guard (and (integerp max) (< x max)) (- max x))) (9 8 7) The guard on the [47m(- max x)[0m above is [47m(and (integerp x) (integerp max) (< x max))[0m and the compiler is informed that [47mx[0m is an integer by the [47mOF-TYPE[0m. The examples just above are of [47mFOR[0m [47mloop$[0ms. Here is a [47mDO[0m [47mloop$[0m example that illustrates types and guards. ACL2 !>(loop$ with i of-type integer = 7 with ans = nil do :guard (true-listp ans) (progn (setq ans (cons i ans)) (setq i (- i 2)) (if (< i 0) (loop-finish) t)) finally :guard (true-listp ans) (return (reverse ans))) (7 5 3 1) ACL2 !> Neither [47m:GUARD[0m is necessary in order for this execution to complete. However, if this [47mloop$[0m is put into a definition --- [47m(defun foo () (loop$ ...))[0m --- then both [47m:GUARD[0m expressions are necessary in order for the definition to be [guard]-verified. As suggested above, when a [47mloop$[0m expression occurs in the body of a [guard]-verified function, it will be executed as a Common Lisp [47mloop[0m expression, which can be much more efficient than executing without such guard verification. This efficiency can also be gained in top-level [47mloop$[0m expressions if the [tau-system] completes (silently) the necessary guard verification. See [print-cl-cache]. Subtopics [Do$] Definition of [47mdo$[0m [Do-loop$] Iteration with [47m[loop$][0m using local variables and [stobj]s [For-loop$] Iteration with [47m[loop$][0m over an interval of integers or a list [Loop$-primer] Primer for using [47m[loop$][0m [Loop$-recursion] Defining functions that recur from within [47mFOR[0m [47mloop$[0m expressions [Loop$-recursion-induction] Advice on inductive theorems about [47m[loop$][0m-recursive functions [Stating-and-proving-lemmas-about-loop$s] Stating and proving theorems about [47mloop$[0ms") (loop$-do (pointers) "See [do-loop$].") (loop$-for (pointers) "See [for-loop$].") (loop$-primer (loop$ documentation programming) "Primer for using [47m[loop$][0m The Loop$ Primer Preface This primer was created at the request of and with the support of Warren Hunt. It was originally conceived as a standalone document, but it has been integrated into the ACL2 documentation to increase its utility. The ACL2 [47m[loop$][0m feature is an iteration primitive modeled on a small subset of the Common Lisp [47mloop[0m facility. This documentation is an elementary introduction to [47mloop$[0m for use in both programming and proofs. We assume the reader is already an experienced ACL2 user who is just new to [47mloop$[0m. [47mLoop$[0m exploits ACL2's ``higher order'' capability using [47m[apply$][0m. Logically, [47mloop$[0m expressions are translated into calls of [scion]s or ``mapping functions'' that map one or more [47m[lambda][0m objects over ranges. When [47mloop$[0m expressions are typed into the ACL2 top-level loop these formal semantics are executed, which can be inefficient. When [47mloop$[0m expressions are in [guard] verified (see [47m[verify-guards][0m) functions they are compiled into Common Lisp [47mloop[0m expressions and are executed very efficiently. Two issues complicate the situation. First, Common Lisp's [47mloop[0m facility is extraordinarily complex, requiring a full chapter of the reference manual to explain. See {loop | http://www.lispworks.com/documentation/HyperSpec/Body/m_loop.htm#loop} in the Common Lisp HyperSpec or Chapter 26 (pages 709-747) of Guy Steele's monumental [31;1mCommon Lisp The Language, Second Edition[0m. Second, ACL2's logic is first-order, not higher-order, and so the [47mapply$[0m-based semantics imposes restrictions that new users of ACL2 may find hard to deal with. This primer focuses on how to write [47mloop$[0m expressions and how to prove things about them. We start by asking you some questions that test your basic knowledge of ACL2, so that you can decide whether this primer is right for you. Then we discuss the so-called ``[47mFOR[0m'' [47mloop$[0m and later move on to the ``[47mDO[0m'' [47mloop$[0m. We follow the ``monkey see, monkey do'' teaching style. We informally and incompletely sketch the syntax and semantics, but we provide lots of examples and we offer many challenge problems for you to solve. Answers are also provided. There are two glaring omissions in this primer: [guard] verification and the use of [stobj]s in [47mDO[0m [47mloop$[0m. While guard verification is crucial to the efficient execution of [47mloop$[0ms by Common Lisp, we omitted much discussion of it because guard obligations are generated automatically and are generally just ``ordinary'' conjectures that we assume the experienced user can figure out how to prove. The newcomer to [47mloop$[0m may wonder ``why am I having to prove this?'' but the answer is always the same: ``the Common Lisp compiler requires this in order for [47mloop$[0m to behave like [47mloop[0m.'' Often the ``fix'' to a [47mloop$[0m guard verification problem is to add a [47m:guard[0m to the [47mloop$[0m body, remembering that it is translated into a [47mlambda[0m object that must be guard verified in isolation since it might be passed around and applied in many contexts. We include the syntax for [47mloop$[0m guards. We omitted much discussion of stobjs --- which are allowed in [47mDO[0m [47mloop$[0ms but not in other kinds of [47mloop$[0ms --- because they raise the same problems in [47mDO[0m [47mloop$[0ms as they do in ``ordinary'' uses: syntactic single-threadedness into, through, and out of expressions. We assume the experienced user knows how to deal with these issues. There is a strong emphasis in this primer on problems for you to work on. The best way to learn how to do something is to practice doing it! The primer is divided into subjects listed in the Table of Contents which is at the link [lp-section-0]. We recommend you read these sections in the order shown. Each section ends with a pointer to the next section but also includes a link to the Table of Contents. Now go to [lp-section-1]. The Table of Contents is at [lp-section-0]. Subtopics [Lp-section-0] Loop$ Primer Table of Contents) [Lp-section-1] Background Reviews [Lp-section-2] [47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2 [Lp-section-3] Examples of [47mFOR[0m [47mLoop$[0ms [Lp-section-4] Syntax of [47mFOR[0m [47mLoop$[0ms [Lp-section-5] Informal Semantics of [47mFOR[0m [47mLoop$[0ms [Lp-section-6] Challenge Problems about [47mFOR[0m [47mLoop$[0ms [Lp-section-7] Using [47mLoop$[0ms and Guards in [47mDefun[0ms [Lp-section-8] Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms [Lp-section-9] Semantics of [47mFOR[0m [47mLoop$[0ms [Lp-section-10] The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m [Lp-section-11] Proving Theorems about [47mFOR[0m [47mLoop$[0ms [Lp-section-12] Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms [Lp-section-13] Examples of [47mDO[0m [47mLoop$[0ms [Lp-section-14] Challenge Problems about [47mDO[0m [47mLoop$[0ms [Lp-section-15] Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms [Lp-section-16] Proving Theorems about [47mDO[0m [47mLoop$[0ms [Lp-section-17] Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms [Lp-section-18] Conclusion") (loop$-recursion (loop$) "Defining functions that recur from within [47mFOR[0m [47mloop$[0m expressions Examples (defun$ nat-treep (x) (declare (xargs :loop$-recursion t :measure (acl2-count x))) (cond ((atom x) (natp x)) (t (and (true-listp x) (eq (car x) 'NATS) (loop$ for e in (cdr x) always (nat-treep e)))))) (defun$ copy-nat-tree (x) (declare (xargs :loop$-recursion t :measure (acl2-count x))) (cond ((atom x) (if (natp x) (if (equal x 0) 0 (+ 1 (copy-nat-tree (- x 1)))) x)) (t (cons 'nats (loop$ for e in (cdr x) collect (copy-nat-tree e)))))) Notice that [47mnat-treep[0m and [47mcopy-nat-tree[0m each contain a simple [47mFOR[0m [47m[loop$][0m (also see [for-loop$]) in which the function being defined is called recursively. [47mCopy-nat-tree[0m is a little more complicated than [47mnat-treep[0m because [47mcopy-nat-tree[0m also contains a recursive call outside of any [47mloop$[0m. Notice also that both events specify the [47m[xargs][0m [47m:loop$-recursion t[0m and explicitly provide a [47m:measure[0m. The usual other [47mxargs[0m are optional but [47m:loop$-recursion t[0m is required if recursion is used inside a [47mFOR[0m [47mloop$[0m and the measure must be made explicit. Recursion is not allowed inside a [47mDO[0m [47mloop$[0m expression. In fact, ACL2 disallows the use of [47m:loop$-recursion[0m in the [47mxargs[0m of any definition whose body contains a [47mDO[0m [47mloop$[0m. So this topic is only about [47mFOR[0m [47mloop$[0ms. Some examples of [47mloop$[0m-recursive definitions may be found in the book [47mprojects/apply/loop-recursion-examples.lisp[0m. [31;1mWarning:[0m We advise you to use [47m[defun$][0m rather than [47m[defun][0m when introducing a [47m:logic[0m mode [47mloop$[0m-recursive function. When a [47mloop$[0m-recursive function is introduced it is assigned a badge. This is required because we cannot translate the body of a [47mloop$[0m-recursive function without a badge. However, no warrant is assigned by [47mdefun[0m. But it is impossible to reason about applications (with [47m[apply$][0m) of unwarranted functions. Indeed, it is even impossible to execute such applications in the top-level ACL2 read-eval-print loop. See [guarantees-of-the-top-level-loop]. So a [47m:logic[0m mode [47mloop$[0m-recursive function --- which is guaranteed to involve applications of itself with [47mapply$[0m --- can't be reasoned about or executed (except on data not exercising the recursive calls inside [47mloop$[0ms). These inconveniences can be avoided by using [47mdefun$[0m when introducing [47m:logic[0m mode [47mloop$[0m-recursive functions because [47mdefun$[0m expands to a [47mdefun[0m followed by a [47m[defwarrant][0m. [31;1mWarning:[0m Even though the functions defined above are recursive, ACL2 does not generate induction schemes for them! If you want to do inductive proofs about [47mloop$[0m-recursive functions you must provide a suitable [47m:induction[0m hint. In addition, to be provable by induction, theorems about [47mloop$[0m-recursive functions must be suitably general. This topic is discussed further in [loop$-recursion-induction]. Restrictions If a function being defined exhibits recursion from within a [47m[loop$][0m body or within the [47mWHEN[0m or [47mUNTIL[0m clauses of a [47mloop$[0m in a [47m[defun][0m of [3mfn[0m, then the [47mdefun[0m must include an [47m[xargs][0m declaration with [47m:loop$-recursion t[0m. In addition, * the [47mxargs[0m declaration must include an explicit [47m:measure[0m, * [3mfn[0m must not be part of a [47m[mutual-recursion][0m clique, * every formal of [3mfn[0m must be ``ordinary,'' e.g., not of [47m[ilk][0m [47m:FN[0m or [47m:EXPR[0m, * [3mfn[0m must return a single value, * [3mfn[0m's measure must be of type [47m[natp][0m or be a lexicographic combination of natural numbers as defined by the [47mllist[0m function in the Community Books at [47mbooks/ordinals/[0m, * [3mfn[0m must be [47m[tame][0m, which implies it may not take or return [47m[state][0m or [47m[stobj][0ms, * every quoted [47m[lambda][0m object in the body of [3mfn[0m must be well-formed (see [47m[well-formed-lambda-objectp][0m), which implies that every such [47mlambda[0m object is tame and every function symbol, including [3mfn[0m, used in each must have a [47m[badge][0m, * every quoted [47mlambda[0m object in the body of [3mfn[0m that calls [3mfn[0m recursively must occur as the first argument of a [47mloop$[0m scion and [3mnot[0m in some arbitrary scion, * there is at least one recursive call of [3mfn[0m inside a quoted [47mlambda[0m object which means that the [47mloop$-recursion t[0m declaration was actually necessary, and * the necessary measure conjectures (see below) must be proved. These restrictions make a little more sense if you reflect on what has to be done to check and admit a [47mloop$[0m-recursive function. First, we assume that most ACL2 functions are not [47mloop$[0m-recursive. So to keep [47mdefun[0m-processing as fast as possible, we require you to declare when you are using [47mloop$[0m recursion. That declaration triggers additional checks. But before checks can begin, we have to translate the body of [3mfn[0m and since [47mloop$[0ms translate into calls of [47mloop$[0m scions on quoted [47mlambda[0ms and those must be tame, and since some of those [47mlambda[0ms involve calls of [3mfn[0m, we must assign a badge to [3mfn[0m even before we have translated its body. We assign a badge that declares [3mfn[0m to take the appropriate number of ordinary inputs, to return one result, and be tame. We check those requirements after [3mfn[0m has been admitted. Because the measure guessing heuristics of ACL2 do not look for calls inside of quoted [47mlambda[0ms, the measure must be explicitly declared even if it [47macl2-count[0m. To find every recursive call in a quoted [47mlambda[0m object those objects must all be well-formed. If such an object occurs as the first argument of a [47mloop$[0m scion then we know it is only applied to elements of the [47mloop$[0m scion's target. Given that, we can investigate whether the recursive calls in the [47mlambda[0m object are on smaller things. But if a recursive call were to occur in a quoted [47mlambda[0m object that was passed to some other kind of scion, we have no way to know (without extensive analysis) to what it might be applied. Some of these restrictions could be lifted with more analysis and coding. For example, we could change the specification for the [47m:loop$-recursion[0m [47mxargs[0m keyword so that instead of taking on a Boolean value it takes on a badge. Then we could tentatively assign that badge to [3mfn[0m before processing and check it afterwards. Our current thinking is to ask users to live with these restrictions and let us see whether [47mloop$[0m-recursion is useful (almost certainly it will be), whether the community can develop proof techniques and tools to reason about them as effectively as we reason about conventional recursive functions (we're optimistic), and whether investing time in lifting some of these restrictions is worth it given all the other ways we could improve ACL2. Measure Conjectures Measure conjectures must be generated for the recursive calls inside [47mloop$[0m bodies. (We also generate conjectures for the recursive calls the other [47mloop$[0m-expression components, e.g., the [47mWHEN[0m clause, exactly analogously, but we speak of the [47mloop$[0m body only below. We also focus on simple [47mloop$[0ms here but the conjectures described generalize to fancy [47mloop$[0ms.) Given a recursive call inside the body of a [47mloop$[0m with iteration variable [3mv[0m, we first generate a new variable symbol, [3mv'[0m. Certain terms, e.g., tests and arguments to recursive calls, will be extracted from within the body and used in the measure conjecture. We rename [3mv[0m to [3mv'[0m in these terms to distinguish occurrences of [3mv[0m outside the [47mloop$[0m from those inside. The measure conjecture requires us to prove that the given measure decreases, as usual. But the ruling tests are those ruling the [47mloop$[0m, conjoined with the hypothesis that [3mv'[0m is a member of the target, conjoined with the (renamed) tests from inside the body ruling the recursive call. Below is an example. We show only the measure conjectures generated from inside the [47mloop$[0m because there are two recursive calls in the [47mloop$[0m body. (defun$ fn (v) (declare (xargs :loop$-recursion t :measure (acl2-count x))) (cond ((natp v) ...) ((true-listp v) (loop$ for v in (target v) sum (if (and (integerp v) (< v 0)) (fn (- v)) (fn v)))) (t ...))) Note that [47mv[0m used both as the formal of [47mfn[0m and as the iterative variable of the [47mloop$[0m. In the measure conjectures below, the iterative variable has been renamed to [47mnv0[0m. Two measure conjectures are generated from within the [47mloop$[0m: (implies (and (not (natp v)) (true-listp v) (member-equal nv0 (target v)) (and (integerp nv0) (< nv0 0))) (o< (acl2-count (- nv0)) (acl2-count v))) (implies (and (not (natp v)) (true-listp v) (member-equal nv0 (target v)) (not (and (integerp nv0) (< nv0 0)))) (o< (acl2-count nv0) (acl2-count v))) Note that these conjectures require that when [47mfn[0m is called from within the [47mloop$[0m the argument is smaller than the initial value of the formal. Notice also that there is no [3ma priori[0m restriction on the size of [47m(target v)[0m. However, because of the way [47mfn[0m is used inside this particular example [47mloop$[0m, there are restrictions on the size of the elements of [47m(target v)[0m. These conjectures, along with those generated from calls outside the [47mloop$[0m are sufficient to guarantee that [47mfn[0m always terminates. [31;1mNote:[0m Careful readers might note that the way we handle measure conjectures for [47mloop$[0ms differs from the way we handle guard conjectures for [47mloop$[0ms. In [47m[loop$][0m we explained that [47mloop$[0ms are translated into calls of [47mloop$[0m [47m[scion][0ms on quoted [47m[lambda][0m objects and that the guard conjectures for the [47mlambda[0m are insensitive to the context in which the object appeared. But the measure conjectures are sensitive to the context: tests from outside the [47mloop$[0m are present in the measure conjectures. This is deliberate. Guard conjectures are context insensitive because the implementation caches compiled [47mlambda[0m objects without remembering the contexts in which they first occurred. Thus, a [47mlambda[0m object generated by a [47mloop$[0m may be called on anything and we cannot guarantee that the input guard to the [47mlambda[0m object will be satisfied. [3mBut we can guarantee that the computation carried out by the [47mlambda[0m[3m will terminate![0m The [47mlambda[0m object generated for [47mfn[0m above terminates no matter what it is called on -- even if called on elements not in [47m(target v)[0m -- because [47mfn[0m terminates. Finally, recall that [47mloop$[0m-recursive functions do not automatically suggest induction schemes and that special care must be taken when formulating inductively provable conjectures about them. See [loop$-recursion-induction]. Subtopics [Definductor] Create an induction scheme for a [47mloop$[0m-recursive function") (loop$-recursion-induction (loop$) "Advice on inductive theorems about [47m[loop$][0m-recursive functions [31;1mWarning:[0m This documentation topic is fairly preliminary because we do not have a lot of experience yet with [47m[apply$][0m, [47m[loop$][0m, and [47m[loop$-recursion][0m. We assume here that readers are familiar with the topics cited above. Definductor The principles sketched here are illustrated concretely in the tutorial community book [47mprojects/apply/copy-nat-tree.lisp[0m. As noted in that book, the inductions are hinted manually so the reader can see from first principles what is involved. However, in the book [47mprojects/apply/top[0m we provide a utility that sometimes automates the creation of the inductive hint function and associates it with the given [47mloop$[0m-recursive function. See [47m[definductor][0m. The examples worked manually in [47mcopy-nat-tree.lisp[0m are recapitulated towards the end of [47mprojects/apply/definductor-tests.lisp[0m, without the manually provided hints. In addition, the book [47mprojects/apply/loop-recursion-examples.lisp[0m gives some other examples of loop$-recursive functions and inductive theorems about them. Some Basic Principles for Inductive Proofs about [47mLoop$[0m-Recursive Functions If ACL2 did not have [47mloop$[0m, functions defined in terms of [47mloop$[0m-recursion would have to be defined with [47m[mutual-recursion][0m. Reconsider the example presented in [47m[loop$-recursion][0m. (defun$ nat-treep (x) (declare (xargs :loop$-recursion t :measure (acl2-count x))) (cond ((atom x) (natp x)) (t (and (true-listp x) (eq (car x) 'NATS) (loop$ for e in (cdr x) always (nat-treep e)))))) (defun$ copy-nat-tree (x) (declare (xargs :loop$-recursion t :measure (acl2-count x))) (cond ((atom x) (if (natp x) (if (equal x 0) 0 (+ 1 (copy-nat-tree (- x 1)))) x)) (t (cons 'nats (loop$ for e in (cdr x) collect (copy-nat-tree e)))))) Without [47mloop$[0m the latter function would have to be defined this way. We name it [47mmr-copy-nat-tree[0m, where the ``[47mmr[0m'' reminds us this is part of a mutually recursive clique. (mutual-recursion (defun mr-copy-nat-tree (x) (cond ((atom x) (if (natp x) (if (equal x 0) 0 (+ 1 (mr-copy-nat-tree (- x 1)))) x)) (t (cons 'nats (mr-copy-nat-tree-list (cdr x)))))) (defun mr-copy-nat-tree-list (x) (cond ((endp x) nil) (t (cons (mr-copy-nat-tree (car x)) (mr-copy-nat-tree-list (cdr x))))))) Note that we define [47mmr-copy-nat-tree[0m by copying the definition of [47mcopy-nat-tree[0m (renaming recursive calls appropriately) but replacing the use of [47mloop$[0m in [47mcopy-nat-tree[0m with a call of a mutually-recursive function here called [47mmr-copy-nat-tree-list[0m. We call [47mmr-copy-nat-tree-list[0m the ``list counterpart'' of [47mmr-copy-nat-tree[0m. However, in general there may be more than just two functions in the clique and so we refer generically to [47mmr-copy-nat-tree-list[0m as a ``co-member'' of the clique. How would you prove theorems about [47mmr-copy-nat-tree[0m? Four principles are known to most ACL2 users of [47mmutual-recursion[0m. These principles apply to [47mloop$[0m-recursive functions as well as to mutually recursive ones. We state them here in terms of both kinds of definitions. * While simple recursive functions suggest ``appropriate'' inductions, mutually recursive functions and [47mloop$[0m-recursive functions do not. If you want to prove a theorem about such functions you have to arrange some kind of induction hint. * You can't generally prove an isolated theorem about a single member of a mutually recursive clique or a [47mloop$[0m-recursive function. Instead, you must state a conjecture about every member of the clique, conjoin all those theorems together, and prove them inductively all at once. Applied to proving a theorem about [47mmr-copy-nat-tree[0m this advice means we must conjoin the theorem about that function with ``the same'' theorem about [47mmr-copy-nat-tree-list[0m, and more generally with theorems about every co-member of the clique. Of course, what we mean by ``the same'' theorem about different members of the clique depends on what each member contributes to the overall computation. Applied to the [47mloop$[0m-recursive function [47mcopy-nat-tree[0m this advice means we must simultaneously prove a theorem about every [47mloop$[0m in the function. * Inductively provable theorems must be sufficiently general. When dealing with a mutually recursive clique, each conjunct must address itself to the ``general'' call of the co-member in question, e.g., to [47m(mr-copy-nat-tree-list x)[0m not to the specific call inside [47mmr-copy-nat-tree[0m, which is [47m(mr-copy-nat-tree-list (cdr x))[0m. When dealing with a [47mloop$[0m-recursive function, each conjunct must address itself to the general target, not to specific target in the [47mloop$[0m recursive function. In the case of the [47mloop$[0m-recursive function [47mcopy-nat-tree[0m we need a conjunct about [47m(loop$ for e in x collect (copy-nat-tree e))[0m, not about [47m(loop$ for e in (cdr x) collect (copy-nat-tree e))[0m. * Finally, the induction scheme used must provide an inductive hypothesis about every recursive call of every co-member of the clique or, in the case of [47mloop$[0m-recursion, about every recursive unwinding of each [47mloop$[0m. [31;1mRemember:[0m Because [47mloop$[0m-recursive functions call themselves recursively with [47mapply$[0m, any theorem about a [47mloop$[0m recursive function must almost certainly include a warrant hypothesis for that function! We illustrate these principles in the community book [47mprojects/apply/copy-nat-list.lisp[0m.") (loop-stopper (rewrite) "Limit application of permutative rewrite rules See [rule-classes] for a discussion of the syntax of the [47m:loop-stopper[0m field of [47m:[0m[47m[rewrite][0m rule-classes. Here we describe how that field is used, and also how that field is created when the user does not explicitly supply it. For example, the built-in [47m:[0m[47m[rewrite][0m rule [47mcommutativity-of-+[0m, (implies (and (acl2-numberp x) (acl2-numberp y)) (equal (+ x y) (+ y x))), creates a rewrite rule with a loop-stopper of [47m((x y binary-+))[0m. This means, very roughly, that the term corresponding to [47my[0m must be ``smaller'' than the term corresponding to [47mx[0m in order for this rule to apply. However, the presence of [47m[binary-+][0m in the list means that certain functions that are ``invisible'' with respect to [47m[binary-+][0m (by default, [47m[unary--][0m is the only such function) are more or less ignored when making this ``smaller'' test. We are much more precise below. Our explanation of loop-stopping is in four parts. First we discuss ACL2's notion of ``term order.'' Next, we bring in the notion of ``invisibility'', and use it together with term order to define orderings on terms that are used in the loop-stopping algorithm. Third, we describe that algorithm. These topics all assume that we have in hand the [47m:loop-stopper[0m field of a given rewrite rule; the fourth and final topic describes how that field is calculated when it is not supplied by the user. ACL2 must sometimes decide which of two terms is syntactically simpler. It uses a total ordering on terms, called the ``term order.'' Under this ordering constants such as [47m'(a b c)[0m are simpler than terms containing variables such as [47mx[0m and [47m(+ 1 x)[0m. Terms containing variables are ordered according to how many occurrences of variables there are. Thus [47mx[0m and [47m(+ 1 x)[0m are both simpler than [47m(cons x x)[0m and [47m(+ x y)[0m. If variable counts do not decide the order, then the number of function applications are tried. Thus [47m(cons x x)[0m is simpler than [47m(+ x (+ 1 y))[0m because the latter has one more function application. Finally, if the number of function applications do not decide the order, a lexicographic ordering on Lisp objects is used. See [term-order] for details. When the loop-stopping algorithm is controlling the use of permutative [47m:[0m[47m[rewrite][0m rules it allows [47mterm1[0m to be moved leftward over [47mterm2[0m only if [47mterm1[0m is smaller, in a suitable sense. Note: The sense used in loop-stopping is [31;1mnot[0m the above explained term order but a more complicated ordering described below. The use of a total ordering stops rules like commutativity from looping indefinitely because it allows [47m(+ b a)[0m to be permuted to [47m(+ a b)[0m but not vice versa, assuming [47ma[0m is smaller than [47mb[0m in the ordering. Given a set of permutative rules that allows arbitrary permutations of the tips of a tree of function calls, this will normalize the tree so that the smallest argument is leftmost and the arguments ascend in the order toward the right. Thus, for example, if the same argument appears twice in the tree, as [47mx[0m does in the [47m[binary-+][0m tree denoted by the term [47m(+ a x b x)[0m, then when the allowed permutations are done, all occurrences of the duplicated argument in the tree will be adjacent, e.g., the tree above will be normalized to [47m(+ a b x x)[0m. Suppose the loop-stopping algorithm used term order, as noted above, and consider the [47m[binary-+][0m tree denoted by [47m(+ x y (- x))[0m. The arguments here are in ascending term order already. Thus, no permutative rules are applied. But because we are inside a [47m+-expression[0m it is very convenient if [47mx[0m and [47m(- x)[0m could be given virtually the same position in the ordering so that [47my[0m is not allowed to separate them. This would allow such rules as [47m(+ i (- i) j) = j[0m to be applied. In support of this, the ordering used in the control of permutative rules allows certain unary functions, e.g., the unary minus function above, to be ``invisible'' with respect to certain ``surrounding'' functions, e.g., [47m[+][0m function above. Briefly, a unary function symbol [47mfn1[0m is invisible with respect to a function symbol [47mfn2[0m if [47mfn2[0m belongs to the value of [47mfn1[0m in [47m[invisible-fns-table][0m; also see [set-invisible-fns-table], which explains its format and how it can be set by the user. Roughly speaking, ``invisible'' function symbols are ignored for the purposes of the term-order test. Consider the example above, [47m(+ x y (- x))[0m. The translated version of this term is [47m(binary-+ x (binary-+ y (unary-- x)))[0m. The initial [47m[invisible-fns-table][0m makes [47m[unary--][0m invisible with respect to [47m[binary-+][0m. The commutativity rule for [47m[binary-+][0m will attempt to swap [47my[0m and [47m(unary-- x)[0m and the loop-stopping algorithm is called to approve or disapprove. If term order is used, the swap will be disapproved. But term order is not used. While the loop-stopping algorithm is permuting arguments inside a [47m[binary-+][0m expression, [47m[unary--][0m is invisible. Thus, instead of comparing [47my[0m with [47m(unary-- x)[0m, the loop-stopping algorithm compares [47my[0m with [47mx[0m, approving the swap because [47mx[0m comes before [47my[0m. Here is a more precise specification of the total order used for loop-stopping with respect to a list, [47mfns[0m, of functions that are to be considered invisible. Let [47mx[0m and [47my[0m be distinct terms; we specify when ``[47mx[0m is smaller than [47my[0m with respect to [47mfns[0m.'' If [47mx[0m is the application of a unary function symbol that belongs to [47mfns[0m, replace [47mx[0m by its argument. Repeat this process until the result is not the application of such a function; let us call the result [47mx-guts[0m. Similarly obtain [47my-guts[0m from [47my[0m. Now if [47mx-guts[0m is the same term as [47my-guts[0m, then [47mx[0m is smaller than [47my[0m in this order iff [47mx[0m is smaller than [47my[0m in the standard term order. On the other hand, if [47mx-guts[0m is different than [47my-guts[0m, then [47mx[0m is smaller than [47my[0m in this order iff [47mx-guts[0m is smaller than [47my-guts[0m in the standard term order. Now we may describe the loop-stopping algorithm. Consider a rewrite rule with conclusion [47m(equiv lhs rhs)[0m that applies to a term [47mx[0m in a given context; see [rewrite]. Suppose that this rewrite rule has a loop-stopper field (technically, the [47m:heuristic-info[0m field) of [47m((x1 y1 . fns-1) ... (xn yn . fns-n))[0m. (Note that this field can be observed by using the command [47m:[0m[47m[pr][0m with the name of the rule; see [pr].) We describe when rewriting is permitted. The simplest case is when the loop-stopper list is [47mnil[0m (i.e., [47mn[0m is [47m0[0m); in that case, rewriting is permitted. Otherwise, for each [47mi[0m from 1 to [47mn[0m let [47mxi'[0m be the actual term corresponding to the variable [47mxi[0m when [47mlhs[0m is matched against the term to be rewritten, and similarly correspond [47myi'[0m with [47my[0m. If [47mxi'[0m and [47myi'[0m are the same term for all [47mi[0m, then rewriting is not permitted. Otherwise, let [47mk[0m be the least [47mi[0m such that [47mxi'[0m and [47myi'[0m are distinct. Let [47mfns[0m be the list of all functions that are invisible with respect to every function in [47mfns-k[0m, if [47mfns-k[0m is non-empty; otherwise, let [47mfns[0m be [47mnil[0m. Then rewriting is permitted if and only if [47myi'[0m is smaller than [47mxi'[0m with respect to [47mfns[0m, in the sense defined in the preceding paragraph. It remains only to describe how the loop-stopper field is calculated for a rewrite rule when this field is not supplied by the user. (On the other hand, to see how the user may specify the [47m:loop-stopper[0m, see [rule-classes].) Suppose the conclusion of the rule is of the form [47m(equiv lhs rhs)[0m. First of all, if [47mrhs[0m is not an instance of the left hand side by a substitution whose range is a list of distinct variables, then the loop-stopper field is [47mnil[0m. Otherwise, consider all pairs [47m(u . v)[0m from this substitution with the property that the first occurrence of [47mv[0m appears in front of the first occurrence of [47mu[0m in the print representation of [47mrhs[0m. For each such [47mu[0m and [47mv[0m, form a list [47mfns[0m of all functions [47mfn[0m in [47mlhs[0m with the property that [47mu[0m or [47mv[0m (or both) appears as a top-level argument of a subterm of [47mlhs[0m with function symbol [47mfn[0m. Then the loop-stopper for this rewrite rule is a list of all lists [47m(u v . fns)[0m. [3mRemark.[0m The paragraph above mentions ``the conclusion of the rule'' as [47m(equiv lhs rhs)[0m. The rule's conclusion is actually produced from a naive version [47m(equiv lhs0 rhs)[0m of the conclusion by expanding away all [lambda] applications in [47mlhs0[0m. If [47mlhs0[0m and [47mlhs[0m are distinct (i.e., if there is any such lambda expansion) and also the loop-stopper field is calculated as [47mnil[0m as described above, then a second attempt to calculate the loop-stopper is made using [47mlhs0[0m in place of [47mlhs[0m. Subtopics [Add-invisible-fns] Make some unary functions invisible to the [loop-stopper] algorithm [Invisible-fns-table] Functions that are invisible to the [loop-stopper] algorithm [Remove-invisible-fns] Make some unary functions no longer invisible [Set-invisible-fns-table] Set the invisible functions table") (lower-case-p (characters acl2-built-ins) "Recognizer for lower case characters [47m(Lower-case-p x)[0m is true if and only if [47mx[0m is a lower case character, i.e., a member of the list [47m#\A[0m, [47m#\B[0m, ..., [47m#\Z[0m. The [guard] for [47mlower-case-p[0m states that its argument is a character. [47mLower-case-p[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<lower-case-p> (defun lower-case-p (x) (declare (xargs :guard (characterp x))) (cond ((standard-char-p x) (and (member x '(#\a #\b #\c #\d #\e #\f #\g #\h #\i #\j #\k #\l #\m #\n #\o #\p #\q #\r #\s #\t #\u #\v #\w #\x #\y #\z)) t)) (t (lower-case-p-non-standard x))))") (lp (ld) "The Common Lisp entry to ACL2 To enter the ACL2 [command] loop from Common Lisp, call the Common Lisp program [47mlp[0m (which stands for ``loop,'' as in ``read-eval-print loop'' or ``[command] loop.'') The ACL2 [command] loop is actually coded in ACL2 as the function [47m[ld][0m (which stands for ``load''). The [command] loop is just what you get by loading from the standard object input channel, [47m[*standard-oi*][0m. Calling [47m[ld][0m directly from Common Lisp is possible but fragile because hard lisp errors or aborts throw you out of [47m[ld][0m and back to the top-level of Common Lisp. [47mLp[0m calls [47m[ld][0m in such a way as to prevent this and is thus the standard way to get into the ACL2 [command] loop. Also see [ACL2-customization] for information on the loading of an initialization file. All of the visible functionality of [47mlp[0m is in fact provided by [47m[ld][0m, which is written in ACL2 itself. Therefore, you should see [ld] for detailed [documentation] of the ACL2 [command] loop. We sketch it below, for novice users. Every expression typed to the ACL2 top-level must be an ACL2 expression. Any ACL2 expression may be submitted for evaluation. Well-formedness is checked. Some well-formed expressions cannot be evaluated because they involve (at some level) undefined constrained functions (see [encapsulate]). In addition, ACL2 does not allow ``global variables'' in expressions to be evaluated. Thus, [47m(car '(a b c))[0m is legal and evaluates to [47mA[0m, but [47m(car x)[0m is not, because there is no ``global context'' or binding environment that gives meaning to the variable symbol [47mx[0m. There is an exception to the global variable rule outlined above: single-threaded objects (see [stobj]) may be used as global variables in top-level expressions. The most commonly used such object is the ACL2 ``current state,'' which is the value of the variable symbol [47m[state][0m. This variable may occur in the top-level form to be evaluated, but must be passed only to ACL2 functions ``expecting'' [47mstate[0m as described in the documentation for [47m[state][0m and for [47m[stobj][0ms in general. If the form returns a new [state] object as one of its values, then that is considered the new ``current'' [state] for the evaluation of the subsequent form. See [state]. ACL2 provides some support for the functionality usually provided by global variables in a read-eval-print loop, namely the saving of the result of a computation for subsequent re-use in another expression. See [assign] and see [@]. If the form read is a single keyword, e.g., [47m:[0m[47m[pe][0m or [47m:[0m[47m[ubt][0m, then special procedures are followed. See [keyword-commands]. The [command] loop keeps track of the [command]s you have typed and allows you to review them, display them, and roll the logical [state] back to that created by any [command]. See [history]. ACL2 makes the convention that if a top-level form returns three values, the last of which is an ACL2 [state], then the first is treated as a flag that means ``an error occurred,'' the second is the value to be printed if no error occurred, and the third is (of course) the new [state]. When ``an error occurs'' no value is printed. Thus, if you execute a top-level form that happens to return three such values, only the second will be printed (and that will only happen if the first is [47mnil[0m!). See [ld] for details. Subtopics [Q] Quit ACL2 (type [47m:q[0m) --- reenter with [47m(lp)[0m") (lp-background-review-1 (lp-section-1) "Background review of basic ACL2 knowledge Here are some questions to review basic features of ACL2. ------------------------------ Consider the expression below and answer the following questions about it, without running ACL2! We're looking for informal answers largely in agreement with ours, not perfect answers. If you want to see the questions together with our answers, see [lp-background-review-1-answers]. (defun abc (x) (declare (xargs :mode :program :guard (true-listp x))) (cond ((endp x) nil) (t (cons (cons '? (car x)) (abc (cdr x)))))) ------------------------------ 1: Informally, what happens if you type that expression at the top-level of the ACL2 read-eval-print loop? ------------------------------ 2: More formally, how does the utterance above affect the ACL2 logic? ------------------------------ 3: A little bit of Lisp knowledge will tell you that all terms are either variables, constants (usually quoted), or calls of functions, where calls are of the form [47m(fn a1 ... an)[0m, where [47mfn[0m is a function symbol or [47mlambda[0m object that takes [47mn[0m arguments and the [47mai[0m are terms. But the [47mcond[0m expression above is not of this form. [47mCond[0m is a macro that translates into a formal term. What formal term does it translate to? And if you didn't know, how would you find out? ------------------------------ 4: Let [47mx[0m be the object that prints as [47m((A . 1) (B . 2) (C . 3))[0m. What is the value of [47m(car x)[0m or is that a nonsensical question? Several of the questions below are nonsensical! ------------------------------ 5: Given the value of [47mx[0m in question 4, what is the value of [47m(true-listp x)[0m? ------------------------------ 6: Given the value of [47mx[0m in question 4, what is the value of [47m(cons '? (car x))[0m? ------------------------------ 7: Given the value of [47mx[0m in question 4, what is the value of [47m(cdr x)[0m? ------------------------------ 8: Recall we defined [47mabc[0m above. What is the value [47m(abc '((a . 1) (b . 2) (c . 3)))[0m? ------------------------------ 9: What is the difference between [47m'((a . 1) (b . 2) (c . 3))[0m and [47m((A . 1) (B . 2) (C . 3))[0m? ------------------------------ 10: What is the value of [47m(abc ((a . 1) (b . 2) (c . 3)))[0m? ------------------------------ 11: How would you explain what [47mabc[0m is, i.e., how it ``works'' or what it ``does?'' ------------------------------ 12: What is the value of [47m(abc 3 4 5)[0m? ------------------------------ 13: What is the value of [47m(abc '(3 . 4))[0m? ------------------------------ 14: How do you get ACL2 to print the value of [47m(abc '(3 . 4))[0m? ------------------------------ 15: How can you upgrade [47mabc[0m from a [47m:program[0m mode function to a [47m:logic[0m mode function? ------------------------------ 16: What is the axiom added to ACL2 when [47mabc[0m is upgraded? ------------------------------ 17: Is [47m(true-listp (abc x))[0m a theorem in ACL2? ------------------------------ 18: What would you type to get ACL2 to try to prove it? ------------------------------ 19: How would you describe the behavior of the [47m:logic[0m function [47mdef[0m below? By the way, we're naming certain functions in these reviews with consecutive letters of the alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m, [47mmno[0m, etc. These names are not mnemonic or acronyms. Don't read anything into the names! (defun def (x) (if (endp x) nil (append (def (cdr x)) (list (car x))))) ------------------------------ 20: Define [47msq[0m to square a number. E.g., [47m(sq 9)[0m returns [47m81[0m and [47m(sq -1/2)[0m returns [47m1/4[0m. ------------------------------ 21: How would you describe the behavior of [47msq*[0m below? (defun sq* (x) (if (endp x) nil (cons (sq (car x)) (sq* (cdr x))))) ------------------------------ 22: What would you type to make ACL2 prove the following conjecture? (equal (sq* (def x)) (def (sq* x))) ------------------------------ 23: Prove [47m(nat-listp (ghi 0 max))[0m, where (defun ghi (i max) (declare (xargs :measure (nfix (- (+ 1 (nfix max)) (nfix i))))) (let ((i (nfix i)) (max (nfix max))) (cond ((> i max) nil) (t (cons i (ghi (+ 1 i) max)))))) ------------------------------ For our answers see [lp-background-review-1-answers]. If your answers don't basically agree with ours, you're probably not yet ready to read this material on [loop$]. We recommend that you read the topic, [recursion-and-induction]. If your answers largely agree with ours, go back to the [lp-section-1]. (Return to the Table of Contents (see [LP-SECTION-0]).)") (lp-background-review-1-answers (lp-section-1) "Answers to background review of basic ACL2 knowledge (defun abc (x) (declare (xargs :mode :program :guard (true-listp x))) (cond ((endp x) nil) (t (cons (cons '? (car x)) (abc (cdr x)))))) ------------------------------ 1: Informally, what happens if you type that expression at the top-level of the ACL2 read-eval-print loop? Answer: It defines [47mabc[0m as a Lisp program. Note the [47mdeclare[0m that says the [47m:mode[0m is [47m:program[0m. By the way, when Lisp and ACL2 read symbols, like [47mabc[0m, [47mx[0m, [47mdeclare[0m, etc., they automatically convert them to UPPERCASE. So it doesn't matter if we write [47mabc[0m or [47mABC[0m, or [47mAbc[0m, etc. ------------------------------ 2: More formally, how does the utterance above affect the ACL2 logic? Answer: It doesn't. Defining a [47m:program[0m introduces no axioms into the logic. ------------------------------ 3: A little bit of Lisp knowledge will tell you that all terms are either variables, constants (usually quoted), or calls of functions, where calls are of the form [47m(fn a1 ... an)[0m, where [47mfn[0m is a function symbol or [47mlambda[0m object that takes [47mn[0m arguments and the [47mai[0m are terms. But the [47mcond[0m expression above is not of this form. [47mCond[0m is a macro that translates into a formal term. What formal term does the [47mcond[0m expression translate to? And if you didn't know, how would you find out? Answer: The expression (cond ((endp x) nil) (t (cons (cons '? (car x)) (abc (cdr x))))) translates to (if (endp x) 'nil (cons (cons '? (car x)) (abc (cdr x)))) To see the translation of an expression use [47m[trans][0m. ------------------------------ 4: Let [47mx[0m be the object that prints as [47m((A . 1) (B . 2) (C . 3))[0m. What is the value of [47m(car x)[0m or is that a nonsensical question? Several of the questions below are nonsensical! Answer: [47m(car x)[0m is [47m(A . 1)[0m if [47mx[0m is [47m((A . 1) (B . 2) (C . 3))[0m. ------------------------------ 5: Given the value of [47mx[0m in question 4, what is the value of [47m(true-listp x)[0m? Answer: [47mT[0m, because [47mx[0m is a nest of conses whose rightmost terminal is [47mNIL[0m. ------------------------------ 6: Given the value of [47mx[0m in question 4, what is the value of [47m(cons '? (car x))[0m? Answer: [47m(? A . 1)[0m ------------------------------ 7: Given the value of [47mx[0m in question 4, what is the value of [47m(cdr x)[0m? Answer: [47m((B . 2) (C . 3))[0m ------------------------------ 8: What is the value [47m(abc '((a . 1) (b . 2) (c . 3)))[0m? Answer: [47m((? A . 1) (? B . 2) (? C . 3))[0m ------------------------------ 9: What is the difference between [47m'((a . 1) (b . 2) (c . 3))[0m and [47m((A . 1) (B . 2) (C . 3))[0m? Answer: [47m'((a . 1) (b . 2) (c . 3))[0m is a constant term that evaluates to the list [47m((A . 1) (B . 2) (C . 3))[0m. The quote mark in front an object forms a term that evaluates to that object. And remember, case is generally irrelevant in symbols. ------------------------------ 10: What is the value of [47m(abc ((a . 1) (b . 2) (c . 3)))[0m? Answer: That's a nonsensical question. [47m(abc ((a . 1) (b . 2) (c . 3)))[0m is not a well-formed term. For example, [47m(a . 1)[0m is not a function symbol or a [47mlambda[0m expression, or a macro. ------------------------------ 11: How would you explain what [47mabc[0m is, i.e., how it ``works'' or what it ``does?'' Answer: The symbol [47mABC[0m is the name of a Lisp program that takes one argument and returns one result. It can be run, but nothing can be proved about it because there are no axioms defining it. When [47mabc[0m is called on [47mx[0m it copies the [47mcdr[0m-chain of [47mx[0m, adding the question mark symbol to each new element. ------------------------------ 12: What is the value of [47m(abc 3 4 5)[0m? Answer: Nonsensical. [47mABC[0m takes only one argument, not three. ------------------------------ 13: What is the value of [47m(abc '(3 . 4))[0m? Answer: Actually, it is [47m((? . 3))[0m, but ACL2 won't evaluate [47m(abc '(3 . 4))[0m in the default configuration of the top-level read-eval-print loop because [47m(3 . 4)[0m is not a [47m[true-listp][0m. The guard on [47mABC[0m stipulates that the argument to [47mABC[0m is ``supposed'' to be a [47mtrue-listp[0m. So the read-eval-print loop causes a guard violation error. We explain why the value of [47m(abc '(3 . 4))[0m is actually [47m((? . 3))[0m in the next answer. ------------------------------ 14: How do you get ACL2 to compute and print the value of [47m(abc '(3 . 4))[0m? Answer: The top-level read-eval-print loop has a parameter that controls whether ACL2 checks the guards or not. By default, that parameter is set to [47mT[0m, meaning it does check guards. But by executing [47m(set-guard-checking nil)[0m the parameter is set to [47mNIL[0m and then guards are not checked. With that setting, ACL2 evaluation just ignores the guard and runs the body of the program. So here is how [47m(abc '(3 . 4))[0m is evaluated. First, it checks whether [47m[endp][0m holds on [47m(3 . 4)[0m. The definition of [47mendp[0m is [47matom[0m, which means ``is not a [47m[cons][0m pair,'' and [47m(3 . 4)[0m is a [47mcons[0m pair. So the answer to the [47mendp[0m test is [47mNIL[0m and the execution of [47m(abc '(3 . 4))[0m branches to the [47m(cons (cons '? (car x)) (abc (cdr x)))[0m, where [47mx[0m is [47m(3 . 4)[0m. But the [47mcar[0m and [47mcdr[0m of the pair [47m(3 . 4)[0m are [47m3[0m and [47m4[0m respectively. So the value of [47m(abc '(3 . 4))[0m is [47m(cons (cons '? 3) (abc 4))[0m. But what is the value of [47m(abc 4)[0m? [47m(Endp 4)[0m is [47mT[0m because [47m4[0m is an atom. So the value of [47m(cons (cons '? 3) (abc 4))[0m is [47m(cons (cons '? 3) NIL)[0m, which is printed as [47m((? . 3))[0m. ------------------------------ 15: How can you upgrade [47mabc[0m from a [47m:program[0m mode function to a [47m:logic[0m mode function? Answer: Invoke [47m[verify-termination][0m like this [47m(verify-termination abc)[0m. ------------------------------ 16: What is the axiom added to the ACL2 logic when [47mabc[0m is upgraded? Answer: <b>Definitional Axiom for ABC</b> (abc x) = (if (endp x) nil (cons (cons '? (car x)) (abc (cdr x)))). Note that the guard is irrelevant in the logic. [47m(Abc x)[0m is always equal to the right-hand side of the axiom above (the ``body'' of [47mabc[0m), regardless of what [47mx[0m is. ------------------------------ 17: Is [47m(true-listp (abc x))[0m a theorem in ACL2? Answer: Yes! It may not seem so because the [47mdefun[0m of [47mabc[0m mentions the [47m:guard[0m of [47m(true-listp x)[0m and yet the conjecture here doesn't constrain [47mx[0m. But guards of ACL2 functions are logically irrelevant. The Definitional Axiom added for [47mabc[0m does not mention the guard. So [47m(true-listp (abc x))[0m is a theorem no matter what [47mx[0m is! Proof of [47m(true-listp (abc x))[0m by induction on [47mx[0m: Base Case: (atom x) ; i.e., x is not a consp (true-listp (abc x)) = ; def abc (true-listp (if (endp x) nil ...)) = ; def endp and (atom x). (true-listp (if T nil ...)) = ; axiom about IF (true-listp nil) = ; def true-listp T Induction Step: (consp x) Induction Hyp: (true-listp (abc (cdr x))) (true-listp (abc x)) = ; def abc (true-listp (if (endp x) nil (cons (cons '? (car x)) (abc (cdr x))))) = ; def endp and (consp x) (true-listp (if NIL nil (cons (cons '? (car x)) (abc (cdr x))))) = ; axiom about IF (true-listp (cons (cons '? (car x)) (abc (cdr x)))) = ; def true-listp (true-listp (abc (cdr x))) = ; Induction Hyp T Q.E.D. If you ask ACL2 to do the proof (see the next question) its proof doesn't mention induction. That's because when [47mabc[0m was defined ACL2 does a little inductive reasoning to deduce the ``type'' of the output and deduced that it is always a [47mtrue-listp[0m. That type inference essentially does the inductive proof above. ------------------------------ 18: What would you type to get ACL2 to try to prove it? Answer: (thm (true-listp (abc x))) or (defthm little-theorem-about-abc (true-listp (abc x))) ------------------------------ 19: How would you describe the behavior of the [47m:logic[0m function [47mdef[0m below? By the way, we're naming certain functions in these reviews with consecutive letters of the alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m, [47mmno[0m, etc. These names are not mnemonic or acronyms. Don't read anything into the names! (defun def (x) (if (endp x) nil (append (def (cdr x)) (list (car x))))) Answer: It reverses [47mx[0m, i.e., it returns a list containing the elements of [47mx[0m in reverse order. E.g., [47m(def '(a b c))[0m returns [47m(C B A)[0m. ------------------------------ 20: Define [47msq[0m to square a number. E.g., [47m(sq 9)[0m returns [47m81[0m and [47m(sq -1/2)[0m returns [47m1/4[0m. Answer: (defun sq (x) (* x x)) We could add a declaration, like [47m(declare (xargs :guard (rationalp x)))[0m or [47m(declare (xargs :guard (acl2-numberp x)))[0m. But we've chosen to keep things simple here. ------------------------------ 21: How would you describe the behavior of [47msq*[0m below? (defun sq* (x) (if (endp x) nil (cons (sq (car x)) (sq* (cdr x))))) Answer: It squares every element of [47mx[0m and returns the list of those results in the same order. E.g., [47m(sq* '(1 2 3 -1/2 #c(0 1)))[0m is [47m(1 4 9 1/4) -1[0m. ------------------------------ 22: What would you type to make ACL2 prove the following conjecture? (equal (sq* (def x)) (def (sq* x))) Answer: To get ACL2 to try to prove the theorem you could type (defthm sq*-def (equal (sq* (def x)) (def (sq* x)))) But ACL2 would fail to find the proof unless you'd proved some lemmas about [47mdef[0m. You might see a ``checkpoint'' like *** Key checkpoint under a top-level induction before generating a goal of NIL (see :DOC nil-goal): *** Subgoal *1/2'' (IMPLIES (AND (CONSP X) (EQUAL (DEF (SQ* (CDR X))) (SQ* (DEF (CDR X))))) (EQUAL (APPEND (SQ* (DEF (CDR X))) (LIST (* (CAR X) (CAR X)))) (SQ* (APPEND (DEF (CDR X)) (LIST (CAR X)))))) What would that suggest you do? What we'd do is prove the following lemma first and then try [47msq*-def[0m. (defthm sq*-append (equal (sq* (append a b)) (append (sq* a) (sq* b)))) When that lemma is available as a [47m:[0m[47m[rewrite][0m rule during the proof of [47msq*-def[0m the checkpoint above would be further simplified, the induction hypothesis of the [47msq*-def[0m conjecture would be used, and the proof of [47msq*-def[0m would succeed. The experienced ACL2 user would anticipate this in a simple problem like this one. But in a messier problem the experienced user would just be emotionally prepared for the proof attempt to fail and inspect the checkpoints to try to figure out how to complete the proof. See [the-method]. ------------------------------ 23: Prove [47m(nat-listp (ghi 0 max))[0m, where (defun ghi (i max) (declare (xargs :measure (nfix (- (+ 1 (nfix max)) (nfix i))))) (let ((i (nfix i)) (max (nfix max))) (cond ((> i max) nil) (t (cons i (ghi (+ 1 i) max)))))) Answer: You can't prove [47m(nat-listp (ghi 0 max))[0m by induction with that [47m0[0m in one of the controlling arguments. You have to generalize first. (defthm nat-listp-ghi-lemma (nat-listp (ghi i max))) (defthm nat-listp-ghi (nat-listp (ghi 0 max))) ------------------------------ That completes the answers to this review of basic ACL2 knowledge. If your answers don't largely agree with ours, you're probably not yet ready to read the material in the [loop$-primer]. We recommend that you take the ``Recursion and Induction'' course [31;1m(which should be somehow linked in here!)[0m. (Return to the Table of Contents (see [LP-SECTION-0]).)") (lp-background-review-2 (lp-section-1) "Review of [47m[apply$][0m and related concepts Below are some questions designed to review basic knowledge of [47m[apply$][0m and related concepts used in the semantics of [47mloop$[0m. For our answers see [lp-background-review-2-answers]. But our answers are sometimes quite long and elaborate --- more like little lectures on the subject than just answers. So don't expect to reproduce our answers. It's up to you to decide if you know this stuff. As you use [47mloop$[0m, ACL2 will print warnings and error messages about functions not having badges or warrants or expressions not being tame. We don't want your reaction to be ``Ack! What's that all about?'' We want it to be at least ``Oh yes, I remember now.'' We recommend that after you've read and answered the questions, you read our answers even if you're pretty confident in your answers. ------------------------------ Consider these events, executed as the first three events in new ACL2 sessions. (include-book "projects/apply/top" :dir :system) (defun sq (x) (declare (xargs :guard (natp x))) (* x x)) (defun ghi (fn lst) (declare (xargs :guard (and (apply$-guard fn '(nil)) (true-listp lst)))) (cond ((endp lst) nil) (t (cons (apply$ fn (list (car lst))) (ghi fn (cdr lst)))))) The three events are executed without error and [47msq[0m and [47mghi[0m are admitted in [47m:logic[0m mode. By the way, we're naming certain functions in these reviews with consecutive letters of the alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m, [47mmno[0m, etc. These names are not mnemonic or acronyms. Don't read anything into the names! Note that unlike the review of elementary ACL2 features (see [47m[lp-background-review-1][0m), here we define [47m(sq x)[0m with a guard of [47m(natp x)[0m. Both [47msq[0m and [47mghi[0m are guard verified upon admission. ------------------------------ 1: What is the value of [47m(ghi 'sq '(1 2 3))[0m? Hint: This is a trick question! ------------------------------ 2: How do you assign a badge and warrant to [47msq[0m? ------------------------------ 3: What is the name of the ``warrant function for [47msq[0m?'' What does [47m(warrant sq)[0m abbreviate? What does [47m(warrant sq)[0m imply about [47mbadge[0m and [47mapply$[0m? ------------------------------ 4: Can [47mghi[0m be warranted? If so, what command do you type? ------------------------------ 5: What is the name of the warrant function for [47mghi[0m? Explain what the warrant for [47mghi[0m tells us. ------------------------------ 6: The following definition is admissible. Can it be warranted? (defun mno (x y z) (if (endp x) z (apply$ y (list (car x) (mno (cdr x) y z))))) ------------------------------ 7: Is [47m(equal (mno x 'cons y) (append x y))[0m a theorem? ------------------------------ 8: The following [47mdefun[0m is admissible but cannot be warranted. Why? (defun xyz (x) (apply$ x (list x))) ------------------------------ 9: Recall [47mghi[0m as defined at the beginning of this review. Assume [47msq[0m has been warranted. What is the value of [47m(ghi 'sq '(1 2 3))[0m? ------------------------------ 10: Is [47m(nat-listp (ghi 'sq lst))[0m a theorem? If not, what theorem does this suggest? ------------------------------ 11: What is the value of the term below? (ghi (lambda$ (e) (ghi 'sq e)) '((1 2 3) (4 5 6) (7 8 9))) ------------------------------ 12: Suppose you want to define [47mjkl[0m to be something like what's shown below and you want the guards verified. (defun jkl (lst) (declare (xargs :guard ...)) (ghi (lambda$ (e) (ghi 'sq e)) lst))) Notice that the body of [47mjkl[0m is the doubly nested [47mghi[0m term just tested, except now instead of applying it to a constant list we're applying it to the argument of [47mjkl[0m. What is the appropriate [47m:[0m[47m[guard][0m and do you have to make other modifications to the suggested [47mdefun[0m of [47mjkl[0m? ------------------------------ 13: Can [47mjkl[0m be warranted? ------------------------------ 14: Is this a theorem? If not, what theorem does it suggest? (implies (nat-listp-listp lst) (nat-listp-listp (jkl lst))) ------------------------------ See [lp-background-review-2-answers] for our answers. If your answers basically agree with ours we think you're ready to learn about [47mloop$[0m, so go back to the [loop$-primer]. Otherwise, we strongly recommend that you read [introduction-to-apply$] and then [47m[apply$][0m before reading about [47mloop$[0m. (Return to the Table of Contents (see [LP-SECTION-0]).)") (lp-background-review-2-answers (lp-section-1) "Answers to the review of [47m[apply$][0m and related concepts Below are our answers to the Review of [47m[apply$][0m and related concepts. If your answers basically agree with ours, we think you're ready to follow the discussion in [47m[loop$-primer][0m. If not, we recommend that you read [introduction-to-apply$] and then [47m[apply$][0m before reading about [47mloop$[0m. But our answers are sometimes quite long and elaborate --- more like little lectures on the subject than just answers. So don't expect to reproduce our answers. It's up to you to decide if you know this stuff. As you use [47mloop$[0m, ACL2 will print warnings and error messages about functions not having badges or warrants or expression not being tame. We don't want your reaction to be ``Ack! What's that all about?'' We want it to be at least ``Oh yes, I remember now.'' So we recommend that you read these little mini-lectures in full. ------------------------------ Consider these events, executed as the first three events in new ACL2 sessions. (include-book "projects/apply/top" :dir :system) (defun sq (x) (declare (xargs :guard (natp x))) (* x x)) (defun ghi (fn lst) (declare (xargs :guard (and (apply$-guard fn '(nil)) (true-listp lst)))) (cond ((endp lst) nil) (t (cons (apply$ fn (list (car lst))) (ghi fn (cdr lst)))))) The three events are executed without error and [47msq[0m and [47mghi[0m are admitted in [47m:logic[0m mode. By the way, we're naming certain functions in these reviews with consecutive letters of the alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m, [47mmno[0m, etc. These names are not mnemonic or acronyms. Don't read anything into the names! Note that unlike the review of elementary ACL2 features (see [47m[lp-background-review-1][0m), here we define [47m(sq x)[0m with a guard of [47m(natp x)[0m. Both [47msq[0m and [47mghi[0m are guard verified upon admission. ------------------------------ 1: What is the value of [47m(ghi 'sq '(1 2 3))[0m? Hint: This is a trick question! Answer: Note that [47mghi[0m is a [scion] of [47mapply$[0m. It calls [47mapply$[0m, passing in the first argument of [47mghi[0m as the ``function'' to [47mapply$[0m. The evaluation of the above term fails with an error message because [47msq[0m is a user-defined [47m:[0m[47m[logic][0m mode function but has not been [warrant]ed (see [47m[defwarrant][0m). [47m:Logic[0m mode functions must be warranted to be applied (with [47mapply$[0m) at the top-level of the ACL2 read-eval-print loop. Furthermore, if you ever try to prove a theorem whose proof requires expansion of the applications (with [47mapply$[0m) of such functions, their warrants must be provided as hypotheses. We'll get to that later. By the way, [47m:[0m[47m[program][0m mode functions must be [47m[badge][0md (see [47m[defbadge][0m) to be applied at the top-level, but they need not be warranted (because [47m:program[0m mode functions cannot be warranted or used meaningfully in conjectures to be proved). See [guarantees-of-the-top-level-loop] for a discussion of the badge and warrant restrictions enforced by top-level evaluation. ------------------------------ 2: How do you assign a badge and warrant to [47msq[0m? Answer: [47m(defwarrant sq)[0m. [47m[Defwarrant][0m assigns both a badge and a warrant to its argument, which must be a [47m:logic[0m mode function satisfying certain restrictions on how it uses its arguments and how the termination of the function is justified. If the function cannot be badged or cannot be warranted, an error is printed. [47m[Defbadge][0m just assigns a badge and can work on [47m:program[0m or [47m:logic[0m mode functions. ------------------------------ 3: What is the name of the ``warrant function for [47msq[0m?'' What does [47m(warrant sq)[0m abbreviate? What does [47m(warrant sq)[0m imply about [47mbadge[0m and [47mapply$[0m? Answer: The warrant function for [47msq[0m is named [47mapply$-warrant-sq[0m, which is a 0-ary predicate. [47m(Warrant sq)[0m is just an abbreviation for a call of [47mapply$-warrant-sq[0m and if more than one function symbol appears after the symbol [47mwarrant[0m then it expands to the conjunction of each of their predicates. We'll show an example later. [47mApply$-warrant-sq[0m is introduced as a constrained function using [47m[defun-sk][0m. Here is the event in question, but the details here are not critical to the present discussion. (defun-sk apply$-warrant-sq () (forall (args) (and (equal (badge-userfn 'sq) '(apply$-badge 1 1 . t)) (equal (apply$-userfn 'sq args) (sq (car args))))) :constrain t) What is critical is the role that [47m(apply$-warrant-sq)[0m plays in the following theorem, which is proved as a [47m:[0m[47m[rewrite][0m rule by [47m(defwarrant sq)[0m. (defthm apply$-sq (implies (force (apply$-warrant-sq)) (and (equal (badge 'sq) '(apply$-badge 1 1 . t)) (equal (apply$ 'sq args) (sq (car args)))))) which allows the prover to reduce [47m(badge 'sq)[0m to [47m(apply$-badge 1 1 . t)[0m and to reduce any instance of [47m(apply$ 'sq args)[0m to [47m(sq (car args))[0m. The [47m[badge][0m of [47msq[0m tells the prover that [47msq[0m is a function of one argument that returns one result. The ``[47m . t[0m'' means ``all the arguments are ordinary objects,'' i.e., never treated like ``functions.'' The second part of the rule above will reduce the typical application of [47msq[0m, e.g., [47m(apply$ 'sq (list e))[0m, to [47m(sq e)[0m. Finally, note that name of the rule is [47mapply$-sq[0m, both the [47mbadge[0m and [47mapply$[0m reductions are conditional on the warrant hypothesis for [47msq[0m, and that the warrant hypothesis is [47m[force][0md. ------------------------------ 4: Can [47mghi[0m be warranted? If so, what command do you type? Answer: Yes! Just type [47m(defwarrant ghi)[0m. ------------------------------ 5: What is the name of the warrant function for [47mghi[0m? Explain what the warrant for [47mghi[0m tells us. Answer: The warrant function for [47mghi[0m is named [47mapply$-warrant-ghi[0m. [47m(warrant ghi)[0m abbreviates [47m(apply$-warrant-ghi)[0m, and, by the way, [47m(warrant sq ghi ...)[0m expands to (and (apply$-warrant-sq) (apply$-warrant-ghi) ...). The rule [47mapply$-ghi[0m is proved by [47mdefwarrant[0m. (defthm apply$-ghi (and (implies (force (apply$-warrant-ghi)) (equal (badge 'ghi) '(apply$-badge 2 1 :fn nil))) (implies (and (force (apply$-warrant-ghi)) (tamep-functionp (car args))) (equal (apply$ 'ghi args) (ghi (car args) (car (cdr args))))))) Notice that [47mapply$-ghi[0m is really two [47m:rewrite[0m rules, both conditioned on the forced warrant for [47mghi[0m. The first rule tells us what the [47m[badge][0m of [47mghi[0m is. In particular we see that the first argument of [47mghi[0m has ``[ilk]'' [47m:[0m[47mfn[0m, which means that argument is treated as a function and can eventually be applied with [47mapply$[0m. Arguments of ilk [47m:fn[0m are never treated as ordinary objects. The badge of [47mghi[0m also tells us the second argument has ilk [47mnil[0m, which means it is an ordinary object (and is never treated as a function). The details are in [47m[defbadge][0m. Note that the second conjunct of the [47mapply$-ghi[0m rule above rewrites instances of [47m(apply$ 'ghi args)[0m and would rewrite [47m(apply$ 'ghi (list x y))[0m to [47m(ghi x y)[0m. However, it can only be used if the first argument passed to [47mghi[0m, namely [47mx[0m above, is a [tame] function. Ilks, warrants, and tameness are concepts that are critical to the soundness of ACL2's handling of [47mapply$[0m. For details see [47m[apply$][0m. ------------------------------ 6: The following definition is admissible. Can it be warranted? (defun mno (x y z) (if (endp x) z (apply$ y (list (car x) (mno (cdr x) y z))))) Answer: Yes. Its badge is determined to be [47m(apply$-badge 3 1 nil :fn nil)[0m. For example, (mno '(1 2 3) 'cons '(4 5 6)) = (cons 1 (mno '(2 3) 'cons '(4 5 6))) = (cons 1 (cons 2 (mno '(3) 'cons '(4 5 6)))) = (cons 1 (cons 2 (cons 3 (mno 'nil 'cons '(4 5 6))))) = (cons 1 (cons 2 (cons 3 '(4 5 6)))) = '(1 2 3 4 5 6) In fact, [47mmno[0m is more often named ``[47mfoldr[0m'' in the functional programming literature. ------------------------------ 7: Is [47m(equal (mno x 'cons y) (append x y))[0m a theorem? Answer: Yes! You might think we need to add the warrant hypothesis for [47mcons[0m since [47m(apply$ 'cons ...)[0m must be expanded to do the proof. However, most ACL2 primitives, like [47mcons[0m, are built into the definition of [47mapply$[0m and warrants are not necessary for them. In fact, the primitives don't have warrant functions. E.g., [47m(apply$ 'cons (list x y))[0m is [47m(cons x y)[0m, unconditionally. The complete list of [47mapply$[0m primitives may be exhibited by evaluating (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP APPLY$ EV$) (strip-cars *badge-prim-falist*)). However, [3muser-defined function symbols[0m need warrants in order to be applied (with [47mapply$[0m). But not all user-defined symbols can be warranted. ------------------------------ 8: The following [47mdefun[0m is admissible but cannot be warranted. Why? (defun xyz (x) (apply$ x (list x))) Answer: It is impossible to classify the argument [47mx[0m. Is it a function or is it an ordinary object? It's used both ways. [47m(Defwarrant xyz)[0m fails. In order for [47mapply$[0m to be able to handle a function symbol certain restrictions must hold. These restrictions guarantee that there is a model that makes all warrants true. Here's a way to think about it. Imagine that [47mapply$[0m is defined as a big case analysis that enumerates all the functions that [47mapply$[0m can handle and calls them appropriately. That big definition of [47mapply$[0m has some measure that explains why it terminates --- a fairly messy measure given that [47mapply$[0m can all [47mghi[0m which calls [47mapply$[0m. Now imagine you want to define a new function, e.g., [47mxyz[0m, and change the definition of that big [47mapply$[0m to include all the old functions plus [47mxyz[0m. You'll need to weave the measure of [47mxyz[0m into the measure of the big [47mapply$[0m. [47mDefwarrant[0m enforces restrictions that tell us this is possible. Of course, the restrictions are overly restrictive: to be perfect [47mdefwarrant[0m would have to solve the halting problem. While the failure of [47m(defwarrant xyz)[0m prevents us from being able to use [47mapply$[0m to apply [47mxyz[0m, it is possible to evaluate some calls of [47mxyz[0m and to prove theorems about them. (thm (equal (xyz '(lambda (x) (len x))) 3) In the proof of the theorem above, [47mxyz[0m applied the given [47mlambda[0m object to itself and computed that its length is 3. ------------------------------ 9: Recall [47mghi[0m as defined at the beginning of this review. Assume [47msq[0m has been warranted. What is the value of [47m(ghi 'sq '(1 2 3))[0m? Answer: [47m(1 4 9)[0m. Recall that an earlier question established that [47mghi[0m can be warranted and one might think warranting [47mghi[0m is necessary for [47m(ghi 'sq '(1 2 3))[0m to be evaluated without error. But that's untrue. [47mGhi[0m is not being applied (with [47mapply$[0m) here, so whether it has been warranted or not is irrelevant. However, [47msq[0m is being applied. ------------------------------ 10: Is [47m(nat-listp (ghi 'sq lst))[0m a theorem? If not, what theorem does this suggest? Answer: No, it's not a theorem as written. For example [47m(ghi 'sq '(-1/2 #c(0 1)))[0m has the value [47m(1/4 -1)[0m, although to get that value computed by the top-level read-eval-print loop you have to turn off guard checking (see [47m[set-guard-checking][0m). The following is a theorem. (implies (and (warrant sq) (nat-listp lst)) (nat-listp (ghi 'sq lst))) The [47mwarrant[0m hypothesis for [47msq[0m is necessary because to prove anything interesting about [47m(apply$ 'sq ...)[0m we need the warrant for [47msq[0m. The [47mnat-listp[0m hypothesis is necessary because otherwise [47msq[0m may not return a natural number. ------------------------------ 11: What is the value of the term below? (ghi (lambda$ (e) (ghi 'sq e)) '((1 2 3) (4 5 6) (7 8 9))) Answer: [47m((1 4 9) (16 25 36) (49 64 81))[0m. [47m[Lambda$][0m is an interesting ACL2 feature. It translates the body term and constructs a [47mlambda[0m object suitable for [47mapply$[0m. The [47mghi[0m term above is also interesting. It shows that the outer call of [47mghi[0m can successfully [47mapply$[0m the [47mlambda[0m object which itself calls [47mghi[0m on [47msq[0m. ------------------------------ 12: Suppose you want to define [47mjkl[0m to be something like what's shown below and you want the guards verified. (defun jkl (lst) (declare (xargs :guard ...)) (ghi (lambda$ (e) (ghi 'sq e)) lst))) Notice that the body of [47mjkl[0m is the doubly nested [47mghi[0m term just tested, except now instead of applying it to a constant list we're applying it to the argument of [47mjkl[0m. What is the appropriate [47m:[0m[47m[guard][0m and do you have to make other modifications to the suggested [47mdefun[0m of [47mjkl[0m? Answer: First, we define a predicate that recognizes a list of [47mnat-listp[0ms, i.e., a list of lists, where each element of each of the inner lists is a natural number. (defun nat-list-listp (lst) (declare (xargs :guard (true-listp lst))) (if (endp lst) t (and (nat-listp (car lst)) (nat-list-listp (cdr lst))))) We could warrant [47mnat-list-listp[0m with [47m(defwarrant nat-list-listp)[0m if we wanted to, but because it is only used in a guard below, a warrant is not necessary. If we intend to apply it with [47mapply$[0m we would need a warrant and we can always warrant it when needed. We can then define [47mjkl[0m with the :[47mguard[0m shown below. The [47mtrue-listp[0m conjunct of the guard below is necessary because [47mnat-list-listp[0m has [47mtrue-listp[0m as its guard. But note that we also modified the [47m[lambda$][0m expression to express the guard on its local variable [47me[0m. (defun jkl (lst) (declare (xargs :guard (and (true-listp lst) (nat-list-listp lst)))) (ghi (lambda$ (e) (declare (xargs :guard (nat-listp e))) (ghi 'sq e)) lst)) [47mJkl[0m is guard verified upon admission. Consider what that means. In particular, every time [47msq[0m is called it is called on something satisfying the guard of [47msq[0m. The guard proof obligations generated for a nest of functions using [47mapply$[0m can be quite messy. ------------------------------ 13: Can [47mjkl[0m be warranted? Answer: Yes. [47m(defwarrant jkl)[0m succeeds. A key observation is that the [47mlambda$[0m expression in its definition is a [47mtame[0m function (see [47mtame[0m). That is syntactically determined because the body of the [47mlambda$[0m is [47m(ghi 'sq e)[0m, [47mghi[0m requires a tame function as its first argument, and [47msq[0m is a tame function. ------------------------------ 14: Is this a theorem? If not, what theorem does it suggest? (implies (nat-list-listp lst) (nat-list-listp (jkl lst))) Answer: It is not quite a theorem as written. We need to add warrant hypotheses for the functions being applied with [47mapply$[0m. Note that [47mjkl[0m is not being applied, so we don't need its warrant. The outer [47mghi[0m in the definition of [47mjkl[0m is also not being applied. But the [47m[lambda$][0m expression passed as an argument to the outer [47mghi[0m is being applied by the outer [47mghi[0m, and to evaluate the body of that [47mlambda[0m object we [47mapply$[0m [47mghi[0m, so we need the warrant for [47mghi[0m there. Furthermore, that inner [47mghi[0m will apply [47msq[0m. So we need the warrant for that. Thus, the following is indeed a theorem. (implies (and (warrant ghi sq) (nat-list-listp lst)) (nat-list-listp (jkl lst))) For some heuristic advice on how to figure out the necessary warrants, see the section ``Determining the Necessary Warrants'' in see [47m[warrant][0m. However, if you omit the warrant hypotheses ACL2 will often ``remind'' you at the end of failed proof attempts by exhibiting checkpoints derived from forcing the warrants when [47mapply$[0m rules are applied. If the warrants are omitted in this particular theorem checkpoints require proving both [47m(apply$-warrant-sq)[0m and [47m(apply$-warrant-ghi)[0m. Finally, one might worry that it is impossible for all the listed warrants to be true at once, so perhaps listing a bunch of warrants might make your theorems vacuously valid. But [47mdefwarrant[0m ensures that there is a model of the ACL2 logic in which all warrants are valid. Thus, adding warrant hypotheses in no way makes your theorems less meaningful. ------------------------------ If your answers basically agree with ours you should proceed on to [lp-section-2]. Otherwise, we strongly recommend that you read [introduction-to-apply$] and then [47m[apply$][0m before reading about [47mloop$[0m. (Return to the Table of Contents (see [LP-SECTION-0]).)") (lp-section-0 (loop$-primer) "Loop$ Primer Table of Contents) The Loop$ Primer Table of Contents * [loop$-primer]: Preface * lp-section-0: Table of Contents * [lp-section-1]: Background Reviews * [lp-section-2]: [47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2 * [lp-section-3]: Examples of [47mFOR[0m [47mLoop$[0ms * [lp-section-4]: Syntax of [47mFOR[0m [47mLoop$[0ms * [lp-section-5]: Informal Semantics of [47mFOR[0m [47mLoop$[0ms * [lp-section-6]: Challenge Problems about [47mFOR[0m [47mLoop$[0ms * [lp-section-7]: Using [47mLoop$[0ms and Guards in [47mDefun[0ms * [lp-section-8]: Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms * [lp-section-9]: Semantics of [47mFOR[0m [47mLoop$[0ms * [lp-section-10]: The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m * [lp-section-11]: Proving Theorems about [47mFOR[0m [47mLoop$[0ms * [lp-section-12]: Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms * [lp-section-13]: Examples of [47mDO[0m [47mLoop$[0ms * [lp-section-14]: Challenge Problems about [47mDO[0m [47mLoop$[0ms * [lp-section-15]: Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms * [lp-section-16]: Proving Theorems about [47mDO[0m [47mLoop$[0ms * [lp-section-17]: Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms * [lp-section-18]: Conclusion * lp-section-0: Table of Contents") (lp-section-1 (loop$-primer) "Background Reviews LP1: Background Reviews We assume you're familiar with elementary Common Lisp and ACL2. The questions and answers in [lp-background-review-1] offer a quick review. Come back here when you're comfortable with such questions. [47mLoop$[0m makes extensive use of ACL2's limited second order functionality. The questions and answers in [47m[lp-background-review-2][0m offer a quick review of the main features and limitations of [47mapply$[0m and the related concepts. We assume you're comfortable with these features too. Now go to [lp-section-2] (or return to the Table of Contents (see [LP-SECTION-0])). Subtopics [Lp-background-review-1] Background review of basic ACL2 knowledge [Lp-background-review-1-answers] Answers to background review of basic ACL2 knowledge [Lp-background-review-2] Review of [47m[apply$][0m and related concepts [Lp-background-review-2-answers] Answers to the review of [47m[apply$][0m and related concepts") (lp-section-10 (loop$-primer) "The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m LP10: The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m Below we show the evaluation of a fancy [47mloop$[0m that uses the function [47mpackn[0m to create a list of symbols. We start with an example of [47mpackn[0m so you can infer its behavior. But our real interest is the behavior of the [47mloop$[0m. ACL2 !>(packn (list 'R2 '- 'D 2)) R2-D2 ACL2 !>(let ((mark '*)) (loop$ for x in '(a * b c d e * f g h i j * k) as y in '(u v * w * u v * x y z) as i from 0 to 100 by 3 when (and (evenp i) (not (eq x mark)) (not (eq y mark))) collect (packn (list x y '_ i)))) (AU_0 GX_24 IZ_30) ACL2 !> We now explain carefully the evaluation of the [47mloop$[0m expression above in an environment in which [47mmark[0m is bound to the asterisk symbol, [47m*[0m. The first three lines of the [47mloop$[0m introduce the so-called [3miteration variables[0m, [47mx[0m, [47my[0m, and [47mi[0m, and their respective [3mranges[0m. The [47mwhen[0m clause specifies a predicate on the iteration variables, identifying the ``good'' cases, i.e., the values of the iteration variables that we care about. However, note that the predicate above mentions the variable [47mmark[0m, which is not one of the iteration variables. We call such variables [3mglobals[0m because their values are not set within the scope of the [47mloop[0m. The [47mcollect[0m clause specifies an expression to be evaluated on the ``good'' iteration variable values and collects the results of those evaluations. If you replace the symbol [47mloop$[0m above by [47mloop[0m you get a legal Common Lisp [47mloop[0m expression with the same value (if executed when [47mmark[0m is bound to [47m*[0m). For our purposes, the easiest way to think about this particular statement is to decompose it into three steps. Step 1: The lines introducing the iteration variables and their ranges cause us to make a table of corresponding values of [47mx[0m, [47my[0m, and [47mi[0m, as shown below in the form of a list of triples. This list is as long as the shortest individual range. ; x y i ((A U 0) (* V 3) (B * 6) (C W 9) (D * 12) (E U 15) (* V 18) (F * 21) (G X 24) (H Y 27) (I Z 30)). Step 2: the [47mwhen[0m clause maps over the above table and identifies the entries as ``good'' or ``bad'', where the good ones have an even value for [47mi[0m and values for [47mx[0m and [47my[0m that are not the asterisk mark, [47m*[0m. We annotate the table accordingly below. ; x y i ((A U 0) ; GOOD! (* V 3) ; bad: odd i (and asterisk) (B * 6) ; bad: asterisk (C W 9) ; bad: odd i (D * 12) ; bad: asterisk (E U 15) ; bad: odd i (* V 18) ; bad: asterisk (F * 21) ; bad: odd i (and asterisk) (G X 24) ; GOOD! (H Y 27) ; bad: odd i (I Z 30)). ; GOOD! Effectively the [47mwhen[0m clause pares down the table to just the good entries. ; x y i ((A U 0) ; GOOD! (G X 24) ; GOOD! (I Z 30)). ; GOOD! Step 3: the [47mcollect[0m clause maps over pared-down table, evaluating and collecting the results of [47m(packn (list x y '_ i))[0m for each triple in the table. (AU_0 GX_24 IZ_30). The ACL2 semantics of the [47mloop$[0m statement reflects this understanding of the statement. (The display below is the output of [47m:tca[0m on the [47mloop$[0m, but with the [47mDECLARE[0m forms deleted and the three comments added.) (collect$+ ; step 3 (lambda$ (loop$-gvars loop$-ivars) (let ((x (car loop$-ivars)) (y (cadr loop$-ivars)) (i (caddr loop$-ivars))) (packn (list x y '_ i)))) nil (when$+ ; step 2 (lambda$ (loop$-gvars loop$-ivars) (let ((mark (car loop$-gvars)) (x (car loop$-ivars)) (y (cadr loop$-ivars)) (i (caddr loop$-ivars))) (and (evenp i) (not (eq x mark)) (not (eq y mark))))) (list mark) (loop$-as (list '(a * b c d e * f g h i j * k) ; step 1 '(u v * w * u v * x y z) (from-to-by 0 100 3))))) In step 1, the [47mloop$-as[0m function takes a list of the individual ranges and builds the first version of the iteration variable table. The function [47mfrom-to-by[0m just enumerates the integers from its first argument to its second argument in steps of size given by its third argument. In step 2, the [47mwhen$+[0m function takes three arguments. Note that the last argument of the [47mwhen$+[0m function is the iteration variable table computed by step 1. The first argument of the [47mwhen$+[0m function is a [47mlambda$[0m expression representing the predicate used to identify the ``good'' entries. But that predicate may also require the value of any global variables used. So the [47mlambda$[0m expression has two arguments, [47mloop$-gvars[0m, the list of values of the global variables, and [47mloop$-ivars[0m, a tuple of values corresponding to a line in the iteration variable table. The middle argument of the [47mwhen$+[0m provides the values of the global variables and, as noted earlier, the last argument is the iteration variable table. The [47mwhen$+[0m maps over the iteration variable table and collects the ``good'' lines, returning them as a list. In step 3, the [47mcollect$+[0m takes three arguments. The first is a [47mlambda$[0m expression on the [47mloop$-gvars[0m and [47mloop$-ivars[0m as above. The second and third arguments are the global variable values and the ``good'' lines from the pared-down iteration variable table as computed by step 2. Note that since the [47mcollect[0m clause does not mention any global variables the global variable tuple in the second argument of the [47mcollect$+[0m is [47mnil[0m. Of course, Common Lisp does not decompose the corresponding [47mloop[0m statement this way but generates much more efficient compiled code. The ACL2 semantics is rendered compositionally to make it easier to reason about [47mloop$[0m statements. If the guards of the [47mloop$[0m statement --- which we haven't discussed yet --- are verified then the ACL2 loop$ statement is rendered into the corresponding Common Lisp [47mloop[0m statement, compiled, and efficiently executed. Now go to [lp-section-11] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-11 (loop$-primer) "Proving Theorems about [47mFOR[0m [47mLoop$[0ms LP11: Proving Theorems about [47mFOR[0m [47mLoop$[0ms Proving theorems about [47mFOR[0m [47mloop$[0m in ACL2 is essentially no different than proving theorems about other constructs in ACL2. Indeed, since [47mloop$[0ms turn into calls of [scion]s of [47m[apply$][0m, proving things about them is exactly the problem of proving things about scions. However, [47mloop$[0ms raise some problems that are not fully technical. * Iteration is so common in programming --- and the meaning of [47mloop$[0m statements are intuitively obvious --- that you often don't think anything logically complicated is going on! But when proofs are desired you must keep induction in mind and you must train yourself to see the need for generalization in order to allow the necessary inductions. * You're not syntactically aware of the presence of [47mapply$[0m and the concomitant need for [tame]ness and [warrant]s. * You don't see the translations of [47mloop$[0ms when you type them but they appear ``unexpectedly'' in the checkpoints of failing proofs and that can throw you for a loop (so to speak). * The translations of [47mloop$[0ms, especially of fancy [47mloop$[0m, are pretty complicated in and of themselves and can be difficult to understand, much less generalize and manipulate formally. * The ACL2 user rarely has to think about local variable bindings, but those issues arise quite often in dealing with loop$s (and nested [47mlambda[0m objects in general). With these points in mind we will now work through a proof about a fancy [47mloop$[0m. In the next section we'll challenge you to do some proofs about other [47mloop$[0ms. The proof description below is rather long because we cast it as a narrative of the proof discovery process and the actual chronology of events submitted, including failed events and our thoughts about the failures. Sample Question: Define the function [47mall-pairs[0m recursively so that [47m(all-pairs imax jmax)[0m creates a list of all pairs [47m(i . j)[0m where [47m1 <= i <= imax[0m and [47m1 <= j <= jmax[0m. Then define the [47mloop$[0m version of [47mall-pairs[0m and prove it is equivalent to [47mall-pairs[0m. Both versions must be guard verified. Sample Solution (as a narrative of the discovery). As usual, we make sure we're operating in a session where (include-book "projects/apply/top" :dir :system) We will construct our pairs with (defun make-pair (i j) (declare (xargs :guard t)) (cons i j)) Here is our recursive definition. It involves two helper functions. [47mAll-pairs-helper2[0m keeps [47mi[0m fixed and runs [47mj[0m from [47m1[0m to [47mjmax[0m to compute the list of pairs [47m((i . 1) (i . 2) ... (i . jmax))[0m. [47mAll-pairs-helper1[0m just calls the former helper for each [47mi[0m from [47m1[0m to [47mimax[0m and appends the lists together. The top-level [47mall-pairs[0m calls [47mall-pairs-helper1[0m with [47mi[0m properly initialized to [47m1[0m. (defun all-pairs-helper2 (i j jmax) (declare (xargs :measure (nfix (- (+ (nfix jmax) 1) (nfix j))) :guard (and (natp i) (natp j) (natp jmax)))) (let ((j (nfix j)) (jmax (nfix jmax))) (cond ((> j jmax) nil) (t (cons (make-pair i j) (all-pairs-helper2 i (+ 1 j) jmax)))))) (defun all-pairs-helper1 (i imax jmax) (declare (xargs :measure (nfix (- (+ (nfix imax) 1) (nfix i))) :guard (and (natp i) (natp imax) (natp jmax)))) (let ((i (nfix i)) (imax (nfix imax))) (cond ((> i imax) nil) (t (append (all-pairs-helper2 i 1 jmax) (all-pairs-helper1 (+ 1 i) imax jmax)))))) (defun all-pairs (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (all-pairs-helper1 1 imax jmax)) Here is a simple test. ACL2 !>(all-pairs 2 4) ((1 . 1) (1 . 2) (1 . 3) (1 . 4) (2 . 1) (2 . 2) (2 . 3) (2 . 4)) And here is our first attempt to define the [47mloop$[0m version, which is considerably ``simpler'' (or, at least, shorter). But this will fail! Can you say why without reading the error message? (defun all-pairs-loop$ (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (loop$ for i from 1 to imax append (loop$ for j from 1 to jmax collect (make-pair i j)))) ACL2 Error [Translate] in ( DEFUN ALL-PAIRS-LOOP$ ...): The body of a LAMBDA object, lambda$ term, or loop$ statement should be fully badged but MAKE-PAIR is used in ((LAMBDA (I J) (MAKE-PAIR I J)) (CAR LOOP$-GVARS) (CAR LOOP$-IVARS)) and has no badge. ... ... Note: this error occurred in the context (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL # 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL # 1)))) (LET ((I (CAR LOOP$-GVARS)) (J (CAR LOOP$-IVARS))) (DECLARE (IGNORABLE I J)) (MAKE-PAIR I J))). The error message above includes some extraneous possible explanation of the error which we've omitted. The error tells us we forgot to assign a badge to [47mmake-pair[0m. We could call [47m(defbadge make-pair)[0m at this point. But since we intend to prove things about [47mall-pairs-loop$[0m we'll actually need the warrant for the [47mmake-pair[0m, since [47mmake-pair[0m is user-defined and is used in the body of a [47mloop$[0m. So we'll go ahead and create the warrant. (defwarrant make-pair) (Had we just badged [47mmake-pair[0m at this point and proceeded another error message would crop up in due course and tell us to warrant it.) Trying the [47mdefun[0m again causes another failure with the checkpoint shown below. (defun all-pairs-loop$ (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (loop$ for i from 1 to imax append (loop$ for j from 1 to jmax collect (make-pair i j)))) *** Key checkpoint at the top level: *** Subgoal 1.2' (IMPLIES (AND (CONSP LOOP$-IVARS) (NOT (CDR LOOP$-IVARS)) (CONSP LOOP$-GVARS) (NOT (CDR LOOP$-GVARS))) (INTEGERP (CAR LOOP$-GVARS))) ACL2 Error [Failure] in ( DEFUN ALL-PAIRS-LOOP$ ...): The proof of the guard conjecture for ALL-PAIRS-LOOP$ has failed; see the discussion above about :VERIFY-GUARDS and :GUARD-DEBUG. See :DOC failure. We need to prove, as part of the guard verification, that [47m(CAR LOOP$-GVARS)[0m is an integer. At this point we might want to refresh our idea of what the formal semantics of that nested loop$ is! We do not recommend using [47m:trans[0m for that refreshment! You can try it and you'll see 67 lines of output with a lot of extra stuff in it used to help evaluate such forms efficiently. Instead we'll use [47m:tca[0m (``translate, clean, and annotate'') which produces about half as much output and shows the original form of each [47mloop$[0m together with formal semantics, complete with [47m:guard[0m declarations on the [47mLAMBDA[0m objects and correspondences between the variable names used in the original statement with the components of the formals [47mLOOP$-GVARS[0m and [47mLOOP$-IVARS[0m in the [47mlambda$[0m terms generated. (Note: We have manually inserted some comments to identify certain lines of the display below.) ACL2 !>:tca (loop$ for i from 1 to imax append (loop$ for j from 1 to jmax collect (make-pair i j))) (PROG2$ '(LOOP$ FOR I FROM 1 TO IMAX APPEND (LOOP$ FOR J FROM 1 TO JMAX COLLECT (MAKE-PAIR I J))) (APPEND$+ ; [0] (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) ; [1] (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) ; [2] (EQUAL (LEN LOOP$-GVARS) 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1)) :SPLIT-TYPES T)) (LET ((JMAX (CAR LOOP$-GVARS)) ; [3] (I (CAR LOOP$-IVARS))) (PROG2$ '(LOOP$ FOR J FROM 1 TO JMAX COLLECT (MAKE-PAIR I J)) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1)) :SPLIT-TYPES T)) (LET ((I (CAR LOOP$-GVARS)) (J (CAR LOOP$-IVARS))) (MAKE-PAIR I J))) (LIST I) (LOOP$-AS (LIST (FROM-TO-BY 1 JMAX 1))))))) ; [4] (LIST JMAX) ; [5] (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1))))) ; [6] We're trying to verify the guards all the functions in that expression, and we have the [47m:guard[0m in the [47mdefun[0m of [47mall-pairs-loop$[0m to work with. That [47m:guard[0m is [47m(and (natp imax) (natp jmax))[0m. So what functions above require an argument to be an integer? Hint: There is only one such function but it occurs in two places. [47mFrom-to-by[0m requires all three of its arguments to be integers and that function appears on lines [4] and [6]. Line [4] requires [47mjmax[0m to be an integer and line [6] requires [47mimax[0m to be an integer. But line [6] is the formal term representing the ``[47mfrom 1 to imax[0m'' range of the [47mappend[0m [47mloop$[0m formalized with the fancy scion [47mAPPEND$+[0m at line [0]. That [47mimax[0m is literally the first formal variable of the defun of [47mall-pairs-loop$[0m whose [47m:guard[0m says [47mimax[0m and [47mjmax[0m are a naturals. So [6] is not the problem. The [47mjmax[0m in line [4], on the other hand, is actually a [47mlet[0m-bound variable (see line [3]) within the [47mlambda[0m object (line [1]) that is the body of the [47mappend[0m loop$ [line 0]. [47mjmax[0m is bound inside that [47mlambda[0m on line [3] to [47m(car loop$-gvars)[0m and the [47m:guard[0m (line [2]) of that [47mlambda[0m does not require [47m(car loop$-gvars)[0m to be an integer. We need to add that requirement to [2]. So how do we change the [47m:guard[0m of a [47mlambda[0m generated by the translation of the [47mappend[0m [47mloop$[0m? We add ``[47m:guard (natp jmax)[0m'' after the [47mappend[0m operator. (Note that [47m(integerp jmax)[0m would suffice here but we added the stronger condition ensured by the [47mall-pairs-loop$[0m's guard.) Using [47m:tca[0m again on the modified [47mloop$[0m confirms our change. ACL2 !>:tca (loop$ for i from 1 to imax append :guard (natp jmax) ; [new] (loop$ for j from 1 to jmax collect (make-pair i j))) (PROG2$ '(LOOP$ FOR I FROM 1 TO IMAX APPEND (LOOP$ FOR J FROM 1 TO JMAX COLLECT (MAKE-PAIR I J))) (APPEND$+ ; [0] (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) ; [1] (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) ; [2'] (EQUAL (LEN LOOP$-GVARS) 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1) (NATP (CAR LOOP$-GVARS))) ; [new] :SPLIT-TYPES T)) (LET ((JMAX (CAR LOOP$-GVARS)) ; [3] (I (CAR LOOP$-IVARS))) (PROG2$ '(LOOP$ FOR J FROM 1 TO JMAX COLLECT (MAKE-PAIR I J)) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1)) :SPLIT-TYPES T)) (LET ((I (CAR LOOP$-GVARS)) (J (CAR LOOP$-IVARS))) (MAKE-PAIR I J))) (LIST I) (LOOP$-AS (LIST (FROM-TO-BY 1 JMAX 1))))))) ; [4] (LIST JMAX) ; [5] (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1))))) ; [6] Observe the difference between the [47m:guard[0m on the original line [2] and the [47m:guard[0m on the new line [2']. The latter includes [47m(natp (car loop$-gvars))[0m. If we think in terms of scions, we're saying ``Every time this [47mlambda[0m object is applied, its two formals must satisfy the conjunction beginning at line [2'].'' Finally, how do we know every application of the [47mlambda[0m by the fancy scion [47mappend$+[0m (line [0]) will satisfy this guard? We know from the definition of [47mappend$+[0m that every application supplies the [47m(list jmax)[0m from line [5] as the value of [47mloop$-gvars[0m. That occurrence of [47mjmax[0m is at the top-level of the body and in the scope of the guard of [47mall-pairs-loop$[0m, which says [47mjmax[0m is a natural. So the guards can be proved now. So now we can admit and verify the guards of our [47mloop$[0m version of [47mall-pairs[0m. (defun all-pairs-loop$ (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (loop$ for i from 1 to imax append :guard (natp jmax) (loop$ for j from 1 to jmax collect (make-pair i j)))) Our goal is to prove the theorem below. We use [The-Method], with which we assume you're familiar but which we narrate below. First we try to prove our main goal. It fails with the checkpoint shown. (defthm main (implies (and (natp imax) (natp jmax)) (equal (all-pairs-loop$ imax jmax) (all-pairs imax jmax)))) *** Key checkpoint at the top level: *** Goal'' (IMPLIES (AND (INTEGERP IMAX) (<= 0 IMAX) (INTEGERP JMAX) (<= 0 JMAX)) (EQUAL (APPEND$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (CONS (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) (LIST (CAR LOOP$-IVARS)) (LOOP$-AS (LIST (FROM-TO-BY 1 (CAR LOOP$-GVARS) 1))))) (LIST JMAX) (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1)))) (ALL-PAIRS-HELPER1 1 IMAX JMAX))) Looking at the conclusion we see need to prove that the [47mappend$+[0m term is equal to the [47mall-pairs-helper1[0m term. From our ACL2 experience with recursive functions like [47mall-pairs-helper1[0m we know this is an inductive proof. But no induction is suggested by [47m(all-pairs-helper1 1 imax jmax)[0m because the constant [47m1[0m is in a controller position. We need to generalize the [47m1[0m by replacing it with [47mi0[0m, a general initial value of [47mi[0m. Note that we replace the [47m1[0m in two places, namely, the first [47m1[0m in [47m(loop$-as (list (from-to-by 1 imax 1)))[0m, and the [47m1[0m in [47m(all-pairs-helper1 1 imax jmax)[0m. Those two [47m1[0ms are the concrete initial values of two [47mi[0m counters on opposite sides of the equality. There are three other occurrences of the number [47m1[0m in the conjecture. The first one is the initial value of the variable [47mj[0m, the second is the step size for counting up from [47mj[0m to [47mjmax[0m, and the third one is the step size for counting up from [47mi[0m to [47mimax[0m. We do not change those three occurrences of [47mi[0m. We submit the proposed generalization as [47mlemma1[0m. The conclusion of [47mlemma1[0m is exactly the equality conclusion above except for the replacement of those two [47m1[0ms by the new variable [47mi0[0m. The hypothesis of [47mlemma1[0m requires all the variables to be naturals. But the proof attempt fails! The checkpoint is shown below. (defthm lemma1 (implies (and (natp imax) (natp jmax) (natp i0)) (equal (append$+ (lambda$ (loop$-gvars loop$-ivars) (collect$+ (lambda$ (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (car loop$-ivars))) (list (car loop$-ivars)) (loop$-as (list (from-to-by 1 (car loop$-gvars) 1))))) (list jmax) (loop$-as (list (from-to-by i0 imax 1)))) (all-pairs-helper1 i0 imax jmax)))) *** Key checkpoint under a top-level induction: *** Subgoal *1/6'' (IMPLIES (AND (<= I0 IMAX) (EQUAL (APPEND$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (CONS (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) (LIST (CAR LOOP$-IVARS)) (LOOP$-AS (LIST (FROM-TO-BY 1 (CAR LOOP$-GVARS) 1))))) (LIST JMAX) (LOOP$-AS (LIST (FROM-TO-BY (+ 1 I0) IMAX 1)))) (ALL-PAIRS-HELPER1 (+ 1 I0) IMAX JMAX)) (INTEGERP IMAX) (<= 0 IMAX) (INTEGERP JMAX) (<= 0 JMAX) (INTEGERP I0) (<= 0 I0)) (EQUAL (APPEND (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (CONS (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) (LIST I0) (LOOP$-AS (LIST (FROM-TO-BY 1 JMAX 1)))) (ALL-PAIRS-HELPER1 (+ 1 I0) IMAX JMAX)) (APPEND (ALL-PAIRS-HELPER2 I0 1 JMAX) (ALL-PAIRS-HELPER1 (+ 1 I0) IMAX JMAX)))) Notice that we're trying to prove something of the form (EQUAL (APPEND a1 b1) (APPEND a2 b2)) where [47mb1[0m and [47mb2[0m are identical. So we will prove [47m(EQUAL a1 a2)[0m. But again, this is inductive. The [47m(from-to-by 1 jmax 1)[0m and the [47m(all-pairs-helper2 i0 1 jmax)[0m are both counting up from [47m1[0m as the initial value of [47mj[0m. We need to generalize those [47m1[0ms to [47mj0[0m. So we submit the following as [47mlemma2[0m. And it succeeds! (defthm lemma2 (implies (and (natp imax) (natp jmax) (natp i0) (natp j0)) (equal (collect$+ (lambda$ (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (car loop$-ivars))) (list i0) (loop$-as (list (from-to-by j0 jmax 1)))) (all-pairs-helper2 i0 j0 jmax)))) So now we return to [47mlemma1[0m, whose checkpoint suggested [47mlemma2[0m. But it fails again, this time with a different checkpoint (defthm lemma1 (implies (and (natp imax) (natp jmax) (natp i0)) (equal (append$+ (lambda$ (loop$-gvars loop$-ivars) (collect$+ (lambda$ (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (car loop$-ivars))) (list (car loop$-ivars)) (loop$-as (list (from-to-by 1 (car loop$-gvars) 1))))) (list jmax) (loop$-as (list (from-to-by i0 imax 1)))) (all-pairs-helper1 i0 imax jmax)))) *** Key checkpoint at the top level: *** [1]Goal (APPLY$-WARRANT-COLLECT$+) Note that this checkpoint comes from a forcing round (the clue is the ``[47m[1][0m prefix to the [47mGoal[0m), which means the proof succeeded except for some hypotheses that were forced so that certain lemmas could fire and now have to be proved. But the hypothesis above is the warrant for [47mcollect$+[0m. We need the warrant for [47mcollect$+[0m because that function is being applied with [47mapply$[0m every time [47mappend$+[0m iterates. This is easy to fix. We just add the warrant as a hypothesis to [47mlemma1[0m. (defthm lemma1 (IMPLIES (AND (warrant collect$+) (natp imax) (natp jmax) (natp i0)) (equal (append$+ (lambda$ (loop$-gvars loop$-ivars) (collect$+ (lambda$ (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (car loop$-ivars))) (list (car loop$-ivars)) (loop$-as (list (from-to-by 1 (car loop$-gvars) 1))))) (list jmax) (loop$-as (list (from-to-by i0 imax 1)))) (all-pairs-helper1 i0 imax jmax)))) This proof succeeds. So now we return to [47mmain[0m. By the way, because we expect the theorem to be proved by applying [47mlemma1[0m, we provide the hint that tells the prover not to even try induction. This just reduces the output if the proof fails. Unfortunately this attempt fails, but with two easy-to-fix checkpoints. (defthm main (implies (and (natp imax) (natp jmax)) (equal (all-pairs-loop$ imax jmax) (all-pairs imax jmax))) :hints (("Goal" :do-not-induct t))) *** Key checkpoints at the top level: *** [1]Subgoal 2 (APPLY$-WARRANT-MAKE-PAIR) [1]Subgoal 1 (APPLY$-WARRANT-COLLECT$+) Note that the checkpoints are forcing round subgoals showing that we need two warrants. So we add both warrants to [47mmain[0m's hypotheses. And we're done. (defthm main (implies (and (warrant collect$+ make-pair) (natp imax) (natp jmax)) (equal (all-pairs-loop$ imax jmax) (all-pairs imax jmax))) :hints (("Goal" :do-not-induct t))) Note: The [47m:do-not-induct[0m hint could be deleted because the theorem is proved without appealing to induction anyway. You might wonder why we need the warrant on [47mmake-pairs[0m. It never arose in any checkpoint except in the very last failed proof. The first time we tried to prove [47mmain[0m we failed, and got this checkpoint. Goal'' (IMPLIES (AND (INTEGERP IMAX) (<= 0 IMAX) (INTEGERP JMAX) (<= 0 JMAX)) (EQUAL (APPEND$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (CONS (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) (LIST (CAR LOOP$-IVARS)) (LOOP$-AS (LIST (FROM-TO-BY 1 (CAR LOOP$-GVARS) 1))))) (LIST JMAX) (LOOP$-AS (LIST (FROM-TO-BY 1 IMAX 1)))) (ALL-PAIRS-HELPER1 1 IMAX JMAX))) The innermost [47mlambda$[0m is the body of the innermost [47mloop$[0m statement, [47m(loop$ for j from 1 to jmax collect (make-pair i j))[0m, except it has been simplified by the expansion of [47m(make-pair i j)[0m to [47m(cons i j)[0m. That expansion of [47mmake-pair[0m inside a [47mlambda$[0m required the warrant for [47mmake-pair[0m and that was forced to produce the [47mcons[0m. Had that first proof attempt at [47mmain[0m succeeded except for that forced subgoal, a forcing round would have brought to our attention the need for the warrant on [47mmake-pair[0m. But that proof attempt failed because the prover could not do a suitable induction to prove [47mGoal''[0m. Indeed, that is what led us to [47mlemma1[0m. But forced subgoals are not reported if the proof fails for other reasons. So we were left unaware that we were depending on the warrant for [47mmake-pair[0m. In the penultimate failed proof [47mmain[0m just above, the same forced expansion of [47mmake-pair[0m occurred and this time the proof succeeded except for the forced subgoals requiring warrants for [47mmake-pair[0m and [47mcollect$+[0m. That finally brought the [47mmake-pair[0m expansion to our attention. The more experienced ACL2 user would have noticed (indeed, did notice!) the expansion of [47mmake-pair[0m in [47mGoal''[0m above and understood the warrant for [47mmake-pair[0m was needed but wanted to see what would happen if that fact was overlooked. The final series of events to solve this problem is shown below. ; Include standard apply$ book. (include-book "projects/apply/top" :dir :system) ; Define and verify the guards of the recursive all-pairs. (defun make-pair (i j) (declare (xargs :guard t)) (cons i j)) (defun all-pairs-helper2 (i j jmax) (declare (xargs :measure (nfix (- (+ (nfix jmax) 1) (nfix j))) :guard (and (natp i) (natp j) (natp jmax)))) (let ((j (nfix j)) (jmax (nfix jmax))) (cond ((> j jmax) nil) (t (cons (make-pair i j) (all-pairs-helper2 i (+ 1 j) jmax)))))) (defun all-pairs-helper1 (i imax jmax) (declare (xargs :measure (nfix (- (+ (nfix imax) 1) (nfix i))) :guard (and (natp i) (natp imax) (natp jmax)))) (let ((i (nfix i)) (imax (nfix imax))) (cond ((> i imax) nil) (t (append (all-pairs-helper2 i 1 jmax) (all-pairs-helper1 (+ 1 i) imax jmax)))))) (defun all-pairs (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (all-pairs-helper1 1 imax jmax)) ; Warrant make-pair so we can use it in a loop$. (defwarrant make-pair) ; Define and verify the guards of the loop$ version. (defun all-pairs-loop$ (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (loop$ for i from 1 to imax append :guard (natp jmax) (loop$ for j from 1 to jmax collect (make-pair i j)))) ; Prove that the generalized inner loop$ is all-pairs-helper2. (defthm lemma2 (implies (and (natp imax) (natp jmax) (natp i0) (natp j0)) (equal (collect$+ (lambda$ (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (car loop$-ivars))) (list i0) (loop$-as (list (from-to-by j0 jmax 1)))) (all-pairs-helper2 i0 j0 jmax)))) ; Prove that the generalized outer loop$ is all-pairs-helper1. (defthm lemma1 (implies (and (warrant collect$+) (natp imax) (natp jmax) (natp i0)) (equal (append$+ (lambda$ (loop$-gvars loop$-ivars) (collect$+ (lambda$ (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (car loop$-ivars))) (list (car loop$-ivars)) (loop$-as (list (from-to-by 1 (car loop$-gvars) 1))))) (list jmax) (loop$-as (list (from-to-by i0 imax 1)))) (all-pairs-helper1 i0 imax jmax)))) ; Main theorem (defthm main (implies (and (warrant collect$+ make-pair) (natp imax) (natp jmax)) (equal (all-pairs-loop$ imax jmax) (all-pairs imax jmax)))) Now go to [lp-section-12] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-12 (loop$-primer) "Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms LP12: Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms If you have not already, warm up by proving the correctness of your solutions to the problems in [lp-section-8]. Remember to operate in a session in which you have included the standard [47mloop$[0m book. (include-book "projects/apply/top" :dir :system) Our answers to the problems in [lp-section-8] are in [community-books] file [47mdemos/loop-primer/lp8.lisp[0m, and our answers to the problems below are in [community-books] file [47mdemos/loop-primer/lp12.lisp[0m. ------------------------------ [31;1mLP12-1[0m Define [47m(assoc-equal-loop$ x alist)[0m to be equal to [47m(assoc-equal x alist)[0m when [47m(alistp alist)[0m. Verify the guards of [47massoc-equal-loop$[0m and prove that your function satisfies the specification above. Is your function in fact unconditionally equal to [47massoc-equal[0m? If so, prove it; if not, show a counterexample. ------------------------------ [31;1mLP12-2[0m Under what conditions is the following a theorem? Fill in the blank and prove the theorem. (defthm LP12-2 (implies ... (equal (loop$ for x in keys as y in vals collect (cons x y)) (pairlis$ keys vals))) :rule-classes nil) ------------------------------ [31;1mLP12-3[0m Prove (defthm LP12-3 (equal (* 2 (len (loop$ for tl on lst append tl))) (* (len lst) (+ (len lst) 1)))) [3mHint:[0m By phrasing the challenge with the multiplication by 2 on the left-hand side, we produce a conjecture that can be proved (perhaps with a few lemmas) without the need for ``heavy duty'' arithmetic books. Had we divided by 2 on the right-hand side, we'd have brought division into the problem which we intentionally avoided. You will still need a lemma or two, discoverable by The Method. ------------------------------ [31;1mLP12-4[0m Define (defun nats (n) (cond ((zp n) (list 0)) (t (append (nats (- n 1)) (list n))))) and prove that the obvious [47mloop$[0m statement is equivalent to [47m(nats n)[0m when [47mn[0m is a natural. Make your [47mdefthm[0m have [47m:rule-classes nil[0m so as not to interfere with your work on the next problem. ------------------------------ [31;1mLP12-5[0m Define (defun nats-up (i n) (declare (xargs :measure (nfix (- (+ (nfix n) 1) (nfix i))))) (let ((i (nfix i)) (n (nfix n))) (cond ((> i n) nil) (t (cons i (nats-up (+ i 1) n)))))) Prove (defthm LP12-5 (implies (natp n) (equal (loop$ for i from 0 to n collect i) (nats-up 0 n))) :rule-classes nil) ------------------------------ [31;1mLP12-6[0m Fill in the blanks below and prove the theorem. You may need hints. If not, just delete the :hints setting. (defthm LP12-6 (implies (true-listp lst) (equal (loop$ ...) (strip-cars lst))) :hints ... :rule-classes nil) ------------------------------ [31;1mLP12-7[0m Prove the following, adding hints if necessary. Otherwise, just delete the [47m:hints[0m setting. (defthm LP12-7 (loop$ for pair in (loop$ for key in keys as val from 0 to (+ (len keys) -1) collect (cons key val)) always (integerp (cdr pair))) :hints ...) ------------------------------ [31;1mLP12-8[0m Fill in the blanks below and then prove the theorem. You may need hints. If not, just delete the [47m:hints[0m setting. (defthm LP12-8 (implies (natp n) (equal (loop$ ...) (nth n lst))) :hints ... :rule-classes nil) Now go to [lp-section-13] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-13 (loop$-primer) "Examples of [47mDO[0m [47mLoop$[0ms LP13: Examples of [47mDO[0m [47mLoop$[0ms Below is a log of an ACL2 session demonstrating the behavior of a few [47mDO[0m [47mloop$[0ms. As usual with [47mloop$[0ms, one should always work in a session in which the book shown below is included. The examples below do not illustrate guards or proofs about [47mDO[0m [47mloop$[0ms. We'll describe the syntax and semantics of [47mDO[0m [47mloop$[0ms later. But we expect you can intuit the syntax and semantics of these [47mloop$[0m statements from these examples. The following may help if you're unfamiliar with the following Common Lisp primitives. In ACL2, [31;1mThese primitives may only be used within [47mDO[0m[31;1m [47mloop$[0m[31;1ms![0m * [47m(RETURN [0m[3mexpr[0m[47m)[0m terminates the [47mloop$[0m and returns the value of [3mexpr[0m as the value. * [47m(SETQ [0m[3mvar expr[0m[47m)[0m evaluates [3mexpr[0m and assigns the value to the variable [3mvar[0m. Parallel assignment with [47mmv-setq[0m is also supported but not illustrated here. * [47m(PROGN [0m[3mstmt_1 ... stmt_n[0m[47m)[0m evaluates each [3mstmt_i[0m in turn and returns the value of the last one. * [47m(LOOP-FINISH)[0m terminates the iteration in the [47mloop$[0m and passes control to the [47mFINALLY[0m clause, if any. We start the session with the following commands, whose output we do not display here. Note that we use [47m[defstobj][0m to introduce a single-threaded object, [47mst[0m, with one field, [47mfld1[0m. We initialize [47m(fld1 st)[0m to 0. In addition, we warrant two of the functions introduced by the [47m[defstobj][0m. We warrant those functions because they are user-defined [47m:logic[0m mode functions that we'll use in a [47mDO[0m [47mloop$[0m. [47mDefstobj[0m does not automatically badge or warrant the functions it defines but they are warrantable. (include-book "projects/apply/top" :dir :system) (defstobj st fld1) (update-fld1 0 st) (defwarrant fld1) (defwarrant update-fld1) So having set up our session, we now experiment with [47mDO[0m [47mloop$[0ms. ; Reverse the elements of the initial value of temp. ACL2 !>(loop$ with temp = '(a b c) with ans = nil do (cond ((endp temp) (return ans)) (t (progn (setq ans (cons (car temp) ans)) (setq temp (cdr temp)))))) (C B A) ; Reverse the elements of lst down to the first xxx, or return ; not-found if there is no xxx in lst. ACL2 !>(defun reverse-to-xxx (lst) (loop$ with temp = lst with ans = nil do (cond ((endp temp) (return 'not-found)) (t (progn (cond ((eq (car temp) 'xxx) (loop-finish)) (t (setq ans (cons (car temp) ans)))) (setq temp (cdr temp))))) finally (return ans))) Since REVERSE-TO-XXX is non-recursive, its admission is trivial. We could deduce no constraints on the type of REVERSE-TO-XXX. Summary Form: ( DEFUN REVERSE-TO-XXX ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) REVERSE-TO-XXX ACL2 !>(reverse-to-xxx '(a b c xxx d e f)) (C B A) ACL2 !>(reverse-to-xxx '(a b c d e f)) NOT-FOUND ; In the next example we will reverse the elements of the initial value of ; temp, except for the xxx's which we just drop but count. We use (fld1 st) ; to store the accumulated count. This loop$ returns the reversed elements ; and the final value of st. But first we'll show that (fld1 st) is ; initially 0. ACL2 !>(fld1 st) 0 ACL2 !>(loop$ with temp = '(a b c xxx d e xxx f g) with ans = nil do :values (nil st) (cond ((endp temp) (return (mv ans st))) (t (progn (cond ((eq (car temp) 'xxx) (setq st (update-fld1 (+ 1 (fld1 st)) st))) (t (setq ans (cons (car temp) ans)))) (setq temp (cdr temp)))))) ((G F E D C B A) <st>) ACL2 !>(fld1 st) 2 We included the last example showing that stobjs can be used inside of [47mDO[0m [47mloop$[0ms just to alert you to that feature. However, in the rest of this primer we do not deal with stobjs in [47mloop$[0m because there is enough to cover without that! See the ACL2 documentation topic [DO-loop$] for a more thorough discussion of [47mDO[0m [47mloop$[0ms. Now go to [lp-section-14] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-14 (loop$-primer) "Challenge Problems about [47mDO[0m [47mLoop$[0ms LP14: Challenge Problems about [47mDO[0m [47mLoop$[0ms In this section you'll be asked to write and evaluate some [47mDO[0m [47mloop$[0ms based entirely on the examples given in the previous section. We'll deal with termination, guards, proofs, etc., later. We want all iteration in your answers to be done with [47mDO[0m [47mloop$[0ms even if the problem could be solved with a [47mFOR[0m [47mloop$[0m. Our answers to the problems in this section are in [community-books] file [47mdemos/loop-primer/lp14.lisp[0m. ------------------------------ [31;1mLP14-1:[0m Make a list of the integers from 10 down to 0. [31;1mExpected Value:[0m[47m(10 9 8 7 6 5 4 3 2 1 0)[0m Ok, we know this is a silly question if taken literally! Why use iteration at all if the answer is a constant? If you want to cheat, just enter (loop$ with ans = '(10 9 8 7 6 5 4 3 2 1 0) do (return ans)) But the spirit of these questions is to use iteration and, if it helps, imagine we'd asked you to write a [47mloop$[0m that returns the list of integers from 1000000 down to 0! ------------------------------ [31;1mLP14-2:[0m Sum the naturals less than or equal to 100. [31;1mExpected Value:[0m [47m5050[0m Hint: Write the [47mloop$[0m so that it counts down! If you count up you'll have to provide a measure term, which can be done by including [47m:measure[0m [3mmeasure-term[0m immediately after the [47mDO[0m operand and before the body. ------------------------------ [31;1mLP14-3:[0m Sum the squares of the naturals less than or equal to 100, using the following function to square. (defun sq (x) (* x x)) [31;1mExpected Value:[0m [47m338350[0m ------------------------------ [31;1mLP14-4:[0m Write a [47mDO[0m that finds the first occurrence of the symbol [47mXXX[0m in the list [47m'(A B C XXX D E F)[0m and returns the tail of the list starting with that occurrence. [31;1mExpected Value:[0m [47m(XXX D E F)[0m ------------------------------ [31;1mLP14-5:[0m Fill in the blank below so that the next form is a theorem. You do not have to prove the theorem (but it shouldn't be hard). (defun do-loop$-member (e lst) (loop$ ...)) (defthm lp14-5 (equal (do-loop$-member e lst) (member e lst)) :rule-classes nil) ------------------------------ [31;1mLP14-6:[0m Given the following (defun steps-for-member (e lst steps) (cond ((endp lst) (list steps nil)) ((equal (car lst) e) (list steps lst)) (t (steps-for-member e (cdr lst) (+ 1 steps))))) fill in the blank so that this is a theorem. (defthm lp14-6 (equal (loop$ ...) (steps-for-member e lst steps)) :rule-classes nil) ------------------------------ [31;1mLP14-7:[0mWrite a [47mDO[0m to compute the list of all pairs [47m(i . j)[0m such that 1 <= [47mi[0m <= 3 and 1 <= [47mj[0m <= 4. [31;1mExpected Value:[0m ((1 . 1) (1 . 2) (1 . 3) (1 . 4) (2 . 1) (2 . 2) (2 . 3) (2 . 4) (3 . 1) (3 . 2) (3 . 3) (3 . 4)) ------------------------------ Now go to [lp-section-15] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-15 (loop$-primer) "Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms LP15: Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms The ``most elaborate'' [47mDO[0m [47mloop$[0m looks like this. (LOOP$ WITH var1 OF-TYPE spec1 = init1 ; a WITH declaration WITH var2 OF-TYPE spec2 = init2 ... DO :measure m :guard do-guard :values v do-body FINALLY :guard fin-guard fin-body) where much of that is optional: ``[47mOF-TYPE speci[0m'', ``[47m= initi[0m'' (when ``[47mOF-TYPE speci[0m'' is present), ``[47m:MEASURE m[0m'', the two ``[47m:GUARD[0m ...'' clauses, ``[47m:VALUES v[0m'', and ``[47mFINALLY fin-body[0m''. If the [47m:MEASURE[0m is omitted, ACL2 tries to guess a likely measure using the same heuristic it does with recursive [47m[defun][0ms. If [47m:VALUES[0m is omitted then [47mv[0m defaults to [47m(nil)[0m. All ACL2 function symbols in [47mm[0m, [47mdo-body[0m, and [47mfin-body[0m must be [badge]d so [47m[apply$][0m can handle them. Furthermore, they must be [warrant]ed if proofs are to be done about them or if they are in [logic] mode and are called during evaluation. As you've already inferred from our examples, [47mdo-body[0m and [47mfin-body[0m are not normal ACL2 terms! They allow restricted uses of [47mRETURN[0m, [47mPROGN[0m, [47mSETQ[0m, [47mMV-SETQ[0m, and [47mLOOP-FINISH[0m. As for semantics, every legal [47mDO[0m [47mloop$[0m translates into a term of the form (DO$ m-lambda alist do-body-lambda fin-body-lambda a5 a6) where [47mm-lambda[0m, [47mdo-body-lambda[0m, and [47mfin-body-lambda[0m are quoted [47mLAMBDA[0m objects derived from the respective terms in the [47mloop$[0m statement. [47mAlist[0m is an association list that maps the variables of those terms to their initial values. We discuss the other three arguments later. All three of these [47mLAMBDA[0m objects operate on [47malist[0m. The [47mm-lambda[0m may return a natural, and otherwise must return a list of naturals which is treated as a lexicographic tuple whose first component is the most significant. The other two [47mLAMBDA[0m objects return a triple of the form [47m(exit-token value new-alist)[0m. The [47mexit-token[0m is [47m:RETURN[0m, [47m:LOOP-FINISH[0m, or [47mNIL[0m, and indicates what happens next: the [47mvalue[0m is to be returned as the value of the [47mloop$[0m, the [47mfin-body-lambda[0m is to be applied to the [47mnew-alist[0m, or the [47mloop$[0m is to iterate again on [47mnew-alist[0m. But before the iteration, the [47mm-lambda[0m is applied to the [47mnew-alist[0m and must be of smaller measure according to [47m[l<][0m for iteration to continue. If the given measure fails to decrease, then, logically speaking, [47ma5[0m is used to compute a default answer. (That argument is actually the output signature of the [47mloop$[0m specifying how many values are to be returned and whether each value is an ordinary object, a double-float, or a [stobj].) However, in execution, an error is signaled if the measure fails to decrease. Such runtime errors (including [47mOF-TYPE[0m and guard violations if guards are being checked) are reported using [47ma6[0m which is just a quoted constant about the original [47mloop$[0m statement. (In fact, [47ma6[0m is logically irrelevant and the theorem prover replaces quoted non-[47mnil[0m final argument to [47mdo$[0m by [47mnil[0m in proofs as part of the cleaning-up process.) Consider this simple [47mDO[0m [47mloop$[0m and its cleaned-up semantics as shown by the [47m:[0m[47m[tcp][0m command. (We have re-pretty-printed it to add comments and highlight some symmetries.) ACL2 !>:tcp (loop$ with i = n with ans = 0 do (if (zp i) (return ans) (progn (setq ans (+ 1 ans)) (setq i (- i 1))))) (DO$ ; measure lambda: (LAMBDA$ (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'I ALIST)))) ; initial alist: (LIST (CONS 'I N) (CONS 'ANS 0)) ; do-body lambda: (LAMBDA$ (ALIST) (IF (ZP (CDR (ASSOC-EQ-SAFE 'I ALIST))) (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))) (LIST NIL NIL (LIST (CONS 'I (+ -1 (CDR (ASSOC-EQ-SAFE 'I ALIST)))) (CONS 'ANS (+ 1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))))) ; fin-body lambda (irrelevant here) (LAMBDA$ (ALIST) (LIST NIL NIL (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) ; irrelevant args a5 and a6 '(NIL) NIL) [47mASSOC-EQ-SAFE[0m is just [47mASSOC-EQ[0m with a slightly weaker guard. Think of [47m(CDR (ASSOC-EQ-SAFE 'var ALIST))[0m as the current value of the local variable [47mvar[0m. The measure is that the [47mACL2-COUNT[0m of the current value of [47mI[0m decreases. The output of the [47mdo-body[0m [47mlambda[0m is a triple. The true branch of the [47mIF[0m indicate iteration is to stop and return the current value of [47mANS[0m. The false branch indicates iteration is to continue with the new alist given as the third element of the triple. The [47mfin-body[0m [47mlambda[0m is irrelevant because there is no [47m:LOOP-FINISH[0m exit in the do-body. Of course, the semantics of [47mdo$[0m is explicit in its definition. So you might want to execute [47m:pe do$[0m in your ACL2 session and just read how [47mdo$[0m operates. We realize the above descriptions are pretty sketchy. But in the coming discussions and proof problems we'll limit ourselves to [47mDO[0m [47mloop$[0ms without [47mof-type[0ms or [47mguards[0m, they'll all return single non-[47m[stobj][0m values so the [47m:values[0m option won't be needed, and you won't really need to use the [47mfinally[0m clause or any fancier bodies than we show in our examples. For more details about both the syntax and semantics of [47mDO[0m [47mloop$[0ms see [do-loop$]. [31;1mBut beware! That link takes you out of the [47mloop$[0m[31;1m primer![0m To get back here either use your browser's ``back'' button or remember to return to [47mlp-section-15[0m! Now go to [lp-section-16] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-16 (loop$-primer) "Proving Theorems about [47mDO[0m [47mLoop$[0ms LP16: Proving Theorems about [47mDO[0m [47mLoop$[0ms Let's prove a theorem about a [47mDO[0m [47mloop$[0m. Specifically, let's prove (defthm main (implies (natp n) (equal (loop$ with i = n with ans = 0 do (if (zp i) (return ans) (progn (setq ans (+ 1 ans)) (setq i (- i 1))))) n))) A few words of warning are appropriate. * The Method (see [the-method]) is a good way to proceed: try to prove the theorem expecting it to fail and look at the checkpoints. * Unsurprisingly, the theorem above has to be [3mgeneralized[0m before it can be proved. But it can feel strange to generalize a [47mloop$[0m. * If we prove a lemma that rewrites a [47mloop$[0m expression we have to remember that before rewrite rules are applied the interior terms are rewritten. In particular, ACL2 can rewrite the bodies of the [47mlambda[0m objects. The most common changes are that non-recursive functions are generally expanded (depending on the theory in use) and [47mIF[0ms are normalized. That means we need to normalize the bodies of any [47mloop$[0m we use in a lemma if we expect that lemma to match a term being rewritten! This observation is relevant here because [47m[zp][0m is non-recursively defined and so will expand when the body of the [47mloop$[0m above is rewritten. * ACL2 does not display [47mdo$[0m terms as [47mDO[0m [47mloop$[0ms. So get used to reading [47mdo$[0m terms and thinking of [47mloop$[0m statements! (We may fix this someday but at the moment we find it advantageous to really see the terms the prover is dealing with!) [31;1mA Tedious Recipe for Proving Theorems about [47mDO[0m[31;1m [47mLoop$[0m[31;1ms[0m When you first start proving theorems about [47mDO[0m [47mloop$[0ms it might be helpful to follow the tedious recipe below. It will familiarize you with the semantics of [47mDO[0m [47mloop$[0ms and teach you certain techniques that are easy applications of lessons you've already internalized as an experienced ACL2 user, albeit one unfamiliar with [47mloop$[0m. But after a little experience you'll find it straightforward to skip some steps! * Use The Method to find the normal form of the [47mloop$[0m. * Define a recursive function that computes the value of the [47mloop$[0m using the same algorithm as the [47mloop$[0m. This function can serve two purposes. First, it can be an intermediate stop on the way to proving that the [47mloop$[0m satisfies your specification. We'll make this clear in the next point. Second, it can suggest an induction scheme that is probably useful. We'll return to this point at the end of our recipe for proving things about [47mDO[0m [47mloop$[0ms. * Prove that the [47mloop$[0m computes the same value as the function. We frequently refer to this as ``lemma 1'' in the recipe. Generally you will have to generalize the [47mloop$[0m to prove it by the induction suggested by the function. And you will have to write the normal form of the [47mloop$[0m body instead of the ``pretty'' form used in the main theorem so this lemma can be used to hit the rewritten [47mloop$[0m in the proof of the main theorem later. * Prove that the function satisfies the specification. We frequently refer to this as ``lemma 2''. * Prove that the [47mloop$[0m satisfies the specification by chaining together the two lemmas. Of course, as with all ``recipes'', sometimes you have to adjust depending on the ingredients at hand. Sometimes you can just write the body of the [47mloop$[0m in normal form to begin with. Sometimes you do not have to define a special function because the [47mloop$[0m itself or a function already in the conjecture suggests an appropriate induction. Sometimes you may find it easier to copy the [47mdo$[0m form revealed by The Method into your statement of lemma 1 and generalize that form, rather than try to express lemma 1 as a [47mloop$[0m. You may also be content to skip the ``intermediate stop'' of lemma 1 altogether and prove that the [47mloop$[0m satisfies a generalized specification, sometimes providing an [47m:induct[0m hint instead of inserting the special function into the lemma. Sometimes you do not have to generalize. Sometimes instead of proving lemma 1 and lemma 2 you can just prove the main goal directly. As an experienced ACL2 user you will recognize when you can skip steps in this recipe. We spell the recipe out rigidly here just to give you one promising way to proceed. We're going to prove the theorem (defthm main (implies (natp n) (equal (loop$ with i = n with ans = 0 do (if (zp i) (return ans) (progn (setq ans (+ 1 ans)) (setq i (- i 1))))) n))) both ways, first by following the tedious recipe, and then the way a user familiar with [47mDO[0m [47mloop$[0m proofs might do it. So here goes! Following the recipe to prove [47mmain[0m above, we first try The Method. The prover tries an induction suggested by the [47mDO[0m [47mloop$[0m, namely induction on [47mN[0m by [47m-1[0m, but without instantiating [47mANS[0m because the initial value of [47mANS[0m is the constant [47m0[0m. We know this proof will fail and it does. The pre-induction checkpoint is shown below. *** Key checkpoint at the top level: *** Goal'' (IMPLIES (AND (INTEGERP N) (<= 0 N)) (EQUAL (DO$ (LAMBDA$ (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'I ALIST)))) (CONS (CONS 'I N) '((ANS . 0))) (LAMBDA$ (ALIST) (IF (INTEGERP (CDR (ASSOC-EQ-SAFE 'I ALIST))) (IF (< 0 (CDR (ASSOC-EQ-SAFE 'I ALIST))) (LIST NIL NIL (LIST (CONS 'I (+ -1 (CDR (ASSOC-EQ-SAFE 'I ALIST)))) (CONS 'ANS (+ 1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))) (LAMBDA$ (ALIST) (LIST NIL NIL (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) '(NIL) NIL) N)) Look carefully at the [47mdo-body[0m [47mlambda[0m, the second [47mlambda[0m object in the [47mdo$[0m. The [47m(ZP I)[0m in our original [47mDO[0m [47mloop$[0m has opened up, introducing [47m(INTEGERP i)[0m and [47m(< 0 i)[0m and [47mIF[0m normalization -- except instead of seeing the simple variable [47mI[0m we see its current value in the [47mALIST[0m being computed on each iteration. [31;1mThis is valuable information! It tells us what the rewritten body of the [47mloop$[0m[31;1m looks like in the theory in which our proof is being conducted. If we prove a [47m:rewrite[0m[31;1m rule expecting it to fire during the proof of our [47mmain[0m[31;1m theorem, its body must match that shown above![0m Now we define the recursive function that is supposed to be operationally equivalent to the [47mloop$[0m. This will suggest the induction. (defun copy-nat-ac (i ans) (if (zp i) ans (copy-nat-ac (- i 1) (+ 1 ans)))) Next comes the hard part. We state the lemma that equates the [47mloop$[0m to the function, but we have to generalize it so it can be proved by induction and we have to use the normal form of the body. We could state the lemma in terms of [47mDO$[0m of course, but with a little practice you can usually ``reverse engineer'' the desired lemma into a [47mloop$[0m. So here is the so-called ``lemma 1''. (defthm lemma1 (implies (and (natp n) (natp ans0)) (equal (loop$ with i = n with ans = ans0 do (if (integerp i) (if (< 0 i) (progn (setq ans (+ 1 ans)) (setq i (- i 1))) (return ans)) (return ans))) (copy-nat-ac n ans0)))) Note that we generalized the initial value of [47mans[0m in the [47mloop$[0m from [47m0[0m to [47mans0[0m and used [47mans0[0m as the accumulator in [47m(copy-nat-ac n ans0)[0m. By the way, we could have written [47mlemma1[0m in terms of the [47mDO$[0m term shown in the checkpoint, rather than as a [47mloop$[0m. But we have to generalize that [47m0[0m whether we use a [47mloop$[0m or the [47mDO$[0m term. The generalized [47mDO$[0m form of [47mlemma1[0m is (defthm lemma1 (implies (and (natp n) (natp ans0)) (equal (DO$ (LAMBDA$ (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'I ALIST)))) (CONS (CONS 'I N) (cons (cons 'ans ans0) nil)) ; note generalization of 0! (LAMBDA$ (ALIST) (IF (INTEGERP (CDR (ASSOC-EQ-SAFE 'I ALIST))) (IF (< 0 (CDR (ASSOC-EQ-SAFE 'I ALIST))) (LIST NIL NIL (LIST (CONS 'I (+ -1 (CDR (ASSOC-EQ-SAFE 'I ALIST)))) (CONS 'ANS (+ 1 (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) (LIST :RETURN (CDR (ASSOC-EQ-SAFE 'ANS ALIST)) (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST))))))) (LAMBDA$ (ALIST) (LIST NIL NIL (LIST (CONS 'I (CDR (ASSOC-EQ-SAFE 'I ALIST))) (CONS 'ANS (CDR (ASSOC-EQ-SAFE 'ANS ALIST)))))) '(NIL) NIL) (copy-nat-ac n ans0)))). The UPPERCASE part above was just copied from the checkpoint and then the pair in the initial alist binding [47mANS[0m, which was [47m'(ANS . 0)[0m, was replaced by [47m(cons (cons 'ans ans0) nil)[0m. So while it looks messy, it's not hard to enter. Furthermore, it saves us from having to figure out the normal form --- it's already in the checkpoint. The [47mDO$[0m term in this version of [47mlemma1[0m is just the formal translation of the generalized [47mDO[0m [47mloop$[0m we wrote in the earlier version of [47mlemma1[0m. Next we prove ``lemma 2'' equating the recursive function with the (generalized) specification. This theorem does not involve [47mloop$[0m and its proof should be utterly familiar to you. (defthm lemma2 (implies (and (natp n) (natp ans0)) (equal (copy-nat-ac n ans0) (+ n ans0)))) Finally, we prove our main theorem. (defthm main (implies (natp n) (equal (loop$ with i = n with ans = 0 do (if (zp i) (return ans) (progn (setq ans (+ 1 ans)) (setq i (- i 1))))) n))) The proof rewrites the ``pretty'' [47mdo-body[0m [47mlambda[0m into the normal form, [47mlemma1[0m rewrites the new form of the [47mloop$[0m after instantiating [47mans0[0m to [47m0[0m, to [47m(copy-nat-ac n 0)[0m, then [47mlemma2[0m hits that to [47m(+ n 0)[0m, and arithmetic does the rest. As we noted, our recipe is overly rigid. Here is another sequence of events that proves [47mmain[0m. The experienced user realizes that the generalized [47mDO[0m [47mloop$[0m will in fact suggest the appropriate induction to ACL2. So no special function is introduced. Furthermore, the user --- who has proved several theorems about [47mloop$[0ms involving [47mIF[0m and [47mZP[0m will know how to write the normal form. That user would just do this. (defthm lemma (implies (and (natp n) (natp ans0)) (equal (loop$ with i = n with ans = ans0 do (if (integerp i) (if (< 0 i) (progn (setq ans (+ 1 ans)) (setq i (- i 1))) (return ans)) (return ans))) (+ n ans0)))) (defthm main (implies (natp n) (equal (loop$ with i = n with ans = 0 do (if (zp i) (return ans) (progn (setq ans (+ 1 ans)) (setq i (- i 1))))) n))) For more details about rewriting [47mlambda[0m objects you can leave the [47mloop$[0m primer and read [rewrite-lambda-object] and [rewriting-versus-cleaning-up-lambda-objects]. But remember to come [31;1mback[0m here to [47mlp-section-16[0m! Now go to [lp-section-17] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-17 (loop$-primer) "Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms LP17: Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms In the following problems please write [47mDO[0m [47mloop$[0ms even though some of the problems can be solved with [47mFOR[0m [47mloop$[0ms. Our answers to the problems in this section are in [community-books] file [47mdemos/loop-primer/lp17.lisp[0m. ------------------------------ [31;1mLP17-1:[0m Write a [47mDO[0m [47mloop$[0m that reverses the list [47mlst[0m. For example, if [47mlst[0m is [47m(A B C)[0m the result should be [47m(C B A)[0m. Prove that your [47mDO[0m [47mloop$[0m is equal to [47m(rev lst)[0m, where (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) ------------------------------ [31;1mLP17-2:[0m Write a [47mDO[0m [47mloop$[0m that computes [47m(member e lst)[0m and prove it correct. [31;1mHint:[0m Sometimes the main theorem suggests the right induction on its own. ------------------------------ [31;1mLP17-3:[0m Prove the following: (defthm lp17-3-main (equal (loop$ with x = lst with ans = 0 do (cond ((endp x) (return ans)) (t (progn (setq ans (+ 1 ans)) (setq x (cdr x)))))) (len lst))) ------------------------------ [31;1mLP17-4:[0m Write a [47mDO[0m [47mloop$[0m that computes [47m(nth n lst)[0m, when [47mn[0m is a natural number. Prove it correct. ------------------------------ [31;1mLP17-5:[0m Prove the following. (defthm lp17-5-main (implies (true-listp lst) (equal (loop$ with x = lst with ans = nil do (cond ((endp x) (return ans)) (t (progn (setq ans (append ans (list (car x)))) (setq x (cdr x)))))) lst))) ------------------------------ [31;1mLP17-6:[0m Prove the following. (defthm lp17-6-main (implies (and (natp m) (natp n)) (equal (loop$ with i = m with j = n do (if (zp i) (return j) (progn (setq i (- i 1)) (setq j (+ j 1))))) (+ m n)))) ------------------------------ [31;1mLP17-7:[0m Write a [47mDO[0m [47mloop$[0m that computes [47m(fact n)[0m, for natural number [47mn[0m, where (defun fact (n) (if (zp n) 1 (* n (fact (- n 1))))) ------------------------------ [31;1mLP17-8:[0m Write a [47mDO[0m [47mloop$[0m that scans a list of numbers, [47mlst[0m, once and returns the sum of the elements and the sum of the squares (with [47msq[0m as defined below) of the elements of [47mlst[0m as a cons pair. E.g., given [47m(1 2 3 4 5)[0m return [47m(cons (+ 1 2 3 4 5) (+ (sq 1) (sq 2) (sq 3) (sq 4) (sq 5)))[0m = [47m(15 . 55)[0m. Prove that your do loop$ is equal to (cons (loop$ for e in lst sum e) (loop$ for e in lst sum (sq e))) Use the following definition of [47msq[0m. (defun sq (x) (* x x)) ------------------------------ [31;1mLP17-9:[0m Define [47m(partition-symbols lst)[0m with a [47mDO[0m [47mloop$[0m that partitions [47mlst[0m into two lists, one containing all the symbols in [47mlst[0m and the other containing all the non-symbols. Return the cons of the two partitions and prove [47mpartition-symbols[0m correct. Hint: Since you are likely to collect the elements in reverse order, a suitable specification for these purposes is that [47mpartition-symbols[0m is equal to (cons (rev (loop$ for e in lst when (symbolp e) collect e)) (rev (loop$ for e in lst when (not (symbolp e)) collect e))) ------------------------------ [31;1mLP17-10:[0m Write a [47mDO[0m [47mloop$[0m that returns the list of naturals from [47mn[0m down to [47m0[0m, where [47mn[0m is a natural. For example, if [47mn[0m is [47m10[0m the answer is [47m(10 9 8 7 6 5 4 3 2 1 0)[0m. Prove that when [47mn[0m is a natural, your [47mDO[0m [47mloop$[0m returns the same thing as [47m(loop$ for i from 0 to n collect (- n i))[0m. Hints: Remember that in order for your ``lemma1'' to be applied in the proof of your main theorem it must match the rewritten lambda objects of the main theorem. We've focused on matching the [47mdo-body[0m [47mlambda[0m. But it must also match the measure [47mlambda[0m. So when you formulate your ``lemma1'', pay attention to how your measure term normalizes under rewrite. And by the way, if you use non-recursive functions in a term and you don't want them opened up when the lambda objects are rewritten in the main theorem, try disabling them. (Some non-recursive functions cannot be disabled. But another workaround is to define the whole measure as a function and disable it when appropriate.) ------------------------------ [31;1mLP17-11:[0m Define [47m(all-pairs-do-loop$ imax jmax)[0m to compute the same [47m(all-pairs imax jmax)[0m as was defined in section 11 (and below). But use [47mDO[0m [47mloop$s[0m instead of [47mFOR[0m [47mloop$[0ms in your definition of [47mall-pairs-do-loop$[0m. Below we comment on what you should prove. The definition of [47mall-pairs[0m was as follows. (defun make-pair (i j) (declare (xargs :guard t)) (cons i j)) (defwarrant make-pair) (defun all-pairs-helper2 (i j jmax) (declare (xargs :measure (nfix (- (+ (nfix jmax) 1) (nfix j))) :guard (and (natp i) (natp j) (natp jmax)))) (let ((j (nfix j)) (jmax (nfix jmax))) (cond ((> j jmax) nil) (t (cons (make-pair i j) (all-pairs-helper2 i (+ 1 j) jmax)))))) (defun all-pairs-helper1 (i imax jmax) (declare (xargs :measure (nfix (- (+ (nfix imax) 1) (nfix i))) :guard (and (natp i) (natp imax) (natp jmax)))) (let ((i (nfix i)) (imax (nfix imax))) (cond ((> i imax) nil) (t (append (all-pairs-helper2 i 1 jmax) (all-pairs-helper1 (+ 1 i) imax jmax)))))) (defun all-pairs (imax jmax) (declare (xargs :guard (and (natp imax) (natp jmax)))) (all-pairs-helper1 1 imax jmax)) Hints: In following our advice on proving do loop$s you will define functions that compute the same things as your [47mDO[0m [47mloop$[0ms. In our solution we called these two functions [47mapdh1[0m and [47mapdh2[0m, where ``[47mapdh[0m'' stands for @ldquo;[47mall-pairs-do-helper[0m''. You will prove two ``[47mlemma1[0m'' theorems, one for each [47mloop$[0m. The second of those theorems will establish allow you to prove that your [47mall-pairs-do-loop$[0m is [47mapdh1[0m. The next step in our recipe is to prove that the [47mapdh1[0m is [47mall-pairs[0m as above. This will not involve [47mloop$[0ms of any sort. It's just a normal proof about the relation between some recursively defined functions. But we found this step surprisingly challenging! Since that second step does not involve [47mloop$[0ms, you may consider your answer correct if you just prove the two ``[47mlemma1[0m'' theorems! But if you want a non-[47mloop$[0m challenge, finish the proof all the way to [47mall-pairs[0m. Now go to [lp-section-18] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-18 (loop$-primer) "Conclusion LP18: Conclusion Here are two pieces of advice. First, if you can think of a good name for the concept implemented by a [47mloop$[0m statement, use [47mdefun[0m to define that name. This is especially the case if you intend to reason about that [47mloop$[0m statement or to write more than one instance of it. For example, rather than write instances of (loop$ for a in x as b in y sum (* a b)) it is better to define [47m(dot-product x y)[0m with that [47mloop$[0m as its body and then write calls of [47mdot-product[0m. Basically, names are good as long as you can remember them. They give you a place to hang lemmas and the lemmas match without having to think about rewriting lambdas, local variables, etc. Not all [47mloop$[0ms compute concepts with obvious, memorable names, but just because you can write ``anonymous'' iterations doesn't mean you should! Second, remember when you create a lemma intended to rewrite a [47mloop$[0m statement you should normalize the body under your intended rewrite theory. As an experienced ACL2 user you would never write a lemma that tried to rewrite an [47mendp[0m or [47mnfix[0m or [47mzp[0m term. The lemma will never ``see'' such terms because the rewriter will have opened them up. You should apply that same kind of thinking when you write lemmas intended to rewrite [47mloop$[0ms. That's it. We can't think of anything else to say! We urge you to resort to the ACL2 user's manual for further information. Some relevant topics are * [47m[loop$][0m * [for-loop$] * [do-loop$] * [47m[lambda$][0m * [rewrite-lambda-object] * [stating-and-proving-lemmas-about-loop$s] The End of the [47mLoop$[0m Primer. (Return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-2 (loop$-primer) "[47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2 LP2: [47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2 The [47mloop[0m macro of Common Lisp was inspired by the ``iterative statements'' in Warren Teitelman's CLISP package of Interlisp (1974). But programming languages have had iterative statements since early in the development of compilers. The first release of a FORTRAN compiler (1957) supported what is probably the most well-known iterative construct, the ``DO loop.'' But CLISP added many additional features including simultaneous looping over multiple ranges, structured ways to filter the elements, structured exit control mechanisms, and multiple ways to accumulate the results. Common Lisp supports these and many other features. ACL2's [47mloop$[0m facility supports a tiny subset of Common Lisp's [47mloop[0m statements. It is hard to overstate how small the ACL2 subset is! For example, to manage iteration over a range of numbers, ACL2 provides [47mFROM[0m, [47mTO[0m, and [47mBY[0m, but Common Lisp additionally provides [47mDOWNFROM[0m,[47mUPFROM[0m,[47mDOWNTO[0m,[47mUPTO[0m,[47mBELOW[0m,and [47mABOVE[0m. For value accumulation, ACL2 supports [47mSUM[0m, [47mCOLLECT[0m, [47mAPPEND[0m, [47mALWAYS[0m, and [47mTHEREIS[0m, while Common Lisp also supports [47mNCONC[0m, [47mCOUNT[0m, [47mMAXIMIZE[0m, and [47mMINIMIZE[0m. Even within its restricted subset, ACL2 syntax is less flexible regarding the order of the various ``clauses'' and the presence of, say, multiple accumulators. The list of differences could go on and on because the Common Lisp facility is so elaborate. While many more Common Lisp [47mloop[0m features could be supported in ACL2, we believe it is best to test and refine the techniques reasoning about [47mloop$[0m before elaborating it further. Now go to [lp-section-3] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-3 (loop$-primer) "Examples of [47mFOR[0m [47mLoop$[0ms LP3: Examples of [47mFOR[0m [47mLoop$[0ms Below is the complete log of an ACL2 session demonstrating the behavior of [47mFOR[0m [47mloop$[0ms. ACL2 also supports [47mDO[0m [47mloop$[0ms but they are not illustrated here. Note that to use [47mloop$[0m one should always work in a session in which the book shown below is included. The examples below do not illustrate guards, the use of user defined functions in [47mloop$[0m expressions, or proofs about [47mloop$[0ms. We'll describe the syntax and semantics of [47mloop$[0m in the next two sections. But we expect you can intuit the syntax and semantics of [47mloop$[0m statements from these examples alone. Please try! ACL2 !>(include-book "projects/apply/top" :dir :system) Summary Form: ( INCLUDE-BOOK "projects/apply/top" ...) Rules: NIL Time: 1.00 seconds (prove: 0.00, print: 0.00, other: 1.00) "/Users/demo/books/projects/apply/top.lisp" ACL2 !>(loop$ for x in '(a b c) collect (cons 'hi x)) ((HI . A) (HI . B) (HI . C)) ACL2 !>(loop$ for x in '(a b c) when (not (eq x 'b)) collect (cons 'hi x)) ((HI . A) (HI . C)) ACL2 !>(loop$ for x in '(a b c d e f g) until (eq x 'd) collect x) (A B C) ACL2 !>(loop$ for x on '(a b c) collect x) ((A B C) (B C) (C)) ACL2 !>(loop$ for x on '(a b c) collect (cons (car x) (len x))) ((A . 3) (B . 2) (C . 1)) ACL2 !>(loop$ for i from 1 to 10 sum i) 55 ACL2 !>(loop$ for i from 1 to 12 by 3 collect (* i i)) (1 16 49 100) ACL2 !>(loop$ for x in '((a b c) (d e f) (g h i)) collect (cons 'hi x)) ((HI A B C) (HI D E F) (HI G H I)) ACL2 !>(loop$ for x in '((a b c) (d e f) (g h i)) append (cons 'hi x)) (HI A B C HI D E F HI G H I) ACL2 !>(loop$ for x in '(2 4 6) always (evenp x)) T ACL2 !>(loop$ for x in '(2 4 5 6) always (evenp x)) NIL ACL2 !>(loop$ for x in '(2 4 5 6) thereis (if (evenp x) nil x)) 5 ACL2 !>(let ((greeting 'hi)) (loop$ for x in '(a b c) collect (cons greeting x))) ((HI . A) (HI . B) (HI . C)) ACL2 !>(loop$ for x in '(a b c) as y in '(65 66 67 68) collect (cons x y)) ((A . 65) (B . 66) (C . 67)) ACL2 !>(loop$ for x in '(a b c d) as y in '(65 66 67) collect (cons x y)) ((A . 65) (B . 66) (C . 67)) ACL2 !>(loop$ for x in '((1 2 3) (4 5 6) (7 8 9)) collect (loop$ for i in x collect (* i i))) ((1 4 9) (16 25 36) (49 64 81)) Now go to [lp-section-4] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-4 (loop$-primer) "Syntax of [47mFOR[0m [47mLoop$[0ms LP4: Syntax of [47mFOR[0m [47mLoop$[0ms To describe the syntax of [47mFOR[0m [47mloop$[0ms we first describe the most elaborate [47mFOR[0m [47mloop$[0m. Then we note which elements can be omitted. The most elaborate [47mFOR[0m [47mloop$[0m is of the form [47m(LOOP$ FOR [0m[3mv1[0m[47m OF-TYPE [0m[3mspec1 target1[0m [47mAS [0m [3mv2[0m[47m OF-TYPE [0m[3mspec2 target2[0m ... [47mAS [0m [3mvn[0m[47m OF-TYPE [0m[3mspecn targetn[0m [47mUNTIL :GUARD [0m[3mguard1 until-expr[0m [47mWHEN [0m [47m:GUARD [0m[3mguard2 when-expr[0m [3mop[0m[47m :GUARD [0m[3mguard3 body-expr[0m[47m)[0m where * each [3mvi[0m is a legal variable symbol, they are all distinct, and are collectively called the [3miteration variables[0m, * each [3mspeci[0m is a [47m[type-spec][0m for the corresponding variable [3mvi[0m, * each [3mtargeti[0m is of one of the forms below and specifies the range of values to be taken by the corresponding variable [3mvi[0m. Abstractly you may think of the ``range'' here simply as a list of the values as described below, where [3mlist-expr[0m is a term (which is expected to evaluate to a true list), [3mlo-expr[0m and [3mhi-expr[0m are terms (which are expected to evaluate to integers), and [3mstep-expr[0m is a term (which is expected to evaluate to a positive integer). In the examples given below, let [47mrv[0m be the list reverse function, so [47m(rv '(a b c))[0m is [47m(C B A)[0m. * [47mIN[0m [3mlist-expr[0m --- range is the value of [3mlist-expr[0m. For example, the range of ``[47mIN[0m [47m(rv '(a b c))[0m'' is [47m(C B A)[0m. * [47mON[0m [3mlist-expr[0m --- range is the list of successive non-[47mnil[0m tails of the value of [3mlist-expr[0m. For example, the range of ``[47mON[0m [47m(rv '(a b c))[0m'' is [47m((C B A) (B A) (A))[0m. The range value is produced by [47m(TAILS [0m[3mlist-expr[0m[47m)[0m. * [47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m [47mBY[0m [3mstep-expr[0m --- If ``[47mBY[0m [3mstep-expr[0m'' is omitted, ``[47mBY 1[0m'' is used. The range contains all the integers from the value of [3mlo-expr[0m to the greatest integer less than or equal to the value of [3mhi-expr[0m such that each is separated from its higher neighbor by the value of [3mstep-expr[0m. For example, the range of ``[47mFROM[0m 1 [47mTO[0m 10 [47mBY[0m 2'' is [47m(1 3 5 7 9)[0m. The range value is produced by [47m(FROM-TO-BY [0m[3mlo-expr[0m [3mhi-expr[0m [3mstep-expr[0m[47m)[0m. * each [3mguardi[0m is a term, * each [3muntil-expr[0m, [3mwhen-expr[0m, and [3mbody-expr[0m is a [47m[tame][0m term, and * [3mop[0m is one of the [3moperators[0m [47mSUM[0m, [47mCOLLECT[0m, [47mAPPEND[0m, [47mALWAYS[0m, or [47mTHEREIS[0m. The symbols [47mFOR[0m, [47mIN[0m, [47mON[0m, [47mFROM[0m, [47mTO[0m, [47mBY[0m, [47mOF-TYPE[0m, [47mWHEN[0m, [47mUNTIL[0m, [47mSUM[0m, [47mCOLLECT[0m, [47mAPPEND[0m, [47mALWAYS[0m, and [47mTHEREIS[0m when used in [47mloop$[0m statements may be in any package. Common Lisp prohibits loops with both a [47mWHEN[0m clause and either an [47mALWAYS[0m or a [47mTHEREIS[0m operator. For example, if you are tempted to write ``[47mWHEN[0m [3mp[0m [47mALWAYS[0m [3mq[0m'' you can instead write ``[47mALWAYS[0m [47m(if [0m[3mp q[0m [47mt)[0m.'' The following elements may be omitted from the most elaborate form and still produce legal [47mloop$[0m statements: * any line beginning with [47mAS[0m, [47mUNTIL[0m or [47mWHEN[0m, * any [47mOF-TYPE[0m [3mspeci[0m, and * any [47m:GUARD[0m [3mguardi[0m. A [47mFOR[0m [47mloop$[0m expression with just one iteration variable and in which the iterative expressions mention no free variable other than the iteration variable is called a [3msimple [47mloop$[0m[3m[0m (or, sometimes, a [3msimple loop[0m). An example of a simple loop is (loop$ for x in lst when (evenp x) collect (+ 1 (sq x))). A [47mFOR[0m [47mloop$[0m expression is called a [3mfancy [47mloop$[0m[3m[0m if it is not simple. Both of the following [47mloop$[0ms are fancy. (loop$ for x in xlst as y on ylst collect (expr x y)) (loop$ for x in xlst collect (expr x z)) The first is fancy because it has two iteration variables, [47mx[0m and [47my[0m. The second is fancy because the body freely uses the variable [47mz[0m which is not the iteration variable. Now go to [lp-section-5] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-5 (loop$-primer) "Informal Semantics of [47mFOR[0m [47mLoop$[0ms LP5: Informal Semantics of [47mFOR[0m [47mLoop$[0ms The value returned by a [47mFOR[0m [47mloop$[0m can be specified as follows --- but we hasten to add that this is not how Common Lisp compilers implement [47mloop$[0m! We think this description is easier to understand. The first step in evaluating a [47mFOR[0m [47mloop$[0m is to determine the range of each iteration variable by evaluating the target expressions as previously described. Next, repeat the following steps until the process stops. (1) If any range is empty, stop. (2) Otherwise, assign each iteration variable the first value in its range and shorten the range by one, by removing that first element. (3) If the [3muntil-expr[0m evaluates to non-[47mnil[0m under the current values of the global and iteration variables, stop. Otherwise, if the [3mwhen-expr[0m evaluates to non-[47mnil[0m under the current values of the variables, then evaluate the [3mbody-expr[0m under the current values. Otherwise, do not evaluate the [3mbody-expr[0m. When the repetition stops, the [3mbody-expr[0m will have been evaluated [3mn[0m times, each time producing a value [3mvali[0m, 0 <= [3mi[0m < [3mn[0m, where the [3mvali[0m are listed in the order in which they were produced. The result returned by the [47mloop$[0m is determined by the operator, [3mop[0m, of the [47mloop$[0m as follows. * [47mSUM[0m --- return the sum of the [3mvali[0m * [47mCOLLECT[0m --- return [47m(LIST [0m[3mval1[0m ... [3mvaln[0m[47m)[0m * [47mAPPEND[0m --- return [47m(APPEND [0m[3mval1[0m ... [3mvaln[0m[47m)[0m * [47mALWAYS[0m --- return [47m(AND [0m[3mval1[0m ... [3mvaln[0m[47m T)[0m * [47mTHEREIS[0m --- return [47m(OR [0m[3mval1[0m ... [3mvaln[0m[47m)[0m Note that if [3mop[0m is [47mALWAYS[0m, iteration can stop the first time a [3mvali[0m is [47mnil[0m. Similarly, if [3mop[0m is [47mTHEREIS[0m, iteration can stop the first time a [3mvali[0m is non-[47mnil[0m. Note also that an [47mALWAYS[0m [47mloop$[0m returns [47mNIL[0m or [47mT[0m but a [47mTHEREIS[0m [47mloop$[0m returns [47mnil[0m or the first non-[47mnil[0m value produced by the evaluation of the body. Now go to [lp-section-6] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-6 (loop$-primer) "Challenge Problems about [47mFOR[0m [47mLoop$[0ms LP6: Challenge Problems about [47mFOR[0m [47mLoop$[0ms The questions below ask you to write and evaluate some [47mFOR[0m [47mloop$[0ms at the top-level of ACL2. Our answers to the problems in this section are in [community-books] file [47mdemos/loop-primer/lp6.lisp[0m. Feel free to look at our answers after you have worked on a problem. But remember: reading an answer is not as helpful as finding it yourself. If you give up on a problem, look at our answer for just that problem, so maybe you take a little more insight into your work on subsequent problems. Don't forget to start your session by including the standard book for [47mapply$[0m. (include-book "projects/apply/top" :dir :system) Don't bother with adding [47m:guard[0m expressions and don't define any functions of your own yet. All of these questions can be answered by [47mloop$[0m expressions involving only ACL2 primitives and the constant function [47mbags[0m which we introduce below for convenience. Let a ``bag'' be a true list of symbols. The function below returns a constant list of bags. You may use [47m(bags)[0m in your solutions. Notice that some elements of [47m(bags)[0m contain the symbol [47mx[0m and other do not. (defun bags () '((a b c) (d x e f) (g h i x) (j) (x k l))) Here is a sample question and how you might check that your [47mloop$[0m computes the expected value. ------------------------------ Sample Question: Build an alist that pairs the first symbol in every bag of [47m(bags)[0m with the number of other symbols in the bag. The expected value is [47m((A . 2) (D . 3) (G . 3) (J . 0) (X . 2))[0m. Sample Check of a Solution: (equal (loop$ for bag in (bags) collect (cons (car bag) (len (cdr bag)))) '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2))) Of course, you could just type the [47mloop$[0m statement at the top-level of your ACL2 session and visually inspect the answer. If you want to make a certified book out of your answers we recommend expressing the checks as [47mdefthm[0m events of [47m:rule-classes nil[0m, as in (defthm check-sample-question (equal (loop$ for bag in (bags) collect (cons (car bag) (len (cdr bag)))) '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2))) :rule-classes nil) However, if your [47mloop$[0m involves a user-defined function and you express your answers as [47mdefthm[0ms then each theorem will need to have appropriate warrant hypotheses, as illustrated below. (defun my-len (x) (if (atom x) 0 (+ 1 (my-len (cdr x))))) (defwarrant my-len) (defthm check-my-sample-question (implies (warrant my-len) (equal (loop$ for bag in (bags) collect (cons (car bag) (my-len (cdr bag)))) '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2)))) :rule-classes nil) ------------------------------ [31;1mLP6-1:[0m Concatenate all the bags in [47m(bags)[0m. [31;1mExpected Value:[0m[47m(A B C D X E F G H I X J X K L)[0m ------------------------------ [31;1mLP6-2:[0m Collect the bags that contain the symbol [47mx[0m. [31;1mExpected Value:[0m[47m((D X E F) (G H I X) (X K L))[0m ------------------------------ [31;1mLP6-3:[0m If you used some version of [47mmember[0m in your solution to LP6-2, now do it without using any version of [47mmember[0m. [31;1mExpected Value:[0m[47m((D X E F) (G H I X) (X K L))[0m Don't use any version of [47mmember[0m in your answers to the remaining questions in this section. ------------------------------ [31;1mLP6-4:[0m Remove all the [47mx[0ms from each bag in [47m(bags)[0m and concatenate the resulting bags. [31;1mExpected Value:[0m[47m(A B C D E F G H I J K L)[0m ------------------------------ [31;1mLP6-5:[0m Collect the first symbol of each of the bags in [47m(bags)[0m that contains an [47mx[0m. [31;1mExpected Value:[0m[47m(D G X)[0m ------------------------------ [31;1mLP6-6:[0m From each bag in [47m(bags)[0m, remove the elements preceding the first [47mx[0m and collect the resulting bags. [31;1mExpected Value:[0m[47m(NIL (X E F) (X) NIL (X K L))[0m ------------------------------ [31;1mLP6-7:[0m Let's say the ``alternating sum of signed squares'' of a list of numbers is the sum of the squares of the elements, except the squares of elements in even positions (0-based) are added and the squares in odd positions are subtracted. So the alternating sum of signed squares of [47m(1 2 3 4 5)[0m is [47m(+ 1 -4 9 -16 25)[0m = [47m15[0m. Compute the alternating sum of signed squares of the lengths of the bags in [47m(bags)[0m [31;1mExpected Value:[0m[47m(+ 9 -16 16 -1 9)[0m = [47m17[0m. ------------------------------ [31;1mLP6-8:[0m Collect all the function symbols in the current ACL2 world with an arity greater than 9. Three Hints: First, the term [47m(function-theory :here)[0m returns a list of the runes of all the [47m:logic[0m mode functions currently in the ACL2 world. However, it expands to an expression involving the variable [47mworld[0m which can be obtained by [47m(w state)[0m. And [47m[state][0m may not be used in [47mFOR[0m [47mloop$[0m! So you'll have to [47m[let][0m bind [47mworld[0m to [47m(w state)[0m and write your [47mloop$[0m inside the scope of that [47mlet[0m. Second, every [47m[rune][0m returned by [47mfunction-theory[0m is of the form [47m(:DEFINITION fn . x)[0m, where [47mfn[0m is the name of a function. Third, the arity of a symbol [47mfn[0m is obtained from the world by [47m(arity fn world)[0m, except sometimes (for reasons we won't go into!) it returns [47mnil[0m. [31;1mExpected Value:[0m As of ACL2 Version 8.5 (after including the [47m"projects/apply/top"[0m book) the answer was [47m(MEMOIZE-FORM SEARCH-FN SEARCH-FN-GUARD BUILD-STATE1)[0m, but that may change. ------------------------------ [31;1mLP6-9:[0m Collect the name of every theorem about [47mEXPT[0m in the current world. Three More Hints: First, the ACL2 world is a list of triples of the form [47m(name property . val)[0m representing the current property lists. In ACL2 Version 8.5, the length of the world (after including the [47m"projects/apply/top"[0m book) is 137,846, so it's too big to just look at! Second, each event that named a theorem has a triple of the form [47m(name THEOREM . val)[0m, where [47mname[0m is the event name and [47mval[0m is the translated version of the theorem. (Thus, you won't find macros like [47m+[0m or [47mappend[0m in [47mval[0m! Instead it would contain the function symbols appearing in their expansions, e.g., [47mbinary-+[0m and [47mbinary-append[0m. But since we're looking for [47mexpt[0m and it is not a macro, this doesn't matter.) Third, the ACL2 term [47m(all-fnnames term)[0m returns a list of all the function symbols used in the fully translated term [47mterm[0m. [31;1mExpected Value:[0m As of ACL2 Version 8.5 (after including the [47m"projects/apply/top"[0m book) the answer was [47m(APPLY$-PRIM-META-FN-EV-CONSTRAINT-462 RATIONALP-EXPT-TYPE-PRESCRIPTION EXPT-TYPE-PRESCRIPTION-NON-ZERO-BASE)[0m ------------------------------ These exercises highlight three important lessons about [47mloop$[0m. The first is that with [47mloop$[0m you can avoid defining a lot of recursive functions. Imagine doing these same exercises without [47mloop$[0m. The second is that it is not always a good idea to ``inline'' [47mloop$[0ms instead of defining functions. The clearest example of that arises above when we prohibited you from using [47mmember[0m! Just because [47mmember[0m can be replaced by a [47mloop$[0m doesn't mean it should be! [47mMember[0m is an exceptionally useful function that enjoys a lot of elegant properties. By introducing the name [47mmember[0m and proving its properties we can use it conveniently and appeal to those properties often. Of course, [47mmember[0m is a Common Lisp primitive, so we're not free to define it, but if we were to define a function like that we could use a [47mloop$[0m in its definition. Another example of this second lesson is in question LP6-7. Depending on the project at hand, the notion of ``alternating sum of signed squares'' might be a useful one in its own right. So perhaps if such a problem came up you might define [47m(alternating-sum-of-signed-squares lst)[0m, perhaps using [47mloop$[0m in the [47mdefun[0m, and then use (alternating-sum-of-signed-squares (loop$ for bag in (bags) collect (len bag))) to compute the quantity requested in LP6-7. The question raised by this second lesson isn't so much whether you use a [47mloop$[0m to express the concept but whether you use a [47mdefun[0m to give the concept a name. A good rule of thumb is: [3mif the concept has a natural name, define it![0m Of course, there is the usual trade-off between execution efficiency and modularity. There are various ways to deal with this trade-off in ACL2 but since they are not unique to [47mloop$[0m we won't discuss them. The third lesson is highlighted by LP6-8 and LP6-9. [47mLoop$[0m can be very useful in extracting data about your current ACL2 session, if you are familiar with the ACL2 system-level utilities (see [system-utilities] for some of them). Perhaps more relevant is the observation that if you are building a big model involving lots of data, you might find [47mloop$[0m handy in querying your own data. Now go to [lp-section-7] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-7 (loop$-primer) "Using [47mLoop$[0ms and Guards in [47mDefun[0ms LP7: Using [47mLoop$[0ms and Guards in [47mDefun[0ms [47mLoop$[0m statements are most efficient when they are guard verified. [47mLoop$[0ms typed at the top-level are typically not guard verified and so they are not executed by running compiled Common Lisp [47mloop[0ms. Instead, their formal semantics is executed which is akin to saying they are interpreted. But execution efficiency was one of the motivational factors in the introduction of [47mloop$[0m and that is best achieved by using [47mloop$[0ms in guard verified function definitions. Here is an example. We've already discussed [47mmember[0m and the fact that calls of [47mmember[0m can be replaced by [47mloop$[0ms. [47mMember[0m is a macro that expands logically to [47mmember-equal[0m, where (defun member-equal (x lst) (declare (xargs :guard (true-listp lst))) (cond ((endp lst) nil) ((equal x (car lst)) lst) (t (member-equal x (cdr lst))))) Let's define an equivalent function, named [47mmember-equal-loop$[0m, using [47mloop$[0m. (defun member-equal-loop$ (x lst) (declare (xargs :guard (true-listp lst))) (loop$ for tail of-type (satisfies true-listp) on lst thereis (if (equal x (car tail)) tail nil))) (defthm member-equal-loop$-is-member-equal (equal (member-equal-loop$ x lst) (member-equal x lst))) Since [47mmember-equal[0m has a guard of [47m(true-listp lst)[0m, we will give our [47mmember-equal-loop$[0m the same guard. But in our [47mloop$[0m above we also wrote that the iteration variable [47mtail[0m satisfies [47mtrue-listp[0m. We do that so that ACL2 can prove the guard on [47m(car tail)[0m in the [47mthereis[0m clause. (We could change ACL2 to infer this type for [47mtail[0m in this special case, but more generally we would prefer to have an effective heuristic for transferring arbitrary properties of [47mlst[0m to relevant properties of [47mtail[0m.) The guard obligations for [47mmember-equal-loop$[0m are obscure because we haven't explained the formal semantics of [47mloop$[0m yet. But we do not discuss the guard obligations of [47mloop$[0ms in the primer. If you define a function containing a [47mloop$[0m and try to verify its guards the system will generate the necessary obligations and try to prove them. Our solutions to all the exercises in this primer can be guard verified automatically. For more details on [47mFOR[0m [47mloop$[0m guards and the guard obligations they generate, see [for-loop$], specifically, the sections ``Special Guard Conjectures for [47mFOR[0m [47mLoop$[0ms'' and ``Discussion of Why [47mLoop$[0ms Have Special Guards.'' After admitting [47mmember-equal-loop$[0m ACL2 can prove inductively that it is equal to [47mmember-equal[0m. We'll come back to that later too. An alternative way to specify the type of [47mtail[0m would be to add a [47m:guard[0m rather than an [47mof-type[0m expression. (defun member-equal-loop$ (x lst) (declare (xargs :guard (true-listp lst))) (loop$ for tail on lst thereis :guard (true-listp tail) (if (equal x (car tail)) tail nil))) The [47m:guard[0m feature of ACL2 is more flexible than [47mof-type[0m because guards allow you to use multiple variables to express a constraint, while [47mof-type[0m implicitly limits the assertion to the variable being introduced. For example, with a guard you could say [47m(subsetp-equal tail lst)[0m while you cannot express such a constraint with [47mof-type[0m. However, [47mof-type[0m is understood by the Common Lisp compiler which might optimize the compiled code using that type information, while guards are not seen by the compiler. When you use a [47mloop$[0m in a [47mdefun[0m to be guard verified, be sure to constrain its iteration variables (and global variables) appropriately so you can verify the guards of the body. (You are also allowed to specify different guards for any [47mwhen[0m and [47muntil[0m expressions.) We generally split our constraints between [47mof-type[0m and [47m:guard[0m to inform the compiler of simple types, while more elaborate guard conditions are sometimes necessary to verify the guards of the body, etc. ACL2 will take any [47mof-type[0m information and conjoin it to any [47m:guard[0m when doing guard verification. Now go to [lp-section-8] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-8 (loop$-primer) "Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms LP8: Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms Do the problems below, starting in a fresh ACL2 session that starts with the standard [47m(include-book "projects/apply/top" :dir :system)[0m. Each problem starts with one or more recursive functions. Admit those functions in your session. Then define equivalent versions using [47mloop$[0ms instead of recursion. Make sure each of your [47mdefun[0ms is admitted and guard verified. Try to ensure that the [47mloop$[0m version is unconditionally equal to the recursive version of each function. But you might find more elegant solutions if you're willing to condition your equivalences on the guards of the recursive versions. After all, a main motivation for using [47mloop$[0m is the runtime efficiency of the compiled raw Lisp, and since no ACL2 function is executed in raw Lisp unless the guards are verified. Finally, you need not use ACL2 to prove that your [47mloop$[0m functions correctly implement their recursive counterparts. But you should be aware that with a few exceptions the proofs of our solutions were completely automatic. We'll focus on proving theorems about [47mloop$[0ms later in the primer. Our answers to the problems in this section are in [community-books] file [47mdemos/loop-primer/lp8.lisp[0m. ------------------------------ Sample Question: [47m(Sum-vals alist)[0m sums the value components of an alist. Note its guard. (defun symbol-to-integer-alistp (x) (declare (xargs :guard t)) (if (atom x) (equal x nil) (and (consp (car x)) (symbolp (caar x)) (integerp (cdar x)) (symbol-to-integer-alistp (cdr x))))) (defun sum-vals (alist) (declare (xargs :guard (symbol-to-integer-alistp alist))) (cond ((endp alist) 0) (t (+ (cdar alist) (sum-vals (cdr alist)))))) E.g., [47m(sum-vals '((a . 1) (b . 2) (c . 3))) = 6[0m. Define [47msum-vals-loop$[0m so that it is unconditionally equivalent to [47msum-vals[0m but uses [47mloop$[0m instead of recursion. Sample Solution: (defun sum-vals-loop$ (alist) (declare (xargs :guard (symbol-to-integer-alistp alist))) (loop$ for pair in alist sum :guard (and (consp pair) (integerp (cdr pair))) (cdr pair))) The [47m(consp pair)[0m in the [47mloop$[0m [47m:guard[0m is necessary because the [47mloop$[0m body contains [47m(cdr pair)[0m and Common Lisp expects [47mcdr[0m to be applied to a [47mconsp[0m or [47mnil[0m. The [47m(integerp (cdr pair))[0m is necessary because the value of the [47mloop$[0m body is being [47msum[0mmed and so must be (at least) a number to satisfy Common Lisp's expectation on [47m+[0m. Verification of Sample Solution: (defthm sum-vals-loop$-is-sum-vals (equal (sum-vals-loop$ alist) (sum-vals alist)) :rule-classes nil) It is conceivable in some Common Lisps that the following would compile into more efficient code. (defun sum-vals-loop$ (alist) (declare (xargs :guard (symbol-to-integer-alistp alist))) (loop$ for pair of-type cons in alist sum :guard (integerp (cdr pair)) (the integer (cdr pair)))) The thinking is that the [47mof-type cons[0m and [47m(the integer (cdr pair))[0m could in principle allow the compiler to do type checking that could eliminate runtime tests to avoid errors. That's because [47mof-type[0m and [47mthe[0m are Common Lisp primitives, as are the particular [47m[type-spec][0ms used in [47msum-vals-loop$[0m. Whether such a well-declared version of [47msum-vals-loop$[0m would actually run faster on your Common Lisp depends on the compiler and the optimization proclamations. In CCL and SBCL with ACL2's default proclamations, this well-declared version runs no faster than the original sample solution does. We raise this point simply to alert the reader to the difference between compiler directives and [47m:guard[0ms. ------------------------------ [31;1mLP8-1[0m Define [47msum-vals-loop$[0m which is like our solution shown for [47msum-vals[0m above, except instead of using [47msymbol-to-integer-alist[0m as the [47m:guard[0m write the [47m:guard[0m as [47m(and (true-listp alist) (loop$ ...))[0m. Be sure your definition is admitted and guard verified. If you want a slightly more challenging problem, omit the [47m(true-listp alist)[0m from the [47m:guard[0m and use a [47mFOR[0m [47mloop$[0m ``[47mON[0m'' [47malist[0m. FYI: Common Lisp requires ``[47mIN[0m'' [47mloop$[0ms to be over a [47mtrue-listp[0m target, but there is no such requirement for ``[47mON[0m'' [47mloop$[0ms. You can always convert an ``[47mIN[0m'' [47mloop$[0m governed by a [47mtrue-listp[0m check to an ``[47mON[0m'' [47mloop$[0m without the check. See our solutions. But because of that, we'll use the more elegant ``[47mIN[0m'' solutions in the rest of these problems. ------------------------------ [31;1mLP8-2[0m The recursive function below is in the ACL2 sources (therefore, you will not have to define it in your session). Define an equivalent function, named [47marglistp1-loop$[0m that uses [47mloop$[0m instead of recursion. (defun arglistp1 (lst) (declare (xargs :guard t)) (cond ((atom lst) (null lst)) (t (and (legal-variablep (car lst)) (arglistp1 (cdr lst)))))) Why is [47marglistp1-loop$[0m a little less efficient than [47marglistp[0m? ------------------------------ [31;1mLP8-3[0m The two recursive functions below are used in the ACL2 sources (thus, you won't have to define them in your session). Define [47mpackn1-loop$[0m that is equivalent to [47mpackn1[0m but so that it uses [47mloop$[0ms and does not mention [47matom-listp[0m. (defun atom-listp (lst) (declare (xargs :guard t :mode :logic)) (cond ((atom lst) (eq lst nil)) (t (and (atom (car lst)) (atom-listp (cdr lst)))))) (defun packn1 (lst) (declare (xargs :guard (atom-listp lst))) (cond ((endp lst) nil) (t (append (explode-atom (car lst) 10) (packn1 (cdr lst)))))) ------------------------------ [31;1mLP8-4[0m Define [47mselect-corresponding-element-loop$[0m so that it is equivalent to [47mselect-corresponding-element[0m, below, but using a [47mloop$[0m statement. (defun select-corresponding-element (e lst1 lst2) (declare (xargs :guard (and (true-listp lst1) (true-listp lst2) (not (member nil lst2))))) (cond ((endp lst1) nil) ((endp lst2) nil) ((equal e (car lst1)) (car lst2)) (t (select-corresponding-element e (cdr lst1) (cdr lst2))))) For example, (select-corresponding-element 'wednesday '(sunday monday tueday wednesday thursday friday saturday) '(dimanche lundi mardi mercredi jeudi vendredi samedi)) = 'MERCREDI ------------------------------ [31;1mLP8-5[0m Define [47msame-mod-wildcard-loop$[0m to be equivalent to [47msame-mod-wildcard[0m, below, but using a [47mloop$[0m statement. (defun same-mod-wildcard (lst1 lst2) (declare (xargs :guard (and (true-listp lst1) (true-listp lst2) (equal (len lst1) (len lst2))))) (cond ((endp lst1) t) ((or (eq (car lst1) '*) (eq (car lst2) '*)) (same-mod-wildcard (cdr lst1) (cdr lst2))) ((equal (car lst1) (car lst2)) (same-mod-wildcard (cdr lst1) (cdr lst2))) (t nil))) For example, (same-mod-wildcard '(a * c d *) '(a x c * d)) = T ------------------------------ [31;1mLP8-6[0m The following function is part of the ACL2 source code, so you don't have to define it in your session. (defun getprops1 (alist) (declare (xargs :guard (true-list-listp alist))) (cond ((endp alist) nil) ((or (null (cdar alist)) (eq (car (cdar alist)) *acl2-property-unbound*)) (getprops1 (cdr alist))) (t (cons (cons (caar alist) (cadar alist)) (getprops1 (cdr alist)))))) Define [47mgetprops1-loop$[0m to do the same thing using [47mloop$[0m. ------------------------------ Now go to [lp-section-9] (or return to the Table of Contents (see [LP-SECTION-0])).") (lp-section-9 (loop$-primer) "Semantics of [47mFOR[0m [47mLoop$[0ms LP9: Semantics of [47mFOR[0m [47mLoop$[0ms For a thorough discussion of the semantics of [47mFOR[0m [47mloop$[0ms see [for-loop$], specifically the section ``Semantics'' which includes two subsections, ``Semantics of Simple [47mLoop$[0ms'' and ``Semantics of Fancy [47mLoop$[0ms.'' ``Fancy'' [47mFOR[0m [47mloop$[0ms are [47mFOR[0m [47mloop$[0ms involving multiple iteration variables and/or use of ``global'' (i.e., non-iteration) variables in the [47mloop$[0m body or the [47muntil[0m or [47mwhen[0m clauses. We discuss [47mDO[0m [47mloop$[0ms later. In this section of the primer we just present some examples to drive home a few important points about [47mFOR[0m [47mloop$[0ms, namely * The semantics of a [47mloop$[0m statement is obtained by translating the [47mloop$[0m statement, as with the command [47m:[0m[47m[trans][0m. * However, translation inserts a lot of tags into the formal term it produced. These tags allow us to execute [47mloop$[0m statements more efficiently in the top-level ACL2 read-eval-print [47mloop$[0m. The tags on a translated [47mloop$[0m, [3mterm[0m, can be removed by the [47m:[0m[47m[tc][0m (``translate and clean'') command and its variants [47m:tca[0m and [47m:tcp[0m. When we exhibit semantics we typically show these simplified, equivalent terms produced by one of these commands. * The semantics of [47mFOR[0m [47mloop$[0ms look quite different from the semantics of [47mDO[0m [47mloop$[0ms. Furthermore, the semantics of simple [47mloop$[0ms have a different form than those of fancy [47mloop$[0m. So ``minor'' changes in the syntax of a [47mloop$[0m statement --- the addition of an [47mAS[0m clause, the use of global variable in the body of the [47mloop$[0m, or the use of [47mDO[0m instead of, say, [47mcollect[0m --- can cause radical changes in the form of the semantics. * The semantics of [47mloop$[0ms always involve calls of [47m[scion][0ms on lambda objects derived from the [47mwhen[0m, [47muntil[0m, and [47mloop$[0m body clauses. The scions for simple [47mFOR[0m [47mloop$[0ms are [47msum$[0m, [47mcollect$[0m, [47malways$[0m, [47mthereis$[0m, [47mappend$[0m, [47muntil$[0m, and [47mwhen$[0m; the scions for fancy [47mFOR[0m [47mloop$[0ms are [47msum$+[0m, [47mcollect$+[0m, [47malways$+[0m, [47mthereis$+[0m, [47mappend$+[0m, [47muntil$+[0m, and [47mwhen$+[0m; and the scion for [47mDO[0m [47mloop$[0ms is [47mdo$[0m. * The iteration variables become formals of the [47mlambda[0m objects and standard names are used in place of the user's names. Now we drive home these points with some examples. The next section (see [LP-SECTION-10]) elaborates further. Here is the full, formal translation of a simple [47mFOR[0m [47mloop$[0m. ACL2 !>:trans (loop$ for x of-type integer in lst when (evenp x) collect (* x x)) (RETURN-LAST 'PROGN '(LOOP$ FOR X OF-TYPE INTEGER IN LST WHEN (EVENP X) COLLECT (* X X)) (COLLECT$ '(LAMBDA (LOOP$-IVAR) (DECLARE (TYPE INTEGER LOOP$-IVAR) (XARGS :GUARD (INTEGERP LOOP$-IVAR) :SPLIT-TYPES T) (IGNORABLE LOOP$-IVAR)) (RETURN-LAST 'PROGN '(LAMBDA$ (LOOP$-IVAR) (DECLARE (TYPE INTEGER LOOP$-IVAR)) (LET ((X LOOP$-IVAR)) (DECLARE (IGNORABLE X)) (* X X))) ((LAMBDA (X) (BINARY-* X X)) LOOP$-IVAR))) (WHEN$ '(LAMBDA (LOOP$-IVAR) (DECLARE (TYPE INTEGER LOOP$-IVAR) (XARGS :GUARD (INTEGERP LOOP$-IVAR) :SPLIT-TYPES T) (IGNORABLE LOOP$-IVAR)) (RETURN-LAST 'PROGN '(LAMBDA$ (LOOP$-IVAR) (DECLARE (TYPE INTEGER LOOP$-IVAR)) (LET ((X LOOP$-IVAR)) (DECLARE (IGNORABLE X)) (EVENP X))) ((LAMBDA (X) (EVENP X)) LOOP$-IVAR))) LST))) However, the logical meaning of this is easier to understand by looking at one of the [47mtc[0m variations. ACL2 !>:tc (loop$ for x of-type integer in lst when (evenp x) collect (* x x)) (COLLECT$ '(LAMBDA (LOOP$-IVAR) (BINARY-* LOOP$-IVAR LOOP$-IVAR)) (WHEN$ '(LAMBDA (LOOP$-IVAR) (EVENP LOOP$-IVAR)) LST)) ACL2 !>:tcp (loop$ for x of-type integer in lst when (evenp x) collect (* x x)) (COLLECT$ (LAMBDA$ (LOOP$-IVAR) (* LOOP$-IVAR LOOP$-IVAR)) (WHEN$ (LAMBDA$ (LOOP$-IVAR) (EVENP LOOP$-IVAR)) LST)) ACL2 !>:tca (loop$ for x of-type integer in lst when (evenp x) collect (* x x)) (PROG2$ '(LOOP$ FOR X OF-TYPE INTEGER IN LST WHEN (EVENP X) COLLECT (* X X)) (COLLECT$ (LAMBDA$ (LOOP$-IVAR) (DECLARE (TYPE INTEGER LOOP$-IVAR) (XARGS :GUARD (INTEGERP LOOP$-IVAR) :SPLIT-TYPES T)) (LET ((X LOOP$-IVAR)) (* X X))) (WHEN$ (LAMBDA$ (LOOP$-IVAR) (DECLARE (TYPE INTEGER LOOP$-IVAR) (XARGS :GUARD (INTEGERP LOOP$-IVAR) :SPLIT-TYPES T)) (LET ((X LOOP$-IVAR)) (EVENP X))) LST))) Note that [47m:tc[0m prints the term generated by translating the [47mloop$[0m and then removing all tags. The guard and type declarations are logically irrelevant. What you see is what the theorem prover will see (if all the necessary warrants are assumed) before it starts to rewrite the term. Note that the [47mlambda[0m object is just a quoted list constant and the body has been translated so that the [47m*[0m macro was expanded in terms of [47mbinary-*[0m. [47m:Tcp[0m (``p'' for ``pretty'') introduces familiar system macros. [47m:Tca[0m (``a'' for ``annotations'') includes the original [47mloop$[0m statement and shows declarations (if any) and the correspondence between the user's iteration variable ([47mx[0m here) and the formal variable used in the [47mlambda[0m objects generated ([47mloop$-ivar[0m here). The translation of [47mloop$[0m bodies into [47mlambda[0m objects standardizes the variable name, either as [47mloop$-ivar[0m for simple [47mloop$[0ms which have just one iteration variable, or as [47mloop$-gvars[0m and [47mloop$-ivars[0m for fancy [47mloop$[0ms which may have one or more global variables and one or more iteration variables. We'll deal with fancy [47mloop$[0ms immediately below, but values are passed for [47mloop$-gvars[0m and [47mloop$-ivars[0m as tuples listing all the global values and all the current iteration variable values. The advantage of this standardization is that choosing different names for the iteration variables does not affect the formal semantics. However, if we make a simple syntactic change, like introducing a global variable by changing the body of the loop$ from [47m(* x x)[0m to [47m(* x a)[0m, where [47ma[0m is not an iteration variable, we drastically change the semantics because we've converted the simple [47mloop$[0m into a fancy [47mloop$[0m. The (clean and pretty) semantics of (loop$ for x in lst when (evenp x) collect (* x a)) is (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (* (CAR LOOP$-IVARS) (CAR LOOP$-GVARS))) (LIST A) (WHEN$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (EVENP (CAR LOOP$-IVARS))) NIL (LOOP$-AS (LIST LST)))) The annotated semantics of that [47mloop$[0m is (PROG2$ '(LOOP$ FOR X IN LST WHEN (EVENP X) COLLECT (* X A)) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1)) :SPLIT-TYPES T)) (LET ((A (CAR LOOP$-GVARS)) (X (CAR LOOP$-IVARS))) (* X A))) (LIST A) (WHEN$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 0) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1)) :SPLIT-TYPES T)) (LET ((X (CAR LOOP$-IVARS))) (EVENP X))) NIL (LOOP$-AS (LIST LST))))) Logically, we could have typed either of the above terms instead of the fancy [47mloop$[0m. But operationally, the [47mloop$[0m executes faster (when guards are verified). Notice that the simple scions [47mCOLLECT$[0m and [47mWHEN$[0m have been replaced by their fancy counterparts, [47mCOLLECT$+[0m and [47mWHEN$+[0m. The [47mlambda[0m objects now have two formals, one for holding a tuple containing all of the global variable values and one for a tuple holding all of the current iteration variable values. The global variable value tuple, [47m(LIST A)[0m, is passed into the fancy scions if the corresponding [47mlambda[0m object uses globals (as for the [47mcollect$+[0m but not for the [47mwhen$+[0m [47mlambda[0m where [47mNIL[0m is passed instead). The list over which the iteration variable ranges, [47mLST[0m, is now a list of tuples constructed by [47mLOOP$-AS[0m. Finally, the bodies of the [47mlambda[0ms now access the relevant values with [47mCAR[0m and [47mCDR[0m nests around the global and iteration tuples. (No [47mCDR[0ms appear above because there is only one global and one iteration variable in this example.) The following similar but still fancier [47mloop$[0m illustrates the general situation. This [47mloop$[0m has two iteration variables, [47mx[0m and [47my[0m taking on values from two ranges, [47mxlst[0m, and [47mylst[0m, and uses two global variables, [47ma[0m and [47mb[0m, in the body. We've added comments to name the components of the two tuples. ACL2 !>:tcp (loop$ for x in xlst as y in ylst when (evenp x) collect (* x y a b)) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (* (CAR LOOP$-IVARS) ; x (CADR LOOP$-IVARS) ; y (CAR LOOP$-GVARS) ; a (CADR LOOP$-GVARS))) ; b (LIST A B) (WHEN$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (EVENP (CAR LOOP$-IVARS))) ; x NIL (LOOP$-AS (LIST XLST YLST)))) Notice how the bodies of the [47mlambda[0m objects now use components of the [47mloop$-gvars[0m and [47mloop$-ivars)[0m for the current values of the global variables [47ma[0m and [47mb[0m and the iteration variables [47mx[0m and [47my[0m. The values of [47mx[0m and [47my[0m are corresponding elements of [47mxlst[0m and [47mylst[0m as grouped together by [47m(loop$-as (list xlst ylst))[0m. For a still-more elaborate [47mFOR[0m [47mloop$[0m and a step-by-step description of how the value of the formal semantics is computed, go to [lp-section-10]. Now go to [lp-section-10] (or return to the Table of Contents (see [LP-SECTION-0])).") (macro-aliases-table (macros) "A [table] used to associate function names with macro names Example Form: (table macro-aliases-table 'append 'binary-append) This example associates the function symbol [47m[binary-append][0m with the macro name [47m[append][0m. As a result, the name [47m[append][0m may be used as a runic designator (see [theories]) by the various theory functions. Thus, for example, it will be legal to write (in-theory (disable append)) as an abbreviation for (in-theory (disable binary-append)). General Form: (table macro-aliases-table 'macro-name 'function-name) or more generally (table macro-aliases-table macro-name-form function-name-form) where [47mmacro-name-form[0m and [47mfunction-name-form[0m evaluate to values [47mMAC[0m and [47mFN[0m, subject to the following requirements. * [47mMAC[0m is a symbol that is a macro name. * [47mFN[0m is a symbol. * [47mFN[0m is either a function symbol or else a symbol that does not have a definition (a [3mnew name[0m). In particular, [47mFN[0m is not a macro name. After admitting the [table] event displayed above, we may say that [47mMAC[0m is a [3mmacro-alias for[0m [47mFN[0m. Further Explanation See [table] for a general discussion of tables and the [47mtable[0m [event], which is used to manipulate tables. The table, [47m[macro-aliases-table][0m, is an alist that can associate macro symbols with function symbols, so that macro names may be used as runic designators (see [theories] and discussion below). For a convenient way to add entries to this [table], see [add-macro-alias], which allows the second argument to be, itself, a macro-alias. To remove entries conveniently from the [table], see [remove-macro-alias]. As hinted above, this [table] is used by theory functions; see [theories]. For example, in order that [47m(disable append)[0m be interpreted as [47m(disable binary-append)[0m, it suffices that [47m(table macro-aliases-table 'append 'binary-append)[0m, has been executed. In fact, this [table] does indeed establish many of the macros provided by the ACL2 system as macro-aliases, such as establishing [47m[append][0m as a macro-alias for [47m[binary-append][0m. This only takes place when the macro is ``essentially the same thing as'' a corresponding function; for example, [47m(append x y)[0m and [47m(binary-append x y)[0m represent the same term, for any expressions [47mx[0m and [47my[0m. Note that the value [47mFN[0m of [47mfunction-name-form[0m (above) is allowed to be a symbol to be defined later as a function symbol. The following examples illustrate some approaches that work and some that do not. ;;;;;;;;;; ;;; Example 1: No errors, with function defined before setting the table. ;;;;;;;;;; (defun fn (x) x) (defmacro mac (x) (list 'fn x)) (table macro-aliases-table 'mac 'fn) ; or (add-macro-alias mac fn) (in-theory (disable mac)) ;;;;;;;;;; ;;; Example 2: No errors, with function defined after setting the table. ;;;;;;;;;; (defmacro mac (x) (list 'fn x)) ; Legal, even though fn is not yet defined: (table macro-aliases-table 'mac 'fn) ; or (add-macro-alias mac fn) (defun fn (x) x) (in-theory (disable mac)) ;;;;;;;;;; ;;; Example 3: ERROR. ;;;;;;;;;; (defun fn (x) x) (defmacro mac1 (x) (fn x)) (defmacro mac2 (x) (list 'mac1 x)) ; BAD, since the table event above anticipates fn to be defined as ; a function, not a macro (but, no error yet) -- but not (yet) an error: (table macro-aliases-table 'mac2 'mac1) ; or (add-macro-alias mac2 mac1) ; ERROR, since mac2 does not designate rules, because it aliases a macro: (in-theory (disable mac2)) ; OK, but too late to help with that in-theory event; see below: (table macro-aliases-table 'mac1 'fn) ; or (add-macro-alias mac1 fn) ; ERROR, since mac2 is still associated with mac1, not with fn: (in-theory (disable mac2)) ;;;;;;;;;; ;;; Example 4: Fixed version of Example 3. ;;;;;;;;;; (defun fn (x) x) (defmacro mac1 (x) (fn x)) (defmacro mac2 (x) (list 'mac1 x)) (add-macro-alias mac1 fn); or (table macro-aliases-table 'mac1 'fn) ; The following is equivalent to (add-macro-alias mac2 fn), since ; mac1 is a macro-alias for fn by virtue of the preceding event. (add-macro-alias mac2 mac1) ; Success: (in-theory (disable mac2))") (macro-args (macros) "The formals list of a macro definition Examples: (x y z) (x y z &optional max (base '10 basep)) (x y &rest rst) (x y &key max base) (&whole sexpr x y) The ``lambda-list'' of a macro definition may include simple formal parameter names as well as appropriate uses of the following lambda-list keywords from Common Lisp, respecting the order shown: * [47m&whole x[0m [47mX[0m does not represent an actual parameter; rather, it is bound to the entire macro call. * [47m&optional x1 x2 ...[0m The actual for any [47mxi[0m may be omitted, in which case the actual for every [47mxj[0m with [47mj > i[0m must also be omitted. * [47m&rest x[0m [47mX[0m does not represent an actual parameter; rather, it is bound to the list of all actuals provided from that position onward. * [47m&body x[0m This is identical to [47m&rest x[0m. * [47m&key x[0m The call may have a keyword argument for [47mx[0m by including [47m:x val[0m after all required actual parameters, in which case the formal [47mx[0m is bound to the actual [47mval[0m. * [47m&allow-other-keys[0m Keyword arguments not specified by [47m&key[0m are allowed but ignored. ACL2 does not support the Common Lisp lambda-list keywords [47m&aux[0m and [47m&environment[0m. In addition, there are the following restrictions: (1) initialization forms in [47m&optional[0m and [47m&key[0m specifiers must be quoted values; (2) [47m&allow-other-keys[0m may only be used once, as the last specifier; and (3) destructuring is not allowed. The use of default values is allowed, so that an optional or keyword argument may be given in any of the following forms. * [47marg[0m or, equivalently, [47m(arg)[0m * [47m(arg 'init)[0m * [47m(arg 'init supplied-p)[0m For the second and third forms above, [47minit[0m is the value when the argument is not supplied; for the first form, that default value is [47mnil[0m. Note that it must be quoted. The [47msupplied-p[0m argument is [47mnil[0m when the argument is not supplied, else is [47mt[0m, as illustrated by the demo below. You are encouraged to experiment with the macro facility. One way to do so is to define a macro that does nothing but return the quotation of its arguments, e.g., (defmacro demo (x y &optional (opt '5) &key (key1 '6 key1p) key2) (list 'quote (list x y opt key1 key1p key2))) You may then execute the macro on some sample forms, e.g., term value (demo 1 2) (1 2 5 6 NIL NIL) (demo 1 2 3) (1 2 3 6 NIL NIL) (demo 1 2 3 :key1 6) (1 2 3 6 T NIL) (demo 1 2 3 :key1 7) (1 2 3 7 T NIL) (demo 1 2 3 :key2 8) (1 2 3 6 NIL 8) (demo 1 2 :key1 3) error: non-even key/value arglist (because :key1 is used as opt) In particular, Common Lisp specifies (hence so does ACL2) that if you use both [47m&rest[0m and [47m&key[0m, then both will be bound using the same list of arguments. The following example should serve to illustrate how this works. ACL2 !>(defmacro foo (&rest args &key k1 k2 k3) (list 'quote (list args k1 k2 k3))) Summary Form: ( DEFMACRO FOO ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !>(foo :k1 3 :k2 4 :k3 5) ((:K1 3 :K2 4 :K3 5) 3 4 5) ACL2 !>(foo :k1 3 :k2 4) ((:K1 3 :K2 4) 3 4 NIL) ACL2 !>(foo :k1 3 :bad-key 7) ACL2 Error in macro expansion: Illegal key/value args (:BAD-KEY 7) in macro expansion of (FOO :K1 3 :BAD-KEY 7). The argument list for FOO is (&REST ARGS &KEY K1 K2 K3). ACL2 !> If we don't want to get the error above, we can use [47m&allow-other-keys[0m, as follows. ACL2 !>(defmacro bar (&rest args &key k1 k2 k3 &allow-other-keys) (list 'quote (list args k1 k2 k3))) Summary Form: ( DEFMACRO BAR ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) BAR ACL2 !>(bar :k1 3 :bad-key 7) ((:K1 3 :BAD-KEY 7) 3 NIL NIL) ACL2 !> Also see [trans]. Subtopics [Set-duplicate-keys-action] Control action for macro calls with duplicate keyword arguments") (macro-command (proof-builder) "Compound command for the interactive proof-builder The interactive [proof-builder] supports the definition of compound commands, called ``macro commands'', which expand into zero or more other commands. Some of these are ``atomic'' macro commands; these are viewed as a single command step when completed successfully. More [documentation] may be written on the interactive [proof-builder]. For now, we simply point out that there are lots of examples of the use of [47mdefine-pc-macro[0m and [47mdefine-pc-atomic-macro[0m in the ACL2 source file [47m"proof-builder-b.lisp"[0m. The former is used to create macro commands, which can be submitted to the interactive loop (see [verify]) and will ``expand'' into zero or more commands. The latter is similar, except that the undoing mechanism (see [ACL2-pc::undo]) understands atomic macro commands to represent single interactive commands. Also see [ACL2-pc::comm] and see [ACL2-pc::commands] for a discussion of the display of interactive commands. Also see [toggle-pc-macro] for how to change a macro command to an atomic macro command, and vice versa.") (macrolet (basics acl2-built-ins) "Local binding of macro symbols See [flet] for an analogous utility for defining functions locally. Example Form: (defun f1 (x) (macrolet ((mac (a) (list 'quote a))) (cons x (mac x)))) The Example Form above is equivalent to the following, in which the call of local macro [47mmac[0m has been expanded. (defun f1-alt (x) (cons x (quote x))) The General Forms are similar to those of [47m[flet][0m. General Forms: (macrolet (def1 ... defk) body) (macrolet (def1 ... defk) declare-form1 .. declare-formk body) where [47mbody[0m is a term, and each [47mdefi[0m is a definition as in [47m[defmacro][0m but with the leading [47mdefmacro[0m symbol omitted. See [defmacro], but see [declare] for the declarations permitted directly under the [47mdefi[0m. On the other hand, regarding the [47mdeclare-formi[0m (if any are supplied): each must be of the form [47m(declare decl1 ... decln)[0m, where each [47mdecli[0m is of the form [47m(inline g1 ... gm)[0m or [47m(notinline g1 ... gm)[0m, and each [47mgi[0m is defined by some [47mdefi[0m. Unlike the related utility [47m[flet][0m, those [47minline[0m and [47mnotinline[0m declarations are unlikely to have any effect. The innermost [47m[flet][0m or [47mmacrolet[0m binding of a symbol, [47mf[0m, above a call of [47mf[0m, is the one that provides the definition of [47mf[0m for that call. Note that neither [47mflet[0m nor [47mmacrolet[0m provide recursion: that is, the definition of [47mf[0m in an [47mflet[0m or [47mmacrolet[0m binding of [47mf[0m is ignored in the body of that binding. The following requirements are imposed by Common Lisp and enforced by ACL2. * Every variable occurring in the body of a [47mdefi[0m must be a formal parameter name of that [47mdefi[0m. * No function or macro symbol called in the body of a [47mdefi[0m may be defined by a superior [47mflet[0m or [47mmacrolet[0m binding. (Not every Common Lisp implementation includes this restriction for superior [47mmacrolet[0m bindings, but at least one (GCL) does so we include it in ACL2.) Although [47mmacrolet[0m behaves in ACL2 essentially as it does in Common Lisp, ACL2 imposes the following restrictions and qualifications. * Every [47m[declare][0m form for a local definition ([47mdef1[0m through [47mdefk[0m, above) must be an [47mignore[0m, [47mignorable[0m, or [47mtype[0m expression. * Each [47mdefi[0m must bind a different symbol. * Each [47mdefi[0m must bind a symbol that is a legal name for an ACL2 macro. In particular, the symbol may not be in the keyword package or the main Lisp package. Moreover, the symbol may not be a built-in ACL2 function or macro. * When an expression [47m(macrolet (... defi ...) ...)[0m occurs in the body of a [47mDO[0m [47m[loop$][0m expression, nevertheless constructs such as [47mPROGN[0m and [47mSETQ[0m that ACL2 permits in [47mDO[0m [47mloop$[0m bodies are not permitted in [47mdefi[0m (unless they occur within the scope of a [47mDO[0m [47mloop$[0m expression in that body). [47mMacrolet[0m bindings are evaluated in parallel. Consider the following example. (defun f1 (x) (cons x 'x)) (macrolet ((f1 (x) x) (f2 () (list 'quote ; The following reference is to the global f1, ; not to the identity macro just above. (f1 3)))) (f2)) The [47mmacrolet[0m form above evaluates to [47m(3 . x)[0m, not to 3, as explained in the comment above. Here is a somewhat analogous form that one might expect to evaluate to 3, but that is not the case; see below. (macrolet ((f1 (x) x)) (macrolet ((f2 () (list 'quote (f1 3)))) (f2))) The body of [47mf2[0m calls a symbol, [47mf1[0m, that is bound by a superior [47mmacrolet[0m binding. As noted above, this is illegal (also for superior [47mflet[0m bindings). Under the hood, ACL2 expands away [47mmacrolet[0m bindings. The following example illustrates this point. ACL2 !>:trans (macrolet ((mac (a) (list 'cons a a))) (car (mac b))) (CAR (CONS B B)) => * ACL2 !> [47mMacrolet[0m is part of Common Lisp. See any Common Lisp documentation for more information. We conclude by pointing out an important aspect of [47mmacrolet[0m shared by ACL2 and Common Lisp: The binding is lexical, not dynamic. That is, the [47mmacrolet[0m binding of a symbol only applies to calls of that symbol in the body of the [47mmacrolet[0m, not other calls made in the course of evaluation. See [flet] for discussion of this point.") (macros (acl2) "Macros allow you to extend the syntax of ACL2. Subtopics [Add-binop] Associate a function name with a macro name [Add-macro-alias] Associate a function name with a macro name [Add-macro-fn] Associate a function name with a macro name [Check-vars-not-free] Avoid variable capture in macro calls [Defabbrev] A convenient form of macro definition for simple expansions [Defmacro] Define a macro [Defmacro-untouchable] Define an ``untouchable'' macro [Macro-aliases-table] A [table] used to associate function names with macro names [Macro-args] The formals list of a macro definition [Make-event] Evaluate (expand) a given form and then evaluate the result [Remove-binop] Remove the association of a function name with a macro name [Remove-macro-alias] Remove the association of a function name with a macro name [Remove-macro-fn] Remove the association of a function name with a macro name [Safe-mode] A mode that avoids [guard] violations on [primitive]s [Set-duplicate-keys-action] Control action for macro calls with duplicate keyword arguments [Tc] translate form and clean it up [Tca] translate a form and clean it up into an annotated pretty term [Tcp] translate a form and clean it up into a pretty term [Trans] Print the translation of a form [Trans!] Print the translation without code restrictions on the input [Trans*] Show intermediate expansion results for the translation of a form [Trans*-] Variant of [47m[trans*][0m the skips [47m[make-event][0m expansion [Trans1] Print the one-step macroexpansion of a form [Untrans-table] Associates a function symbol with a macro for printing user-level terms [User-defined-functions-table] An advanced [table] used to replace certain system functions") (magic-ev-fncall (meta) "Call the named function on the given arguments and return the value. Introduction. [47mMagic-ev-fncall[0m is a [logic]-mode function that can apply a given function (which need not be in logic mode) to an argument list. Although the result can be computed, [47mmagic-ev-fncall[0m is technically a constrained function (with unknown constraints), which can be assumed in metafunctions and [clause] processors to produce correct results, via [meta-extract]. Examples: (magic-ev-fncall 'cons '(3 4) state t nil) = (mv nil '(3 . 4)) (magic-ev-fncall (car '(floor foo)) (list (+ 6 7) 5) state t nil) = (mv nil 2) General Form: (magic-ev-fncall fn arglist state hard-error-returns-nilp aokp) where [47mfn[0m is a function symbol, [47marglist[0m is a suitable argument list for [47mfn[0m, and the last two formals are described below. When successful, the result is [47m(mv nil value)[0m where [47mvalue[0m is the application of [47mfn[0m to [47marglist[0m. Although this fact cannot be proven, it may be assumed correct in metafunctions and clause processors via [meta-extract], assuming of course that [47mfn[0m is a [logic]-mode function. In general, the result is either [47m(mv t error-msg)[0m (if, e.g., the function was not defined, the arity was wrong, or the guards were violated) or [47m(mv nil value)[0m on success. In the case of a [multiple-value]d function the second return value is the list of values. A non-nil error message, [47merror-msg[0m, is a message suitable for printing with [47m[fmt][0m; see [msg]. If a hard error is encountered during execution and [47mhard-error-returns-nilp[0m is non-[47mnil[0m, then the error is ignored and the value returned is [47m(mv nil nil)[0m (note that the logical value of a call of [47mHARD-ERROR[0m is [47mnil[0m). If [47mhard-error-returns-nilp[0m is [47mnil[0m then the return value is of the form [47m(mv T error-msg)[0m. The [47maokp[0m argument controls whether attachments to constrained functions may be executed (see [defattach]). If [47mnil[0m, then an error message is returned when an attachment would otherwise be executed. When used in a clause-processor or metafunction, it can be assumed via a [meta-extract] hypothesis that [47mmagic-ev-fncall[0m works correctly with respect to the evaluator, but only if [47mhard-error-returns-nilp[0m is [47mt[0m and [47maokp[0m is [47mnil[0m. The [guard] for [47m(magic-ev-fncall fn arglist state h aokp)[0m is [47mt[0m, but evaluation of this call enforces the following requirements. * [47mFn[0m must be a function symbol of the current ACL2 [world] other than [47mif[0m, whose arity is equal to the length of the true-list, [47marglist[0m. * [47mFn[0m must not have any [47mstobj[0m inputs or be a stobj creator. * Calls of [47mfn[0m must not require a trust tag (see [defttag]). * [47mFn[0m must not be untouchable (see [push-untouchable]). The implementation of these checks incorporates a bit of trickery so that they are reasonably efficient. Note that [47m[set-guard-checking][0m affects evaluation of calls of [47m(magic-ev-fncall fn ...)[0m just as it affects calls of [47mfn[0m, for example as follows. ACL2 !>(magic-ev-fncall 'car '((a b c)) state t nil) (NIL A) ACL2 !>(magic-ev-fncall 'car '(3) state t nil) (T <... message elided here ...>) ACL2 !>(set-guard-checking nil) Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(magic-ev-fncall 'car '(3) state t nil) (NIL NIL) ACL2 > Additional Notes. * If [47mfn[0m is a [program]-mode function, then the call will be evaluated under [safe-mode], which avoids raw Lisp errors due to calls of ill-[guard]ed program-mode functions. * If the application of [47mfn[0m returns multiple values [47m(mv v1 v2 ...)[0m, then the resulting value will be the corresponding list [47m(v1 v2 ...)[0m. * A reasonable model for [47m(magic-ev-fncall 'fn (list a1 a2 ...) state h aokp)[0m is [47m(ec-call (fn a1 a2 ...))[0m.") (mailing-lists (acl2 about-acl2 community) "Mailing lists for ACL2 users There are the following mailing lists for ACL2 users. You can post messages to these lists only if you are a member, but anyone can view the archives. * [31;1macl2 list[0m: General ACL2 list for users and others interested in ACL2 * To post: [47m{acl2@utlists.utexas.edu | mailto:acl2@utlists.utexas.edu}[0m * To subscribe, unsubscribe, or view archives: [47m{https://utlists.utexas.edu/sympa/info/acl2 | https://utlists.utexas.edu/sympa/info/acl2}[0m * [31;1macl2-help list[0m: ACL2 help list, for questions about using ACL2(recommended for new users) * To post: [47m{acl2-help@utlists.utexas.edu | mailto:acl2-help@utlists.utexas.edu}[0m * To subscribe, unsubscribe, or view archives: [47m{https://utlists.utexas.edu/sympa/info/acl2-help | https://utlists.utexas.edu/sympa/info/acl2-help}[0m * [31;1macl2-books list[0m: Mailing list for discussion of cutting-edge developments in ACL2 and the ACL2 Community Books * To post: [47m{acl2-books@googlegroups.com | mailto:acl2-books@googlegroups.com}[0m * To subscribe, unsubscribe, or view archives: [47m{https://groups.google.com/forum/#!forum/acl2-books | https://groups.google.com/forum/#!forum/acl2-books}[0m Finally, please report bugs in ACL2 to {Matt Kaufmann | mailto:kaufmann@cs.utexas.edu}. See [community] for ways to connect with other ACL2 users, get help with ACL2, and contribute to improving ACL2 and its [community-books].") (make (defrec acl2-built-ins) "Constructor macro for [defrec] structures. The [47mmake[0m macro is built into ACL2, and allows you to construct new instances of structures that have been introduced with [defrec]. For instance: (make employee :name "Jimmy" :salary 0 :position "Unpaid Intern") Creates a new [47memployee[0m structure with the given values for its [47mname[0m, [47msalary[0m, and [47mposition[0m fields. See [defrec] for more information.") (make-character-list (characters acl2-built-ins) "[coerce] to a list of characters Non-characters in the given list are [coerce]d to the character with code 0. [31;1mFunction: [0m<make-character-list> (defun make-character-list (x) (declare (xargs :guard t)) (cond ((atom x) nil) ((characterp (car x)) (cons (car x) (make-character-list (cdr x)))) (t (cons *null-char* (make-character-list (cdr x))))))") (make-event (events macros) "Evaluate (expand) a given form and then evaluate the result [47mMake-event[0m is a utility for generating [events]. It provides a capability not offered by Lisp macros (see [defmacro]), as it allows access to the ACL2 [state] and logical [world]. In essence, the expression [47m(make-event form)[0m replaces itself with the result of evaluating [47mform[0m --- let's call that result [47mev[0m --- as though one had submitted [47mev[0m instead of the [47mmake-event[0m call. For example, [47m(make-event (quote (defun f (x) x)))[0m is equivalent to the event [47m(defun f (x) x)[0m. We assume basic familiarity with the ACL2 [3mstate[0m. For relevant background, see [state] and perhaps see [programming-with-state]. There are several simple examples below. For examples that can give additional insight into the use of [47mmake-event[0m for tool development, see [make-event-example-1] and [make-event-example-2]. Also see the [47mmake-event/[0m subdirectory of the ACL2 [community-books] for more examples, for example, [47mbooks/make-event/search-generation.lisp[0m. We break this documentation into the following sections. * [31;1mIntroduction[0m * [31;1mDetailed Documentation[0m * [31;1mError Reporting[0m * [31;1mRestriction to Event Contexts[0m * [31;1mExamples Illustrating How to Access State[0m * [31;1mAdvanced Expansion Control[0m We begin with an introduction, which focuses on examples and introduces the key notion of ``expansion phase''. Introduction [47mMake-event[0m is particularly useful for those who program using the ACL2 [47m[state][0m; see [programming-with-state]. That is because the evaluation of [47mform[0m may read and even modify the ACL2 [47m[state][0m. Suppose for example that we want to define a constant [47m*world-length*[0m, that is the length of the current ACL2 [world]. A [47mmake-event[0m form can accomplish this task, as follows. ACL2 !>(length (w state)) 98883 ACL2 !>(make-event (list 'defconst '*world-length* (length (w state)))) Summary Form: ( DEFCONST *WORLD-LENGTH* ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Summary Form: ( MAKE-EVENT (LIST ...)) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) *WORLD-LENGTH* ACL2 !>*world-length* 98883 ACL2 !>(length (w state)) 98890 ACL2 !> How did this work? First, evaluation of the form [47m(list 'defconst '*world-length* (length (w state)))[0m returned the event form [47m(defconst *world-length* 98883)[0m. Then that event form was automatically submitted to ACL2. Of course, that changed the ACL2 logical [world], which is why the final value of [47m(length (w state))[0m is greater than its initial value. The example above illustrates how the evaluation of a [47mmake-event[0m call takes place in two phases. The first phase evaluates the argument of the call, in this case [47m(list 'defconst '*world-length* (length (w state)))[0m, to compute an event form, in this case [47m(defconst *world-length* 98883)[0m. We call this evaluation the ``expansion'' phase. Then the resulting event form is evaluated, which in this case defines the constant [47m*world-length*[0m. Now suppose we would like to introduce such a [47m[defconst][0m form any time we like. It is common practice to define macros to automate such tasks. Now we might be tempted simply to make the following definition. ; WRONG! (defmacro define-world-length-constant (name state) (list 'defconst name (length (w state)))) But ACL2 rejects such a definition, because the formal parameter [47m"STATE"[0m is bound to the syntactic object in the macro call, not to the actual ACL2 [state]; see [defmacro]. You can try to experiment with other such direct methods to define a macro that accesses the ACL2 state, but they won't work. Instead, however, you can use the approach illustrated by the [47mmake-event[0m example above to define the desired macro, as follows. (defmacro define-world-length-constant (name) `(make-event (list 'defconst ',name (length (w state))))) Here is a log that may help to explain this macro, assuming it has been defined as displayed just above. ACL2 !>:trans1 (define-world-length-constant *foo*) (MAKE-EVENT (LIST 'DEFCONST '*FOO* (LENGTH (W STATE)))) ACL2 !>(LIST 'DEFCONST '*FOO* (LENGTH (W STATE))) (DEFCONST *FOO* 109707) ACL2 !> ACL2 !>(define-world-length-constant *foo*) Summary Form: ( DEFCONST *FOO* ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Summary Form: ( MAKE-EVENT (LIST ...)) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) *FOO* ACL2 !>*foo* 109707 ACL2 !>:pe *foo* 2:x(DEFINE-WORLD-LENGTH-CONSTANT *FOO*) > (DEFCONST *FOO* 109707) ACL2 !>(length (w state)) 109713 ACL2 !>(define-world-length-constant *bar*) Summary Form: ( DEFCONST *BAR* ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Summary Form: ( MAKE-EVENT (LIST ...)) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) *BAR* ACL2 !>*bar* 109713 ACL2 !>:pe *bar* 3:x(DEFINE-WORLD-LENGTH-CONSTANT *BAR*) > (DEFCONST *BAR* 109713) ACL2 !>(length (w state)) 109719 ACL2 !> The expansion phase can be used for computation that has side effects, generally by modifying state. Here is a modification of the above example that does not change the ACL2 world at all, but instead saves the length of the world into a state global variable (see [assign]). (make-event (er-progn (assign my-world-length (length (w state))) (value '(value-triple nil)))) Notice that this time, the value returned by the expansion phase is not a single value; rather, it is an [error-triple] whose value component is an event form, namely, the event form [47m(value-triple nil)[0m. Evaluation of that event form does not change the ACL2 world (see [value-triple]). Thus, the sole purpose of the [47mmake-event[0m call above is to change the [state] by associating the length of the current logical world with the state global, [47mmy-world-length[0m. After evaluating this form, [47m(@ my-world-length)[0m provides the length of the ACL2 world, as illustrated by the following transcript. ACL2 !>:pbt 0 0:x(EXIT-BOOT-STRAP-MODE) ACL2 !>(length (w state)) 109700 ACL2 !>(make-event (er-progn (assign my-world-length (length (w state))) (value '(value-triple nil)))) Summary Form: ( MAKE-EVENT (ER-PROGN ...)) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) NIL ACL2 !>(length (w state)) 109700 ACL2 !>:pbt 0 0:x(EXIT-BOOT-STRAP-MODE) ACL2 !> When [47mmake-event[0m is invoked by a book, it is expanded during book certification but not, by default, when the book is included. Consider again the example [47m(define-world-length-constant *foo*)[0m given above. If that form is in a book, then the value of [47m*foo*[0m will be the length of the world at the time this form was invoked during book certification, regardless of world length at [47m[include-book][0m time. That is because the expansion, [47m(DEFCONST *FOO* 109700)[0m, is recorded in the book's [certificate] and re-used during a subsequent [47m[include-book][0m. However, the keyword [47m:check-expansion[0m may be given the value [47mt[0m so that the expansion is done even during [47minclude-book[0m, which comes with a check that the result is the same as it was during book certification. This keyword can be useful for side effects. For example, if you insert the following form in a book, then the length of the world will be printed when the form is encountered, whether during [47m[certify-book][0m or during [47m[include-book][0m. (make-event (pprogn (fms "Length of current world: ~x0~|" (list (cons #\0 (length (w state)))) *standard-co* state nil) (value '(value-triple nil))) :check-expansion t) Detailed Documentation Examples: ; Trivial example: evaluate (quote (defun foo (x) x)) to obtain ; (defun foo (x) x), which is then evaluated. (make-event (quote (defun foo (x) x))) ; Evaluate (generate-form state) to obtain (mv nil val state), and ; then evaluate val. (Generate-form is not specified here, but ; imagine for example that it explores the state and then generates ; some desired definition or theorem.) (make-event (generate-form state)) ; As above, but make sure that if this form is in a book, then when ; we include the book, the evaluation of (generate-form state) ; should return the same value as it did when the book was ; certified. (make-event (generate-form state) :CHECK-EXPANSION t) General Form: (make-event form :CHECK-EXPANSION chk :ON-BEHALF-OF obj :EXPANSION? form :SAVE-EVENT-DATA save) where [47mchk[0m is [47mnil[0m (the default), [47mt[0m, or the intended ``expansion result'' from the evaluation of [47mform[0m (as explained below); [47mobj[0m is an arbitrary ACL2 object, used only in reporting errors in expansion, i.e., in the evaluation of form; and [47msave[0m is arbitrary but is considered only as either [47mnil[0m or non-[47mnil[0m. The [47m:EXPANSION?[0m keyword is discussed in the final section, on Advanced Expansion Control. See [make-event-details] for discussion of the [47m:ON-BEHALF-OF[0m and :SAVE-EVENT-DATA keywords. We strongly recommend that you browse some [47m.lisp[0m files in the community books directory [47mbooks/make-event/[0m. You may even find it helpful, in order to understand [47mmake-event[0m, to do so before continuing to read this documentation. You may also find it useful to browse community book [47mbooks/std/testing/eval.lisp[0m, which contains definitions of macros [47mmust-succeed[0m and [47mmust-fail[0m that are useful for testing and are used in many books in the [47mbooks/make-event/[0m directory, especially [47meval-tests.lisp[0m. Another example, [47mbooks/make-event/defrule.lisp[0m, shows how to use macros whose calls expand to [47mmake-event[0m forms, which in turn can generate [events]. For more examples, see file [47mbooks/make-event/Readme.lsp[0m. Other than the examples, the explanations here should suffice for most users. If you want explanations of subtler details, see [make-event-details]. Note that [47mmake-event[0m is generally legal only where an embedded event form is expected: essentially, at the top level of a book or the read-eval-print loop, possibly within surrounding calls of [47mmake-event[0m or of event constructors such as [47m[progn][0m and [47m[encapsulate][0m. For details see the section ``Restriction to Event Contexts'', below. [47mMake-event[0m is related to Lisp macroexpansion in the sense that its argument is evaluated to obtain an expansion result, which is evaluated again. Let us elaborate on each of these notions in turn: ``is evaluated,'' ``expansion result'', and ``evaluated again.'' The final section, on Advanced Expansion Control, will generalize these processes in a way that we ignore for now. ``is evaluated'' --- The argument can be any expression, which is evaluated as would be any expression submitted to ACL2's top level loop. Thus, [47m[state][0m and user-defined [47m[stobj][0ms may appear in the form supplied to [47mmake-event[0m. Henceforth, we will refer to this evaluation as ``expansion.'' Expansion is actually done in a way that restores ACL2's built-in [47m[state][0m global variables, including the logical [world], to their pre-expansion values (with a few exceptions --- see [make-event-details] --- and where we note that changes to user-defined [47m[state][0m global variables (see [assign]) are preserved). So, for example, events might be evaluated during expansion, but they will disappear from the logical [world] after expansion returns its result. Moreover, proofs are enabled by default during expansion (see [ld-skip-proofsp]) if keyword [47m:CHECK-EXPANSION[0m is supplied a non-[47mnil[0m value or a certain attachment is made (see (4) below). ``expansion result'' --- The above expansion may result in an ordinary (non-[47m[state][0m, non-[47m[stobj][0m) value, which we call the ``expansion result.'' Or, expansion may result in a multiple value of the form [47m(mv erp val state)[0m, or, more generally, [47m(mv erp val state stobj-1 ... stobj-k)[0m where each [47mstobj-i[0m is a [stobj]; then the expansion result is [47mval[0m unless [47merp[0m is not [47mnil[0m, in which case there is no expansion result, and the original [47mmake-event[0m evaluates to a soft error. In either case (single or multiple value), either [47mval[0m is an embedded event form (see [embedded-event-form]), or else the original [47mmake-event[0m evaluates to a soft error, printed as described under ``Error Reporting'' below. ([3mTechnical remark[0m: The expansion result described above may be modified for [47m[include-book][0m, [47m[add-include-book-dir][0m, and [47m[add-include-book-dir!][0m, replacing [book-name]s to indicate [full-book-name]s. For further details see comments in source function [47mmake-include-books-absolute[0m. End of technical remark.) ``evaluated again'' --- the expansion result is evaluated in place of the original [47mmake-event[0m. The expansion process can invoke subsidiary calls of [47mmake-event[0m, and the expansion result can (perhaps after macroexpansion) be a call of [47mmake-event[0m. It can be useful to track all these [47mmake-event[0m calls. The [state] global variable [47mmake-event-debug[0m may be set to a non-[47mnil[0m value, for example [47m(assign make-event-debug t)[0m, in order to see a trace of the expansion process, where a level is displayed (as in ``[47m3>[0m'') to indicate the depth of subsidiary expansions. Expansion of a [47mmake-event[0m call will yield an event that replaces the original [47mmake-event[0m call. In particular, if you put a [47mmake-event[0m form in a book, then in essence it is replaced by its expansion result, created during the proof pass of the [47m[certify-book][0m process. We now elaborate on this idea of keeping the original expansion. A [47mmake-event[0m call generates a ``[47mmake-event[0m replacement'' that may be stored by the system. In the simplest case, this replacement is the expansion result. When a book is certified, these replacements are stored in a book's certificate (technically, in the [47m:EXPANSION-ALIST[0m field). Thus, although the book is not textually altered during certification, one may imagine a ``book expansion'' corresponding to the original book, in which events are substituted by replacements that were generated during the proof phase of certification. A subsequent [47m[include-book][0m will then include the book expansion corresponding to the indicated book. When a book is compiled during [47m[certify-book][0m, it is actually the corresponding book expansion, stored as a temporary file, that is compiled instead. That temporary file is deleted after compilation unless one first evaluates the form [47m(assign keep-tmp-files t)[0m. Note however that all of the original forms must still be legal [events]; see [embedded-event-form]. So for example, if the first event in a book is [47m(local (defmacro my-id (x) x))[0m, and is followed by [47m(my-id (make-event ...))[0m, the final ``[47minclude-book[0m'' pass of [47m[certify-book][0m will fail because [47mmy-id[0m is not defined when the [47mmy-id[0m call is encountered. A [47mmake-event[0m replacement might not be the expansion when either of the keyword arguments [47m:CHECK-EXPANSION[0m or [47m:EXPANSION?[0m is supplied. We deal with the latter in the final section, on Advanced Expansion Control. If [47m:CHECK-EXPANSION t[0m is supplied and the expansion is [47mexp[0m, then the replacement is obtained from the original [47mmake-event[0m call, by substituting [47mexp[0m for [47mt[0m as the value of keyword [47m:CHECK-EXPANSION[0m. Such a [47mmake-event[0m call --- during the second pass of an [47m[encapsulate][0m, or during event processing on behalf of [47m[include-book][0m other than when including a book near the end of its certification process --- will do the expansion again and check that the expansion result is equal to the original expansion result, [47mexp[0m. In the unusual case that you know the expected expansion result, [47mres[0m, you can specify [47m:CHECK-EXPANSION res[0m in the first place, so that the check is also done during the initial evaluation of the [47mmake-event[0m form. IMPORTANT BUT OBSCURE DETAIL: That expansion check is only done when processing events, not during a preliminary load of a book's compiled file. The following paragraph elaborates. (Here are details on the point made just above, for those who use the [47m:CHECK-EXPANSION[0m argument to perform side-effects on the [state]. When you include a book, ACL2 generally loads a compiled file before processing the events in the book; see [book-compiled-file]. While it is true that a non-[47mnil[0m [47m:CHECK-EXPANSION[0m argument causes [47m[include-book][0m to perform expansion of the [47mmake-event[0m form during event processing it does [3mnot[0m perform expansion when the compiled file (or expansion file; again, see [book-compiled-file]) is loaded.) ACL2 performs the following space-saving optimization: when the expansion result is a [47m[local][0m event, then the [47mmake-event[0m replacement is [47m(local (value-triple :ELIDED))[0m. The notion of ``expansion'' and ``replacement'' extend to the case that a call of [47mmake-event[0m is found in the course of macroexpansion. The following example illustrates this point. (encapsulate () (defmacro my-mac () '(make-event '(defun foo (x) x))) (my-mac)) :pe :here The above call of [47m[pe][0m shows that the form [47m(my-mac)[0m has a [47mmake-event[0m expansion (and replacement) of [47m(DEFUN FOO (X) X)[0m: (ENCAPSULATE NIL (DEFMACRO MY-MAC NIL '(MAKE-EVENT '(DEFUN FOO (X) X))) (DEFUN FOO (X) X)) Error Reporting Suppose that expansion produces a soft error as described above. That is, suppose that the argument of a [47mmake-event[0m call evaluates to a multiple value [47m(mv erp val state ...)[0m where [47merp[0m is not [47mnil[0m. If [47merp[0m is a string, then that string is printed in the error message. If [47merp[0m is a [47m[cons][0m pair whose [47m[car][0m is a string, then the error prints [47m"~@0"[0m with [47m#\0[0m bound to that [47mcons[0m pair; see [fmt]. Any other non-[47mnil[0m value of [47merp[0m causes a generic error message to be printed. Restriction to Event Contexts A [47mmake-event[0m call must occur either at the top level, or during [47mmake-event[0m expansion, or as an argument of an event constructor. We explain in more detail below. This restriction is imposed to enable ACL2 to track expansions produced by [47mmake-event[0m. The following examples illustrate this restriction. ; Legal: (progn (with-output :on summary (make-event '(defun foo (x) x)))) ; Illegal: (mv-let (erp val state) (make-event '(defun foo (x) x)) (mv erp val state)) More precisely: a [47mmake-event[0m call that is not itself evaluated during [47mmake-event[0m expansion is subject to the following requirement. After macroexpansion has taken place, such a [47mmake-event[0m call must be in an ``event context'', defined recursively as follows. (All but the first two cases below correspond to similar cases for constructing events; see [embedded-event-form].) * A form submitted at the top level, or more generally, supplied to a call of [47m[ld][0m, is in an event context. * A form occurring at the top level of a book is in an event context. * If [47m([0m[47m[local][0m[47m x1)[0m is in an event context, then so is [47mx1[0m. * If [47m([0m[47m[skip-proofs][0m[47m x1)[0m is in an event context, then so is [47mx1[0m. * If [47m([0m[47m[make-event][0m[47m x ...)[0m is in an event context and its expansion [47mx1[0m is an embedded event form, then [47mx1[0m is in an event context. * If [47m([0m[47m[with-output][0m[47m ... x1)[0m, [47m([0m[47m[with-prover-step-limit][0m[47m ... x1 ...)[0m, or [47m([0m[47m[with-prover-time-limit][0m[47m ... x1)[0m is in an event context, then so is [47mx1[0m. * For any call of [47m[progn][0m or [47m[progn!][0m, each of its arguments is in an event context. * For any call of [47m[encapsulate][0m, each of its arguments except the first (the signature list) is in an event context. * If [47m(RECORD-EXPANSION x1 x2)[0m is in an event context, then [47mx1[0m and [47mx2[0m are in event contexts. Note: [47mrecord-expansion[0m is intended for use only by the implementation. Low-level remark, for system implementors. There is the one exception to the above restriction: a single [47m[state-global-let*][0m form immediately under a [47mprogn![0m call. For example: (progn! (state-global-let* <bindings> (make-event ...))) However, the following form may be preferable (see [progn!]): (progn! :STATE-GLOBAL-BINDINGS <bindings> (make-event ...)) Also see [remove-untouchable] for an interesting use of this exception. Avoiding large [47mmake-event[0m forms in [certificate] files The [certificate] file for a book contains expansions of [47mmake-event[0m forms from the book. (Those interested may find details about this in an Implementation Note about ``The book expansion'' in the documentation topic, [make-event-details].) Those expansions can be very large if one is not careful. Consider the difference between the following two events. (make-event `(defconst *foo* ,(length (w state)))) (make-event `(defconst *foo* (length ',(w state)))) The first generates an expansion such as [47m(defconst *foo* 122700)[0m (where the numeric value depends on the [world] in which the [47mmake-event[0m form is evaluated). The second, however, generates an expansion of the form [47m(defconst *foo* (length '<wrld>))[0m, where [47m<wrld[0m is an ACL2 world --- a very large structure. The [47m.cert[0m file for a book containing the second form will therefore contain many megabytes. Moreover, with the second form the length of that world will need to be computed when the book is included (which may be fast, but could be slow for a different such computation). Examples Illustrating How to Access State You can modify the ACL2 [state] by doing your state-changing computation during the expansion phase, before expansion returns the event that is submitted. Let us look at some examples and then consider a restriction for many built-in state globals. First consider the following. Notice that expansion modifies a state global, [47mmy-global[0m, during [47mmake-event[0m expansion (see [assign]); and then, expansion returns a [47m[defun][0m event to be evaluated. (make-event (er-progn (assign my-global (length (w state))) (value '(defun foo (x) (cons x x))))) Then we get: ACL2 !>(@ my-global) 72271 ACL2 !>:pe foo L 1:x(MAKE-EVENT (ER-PROGN # #)) >L (DEFUN FOO (X) (CONS X X)) ACL2 !> Here's a slightly fancier example, where the computation affects the [47m[defun][0m. In a new session, execute: (make-event (er-progn (assign my-global (length (w state))) (value `(defun foo (x) (cons x ,(@ my-global)))))) Then: ACL2 !>(@ my-global) 72271 ACL2 !>:pe foo L 1:x(MAKE-EVENT (ER-PROGN # #)) >L (DEFUN FOO (X) (CONS X 72271)) ACL2 !> Because [47mmake-event[0m creates [event] forms that can go into [books] and [47m[encapsulate][0m events, you can use [47mmake-event[0m forms such as those above to modify the ACL2 [state] using books and [47mencapsulate[0m events. The most common way to do this is for the [47mmake-event[0m expansion to be a trivial event form such as [47m(value-triple nil)[0m, such as the following. (make-event (er-progn (assign my-list-of-10 (make-list 10)) (value '(value-triple nil)))) The desired effect will take place during calls of [47m[certify-book][0m, but it will generally [31;1mnot[0m take place during [47m[include-book][0m on a certified book because the expansion is evaluated (it is stored in the book's [certificate] for this purpose), but the expansion is merely [47m(value-triple nil)[0m. To ensure that the original [47mmake-event[0m call is evaluated even when including the book, use [47m:check-expansion t[0m, for example as follows. (make-event (er-progn (assign my-list-of-10 (make-list 10)) (value '(value-triple nil))) :check-expansion t) Note that ACL2 [table] [events] may avoid the need to use [state] globals. For example, instead of the example above, consider this example in a new session. (make-event (let ((world-len (length (w state)))) `(progn (table my-table :STORED-WORLD-LENGTH ,world-len) (defun foo (x) (cons x ,world-len))))) Then: ACL2 !>(table my-table) ((:STORED-WORLD-LENGTH . 72271)) ACL2 !>:pe foo 1:x(MAKE-EVENT (LET # #)) >L (DEFUN FOO (X) (CONS X 72271)) ACL2 !> Many built-in [state] globals revert after expansion. If your own state global (like [47mmy-global[0m above) can be set during expansion, then the new value will persist. But that persistence will fail for many state globals, specifically, those that are stored in the list, [47m*protected-system-state-globals*[0m. We advise users [31;1mnot[0m to assume that system state modifications, such as the state of guard-checking, will persist after executing a [47mmake-event[0m form; persistence depends on the relevant state globals not being in the list, [47m*protected-system-state-globals*[0m. That advice may suffice for most users. But if you want to understand the point above more deeply, then consider the following example. (make-event (er-progn (set-guard-checking :none) ; sets state global 'guard-checking-on (assign my-global (car 3)) (value (list 'value-triple (@ my-global))))) This [47mmake-event[0m form succeeds and afterwards, the value of [47m(@ my-global)[0m is [47mnil[0m, which of course is the value expected after the call above of [47m[assign][0m. However, the value of [47m(@ guard-checking-on)[0m after executing this [47mmake-event[0m form is [47mt[0m, not [47m:none[0m. That is because the symbol [47mguard-checking-on[0m belongs to the list of symbols stored in the constant, [47m*protected-system-state-globals*[0m, and thus the value of the state global [47mguard-checking-on[0m is reverted to its initial value (which was assume here is the default, [47mt[0m) after the [47mmake-event[0m form completes execution. [31;1mRemarks on [47m*Protected-system-state-globals*[0m[31;1m for advanced users.[0m * The constant [47m*protected-system-state-globals*[0m is defined to include all built-in state globals, [3mexcept[0m for those that the ACL2 implementors have decided can safely retain values set during [47mmake-event[0m expansion. If you find state globals that you would like to be added to this list of exceptions, please contact the ACL2 implementors. Note for example that it would not be safe to allow [47mguard-checking-on[0m as an exception, since ACL2 relies on the persistence of this state global's value after each event (for explanation, see the Essay on Guard Checking in the ACL2 sources). * As noted in a comment in the example above, the macro [47m[set-guard-checking][0m sets the state global, [47m'guard-checking-on[0m. A natural question is how one might know this. For most ACL2 users (one might say, traditional ACL2 users), it should suffice simply not to expect system state modifications (like the state of guard-checking) to persist after executing a [47mmake-event[0m form. For system implementors, one however needs to work with the ACL2 system by looking at the definition of the utility --- in this example, [47mset-guard-checking[0m --- or at the least, get a sense of its expansion by using macroexpansion (for example see [trans1]). Advanced Expansion Control We conclude this [documentation] section by discussing additional control over [47mmake-event[0m expansion. The discussion below is split into the following parts; further discussion follows. The first three parts are illustrated in community book [47mbooks/make-event/make-event-keywords-or-exp.lisp[0m. (1) The value produced by expansion may have the form [47m(:DO-PROOFS exp)[0m, which specifies [47mexp[0m as the expansion result, to be evaluated without skipping proofs even when including a book. (2) The value produced by expansion may have the form [47m(:OR exp-1 ... exp-k)[0m, which specifies that the first form [47mexp-i[0m to evaluate without error is the expansion result. (3) The keyword argument [47m:EXPANSION?[0m can serve to eliminate the storing of [47mmake-event[0m replacements, as described above for the ``book expansion'' of a book. (4) In contexts where proofs are normally skipped (see [ld-skip-proofsp]), the expansion phase normally takes place with proofs skipped unless the [47m:CHECK-EXPANSION[0m keyword is supplied a non-[47mnil[0m value. However, proofs can be made to take place unconditionally during the expansion phase by using an attachment, as discussed below. We now elaborate on each of these. (1) [47m:DO-PROOFS[0m ``call'' produced by expansion. We have discussed the expansion result produced by the expansion phase of evaluating a [47mmake-event[0m call. However, if the expansion phase produces an expression of the form [47m(:DO-PROOFS exp)[0m, then the expansion result is actually [47mexp[0m. The [47m:DO-PROOFS[0m wrapper indicates that even if proofs are currently being skipped (see [ld-skip-proofsp]), then evaluation of [47mexp[0m should take place with proofs not skipped. For example, proofs will be performed when evaluating the [47mmake-event[0m expansion, namely the indicated [47mdefthm[0m event, in the following example. (set-ld-skip-proofsp t state) (make-event '(:DO-PROOFS (defthm app-assoc (equal (append (append x y) z) (append x y z))))) Note that such use of [47m:DO-PROOFS[0m causes proofs to be performed when evaluating the expansion while including an uncertified book. But when including a certified book, then unless [47m:CHECK-EXPANSION[0m is supplied a non-[47mnil[0m value, the [47mmake-event[0m replacement will just be the expansion, which does not include the [47m:DO-PROOFS[0m wrapper and hence will be evaluated with proofs skipped. (2) [47m:OR[0m ``call'' produced by expansion. There may be times where you want to try different expansions. For example, the community book [47mbooks/make-event/proof-by-arith.lisp[0m attempts to admit a given event, which we'll denote [47mEV[0m, by trying events of the following form as [47mBOOK[0m varies over different community books. (encapsulate () (local (include-book BOOK :DIR :SYSTEM)) EV) A naive implementation of this macro would evaluate all such [47m[encapsulate][0m events until one succeeds, and then return that successful event as the expansion. Then that event would need to be evaluated again! With some hacking one could avoid that re-evaluation by using [47m[skip-proofs][0m, but that won't work if you are trying to create a certified book without skipped proofs. Instead, the implementation creates an expansion of the form [47m(:OR ev-1 ev-2 ... ev-k)[0m, where the list [47m(ev-1 ev-2 ... ev-k)[0m enumerates the generated encapsulate events. In general, for this ``disjunctive case'' of a result from expansion, each [47mev-i[0m is evaluated in sequence, and the first that succeeds without error is considered to be the expansion result --- and a repeat evaluation is avoided. If evaluation of each [47mev-i[0m results in an error, then so does the [47mmake-event[0m call. This special use of [47m:OR[0m in a value produced by expansion does not permit nesting such as [47m(:OR ev-1 (:OR ev-2 ev-3))[0m. That is, when an expansion result is [47m(:OR ev-1 ev-2 ... ev-k)[0m, none of the [47mev-i[0m may be of the form [47m(:OR ...)[0m. Note that it is allowed for [47mev-i[0m to be a call of [47mmake-event[0m, even one involving this special use of [47m:OR[0m. If [47mev-i[0m is [47m(:DO-PROOFS ev-i')[0m, then [47mev-i'[0m is considered to be the expansion in place of [47mev-i[0m. (3) The [47m:EXPANSION?[0m keyword argument. If keyword argument [47m:EXPANSION?[0m has a non[47mnil[0m value, then the [47m:CHECK-EXPANSION[0m keyword must be omitted or have value [47mnil[0m or [47mt[0m, hence not a cons pair. The idea of the [47m:EXPANSION?[0m keyword is to give you a way to avoid storing expansion results in a book's [certificate]. Roughly speaking, when the expansion result matches the value of [47m:EXPANSION?[0m, then no expansion result is stored for the event by book certification; then when the book is later included, the value of [47m:EXPANSION?[0m is used as the expansion, thus bypassing the expansion phase. One could say that the event is its own make-event replacement, but it is more accurate to say that there is no make-event replacement at all, since nothing is stored in the certificate for this event. Below, we elaborate on make-event replacements when [47m:EXPANSION?[0m is used and also discuss other properties of this keyword. We modify the notion of ``expansion result'' for [47mmake-event[0m forms to comprehend the use of the [47m:EXPANSION?[0m keyword. For that purpose, let's consider a call of [47mmake-event[0m to be ``reducible'' if it has an [47m:EXPANSION?[0m keyword with non-[47mnil[0m value, [47mexp[0m, and its [47m:CHECK-EXPANSION[0m keyword is missing or has value [47mnil[0m, in which case the ``reduction'' of this [47mmake-event[0m call is defined to be [47mexp[0m. The expansion result as originally defined is modified by the following ``recursive reduction'' process: recur through the original expansion, passing through calls of [47m[local][0m, [47m[skip-proofs][0m, [47m[with-output][0m, [47m[with-prover-step-limit][0m, and [47m[with-prover-time-limit][0m, and replacing (recursively) any reducible call of [47mmake-event[0m by its reduction. Furthermore, we refer to two forms as ``reduction equivalent'' if their recursive reductions are equal. Note that the recursive reduction process does not pass through [47m[progn][0m or [47m[encapsulate][0m, but that process is applied to the computation of expansions for their subsidiary [47m[make-event][0m calls. To explain further the effect of [47m:EXPANSION? exp[0m, we split into the following two cases. [31;1mCase 1[0m: Evaluation is not taking place when including a book or evaluating the second pass of an [47m[encapsulate][0m event; more precisely, the value of [47m(ld-skip-proofsp state)[0m is not the symbol [47mINCLUDE-BOOK[0m. There are two subcases. * Case 1a: The expansion result is not reduction-equivalent to [47mexp[0m. Then the [47mmake-event[0m call is processed as though the [47m:EXPANSION?[0m keyword had been omitted. * Case 2a: The expansion result is reduction-equivalent to [47mexp[0m. Then there is no [47mmake-event[0m replacement for this call of [47mmake-event[0m; no replacement will be put into the [certificate] file for a book containing this [47mmake-event[0m call. When that book is subsequently included, the original form will be evaluated in the manner described in the next case. [31;1mCase 2[0m: Evaluation is taking place when including a book or evaluating the second pass of an [47m[encapsulate][0m event; more precisely, the value of [47m(ld-skip-proofsp state)[0m is the symbol [47mINCLUDE-BOOK[0m. Then the expansion is [47mexp[0m. The expansion phase is skipped unless [47m:CHECK-EXPANSION[0m is [47mt[0m. The [47m:EXPANSION?[0m keyword can be particularly useful in concert with the disjunctive (``[47m:OR[0m'') case (2) discussed above. Suppose that expansion produces a value as discussed in (2) above, [47m(:OR exp-1 ... exp-k)[0m. If one of these expressions [47mexp-i[0m is more likely than the others to be the expansion, then you may wish to specify [47m:EXPANSION? exp-i[0m, as this will avoid storing a [47mmake-event[0m replacement in that common case. This could be useful if the expressions are large, to avoid enlarging the [certificate] file for a book containing the [47mmake-event[0m call. It is legal to specify both [47m:EXPANSION? exp[0m and [47m:CHECK-EXPANSION t[0m. When either [47m(ld-skip-proofsp state)[0m is the symbol [47mINCLUDE-BOOK[0m, or evaluation is taking place in raw Lisp, then this combination is treated the same as if [47m:EXPANSION?[0m is omitted and the value of [47m:CHECK-EXPANSION[0m is [47mexp[0m. Otherwise, this combination is treated the same as [47m:CHECK-EXPANSION t[0m, modified to accommodate the effect of [47m:EXPANSION?[0m as discussed above: if the expansion is indeed the value of [47m:EXPANSION?[0m, then no [47mmake-event[0m replacement is generated. (4) Unconditionally enabling proofs during the expansion phase using an attachment. Proofs are normally skipped during the expansion phase unless the [47m:CHECK-EXPANSION[0m keyword is supplied a non-[47mnil[0m value. To cause proofs to take place unconditionally during the expansion phase, evaluate one of the following two forms, as explained below. (defattach (always-do-proofs-during-make-event-expansion constant-t-function-arity-0) :system-ok t) (defattach (always-do-proofs-during-make-event-expansion constant-all-function-arity-0) :system-ok t) The first of these is probably preferred in most cases, since it does not have any effect while evaluating an [47m[include-book][0m form (more precisely, when [47m(ld-skip-proofsp state)[0m is [47m'include-book[0m). The second removes that restriction. To restore the default behavior, evaluate the following. (defattach (always-do-proofs-during-make-event-expansion constant-nil-function-arity-0) :system-ok t) (If you would like an explanation of [47mdefattach[0m in general, see [defattach].) Subtopics [Make-event-details] Details on [47m[make-event][0m expansion [Make-event-example-1] An example use of [47m[make-event][0m [Make-event-example-2] An example use of [47m[make-event][0m [Make-event-example-3] Using [47m[make-event][0m to define [47m[thm][0m") (make-event-details (make-event) "Details on [47m[make-event][0m expansion The normal user of [47mmake-event[0m can probably ignore this section, but we include it for completeness. We assume that the reader has read and understood the basic documentation for [47mmake-event[0m (see [make-event]), but we begin below with a summary of expansion. Introduction Here is a summary of how we handle expansion involving [47mmake-event[0m forms. [47m(make-event form :check-expansion nil)[0m This shows the [47m:check-expansion[0m default of [47mnil[0m, and is typical user input. We compute the expansion [47mexp[0m of [47mform[0m, which is the expansion of the original [47mmake-event[0m expression and is evaluated in place of that expression. [47m(make-event form :check-expansion t)[0m The user presumably wants it checked that the expansion doesn't change in the future, in particular during [47m[include-book][0m. If the expansion of [47mform[0m is [47mexp[0m, then we will evaluate [47mexp[0m to obtain the value as before, but this time we record that the expansion of the original [47mmake-event[0m expression is [47m(make-event form :check-expansion exp)[0m rather than simply [47mexp[0m. [47m(make-event form :check-expansion exp) ; exp a cons[0m This is generated for the case that [47m:check-expansion[0m is [47mt[0m, as explained above. Evaluation is handled as described in that above case, except here we check that the expansion result is the given [47mexp[0m. (Actually, the user is also allowed to supply such a form.) The original [47mmake-event[0m expression does not undergo any expansion (intuitively, it expands to itself). Now let us take a brief look at how we expand [47m[progn][0m and [47m[encapsulate][0m forms. More details are found further below (see ``Detailed semantics''). [47m(progn ... (make-event form ...) ...)[0m The expansion is obtained, roughly speaking, by replacing the [47mmake-event[0m form by its expansion, [47mexp[0m, except that if [47m:check-expansion exp[0m is supplied explicitly, then no such replacement takes place. Expansion for [47m(encapsulate ... (make-event form ...) ...)[0m is similar to the case for [47mprogn[0m, except that if the expansion of [47mform[0m is [47mexp[0m, then what is stored is [47m(record-expansion (make-event form ...) exp)[0m. Also as for [47mprogn[0m, the exception is that when [47m:check-expansion exp[0m is supplied explicitly, no such replacement takes place. Here, [47mrecord-expansion[0m is a macro that simply returns its second argument, but is used for checking redundancy of [47mencapsulate[0m forms (see [redundant-encapsulate]). Certain ``wrappers'' around a [47mmake-event[0m are restored as the last part of the expansion process, in particular for [47mmake-event[0m calls that are inside calls of [47m[encapsulate][0m or [47m[progn][0m, as well as in events processed during a book's certification, including [portcullis] commands from the certification [world]. For example, if you evaluate a form [47m(local (with-prover-step-limit 100 (make-event ...)))[0m where the [47mmake-event[0m call has expansion [47m<exp>[0m, and then you certify a book, the book's [certificate] file will include among its portcullis commands the form [47m(local (with-prover-step-limit 100 <exp>))[0m. Macroexpansion is performed to determine the wrappers. The wrappers thus restored are as follows. local skip-proofs with-cbd with-guard-checking-event with-output with-prover-step-limit with-prover-time-limit The discussion below references this process as the final expansion being ``rebuilt from'' the form. Detailed semantics In our explanation of the semantics of [47mmake-event[0m, we assume familiarity with the notion of ``embedded event form'' (see [embedded-event-form]). Let's say that the ``actual embedded event form'' corresponding to a given form is the underlying call of an ACL2 event: that is, [47m[local][0ms are dropped when [47mld-skip-proofsp[0m is [47m'include-book[0m, and macros are expanded away, thus leaving us with a [47m[progn][0m, a [47m[make-event][0m, or an event form (possibly [47m[encapsulate][0m), any of which might have surrounding [47m[local][0m, [47m[skip-proofs][0m, or [47m[with-output][0m calls. Thus, such an actual embedded event form can be viewed as having the form [47m(rebuild-expansion wrappers base-form)[0m where [47mbase-form[0m is a [47mprogn[0m, a [47mmake-event[0m, or an event form (possibly [47mencapsulate[0m), and [47mwrappers[0m are (as in ACL2 source function [47mdestructure-expansion[0m) the result of successively removing the event form from the result of macroexpansion, leaving a sequence of [47m(local)[0m, [47m(skip-proofs)[0m, and [47m(with-output ...)[0m forms. In this case we say that the form ``destructures into'' the indicated [47mwrappers[0m and [47mbase-form[0m, and that it can be ``rebuilt from'' those [47mwrappers[0m and [47mbase-form[0m. Elsewhere we define the notion of the ``expansion result'' from an evaluation (see [make-event]), and we mention that when expansion concludes, the ACL2 logical [world] and most of the [47mstate[0m are restored to their pre-expansion values. Specifically, after evaluation of the argument of [47mmake-event[0m (even if it is aborted), the ACL2 logical world is restored to its pre-evaluation value, as are all state global variables in the list [47m*protected-system-state-globals*[0m. Thus, assignments to user-defined state globals (see [assign]) do persist after expansion, since they are not in that list. We recursively define the combination of evaluation and expansion of an embedded event form as shown below. We also simultaneously define the notion of ``expansion takes place,'' which is assumed to propagate upward (in a sense that will be obvious), such that if no expansion takes place, then the expansion of the given form is considered to be itself. It is useful to keep in mind a goal that we will consider later: Every [47mmake-event[0m subterm of an expansion result has a [47m:check-expansion[0m field that is a [47m[consp][0m, where for this purpose [47mmake-event[0m is viewed as a macro that returns its [47m:check-expansion[0m field. If the given form is not an embedded event form, then simply cause a soft error, [47m(mv erp val state)[0m where [47merp[0m is not [47mnil[0m. Otherwise: If the evaluation of the given form does not take place (presumably because [47m[local][0m events are being skipped), then no expansion takes place. Otherwise: Let [47mx[0m be the actual embedded event form corresponding to the given form, which destructures into wrappers [47mW[0m and base-form [47mB[0m. Then the original form is evaluated by evaluating [47mx[0m, and its expansion is as follows. If [47mB[0m is [47m(make-event form :check-expansion val)[0m, then expansion takes place if and only if [47mval[0m is not a [47mconsp[0m and no error occurs, as now described. Let [47mR[0m be the expansion result from protected evaluation of [47mform[0m, if there is no error. [47mR[0m must be an embedded event form, or it is an error. Then evaluate/expand [47mR[0m, where if [47mval[0m is not [47mnil[0m then state global [47m'ld-skip-proofsp[0m is initialized to [47mnil[0m. (This initialization is important so that subsequent expansions are checked in a corresponding environment, i.e., where proofs are turned on in both the original and subsequent environments.) It is an error if this evaluation causes an error. Otherwise, the evaluation yields a value, which is the result of evaluation of the original [47mmake-event[0m expression, as well as an expansion, [47mE_R[0m. Let [47mE[0m be rebuilt from [47mW[0m and [47mE_R[0m. The expansion of the original form is [47mE[0m if [47mval[0m is [47mnil[0m, and otherwise is the result of replacing the original form's [47m:check-expansion[0m field with [47mE[0m, with the added requirement that if [47mval[0m is not [47mt[0m (thus, a [47mconsp[0m) then [47mE[0m must equal [47mval[0m or else we cause an error. If [47mB[0m is [47m(progn form1 form2 ...)[0m (and similarly for [47m[progn!][0m), and at least one [47mformi[0m has an expansion, then the expansion of the original form is obtained by replacing each [47mformi[0m by its expansion and then rebuilding the entire [47mprogn[0m call from [47mB[0m. If [47mB[0m is [47m(encapsulate sigs form1 form2 ...)[0m, then after evaluating [47mB[0m, the expansion of the original form is the result of rebuilding from [47mB[0m, with wrappers [47mW[0m, after replacing each [47mformi[0m in [47mB[0m for which expansion takes place by [47m(record-expansion formi formi')[0m, where [47mformi'[0m is the expansion of [47mformi[0m. Note that these expansions are determined as the [47mformi[0m are evaluated in sequence (where in the case of [47mencapsulate[0m, this determination occurs only during the first pass). Except, if no expansion takes place for any [47mformi[0m, then the expansion of the original form is itself. Otherwise, the expansion of the original form is itself. (Optional Implementation Notes. The latest expansion of a [47m[make-event][0m, [47m[progn][0m, [47m[progn!][0m, or [47m[encapsulate][0m is temporarily stored in state global [47m'last-make-event-expansion[0m, except that if no expansion has taken place for that form then [47m'last-make-event-expansion[0m has value [47mnil[0m. Expansions ultimately show up in the world's [47m[command][0m tuples; for example, immediately after processing a command its expansion is [47m(access-command-tuple-last-make-event-expansion (cddr (car (w state))))[0m. Top-level expansions do not include rebuilding of wrappers, although such wrappers are restored when constructing [portcullis] commands as discussed above. End of Implementation Notes.) Similarly to the [47m[progn][0m and [47m[encapsulate][0m cases above, book certification causes a book to be replaced by its so-called ``book expansion,'' where each event [47mev[0m for which expansion took place during the proof pass of certification is replaced by its expansion, but with certain [47m[local][0m events elided. Optional Implementation Note. The book expansion is actually implemented by way of the [47m:expansion-alist[0m field of its [certificate], which associates 0-based positions of top-level forms in the book (not including the initial [47m[in-package][0m form) with their expansions. Thus, the book's source file is not overwritten; rather, the certificate's expansion-alist is applied when the book is included or compiled. End of Implementation Note. It is straightforward by computational induction to see that for any expansion of an embedded event form, every [47mmake-event[0m sub-event has a [47m[consp][0m [47m:check-expansion[0m field. Here, by ``sub-event'' we mean to expand macros; and we also mean to traverse [47mprogn[0m and [47mencapsulate[0m forms as well as [47m:check-expansion[0m fields of [47mmake-event[0m forms. Thus, we will only see [47mmake-event[0m forms with [47mconsp[0m [47m:check-expansion[0m fields in the course of [47minclude-book[0m forms, the second pass of [47mencapsulate[0m forms, and raw Lisp. This fact guarantees that an event form will always be treated as its original expansion. Notes on ttags See [defttag] for documentation of the notion of ``trust tag'' (``ttag''). We note here that even if an event [47m(defttag tag-name)[0m for non-[47mnil[0m [47mtag-name[0m is admitted only during the expansion phase of a [47m[make-event][0m form, then such expansion will nevertheless still cause [47mtag-name[0m to be recorded in the logical [world] (assuming that the [47mmake-event[0m form is admitted). So in order to certify such a book, a suitable [47m:ttags[0m argument must be supplied; see [certify-book]. ACL2 does provide a way to avoid the need for [47m:ttags[0m arguments in such cases. The idea is to certify a book twice, where the results of [47mmake-event[0m expansion are saved from the first call of [47m[certify-book][0m and provided to the second call. See [set-write-ACL2x]. Finally, we discuss a very unusual case where certification does not involve trust tags but a subsequent [47m[include-book][0m does involve trust tags: a [47mmake-event[0m call specifying [47m:check-expansion t[0m, whose expansion generates a [47m[defttag][0m event during [47m[include-book][0m but not [47m[certify-book][0m. Consider the following book. (in-package "ACL2") (make-event (er-progn (if (@ skip-notify-on-defttag) ; non-nil when including a certified book (pprogn (fms "Value of (@ skip-notify-on-defttag): ~x0~|" (list (cons #0 (@ skip-notify-on-defttag))) *standard-co* state nil) (encapsulate () (defttag :foo) (value-triple "Imagine something bad here!"))) (value nil)) (value '(value-triple :some-value))) :check-expansion t) This book certifies successfully without the need for a [47m:ttags[0m argument for [47m[certify-book][0m. Indeed, the above book's [certificate] does not specify [47m:foo[0m as a trust tag associated with the book, because no [47mdefttag[0m event was executed during book certification. Unfortunately, if we try to include this book without specifying a value of [47m:ttags[0m that allows [47m:foo[0m, book inclusion will cause executing of the above [47m[defttag][0m. If that inclusion happens in the context of certifying some superior book and the appropriate [47m:ttags[0m arguments have not been provided, that certification will fail. Expansion errors and the [47m:ON-BEHALF-OF[0m keyword argument Consider the case that expansion returns an [error-triple] [47m(mv erp val state)[0m, where [47merp[0m is not [47mnil[0m. Then [47mmake-event[0m may conclude with an error message, as follows. * If keyword [47m:ON-BEHALF-OF[0m has value [47m:quiet![0m then there is no such concluding error message. * Otherwise, if [47merp[0m is a string, then the concluding error message is produced by printing [47merp[0m with the call [47m(er soft ctx erp)[0m, where [47mctx[0m is the context (see [ctx]). * Otherwise, if [47merp[0m is a message (see [msg]), then the concluding error message is produced by the call [47m(er soft ctx "~@0" erp)[0m, where [47mctx[0m is the context (see [ctx]). * Otherwise, if keyword [47m:ON-BEHALF-OF[0m has value [47m:quiet[0m then there is no concluding error message. * Otherwise, if keyword [47m:ON-BEHALF-OF[0m is not supplied or has value [47mnil[0m --- so we are now in the typical case --- then the concluding error message is ``Error in MAKE-EVENT from expansion of:'' followed by the form. * Otherwise, keyword [47m:ON-BEHALF-OF[0m has a value [47mx[0m other than [47m:quiet![0m, [47m:quiet[0m, or [47mnil[0m, in which case the concluding error message is as just above, except that after ``Error in MAKE-EVENT'' is stated ``on behalf of'' followed by [47mx[0m. Note that errors generated during expansion are not affected by the cases above; those only control the concluding error message, if any. The [47m:save-event-data[0m keyword argument See [get-event-data] for relevant background on data stored for each event. The association list stored in [47mlast-event-data[0m is normally replaced every time an event concludes (at the summary phase), and that holds for calls of [47mmake-event[0m. But there is the following exception: when [47mmake-event[0m is called with a non-[47mnil[0m value for keyword [47m:save-event-data[0m, then that association list persists from the expansion phase. This is how the [47m[thm][0m macro is able to populate the [47mlast-event-data[0m association list without having that list be smashed when the surrounding [47mmake-event[0m (used for implementing [47mthm[0m) concludes.") (make-event-example-1 (make-event) "An example use of [47m[make-event][0m Here, we develop a reasonably self-contained example that illustrates how to use [47mmake-event[0m to develop tools, by solving a challenge posed by Alessandro Coglio. For another such example, see [make-event-example-2]. The challenge is to develop a programmatic method for solving the following sort of problem. 1. Create a [47m[defun][0m form. 2. Submit it to ACL2, obtaining a new ACL2 [state] whose [world] includes the function just submitted. 3. Access various elements of this function (e.g., unnormalized body). 4. Create and return a new [47mdefun[0m that's based on elements of the previous one. 5. Submit this new defun via a [47m[make-event][0m, but in a state that does not include the previous [47mdefun[0m. We illustrate how to do this sort of thing by specifying the ``new [47mdefun[0m that's based on elements of the previous one'' to be as follows: add the formal, [47my[0m, and modify the body so that [47my[0m is consed onto the old body. Of course, this is a trivial example that could be done without [47mmake-event[0m; but we solve it in a way that shows how to solve any such problem. For simplicity, let's not worry about the case that [47my[0m is already a formal of the existing [47mdefun[0m. Here are the main steps. * (a) Submit the [47mdefun[0m. * (b) Gather information from the resulting world. In this case, we access the formals and body of the definition. * (c) Create the desired event. The following code does those three things, as explained in comments below, which include references to the three steps above. (er-progn ; Each of the two forms below returns an error triple (see :DOC ; error-triple), so we can evaluate both by using er-progn, which ; returns the last (second) error triple. (defun foo (x) (cons x x)) ; (a) (let ((formals (formals 'foo (w state))) ; (b) (body (body 'foo nil (w state)))) (value `(defun foo ,(cons 'y formals) ; (c) (cons y ,body))))) So far so good: we have computed an error triple [47m(mv nil val state)[0m whose value component, [47mval[0m, is the desired [47mdefun[0m form. However, that leaves us in a world that includes the first [47mdefun[0m form. For a solution to the original challenge (for our specific case), that must not be the case, and moreover the second [47mdefun[0m form should be included in the current world. Fortunately, [47m[make-event][0m is perfectly suited to do both of these things. Consider the following form, which simply wraps [47mmake-event[0m around the code displayed just above. (make-event (er-progn (defun foo (x) (cons x x)) (let ((formals (formals 'foo (w state))) (body (body 'foo nil (w state)))) (value `(defun foo ,(cons 'y formals) (cons y ,body)))))) The expansion phase (see [make-event]) computes the new [47mdefun[0m form --- the one with the extra formal and modified body --- and then that new [47mdefun[0m form is evaluated in the original world, which does not include the first [47mdefun[0m form. We complete the job by making a programmatic solution, with a macro that expands to such a [47mmake-event[0m form. We make it nice by inhibiting all output except error output. (defmacro cons-y-onto-body (def new-name) `(make-event (with-output! :off :all :on error (er-progn ,def (let* ((name ',(cadr def)) (new-name ',new-name) (formals (formals name (w state))) (body (body name nil (w state)))) (value (list 'defun new-name (cons 'y formals) (list 'cons 'y body)))))) :on-behalf-of :quiet!)) This could be improved by doing some error checking, but we leave that as an exercise. Below is a log, with comments added, that shows uses of the macro above. ; First we call the macro successfully. Notice that although we inhibited ; output during the expansion phase (using with-output!), below we see output ; from the resulting new defun event. ACL2 !>(cons-y-onto-body (defun f (x) x) new-f) Since NEW-F is non-recursive, its admission is trivial. We observe that the type of NEW-F is described by the theorem (CONSP (NEW-F Y X)). We used primitive type reasoning. Summary Form: ( DEFUN NEW-F ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) Summary Form: ( MAKE-EVENT (WITH-OUTPUT! :OFF ...) ...) Rules: NIL Time: 0.03 seconds (prove: 0.00, print: 0.00, other: 0.03) NEW-F ACL2 !>:pe new-f ; Check that the new definition was indeed submitted. L 2:x(CONS-Y-ONTO-BODY (DEFUN F # ...) NEW-F) >L (DEFUN NEW-F (Y X) (CONS Y X)) ACL2 !>:pe f ; Check that the old definition was NOT submitted. ACL2 Error in :PE: The object F is not a logical name. See :DOC logical- name. ; The defun below is ill-formed, so we get an error when it is submitted, ; during the expansion phase. Our use of with-output! allowed error messages, ; so we see the error message in this case. ACL2 !>(cons-y-onto-body (defun g (x) (+ y y)) new-g) ACL2 Error in ( DEFUN G ...): The body of G contains a free occurrence of the variable symbol Y. Summary Form: ( MAKE-EVENT (WITH-OUTPUT! :OFF ...) ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Error in ( MAKE-EVENT (WITH-OUTPUT! :OFF ...) ...): See :DOC failure. ******** FAILED ******** ACL2 !>") (make-event-example-2 (make-event) "An example use of [47m[make-event][0m Here, we develop a reasonably self-contained example that illustrates how to use [47mmake-event[0m to develop tools. For another such example, see [make-event-example-1]. We thank Yan Peng for putting forward this problem. We begin by discussing prerequisites for this presentation. Next, we present the challenge problem, followed by code that solves the problem together with an example that illustrates its use. Finally, we start from the beginning and show how to develop the solution step-by-step. Prerequisites We assume some general ACL2 and Common Lisp background, including familiarity with [macros] and backquote. But we do some programming below that goes beyond that general background in our use of the ACL2 [state]. See [programming-with-state] for relevant discussion, including state global variables, [47m[f-get-global][0m, [47m[f-put-global][0m, [error-triple]s and their construction using [47mvalue[0m, [47m[value-triple][0m, and [47m[pprogn][0m. We also assume familiarity with both [47m[progn][0m and the notion of legal event form; see [embedded-event-form]. If you are not familiar with these notions, then the discussion below might still make some sense, but you might need to read about these notions in order to complete your understanding. Next, we present the challenge problem that we will solve below. Challenge problem Define a utility that evaluates a given sequence of [events], even continuing past errors, which stores the list of event forms that caused errors. Let us call this utility [47mprogn+[0m, since it can be viewed as an enhancement of [47m[progn][0m. So a successful solution should allow us to evaluate the following form to define function symbols [47mf1[0m, [47mf2[0m, and [47mf3[0m, as well as the event [47mgood-thm[0m, and also store the events for [47mbad-thm[0m and [47mbad-fn[0m. (progn+ (defun f1 (x) x) (defthm good-thm (equal 1 1) :rule-classes nil) (value-triple (cw "@@HI~%")) (defthm bad-thm (equal x y) :rule-classes nil) ; error! (defun f2 (x) x) (defun bad-fn (x) y) ; error! (defun f3 (x) x) ) We next present a definition of [47mprogn+[0m, together with output from the example displayed above. After that we will start from the beginning and describe how one might develop [47mprogn+[0m from scratch. The completed code and a test (defmacro save-progn+-error (x) `(make-event (pprogn (f-put-global 'progn+-errors (cons ,x (f-get-global 'progn+-errors state)) state) (value '(value-triple nil))))) (defun progn+-fn (lst) (declare (xargs :guard (true-listp lst) :mode :program)) (cond ((endp lst) nil) (t (cons `(make-event '(:or ,(car lst) (save-progn+-error ',(car lst)))) (progn+-fn (cdr lst)))))) (defmacro progn+ (&rest lst) (declare (xargs :guard (and (true-listp lst) lst))) `(progn (make-event (pprogn (f-put-global 'progn+-errors nil state) (value '(value-triple nil)))) ,@(progn+-fn lst))) ; Example: (progn+ (defun f1 (x) x) (defthm good-thm (equal 1 1) :rule-classes nil) (value-triple (cw "@@HI~%")) (defthm bad-thm (equal x y) :rule-classes nil) (defun f2 (x) x) (defun bad-fn (x) y) (defun f3 (x) x) ) After running the example (which is the final form above), we expect the resulting logical [world] to contain definitions of function symbols [47mf1[0m, [47mf2[0m, and [47mf3[0m, as well as the event [47mgood-thm[0m, but that no events would be stored for [47mbad-thm[0m or [47mbad-fn[0m. Moreover, we expect that a state global variable holds the event forms for [47mbad-thm[0m and [47mbad-fn[0m. Let us check that all of these expectations are met. ACL2 !>:pe f1 4:x(PROGN+ (DEFUN F1 # ...) (DEFTHM GOOD-THM # ...) ...) >L (DEFUN F1 (X) X) ACL2 !>:pe f2 4:x(PROGN+ (DEFUN F1 # ...) (DEFTHM GOOD-THM # ...) ...) >L (DEFUN F2 (X) X) ACL2 !>:pe f3 4:x(PROGN+ (DEFUN F1 # ...) (DEFTHM GOOD-THM # ...) ...) >L (DEFUN F3 (X) X) ACL2 !>(@ progn+-errors) ; same as (f-get-global 'progn+-errors state) ((DEFUN BAD-FN (X) Y) (DEFTHM BAD-THM (EQUAL X Y) :RULE-CLASSES NIL)) ACL2 !> Development of the solution We now start from the beginning. Recall that [47m[progn][0m does almost what we ask [47mprogn+[0m to do, except that [47m[progn][0m stops at the first error. So our approach will be to define a macro that is much like [47mprogn[0m, except that each event is modified as follows: if evaluation fails for an event, then that event is pushed onto the value of a specific state global (see [programming-with-state]), [47mprogn+-errors[0m. Moreover, since [47m[progn][0m is applied only to legal event forms (see [embedded-event-form]), we need this modification to be a legal event form, too. Fortunately, a call of [47m[make-event][0m is a legal event form. So our plan is for [47m(progn+ ... <event> ...)[0m to expand to a call [47m(progn ... (make-event ...) ...)[0m so that the indicated [47mmake-event[0m call attempts to evaluate [47m<event>[0m, and if that attempt fails, then [47m<event>[0m it is pushed onto [47mprogn+-errors[0m. Thus, we begin with a simple piece of the task, by showing how to create an event that will push a specific form, [47m(defthm bad-thm (equal x y) :rule-classes nil)[0m, onto [47mprogn+-errors[0m. (make-event (pprogn (f-put-global 'progn+-errors (cons '(defthm bad-thm (equal x y) :rule-classes nil) (f-get-global 'progn+-errors state)) state) (value '(value-triple nil)))) It might seem more natural to write [47m(f-put-global ...)[0m, instead of the more complex [47m(pprogn (f-put-global ...) (value '(value-triple nil)))[0m. However, the argument to [47mmake-event[0m must evaluate to either: (1) a legal event form; or (2) an [error-triple], [47m(mv nil x state)[0m, where [47mx[0m is a legal event form. Since the [47mf-put-global[0m call modifies state, (1) is not an option; so we choose (2). Since the role of [47mx[0m is only to provide an event form, we choose [47mx[0m to be the trivial event form [47m(value-triple nil)[0m. We follow good programming practice by wrapping the functionality displayed above into a concise utility, as follows. (defmacro save-progn+-error (x) ; Push x (which is evaluated) onto the value of state global 'progn+-errors. `(make-event (pprogn (f-put-global 'progn+-errors (cons ,x (f-get-global 'progn+-errors state)) state) (value '(value-triple nil))))) Before we write [47mprogn+[0m, it helps to approximate its expansion in the specific ``Example'' displayed above. We know in advance which two forms will fail, so we `cheat' by using [47mprogn[0m but with those two forms replaced by calls to [47msave-progn+-error[0m. (f-put-global 'progn+-errors nil state) (progn (defun f1 (x) x) (defthm good-thm (equal 1 1) :rule-classes nil) (value-triple (cw "@@HI~%")) (save-progn+-error '(defthm bad-thm (equal x y) :rule-classes nil)) (defun f2 (x) x) (save-progn+-error '(defun bad-fn (x) y)) (defun f3 (x) x) ) Our next task is to find a way to tell ACL2 that it should run a given event, and if that event fails it should save it using [47msave-progn+-error[0m. Fortunately, the [47m:OR[0m keyword of [47m[make-event][0m is perfect for this task. Consider the following two examples. (make-event '(:or (defun f2 (x) x) (save-progn+-error '(defun f2 (x) x)))) (make-event '(:or (defun bad-fn (x) y) (save-progn+-error '(defun bad-fn (x) y)))) In the first example, [47mmake-event[0m invokes the given call of [47m[defun][0m, which runs without error; and [47mmake-event[0m then exits without error. In the second example, [47mmake-event[0m invokes the given call of [47mdefun[0m, which causes an error; so then [47mmake-event[0m evaluates the second argument of the [47m:OR[0m, to invoke [47msave-progn+-error[0m on that same [47mdefun[0m call. Since that call of [47msave-progn+-error[0m evaluates without error (because it expands to [47m(value-triple nil)[0m), the [47mmake-event[0m call exits without error. See [make-event] for more information about the [47m:OR[0m keyword. We can now define [47mprogn+[0m to be the result of modifying each of its forms as in the two examples displayed just above. First we write a function that transforms a list by applying that modification to each of its members. (defun progn+-fn (lst) (declare (xargs :guard (true-listp lst) :mode :program)) (cond ((endp lst) nil) (t (cons `(make-event '(:or ,(car lst) (save-progn+-error ',(car lst)))) (progn+-fn (cdr lst)))))) We complete our definition of [47mprogn+[0m, by generating a [47mprogn[0m call with the desired modification of each form in the list, using [47mprogn+-fn[0m --- but preceded by yet another [47mmake-event[0m call, this one for initializing our state global to [47mnil[0m. (defmacro progn+ (&rest lst) (declare (xargs :guard (and (true-listp lst) lst))) `(progn (make-event (pprogn (f-put-global 'progn+-errors nil state) (value '(value-triple nil)))) ,@(progn+-fn lst))) [31;1mExercise[0m: Modify this tool so that instead of merely updating a state global, it prints the failed events at the end of execution; and moreover, it prints them in their original order. See [make-event-example-2-exercise] for a solution. Subtopics [Make-event-example-2-exercise] Solution to an exercise from [47m[make-event-example-2][0m") (make-event-example-2-exercise (make-event-example-2) "Solution to an exercise from [47m[make-event-example-2][0m See [make-event-example-2] for a worked example using [47m[make-event][0m, concluding with an exercise. Here we present a solution to that exercise. It assumes that we have evaluated the definitions of [47msave-progn+-error[0m, [47mprogn+-fn[0m, and [47mprogn+[0m from [make-event-example-2]. (defmacro progn+-errors (&rest lst) (declare (xargs :guard (and (true-listp lst) lst))) `(progn (progn+ ,@lst) (make-event (list 'value-triple (list 'quote (reverse (f-get-global 'progn+-errors state)))))))") (make-event-example-3 (make-event) "Using [47m[make-event][0m to define [47m[thm][0m The definition of [47m[thm][0m provides a simple, yet informative, example use of [47mmake-event[0m. Formerly (through ACL2 Version 8.1), this was the definition of [47mthm[0m, where [47mthm-fn[0m provides an interface to the prover. (defmacro thm (term &key hints otf-flg) (list 'thm-fn (list 'quote term) 'state (list 'quote hints) (list 'quote otf-flg))) However, this version of [47mthm[0m did not permit calls of [47mthm[0m in [books] or [47m[encapsulate][0m forms. To remedy that deficiency, the definition was changed to the following; below we explain components of this definition. (It has since been updated further, but that is not relevant here so we don't comment here on further updates.) (defmacro thm (&whole event-form term &key hints otf-flg) `(with-output :off summary :stack :push (make-event (er-progn (with-output :stack :pop (thm-fn ',term state ',hints ',otf-flg ',event-form)) (value '(value-triple :invisible))) :expansion? (value-triple :invisible) :on-behalf-of :quiet! :save-event-data t))) The use of [47m[with-output][0m avoids printing anything about [47mmake-event[0m in the [summary] (by using [47m:off summary[0m). But we do want a summary for the prover call itself, to see the rules used, time elapsed, and so on. By using the keyword argument [47m:stack :push[0m, but then calling [47mwith-output[0m again with argument [47m:stack :pop[0m before calling [47mthm-fn[0m, we remove the effect of [47m:off summary[0m before calling [47mthm-fn[0m. By ignoring the [47mwith-output[0m wrapper, we may view the body of the [47mmake-event[0m form as follows. (er-progn (thm-fn ...) (value '(value-triple :invisible))) Evaluation of this call of [47m[er-progn][0m causes [47mthm-fn[0m to be run and, if there is no error and the proof succeeds, to return the event [47m(value-triple :invisible)[0m. That event is a no-op, and it generally doesn't even cause a value to be printed; see [ld-post-eval-print]. Since an error-free expansion is always [47m(value-triple :invisible)[0m, that event is specified with the [47m:expansion?[0m keyword so that the expansion is not stored, in particular in a book's [certificate] file. See [make-event]. The use of [47m:on-behalf-of :quiet![0m avoids a needless, distracting error message from [47mmake-event[0m when the proof fails. The [47m:save-event-data[0m keyword argument is a low-level implementation detail that we ignore here.") (make-fast-alist (fast-alists acl2-built-ins) "[47m(make-fast-alist alist)[0m creates a fast-alist from the input alist, returning [47malist[0m itself or, in some cases, a new object equal to it. Note: it is often better to use [47mwith-fast-alist[0m; see [with-fast-alist]. Logically, [47mmake-fast-alist[0m is the identity function. [31;1mFunction: [0m<make-fast-alist> (defun make-fast-alist (alist) (declare (xargs :guard t)) alist) Under the hood, we construct and return an object that is [47mequal[0m to [47malist[0m and which is a fast alist. If [47malist[0m is already a fast alist, almost no work is required: we simply return it unchanged. When [47malist[0m is not fast, we must minimally construct a hash table for its bindings. It is often possible to bind this new hash table to [47malist[0m itself. But in certain cases when the alist keys are not [normed], a new alist must be constructed, also, and so we may return an [47mequal[0m but not [47meq[0m alist. (In these cases, we still try to avoid at least some consing by reusing the "longest normed tail" of the alist.)") (make-lambda (pointers) "See [system-utilities].") (make-lambda-application (pointers) "See [system-utilities].") (make-lambda-term (pointers) "See [system-utilities].") (make-list (lists acl2-built-ins) "Make a list of a given size For a nonnegative integer [47msize[0m, [47m(Make-list size)[0m is a list of elements of length [47msize[0m, each of which is initialized to the [47m:initial-element[0m (which defaults to [47mnil[0m). [47mMake-list[0m is a macro in ACL2, defined in terms of a tail recursive function [47mmake-list-ac[0m whose [guard] requires [47msize[0m to be a nonnegative integer. [47mMake-list[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<make-list> (defmacro make-list (size &key initial-element) (cons 'make-list-ac (cons size (cons initial-element '(nil))))) [31;1mFunction: [0m<make-list-ac> (defun make-list-ac (n val ac) (declare (xargs :guard (and (integerp n) (>= n 0)))) (cond ((zp n) ac) (t (make-list-ac (1- n) val (cons val ac)))))") (make-list-ac (pointers) "See [make-list].") (make-ord (ordinals acl2-built-ins) "A constructor for ordinals. [47mMake-ord[0m is the ordinal constructor. Its use is recommended instead of using [47m[cons][0m to make ordinals. For a discussion of ordinals, see [ordinals]. For any ordinal, [47malpha < epsilon-0[0m, there exist natural numbers [47mp[0m and [47mn[0m, positive integers [47mx1, x2, ..., xn[0m and ordinals [47ma1 > a2 > ... > an > 0[0m such that [47malpha > a1[0m and [47malpha = w^(a1)x1 + w^(a2)x2 + ... + w^(an)xn + p[0m. We call [47ma1[0m the ``first exponent'', [47mx1[0m the ``first coefficient'', and the remainder [47m(w^(a2)x2 + ... + w^(an)xn + p)[0m the ``rest'' of alpha. [47m(Make-ord fe fco rst)[0m corresponds to the ordinal [47m(w^fe)fco + rst[0m. Thus the first infinite ordinal, [47mw[0m ([47momega[0m), is constructed by (make-ord 1 1 0) and, for example, the ordinal [47m(w^2)5 + w2 + 7[0m is constructed by: (make-ord 2 5 (make-ord 1 2 7)) . The reason [47mmake-ord[0m is used rather than [47m[cons][0m is that it allows us to reason more abstractly about the ordinals, without having to worry about the underlying representation. [31;1mFunction: [0m<make-ord> (defun make-ord (fe fco rst) (declare (xargs :guard (and (posp fco) (o-p fe) (o-p rst)))) (cons (cons fe fco) rst))") (make-summary-data (clause-processor) "Return summary data from a [clause-processor] function For relevant background, see [clause-processor]. Here we discuss the value [47md[0m and its effect in the signature [3+] shown in that topic: [3+] ((CL-PROC cl hint st_1 ... st_k) => (mv erp cl-list st_i1 ... st_in d)) The purpose of [47md[0m is to return [summary] information, as illustrated by the following (admittedly artificial) example. Here we abbreviate somewhat; the full example may be found in the [community-book], [47mbooks/clause-processors/basic-examples.lisp[0m. (defevaluator evl evl-list ...) (defun strengthen-cl2 (cl term state) (declare (xargs :stobjs state)) (cond ((null term) ; then no change (mv nil (list cl) state nil)) ... ((pseudo-termp term) (mv nil (list (cons (list 'not term) cl) (list term)) state (make-summary-data :runes '((:rewrite car-cons) (:rewrite cdr-cons) (:rewrite car-cons)) :use-names '(nth binary-append) :by-names '(nthcdr) :clause-processor-fns '(note-fact-clause-processor)))) (t ..))) (defthm correctness-of-strengthen-cl2 (implies (and (pseudo-term-listp cl) (alistp a) (evl (conjoin-clauses (clauses-result (strengthen-cl2 cl term state))) a)) (evl (disjoin cl) a)) :rule-classes :clause-processor) (defthm test-strengthen-cl2 (equal y y) :hints (("Goal" :instructions ((:prove :hints (("Goal" :clause-processor (strengthen-cl2 clause '(equal x x) state))))))) :rule-classes nil) Evaluation of the final [47mdefthm[0m event above prints the following [summary], which illustrates how the values of the four legal keywords for [47mmake-summary-data[0m naturally translate to the summary, specifically, to the [47m"Rules"[0m field for the [47m:runes[0m keyword and to the [47m"Hint-events"[0m field for the others. Summary Form: ( DEFTHM TEST-STRENGTHEN-CL2 ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL) (:REWRITE CAR-CONS) (:REWRITE CDR-CONS)) Hint-events: ((:BY NTHCDR) (:CLAUSE-PROCESSOR NOTE-FACT-CLAUSE-PROCESSOR) (:CLAUSE-PROCESSOR STRENGTHEN-CL2) (:USE BINARY-APPEND) (:USE NTH)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Note that each keyword is optional; in particular, the form [47m(make-summary-data)[0m is legal, and it specifies [47mnil[0m for each of the four keywords. Moreover, it is also legal for [47md[0m to be [47mnil[0m, which is equivalent to [47m(make-summary-data)[0m. Thus, if [47md[0m is [47mnil[0m or [47m(make-summary-data)[0m then [3+] and [3] in the documentation for [clause-processor] have the same effect: that is, there will be no visible effect if we change such a clause-processor function (i.e., one returning empty summary data) from form [3+] to form [3] by dropping the return value of [47md[0m. Duplicates are allowed in the list, for each argument of [47mmake-summary-data[0m; no duplicates will appear in the summary. There is also no need to sort elements of those lists. Finally, note that the summary information from [47md[0m not only goes into the summary, but also is incorporated when extending the [proof-supporters-alist] to record the dependencies of the completed event. (assert-event (equal (sort-symbol-listp (car (global-val 'proof-supporters-alist (w state)))) '(BINARY-APPEND CAR-CONS CDR-CONS NOTE-FACT-CLAUSE-PROCESSOR NTH NTHCDR STRENGTHEN-CL2 TEST-STRENGTHEN-CL2)))") (make-tau-interval (tau-system acl2-built-ins) "Make a tau interval General Form: (make-tau-interval doc lo-rel lo hi-rel hi) An interval is a structure of the form: [47m([0m[3mdom[0m [47m([0m[3mlo-rel[0m [47m.[0m [3mlo[0m[47m)[0m [47m.[0m [47m([0m[3mhi-rel[0m [47m.[0m [3mhi[0m[47m))[0m. Every tau contains an interval used to represent the domain, the upper, and the lower bounds of the objects recognized by the tau. [47mmake-tau-interval[0m constructs well-formed intervals only if its five arguments satisfy certain restrictions given below. When these restrictions are violated [47mmake-tau-interval[0m can construct objects that are not intervals! [47mmake-tau-interval[0m does not attempt to coerce or adjust its arguments to make well-formed intervals. For examples of intervals (and non-intervals!) constructed by [47mmake-tau-interval[0m see [47m[tau-intervalp][0m. For examples of what objects are contained in certain intervals, see [47m[in-tau-intervalp][0m. The components of an interval are as follows: [3mDom[0m (``domain'') must be one of four symbols: [47mINTEGERP[0m, [47mRATIONALP[0m, [47mACL2-NUMBERP[0m, or [47mNIL[0m denoting no restriction on the domain. The two ``relations,'' [3mlo-rel[0m and [3mhi-rel[0m are Booleans, where [47mt[0m denotes less-than inequality ([47m[<][0m) and [47mnil[0m represents less-than-or-equal inequality ([47m[<=][0m). Think of [47mt[0m meaning ``strong'' and [47mnil[0m meaning ``weak'' inequality. [3mLo[0m and [3mhi[0m must be either [47mnil[0m or explicit rational numbers. If [3mlo[0m is [47mnil[0m it denotes negative infinity; if [3mhi[0m is [47mnil[0m it denotes positive infinity. [3mLo[0m must be no greater than [3mhi[0m. [3mNote[0m: Even though [47mACL2-NUMBERP[0m intervals may contain complex rationals, the [3mlo[0m and [3mhi[0m bounds must be rational. This is an arbitrary decision made by the implementors to simplify coding. Finally, if the [3mdom[0m is [47mINTEGERP[0m, then both relations should be weak and [3mlo[0m and [3mhi[0m must be integers when they are non-[47mnil[0m. For [3mx[0m to be ``in'' an interval it must be of the type described by the domain predicate [3mdom[0m, [3mlo[0m must be smaller than [3mx[0m in the strong or weak sense denoted by [3mlo-rel[0m, and [3mx[0m must be smaller than [3mhi[0m in the strong or weak sense denoted by [3mhi-rel[0m. The components of an interval may be accessed with the functions [47m[tau-interval-dom][0m, [47m[tau-interval-lo-rel][0m, [47m[tau-interval-lo][0m, [47m[tau-interval-hi-rel][0m, and [47m[tau-interval-hi][0m.") (make-wormhole-status (wormhole) "Creates a wormhole status object from given status, entry code, and data General Form: (make-wormhole-status whs code data) See [wormhole]. [47mWhs[0m is generally a well-formed wormhole status (but see below), [47mcode[0m should be [47m:ENTER[0m or [47m:SKIP[0m, and [47mdata[0m is arbitrary. This function returns a new status with the specified entry code and data. The result does not logically depend on [47mwhs[0m, but if the wormhole status corresponding to the given code and data is equal to [47mwhs[0m, then [47mwhs[0m is returned, which will save a cons. [31;1mWarning[0m: if [47mdata[0m is large then the equality test can be slow. That problem is avoided by passing [47mwhs = nil[0m. For an example of this use of [47mnil[0m in the ACL2 source code, see source function [47msave-ev-fncall-guard-er[0m.") (makunbound-global (programming-with-state acl2-built-ins) "Remove the value assigned to a global variable in [47m[state][0m Examples: (makunbound-global 'y state) General Form: (makunbound-global s state) where [47ms[0m evaluates to a symbol. This value returned is the result of modifying the ACL2 [state] so that the given symbol does not have a value. This function thus acts as a no-op if the symbol does not have a value in the given state. Also see related utilities [47m[f-get-global][0m, [47m[f-put-global][0m, and [47m[f-boundp-global][0m.") (managing-acl2-packages (packages) "User-contributed documentation on packages Jared Davis has contributed documentation on {managing ACL2 packages | http://www.cs.utexas.edu/users/moore/acl2/contrib/managing-acl2-packages.html}. Also see [working-with-packages].") (match-free (pointers) "See [free-variables].") (max (numbers acl2-built-ins) "The larger of two numbers [47m(Max x y)[0m is the larger of the numbers [47mx[0m and [47my[0m. The [guard] for [47mmax[0m requires its arguments to be rational ([real], in ACL2(r)) numbers. [47mMax[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<max> (defun max (x y) (declare (xargs :guard (and (real/rationalp x) (real/rationalp y)))) (if (> x y) x y))") (maximum-length (arrays acl2-built-ins) "Return the [47m:maximum-length[0m from the [header] of an array Example Form: (maximum-length 'delta1 a) General Form: (maximum-length name alist) where [47mname[0m is an arbitrary object and [47malist[0m is a 1- or 2-dimensional array. This function returns the contents of the [47m:maximum-length[0m field of the [header] of [47malist[0m. Whenever an [47m[aset1][0m or [47m[aset2][0m would cause the length of the alist to exceed its maximum length, a [47m[compress1][0m or [47m[compress2][0m is done automatically to remove irrelevant pairs from the array. [47mMaximum-length[0m operates in virtually constant time if [47malist[0m is the semantic value of [47mname[0m. See [arrays]. [31;1mFunction: [0m<maximum-length> (defun maximum-length (name l) (declare (xargs :guard (or (array1p name l) (array2p name l)))) (cadr (assoc-keyword :maximum-length (cdr (header name l)))))") (maybe-convert-to-mv (pointers) "See [system-utilities].") (maybe-flush-and-compress1 (arrays acl2-built-ins) "Compress a one-dimensional array only if necessary The call [47m(maybe-flush-and-compress1 name ar)[0m is equivalent to the first calling [47m(flush-compress name)[0m and then [47m(compress1 name ar)[0m, except that both operations are skipped (and [47mar[0m is returned) if [47mar[0m, which has name [47mname[0m, is already compressed.") (mbe (guard programming acl2-built-ins) "Attach code for execution The macro [47mmbe[0m (``must be equal'') can be used in function definitions in order to cause evaluation to use alternate code to that provided for the logic. An example is given below. However, the use of [47mmbe[0m can lead to non-terminating computations. See [defexec], perhaps after reading the present documentation, for a way to prove termination. In the ACL2 logic, [47m(mbe :exec exec-code :logic logic-code)[0m equals [47mlogic-code[0m; the value of [47mexec-code[0m is ignored. However, in raw Lisp it is the other way around: this form macroexpands simply to [47mexec-code[0m. ACL2's [guard] verification mechanism ensures that the raw Lisp code is only evaluated when appropriate, since the guard proof obligations generated for (the macroexpansion of) this call of [47mmbe[0m include not only the guard proof obligations from [47mexec-code[0m, but also, under suitable contextual assumptions, the term [47m(equal exec-code logic-code)[0m. See [verify-guards] (in particular, for discussion of the contextual assumptions from the [47m:guard[0m and [47m[if][0m-tests) and, for general discussion of guards, see [guard]. Normally, during evaluation of an [47mmbe[0m call, only the [47m:logic[0m code is evaluated unless the call is in the body of a [guard]-verified function or under a call of a [47m:[0m[47m[program][0m mode function; in those cases only the [47m:exec[0m code is evaluated. This implies that equality of [47m:exec[0m and [47m:logic[0m code is never checked at runtime. (Rather, such equality is proved when verifying guards.) We qualified with ``normally'' above because there are two exceptions. During a ``safe mode'', which is used in macroexpansion and evaluation of [47m[defconst][0m forms, the [47m:logic[0m and [47m:exec[0m code are both evaluated and their equality is checked. Second, when guard-checking is set to [47m:all[0m or [47m:none[0m, then for any [47mmbe[0m call in the body of a [47m:logic[0m mode definition, only the [47m:logic[0m code will be evaluated. Note that the [47m:exec[0m and the [47m:logic[0m code in an [47mmbe[0m call must have the same output signature. For example, one cannot return [47m([0m[47m[mv][0m[47m * *)[0m while the other returns just a single value. Also see [mbt], which stands for ``must be true.'' You may find it more natural to use [47m[mbt][0m for certain applications, as described in its [documentation]. Here is an example of the use of [47mmbe[0m. Suppose that you want to define factorial in the usual recursive manner, as follows. (defun fact (n) (if (zp n) 1 (* n (fact (1- n))))) But perhaps you want to be able to execute calls of [47mfact[0m on large arguments that cause stack overflows, perhaps during proofs. (This isn't a particularly realistic example, but it should serve.) So, instead you can define this tail-recursive version of factorial: (defun fact1 (n acc) (declare (xargs :guard (and (integerp n) (>= n 0) (integerp acc)))) (if (zp n) acc (fact1 (1- n) (* n acc)))) We are now ready to define [47mfact[0m using [47mmbe[0m. Our intention is that logically, [47mfact[0m is as shown in the first definition above, but that [47mfact[0m should be executed by calling [47mfact1[0m. Notice that we defer [guard] verification, since we are not ready to prove the correspondence between [47mfact1[0m and [47mfact[0m. (defun fact (n) (declare (xargs :guard (and (integerp n) (>= n 0)) :verify-guards nil)) (mbe :exec (fact1 n 1) :logic (if (zp n) 1 (* n (fact (1- n)))))) Next, we prove the necessary correspondence lemmas. Notice the inclusion of a community book to help with the arithmetic reasoning. (include-book "arithmetic/top-with-meta" :dir :system) (defthm fact1-fact (implies (integerp acc) (equal (fact1 n acc) (* acc (fact n))))) We may now do guard verification for [47mfact[0m, which will allow the execution of the raw Lisp [47mfact[0m function, where the above [47mmbe[0m call expands simply to [47m(fact1 n 1)[0m. (verify-guards fact) Now that guards have been verified, a trace of function calls illustrates that the evaluation of calls of [47mfact[0m is passed to evaluation of calls of [47mfact1[0m. The outermost call below is of the logical function stored for the definition of [47mfact[0m; all the others are of actual raw Common Lisp functions. ACL2 !>(trace$ fact fact1) NIL ACL2 !>(fact 3) 1> (ACL2_*1*_ACL2::FACT 3) 2> (FACT 3) 3> (FACT1 3 1) 4> (FACT1 2 3) 5> (FACT1 1 6) 6> (FACT1 0 6) <6 (FACT1 6) <5 (FACT1 6) <4 (FACT1 6) <3 (FACT1 6) <2 (FACT 6) <1 (ACL2_*1*_ACL2::FACT 6) 6 ACL2 !> You may occasionally get warnings when you compile functions defined using [47mmbe[0m. (For commands that invoke the compiler, see [compilation].) These can be inhibited by using an [47mignorable[0m [47m[declare][0m form. Here is a simple but illustrative example. Note that the declarations can optionally be separated into two [47m[declare][0m forms. (defun foo (x y) (declare (ignorable x) (xargs :guard (equal x y))) (mbe :logic x :exec y)) Finally, we observe that when the body of a function contains a term of the form [47m(mbe :exec exec-code :logic logic-code)[0m, the user would be unlikely to notice any difference in the theorem prover if this term were replaced by [47mlogic-code[0m. ACL2 takes various steps to ensure this. For example, the proof obligations generated for admitting a function treat the above [47mmbe[0m term simply as [47mlogic-code[0m. Function expansion, [47m:use[0m [hints], [47m:[0m[47m[definition][0m rules, generation of [constraint]s for functional instantiation, and creation of rules of class [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[forward-chaining][0m also treat [47mmbe[0m calls as their [47m:logic[0m code. Subtopics [Defexec] Attach a terminating executable function to a definition [Mbe1] Attach code for execution [Mbt] Introduce a test into the logic that, however, evaluates to [47mt[0m [Mbt*] Introduce a guard proof obligation [Must-be-equal] Attach code for execution") (mbe1 (mbe acl2-built-ins) "Attach code for execution The form [47m(mbe1 exec logic)[0m is equivalent to the forms [47m(mbe :logic logic :exec exec)[0m and [47m(must-be-equal logic exec)[0m. See [mbe].") (mbt (mbe acl2-built-ins) "Introduce a test into the logic that, however, evaluates to [47mt[0m The macro [47mmbt[0m (``must be true'') can be used in order to add code in order to admit function definitions in [47m:[0m[47m[logic][0m mode, without paying a cost in execution efficiency. Examples below illustrate its intended use. Semantically, [47m(mbt x)[0m equals [47mx[0m. However, in raw Lisp [47m(mbt x)[0m ignores [47mx[0m entirely, and macroexpands to [47mt[0m. ACL2's [guard] verification mechanism ensures that the raw Lisp code is only evaluated when appropriate, since a guard proof obligation [47m(equal x t)[0m is generated. See [verify-guards] and, for general discussion of guards, see [guard]. Also see [mbe], which stands for ``must be equal.'' Although [47mmbt[0m is more natural in many cases, [47mmbe[0m has more general applicability. In fact, [47m(mbt x)[0m is essentially defined to be [47m(mbe :logic x :exec t)[0m. Another related utility is [47m[mbt*][0m, which generates the same proof obligation as [47mmbt[0m but logically, is simply [47mt[0m. We can illustrate the use of [47mmbt[0m on the following generic example, where [47m<g>[0m, [47m<test>[0m, [47m<rec-x>[0m, and [47m<base>[0m are intended to be terms involving only the variable [47mx[0m. (defun foo (x) (declare (xargs :guard <g>)) (if <test> (foo <rec-x>) <base>)) In order to admit this function, ACL2 needs to discharge the proof obligation that [47m<rec-x>[0m is smaller than [47mx[0m, namely: (implies <test> (o< (acl2-count [47m<rec-x>[0m) (acl2-count x))) But suppose we need to know that [47m<g>[0m is true in order to prove this. Since [47m<g>[0m is only the [guard], it is not part of the logical definition of [47mfoo[0m. A solution is to add the guard to the definition of [47mfoo[0m, as follows. (defun foo (x) (declare (xargs :guard <g>)) (if (mbt <g>) (if <test> (foo <rec-x>) <base>) nil)) If we do this using [47m<g>[0m rather than [47m(mbt <g>)[0m, then evaluation of every recursive call of [47mfoo[0m will cause the evaluation of (the appropriate instance of) [47m<g>[0m. But since [47m(mbt <g>)[0m expands to [47mt[0m in raw Lisp, then once we verify the guards of [47mfoo[0m, the evaluations of [47m<g>[0m will be avoided (except at the top level, when we check the guard before allowing evaluation to take place in Common Lisp). Other times, the guard isn't the issue, but rather, the problem is that a recursive call has an argument that itself is a recursive call. For example, suppose that [47m<rec-x>[0m is of the form [47m(foo <expr>)[0m. There is no way we can hope to discharge the termination proof obligation shown above. A standard solution is to add some version of this test: (mbt (o< (acl2-count [47m<rec-x>[0m) (acl2-count x))) Here is a specific example based on one sent by Vernon Austel. (defun recurX2 (n) (declare (xargs :guard (and (integerp n) (<= 0 n)) :verify-guards nil)) (cond ((zp n) 0) (t (let ((call (recurX2 (1- n)))) (if (mbt (< (acl2-count call) n)) (recurX2 call) 1 ;; this branch is never actually taken ))))) (defthm recurX2-0 (equal (recurX2 n) 0)) (verify-guards recurX2) If you [47m([0m[47m[trace$][0m[47m acl2-count)[0m, you will see that evaluation of [47m(recurX2 2)[0m causes several calls of [47m[ACL2-count][0m before the [47m[verify-guards][0m. But this evaluation does not call [47macl2-count[0m after the [47mverify-guards[0m, because the ACL2 evaluation mechanism uses raw Lisp to do the evaluation, and the form [47m(mbt (< (acl2-count call) n))[0m macroexpands to [47mt[0m in Common Lisp. You may occasionally get warnings when you compile functions defined using [47mmbt[0m. (For commands that invoke the compiler, see [compilation].) These can be inhibited by using an [47mignorable[0m [47m[declare][0m form. Here is a simple but illustrative example. Note that the declarations can optionally be separated into two [47m[declare][0m forms. (defun foo (x y) (declare (ignorable x) (xargs :guard (equal x t))) (and (mbt x) y))") (mbt* (mbe acl2-built-ins) "Introduce a guard proof obligation The macro [47mmbt*[0m is a variant of [47mmbt[0m (``must be true''). However, unlike [47mmbt[0m, the call [47m(mbt* test)[0m is equivalent simply to [47mt[0m for both logic and evaluation. The only effective difference between [47m(mbt* test)[0m and [47mt[0m is that [47m(mbt* test)[0m generates a [guard] proof obligation (when used in a [47m[logic][0m-mode definition) of [47mtest[0m. If you think that [47mmbt*[0m might be of use, please see [assert*], which is defined using [47mmbt*[0m to create a [guard] proof obligation without any logical or execution burden.") (measure (xargs) "Declare a measure for a [47m[defun][0m See [xargs] for discussion of how to use the [47m:measure[0m keyword to specify a measure for a definition. A related utility, [47mget-measure[0m, may be found in the [community-books], file [47mstd/system/get-measure.lisp[0m. Subtopics [Measure-debug] Generate markers to indicate sources of [measure] proof obligations [Termination-theorem] Use a (functional instance of a) previously-proved measure theorem [Termination-theorem-example] How to use a previously-proved measure theorem [Tthm] The [measure] (termination) theorem for a given function symbol") (measure-debug (measure debugging) "Generate markers to indicate sources of [measure] proof obligations When ACL2 is asked to accept a recursive (or mutually recursive) function definition, it generates a goal often called the ``measure conjecture.'' That goal can split into numerous goals, some of which may not be theorems if the definition being processed has bugs. This [documentation] topic explains a capability provided by ACL2 to help find such bugs. For a similar utility appropriate for [guard] verification, see [guard-debug]. We begin with the following simple, admittedly artificial, example. (defun f (x) (if (consp x) (f (cons x x)) x)) ACL2 generates the following proof obligation.. (IMPLIES (CONSP X) (O< (ACL2-COUNT (CONS X X)) (ACL2-COUNT X))) In this simple example, it is obvious that ACL2 cannot prove the goal because in fact, [47m(CONS X X)[0m does not have a smaller [47m[ACL2-count][0m than [47mX[0m, even assuming [47m(CONSP X)[0m. But you can get ACL2 to show explicitly the source of this proof obligation by specifying [47m:measure-debug t[0m in an [47m[xargs][0m [47m[declare][0m form, as follows. ACL2 !>(defun f (x) (declare (xargs :measure-debug t)) (if (consp x) (f (cons x x)) x)) For the admission of F we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). The non-trivial part of the measure conjecture is Goal (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:RELATION F)) '(F (CONS X X))) (CONSP X)) (O< (ACL2-COUNT (CONS X X)) (ACL2-COUNT X))). The [47mextra-info[0m call is telling us the following about the [31;1mmeasure[0m conjecture: The appropriate well-founded [31;1mrelation[0m (typically [47m[o<][0m) holds between appropriate terms, because of the indicated recursive call, [47m(F (CONS X X))[0m. We now describe the measure-debug utility in some detail. [47m(Extra-info x y)[0m always returns [47mt[0m by definition. However, if the measure conjecture takes place with a non-[47mnil[0m value for the [47m[xargs][0m keyword [47m:measure-debug[0m, then the goals generated will include hypotheses that are calls of [47mextra-info[0m. Such a hypothesis has one of the following forms. (extra-info '(:MEASURE (:RELATION function-name)) 'recursive-call) (extra-info '(:MEASURE (:DOMAIN function-name)) '(D (M term))) The first form says that the goal is to show that the measure decreases for the indicated recursive call in the body of the function named [47mfunction-name[0m. The second form says that the goal is to show that the measure always returns a suitable value. We illustrate with a slightly more elaborate, but still contrived, example, which we hope clearly illustrates the points above. Notice that [47m:measure-debug t[0m need only be specified for a single [47m[defun][0m form in a call of [47m[mutual-recursion][0m. Also notice in the output that when there is more than one source for a goal, each source is indicated by its own call of [47mextra-info[0m. ACL2 !>(defstub my-measure (x) t) ; for the contrived example below [[ .. output omitted here .. ]] ACL2 !>(mutual-recursion (defun f1 (x) (declare (xargs :measure (my-measure x) :measure-debug t)) (if (consp x) (f2 (cons x (cdr x))) t)) (defun f2 (x) (declare (xargs :measure (my-measure x))) (if (consp x) (f1 (cons (make-list (car x)) (cdr x))) nil))) For the admission of F1 and F2 we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (MY-MEASURE X) for F1 and (MY-MEASURE X) for F2. The non-trivial part of the measure conjecture is Goal (AND (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:RELATION F1)) '(F2 (CONS X (CDR X)))) (CONSP X)) (O< (MY-MEASURE (CONS X (CDR X))) (MY-MEASURE X))) (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:RELATION F2)) '(F1 (CONS (MAKE-LIST-AC (CAR X) NIL NIL) (CDR X)))) (CONSP X)) (O< (MY-MEASURE (CONS (MAKE-LIST-AC (CAR X) NIL NIL) (CDR X))) (MY-MEASURE X))) (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:DOMAIN F2)) '(O-P (MY-MEASURE X))) (EXTRA-INFO '(:MEASURE (:DOMAIN F1)) '(O-P (MY-MEASURE X)))) (O-P (MY-MEASURE X)))). All rules (see [rune]) associated with [47mextra-info[0m are [disable]d by default, so that hypotheses of the form described above are not simplified to [47mt[0m. These hypotheses are intended to ride along for free: you can generally expect the proof to have the same structure whether or not the [47m:measure-debug[0m option is supplied, though on rare occasions the proofs may diverge.") (measure-theorem (pointers) "See [termination-theorem].") (member (lists acl2-built-ins) "Membership predicate General Forms: (member x lst) (member x lst :test 'eql) ; same as above (eql as equality test) (member x lst :test 'eq) ; same, but eq is equality test (member x lst :test 'equal) ; same, but equal is equality test [47m(Member x lst)[0m equals the longest tail of the list [47mlst[0m that begins with [47mx[0m, or else [47mnil[0m if no such tail exists. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements of [47mlst[0m. The [guard] for a call of [47mmember[0m depends on the test. In all cases, the second argument must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mmember[0m and its variants: [47m(member-eq x lst)[0m is equivalent to [47m(member x lst :test 'eq)[0m; [47m(member-equal x lst)[0m is equivalent to [47m(member x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mmember-equal[0m. [47mMember[0m is defined by Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<member-equal> (defun member-equal (x lst) (declare (xargs :guard (true-listp lst))) (cond ((endp lst) nil) ((equal x (car lst)) lst) (t (member-equal x (cdr lst)))))") (member-eq (pointers) "See [member].") (member-equal (pointers) "See [member].") (memoization (pointers) "See [memoize].") (memoize (programming hons-and-memoization events) "Turn on memoization for a specified function See [hons-and-memoization] for a general discussion of the ``[hons-enabled]'' features: memoization, hash consing, and applicative hash tables. Examples: (memoize 'foo) ; remember the values of calls ; of foo (memoize 'foo :condition t) ; same as above (memoize 'foo :condition '(test x)) ; memoize for args satisfying ; the given condition (memoize 'foo :condition-fn 'test) ; memoize for args satisfying ; a call of the given function (memoize 'foo :recursive nil) ; don't memoize recursive calls (memoize 'foo :aokp t) ; attachments OK for stored results (memoize 'foo :stats nil) ; don't collect info for (memsum) (memoize 'foo :ideal-okp t) ; memoize for raw Lisp even if foo is ; in :logic but not guard-verified General Form: (memoize fn ; memoizes fn and returns fn :aokp t/nil ; optional (default nil) :commutative t/lemma-name ; optional (default nil) :condition condition ; optional (default t (unless :invoke)) :condition-fn condition-fn ; optional :forget t/nil ; optional (default nil) :hints hints ; optional, for verifying the ; guards of condition-fn :ideal-okp t/:warn/nil ; optional (default nil) :invoke nil/fn ; optional (default nil) :memo-table-init-size size ; optional (default *mht-default-size*) :otf-flg otf-flg ; optional, for verifying the ; guards of condition-fn :recursive t/nil ; optional (default t) :stats t/nil ; optional (default t (unless :invoke)) :total ; ; see :DOC memoize-partial :verbose t/nil ; optional (default nil) ) where [47mfn[0m evaluates to a user-defined function symbol; [47mcondition[0m is either [47mt[0m (the default), [47m't[0m, [47mnil[0m, or [47m'nil[0m, or else evaluates to an expression whose free variables are among the formal parameters of [47mfn[0m; and [47mcondition-fn[0m is either [47mnil[0m (the default) or else evaluates to a legal function symbol. Further restrictions and options are discussed below. Note that all arguments are evaluated (but for the special handling of value [47mt[0m for [47m:commutative[0m, the argument must literally be [47mt[0m; see below). Generally [47mfn[0m must evaluate to a defined function symbol. However, this value can be the name of a macro that is associated with such a function symbol; see [macro-aliases-table]. That associated function symbol is the one called ``memoized'' in the discussion below, but we make no more mention of this subtlety. In the most common case, [47mmemoize[0m takes a single argument, which evaluates to a function symbol. We call this function symbol the ``memoized function'' because ``memos'' are saved and re-used, in the following sense. When a call of the memoized function is evaluated, the result is ``memoized'' by associating the call's arguments with that result, in a suitable table. But first an attempt is made to avoid such evaluation, by doing a lookup in that table on the given arguments for the result, as stored for a previous call on those arguments. If such a result is found, then it is returned without further computation. This paragraph also applies if [47m:condition[0m is supplied but is [47mt[0m or [47m't[0m. If keyword argument [47m:condition-fn[0m is supplied, but [47m:condition[0m is not, then the result of evaluating [47m:condition-fn[0m must be a defined function symbol whose formal parameter list and [47m[guard][0m are the same as for the function being memoized. If [47mfn[0m is in [47m:[0m[47m[logic][0m mode, then [guard]s must have been verified for [47m:condition-fn[0m. Such a ``condition function'' will be run whenever the memoized function is called, on the same parameters, and the lookup or table store described above are only performed if the result from the condition function call is non-[47mnil[0m. Suppose however that [47m:condition[0m is supplied. If the value supplied is [47mt[0m or [47m't[0m, then the lookup and table store described above are always done. If the value is [47mnil[0m or [47m'nil[0m, then this lookup and table store are never done, although statistics may be gathered; see [profile]. Now consider other values for [47m:condition[0m. An attempt will be made to define a condition function whose [guard] and formal parameters list are the same as those of the memoized function, and whose body is the result, [47mr[0m, of evaluating the given [47mcondition[0m. The name of that condition function is the result of evaluating [47m:condition-fn[0m if supplied, else is the result of concatenating the string [47m"-MEMOIZE-CONDITION"[0m to the end of the name of the memoized function. The condition function will be defined with [guard] verification turned off, but that definition will be followed immediately by a [47m[verify-guards][0m event; and this is where the optional [47m:hints[0m and [47m:otf-flg[0m are attached. At evaluation time the condition function is used as described in the preceding paragraph; so in effect, the condition ([47mr[0m, above) is evaluated, with its variables bound to the corresponding actuals of the memoized function call, and the memoized function attempts a lookup or table store if and only if the result of that evaluation is non-[47mnil[0m. Note that [47mfn[0m can be either a [47m:[0m[47m[logic][0m mode function or a [47m:[0m[47m[program][0m mode function. However, only the corresponding raw Lisp function is actually memoized, so [guard] violations can defeat memoization, and [47m:[0m[47m[logic][0m mode functions without their [guard]s verified will only be memoized when called by [47m:[0m[47m[program][0m mode functions. (See [guards-and-evaluation] for more information about guards and evaluation in ACL2.) If [47mfn[0m is a [47m:[0m[47m[logic][0m mode function and [47m:condition[0m is supplied and not [47mt[0m or [47mnil[0m, then the condition must be a [guard]-verified function. Calls of this macro generate events of the form [47m(table memoize-table fn ((:condition-fn fn) ...))[0m. When successful, the returned value is of the form [47m(mv nil function-symbol state)[0m. Suppose that a function is already memoized. Then it is illegal to memoize that function. Moreover, if the function was memoized with an associated condition (i.e., was memoized with keyword [47m:condition[0m or [47m:condition-fn[0m having value other than [47mt[0m or [47mnil[0m), then it is also illegal to convert the function from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m mode (see [verify-termination]). To turn off memoization, see [unmemoize]. [47mMemoize[0m is illegal for a function if its arguments include [47m[state][0m; if it returns any [stobj]s; if it has been excluded by [47m[never-memoize][0m; or if it is excluded because it is ``special'' in the sense that it is in the [47m"COMMON-LISP"[0m [package], it has no fixed output signature (i.e., it is in the value of the list constant [47m(if return-last do$ read-user-stobj-alist)[0m, [47m(if return-last do$ read-user-stobj-alist)[0m), it has associated raw-Lisp code, or it is used in the implementation of [hons-and-memoization]. A constrained function (typically, one that is introduced in the signature of an [47m[encapsulate][0m event) cannot be memoized; in that case, one may wish to memoize its caller or attachment (see [defattach]). A stobj can be an input of a memoized function, but in that case, the memoization table for that stobj will be cleared every time that stobj is updated. By default, [47mmemoize[0m does not store results when any attachments have been used (see [defattach]). However, such results are stored when [47mmemoize[0m keyword parameter [47m:aokp[0m has value [47mt[0m. Note that for purposes of this discussion, the use of a stored value for a subsidiary function that was memoized with [47m:aokp t[0m is treated as the use of an attachment, since ACL2 does not know whether or not an attachment was actually used in that case. We conclude by documenting keyword parameters not discussed above. Keyword parameter [47m:invoke[0m is [47mnil[0m by default, but its value can be a symbol, [47mg[0m. Examples may be found in [community-books] file [47mdemos/memoize-invoke-input.lsp[0m; for a tool built on this capability that supports evaluation using proved input-output pairs for a function, see [add-io-pairs]. The effect of [47m:invoke g[0m is to replace every call of [47mfn[0m by a call of [47mg[0m. However, there are some restrictions. The function symbol [47mfn[0m must be in [47m:logic[0m mode, and the symbol [47mg[0m must be a [guard]-verified [47m:[0m[47m[logic][0m-mode function symbol with the same [signature] as that of [47mfn[0m. There is the following proof obligation: there must be a theorem in the current ACL2 [world] stating the equality of calls of [47mfn[0m and [47mg[0m on a duplicate-free argument list; for example, if the formals list of [47mfn[0m is [47m(x1 ... xn)[0m, then the theorem could be [47m(equal (fn x1 .... xn) (g x1 ... xn))[0m. If ACL2 finds no such theorem, it will print a [47m[defthm][0m event that you may wish to submit. Next we describe a potential second proof obligation, which will similarly be printed if it is not met. Let [47mguard-fn[0m be the [guard] for [47mfn[0m, and let [47mguard-g[0m be the result of substituting the formals of [47mfn[0m for the formals of [47mg[0m in the guard for [47mg[0m. If [47mguard-fn[0m tautologically implies [47mguard-g[0m (for example, the two are equal or [47mguard-g[0m is [47m'T[0m), then there is no further proof obligation. Otherwise, there must be a theorem in the current ACL2 [world] of the form [47m(implies guard-fn guard-g)[0m. See [verify-guard-implication] for a utility that makes it easy for you to prove such a theorem. Finally, contrary to the usual defaults, the values of keyword [47m:recursive[0m, [47m:condition[0m and [47m:stats[0m default to [47mnil[0m. Indeed, it is an error to specify a non-nil value for [47m:recursive[0m. The alternate defaults of [47mnil[0m for [47m:condition[0m and [47m:stats[0m can avoid memoization overhead when one simply wishes to call [47mg[0m in place of [47mfn[0m; you may override those defaults if you actually want to save computed values and use [47m(memsum)[0m to see statistics. Keyword parameter [47m:recursive[0m is [47mt[0m by default, which means that recursive calls of [47mfn[0m will be memoized just as ``top-level'' calls of [47mfn[0m. When [47m:recursive[0m is instead set to [47mnil[0m, memoization is only done at the top level. Using [47m:recursive nil[0m is similar to writing a wrapper function that just calls [47mfn[0m, and memoizing the wrapper instead of [47mfn[0m. A non-[47mnil[0m value for [47m:commutative[0m can be supplied if [47mfn[0m is a binary function in [47m:logic[0m mode. Suppose that the [47mmemoize[0m event is successful, and consider a subsequent call of [47mfn[0m for which some argument to [47mfn[0m is either a rational number or, in some host Lisps (currently either CCL, or GCL Version 2.6.12 or later) a [hons]. (Indeed, for such GCL versions this is true for any cons, not just a hons.) Then when the evaluation of [47mfn[0m on those arguments is memoized, the evaluation of [47mfn[0m on the swap of those arguments is, in essence, also memoized. If [47m:commutative[0m is supplied and is not [47mnil[0m or [47mt[0m, then it should be the name of a previously-proved theorem whose formula states the commutativity of [47mfn[0m, i.e., is the formula [47m(equal (fn x y) (fn y x))[0m for a pair [47m{x,y}[0m of distinct variables. If [47m:commutative[0m is [47mt[0m --- but not merely an expression that evaluates to [47mt[0m --- then an attempt to prove such a lemma will be made on-the-fly. The name of the lemma is the symbol in the same package as [47mfn[0m, obtained by adding the suffix [47m"-COMMUTATIVE"[0m to the [47m[symbol-name][0m of [47mfn[0m. If the proof attempt fails, then you may want first to prove the lemma yourself with appropriate hints and perhaps supporting lemmas, and then supply the name of that lemma as the value of [47m:commutative[0m. Note that because most output is inhibited by default, you might wish to supply keyword argument [47m:verbose t[0m if the event fails. If [47m:commutative[0m is supplied, and a non-commutative condition is provided by [47m:condition[0m or [47m:condition-fn[0m, then although the results will be correct, the extra memoization afforded by [47m:commutative[0m is unspecified. If [47m:memo-table-init-size[0m is supplied, then it should be a positive integer specifying the initial size of an associated hash table. Argument [47m:aokp[0m is relevant only when attachments are used; see [defattach] for background on attachments. When [47m:aokp[0m is [47mnil[0m, the default, computed values are not stored when an attachment was used, or even when an attachment may have been used because a function was called that had been memoized using [47m:aokp t[0m. Otherwise, computed values are always stored, but saved values are not used except when attachments are allowed. To summarize: aokp=nil (default): ``Pure'', i.e., values do not depend on attachments - Fetch: always legal - Store: only store resulting value when attachments were not used aokp=t: ``Impure'', i.e., values may depend on attachments - Fetch: only legal when attachments are allowed (e.g., not during proofs) - Store: always legal Note that for this handling of [47m:aokp[0m, the computation of a value returned by function [47m[apply$-userfn][0m or [47m[badge-userfn][0m is considered to have used an attachment. The default value for [47m:stats[0m is essentially [47mt[0m. (Technically, this can be subverted by using raw Lisp, to change the default by changing the values of variables [47m*record-xxx*[0m introduced in ACL2 source file [47mmemoize-raw.lisp[0m.) When [47m:stats[0m has its default value (assuming the above raw Lisp changes are not made) or value [47mt[0m, calls of memoized functions will collect information that can be displayed by calling [47m[memsum][0m. But if [47m:stats[0m is [47mnil[0m, this information will not be collected, possibly resulting in better performance for the memoized function. As of this writing, built-in memoized functions use [47m:stats nil[0m to benefit performance. If [47m:ideal-okp[0m is supplied and not [47mnil[0m, then it is permitted to memoize an ``ideal-mode'' function: one in [47m:[0m[47m[logic][0m mode whose [guard]s have not been verified. However, this might not have the effect you desire, because you will be memoizing the submitted version of the function, not its executable-counterpart that is executed in the ACL2 loop and on behalf of the prover (see [evaluation]). Thus, if you memoize an ideal-mode function and then call it at the top-level of the ACL2 loop (or, for example, it is called to evaluate a ground term arising in a proof or in the evaluation of a [meta]function in a proof), the effects of memoization will not be felt because the raw Lisp code is not run unless guards are verified. There are circumstances in which the raw Lisp code of an ideal-mode function is called. For example, if the ideal-mode function is called by a [47m:[0m[47m[program][0m mode function, evaluation can transfer to raw Lisp where the effects of memoization will be felt. A trick, described below, with [47m[ec-call][0m can provide some of the benefit of memoizing an ideal-mode function. The trick exploits the fact that [47mec-call[0m allows you to call an ideal-mode function within a [guard]-verified (``Common Lisp compliant'') [47m:[0m[47m[logic][0m mode function without having to verify guards for the ideal-mode function. The following edited log illustrates the points above. ACL2 !>(defun fib (n) (declare (xargs :guard (natp n) :verify-guards nil)) (if (zp n) 0 (if (eql n 1) 1 (+ (fib (- n 1)) (fib (- n 2)))))) [[ .. output omitted .. ]] FIB ACL2 !>(memoize 'fib :ideal-okp t) FIB ACL2 !>(time$ (fib 38)) ; slow: uses only executable-counterpart ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited on recursive calls of the executable-counterpart (i.e., in the ACL2 logic) of FIB. To check guards on all recursive calls: (set-guard-checking :all) To leave behavior unchanged except for inhibiting this message: (set-guard-checking :nowarn) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 3.91 seconds realtime, 3.90 seconds runtime ; (416 bytes allocated). 39088169 ACL2 !>(time$ (fib 38)) ; still slow; no results were stored before ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited on recursive calls of the executable-counterpart (i.e., in the ACL2 logic) of FIB. To check guards on all recursive calls: (set-guard-checking :all) To leave behavior unchanged except for inhibiting this message: (set-guard-checking :nowarn) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 3.92 seconds realtime, 3.91 seconds runtime ; (416 bytes allocated). 39088169 ACL2 !>(defun fib-logic-wrapper (n) ; guard-verified (declare (xargs :guard (natp n))) (ec-call (fib n))) [[ .. output omitted .. ]] FIB-LOGIC-WRAPPER ACL2 !>(memoize 'fib-logic-wrapper) FIB-LOGIC-WRAPPER ACL2 !>(time$ (fib-logic-wrapper 38)) ; slow; no fib results are stored ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited on recursive calls of the executable-counterpart (i.e., in the ACL2 logic) of FIB. To check guards on all recursive calls: (set-guard-checking :all) To leave behavior unchanged except for inhibiting this message: (set-guard-checking :nowarn) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 3.92 seconds realtime, 3.91 seconds runtime ; (2,128 bytes allocated). 39088169 ACL2 !>(time$ (fib-logic-wrapper 38)) ; fast; fib-logic-wrapper result was stored ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.00 seconds realtime, 0.00 seconds runtime ; (16 bytes allocated). 39088169 ACL2 !>(time$ (fib-logic-wrapper 37)) ; slow; result only for 38 was stored ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited on recursive calls of the executable-counterpart (i.e., in the ACL2 logic) of FIB. To check guards on all recursive calls: (set-guard-checking :all) To leave behavior unchanged except for inhibiting this message: (set-guard-checking :nowarn) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 2.42 seconds realtime, 2.42 seconds runtime ; (416 bytes allocated). 24157817 ACL2 !>(defun fib-program-wrapper (n) ; program mode function (declare (xargs :guard (natp n) :mode :program)) (fib n)) Summary Form: ( DEFUN FIB-PROGRAM-WRAPPER ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FIB-PROGRAM-WRAPPER ACL2 !>(time$ (fib-program-wrapper 100)) ; fast because raw-Lisp fib is called ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.00 seconds realtime, 0.00 seconds runtime ; (7,600 bytes allocated). 354224848179261915075 ACL2 !> Two non-[47mnil[0m values are allowed for keyword parameter [47m:ideal-okp[0m: [47m:warn[0m and [47mt[0m. Both of these values allow memoization of ideal-mode functions, but if [47m:warn[0m is supplied then a warning will take place at memoization time, specifically for the resulting [table] event. Note that you may set the key [47m:memoize-ideal-okp[0m of the [47m[ACL2-defaults-table][0m to value [47mt[0m or [47m:warn[0m to change the default, but if parameter [47m:ideal-okp[0m is supplied, the [47m[ACL2-defaults-table][0m value is ignored. The value of [47m:verbose[0m is [47mnil[0m by default, which avoids output that is typically distracting. Otherwise [47mverbose[0m should be [47mt[0m. We can see the types of output that are inhibited by default by using [47m:[0m[47m[trans1][0m as follows follows (most output elided here); see [with-output]. ACL2 !>:trans1 (memoize 'nth :verbose nil) (WITH-OUTPUT :OFF (SUMMARY PROVE EVENT) :GAG-MODE NIL ... ACL2 !> The default for [47m:forget[0m is [47mnil[0m. If [47m:forget[0m is supplied, and not [47mnil[0m, then it must be [47mt[0m, which causes all memoization done for a top-level call of [47mfn[0m to be forgotten when that top-level call exits. Subtopics [Clear-memoize-statistics] Clears all profiling info displayed by [47m([0m[47m[memoize-summary][0m[47m)[0m [Clear-memoize-table] Forget values remembered for the given function [Clear-memoize-tables] Forget values remembered for all the memoized functions [Memoize-partial] [47m[Memoize][0m a partial version of a limited (`clocked') function [Memoize-summary] Display all collected profiling and memoization info [Memsum] Display all collected profiling and memoization info [Never-memoize] Mark a function as unsafe to memoize. [Protect-memoize-statistics] Ensure the integrity of memoization statistics even upon aborts [Restore-memoization-settings] Restore the saved memoization settings [Save-and-clear-memoization-settings] Save and remove the current memoization settings [Set-bad-lisp-consp-memoize] Turn off or on memoization of raw Lisp function [47mbad-lisp-consp[0m [Unmemoize] Turn off memoization for the specified function [Verify-guard-implication] [Guard] implication for [47m[memoize][0m keyword [47m:invoke[0m") (memoize-partial (memoize) "[47m[Memoize][0m a partial version of a limited (`clocked') function See [memoize] for relevant background. Here we describe a utility that supports effective memoization for functions that have been introduced by [47m[defun][0m, as follows, under certain restrictions. (defun fn-limit (x1 ... xn limit) (declare ...) ; optional, as usual for defun ; ; (if (zp limit) <base> (let ((limit (1- limit))) <body>))) Here [47mfn-limit[0m represents a function symbol and [47m(x1 ... xn limit)[0m denotes a non-empty list of formal parameters, where we call the final formal (here, shown as [47mlimit[0m) the ``limit variable''. [47m<Base>[0m is any syntactically legal expression, but [47m<body>[0m is restricted as follows: the occurrences of the limit variable are exactly as the final parameter in each recursive call of [47mfn[0m. More precisely, that restriction must hold after [47m<body>[0m is converted to a translated term (see [term]). In other words, the translation of [47m<body>[0m must have the property that the limit variable only occurs in recursive calls, and in those calls it occurs exactly as the final argument and not in any other arguments. Such use of a ``limit'' argument to obtain termination is an old trick that pre-dates ACL2. Such ``limited'' functions have traditionally often been called ``clocked'' functions. In this documentation we refer to such a function as a ``total'' function, because the limit argument guarantees that its evaluation terminates. We will be generating a corresponding ``partial'' function that avoids the limit argument, and hence might not terminate --- but when it does, it computes the desired value, and uses memoization to do so, which can speed up computation. We organize the rest of this topic as follows: General Form, Basic Example, Example with Mutual Recursion, Detailed Documentation, and Optional Technical Remarks. General Form: (memoize-partial fn+ ; see below :kwd1 val1 ... :kwdn valn) where the supplied [47m:kwdi[0m and [47mvali[0m are valid keywords and values for [47m[memoize][0m. In the simplest case, [47mfn+[0m is a symbol. Later below, after providing an example, we give more complete documentation, including discussion of [47m[mutual-recursion][0m and the general case for [47mfn+[0m. None of the arguments is evaluated. Basic Example The following example from [community-book] file [47mbooks/demos/memoize-partial-input.lsp[0m illustrates the use of [47m[memoize-partial][0m. Consider the {Collatz Conjecture | https://en.wikipedia.org/wiki/Collatz_conjecture}, sometimes known as the 3n+1 problem. For any positive integer [47mn[0m, compute a new integer as [47mn/2[0m if [47mn[0m is even, else as [47m3*n+1[0m. The Collatz conjecture states that this process eventually reaches [47m1[0m. Since this is an open problem, we can't realistically hope to prove termination, so we may code the above algorithm by using a limit argument, as follows. This function returns, unless the limit is reached, the number of steps required for the computation to terminate (reach 1). (defun collatz-limit (n limit) (declare (xargs :guard (and (natp n) (natp limit)) :measure (acl2-count limit))) (if (zp limit) (prog2$ (er hard? 'collatz-limit "Limit exceeded!") 0) (let ((limit (1- limit))) (if (int= n 1) 0 (1+ (collatz-limit (if (evenp n) (floor n 2) (1+ (* 3 n))) limit)))))) A moment's reflection suggests that if this algorithm terminates, then there are no cycles, so memoization from a single call will be useless. However, memoization can be useful if we make distinct calls. But memoization might not be very useful even then, because after we save the result of a call [47m(collatz-limit n0 limit0)[0m, a later call on [47mn0[0m might be with a different limit, say, [47m(collatz-limit n0 limit1)[0m. So we prefer to memoize using the corresponding partial function, without a limit argument. We can do that as follows. (memoize-partial collatz) Under the hood this generates, essentially, the following Common Lisp definition, which is to be memoized. (defun collatz (n) (if (int= n 1) 0 (1+ (collatz (if (evenp n) (floor n 2) (1+ (* 3 n))))))) Since the [47mlimit[0m argument has disappeared, memoization is now more effective. But how can one define [47mcollatz[0m in the ACL2 logic? The [47mmemoize-partial[0m call shown above actually generates the following events, which define [47mcollatz[0m to capture the notion of the ``eventual stable value, as [47mlimit[0m goes to infinity, of [47m(collatz n limit)[0m''. It probably is not important to read these events unless one plans to reason about [47mcollatz[0m, and even then one might be able to complete proofs without reading these events. (DEFCHOOSE COLLATZ-LIMIT-CHANGE (LARGE) (N LIMIT) (AND (NATP LARGE) (<= LIMIT LARGE) (NOT (EQUAL (COLLATZ-LIMIT N LIMIT) (COLLATZ-LIMIT N LARGE))))) (DEFCHOOSE COLLATZ-LIMIT-STABLE (LIMIT) (N) (AND (NATP LIMIT) (EQUAL (COLLATZ-LIMIT N LIMIT) (COLLATZ-LIMIT N (COLLATZ-LIMIT-CHANGE N LIMIT))))) (DEFUN COLLATZ (N) (DECLARE (XARGS :GUARD (LET ((LIMIT 0)) (DECLARE (IGNORABLE LIMIT)) (AND (NATP N) (NATP LIMIT))))) (COLLATZ-LIMIT N (NFIX (COLLATZ-LIMIT-STABLE N)))) The upshot is a logical definition of [47m(collatz n)[0m as the eventual value (if any), as [47mlimit[0m increases without bound, of [47m(collatz n limit)[0m --- together with an installed Common Lisp definition that is actually executed and, moreover, is memoized. We note that the call [47m(memoize-partial collatz)[0m also generates a [47m[table][0m event as well as the form [47m(MEMOIZE 'COLLATZ :TOTAL 'COLLATZ-LIMIT)[0m. However, these details are best ignored by the user; we do not expect those events to be generated by hand, and in particular it is probably inadvisable to use the [47m:TOTAL[0m keyword of [47m[memoize][0m other than indirectly using [47mmemoize-partial[0m. Failure to heed this advice could make failures more difficult to debug. See [community-book] file [47mbooks/demos/memoize-partial-input.lsp[0m for an application of this use of [47mmemoize-partial[0m, to compute the total number of steps required (without accounting for memoization) to run the Collatz algorithm to completion on the first [47mn[0m positive integers. Example with Mutual Recursion The following example, also from [community-book] file [47mbooks/demos/memoize-partial-input.lsp[0m, illustrates the use of [47mmemoize-partial[0m on functions that have been defined using [47m[mutual-recursion][0m. (The suffix ``[47m-bdd[0m'' below is intended to denote ``bounded'', to suggest what the ``[47m-limit[0m'' suffix suggested in the first example.) (mutual-recursion (defun evenlp-bdd (x bound) (declare (xargs :guard (natp bound))) (if (zp bound) 'ouch (let ((bound (1- bound))) (if (consp x) (oddlp-bdd (cdr x) bound) t)))) (defun oddlp-bdd (x bound) (declare (xargs :guard (natp bound))) (if (zp bound) 'ouch (let ((bound (1- bound))) (if (consp x) (evenlp-bdd (cdr x) bound) nil))))) (memoize-partial ((evenlp evenlp-bdd) (oddlp oddlp-bdd))) Notice that this time the argument of [47mmemoize-partial[0m is a list of tuples. Each tuple is a list with two elements: the name of the partial function to be defined, followed by the corresponding total (limited) function that has already been defined. Indeed, the preceding example abbreviates [47m(memoize-partial ((collatz collatz-limit)))[0m. Such abbreviations are discussed in the Detailed Documentation section below. Recall that in the first example, the [47mmemoize-partial[0m call defined functions [47mcollatz-limit-change[0m and [47mcollatz-limit-stable[0m using [47m[defchoose][0m, and then function [47mcollatz[0m using [47m[defun][0m. In the present example such a trio of functions is introduced for each of the functions defined in the corresponding [47mmutual-recursion[0m --- equivalently, for each of the tuples supplied to [47mmemoize-partial[0m. (DEFCHOOSE EVENLP-BDD-CHANGE (LARGE) (X BOUND) (AND (NATP LARGE) (<= BOUND LARGE) (NOT (EQUAL (EVENLP-BDD X BOUND) (EVENLP-BDD X LARGE))))) (DEFCHOOSE EVENLP-BDD-STABLE (BOUND) (X) (AND (NATP BOUND) (EQUAL (EVENLP-BDD X BOUND) (EVENLP-BDD X (EVENLP-BDD-CHANGE X BOUND))))) (DEFUN EVENLP (X) (DECLARE (XARGS :GUARD (LET ((BOUND 0)) (DECLARE (IGNORABLE BOUND)) (NATP BOUND)))) (EVENLP-BDD X (NFIX (EVENLP-BDD-STABLE X)))) (DEFCHOOSE ODDLP-BDD-CHANGE (LARGE) (X BOUND) (AND (NATP LARGE) (<= BOUND LARGE) (NOT (EQUAL (ODDLP-BDD X BOUND) (ODDLP-BDD X LARGE))))) (DEFCHOOSE ODDLP-BDD-STABLE (BOUND) (X) (AND (NATP BOUND) (EQUAL (ODDLP-BDD X BOUND) (ODDLP-BDD X (ODDLP-BDD-CHANGE X BOUND))))) (DEFUN ODDLP (X) (DECLARE (XARGS :GUARD (LET ((BOUND 0)) (DECLARE (IGNORABLE BOUND)) (NATP BOUND)))) (ODDLP-BDD X (NFIX (ODDLP-BDD-STABLE X)))) The corresponding Common Lisp functions, to be executed for [guard]-verified calls of [47mevenlp[0m and [47moddlp[0m, are defined as one might expect, in analogy to the Common Lisp definition in the first example. Moreover, they are memoized. Here are (again, essentially) the Common Lisp definitions of [47mevenlp[0m and [47moddlp[0m. (DEFUN EVENLP (X) (IF (CONSP X) (ODDLP (CDR X)) T)) (DEFUN ODDLP (X) (DECLARE (IGNORABLE X)) (IF (CONSP X) (EVENLP (CDR X)) NIL)) Detailed Documentation Recall the General Form (memoize-partial fn+ ; see below :kwd1 val1 ... :kwdn valn) where the supplied [47m:kwdi[0m and [47mvali[0m represent keyword options to be used for a generated call of [47m[memoize][0m. We discuss later below how [47mfn+[0m specifies either a recursively-defined function symbol or a sequence of function symbols defined by [47mmutual-recursion[0m --- all [guard]-verified. We call the final formal parameter, which must be the same for each function symbol defined in the [47mmutual-recursion[0m case, the ``limit variable''. The translated body (see [term] regarding the notion of ``translated'') of each of these function symbols must be of the following form, or of the corresponding form using [47m[cond][0m in place of [47m[if][0m, where here [47mlimit[0m denotes the limit variable. (if (zp limit) <base> (let ((limit (1- limit))) <body>)) Moreover, each limit variable occurring in [47m<body>[0m must occur as the final argument of a call of the defined function --- in the mutual recursion case, of the functions defined by the [47mmutual-recursion[0m --- and conversely, each such call must have the limit variable as its final argument. Let us refer to each specified function as the ``total'' function. A successful invocation admits a sequence of three definitions for each total function, which we call the ``changed'', ``stable'', and ``partial'' function. Here are those three definitions, where ``[47m...[0m'' denotes the formals of the partial function (that is, the formals of the total function other than the final formal, which is the limit variable). We write [47mLIMIT[0m below to denote the limit variable. Note that [47mLARGE[0m is replaced by a fresh variable when necessary, to avoid duplicating an existing formal. (DEFCHOOSE <changed> (LARGE) (... LIMIT) (AND (NATP LARGE) (<= LIMIT LARGE) (NOT (EQUAL (<total> ... LIMIT) (<total> ... LARGE))))) (DEFCHOOSE <stable> (LIMIT) (...) (AND (NATP LIMIT) (EQUAL (<total> ... LIMIT) (<total> ... (<change> ... LIMIT))))) (DEFUN <partial> (...) (DECLARE (XARGS :GUARD (LET ((LIMIT 0)) (DECLARE (IGNORABLE LIMIT)) <guard_of_total>))) (<total> ... (NFIX (<stable> ...)))) Under the hood, however, a Common Lisp definition is installed for [47m<partial>[0m that avoids the limit variable, essentially by eliminating it in [47m<body>[0m to produce a corresponding term, [47m<body'>[0m, with the following result. (Low-level details about exactly what is generated are discussed in the Optional Technical Remarks below, but should probably be ignored by most users.) (defun <partial> (...) <body'> We turn now to the first argument of [47mmemoize-partial[0m, denoted [47mfn+[0m above, with discussion of its legal forms and its relation to the other (keyword) arguments of [47mmemoize-partial[0m. The most flexible form for [47mfn+[0m is a list of tuples, where each tuple is of the following form and the keyword arguments are optional and in any order. (<partial> <total> :change <change> :stable <stable> :kwd1 val1 ... :kwdn valn) The symbols [47m<partial>[0m, [47m<total>[0m, [47m<change>[0m, and [47m<stable>[0m are as discussed above, and the arguments [47m:kwd1 val1 ... :kwdn valn[0m are as supplied to [47m[memoize][0m. There should be a single tuple in the singly recursive case. In the case that the partial functions were defined by a [47mmutual-recursion[0m defining functions [47mf1[0m, ..., [47mfn[0m, then the [47m<partial>[0m components of the tuples (their [47m[car][0ms) must also be [47mf1[0m, ..., [47mfn[0m. The keyword/value pairs of the tuple are optional. The default for [47m<change>[0m is obtained by adding the suffix [47m"-CHANGE"[0m to [47m<total>[0m, to create a symbol in the same package as that of [47m<total>[0m; similarly for [47m<stable>[0m and the suffix [47m"-STABLE"[0m. The [47m<total>[0m function is defined as described above, with an under-the-hood Common Lisp definition also as described above, and [memoize]d. The [47mmemoize[0m call uses the keywords supplied in the tuple other than [47m:change[0m and [47m:stable[0m. For any [47mmemoize[0m keywords not specified in the tuple, the keywords specified at the top level of the [47mmemoize-partial[0m call --- that is, the keyword arguments (if any) following the first argument (that is, following [47mfn+[0m) --- are also used in that generated [47mmemoize[0m call. There are some abbreviations allowed for [47mfn+[0m, as follows. * A symbol [47mfn[0m for [47mfn+[0m abbreviates the list [47m(fn)[0m, which is an abbreviation as noted below. * If [47mfn+[0m is a list [47m(t1 ... tk)[0m, then each [47mti[0m that is a symbol, say [47mfn[0m, abbreviates the tuple [47m(fn fn-limit)[0m, where [47mfn-limit[0m is obtained by adding the suffix [47m"-LIMIT"[0m to [47mfn[0m, to create a symbol in the same package as that of [47mfn[0m. Consider our first example, [47m(memoize-partial collatz)[0m. In this case [47mfn+[0m is [47mcollatz[0m. By the first rule above, this abbreviates [47m(collatz)[0m, which the second rule says is an abbreviation for [47m(collatz collatz-limit)[0m. The default values are computed to treat this as the following tuple. (collatz collatz-limit :change collatz-limit-change :stable collatz-limit-stable) Note that the keyword value [47m:condition nil[0m for [47mmemoize[0m can be used to install executable definitions without actually saving values, essentially by merely profiling (except that unlike [47m[profile][0m the recursive calls are also affected by the [47mmemoize[0m call). See the example involving ``worse-than'' functions in community book [47mbooks/demos/memoize-partial-input.lsp[0m. We conclude this section by discussing restrictions pertaining to [stobj]s. Recall that memoization is illegal (other than profiling) for functions that return a stobj or have the ACL2 [state] as an input. Those same restrictions apply to [47mmemoize-partial[0m. However, it is legal for the given (``total'') functions to have user-defined stobjs as inputs, as long as they are not returned. In that case, the generated definition of the partial function will be made with a call of [47m[non-exec][0m wrapped around the body. Optional Technical Remarks. Warning: These are technical remarks that are completely optional. Our general remark is to invite readers who want to dive below the user level, including implementation and foundational issues, to read the comment entitled ``Essay on Memoization with Partial Functions (Memoize-partial)'' in ACL2 source file [47mother-events.lisp[0m. Our more specific remark concerns generated Common Lisp definitions. Recall that in the Basic Example above, we say that the Common Lisp definition of [47mcollatz[0m is essentially as follows. (defun collatz (n) (if (int= n 1) 0 (1+ (collatz (if (evenp n) (floor n 2) (1+ (* 3 n))))))) We say ``essentially'' because the actual Common Lisp definition of [47mcollatz[0m is a bit different, as follows. (DEFUN COLLATZ (N) (DECLARE (IGNORABLE N)) (FLET ((COLLATZ-LIMIT (N LIMIT) (DECLARE (IGNORE LIMIT)) (COLLATZ N))) (DECLARE (INLINE COLLATZ-LIMIT)) (LET ((LIMIT 0)) (DECLARE (IGNORABLE LIMIT)) (IF (INT= N 1) 0 (1+ (COLLATZ-LIMIT (IF (EVENP N) (FLOOR N 2) (1+ (* 3 N))) LIMIT)))))) A little reflection will conclude that these two definitions are equivalent. The latter, however, avoids a macroexpansion issue discussed in the aforementioned Essay.") (memoize-summary (memoize) "Display all collected profiling and memoization info Logically, this function just returns [47mnil[0m, but it displays profiling and memoization table information. The profiling statistics may be cleared with [47m([0m[47m[clear-memoize-statistics][0m[47m)[0m. Note that by default, statistics might be inaccurate when calls of [memoize]d functions are aborted. This issue can be avoided, however; see [protect-memoize-statistics].") (memsum (memoize) "Display all collected profiling and memoization info This macro is an abbreviation for [47m[memoize-summary][0m. Logically, it just returns [47mnil[0m. Also see [protect-memoize-statistics].") (merge-sort-lexorder (lists acl2-built-ins) "Sort a list The call [47m(merge-sort-lexorder x)[0m sorts the true-list [47mx[0m using a non-strict total order, [47m[lexorder][0m, on the ACL2 universe.") (meta (rule-classes) "Make a [47m:meta[0m rule (a hand-written simplifier) See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Meta rules extend the ACL2 simplifier with hand-written code to transform certain terms to equivalent ones. To add a meta rule, the [47m:[0m[47m[corollary][0m formula must establish that the hand-written ``metafunction'' preserves the meaning of the transformed term. Examples: (defthm fn-correct-1 ; Modify the rewriter to use fn to (equal (evl x a) ; transform terms that are calls of (evl (fn x) a)) ; nth or of foo. :rule-classes ((:meta :trigger-fns (nth foo)))) (defthm fn-correct-2 ; As above, but this illustrates (implies (and (pseudo-termp x) ; that without loss of generality we (alistp a)) ; may restrict x to be shaped like a (equal (evl x a) ; term and a to be an alist. (evl (fn x) a))) :rule-classes ((:meta :trigger-fns (nth foo)))) (defthm fn-correct-3 ; As above (with or without the (implies (and (pseudo-termp x) ; hypotheses on x and a), with the (alistp a) ; additional restriction that the (evl (hyp-fn x) a)) ; meaning of (hyp-fn x) is true in (equal (evl x a) ; the current context. That is, the (evl (fn x) a))) ; applicability of the transformation :rule-classes ; may be dependent upon some computed ((:meta :trigger-fns (nth foo)))) ; hypotheses. While our intention is that the set of ACL2 documentation topics is self-contained, readers might find it useful to see the following paper for an introduction to meta reasoning in ACL2. W. A. Hunt, Jr., R. B. Krug, M. Kaufmann, J S. Moore and E. W. Smith, ``Meta Reasoning in ACL2.'' TPHOLs 2005, ed. J. Hurd and T. F. Melham, LNCS 3603, Springer-Verlag, Berlin, 2005, pp. 163--178. A non-[47mnil[0m list of function symbols must be supplied as the value of the [47m:trigger-fns[0m field in a [47m:meta[0m rule class object (except that a macro alias can stand in for a function symbol; see [add-macro-alias]). General Forms: (implies (and (pseudo-termp x) ; this hyp is optional (alistp a) ; this hyp is optional (ev (hyp-fn x ...) a) ; this hyp is optional ; meta-extract hyps may also be included (see below) ) (equiv (ev x a) (ev (fn x ...) a))) where [47mequiv[0m is a known [equivalence] relation, [47mx[0m and [47ma[0m are distinct variable names, and [47mev[0m is an evaluator function (see below), and [47mfn[0m is a function symbol, as is [47mhyp-fn[0m when provided. The arguments to [47mfn[0m and [47mhyp-fn[0m should be identical. In the most common case, both take a single argument, [47mx[0m, which denotes the term to be simplified. If [47mfn[0m and/or [47mhyp-fn[0m are [guard]ed, their [guard]s should be trivially implied by [47m[pseudo-termp][0m. We say the theorem above is a ``metatheorem'' or ``metalemma'' and [47mfn[0m is a ``metafunction'', and [47mhyp-fn[0m is a ``hypothesis metafunction''. If ``[47m...[0m'' is empty, i.e., the metafunctions take just one argument, we say they are ``vanilla flavored.'' If ``[47m...[0m'' is non-empty, we say the metafunctions are ``extended.'' Extended metafunctions can access [47m[state][0m and context sensitive information to compute their results, within certain limits. We discuss vanilla metafunctions here and recommend a thorough understanding of them before proceeding (at which time see [extended-metafunctions]). If a metafunction application to a term, [47mu[0m, evaluates to a result of the form [47m(if TEST NEW-TERM u)[0m, then [47mTEST[0m is treated as an ``implicit hypothesis''. For discussion of this relatively advanced feature, see [meta-implicit-hypothesis]. Additional hypotheses are supported, called ``meta-extract hypotheses''. These allow metafunctions to depend on the validity of certain terms extracted from the context or the logical [world]. These hypotheses provide a relatively advanced form of metatheorem so we explain them elsewhere; see [meta-extract]. One might think that metafunctions and (if supplied) hypothesis metafunctions must be executable: that is, not constrained (i.e., introduced in the [signature] of [47m[encapsulate][0m [events]), and not [declare]d [47m:[0m[47m[non-executable][0m. After all, there is no point in installing a simplifier that cannot be run! However, such a restriction is not enforced, because one could introduce a metafunction using [47m[encapsulate][0m and then use [47m[defattach][0m to attach it to an executable function; see [defattach]. We defer discussion of the case in which there is a hypothesis metafunction and for now address the case in which the other two hypotheses are present. In the discussion below, we refer to the argument, [47mx[0m, of [47mfn[0m and [47mhyp-fn[0m as a ``(translated) term,'' i.e., an object satisfying the ACL2 built-in predicate [47mtermp[0m. When these metafunctions are executed by the simplifier, they will be applied to (the quotations of) terms. But during the proof of the metatheorem itself, [47mx[0m may not be the quotation of a term. If the [47m[pseudo-termp][0m hypothesis is omitted, [47mx[0m may be any object. Even with the [47m[pseudo-termp][0m hypothesis, [47mx[0m may merely ``look like a term'' but use non-function symbols or function symbols of incorrect arity. In any case, the metatheorem is stronger than necessary to allow us to apply the metafunctions to terms, as we do in the discussion below. We return later to the question of proving the metatheorem. Suppose the general form of the metatheorem above is proved with the [47m[pseudo-termp][0m and [47m[alistp][0m hypotheses. Then when the simplifier encounters a term, [47m(h t1 ... tn)[0m, that begins with a function symbol, [47mh[0m, listed in [47m:trigger-fns[0m, it applies the metafunction, [47mfn[0m, to the quotation of the term, i.e., it evaluates [47m(fn '(h t1 ... tn))[0m to obtain some result, which can be written as [47m'val[0m. If [47m'val[0m is different from [47m'(h t1 ... tn)[0m and [47mval[0m is a well-formed term (see the next paragraph), then [47m(h t1 ... tn)[0m is replaced by [47mval[0m, which is then passed along for further rewriting. Because the metatheorem establishes the correctness of [47mfn[0m for all terms (even non-terms!), there is no restriction on which function symbols are listed in the [47m:trigger-fns[0m. Generally, of course, they should be the symbols that head up the terms simplified by the metafunction [47mfn[0m. Note that the result of applying a metafunction (or a hypothesis metafunction) must be a term, i.e., must satisfy the predicate [47m[termp][0m in the current logical [world]. If not, then an error occurs. See [term-table] for how one obtains some assistance towards testing that [47mval[0m is indeed a term. ACL2 actually enforces a stronger requirement, disallowing calls of certain ``forbidden'' function symbols as described in [47m[set-skip-meta-termp-checks][0m. Both of these runtime checks can be avoided by proving that the metafunction (and the corresponding hypothesis metafunction, if any) always produces an acceptable term. See [well-formedness-guarantee]. Alternatively, with an active trust tag (see [defttag]) you can tell ACL2 to skip these tests; see [47m[set-skip-meta-termp-checks][0m. The ``evaluator'' function, [47mev[0m, is a function that can evaluate a certain class of expressions, namely, all of those composed of variables, constants, and applications of a fixed, finite set of function symbols, [47mg1[0m, ..., [47mgk[0m. Generally speaking, the set of function symbols handled by [47mev[0m is chosen to be exactly the function symbols recognized and manipulated by the metafunctions being introduced. For example, if [47mfn[0m manipulates expressions in which [47m'[0m[47m[equal][0m and [47m'[0m[47m[binary-append][0m occur as function symbols, then [47mev[0m is generally specified to handle [47m[equal][0m and [47m[binary-append][0m. The actual requirements on [47mev[0m become clear when the metatheorem is proved. The standard way to introduce an evaluator is to use the ACL2 macro [47m[defevaluator][0m, though this is not strictly necessary. See [defevaluator] if you want details. [Aside for the logic-minded.] Why are we justified in using metafunctions this way? Suppose [47m(fn 'term1)[0m is [47m'term2[0m. What justifies replacing [47mterm1[0m by [47mterm2[0m? The first step is to assert that [47mterm1[0m is [47m(ev 'term1 a)[0m, where [47ma[0m is an alist that maps [47m'var[0m to [47mvar[0m, for each variable [47mvar[0m in [47mterm1[0m. This step is incorrect, because [47m'term1[0m may contain function symbols other than the ones, [47mg1[0m, ..., [47mgk[0m, that [47mev[0m knows how to handle. But we can grow [47mev[0m to a ``larger'' evaluator, [47mev*[0m, an evaluator for all of the symbols that occur in [47mterm1[0m or [47mterm2[0m. We can prove that [47mev*[0m satisfies the [constraint]s on [47mev[0m, provided no [47m[defaxiom][0m events are adding constraints to [47mev[0m (or callers of [47mev[0m, and recursively); ACL2 checks this additional property. Hence, the metatheorem holds for [47mev*[0m in place of [47mev[0m, by functional instantiation. We can then carry out the proof of the [equivalence] of [47mterm1[0m and [47mterm2[0m as follows: Fix [47ma[0m to be an alist that maps the quotations of the variables of [47mterm1[0m and [47mterm2[0m to themselves. Then, term1 = (ev* 'term1 a) ; (1) by construction of ev* and a = (ev* (fn 'term1) a) ; (2) by the metatheorem for ev* = (ev* 'term2 a) ; (3) by evaluation of fn = term2 ; (4) by construction of ev* and a Note that in line (2) above, where we appeal to the (functional instantiation of the) metatheorem, we can relieve its (optional) [47m[pseudo-termp][0m and [47m[alistp][0m hypotheses by appealing to the facts that [47mterm1[0m is a term and [47ma[0m is an alist by construction. [End of Aside for the logic-minded.] There are subtleties related to the notion of ``growing'' [47mev[0m to a ``larger'' evaluator, as mentioned in the paragraph just above. For corresponding restrictions on [47m:meta[0m rules, see [evaluator-restrictions]. Finally, we turn to the second case, in which there is a hypothesis metafunction. In that case, consider as before what happens when the simplifier encounters a term, [47m(h t1 ... tn)[0m, where [47mh[0m is listed in [47m:trigger-fns[0m. This time, after it applies [47mfn[0m to [47m'(h t1 ... tn)[0m to obtain the quotation of some new term, [47m'val[0m, it then applies the hypothesis metafunction, [47mhyp-fn[0m. That is, it evaluates [47m(hyp-fn '(h t1 ... tn))[0m to obtain some result, which can be written as [47m'hyp-val[0m. If [47mhyp-val[0m is not in fact a term, the metafunction is not used. Provided [47mhyp-val[0m is a term, the simplifier attempts to establish (by conventional backchaining) that this term is non-[47mnil[0m in the current context. Note that this backchaining is done just as it is done for hypotheses of [rewrite] (and [linear]) rules, namely, by rewriting with special attention to calls of certain functions including [47m[force][0m, [47m[case-split][0m, [47m[syntaxp][0m, and [47m[bind-free][0m. If this attempt to establish this term fails, then the meta rule is not applied. Otherwise, [47m(h t1...tn)[0m is replaced by [47mval[0m as in the previous case (where there was no hypothesis metafunction). Why is it justified to make this extension to the case of hypothesis metafunctions? First, note that the rule (implies (and (pseudo-termp x) (alistp a) (ev (hyp-fn x) a)) (equal (ev x a) (ev (fn x) a))) is logically equivalent to the rule (implies (and (pseudo-termp x) (alistp a)) (equal (ev x a) (ev (new-fn x) a))) where [47m(new-fn x)[0m is defined to be [47m(list 'if (hyp-fn x) (fn x) x)[0m. (If we're careful, we realize that this argument depends on making an extension of [47mev[0m to an evaluator [47mev*[0m that handles [47m[if][0m and the functions manipulated by [47mhyp-fn[0m.) If we write [47m'term[0m for the quotation of the present term, and if [47m(hyp-fn 'term)[0m and [47m(fn 'term)[0m are both terms, say [47mhyp1[0m and [47mterm1[0m, then by the previous argument we know it is sound to rewrite term to [47m(if hyp1 term1 term)[0m. But since we have established in the current context that [47mhyp1[0m is non-[47mnil[0m, we may simplify [47m(if hyp1 term1 term)[0m to [47mterm1[0m, as desired. We now discuss the role of the [47m[pseudo-termp][0m hypothesis. [47m(Pseudo-termp x)[0m checks that [47mx[0m has the shape of a term. Roughly speaking, it ensures that [47mx[0m is a symbol, a quoted constant, or a true list consisting of a [47mlambda[0m expression or symbol followed by some pseudo-terms. Among the properties of terms not checked by [47m[pseudo-termp][0m are that variable symbols never begin with ampersand, [47mlambda[0m expressions are closed, and function symbols are applied to the correct number of arguments. See [pseudo-termp]. There are two possible roles for [47m[pseudo-termp][0m in the development of a metatheorem: it may be used as the [guard] of the metafunction and/or hypothesis metafunction and it may be used as a hypothesis of the metatheorem. Generally speaking, the [47m[pseudo-termp][0m hypothesis is included in a metatheorem only if it makes it easier to prove. The choice is yours. (An extreme example of this is when the metatheorem is invalid without the hypothesis!) We therefore address ourselves the question: should a metafunction have a [47m[pseudo-termp][0m [guard]? A [47m[pseudo-termp][0m [guard] for a metafunction, in connection with other considerations described below, improves the efficiency with which the metafunction is used by the simplifier. To make a metafunction maximally efficient you should (a) provide it with a [47m[pseudo-termp][0m [guard] and exploit the [guard] when possible in coding the body of the function (see [guards-and-evaluation], especially the section on efficiency issues), (b) verify the [guard]s of the metafunction (see [verify-guards]), and (c) compile the metafunction (see [comp]). When these three steps have been taken the simplifier can evaluate [47m(fn 'term1)[0m by running the compiled ``primary code'' (see [guards-and-evaluation]) for [47mfn[0m directly in Common Lisp. (Note however that explicit compilation may be suppressed; see [compilation].) Before discussing efficiency issues further, let us review for a moment the general case in which we wish to evaluate [47m(fn 'obj)[0m for some [47m:[0m[47m[logic][0m function. We must first ask whether the [guard]s of [47mfn[0m have been verified. If not, we must evaluate [47mfn[0m by executing its logic definition. This effectively checks the [guard]s of every subroutine and so can be slow. If, on the other hand, the [guard]s of [47mfn[0m have been verified, then we can run the primary code for [47mfn[0m, provided [47m'obj[0m satisfies the [guard] of [47mfn[0m. So we must next evaluate the [guard] of [47mfn[0m on [47m'obj[0m. If the [guard] is met, then we run the primary code for [47mfn[0m, otherwise we run the logic code. Now in the case of a metafunction for which the three steps above have been followed, we know the [guard] is (implied by) [47m[pseudo-termp][0m and that it has been verified. Furthermore, we know without checking that the [guard] is met (because [47mterm1[0m is a term and hence [47m'term1[0m is a [47m[pseudo-termp][0m). Hence, we can use the compiled primary code directly. We strongly recommend that you compile your metafunctions, as well as all their subroutines (unless explicit compilation is suppressed; see [compilation]). Guard verification is also recommended. Finally, we present a very simple example of the use of [47m:meta[0m rules, based on one provided by Robert Krug. This example illustrates a trick for avoiding undesired rewriting after applying a metafunction or any other form of rewriting. To elaborate: in general, the term [47mt2[0m obtained by applying a metafunction to a term [47mt1[0m is then handed immediately to the rewriter, which descends recursively through the arguments of function calls to rewrite [47mt2[0m completely. But if [47mt2[0m shares a lot of structure with [47mt1[0m, then it might not be worthwhile to rewrite [47mt2[0m immediately. (A rewrite of [47mt2[0m will occur anyhow the next time a goal is generated.) The trick involves avoiding this rewrite by wrapping [47mt2[0m inside a call of [47m[hide][0m, which in turn is inside a call of a user-defined ``unhiding'' function, [47munhide[0m. (defun unhide (x) (declare (xargs :guard t)) x) (defthm unhide-hide (equal (unhide (hide x)) x) :hints (("Goal" :expand ((hide x))))) (in-theory (disable unhide)) (defun my-plus (x y) (+ x y)) (in-theory (disable my-plus)) (defevaluator evl evl-list ((my-plus x y) (binary-+ x y) (unhide x) (hide x))) (defun meta-fn (term) (declare (xargs :guard (pseudo-termp term))) (if (and (consp term) (equal (length term) 3) (equal (car term) 'my-plus)) `(UNHIDE (HIDE (BINARY-+ ,(cadr term) ,(caddr term)))) term)) (defthm my-meta-lemma (equal (evl term a) (evl (meta-fn term) a)) :hints (("Goal" :in-theory (enable my-plus))) :rule-classes ((:meta :trigger-fns (my-plus)))) Notice that in the following (silly) conjecture, ACL2 initially does only does the simplification directed by the metafunction; a second goal is generated before the commutativity of addition can be applied. If the above calls of [47mUNHIDE[0m and [47mHIDE[0m had been stripped off, then [47mGoal'[0m would have been the term printed in [47mGoal''[0m below. ACL2 !>(thm (equal (my-plus b a) ccc)) This simplifies, using the :meta rule MY-META-LEMMA and the :rewrite rule UNHIDE-HIDE, to Goal' (EQUAL (+ B A) CCC). This simplifies, using the :rewrite rule COMMUTATIVITY-OF-+, to Goal'' (EQUAL (+ A B) CCC). The discussion above probably suffices to make good use of this [47m(UNHIDE (HIDE ...))[0m trick. However, we invite the reader who wishes to understand the trick in depth to evaluate the following form before submitting the [47m[thm][0m form above. (trace$ (rewrite :entry (list (take 2 arglist)) :exit (list (car values))) (rewrite-with-lemma :entry (list (take 2 arglist)) :exit (take 2 values))) The following annotated subset of the trace output (which may appear a bit different depending on the underlying Common Lisp implementation) explains how the trick works. 2> (REWRITE ((MY-PLUS B A) NIL))> 3> (REWRITE-WITH-LEMMA ((MY-PLUS B A) (REWRITE-RULE (:META MY-META-LEMMA) 1822 NIL EQUAL META-FN NIL META NIL NIL)))> We apply the meta rule, then recursively rewrite the result, which is the (UNHIDE (HIDE ...)) term shown just below. 4> (REWRITE ((UNHIDE (HIDE (BINARY-+ B A))) ((A . A) (B . B))))> 5> (REWRITE ((HIDE (BINARY-+ B A)) ((A . A) (B . B))))> The HIDE protects its argument from being touched by the rewriter. <5 (REWRITE (HIDE (BINARY-+ B A)))> 5> (REWRITE-WITH-LEMMA ((UNHIDE (HIDE (BINARY-+ B A))) (REWRITE-RULE (:REWRITE UNHIDE-HIDE) 1806 NIL EQUAL (UNHIDE (HIDE X)) X ABBREVIATION NIL NIL)))> Now we apply UNHIDE-HIDE, then recursively rewrite its right-hand side in an environment where X is bound to (BINARY-+ B A). 6> (REWRITE (X ((X BINARY-+ B A))))> Notice that at this point X is cached, so REWRITE just returns (BINARY-+ B A). <6 (REWRITE (BINARY-+ B A))> <5 (REWRITE-WITH-LEMMA T (BINARY-+ B A))> <4 (REWRITE (BINARY-+ B A))> <3 (REWRITE-WITH-LEMMA T (BINARY-+ B A))> <2 (REWRITE (BINARY-+ B A))> Subtopics [Backchain-limit] Limiting the effort expended on relieving hypotheses [Case-split] Like force but immediately splits the top-level goal on the hypothesis [Evaluator-restrictions] Some restrictions on the use of evaluators in meta-level rules [Extended-metafunctions] State and context sensitive metafunctions [Force] Identity function used to force a hypothesis [Magic-ev-fncall] Call the named function on the given arguments and return the value. [Meta-extract] Meta reasoning using valid terms extracted from context or [world] [Meta-implicit-hypothesis] A potentially more efficient way of coding a hypothesis metafunction [Set-skip-meta-termp-checks] Skip output checks for [meta] functions and [clause-processor]s [Set-skip-meta-termp-checks!] Skip output checks non-[local]ly for [meta] functions and [clause-processor]s [Syntaxp] Attach a heuristic filter on a rule [Term-table] A table used to validate meta rules [Transparent-functions] Working around restrictions on the use of evaluators in meta-level rules") (meta-extract (meta clause-processor) "Meta reasoning using valid terms extracted from context or [world] For this advanced topic, we assume familiarity with metatheorems and metafunctions (see [meta]), as well as extended metafunctions (see [extended-metafunctions]). The capability described here --- so-called ``meta-extract hypotheses'' for a [47m:[0m[47m[meta][0m or a [47m:[0m[47m[clause-processor][0m rule --- provides an advanced form of meta-level reasoning that was initially designed largely by Sol Swords, who also provided a preliminary implementation. A meta rule or clause-processor rule may have so-called ``meta-extract'' hypotheses that take forms displayed below. Here [47mevl[0m is the evaluator, [47mobj[0m is an arbitrary term, [47mmfc[0m is the metafunction context (which is a variable other than the symbol [47mSTATE[0m that represents the metafunction context; see [extended-metafunctions]), [47mstate[0m is literally the symbol [47mSTATE[0m, [47ma[0m is the second argument of [47mevl[0m in both arguments of the conclusion of the rule, and [47maa[0m is an arbitrary term. (evl (meta-extract-contextual-fact obj mfc state) a) (evl (meta-extract-global-fact obj state) aa) ; equivalent to the next form (evl (meta-extract-global-fact+ obj state state) aa) (evl (meta-extract-global-fact+ obj st state) aa) The first form is only legal for [47m:meta[0m rules for which the metafunction is an extended metafunction. The remaining forms are legal for both [47m:meta[0m rules and [47m:clause-processor[0m rules. Sol Swords has contributed a community book, [47mclause-processors/meta-extract-user.lisp[0m, that uses a Skolemization trick to allow one to use at most one [47mmeta-extract-global-fact+[0m hypothesis and at most one [47mmeta-extract-contextual-fact[0m hypothesis. These additional hypotheses may be necessary in order to prove a proposed metatheorem or (for the second type of hypothesis above) clause-processor rule, in particular when the correctness of the metafunction depends on the correctness of utilities extracting formulas from the logical [world] or (for the first type) facts from the metafunction context (mfc). After the rule is proved, however, the meta-extract hypotheses have no effect on how the rule is applied during a proof. An argument for correctness of using meta-extract hypotheses is given in the ACL2 source code within a comment entitled ``Essay on Correctness of Meta Reasoning''. In the documentation below, we focus primarily on [47m:[0m[47m[meta][0m rules, since the use of [47mmeta-extract-global-fact[0m hypotheses in [47m:[0m[47m[clause-processor][0m rules is entirely analogous. (At the end, though, we discuss the last of the four forms displayed above.) And for [47m:meta[0m rules we focus not on the application of rules but, rather, on how the use of meta-extract hypotheses allow you to prove correctness of metafunctions that use facts from the logical [world] or the metafunction context (mfc). Below we describe properties of [47mmeta-extract-contextual-fact[0m and [47mmeta-extract-global-fact[0m, but only after we illustrate their utility with an example. But even before we present that example, we first give a sense of how to think about these functions by showing a theorem that one can prove about the first of them. If this snippet doesn't help your intuition, then just skip over it and start with the example. (defevaluator evl evl-list ((binary-+ x y) (typespec-check x y))) (thm (implies (not (bad-atom (cdr (assoc-equal 'x alist)))) (equal (evl (meta-extract-contextual-fact (list :typeset 'x) mfc state) alist) (not (equal 0 ; indicates non-empty intersection (logand (type-set-quote ; type-set of a constant (cdr (assoc-equal 'x alist))) (mfc-ts-fn 'x mfc state nil))))))) Next we present an example, which comes from the community book, [47mbooks/clause-processors/meta-extract-simple-test.lisp[0m. That book presents very basic, contrived examples that nevertheless illustrate meta-extract hypotheses. For a more interesting tutorial example, see the community book [47mbooks/demos/nth-update-nth-meta-extract.lisp[0m. Our example includes this meta rule. (defthm plus-identity-2-meta (implies (and (nthmeta-ev (meta-extract-global-fact '(:formula bar-posp) state) (list (cons 'u (nthmeta-ev (cadr (cadr term)) a)))) (nthmeta-ev (meta-extract-contextual-fact `(:typeset ,(caddr term)) mfc state) a)) (equal (nthmeta-ev term a) (nthmeta-ev (plus-identity-2-metafn term mfc state) a))) :rule-classes ((:meta :trigger-fns (binary-+)))) The two hypotheses illustrate the two basic kinds of meta-extract hypotheses: applications of the evaluator to a call of [47mmeta-extract-global-fact[0m and to a call of [47mmeta-extract-contextual-fact[0m. Here is the definition of the metafunction used in the above rule, slightly simplified here from what is found in the above book (but adequate for proving the two events that follow it in the above book). (defun plus-identity-2-metafn (term mfc state) (declare (xargs :stobjs state :verify-guards nil)) (case-match term (('binary-+ ('bar &) y) (cond ((equal (meta-extract-formula 'bar-posp state) '(POSP (BAR U))) (if (ts= (mfc-ts y mfc state :forcep nil) *ts-character*) (cadr term) term)) (t term))) (& term))) This metafunction returns its input term unchanged except in the case that the term is of the form [47m(binary-+ (bar x) y)[0m and the following two conditions are met, in which case it returns [47m(bar x)[0m. (1) (equal (meta-extract-formula 'bar-posp state) '(POSP (BAR U))) (2) (ts= (mfc-ts y mfc state :forcep nil) *ts-character*) So suppose that term is [47m(list 'binary-+ (list 'bar x) y)[0m. We show how the meta-extract hypotheses together with (1) and (2) imply that the conclusion of the above [47m:meta[0m rule holds. Here is that conclusion after a bit of simplification. (equal (nthmeta-ev (list 'binary-+ (list 'bar x) y) a) (nthmeta-ev (list 'bar x) a)) This equality simplifies as follows using the evaluator properties of [47mnthmeta-ev[0m. (equal (binary-+ (bar (nthmeta-ev x a)) (nthmeta-ev y a)) (bar (nthmeta-ev x a))) Since a positive number plus a character is that number, it clearly suffices to show: (A) (posp (bar (nthmeta-ev x a))) (B) (characterp (nthmeta-ev y a)) It remains then to show that these follow from (1) and (2) together with the meta-extract hypotheses. First consider (A). We show that it is just a simplification of the first meta-extract hypothesis. (nthmeta-ev (meta-extract-global-fact '(:formula bar-posp) state) (list (cons 'u (nthmeta-ev (cadr (cadr term)) a)))) = {by our assumption that term is (list 'binary-+ (list 'bar x) y)} (nthmeta-ev (meta-extract-global-fact '(:formula bar-posp) state) (list (cons 'u (nthmeta-ev x a)))) = {by definition of meta-extract-global-fact, as discussed later} (nthmeta-ev (meta-extract-formula 'bar-posp state) (list (cons 'u (nthmeta-ev x a)))) = {by (1)} (nthmeta-ev '(posp (bar u)) (list (cons 'u (nthmeta-ev x a)))) = {by evaluator properties of nthmeta-ev} (posp (bar (nthmeta-ev x a))) Now consider (B). We show that it is just a simplification of the second meta-extract hypothesis. (nthmeta-ev (meta-extract-contextual-fact `(:typeset ,(caddr term)) mfc state) a) = {by our assumption that term is (list 'binary-+ (list 'bar x) y)} (nthmeta-ev (meta-extract-contextual-fact (list ':typeset y) mfc state) a) = {by definition of meta-extract-contextual-fact, as discussed later} (nthmeta-ev (list 'typespec-check (list 'quote (mfc-ts y mfc state :forcep nil)) y) a) = {by (2)} (nthmeta-ev (list 'typespec-check (list 'quote *ts-character*) y) a) = {by evaluator properties of nthmeta-ev} (typespec-check *ts-character* (nthmeta-ev y a)) = {by definition of typespec-check} (characterp (nthmeta-ev y a)) Note the use of [47m:forcep nil[0m above. All of the [47mmfc-xx[0m functions take a keyword argument [47m:forcep[0m. Calls of [47mmfc-xx[0m functions made on behalf of [47mmeta-extract-contextual-fact[0m always use [47m:forcep nil[0m, so in order to reason about these calls in your own metafunctions, you will want to use [47m:forcep nil[0m. We have contemplated adding a utility like [47mmeta-extract-contextual-fact[0m that allows forcing but returns a tag-tree (see [ttree]), and may do so if there is demand for it. Finally, we document what is provided logically by calls of [47mmeta-extract-global-fact[0m and [47mmeta-extract-contextual-fact[0m. Of course, you are invited to look at the definitions of these functions in the ACL2 source code, or by using [47m:[0m[47m[pe][0m. Note that both of these functions are non-executable (each of their bodies is inside a call of [47m[non-exec][0m); their purpose is purely logical, not for execution. The functions return [47m*t*[0m, i.e., [47m(quote t)[0m, in cases that they provide no information. First we consider the value of [47m(meta-extract-global-fact obj state)[0m for various values of [47mobj[0m. When we refer below to concepts like ``body'' and ``evaluation'', we refer to these with respect to the logical world of the input [47mstate[0m. CASE [47mobj[0m = [47m(list :formula FN)[0m: In this case [47m(meta-extract-global-fact obj state)[0m is equal to [47m(meta-extract-formula FN state)[0m. That, in turn, evaluates to the ``formula'' of [47mFN[0m in the following sense when [47mstate[0m is the ACL2 ``live'' [state] object. If [47mFN[0m is a function symbol with formals [47m(X1 ... Xk)[0m, then the formula is the [constraint] on [47mFN[0m if [47mFN[0m is constrained or introduced by [47m[defchoose][0m, and otherwise is [47m(equal (FN X1 ... Xk) BODY)[0m, where [47mBODY[0m is the (unsimplified) body of the definition of [47mFN[0m. Otherwise, if [47mFN[0m is the name of a theorem, the formula is just what is stored for that theorem. Otherwise, the formula is [47m*t*[0m. CASE [47mobj[0m = [47m(list :lemma FN N)[0m: Assume [47mN[0m is a natural number; otherwise, treat [47mN[0m as 0. Then [47m(meta-extract-global-fact obj state)[0m is equal to the term naturally constructed from the [47mrewrite-rule[0m record structure [47m(nth N (getpropc FN 'lemmas nil (w state)))[0m if [47mN[0m is in range, else [47m*t*[0m. (The ACL2 source function [47mrewrite-rule-term[0m does this construction of a term from a [47mrewrite-rule[0m record structure. It has a guard of [47mt[0m; a version that may execute more quickly but has a less trivial guard is [47mrewrite-rule-term-exec[0m.) Thus, if [47mFN[0m is a function symbol with more than [47mN[0m associated lemmas --- ``associated'' in the sense of being either a [47m:[0m[47m[definition][0m rule for [47mFN[0m or a [47m:[0m[47m[rewrite][0m rule for [47mFN[0m whose left-hand side has a top function symbol of [47mFN[0m --- then when [47mstate[0m is the actual ACL2 ``live'' [state] object, [47m(meta-extract-global-fact obj state)[0m evaluates to the [47mN[0mth such lemma (with zero-based indexing). CASE [47mobj[0m = [47m(list :linear-lemma FN N)[0m: Assume [47mN[0m is a natural number; otherwise, treat [47mN[0m as 0. Then [47m(meta-extract-global-fact obj state)[0m is equal to the term naturally constructed from the [47mlinear-lemma[0m record structure [47m(nth N (getpropc FN 'linear-lemmas nil (w state)))[0m if [47mN[0m is in range, else [47m*t*[0m. (The ACL2 source function [47mlinear-lemma-term[0m does this construction of a term from a [47mlinear-lemma[0m record structure. It has a guard of [47mt[0m; a version that may execute more quickly but has a less trivial guard is [47mlinear-lemma-term-exec[0m.) Thus, if [47mFN[0m is a function symbol with more than [47mN[0m associated linear-lemmas --- ``associated'' in the sense of being a [47m:[0m[47m[linear][0m rule that has a max-term whose top function symbol is [47mFN[0m --- then when [47mstate[0m is the actual ACL2 ``live'' [state] object, [47m(meta-extract-global-fact obj state)[0m evaluates to the [47mN[0mth such linear lemma (with zero-based indexing). CASE [47mobj[0m = [47m(list :fncall FN ARGLIST)[0m: Consider the term [47m(magic-ev-fncall FN ARGLIST state t nil)[0m, which is axiomatized to return a multiple values pair [47m(mv erp val)[0m, and moreover: if [47mstate[0m is the actual ACL2 ``live'' [state] and [47merp[0m is [47mnil[0m, then [47mval[0m is the result of applying [47mfn[0m to [47marglist[0m. For example, after submitting [47m(defun foo (z) (mv (cdr z) (car z)))[0m, we can evaluate a corresponding call of [47mmagic-ev-fncall[0m as follows, noting that for this purpose the macro [47m[mv][0m is given its logical meaning, [47m[list][0m: ACL2 !>(magic-ev-fncall 'foo '((a b c)) state t nil) (NIL ((B C) A)) ACL2 !> Let [47merp[0m and [47mval[0m be as above: more precisely, let them abbreviate the terms [47m(nth '0 (magic-ev-fncall FN ARGLIST state t nil))[0m and [47m(nth '1 (magic-ev-fncall FN ARGLIST state t nil))[0m, respectively. Then [47m(meta-extract-global-fact obj state)[0m is either [47m*t*[0m, in the ``error case'' that [47merp[0m is not [47mnil[0m, or else is a term that equates [47mval[0m with the application of [47mFN[0m to [47mARGLIST[0m, as follows. Assume that [47mFN[0m is a [47m:[0m[47m[logic][0m-mode function symbol and that [47mARGLIST[0m is a true list of values of the same length as list of formal parameters for [47mFN[0m (i.e., as the input arity of [47mFN[0m). Let [47m(QARG1 ... QARGk)[0m be the result of quoting each element of [47mARGLIST[0m, i.e., replacing each [47my[0m in [47mARGLIST[0m by the two-element list [47m(quote y)[0m. Then [47m(meta-extract-global-fact obj state)[0m reduces to the term [47m(equal (FN QARG1 ... QARGk) (quote val))[0m. CASE otherwise: For any other values of [47mobj[0m, the value is [47m*t*[0m. Finally, the value of [47m(meta-extract-contextual-fact obj mfc state)[0m is as follows for various values of [47mobj[0m. Note a difference from the semantics of [47mmeta-extract-global-fact[0m: below, the relevant logical world is the one stored in the metafunction context, [47mmfc[0m, not in the input [47mstate[0m. CASE [47mobj[0m = (list :typeset TERM ...): The value is the value of [47m(typespec-check ts TERM)[0m, where [47mts[0m is the value of [47m(mfc-ts TERM mfc state :forcep nil :ttreep nil)[0m, and where [47m(typespec-check ts val)[0m is defined to be true when [47mval[0m has type-set [47mts[0m. (Exception: If [47mval[0m satisfies [47mbad-atom[0m then [47mtypespec-check[0m is true when [47mts[0m is negative.) CASE [47mobj[0m = (list :rw+ TERM ALIST OBJ EQUIV ...): We assume below that [47mEQUIV[0m is a symbol that represents an equivalence relation, where [47mnil[0m represents [47m[equal][0m, [47mt[0m represents [47m[iff][0m, and otherwise [47mEQUIV[0m represents itself (an equivalence relation in the current logical [world]). For any other [47mEQUIV[0m the value is [47m*t*[0m. Now let [47mrhs[0m be the value of [47m(mfc-rw+ TERM ALIST OBJ EQUIV mfc state :forcep nil :ttreep nil)[0m. Then the value is the term [47m(list 'equv (sublis-var ALIST TERM) rhs)[0m, where equv is the equivalence relation represented by [47mEQUIV[0m, and [47msublis-var[0m is defined to substitute a variable-binding alist into a term. CASE [47mobj[0m = (list :rw TERM OBJ EQUIV ...): The value is the same as above but for an [47mALIST[0m of [47mnil[0m, i.e., for the case that [47mobj[0m is [47m(list :rw+ TERM nil OBJ EQUIV ...)[0m. CASE [47mobj[0m = (list :ap TERM ...): The value is [47m(list 'not TERM)[0m if [47m(mfc-ap TERM mfc state :forcep nil)[0m is true, else is [47m*t*[0m. CASE [47mobj[0m = (list :relieve-hyp HYP ALIST RUNE TARGET BKPTR ...): The value is [47m(sublis-var alist hyp)[0m --- see above for a discussion of [47msublis-var[0m --- if the following is true. (mfc-relieve-hyp hyp alist rune target bkptr mfc state :forcep nil :ttreep nil) Otherwise the value is [47m*t*[0m. CASE otherwise: If no case above applies, then the value is [47m*t*[0m. We conclude by considering the fourth of the four forms above (and implicitly, its special case represented by the third form above): (evl (meta-extract-global-fact+ obj st state) aa) The discussion above is for the function [47mmeta-extract-global-fact+[0m, but assumes that the logical [world]s of [47mst[0m and [47mstate[0m are equal; otherwise the value returned is [47m*t*[0m. Of course, since a call of [47mmeta-extract-global-fact[0m expands to a corresponding call of [47mmeta-extract-global-fact+[0m in which the last two arguments are both [47mstate[0m, that condition holds automatically for that case. But the [47mstate[0m mentioned in the meta-extract hypotheses of a [meta] rule or [clause-processor] rule is in essence an initial state. In the case of a clause-processor rule, the clause-processor function may modify that initial state (say, by printing or modifying some state globals) without changing its world, and then pass that modified state to [47mfncall-term[0m. While [47mfncall-term[0m may produce a different result for this modified state than for the initial state, both are valid: other than its world, the state is used only for heuristic purposes, such as determining whether guard-checking may cause an error. A useful instance of the hypothesis displayed above will be one in which [47mst[0m is that modified state.") (meta-extract-contextual-fact (pointers) "See [meta-extract].") (meta-extract-formula (pointers) "See [meta-extract].") (meta-extract-global-fact (pointers) "See [meta-extract].") (meta-extract-global-fact+ (pointers) "See [meta-extract].") (meta-extract-rw+-term (pointers) "See [meta-extract].") (meta-implicit-hypothesis (meta) "A potentially more efficient way of coding a hypothesis metafunction We assume familiarity with [meta] rules. In this topic, we discuss a relatively advanced capability of meta reasoning in ACL2 that can increase its efficiency. Introduction In brief: if a metafunction application to a term, [47mu[0m, evaluates to a result of the form [47m(if TEST NEW-TERM u)[0m, then [47mTEST[0m is treated as an ``implicit hypothesis,'' which must rewrite to true in order for the meta rule to simplify the input term. We now explain in more detail. Recall the general form of a meta rule: (implies (and (pseudo-termp x) ; this hyp is optional (alistp a) ; this hyp is optional (ev (hyp-fn x ...) a) ; this hyp is optional ; meta-extract hyps may also be included (see below) ) (equiv (ev x a) (ev (fn x ...) a))) When this rule is to be applied to a term, [47mx[0m, then [47m(hyp-fn x ...)[0m is evaluated to produce a term, which must rewrite to true in order to evaluate the call [47m(fn x ...)[0m, which is then rewritten to a replacement for [47mx[0m. But it may be that these calls of [47mhyp-fn[0m and [47mfn[0m share a sub-computation. ACL2 provides the ``implicit hypothesis'' mechanism in order to share such a sub-computation. The next section illustrates how this mechanism works. The final section provides a precise specification of implicit hypotheses and how they are used in metareasoning. Example The following example is trivial but illustrates the sort of situation for which implicit hypotheses can be useful. First let us introduce a function and an evaluator (see [defevaluator]). (defun foo (x y) (+ x y)) (defevaluator evl evl-list ((if x y z) (foo x y) (binary-+ x y) (unary-- x) (acl2-numberp x) (not x))) Let us write a meta function and associated hypothesis metafunction that apply a common function, [47mmeta-helper[0m, to a term, [47mterm[0m, to return one of two multiple values: [47m(mv nil term)[0m in the case that there is no simplification; else [47m(mv hyp new-term)[0m, where the following is a theorem: `(implies ,hyp (equal ,term ,new-term)). Of course, the following definition introduces a function whose calls can be evaluated very quickly; but for purposes of this example, let us pretend that calls of [47mmeta-helper[0m take a great deal of time to evaluate. (defun meta-helper (term) ; PRETEND that his function is expensive to compute! (declare (xargs :guard (pseudo-termp term))) (case-match term (('foo x ('foo y ('unary-- x))) (declare (ignore x)) (mv `(acl2-numberp ,y) y)) (& (mv nil term)))) We can now define our meta function and hypothesis metafunction and prove a meta rule based on them. (defun meta-fn (term) (declare (xargs :guard (pseudo-termp term))) (mv-let (hyp new-term) (meta-helper term) (if hyp new-term term))) (defun meta-hyp-fn (term) (declare (xargs :guard (pseudo-termp term))) (mv-let (hyp new-term) (meta-helper term) (declare (ignore new-term)) (or hyp ''nil))) (defthm meta-fn-correct (implies (evl (meta-hyp-fn x) a) (equal (evl x a) (evl (meta-fn x) a))) :rule-classes ((:meta :trigger-fns (foo)))) In order to see this meta rule in action, let us disable [47mfoo[0m and try a little test. (in-theory (disable foo)) (defthm meta-fn-correct-test (implies (acl2-numberp b) (equal (foo a (foo b (- a))) b))) Happily, the test succeeds, with the [summary] showing that our meta rule, [47mmeta-fn-correct[0m, was indeed used in the proof. But if we first submit the form [47m(trace$ meta-fn meta-hyp-fn meta-helper)[0m, we will see that [47mmeta-helper[0m is called twice on the term [47m(FOO A (FOO B (UNARY-- A)))[0m: once on behalf of [47mmeta-fn[0m and once on behalf of [47mmeta-hyp-fn[0m. This would be unfortunate if [47mmeta-helper[0m were expensive to compute. So let us back up and try a different approach, which illustrates the idea of using an ``implicit hypothesis'' in order to avoid recomputation. This time, we avoid defining a hypothesis metafunction, but instead we define [47mmeta-fn[0m to return a term of the form [47m(if TEST NEW-TERM term)[0m. Here, [47mTEST[0m is [47m`(acl2-numberp ,y)[0m; we call this an ``implicit hypothesis.'' :ubt! meta-fn (defun meta-fn (term) (declare (xargs :guard (pseudo-termp term))) (mv-let (hyp new-term) (meta-helper term) (if hyp ; the interesting case `(if ,hyp ,new-term ,term) term))) There is nothing remarkable in the proof of the corresponding meta rule. (defthm meta-fn-correct (equal (evl x a) (evl (meta-fn x) a)) :rule-classes ((:meta :trigger-fns (foo)))) Let us test our new implementation. If we first evaluate the form [47m(trace$ meta-fn meta-helper)[0m, we will see that this time, [47mmeta-helper[0m is called only once on the term [47m(FOO A (FOO B (UNARY-- A)))[0m. (in-theory (disable foo)) (defthm meta-fn-correct-test (implies (acl2-numberp b) (equal (foo a (foo b (- a))) b))) Note that the following proof attempt fails but does not loop. Naively, one might expect it to loop, since the false branch of the [47mIF[0m term returned by [47mmeta-fn[0m has the original (input) term as its false branch. However, ACL2 notices the special form [47m(if TEST NEW-TERM term)[0m of the term returned by calling [47mmeta-fn[0m, and treats this result as though [47mTEST[0m is the term returned by a hypothesis metafunction and [47mNEW-TERM[0m is the term returned by the metafunction. (thm ; FAILS but does not loop! (equal (foo a (foo b (- a))) b)) Suppose that instead we had defined [47mmeta-fn[0m as follows, that is, with the `then' and `else' branches swapped. (defun meta-fn (term) (declare (xargs :guard (pseudo-termp term))) (mv-let (hyp new-term) (meta-helper term) (if hyp ; the interesting case ; `(if (not ,hyp) ,term ,new-term) term))) Then the events above go through as before, up to the [47m[thm][0m form. But that form loops, because the generated [47mIF[0m term no longer has the special form [47m(if TEST NEW-TERM term)[0m. In the (likely rare) case that really wishes to allow an unresolved case split for which one branch is the original term, this swapping of branches is available to defeat the recognition of an implicit hypothesis. Precise specification Consider a meta rule: (implies (and (pseudo-termp x) ; this hyp is optional (alistp a) ; this hyp is optional (ev (hyp-fn x ...) a) ; this hyp is optional ; meta-extract hyps may also be included (see below) ) (equiv (ev x a) (ev (fn x ...) a))) Recall that when this rule is applied to a term, [47mterm[0m, then a list of hypotheses is initially generated as follows, where each generated hypothesis must be rewritten to a non-[47mnil[0m value in order for the rule to fire. 1. If there is a hypothesis metafunction, [47mhyp-fn[0m, then let [47mhyps[0m be the list of hypothesis terms returned by the call of [47mhyp-fn[0m on [47mterm[0m. More precisely, the term returned by the call of [47mhyp-fn[0m is flattened into a list of ``hypothesis terms,'' so that for example the (translated) conjunction [47m(if a (if b c 'nil) 'nil)[0m generates the list [47m(a b c)[0m of hypothesis terms. 2. Otherwise, let [47mhyps[0m be [47mnil[0m. When this rule is applied by calling [47mfn[0m on a term, [47mterm[0m, we say that a term, [47mtest[0m, is an ``implicit hypothesis'' if the value returned by that call of [47mfn[0m is a term of the form [47m(if test new-term term)[0m: that is, [47mtest[0m is the test of the resulting [47mif[0m term and the input term is the false branch of that [47mif[0m term. In this case, ACL2 recognizes [47mtest[0m as an implicit hypothesis, which triggers two changes made in how this meta rule is applied. First, [47mhyps[0m is extended by the flattened list of hypotheses generated from [47mtest[0m. Second, instead of applying [47mhyp-fn[0m to the original term, [47mterm[0m, [47mhyp-fn[0m is applied to [47mnew-term[0m.") (metafunction-context (extended-metafunctions) "A structure that holds data supporting extended meta reasoning This advanced topic explains the [47mmfc[0m structure documented elsewhere; see [extended-metafunctions] for prerequisite background. This documentation is deliberately minimal, as we consider the [47mmfc[0m structure to be implementation-level; comments in the source code may serve to provide more information. [31;1mWARNING![0m This is a data structure that supports the ACL2 implementation. While it is highly stable in practice, there is no guarantee that future ACL2 implementations will avoid changing it. Use it at your own (perhaps small) risk! If you want to avoid all such risk, use the interfaces described in the documentation for [extended-metafunctions], such as [47mmfc-rw[0m. The [47mmfc[0m (metafunction-context) structure, which is given in the ACL2 sources by the form [47m(defrec metafunction-context ...)[0m, currently has the following fields. Each instance is constructed in the context where it is needed, for example, during execution of a function that implements the ACL2 rewriter. * [47mancestors[0m: a list of terms assumed true, modified as we backchain * [47mbackchain-limit[0m: heuristic limit to backchaining * [47mfnstack[0m: functions and terms currently being expanded --- of heuristic use only * [47mgeneqv[0m: a generated equivalence relation to maintain * [47mgstack[0m: either [47mnil[0m or a goal stack, as in [cw-gstack] * [47mobj[0m: this ``objective'' is either [47mt[0m, [47mnil[0m, or [47m?[0m --- of heuristic use only. * [47mrcnst[0m: a [47mrewrite-constant[0m record that holds many fields to be accessed by the ACL2 rewriter. See the definition [47m(defrec rewrite-constant ...)[0m, including comments therein, in the ACL2 sources. * [47mrdepth[0m: maximum allowed rewrite stack depth --- of heuristic use only * [47msimplify-clause-pot-lst[0m: a pot-lst of polynomials ([47mpoly[0m records) * [47mttree[0m: the evolving [ttree] describing the rewrites * [47mtype-alist[0m: a [type-alist], representing assumptions governing the current rewrite * [47munify-subst[0m: either [47mnil[0m or a unifying substitution used by the rewriter * [47mwrld[0m: the current ACL2 [world] Here is an example of the use of these fields, which shows how to access the literal of the [clause] (goal) under which the current rewrite is taking place. (defevaluator my-ev my-ev-lst ((if x y z))) (defun my-metafn (x mfc state) (declare (xargs :stobjs state :verify-guards nil) (ignore state)) (let* ((rcnst (access metafunction-context mfc :rcnst)) (not-flg/atm (access rewrite-constant rcnst :current-literal)) (atm (access current-literal not-flg/atm :atm))) (prog2$ (cw "Current literal:~%~x0~%Current term:~%~x1~%" atm x) x))) (defthm my-meta-correct (equal (my-ev x a) (my-ev (my-metafn x mfc state) a)) :rule-classes ((:meta :trigger-fns (nth)))) (defthmd mv-nth-is-nth (equal (mv-nth x y) (nth x y))) (set-gag-mode nil) (thm (implies (and (true-listp x) (true-listp y)) (equal (mv-nth n (append (car (cons x x)) y)) uuu)) :hints (("Goal" :do-not '(preprocess)) ("Goal'" :in-theory (enable mv-nth-is-nth)))) Here is some relevant output from the [thm] call, which shows that the rule [47mmv-nth-is-nth[0m above has been applied while rewriting the conclusion of the proposed theorem --- the meta function's printing happens while in the course of rewriting the [47mNTH[0m call resulting from the application of the rule (i.e., an instance of the right-hand side of the rule). Goal' (IMPLIES (AND (TRUE-LISTP X) (TRUE-LISTP Y)) (EQUAL (MV-NTH N (APPEND X Y)) UUU)). Current literal: (EQUAL (MV-NTH N (BINARY-APPEND X Y)) UUU) Current term: (NTH N (BINARY-APPEND X Y))") (mfc (pointers) "See [metafunction-context].") (mfc-ancestors (pointers) "See [extended-metafunctions].") (mfc-ap (pointers) "See [extended-metafunctions].") (mfc-clause (pointers) "See [extended-metafunctions].") (mfc-rdepth (pointers) "See [extended-metafunctions].") (mfc-relieve-hyp (pointers) "See [extended-metafunctions].") (mfc-rw (pointers) "See [extended-metafunctions].") (mfc-rw+ (pointers) "See [extended-metafunctions].") (mfc-ts (pointers) "See [extended-metafunctions].") (mfc-type-alist (pointers) "See [extended-metafunctions].") (mfc-unify-subst (pointers) "See [extended-metafunctions].") (mfc-world (pointers) "See [extended-metafunctions].") (min (numbers acl2-built-ins) "The smaller of two numbers [47m(Min x y)[0m is the smaller of the numbers [47mx[0m and [47my[0m. The [guard] for [47mmin[0m requires its arguments to be rational ([real], in ACL2(r)) numbers. [47mMin[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<min> (defun min (x y) (declare (xargs :guard (and (real/rationalp x) (real/rationalp y)))) (if (< x y) x y))") (minimal-theory (theories theory-functions) "A minimal theory to enable This [47m[theory][0m (see [theories]) enables only a few built-in functions and [executable-counterpart]s. It can be useful when you want to formulate lemmas that rather immediately imply the theorem to be proved, by way of a [47m:use[0m hint (see [hints]), for example as follows. :use (lemma-1 lemma-2 lemma-3) :in-theory (union-theories '(f1 f2) (theory 'minimal-theory)) In this example, we expect the current goal to follow from lemmas [47mlemma-1[0m, [47mlemma-2[0m, and [47mlemma-3[0m together with rules [47mf1[0m and [47mf2[0m and some obvious facts about built-in functions (such as the [definition] of [47m[implies][0m and the [47m:[0m[47m[executable-counterpart][0m of [47m[car][0m). The [47m:[0m[47m[in-theory][0m hint above is intended to speed up the proof by turning off all inessential rules.") (minusp (numbers acl2-built-ins) "Test whether a number is negative [47m(Minusp x)[0m is true if and only if [47mx < 0[0m. The [guard] of [47mminusp[0m requires its argument to be a rational ([real], in ACL2(r)) number. [47mMinusp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<minusp> (defun minusp (x) (declare (xargs :guard (real/rationalp x))) (< x 0))") (miscellaneous (acl2) "A miscellany of documented functions and concepts (often cited in more accessible [documentation]) Perhaps as the system matures this section will become more structured. Subtopics [Abort-soft] Control how interrupts are handled in proofs [ACL2-customization] File of initial commands for ACL2 to run at [startup] [Case-split-limitations] Limiting the number of immediate subgoals [Clause] A representation of prover goals [Default-defun-mode] The default [defun-mode] of [47m[defun][0m'd functions [Gc$] Invoke the garbage collector [Gc-strategy] The garbage collection strategy [Gcl] Tips on building and using ACL2 based on Gnu Common Lisp [Hints] Advice to the theorem proving process [Ld] The ACL2 read-eval-print loop, file loader, and [command] processor [Local-incompatibility] When non-local [events] won't replay in isolation [Ordinals] Ordinals in ACL2 [Reader] Reading expressions in the ACL2 read-eval-print loop [Set-case-split-limitations] Set the [case-split-limitations] [Set-gc-strategy] Set the garbage collection strategy (CCL only) [Set-prover-step-limit] Sets the step-limit used by the ACL2 prover [Set-subgoal-loop-limits] Set the maximum length and repetition count of the subgoal path [Specious-simplification] Nonproductive proof steps [Subgoal-loop-limits] maximum length of the subgoal stack [Subversive-inductions] Why we restrict [encapsulate]d recursive functions [Subversive-recursions] Why we restrict [encapsulate]d recursive functions [Syntax] The syntax of ACL2 is that of Common Lisp [Term] The three senses of well-formed ACL2 expressions or formulas [Thm] Prove a theorem [Top-level] Evaluate a top-level form as a function body [Ttags-seen] List some declared trust tags (ttags) [Ttree] Tag-trees [Type-set] How type information is encoded in ACL2 [With-prover-step-limit] Limit the number of steps for proofs [With-prover-time-limit] Limit the time for proofs") (mixed-mode-functions (apply$) "[47m:[0m[47m[logic][0m mode functions can [47m[apply$][0m [47m:[0m[47m[program][0m mode functions Because [47m:[0m[47m[program][0m mode functions can be given badges it is possible to [47m[apply$][0m them from within [47m:[0m[47m[logic][0m mode functions. Colloquially, we call such [47m:logic[0m mode functions ``mixed mode,'' but that is a misnomer. They are indisputably in [47m:logic[0m mode. First, note that the only way to introduce a [47m:program[0m mode function into [47m:logic[0m mode functions is to use the quoted [47m:program[0m mode function name in an argument slot of [ilk] [47m:FN[0m, use the [47m:program[0m mode function in a quoted [47m[lambda][0m object or [47m[lambda$][0m expression in a slot of [ilk] [47m:FN[0m or use it in a quoted expression in a slot of ilk [47m:EXPR[0m. We do not allow [47m:program[0m mode functions to be called directly from [47m:logic[0m mode functions. For example, if [47mprgm[0m is defined as a [47m:program[0m mode function of one argument, and has been assigned a badge by [47m[defbadge][0m (defun foo (x) (declare (xargs :mode :logic)) (apply$ 'prgm (list x))) is legal but (defun foo (x) (declare (xargs :mode :logic)) (prgm x)) is not. Second, the presence of a [47m:program[0m mode function in a [47m:logic[0m mode function prohibits the [47m:logic[0m mode function from being guard verified. Mixed-mode functions raise interesting questions for top-level evaluation and evaluation and rewriting during proofs. When a [47m:program[0m mode function is [47mapply$[0med, it is always done in [47m[safe-mode][0m. In general, evaluating a [47m:program[0m mode function at the top-level can cause hard Lisp errors. For example, (defun prgm (x) (declare (xargs :mode :program)) (car x)) Then [47m(prgm 23)[0m causes a hard Lisp error in both CCL and SBCL, but [47m(prgm 'abc)[0m returns numbers in both of those Common Lisps, but they return different numbers. Furthermore, there is no guarantee across all Common Lisps that [47m(prgm 'abc)[0m will always return the same number throughout a given ACL2 session; the value could conceivably change as memory is allocated, compacted, garbage collected, etc., since according to the CLTL standard, one is not supposed to apply [47mCAR[0m to any symbol other than [47mNIL[0m but no error need be signaled. It is likely that a CLTL implementation of [47mCAR[0m just accesses memory where the [47mCAR[0m component of a cons is supposed to be! We tolerate such behavior when [47m:program[0m mode functions are directly called at the top-level because there are no axioms about them and we regard the evaluation of such programs from within the ACL2 loop as just a convenience to the user. But [47mapply$[0m is a [47m:logic[0m mode function and we must guarantee that when any [47m:logic[0m mode function is evaluated functional substitutivity holds: identical calls must yield identical results. That is, [47mapply$[0m must behave like a [3mfunction[0m and not give different answers to the same questions over time when errors are not signaled. We also strive to achieve the goal that [47m:logic[0m mode functions never cause hard Lisp errors other than resource errors like stack overflow or memory exhaustion. So when [47mapply$[0m is given a badged [47m:program[0m mode function, e.g., had we badged [47mprgm[0m and then evaluated [47m(apply$ 'prgm '(abc))[0m, it must at least return the same ACL2 object every time! To achieve this end [47mapply$[0m runs [47m:program[0m mode functions in [47m[safe-mode][0m. (Safe mode does shift into raw Lisp on calls of guard verified [47m:logic[0m mode functions which might be called from within the [47m:program[0m mode function. But a mixed mode function cannot be guard verified because the [47m:program[0m mode functions used within it cannot be guard verified.) This means that a top-level call of a mixed mode function generally runs slower than a corresponding call of an otherwise identical [47m:program[0m mode function. (And, on the positive side, it means that mixed mode functions actually behave like [3mfunctions[0m while [47m:program[0m mode ones may not!) The only way to speed up a mixed-mode function is to convert the [47m:program[0m mode functions in it to [47m:logic[0m mode with [47m[verify-termination][0m and verify the guards. As for proofs, since there are no axioms about [47m:program[0m mode functions, if a mixed-mode function is expanded in a proof all [47m:program[0m mode functions in it are treated as though they are undefined. In particular, the absence of a warrant on the [47m:program[0m mode function [47mprgm[0m means that [47m(apply$ 'prgm '(abc))[0m, is not evaluated by the prover despite the fact that it is a ground term.") (mod (numbers acl2-built-ins) "Remainder using [47m[floor][0m ACL2 !>(mod 14 3) 2 ACL2 !>(mod -14 3) 1 ACL2 !>(mod 14 -3) -1 ACL2 !>(mod -14 -3) -2 ACL2 !>(mod -15 -3) 0 ACL2 !> [47m(Mod i j)[0m is that number [47mk[0m that [47m(* j (floor i j))[0m added to [47mk[0m equals [47mi[0m. The [guard] for [47m(mod i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real], in ACL2(r)) numbers and [47mj[0m is non-zero. [47mMod[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<mod> (defun mod (x y) (declare (xargs :guard (and (real/rationalp x) (real/rationalp y) (not (eql y 0))))) (- x (* (floor x y) y)))") (mod-expt (numbers acl2-built-ins) "Exponential function [47m(mod-expt r i m)[0m is the result of raising the number [47mr[0m to the integer power [47mi[0m and then taking the residue mod [47mm[0m. That is, [47m(mod-expt r i m)[0m is equal to [47m(mod (expt r i) m)[0m. The [guard] for [47m(mod-expt r i m)[0m is that [47mr[0m is a rational number and [47mi[0m is an integer; if [47mr[0m is [47m0[0m then [47mi[0m is nonnegative; and [47mm[0m is a non-zero rational number. In some implementations (GCL Version 2.7.0 as of this writing), this function is highly optimized when [47mr[0m and [47mi[0m are natural numbers, not both zero, and [47mm[0m is a positive integer. For other Lisp implementations, consider using function [47mmod-expt-fast[0m, defined in the community book [47marithmetic-3/floor-mod/mod-expt-fast.lisp[0m, which should still provide significantly improved performance over this function. [31;1mFunction: [0m<mod-expt> (defun mod-expt (base exp mod) (declare (xargs :guard (and (real/rationalp base) (integerp exp) (not (and (eql base 0) (< exp 0))) (real/rationalp mod) (not (eql mod 0))))) (mod (expt base exp) mod))") (mode (pointers) "See [xargs] for information about the keyword [47m:mode[0m.") (modeling_in_acl2 (pages_written_especially_for_the_tours) "Modeling in ACL2 {IMAGE} (see [Running_Models]) {IMAGE} Below we define [31;1mmc(s,n)[0m to be the function that [31;1msingle-step[0ms [31;1mn[0m times from a given starting state, [31;1ms[0m. In Common Lisp, ``mc(s,n)'' is written [47m(mc s n)[0m. [31;1m(defun mc (s n)[0m ; To step [31;1ms[0m [31;1mn[0m times: [31;1m(if (zp n)[0m ; If [31;1mn[0m is 0 [31;1ms[0m ; then return [31;1ms[0m [31;1m(mc (single-step s) (- n 1))))[0m ; else step [31;1msingle-step(s)[0m [31;1mn-1[0m times. This is an example of a formal model in ACL2. {IMAGE} (see [Running_Models])") (models_in_engineering (pages_written_especially_for_the_tours) "Models in Engineering {IMAGE} Frequently, engineers use mathematical models. Use of such models frequently lead to [31;1mbetter designs[0m, [31;1mfaster completion of acceptable products[0m, and [31;1mreduced overall cost[0m, because models allow the trained user to study the design before it is built and analyze its properties. Usually, testing and analyzing a model is cheaper and faster than fabricating and refabricating the product. {IMAGE}") (models_of_computer_hardware_and_software (pages_written_especially_for_the_tours) "Models of Computer Hardware and Software {IMAGE} (see [A_Typical_State]) {IMAGE} Computing machines, whether hardware or software or some combination, are frequently modeled as ``state machines.'' To so model a computing machine we must represent its [31;1mstates[0m as objects in our mathematical framework. [31;1mTransitions[0m are functions or relations on state objects. In what language shall we define these objects, functions, and relations? The mathematical languages we were taught in high school [31;1malgebra[0m, [31;1mgeometry[0m, [31;1mtrigonometry[0m, and [31;1mcalculus[0m are often inappropriate for modeling digital systems. They primarily let us talk about numbers and continuous functions. To see what kind of expressive power we need, take a closer look at what a typical state contains. {IMAGE} (see [A_Typical_State])") (monitor (break-rewrite) "To monitor attempted applications of certain rules by the rewriter This function stores information about which runes should be monitored during rewriting and what criteria are used to invoke an interactive break when those runes are tried by the rewriter during a subsequent proof attempt. Outline * Protocol for Using Monitors * Example and General Forms * Background on Rewriting * Criteria for Breaks * Example Break Conditions * What If No Break Occurs? Protocol for Using Monitors When a proof fails and you expected it to succeed by applying rules you've proved, it can be helpful to see what happens when (if) the rewriter attempts to use your rules. The [break-rewrite] utility allows you to monitor each attempt by the rewriter to use specific rules ([rune]s). The basic protocol is that you turn on the break-rewrite utility with [47m[brr][0m and then you use this facility, [47mmonitor[0m, to specify the rules you want to monitor and the criteria for entering an interactive break. (The variant [47m[monitor!][0m is like [47mmonitor[0m but also makes sure the break rewrite utility is turned on.) Then you attempt the failed proof again. When a monitored rule is tried and the criteria for that rule are satisfied, the rewriter triggers an interactive break allowing you to query the environment and watch what happens. The break is a read-eval-print loop (in fact it is managed by [47mld[0m, the same function that provides ACL2's top-level interactive loop). However, it is inside a [47m[wormhole][0m, allowing you to see what happening in rewrite. But any changes you make while in this break disappear when the break exits and the wormhole evaporates. See [brr-commands] for a list of the commands that specifically give you access to parts of the rewriter's state. Such breaks do not allow you to change the course of the rewriter or otherwise guide the proof attempt! Breaks [31;1mdo[0m allow you to abort a proof attempt, which you typically do when you've understood why your rule failed to apply. If you're seeking an interactive proof checker see [47m[proof-builder][0m. To learn about the interactive breaks triggered when monitored runes are tried, see [break-rewrite]. The current topic deals with how to install a monitor on a rule. Example and General Forms Examples: (monitor '(:rewrite assoc-of-app) 't) (monitor '(:r assoc-of-app) t) (monitor 'assoc-of-app t) (monitor '(rewrite assoc-of-app) '(:condition t :depth 2)) (monitor '(rewrite assoc-of-app) '(:condition t :rf t :depth 2)) Keyword Command Examples: :monitor assoc-of-app t :monitor lemma42 (:condition (equal (brr@ :target) '(F A (G A (H B)))) :rf t :depth 2 :abstraction (F x (G x y)) :lambda t)) General Forms: (monitor x criteria) (monitor x criteria t) ; a quiet version (monitor! x criteria) ; like quiet monitor but turns on brr first where (the value of) [47mx[0m is a [rune] or more generally a runic designator (see [theories]) designating one or more runes of classes [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, or [47m:[0m[47m[linear][0m and (the value of) [47mcriteria[0m is a ``keyword value list'' --- a list of alternating keywords and values. If no [47m:condition[0m key is supplied, [47m:condition t[0m is used. If [47mcriteria[0m is some term, [47my[0m, it is treated as the keyword value list [47m(:condition y)[0m. The following keywords and values are supported but the details are discussed below. * [47m:rf[0m --- value must be [47mT[0m or [47mNIL[0m, defaults to [47mNIL[0m * [47m:depth[0m --- value must be a natural number * [47m:abstraction[0m --- value must be a term and it is most often an abstraction of the pattern that triggers [47mx[0m obtained by replacing some subterms of that pattern by new variables * [47m:lambda[0m --- value must be [47mt[0m or [47mnil[0m * [47m:condition[0m --- value must be a term, called the ``break condition'' which contains at most one free variable and that variable must be [47m[state][0m. An interactive break is initiated only if the [47m:condition[0m term evaluates to non-[47mnil[0m. If not provided, the [47m:condition[0m value defaults to [47m'T[0m. The keys [47m:depth[0m, [47m:abstraction[0m, and [47m:lambda[0m are only relevant when the rule named by [47mx[0m rewrites with an equivalence relation that is a refinement of the equivalence relation the rewriter is obligated to maintain on the current target (see [geneqv]) and the rule's ``pattern'' [31;1mdoes not match[0m the target. They specify criteria under which a failed match is to be considered a ``near miss.'' Details are given below. The key [47m:rf[0m with value [47mT[0m indicates that breaks are to also occur (if the [47m:condition[0m evaluates to non-[47mnil[0m and) the rune's equivalence relation has failed to be a refinement of the equivalence relation the rewriter is obligated to maintain on the current target. See [refinement-failure]. If [47m:rf[0m is [47mnil[0m or not provided, refinement failures do not trigger breaks but the other kinds of breaks may occur. Keywords other than [47m:condition[0m, [47m:rf[0m, [47m:depth[0m, [47m:abstraction[0m, and [47m:lambda[0m are allowed with no constraints on their values. The purpose of this allowance is so that the user who wants to attach his or her own function to ACL2's [47m[brr-near-missp][0m predicate can pass information to that function. When successful, [47mmonitor[0m arranges for the rewriter to trigger an interactive break when any rule named by [47mx[0m and of the above classes is tried, provided the [break-rewrite] utility has been turned on --- using [47m:[0m[47m[brr][0m[47m t[0m, [47m:[0m[47m[monitor!][0m, or [with-brr-data] --- and the circumstances of the attempt to apply the rule satisfy the [47mcriteria[0m as checked by the function [47m[brr-near-missp][0m. [47mMonitor[0m prints to the comment window a list of all the currently-monitored runes and their criteria and returns the error-triple [47m(value :invisible)[0m. The so-called ``quiet'' versions above do no printing. Some [47m:rewrite[0m rules are considered ``simple abbreviations''; see [simple]. These can be be monitored, but are only tried at certain times during the proof. Monitoring is carried out by code inside the rewriter but abbreviation rules may be applied by a special purpose simplifier inside the so-called [3mpreprocess[0m phase of a proof. If you desire to monitor an abbreviation rule, a warning will be printed suggesting that you may want to supply the hint [47m:DO-NOT '(PREPROCESS)[0m; see [hints]. Without such a hint, an abbreviation rule can be applied during the preprocess phase of a proof, and no such application will cause an interactive break. To remove a rune from the list of monitored runes, use [47m[unmonitor][0m. To see which runes are monitored and what their break criteria are, evaluate [47m([0m[47m[monitored-runes][0m[47m)[0m. [47mMonitor[0m, [47munmonitor[0m and [47mmonitored-runes[0m are macros that expand into expressions involving [47mstate[0m. While these macros appear to return the list of [monitor]ed runes this is an illusion. They all print [monitor]ed rune information to the comment window and then return [error-triple]s instructing [47mld[0m to print nothing. It is impossible to return the list of [monitor]ed runes because it exists only in the [wormhole] [state] with which you interact when a break occurs. This allows you to change the [monitor]ed runes and their conditions during the course of a proof attempt without changing the [state] in which the proof is being constructed. Note: This list of monitored runes is maintained as a locally bound variable by break-rewrite. For example, suppose that at the top-level of ACL2 the list of monitored runes and their criteria is [47mx[0m. Suppose you then start a proof attempt, a break-rewrite break occurs and in that break you use [47mmonitor[0m or [47munmonitor[0m to change the list of monitored runes to [47my[0m. Now suppose that you release or abort from the break and ACL2 returns to the top-level. You might think the list of monitored runes is [47my[0m but in fact it is [47mx[0m. The list is locally bound to value in the caller's environment each time break-rewrite is entered and thus restored to the value in the caller's environment when break-rewrite returns. Background on Rewriting Before we explain the criteria for triggering breaks we establish some basic terminology about the rewriter. We start with how it applies [47m:rewrite[0m rules. The rewriter walks through a term (typically left-to-right, innermost first) maintaining a list of known assumptions represented as a [type-alist]. It rewrites each subterm under those assumptions. The subterm the rewriter is currently considering is called the ``target''. Each [47m:rewrite[0m rule is derived from some theorem essentially of the form [47m(implies (and hyp1 ... hypn) (equiv lhs rhs))[0m, where the [47mhypi[0m, [47mlhs[0m, and [47mrhs[0m are terms and [47mequiv[0m is known [equivalence] relation. The [47mlhs[0m is always a function application and the rule derived from the theorem is stored in the ACL2 logical [world] under the topmost function symbol of the [47mlhs[0m. Each time the rewriter steps to a new target it retrieves all the rules stored under the topmost function symbol of the target and tries each rule in turn (provided the rule is enabled and its [47mequiv[0m is a [congruence] relation in the current context). To try a [47m:rewrite[0m rule the rewriter first attempts to match the [47mlhs[0m to the target. By ``match'' we mean the rewriter tries to find a substitution for the variables of [47mlhs[0m (consistent with the [47m[restrict][0m hints governing the target) such that applying the substitution to the [47mlhs[0m produces the target. If the [47mlhs[0m matches the target, the rewriter then attempts to establish the [47mhypi[0m by rewriting each of them in turn, instantiating each [47mhypi[0m with the substitution. If the instance of each [47mhypi[0m rewrites to true, we know --- by the theorem justifying this rule --- that that the instance of [47mlhs[0m is equivalent to the corresponding instance of [47mrhs[0m, but the instance of [47mlhs[0m is the target. So the rewriter is logically justified in replacing the occurrence of the target by the instance of [47mrhs[0m and recursively rewrites that. Heuristic considerations may prevent such a replacement, e.g., the instantiated [47mrhs[0m is considered ``too complicated,'' a loop might be detected, etc. We can generalize and summarize this description just by saying that each rule has a pattern, some hypotheses, and a result. We say the rule is ``about'' the topmost function symbol in the pattern. If the pattern matches the target, the hypotheses are true, and heuristic considerations allow, we use the result. [47m:Definition[0m and [47m:rewrite-quoted-constant[0m rules fit easily within this scheme. But [47m:linear[0m rules are a little different. The conclusion of a [47m:linear[0m rule an arithmetic inequality relating subterms, the pattern is one of those subterms, and the result is the entire inequality conclusion. If the hypotheses are all rewritten to true, the result is instantiated and added to the context, telling the rewriter possibly useful information about the target. Criteria for Breaks If matching fails it is sometimes useful to see why. How did the pattern and the target differ? But since a rule about a given function symbol is tried every time the target has that same topmost function symbol, most rules fail to match much more often than they match. Triggering a break on every failed match is counterproductive. Instead, we introduce the notion of a ``near miss'' and allow you to set criteria that trigger breaks when a failed match is a near miss. There are three built-in near miss criteria, [47m:depth[0m, [47m:abstraction[0m, and [47m:lambda[0m. We expect any given monitored command will probably specify only one of these three criteria, depending on the pattern in the rule and your judgment of what might be going wrong, but there is nothing preventing you from specifying multiple criteria. If any one of them is satisfied by a failed match a break will occur. * [47m:depth n[0m causes a break if the pattern of the rune fails to match the target but the pattern does match down to depth [47mn[0m. For example, the pattern [47m(F X (G X (H Y (I Z))))[0m fails to match the target [47m(F A (G B C))[0m, but it does match to depth 2. To check this criterion the break utility abstracts the pattern by copying it and replacing every subterm at [47mn[0m by a new variable symbol. The depth [47mn[0m abstractions of [47m(F X (G (H Y (I Z))))[0m for [47mn[0m=1, 2, and 3 are shown below. * [47mn[0m = 1: [47m(F GENSYM0 GENSYM1)[0m * [47mn[0m = 2: [47m(F X (G GENSYM0 GENSYM1))[0m * [47mn[0m = 3: [47m(F X (G X (H GENSYM0 GENSYM1)))[0m * [47m:abstraction apat[0m causes a break if the pattern of the rune fails to match the target but the translation of [47mapat[0m does match the target. This is useful when you want more control over the abstraction of the pattern than [47m:depth[0m gives you. For example, the depth 2 abstraction of [47m(F X (G X (H Y (I Z))))[0m is [47m(F X (G GENSYM0 GENSYM1))[0m but you may be interested only in breaks when [47m(F X (G X GENSYM1))[0m matches the target, i.e., where the first arguments of [47mF[0m and [47mG[0m are the same. If so you could specify the criterion [47m:abstraction (F X (G X Y))[0m or, equivalently, [47m:abstraction (F X (G X GENSYM1))[0m. * [47m:lambda t[0m causes a break if the pattern of the rune fails to match the target but does match everywhere except on quoted [47m[lambda][0m constants. This is checked by replacing each quoted [47mlambda[0m object in the pattern by a new variable. This is particularly useful when your rule contains a [47mlambda$[0m expression, which translates to a quoted [47mlambda[0m constant, but the occurrence of that constant in the target has been rewritten (see [rewrite-lambda-object]). See also the discussion of ``Normal Forms in Loop$ Bodies'' in [stating-and-proving-lemmas-about-loop$s]. When a near miss break is caused it prints a message like this (1 Breaking (:REWRITE LEMMA) on (F (G A B) A '(A B C D ...)): The pattern in this rule failed to match the target. However, this is considered a NEAR MISS under the break criteria, (:CONDITION 'T :ABSTRACTION (F X1 X2 X3)), specified when this rule was monitored. The message then displays all of the near miss break criteria that were satisfied and then prompts you for input. This allows you to inspect the pattern (via the [47m[brr-commands][0m [47m:lhs[0m or [47m:max-term[0m depending on whether the monitored lemma is a [47m:rewrite[0m rule or a [47m:linear[0m rule. You can inspect the target term with the command [47m:target[0m. The ``+'' versions of those commands, e.g., [47m:lhs+[0m, will print the terms without evisceration. If you want more information about why the pattern of the rule failed to match the target, use the command [47m:explain-near-miss[0m or its ``+'' version. You may exit the break with any of the usual commands, e.g., [47m:ok[0m to continue the proof attempt (because perhaps you determined that the lemma was never supposed to match this particular target) or [47m:a![0m to abort back to the top-level to fix the problem (because you figured out why the lemma, as written, will not match the intended target). On the other hand, suppose the pattern of the rune matches the target. Then the break condition term, i.e., the [47m:condition[0m criterion, is evaluated. The only variable allowed in the break condition term is [47mstate[0m, which in the context of the break-rewrite utility is a [47m[wormhole][0m state. Suppose the break condition term evaluates to [47mans[0m. If [47mans[0m is [47mnil[0m, no break occurs. If [47mans[0m is [47mt[0m, an interactive break occurs and the user is prompted for commands. Otherwise, [47mans[0m is expected to be a true list of commands to be fed to the break, i.e., to be appended to [47mstandard-oi[0m. Those commands are then executed just as though the user typed them. If they exit the break, the user is not prompted for further commands. If they don't exit the break, the user is prompted for more commands. Example Break Conditions In order to develop effective break conditions it must be possible to access context sensitive information, i.e., information about the context in which the [monitor]ed rune is being tried. The [47m[brr@][0m macro may be used in break conditions to access such information as the term being rewritten and the current governing assumptions. This information is not stored in the proof [state] but is transferred into the [wormhole] [state] when breaks occur. The macro form is [47m(brr@ :sym)[0m where [47m:sym[0m is one of several keyword symbols, including [47m:target[0m (the term being rewritten), [47m:unify-subst[0m (the substitution that instantiates the left-hand side of the conclusion of the rule so that it is the target term), and [47m:[0m[47m[type-alist][0m (the governing assumptions). See [brr@]. For example, ACL2 !>:monitor (:rewrite assoc-of-app) (equal (brr@ :target) '(app (app a b) c)) will monitor [47m(:rewrite assoc-of-app)[0m but will cause an interactive break only when the target term is literally [47m(APP (APP A B) C)[0m. Because break conditions are evaluated in the interaction environment, the user developing a break condition for a given rune can test candidate break conditions before installing them. For example, suppose an unconditional break has been installed on a rune, that an interactive break has occurred and that the user has determined both that this particular application is uninteresting and that many more such applications will likely occur. An appropriate response would be to develop an expression that recognizes such applications and returns [47mnil[0m. Of course, the hard task is figuring out what makes the current application uninteresting. But once a candidate expression is developed, the user can evaluate it in the current context simply to confirm that it returns [47mnil[0m. Recall that when a break condition returns a non-[47mnil[0m true list that list is appended to the front of [47mstandard-oi[0m. For example, ACL2 !>:monitor (:rewrite assoc-of-app) '(:go) will cause [47m(:rewrite assoc-of-app)[0m to be monitored and will make the break condition be [47m'(:go)[0m. This break condition always evaluates to the non-[47mnil[0m true list [47m(:go)[0m. Thus, an interactive break will occur every time [47m(:rewrite assoc-of-app)[0m is tried. The break is fed the command [47m:go[0m. Now the command [47m:go[0m causes [47mbreak-rewrite[0m to (a) evaluate the attempt to apply the lemma, (b) print the result of that attempt, and (c) exit from the interactive break and let the proof attempt continue. Thus, in effect, the above [47m:monitor[0m merely ``traces'' the attempted applications of the rune but never causes an interactive break requiring input from the user. It is possible to use this feature to cause a conditional break where the effective break condition is tested [31;1mafter[0m the lemma has been tried. For example: ACL2 !>:monitor (:rewrite lemma12) '(:unify-subst :eval! :ok-if (or (not (brr@ :wonp)) (not (equal (brr@ :rewritten-rhs) '(foo a)))) :rewritten-rhs) causes the following behavior when [47m(:rewrite lemma12)[0m is tried. A break always occurs, but it is fed the commands above. The first, [47m:unify-subst[0m, causes [47mbreak-rewrite[0m to print out the unifying substitution. Then in response to [47m:eval![0m the lemma is tried but with all runes temporarily [unmonitor]ed. Thus no breaks will occur during the rewriting of the hypotheses of the lemma. When the attempt has been made, control returns to [47mbreak-rewrite[0m (which will print the results of the attempt, i.e., whether the lemma was applied, if so what the result is, if not why it failed). The next command, the [47m:ok-if[0m with its following expression, is a conditional exit command. It means exit [47mbreak-rewrite[0m if either the attempt was unsuccessful, [47m(not (brr@ :wonp))[0m, or if the result of the rewrite is any term other than [47m(foo a)[0m. If this condition is met, the break is exited and the remaining break commands are irrelevant. If this condition is not met then the next command, [47m:rewritten-rhs[0m, prints the result of the application (which in this contrived example is known to be [47m(foo a)[0m). Finally, the list of supplied commands is exhausted but [47mbreak-rewrite[0m expects more input. Therefore, it begins prompting the user for input. The end result of the above [47m:monitor[0m command is that the rune in question is elaborately traced and interactive breaks occur whenever it rewrites its target to [47m(foo a)[0m. We recognize that the above break condition is fairly arcane. We suspect that with experience we will develop some useful idioms. For example, it is straightforward now to define macros that monitor runes in the ways suggested by the following names: [47mtrace-rune[0m, [47mbreak-if-target-is[0m, and [47mbreak-if-result-is[0m. For example, the last could be defined as (defmacro break-if-result-is (rune term) `(monitor ',rune '(quote (:eval :ok-if (not (equal (brr@ :rewritten-rhs) ',term)))))) (Note however that the submitted term must be in translated form.) Since we don't have any experience with this kind of control on lemmas we thought it best to provide a general (if arcane) mechanism and hope that the ACL2 community will develop the special cases that we find most convenient. Note: The combination of a non-trivial [47m:condition[0m and some near-miss criteria can result in confusing behavior. To get a near-miss break a target has to fail to match the rule's pattern but succeed in matching the near-miss criteria. So the near-miss criteria is irrelevant if the target matches the rule. But to get a break the target must match the rule in such a way that the [47m:condition[0m is satisfied. Failure to get any breaks when you have a non-trivial [47m:condition[0m and a very general near-miss criteria may mean targets matching the near-miss criteria also matched the rule's pattern but failed to satisfy your [47m:condition[0m. Our personal preference when monitoring for near-misses is to use the default [47m:condition[0m of [47mt[0m, at least until we see what kind of matches are arising. What If No Break Occurs? Suppose [47mrune[0m is a rune that names a rule about some function symbol [47mfn[0m. What does it mean if you've installed a monitor on [47mrune[0m with [47m(:condition t :depth 1)[0m and [31;1mno break ever occurs[0m? Then one of the following is probably true. * the break-rewrite utility is not turned on --- you should evaluate [47m(brr t)[0m, * [47mrune[0m is disabled in the theory used for subgoals mentioning [47mfn[0m --- you should enable it either with a global [47m[in-theory][0m command or a subgoal-specific [47m:in-theory[0m hint (see [hints]), * [47mrune[0m names an abbreviation rule as discussed above --- you should add the hint [47m:DO-NOT '(PREPROCESS)[0m (see [hints]), * the [47m:[0m[47m[hints][0m supplied includes a [47m:hands-off[0m list that includes [47mfn[0m --- perhaps you should disable other rules about [47mfn[0m (since that is presumably why you put [47mfn[0m on the [47m:hands-off[0m list in the first place) and remove [47mfn[0m from the [47m:hands-off[0m list, * the only terms that the rewriter ever encountered with the topmost function [47mfn[0m were within a [47mHIDE[0m, * no target with the topmost function symbol [47mfn[0m was ever seen by rewrite --- perhaps [47mfn[0m was involved in the conjecture or introduced into the proof attempt but was eliminated by another rewrite. The rewriter is complicated. There may be other ways this could happen!") (monitor! (break-rewrite) "A quiet combination of [47m[monitor][0m and [47m[brr][0m [47mMonitor![0m is essentially the corresponding call of [47m[monitor][0m preceded by [47m(brr t)[0m, but avoiding output. See [monitor] and see [brr]. Note that [47mmonitor![0m may be used in place of [47mmonitor[0m even when inside an interactive break from [break-rewrite]; in that case, the [47mbrr[0m invocation on its behalf is essentially redundant.") (monitored-runes (break-rewrite) "Print the [monitor]ed [rune]s and their break conditions Example and General Form: (monitored-runes) :monitored-runes This macro prints a list, each element of which is of the form [47m(rune condition)[0m, showing each [monitor]ed [rune] and its current break condition. The list is printed to the comment window and [3mnot[0m returned as the value [47m(monitored-runes)[0m. The actual list is maintained in a wormhole managed by [break-rewrite]. Technically, the list of monitored runes is a locally bound variable of break-rewrite. The initial value of the variable is determined by its value in the containing scope of a call of break-rewrite. The value may be changed during interactions within the break, but it reverts to its old value upon return from break-rewrite. Thus if you monitor some runes, start a proof, adjust the monitored runes from within break-rewrite breaks in the proof attempt, and eventually return to the top-level, the value shown by [47m:monitored-runes[0m will be the same as it was when you started the proof.") (msg (io acl2-built-ins) "Construct a ``message'' suitable for the [47m~@[0m directive of [47m[fmt][0m See [fmt] for background on formatted printing with ACL2. In short: for a call [47m(msg s arg0 arg1 arg2 ...[0m), [47ms[0m should be a string suitable as an argument to [47m[fmt][0m and [47m(arg0 arg1 arg2 ...)[0m should be the bindings of [47m#\0[0m, [47m#\1[0m, [47m#\2[0m, and so on. See [msgp] for a weak recognizer of objects returned by [47mmsg[0m. Now, for a more careful explanation: We document [47mmsg[0m precisely below, but first, we give an informal introduction and illustrate with an example. Suppose you are writing a program that is to do some printing. Typically, you will either pass the ACL2 state around (see [programming-with-state]) and use formatted printing functions that take the state as an argument (see [fmt])), or else you might avoid using state by calling the utility, [47m[cw][0m, to do your printing. Alternatively, you might print error messages upon encountering illegal situations; see [er]. But there are times where instead of printing immediately, you may prefer to pass messages around, for example to accumulate them before printing a final message. In such cases, it may be desirable to construct ``message'' objects to pass around. For example, consider the following pair of little programs. The first either performs a computation or prints an error, and the second calls the first on two inputs. (defun invert1 (x) (if (consp x) (cons (cdr x) (car x)) (prog2$ (cw "ERROR: ~x0 expected a cons, but was given ~x1.~|" 'invert1 x) nil))) (defun invert2 (x1 x2) (list (invert1 x1) (invert1 x2))) For example: ACL2 !>(invert1 '(3 . 4)) (4 . 3) ACL2 !>(invert1 'a) ERROR: INVERT1 expected a cons, but was given A. NIL ACL2 !>(invert2 '(3 . 4) '(5 . 6)) ((4 . 3) (6 . 5)) ACL2 !>(invert2 'a 'b) ERROR: INVERT1 expected a cons, but was given A. ERROR: INVERT1 expected a cons, but was given B. (NIL NIL) ACL2 !> Notice that when there are errors, there is no attempt to explain that these are due to a call of [47minvert2[0m. That could be fixed, of course, by arranging for [47minvert2[0m to print its own error; but for complicated programs it can be awkward to coordinate printing from many sources. So let's try a different approach. This time, the first function returns two results. The first result is an ``error indicator'' --- either a message object or [47mnil[0m --- while the second is the computed value (only of interest when the first result is [47mnil[0m). Then the higher-level function can print a single error message that includes the error message(s) from the lower-level function, as shown below. (defun invert1a (x) (if (consp x) (mv nil (cons (cdr x) (car x))) (mv (msg "ERROR: ~x0 expected a cons, but was given ~x1.~|" 'invert1a x) nil))) (defun invert2a (x1 x2) (mv-let (erp1 y1) (invert1a x1) (mv-let (erp2 y2) (invert1a x2) (if erp1 (if erp2 (cw "~x0 failed with two errors:~| ~@1 ~@2" 'invert2a erp1 erp2) (cw "~x0 failed with one error:~| ~@1" 'invert2a erp1)) (if erp2 (cw "~x0 failed with one error:~| ~@1" 'invert2a erp2) (list y1 y2)))))) For example: ACL2 !>(invert2a '(3 . 4) '(5 . 6)) ((4 . 3) (6 . 5)) ACL2 !>(invert2a '(3 . 4) 'b) INVERT2A failed with one error: ERROR: INVERT1A expected a cons, but was given B. NIL ACL2 !>(invert2a 'a 'b) INVERT2A failed with two errors: ERROR: INVERT1A expected a cons, but was given A. ERROR: INVERT1A expected a cons, but was given B. NIL ACL2 !> If you study the example above, you might well understand [47mmsg[0m. But we conclude with precise documentation. General Form: (msg str arg1 ... argk) where [47mstr[0m is a string and [47mk[0m is at most 9. This macro returns a pair suitable for giving to the [47mfmt[0m directive [47m~@[0m. Thus, suppose that [47m#\c[0m is bound to the value of [47m(msg str arg1 ... argk)[0m, where [47mc[0m is a character and [47mk[0m is at most 9. Then the [47mfmt[0m directive [47m~@c[0m will print out the string, [47mstr[0m, in the context of the alist in which the successive [47mfmt[0m variables [47m#\0[0m, [47m#\1[0m, ..., [47m#\k[0m are bound to the successive elements of [47m(arg1 ... argk)[0m.") (msgp (io acl2-built-ins) "Recognizer for a ``message'' The form [47m(msgp x)[0m evaluates to true when [47mx[0m evaluates either to a string or to a [47mcons[0m whose [47mcar[0m is a string and whose [47mcdr[0m satisfies [47m[character-alistp][0m. Note that [47mmsgp[0m will always hold for the output of the macro [msg]. [31;1mFunction: [0m<msgp> (defun msgp (x) (declare (xargs :guard t)) (or (stringp x) (and (consp x) (stringp (car x)) (character-alistp (cdr x)))))") (multiple-value (pointers) "See [mv-let].") (must-be-equal (mbe acl2-built-ins) "Attach code for execution The form [47m(must-be-equal logic exec)[0m evaluates to [47mlogic[0m in the ACL2 logic but evaluates to [47mexec[0m in raw Lisp. The point is to be able to write one definition to reason about logically but another for evaluation. Please see [mbe] and see [mbt] for appropriate macros to use, rather than calling [47mmust-be-equal[0m directly, since it is easy to commute the arguments of [47mmust-be-equal[0m by accident. In essence, the guard for [47m(must-be-equal x y)[0m is [47m(equal x y)[0m. However, note that [47mmust-be-equal[0m is a macro: [47m(must-be-equal logic exec)[0m expands to [47m(mbe1 exec logic)[0m, which expands to a call of [47m[return-last][0m.") (mutual-recursion (events programming defun) "Define some mutually recursive functions See [defun] for relevant background. Example: (mutual-recursion (defun evenlp (x) (if (consp x) (oddlp (cdr x)) t)) (defun oddlp (x) (if (consp x) (evenlp (cdr x)) nil))) General Form: (mutual-recursion def1 ... defn) where each [47mdefi[0m is a call of [47m[defun][0m, [47m[defund][0m, [47m[defun-nx][0m, or [47mdefund-nx[0m. Note that although one definition is acceptable, we focus on the case of at least two definitions, since normally one would not bother with [47mmutual-recursion[0m otherwise. When mutually recursive functions are introduced it is necessary to do the termination analysis on the entire clique of definitions. Each [47m[defun][0m form specifies its own measure, either with the [47m:measure[0m keyword [47mxarg[0m (see [xargs]) or by default to [47m[ACL2-count][0m. When a function in the clique calls a function in the clique, the measure of the callee's actuals must be smaller than the measure of the caller's formals --- just as in the case of a simply recursive function. But with mutual recursion, the callee's actuals are measured as specified by the callee's [47m[defun][0m while the caller's formals are measured as specified by the caller's [47m[defun][0m. These two measures may be different but must be comparable in the sense that [47m[o<][0m decreases through calls. If you want to specify [47m:[0m[47m[hints][0m or [47m:guard-hints[0m (see [xargs]), you can put them in the [47m[xargs][0m declaration of any of the [47m[defun][0m forms, as the [47m:[0m[47m[hints][0m from each form will be appended together, as will the [47m:[0m[47m[guard-hints][0m from each form. However, for the following [47m[xargs][0m declarations, listed alphabetically, it is illegal to specify more than one value, though it is legal to specify the same value more than once. :GUARD-DEBUG :GUARD-SIMPLIFY :LOOP$-RECURSION :MEASURE-DEBUG :MODE :NON-EXECUTABLE :NORMALIZE :OTF-FLG :SPLIT-TYPES :VERIFY-GUARDS :WELL-FOUNDED-RELATION Thus, for example, you may specify [47m:guard-debug t[0m in two different [47mdefun[0m forms in your [47mmutual-recursion[0m call, in which case the [guard-debug] feature will be active; but you must not specify [47m:guard-debug t[0m in one [47mdefun[0m but [47m:guard-debug nil[0m in another. It suffices to specify such a value once, as that will apply throughout analysis of the [47mmutual-recursion[0m form. You may find it helpful to use a lexicographic order, the idea being to have a measure that returns a list of two arguments, where the first takes priority over the second. Here is an example. (include-book "ordinals/lexicographic-ordering" :dir :system) (encapsulate () (set-well-founded-relation l<) ; will be treated as LOCAL (mutual-recursion (defun foo (x) (declare (xargs :measure (list (acl2-count x) 1))) (bar x)) (defun bar (y) (declare (xargs :measure (list (acl2-count y) 0))) (if (zp y) y (foo (1- y)))))) The [47m[guard][0m analysis must also be done for all of the functions at the same time. If any one of the [47m[defun][0ms specifies the [47m:[0m[47m[verify-guards][0m [47mxarg[0m to be [47mnil[0m, then [guard] verification is omitted for all of the functions. Similarly, if any one of the [47m[defun][0ms specifies the [47m:non-executable[0m [47mxarg[0m to be [47mt[0m, or if any of the definitions uses [47m[defun-nx][0m or [47mdefund-nx[0m, then every one of the definitions will be treated as though it specifies a [47m:non-executable[0m [47mxarg[0m of [47mt[0m. Technical Note: Each [47mdefi[0m above must be a call of [47m[defun][0m, [47m[defund][0m, [47m[defun-nx][0m, or [47mdefund-nx[0m. In particular, it is not permitted for a [47mdefi[0m to be an arbitrary form that macroexpands into a [47m[defun][0m form. This is because [47mmutual-recursion[0m is itself a macro, and since macroexpansion occurs from the outside in, at the time [47m(mutual-recursion def1 ... defk)[0m is expanded the [47mdefi[0m have not yet been macroexpanded. Suppose you have defined your own [47m[defun][0m-like macro and wish to use it in a [47mmutual-recursion[0m expression. Well, you can't. (!) But you can define your own version of [47mmutual-recursion[0m that allows your [47m[defun][0m-like form. Here is an example. Suppose you define (defmacro my-defun (&rest args) (my-defun-fn args)) where [47mmy-defun-fn[0m takes the arguments of the [47mmy-defun[0m form and produces from them a [47m[defun][0m form. As noted above, you are not allowed to write [47m(mutual-recursion (my-defun ...) ...)[0m. But you can define the macro [47mmy-mutual-recursion[0m so that (my-mutual-recursion (my-defun ...) ... (my-defun ...)) expands into [47m(mutual-recursion (defun ...) ... (defun ...))[0m by applying [47mmy-defun-fn[0m to each of the arguments of [47mmy-mutual-recursion[0m. (defun my-mutual-recursion-fn (lst) (declare (xargs :guard (alistp lst))) ; Each element of lst must be a consp (whose car, we assume, is always ; MY-DEFUN). We apply my-defun-fn to the arguments of each element and ; collect the resulting list of DEFUNs. (cond ((atom lst) nil) (t (cons (my-defun-fn (cdr (car lst))) (my-mutual-recursion-fn (cdr lst)))))) (defmacro my-mutual-recursion (&rest lst) ; Each element of lst must be a consp (whose car, we assume, is always ; MY-DEFUN). We obtain the DEFUN corresponding to each and list them ; all inside a MUTUAL-RECURSION form. (declare (xargs :guard (alistp lst))) (cons 'mutual-recursion (my-mutual-recursion-fn lst))). Subtopics [Defuns] An alternative to [47m[mutual-recursion][0m [Mutual-recursion-proof-example] A small proof about mutually recursive functions [Set-bogus-mutual-recursion-ok] Allow unnecessary ``mutual recursion''") (mutual-recursion-proof-example (tutorial5-miscellaneous-examples mutual-recursion) "A small proof about mutually recursive functions Sometimes one wants to reason about mutually recursive functions. Although this is possible in ACL2, it can be a bit awkward. This example is intended to give some ideas about how one can go about such proofs. For an introduction to mutual recursion in ACL2, see [mutual-recursion]. We begin by defining two mutually recursive functions: one that collects the variables from a [term], the other that collects the variables from a list of [term]s. We actually imagine the [term] argument to be a [47mpseudo-termp[0m; see [pseudo-termp]. (mutual-recursion (defun free-vars1 (term ans) (cond ((atom term) (add-to-set-eq term ans)) ((fquotep term) ans) (t (free-vars1-lst (cdr term) ans)))) (defun free-vars1-lst (lst ans) (cond ((atom lst) ans) (t (free-vars1-lst (cdr lst) (free-vars1 (car lst) ans))))) ) Now suppose that we want to prove the following theorem. (defthm symbol-listp-free-vars1-try-1 (implies (and (pseudo-termp x) (symbol-listp ans)) (symbol-listp (free-vars1 x ans)))) Often ACL2 can generate a proof by induction based on the structure of definitions of function symbols occurring in the conjecture. In this case, ACL2 chooses to use an induction scheme suggested by [47m(symbol-listp ans)[0m, and sadly, that doesn't work. If one were doing this proof with pencil and paper, one would be more likely to prove a combination of the conjecture above and an analogous conjecture about free-vars1-lst. Feel free to try a pencil and paper proof! Or you can read on, to see how one can get ACL2 to do such a proof after all. The trick is to define a function that suggests an appropriate induction. The induction suggested is based on the if-then-else structure of the function's definition, where inductive hypotheses are generated for recursive calls --- below we explain how that works for this function. (defun symbol-listp-free-vars1-induction (x ans) (if (atom x) ; then we just make sure x and ans aren't considered irrelevant: (list x ans) (list (symbol-listp-free-vars1-induction (car x) ans) (symbol-listp-free-vars1-induction (cdr x) ans) (symbol-listp-free-vars1-induction (cdr x) (free-vars1 (car x) ans))))) The if-then-else structure of this function generates two cases. In one case, [47m(atom x)[0m is true, and the theorem to be proved should be proved under no additional hypotheses except for [47m(atom x)[0m; in other words, [47m(atom x)[0m gives us the base case of the induction. In the other case, [47m(not (atom x))[0m is assumed together with three instances of the theorem to be proved, one for each recursive call. So, one instance substitutes [47m(car x)[0m for [47mx[0m; one substitutes [47m(cdr x)[0m for [47mx[0m; and the third substitutes [47m(cdr x)[0m for [47mx[0m and [47m(free-vars1 (car x) ans)[0m for [47mans[0m. If you think about how you would go about a hand proof of the theorem to follow, you'll likely come up with a similar scheme. We now prove the two theorems together as a conjunction, because the inductive hypotheses for one are sometimes needed in the proof of the other (even when you do this proof on paper!). (defthm symbol-listp-free-vars1 (and (implies (and (pseudo-termp x) (symbol-listp ans)) (symbol-listp (free-vars1 x ans))) (implies (and (pseudo-term-listp x) (symbol-listp ans)) (symbol-listp (free-vars1-lst x ans)))) :hints (("Goal" :induct (symbol-listp-free-vars1-induction x ans)))) The above works, but we conclude by illustrating a more efficient approach, in which we restrict to appropriate inductive hypotheses for each case. (ubt 'symbol-listp-free-vars1-induction) (defun symbol-listp-free-vars1-induction (flg x ans) ; Flg is nil if we are ``thinking'' of a single term. (if (atom x) ; whether x is a single term or a list of terms (list x ans) (if flg ; i.e., if x is a list of terms (list (symbol-listp-free-vars1-induction nil (car x) ans) (symbol-listp-free-vars1-induction t (cdr x) (free-vars1 (car x) ans))) (symbol-listp-free-vars1-induction t (cdr x) ans)))) We now state the theorem as a conditional, so that it can be proved nicely using the [induction] scheme that we have just coded. The prover will not store an [47m[if][0m [term] as a [rewrite] rule, but that's OK (provided we tell it not to try), because we're going to derive the corollaries of interest later and make [31;1mthem[0m into [rewrite] rules. (defthm symbol-listp-free-vars1-flg (if flg (implies (and (pseudo-term-listp x) (symbol-listp ans)) (symbol-listp (free-vars1-lst x ans))) (implies (and (pseudo-termp x) (symbol-listp ans)) (symbol-listp (free-vars1 x ans)))) :hints (("Goal" :induct (symbol-listp-free-vars1-induction flg x ans))) :rule-classes nil) And finally, we may derive the theorems we are interested in as immediate corollaries. (defthm symbol-listp-free-vars1 (implies (and (pseudo-termp x) (symbol-listp ans)) (symbol-listp (free-vars1 x ans))) :hints (("Goal" :by (:instance symbol-listp-free-vars1-flg (flg nil))))) (defthm symbol-listp-free-vars1-lst (implies (and (pseudo-term-listp x) (symbol-listp ans)) (symbol-listp (free-vars1-lst x ans))) :hints (("Goal" :by (:instance symbol-listp-free-vars1-flg (flg t))))) You may find [community-books] that help you to automate this kind of reasoning about mutually recursive functions. See for example [make-flag].") (mv (basics acl2-built-ins) "Returning a multiple value [47mMv[0m is the mechanism provided by ACL2 for returning two or more values. Logically, [47m(mv x1 x2 ... xn)[0m is the same as [47m(list x1 x2 ... xn)[0m, a list of the indicated values. However, ACL2 avoids the cost of building this list structure, with the cost that [47mmv[0m may only be used in a certain style in definitions: if a function ever returns using [47mmv[0m (either directly, or by calling another function that returns a multiple value), then this function must always return the same number of values. For more explanation of the multiple value mechanism, see [mv-let]. Also see [mv-list] for a way to convert a multiple value into an ordinary list. ACL2 does not support the Common Lisp construct [47mvalues[0m, whose logical meaning seems difficult to characterize. [47mMv[0m is the ACL2 analogue of that construct. Subtopics [Mv-let] Calling multi-valued ACL2 functions [Mv-list] Converting [multiple-value] result to a single-value list [Mv-nth] The nth element (zero-based) of a multiply valued expression [Mv?] Return one or more values [Mv?-let] Calling possibly multi-valued ACL2 functions") (mv-let (mv basics acl2-built-ins) "Calling multi-valued ACL2 functions Example Form: (mv-let (x y z) ; local variables (mv 1 2 3) ; multi-valued expression (declare (ignore y)) ; optional declarations (cons x z)) ; body The form above binds the three ``local variables,'' [47mx[0m, [47my[0m, and [47mz[0m, to the three results returned by the multi-valued expression and then evaluates the body. The result is [47m'(1 . 3)[0m. The second local, [47my[0m, is [declare]d [47mignore[0md. The multi-valued expression can be any ACL2 expression that returns [47mk[0m results, where [47mk[0m is the number of local variables listed. Often however it is simply the application of a [47mk[0m-valued function. [47mMv-let[0m is the standard way to invoke a multi-valued function and then manipulate the values returned. General Form: (mv-let (var1 ... vark) term body) or (mv-let (var1 ... vark) term (declare ...) ... (declare ...) body) where the [47mvari[0m are distinct variables, [47mterm[0m is a term that returns [47mk[0m results and mentions only variables bound in the environment containing the [47mmv-let[0m expression, and [47mbody[0m is a term mentioning only the [47mvari[0m and variables bound in the environment containing the [47mmv-let[0m. Each [47mvari[0m must occur in [47mbody[0m unless it is [declare]d [47mignore[0md or [47mignorable[0m in one of the optional [47m[declare][0m forms, unless this requirement is turned off; see [set-ignore-ok]. The value of the [47mmv-let[0m term is the result of evaluating [47mbody[0m in an environment in which the [47mvari[0m are bound, in order, to the [47mk[0m results obtained by evaluating [47mterm[0m in the environment containing the [47mmv-let[0m. Here is an extended example that illustrates both the definition of a multi-valued function and the use of [47mmv-let[0m to call it. Consider a simple binary tree whose interior nodes are [47m[cons][0mes and whose leaves are non-[47m[cons][0mes. Suppose we often need to know the number, [47mn[0m, of interior nodes of such a tree; the list, [47msyms[0m, of symbols that occur as leaves; and the list, [47mints[0m, of integers that occur as leaves. (Observe that there may be leaves that are neither symbols nor integers.) Using a multi-valued function we can collect all three results in one pass. Here is the first of two definitions of the desired function. This definition is ``primitive recursive'' in that it has only one argument and that argument is reduced in size on every recursion. (defun count-and-collect (x) ; We return three results, (mv n syms ints) as described above. (cond ((atom x) ; X is a leaf. Thus, there are 0 interior nodes, and depending on ; whether x is a symbol, an integer, or something else, we return ; the list containing x in as the appropriate result. (cond ((symbolp x) (mv 0 (list x) nil)) ((integerp x)(mv 0 nil (list x))) (t (mv 0 nil nil)))) (t ; X is an interior node. First we process the car, binding n1, syms1, and ; ints1 to the answers. (mv-let (n1 syms1 ints1) (count-and-collect (car x)) ; Next we process the cdr, binding n2, syms2, and ints2. (mv-let (n2 syms2 ints2) (count-and-collect (car x)) ; Finally, we compute the answer for x from those obtained for its car ; and cdr, remembering to increment the node count by one for x itself. (mv (1+ (+ n1 n2)) (append syms1 syms2) (append ints1 ints2))))))) This use of a multiple value to ``do several things at once'' is very common in ACL2. However, the function above is inefficient because it [append]s [47msyms1[0m to [47msyms2[0m and [47mints1[0m to [47mints2[0m, copying the list structures of [47msyms1[0m and [47mints1[0m in the process. By adding ``accumulators'' to the function, we can make the code more efficient. (defun count-and-collect1 (x n syms ints) (cond ((atom x) (cond ((symbolp x) (mv n (cons x syms) ints)) ((integerp x) (mv n syms (cons x ints))) (t (mv n syms ints)))) (t (mv-let (n2 syms2 ints2) (count-and-collect1 (cdr x) (1+ n) syms ints) (count-and-collect1 (car x) n2 syms2 ints2))))) We claim that [47m(count-and-collect x)[0m returns the same triple of results as [47m(count-and-collect1 x 0 nil nil)[0m. The reader is urged to study this claim until convinced that it is true and that the latter method of computing the results is more efficient. One might try proving the theorem (defthm count-and-collect-theorem (equal (count-and-collect1 x 0 nil nil) (count-and-collect x))). Hint: the inductive proof requires attacking a more general theorem. ACL2 does not support the Common Lisp construct [47mmultiple-value-bind[0m, whose logical meaning seems difficult to characterize. [47mMv-let[0m is the ACL2 analogue of that construct. Also see [mv] and see [mv-list].") (mv-list (mv acl2-built-ins) "Converting [multiple-value] result to a single-value list Example Forms: ; Returns the list (3 4): (mv-list 2 (mv 3 4)) ; Returns a list containing the three values returned by var-fn-count: (mv-list 3 (var-fn-count '(cons (binary-+ x y) z) nil)) General form: (mv-list n term) Logically, [47m(mv-list n term)[0m is just [47mterm[0m; that is, in the logic [47mmv-list[0m simply returns its second argument. However, the evaluation of a call of [47mmv-list[0m on explicit values always results in a single value, which is a ([47mnil[0m-terminated) list. For evaluation, the term [47mn[0m above (the first argument to an [47mmv-list[0m call) must ``essentially'' (see below) be an integer not less than 2, where that integer is the number of values returned by the evaluation of [47mterm[0m (the second argument to that [47mmv-list[0m call). We say ``essentially'' above because it suffices that the translation of [47mn[0m to a term (see [trans]) be of the form [47m(quote k)[0m, where [47mk[0m is an integer greater than 1. So for example, if [47mterm[0m above returns three values, then [47mn[0m can be the expression [47m3[0m, or [47m(quote 3)[0m, or even [47m(mac 3)[0m if [47mmac[0m is a macro defined by [47m(defmacro mac (x) x)[0m. But [47mn[0m cannot be [47m(+ 1 2)[0m, because even though that expression evaluates to [47m3[0m, nevertheless it translates to [47m(binary-+ '1 '2)[0m, not to [47m(quote 3)[0m. [47mMv-list[0m is the ACL2 analogue of the Common Lisp construct [47mmultiple-value-list[0m. [31;1mFunction: [0m<mv-list> (defun mv-list (input-arity x) (declare (xargs :guard t) (ignore input-arity)) x)") (mv-nth (mv acl2-built-ins) "The nth element (zero-based) of a multiply valued expression [47m(Mv-nth n l)[0m is the [47mn[0mth element of [47ml[0m, zero-based. If [47mn[0m is greater than or equal to the length of [47ml[0m, then [47mmv-nth[0m returns [47mnil[0m. [47m(Mv-nth n l)[0m has a [guard] that [47mn[0m is a non-negative integer. [47mMv-nth[0m is equivalent to the Common Lisp function [47m[nth][0m (although without the guard condition that the list is a [47m[true-listp][0m), but is used by ACL2 to access the nth value returned by a multiply valued expression. So, if you do proofs about functions that involve [47m[mv-let][0m, you may see calls of [47mmv-nth[0m in the prover output. For example, the following are logically equivalent: (mv-let (n1 n2) (mv (+ x y) (* x y)) (- n1 n2)) (let ((var (list (+ x y) (* x y)))) (let ((n1 (mv-nth 0 var)) (n2 (mv-nth 1 var))) (- n1 n2))) Here is a similar such example involving the ACL2 [state]. The following two forms are logically equivalent, but the second is only legal in contexts such as theorems (and proofs) rather than function definitions, since it violates single-threadedness restrictions (more on this below; also see [state] and see [stobj]). (mv-let (erp val state) (read-object ch state) (value (list erp val))) (let ((erp (mv-nth 0 (read-object ch state))) (val (mv-nth 1 (read-object ch state))) (state (mv-nth 2 (read-object ch state)))) (value (list erp val))) [47mMv-nth[0m is given some special treatment by the prover. To control that behavior see [theories-and-primitives]. Finally, we elaborate on the single-threadedness issue above. If [47mEXPR[0m is an expression that is multiply valued, then the form [47m(mv-nth n EXPR)[0m is illegal both in definitions and in forms submitted directly to the ACL2 loop. Indeed, [47mEXPR[0m cannot be passed as an argument to any function ([47mmv-nth[0m or otherwise) in such an evaluation context. The reason is that ACL2 code compiled for execution does not actually create a list for multiple value return; for example, the [47mread-object[0m call above logically returns a list of length 3, but when evaluated, it instead stores its three returned values without constructing a list. The upshot is that it is generally best not to call [47mmv-nth[0m directly, but rather to use [47m[mv-let][0m, which generates [47mmv-nth[0m calls for reasoning but not for Lisp evaluation. However, if you really want to use [47mmv-nth[0m directly to access a multiply-valued result, then --- at the cost of computational efficiency --- you can use [47m[mv-list][0m, writing [47m(mv-nth n (mv-list k EXPR))[0m for suitable [47mk[0m, where [47mmv-list[0m converts a multiple value result into the corresponding list; see [mv-list]. [31;1mFunction: [0m<mv-nth> (defun mv-nth (n l) (declare (xargs :guard (and (integerp n) (>= n 0)))) (if (atom l) nil (if (zp n) (car l) (mv-nth (- n 1) (cdr l)))))") (mv? (mv acl2-built-ins) "Return one or more values [47mMv?[0m is designed to work with [47mmv?-let[0m, generalizing how [47m[mv][0m works with [47m[mv-let][0m by allowing the binding of a single variable. For example, the following form is legal. (mv?-let (y) (mv? (f x)) (declare (type integer y)) (g x y z)) The expression above is equivalent to the following expression, because [47m(mv? form)[0m expands to [47mform[0m for any expression, [47mform[0m. (let ((y (f x))) (declare (type integer y)) (g x y z)) Logically, [47m(mv? x)[0m is the same as [47mx[0m, while [47m(mv? v1 v2 ...)[0m is the same as [47m(list v1 v2 ...)[0m. Also see [mv] and see [mv?-let].") (mv?-let (mv acl2-built-ins) "Calling possibly multi-valued ACL2 functions [47mMv?-let[0m is a macro that extends the macro [47m[mv-let][0m by allowing a single variable to be bound. Thus, the syntax is the same as that of [47m[mv-let][0m except that [47mmv?-let[0m is permitted to bind a single variable to a form that produces a single value. The macros [47mmv?-let[0m and [47m[mv?][0m are provided to facilitate the writing of macros that traffic in expressions that could return one or more (multiple) values. For example, the form (mv?-let (y) (f x) (declare (type integer y)) (g x y z)) is equivalent to the following form. (let ((y (f x))) (declare (type integer y)) (g x y z)) Calls of [47mmv?-let[0m and of [47m[mv-let][0m are equivalent when the first argument contains at least two variables; see [mv-let] for documentation. In the case of binding a single variable, the general form is (mv?-let (var) term (declare ...) ... (declare ...) body) and this is equivalent to the following form (see [let]). (let ((var term)) (declare ...) ... (declare ...) body) Also see [mv?].") (name (events) "Syntactic rules on logical names Examples Counter-Examples PRIMEP 91 (not a symbolp) F-AC-23 :CHK-LIST (in KEYWORD package) 1AX *PACKAGE* (in the Lisp Package) |Prime Number| 1E3 (not a symbolp) Many different ACL2 entities have names, e.g., functions, macros, variables, constants, packages, theorems, [theories], etc. Package names are strings. All other names are symbols and may not be in the [47m"KEYWORD"[0m package. Moreover, names of functions, macros, constrained functions, and constants, other than those that are predefined, must not be in the ``main Lisp package'' (which is ([47m"LISP"[0m or [47m"COMMON-LISP"[0m, according to whether we are following CLTL1 or CLTL2). An analogous restriction on variables is given below. [47mT[0m, [47mnil[0m, and all names above except those that begin with ampersand (&) are names of variables or constants. [47mT[0m, [47mnil[0m, and those names beginning and ending with star (*) are constants. All other such names are variables. Note that names that start with ampersand, such as [47m&rest[0m, may be lambda list keywords and are reserved for such use whether or not they are in the CLTL constant [47mlambda-list-keywords[0m. (See pg 82 of CLTL2.) That is, these may not be used as variables. Unlike constants, variables may be in the main Lisp package as long as they are in the original list of imports from that package to ACL2, the list [47m*common-lisp-symbols-from-main-lisp-package*[0m, and do not belong to a list of symbols that are potentially ``global.'' This latter list is the value of [47m*common-lisp-specials-and-constants*[0m. Our restrictions pertaining to the main Lisp package take into account that some symbols, e.g., [47mlambda-list-keywords[0m and [47mboole-c2[0m, are ``special.'' Permitting them to be bound could have harmful effects. In addition, the Common Lisp language does not allow certain manipulations with many symbols of that package. So, we stay away from them, except for allowing certain variables as indicated above.") (name_the_formula_above (pages_written_especially_for_the_tours) "Name the Formula Above When the theorem prover explicitly assigns a name, like [47m*1[0m, to a formula, it has decided to prove the formula by induction.") (nat-listp (numbers lists acl2-built-ins) "Recognizer for a true list of natural numbers The predicate [47mnat-listp[0m tests whether its argument is a true list of natural numbers. [31;1mFunction: [0m<nat-listp> (defun nat-listp (l) (declare (xargs :guard t)) (cond ((atom l) (eq l nil)) (t (and (natp (car l)) (nat-listp (cdr l))))))") (natp (numbers acl2-built-ins) "A recognizer for the natural numbers The natural numbers is the set of all non-negative integers, [47m{0,1,2,3,...}[0m. [47mNatp[0m returns [47mt[0m if and only its argument is a natural number, and [47mnil[0m otherwise. The community book [arithmetic/natp-posp] has some lightweight rules for reasoning about [47mposp[0m and [47mnatp[0m, and is included in the [arithmetic-1] library. For a somewhat heavier and more comprehensive alternative, you may wish to instead see the [arith-equivs] book. [31;1mFunction: [0m<natp> (defun natp (x) (declare (xargs :guard t)) (and (integerp x) (<= 0 x)))") (near-misses (debugging) "Approximate event name matches General Form: (near-misses name) where [47mname[0m is a symbol. Community books [47m"xdoc/spellcheck"[0m and [47m"system/event-names"[0m are used automatically (by temporarily including them) to compute a list of names of [events] that approximate the given name. Example: ACL2 !>(near-misses nt) (NOT NTH) ACL2 !>") (nested-stobjs (stobj) "Using [stobj]s that contain stobjs For this topic we assume that you already understand the basics of single-threaded objects in ACL2. See [stobj], and in particular, see [defstobj], which notes that a stobj field can itself be a stobj, an array or hash-table of stobjs, or a [stobj-table]. The present [documentation] topic expands on that point. However, we ignore stobj-table fields here; see [stobj-table] for such documentation. Our presentation is in five sections. First we augment the documentation for [47m[defstobj][0m by explaining how stobjs may be specified for fields in a new stobj definition. Then we explain an aliasing problem, which accounts for a prohibition against making direct calls to accessors and updaters involving stobj fields of stobjs. Next, we introduce an ACL2 primitive, [47mstobj-let[0m, which provides the only way to read and write stobj components of stobjs. The fourth section provides precise documentation for [47mstobj-let[0m. We conclude by discussing the use of [47mstobj-let[0m with abstract stobjs (see [defabsstobj]); the discussion below ignores abstract stobjs until reaching that section. See also ACL2 community book [47mdemos/modeling/nested-stobj-toy-isa.lisp[0m for a worked example, which applies nested stobj structures to the problem of defining interpreters. A variety of small additional examples may be found in ACL2 community book [47mbooks/system/tests/nested-stobj-tests.lisp[0m; and yet another, this one using [47m[swap-stobjs][0m to exchange stobj fields of a stobj, is in [47mbooks/demos/swap-stobj-fields.lisp[0m. For further discussion, you are welcome to read the ``Essay on Nested Stobjs'', a long comment in ACL2 source file [47mother-events.lisp[0m. However, this documentation topic is intended to be self-contained for those familiar with [stobj]s. SECTION: Extension of [47m[defstobj][0m to permit [stobj]s within stobjs Recall that the [47m:type[0m keyword of a [47m[defstobj][0m field descriptor can be a ``type-indicator'' that specifies the type of the field as a type-spec (see [type-spec]). For example, the following specifies an integer field, a field that is an array of bytes, and a field that is a hash table whose values are integers. (defstobj st (int-field :type integer :initially 0) (ar-field :type (array unsigned-byte (10)) :initially 0) (ht-field :type (hash-table eql nil integer) :initially 0)) But the [47m:type[0m of a stobj field descriptor may instead be based on a stobj. For example, the following sequence of three [events] is legal. The first field descriptor of [47mtop[0m, named [47msub1-field[0m, illustrates one new kind of value for [47m:type[0m: the name of a previously-introduced stobj, which here is [47msub1[0m. The second field descriptor of [47mtop[0m, named [47msub2-ar-field[0m, illustrates a second new kind of value for [47m:type[0m: an array whose elements are specified by the name of a previously-introduced stobj, in this case, the stobj [47msub2[0m. The third field descriptor is analogous to the second, but with a hash table instead of an array. (See [stobj-table] for the fourth new kind of value for [47m:type[0m.) (defstobj sub1 fld1) (defstobj sub2 fld2) (defstobj top (sub1-field :type sub1) (sub2-ar-field :type (array sub2 (10))) (sub2-ht-field :type (hash-table equal nil sub2))) The [47m:initially[0m keyword is illegal for fields whose [47m:type[0m is a stobj, an array of stobjs, or a hash table of stobjs (or, not further discussed here, a [stobj-table]). For a stobj field, the initial value is provided by a corresponding call of the stobj creator for that stobj. For a field that is an array of stobjs, the stobj creator is called once for each element of the array, so that the array elements are distinct. For example, each element of [47msub2-ar-field[0m in the example above is initially provided by a separate call of [47mcreate-sub2[0m. Each initial element is thus unique, and in particular is distinct from the initial global value of the stobj. Similarly, the initial global stobj for [47msub1[0m is distinct from the initial [47msub1-field[0m field of the global stobj for [47mtop[0m, as these result from separate calls of [47mcreate-sub1[0m. For a hash-table field, the [47m:initially[0m keyword is not actually used for the initial hash table, which is empty. Instead, the [47m:initially[0m keyword typically determines the value returned when an accessor is applied to a key that is not bound --- but not for a hash table with stobj values. In that case, a fresh copy of the indicated stobj is returned when applying the accessor to an unbound key. When a stobj is used in a field of another stobj, we may refer to the former field as a ``child stobj'' and the latter stobj as a ``parent stobj''. So in the example above, [47msub1-field[0m is a child stobj of type [47msub1[0m for parent stobj [47mtop[0m, [47msub2-ar-field[0m is an array of child stobjs of type [47msub2[0m for parent stobj [47mtop[0m, and [47msub2-ht-field[0m is a hash table of child stobjs of type [47msub2[0m for parent stobj [47mtop[0m. A child stobj has the same structural shape as the global stobj of its type, but as explained above, these are distinct structures. We follow standard terminology by saying ``isomorphic'' to indicate the same structural shape. So for example, (the value of) [47msub1-field[0m is isomorphic to [47msub1[0m, though these are distinct structures. ACL2 enforces the following restriction, which can allow for greater efficiency in the raw Lisp code generated for [47mstobj-let[0m forms, as per the discussion below about clearing memoization tables. If the parent stobj is introduced by [47m[defstobj][0m using keyword argument [47m:non-memoizable t[0m, then this is required to have been the case for every child stobj as well. SECTION: An aliasing problem Before introducing [47mstobj-let[0m below, we provide motivation for this ACL2 primitive. Consider the following [events]. (defstobj child fld) (defstobj parent (fld2 :type child)) Now suppose we could evaluate the following code, to be run immediately after admitting the two [47m[defstobj][0m events above. (let* ((child (fld2 parent)) (child (update-fld 3 child))) (mv child parent)) Now logically there is no change to [47mparent[0m: [47mparent[0m is passed through unchanged. We can indeed prove that fact! (thm (equal (mv-nth 1 (let* ((child (fld2 parent)) (child (update-fld 3 child))) (mv child parent))) parent)) But recall that stobjs are updated with destructive assignments. That is, we really are updating [47m(fld2 parent)[0m to be the new value of [47mchild[0m, whether this is explained logically or not. Thus, evaluation of the above [47m[let*][0m form does in fact change the actual global stobj, [47mparent[0m. (Aside: Here is an explanation involving raw Lisp, for those who might find this useful. We escape to raw Lisp and execute the following. (let ((parent (cdr (assoc-eq 'parent *user-stobj-alist*)))) (let* ((child (fld2 parent)) (child (update-fld 4 child))) (mv child parent))) Then, in raw Lisp, [47m(fld (fld2 (cdr (assoc-eq 'parent *user-stobj-alist*))))[0m evaluates to [47m4[0m, illustrating the destructive update. End of Aside.) Such aliasing can permit a change to a child stobj to cause a logically-inexplicable change to the parent stobj. Similarly, unfettered accessing of stobj fields can result in logically inexplicable changes to the child stobj when the parent stobj is changed. Thus, ACL2 disallows direct calls of stobj accessors and updaters for fields whose [47m:type[0m is a stobj or an array or hash table of stobjs (or a [stobj-table]). Instead, ACL2 provides [47mstobj-let[0m for reading and writing such fields in a sound manner. SECTION: Accessing and updating stobj fields of stobjs using [47mstobj-let[0m ACL2 provides a primitive, [47mstobj-let[0m, to access and update stobj fields of stobjs, in a manner that avoids the aliasing problem discussed above. In this section we provide an informal introduction to [47mstobj-let[0m, using examples, to be followed in the next section by precise documentation. We begin by returning to a slight variant of the example above. (defstobj child fld) (defstobj parent (fld2 :type child) fld3) The following form returns the result of updating the [47mfld2[0m field of [47mparent[0m, which is a stobj isomorphic to [47mchild[0m, to have a value of 3. Below we explain the terms ``bindings'', ``producer variables'', ``producer'', and ``consumer'', as well as how to understand this form. (Note that ``producer variables'' refers to a list of one or more variables.) (stobj-let ((child (fld2 parent))) ; bindings (child) ; producer variables (update-fld 3 child) ; producer (update-fld3 'a parent)) ; consumer The four lines under ``[47mstobj-let[0m'' just above can be understood as follows. * Bindings: Bind [47mchild[0m to [47m(fld2 parent)[0m. * Producer variables and producer: Then bind the variable, [47mchild[0m, to the value of the producer, [47m(update-fld 3 child)[0m. * Implicit update of parent: Update [47mfld2[0m of [47mparent[0m with the producer variable, [47mchild[0m. * Consumer: Finally, return [47m(update-fld3 'a parent)[0m. Thus, the logical expansion of the [47mstobj-let[0m form above is the following expression, though this is approximate (see below). (let ((child (fld2 parent))) ; bindings (let ((child (update-fld 3 child))) ; bind producer variables to producer (let ((parent (update-fld2 child parent))) ; implicit update of parent (update-fld3 'a parent)))) The bindings always bind distinct names to child stobjs of a unique parent stobj, where the child stobj corresponds to the [47m:type[0m associated with the indicated accessor in the [47m[defstobj][0m form for the parent stobj. Thus in this case, for the unique binding, variable [47mchild[0m is bound to the stobj of `type' [47mchild[0m for accessor [47mfld2[0m of the parent stobj, [47mparent[0m. We refer to [47mchild[0m from the bindings as a ``stobj-let-bound variable''. Note also that the ``implicit extra step'' mentioned above is generated by macroexpansion of [47mstobj-let[0m; it logically updates the parent with new child values, just before calling the consumer. Implementation note for those using [memoization]: destructive updating in raw Lisp lets us omit this implicit extra step, though the raw Lisp code generated for [47mstobj-let[0m will clear the memoization table for every function taking the parent stobj as an input, if any child stobj bound in the bindings is among the producer variables --- unless the parent stobj was introduced by [47m[defstobj][0m using keyword argument [47m:non-memoizable t[0m. The form above is equivalent to the form displayed just below, which differs only in specifying an explicit stobj updater corresponding to the stobj accessor, [47mfld2[0m. Here we show the default updater name, whose name has [47m"UPDATE-"[0m prepended to the name of the accessor. But if the [47m:RENAMING[0m field of the [47mdefstobj[0m event specified a different updater name corresponding to [47mfld2[0m, then that would need to be included where we have added [47mupdate-fld2[0m below. (stobj-let ((child (fld2 parent) update-fld2)) ; bindings, including updater(s) (child) ; producer variables (update-fld 3 child) ; producer (update-fld3 'a parent)) ; consumer You can experiment using [47m:[0m[47m[trans1][0m to see the single-step macroexpansion of a [47mstobj-let[0m form in the logic. For example, here is how that works for a [47mstobj-let[0m form that binds three fields and updates two of them. Notice that because more than one field is updated, an [47m[mv-let][0m form is generated to bind the two fields to their values returned by the producer, rather than a [47m[let][0m form as previously generated. First, let's introduce some events. (defstobj child1 child1-fld) (defstobj child2 child2-fld) (defstobj child3 child3-fld) (defstobj mom (fld1 :type child1) (fld2 :type child2) (fld3 :type child3)) ; Silly stub: (defun update-last-op (op mom) (declare (xargs :stobjs mom)) (declare (ignore op)) mom) (defun new-mom (mom) (declare (xargs :stobjs mom)) (stobj-let ((child1 (fld1 mom)) (child2 (fld2 mom)) (child3 (fld3 mom))) (child1 child3) (let* ((child1 (update-child1-fld 'one child1)) (child3 (update-child3-fld 'three child3))) (mv child1 child3)) (update-last-op 'my-compute mom))) Now let's look at the single-step macroexpansion of the above [47mstobj-let[0m form. ACL2 !>:trans1 (stobj-let ((child1 (fld1 mom)) (child2 (fld2 mom)) (child3 (fld3 mom))) (child1 child3) (let* ((child1 (update-child1-fld 'one child1)) (child3 (update-child3-fld 'three child3))) (mv child1 child3)) (update-last-op 'my-compute mom)) (PROGN$ (LET ((CHILD1 (FLD1 MOM)) (CHILD2 (FLD2 MOM)) (CHILD3 (FLD3 MOM))) (DECLARE (IGNORABLE CHILD1 CHILD2 CHILD3)) (MV-LET (CHILD1 CHILD3) (CHECK-VARS-NOT-FREE (MOM) (LET* ((CHILD1 (UPDATE-CHILD1-FLD 'ONE CHILD1)) (CHILD3 (UPDATE-CHILD3-FLD 'THREE CHILD3))) (MV CHILD1 CHILD3))) (LET* ((MOM (UPDATE-FLD1 CHILD1 MOM)) (MOM (UPDATE-FLD3 CHILD3 MOM))) (CHECK-VARS-NOT-FREE (CHILD1 CHILD2 CHILD3) (UPDATE-LAST-OP 'MY-COMPUTE MOM)))))) ACL2 !> If you try to evaluate a [47mstobj-let[0m form directly in the top-level loop, rather than from within a function body, you will get an error. The example above illustrates how [47mstobj-let[0m may be used in function bodies; here is another example, presented using an edited log. ACL2 !>(defstobj child fld) Summary Form: ( DEFSTOBJ CHILD ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) CHILD ACL2 !>(defstobj parent (fld2 :type child) fld3) Summary Form: ( DEFSTOBJ PARENT ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) PARENT ACL2 !>(defun f (parent) (declare (xargs :stobjs parent)) (stobj-let ((child (fld2 parent))) ; bindings (child) ; producer variables (update-fld 3 child) ; producer (update-fld3 'a parent))) ; consumer [[output omitted]] F ACL2 !>(f parent) <parent> ACL2 !>(defun check-f (parent) ; returns the value of the field of the child stobj (declare (xargs :stobjs parent)) (stobj-let ((child (fld2 parent))) ; bindings (val) ; producer variables (fld child) ; producer val)) ; consumer [[output omitted]] CHECK-F ACL2 !>(check-f parent) 3 ACL2 !> Notice that the second function defined above, [47mcheck-f[0m, uses a [47mstobj-let[0m form that returns an ordinary value: it reads a value from a child stobj, but does not write to the child stobj, as indicated by the lack of a child stobj among the producer variables. So for that [47mstobj-let[0m form, there is no implicit extra step. We labeled a [47mstobj-let[0m expansion above as ``approximate'' for two reasons, which we give here informally. (Now you know how to apply [47m:[0m[47m[trans1][0m to that [47mstobj-let[0m call to see the precise expansion.) First, [47mstobj-let[0m declares the stobj-let-bound variables to be [47mignorable[0m for the top [47mlet[0m bindings. Second, and more importantly, [47mstobj-let[0m imposes the following restrictions on the producer and consumer, to avoid the aliasing problem: it disallows references to the parent stobj in the producer and it also disallows references to any bound stobj (i.e., bound in the bindings) in the consumer. We conclude this section with examples based on a slight variation of the nested stobj example from the first section above. These events can also be found in ACL2 community book [47mbooks/system/tests/nested-stobj-tests.lisp[0m, immediately under the following comment: ; As promised in :doc stobj-let, we begin with an example from that :doc. Note that some lemmas were needed in order to complete the [guard] proof for the function [47mupdate-top[0m, which may be found in the above file; they are omitted below. First we introduce three stobjs. (defstobj kid1 fld1) (defstobj kid2 fld2) (defstobj mom (kid1-field :type kid1) (kid2-ar-field :type (array kid2 (5))) last-op) The next function takes a given index and a [47mmom[0m stobj, and swaps the value stored in the stobj in [47mmom[0m's [47mkid2-ar-field[0m array at that index with the value stored in the stobj in [47mmom[0m's [47mkid1-field[0m field. (defun mom-swap-fields (index mom) (declare (xargs :stobjs mom :guard (and (natp index) (< index (kid2-ar-field-length mom))))) (stobj-let ((kid1 (kid1-field mom)) (kid2 (kid2-ar-fieldi index mom))) (kid1 kid2) (let* ((val1 (fld1 kid1)) (val2 (fld2 kid2)) (kid1 (update-fld1 val2 kid1)) (kid2 (update-fld2 val1 kid2))) (mv kid1 kid2)) (update-last-op 'swap mom))) Function [47mmom.kid1-fld1[0m stores a given value in the given [47mmom[0m's [47mkid1-fld1[0m field. (defun mom.kid1-fld1 (val mom) (declare (xargs :stobjs mom)) (stobj-let ((kid1 (kid1-field mom))) (kid1) (update-fld1 val kid1) (update-last-op val mom))) We next combine the two functions above, according to an [47mop[0m argument, as indicated by the following definition. (defun update-mom (op mom) (declare (xargs :stobjs mom)) (cond ((and (consp op) (eq (car op) 'swap) (natp (cdr op)) (< (cdr op) (kid2-ar-field-length mom))) (mom-swap-fields (cdr op) mom)) (t (mom.kid1-fld1 op mom)))) The following checker function uses a [47mstobj-let[0m form like the ones above, a major difference being that the producer variable is not a stobj, since the producer does not modify any stobjs. (defun check-update-mom (index val1 val2 last-op mom) (declare (xargs :stobjs mom :mode :program :guard (or (null index) (and (natp index) (< index (kid2-ar-field-length mom)))))) (and (equal (last-op mom) last-op) (stobj-let ((kid1 (kid1-field mom)) (kid2 (kid2-ar-fieldi index mom))) (val) ; producer variables (and (equal val1 (fld1 kid1)) (equal val2 (fld2 kid2))) val))) Now let us run our update function to populate some fields within the [47mmom[0m stobj. (let* ((mom ; set mom to (3 (x0 x1 x2 x3 x4)) (update-mom 3 mom)) (mom ; set mom to (x1 (x0 3 x2 x3 x4)) (update-mom '(swap . 1) mom)) (mom ; set mom to (7 (x0 3 x2 x3 x4)) (update-mom 7 mom)) (mom ; set mom to (x0 (7 3 x2 x3 x4)) (update-mom '(swap . 0) mom)) (mom ; set mom to (5 (7 3 x2 x3 x4)) (update-mom 5 mom)) (mom ; set mom to (7 (5 3 x2 x3 x4)) (update-mom '(swap . 0) mom))) mom) Are the above values of 7, 5, and 3 as expected, with a last operation being a swap? Yes! ACL2 !>(and (check-update-mom 0 7 5 'swap mom) (check-update-mom 1 7 3 'swap mom)) T ACL2 !> Notice that above, we never tried to access two different entries of the array. This can be done, but we need to bind two different stobjs to those fields. Fortunately, congruent stobjs make this possible; see [defstobj], in particular the discussion of congruent stobjs. Since we want to bind two stobjs to values in the array that are isomorphic to the stobj [47mkid2[0m, we introduce a stobj congruent to [47mkid2[0m. (defstobj kid2a fld2a :congruent-to kid2) Then we can define our swapping function as follows. The [guard] proof obligation includes the requirement that the two indices be distinct, again to avoid an aliasing problem. (defun mom-swap-indices (i1 i2 mom) (declare (xargs :stobjs mom :guard (and (natp i1) (< i1 (kid2-ar-field-length mom)) (natp i2) (< i2 (kid2-ar-field-length mom)) (not (equal i1 i2))))) (stobj-let ((kid2 (kid2-ar-fieldi i1 mom)) (kid2a (kid2-ar-fieldi i2 mom))) (kid2 kid2a) (let* ((val2 (fld2 kid2)) (val2a (fld2 kid2a)) (kid2 (update-fld2 val2a kid2)) (kid2a (update-fld2 val2 kid2a))) (mv kid2 kid2a)) mom)) The aforementioned community book, [47mbooks/system/tests/nested-stobj-tests.lisp[0m, contains a corresponding checker immediately following this definition. Also see that book for an analogous example using a hash-table field in place of an array field; search there for ``hash tables with stobj value types''. SECTION: Precise documentation for [47mstobj-let[0m General Form: (stobj-let BINDINGS PRODUCER-VARIABLES PRODUCER CONSUMER) where [47mPRODUCER-VARIABLES[0m is a non-empty true list of legal variable names without duplicates, [47mPRODUCER[0m and [47mCONSUMER[0m are expressions, and [47mBINDINGS[0m is a list subject to the following requirements. [47mBINDINGS[0m is a non-empty true list of tuples, each of which has the form [47m(VAR ACCESSOR)[0m or [47m(VAR ACCESSOR UPDATER)[0m. Each [47mVAR[0m may occur only once, and to avoid aliasing, the same [47mACCESSOR[0m may not be bound more than once if at least one of the variables to which it's bound is among the [47mPRODUCER-VARIABLES[0m. There is a stobj name, [47mST[0m, previously introduced by [47m[defstobj][0m (not [47m[defabsstobj][0m), such that each [47maccessor[0m is of the form [47m(ACC ST)[0m or [47m(ACCi I ST)[0m, with the same stobj name ([47mST[0m) for each binding. Each of these accessors and (if supplied) updaters is a stobj accessor for the same stobj, which is typically [47mST[0m but may be a stobj congruent to [47mST[0m. In the case [47m(ACC ST)[0m, [47mACC[0m is the accessor for a scalar (hence not array, hash-table, or stobj-table) field. In the case [47m(ACC I ST)[0m, [47mACC[0m is the accessor for an array or hash-table field and [47mI[0m is either a symbol, a natural number, or a list [47m(quote C)[0m. If [47mUPDATER[0m is supplied, then it is a symbol that is the name of the stobj updater for the field of [47mST[0m accessed by [47mACCESSOR[0m. If [47mUPDATER[0m is not supplied, then for the discussion below we consider it to be, implicitly, the symbol in the same package as the function symbol [47mACC[0m of [47mACCESSOR[0m, obtained by prepending the string [47m"UPDATE-"[0m to the [47m[symbol-name][0m of [47mACC[0m unless the name of [47mACC[0m ends in [47m"-GET"[0m (suggesting a hash-table field access), in which case the implicit [47mUPDATER[0m is obtained by replacing the suffix [47m"-GET"[0m with [47m"-PUT"[0m. Finally, [47mACCESSOR[0m has a [signature] specifying a return value that is either [47mVAR[0m or is a stobj that is congruent to [47mVAR[0m. (This means that only stobjs may be bound in these bindings.) If the conditions above are met, then the General Form expands to one of the expressions below, depending on whether the list [47mPRODUCER-VARIABLES[0m has one member or more than one member, respectively. (But see below for extra code, denoted ``[47m<check>[0m'', that may be inserted if there are stobj array or hash-table accesses in [47mBINDINGS[0m.) We observe the following conventions. * Let [47mBINDINGS'[0m be the result of dropping each updater (if any) from [47mBINDINGS[0m, that is, replacing each tuple [47m(VAR ACCESSOR UPDATER)[0m in [47mBINDINGS[0m by [47m(VAR ACCESSOR)[0m. * Let [47mSTOBJ-LET-BOUND-VARIABLES[0m be the list of variables [47mVAR[0m discussed above, that is, [47m(strip-cars BINDINGS)[0m. * Let [47mUPDATES[0m be the result of mapping through [47mPRODUCER-VARIABLES[0m and, for each variable [47mVAR[0m that has a binding [47m(VAR ACCESSOR UPDATER)[0m in [47mBINDINGS[0m (where [47mUPDATER[0m may be implicit, as discussed above), collect into [47mUPDATES[0m the tuple [47m(ST (UPDATER VAR ST))[0m. For [47mPRODUCER-VARIABLES[0m = [47m(PRODUCER-VAR)[0m: (let BINDINGS' (declare (ignorable . STOBJ-LET-BOUND-VARIABLES)) (let ((PRODUCER-VAR PRODUCER)) (let* UPDATES CONSUMER))) Otherwise: (let BINDINGS' (declare (ignorable . STOBJ-LET-BOUND-VARIABLES)) (mv-let PRODUCER-VARIABLES PRODUCER (let* UPDATES CONSUMER))) Moreover, ACL2 places restrictions on the resulting expression: [47mST[0m must not occur free in [47mPRODUCER[0m when at least one variable in [47mSTOBJ-LET-BOUND-VARIABLES[0m occurs in [47mPRODUCER[0m; and every variable in [47mSTOBJ-LET-BOUND-VARIABLES[0m must not occur free in [47mCONSUMER[0m. If one of these conditions is violated, you will see an error message saying that ``It is forbidden to use'' the variable where it should not occur free. [47mStobj-let[0m forms can be evaluated using ordinary objects in theorem contexts, much as any form. They can also, of course, appear in function bodies. However, a [47mstobj-let[0m form cannot be evaluated directly in the top-level loop or other top-level contexts for execution (such as during [47m[make-event][0m expansion). Finally, let [47mFORM[0m denote the form displayed above (either case). When [47mFORM[0m appears in the body of a definition then in some cases, its translation into logic is an expression of the form [47m(PROG2$ <check> FORM[0m'), where [47mFORM'[0m is the translation of [47mFORM[0m. (See [term] for a discussion of translation.) The [47m<check>[0m expression generates an extra [guard] proof obligation, which guarantees that no aliasing occurs in [47mBINDINGS[0m for two variables bound to accesses of the same stobj array or hash table, when at least one of the two variables is a producer variable. When ACL2 determines that no such aliasing is possible, for example because all the array or hash-table accesses use distinct numeric indices or because there are no producer variables, then [47mFORM[0m does not undergo such replacement. Warning: The use of [47m:[0m[47m[trans1][0m will not show this addition of a check. But you can see it after admitting the definition of [47mFN[0m (perhaps using [47m[skip-proofs][0m if you are having difficulty admitting the definition), as follows. (untranslate (body 'FN nil (w state)) nil (w state)) SECTION: Using [47mstobj-let[0m with abstract stobjs This section shows how an abstract stobj may be considered to have child stobj accessors and updaters that may be used with [47mstobj-let[0m, in essentially in the same way that a child stobj of a concrete stobj may be accessed and updated with [47mstobj-let[0m. Below we assume familiarity with abstract stobjs; see [defabsstobj]. We begin with a specification of child stobj accessor/updater pairs for abstract stobjs. We then present an example. Finally we conclude by discussing aspects of [47mstobj-let[0m specific to abstract stobjs. Child stobj accessors and updaters for abstract stobjs The documentation for [47m[defabsstobj][0m notes a function spec in the [47m:EXPORTS[0m may introduce a child stobj accessor by including the keyword, [47m:UPDATER[0m, whose value is the corresponding child stobj updater. Here we flesh out that brief summary. An abstract stobj [47mst[0m is considered to have a child stobj with accessor [47macc[0m and updater [47mupd[0m if the [47mdefabsstobj[0m event introducing [47mst[0m has a pair of function specs of the following form. (acc :logic acc$a :exec acc$c :updater upd) ; and optionally, other keywords (upd :logic upd$a :exec upd$c) ; and optionally, other keywords It is required that [47macc$c[0m is a child stobj accessor for the foundational stobj, [47mst$c[0m, of [47mst[0m. It is also required that [47mupd$c[0m is the child stobj updater of [47mst$c[0m that corresponds to [47macc$c[0m. We may call [47macc[0m and [47mupd[0m a child stobj accessor/updater pair for [47mst[0m. Note that [47mst$c[0m may itself be an abstract stobj, in which case its exports [47macc$c[0m and [47mupd$c[0m must be a child stobj accessor/updater pair for [47mst$c[0m. For [47macc[0m and [47macc$c[0m as above, [47macc[0m is considered to be a scalar accessor if [47macc$c[0m is a scalar accessor, and otherwise [47macc[0m is an array or hash-table accessor (unless it is a stobj-table accessor, discussed elsewhere; see [stobj-table]); similarly for [47mupd[0m, which therefore is a scalar accessor if and only if [47macc[0m is a scalar accessor. A child stobj accessor/updater pair may be used in [47mstobj-let[0m in the same way when the parent is an abstract stobj as when the parent is a concrete stobj. Example uses of [47mstobj-let[0m for an abstract stobj The following basic example comes from the [community-book], [47mbooks/system/tests/abstract-stobj-nesting/two-usuallyequal-nums-stobj-simpler.lisp[0m, which is based on a book contributed by Sol Swords. This example introduces an abstract stobj with child stobj fields, and uses [47mstobj-let[0m to read and write those fields. For even simpler examples that illustrate array and hash-table fields, see community books [47mabsstobj-with-arrays.lisp[0m and [47mabsstobj-with-hash-tables.lisp[0m in the same directory as above. We start by introducing a concrete stobj with two child stobj fields, each of which represents a natural number, together with a ``valid bit'' that, when true, asserts the equality of those two numbers. (defstobj n$ (n$val :type (integer 0 *) :initially 0)) (defstobj n$2 (n$val$c :type (integer 0 *) :initially 0) :congruent-to n$) (defstobj two-usuallyequal-nums$c (uenslot1$c :type n$) ; stobj slot ; (uenslot2$c :type n$2) ; stobj slot ; (uenvalid$c :type (member t nil) :initially nil)) We represent this concrete stobj abstractly using a cons structure of the form [47m(valid slot1 . slot2)[0m for the valid bit and the two numbers. Here is the recognizer for that abstract stobj. (defun-nx two-usuallyequal-nums$ap (x) ; A two-usuallyequal-nums contains three fields (valid slot1 . slot2). Valid ; is Boolean, and slot1 and slot2 are n$ stobjs that must be equal if valid is ; T. (declare (xargs :guard t)) (and (consp x) (consp (cdr x)) (let* ((valid (car x)) (slot1 (cadr x)) (slot2 (cddr x))) (and (booleanp valid) (n$p slot1) (n$p slot2) (implies valid (equal slot1 slot2)))))) The next step is to define functions in support of the abstract stobj that we intend to introduce. Here is one such definition. (defun-nx update-uenslot1$a (n$ x) (declare (xargs :guard (and (two-usuallyequal-nums$ap x) (or (not (uenvalid$a x)) (non-exec (equal (n$val n$) (n$val (uenslot2$a x)))))) :stobjs n$)) (cons (car x) (cons n$ (cddr x)))) After introducing such functions we introduce our abstract stobj as follows (see the aforementioned book if you want details). Notice the use of the [47m:updater[0m keyword, which identifies child stobj fields of the new abstract stobj. Thus, [47muenslot1[0m accesses a child stobj field of the [47mtwo-usuallyequal-nums[0m stobj, and that field is updated by the specified [47m:updater[0m, [47mupdate-uenslot1[0m; similarly for [47muenslot2[0m and its corresponding updater, [47mupdate-uenslot2[0m. (defabsstobj two-usuallyequal-nums :exports ((uenslot1 :logic uenslot1$a :exec uenslot1$c :updater update-uenslot1) (uenslot2 :logic uenslot2$a :exec uenslot2$c :updater update-uenslot2) (uenvalid :logic uenvalid$a :exec uenvalid$c) (update-uenslot1 :logic update-uenslot1$a :exec update-uenslot1$c) (update-uenslot2 :logic update-uenslot2$a :exec update-uenslot2$c) (update-uenvalid :logic update-uenvalid$a :exec update-uenvalid$c))) We may now use [47mstobj-let[0m in the same way that we use it for concrete stobjs with child stobj fields. That point is illustrated by the following definition, which accesses the numbers in the two child stobj fields. (defun fields-of-two-usuallyequal-nums (two-usuallyequal-nums) (declare (xargs :stobjs two-usuallyequal-nums)) (stobj-let ; bindings: ((n$ (uenslot1 two-usuallyequal-nums)) (n$2 (uenslot2 two-usuallyequal-nums))) ; producer variables: (n1 n2) ; producer: (mv (n$val n$) (n$val n$2)) ; consumer: (list :n n1 :n2 n2 :valid (uenvalid two-usuallyequal-nums)))) Here is what we get when we we this function before updating the abstract stobj. ACL2 !>(fields-of-two-usuallyequal-nums two-usuallyequal-nums) (:N 0 :N2 0 :VALID NIL) ACL2 !> We can update the abstract stobj by first setting the valid bit to nil, so that we can sequentially update the two child stobjs. We say more about that point below. (defun update-two-usuallyequal-nums (n two-usuallyequal-nums) (declare (xargs :guard (natp n) :stobjs two-usuallyequal-nums)) (let* ((two-usuallyequal-nums (update-uenvalid nil two-usuallyequal-nums))) (stobj-let ((n$ (uenslot1 two-usuallyequal-nums)) (n$2 (uenslot2 two-usuallyequal-nums))) (n$ n$2) (let* ((n$ (update-n$val n n$)) (n$2 (update-n$val n n$2))) (mv n$ n$2)) (update-uenvalid t two-usuallyequal-nums)))) To see why we first update the valid bit to [47mnil[0m, consider the logical translation of the [47mstobj-let[0m form above. ACL2 !>(untranslate (body 'update-two-usuallyequal-nums nil (w state)) nil (w state)) (LET ((TWO-USUALLYEQUAL-NUMS (UPDATE-UENVALID NIL TWO-USUALLYEQUAL-NUMS))) (LET ((N$ (UENSLOT1 TWO-USUALLYEQUAL-NUMS)) (N$2 (UENSLOT2 TWO-USUALLYEQUAL-NUMS))) (MV-LET (N$ N$2) (LET* ((N$ (UPDATE-N$VAL N N$)) (N$2 (UPDATE-N$VAL N N$2))) (LIST N$ N$2)) (LET* ((TWO-USUALLYEQUAL-NUMS (UPDATE-UENSLOT1 N$ TWO-USUALLYEQUAL-NUMS)) (TWO-USUALLYEQUAL-NUMS (UPDATE-UENSLOT2 N$2 TWO-USUALLYEQUAL-NUMS))) (UPDATE-UENVALID T TWO-USUALLYEQUAL-NUMS))))) ACL2 !> We can see that if the valid bit were [47mt[0m before doing any updates, then the guard proof obligation would fail for the first child stobj update, made with [47mupdate-uenslot1[0m (as defined above; see its guard). The update works, as shown in the log below. ACL2 !>(update-two-usuallyequal-nums 17 two-usuallyequal-nums) <two-usuallyequal-nums> ACL2 !>(fields-of-two-usuallyequal-nums two-usuallyequal-nums) (:N 17 :N2 17 :VALID T) ACL2 !> Aspects of [47mstobj-let[0m specific to abstract stobjs As suggested by the example above, [47mstobj-let[0m operates about the same whether the parent stobj is a concrete stobj or an abstract stobj. In this section we discuss some differences. One difference is that the only field accessors in the [47mBINDINGS[0m are child stobj field accessors. After all those are the only exported functions for an abstract stobj that may be considered to correspond to fields.. Another difference is in the aliasing checks. Recall that for an abstract stobj [47mst[0m, each child stobj accessor has an [47m:EXEC[0m function that is a child stobj accessor of the foundational stobj, [47mst$c[0m, for [47mst[0m. If [47mst$c[0m is itself an abstract stobj then the [47m:EXEC[0m function for [47mst$c[0m is a child stobj accessor for the foundation of [47mst$c[0m; and so on. At the end of this chain we have a child stobj accessor for a concrete stobj, which we may call the underlying concrete child stobj accessor. The aliasing checks are actually done with respect to the underlying concrete child stobj accessors that correspond to the accessors in the [47mBINDINGS[0m. After all, under the hood those concrete stobj functions are the ones that are actually executed on the ``live'' stobj. Another aspect of [47mstobj-let[0m specific to abstract stobjs is how aborts are handled. If an abort occurs in the middle of a [47mstobj-let[0m that updates child stobjs, when the parent stobj is an abstract stobj, you may be put into an illegal state, with instructions for how to continue at your own risk. See [illegal-state]. Subtopics [Stobj-table] A [stobj] field mapping stobj names to stobjs") (never-memoize (memoize) "Mark a function as unsafe to memoize. Logically, this function just returns [47mnil[0m. But execution of [47m(never-memoize fn)[0m records that [47mfn[0m must never be memoized, so that any attempt to memoize [47mfn[0m will fail. Any function can be marked as unsafe to memoize; in fact, [47mfn[0m need not even be defined at the time it is marked. This is useful for prohibiting the memoization of functions that are known to involve destructive functions like [47mnreverse[0m.") (newline (io princ$) "Print a newline to a given output channel This function is simply a wrapper around a call to [princ$] for the purpose of printing the ASCII character 0x0A, also known as a newline or line feed. [31;1mFunction: [0m<newline> (defun newline (channel state) (declare (xargs :guard (and (symbolp channel) (open-output-channel-p channel :character state)))) (princ$ #\Newline channel state))") (nfix (numbers acl2-built-ins) "Coerce to a natural number [47mNfix[0m simply returns any natural number argument unchanged, returning [47m0[0m on an argument that is not a natural number. Also see [ifix], see [rfix], see [realfix], and see [fix] for analogous functions that coerce to an integer, a rational number, a real, and a number, respectively. [47mNfix[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<nfix> (defun nfix (x) (declare (xargs :guard t)) (if (and (integerp x) (>= x 0)) x 0))") (nfix-list (pointers) "See [l<].") (nil-goal (debugging) "How to proceed when the prover generates a goal of [47mNIL[0m Failed proofs generally conclude with lists of key checkpoints. (See [set-gag-mode] or [introduction-to-key-checkpoints] for an introduction to the notion of ``key checkpoint''.) These lists may sometimes be annotated as follows. [NOTE: A goal of NIL was generated. See :DOC nil-goal.] This [documentation] topic gives some ideas about how to think about the situation described by that message, that is: some goal has reduced to [47mNIL[0m. Suppose that you see the above NOTE. If you look at the proof log, you will see a message saying that a goal of [47mNIL[0m has been generated. This may indicate that the original goal is not a theorem, since most of the prover's activity is typically to replace a goal by an equivalent conjunction of its child subgoals. However, if some ancestor of the [47mNIL[0m goal has undergone a process other than simplification or destructor elimination --- that is, fertilization (heuristic use of equalities), generalization, or elimination of irrelevance --- then it is quite possible that the prover got to the [47mNIL[0m goal by replacing a goal by a stronger (and perhaps false) conjunction of child subgoals. Let's dig a bit deeper by considering two cases for production of a [47mNIL[0m subgoal. First consider the case that the subgoal is a key checkpoint at the top level or under a top-level induction --- that is, a key checkpoint listed in the proof [summary]. In that case, the original conjecture is very likely not a theorem. Otherwise, if you are using [gag-mode] (which is the case by default), then you may need to issue the command [47m:[0m[47m[pso][0m (``Print Saved Output'') to see whether the goal was strengthened from one that was originally a theorem; but here is what may be a better idea. Instead, it may be best to focus on the key checkpoints printed in the summary to see if they suggest useful [rewrite] rules to prove. If some [47mNIL[0m subgoal is under a key checkpoint at the top level or under a top-level induction, then as discussed above, the original conjecture is probably not a theorem. Therefore, in that case, ACL2 always prints a [47mNIL[0m subgoal first in a list of checkpoints printed in the [summary], so that a [47mNIL[0m subgoal comes quickly to your attention.") (ninth (nth acl2-built-ins) "Ninth member of the list See any Common Lisp documentation for details.") (no-duplicatesp (lists acl2-built-ins) "Check for duplicates in a list General Forms: (no-duplicatesp x) (no-duplicatesp x :test 'eql) ; same as above (eql as equality test) (no-duplicatesp x :test 'eq) ; same, but eq is equality test (no-duplicatesp x :test 'equal) ; same, but equal is equality test [47m(no-duplicatesp lst)[0m is true if and only if no member of [47mlst[0m occurs twice in [47mlst[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing elements of [47mlst[0m. The [guard] for a call of [47mno-duplicatesp[0m depends on the test. In all cases, the argument must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then the argument must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then the argument must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mno-duplicatesp[0m and its variants: [47m(no-duplicatesp-eq x lst)[0m is equivalent to [47m(no-duplicatesp x lst :test 'eq)[0m; [47m(no-duplicatesp-equal x lst)[0m is equivalent to [47m(no-duplicatesp x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mno-duplicatesp-equal[0m. [31;1mFunction: [0m<no-duplicatesp-equal> (defun no-duplicatesp-equal (l) (declare (xargs :guard (true-listp l))) (cond ((endp l) t) ((member-equal (car l) (cdr l)) nil) (t (no-duplicatesp-equal (cdr l)))))") (no-duplicatesp-eq (pointers) "See [no-duplicatesp].") (no-duplicatesp-equal (pointers) "See [no-duplicatesp].") (no-op (pointers) "See [hints] for information about the keyword [47m:no-op[0m.") (no-thanks (pointers) "See [hints] for information about the keyword [47m:no-thanks[0m.") (non-exec (guard acl2-built-ins) "Mark code as non-executable [47mNon-exec[0m is a macro such that logically, [47m(non-exec x)[0m is equal to [47mx[0m. However, the argument to a call of [47mnon-exec[0m need not obey the usual syntactic restrictions for executable code, and indeed, evaluation of a call of [47mnon-exec[0m will result in an error. Moreover, for any form occurring in the body of a function (see [defun]) that is a call of [47mnon-exec[0m, no guard proof obligations are generated for that form. The following example, although rather contrived, illustrates the use of [47mnon-exec[0m. One can imagine a less contrived example that efficiently computes return values for a small number of fixed inputs and, for other inputs, returns something logically ``consistent'' with those return values. (defun double (x) (case x (1 2) (2 4) (3 6) (otherwise (non-exec (* 2 x))))) We can prove that [47mdouble[0m is compliant with Common Lisp (see [guard]) and that it always computes [47m(* 2 x)[0m. (verify-guards double) (thm (equal (double x) (* 2 x))) We can evaluate double on the specified arguments. But a call of [47mnon-exec[0m results in an error message that reports the form that was supplied to [47mnon-exec[0m. ACL2 !>(double 3) 6 ACL2 !>(double 10) ACL2 Error in TOP-LEVEL: ACL2 has been instructed to cause an error because of an attempt to evaluate the following form (see :DOC non- exec): (* 2 X). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> During proofs, the error is silent; it is ``caught'' by the proof mechanism and generally results in the introduction of a call of [47m[hide][0m during a proof. Also see [defun-nx] for a utility that makes every call of a function non-executable, rather than a specified form. The following examples contrast [47mnon-exec[0m with [47m[defun-nx][0m, in particular illustrating the role of [47m[non-exec][0m in avoiding guard proof obligations. ; Guard verification fails: (defun-nx f1 (x) (declare (xargs :guard t)) (car x)) ; Guard verification succeeds after changing the guard above: (defun-nx f1 (x) (declare (xargs :guard (consp x))) (car x)) ; Guard verification succeeds: (defun f2 (x) (declare (xargs :guard t)) (non-exec (car x))) ; Evaluating (g1) prints "Hello" before signaling an error. (defun g1 () (f1 (cw "Hello"))) ; Evaluating (g2) does not print before signaling an error. (defun g2 () (non-exec (cw "Hello"))) ; Evaluating (h1) gives a guard violation for taking reciprocal of 0. (defun h1 () (f1 (/ 1 0))) ; Evaluating (h2) does not take a reciprocal, hence there is no guard ; violation for that; we just get the error expected from using non-exec. (defun h2 () (non-exec (/ 0)))") (non-executable (pointers) "See [xargs] for information about the keyword [47m:non-executable[0m.") (non-linear-arithmetic (linear) "Non-linear Arithmetic This documentation topic is divided into two parts. We first discuss the practical aspect of how to use the non-linear arithmetic extension to ACL2, and then the theory behind it. We assume that the reader is familiar with the material in [47m[linear-arithmetic][0m and that on [47m:[0m[47m[linear][0m rules. We begin our discussion of how to use non-linear arithmetic with a simple example. Assume that we wish to prove: (thm (implies (and (rationalp x) (rationalp y) (rationalp z) (< 0 y) (< x (* y z))) (< (floor x y) z))) Note that [47m(floor x y) <= (/ x y)[0m. Note also that if we divide both sides of [47mx < (* y z)[0m by [47my[0m, since [47m0 < y[0m, we obtain [47m(/ x y) < z[0m. By chaining these two inequalities together, we get the inequality we desired to prove. We now proceed with our example session: (skip-proofs (progn ; Since the truth of this theorem depends on the linear properties ; of floor, we will need the linear lemma: (defthm floor-bounds-1 (implies (and (rationalp x) (rationalp y)) (and (< (+ (/ x y) -1) (floor x y)) (<= (floor x y) (/ x y)))) :rule-classes ((:linear :trigger-terms ((floor x y))))) ; We now disable floor, so that the linear lemma will be used. (in-theory (disable floor)) ; We create five rewrite rules which we will use during non-linear ; arithmetic. The necessity for these is due to one of the differences in ; ACL2's behavior when non-linear arithmetic is turned on. Although ; the conclusions of linear lemmas have always been rewritten before ; they are used, now, when non-linear arithmetic is turned on, the ; conclusions are rewritten under a different theory than under ``normal'' ; rewriting. This theory is also used in other, similar, circumstances ; described below. (defthm |arith (* -1 x)| (equal (* -1 x) (- x))) (defthm |arith (* 1 x)| (equal (* 1 x) (fix x))) (defthm |arith (* x (/ x) y)| (equal (* x (/ x) y) (if (equal (fix x) 0) 0 (fix y)))) (defthm |arith (* y x)| (equal (* y x) (* x y))) (defthm |arith (fix x)| (implies (acl2-numberp x) (equal (fix x) x)))) ) ; End skip-proofs. ; We disable the above rewrite rules from normal use. (in-theory (disable |arith (* -1 x)| |arith (* 1 x)| |arith (* x (/ x) y)| |arith (* y x)| |arith (fix x)|)) ; We create an arithmetic-theory. Note that we must give a quoted ; constant for the theory --- none of the normal [47m[theory-functions][0m ; are applicable to in-arithmetic-theory. (in-arithmetic-theory '(|arith (* -1 x)| |arith (* 1 x)| |arith (* x (/ x) y)| |arith (* y x)| |arith (fix x)|)) ; We turn non-linear arithmetic on. (set-non-linearp t) ; We can now go ahead and prove our theorem. (thm (implies (and (rationalp x) (rationalp y) (rationalp z) (< 0 y) (< x (* y z))) (< (floor x y) z))) The above example illustrates the two practical requirements for using non-linear arithmetic in ACL2. First, one must set up an arithmetic-theory. Usually, one would not set up an arithmetic-theory on one's own but would instead load a library book or books which do so. Second, one must turn the non-linear arithmetic extension on. This one must do explicitly --- no book can do this for you. For a brief discussion of why this is so, even though [47m(set-non-linearp t)[0m is an embeddable event, see [ACL2-defaults-table] (in particular, the final paragraph). (Note that [47m(set-non-linearp t)[0m modifies the [47macl2-defaults-table[0m.) Also see [set-non-linearp], see [embedded-event-form], and see [events]. You can also enable non-linear arithmetic with the hint [47m:nonlinearp t[0m. See [hints]. We, in fact, recommend the use of a hint which will enable nonlinear arithmetic only when the goal has stabilized under rewriting. Using [47m[default-hints][0m can make this easier. (defun nonlinearp-default-hint (stable-under-simplificationp hist pspv) (cond (stable-under-simplificationp (if (not (access rewrite-constant (access prove-spec-var pspv :rewrite-constant) :nonlinearp)) '(:computed-hint-replacement t :nonlinearp t) nil)) ((access rewrite-constant (access prove-spec-var pspv :rewrite-constant) :nonlinearp) (if (not (equal (caar hist) 'SETTLED-DOWN-CLAUSE)) '(:computed-hint-replacement t :nonlinearp nil) nil)) (t nil))) (set-default-hints '((nonlinearp-default-hint stable-under-simplificationp hist pspv))) This has proven to be a helpful strategy which allows faster proof times. We now proceed to briefly describe the theory behind the non-linear extension to ACL2. In [47m[linear-arithmetic][0m it was stated that, ``[L]inear polynomial inequalities can be combined by cross-multiplication and addition to permit the deduction of a third inequality....'' That is, if 0 < poly1, 0 < poly2, and [47mc[0m and [47md[0m are positive rational constants, then 0 < c*poly1 + d*poly2. Similarly, given the above, 0 < poly1*poly2. In the linear arithmetic case, we are taking advantage of the facts that multiplication by a positive rational constant does not change the sign of a polynomial and that the sum of two positive polynomials is itself positive. In the non-linear arithmetic case, we are using the fact that the product of two positive polynomials is itself positive. For example, suppose we have the three assumptions: p1: 3*x*y + 7*a < 4 p2: 3 < 2*x or p2': 0 < -3 + 2*x p3: 1 < y or p3': 0 < -1 + y, and we wish to prove that [47ma < 0[0m. As described elsewhere (see [linear-arithmetic]), we proceed by assuming the negation of our goal: p4: 0 <= a, and looking for a contradiction. There are no cancellations which can be performed by linear arithmetic in the above situation. (Recall that two polynomials are canceled against each other only when they have the same largest unknown.) However, [47mp1[0m has a product as its largest unknown, and for each of the factors of that product there is a poly that has that factor as a largest unknown. When non-linear arithmetic is enabled, ACL2 will therefore multiply [47mp1'[0m and [47mp2'[0m obtaining p5: 0 < 3 + -2*x + -3*y + 2*x*y. The addition of this polynomial will allow cancellation to continue and, in this case, we will prove our goal. Thus, just as ACL2 adds two polynomials together when they have the same largest unknown of opposite signs in order to create a new ``smaller'' polynomial; so ACL2 multiplies polynomials together when the product of their largest unknowns is itself the largest unknown of another polynomial. As the use of [47m:[0m[47m[linear][0m lemmas to further seed the arithmetic database may allow cancellation to proceed, so may the use of non-linear arithmetic. This multiplication of polynomials is the motivation for an arithmetic-theory distinct from the normal one. Because this may be done so often, and because the individual factors have presumably already been rewritten, it is important that this be done in an efficient way. The use of a small, specialized, theory helps avoid the repeated application of rewrite rules to already stabilized terms. Subtopics [Set-non-linearp] To turn on or off non-linear arithmetic reasoning") (nonlinearp (pointers) "See [hints] for information about the keyword [47m:nonlinearp[0m.") (nonnegative-integer-quotient (numbers acl2-built-ins) "Natural number division function Example Forms: (nonnegative-integer-quotient 14 3) ; equals 4 (nonnegative-integer-quotient 15 3) ; equals 5 [47m(nonnegative-integer-quotient i j)[0m returns the integer quotient of the integers [47mi[0m and (non-zero) [47mj[0m, i.e., the largest [47mk[0m such that [47m(* j k)[0m is less than or equal to [47mi[0m. Also see [floor], see [ceiling] and see [truncate], which are derived from this function and apply to rational numbers. The [guard] of [47m(nonnegative-integer-quotient i j)[0m requires that [47mi[0m is a nonnegative integer and [47mj[0m is a positive integer. [31;1mFunction: [0m<nonnegative-integer-quotient> (defun nonnegative-integer-quotient (i j) (declare (xargs :guard (and (integerp i) (not (< i 0)) (integerp j) (< 0 j)))) (if (or (= (nfix j) 0) (< (ifix i) j)) 0 (+ 1 (nonnegative-integer-quotient (- i j) j))))") (nontautological_subgoals (pages_written_especially_for_the_tours) "Prover output omits some details The theorem prover's proof output is intended to suggest an outline of the reasoning process employed by its proof engine, which is virtually always more than is necessary for the ACL2 user. In particular, the output often omits subgoals that are sufficiently trivial, including tautologies.") (normalization (pointers) "See [normalize].") (normalize (xargs) "Storing simplified [definition] bodies and [guard]s By default, when you submit a [47m[defun][0m form, the body is simplified for certain later uses. This simplification is sometimes called ``normalization''; the ACL2 system function that accomplishes this task is [47mnormalize[0m. Consider the following examples, where we make two definitions and then show their bodies using [47m:[0m[47m[pf][0m.. ACL2 !>(defun f1 (x y) (cons (implies x y) (integerp 3))) [.. output omitted ..] F1 ACL2 !>(defun f2 (x y) (declare (xargs :normalize nil)) (cons (implies x y) (integerp 3))) [.. output omitted ..] F2 ACL2 !>:pf f1 (EQUAL (F1 X Y) (IF X (IF Y '(T . T) '(NIL . T)) '(T . T))) ACL2 !>:pf f2 (EQUAL (F2 X Y) (CONS (IMPLIES X Y) (INTEGERP 3))) ACL2 !> We see that the body of [47mf1[0m has undergone the default simplification (with [47mnormalize[0m), while the body of [47mf2[0m has not because of the [47m[xargs][0m in its [47mdefun[0m form. The example above illustrates that normalization consists of the following three parts: * propagation upward of [47mif[0m tests; * potential simplification with type reasoning (see [TYPE-REASONING]); and * the expansion of calls of a few built-in functions like [47m[implies][0m (the full list is the value of the constant, [47m*expandable-boot-strap-non-rec-fns*[0m). We have seen an example where type reasoning (see [TYPE-REASONING]) can be expensive. So when ACL2 normalizes [definition] bodies and [guard]s, it establishes a [backchain-limit] for [type-set] reasoning of 1, unless that limit is currently 0. (The global default is to have no limit.) Also see the [community-books] utility [47m[install-not-normalized][0m.") (normed (hons) "Normed objects are ACL2 Objects that are "canonical" or "unique" in a certain sense. In Common Lisp, we can tell whether an ACL2 object is [31;1mnormed[0m or not, but there is no way for an ordinary ACL2 function to see whether an object is normed. Hence, whether or not an object is normed is an implementation-level concept. The fundamental property of normed objects is that if A and B are both normed, then [47m(equal A B)[0m holds if and only if [47m(eql A B)[0m holds. For strings and conses, [47m(eql A B)[0m holds only when [47m(eq A B)[0m, so any normed conses or strings are [47m[equal][0m precisely when they are [47m[eq][0m. The potential benefits of having normed objects include: constant-time equality comparisons, reduced memory usage, fast association lists, and function memoization. Note that in our implementation, all symbols, characters, and numbers are automatically normed, and whenever a cons is normed its car and cdr must also be normed. The Meaning of Normed in Common Lisp. Recall that the ACL2 Objects are certain "good" Common Lisp symbols, characters, strings, and numbers, and the conses which can be recursively formed from these good atoms. Not all properties of these objects are visible in the ACL2 logic. An example of an invisible property is the pointer identity of an object. For example, suppose we write the following. (defconst *x* (cons 1 2)) (defconst *y* (cons 1 2)) In Common Lisp, [47m[cons][0m is guaranteed to provide a new pair that is distinct from any previously created pair, so we know that *x* and *y* will be distinct objects and we will be able to tell them apart from one another using [47meq[0m. But this difference is not visible in the ACL2 logic, and no ACL2 function can tell *x* apart from *y*. The normed-ness of an object is a similarly invisible property. In Common Lisp, invisible to ACL2, we maintain a data structure called a "Hons Space" that records which objects are normed. So, being normed is not an intrinsic property of an object, but instead is determined by whether the object is mentioned in this Hons Space. Notes about Garbage Collection. The Hons Space includes tables with pointers to every normed cons and string. One consequence of this is that normed objects cannot be reclaimed by Lisp's ordinary garbage collector, even after they have become unreachable from the perspective of an ACL2 program. For CCL and GCL users only, [47m[hons-wash][0m is a special kind of garbage collection that allows normed conses to be reclaimed. For other Lisps, the only option is to occasionally, manually clear out these Hons Space tables with [47m[hons-clear][0m.") (not (basics acl2-built-ins) "Logical negation [47mNot[0m is the ACL2 negation function. The negation of [47mnil[0m is [47mt[0m and the negation of anything else is [47mnil[0m. [47mNot[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<not> (defun not (p) (declare (xargs :guard t)) (if p nil t))") (note-1-1 (release-notes) "Acl2 Version 1.1 Notes The new features are extensively documented. The relevant topics are: It is especially important to read all of the [documentation] for [books] before trying to use books. However, the new [47m:more[0m keyword command is so handy for reading long [documentation] strings that we recommend you start with [47m:[0m[47m[doc][0m more if reading at the terminal. Some documentation has been written for [guard]s which you might find interesting.") (note-1-2 (release-notes) "Acl2 Version 1.2 Notes Hacker mode has been eliminated and [programming] mode has been added. [Programming] mode is unsound but does syntax checking and permits redefinitions of names. See [47m:[0m[47m[doc][0m [47mload-mode[0m and [47m:[0m[47m[doc][0m [47mg-mode[0m. The arguments to [47m[ld][0m have changed. [47m[Ld][0m is now much more sophisticated. See [ld]. For those occasions on which you wish to look at a large list structure that you are afraid to print, try [47m(walkabout x state)[0m, where [47mx[0m is an Acl2 expression that evaluates to the structure in question. I am afraid there is no [documentation] yet, but it is similar in spirit to the Interlisp structure editor. You are standing on an object and commands move you around in it. E.g., 1 moves you to its first element, 2 to its second, etc.; 0 moves you up to its parent; [47mnx[0m and [47mbk[0m move you to its next sibling and previous sibling; [47mpp[0m prettyprints it; [47m[q][0m exits returning [47mnil[0m; [47m[=][0m exits returning the thing you're standing on; [47m(= symb)[0m assigns the thing you're standing on to the [state] global variable [47msymb[0m. Several new [hints] have been implemented, including [47m:by[0m and [47m:do-not[0m. The old [47m:do-not-generalize[0m has been scrapped in favor of such new [hints] as [47m:do-not[0m [47m(generalize elim)[0m. [47m:By[0m lets you say ``this goal is subsumed by'' a given lemma instance. The [47m:by[0m hint also lets you say ``this goal can't be proved yet but skip it and see how the rest of the proof goes.'' See [hints].") (note-1-3 (release-notes) "Acl2 Version 1.3 Notes [Programming] mode has been eliminated. Instead, all functions have a ``color'' which indicates what can be done with the function. For example, [47m:red[0m functions can be executed but have no axioms describing them. Thus, [47m:red[0m functions can be introduced after passing a simple syntactic check and they can be redefined without undoing. But nothing of consequence can be proved about them. At the other extreme are [47m:gold[0m functions which can be executed and which also have passed both the termination and the [guard] verification proofs. The color of a function can be specified with the new [47m[xargs][0m keyword, [47m:color[0m, which, if omitted defaults to the global setting of [47mld-color[0m. [47mLd-color[0m replaces [47mload-mode[0m. Setting [47mld-color[0m to [47m:red[0m causes behavior similar to the old [47m:g-mode[0m. Setting [47mld-color[0m to [47m:gold[0m causes behavior similar to the old [47m:v-mode[0m. It is possible to prototype your system in [47m:red[0m and then convert [47m:red[0m functions to [47m:[0m[47mblue[0m individually by calling [47m[verify-termination][0m on them. They can then be converted to [47m:gold[0m with [47m[verify-guards][0m. This allows us to undertake to verify the termination and [guard]s of system functions. See [47m:[0m[47m[doc][0m color for an introduction to the use of colors. Type prescription rules have been added. Recall that in Nqthm, some [47m[rewrite][0m rules were actually stored as ``[type-prescription]s.'' Such rules allow the user to inform Nqthm's primitive type mechanism as to the kinds of shells returned by a function. Earlier versions of Acl2 did not have an analogous kind of rule because Acl2's type mechanism is complicated by [guard]s. Version 1.3 supports [47m[type-prescription][0m rules. See [type-prescription]. Three more new [rule-classes] implement congruence-based rewriting. It is possible to identify a binary relation as an equivalence relation (see [equivalence]), to show that one equivalence relation refines another (see [refinement]) and to show that a given equivalence relation is maintained when rewriting a given function call, e.g., [47m(fn ...xk...)[0m, by maintaining another equivalence relation while rewriting the [47mk[0mth argument (see [congruence]). If [47mr[0m has been shown to be an [equivalence] relation and then [47m(implies hyps (r (foo x) (bar x)))[0m is proved as a [47m:[0m[47m[rewrite][0m rule, then instances of [47m(foo x)[0m will be replaced by corresponding instances of [47m(bar x)[0m provided the instance occurs in a slot where the maintenance of [47mr-equivalence[0m is known to be sufficient and [47mhyps[0m can be established as usual. In Version 1.2, [rule-classes] were simple keywords, e.g., [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[elim][0m. In Version 1.3, [rule-classes] have been elaborated to allow you to specify how the theorem ought to be used as a rule. That is, the new [rule-classes] allows you to separate the mathematical statement of the formula from its interpretation as a rule. See [rule-classes]. Rules used to be named by symbols, e.g., [47m[car][0m and [47mcar-cons[0m were the names of rules. Unfortunately, this was ambiguous because there are three rules associated with function symbols: the symbolic definition, the executable-counterpart, and the [type-prescription]; many different rules might be associated with theorems, depending on the rule classes. In Version 1.3 rules are named by ``[rune]s'' (which is just short hand for ``rule names''). Example [rune]s are [47m(:definition car)[0m, [47m(:executable-counterpart car)[0m, and [47m(:type-prescription car . 1)[0m. Every rule added by an event has a different name and you can [enable] and [disable] them independently. See [rune] and see [theories]. The identity function [47m[force][0m, of one argument, has been added and given a special interpretation by the functions responsible for establishing hypotheses in backchaining: When the system fails to establish some hypothesis of the form [47m(force term)[0m, it simply assumes it is true and goes on, delaying until later the establishment of term. In particular, pushes a new subgoal to prove term in the current context. When that subgoal is attacked, all of the resources of the theorem prover, not just rewriting, are brought to bear. Thus, for example, if you wish to prove the rule [47m(implies (good-statep s) (equal (exec s n) s'))[0m and it is your expectation that every time [47mexec[0m appears its first argument is a [47mgood-statep[0m then you might write the rule as [47m(implies (force (good-statep s)) (equal (exec s n) s'))[0m. This rule is essentially an unconditional rewrite of [47m(exec s n)[0m to [47ms'[0m that spawns the new goal [47m(good-statep s)[0m. See [force]. Because you can now specify independently how a theorem is used as a rule, you need not write the [47m[force][0m in the actual theorem proved. See [rule-classes]. Version 1.3 supports a facility similar to Nqthm's [47m[break-lemma][0m. See [break-rewrite]. You can install ``[monitor]s'' on [rune]s that will cause interactive breaks under certain conditions. Acl2 also provides ``[wormhole]s'' which allow you to write functions that cause interaction with the user but which do not require that you have access to [47m[state][0m. See [wormhole]. The rewriter now automatically backchains to stronger recognizers. There is no user hook to this feature but it may simplify some proofs with which older versions of Acl2 had trouble. For example, if the rewriter is trying to prove [47m(rationalp (foo a b c))[0m it is now smart enough to try lemmas that match with [47m(integerp (foo a b c))[0m.") (note-1-4 (release-notes) "Acl2 Version 1.4 Notes Once again [47m[ld][0m only takes one required argument, as the [47mbind-flg[0m has been deleted. Three commands have been added in the spirit of [47m:[0m[47m[pe][0m. [47m:[0m[47m[Pe!][0m is similar to [47m:[0m[47m[pe][0m but it prints all [events] with the given name, rather than just the most recent. The command [47m:[0m[47m[pf][0m prints the corollary formula corresponding to a name or [rune]. The command [47m:[0m[47m[pl][0m (print lemmas) prints rules whose top function symbol is the given name. See [pe!], see [pf], and see [pl]. Book naming conventions have been changed somewhat. The once-required [47m.lisp[0m extension is now prohibited! Directories are supported, including a notion of ``connected book directory''. See [book-name]. Also, the second argument of [47m[certify-book][0m is now optional, defaulting to [47m0[0m. [Compilation] is now supported inside the Acl2 loop. See [comp] and see [set-compile-fns]. The default color is now part of the Acl2 [world]; see [47m:[0m[47m[doc][0m [47mdefault-color[0m. [47mLd-color[0m is no longer an [47m[ld][0m special. Instead, colors are [events]; see the documentation for [47mred[0m, [47mpink[0m, [47mblue[0m, and [47mgold[0m. A [table] exists for controlling whether Acl2 prints comments when it [force]s hypotheses of rules; see [47m:[0m[47m[doc][0m [47mforce-table[0m. Also, it is now possible to turn off the forcing of assumptions by disabling the definition of [force]; see [force]. The event [47mdefconstant[0m is no longer supported, but a very similar event, [47m[defconst][0m, has been provided in its place. See [defconst]. The event for defining [congruence] relations is now [47m[defcong][0m (formerly, [47mdefcon[0m). Patterns are now allowed in [47m:expand[0m [hints]. See the documentation for [47m:expand[0m inside the documentation for [hints]. We have improved the way we report rules used by the simplifier. All [rune]s of the same type are reported together in the running commentary associated with each goal, so that for example, executable-counterparts are listed separately from definitions, and rewrite rules are listed separately from [linear] rules. The preprocessor now mentions ``simple'' rules; see [simple]. The mechanism for printing warning messages for new rewrite rules, related to subsumption, now avoids worrying about nonrecursive function symbols when those symbols are [disable]d. These messages have also been eliminated for the case where the old rule is a [47m:[0m[47m[definition][0m rule. Backquote has been modified so that it can usually provide predictable results when used on the left side of a rewrite rule. Time statistics are now printed even when an event fails. The Acl2 trace package has been modified so that it prints using the values of the Lisp globals [47m*print-level*[0m and [47m*print-length*[0m (respectively). [Table] has been modified so that the [47m:clear[0m option lets you replace the entire [table] with one that satisfies the [47mval[0m and key guards (if any); see [table]. We have relaxed the translation rules for [47m:measure[0m [hints] to [47m[defun][0m, so that the same rules apply to these terms that apply to terms in [47m[defthm][0m [events]. In particular, in [47m:measure[0m [hints] [47m[mv][0m is treated just like [47m[list][0m, and [47m[state][0m receives no special handling. The [loop-stopper] test has been relaxed. The old test required that every new argument be strictly less than the corresponding old argument in a certain [term-order]. The new test uses a lexicographic order on term lists instead. For example, consider the following rewrite rule. (equal (variable-update var1 val1 (variable-update var2 val2 vs)) (variable-update var2 val2 (variable-update var1 val1 vs))) This rule is permutative. Now imagine that we want to apply this rule to the term (variable-update u y (variable-update u x vs)). Since the actual corresponding to both [47mvar1[0m and [47mvar2[0m is [47mu[0m, which is not strictly less than itself in the [term-order], this rule would fail to be applied in this situation when using the old test. However, since the pair [47m(u x)[0m is lexicographically less than the pair [47m(u y)[0m with respect to our [term-order], the rule is in fact applied using our new test. Messages about [events] now contain a space after certain left parentheses, in order to assist emacs users. For example, the event (defthm abc (equal (+ (len x) 0) (len x))) leads to a [summary] containing the line Form: ( DEFTHM ABC ...) and hence, if you search backwards for ``[47m(defthm abc[0m'', you won't stop at this message. More tautology checking is done during a proof; in fact, no goal printed to the screen, except for the results of applying [47m:use[0m and [47m:by[0m [hints] or the top-level goals from an induction proof, are known to Acl2 to be tautologies. The [47m[ld-query-control-alist][0m may now be used to suppress printing of queries; see [ld-query-control-alist]. Warning messages are printed with short summary strings, for example the string ``[47mUse[0m'' in the following message. ACL2 Warning [Use] in ( THM ...): It is unusual to :USE the formula of an enabled :REWRITE or :DEFINITION rule, so you may want to consider disabling (:REWRITE FOO) in the hint provided for Goal. See :DOC using- enabled-rules. At the end of the event, just before the time is printed, all such summary strings are printed out. The keyword command [47m:u[0m has been introduced as an abbreviation for [47m:[0m[47m[ubt][0m [47m:[0m[47m[max][0m. Printing of query messages is suppressed by [47m:u[0m. The keyword [47m:cheat[0m is no longer supported by any event form. Some irrelevant formals are detected; see [irrelevant-formals]. A bug in the application of metafunctions was fixed: now if the output of a metafunction is equal to its input, the application of the metafunction is deemed unsuccessful and the next metafunction is tried. An example has been added to the documentation for [equivalence] to suggest how to make use of [equivalence] relations in rewriting. The following Common Lisp functions have been added to Acl2: [47m[alpha-char-p][0m, [47m[upper-case-p][0m, [47m[lower-case-p][0m, [47m[char-upcase][0m, [47m[char-downcase][0m, [47m[string-downcase][0m, [47m[string-upcase][0m, and [47mdigit-charp-p[0m. A documentation section called [47m[proof-builder][0m has been added for the interactive facility, whose documentation has been slightly improved. See in particular the documentation for [proof-builder], [47m[verify][0m, and [macro-command]. A number of [events] that had been inadvertently disallowed in [books] are now permitted in [books]. These are: [47m[defcong][0m, [47mdefcor[0m, [47m[defequiv][0m, [47m[defrefinement][0m, [47m[defstub][0m, and [47m[verify-termination][0m.") (note-1-5 (release-notes) "Acl2 Version 1.5 Notes Acl2 now allows ``complex rationals,'' which are complex numbers whose real parts are rationals and whose imaginary parts are non-zero rationals. See [complex]. A new way of handling [47m[force][0md hypotheses has been implemented. Rather than cause a case split at the time the [47m[force][0m occurs, we complete the main proof and then embark on one or more ``forcing rounds'' in which we try to prove the [force]d hypotheses. See [forcing-round]. To allow us to compare the new handling of [47m[force][0m with the old, Version 1.5 implements both and uses a flag in [47m[state][0m to determine which method should be used. Do [47m(assign old-style-forcing t)[0m if you want [47m[force][0m to be handled as it was in Version 1.4. However, we expect to eliminate the old-style forcing eventually because we think the new style is more effective. To see the difference between the two approaches to forcing, try proving the associativity of [append] under both settings of [47mold-style-forcing[0m. To get the new behavior invoke: (thm (implies (and (true-listp a) (true-listp b)) (equal (append (append a b) c) (append a (append b c))))) Then [47m(assign old-style-forcing t)[0m and invoke the [47mthm[0m [command] above again. A new [47m:cases[0m [hints] allows proof by cases. See [hints]. [47m[Include-book][0m and [47m[encapsulate][0m now restore the [47m[ACL2-defaults-table][0m when they complete. See [include-book] and see [encapsulate]. The [guard]s on many Acl2 primitives defined in [47maxioms.lisp[0m have been weakened to permit them to be used in accordance with lisp custom and tradition. It is possible to attach heuristic filters to [47m:[0m[47m[rewrite][0m rules to limit their applicability. See [syntaxp]. A tutorial has been added (but as of Version_3.6.1 it has become obsolete). [Events] now print the Summary paragraph listing [rune]s used, time, etc., whether they succeed or fail. The format of the ``[failure] banner'' has been changed but still has multiple asterisks in it. [47mThm[0m also prints a Summary, whether it succeeds or fails; but [47mthm[0m is not an event. A new event form [47m[skip-proofs][0m has been added; see [skip-proofs]. A user-specific customization facility has been added in the form of a book that is automatically included, if it exists on the current directory. See [ACL2-customization]. A facility for conditional metalemmas has been implemented; see [meta]. The acceptable values for [47m[ld-skip-proofsp][0m have changed. In the old version (Version 1.4), a value of [47mt[0m meant that proofs and [47m[local][0m [events] are to be skipped. In Version 1.5, a value of [47mt[0m means proofs (but not [47m[local][0m [events]) are to be skipped. A value of [47m'[0m[47m[include-book][0m means proofs and [47m[local][0m [events] are to be skipped. There are two other, more obscure, acceptable values. See [ld-skip-proofsp]. In order to turn off the forcing of assumptions, one should now [disable] the [47m:[0m[47m[executable-counterpart][0m of [47m[force][0m (rather than the [47m:[0m[47m[definition][0m of [47m[force][0m, as in the previous release); see [force]. The macros [47m[enable-forcing][0m and [47m[disable-forcing][0m make it convenient to [enable] or [disable] forcing. See [enable-forcing] and see [disable-forcing]. The new commands [47m:[0m[47m[pr][0m and [47m:[0m[47m[pr!][0m print the rules created by an event or command. See [pr] and see [pr!]. The new [history] [command]s [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m will replace a compound [command] such as an [47m[encapsulate][0m or [47m[include-book][0m by the sequence of [events] in it. That is, they ``[puff] up'' or ``lift'' the subevents of a [command] to the [command] level, eliminating the formerly superior [command] and lengthening the [history]. This is useful if you want to ``partially undo'' an [47m[encapsulate][0m or book or other compound [command] so you can experiment. See [puff] and see [puff*]. Theory expressions now are allowed to use the free variable [47m[world][0m and prohibited from using the free variable [47m[state][0m. See [theories], although it is essentially the same as before except it mentions [47m[world][0m instead of [47m[state][0m. See [world] for a discussion of the Acl2 logical [world]. Allowing [47m[in-theory][0m [events] to be state-sensitive violated an important invariant about how [books] behaved. [47m[Table][0m keys and values now are allowed to use the free variable [47m[world][0m and prohibited from using the free variable [47m[state][0m. See the note above about theory expressions for some explanation. The macro for minus, [47m[-][0m, used to expand [47m(- x 3)[0m to [47m(+ x -3)[0m and now expands it to [47m(+ -3 x)[0m instead. The old macro, if used in the left-hand sides of rewrite rules, produced inapplicable rules because the constant occurs in the second argument of the [47m[+][0m, but potential target terms generally had the constant in the first argument position because of the effect of [47mcommutativity-of-+[0m. A new class of rule, [47m:linear-alias[0m rules, allows one to implement the Nqthm package and similar hacks in which a [disable]d function is to be known equivalent to an arithmetic function. A new class of rule, [47m:built-in-clause[0m rules, allows one to extend the set of clauses proved silently by [47m[defun][0m during measure and [guard] processing. See [built-in-clause]. The new command [47m[pcb!][0m is like [47m[pcb][0m but sketches the [command] and then prints its subsidiary [events] in full. See [pcb!]. [47m:[0m[47m[Rewrite][0m class rules may now specify the [47m:[0m[47m[loop-stopper][0m field. See [rule-classes] and see [loop-stopper]. The rules for how [loop-stopper]s control permutative rewrite rules have been changed. One effect of this change is that now when the built-in commutativity rules for [47m[+][0m are used, the terms [47ma[0m and [47m(- a)[0m are permuted into adjacency. For example, [47m(+ a b (- a))[0m is now normalized by the commutativity rules to [47m(+ a (- a) b)[0m; in Version 1.4, [47mb[0m was considered syntactically smaller than [47m(- a)[0m and so [47m(+ a b (- a))[0m is considered to be in normal form. Now it is possible to arrange for unary functions be be considered ``invisible'' when they are used in certain contexts. By default, [47m[unary--][0m is considered invisible when its application appears in the argument list of [47m[binary-+][0m. See [loop-stopper] and see :DOC set-invisible-fns-table. Extensive documentation has been provided on the topic of Acl2's ``term ordering.'' See [term-order]. Calls of [47m[ld][0m now default [47m[ld-error-action][0m to [47m:return[0m rather than to the current setting. The [command] descriptor [47m:x[0m has been introduced and is synonymous with [47m:[0m[47m[max][0m, the most recently executed [command]. [History] [command]s such as [47m:[0m[47m[pbt][0m print a [47m:x[0m beside the most recent [command], simply to indicate that it [31;1mis[0m the most recent one. The [command] descriptor [47m:x-23[0m is synonymous with [47m(:x -23)[0m. More generally, every symbol in the keyword package whose first character is [47m#\x[0m and whose remaining [characters] parse as a negative integer is appropriately understood. This allows [47m:[0m[47m[pbt][0m [47m:x-10[0m where [47m:[0m[47m[pbt][0m [47m(:max -10)[0m or [47m:[0m[47m[pbt][0m [47m(:here -10)[0m were previously used. The old forms are still legal. The order of the arguments to [47m[defcong][0m has been changed. The simplifier now reports the use of unspecified built-in type information about the primitives with the phrase ``primitive type reasoning.'' This phrase may sometimes occur in situations where ``propositional calculus'' was formerly credited with the proof. The function [47m[pairlis][0m has been replaced in the code by a new function [47m[pairlis$][0m, because Common Lisp does not adequately specify its [47m[pairlis][0m function. Some new Common Lisp functions have been added, including [47m[logtest][0m, [47m[logcount][0m, [47m[integer-length][0m, [47m[make-list][0m, [47m[remove-duplicates][0m, [47m[string][0m, and [47m[concatenate][0m. The source file [47m/slocal/src/acl2/axioms.lisp[0m is the ultimate reference regarding Common Lisp functions in Acl2. The functions [47m[defuns][0m and [47m[theory-invariant][0m have been documented. See [defuns] and see [theory-invariant]. A few symbols have been added to the list [47m*acl2-exports*[0m. A new key has been implemented for the [47m[ACL2-defaults-table][0m, [47m:irrelevant-formals-ok[0m. See [set-irrelevant-formals-ok]. The connected book directory, [47m[cbd][0m, must be nonempty and begin and end with a slash. It is set (and displayed) automatically upon your first entry to [47m[lp][0m. You may change the setting with [47m[set-cbd][0m. See [cbd]. [47m:[0m[47m[oops][0m will undo the last [47m:[0m[47m[ubt][0m. See [oops]. Documentation has been written about the ordinals. See :DOC [47me0-ordinalp[0m and see :DOC [47me0-ord-<[0m. [Note added later: Starting with Version_2.8, instead see [o-p] and see [o<]. The color [events] --- (red), (pink), (blue), and (gold) --- may no longer be enclosed inside calls of [47m[local][0m, for soundness reasons. In fact, neither may any event that sets the [47m[ACL2-defaults-table][0m. See [embedded-event-form]. See [ld-keyword-aliases] for an example of how to change the exit keyword from [47m:[0m[47m[q][0m to something else. The attempt to install a [monitor] on [47m:[0m[47m[rewrite][0m rules stored as simple abbreviations now causes an error because the application of abbreviations is not tracked. A new message is sometimes printed by the theorem prover, indicating that a given simplification is ``specious'' because the subgoals it produces include the input goal. In Version 1.4 this was detected but not reported, causing behavior some users found bizarre. See [specious-simplification]. [47m:[0m[47m[Definition][0m rules are no longer always required to specify the [47m:clique[0m and [47m:controller-alist[0m fields; those fields can be defaulted to system-determined values in many common instances. See [definition]. A warning is printed if a macro form with keyword arguments is given duplicate keyword values. Execute [47m(thm t :doc nil :doc "ignored")[0m and read the warning printed. A new restriction has been placed on [47m[encapsulate][0m. Non-[47m[local][0m recursive definitions inside the [47m[encapsulate][0m may not use, in their tests and recursive calls, the constrained functions introduced by the [47m[encapsulate][0m. See [subversive-recursions]. (Note added in Version 2.3: Subversive recursions were first recognized by us here in Version 1.5, but our code for recognizing them was faulty and the bug was not fixed until Version 2.3.) The [events] [47m[defequiv][0m, [47m[defcong][0m, [47m[defrefinement][0m, and [47m[defevaluator][0m have been reimplemented so that they are just macros that expand into appropriate [47m[defthm][0m or [47m[encapsulate][0m [events]; they are no longer primitive [events]. See the [documentation] of each affected event. The [47mdefcor[0m event, which was a shorthand for a [47m[defthm][0m that established a [corollary] of a named, previously proved event, has been eliminated because its implementation relied on a technique we have decided to ban from our code. If you want the effect of a [47mdefcor[0m in Version 1.5 you must submit the corresponding [47m[defthm][0m with a [47m:by[0m hint naming the previously proved event. Error reporting has been improved for inappropriate [47m[in-theory][0m [hints] and [events], and for syntax errors in rule classes, and for non-existent filename arguments to [47m[ld][0m. Technical Note: We now maintain the Third Invariant on [47mtype-alists[0m, as described in the Essay on the Invariants on Type-alists, and Canonicality. This change will affect some proofs, for example, by causing a to rewrite more quickly to [47mc[0m when [47m(equiv a b)[0m and [47m(equiv b c)[0m are both known and [47mc[0m is the canonical representative of the three.") (note-1-6 (release-notes) "Acl2 Version 1.6 Notes A new key has been implemented for the [47m[ACL2-defaults-table][0m, [47m:ignore-ok[0m. See [set-ignore-ok]. It is now legal to have color [events], such as [47m(red)[0m, in the [portcullis] of a book. More generally, it is legal to set the [47m[ACL2-defaults-table][0m in the [portcullis] of a book. For example, if you execute [47m:red[0m and then certify a book, the event [47m(red)[0m will show up in the [portcullis] of that book, and hence the definitions in that book will all be red (except when overridden by appropriate declarations or [events]). When that book is included, then as always, its [portcullis] must first be ``raised,'' and that will cause the default color to become red before the [events] in the book are executed. As always, the value of [47m[ACL2-defaults-table][0m immediately after execution of an [47m[include-book][0m, [47m[certify-book][0m, or [47m[encapsulate][0m form will be the same as it was immediately before execution (and hence, so will the default color). See [portcullis] and, for more about books, see [books]. A theory [47m[ground-zero][0m has been defined to contain exactly those rules that are [enable]d when Acl2 starts up. See [ground-zero]. The function [47m[nth][0m is now [enable]d, correcting an oversight from Version 1.5. Customization files no longer need to meet the syntactic restrictions put on [books]; rather, they can contain arbitrary Acl2 forms. See [ACL2-customization]. Structured directory names and structured file names are supported; see especially the documentation for [pathname], [book-name], and [47m[cbd][0m. Acl2 now works with some Common Lisp implementations other than akcl, including Lucid, Allegro, and MCL. A facility has been added for displaying proof trees, especially using emacs; see [proof-tree]. There is a considerable amount of new [documentation], in particular for the printing functions [47m[fmt][0m, [47m[fmt1][0m, and [47m[fms][0m, and for the notion of Acl2 term (see [term]). It is possible to introduce new well-founded relations, to specify which relation should be used by [47m[defun][0m, and to set a default relation. See [well-founded-relation-rule]. It is possible to make functions suggest new inductions. See [induction]. It is possible to change how Acl2 expresses [type-set] information; in particular, this affects what clauses are proved when [force]d assumptions are generated. See [type-set-inverter]. A new restriction has been added to [47m[defpkg][0m, having to do with undoing. If you undo a [47m[defpkg][0m and define the same package name again, the imports list must be identical to the previous imports or else an explanatory error will occur. See [package-reincarnation-import-restrictions]. [47m[Theory-invariant][0m and [47m[set-irrelevant-formals-ok][0m are now embedded event forms. The command [47m:[0m[47m[good-bye][0m may now be used to quit entirely out of Lisp, thus losing your work forever. This command works in akcl but may not work in every Common Lisp. A theory [47m[ground-zero][0m has been added that contains exactly the [enable]d rules in the [startup] theory. See [ground-zero]. [47mDefine-pc-macro[0m and [47mdefine-pc-atomic-macro[0m now automatically define [47m:red[0m functions. (It used to be necessary, in general, to change color to [47m:red[0m before invoking these.) For a proof of the well-foundedness of [47me0-ord-<[0m on the [47me0-ordinalp[0ms, see [proof-of-well-foundedness]. [Note added later: Starting with Version_2.8, [47m[o<][0m and [47m[o-p][0m replace [47me0-ord-<[0m and [47me0-ordinalp[0m, respectively.] Free variables are now handled properly for hypotheses of [47m:[0m[47m[type-prescription][0m rules. When the system is loaded or saved, [47m[state][0m is now bound to [47m*the-live-state*[0m. [47m[Certify-book][0m has been modified so that when it compiles a file, it loads that object file. [47m[Defstub][0m has been modified so that it works when the color is hot ([47m:red[0m or [47m:pink[0m). Several basic, but not particularly commonly used, [events] have been added or changed. The obscure axiom [47msymbol-name-intern[0m has been modified. The definition of [47mfirstn[0m has been changed. [47m[Butlast][0m is now defined. The definition of [47m[integer-length][0m has been modified. The left-hand side of the rewrite rule [47mrational-implies2[0m has been changed from [47m(* (numerator x) (/ (denominator x)))[0m to [47m(* (/ (denominator x)) (numerator x))[0m, in order to respect the fact that [47m[unary-/][0m is invisible with respect to [47m[binary-*][0m. See [loop-stopper]. The `preprocess' process in the waterfall (see [hints] for a discussion of the [47m:do-not[0m hint) has been changed so that it works to avoid case-splitting. The `simplify' process refuses to force (see [force]) when there are [47m[if][0m terms, including [47m[and][0m and [47m[or][0m terms, in the goal being simplified. The function [47mapply[0m is no longer introduced automatically by translation of user input to internal form when functions are called on inappropriate explicit values, e.g., [47m(car 3)[0m. The choice of which variable to use as the measured variable in a recursive definition has been very slightly changed.") (note-1-7 (release-notes) "ACL2 Version 1.7 (released October 1994) Notes [47m[Include-book][0m now takes (optionally) an additional keyword argument, indicating whether a compiled file is to be loaded. The default behavior is unchanged, except that a warning is printed when a compiled file is not loaded. See [include-book]. A markup language for [documentation] strings has been implemented, and many of the source files have been marked up using this language (thanks largely to the efforts of Laura Lawless). See markup. Moreover, there are translators that we have used to provide versions of the ACL2 [documentation] in info (for use in emacs), html (for Mosaic), and tex (for hardcopy) formats. A new event [47mdefdoc[0m has been implemented. It is like [47m[deflabel][0m, but allows redefinition of [doc] strings and has other advantages. See [47mdefdoc[0m. We used to ignore corollaries when collecting up the axioms introduced about constrained functions. That bug has been fixed. We thank John Cowles for bringing this bug to our attention. The macro [47m[defstub][0m now allows a [47m:[0m[47m[doc][0m keyword argument, so that [documentation] may be attached to the name being introduced. A new command [47m[nqthm-to-ACL2][0m has been added to help Nqthm users to make the transition to ACL2. See [nqthm-to-ACL2], which also includes a complete listing of the relevant tables. Many function names, especially of the form ``foo[47m-lst[0m'', have been changed in order to support the following convention, for any ``foo'': [47m(foo-listp lst)[0m represents the notion [47m(for x in lst always foop x)[0m. A complete list of these changes may be found at the end of this note. All of them except [47msymbolp-listp[0m and [47mlist-of-symbolp-listp[0m have the string ``[47m-lst[0m'' in their names. Note also that [47mkeyword-listp[0m has been renamed [47m[keyword-value-listp][0m. Accumulated persistence has been implemented. It is not connected to [47m:[0m[47m[brr][0m or rule monitoring. See [accumulated-persistence]. [47m:Trigger-terms[0m has been added for [47m:[0m[47m[linear][0m rule classes, so you can hang a [linear] rule under any addend you want. See [linear], which has been improved and expanded. ACL2 now accepts [47m256[0m [characters] and includes the Common Lisp functions [47m[code-char][0m and [47m[char-code][0m. However, ACL2 controls the lisp reader so that [47m#\c[0m may only be used when [47mc[0m is a single standard character or one of [47mNewline[0m, [47mSpace[0m, [47mPage[0m, [47mRubout[0m, [47mTab[0m. If you want to enter other [characters] use [47m[code-char][0m, e.g., [47m(coerce (list (code-char 7) (code-char 240) #a) 'string)[0m. See [characters]. Note: our current handling of [characters] makes the set of theorems different under Macintosh Common Lisp (MCL) than under other Common Lisps. We hope to rectify this situation before the final release of ACL2. A new [table], [47m[macro-aliases-table][0m, has been implemented, that associates macro names with function names. So for example, since [47m[append][0m is associated with [47m[binary-append][0m, the form [47m(disable append)[0m it is interpreted as though it were [47m(disable binary-append)[0m. See [macro-aliases-table], see [add-macro-alias] and see [remove-macro-alias]. The implementation of conditional metalemmas has been modified so that the metafunction is applied before the hypothesis metafunction is applied. See [meta]. The Common Lisp functions [47m[acons][0m and [47m[endp][0m have been defined in the ACL2 logic. We have added the symbol [47m[declare][0m to the list [47m*acl2-exports*[0m, and hence to the package [47m"ACL2-USER"[0m. A new hint, [47m:restrict[0m, has been implemented. See [hints]. It used to be that if [47m:[0m[47m[ubt][0m were given a number that is greater than the largest current [command] number, it treated that number the same as [47m:[0m[47m[max][0m. Now, an error is caused. The [table] [47m:force-table[0m has been eliminated. A command [47m:[0m[47m[disabledp][0m (and macro [47m[disabledp][0m) has been added; see [disabledp]. [Compilation] via [47m:[0m[47m[set-compile-fns][0m is now suppressed during [47m[include-book][0m. In fact, whenever the [state] global variable [47m[ld-skip-proofsp][0m has value [47m'[0m[47m[include-book][0m. Here are some less important changes, additions, and so on. Unlike previous releases, we have not proved all the theorems in [47maxioms.lisp[0m; instead we have simply assumed them. We have deferred such proofs because we anticipate a fairly major change in Version 1.8 in how we deal with [guard]s. We used to (accidentally) prohibit the ``redefinition'' of a [table] as a function. That is no longer the case. The check for whether a [corollary] follows tautologically has been sped up, at the cost of making the check less ``smart'' in the following sense: no longer do we expand primitive functions such as [47m[implies][0m before checking this propositional implication. The [command] [47m[ubt!][0m has been modified so that it never causes or reports an error. See [ubt!]. ACL2 now works in Harlequin LispWorks. The user can now specify the [47m:trigger-terms[0m for [47m:[0m[47m[linear][0m rules. See [linear]. The name of the system is now ``ACL2''; no longer is it ``Acl2''. The raw lisp counterpart of [47m[theory-invariant][0m is now defined to be a no-op as is consistent with the idea that it is just a call of [47m[table][0m. A bug was fixed that caused [proof-builder] [instructions] to be executed when [47m[ld-skip-proofsp][0m was [47mt[0m. The function [47m[rassoc][0m has been added, along with a corresponding function used in its [guard], [47mr-eqlable-alistp[0m. The [47m[in-theory][0m event and hint now print a warning not only when certain ``primitive'' [47m:[0m[47m[definition][0m rules are [disable]d, but also when certain ``primitive'' [47m:[0m[47m[executable-counterpart][0m rules are [disable]d. The modified version of [47mtrace[0m provided by ACL2, for use in raw Lisp, has been modified so that the lisp special variable [47m*trace-alist*[0m is consulted. This alist associates, using [47m[eq][0m, values with their print representations. For example, initially [47m*trace-alist*[0m is a one-element list containing the pair [47m(cons state '|*the-live-state*|)[0m. The system now prints an observation when a form is skipped because the default color is [47m:red[0m or [47m:pink[0m. (Technically: [47mwhen-cool[0m has been modified.) Additional protection exists when you submit a form to raw Common Lisp that should only be submitted inside the ACL2 read-eval-print loop. Here is a complete list of the changes in function names described near the top of this note, roughly of the form foo-lst --> foo-listp meaning: the name ``[47mfoo-lst[0m'' has been changed to ``[47mfoo-listp[0m.'' symbolp-listp --> symbol-listp list-of-symbolp-listp --> symbol-list-listp {for consistency with change to symbol-listp} rational-lst --> rational-listp {which in fact was already defined as well} integer-lst --> integer-listp character-lst --> character-listp stringp-lst --> string-listp 32-bit-integer-lst --> 32-bit-integer-listp typed-io-lst --> typed-io-listp open-channel-lst --> open-channel-listp readable-files-lst --> readable-files-listp written-file-lst --> written-file-listp read-file-lst --> read-file-listp writeable-file-lst --> writable-file-listp {note change in spelling of ``writable''} writeable-file-lst1 --> writable-file-listp1 pseudo-termp-lst --> pseudo-term-listp hot-termp-lst --> hot-term-listp {by analogy with pseudo-term-listp} weak-termp-lst --> weak-term-listp weak-termp-lst-lst --> weak-termp-list-listp ts-builder-case-lstp -> ts-builder-case-listp quotep-lst --> quote-listp termp-lst --> term-listp instr-lst --> instr-listp spliced-instr-lst --> spliced-instr-listp rewrite-fncallp-lst --> rewrite-fncallp-listp every-occurrence-equiv-hittablep1-lst --> every-occurrence-equiv-hittablep1-listp some-occurrence-equiv-hittablep1-lst --> some-occurrence-equiv-hittablep1-listp {by analogy with the preceding, even though it's a ``some'' instead of ``all'' predicate] almost-quotep1-lst --> almost-quotep1-listp ffnnames-subsetp-lst --> ffnnames-subsetp-listp boolean-lstp --> boolean-listp subst-expr1-lst-okp --> subst-expr1-ok-listp") (note-1-8 (release-notes) "ACL2 Version 1.8 (May, 1995) Notes See [note-1-8-update] for yet more recent changes. [Guard]s have been eliminated from the ACL2 logic. A summary is contained in this brief note. Also see [defun-mode] and see [set-guard-checking]. [Guard]s may be included in [defuns] as usual but are ignored from the perspective of admission to the logic: functions must terminate on all arguments. As in Nqthm, primitive functions, e.g., [47m[+][0m and [47m[car][0m, logically default unexpected arguments to convenient values. Thus, [47m(+ 'abc 3)[0m is [47m3[0m and [47m(car 'abc)[0m is [47mnil[0m. See [programming], and see the [documentation] for the individual primitive functions. In contrast to earlier versions of ACL2, Version 1.8 logical functions are executed at Nqthm speeds even when [guard]s have not been verified. In versions before 1.8, such functions were interpreted by ACL2. Colors have been eliminated. Two ``[defun-mode]s'' are supported, [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m. Roughly speaking, [47m:[0m[47m[program][0m does what [47m:red[0m used to do, namely, allow you to prototype functions for execution without any proof burdens. [47m:[0m[47m[Logic][0m mode does what [47m:blue[0m used to do, namely, allow you to add a new definitional axiom to the logic. A global [default-defun-mode] is comparable to the old default color. The system comes up in [47m:[0m[47m[logic][0m mode. To change the global [defun-mode], type [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m at the top-level. To specify the [defun-mode] of a [47m[defun][0m locally use [47m(declare (xargs :mode mode))[0m. The [prompt] has changed. The initial [prompt], indicating [47m:[0m[47m[logic][0m mode, is ACL2 !> If you change to [47m:[0m[47m[program][0m mode the [prompt] becomes ACL2 p!> [Guard]s can be seen as having either of two roles: (a) they are a specification device allowing you to characterize the kinds of inputs a function ``should'' have, or (b) they are an efficiency device allowing logically defined functions to be executed directly in Common Lisp. If a [guard] is specified, as with [47m[xargs][0m [47m:[0m[47m[guard][0m, then it is ``verified'' at defun-time (unless you also specify [47m[xargs][0m [47m:verify-guards nil[0m). [Guard] verification means what it always has: the input [guard] is shown to imply the [guard]s on all subroutines in the body. If the [guard]s of a function are verified, then a call of the function on inputs satisfying the [guard] can be computed directly by Common Lisp. Thus, verifying the [guard]s on your functions will allow them to execute more efficiently. But it does not affect their logical behavior and since you will automatically get Nqthm speeds on unverified logical definitions, most users will probably use [guard]s either as a specification device or only use them when execution efficiency is extremely important. Given the presence of [guard]s in the system, two issues are unavoidable. Are [guard]s verified as part of the [47m[defun][0m process? And are [guard]s checked when terms are evaluated? We answer both of those questions below. Roughly speaking, in its initial [state] the system will try to verify the [guard]s of a [47m[defun][0m if a [47m:[0m[47m[guard][0m is supplied in the [47m[xargs][0m and will not try otherwise. However, [guard] verification in [47m[defun][0m can be inhibited ``locally'' by supplying the [47m[xargs][0m [47m:[0m[47m[verify-guards][0m [47mnil[0m. ``Global'' inhibition can be obtained via the [47m:[0m[47m[set-verify-guards-eagerness][0m. If you do not use the [47m:[0m[47m[guard][0m [47m[xargs][0m, you will not need to think about [guard] verification. We now turn to the evaluation of expressions. Even if your functions contain no [guard]s, the primitive functions do and hence you have the choice: when you submit an expression for evaluation do you mean for [guard]s to be checked at runtime or not? Put another way, do you mean for the expression to be evaluated in Common Lisp (if possible) or in the logic? Note: If Common Lisp delivers an answer, it will be the same as in the logic, but it might be erroneous to execute the form in Common Lisp. For example, should [47m(car 'abc)[0m cause a [guard] violation error or return [47mnil[0m? The top-level ACL2 loop has a variable which controls which sense of execution is provided. To turn ``[guard] checking on,'' by which we mean that [guard]s are checked at runtime, execute the top-level form [47m:set-guard-checking t[0m. To turn it off, do [47m:set-guard-checking nil[0m. The status of this variable is reflected in the [prompt]. ACL2 !> means [guard] checking is on and ACL2 > means [guard] checking is off. The exclamation mark can be thought of as ``barring'' certain computations. The absence of the mark suggests the absence of error messages or unbarred access to the logical axioms. Thus, for example ACL2 !>(car 'abc) will signal an error, while ACL2 >(car 'abc) will return [47mnil[0m. Note that whether or not [guard]s are checked at runtime is independent of whether you are operating in [47m:[0m[47m[program][0m mode or [47m:[0m[47m[logic][0m mode and whether theorems are being proved or not. (Although it must be added that functions defined in [47m:[0m[47m[program][0m mode cannot help but check their [guard]s because no logical definition exists.) Version 1.8 permits the verification of the [guard]s of theorems, thus insuring that all instances of the theorem will evaluate without error in Common Lisp. To verify the [guard]s of a theorem named [47mname[0m execute the event (verify-guards name). If a theorem's [guard]s have been verified, the theorem is guaranteed to evaluate without error to non-[47mnil[0m in Common Lisp (provided resource errors do not arise). Caveat about [47m[verify-guards][0m: [47m[implies][0m is a function symbol, so in the term [47m(implies p q)[0m, [47mp[0m cannot be assumed true when [47mq[0m is evaluated; they are both evaluated ``outside.'' Hence, you cannot generally verify the [guard]s on a theorem if [47m[implies][0m is used to state the hypotheses. Use [47m[if][0m instead. In a future version of ACL2, [47m[implies][0m will likely be a macro. See sum-list-example.lisp for a nice example of the use of Version 1.8. This is roughly the same as the documentation for [guard-example]. We have removed the capability to do ``old-style-forcing'' as existed before Version 1.5. See [note-1-5]. NOTE: Some low level details have, of course, changed. One such change is that there are no longer two distinct type prescriptions stored when a function is admitted with its [guard]s verified. So for example, the type prescription [rune] for [47m[binary-append][0m is now (:type-prescription binary-append) while in Versions 1.7 and earlier, there were two such [rune]s: (:type-prescription binary-append . 1) (:type-prescription binary-append . 2) Nqthm-style forcing on [linear] arithmetic assumptions is no longer executed when forcing is [disable]d. Functional instantiation now benefits from a trick also used in Nqthm: once a [constraint] generated by a [47m:functional-instance[0m lemma instance (see [lemma-instance]) has been proved on behalf of a successful event, it will not have to be re-proved on behalf of a later event. [47m[1+][0m and [47m[1-][0m are now macros in the logic, not functions. Hence, for example, it is ``safe'' to use them on left-hand sides of rewrite rules, without invoking the common warning about the presence of nonrecursive function symbols. A new [documentation] section [file-reading-example] illustrates how to process forms in a file. A new [proof-builder] command [47mforwardchain[0m has been added; see [ACL2-pc::forwardchain]. It is now possible to use quantifiers. See [defun-sk] and see [defchoose]. There is a new event [47m[set-inhibit-warnings][0m, which allows the user to turn off warnings of various types. see [set-inhibit-warnings]. An unsoundness relating [47m[encapsulate][0m and [47m:functional-instance[0m [hints] has been remedied, with a few small effects visible at the user level. The main observable effect is that [47m[defaxiom][0m and non-local [47m[include-book][0m [events] are no longer allowed in the scope of any [47m[encapsulate][0m event that has a non-empty [signature]. When [47m[certify-book][0m is called, we now require that the default [defun-mode] (see [default-defun-mode]) be [47m:[0m[47m[logic][0m. On a related note, the default [defun-mode] is irrelevant to [47m[include-book][0m; the mode is always set to [47m:[0m[47m[logic][0m initially, though it may be changed within the book and reverts to its original value at the conclusion of the [47m[include-book][0m. A bug in [47m[include-book][0m prevented it from acting this way even though the [documentation] said otherwise. The [documentation] has been substantially improved. A new section ``Programming'' contains [documentation] of many useful functions provided by ACL2; see [programming]. Also, the [documentation] has been ``marked up'' extensively. Thus in particular, users of Mosaic will find many links in the [documentation]. The symbols [47m[force][0m, [47m[mv-nth][0m, and [47macl2-count[0m have been added to the list [47m*acl2-exports*[0m. We now permit most names from the main Lisp package to be used as names, except for names that define functions, macros, or constants. See [name]. We have changed the list of imports from the Common Lisp package to ACL2, i.e., the list [47m*common-lisp-symbols-from-main-lisp-package*[0m, to be exactly those external symbols of the Common Lisp package as specified by the draft Common Lisp standard. In order to accommodate this change, we have renamed some ACL2 functions as shown below, but these and other ramifications of this change should be transparent to most ACL2 users. warning --> warning$ print-object --> print-object$ Proof trees are no longer enabled by default. To start them up, [47m:[0m[47m[start-proof-tree][0m. We have added the capability of building smaller images. The easiest way to do this on a Unix (trademark of AT&T) system is: [47mmake small[0m. Here we will put some less important changes, additions, and so on. We have added definitions for the Common Lisp function [47m[position][0m (for the test [47m[eql][0m), as well as corresponding versions [47m[position-equal][0m and [47m[position-eq][0m that use tests [47m[equal][0m and [47m[eq][0m, respectively. See [position], see [position-equal], and see [position-eq]. The [47m[defthm][0m event [47mrational-listp-implies-rationalp-car[0m no longer exists. We fixed a bug in the hint mechanism that applied [47m:by[0m, [47m:cases[0m, and [47m:use[0m [hints] to the first induction goal when the prover reverted to proving the original goal by induction. We fixed a bug in the handling of [47m(set-irrelevant-formals-ok :warn)[0m. In support of removing the old-style forcing capability, we deleted the initialization of [state] global [47mold-style-forcing[0m and deleted the definitions of [47mrecover-assumptions[0m, [47mrecover-assumptions-from-goal[0m, [47mremove-assumptions1[0m, [47mremove-assumptions[0m, and [47msplit-on-assumptions[0m, and we renamed [47msplit-on-assumptions1[0m to [47msplit-on-assumptions[0m. The special value [47m'none[0m in the [proof-builder] commands [47mclaim[0m and [47m[=][0m has been replaced by [47m:none[0m. A bug in the handling of [hints] by subgoals has been fixed. For example, formerly a [47m:do-not[0m hint could be ``erased'' by a [47m:use[0m hint on a subgoal. Thanks go to Art Flatau for noticing the bug. The functions [47mweak-termp[0m and [47mweak-term-listp[0m have been deleted, and their calls have been replaced by corresponding calls of [47m[pseudo-termp][0m and [47mpseudo-term-listp[0m. The notion of [47m[pseudo-termp][0m has been slightly strengthened by requiring that terms of the form [47m(quote ...)[0m have length 2. Performance has been improved in various ways. At the prover level, backchaining through the recognizer alist has been eliminated in order to significantly speed up ACL2's rewriter. Among the other prover changes (of which there are several, all technical): we no longer clausify the input term when a proof is interrupted in favor of inducting on the input term. At the [io] level, we have improved performance somewhat by suitable declarations and proclamations. These include technical modifications to the macros [47m[mv][0m and [47m[mv-let][0m, and introduction of a macro [47mthe-mv[0m analogous to the macro [47m[the][0m but for forms returning multiple values. The function [47mspaces[0m now takes an extra argument, the current column. A bug in the [proof-builder] [47mequiv[0m command was fixed. The function [47mintersectp[0m has been deleted, because it was essentially duplicated by the function [47m[intersectp-equal][0m. We now proclaim functions in AKCL and GCL before compiling [books]. This should result in somewhat increased speed. The function [47mrepeat[0m has been eliminated; use [47m[make-list][0m instead. The [proof-builder] command [47mexpand[0m has been fixed so that it eliminates [47m[let][0m (lambda) expressions when one would expect it to. A new primitive function, [47m[mv-nth][0m, has been introduced. [47m[Mv-nth][0m is equivalent to [47m[nth][0m and is used in place of [47m[nth][0m in the translation of [47m[mv-let][0m expressions. This allows the user to control the simplification of [47m[mv-let][0m expressions without affecting how [47m[nth][0m is treated. In that spirit, the rewriter has been modified so that certain [47m[mv-nth][0m expressions, namely those produced in the translation of [47m(mv-let (a b c)(mv x y z) p)[0m, are given special treatment. A minor bug in [47muntranslate[0m has been fixed, which for example will fix the printing of conjunctions. [47mTranslate[0m now takes a [47mlogicp[0m argument, which indicates whether it enforces the restriction that [47m:[0m[47m[program][0m mode functions do not occur in the result. The modified version of [47mtrace[0m provided by ACL2, for use in raw Lisp, has been modified so that the lisp special variable [47m*trace-alist*[0m has a slightly different functionality. This alist associates, using [47m[eq][0m, symbols with the print representations of their values. For example, initially [47m*trace-alist*[0m is a one-element list containing the pair [47m(cons 'state '|*the-live-state*|)[0m. Thus, one may cons the pair [47m(cons '*foo* "It's a FOO!")[0m on to [47m*trace-alist*[0m; then until [47m*foo*[0m is defined, this change will have no effect, but after for example (defconst *foo* 17) then [47mtrace[0m will print [47m17[0m as [47m"It's a FOO!"[0m. [47mTrace[0m also traces the corresponding logic function. [Proof-tree] display has been improved slightly in the case of successful proofs and certain event failures. The function [47mpositive-integer-log2[0m has been deleted. The macro [47m[skip-proofs][0m now prints a warning message when it is encountered in the context of an [47m[encapsulate][0m event or a book. See [skip-proofs]. Some functions related to [47mthe-fn[0m and [47mwormhole1[0m now have [defun-mode] [47m:[0m[47m[program][0m, but this change is almost certain to be inconsequential to all users.") (note-1-8-update (release-notes) "ACL2 Version 1.8 (Summer, 1995) Notes ACL2 can now use Ordered Binary Decision Diagram technology. See [bdd]. There is also a [proof-builder] [47mbdd[0m command. ACL2 is now more respectful of the intention of the function [47m[hide][0m. In particular, it is more careful not to dive inside any call of [47m[hide][0m during equality substitution and case splitting. The [47m[ld][0m special (see [ld]) [47m[ld-pre-eval-print][0m may now be used to turn off printing of input forms during processing of [47m[encapsulate][0m and [47m[certify-book][0m forms, by setting it to the value [47m:never[0m, i.e., [47m(set-ld-pre-eval-print :never state)[0m. See [ld-pre-eval-print]. The TUTORIAL documentation section (now obsolete) has, with much help from Bill Young, been substantially improved to a bona fide introduction. The term pretty-printer has been modified to introduce [47m(<= X Y)[0m as an abbreviation for [47m(not (< Y X))[0m. Forward chaining and linear arithmetic now both benefit from the evaluation of ground subterms. A new macro [47m[set-inhibit-output-lst][0m has been defined. This should be used when setting the [state] global [47minhibit-output-lst[0m; see [set-inhibit-output-lst] and see [proof-tree]. The test for redundancy in definitions includes the [guard] and type declarations. See [redundant-events]. See [generalized-booleans] for a discussion of a potential soundness problem for ACL2 related to the question: Which Common Lisp functions are known to return Boolean values? Here we will put some less important changes, additions, and so on. A bug has been fixed so that now, execution of [47m:comp t[0m (see [comp]) correctly handles non-standard characters. A bug in [47m[digit-char-p][0m has been fixed, so that the ``default'' is [47mnil[0m rather than [47m0[0m. [47m[True-listp][0m now tests the final [47m[cdr][0m against [47mnil[0m using [47m[eq][0m instead of [47m[equal][0m, for improved efficiency. The logical meaning is, however, unchanged. [47m[Put-assoc-equal][0m has been added to the logic (it used to have [47m:[0m[47m[defun-mode][0m [47m:[0m[47m[program][0m, and has been documented.") (note-1-9 (release-notes) "ACL2 Version 1.9 (Fall, 1996) Notes By default, when the system is started it is illegal to use the variable [47m[state][0m as a formal parameter of a function definition. The aim is to prevent novice users from stumbling into the Byzantine syntactic restrictions on that variable symbol. Use :set-state-ok t or, equivalently, (set-state-ok t) to switch back to the old default mode. See [set-state-ok] [47mSet-state-ok[0m is an event that affects the ACL2 defaults table (see [ACL2-defaults-table]). Recall that when books are included, the defaults table is restored to its pre-inclusion state. Thus, while a [47mset-state-ok[0m form will permit the book to define a [47mstate[0m-using function, it will not permit the user of the book to make such a definition. We recommend putting [47m(set-state-ok t)[0m in any book that defines a [47mstate[0m using function. Books certified under Version 1.8 must be recertified under Version 1.9. See :DOC version. The simplifier has been made to look out for built-in clauses, whereas in past versions such clauses were only noticed by the ``preprocessor'' at the top of the waterfall. THIS CHANGE MAY PREVENT OLD SCRIPTS FROM REPLAYING! The undesirable side-effect is caused by the fact that [47m:HINTS[0m require you to refer to clauses by their exact name (see [goal-spec]) and because the new simplifier proves more clauses than before, the goals produced have different names. Thus, if a script uses [47m:HINTS[0m that refer to clauses other than "Goal", e.g., "Subgoal 1.3" then the hint may be applied to a different subgoal than originally intended. The use of built-in-clauses has been made more efficient. If a set of clauses arise often in a piece of work, it might be advantageous to build them in even if that results in a large set (hundreds?) of built-in clauses. See [built-in-clause] Wormholes can now be used in :logic mode functions. See [wormhole] It is now possible to provide ``computed hints.'' For example, have you ever wished to say ``in all goals with a name like this, :use that'' or ``if this term is in the subgoal, then :use that''? Well, see [computed-hints] and the extraordinarily long example in see [using-computed-hints]. [47mHide[0m terms may be rewritten with :rewrite rules about [47mhide[0m. See [hide], where we also now explain why [47mhide[0m terms are sometimes introduced into your proof attempts. A bug that sometimes caused the ``non-lazy IF'' hard error message was fixed. A bug that sometimes caused a hard error in forward chaining was fixed. A bug in print-rules (:pr) was fixed. We report the use of :executable-counterparts in the evaluation of SYNTAXP forms. Some documentation errors were fixed. A bug in parent-tree tracking in add-literal-and-pt was fixed. A bug in ok$, go$ and eval$ was fixed. Clausify now optimizes (mv-nth 'k (list x0 ... xk ... xn)) to xk.") (note-2-0 (release-notes) "ACL2 Version 2.0 (July, 1997) Notes This is the first version of ACL2 released under the copyright of the University of Texas (UT). Future releases of ACL2 will be made from UT rather than Computational Logic, Inc. (CLI). Version 2.0 is just Version 1.9 as released by CLI, with a few bugs fixed. A bug causing an infinite loop was fixed in functional instantiation. The bug manifested itself when two conditions occurred simultaneously: First, the functional substitution replaces a function symbol, e.g., [47mFOO[0m, with a [47mLAMBDA[0m expression containing a free variable (a variable not among in the [47mLAMBDA[0m formals). And, second, in one of the constraints being instantiated there is a call of the function symbol [47mFOO[0m within the scope of another [47mLAMBDA[0m expression. Unless you used such a functional substitution, this bug fix will not affect you. Less important notes: The implementation of [47mPRINC$[0m was changed so that it was no longer sensitive to the external setting of [47m*print-base*[0m and other Common Lisp special variables. Typographical errors were fixed in the documentation.") (note-2-1 (release-notes) "ACL2 Version 2.1 (December, 1997) Notes The identity function [47m[case-split][0m has been added. It is similar to [47m[force][0m but causes an immediate split of the top-level goal on whether the indicated hypothesis is true. Less important notes: Minor bugs in the documentation were fixed.") (note-2-2 (release-notes) "ACL2 Version 2.2 (August, 1998) Notes Important changes: A bug was fixed in the compile command, [47m:comp[0m. The compiled code produced by [47m:comp[0m in previous versions could be wildly incorrect because of a confusion between the printer and the reader regarding what was the current Lisp [47m*package*[0m. This bug could manifest itself only if you used the [47m:comp[0m command to compile previously uncompiled functions while the current package was different from [47m"ACL2"[0m. What happened in that situation depended upon what symbols were imported into your current package. The most likely behavior is that the compiler would break or complain or the resulting compiled code would call functions that did not exist. There have been no other important changes to the code. However, this release contains some useful new books, notably those on the [47mbooks[0m subdirectories [47mcli-misc[0m and [47mihs[0m. Both have [47mREADME[0m files. The [47mihs[0m books provide support for integer hardware specifications. These books were crucial to Bishop Brock's successful modeling of the Motorola CAP. We thank Bishop for producing them and we thank all those who worked so hard to get these books released. We highly recommend the [47mihs[0m books to those modeling ALUs and other arithmetic components of microprocessors or programming languages. In previous versions of ACL2, the arithmetic books, found on [47mbooks/arithmetic/[0m, included the addition of several unproved axioms stating properties of the rationals that we believed could be derived from our ``official'' axioms but which we had not mechanically proved. The axioms were found in the book [47mrationals-with-axioms.lisp[0m, which was then used in the uppermost arithmetic books [47mtop.lisp[0m and [47mtop-with-meta.lisp[0m. John Cowles has now provided us with ACL2 proofs of those ``axioms'' and so in this release you will find both [47mrationals-with-axioms.lisp[0m and [47mrationals-with-axioms-proved.lisp[0m. The former is provided for compatibility's sake. The latter is identical but contains [47mdefthm[0ms where the former contains [47mdefaxiom[0ms. The top-most books have been rebuilt using ``[47m-axioms-proved[0m'' book. Thanks John. Less important notes: Bishop Brock found a bug in [47mtranslated-acl2-unwind-protectp4[0m. Jun Sawada reported a bug in linear arithmetic that caused us not to prove certain trivial theorems concluding with [47m(not (equal i j))[0m. We have fixed both. We now prohibit definitions that call certain event commands such as [47mDEFTHM[0m and [47mTABLE[0m because our Common Lisp implementations of them differ from their ACL2 meanings (so that compiled books can be loaded correctly and efficiently). Minor bugs in the documentation were fixed.") (note-2-3 (release-notes) "ACL2 Version 2.3 (October, 1998) Notes Important changes: Versions of ACL2 preceding this one contain a subtle soundness bug! We found a flaw in our detection of [subversive-recursions]. The bug allowed some subversive recursions to slip through undetected. We believe it would have been difficult to have exploited this flaw inadvertently. In particular, the following five conditions are necessary. (1) Introduce a constrained function, say [47mf[0m, via an [47mencapsulate[0m. (2) In the same encapsulation, define a clique of mutually recursive functions. This clique must be non-[47mlocal[0m and in [47m:logic[0m mode. (3) In that mutually recursive clique, use the constrained function [47mf[0m (perhaps indirectly) so that the termination argument for the clique depends on properties of the [3mwitness[0m for [47mf[0m. Thus, [47mf[0m or some other function dependent upon [47mf[0m, must be used in an argument in a recursive call or in a term governing a recursive call. Furthermore, the use of [47mf[0m must be such that the termination proof cannot be done without exploiting properties of the witness for [47mf[0m. Other uses of the constrained functions in the clique are ok. (4) Fail to include the exploited properties of [47mf[0m among the constraints of the encapsulation. (5) Later, outside the encapsulation, explicitly use a functional instantiation in which [47mf[0m is replaced by a function not enjoying the crucial properties. See [subversive-recursions] for details. Less important notes: We have begun to write some introductory tutorial material for those who wish to learn to program in ACL2. Most of this material is HTML-based. See the Hyper-Card on the ACL2 home page. The documentation of [47m[verify-guards][0m was improved to explain why one might wish to verify the ``guards'' of a [47mdefthm[0m event. The missing documentation was noticed by John Cowles. A bug was fixed in cross fertilization. The bug caused the system to report that it had substituted one term for another when in fact no substitution occurred. The bug was noticed by Bill McCune.") (note-2-4 (release-notes) "ACL2 Version 2.4 (August, 1999) Notes Important changes: We corrected a soundness bug in Version 2.3 related to the handling of [47m[immediate-force-modep][0m. The bad behavior was noticed by Robert Krug. Thanks! We corrected a bug that permitted [47m[verify-guards][0m to accept a function even though a subfunction had not yet had its guards verified. Thanks to John Cowles for noticing this. User defined single-threaded objects are now supported. See [stobj]. Less important notes: We corrected a bug that prevented the intended expansion of some recursive function calls. We changed the handling of the primitive function [47m[illegal][0m, which is logically defined to be [47mnil[0m but which is programmed to signal an error, so that when it is evaluated as part of a proof, it does not signal an error. The old handling of the function prevented some guard proofs involving [47m[the][0m or [47m[let][0ms with internal declarations. We corrected a bug that permitted some [47mLOCAL[0m [47mDEFAXIOM[0m events to slip into certified books. We corrected a bug that prevented the correct undoing of certain [47mDEFPKG[0m forms. Changes were made to support CMU Lisp. Pete Manolios helped with these changes. Changes were made to make the make files more compatible with Allegro Common Lisp. Jun Sawada, who has been a great help with keeping ACL2 up and running at UT on various platforms, was especially helpful. Thanks Jun.") (note-2-5 (release-notes) "ACL2 Version 2.5 (June, 2000) Notes Important Changes: Concurrent with the release of ACL2 Version 2.5 is the publication of two books about ACL2. See the ``Books and Papers about ACL2 and Its Applications'' on the ACL2 Home Page. The [47mbooks[0m subdirectory now contains many new certifiable books, including solutions to the exercises in the two published books and full scripts for the case studies. See [47mbooks/README.html[0m. Improved Unix [47mMakefile[0m support for book certification has also been written. See [47mbooks/README.html[0m. The list of symbols in [47m*acl2-exports*[0m has been considerably expanded. If you have packages built by importing [47m*acl2-exports*[0m you might want to look carefully at the new value of that constant. The new value includes all [47m:logic[0m mode functions as of Version 2.5, as well as all documented macros and all built-in theorem names. [47m[Include-book][0m and [47m[certify-book][0m were modified to have some additional keyword arguments. It is possible to certify a book containing [47m[defaxiom][0m and/or [47m[skip-proofs][0m events and get warning messages or errors signaled, according to the settings of these new flags. In addition, it is possible to specify in [47minclude-book[0m whether the book must be certified (under penalty of error if not). The default values of these new arguments cause warnings to be printed rather than errors signaled. The above change involved altering the form of certificate files. When books certified under previous versions are included, more warnings will be generated because these books are considered possibly to contain [47mdefaxiom[0m and/or [47mskip-proofs[0m events. We anticipate further changes to this aspect of books and consider the current mechanisms (for controlling whether warnings or errors are signaled) just a prototype. See also the discussion below of ``soundness related'' warnings. Your suggestions are welcome. A discrepancy between ACL2 and Common Lisp was fixed, having to do with [47mdeclare ignore[0m. In past versions of ACL2, a formal parameter of a [47mdefun[0m was considered ignored if it was not used in the body, the guard or the measure of the [47mdefun[0m. That meant that a variable used only in the guard could not be declared ignored in ACL2; but some Common Lisp compilers would complain because the variable was not used in the body. Now, ACL2 considers a variable ignored if it is not used in the body. ACL2 can now be built in releases 5.0 and later of Allegro Common Lisp. (Other releases of Allegro Common Lisp and of other lisps continue to be supported as well.) This includes Allegro Common Lisp running on Windows 98 platforms. John Cowles helped us do some testing and answered questions for us. Thanks John! We incorporated Ruben Gamboa's changes to allow the building of a variant, ACL2(r), of ACL2, in which the user can reason about the real numbers using non-standard analysis. See [real]. Note that ACL2(r) and ACL2 have different underlying theories, and books certified in one system may not be included in the other. For backward compatibility and to ensure a smooth transition, ACL2 is built by default, not ACL2(r). This is a compile-time switch; see the makefile for instructions. There should be no changes to ACL2 resulting from the capability of building ACL2(r) from the same sources. Also see [acknowledgments] for more on the history of ACL2(r). A large number of bugs (some affecting soundness) were fixed, and many small new features were added. See below. Less Important Changes: Some warnings are now considered ``soundness related,'' namely, those that advise you that an uncertified book has been included or that a book containing [47mDEFAXIOM[0m or [47mSKIP-PROOFS[0m events. (Technically, [47mDEFAXIOM[0ms do not imperil soundness in the proof- theoretic sense, though they may imperil the validity of theorems. But you should know when a book has added an axiom to your logic!) In previous versions of ACL2, all warnings were inhibited if the token [47mwarning[0m was included in the argument to [47m[set-inhibit-output-lst][0m. Now, soundness related warnings are printed even if [47mwarning[0ms have been inhibited. To inhibit all warnings, supply the token [47mwarning![0m to [47mset-inhibit-output-lst[0m. Several bugs in [47m[defstobj][0m were fixed, relating to the possibility that some of the subfunctions introduced by the [47mdefstobj[0m were already defined. [47m:[0m[47m[Puff][0m no longer tries to expand [47m[defstobj][0m events. Previously, the attempt would cause a hard error. A soundness bug was fixed. The bug might have been exercised if you had an alternative definition (implies hyps (equiv (fn ...) body)) in which equiv is an equivalence relation other than EQUAL. In this case, calls of fn might have been expanded to body in places that were not equiv-hittable. An obscure soundness bug was fixed. The bug was exercised only if you had a metafunction with a computed hypothesis (i.e., a ``meta hypothesis function''), the hypothesis contained a free variable, i.e., a variable not involved in the term being rewritten, and the free variable occurred in the output of the metafunction. The possibility of this bug was brought to our attention by Robert Krug. We fixed a bug in the handling of [47mhide[0m related to the question of whether a variable symbol occurs in a term. The old code did not find the variable and could cause the system to throw away a hypothesis about it on the grounds that it was never mentioned. Rob Sumners helped discover this problem. The handling of [47m:[0m[47m[elim][0m rules was generalized, permitting arbitrary known equivalence relations instead of merely [47mequal[0m in the concluding equality. The printing of runes (rule names; see [rune]) used has been made "deterministic," both in proof output and in proof attempt summaries, by sorting the runes before printing. The handling of free variables has been improved for hypotheses such as [47m(< 0 X)[0m, and more generally, any hypotheses involving a comparison with [47m0[0m (even for example [47m(< X 1)[0m where [47mX[0m is known to be an integer, which is handled as [47m(<= X 0)[0m). Thanks to Robert Krug for bringing relevant examples to our attention. A new value, [47m:comp[0m, has been implemented for the [47m:load-compiled-file[0m keyword of [47m[include-book][0m. If this value is supplied, then a compiled file will always be loaded, even if that requires creating the compiled file first. The event [47minclude-book[0m now generates a warning when a compiled file is expected but not found (see [include-book]). Formerly, it only did so when executed at the top level; it failed to generate the warning when executed on behalf of a surrounding [47minclude-book[0m command. Certain redefinition warnings generated by Allegro Common Lisp have been eliminated. A new key has been implemented for the [47m[ACL2-defaults-table][0m, [47m:bogus-mutual-recursion-ok[0m, set with [47m:[0m[47m[set-bogus-mutual-recursion-ok][0m. Thanks to David Russinoff for pointing out the utility of such a key. A bug was fixed in [47m[defun-sk][0m that prevented its generated events from being accepted when guard verification is being performed. Thanks to Bill Young for bringing this problem to our attention. A second bug was brought to our attention by Pete Manolios, which was causing certain [47m[defun-sk][0m events to be rejected. That problem has been fixed, and an "Infected" warning has also been eliminated. The command [47m[good-bye][0m now works with Allegro Common Lisp. A low-level bug was fixed that could, for example, cause an error such as "Error: Expected 5 args but received 4 args" when interrupting a [47mlocal[0m event. A bug has been fixed in the [proof-builder] related to definition expansion. Thanks to Pete Manolios for bringing this to our attention with a simple example. A bug has been fixed related to the [47m:[0m[bdd] hint in the presence of [equivalence] relations. Thanks to Pete Manolios for bringing this to our attention with a simple example. The functions [47m[position][0m and [47m[position-equal][0m formerly required the second argument to be a true list. In accordance with Common Lisp, we now also allow the second argument to be a string. This could cause earlier proofs about these functions to fail unless [47m[true-listp][0m is known to hold where necessary. Robert Krug wrote a patch, which has been incorporated, to prevent certain infinite loops that can arise in linear arithmetic. Thanks, Robert! The macro [47m[let*][0m no longer requires the bound variables to be distinct. An obscure bug was fixed related to congruence rules. The bug would sometimes cause ACL2 to behave as though no rules (other than equality) were available for some argument positions. Thanks to Pete Manolios for bringing this bug to our attention. Documentation topics have been added for [47m[hard-error][0m and [47m[prog2$][0m, and the documentation for [47m[illegal][0m has been improved. Thanks to Rob Sumners for a useful suggestion in the examples in documentation for [47mprog2$[0m and a fix in documentation for [47m[sublis][0m. The event form [47m[certify-book][0m was made more secure, in that it can now catch attempts to write a book to disk during its certification. Thanks to Rob Sumners for pointing out the insecurity of the existing mechanism. A Y2K problem was fixed with our applicative handling of dates. Accessors and updaters for [47m[stobj][0ms have been made more efficient when the underlying lisp is Allegro Common Lisp, by the use of appropriate simple array declarations. A raw Lisp break had been possible when a certified book that had no guard verification was included in a session after [47m([0m[47m[set-verify-guards-eagerness][0m[47m 2)[0m. This has been fixed. The keyword command [47m:[0m[47m[comp][0m can now be used to compile only raw Lisp functions, excluding executable counterparts, by supplying the argument [47m:raw[0m. Rewrite rule [47mnth-of-character-listp[0m was removed from source file axioms.lisp since it is essentially subsumed by [47mcharacterp-nth[0m. Printing has been sped up. In one example the improvement was over 50% in both Allegro and GCL. We now allow printing in a "downcase" mode, where symbols are printed in lower case. All printing functions except [47mprint-object$[0m now print characters in lower case for a symbol when the ACL2 state global variable [47mprint-case[0m has value [47m:downcase[0m and vertical bars are not necessary for printing that symbol. See [io] for a discussion of the macros [47macl2-print-case[0m and [47mset-acl2-print-case[0m. The default printing remains unchanged, i.e., symbols are printed in upper case when vertical bars are not required. A low-level printing function ([47mprin1$[0m) was modified so that it is not sensitive to various Common Lisp globals related to printing. So for example, the function [47m[fmt][0m is no longer sensitive to the value of Common Lisp global [47m*print-case*[0m. (The preceding paragraph explains how to control the case for printing in ACL2.) The definition of [47m[array1p][0m was fixed so that the [47m:maximum-length[0m of an array must be strictly greater than the number specified in the [47m:dimensions[0m field; they may no longer be equal. This was always the intention; the documentation (see [arrays]) has remained unchanged. The corresponding change was also made to [47m[array2p][0m. Allegro Common Lisp formerly caused an error when [47m[compress1][0m was called on an array where the numbers above were equal; now, we get a guard violation instead, which is appropriate. In the context of theories, a name now represents not just the corresponding [47m:definition[0m [rune], as it has done in earlier versions of ACL2, but also the corresponding [47m:[0m[47m[induction][0m rune. See [theories] for a discussion of runic designators. Most users will rarely, if ever, notice this change. One situation where this change will make a difference is after executing [47m(in-theory (current-theory 'foo))[0m followed by [47m(in-theory (enable bar))[0m, where function [47mbar[0m is introduced after event [47mfoo[0m, and [47mbar[0m is recursively defined. The latter [47m[in-theory][0m form now enables the rune [47m(:induction bar)[0m, which implies that the prover can use the induction scheme stored at definition time for [47mbar[0m. Formerly, the rune [47m(:induction bar)[0m was not enabled by [47m(in-theory (enable bar))[0m, and hence the induction scheme for [47mbar[0m was ignored even when explicit [47m:induct[0m hints were supplied. You may now supply [47m[xargs][0m keyword pair [47m:normalize nil[0m in order to prevent certain definitions from ``hanging'' when there are many [47mif[0m-subexpressions. see [defun]. We now translate type declarations of [47mreal[0m into guards, as we have already done for other types such as [47mrational[0m. For example, [47m(declare (type real x))[0m generates the [guard] [47m(rationalp x)[0m. See [type-spec]. The theorem prover now behaves reasonably under the combination of specifying a value of [47mt[0m both for [47m:[0m[47m[otf-flg][0m and for a hint [47m:do-not-induct[0m. Previously, it aborted the first time it would have otherwise pushed a goal for induction, but now, it will continue and wait until all induction subgoals have been pushed before it aborts. We changed slightly the definition of [47m[round][0m. However, we believe that the new definition is equivalent to the old. The definition of Common Lisp function [47m[substitute][0m has been added. The following changes have been made in the use of file names within ACL2. We thank Warren Hunt and John Cowles for running some tests of these changes on Macintosh and Windows 98 platforms (respectively). (1) Names of directories and files now use a syntax like that used for Unix (trademark of AT&T), where directories are separated using the ``[47m/[0m'' character even when the operating system is not Unix or Linux. See [pathname]. ACL2 also continues to support its notion of [3mstructured pathnames[0m from Version 2.4 and before, but might not do so in future releases and hence no longer documents such syntax. (2) The command [47m:[0m[47m[set-cbd][0m may now take a relative pathname as an argument. (3) When the macro [47m[ld][0m is given a file name as a value for [47m[standard-oi][0m, then if that file name is a relative pathname it refers to the result of prepending the connected book directory (see [pathname], see [cbd], and see [set-cbd]) in order to obtain an absolute pathname. Similarly for the [47mld[0m specials [47m[standard-co][0m and [47m[proofs-co][0m. It is no longer necessary to issue [47m:[0m[47m[set-state-ok][0m[47m t[0m if you include a [stobj] declaration for [47m[state][0m, for example: (declare (xargs :stobjs state)) See [declare-stobjs]. The [proof-builder] has been cleaned up a bit, including the documentation and the capability (once again) to define pc-macro commands (see [define-pc-macro]) and proof-builder meta commands (see [define-pc-meta]). Recall that events generate summaries that include a line beginning with ``[47mWarnings:[0m'', which is followed (on the same line) by zero or more brief strings that summarize the warnings generated by that event. Formerly, this warnings summary for an [47m[encapsulate][0m or [47m[include-book][0m event did not include the summary strings for warnings generated by subsidiary events. This has been fixed. Macro [47m[cw][0m has been documented and now expands to a call of a [47m;[0m[47m[logic][0m mode function. See [cw] for a way to print to the screen without having to involve the ACL2 [47m[state][0m. Thanks to Rob Sumners for suggesting that we document this useful utility. Functions [47mduplicates[0m, [47madd-to-set-equal[0m, [47mintersection-eq[0m, [47mevens[0m, and [47modds[0m are now [47m:[0m[47m[logic][0m mode functions.") (|NOTE-2-5{R}| (release-notes) "ACL2 Version 2.5(r) (June, 2000) Notes Important changes to non-standard version: Please see [note-2-5] for changes to Version 2.5 of ACL2. We hope to write more documentation for ACL2(r) in the future.") (note-2-6 (release-notes) "ACL2 Version 2.6 (November, 2001) Notes Because of the large number of modifications, we have divided up the Version 2.6 notes into the following subtopics. * New functionality (see [note-2-6-new-functionality]) * Changes in proof engine (see [note-2-6-proofs]) * Changes in rules and definitions (see [note-2-6-rules]) * Guard-related changes (see [note-2-6-guards]) * proof-builder changes (see [note-2-6-proof-builder]) * System-level changes (see [note-2-6-system]) * Other (minor) changes (see [note-2-6-other]) Subtopics [Note-2-6-guards] ACL2 Version 2.6 Notes on Guard-related Changes [Note-2-6-new-functionality] ACL2 Version 2.6 Notes on New Functionality [Note-2-6-other] ACL2 Version 2.6 Notes on Other (Minor) Changes [Note-2-6-proof-builder] ACL2 Version 2.6 Notes on proof-builder Changes [Note-2-6-proofs] ACL2 Version 2.6 Notes on Changes in Proof Engine [Note-2-6-rules] ACL2 Version 2.6 Notes on Changes in Rules and Constants [Note-2-6-system] ACL2 Version 2.6 Notes on System-level Changes") (note-2-6-guards (note-2-6) "ACL2 Version 2.6 Notes on Guard-related Changes When you [47m[declare][0m that a function treats certain formals as [47m:[0m[47m[stobj][0m[47ms[0m, the [guard] of the function is automatically extended to include the corresponding stobj-recognizer calls. For example, if a definition includes [47m(declare (xargs :stobjs (ST)))[0m then the guard of the function is changed by the addition of the conjunct [47m(ST-P ST)[0m. One impact of this is that if you use the built-in ACL2 [47m[state][0m as a formal parameter of a function, [47m(STATE-P STATE)[0m is added to the guard. This may introduce a guard where there was none in previous versions of the system. In older versions, therefore, no attempt would be made to [47m[verify-guards][0m, while in the new version, we would attempt guard verification. You may wish to add [47m(declare (xargs :verify-guards nil))[0m to such definitions. A related change affects users who do not use stobjs or [47mstate[0m. In previous versions of the system --- as now --- a [47mtype[0m declaration extended the guard you provided explicitly. Thus, if you wrote [47m(declare (type integer n))[0m then [47m(INTEGERP n)[0m was added to your guard. This is still the case and [47m:stobjs[0m recognizers are similarly added. But in older versions of the system we ``added'' the conjuncts without checking whether they were already present in the guard you provided. This sometimes produced such guards as [47m(and (integerp n) (integerp n))[0m where the first was produced by your [47mtype[0m declaration and the second was your [47m:guard[0m. We now eliminate redundant conjuncts; this may rearrange the order of the conjuncts. The guard conjectures for functions using [47mstobj[0ms have been simplified somewhat by taking advantage of the syntactic restrictions checked for single-threaded objects. The following functions have been modified so that character and string arguments are restricted to standard characters. (See [standard-char-p] and see [standard-char-listp].) [47m[upper-case-p][0m [47m[lower-case-p][0m [47m[char-upcase][0m [47m[char-downcase][0m [47mstring-downcase1[0m [47m[string-downcase][0m [47mstring-upcase1[0m [47m[string-upcase][0m [47m[char-equal][0m [47mstring-equal1[0m [47m[string-equal][0m Also, function [47mstandard-string-alistp[0m replaces function [47mstring-alistp[0m, with concomitant changes in the guard to [47m[assoc-string-equal][0m, and in variable [47m*acl2-exports*[0m. Also, lemma [47mstandard-string-alistp-forward-to-alistp[0m replaces lemma [47mstring-alistp-forward-to-alistp[0m. There is a new lemma [47mstandard-char-p-nth[0m, which has also been added to [47m*acl2-exports*[0m. The guard had been inadvertently omitted from the definition of the function [47m[substitute][0m (and its subroutine [47msubstitute-ac[0m). This omission has been corrected; also, the guard is slightly stronger than the documentation had claimed (and that has been corrected).") (note-2-6-new-functionality (note-2-6) "ACL2 Version 2.6 Notes on New Functionality A fundamental change is the provision of the ``nu-rewriter'' for simplifying expressions composed of [47mNTH[0m, [47mUPDATE-NTH[0m, and [47mUPDATE-NTH-ARRAY[0m applications and [47mLET[0m expressions and other calls of non-recursive functions or [47mLAMBDA[0m expressions involving those symbols. The nu-rewriter applies the obvious rewrite rule for [47m(NTH i (UPDATE-NTH j v s))[0m and the analogous rule for [47mUPDATE-NTH-ARRAY[0m. See nu-rewriter. The nu-rewriter can be enabled with [47mset-nu-rewriter-mode[0m. A new flag has been added to the [47mxargs[0m of [47m[defun][0m permitting the declaration that the function is [47mnon-executable[0m. The usage is [47m(declare (xargs :non-executable t))[0m and the effect is that the function has no executable counterpart. On the positive side: the function is permitted to use single-threaded object names and functions arbitrarily, as in theorems rather than as in executable definitions. Such functions are not permitted to declare any names [47m:[0m[47m[stobj][0m[47ms[0m but accessors, etc., may be used, just as in theorems. A new flag has been added to permit the system to abbreviate output by introducing [47mLET*[0m notation identifying common subterms. The formula being proved is not affected; this flag changes its displayed form only. See [set-let*-abstractionp]. A ``raw mode'' has been added, primarily for faster loading of applications. see [set-raw-mode]. Functions [47m[alphorder][0m and [47m[lexorder][0m have been put in [47m:[0m[47m[logic][0m mode. [47mLexorder[0m is now a total order ordering of the ACL2 universe, and theorems are included to that effect. Thanks to Pete Manolios for suggesting the idea and providing events to use, and to Rob Sumners for assistance with some modifications. See also the new book [47mbooks/misc/total-order[0m for an irreflexive total order. The ACL2 user can now make system calls to the host operating system. See [sys-call] and see [sys-call-status]. Thanks to Rob Sumners for working out this idea with Pete Manolios and Robert Krug, who we also thank, and for working out the implementation with us. It is no longer required to use absolute [pathname]s in [47m[include-book][0m forms that have been executed before a [47m[certify-book][0m. Any relative pathname strings in such contexts will be expanded into absolute pathnames before they are saved in the [47m[portcullis][0m of the [47m[certificate][0m of the book being certified. ACL2 can now be built on top of Allegro Common Lisp 6.0, and also on Windows platforms on top of Allegro Common Lisp and GCL. Thanks to Pete Manolios and Vinay K. Siddhavanahalli for their help with Windows. Rob Sumners has designed and provided an initial implementation for two improvements to [47m[defstobj][0m (also see [stobj]). First, array fields can now be resized. Resize and length functions are provided for array fields, which can be used to resize stobj array fields dynamically. The recognizers for array fields have been simplified to accommodate this change, so that they only check that each element of the array field has the specified type. Second, performance has been improved for stobjs with a large number of fields, by changing their Common Lisp implementation to store the fields in a simple vector instead of a list. Now [stobj]s may be bound locally; see [with-local-stobj]. Thanks to Rob Sumners, who encouraged us to implement this capability, was an early user of it, and participated usefully in discussions on its design. New functions [47m[fms!][0m, [47m[fmt!][0m, and [47m[fmt1!][0m are the same as their respective functions without the ``[47m![0m,'' except that the ``[47m![0m'' functions are guaranteed to print forms that can be read back in (at a slight readability cost). We added [47m[extended-metafunctions][0m, metafunctions which allow [47m[state][0m and context sensitive rewriting to some extent. We thank Robert Krug for pushing for and on this idea. The documentation has been improved. In particular, a new documentation topic provides a gentle introduction to ACL2 [47m[arrays][0m --- see [arrays-example] --- and additional documentation has been provided for getting started with proof trees in emacs --- see [proof-tree]. New Makefile targets [47mfasl[0m and [47mo[0m have been added to the [47mbooks/[0m directory of the distribution. For example, you might first certify books using an ACL2 built on top of GCL (which creates compiled files with suffix [47mo[0m). Then, when standing in the [47mbooks/[0m directory, you might execute the command make fasl ACL2=my-allegro-acl2 which will create compiled ([47m.fasl[0m) files for Allegro Common Lisp, assuming that [47mmy-allegro-acl2[0m starts up an ACL2 built on that Common Lisp. The macro [47m[let*][0m now allows variables to be declared ignored. See [let*] and see [let]. The user may now control backchaining. This feature was designed and primarily implemented by Robert Krug (though the authors of ACL2 are responsible for any errors); thanks, Robert! See [backchain-limit]. It is now possible to ``slow down'' the rate at which case splits are generated by the simplifier. See [set-case-split-limitations]. Accesses to [stobj]s using [47m[nth][0m or [47m[update-nth][0m are now displayed using symbolic constants instead of numeric indices. For example, given the event (defstobj foo a b :renaming ((b c))) then the term [47m(nth 0 foo)[0m will be displayed (for example, during proofs) as [47m(nth *a* foo)[0m while [47m(nth 1 foo)[0m will be displayed as [47m(nth *c* foo)[0m. The [47m[defstobj][0m event now correspondingly introduces a [47m[defconst][0m event for each field accessor function, introducing a constant whose name is obtained from the accessor's name by prefixing and suffixing a ``[47m*[0m,'' as in the example above: accessor [47ma[0m generates [47m(defconst *a* 0)[0m and accessor [47mc[0m generates [47m(defconst *c* 1)[0m. See [nth-aliases-table] for how to extend this feature for alternate names of [stobj]s. Computed hints have been improved. It is now possible to detect within a computed hint whether the goal clause is stable under simplification; it is also possible for a computed hint to change the list of available hints. See [computed-hints]. It is now possible to provide ``default hints'' that are appended to the hints explicitly provided. See [set-default-hints]. Using computed hints (see [computed-hints]) and default hints (see [set-default-hints]) it is possible to implement a book that supports ``priority phased simplification.'' Using this book you can assign priorities to your rules and cause the theorem prover to simplify each goal maximally under all the rules of one priority before enabling rules of the next priority. See [47mbooks/misc/priorities.lisp[0m. The macro [47m[defabbrev][0m has been improved to allow [47m[declare][0m forms and documentation strings and to do more error-checking. Thanks to Rob Sumners for designing this enhancement and providing the first implementation. See [defabbrev]. Further changes were made to support CMU Lisp. Wolfhard Buss helped with these changes. A new table was added that is used when printing proof output, so that nests of right-associated calls of a binary function are replaced by corresponding macro calls, as has been the case for [47m[binary-+][0m and [47m[+][0m, [47m[binary-append][0m and [47m[append][0m, and so on. See [add-binop]. Operators [47m[logand][0m, [47m[logior][0m, [47m[logxor][0m, and [47m[logeqv][0m are now macros (formerly, they were functions) that call corresponding binary functions (e.g., [47mbinary-logand[0m) defined in source file [47m"axioms.lisp"[0m. Thanks to Rob Sumners for this enhancement. Proof output will however continue to show calls of [47m[logand][0m, [47m[logior][0m, [47m[logxor][0m, and [47m[logeqv][0m. Function [47m([0m[47m[allocate-fixnum-range][0m[47m fixnum-lo fixnum-hi)[0m sets aside more "permanent" fixnums in GCL. ACL2 now runs under [47mCLISP[0m. Thanks to Wolfhard Buss and Sam Steingold for their assistance with the port. Michael ``Bogo'' Bogomolny has created a search engine, accessible from the ACL2 home page. For that purpose he modified the HTML translator to create one file per topic (a good idea in any case). Thanks, Bogo! An emacs file of potential (but optional) use for ACL2 users may be found in [47memacs/emacs-acl2.el[0m. In particular, this file supports the use of proof trees (see [proof-tree]). Some [books] have been added or modified. In particular, Robert Krug has contributed [47mbooks/arithmetic-2/[0m, which provides an alternative to the existing collection of books about arithmetic, [47mbooks/arithmetic/[0m. For a discussion of the distributed books see the link to [47mREADME.html[0m in the installation instructions.") (note-2-6-other (note-2-6) "ACL2 Version 2.6 Notes on Other (Minor) Changes Warning strings are now case-insensitive. See [set-inhibit-warnings]. ACL2 causes a warning when an [in-theory] hint or event causes a 0-ary function's definition to be disabled but its [47m:[0m[47m[executable-counterpart][0m to be enabled. A minor modification has been made to [47m[defstobj][0m that can have a positive impact on performance in Allegro Common Lisp. (For Lisp hackers: the stobj name was formerly declared special, and that was disabling Allegro's tail-merging routing for compilation of some recursive functions using stobjs.) The downside is that stobj names can no longer be evaluated in raw Lisp. However, raw Lisp is not the right place to be evaluating ACL2 forms anyhow; see [set-raw-mode]. We thank Rob Sumners for bringing this issue to our attention. Before Version 2.6, there has been the following problem with [47m[defstub][0m and [47m[encapsulate][0m in the case that the current package is not the ACL2 package. If a [signature] was specified using the symbol [47m=>[0m, then that symbol had to have been imported into the current package from the ACL2 package when the current package was defined. There are no longer any package restrictions on the use of [47m=>[0m. Thanks to John Cowles for bringing this problem to our attention. Bugs in [47m[defun-sk][0m have been fixed. [47mDefun-sk[0m forms introducing functions of no arguments were failing to be admitted, for example: [47m(defun-sk always-p1 () (forall (x) (p1 x)))[0m. Thanks to John Cowles for bringing this problem to our attention. Also, [47mdefun-sk[0m failed on an example in the documentation (see [tutorial4-defun-sk-example]), as pointed out by Matyas Sustik; this bug has been fixed as well. The trace mechanism has been fixed to handle [stobj]s, and to avoid the printing of so-called [3menabled structures[0m. The [47m[brr][0m command [47m:type-alist[0m now produces more readable output. An [47m[include-book][0m of an uncertified book no longer loads an associated compiled file. We added a few checks to make sure that the underlying lisp is suitable, for example checking that the reader is case-insensitive and reads in symbols with upper-case names where appropriate. We now warn when forcing (see [force]) or immediate force mode (see [immediate-force-modep]) change state between enabled and disabled. Also see [enable-immediate-force-modep] and see [disable-immediate-force-modep] for information about these new macros, which may be used to control immediate force mode. We have eliminated the use of a low-level raw Lisp constant, [47m*most-recent-multiplicity*[0m. Our test suite saw a speed-up of approximately 2% as a result for an ACL2 image built on GCL (but no significant speed-up for an ACL2 image built on Allegro Common Lisp). We thank Rob Sumners for suggesting this improvement. Fixnum declarations are now realized as [47m(signed-byte 29)[0m instead of [47m(signed-byte 27)[0m. We check that the underlying Common Lisp recognizes objects of type [47m(signed-byte 29)[0m as fixnums, with the exception of CLISP, which is said to have an efficient bignum implementation. A new documentation topic [functional-instantiation-example] illustrates functional instantiation. A bug has been fixed in the monitoring of runes (see [monitor]). Thanks to Dave Greve for sending an example that clearly showed the problem. A warning is now issued when it is detected that a [47m:[0m[47m[type-prescription][0m rule may not be as strong as it appears because it is not sufficient to prove itself by type reasoning. An error is caused for rules of class [47m:[0m[47m[meta][0m when the function symbol [47mIF[0m is among the [47m:trigger-fns[0m. ([47mIF[0m was ignored anyhow; the point of this change is to avoid misleading the user.) A minor bug has been fixed in [47m:[0m[47m[pr][0m, evident for example if this command was applied to [47mIF[0m. A minor hole in [47m:[0m[47m[set-bogus-mutual-recursion-ok][0m did not permit the acceptance of [47m[mutual-recursion][0m forms that include constant function definitions. This has been fixed. Thanks to Eric Smith for coming up with a simple example illustrating the problem. The temporary files "TMP.lisp" and "TMP1.lisp" written out by [47m:[0m[47m[comp][0m are now written to the connected book directory (see [cbd]). Previously, the Allegro compiler was not eliminating tail recursion for executable counterparts of functions, because of the way one of its flags had been set. As a result, calls of functions whose guards had not been verified could run out of stack space when this was not necessary. This situation has been fixed. Executable counterparts could have slow array accesses. This has been fixed (specifically, constants are no longer replaced with their values in the definitions of executable counterparts). Various improvements have been made to the documentation. Thanks in particular to Eric Smith for pointing out a numbers of places where fixes were in order. File "mcl-acl2-startup.lisp" has been updated, thanks to feedback from Philippe Georgelin. Inefficiencies in GCL fixnum computations were remedied for macros [47m+f[0m and [47m*f[0m. Thanks to Rob Sumners for pointing out this issue.") (note-2-6-proof-builder (note-2-6) "ACL2 Version 2.6 Notes on proof-builder Changes The proof-builder command [47m=[0m, when used with no arguments, now reports which hypothesis is being used. The output from [proof-builder] command [47mtype-alist[0m has been improved. A slight change has been made to the [proof-builder] for commands [47mpromote[0m, [47mcasesplit[0m, [47mequiv[0m, and [47m=[0m, so that terms of the form [47m(if x nil y)[0m are recognized as conjunctions, [47m(and (not x) y)[0m. Thanks to Pete Manolios for suggesting that we consider such a change. There is a new [proof-builder] command [47mprint-all-concs[0m that prints all the conclusions of the unproved goals. A new [47m[proof-builder][0m command, [47mrunes[0m, has been added. It reports the [rune]s that have participated in the interactive proof up to the current point.") (note-2-6-proofs (note-2-6) "ACL2 Version 2.6 Notes on Changes in Proof Engine Certain optimizations are performed when converting terms to clausal form. For example, [47m(< 0 1)[0m is known to be [47mt[0m, [47m(HARD-ERROR ctx str alist)[0m is known to be [47mnil[0m, and [47m(INTEGERP n)[0m is known to imply [47m(RATIONALP n)[0m. In earlier versions of ACL2, the conversion of a term to clausal form expanded [47mLAMBDA[0m applications. That may no longer occur. Some proofs may slow down (or fail) because your [47mLAMBDA[0m-expressions are not expanded away when you ``expected'' them to be. Robert Krug found a soundness bug in our linear arithmetic package. The bug was caused by the derivation of an equation from two inequalities without taking adequate precautions to ensure that both sides of the inequalities were numeric. Robert also kindly provided a fix which we adopted. Thanks Robert! We fixed a bug that could prevent the application of a metatheorem. A bug has been fixed that had caused bogus forcing rounds (see [forcing-round]). The bug could occur when the hypothesis of a rule was forced (see [force]) before the prover decided to start over and prove the original goal by induction. Thanks to Rob Sumners for drawing our attention to this problem. Some low-level fixes have been made that prevent certain infinite loops, based on reports by users. We thank Yunja Choi, Matt Wilding, and Pete Manolios for reporting such problems. An obscure potential soundness hole has been fixed by redoing the way evaluation takes place in the ACL2 loop and during theorem proving. We expect that users will see no difference based on this change. (Those interested in the details can see the long comment ``Essay on Evaluation in ACL2'' in source file interface-raw.lisp.) A small change was made in computation for a heuristic that controls backchaining. This will speed up proofs dramatically in a very few cases but should have a very small impact in general. The simplifier has been modified to avoid eliminating hypotheses of goals that can be established by contextual (specifically, type-set) reasoning alone. We believe that this change will generally strengthen ACL2's reasoning engine, although on rare occasions a lemma that formerly was provable may require user assistance. Thanks to Robert Krug for suggesting this change and providing its implementation. Case splits are now limited, by default. This may allow some proof attempts to provide output where previously the prover would appear to ``go out to lunch.'' For a more complete discussion, including instructions for how users can control case splitting, see [set-case-split-limitations]. A bug has been fixed in the handling of [47m:[0m[47m[type-prescription][0m rules by the [bdd] package. Thanks to Rob Sumners for discovering this bug and supplying a helpful example. ACL2 may now use the built-in induction scheme for a function symbol even if that function symbol is disabled. Formerly, if a function symbol was disabled then its induction scheme was only considered if an explicit induction hint was supplied, other than [47m:induct t[0m. We eliminated the rule-class [47mlinear-alias[0m. This rule class was seldom used and complicated the linear arithmetic decision procedure in ways that made it difficult to extend to handle some non-linear special cases. The only use of the rule-class that we know of was in our own [47mNqthm[0m books, which were an attempt to provide an embedding of the Nqthm logic and theorem prover into ACL2. But that facility was also practically never used, as far as we know. So both [47mlinear-alias[0m rules and the [47mNqthm[0m books have been eliminated. In earlier versions of ACL2, when the [47mIF[0m-form of [47m(AND p q)[0m was assumed true --- as when rewriting the [47malpha[0m expression in [47m(IF (AND p q) alpha beta)[0m --- the assumption mechanism did not deduce that [47mp[0m and [47mq[0m are true, only that their conjunction, in its [47mIF[0m-form, is true. This has long been known as a deficiency in both ACL2 and the earlier Nqthm but it was tedious to do better when one considered the full range of [47mIF[0m-forms one might encounter in the test of another [47mIF[0m. Rather than code all the cases, we just waited until clausification got rid of them. Robert Krug developed a pretty nice treatment of the general case and we added it in this version. This also involved a surprising number of changes elsewhere in the system because the improved handling of assumptions caused the theorem prover often to ``erase'' hypotheses provided by [47m:use[0m hints because it could simplify them to [47mt[0m. Thank you Robert! In response to a suggestion from Robert Krug, we added [47mmfc-ap[0m so that extended metafunctions can take advantage of linear arithmetic. See [extended-metafunctions]. There is less delay in printing goals. In previous versions, a goal was not printed until its subgoals were created (or the goal was proved). Now, the goal is printed essentially as soon as it is created. A small technical change has been made in the function [47m[term-order][0m, to give priority on the function symbol count over the weighting of constants. So for example, while previously the term [47m(f)[0m preceded the constant 2, that is no longer the case. If this change is noticed at all, it will probably be noticed in how so-called [3mpermutative[0m rewrite rules are applied; see [loop-stopper]. Thanks to Robert Krug for suggesting this improvement and providing part of the implementation.") (note-2-6-rules (note-2-6) "ACL2 Version 2.6 Notes on Changes in Rules and Constants The following symbols have been added to the list constant [47m*common-lisp-specials-and-constants*[0m: [47mREPLACE[0m, [47mFILL[0m, [47mCHARACTER[0m, [47m=[0m, [47mBREAK[0m, and [47mPRIN1[0m. This was done in support of ports to Allegro 6.0 and Windows platforms (see [note-2-6-new-functionality]). The list of symbols in [47m*acl2-exports*[0m has been modified, for example to include [47mshow-accumulated-persistence[0m and the legal arguments to [47m[set-inhibit-output-lst][0m. Functions [47m[zp][0m and [47m[zip][0m are now handled slightly differently. They are are now disabled, but each comes with a [47m:[0m[47m[rewrite][0m rule that allows their expansion on non-variable terms, and also with a [47m:[0m[47m[compound-recognizer][0m rule that avoids the need for opening up these functions when applied to variables. The resulting behavior should be very similar to the behavior of previous versions, except that case splits will be avoided when these functions are applied to variables. Function [47mstandard-string-alistp[0m replaces function [47mstring-alistp[0m. For further discussion, see [note-2-6-guards]. Rules of class [47m:[0m[47m[rewrite][0m whose conclusion is a term of the form [47m(equal lhs rhs)[0m have always been stored in the expected way: [47mlhs[0m rewrites to [47mrhs[0m. This way of storing [47m:rewrite[0m rules has been extended to allow [47m[=][0m, [47m[eq][0m, or [47m[eql][0m in place of [47m[equal][0m. Rewrite rule [47mnth-update-nth[0m, in source file [47maxioms.lisp[0m, has been strengthened. A new rewrite rule [47mequal-constant-+[0m has been added to the book [47marithmetic/equalities[0m. This should generally be a beneficial change, but existing proofs involving the arithmetic books could conceivably be affected. Function [47m[symbol-package-name][0m and constant [47m*main-lisp-package-name*[0m have undergone small changes. This change should rarely be noticed by users and is discussed elsewhere; see [note-2-6-system]. We mention here that proofs involving [stobj]s may need to be modified because of changes in auxiliary functions generated by [47m[defstobj][0m. (These changes were made in support of a new resizing capability, mentioned elsewhere in these release notes; see [note-2-6-new-functionality]. In the distributed book directory [47mbooks/arithmetic/[0m, the book [47mrationals-with-axioms-proved.lisp[0m has been renamed [47mrationals.lisp[0m. (ACL2(r) only) Rewrite rules [47mrealp-+[0m, [47mrealp-*[0m, [47mrealp-unary--[0m, and [47mrealp-unary-/[0m have been added in analogy to existing rules [47mrationalp-+[0m, [47mrationalp-*[0m, [47mrationalp-unary--[0m, and [47mrationalp-unary-/[0m. Thanks to Jun Sawada for suggesting this change. The definition of [47m[aref1][0m has been modified slightly. Previously, if [47m*my-a*[0m were an array then [47m(aref1 'some-name *my-a* :header)[0m would evaluate to the [47mcdr[0m of the [47m[header][0m of [47m*my-a*[0m rather than to its [47m[default][0m. See [arrays]. Changes have been made in the [47mihs[0m books, based on suggestions from Jun Sawada, that support its use with ACL2(r) (see [real]). The primary change is to replace calls of [47m[rationalp][0m with calls of [47m[real/rationalp][0m, which should have no effect on users of standard ACL2.") (note-2-6-system (note-2-6) "ACL2 Version 2.6 Notes on System-level Changes We modified the tracking of [47m[skip-proofs][0m events and the use of [47m[state][0m global [47mld-skip-proofsp[0m in order to avoid some soundness issues. For example, [47m[skip-proofs][0m events buried in locally-included books are now tracked. The ``Essay on Skip-proofs'' in source file [47maxioms.lisp[0m gives several examples of dicey behavior that is no longer supported. We fixed a problem with some of the makefiles, so that recursive invocations of `make' now use the version of `make' specified on the command line. Files were fixed to help non-Unix/Linux users with book certification. Thanks to John Cowles for finding some problems and suggesting fixes to [47mbooks/certify-numbers.lisp[0m, [47mbooks/arithmetic/certify.lsp[0m, and [47mbooks/cowles/certify.lsp[0m. We thank Scott Burson for noticing and fixing some other such problems. Moreover, a bdd test was being ignored entirely in Version 2.5; this problem has been fixed as well. A minor change in system function save-acl2-in-allegro will allow this function to continue to work in Allegro CL versions starting (someday) with 10.0. Thanks to Art Flatau for suggesting such a fix. The [47mbooks/case-studies/[0m directory has been removed. These books are in support of the first (1998) ACL2 workshop, and are accessible via the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/}. Also, the [47mbooks/cli-misc[0m directory has been renamed [47mbooks/misc[0m, and the [47mbooks/nqthm[0m directory has been removed. The notion of ACL2 version has been slightly modified to catch unsoundness due to implementation dependencies. See [version]. Another change to eliminate such unsoundness is that built-in symbols now have a [47m[symbol-package-name][0m of [47m"COMMON-LISP"[0m; formerly, this string was [47m"LISP"[0m for ACL2 images built on GCL. See [symbol-package-name]. At a low level, the (undocumented) constant [47m*main-lisp-package-name*[0m is now [47m"COMMON-LISP"[0m; before, it was [47m"LISP"[0m for GCL.") (|NOTE-2-6{R}| (release-notes) "ACL2 Version 2.6(r) (November, 2001) Notes Important changes to non-standard version: None since Version 2.5. Please see [note-2-6] for changes to Version 2.6 of ACL2. We hope to write more documentation for ACL2(r) in the future.") (note-2-7 (release-notes) "ACL2 Version 2.7 (November, 2002) Notes The Version_2.7 notes are divided into the subtopics below. Here we give only a brief summary of a few of the changes that seem most likely to impact existing proofs. Not included in this brief summary, but included in the subtopics, are descriptions of improvements (including bug fixes and new functionality) that should not get in the way of existing proof efforts. In particular, please see [note-2-7-new-functionality] for discussion of a number of new features that you may find useful. Acknowledgments and elaboration, as well as other changes, can be found in the subtopics listed below. Bug fixes (see [note-2-7-bug-fixes]) * Three soundness bugs were fixed. These bugs were probably rarely hit, so users may well not notice these changes. * [47m[Certify-book][0m now requires [47m:skip-proofs-ok t[0m (respectively, [47m:defaxioms-okp t[0m) if there are [47m[skip-proofs][0m (respectively, [47m[defaxiom][0m) events in the book or any included sub-books. * When [47m:by[0m hints refer to a definition, they now use the original body of that definition rather than the simplified (``normalized'') body. * When [47m[ld][0m is applied to a stringp file name, it now temporarily sets the connected book directory (see [cbd]) to the directory of that file while evaluating forms in that file. New functionality (see [note-2-7-new-functionality]) * ACL2 now works harder to apply [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules with free variables in the hypotheses. See [note-2-7-new-functionality], in particular its first two paragraphs, for details. [Forward-chaining] also does more with free variables. Changes in proof engine (see [note-2-7-proofs]) * Some prover heuristics have changed slightly. Among other consequences, this can cause subgoal [hints] to change. For example, suppose that the Version_2.6 proof of a particular theorem generated "Subgoal 2" and "Subgoal 1" while Version_2.7 only generates the second of these. Then a subgoal hint attached to "Subgoal 1" in Version_2.6 would have to be attached to "Goal'" in Version_2.7. (See [goal-spec].) The full topic has details (see [note-2-7-proofs]). Changes in rules and definitions (see [note-2-7-rules]) * The package name of a generated variable has changed for [47m[defcong][0m. Guard-related changes (see [note-2-7-guards]) * [47m[Guard][0m verification formerly succeeded in a few cases where it should have failed. * Guards generated from type declarations now use functions [47msigned-byte-p[0m and [47munsigned-byte-p[0m, now defined in source file [47maxioms.lisp[0m and formerly defined rather similarly under [47mbooks/ihs/[0m. proof-builder changes (see [note-2-7-proof-builder]) * See the above doc topic. System-level changes (see [note-2-7-system]) * See the above doc topic. Other changes (see [note-2-7-other]) * A new [47m[table][0m, [47m[invisible-fns-table][0m, takes the place of the handling of invisible functions in the [47m[ACL2-defaults-table][0m, * The [47m[theory-invariant][0m event has been modified so that the default action is an error rather than a warning. * Proof output that reports destructor elimination no longer uses the word ``generalizing''. Again, please proceed to the subtopics for more thorough release notes. Subtopics [Note-2-7-bug-fixes] ACL2 Version 2.7 Notes on Bug Fixes [Note-2-7-guards] ACL2 Version 2.7 Notes on Guard-related Changes [Note-2-7-new-functionality] ACL2 Version 2.7 Notes on New Functionality [Note-2-7-other] ACL2 Version 2.7 Notes on Miscellaneous Changes [Note-2-7-proof-builder] ACL2 Version 2.7 Notes on proof-builder Changes [Note-2-7-proofs] ACL2 Version 2.7 Notes on Changes in Proof Engine [Note-2-7-rules] ACL2 Version 2.7 Notes on Changes in Rules and Constants [Note-2-7-system] ACL2 Version 2.7 Notes on System-level Changes") (note-2-7-bug-fixes (note-2-7) "ACL2 Version 2.7 Notes on Bug Fixes Francisco J. Martin-Mateos emailed us a soundness bug (!) in our handling of functional instantiation (for example see [functional-instantiation-example]). We are grateful for that email, which clearly illustrated the problem. It is included just below the definition of [47mpush-clause[0m in ACL2 source file [47mprove.lisp[0m, where we have fixed the bug. This bug was fixed in a re-release of Version 2.6 in February, 2002. Rob Sumners emailed us a soundness bug (!) in function [47mcommutative-p1[0m, which is used by the ACL2 [bdd] package. We are grateful for his help; his email gave a proof of nil and also pointed to the problem function. This bug was fixed in a re-release of Version 2.6 in February, 2002. We discovered and fixed a soundness bug illustrated by the book below, which was certifiable in Version 2.6 and ends in a proof of [47mnil[0m. The event [47m(verify-guards foo)[0m should have been rejected, because [47mfoo[0m calls a function whose guards have not been verified, namely, [47mbar[0m. However, ACL2 did not notice the call of function [47mbar[0m in the body of [47mfoo[0m because it was looking in the simplified (normalized) body of [47mfoo[0m rather than in the original body of [47mfoo[0m. During processing of the book below, the logical definition of [47mzp[0m is used before [47m(verify-guards foo)[0m, and [47m(zp -3)[0m reduces to [47mt[0m in the logic. After [47m(verify-guards foo)[0m, ACL2 simplifies [47m(foo -3)[0m by going into raw Lisp, where [47m(zp -3)[0m is evaluated and reduces to [47mnil[0m. (in-package "ACL2") (defun bar (x) (zp x)) (defthm zp-false-on-negatives (implies (< x 0) (bar x)) :rule-classes :type-prescription) (defun foo (x) (declare (xargs :guard (rationalp x) :verify-guards nil)) (if (< x 0) (if (bar x) 0 1) ; simplified body reduces this line to 0 17)) (defthm foo-of-minus-3-is-0 (equal (foo -3) 0) :rule-classes nil) (verify-guards foo) (defthm foo-of-minus-3-is-1 (equal (foo -3) 1) :rule-classes nil) (defthm bug nil :rule-classes nil :hints (("Goal" :use (foo-of-minus-3-is-0 foo-of-minus-3-is-1)))) The above bug exploited the fact that [47m[zp][0m has a different definition in raw Lisp than in the logic for arguments that violate its guard). The following example caused a hard error in raw Lisp, though not a soundness error. (in-package "ACL2") (defun bar (x) (cons (car x) (car x))) (defun foo (x) (declare (xargs :guard t :verify-guards nil)) (if (bar x) x nil)) (verify-guards foo) (defthm bug (equal (foo 3) t) :rule-classes nil) We have made a minor change to the notion of the [3mformula[0m of a function symbol, related to the change above, which however is unlikely to be noticeable. In order to make it harder to hit problems like the guard problem above, we have slightly modified the raw Lisp definition of [47m[zp][0m. A [47m[break-rewrite][0m command, [47m:ancestors[0m, was broken, but has been fixed. Thanks to Eric Smith for bringing the problem to our attention, and to Robert Krug for supplying the final part of the fix. Some [proof-builder] commands caused errors when all goals have already been proved. This has been fixed. Thanks to Matt Wilding for reporting this bug. Fixed a bug in [47m:[0m[47m[comp][0m. When compiling uncompiled functions with very large definitions, ACL2 was inserted a backslash ([47m\[0m) character into generated files. Fixed the [47m:type-alist[0m [47m:[0m[47m[brr][0m command (see [brr-commands]), whose output was difficult to read when typed after an [47m:eval[0m.. Fixed some clumsy handling of errors when including an uncertified book, for example, with the error message when including an uncertified book with a bad [47m[deftheory][0m event. Thanks to Eric Smith for pointing out this problem. Two modifications to [47m[certify-book][0m now cause it to reflect natural expectations with respect to soundness. First, it now has default values of [47mnil[0m instead of [47mt[0m for keyword arguments [47m:skip-proofs-okp[0m and [47m:defaxioms-okp[0m. Thanks to Robert Krug for suggesting this change and the ACL2 seminar at the University of Texas for discussing it. Second, when [47m:skip-proofs-okp[0m (respectively, [47m:defaxioms-okp[0m) is [47mnil[0m, either explicitly or by default, then [47m[skip-proofs][0m commands (respectively, [47m[defaxiom][0m events) are disallowed inside any included books, regardless of the keyword parameters passed to [47m[include-book][0m. This had not been the case for previous versions of ACL2, regardless of the values of [47m:skip-proofs-okp[0m or [47m:defaxioms-okp[0m passed to [47m[include-book][0m. Improved warnings and errors for [47m[certify-book][0m and [47m[include-book][0m to mention the [portcullis] as a possible source of [47m[skip-proofs][0m and [47m[defaxiom][0ms. ACL2 formerly caused an error when [hints] in a [47m:[0m[47m[corollary][0m were not well-formed. This situation could arise as follows when certifying a book. A lemma FOO is proved [47m[local][0mly to the book (or, is present in a sub-book that is included locally). The [47m:corollary[0m of a subsequent theorem, BAR, disables that rule in a hint. When BAR is proved, this is not a problem. But [47m[certify-book][0m makes a second pass after processing the events in a book: it essentially does an [47m[include-book][0m. During the [47minclude-book[0m pass, FOO is not known (because it was [47m[local][0m), and therefore ACL2 fails to process the [47m[disable][0m of FOO in an [47m[in-theory][0m hint. The fix is that during [47m[include-book][0m, [hints] are ignored in corollaries just as they have been for the main theorem (or definition). It was possible for guard verification to succeed where it should have failed. We have fixed the bug (which was in source function (ironically named!) [47mfcons-term-smart[0m). Thanks to Robert Krug for sending us an example of bungled guard verification. It turns out that this bug was also present in Version_2.6. The [proof-builder] command [47m=[0m has been improved. Formerly, it could fail to apply when certain [47m[implies][0m terms were in the context. Thanks to Pete Manolios for bringing this problem to our attention. The command [47m[add-binop][0m failed to work. This has been fixed. Thanks to Rob Sumners for pointing out this problem. Also see [note-2-7-other] for a discussion of how this and another [table] are no longer part of the [47m[ACL2-defaults-table][0m. Book certification could cause a segmentation fault in cases where the certification world (see [certify-book]) has a very large number of events. This has been fixed. We now allow empty [47m:use[0m [hints] and empty hints, as requested by Eric Smith. Examples: ("Goal" :use ()) ("Goal") A large [47m[mutual-recursion][0m nest could cause a stack overflow when executing either [47m:pr FN[0m, [47m:pr! FN[0m, or [47m:monitor (:definition FN) t[0m, where [47mFN[0m is in that large mutual recursion nest. This has been fixed (implementation detail: function [47mactual-props[0m has been made tail-recursive). NOTE: If you just want the definition of [47mFN[0m, [47m:[0m[47m[pf][0m[47m FN[0m can be much faster than [47m:[0m[47m[pr][0m[47m FN[0m if [47mFN[0m is in a large [47m[mutual-recursion][0m. Hard Lisp errors could occur when including uncertified books. This has been fixed; ACL2 now does syntax-checking formerly omitted when including uncertified books. Previously, the evaluation of [47m[defstobj][0m and [47m[mutual-recursion][0m forms could cause ``undefined'' warnings when the form was compiled. This has been fixed. Thanks to Eric Smith for bringing a [47mmutual-recursion[0m example to our attention. A bug has been fixed in the syntactic check for valid [47m:[0m[47m[loop-stopper][0m values. Formerly, valid [47m:loop-stopper[0m values were erroneously restricted to lists of length at most 2 (a minor problem, since these lists typically have length 1), and the function symbol(s) need not have been defined in the current ACL2 [world]. Thanks to Eric Smith for sending an example to demonstrate the latter problem. Functions definitions that are [47m:non-executable[0m (see [xargs]) had never been recognized as redundant, but this has been fixed. Thanks to Vernon Austel for pointing out this problem. Compilation using [47m:[0m[47m[comp][0m now compiles user-defined [47m:[0m[47m[program][0m mode functions. Formerly only [47m:[0m[47m[logic][0m mode functions could be compiled using [47m:comp[0m. Handling of [47m:by[0m hints has been improved in essentially three ways. The primary change is that now, when the current goal exactly matches the supplied lemma instance, the subsumption test will always succeeds (see [hints], in particular the discussion of [47m:by[0m). Second, certain proof failures involving [47m:by[0m [hints] were failing silently, with duplicate messages ``As indicated by the hint, this goal is subsumed by....'' This could happen when the original goal was among the goals generated by applying the hint. This problem has been fixed by no longer considering this proof step to be specious (see [specious-simplification]). Third and finally, when the [lemma-instance] refers to a definition, the original body of that definition is used rather than the simplified (``normalized'') body. In addition to the above, we now recognize more cases of specious simplification (see [specious-simplification]). Thanks to Eric Smith for bringing this issue to our attention. Fixed building of ACL2 under CLISP so that (1) the appropriate ACL2 startup message is printed out when ACL2 starts up, and (2) the lisp process supplied to make, e.g., LISP=/usr/bin/clisp, is the one written out to the saved ACL2 file. Thanks to Dave Greve and Noah Friedman for suggesting (2). Also, ACL2 now works with CLISP 2.30. We have accommodated a change in CLISP's handling of streams and its package-locking mechanism, as well as certain non-standard characters that formerly could cause CLISP 2.30 to break, even when those characters are in comments. Eliminated compiler warnings for CMU Lisp. Fixed an incorrect error supplied when book certification proceeded so quickly that the file write dates of the book ([47m.lisp[0m file) and the corresponding compiled file are equal. Now that error only occurs if the compiled file has a strictly earlier write date, which probably should never happen. Fixed an infinite loop when executing [47mmake clean-books[0m (and hence `make' with targets that call [47mclean-books[0m, namely, [47mcertify-books-fresh[0m, [47mregression-fresh[0m, and [47mregression-nonstd-fresh[0m), which could occur when any subdirectories of [47mbooks/[0m are missing --- even [47mworkshops/[0m, which is intended to be optional. Thanks to Pete Manolios for pointing out this bug. The [47m[include-book][0m command now works properly even when filenames, or their directories or parent directories (etc.) are links. Thanks to Matt Wilding for pointing out this problem. The commands [47m:[0m[47m[puff][0m [47m:[0m[47m[puff*][0m have been fixed. Formerly, there was a bug when [47m:puff[0m or [47m:puff*[0m caused the execution of an [47m[include-book][0m for an absolute [pathname], [47mP[0m, that was other than the current connected book directory (see [cbd]). When including [47mP[0m, any subsidiary [47m[include-book][0m with a relative pathname would be erroneously considered relative to the current [47m[cbd][0m rather than relative to the directory of [47mP[0m. Thanks to Pete Manolios and Matt Wilding for pointing out this problem. It had been possible in a ``large'' ACL2 image to call [47m[verify-termination][0m successfully on built-in function [47m[sys-call][0m, with undesirable results. This hole has been plugged. Thanks to Rob Sumners for pointing out this problem. The new function [47m[gc$][0m must also stay in [47m:[0m[47m[program][0m mode. ACL2 no longer warns when certifying a book based on [47m[local][0m functions whose [guard]s have not yet been verified. Thanks to Pete Manolios for pointing out this issue. An occasional ``slow array warning'' had been possible during proofs. The following sequence shows how to evoke that warning in previous versions. (in-theory (disable binary-append)) (in-theory (enable binary-append)) (in-theory (disable binary-append)) (ubt 2) (thm (equal (car (cons x y)) x)) (See [note-2-7-other] for a discussion of a change to [47m[compress1][0m in support of this fix; however, users should not need to read that discussion.) The raw Lisp code for [47m[defchoose][0m had a small bug, which was only evidenced in CLISP implementations as far as we know. It has been fixed. When [47m[ld][0m is applied to a stringp file name, it now temporarily sets the connected book directory (see [cbd]) to the directory of that file while evaluating forms in that file. To see the effect of this change, imagine a subdirectory [47m"sub"[0m of the current directory, and imagine executing [47m(ld "sub/foo.lisp")[0m, where file [47mfoo.lisp[0m contains the form [47m(include-book "bar")[0m. Presumably the intention was to consider the file [47mbar.lisp[0m in the same directory, [47msub/[0m, as [47mfoo.lisp[0m. [47mLd[0m now honors that intention, but in previous versions [47m"bar.lisp"[0m would have been a reference to a file in the current directory, not in [47msub/[0m. For users of [47mrun-acl2[0m [perhaps there are none!]: A fix has been provided by a Debian user via Camm Maguire so that acl2-mode will work in Xemacs, which apparently uses variable [47mlisp-mode-shared-map[0m rather than [47mshared-lisp-mode-map[0m. ACL2 has, for a long time (always?), had a mechanism for avoiding re-proving [constraint]s generated by [47m:functional-instance[0m [lemma-instance]s in [47m:use[0m and [47m:by[0m hints. But this mechanism had not applied to defined (as opposed to constrained) functions. This has been fixed. Thanks to Francisco J. Martin-Mateos (ChesKo) for pointing out this problem by sending a clear example.") (note-2-7-guards (note-2-7) "ACL2 Version 2.7 Notes on Guard-related Changes It was possible for guard verification to succeed where it should have failed. See the discussion under [note-2-7-bug-fixes]. There have been changes in the guards generated from type declarations for the following cases. Thanks to Dave Greve and Matt Wilding for suggesting such changes. (type (signed-byte n) val) (type (unsigned-byte n) val) (type (integer m n) val) The following examples illustrate the changes. (type (signed-byte 4) x) ==> [old] (AND (INTEGERP X) (<= -8 X) (<= X 7)) ==> [new] (SIGNED-BYTE-P 4 X) (type (unsigned-byte 4) x) ==> [old] (AND (INTEGERP X) (<= 0 X) (<= X 15)) ==> [new] (UNSIGNED-BYTE-P 4 X)") (note-2-7-new-functionality (note-2-7) "ACL2 Version 2.7 Notes on New Functionality ACL2 now has a more powerful technique for relieving a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m rule's hypothesis that contains free variables. A new [documentation] section has been written describing the handling free variables in rules; see [free-variables]. In brief, the primary change is that when a free-variable match for the current hypothesis fails to allow subsequent hypotheses to be relieved, then additional matches may be attempted until they have all been tried. Also see [rule-classes] (discussion of [47m:match-free[0m). Also see [set-match-free-error], see [set-match-free-default], and see [add-match-free-override] for interfaces provided to the user for controlling the way ACL2 deals with free variables in hypotheses. We thank Rob Sumners for several helpful discussions about the designs of those interfaces, as well as Eric Smith and Robert Krug for helpful related discussions. Robert Krug also found a performance bug in a preliminary version, for which we are grateful. WARNING: Book certification attempts may take much longer now that, by default, ACL2 looks for more free variable matches (see paragraph just above). You can get the old behavior by inserting the form (set-match-free-default :once) just after the initial [47m[in-package][0m form. However, rules from included books that have free variables can still slow down certification. This can be fixed by inserting (add-match-free-override :once t) before the first event in the file that generates a proof. [Forward-chaining] has been made more powerful in the presence of free variables (see [free-variables]), thanks to a contribution by Erik Reeber. Both before and now, when an attempt is made to relieve (prove) a hypothesis of a [47m:forward-chaining[0m rule in the case that at least one variable in that hypothesis is not yet bound, ACL2 looks in the current context for an instance of that hypothesis. If it finds one, then it binds the unbound variables and continues to the next hypothesis. What is new is that ACL2 can now look for multiple instances of that hypothesis. Consider the following example; an explanation is below. (encapsulate (((op * *) => *)) (local (defun op (x y) (< x y))) (defthm transitivity-of-op (implies (and (op x y) (op y z)) (op x z)) :rule-classes :forward-chaining)) ; fails in Version_2.6; succeeds in in Version_2.7 (thm (implies (and (op a b) (op b c) (op b e)) (op a c))) Before Version_2.7, the proof of the [47mthm[0m above fails. When the [47m:forward-chaining[0m rule [47mtransitivity-of-op[0m binds [47mx[0m to [47ma[0m and [47my[0m to [47mb[0m, it then looks for an instance of [47m(op y z)[0m in the current context, with [47my[0m bound to [47mb[0m but [47mz[0m unbound. It happens to find [47m(op b e)[0m before [47m(op b c)[0m, and it then adds [47m(op a e)[0m to the context. But starting with Version_2.7, it continues to look for additional instances and finds [47m(op b c)[0m in the context as well, chaining forward to [47m(op a c)[0m and thus proving the theorem. A new macro, [47m[bind-free][0m, provides a simple way to get much or most of the power of [meta]functions. Thanks to Eric Smith for coming up with the idea and to Robert Krug for providing an implementation (which we modified only very slightly) and documentation. See [bind-free] and see [bind-free-examples]. With the addition of [47m[bind-free][0m (mentioned above), [47m[syntaxp][0m has become a macro, although that change should be transparent to the user. More importantly, the argument of [47msyntaxp[0m may now refer to variables [47mmfc[0m and [47mstate[0m, giving [47msyntaxp[0m some of the power of extended metafunctions; see [syntaxp] and see [extended-metafunctions]. Thanks to Robert Krug for implementing that extension. Also, the argument of [47m[syntaxp][0m may now include calls of [47m:[0m[47m[program][0m mode functions. See [syntaxp] and see [syntaxp-examples] (thanks to Robert Krug for updating the former and creating the latter documentation). The linear-arithmetic decision procedure (see [linear-arithmetic]) has now been extended so that ACL2 can reason about non-linear arithmetic as well (see [non-linear-arithmetic] for how to turn on this feature). We thank Robert Krug for the initial implementation of this, and Eric Smith for finding a couple of bugs in it. Some [47m[trace][0m utilities have been made available in the ACL2 loop. * Function [47m[trace$][0m (and also [47m[untrace$][0m) calls the corresponding underlying Lisp routine [47mtrace[0m (and [47muntrace[0m), which however continues (as it has for some time) to be enhanced for GCL and Allegro CL. * Macro [47m[open-trace-file][0m causes trace output to go to a specified file. Macro [47m[close-trace-file][0m causes trace output to go to the screen (which is the default). * Macro [47mwith-error-trace[0m (or, [47mwet[0m for short) causes a backtrace to be written out for many failures, including guard violations. See [trace], see [trace$], and see :DOC [47mwet[0m [** NOTE: eliminated after Version 3.3]. A new [47m[theory][0m, [47m[minimal-theory][0m has been provided (see [theories]). It can be particularly useful for speeding up proofs involving [47m:use[0m [hints]. New [47m[events][0m [47m[defund][0m and [47m[defthmd][0m behave exactly like [47m[defun][0m and [47m[defthm][0m, respectively, except that these new events disable the new name. The new macro [47m[with-output][0m can be used to suppress output that would normally result from evaluation of a form. The form [47m([0m[47m[pstack][0m[47m)[0m can give the user an idea of what the prover has been up to during a proof, or after a user-aborted proof. Moreover, by evaluating [47m(verbose-pstack t)[0m (see [verbose-pstack]) one can get [trace]-like information about prover functions, including time summaries, printed to the screen during a proof. Thanks to Bill Legato and Robert Krug for initiating this work and to Robert for providing some initial implementation. The new command [47m:[0m[47m[comp-gcl][0m is identical in functionality, except that it always leaves [47m.c[0m and [47m.h[0m files when compiling in GCL. Thanks to Rob Sumners and Vernon Austel for suggesting such a capability. The macro [47m[e/d][0m provides a convenient way to [47m[enable][0m some rules and [47m[disable][0m others. It was formerly in a book supplied with the distribution, [47mbooks/ihs/ihs-init.lisp[0m, written by Bishop Brock (who we thank for providing this useful macro). New distributed books include those in [47mbooks/ordinals/[0m, [47mbooks/rtl/rel3/[0m, and [47mbooks/misc/simplify-defuns.lisp[0m (which is documented in [47mbooks/misc/simplify-defuns.txt[0m). The [47m:expand[0m hint now accepts a special value, [47m:LAMBDAS[0m, that tells the ACL2 rewriter to expand all lambda applications ([47m[let][0m expressions). See [hints]. A new function [47m[zpf][0m has been added as a fast test against 0 for nonnegative fixnums. A new macro [47m[gc$][0m allows the user to call the garbage collector of the underlying Common Lisp. Thanks to Rob Sumners for suggesting this feature. It is now possible to [47m[monitor][0m [simple] (abbreviation) rules. However, as a warning explains, they are still not considered monitored during preprocessing; see [monitor]. Thanks to Robert Krug for providing this improvement. The second argument of [47m[certify-book][0m, if supplied, formerly had to be either [47mt[0m or a non-negative integer. Now it can be the symbol [47m?[0m, in the [47mACL2[0m package, indicating that the usual check should be suppressed on the number of commands that have been executed to create the world in which [47m[certify-book][0m was called.") (note-2-7-other (note-2-7) "ACL2 Version 2.7 Notes on Miscellaneous Changes Made several minor [documentation] improvements. We are grateful to Eric Smith for suggesting (most of) these. Improved [47m(show-bdd)[0m (see [bdd]) to give more useful feedback when there are ``leaf'' terms not known to be Boolean. Sped up processing of large mutual-recursion nests. In one large example the speedup was roughly two orders of magnitude. Modified event printing so that if both [47m'prove[0m and [47m'event[0m are inhibited, then events are no longer printed on behalf of [47m[certify-book][0m, [47m[encapsulate][0m, or [47m[defstobj][0m. Thanks to Eric Smith for prompting consideration of such a change. The following technical change was made to support [47mwith-error-trace[0m and [47mwet[0m (see [note-2-7-new-functionality]), but may be of interest to those who do low-level programming using the ACL2 logical [47m[world][0m. The [47m'unnormalized-body[0m property is now stored not only for functions defined in [47m:[0m[47m[logic][0m mode, but also for functions defined by the user in [47m:[0m[47m[program][0m mode. ([47m:Program[0m mode Functions built into ACL2 still have their [47m'unnormalized-body[0m property omitted, in order to save space.) The handling of ``invisible'' functions for purposes of controlling rewriting (see [loop-stopper]) has been moved to a new table; see [invisible-fns-table]. Macros that access and modify this table are called ``[47m...-invisible-fns-table[0m'' in place of their former names, ``[47m...-invisible-fns-alist[0m.'' This feature was formerly implemented in the [47m[ACL2-defaults-table][0m, which prevented a book from exporting lists of invisible functions intended to work with the [rewrite] rules developed in the book. Thanks to Eric Smith and Rob Sumners for suggesting this change. See [set-invisible-fns-table] (formerly [47mset-invisible-fns-alist[0m), and also see [add-invisible-fns] and see [remove-invisible-fns], which provides ways to incrementally add to and remove from this table, respectively. The handling of printing binary function call nests using macros (See [add-binop]) has also been moved out of the [47m[ACL2-defaults-table][0m as suggested by Eric and Rob, but this feature didn't work anyhow (see [note-2-7-bug-fixes]). Incidentally, the symbols [47mbinop-table[0m, [47m[add-binop][0m, and [47m[remove-binop][0m have all been added to the list [47m*acl2-exports*[0m (see [ACL2-user]), [47m[add-invisible-fns][0m and [47m[remove-invisible-fns][0m have been added to that list, and [47mset-invisible-fns-alist[0m has been replaced in that list by [47m[set-invisible-fns-table][0m. Function [47minvisible-fns-alistp[0m is no longer defined and has been removed from [47m*acl2-exports*[0m. We now enforce the stated restriction on the pairings in [47mmacro-aliases-table[0m (see [macro-aliases-table]), namely, that it associates names of macros with names of functions (with respect to the current ACL2 logical [world]). We make a similar requirement on [47m[invisible-fns-table][0m. The [47m[theory-invariant][0m event has been modified so that the default action is an error rather than a warning. Thanks to Eric Smith for suggesting this change. Also, the value returned upon successful execution of a [47m[theory-invariant][0m event is now the key. Proof output that reports destructor elimination no longer uses the word ``generalizing''. This small change may help in browsing proof output, since now ``generaliz'' takes you to true uses of generalization. Thanks to Matyas Sustik for suggesting such a change. The command [47m:[0m[47m[pl][0m now prints an abbreviated controller-alist for [47m;[0m[47m[definition][0m rules. Formerly the output from [47m:pl[0m could be overwhelming when the supplied function was part of a large [47m[mutual-recursion][0m nest. The defaults for keyword parameters of [47m[certify-book][0m have changed. See [note-2-7-bug-fixes], in particular, the discussion there of two modifications to [47mcertify-book[0m. Technical changes have been made to [47m[compress1][0m and [47m[compress2][0m that should usually be invisible to users. The next paragraph describes them in detail, only for completeness (i.e., that description can be ignored by most users). But first, here is an example showing an effect on users. The slow array warning was not there previously. Notice that the warning only arises if the event form is changed. The solution is to be sure that redundant [47m[defconst][0m forms are syntactically identical. ACL2 !>(defconst *a* (compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (1 . one) (0 . zero)))) Summary Form: ( DEFCONST *A* ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) *A* ACL2 !>(aref1 'demo *a* 0) ZERO ACL2 !>(defconst *a* (compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (1 . one) (0 . zero)))) This event is redundant. See :DOC redundant-events. Summary Form: ( DEFCONST *A* ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) :REDUNDANT ACL2 !>(aref1 'demo *a* 0) ZERO ACL2 !>(defconst *a* (compress1 'demo '((:header :dimensions (5) :maximum-length 15 :default uninitialized :name demo) (0 . zero) (1 . one)))) This event is redundant. See :DOC redundant-events. Summary Form: ( DEFCONST *A* ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) :REDUNDANT ACL2 !>(aref1 'demo *a* 0) ********************************************************** Slow Array Access! A call of AREF1 on an array named DEMO is being executed slowly. See :DOC slow-array-warning ********************************************************** ZERO ACL2 !> As before, the von Neumann structure stored in the [47m'acl2-array[0m property of the array name contains the array list object in its [47m[car][0m. However, previously it was the case that [47mcompress1[0m and [47mcompress2[0m did not update that [47mcar[0m when its new value would be equal to its old value. This was done largely in support of some type-set tables defined using [47m[defconst][0m in [47mtype-set-b.lisp[0m. The new versions of [47m[compress1][0m and [47m[compress2][0m are simpler in that no such exception is made in the case of equal lists, although instead the entire compression process is short-circuited when the input array list object is [47m[eq][0m to the [47mcar[0m of the [47m'acl2-array[0m property. This change was made because the equality test was causing a ``slow array access'' warning to be printed in rare cases during proofs, as described elsewhere (see [note-2-7-bug-fixes]). We no longer distribute documentation specific to Lucid Emacs. The Info documentation in directory [47mdoc/EMACS/[0m works well both for Gnu Emacs and XEmacs. A little-advertised macro, [47mvalue[0m, has long been allowed for top-level forms in [books]; see [embedded-event-form]. This has been replaced by a new macro, [47mvalue-triple[0m. The two have the same semantics at the top-level of books, where [47m[state][0m is ``live''. However, [47mvalue-triple[0m should be used at the top-level of a book, while [47mvalue[0m should be used in function definitions (as before). This change eliminates a warning put out by the Allegro Common Lisp compiler for top-level [47mvalue[0m forms in [books].") (note-2-7-proof-builder (note-2-7) "ACL2 Version 2.7 Notes on proof-builder Changes Output from the [proof-builder] can now be inhibited by supplying the symbol [47mproof-builder[0m in the list given to [set-inhibit-output-lst].") (note-2-7-proofs (note-2-7) "ACL2 Version 2.7 Notes on Changes in Proof Engine An improvement in the linear arithmetic heuristics has been provided by Robert Krug. For information about this change, search for the comment in [47madd-linear-lemma[0m (file [47mrewrite.lisp[0m) that begins as follows. ; Previous to Version_2.7, we just went ahead and used the result of Thanks, Robert! Also thanks to Eric Smith for providing a motivating example. The non-linear-arithmetic addition (see [non-linear-arithmetic]) led to several small changes in the linear-arithmetic decision procedure (see [linear-arithmetic]). Two of these changes could affect existing proofs. First, when we are setting up the initial arithmetic database (which we call the ``pot-lst''), we have always scanned it to see if there were any pairs of inequalities from which we could derive a previously unknown equality. In some cases we added this equality to the clause and in others we used it to rewrite the clause, substituting one side of the equality for the other throughout the clause. Previously, the heuristics that we used to determine whether we performed the substitution differed from those used in several other places in the code. This has now been regularized, and similar heuristics are now used throughout the code. The second change to the linear-arithmetic decision procedure is that we now explicitly add inequalities derived from type reasoning to the pot-lst. Previously, we performed cancellations against these inequalities without adding them to the pot-lst. This change results in there being more inequalities in the pot-lst than before, and so more chances for there to be a pair of inequalities from which an equality can be derived. In effect, certain simple consequences of the current goal (see [type-set]) may now be added as hypotheses of the goal or used to perform equality substitutions. A slight improvement has been made to the way certain rewrite rules are stored. It was already the case that a rewrite rule rule whose conclusion [47mC[0m is not a call of a known equivalence relation (or [47m[eq][0m, [47m[eql][0m, or [47m[=][0m) is stored as [47m(iff C t)[0m, except that if ACL2 can determine (using its [47m[type-set][0m mechanism) that [47mC[0m is Boolean, then the rule is stored as [47m(equal C t)[0m. The improvement is that if [47mC[0m and [47mC'[0m are Boolean, then a rule stated as [47m(iff C C')[0m is stored as [47m(equal C C')[0m. Thanks to Pete Manolios for providing an example that led us to consider this improvement. The heuristic use of equalities (fertilization) has been modified. Previously, ACL2 would sometimes substitute using an equality but keep the equality, and then undo the substitution by using the equality again. Now, when ACL2 keeps an equality after using it, it puts the equality inside a call of [47m[hide][0m. Descendants of that goal that are unchanged by simplification will have this call of [47m[hide][0m removed so that the equality can once again contribute to the proof. This change can cause some proofs to succeed that otherwise would fail. In the unlikely event that a proof fails that formerly succeeded, the following hint on "Goal" may fix the problem (see [hints]): :expand ((:free (x) (hide x))) We have refined the heuristics employed when an [47m[if][0m form is assumed true or false. Our previous attempt (see [note-2-6-proofs] for the original announcement) was not as general as we had believed. We have also improved some low-level code responsible for rewriting [47mIF[0m expressions. In earlier versions of ACL2, it was possible to have the truth or falsity of an [47mIF[0m expression explicitly recorded in the type-alist, and yet not use this information during rewriting. This problem has been corrected. Thanks to Robert Krug for noticing this problem and implementing the fix. We have sped up the rewriter in some cases where there are large collections of mutually-recursive functions (see [mutual-recursion]). (Implementation notes: technically, we have modified the way function [47mbeing-openedp[0m operates on the [47mfnstack[0m, and we have modified [47m*current-acl2-world-key-ordering*[0m as described in the essay above its definition.) [Forward-chaining] is now done in the preprocessing phase of proof attempts (see the discussion of [47m:DO-NOT[0m --- see [hints]). This is part of a technical change, made in support of translation of type declarations to [guard]s (see [note-2-7-guards]). Previously, whenever ACL2 checked for [built-in-clause]s, it then looked for a contradiction using [47m[type-set][0m reasoning if it did not find a suitable built-in clause. The change is to perform forward-chaining in such cases (i.e., when a built-in clause is not found). A couple of changes have been made in the generation of goals for [forcing-round]s. Thanks to Eric Smith for bringing issues to our attention that led to these changes. For one, [guard]s are no longer relevant in such goal generation. Formerly, the addition of a guard could make a proof fail that otherwise succeeded. Secondly, contextual information is now always kept when it involves a constrained constant, i.e., a zero-ary function introduced in the signature of an [47m[encapsulate][0m.") (note-2-7-rules (note-2-7) "ACL2 Version 2.7 Notes on Changes in Rules and Constants The [47m[defcong][0m macro has been slightly changed. The difference is that the variable generated with suffix [47m-EQUIV[0m will now be in the same package as the name of the variable from which it is generated, rather than always belonging to the ACL2 package. Thanks to Hanbing Liu for suggesting this change. (Note that a couple of books have been modified to accommodate this change, e.g., [47mbooks/finite-set-theory/set-theory[0m.) In Version_2.6, a change was made for rules of class [47m:[0m[47m[rewrite][0m whose conclusion is a term of the form [47m(EQV lhs rhs)[0m, where [47mEQV[0m is [47m[=][0m, [47m[eq][0m, or [47m[eql][0m: the rule was stored as though [47mEQV[0m were [47m[equal][0m. (See [note-2-6-rules].) This change has been extended to rules of class [47m:[0m[47m[definition][0m.") (note-2-7-system (note-2-7) "ACL2 Version 2.7 Notes on System-level Changes ACL2 now runs (once again) under LispWorks, specifically, LispWorks 4.2.0. However, we needed a patch, which presumably will be unnecessary after 4.2.7. From LispWorks support: Users with LispWorks4.2.7 should ask us at lisp-support@xanalys.com for the transform-if-node patch. It will be helpful if they quote (Lisp Support Call #11372) when doing so. Also, they must send a bug form generated from their LispWorks image: instructions at http://www.lispworks.com/support/bug-report.html. File [47mbooks/Makefile-generic[0m has been improved so that failed attempts to certify a book will cause the `make' to fail. Previously, an existing [47m.cert[0m file was left in place, and that sufficed for the `make' to be considered a success. Now, the old [47m.cert[0m file is first removed when recertification is found to be necessary. A change has been made to source file [47macl2.lisp[0m to accommodate GCL 2.4.3. (ACL2 Version 2.6 does not work with some versions of GCL 2.4.3.) The error message has been improved when certain forms are typed to raw Lisp and the ACL2 loop has never been entered (with [47m([0m[47m[lp][0m[47m)[0m). The following symbols in the ACL2 package have been made untouchable, meaning that they are not available to the user: [47mev-fncall[0m, [47mev[0m, [47mev-lst[0m, [47mev-acl2-unwind-protect[0m, [47mev-fncall![0m, and [47muser-stobj-alist-safe[0m. The reason is that these functions can not be called safely except under certain restrictions. If you want to call the ACL2 evaluator, consider using the built-in system functions [47mtrans-eval[0m or simple-translate-and-eval. CLISP Version_2.30 implements a notion of ``locking'' the "LISP" package that is incompatible with building ACL2. (CLISP Version_2.27 does not appear to have had this feature.) We have gotten around this problem by unlocking the "LISP" package in ACL2 images built on such CLISPs. Automatic proclaiming for GCL, which has (for a long time) been done for functions in compiled books, has been improved. Formerly, the only time a non-trivial output type (i.e., other than [47mt[0m) was inferred was when macroexpansion produced an explicit call of [47m[the][0m. Now, [47m[if][0m expressions can also generate non-[47mt[0m output types. Consider the following example. (defmacro the-fixnum (n) (list 'the '(signed-byte 29) n)) (defmacro 1+f (x) (list 'the-fixnum (list '1+ (list 'the-fixnum x)))) (defun foo (x) (declare (type (unsigned-byte 27) x)) (if (zp x) 0 (1+f (foo (1-f x))))) Formerly, the [47mproclaim[0m forms for [47mfoo[0m, before and after this improvement, are as shown below. (PROCLAIM '(FTYPE (FUNCTION ((UNSIGNED-BYTE 27)) T) FOO)) ;old (PROCLAIM '(FTYPE (FUNCTION ((UNSIGNED-BYTE 27)) (SIGNED-BYTE 29)) FOO)) ;new Compiler info messages sent to error stream were eliminated for CMUCL.") (|NOTE-2-7{R}| (release-notes) "ACL2 Version 2.7(r) (November, 2002) Notes In source file [47maxioms.lisp[0m, in order for proofs to succeed, ([47mmake proofs[0m), the definitions of [47m[ACL2-count][0m and [47mexplode-atom[0m have been modified slightly, and lemma [47mstandard-numberp-one[0m [modified after Version_3.4 to become [47mstandardp-one[0m] has been given [47m:rule-classes nil[0m. All [47m[skip-proofs][0m forms have been eliminated from the nonstd books, thanks to Ruben Gamboa. The directory [47mbooks/sqrt/[0m, which was intended for ACL2(r), has been moved to [47mbooks/nonstd/sqrt/[0m and added as appropriate to [47mbooks/nonstd/Makefile[0m. Please see [note-2-7] for changes to Version_2.7 of ACL2.") (note-2-8 (release-notes) "ACL2 Version 2.8 (March, 2004) Notes BRIEF SUMMARY. The Version_2.8 notes are divided into the indicated subtopics. Here we give only a brief summary of just a few of the major new features and changes that seem most likely to impact existing proofs. Not included in this brief summary, but included in the subtopics, are descriptions of many improvements (including bug fixes and new functionality) that should not get in the way of existing proof efforts. In the description below we also omit discussion of changes that will become clear by way of error messages if they affect you. In particular, please see [note-2-8-new-functionality] for discussion of a number of new features that you may find useful. Acknowledgments and elaboration, as well as other changes, can be found in the subtopics listed below. Some of the bug fixes (see [note-2-8-bug-fixes]) * Some soundness bugs were fixed. * The handling of free variables in hypotheses (see [free-variables]) of rewrite and linear rules had a bug that prevented some proofs from going through. Now that this bug has been fixed, you may find some proofs running much more slowly than before. You can use [47m[accumulated-persistence][0m and [47m[add-match-free-override][0m to remedy this situation; see [note-2-8-bug-fixes] for details. * The [default-hints] in the current logical [world] are no longer ignored by [47m[verify-guards][0m. * Forms violating guard-checking such as [47m(defconst *silly* (car 3))[0m are now allowed in [books]. Some of the new functionality (see [note-2-8-new-functionality]) * WARNING: You may find that [47mcontrol-d[0m (in emacs, [47mcontrol-c control-d[0m) can throw you completely out of Lisp where it had not formerly done so. * ACL2 now starts up inside the ACL2 loop --- that is, [47m([0m[47m[lp][0m[47m)[0m is executed automatically --- when built on CLISP or Allegro CL. This was already the case for GCL and CMUCL, and it still is not true for LispWorks. * See [note-2-8-ordinals] for a discussion of a significant change in ordinal representation, and in particular, for how to preserve existing proofs that depend on the previous ordinal representation. * Macros [47m[mbe][0m (``must be equal''), [47m[mbt][0m (``must be true''), and [47m[defexec][0m have been introduced, which allow the user to attach alternate executable definitions to functions. * The user can now control multiple matching for free variables in hypotheses for [47m:[0m[47m[forward-chaining][0m rules, as has already been supported for [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules. * It is no longer necessary to specify [47m(set-match-free-error nil)[0m in order to avoid errors when a rule with free variables in its hypotheses is missing the [47m:match-free[0m field. * The form [47m(break-on-error)[0m causes, at least for most Lisps, entry into the Lisp debugger whenever ACL2 causes an error. * A new [47m[table][0m has been provided so that advanced users can override the built-in [47muntranslate[0m functionality. See [user-defined-functions-table]. * The [47m[pstack][0m (`process [prover] stack'') mechanism, formerly denoted [47mcheckpoints[0m, has been improved. One of these improvements is to show actual parameters with [47m(pstack t)[0m rather than formals. * The [47m[defstobj][0m event is now allowed to take an [47m:inline[0m argument, which can speed up execution. * Macro [47m[cw-gstack][0m no longer takes arguments for the [47mgstack[0m or [47m[state][0m. To print terms in full rather than abbreviated: [47m(cw-gstack :evisc-tuple nil)[0m. * The [47m[include-book][0m event now has an additional (optional) keyword, [47m:dir[0m. In particular, [47m(include-book "foo/bar" :dir :system)[0m will include the indicated book after prepending the path of the built-in [47mbooks/[0m directory. You will probably not find [47m:dir :system[0m to be useful if you move the executable image or distributed books; see [include-book], in particular its ``soundness warning''. * The printing of results in raw mode (see [set-raw-mode]) may now be partially controlled by the user: see [47madd-raw-arity[0m. [Note added 2021: this utility has been removed and is no longer necessary.] * For those using Unix/Linux `make': A [47mcert.acl2[0m file can contain forms to be evaluated before an appropriate [47m[certify-book][0m command is invoked automatically (not included in [47mcert.acl2[0m). Some of the changes in the proof engine (see [note-2-8-proofs]) * ACL2 now prevents certain rewriting loops; see [rewrite-stack-limit]. * Small changes have been made to heuristics for controlling rewriting during proofs by induction and in handling certain ``weak'' [compound-recognizer] rules. * The handling of free variables in a hypothesis of a [rewrite] rule (see [free-variables]) has been improved in the case that the hypothesis is of the form [47m(equiv x y)[0m, where [47mequiv[0m is a known equivalence relation (see [equivalence]). * We have modified how the ACL2 simplifier handles the application of a defined function symbol to constant arguments, by avoiding the introduction of [hide] when evaluation fails if the term can be rewritten. * The generation of "Goal" for recursive (and mutually-recursive) definitions now uses the subsumption/replacement limitation (default 500). See [case-split-limitations]. * Default hints now apply to hints given in definitions, not just theorems. See [default-hints]. * Linear arithmetic now uses the conclusions of [47m[forward-chaining][0m rules, and [47m[type-set][0m now uses a small amount of linear reasoning when deciding inequalities. Some of the changes in rules, definitions, and constants (see [note-2-8-rules]) * See the above doc topic. Guard-related changes are described in see [note-2-8-bug-fixes] Some of the proof-builder changes (see [note-2-8-proof-builder]) * Added new [proof-builder] commands [47mwrap1[0m, [47mwrap[0m, and [47mwrap-induct[0m, to combine multiple conjuncts or goals. * The [47mtype-alist[0m command now takes optional arguments that control whether or not the governors and/or conclusion are used in computing the context. Some of the system-level changes (see [note-2-8-system]) * ACL2 now runs on OpenMCL and on MCL 5.0. Some of the other changes (see [note-2-8-other]) * Emacs file [47memacs/emacs-acl2.el[0m has been updated (see [note-2-8-other] for details). * When [47m:pl[0m is given a term other than a symbol, it will print all rewrite rules that match that term. * A new function, [47m[pkg-witness][0m, returns a symbol in the given package. * The list constant [47m*acl2-exports*[0m has been extended. * A new release of the rtl library has been included: [47mbooks/rtl/rel4/[0m. See the [47mREADME[0m file in that directory. Again, please proceed to the subtopics for more thorough release notes. Subtopics [Note-2-8-bug-fixes] ACL2 Version 2.8 Notes on Bug Fixes [Note-2-8-guards] ACL2 Version 2.8 Notes on Guard-related Changes [Note-2-8-new-functionality] ACL2 Version 2.8 Notes on New Functionality [Note-2-8-ordinals] ACL2 Version 2.8 Notes on Changes to the Ordinals [Note-2-8-other] ACL2 Version 2.8 Notes on Miscellaneous Changes [Note-2-8-proof-builder] ACL2 Version 2.8 Notes on proof-builder Changes [Note-2-8-proofs] ACL2 Version 2.8 Notes on Changes in Proof Engine [Note-2-8-rules] ACL2 Version 2.8 Notes on Changes in Rules, Definitions, and Constants [Note-2-8-system] ACL2 Version 2.8 Notes on System-level Changes") (note-2-8-bug-fixes (note-2-8) "ACL2 Version 2.8 Notes on Bug Fixes We have fixed a soundness bug in the tautology checker's handling of expressions of the form [47m(not (not x))[0m. This bug has gone back at least as far as Version_2.4. All of the regression tests passed after the fix, without modification. So we hope that this bug has rarely bitten anyone. Thanks to Qiang Zhang for sending us a proof of [47mnil[0m that led us to this fix: [47m(thm (equal (and p q) (not (or (not p) (not q)))))[0m. And thanks to Matyas Sustik for an observation that led to an improvement of our initial fix. The preceding version (2.7) introduced a soundness bug in handling of ACL2 [arrays], in which functions [47m[compress1][0m and [47m[compress2][0m were returning the input alist rather than compressing it appropriately. Here is a proof of [47mnil[0m that no longer succeeds, based on a bug report from Warren Hunt, whom we thank for bringing this problem to our attention. (defthm bad (not (let* ((ar2 (aset1 'my-array ar1 3 10)) (ar3 (compress1 'my-array ar2)) (ar4 (reverse (reverse ar2))) (ar5 (compress1 'my-array ar4))) (and (equal ar2 ar4) (not (equal ar3 ar5))))) :rule-classes nil) (defthm contradiction nil :rule-classes nil :hints (("Goal" :use ((:instance bad (ar1 (compress1 'my-array '((3 . 5) (:HEADER :DIMENSIONS (5) :MAXIMUM-LENGTH 6 :DEFAULT 0 :NAME MY-ARRAY))))))))) On a related note, a new function [47m[flush-compress][0m can be used for subtle control of under-the-hood raw Lisp support for fast array access, although we expect it to be very rare that users need this extra support. Previous versions have had two soundness bugs that can occur when using the [proof-builder]: * The first bug pertains to the [47mexpand[0m command, and hence [47mx[0m and [47mx-dumb[0m commands (which call [47mexpand[0m); see [proof-builder-commands]. The bug can occur when applying the above commands when the current term is a call of a constrained function symbol for which there is a [47m:[0m[47m[definition][0m rule. Now, the [47mexpand[0m command will succeed only when the function symbol of the current term is a defined function symbol, in which case the original definition is always used, in analogy to how the [47m:expand[0m hint works in the prover; see [hints]. Thanks to John Erickson for sending an example that led us to wonder if there might be a soundness problem. * The second bug pertains to the [47ms[0m command (and commands that call it, e.g., [47ms-prop[0m). The proof-builder forms a context out of the top-level hypotheses and the [47mif[0m-terms governing the current term. If there is a contradiction in the top-level hypotheses, the proof-builder can appropriately consider the goal to be proved, and it does so. But formerly, the criterion was weaker: the contradiction could involve the combination of the top-level hypotheses and [47mif[0m-term governors. Thanks to Rob Sumners for noticing this bug. A soundness bug could be provoked in some Lisps by applying [47m[defpkg][0m to the empty string. This has been disallowed. We fixed a soundness bug related to packages caused by a failure to track axioms introduced [47m[local][0mly on behalf of [47m[defpkg][0m events. See [hidden-death-package]. We fixed a soundness bug caused by a failure to check that a [47m:[0m[47m[type-prescription][0m rule can be processed when proofs are skipped or under a [47m[defequiv][0m event. The former case can occur when processing an [47m[encapsulate][0m or [47m[include-book][0m event, where the rule could depend on a [47m[local][0m [47m:[0m[47m[compound-recognizer][0m rule preceding the proposed [47m:[0m[47m[type-prescription][0m rule under the same [47m[encapsulate][0m or [47m[include-book][0m event. See [local-incompatibility] for such an example. We fixed a potential soundness bug relating to reclassifying a [47m:program[0m mode function to [47m:logic[0m mode (as done by [47m[verify-termination][0m or the submission of an appropriate ``redundant'' definition) without adequate checking that [47m[stobj][0m usage was identical. Allegedly redundant definitions must now preserve the [47mstobjs[0m declaration as well as the formals, body, guard and type declarations. We thank Vernon Austel for pointing out this problem. It was possible to get a raw Lisp error by introducing a [47m[local][0mly defined function with [guard] verification inhibited and then subsequently introducing the same definition non-locally without that inhibition. The following example will clarify. (encapsulate nil (local (defun foo (x) (declare (xargs :guard t :verify-guards nil)) (car x))) (defun foo (x) (declare (xargs :guard t)) (car x))) ; The following causes a raw lisp error because ACL2 runs the Common Lisp ; definition of foo, because it thinks that foo's guard of t was verified. (thm (equal (foo 3) xxx)) Thanks to Jared Davis for bringing this problem to our attention. We are particularly grateful to Jared because his example exploited this bug by applying it to a function defined using [47m[mbe][0m (introduced in this same version, 2.8), in order to prove [47mnil[0m! The sort of error message shown below can legitimately occur when certifying a book in a certification world where there was an [47m[include-book][0m command with a relative pathname (see [pathname]). However, it was occurring more often than necessary. This has been fixed. ACL2 Error in (CERTIFY-BOOK "foo" ...): The certification world has include-book commands for book "bar" that correspond to different full pathnames, namely "/u/dir1/bar" and "/u/dir2/bar". ACL2 cannot currently certify a book in such a world. To work around this problem, use an absolute pathname for at least one of these books (see :DOC pathname). Bugs were fixed in [47m[with-output][0m, in particular related to the use of values [47m:all[0m. Also, documentation for [47mwith-output[0m has been improved. Thanks to Vernon Austel for pointing out the bugs. Fixed a lisp error occurring when [47mbash[0m proof-builder command was given illegal syntax, e.g., [47m(bash (("Goal" :in-theory (enable binary-append))))[0m instead of [47m(bash ("Goal" :in-theory (enable binary-append)))[0m. We added an appropriate guard to [47m[find-rules-of-rune][0m, which will avoid hard lisp errors when this function is called on non-[rune] arguments. Thanks to Eric Smith for pointing out this issue. It was possible for a redundant [47m[include-book][0m form (see [redundant-events]) to leave a [command] in the ACL2 logical [world] and to cause (re-)loading of a compiled file. These behaviors have been fixed. In particular, if [47mbook1[0m has already been included in the current ACL2 [world] and [47m(include-book "book1")[0m occurs in [47mbook2[0m, then the compiled file for [47mbook1[0m will not be loaded again when [47mbook2[0m is included. Thanks to Dave Greve for bringing our attention to these problems, and to Eric Smith for bringing up a special case earlier (where "//" occurred in the book-name). The summary printed at the end of a proof had not listed [47m:[0m[47m[induction][0m rules used in a proof. This has been corrected. The use of proof trees in emacs redefined `[47mcontrol-c control-c[0m' in such a way that in telnet mode, the telnet session was interrupted and perhaps could not be continued. This has been fixed. Source function [47mload-theory-into-enabled-structure[0m contained a guard-violating call of [47m[compress1][0m. Thanks to Vernon Austel for bringing this problem to our attention; even though this bug was benign (as he pointed out), we like keeping the source code free of guard violations. A number of proof-builder atomic macros caused a hard error when all goals have already been proved. This has been fixed. Thanks to John Erickson for sending an example of the issue. A bug has been fixed in [47m[add-match-free-override][0m. Formerly, a [47m[table][0m [guard] violation occurred when calling [47m[add-match-free-override][0m more than once with first argument other than [47m:clear[0m. Definitions of functions involving large constants could cause stack overflows. This has been fixed, at least in some of the most egregious cases (by making a source function [47mfn-count-evg[0m tail-recursive). Thanks to Jared Davis for bringing this problem to our attention. Evaluation of computed hints could cause stack overflows. This has been fixed. Thanks to Eric Smith for bringing this problem to our attention. Evaluation of [47m:[0m[47m[monitor][0m on [47m:[0m[47m[definition][0m [rune]s is now fast even if the specified function is part of a very large [47m[mutual-recursion][0m nest. Thanks to Eric Smith for sending an example showing that this wasn't always the case. Fixed a bug in [47mbooks/bdd/cbf.lisp[0m that was causing certification of distributed bdd books to fail when the connected book directory (see [cbd]) differs from the current working directory. Thanks to Scott Guthery for bringing this bug to our attention and supplying a helpful log. Duplicate rule names have been eliminated from warnings generated upon the use of enabled [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m rules. Thanks to Eric Smith for pointing out this problem. The trace utilities (see [trace]), as modified for GCL and Allegro Common Lisp, had failed to show more than the first return value for so-called ``[47m*1*[0m'' functions (essentially, [executable-counterpart] functions) when they were returning multiple values (via [mv]). This has been fixed. Thanks to Erik Reeber for pointing out this problem. Also, it is now possible to refer to [47marglist[0m in [trace$] forms when ACL2 is built on GCL, not just when ACL2 is built on Allegro Common Lisp. Uses of [47m[hide][0m introduced during proofs by failed attempts to evaluate constrained functions (see [hide]) are now tracked, so that the [rune] [47m(:DEFINITION HIDE)[0m will show up in the summary. The following bug, introduced back in Version 2.7, has been fixed. The bug applied only to GCL and may well not have affected anyone. But the function proclamation computed by ACL2 for compilation usually had an output type of [47mnil[0m where it should have been [47mt[0m. The macro [47m[gc$][0m had a bug exhibited when it was supplied one or more arguments. This has been fixed. The macro [47m[defabbrev][0m broke when supplied a string and no documentation, e.g., [47m(defabbrev foo () "")[0m. Thanks to Rob Sumners for noticing this problem and providing a fix, which we have incorporated. For ACL2 executables built on Allegro Common Lisp, a Lisp error occurred when [47m[trace$][0m was called on other than a defined function symbol. Now ACL2 prints a more useful error message. The proof-builder no longer accepts a [47m([0m[47m[verify][0m[47m)[0m command when some function symbol in the original goal no longer exists in the current ACL2 logical [world]. Thanks to John Erickson for bringing this issue to our attention. The function [47mld-redefinition-action[0m may now be called by the user. Thanks to Vernon Austel for suggesting that we remove this symbol from the list of so-called untouchables. The handling of free variables in hypotheses (see [free-variables]) of rewrite and linear rules had a bug that prevented some proofs from going through. Here is a simple example, essentially provided by Diana Moisuc, who we thank for bringing this issue to our attention. The proof of the [47m[thm][0m below had failed, but now will succeed. This particular bug prevented, for example, the [47m:all[0m behavior from occurring when the first hypothesis of the rule does not have free variables. NOTE: Now that this bug has been fixed, you may find some proofs running much more slowly than before. You can use [47m[accumulated-persistence][0m to locate rules that are slowing down your proofs because of excessive attention to free variables, and then execute [47m[add-match-free-override][0m for those rules (or, just change the rules themselves to specify [47m:once[0m in the [47m:[0m[47m[rule-classes][0m). (defstub foo1 (* ) => *) (skip-proofs (defthm aux-foo1 (implies (and (integerp a) (integerp i) (equal (foo1 0) (list 0 i))) (equal (foo1 a) (list 0 (+ a i)))) :rule-classes ((:rewrite :match-free :all)))) (thm (implies (and (integerp i) (integerp a) (equal (foo1 0) (list 0 i))) (equal (foo1 a) (list 0 (+ a i))))) Formerly, creation of large arrays could cause an error in the underlying Common Lisp implementation without helpful messages for the user. Now, we check Common Lisp restrictions on arrays and print a helpful error message if they are violated, namely: each dimension must be less than the value of Common Lisp constant [47marray-dimension-limit[0m, and the product of the dimensions must be less than the value of Common Lisp constant [47marray-total-size-limit[0m. Thanks to Warren Hunt for bringing this issue to our attention. Note: this change also removes a former restriction of [47m[stobj][0m array fields to size smaller than 2^28-1, provided the underlying Lisp can support larger arrays. The [default-hints] in the current logical [world] were ignored by [47m[verify-guards][0m. This has been fixed. Thanks to Jared Davis for pointing out this bug and sending a helpful example. The [47m[brr][0m mechanism has been cleaned up in order to avoid hard errors and infinite loops that can arrive when typing interrupts ([47mcontrol-c[0m) or end-of-files ([47mcontrol-d[0m) inside the [47m[brr][0m loop. Thanks to Dave Greve, Olga Matlin, Eric Smith, and Serita Van Groningen for bringing this issue to our attention. As a byproduct, if you type [47mcontrol-d[0m (or if inside emacs, [47mcontrol-c control-d[0m), you may now quit entirely out of ACL2 and lisp (see [good-bye]) in some cases where you formerly would not have, for example when sitting at the ACL2 prompt (which formerly, in Allegro Common Lisp for example, would merely take you into raw Lisp rather than quitting everything). We have eliminated structural flaws in the HTML documentation pages that could make them unreadable in some browsers. Thanks to Bill Young for bringing this issue to our attention and to Joe Hendrix for diagnosing the problem. The [proof-builder] could run very slowly after many instructions in a given session. This has been fixed; thanks to Art Flatau for bringing this problem to our attention. (Implementation detail: We now keep tag-trees duplicate-free when we accumulate them into state. This change could have minor speed advantages for some top-level proofs too, not just in the proof-builder.) The printing of accesses to stobjs using nth or update-nth has been done using symbolic constants since ACL2 Version_2.6. However, there was a bug that prevented this feature from working for [47m[update-nth][0m except at a top-level call. This has been fixed. Thanks to Julien Schmaltz for bringing this problem to our attention. For example, consider these events: (defstobj st field0 field1) (thm (equal (nth 1 (update-nth 0 17 st)) (car (cons xxx yyy))) :hints (("Goal" :in-theory (disable nth update-nth)))) Before the fix, the proof attempt of the above silly thm printed the following. (NTH 1 (UPDATE-NTH *FIELD0* 17 ST)) After the fix, we instead see the following. (NTH *FIELD1* (UPDATE-NTH *FIELD0* 17 ST)) It is now possible to certify and subsequently include [books] that require guard-checking to be off. For example, the book can contain the form [47m(defconst *silly* (car 3))[0m even though [47m3[0m fails to satisfy the guard of [47m[car][0m. Formerly, it was necessary to execute [47m:[0m[47m[set-guard-checking][0m[47m nil[0m before a [47m[certify-book][0m or [47m[include-book][0m in order for such a form to be handled without error. Thanks to Hanbing Liu for bringing this problem to our attention. Fixed a [proof-builder] bug that could probably cause a strange error, ``Attempt to access the plist field''. Thanks to Bill Young for bringing this problem to our attention. Fixed a [proof-builder] bug that was failing to record applications of rewrite rules using the proof-builder's [47m:rewrite[0m command, causing the proof summary to omit mention of that rule (for example, when using the proof-builder's [47m:exit[0m command to generate an [47m:instructions[0m hint). Thanks to Bill Young for pointing out this bug. Modernized some of the proof-tree emacs and infix printing stuff, thanks to suggestions made by Camm Maguire.") (note-2-8-guards (note-2-8) "ACL2 Version 2.8 Notes on Guard-related Changes All the guard-related changes may be found elsewhere; in particular, see [note-2-8-bug-fixes].") (note-2-8-new-functionality (note-2-8) "ACL2 Version 2.8 Notes on New Functionality WARNING: You may find that [47mcontrol-d[0m (in emacs, [47mcontrol-c control-d[0m) can throw you completely out of Lisp where it had not formerly done so. (CLISP and Allegro CL only) ACL2 now starts up inside the ACL2 loop --- that is, [47m([0m[47m[lp][0m[47m)[0m is executed automatically --- when built on CLISP or Allegro CL. This was already the case for GCL and CMUCL, and it still is not true for LispWorks. Thanks to Joe Corneli for bringing the CLISP command-line option [47m"-i"[0m to our attention, which led to this CLISP change and inspired reconsideration of how to do this for Allegro CL. Pete Manolios and Daron Vroon have changed the representation of ordinals in ACL2, defined algorithms for ordinal arithmetic, and created a library of theorems to reason about ordinal arithmetic. We thank them for these nice contributions. See [note-2-8-ordinals] for details, in particular, for how to preserve existing proofs that depend on the previous ordinal representation. Sometimes users create rules of class [47m:[0m[47m[rewrite][0m that cause an infinite loop in the ACL2 rewriter. This has lead to Lisp stack overflows and even segmentation faults. Now, the depth of calls of functions in the ACL2 rewriter is limited, and under user control. See [rewrite-stack-limit]. Macros [47m[mbe][0m (``must be equal'') and [47m[mbt][0m (``must be true'') have been introduced, which allow the user to attach fast executable definitions to (presumably slower) [47m:[0m[47m[logic][0m mode functions. Thanks to Vernon Austel for a key idea. Also provided is a macro [47m[defexec][0m, which employs [47m[mbe][0m but enforces the requirement that the executable definition also terminates. Thanks to Jose Luis Ruiz Reina for collaborating in the design and development of [47m[defexec][0m, and for useful comments from a number of others as well in the development of [47mmbe[0m including Joe Hendrix and Rob Sumners. Definitions have been added for functions [47m[rassoc-eq][0m and [47m[rassoc-equal][0m, which are like [47m[rassoc][0m but use different tests and have different guards. (Compare [47m[assoc-eq][0m and [47m[assoc-equal][0m, which are in similar relation to [47m[assoc][0m.) The user can now control multiple matching for free variables in hypotheses for [47m:[0m[47m[forward-chaining][0m rules, as has already been supported for [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules. For [47m:forward-chaining[0m rules, ``free variables'' are those in the hypotheses not bound by a given trigger term. As for [47m:rewrite[0m and [47m:linear[0m rules, free-variable matching may be limited to the first successful attempt by specifying [47m:match-free :once[0m with [47m:forward-chaining[0m in the [47m:[0m[47m[rule-classes][0m, and [47m[add-match-free-override][0m may be used to modify the behavior of an existing rule. Thanks to Erik Reeber for most of the implementation of these new capabilities, as well as significant assistance with a corresponding new documentation topic (see [free-variables-examples-forward-chaining]). It is no longer necessary to specify [47m(set-match-free-error nil)[0m in order to avoid errors when a rule with free variables in its hypotheses is missing the [47m:match-free[0m field. (This was already true during book certification, but now it is the case in interactive sessions as well.) The form [47m(break-on-error)[0m causes, at least for most Lisps, entry into the Lisp debugger whenever ACL2 causes an error. See [break-on-error]. Thanks to John Erickson for providing encouragement to provide this feature. A new [47m[table][0m has been provided so that advanced users can override the built-in [47muntranslate[0m functionality. See [user-defined-functions-table]. The [47m[pstack][0m mechanism (formerly denoted [47mcheckpoints[0m) has been improved. The ``process [prover] stack,'' or pstack, is automatically printed when proofs abort. Evaluation of function calls on explicit arguments during proofs is now tracked. Actual parameters are shown with [47m(pstack t)[0m rather than formals. Thanks to Bill Legato for suggesting the first two of these improvements and, in general, encouraging changes that make ACL2 easier to use. The [47m[defstobj][0m event is now allowed to take an [47m:inline[0m argument, which can speed up execution. Thanks to Rob Sumners for suggesting and implementing this new feature. Macro [47m[assert$][0m has been added in order to make it easy to write assertions in one's code. Semantically, [47m(assert$ test form)[0m is the same as [47mform[0m, but it causes a hard error (using [47m[illegal][0m) if [47mtest[0m evaluates to [47mnil[0m. Macro [47m[cw-gstack][0m no longer takes arguments for the gstack or [47m[state][0m. However, it now takes a keyword argument (which is optional), [47m:evisc-tuple[0m, that can be used to control how it prints terms. In particular, [47mcw-gstack[0m abbreviates large terms by default, but [47m(cw-gstack :evisc-tuple nil)[0m causes terms to be printed in full. Thanks to Robert Krug and Eric Smith for requesting this improvement. The advanced user now has more control over the evisceration of terms. See [ld-evisc-tuple], in particular the new paragraph on ``The printing of error messages and warnings.'' The [47m[include-book][0m event now has an additional (optional) keyword, [47m:dir[0m. The value of [47m:dir[0m should be a keyword that is associated with an absolute directory pathname to be used in place of the current book directory (see [cbd]) for resolving the first argument of [47minclude-book[0m to an absolute pathname. At start-up, the only such keyword is [47m:system[0m, so that for example [47m(include-book "arithmetic/top" :dir :system)[0m will include the book [47m"arithmetic/top"[0m under the [47m"books/"[0m directory of your ACL2 installation. But you can associate ``projects'' with keywords using [47m[add-include-book-dir][0m, e.g., [47m(add-include-book-dir :my-project "/u/smith/project0/")[0m. See [add-include-book-dir] and also see [delete-include-book-dir] and see [include-book]. Note: You will probably not find [47m:dir :system[0m to be useful if the distributed books are not placed in the path of their original location, pointed to by [47m:dir :system[0m, which will often happen if the executable image is obtained from another site. Also see [include-book], in particular its ``soundness warning''. The printing of results in raw mode (see [set-raw-mode]) may now be partially controlled by the user: see [47madd-raw-arity[0m. [Note added 2021: this utility has been removed and is no longer necessary.] Also, newlines are printed when necessary before the value is printed. For those using Unix/Linux `make': A [47mcert.acl2[0m file can contain forms to be evaluated before an appropriate [47m[certify-book][0m command is invoked automatically (not included in [47mcert.acl2[0m). Jared Davis has contributed a new set of books for ordered finite set theory to the standard distribution, [47mbooks/finite-set-theory/osets-0.81/[0m. See the [47mREADME[0m file in that directory. Thanks, Jared. Robert Krug has contributed two related changes (thanks, Robert!) in support of stronger arithmetic reasoning. First, one can now enable and disable nonlinear arithmetic with a [47m:nonlinearp[0m hint, which will override the default provided by [47m[set-non-linearp][0m (initially, [47mnil[0m). See [hints]. Second, [computed-hints] can now have access to the [47mHISTORY[0m, [47mPSPV[0m, and [47mCTX[0m variables of the waterfall, which (for example) allows the writing of a hint which will enable nonlinear arithmetic on precisely those goals that are [47mstable-under-simplificationp[0m. See [computed-hints]. Robert Krug has contributed a new set of arithmetic books to the standard distribution, [47mbooks/arithmetic-3/[0m. See the [47mREADME[0m file in that directory. Thanks, Robert.") (note-2-8-ordinals (note-2-8) "ACL2 Version 2.8 Notes on Changes to the Ordinals Please see [ordinals].") (note-2-8-other (note-2-8) "ACL2 Version 2.8 Notes on Miscellaneous Changes Execution of [47m[table][0m events has been sped up in many cases by avoiding excessive consing. ACL2 now warns if [47m:[0m[47m[rewrite][0m (or [47m:[0m[47m[definition][0m) rules contain free variables on the right-hand side. Thanks to Dave Greve for raising this issue. Emacs file [47memacs/emacs-acl2.el[0m has been updated to better comprehend the notion of the ``ACL2 shell'', which is the buffer to which ACL2 forms are written by commands defined in the above file. Thus, command [47mcontrol-t e[0m has been modified always to write to the ACL2 shell (which is [47m"*shell*"[0m by default), and the following new commands have been defined. o control-t c Set the ACL2 shell to the current buffer. o control-t b Change to the ACL2 shell. The commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pr][0m may now be given a macro name that corresponds via the [47mmacro-aliases-table[0m to a function name, so that for example [47m:pl append[0m is treated the same as [47m:pl binary-append[0m. A more interesting improvement, for [47m:pl[0m only, is that [47m:pl[0m may now take any term. When [47m:pl[0m is given a term other than a symbol, it will print all rewrite rules that match that term. Thanks to David Russinoff, Robert Krug, and Bill Legato for getting this going. A new function, [47m[pkg-witness][0m, returns a symbol in the given package. The installation instructions have been updated, for example to give more guidance on obtaining Lisp implementations and to mention the acl2-help mailing list. Jared Davis has suggested some symbols to be added to [47m*acl2-exports*[0m, and we have done so. Thanks, Jared. o [47mMFC[0m (used in [47m[syntaxp][0m and [47m[extended-metafunctions][0m; thanks also to Robert Krug for this one) o [47mID[0m, [47mCLAUSE[0m, [47mWORLD[0m, and [47mSTABLE-UNDER-SIMPLIFICATIONP[0m (used in [47m[computed-hints][0m) o [47m[set-default-hints][0m The command [47m:[0m[47m[pe][0m has been improved so that when the event is inside an included book, the path of included books (from the top-level book down to the one containing the event) is shown. Thanks to Eric Smith (perhaps among others) for pointing out the utility of this improvement. A new release of the rtl library has been included: [47mbooks/rtl/rel4/[0m. See the [47mREADME[0m file in that directory.") (note-2-8-proof-builder (note-2-8) "ACL2 Version 2.8 Notes on proof-builder Changes Added new [proof-builder] commands [47mwrap1[0m, [47mwrap[0m, and [47mwrap-induct[0m. [47mWrap[0m replaces multiple goals by their conjunction: [47m(wrap instr1 instr2 ...)[0m employs [47mwrap1[0m so that the indicated instructions create only at most one new goal. [47mWrap-induct[0m is a simple example of the use of [47mwrap[0m, so that induction creates only one goal (the conjunction of the base and induction steps). [47mWrap1[0m can be used immediately after a prover call ([47mbash[0m, [47mprove[0m, [47mreduce[0m, [47mbdd[0m, or [47minduct[0m) to collapse the new goals into one. See [proof-builder-commands]. The [proof-builder] command [47m=[0m failed to work as expected when a governing [47mIF[0m-test of the current term is T. This has been fixed (by fixing source function [47mconjuncts-of[0m). Thanks to Yoann Padioleau for bringing this problem to our attention. The [47mtype-alist[0m command now takes optional arguments that control whether or not the governors and/or conclusion are used in computing the context that is printed (see [proof-builder-commands], specifically subtopic [47mtype-alist[0m). Thanks to Rob Sumners for suggesting this improvement. The macro [47m[toggle-pc-macro][0m has always taken an optional second argument of [47matomic-macro[0m or [47mmacro[0m. However, this was not clearly documented, and those two symbols had to be in the [47mACL2[0m package. Both of these problems have been remedied. Thanks to John Erickson for bringing the lack of documentation of the second argument to our attention.") (note-2-8-proofs (note-2-8) "ACL2 Version 2.8 Notes on Changes in Proof Engine ACL2 now prevents certain rewriting loops; see [rewrite-stack-limit]. During the computation of [47m[constraint][0ms for functional instantiation, [47m(prog2$ term1 term2)[0m and [47m(the type term2)[0m are now treated as [47mterm2[0m. A change has been made in heuristics for controlling rewriting during proofs by induction. Formerly, during induction proofs, ACL2 suppressed rewriting of certain ``induction hypothesis'' terms, and forced expansion of certain ``induction conclusion'' terms, until rewriting had stabilized. This meddling with the rewriter is still turned off when rewriting has stabilized, but it is now turned off earlier once an ancestor has been through the rewriter and the current goal is free of ``induction conclusion'' terms. Thanks to Dave Greve and Matt Wilding for providing an example and associated analysis that led us to look for a heuristic modification. A change has been made in the heuristics for handling certain ``weak'' [compound-recognizer] rules when building contexts. Those who want to dig deeply into this change are welcome to look at the code following the call of [47mmost-recent-enabled-recog-tuple[0m in the code for function [47massume-true-false[0m in the ACL2 sources. The handling of free variables in a hypothesis of a [rewrite] rule (see [free-variables]) has been improved in the case that the hypothesis is of the form [47m(equiv x y)[0m, where [47mequiv[0m is a known equivalence relation (see [equivalence]). Previously, if the rewriter was attempting to rewrite the hypothesis [47m(equiv x y)[0m of a rewrite rule, in a context where [47mx'[0m is an instance of [47mx[0m, then the rewriter could fail to notice a term [47m(equiv x' y')[0m true in the current context where [47my'[0m is an instance of [47my[0m, in the case that [47mx'[0m precedes [47my'[0m in the [47m[term-order][0m. This has been remedied. This improvement applies regardless of whether [47mx[0m, [47my[0m, or (we believe) both are already fully instantiated in the present context. Thanks to Joe Hendrix for bringing up an example and to Vernon Austel for providing another, simple example. A very minor change has been made to the rewriter in the case that an equality appears on the left-hand side of a [47m:[0m[47m[rewrite][0m rule. Formerly, when such an equality [47m(equal x y)[0m was commuted to [47m(equal y x)[0m in order for the rule to match the current term, then all equalities on the instantiated right-hand side of the rule were commuted, except for those occurring inside another equality. The instantiated right-hand side is no longer modified. It seems very unlikely that this change will cause proofs to fail, though we cannot completely rule out that possibility. We have modified how the ACL2 simplifier handles the application of a defined function symbol to constant arguments in certain cases, which we now describe. As before, ACL2 attempts to simplify such a function application by evaluation, provided the [47m:[0m[47m[executable-counterpart][0m of the function is enabled. And as before, if that evaluation fails due to a subroutine call of a constrained function (introduced by [47m[encapsulate][0m), ACL2 may wrap a call of [47mhide[0m around this function application. (See [hide].) But now, ACL2 attempts to apply definitions and rewrite rules in the case that this evaluation fails, and only if the resulting term is unchanged does ACL2 wrap [47m[hide][0m around this function application. Thanks to Matt Wilding for bringing up the idea of this modification. The generation of "Goal" for recursive (and mutually-recursive) definitions now uses the subsumption/replacement limitation (default 500). See [case-split-limitations]. Default hints now apply to hints given in definitions, not just theorems. See [default-hints]. Thanks to Robert Krug for implementing the following two improvements involving linear arithmetic reasoning: linear arithmetic now uses the conclusions of [47m[forward-chaining][0m rules, and [47m[type-set][0m now uses a small amount of linear reasoning when deciding inequalities.") (note-2-8-rules (note-2-8) "ACL2 Version 2.8 Notes on Changes in Rules, Definitions, and Constants The [theory] [47m[minimal-theory][0m has been changed by adding the [definition] [rune] for [47m[mv-nth][0m to the theory. A corresponding change has been made to the theory warning mechanism, which was failing to warn if the definition of [47mmv-nth[0m is disabled, even though calls of [47mmv-nth[0m can be expanded by special-purpose code in the rewriter. Thanks to Serita Van Groningen for pointing out this problem with the theory warning mechanism. The [47m[defevaluator][0m event has been modified so that in the body of the evaluator function, to add a new case [47m(ATOM X)[0m (returning [47mnil[0m) has been inserted immediately after the case [47m(EQ (CAR X) 'QUOTE)[0m. This is a no-op semantically but may speed up proofs. Thanks to Warren Hunt for suggesting this change. A new form of [47m:[0m[47m[compound-recognizer][0m rule is now allowed: (if (fn x) concl1 concl2) This is equivalent to an existing form: (and (implies (fn x) concl1) (implies (not (fn x)) concl2)) Thanks to Josh Purinton for bringing this to our attention. Rewrite rules [47mrealpart-+[0m and [47mimagpart-+[0m have been added in order to simplify the [47m[realpart][0m and [47m[imagpart][0m (respectively) of a sum. They follow from a theorem [47madd-def-complex[0m that equates a sum with the complex number formed by adding real and imaginary parts. All three of these theorems may be found in source file [47maxioms.lisp[0m. Thanks to Eric Smith for raising a question leading to these additions, as well as to Joe Hendrix and Vernon Austel for helpful suggestions.") (note-2-8-system (note-2-8) "ACL2 Version 2.8 Notes on System-level Changes ACL2 now runs on OpenMCL, ``an opensourced Common Lisp implementation, derived from Digitool's Macintosh Common Lisp product.'' Thanks to Greg Wright and Robert Krug for doing most of the work for this port. When [47m([0m[47m[lp][0m[47m)[0m is first executed, the underlying raw Lisp package will change to [47m"ACL2"[0m (if that is not already the current package in raw Lisp). This is a minor change that will probably not be noticed, since up to now it has probably been the case that the ACL2 executable starts up with [47m"ACL2"[0m as the underlying raw Lisp package. But this change was made because we have been informed that ACL2 executables based on OpenMCL need not start up with [47m"ACL2"[0m as the underlying raw Lisp package. ACL2 now runs on MCL 5.0. Thanks to Pascal Costanza for updates to the instructions in file [47mmcl-acl2-startup.lisp[0m and for an update to the ACL2 sources (parameter [47m*compiled-file-extension*[0m).") (|NOTE-2-8{R}| (release-notes) "ACL2 Version 2.8(r) (March, 2003) Notes The [47mMakefile[0m has been modified by adding a new target, [47mclean-links[0m. This can be used in order to remove all soft links, which is useful if the directory is copied or moved to a new location or if there are file system changes that cause problems with link pathnames. Please also see [note-2-8] for changes to Version_2.8 of ACL2.") (note-2-9 (release-notes) "ACL2 Version 2.9 (October, 2004) Notes Table of Contents * BUG FIXES * NEW FUNCTIONALITY * CHANGES IN PROOF ENGINE * GUARD-RELATED CHANGES * PROOF-BUILDER CHANGES * SYSTEM-LEVEL CHANGES * BOOK CHANGES * MISCELLANEOUS CHANGES [31;1mBUG FIXES.[0m We fixed a soundness bug due to a conflict between user-supplied package names and internal package names (obtained by prepending a Lisp constant, [47m*1*-package-prefix*[0m) and user-supplied package names. For example, the form [47m(defpkg "ACL2_*1*_MYPKG" ())[0m is no longer legal. Thanks to Robert Krug for asking a question that led directly to the discovery of this bug. We fixed a soundness bug that allows [47m:[0m[47m[logic][0m mode functions to call [47m:[0m[47m[program][0m mode functions. The fix furthermore prevents functions with [guard]s verified from calling functions with guards not verified. We had thought we already prevented all this, but there was a problem with the interaction of [47m[local][0m definitions and redundancy checking (see [redundant-events]). We fixed a soundness bug that could occur when built-in functions were called during macroexpansion (a hole in so-called ``safe-mode''). Fixed a minor bug in system functions [47mgenvar1[0m and [47mgenvar[0m, where [47m[eq][0m had been used in place of [47m[eql][0m. This bug was discovered during the plugging of a hole in safe-mode, mentioned just above. We fixed handling of the [47m:inline[0m keyword for [47m[defstobj][0m, which previously could cause raw Lisp errors in OpenMCL and CMU Common Lisp. Thanks to John Matthews for bringing this issue to our attention. Calls of [47m[include-book][0m could result in a state for which some function definitions were not compiled that should have been. The result could be performance degradation or even stack overflows. This situation could arise in the following two ways. o Inclusion of a book with an absolute pathname that differs from the absolute pathname at certification time, presumably because of the use of soft links. Thanks to Bob Boyer and Warren Hunt for bringing a stack overflow to our attention that led us to this fix. o Large [47m[mutual-recursion][0m nests (more than 20 functions) are executed in a superior book. We fixed some performance bugs that can increase the speed of [47m[include-book][0m calls by a factor of close to 2. Thanks to Eric Smith for asking if we could speed up [47m[include-book][0m processing; we have done so in the past, but primarily focusing on large [47m[mutual-recursion][0m nests (which have nothing in particular to do with the current improvements). Also, thanks to Rob Sumners for a very useful remark early in the process that kept us from drawing an incorrect conclusion at that point. We fixed [47m:[0m[47m[pl][0m so that it can be run on a form that returns multiple values, which it could not do previously. Thanks to Eric Smith for pointing out this problem. Fixed a bug in the Allegro ACL2 trace utility (see [trace$]) that was causing ``[47m10>[0m'' to be printed as ``[47m9>[0m'', ``[47m11>[0m'' to be printed as ``[47m10 >[0m'', ``[47m12>[0m'' to be printed as ``[47m11 >[0m'', and so on. Fixed a [proof-builder] bug that was preventing the use of the [47mDV[0m command (or a numerical command) on [47m[let][0m expressions. Thanks to Bill Young for pointing out this problem. Fixed a bug in a comment on how to set [47mACL2_BOOKS_DIR[0m in the makefile. Thanks to Dave Greve for pointing out this problem. Fixed a potential soundness bug in the linear arithmetic routines. Thanks to Jared Davis for noticing this problem and to Robert Krug for implementing the fix. (Technical details: We had been assuming that polynomials were being normalized --- see the definition of good-polyp in linear-a.lisp --- but this assumption was false.) When the macro [47m[open-trace-file][0m is opened twice in succession, it now automatically closes the first trace output channel before opening another. It is now possible to use `make' to build ACL2 on Windows systems that support `make'. Thanks to Pete Manolios and Mike Thomas for pointing out the problem, to Jared Davis and Mike for helping us to analyze the problem, and to Jared for testing the fix. Fixed a bug in the [guard] of [47m[with-output][0m that was causing a needless guard violation. [31;1mNEW FUNCTIONALITY.[0m The new events [47m[add-default-hints][0m and [47m[remove-default-hints][0m allow one to append to or subtract from the current list of default hints. The event [47m[set-default-hints][0m continues to set the list of default hints, discarding the previous value of the [47m[default-hints][0m. Note that [47m[set-default-hints][0m is still [47m[local][0m to the [47m[encapsulate][0m or book in which it occurs, and [47m[add-default-hints][0m has the same property, although neither is implemented any longer using the [47m[ACL2-defaults-table][0m. New events [47m[add-default-hints!][0m, [47m[remove-default-hints!][0m, and [47m[set-default-hints!][0m are the same as [47m[add-default-hints][0m, [47m[remove-default-hints][0m, and [47m[set-default-hints][0m, respectively, except that the former three events are not [47m[local][0m to their enclosing [47m[encapsulate][0m or book. Thanks to Jared Davis for suggesting these enhancements. OpenMCL's tracing routines have been modified in a similar manner as those of Allegro CL. Thanks to Robert Krug for providing this enhancement. Guard-checking can now be caused to happen on recursive calls. See ``GUARD-RELATED CHANGES'' below for details. Advanced users can now inhibit compilation of so-called ``*1* functions'' with the [47m:comp[0m command; see [comp]. Thanks to Rob Sumners for suggesting this enhancement. Added new legal argument [47mhard?[0m for the [47m[er][0m macro, which is now documented. See [er]. Thanks to Rob Sumners for a discussion leading to this change. Also, the three legal first arguments to [47m[er][0m --- [47mhard[0m, [47mhard?[0m, and [47msoft[0m --- may now be in any package (thanks to Jared Davis for bringing this issue to our attention). We have removed the requirement that for a rule's hypothesis [47m(bind-free term var-list)[0m, at least one variable must occur free in [47mterm[0m. For example, the expression [47m(bind-free (bind-divisor a b) (x))[0m was legal because [47ma[0m and [47mb[0m occur free in [47m(bind-divisor a b)[0m; but [47m(bind-free (foo (bar)) (x))[0m was not legal. The latter is no longer disallowed. (Technical note: this allows [47m[bind-free][0m to be used to create explicit substitutions in metafunction hypotheses.) The following two enhancements have been implemented for rules of class [47m:[0m[47m[meta][0m. Thanks to Eric Smith for requesting more control of reasoning with [47m:[0m[47m[meta][0m rules, which led to these enhancements, and to him and Robert Krug for helpful discussions. o It is now possible to control backchaining in rules of class [47m:[0m[47m[meta][0m by providing a [47m:backchain-limit-lst[0m argument, as was already allowed for rules of class [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m. See [rule-classes]. However, unlike those other two rule classes, the value for [47m:backchain-limit-lst[0m is prohibited from being a non-empty list; it must be either [47mnil[0m or a non-negative integer. o (For advanced users.) It is now legal for hypothesis metafunctions to generate, in essence, calls of [47m[syntaxp][0m and [47m[bind-free][0m, handled essentially as they are handled in hypotheses of [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules. We say ``essentially'' primarily because both [47m[syntaxp][0m and [47m[bind-free][0m are actually macros, but hypothesis metafunctions must generate translated terms (see [term]). The enterprising advanced user can call [47m:[0m[47m[trans][0m to see examples of translated terms corresponding to calls of [47m[syntaxp][0m and [47m[bind-free][0m. A new command [47m:[0m[47m[trans!][0m has been added, which is like [47m:[0m[47m[trans][0m except that [47m:[0m[47m[trans!][0m ignored issues of single-threadedness. See [trans!]. Thanks to Eric Smith for suggesting this addition. The [47m:[0m[47m[pf][0m command now works when the argument is the name of a macro associated with a function by [macro-aliases-table]. [31;1mCHANGES IN PROOF ENGINE.[0m The simplifier has been changed slightly in order to avoid using [forward-chaining] facts derived from a literal (essentially, a top-level hypothesis or conclusion) that has been rewritten. As a practical matter, this may mean that the user should not expect forward-chaining to take place on a term that can be rewritten for any reason (generally function expansion or application of rewrite rules). Formerly, the restriction was less severe: forward-chaining facts from a hypothesis could be used as long as the hypothesis was not rewritten to [47mt[0m. Thanks to Art Flatau for providing an example that led us to make this change; see the comments in source function [47mrewrite-clause[0m for details. The rewriter has been modified to work slightly harder in relieving hypotheses. Thanks to Eric Smith for providing an example that inspired the following, which illustrates the issue. Suppose we introduce functions [47mfoo[0m and [47mbar[0m with the (non-[47m[local][0m) properties shown below. (encapsulate (((foo *) => *) ((bar *) => *)) (local (defun foo (x) (declare (ignore x)) t)) (local (defun bar (x) (declare (ignore x)) t)) (defthm foo-holds (implies x (equal (foo x) t))) (defthm bar-holds-propositionally (iff (bar x) t))) Consider what happens when ACL2's rewriter is used to prove the following theorem. (thm (foo (bar y))) With ACL2's inside-out rewriting, [47m(bar y)[0m is first considered, but rewrite rule [47mbar-holds-propositionally[0m does not apply because the context requires preserving equality, not mere Boolean ([47miff[0m) equivalence. Then the rewriter moves its attention outward and sees the term [47m(foo (bar y))[0m. It attempts to apply the rule [47mfoo-holds[0m, in a context created by binding its variable [47mx[0m to the term [47m(bar y)[0m. It then attempts to relieve the hypothesis [47mx[0m of rule [47mfoo-holds[0m in that context. Before this change, ACL2 basically assumed that since rewriting was inside out, then [47m(bar y)[0m had already been rewritten as much as possible, so the rewrite of [47mx[0m in the aforementioned context (binding [47mx[0m to [47m(bar y)[0m) simply returned [47m(bar y)[0m, and the attempt to relieve the hypothesis of [47mfoo-holds[0m failed. The change is essentially for ACL2's rewriter to make a second pass through the rewriter when the attempt fails to rewrite a variable to [47mt[0m, this time using the fact that we are in a Boolean context. (We mention that source function [47mrewrite-solidify-plus[0m implements this idea, for those who want to dig deeply into this issue.) In our example, that means that the rewriter considers [47m(bar y)[0m in a Boolean context, where it may apply the rule [47mbar-holds-propositionally[0m to relieve the hypothesis successfully. When [47m([0m[47m[set-non-linearp][0m[47m t)[0m has been executed, [non-linear-arithmetic] can now be applied in some cases for which it previously was not. Thanks to Robert Krug for supplying this modification and to Julien Schmaltz for providing a motivating example. We modified the rewriter to avoid certain infinite loops caused by an interaction of the opening of recursive functions with equality reasoning. (This change is documented in detail in the source code, in particular functions [47mrewrite-fncall[0m and [47mfnstack-term-member[0m.) Thanks to Fares Fraij for sending us an example that led us to make this change. The [47m:[0m[47m[executable-counterpart][0m of function [47m[hide][0m is now disabled when ACL2 starts up. This removes an anomaly, for example that (thm (not (equal 1 (* (hide 0) a)))) succeeded while (thm (equal (foo (equal 1 (* (hide 0) a))) (foo nil))) failed. Now both fail. The theory [47m*s-prop-theory*[0m is no longer used by the [3mproof-builder[0m; it has been replaced by [47m(theory '[0m[47m[minimal-theory][0m. We have left the constant [47m*s-prop-theory*[0m defined in the source code in support of existing books, however. This change eliminates annoying theory warnings printed upon invocation of [proof-builder] commands [47ms-prop[0m, [47msl[0m, and [47msplit[0m. Terms are now kept in an internal form that avoids calls of primitive functions (built-ins without explicit definitions; see code for [47mcons-term[0m for details), in favor of the constants that result from evaluating those calls. So for example, the internal form for [47m(cons 1 2)[0m is [47m(quote (1 . 2))[0m. This change was made at around the same time as changes in support of [47m[bind-free][0m; see above. One consequence is that the splitting of goals into cases (technically, source function [47mclausify[0m and even more technically, source function [47mcall-stack[0m) has been modified, which can cause subgoal numbers to change. [31;1mGUARD-RELATED CHANGES.[0m Guard-checking can now be caused to happen on recursive calls, where this was formerly not the case for [47m:[0m[47m[program][0m mode functions and, perhaps more important, for [47m:[0m[47m[logic][0m mode functions whose [guard]s have not been verified. Moreover, a warning is printed when ACL2 does not rule out the exclusion of guard-checking on recursive calls. See [set-guard-checking]. Thanks to David Rager for bringing this issue to our attention, and to Rob Sumners and the Univ. of Texas ACL2 seminar in general for their feedback. Guard violations are reported with less of the offending term hidden. Thanks to Jared Davis for suggesting that we look at this issue. [31;1mPROOF-BUILDER CHANGES.[0m We fixed the [proof-builder] so that diving works as you might expect for a macro call [47m(op a b c)[0m representing [47m(binary-op a (binary-op b c))[0m. In the past, if the current term was of the form [47m(append t1 t2 t3)[0m, then [47m(DV 3)[0m (and [47m3[0m) would dive to [47mt3[0m even though the corresponding function call is [47m(binary-append t1 (binary-append t2 t3))[0m. This is still the case, but now this behavior holds for any macro associated with a function in [47mbinop-table[0m (see [add-binop]). Moreover, users can now write customized diving functions; see [dive-into-macros-table], and also see [47mbooks/misc/rtl-untranslate.lisp[0m for example calls to [47m[add-dive-into-macro][0m. Of course, the old behavior can still be obtained using the [proof-builder]'s [47mDIVE[0m command; see [proof-builder-commands]. The [47mrunes[0m command in the [proof-builder] now shows only the [rune]s used by the most recent primitive or macro command (as shown by [47m:comm[0m), unless it is given a non-[47mnil[0m argument. Also, [proof-builder] command [47mlemmas-used[0m has been added as, in essence, an alias for [47mrunes[0m. (The following two items are also mentioned above under ``BUG FIXES.'') Fixed a [proof-builder] bug that was preventing the use of the [47mDV[0m command (or a numerical command) on [47m[let][0m expressions. Thanks to Bill Young for pointing out this problem. The theory [47m*s-prop-theory*[0m is no longer used by the [3mproof-builder[0m; it has been replaced by [47m(theory '[0m[47m[minimal-theory][0m. We have left the constant [47m*s-prop-theory*[0m defined in the source code in support of existing books, however. This change eliminates annoying theory warnings printed upon invocation of [proof-builder] commands [47ms-prop[0m, [47msl[0m, and [47msplit[0m. [31;1mSYSTEM-LEVEL CHANGES.[0m Fixed a problem with building ACL2 on CMUCL in some systems (source function [47msave-acl2-in-cmulisp[0m). Thanks to Bill Pase for bringing this to our attention. The installation instructions have been extended to include instructions for building on GCL in Mac OS X. Thanks to Jun Sawada and Camm Maguire. Initial pre-allocation of space has been updated for GCL to reflect more current GCL executables (we considered GCL 2.6.1-38). This can help avoid running out of memory for large ACL2 sessions. The main [47mMakefile[0m has been replaced by [47mGNUmakefile[0m, in order to enforce the use of GNU `make'. If you use another `make' program, you'll get an error message that may help you proceed. (GCL only) SGC is no longer turned on for GCL 2.6 sub-versions through 2.6.3 if [47msi::*optimize-maximum-pages*[0m is bound to [47mT[0m, due to an apparent issue with their interaction in those sub-versions. Also, we have eliminated preallocation for all versions after 2.6.1 because GCL doesn't need it (comments are in source function [47msave-acl2-in-akcl[0m). Thanks to Camm Maguire for excellent GCL help and guidance, and to Camm and Bob Boyer for useful discussions. We have removed support for so-called ``small'' images. Thus, [47m:[0m[47m[doc][0m, [47m:[0m[47m[pe][0m and [47m:[0m[47m[pc][0m, [47m[verify-termination][0m, and other commands are fully supported in ACL2 saved images. Because of this and other changes in the generation of the so-called ``*1*'' logical functions, related to guards (as described above in -GUARD-RELATED CHANGES'', and related to the discussion of safe-mode in ``BUG FIXES'' above), image sizes have increased substantially. We no longer [47mtime[0m or run ``[47mnice[0m'' the certification of individual books. The file [47mbooks/Makefile-generic[0m had done these by default, and some individual distributed and workshop book directories had [47mMakefile[0ms that did so as well. Thanks to Mike Thomas, who pointed out the lack of [47mnice[0m on some Windows systems (and we decided on this simple solution). Overall targets in [47mbooks/Makefile[0m still [47mtime[0m their runs by default, and the particular [47mtime[0m program is now controlled by a [47mMakefile[0m variable. Failures during [47mmake certify-books[0m or [47mmake regression[0m now show up in the log as ``[47m**CERTIFICATION FAILED**[0m'', regardless of the operating system (as long as it supports `make'). Formerly, one searched for ``[47m**[0m'' but this did not appear in openMCL runs. We have eliminated ``Undefined function'' warnings that could occur in OpenMCL. [31;1mBOOK CHANGES.[0m Reconciled the definitions of [47mfirstn[0m in [47mbook/misc/csort.lisp[0m, [47mbooks/bdd/bdd-primitives.lisp[0m, [47mbooks/ordinals/ordinal-definitions.lisp[0m, and [47mbooks/data-structures/list-defuns.lisp[0m. Thanks to Ray Richards for bringing this issue to our attention. Distributed book [47mbooks/misc/defpun[0m now can handle [stobj]s where it did not previously. Thanks to John Matthews for bringing this issue to our attention. The "make" variable [47mCOMPILE_FLG[0m in file [47mbooks/Makefile-generic[0m formerly only had an effect if there was a [47mcert.acl2[0m file present. That oversight has been remedied. File [47m"books/arithmetic/certify.lsp"[0m was missing a [47m[certify-book][0m command for [47m"natp-posp"[0m. Thanks to John Cowles for noticing this deficiency and supplying a fix. (This file is of use to those who want to certify the [47m"books/arithmetic/"[0m books without using [47m"make"[0m.) A few small changes have been made to [47m"books/rtl/rel4"[0m. Small changes were made to books [47mmisc/symbol-btree[0m and [47mmisc/rtl-untranslate[0m. In particular, the definition of [47msymbol-btreep[0m was strengthened. We made a minor fix to [47mbooks/ordinals/e0-ordinal.lisp[0m, adding [47m(verify-guards ob+)[0m and hence [47m(verify-guards ocmp)[0m as well. This was necessitated by the fix prohibiting functions with guards verified from calling functions with guards not verified (see also the related discussion under ``BUG FIXES'' above). [31;1mMISCELLANEOUS CHANGES.[0m Further sped up processing of large [47m[mutual-recursion][0m nests (extending what was done for Version_2.7), perhaps by a factor of two in some cases. As promised in Version_2.5 (see [note-2-5]), structured pathnames are no longer supported. So for example, the argument to [47m[include-book][0m must now be a string constant. Some documentation has been improved, for [stobj]s thanks to suggestions by John Matthews and much of the rest thanks to feedback from Eric Smith. The function [47m[current-package][0m is now available to users (it has been taken off the list of so-called ``untouchables''). Thanks to Jared Davis for bringing this issue to our attention. The documentation for topic [using-computed-hints-7] has been improved. Thanks to Doug Harper and Eric Smith for inspiring this improvement. We added several symbols to [47m*acl2-exports*[0m: [47m[cw][0m, [47m[er][0m, [47m[intern$][0m, [47m[set-case-split-limitations][0m, and [47m[set-difference-eq][0m. Thanks to Jared Davis for suggesting most of these. Now, a [47m[table][0m event that sets the value for a key, [47m(table tbl key val :put)[0m, is redundant (see [redundant-events]) when it does not change the value associated with an existing key of the table. In particular, [47m[define-pc-macro][0m is now fully redundant when it does not change an existing [proof-builder] macro-command definition. Thanks to Bill Young for bringing the latter issue to our attention. The definitions of unused system functions [47mev-w[0m and [47mev-w-lst[0m have been deleted. ACL2 now prints a warning if a [47m[defpkg][0m event introduces a package name with lower-case letters, since there is opportunity for later confusion in that case. Thanks to Frederic Peschanski for bringing this problem to our attention and Sandip Ray for encouragement. ACL2 now works in Version 19 of CMU Common Lisp. The function [47m[sys-call][0m has been modified so that for ACL2 built on Allegro Common Lisp in Unix or Linux, the existing environment is used. Thanks to Erik Reeber for bringing this issue to our attention. The function [47m[disabledp][0m can now be given a macro name that has a corresponding function; see [macro-aliases-table]. Also, [47m[disabledp][0m now has a [guard] of [47mt[0m but causes a hard error on an inappropriate argument.") (note-2-9-1 (release-notes) "ACL2 Version 2.9.1 (December, 2004) Notes (GCL only) A bug in [47m[symbol-package-name][0m has been fixed that could be exploited to prove [47mnil[0m, and hence is a soundness bug. Thanks to Dave Greve for sending us an example of a problem with [47m[defcong][0m (see below) that led us to this discovery. ACL2 now warns when [47m[defcong][0m specifies [47m[equal][0m as the first equivalence relation, e.g., [47m(defcong equal iff (member x y) 2)[0m. The warning says that the rule has no effect because [47m[equal][0m already refines all other equivalence relations. Formerly, this caused an error unless [47m:event-name[0m was supplied (see [defcong]), and in fact the error was a nasty raw Lisp error on GCL platforms due to some mishandling of packages by ACL2 that has been fixed (see the paragraph about [47m[symbol-package-name][0m above). Thanks to Dave Greve for sending a helpful example in his report of this problem. (GCL only) The build process was broken for GCL 2.6.0 (and perhaps some earlier versions), and has been fixed. Thanks to Jose Luis Ruiz-Reina for bringing this problem to our attention. (GCL only) We have increased the hole size to at least 20% of max-pages, which may eliminate some garbage collection at the expense of larger virtual memory (not larger resident memory or larger image). Thanks to Camm Maguire for helpful explanations on this topic. We have clarified the [guard] warning message that is printed during evaluation of recursively-defined functions whose [guard]s have not been verified, for example: ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking may be inhibited on some recursive calls of executable counterparts (i.e., in the ACL2 logic), including perhaps EVENLP. To check guards on all recursive calls: (set-guard-checking :all) To leave behavior unchanged except for inhibiting this message: (set-guard-checking :nowarn) And, ACL2 no longer prints that message when the [guard] was unspecified for the function or was specified as [47mT[0m. Thanks to Serita Nelesen for bringing the latter issue to our attention. Finally, ACL2 now prints such a warning at most once during the evaluation of any top-level form; thanks to Bill Young for pointing out this issue. The function [47m[verbose-pstack][0m has been enhanced to allow specified prover functions [31;1mnot[0m to be traced. See [verbose-pstack]. Added [47m[lp][0m, [47mwet[0m, and [47m[set-non-linearp][0m to [47m*acl2-exports*[0m, and hence to the [47m"[0m[47m[ACL2-user][0m[47m"[0m package. The distributed book [47mbooks/arithmetic-3/bind-free/integerp.lisp[0m has been modified in order to prevent potential looping; specifically, the definition of function [47mreduce-integerp-+-fn-1[0m. Thanks to Robert Krug for providing this change. A small improvement was made in the [47mwet[0m failure message when the error occurs during translation to internal form. Thanks to Jared Davis for pointing out the obscurity of some [47mwet[0m error messages. We have improved ACL2's evaluation mechanism for the function [47mbad-atom<=[0m, which now is specified to return [47mnil[0m if neither argument is a so-called ``bad atom'' (as recognized by function [47mbad-atom[0m). The following events had caused a hard error, for example. (We're sorry that [47mbad-atom[0m and [47mbad-atom<=[0m are not documented, but we also consider it unlikely that anyone needs such documentation; otherwise, please contact the implementors.) (defun foo (x y) (declare (xargs :guard t)) (bad-atom<= x y)) (defun bar (x y) (declare (xargs :guard t)) (foo x y)) (thm (equal (bar 3 4) 7)) We have also changed the guard on [47m[alphorder][0m to require both arguments to be atoms. For forms [47m(local x)[0m that are skipped during [47m[include-book][0m, or during the second pass of [47m[certify-book][0m or [47m[encapsulate][0m, ACL2 had nevertheless checked that [47mx[0m is a legal event form. This is no longer the case. The [proof-builder] now does non-linear arithmetic when appropriate. It had formerly ignored [47m[set-non-linearp][0m executed in the ACL2 command loop. Incremental releases are now supported. See [version] and {obsolete after Version 4.3} set-tainted-okp. Thanks to Hanbing Liu for discovering a flaw in our original design. The pattern-matching algorithm for [47m:[0m[47m[rewrite][0m rules has been made slightly more restrictive, thanks to a suggestion and examples from Robert Krug. For example, previously one could get an infinite loop as follows. (defstub foo (x) t) (defaxiom foo-axiom (equal (foo (+ 1 x)) (foo x))) (thm (foo 0)) ; or replace 0 by any integer! That is because the term [47m(foo 0)[0m was considered to match against the pattern [47m(foo (+ 1 x))[0m, with [47mx[0m bound to [47m-1[0m. While such matching is sound, it leads to an infinite loop since it allows [47mfoo-axiom[0m to rewrite [47m(foo 0)[0m to [47m(foo -1)[0m, and then [47m(foo -1)[0m to [47m(foo -2)[0m, and so on. The fix is to insist that the new value, in this case [47m-1[0m, is no larger in size according to [47m[ACL2-count][0m than the old value, in this case [47m0[0m. Since that test fails, the match is considered to fail and the loop no longer occurs. An analogous fix has been made for multiplication, where now we only match when the new term is still a non-zero integer. That change avoids a loop here. (defstub foo (x) t) (defaxiom foo-axiom (equal (foo (* 2 x)) (foo x))) (thm (foo 0)) ; or try (thm (foo 4)) Added macro [47mfind-lemmas[0m in [47mbooks/misc/find-lemmas.lisp[0m (see brief documentation there) for finding all lemmas that mention all function symbols in a given list. [47m:Restrict[0m [hints] now work for [47m:[0m[47m[definition][0m rules, though they continue to be ignored by the preprocessor and hence you may want to use [47m:do-not '(preprocess)[0m with any restrict hints. Thanks to John Matthews for pointing out the lack of support for [47m:definition[0m rules in [47m:restrict[0m hints. Some books have been updated. In particular, there is a new directory [47mbooks/workshops/2004/[0m in workshops distribution, for the 2004 ACL2 workshop. There is also a new version of Jared Davis's ordered sets library, formerly in [47mbooks/finite-set-theory/osets-0.81/[0m but now in [47mbooks/finite-set-theory/osets/[0m. Fixed a bug in the (under-the-hood) raw Lisp definition of [47m[defchoose][0m, which had been causing a warning in CMU Common Lisp. [Technical improvements related to the use of ``[47mmake dependencies[0m'' for certifying distributed books:] File [47mbooks/Makefile-generic[0m now does a better job with ``[47mmake dependencies[0m,'' specifically with respect to handling [47m*.acl2[0m files and handling [47m[include-book][0m commands with [47m:dir :system[0m. Regarding the latter, suppose for example that book [47mbasic.lisp[0m contains the line: (include-book "arithmetic/top-with-meta" :dir :system) Then [47mmake dependencies[0m would generate the following line: basic.cert: $(ACL2_SRC_BOOKS)/arithmetic/top-with-meta.cert Thus, if [47m:dir :system[0m is used with [47m[include-book][0m, the corresponding [47mMakefile[0m should define the variable [47mACL2_SRC_BOOKS[0m. A standard [47mMakefile[0m header for a books directory could thus be as follows. # The following variable should represent the ACL2 source directory. It is the # only variable in this Makefile that may need to be edited. ACL2_SRC = ../../../../../.. ACL2_SRC_BOOKS = $(ACL2_SRC)/books include $(ACL2_SRC_BOOKS)/Makefile-generic ACL2 = $(ACL2_SRC)/saved_acl2h Finally, the ``[47m-s[0m'' flag may now be omitted when running ``[47mmake dependencies[0m.''") (note-2-9-2 (release-notes) "ACL2 Version 2.9.2 (April, 2005) Notes Also see [note-2-9-1] for other changes since the last non-incremental release (Version_2.9). There was a bug in non-linear arithmetic (see [non-linear-arithmetic]) that caused the following error: ACL2 !>(include-book "rtl/rel4/lib/top" :dir :system) .... ACL2 !>(set-non-linearp t) T ACL2 !>(thm (implies (and (bvecp a 77) (bvecp b 50)) (bvecp (fl (/ (* a b) (expt 2 23))) 104)) :hints (("Goal" :in-theory (enable bvecp)))) [Note: A hint was supplied for the goal above. Thanks!] By the simple :definition BVECP, the :executable-counterparts of EXPT and UNARY-/ and the simple :rewrite rule ASSOCIATIVITY-OF-* we reduce the conjecture to Goal' (IMPLIES (AND (INTEGERP A) (<= 0 A) (< A 151115727451828646838272) (INTEGERP B) (<= 0 B) (< B 1125899906842624)) (BVECP (FL (* A B 1/8388608)) 104)). HARD ACL2 ERROR in VARIFY: This should not have happened. The supposed variable, '1/8388608, is instead a constant. ACL2 !> Thanks to Robert Krug for providing a fix for the above error. Guard-checking was being inhibited (since v2-9) for calls of built-in primitives on explicit values, e.g., [47m(car 3)[0m. This has been fixed. Guard-related warnings could be printed during proofs (this bug was introduced in Version_2.9.1). These warnings have been eliminated. Compound-recognizer rules [47mnatp-compound-recognizer[0m and [47mposp-compound-recognizer[0m are now built into ACL2 for predicates [47m[natp][0m and [47m[posp][0m, and hence have been deleted from book [47mnatp-posp.lisp[0m (where they were called [47mnatp-cr[0m and [47mposp-cr[0m, respectively). The function [47mfile-clock-p[0m, which recognizes a component of the ACL2 [47m[state][0m, is now defined using [47m[natp][0m instead of [47m[integerp][0m. Thanks to Jared Davis for suggesting this change. (Technical explanation about functions in ACL2 source file [47maxioms.lisp[0m: With a [47mfile-clock[0m of -1, the call of [47mmake-input-channel[0m in [47mopen-input-channel[0m will create a channel that can't be closed; see the guard of [47mclose-input-channel[0m.) (Allegro CL users only) Support is now provided for building an Allegro CL application, provided you have an Allegro CL dynamic runtime license. (Our belief is that with such a license, many users can use the same application, rather than each user needing a separate license.) See new GNUmakefile target [47mallegro-app[0m and file [47mbuild-allegro-exe.cl[0m for more information. The new home page now contains a link to a new page [47mother-releases.html[0m, which contains information about other ACL2 releases. (This is in one's local home page, but may not show up on the central ACL2 home page until the next non-incremental release.) Thanks to Warren Hunt for suggesting this addition. We thank Erik Reeber for suggesting a solution to output redirection using [47m[sys-call][0m, which we have described at the end of its documentation. A new documentation topic fixes the flawed argument for conservativity of the [47m[defchoose][0m event that appears in Appendix B of Kaufmann and Moore's paper, ``Structured Theory Development for a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2 (2001), pp. 161--203). See [conservativity-of-defchoose]. Thanks to John Cowles and Ruben Gamboa for helpful feedback on drafts of this note. The solution to exercise 6.15 in [47mbooks/textbook/chap6/solutions.txt[0m has been fixed. Thanks to Aaron Smith for pointing out the problem. A new documentation topic [defun-sk-example] gives a little more help in using [47m[defun-sk][0m effectively. Thanks to Julien Schmaltz for presenting this example as a challenge. (GCL only) There is now a way to speed up GCL builds of ACL2, at the cost of perhaps a percent or so in performance of the resulting image. Using `make' one supplies the following. LISP='gcl -eval "(defparameter user::*fast-acl2-gcl-build* t)" Various makefiles have been improved in several ways. (1) Parallel book certification, using GNU make's [47m-j[0m option, can be used. (2) Book certifications now stops at the first failure if [47mbooks/Makefile[0m or [47mbooks/Makefile-generic[0m is used, and returns non-zero exit status. However, the various make targets in the ACL2 source directory ([47mregression[0m, [47mcertify-books[0m, etc.) still continue past failures unless you provide [47mACL2_IGNORE=' '[0m on the `make' command line. (3) The build process has been modified (file [47mGNUmakefile[0m) so that it stops upon a failed compile or a failed initialization. (4) The automatic dependency generation (from ``[47mmake dependencies[0m'' has been improved so that commands of the form [47m(ld "my-book.lisp")[0m in [47m.acl2[0m files cause the appropriate dependencies to be generated. Thanks to comments from several users that led to the above Makefile improvements: Ray Richards, Doug Harper, and the Rockwell ACL2 users for (1) and (2) (and inspiring (4)), and David Rager for (2) and (3). In particular, Doug Harper sent a replacement for the [47m.date[0m mechanism, which was interfering with [47mmake -n[0m; so, these files are no longer written. A mechanism has been added for saving output. In particular, you can now call [47m[ld][0m on a file with output turned off, for efficiency, and yet when a proof fails you can then display the proof attempt for the failed (last) event. See set-saved-output. Another new command --- see [set-print-clause-ids] --- causes subgoal numbers to be printed during proof attempts when output is inhibited. Documentation has been added for using ACL2's makefile support to automate the certification of collections of books. See [books-certification-classic]. Fixed a bug in [47m[sys-call-status][0m that was causing hard Lisp errors. Improved [47m[cw-gstack][0m to allow a [47m:frames[0m argument to specify a range of one or more frames to be printed. see [cw-gstack]. Fixed a bug in [proof-builder] command [47mforwardchain[0m. Thanks to Ming-Hsiu Wang for bringing this bug to our attention. We have provided a mechanism for saving an executable image. See [saving-and-restoring] and see [save-exec]. We have eliminated obsolete functions [47mnote-lib[0m and [47mmake-lib[0m. Modified the [47m[ground-zero][0m [theory] so that it contains all of the built-in rules (in ACL2 source file [47maxioms.lisp[0m). It had formerly failed to include rules from some definitions and theorems near the end of [47maxioms.lisp[0m. A new event, [47m[set-enforce-redundancy][0m, allows the enforcement of [47m[defthm][0m, [47m[defun][0m, and most other events during book development. See [set-enforce-redundancy]. A bug has been fixed that had allowed [47m[deftheory][0m [events] to cause a hard Lisp error when calling [47m[union-theories][0m on ill-formed theories after, for example: :set-guard-checking nil (in-theory (union-theories '((:rewrite no-such-rule)) (current-theory 'ground-zero))) The handling of [guard] checking has been modified somewhat in a way that should only very rarely affect users. (An ``Essay on Guard Checking'' in the ACL2 source code explains this point to anyone interested in implementation details.) (GCL ONLY) Removed the -dir setting in the ACL2 wrapper script for GCL. This should generally have no effect for most users, but it eliminates a potential source of error down the road. Several interesting new definitions and lemmas have been added to the rtl library developed at AMD, and incorporated into [47mbooks/rtl/rel4/lib/[0m. Other book changes include a change to lemma [47mtruncate-rem-elim[0m in [47mbooks/ihs/quotient-remainder-lemmas.lisp[0m, as suggested by Jared Davis. The macro [47m[real/rationalp][0m may now be referred to in [47m[in-theory][0m [events] and [hints], thanks to a new [47m[add-macro-alias][0m event. Thanks to Jared Davis for this suggestion. ACL2 terms of the form [47m(if p 'nil 't)[0m are now printed as [47m(not p)[0m, where in some setting they had been printed as [47m(and (not p) t)[0m. Thanks to Robert Krug for this improvement. (GCL ONLY) Added profiling support, based heavily on code supplied by Camm Maguire. See file [47msave-gprof.lsp[0m for instructions. Thanks to Camm, and also to David Hardin for inspiring this addition. Added support for preprocessing before printing (untranslating) a term. See [user-defined-functions-table], in particular the discussion of [47muntranslate-preprocess[0m. Thanks to Jared Davis for inspiring this addition, and for providing a book that takes advantage of it ([47mbooks/misc/untranslate-patterns.lisp[0m). The documentation has been improved for explaining how [rune]s are assigned; see [rune]. Thanks to Robert Krug for pointing out inaccuracies in the existing documentation.") (note-2-9-3 (release-notes) "ACL2 Version 2.9.3 (August, 2005) Notes Also see [note-2-9-1] and see [note-2-9-2] for other changes since the last non-incremental release (Version_2.9). We fixed a soundness bug that exploited the ability to define [47m:[0m[47m[program][0m mode functions that are improperly guarded, and then to use those functions in [47m[defconst][0m forms. The fix is to evaluate [47m[defconst][0m forms using the same ``safe-mode'' that is used in macroexpansion (see [guards-and-evaluation]). Here is a proof of [47mnil[0m that succeeded in Allegro Common Lisp (but not, for example, GCL). See also a long comment in source function [47mdefconst-fn[0m for an example that does not require the use of [47m:set-guard-checking[0m. :set-guard-checking nil ; execute before certifying the book below (in-package "ACL2") (encapsulate () (local (defun f1 () (declare (xargs :mode :program)) (char-upcase (code-char 224)))) (local (defconst *b* (f1))) (defun f1 () (char-upcase (code-char 224))) (defconst *b* (f1)) (defthm bad (not (equal *b* (code-char 224))) :rule-classes nil)) (defthm ouch nil :hints (("Goal" :use bad)) :rule-classes nil) We fixed a soundness hole due to the fact that the "LISP" package does not exist in OpenMCL. We now explicitly disallow this package name as an argument to [47m[defpkg][0m. Thanks to Bob Boyer and Warren Hunt for bringing an issue to our attention that led to this fix. ACL2 now requires all package names to consist of standard characters (see [standard-char-p], none of which is lower case. The reason is that we have seen at least one lisp implementation that does not handle lower case package names correctly. Consider for example the following raw lisp log (some newlines omitted). >(make-package "foo") #<"foo" package> >(package-name (symbol-package 'FOO::A)) "foo" >(package-name (symbol-package '|FOO|::A)) "foo" > Distributed book [47mbooks/textbook/chap10/compiler[0m, as well as workshop books in directory [47mbooks/workshops/2004/cowles-gamboa/support/[0m, were modified to accommodate the above change. Added [47mnewline[0m, [47m[add-to-set-eql][0m, [47mthe-fixnum[0m, and [47mthe-fixnum![0m to [47m*acl2-exports*[0m. Thanks to Jared Davis for bringing these to our attention. Added a line to [47macl2.lisp[0m to support CMUCL running on Mac OSX, thanks to a suggestion from Fabricio Chalub Barbosa do Rosario. The executable scripts for saved ACL2 images now include [47m$*[0m, so that command-line arguments will be passed along. (For GCL profiling only) Fixed a colon ([47m:[0m) that should have been a semicolon ([47m;[0m) in file [47msave-gprof.lsp[0m. Thanks to David Hardin for pointing out this bug. The documentation for [47m:[0m[47m[elim][0m rules has been expanded and improved, thanks to useful feedback from Hanbing Liu. Fixed a bug in the guard for function [47minclude-book-dir[0m. For those who want to experiment with an alternate implementation of [47m[mv][0m and [47m[mv-let][0m, there is now support for under-the-hood implementation of these in terms of raw Lisp functions [47mvalues[0m and [47mmultiple-value-bind[0m, respectively. The regression suite has seen about a 10% speed-up in Allegro CL and about an 8% slowdown in GCL for builds with this change. See the makefile ([47mGNUmakefile[0m) for examples of how to build ACL2 by including the feature, [47m:acl2-mv-as-values[0m. Source file [47minit.lsp[0m has been renamed to [47minit.lisp[0m in support of this change (technical detail: otherwise GCL loads the init file too soon, before its [47m-eval[0m argument is evaluated). Thanks to David Rager for inspiring this change, by pointing out the problematic use of globals by the existing [47m[mv][0m implementation from the standpoint of supporting parallel evaluation. This capability is experimental: there is likely to be some remaining work to be done on it. A change related to the one just above is that we now limit the maximum number of arguments to any call of [47m[mv][0m to 32. Thanks to Bob Boyer for raising a question that lead to this change. Eliminated some compiler warnings in OpenMCL. In the rtl library ([47mbooks/rtl/rel4/[0m), functions [47mbits[0m and [47msetbits[0m have had their [guard]s improved (as they had been too restrictive, especially for [47msetbits[0m). A new function [47m[time$][0m permits timing of forms, by using (under the hood) the host Common Lisp's [47mtime[0m utility. We fixed an infinite loop that could occur during destructor elimination (see [elim]). Thanks to Sol Swords to bringing this to our attention and sending a nice example, and to Doug Harper for sending a second example that we also found useful. The method of speeding up GCL-based builds (see [note-2-9-2]) has changed slightly from Version_2.9.2. Now, in the `make' command: LISP='gcl -eval "(defparameter user::*fast-acl2-gcl-build* t)" We improved the pretty-printer's handling of keywords. For example, before this change one might see the following printed by ACL2. (MODIFY TH S :KEY1 VAL1 :KEY2 (IF (IF X Y Z) AAAAAAAAAA BBBBBBB)) Now, the above might print as follows. Notice that we have avoided breaking after a keyword (see [keywordp]) that is preceded by other forms on the same line. (MODIFY TH S :KEY1 VAL1 :KEY2 (IF (IF X Y Z) AAAAAAAAAA BBBBBBB)) See [note-2-9-3-ppr-change] for a detailed discussion of this change. (GCL ONLY) Evaluation in a break is no longer inhibited by ACL2 when built on top of GCL, so GCL now matches other Common Lisps in this respect. For ACL2 built on most host Common Lisps, you will see the string [47m[RAW LISP][0m in the prompt, at least at a break, to emphasize that one is inside a break and hence should probably quit from the break. See [breaks]. Jared Davis suggested improvements to lemmas [47mlen-update-nth[0m (in source file [47maxioms.lisp[0m) and [47mappend-true-listp-type-prescription[0m (in [47mbooks/meta/term-defuns.lisp[0m), which have been incorporated. The former required a change in [47mbooks/workshops[0m book [47m2004/ruiz-et-al/support/q-dag-unification.cert[0m, which has been made. The [proof-builder] command [47mrewrite[0m allows further binding of free variables in hypotheses, with new optional argument [47minstantiate-free[0m. proof-builder command [47mshow-rewrites[0m ([47msr[0m) gives corresponding additional information. Documentation for these commands has been improved; see [proof-builder-commands]. Thanks to John Matthews and Bill Young for suggestions and feedback leading to these improvements. Fixed downcase printing so that the package name of a symbol is also downcased. For example, after execution of [47m(defpkg "FOO" nil)[0m and [47m(set-acl2-print-case :downcase)[0m, [47m'foo::ab[0m will print back as the same, rather than as [47m'FOO::ab[0m. It is now possible to control the output so that numbers are printed in binary, octal, or hex, though the default is still radix 10. See [set-print-base]. Note that in support of this change, built-in functions [47m[explode-nonnegative-integer][0m and [47mexplode-atom[0m now take an extra [47mprint-base[0m argument. Different support for radix conversion may be found in a book newly contributed by Jun Sawada, [47mbooks/misc/radix.lisp[0m. Built-in axiom [47mcar-cdr-elim[0m is now only an [47m:[0m[47m[elim][0m rule. It was formerly both an [47m:elim[0m rule and a [47m:[0m[47m[rewrite][0m rule. A new rule, [47mcons-car-cdr[0m, takes the place of the old [47m:rewrite[0m rule, but is instead a hypothesis-free rule that can cause a case split (see source file [47maxioms.lisp[0m). Thanks to Jared Davis for suggesting this change. Lemmas about [47m[alphorder][0m ([47malphorder-reflexive[0m, [47malphorder-transitive[0m, [47malphorder-anti-symmetric[0m, and [47malphorder-total[0m) are now available. (They had been [47m[local][0m in source file [47maxioms.lisp[0m.) Thanks to Serita Nelesen for bringing this issue to our attention. ACL2 has, for some time, printed a space in the event summary after the open parenthesis for a [47m[defthm][0m event, in order to ease backward searching for the original form, for example [47m(defthm bar ...)[0m: Form: ( DEFTHM BAR ...) The intention was that this extra space should be printed for every event form; but it was missing in some cases, for example, for [47m[verify-guards][0m. This has been fixed. In analogy to [47m[include-book][0m, now [47m[ld][0m takes the (optional) keyword argument [47m:dir[0m. Thanks to Jared Davis for providing an implementation of this feature and to Eric Smith and Jeff Marshall for requesting this feature. We fixed a bug in [47m[include-book][0m that could cause an error when redefinition is on, for example: (set-ld-redefinition-action '(:warn! . :overwrite) state) (include-book "/u/acl2/books/arithmetic/top") The behavior of [47m[include-book][0m now matches the documentation: handling of compiled files for uncertified [books] will follow the same rules as for certified books. In particular, if you create an object file in raw Lisp for some book, then including that book will load that object file. Thanks to Jared Davis for bringing this issue to our attention. New documentation explains the interaction of redefinition and redundancy. See [redundant-events] --- the ``Note About Unfortunate Redundancies'' is new. Thanks to Grant Passmore for providing examples that led us to write this additional documentation. Solutions to exercises in { How To Prove Theorems Formally | http://www.cs.utexas.edu/users/moore/publications/how-to-prove-thms} are now available in distributed book [47mbooks/misc/how-to-prove-thms.lisp[0m. Also in that directory may be found a new book [47mhanoi.lisp[0m that contains a solution to the Towers of Hanoi problem. Subtopics [Note-2-9-3-ppr-change] Change in pretty-printing for ACL2 Version_2.9.3") (note-2-9-3-ppr-change (note-2-9-3) "Change in pretty-printing for ACL2 Version_2.9.3 We have improved pretty-printing in ACL2 Version_2.9.3 to handle keywords a little differently. To see a discussion of the basics of this change, see [note-2-9-3]. In this note we describe it in considerable detail. Those who wish to understand the ACL2 pretty-printer's implementation can now find considerably more comments on it in the source code. In this note, we do not focus on the implementation. Rather, we motivate the change and show how the improved prettyprinter performs. Why do we want better keyword handling? Imagine a macro that builds a new state from an old state by changing the values in the affected fields, leaving everything else unchanged. One could write (modify th s :key1 val1 :key2 val2 :key3 val3) where the three keys identify fields in the state. To make it easier to read new concrete states, we may have a function that prints them ``relative'' to a given base state, expressing the new state as a modification of the given base state. So we may find ourselves prettyprinting modify forms like that above. The previous prettyprinter will sometimes print the form above as follows. (modify th s :key1 val1 :key2 val2 :key3 val3) This can be unpleasant to read, because of the way [47m:key1[0m and [47mval1[0m are separated. Here is an example of the old prettyprinter and the new one, both printing an expression from the ACL2 source code in a width of 40: Old: (ADD-TO-TAG-TREE 'ASSUMPTION (MAKE ASSUMPTION :TYPE-ALIST TYPE-ALIST :TERM TERM :REWRITTENP REWRITTENP :IMMEDIATEP IMMEDIATEP :ASSUMNOTES (LIST (MAKE ASSUMNOTE :CL-ID NIL :RUNE RUNE :TARGET TARGET))) TTREE) New: (ADD-TO-TAG-TREE 'ASSUMPTION (MAKE ASSUMPTION :TYPE-ALIST TYPE-ALIST :TERM TERM :REWRITTENP REWRITTENP :IMMEDIATEP IMMEDIATEP :ASSUMNOTES (LIST (MAKE ASSUMNOTE :CL-ID NIL :RUNE RUNE :TARGET TARGET))) TTREE) Basically the change we made forces the prettyprinter to print each [47m:key[0m on a new line unless they all fit on a single line. So we would now get either (modify th s :key1 val1 :key2 :val2 :key3 val3) or (modify th s :key1 val1 :key2 val2 :key3 val3) Furthermore, we fixed it so that if [47mval1[0m (say) is a big s-expression we may still print it on the same line as its key. The old prettyprinter enforced the rule that if you wanted to print [47m(foo a b)[0m and [47mb[0m gets broken up into several lines, then it has to start on a new line. Thus, we'd never print (foo a (bbb (mum x))) but would print instead (foo a (bbb (mum x))) Now, if a is a keyword, we can print the first way. So here are some nice examples of prettyprinted keyword forms. All of these are printed for a page of width 40. <-- 40 chars -> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (MODIFY TH S :KEY1 V1 :KEY2 V2) (MODIFY TH S :KEY1 V1 :KEY2 V2 :KEY3 V3) (MODIFY TH S1 ; Because of the extra char :KEY1 V1 ; in S1 the flat size exceeds :KEY2 V2 ; 40 and we break it. :KEY3 V3) The old ppr would have printed this as: (MODIFY TH S1 :KEY1 V1 :KEY2 V2 :KEY3 V3) Returning to new examples: <-- 40 chars -> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (MODIFY TH S :KEY1 (IF (IF X Y Z) AAAA BBBB) :KEY2 VAL2 :KEY3 VAL3) Now we extend [47mAAAA[0m and [47mBBBB[0m by one char each, so it would overflow the right margin if printed as above, and we get: <-- 40 chars -> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (MODIFY TH S :KEY1 (IF (IF X Y Z) AAAAX BBBBX) :KEY2 VAL2 :KEY3 VAL3) If we make these names even longer we force the value off the line containing [47m:key1[0m: (MODIFY TH S :KEY1 (IF (IF X Y Z) AAAAXXXXX BBBBXXXXX) :KEY2 VAL2 :KEY3 VAL3) Here are some examples from the ACL2 source code, printed in 40 characters: (DEFTHM ALPHORDER-ANTI-SYMMETRIC (IMPLIES (AND (NOT (CONSP X)) (NOT (CONSP Y)) (ALPHORDER X Y) (ALPHORDER Y X)) (EQUAL X Y)) :HINTS (("Goal" :IN-THEORY (UNION-THEORIES '(STRING< SYMBOL<) (DISABLE CODE-CHAR-CHAR-CODE-IS-IDENTITY)) :USE ((:INSTANCE SYMBOL-EQUALITY (S1 X) (S2 Y)) (:INSTANCE BAD-ATOM<=-ANTISYMMETRIC) (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C Y)) (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C X))))) :RULE-CLASSES ((:FORWARD-CHAINING :COROLLARY (IMPLIES (AND (ALPHORDER X Y) (NOT (CONSP X)) (NOT (CONSP Y))) (IFF (ALPHORDER Y X) (EQUAL X Y))) :HINTS (("Goal" :IN-THEORY (DISABLE ALPHORDER)))))) Here is that same one, printed in a width of 60. (DEFTHM ALPHORDER-ANTI-SYMMETRIC (IMPLIES (AND (NOT (CONSP X)) (NOT (CONSP Y)) (ALPHORDER X Y) (ALPHORDER Y X)) (EQUAL X Y)) :HINTS (("Goal" :IN-THEORY (UNION-THEORIES '(STRING< SYMBOL<) (DISABLE CODE-CHAR-CHAR-CODE-IS-IDENTITY)) :USE ((:INSTANCE SYMBOL-EQUALITY (S1 X) (S2 Y)) (:INSTANCE BAD-ATOM<=-ANTISYMMETRIC) (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C Y)) (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C X))))) :RULE-CLASSES ((:FORWARD-CHAINING :COROLLARY (IMPLIES (AND (ALPHORDER X Y) (NOT (CONSP X)) (NOT (CONSP Y))) (IFF (ALPHORDER Y X) (EQUAL X Y))) :HINTS (("Goal" :IN-THEORY (DISABLE ALPHORDER)))))) Just for comparison, here is the above printed in 60 columns by the old prettyprinter. (DEFTHM ALPHORDER-ANTI-SYMMETRIC (IMPLIES (AND (NOT (CONSP X)) (NOT (CONSP Y)) (ALPHORDER X Y) (ALPHORDER Y X)) (EQUAL X Y)) :HINTS (("Goal" :IN-THEORY (UNION-THEORIES '(STRING< SYMBOL<) (DISABLE CODE-CHAR-CHAR-CODE-IS-IDENTITY)) :USE ((:INSTANCE SYMBOL-EQUALITY (S1 X) (S2 Y)) (:INSTANCE BAD-ATOM<=-ANTISYMMETRIC) (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C Y)) (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C X))))) :RULE-CLASSES ((:FORWARD-CHAINING :COROLLARY (IMPLIES (AND (ALPHORDER X Y) (NOT (CONSP X)) (NOT (CONSP Y))) (IFF (ALPHORDER Y X) (EQUAL X Y))) :HINTS (("Goal" :IN-THEORY (DISABLE ALPHORDER)))))) Of course, given that you cannot tell for sure whether the keywords you're seeing are part of a keyword/value parameter list or part of some constant containing random keywords, the prettyprinter can't solve the problem perfectly. We just tried to make it work nicely on well-formed keyword/value parameter lists. For example, here is a form printed by each prettyprinter. Old: (MEMBER X '(:MONDAY :MON :TUESDAY :TUES :WEDNESDAY :WED :THURSDAY :THURS :FRIDAY :FRI :SATURDAY :SAT :SUNDAY :SUN)) New: (MEMBER X '(:MONDAY :MON :TUESDAY :TUES :WEDNESDAY :WED :THURSDAY :THURS :FRIDAY :FRI :SATURDAY :SAT :SUNDAY :SUN)) The new way is not how one would print it by hand! But then, neither is the old way.") (note-2-9-4 (release-notes) "ACL2 Version 2.9.4 (February, 2006) Notes Also see [note-2-9-1], see [note-2-9-2], and see [note-2-9-3] for other changes since the last non-incremental release (Version_2.9). A soundness bug has been fixed that was due to inadequate checking of [47m:[0m[47m[meta][0m rules in the presence of [47m[local][0m [events]. Specifically, a [47mlocal[0m [47m[defevaluator][0m event is insufficient for supporting a [47m:meta[0m rule (an example is shown in source function [47mchk-acceptable-rules[0m). Thanks to Dave Greve and Jared Davis for bringing this bug to our attention, by sending a proof of [47mnil[0m that exploited this bug. The fix is to check legality of [47m:meta[0m rules even when skipping proofs during an [47m[include-book][0m event or the second pass of an [47m[encapsulate][0m event. Fixed problem with parallel make for workshop books by adding a dependency line to [47mbooks/workshops/2003/Makefile[0m. Default hints (see [set-default-hints]) no longer prevent the use of [47m:INSTRUCTIONS[0m (see [proof-builder]). Thanks to Jared Davis for pointing out this problem. New functions [47m[remove-eq][0m and [47m[remove-equal][0m have been defined, in analogy to [47m[remove][0m. These two symbols have also been added to [47m*acl2-exports*[0m. Thanks to David Rager for pointing out that [47mremove-equal[0m was missing. Moreover, the definitions of [47mdelete1-eq[0m and [47mdelete1-equal[0m have been eliminated. Function [47mremove1-eq[0m, now in [47m:[0m[47m[logic][0m mode in source file [47maxioms.lisp[0m, serves in place of [47mdelete1-eq[0m, with corresponding new function definitions for [47m[remove1][0m and [47m[remove1-equal][0m. The symbol [47m[assert$][0m has been added to [47m*acl2-exports*[0m. Thanks to Jared Davis for the suggestion. Added SBCL support. Thanks to Juho Snellman for significant assistance with the port. Thanks to Bob Boyer for suggesting the use of feature [47m:acl2-mv-as-values[0m with SBCL, which can allow thread-level parallelism in the underlying lisp; we have done so when feature [47m:sb-thread[0m is present. We have continued to incorporate suggestions for wording improvements in documentation and error messages. Thanks to all who send these suggestions, especially to Eric Smith, who has suggested the vast majority of them. Made a small improvement to errors and warnings caused on behalf of [set-enforce-redundancy], to indicate when an event of the same name already exists. Fixed a bug in [47mbooks/misc/rtl-untranslate.lisp[0m that was causing a guard violation when adding a new entry for an existing key. Fixed a bug in translation to internal form that caused [47m[defun-sk][0m and [47m[defchoose][0m to have difficulties handling ignored variables in [47m[let][0m forms. Thanks to Sandip Ray for bringing this issue to our attention with a helpful example. The form [47m(push :acl2-mv-as-values *features*)[0m has been added in source file [47macl2-init.lisp[0m for SBCL and OpenMCL only, in order to support parallel execution (looking to the future...). Default-hints (see [set-default-hints]) were being ignored inside the [proof-builder], but no longer. Thanks to John Erickson for bringing this problem to our attention and providing a simple example of it. Modified the [47mTAGS[0m [47m"make"[0m target (specifically, function [47mmake-tags[0m) so that it is gracefully skipped if the [47metags[0m program is not found. Thanks to David Rager for pointing out this issue. Sandip Ray has re-worked the supporting materials for his ACL2 Workshop 2003 talk (originally with John Matthews and Mark Tuttle), to run in a few minutes. The result is in [47mworkshops/2003/ray-matthews-tuttle/support/[0m and is included in the full ACL2 regression suite. Thanks, Sandip. Debian releases of ACL2 had created superfluous [47m.cert.final[0m files when certifying books. This has been fixed; thanks to Jared Davis for noticing this problem. Jared Davis has pointed out that ``If you add a [47m:backchain-limit-lst 0[0m to a rewrite rule whose hypotheses are all forced, then ACL2 `really assumes them' without trying to relieve them right there through rewriting.'' Relevant documentation has been added for [47m:backchain-limit-lst[0m; see [rule-classes]. A new version of the rtl library has been included in [47mbooks/rtl/rel5/[0m. Thanks to David Russinoff for contributing hand proofs for the new lemmas, and to Matt Kaufmann for carrying out their mechanization. Fixed a bug in [47m[save-exec][0m that was failing to set the initial [47mcbd[0m according to the current directory when starting up ACL2. Thanks to Camm Maguire for bringing our attention to this problem. Variables introduced during [47mlet*[0m abstraction are now in the current package. Thanks to Jared Davis for suggesting such a change. See [set-let*-abstractionp]. It is now allowed for two definitions to be considered the same from the standpoint of redundancy (see [redundant-events]) when one specifies a [47m:[0m[47m[guard][0m of [47mt[0m and the other has no explicit [47m:guard[0m (hence, the guard is implicitly [47mt[0m). Thanks to Jared Davis for bringing this issue to our attention. (For users of [47memacs/emacs-acl2.el[0m) There have been a few enhancements to distributed file [47memacs/emacs-acl2.el[0m (skip this paragraph if you don't use that file): o [47mControl-t q[0m continues to compare windows ignoring whitespace, but now, a prefix argument can be given to control case is also ignored (ignore case if positive, else use case). o [47mControl-t Control-l[0m has been defined to be similar to [47mControl-t l[0m, except that proofs are skipped and output is suppressed. o [47mControl-t u[0m has been defined to print, to the shell buffer, a [47m:[0m[47m[ubt!][0m form for the command containing the cursor. o Control-t Control-f buries the current buffer. o [47mMeta-x new-shell[0m now puts the new shell buffer in [47mshell-mode[0m (thanks to David Rager for noticing this issue). Linear arithmetic has been modified so that we do not generate the equality [47m(equal term1 term2)[0m from the pair of inequalities [47m(<= term1 term2)[0m and [47m(<= term2 term1)[0m in the case that we would have to [47m[force][0m both [47mterm1[0m and [47mterm2[0m to be [47m[ACL2-numberp][0ms. Thanks to Dave Greve for providing a motivating example and to Robert Krug for providing a fix. The event [47m[delete-include-book-dir][0m had not been allowed inside [books] and [47m[encapsulate][0m forms. This was an oversight, and has been fixed. Sandip Ray has contributed a new library of books to support proofs of partial and total correctness of sequential programs based on assertional reasoning, in [47mbooks/symbolic/[0m. This work is based on the paper J. Matthews, J S. Moore, S. Ray, and D. Vroon, ``A Symbolic Simulation Approach to Assertional Program Verification,'' currently in draft form. In particular, the books include the macro [47mdefsimulate[0m, which automatically transforms inductive assertion proofs of correctness of sequential programs to the corresponding interpreter proofs. See the [47mREADME[0m in that directory. We have changed the implementation of [47m:dir :system[0m for [47m[ld][0m and [47m[include-book][0m. This change will not affect you if you build an ACL2 executable in the normal manner, leaving in place the [47mbooks/[0m subdirectory of the source directory; nor will it affect you if you download a GCL Debian binary distribution. The change is that if environment variable [47mACL2_SYSTEM_BOOKS[0m is set, then it specifies the distributed books directory, i.e., the directory determined by [47m:dir :system[0m. You may find it convenient to set this variable in your ACL2 script file (typically, [47msaved_acl2[0m). If it is set when you build ACL2, the generated script for running ACL2 will begin by setting [47mACL2_SYSTEM_BOOKS[0m to that value. Thanks to various people who have discussed this issue, in particular Jared Davis who sent an email suggesting consideration of the use of an environment variable, and to Eric Smith who helped construct this paragraph. (Note that this use of [47mACL2_SYSTEM_BOOKS[0m replaces the use of [47mACL2_SRC_BOOKS[0m described previously; see [note-2-9-1].) ACL2 now automatically deletes files [47mTMP*.lisp[0m created during the build process and created by [47m:[0m[47m[comp][0m. If you want these to be saved, evaluate [47m(assign keep-tmp-files t)[0m in the ACL2 loop or in raw Lisp. The [47mclean[0m target for the standard `make' process for certifying books (see [books-certification-classic]) will however delete all files [47mTMP*.*[0m. The [47mTMP[0m files discussed just above now generally include the current process ID in their names, e.g., [47mTMP@16388@1.lisp[0m instead of [47mTMP1.lisp[0m. Thanks to Bob Boyer for suggesting this measure, which will reduce the possibility that two different processes will attempt to access the same temporary file. Now, [47m:[0m[47m[pe][0m will print the information formerly printed by [47m:pe![0m, slightly enhanced to work for logical names that are strings, not just symbols. Thanks to Warren Hunt for leading us to this change by suggesting that [47m:pe nth[0m print the definition of [47m[nth][0m. We eliminated spurious warnings that could occur in raw mode in OpenMCL or CMUCL when [stobj]s are present. We thank Juho Snellman for pointing out the relevant bug and appropriate fix. [47mMfc-rw[0m now takes a third argument that can specify an arbitrary known equivalence relation; see [extended-metafunctions]. Thanks to Dave Greve for discussions suggesting this improvement. A small modification to a symbol-reading function allows documentation string processing on Windows systems that use CR/LF for line breaks. Thanks to William Cook for bringing this issue to our attention. The documentation has been improved on how to control the printing of ACL2 terms. See [user-defined-functions-table]. Thanks to Sandip Ray for asking a question that led to the example presented there. We fixed an inefficiency that could cause an [47m[ld][0m command to seem to hang at its conclusion. Thanks to Sandip Ray for pointing out this problem. We checked that ACL2 runs under LispWorks 4.4.5, and have inhibited redefinition warnings. Two changes have been made on behalf of congruence-based reasoning. Thanks to Dave Greve for examples and discussions that have led to these changes, and to Eric Smith and Vernon Austel, who also sent relevant examples. o When a call of the new unary function [47m[double-rewrite][0m is encountered by the rewriter, its argument will be rewritten twice. This solves certain problems encountered in congruence-based rewriting. Warnings for [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules will suggest when calls of [47m[double-rewrite][0m on variables in hypotheses are likely to be a good idea. See [double-rewrite]. o Hypotheses of the form [47m(equiv var (double-rewrite term))[0m, where [47mequiv[0m is a known [equivalence] relation and [47mvar[0m is a free variable (see [free-variables]), will bind [47mvar[0m to the result of rewriting [47mterm[0m twice. Previously, hypotheses of the form [47m(equal var term)[0m would bind a free variable [47mvar[0m, but the call had to be of [47mequal[0m rather than of an arbitrary known equivalence relation. The following improvements were made in support of ACL2 on top of OpenMCL. o New versions of OpenMCL that do not have [47m:mcl[0m in Lisp variable [47m*features*[0m will now work with ACL2. Thanks to David Rager for bringing this issue to our attention. o Added support for OpenMCL 1.0 for 64-bit DarwinPPC/MacOS X, thanks to Robert Krug. o Fixed tracing in OpenMCL so that the level is reset to 1 even if there has been an abort. o Added support in OpenMCL for [47mWET[0m. o Incorporated suggestions from Gary Byers for printing the ``Welcome to OpenMCL'' prompt before initially entering the ACL2 loop and, and for setting useful environment variable [47mCCL_DEFAULT_DIRECTORY[0m in the ACL2 script. Fixed a long-standing bug in forward-chaining, where variable-free hypotheses were being evaluated even if the [executable-counterpart]s of their function symbols had been disabled. Thanks to Eric Smith for bringing this bug to our attention by sending a simple example that exhibited the problem. Improved reporting by the [break-rewrite] utility upon failure to relieve hypotheses in the presence of free variables, so that information is shown about the attempting bindings. See [free-variables-examples-rewrite]. Thanks to Eric Smith for requesting this improvement. Also improved the [break-rewrite] loop so that terms, in particular from unifying substitutions, are printed without hiding subterms by default. The user can control such hiding (``evisceration''); see :DOC [47mset-brr-term-evisc-tuple[0m. A new directory [47mbooks/defexec/[0m contains books that illustrate the use of [47m[mbe][0m and [47m[defexec][0m. Thanks to the contributors of those books (see the [47mREADME[0m file in that directory). The directories [47mbooks/rtl/rel2[0m and [47mbooks/rtl/rel3[0m are no longer distributed. They are still available by email request. (Subdirectory [47mrel1/[0m supports some of the optional [47mworkshop/[0m books, so it is still distributed.) Added book [47mbooks/misc/sticky-disable.lisp[0m to manage [theories] that might otherwise be modified adversely by [47m[include-book][0m. Thanks to Ray Richards for a query that led to our development of this tool. The commands [47m(exit)[0m and [47m(quit)[0m may now be used to quit ACL2 and Lisp completely; in fact they macroexpand to calls of the same function as does [47m[good-bye][0m (which is now a macro). Thanks to Jared Davis for suggesting the new aliases. (OpenMCL-only comment:) These all work for OpenMCL even inside the ACL2 loop. The macro [47mwet[0m now hides structure by default on large expressions. However, a new optional argument controls this behavior, for example avoiding such hiding if that argument is [47mnil[0m. Thanks to Hanbing Liu for pointing out that [47mwet[0m was not helpful for very large terms. We have fixed a bug in the forward-chaining mechanism that, very rarely, could cause a proof to be aborted needlessly with an obscure error message. Thanks to Jared Davis for sending us an example that evoked this bug. Fixed a bug that was causing proof output on behalf of [47m:functional-instance[0m to be confusing, because it failed to mention that the number of constraints may be different from the number of subgoals generated. Thanks to Robert Krug for pointing out this confusing output. The fix also causes the reporting of rules used when silently simplifying the constraints to create the subgoals. Fixed a bug in handling of leading [47m./[0m in pathnames, as in: [47m(include-book "./foo")[0m. Thanks to Jared Davis for bringing this bug to our attention. Made a small fix for handling of free variables of [47m:[0m[forward-chaining] rules, which had erroneously acted as though a hypothesis [47m(equal var term)[0m can bind the variable [47mvar[0m. A small change has been made for [47m:[0m[47m[type-prescription][0m rules for hypotheses of the form [47m(equal var term)[0m, where [47mvar[0m is a free variable and no variable of [47mterm[0m is free (see [free-variables]). As with [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules, we now bind [47mvar[0m to [47mterm[0m even if [47m(equal u term)[0m happens to be known in the current context for some term [47mu[0m. Also as with [47m:rewrite[0m and [47m:linear[0m rules, similar handling is given to hypotheses [47m(equiv var (double-rewrite term))[0m where [47mequiv[0m is a known [equivalence] relation. We changed the handling of free variables in hypotheses of [47m:[0m[47m[rewrite][0m rules being handled by the [proof-builder]'s [47mrewrite[0m ([47mr[0m) command, in complete analogy to the change described just above for [47m:[0m[47m[type-prescription][0m rules. The installation instructions have been updated for obtaining GCL on a Macintosh. Thanks to Robert Krug for supplying this information and to Camm Maguire for simplifying the process by eliminating the [47mgettext[0m dependency. The macro [47m[comp][0m is now an event, so it may be placed in [books]. Previously, a [47m[save-exec][0m call could fail because of file permission issues, yet ACL2 (and the underlying Lisp) would quit anyhow. This has been fixed. Thanks to Peter Dillinger for bringing this problem to our attention. Jared Davis, with assistance from David Rager, has updated his ordered sets library, [47mbooks/finite-set-theory/osets/[0m. See file [47mCHANGES.html[0m in that directory. A new function, [47m[reset-kill-ring][0m, has been provided for the rare user who encounters memory limitations. See [reset-kill-ring].") (note-2-9-5 (release-notes) "Changes in Version 3.0 since Version 2.9.4 Fixed a bug in [47m[cw-gstack][0m that was causing a hard error when attempting to report on a forced assumption. Thanks to Jared Davis for pointing this out and sending an example that helped us to determine a fix. Added [47m[set-backchain-limit][0m to the set of legal [events] that can be placed in [47m[encapsulate][0m forms and [books]. Thanks to John Cowles for bringing this issue to our attention. Fixed a bug that broke [47mwet[0m. Thanks to David Rager for bringing this bug to our attention. Guard verification now evaluates ground subexpressions (those with no free variables) when computing the guard conjecture for the body of a function. Thanks to Jared Davis for useful conversations leading to this change. See [verify-guards], in particular its ``Note on computation of guard conjectures and evaluation'' near the end of that topic, for more details. Added a warning when a [47m[theory-invariant][0m is redefined. Thanks to Jared Davis for suggesting a warning in this case and providing an informative example. Also, [47m[theory-invariant][0ms are now maintained more completely, as they are checked at the end of every event except for events executed on behalf of an [47m[include-book][0m or the second pass of an [47m[encapsulate][0m. Fixed the handling of runic designators to match their specification (see [theories]), so that disabling the name of a [47m[defthm][0m event [47m[disable][0ms all rules generated for that event. (For those who do numerous builds using feature [47m:acl2-mv-as-values[0m, currently only OpenMCL and multi-threaded SBCL by default:) You can speed up builds by adding the following parameter to `make', under conditions described in [47mGNUmakefile[0m: [47mUSE_ACL2_PROCLAIMS=:REUSE[0m. Arranged that traced functions (see [trace$]) are automatically untraced when events are undone (for example see [ubt]), at least for most underlying Common Lisp implementations. The macro [47m[defun-sk][0m now creates non-executable functions, which allows [47m[stobj][0ms to be used where they had previously been prohibited. More generally, the user now has control over [47m[declare][0m forms to be used by the underlying [47m[defun][0m'd function; see [defun-sk]. Thanks to Sandip Ray for pointing out the need for such a modification. [47m:[0m[47m[Definition][0m rules are now treated, at least by default, as truly first-class definitions. In particular, [47m:expand[0m [hints] use the latest [47m:[0m[47m[definition][0m rule by default. You may specify [47m:install-body nil[0m to get the previous behavior of [47m:definition[0m rules; See [definition], and you may choose a previously-installed [47m:definition[0m rule to provide the current body; see [set-body]. Also see [rule-classes] for details of the [47m:install-body[0m field, and see [hints] to see a new [47m:with[0m directive for controlling expansion. The [47m:with[0m directive for [47m:expand[0m hints can even direct the use of a [47m:[0m[47m[rewrite][0m rule for expansion! Thanks to various people, including Sandip Ray and Rob Sumners, for discussions on the issue of the applicability of [47m:definition[0m rules for [47m:expand[0m [hints]. [Constraint]s for functional instantiation now use the original definition rather than a simplified (``normalized'') version of it. Fixed a bug that caused the prompt to stay the same when guard-checking is off (see [set-guard-checking]) and raw-mode is changed (see [set-raw-mode]). Lemma names in directory [47mbooks/ordinals[0m have been changed by replacing [47m/\[0m with [47m&[0m and replacing [47m\/[0m with [47mV[0m. We made this change because backslash is an escape character and hence disappears unless it is itself escaped. Fixed [proof-tree] output so that failed non-proof events do not cause the proof-tree to be re-printed. Thus for example, if you have already advanced the checkpoint marker, it will not be reset by subsequent failed non-proof events. Thanks to Pete Manolios and Peter Dillinger for bringing this bug to our attention. Fixed a bug that was preventing the printing of [stobj] fields as constants instead of numbers in certain cases. (Note that this bug only affected printing, not soundness.) Thanks to Eric Smith for bringing this problem to our attention and providing the following example (which now works fine). (defstobj st fld1 fld2) (in-theory (disable update-nth)) (defund run (st) (declare (xargs :stobjs (st))) ;adding this didn't seem to help.. st) ;works great; *fld1* prints as *fld1* (thm (equal (update-nth *fld1* 'abc st) (car (cons x y)))) ;*fld1* gets printed as 0, presumably because the call to run intervenes. (thm (equal (update-nth *fld1* 'abc (run st)) (car (cons x y)))) The macro [47m[progn][0m now allows the use of macros defined within its bodies even when at the event level, as illustrated by the following example. (progn (defmacro my-defun (&rest args) `(defun ,@args)) (my-defun g (x) x)) Thanks to Anna Slobodova for bringing this issue to our attention. A related change is that all arguments of [47m[progn][0m must now be embedded event forms (see [embedded-event-form]), so use [47m[er-progn][0m instead if this is not the case. The change to [47m[progn][0m mentioned above also fixes a bug in handling [local] events inside a [47m[progn][0m that is inside an [47m[encapsulate][0m or in a book. For example, the following form formerly caused an error. (encapsulate () (defun foo (x) x) (progn (local (defun bar (x) x)) (defun abc (x) x))) We fixed two bugs in [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m. The first, brought to our attention by Eric Smith (who we thank), caused a cryptic error message when puffing a command with no subsidiary stored events; try, for example, [47m(encapsulate () (value-triple 3))[0m. The second was due to a failure to restore the [47m[ACL2-defaults-table][0m. Suppose for example that we have certified the book [47mfoo.lisp[0m, which contains [47m([0m[47m[program][0m[47m)[0m followed by some definitions and/or theorems. Now suppose we start ACL2 and execute the following. (include-book "foo") (defthm test-thm (equal x x) :rule-classes nil) If we now execute [47m:[0m[47m[puff][0m[47m 1[0m, ACL2 will roll back the world to before the [47m[include-book][0m; then ``puff'' the include-book, which will leave us in [47m:[0m[47m[program][0m mode; and finally skip re-execution of the [47m[defthm][0m because such [events] are skipped in [47m:[0m[47m[program][0m mode. The fix is to re-install the [47m[ACL2-defaults-table][0m immediately after the [47m[include-book][0m to its pre-[47m[include-book][0m value. A new event, [47m[make-event][0m, provides something like macros that take state. For example, one can use it to put tests into certified books, do proof search, and generate new function names. Many examples appear in directory [47mbooks/make-event/[0m. See [make-event]. Thanks to Bob Boyer and Jared Davis for useful feedback and to Warren Hunt, David Rager, and Sandip Ray for helpful discussions leading to some of the examples in directory [47mbooks/make-event/[0m. In support of [47m[make-event][0m, which is described in the preceding paragraph, [47mcertify-book[0m has a new keyword argument, [47m:save-expansion[0m, that controls whether the result of expanding [47m[make-event][0m forms is written out to a file. See [certify-book]; and for a discussion of book expansion files, see [make-event]. We fixed a soundness bug that did not correctly detect [47m[local][0m events. For example, the following event was admitted. (encapsulate () (local (encapsulate () (local (progn (program))) ; or, (local (with-output :off summary (program))) (set-irrelevant-formals-ok t) (defun foo (x) (declare (xargs :measure (acl2-count x))) (1+ (foo x))))) (defthm inconsistent nil :hints (("Goal" :use foo)) :rule-classes nil)) A new value for [guard] checking, [47m:none[0m, is now allowed. If you execute [47m:[0m[47m[set-guard-checking][0m[47m :none[0m, then no guard checking will take place (but raw Lisp code will not be executed in this case). As a result, you should never see a guard violation, even for calls of [47m:[0m[47mprogram[0m mode functions. We thank Pete Manolios, who has long wanted this feature, and also Peter Dillinger, for asking for it. New documentation explains the interaction between the [defun-mode] and the value supplied to [47m:[0m[47m[set-guard-checking][0m. See [guard-evaluation-table], see [guard-evaluation-examples-script], and see [guard-evaluation-examples-log]. In the course of adding the [guard]-checking value [47m:none[0m described in the paragraph above, we eliminated an optimization that eliminated guard checking for some recursive calls of [47m:[0m[logic] mode mutually-recursive functions that have not had their guards verified. But we doubt that this change will be noticed by any users!) The ACL2 hyper-card has been enhanced, thanks to David Rager, with a listing of ``Useful EMACS Commands'' to match comments in [47memacs/emacs-acl2.el[0m. Users contributed books following the [47mReadme.lsp[0m methodology: [47mdata-structures/memories[0m and [47municode[0m (Jared Davis), [47mproofstyles[0m (Sandip Ray and J Moore). Made some improvements to [47mbooks/Makefile-generic[0m (a file discussed elsewhere; see [books-certification-classic]). In particular, improved handling of [47m.acl2[0m files for [47mdependencies[0m target. (Only OpenMCL and, with feature [47m:acl2-mv-as-values[0m, GCL) Fixed a bug that was causing proclaiming to fail when definitions are submitted interactively. The default stack size has been increased for several lisps. (Very technical) A restriction has been weakened on the use of [47m[local][0m [stobj]s under a call of an ACL2 evaluator ([47mtrans-eval[0m or [47msimple-translate-and-eval[0m). Now, the error can only take place for [47m[stobj][0m names that occur in the term being evaluated. Thanks to Erik Reeber for bringing this issue to our attention. The notion of ``ancestor'' has been changed slightly. This notion is used by extended metafunctions and [break-rewrite] (see [extended-metafunctions] and see [brr@]), and also with backchain limits (see [backchain-limit] and see [set-backchain-limit]). Basically, each time a hypothesis is encountered during application of a [rewrite] rule, that hypothesis is pushed (after instantiating and negating) onto the current list of ancestors before it is rewritten. However, hypotheses of the form [47m(equal var term)[0m, where [47mvar[0m is free (see [free-variables]), had not been included in the ancestors (similarly for [47m(equiv var (double-rewrite term))[0m where [47mequiv[0m is a known [equivalence] relation). Now such ``binding hypotheses'' are included in a special way in ancestors data structures. In particular, [47m(null (mfc-ancestors mfc))[0m will now be true if and only if the term being rewritten is part of the current goal as opposed to a hypothesis from a rule encountered during backchaining, even if that hypothesis is a binding hypothesis. Thanks to Dave Greve for bringing this issue to our attention. Termination and induction analysis now continue through both arguments of [47m[prog2$][0m, not just the second. (Normally, the gathering up of [47m[if][0m tests stops at function calls; but it continued through the second argument of [47m[prog2$][0m, and now it will continue through both arguments.) Thanks to Sol Swords for discussion leading to this change. The ACL2 distribution is now kept on the http server rather than the ftp server (but the home page has not been moved). Thanks to Robert Krug for letting us know that some ACL2 users have found it inconvenient to fetch ACL2 using ftp. The file [47mbooks/README.html[0m has been renamed to [47mbooks/Readme.html[0m, since some browsers don't show the former in the directory listing.") (|NOTE-2-9{R}| (release-notes) "ACL2 Version 2.9(r) (October, 2004) Notes No changes have been made for support of non-standard analysis, other than a minor modification or two in [47mbooks/nonstd/[0m books. Please also see [note-2-9] for changes to Version_2.9 of ACL2.") (note-3-0 (release-notes) "ACL2 Version 3.0 (June, 2006) Notes Please see [note-2-9-5] for a description of changes since Version 2.9.4. These include the new [47m[make-event][0m feature, a soundness bug fix, an improvement for [47m:expand[0m [hints], evaluation in the logic by way of [47m:[0m[47m[set-guard-checking][0m[47m :none[0m, and many other improvements. More generally, there have been several incremental releases since Version 2.9: see [note-2-9-1], see [note-2-9-2], see [note-2-9-3], see [note-2-9-4], and see [note-2-9-5]. A very few users have contributed books following the instructions on the web. We expect that when more contributions come in, we will give more attention to the question of how to organize the distributed and workshop books. For now, we have simply added the new contributions according to the old-style distribution methodology.") (note-3-0-1 (release-notes) "ACL2 Version 3.0.1 (August, 2006) Notes NOTE! New users can ignore these release notes, because the documentation has been updated to reflect all changes that are recorded here. Fixed a soundness bug, introduced in the previous release, due to a failure to disallow [47m[table][0m [events] that set the [47m[ACL2-defaults-table][0m in a [47m[local][0m context. Here is a proof of [47mnil[0m that exploits the bug. (encapsulate () (local (program)) (defun foo () (declare (xargs :measure 17)) (+ 1 (foo)))) (thm nil :hints (("Goal" :in-theory (disable foo (foo)) :use foo))) Fixed a bug in the alternatives to [47m[good-bye][0m, which are the [47m[exit][0m and [47m[quit][0m commands. Thanks to Jared Davis and Peter Dillinger for pointing this out right away. The definition of [47m[len][0m has been highly optimized in raw Lisp. Thanks to Bob Boyer and Warren Hunt for suggesting such an improvement and providing a lot of help in coming up with the current implementation. The clause subsumption algorithms have been improved, both to improve efficiency during warnings for [47m:[0m[47m[rewrite][0m rules and to punt when the subsumption computation for induction appears to be blowing up. Thanks to Robert Krug for bringing this issue to our attention and supplying a useful example. A bug has been fixed that prevented [47m[time$][0m from working properly in OpenMCL and multi-threaded SBCL (actually, in any ACL2 image where feature [47m:acl2-mv-as-values[0m is present). Thanks to Sol Swords for bringing this problem to our attention. A [type-spec] of the form [47m(satisfies pred)[0m carries the requirement that [47mpred[0m be a unary function symbol in the current ACL2 [world]; otherwise, it is illegal. Thanks to Dave Greve for pointing out that Common Lisp has this requirement. Installed a fix provided by Gary Byers (for ACL2 source function [47minstall-new-raw-prompt[0m), for OpenMCL, that fixes an issue exposed in some versions of OpenMCL when compiler optimization is off. Fixed a bug in contributed book [47mmisc/untranslate-patterns.lisp[0m that was causing calls of [47madd-untranslate-pattern[0m to be rejected in [books]. Thanks to Ray Richards for pointing out this bug and to Jared Davis for assisting in the fix. Fixed a bug in [47m[defstobj][0m when keywords [47m:initially[0m and [47m:resizable[0m are both supplied. In this case, the definition of the resizing function mistakenly failed to quote the [47m:initially[0m value, even though this value is not to be evaluated. One could even get an error in this case, as in the following example supplied by Erik Reeber, whom we thank for bringing this bug to our attention: (defstobj $test (test-x :type (array t (5)) :initially (0) :resizable t)) A new feature, [47m[with-prover-time-limit][0m, allows the setting of time limits during proofs. This is [31;1mnot[0m a general-purpose time-limit utility, nor is it guaranteed to implement a strict bound; it only attempts to limit time approximately during proofs. Thanks to Pete Manolios and Daron Vroon, who made the most recent request for such a feature, and to Robert Krug for a helpful discussion. (GCL only) Fixed a bug in the procedure for building a profiling image. Thanks to Sol Swords for bringing this bug to our attention and to Eric Smith for bringing a subsequent problem to our attention. Handling of [theories] can now use significantly less time and space. A regression suite run took about 25% longer before this change than it did after making this change (and also the ones in the next two paragraphs). Thanks to Vernon Austel for bringing this issue to our attention and for supplying code, quite some time ago, that provided detailed, useful implementation suggestions. Also thanks to the folks at Rockwell Collins, Inc. for pushing the limits of the existing implementation, thus encouraging this improvement. Fixed a performance bug in obtaining executable counterpart symbols. We now avoid certain computations made on behalf of warnings, when such warnings are disabled. We have relaxed the checks made when including an uncertified book, to match the checks made when including a certified book. Thanks to Eric Smith for suggesting this change. Fixed a bug in [47m:[0m[47m[pso][0m (see set-saved-output) that caused an error when printing the time summary. Made fixes to avoid potential hard Lisp errors caused by the use of [47m:[0m[47m[program][0m mode functions. The fix was to use a ``safe mode,'' already in use to prevent such errors during macroexpansion; see [guards-and-evaluation]. However, such errors were possible during evaluation of macro [guard]s, for example as follows: (defun foo (x) (declare (xargs :mode :program)) (car x)) (defmacro mac (x) (declare (xargs :guard (foo 3))) x) (defun g (x) (mac x)) A similar issue existed for calls of [47m[defpkg][0m, [47m[in-theory][0m, [47m[table][0m, [47m[make-event][0m, and [47mvalue-triple[0m, but has been fixed for all but [47min-theory[0m and [47mmake-event[0m, where technical issues have caused us to defer this change. Fixed a bug in [47mwet[0m that caused problems in OpenMCL, and perhaps other Lisp implementations, when the argument to [47mwet[0m calls, or depends on, certain built-ins including [47m[prog2$][0m, [47m[time$][0m, [47m[mbe][0m, and [47m[must-be-equal][0m. Thanks to David Rager for bringing this problem to our attention. The file [47mbooks/Makefile-generic[0m has been improved so that when book certification fails with `make', the failure message contains the book filename. Documentation has been written to explain how to avoid an expensive immediate rewrite of the result of applying a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[meta][0m rule. See [meta]. Thanks to Robert Krug for supplying this trick, and to Eric Smith and Dave Greve for useful discussions. (OpenMCL only) OpenMCL-based ACL2 image names formerly had extension [47m".dppccl"[0m, which was correct only for some platforms (including 32-bit Darwin PPC). That has been fixed, thanks to a suggestion from Gary Byers. It is now legal to attach both a [47m:use[0m and a [47m:cases[0m hint at the same goal. Thanks to Eric Smith for (most recently) requesting this feature. It is now permissible to include the same symbol more than once in the imports list of a [47m[defpkg][0m form (i.e., its second argument). Also, the evaluation of [47m[defpkg][0m forms with long import lists now uses a reasonably efficient sorting routine to check for two different symbols with the same name (see also [47mbooks/misc/sort-symbols.lisp[0m). If you currently call a function like [47mremove-duplicates-eql[0m for your imports list, as had been suggested by a [47m[defpkg][0m error message, then you may experience some speed-up by removing that call. Thanks to Eric Smith for helping to discover this issue through profiling. Made miscellaneous efficiency improvements not listed above (for example, following a suggestion of Eric Smith to avoid checking for so-called ``bad Lisp objects'' during [47m[include-book][0m, which saved almost 3% in time on one large example). Modified the notion of ``untouchable'' to separate the notion of untouchable functions and macros from the notion of untouchable state global variables. See [push-untouchable]. Thanks to Bob Boyer for sending an example, [47m(put-global 'ld-evisc-tuple t state)[0m, that suggested to us the need for more restrictive handling of untouchables. In particular, many [47mld[0m specials (see [ld]) are now untouchable. You may be able to work around this restriction by calling [47m[ld][0m; see for example the change to [47mbooks/misc/expander.lisp[0m. But please contact the ACL2 implementors if this sort of workaround does not appear to be sufficient for your purposes. Fixed a bug in function [47mset-standard-oi[0m (see [standard-oi]). Fixed a bug in the use of [47m[ld-evisc-tuple][0m. The bad behavior was an improper use of the print-level and print-length components of the tuple (specifically, taking its [47m[caddr][0m and [47m[cadddr][0m instead of taking its [47m[cadr][0m and [47m[caddr][0m). Thanks to Bob Boyer for bringing this bug to our attention. A new argument to the [47mcompile-flg[0m argument of [47m[certify-book][0m, [47m:all[0m, causes creation of a file to be compiled in place of the given book, where that file contains not only a copy of the book (with [47m[make-event][0m forms expanded) but also contains definitions of the so-called ``executable counterparts'' of the functions defined in the book. Then, functions defined in the book will be run compiled when including the book, even for functions whose [guard]s have not been verified, or are in [47m:program[0m mode and running in so-called ``safe mode'' (for example, during expansion of macros). The default behavior, value [47mt[0m of [47mcompile-flg[0m, is unchanged. Moreover, a new [47m:comp![0m argument of [47m[include-book][0m now compiles the executable counterparts when creating the book's compiled file, and unlike [47m:comp[0m, always deletes the old compiled file first so that one always gets a fresh compile. Now, [47m[certify-book][0m gives a "Guards" warning only for [47m:[0m[47m[logic][0m mode functions that are defined in the given book but have not had their guards verified. Previously, it also warned about such functions that were defined in the certification world or in sub-books. A new command, [47m[redo-flat][0m, facilitates the debugging of failed [47m[encapsulate][0m and [47m[progn][0m forms by evaluating preliminary forms in order to leave one at the point of failure. See [redo-flat]. Thanks to Ray Richards and others for asking for such a utility, and to Sandip Ray for useful discussions. We have changed the automatic declaration of function types (still done in GCL and OpenMCL only, for now). Our motivation was to avoid the assumption that Common Lisp functions return one value when ACL2 says that they do; thanks to Bob Boyer for bringing this issue to our attention with the example of defining [47m(foo x y)[0m to be [47m(floor x y)[0m. ACL2 was saying that [47mfoo[0m returns a single value, but because [47mfloor[0m returns two values in raw Lisp, so does [47mfoo[0m. Other changes to automatic declaration include comprehending [47m[defund][0m, not just [47m[defun][0m. A new function, [47m[mod-expt][0m, computes [47m(mod (expt base exp) m)[0m, and does so efficiently in some implementations (currently only in GCL 2.7.0, which is not yet released). Thanks to Warren Hunt for suggesting such an addition. New functions [47m[getenv$][0m and [47m[setenv$][0m have been made available for reading and writing environment variables. Thanks to Jun Sawada for requesting these utilities. The query utility [47m:[0m[47m[pl][0m has been improved in several ways. As before, [47m:[0m[47m[meta][0m rules are only printed if the argument is a symbol; but the information printed for them is now more appropriate. The following are changes for the case that the argument is not a symbol, but rather, a term. (1) Rules are displayed that have [equivalence] relations other than [47m[equal][0m. (2) All matching [47m:[0m[47m[definition][0m rules are displayed, where previously [47m:definition[0m rules were only shown if they were ``simple'' rules (sometimes known as ``abbreviations''); see [simple]. (3) The ``Equiv'' field is printed for terms, not just symbols. (4) The substitution is shown that, when applied to the left-hand side of the rule, will yield the specified term. Thanks to Eric Smith for suggesting these changes. The [proof-builder] command [47m;show-rewrites[0m has been improved to match the changes described above for [47m:[0m[47m[pl][0m. In particular, [47m:[0m[47m[definition][0m rules that are not ``[simple]'' are now displayed by the [proof-builder]'s [47mshow-rewrites[0m (and [47msr[0m) command, and the [proof-builder]'s [47mrewrite[0m command has been correspondingly modified to accept these [47m:definition[0m rules. Fixed `make' targets [47mcopy-distribution[0m, [47mcopy-workshops[0m, and [47mcopy-nonstd[0m so that they should also work for non-developers. Fixed a bug that was causing [47m:[0m[47m[pr][0m to display [47m[syntaxp][0m hypotheses oddly in some cases, in particular [47m(syntaxp (let ...))[0m. (The problem was in the ``untranslate'' display of the internal form of [47msyntaxp[0m calls.) Thanks to Robert Krug for bringing this problem to our attention. We also removed the restriction on [47m[bind-free][0m that its argument could not be a variable, a constant, or (more interestingly) a [47m[lambda][0m application (i.e., a [47m[let][0m or [47m[mv-let][0m expression).") (|NOTE-3-0-1{R}| (release-notes) "ACL2 Version 3.0.1(r) (August, 2006) Notes No significant changes have been made since Version 3.0 for support of non-standard analysis in particular. Please also see [note-3-0-1] for changes to Version 3.0.1 of ACL2.") (note-3-0-2 (release-notes) "ACL2 Version 3.0.2 (December, 2006) Notes NOTE! New users can ignore these release notes, because the documentation has been updated to reflect all changes that are recorded here. Fixed soundness bugs in the handling of primitive function [47m[pkg-witness][0m, and improved its documentation. (The executable counterpart returned an incorrect default value, and the axiom [47msymbol-package-name-pkg-witness-name[0m needed [47mpkg-name[0m to be other than [47m""[0m in order to avoid the default value of "ACL2".) As fallout, a new built-in [47m:[0m[47m[forward-chaining][0m rule, [47msymbol-package-name-of-symbol-is-not-empty-string[0m, now asserts that the [47m[symbol-package-name][0m of a symbol is never [47m""[0m. Thanks to Mike Gordon for bringing these soundness bugs to our attention by attempting to prove translations of ACL2 axioms in HOL4. Fixed a soundness bug in linear arithmetic, due to incomplete tracking of forced assumptions while deriving inequalities. Thanks to Robert Krug for providing a fix and a proof of [47mnil[0m before the fix. Fixed a soundness bug in the redundancy criterion for [47m[defun][0m events, which has been modified; see [redundant-events]. This bug is illustrated below. Thanks to Peter Dillinger and Jared Davis for contributions to an email thread that led us to discover this bug. The solution is that for a definition to be redundant with an earlier definition, ACL2 no longer ignores [47m:[0m[47m[measure][0m [47m[xargs][0m except when skipping proofs (e.g., during [47m[include-book][0m). However, a new ``measure'', [47m(:? v1 ... vk)[0m, is supported, for specifying a measured subset of the set of formals, i.e., a set of formals that serves as the set of parameters for some valid measure. (encapsulate () (local (defun foo (x y) (declare (xargs :measure (acl2-count y))) (if (and (consp x) (consp y)) (foo (cons x x) (cdr y)) y))) ; So the following is redundant -- but it guesses a measure ; of (acl2-count x), which isn't right! (defun foo (x y) (if (and (consp x) (consp y)) (foo (cons x x) (cdr y)) y))) ; end of encapsulate ; Now we prove a non-theorem by exploiting the bug above, ; erroneously replacing formal y by a constant in the induction ; scheme hinted below. (This should not be allowed, as y should be ; labeled as a measured formal.) (defthm bad (atom x) :rule-classes nil :hints (("Goal" :induct (foo x '(3))))) ; It's easy to get a contradiction by instantiating the ; non-theorem just above. (defthm contradiction nil :rule-classes nil :hints (("Goal" :use ((:instance bad (x '(7))))))) Fixed a bug in [47m:[0m[47m[pl][0m and the [proof-builder]'s [47mshow-rewrites[0m ([47msr[0m) command that was causing a Lisp break. For [47m:[0m[47m[pl][0m, also improved the display of unifying substitutions, modified output to take binding hypotheses [47m(equal var term)[0m into account properly, and arranged for inclusion of [meta] rules that modify the given term. Thanks to Eric Smith for bringing these issues to our attention. Introduced new utilities for undoing [command]s, [47m:[0m[47m[ubu][0m and [47m:[0m[47m[ubu!][0m, which are analogous to [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubt!][0m (respectively) except that they only undo back up to, but not including, the indicated command. Fixed a performance bug, pointed out by Eric Smith, that was negating efforts made for the preceding release to avoid computation for disabled warnings. Added [47m[time$][0m and [47mvalue-triple[0m to [47m*acl2-exports*[0m. Thanks to Bob Boyer and Erik Reeber (respectively) for bringing these issues to our attention. Improved the automatic proclaiming of function types for GCL and OpenMCL, specifically to use an output format consistent with the Common Lisp spec. Thanks to Bob Boyer for bringing this issue to our attention. Added [47mbooks/misc/transfinite.lisp[0m, which deals with transfinite induction in ACL2. Thanks to Eric Smith for contributing this book. Added [47mbooks/misc/process-book-readme.lisp[0m to the distribution. Thanks to Sandip Ray for pointing out its omission. Added contributions [47mbooks/concurrent-programs/bakery/[0m and [47mbooks/concurrent-programs/german-protocol/[0m. These contributions can be used as tutorials, especially by new ACL2 users, for learning how to model concurrent protocols in ACL2 and the steps involved in reasoning about their correctness. Thanks to Sandip Ray for these contributions. See the [47mReadme.lsp[0m files in these directories. Theory invariants may now involve the variable [47mENS[0m instead of the variable [47mTHEORY[0m. The practical effect of this change is that any expression of the form [47m(MEMBER-EQUAL rune THEORY)[0m occurring in a [47m[theory-invariant][0m expression should be replaced by [47m(ACTIVE-RUNEP rune)[0m. See [theory-invariant]. Thanks to Eric Smith and Dave Greve for pointing out an inefficiency in the handling of theory invariants that led to this change, which can speed up their handling by orders of magnitude on large examples, and to Eric for testing this change and pointing out problems with an early implementation of it. Theory invariants (see [theory-invariant]) are no longer checked on theories defined by [47m[deftheory][0m [events]. After all, one can define a theory with [47mdeftheory[0m that is not intended to be used as the current theory, but rather is intended to be combined with other [theories] (see [theory-functions]). Thanks to Eric Smith for bringing this issue to our attention. [47m[Theory-invariant][0m errors had been reported with very little detail when warnings were inhibited. This problem has been fixed; thanks to Eric Smith for bringing it to our attention and providing an example. We have also improved the handling of redundancy for [47m[theory-invariant][0m [events]. The macro [47m[defun-sk][0m now has a new optional keyword, [47mrewrite[0m, that can be used to change the form of the [47m:[0m[47m[rewrite][0m rule generated when the quantifier is [47m[forall][0m. Thanks to Eric Smith and Sandip Ray for useful discussions on this topic. We have also slightly modified the [hints] for the [47m[defthm][0m event underneath a [47mdefun-sk[0m in order to make the proof more reliably efficient. A new event, [47m[reset-prehistory][0m, allows setting of a barrier before which undoing is illegal. An argument to this macro allows the barrier to be made permanent; otherwise, it can be removed with [47m:[0m[47m[ubt-prehistory][0m. Thanks to Peter Dillinger for useful conversations leading to the addition of [47m[reset-prehistory][0m. A new query, [47m([0m[47m[wormhole-p][0m[47m [0m[47m[state][0m[47m)[0m, allows users to determine whether or not they are in a [47m[wormhole][0m. Thanks to Peter Dillinger for providing this utility. [47mValue-triple[0m no longer evaluates its form during [47m[include-book][0m, and in raw Lisp its calls trivially macroexpand to [47mnil[0m, without any consideration of its argument. This change avoids errors and warnings when [stobj] names occur in the argument. We fixed what could be considered a soundness hole that could occur by exploiting redefinition in a particular way. Thanks to Peter Dillinger for raising a question that led to discovery of this hole. A bug has been fixed in handling of illegal [theory] expressions. Thanks to Eric Smith, who reported this problem and provided the example [47m(in-theory '((:definition natp) (:rewrite doesntexist)))[0m to show how a hard error could occur. Improved error reporting by [47m[certify-book][0m when the certification [world] contains inadmissible forms. Modified [47m[defchoose][0m to add two new keyword arguments. There is now a [47m:doc[0m keyword argument; previously, an optional documentation string (see [47mdoc-string[0m) was to be placed just before the body, without a keyword. There is also a [47m:strengthen[0m argument that strengthens the axiom added, which allows for the definition of ``fixing'' functions for equivalence relations that choose canonical representatives of equivalence classes. See [defchoose]. Thanks for Dave Greve for useful discussions that led us to this [47m:strengthen[0m enhancement. Added [47mbooks/misc/bash.lisp[0m, which provides utilities for simplifying a goal into a list of subgoals (as documented at the top of that file). Thanks to Dave Greve for requesting this utility and suggesting refinements to its functionality, which have been incorporated. (For Emacs users only) The command [47mmeta-x new-shell[0m provided by file [47memacs/emacs-acl2.el[0m now puts you in shell-mode, which for example supports directory tracking. Thanks to Jared Davis for suggesting this change. Fixed some mishandling of [stobj]s by [47m[make-event][0m expansion. Introduced a new event, [47m[defttag][0m, that introduces a ``trust tag'' (``ttag'') allowing for extensions of ACL2 and for the use of generally unsafe ACL2 constructs. Thanks to Peter Dillinger, Sandip Ray, and Erik Reeber for useful discussions on [47mdefttag[0m and the following related items. A new event, [47m[remove-untouchable][0m, can be used to give users access to system functions and data structures. We also fixed a bug in [47m[push-untouchable][0m; and, it no longer is a no-op in [47m:[0m[47m[program][0m mode. Thanks to Peter Dillinger for proposing [47m[remove-untouchable][0m and suggesting that it and [47m[push-untouchable][0m be functional in [47m:[0m[47m[program][0m mode. Raw-mode (see [set-raw-mode]) no longer disables [47m[certify-book][0m. However, [47m[set-raw-mode][0m is now disallowed unless there is an active ttag (see [defttag]). If you want to execute [47m([0m[47m[set-raw-mode][0m[47m t)[0m and there is no active ttag, consider executing [47m([0m[47m[set-raw-mode-on!][0m[47m)[0m instead. Redefinition of system functions is disallowed unless there is an active ttag. However, [47m[redef!][0m now introduces [47m(defttag :redef!)[0m in order to allow redefinition of system functions. A new event, [47m[progn!][0m, is a legal embedded event form that can go in [books] and both [47m[encapsulate][0m and [47m[progn][0m forms (see [embedded-event-form]), and is similar to [47m[progn][0m except that it allows arbitrary forms. Thus, a [47m[progn!][0m form is potentially dangerous and can only be evaluated if there is an active ttag. See [ttags-seen] for information about how to find the ttags known in the current ACL2 [world], and for related caveats. A new book created with Peter Dillinger, [47mbooks/misc/hacker.lisp[0m (added after Version_3.3: now [47mbooks/hacking/hacker.lisp[0m), uses [47m[progn!][0m to define utilities [47mwith-raw-mode[0m and [47mwith-redef-allowed[0m, which respectively allow raw Lisp evaluation and redefinition to take place within a certifiable book (!). Macro [47m[with-output][0m is no longer allowed in function bodies because it does not have (and has never had) any effect in raw Lisp. See [with-output] for a workaround. Fixed a bug in redundancy of [47m[defstobj][0m in raw Lisp, which caused an error when certifying a book with a redundant [47m[defstobj][0m event whose [47m[stobj][0m had already been modified. Here is an example: (defstobj st fld) (update-fld 3 st) (certify-book "foo" 1) ; where foo.lisp contains (defstobj st fld) New books illustrating [47m[make-event][0m have been contributed in directory [47mbooks/make-event/[0m: [47mdotimes.lisp[0m (David Rager), [47mstobj-test.lisp[0m, and [47mlogical-tangent.lisp[0m (Peter Dillinger). Modified [47mprint-object$[0m (see [io]) so that it no longer prints an extra space at the end. Replaced the ``draconian restriction to avoid capture'' that had prevented some [47m:functional-instance[0m [hints] from being legal. The corresponding check now only requires that no variable free in the functional substitution is captured by a [47m[let][0m or [47m[mv-let][0m (or [47m[lambda][0m) binding. See [lemma-instance]. Added new extended metafunction, [47mmfc-rw+[0m, which is equivalent to [47mmfc-rw[0m except that it takes an alist argument, which may be useful for efficiency. See [extended-metafunctions]. Thanks to Robert Krug for suggesting this more efficient variant of [47mmfc-rw[0m. Added support for the [47mignorable[0m [47m[declare][0m form. We now cause an error on a call of [47mopen-input-channel[0m (see [io]) with an argument string whose first character is the [47m|[0m character. Thanks to Bob Boyer for providing an example (several months ago) showing the danger of such calls, namely that the following command would log you out and kill all of your processes when running on top of GCL in Linux: [47m(open-input-channel "|kill -9 -1" :object state)[0m Restricted the use of [47m[make-event][0m to contexts in which it can be tracked properly, under legal [events] (see [embedded-event-form]). Thanks to Peter Dillinger for bringing an example to our attention that led to this fix. Fixed a bug that was avoiding [guard]-checking for the functions [47m[compress1][0m and [47m[compress2][0m. Thanks to David Rager for bringing this bug to our attention. Added an error message when a [47m[defun][0m or [47m[mutual-recursion][0m event fails, to clarify whether failure is for the [measure] conjecture or for the [guard] conjecture. Thanks to David Rager for requesting clarification for such failures. Fixed a bug in reporting of [guard] violations (hard Lisp error) when certain macros (for example, [47m[cond][0m) are used in the [guard]. Thanks to Jared Davis for bringing this problem to our attention and providing assistance with the solution, in particular by providing a helpful example. Grant Passmore has contributed a resolution/paramodulation prover written in ACL2, in directory [47mbooks/deduction/passmore/[0m. Thanks, Grant. Improved the error message when illegal theories are encountered. Improved the suppression of output for [47minhibit-output[0m arguments of routines in the book [47mbooks/misc/expander.lisp[0m. Thanks to Qiang Zhang for pointing out the possibility for improvement here. Added a new directory [47mbooks/arithmetic-3/extra/[0m that extends [47mbooks/arithmetic-3[0m with additional rules, contributed by Alex Spiridonov with guidance from Robert Krug. WARNING: This directory is under development. It may undergo large changes in future releases, so please consider it experimental and subject to change. Feedback is welcomed. As part of the work mentioned just above, Robert Krug and Alex Spiridonov contributed improvements to [47mbooks/arithmetic-3/[0m: o A new rule [47m|(* (/ x) (/ (expt x n)))|[0m in [47mbind-free/collect.lisp[0m, which is important for reducing [47mcollect-*[0m expressions though it slowed down one proof (see comment above this rule in [47mbind-free/collect.lisp[0m). o Slight improvements of rules [47mintegerp-mod[0m and [47mrationalp-mod[0m in [47mfloor-mod/floor-mod.lisp[0m. o To avoid conflict with [47mbooks/rtl/rel6/arithmetic/[0m, renamed rule [47mmod-minus[0m to [47mmod-neg[0m in [47mfloor-mod/floor-mod.lisp[0m, and renamed [47mintegerp-+-reduce-leading-constant[0m to [47mintegerp-+-reduce-leading-rational-constant[0m in [47mbind-free/integerp.lisp[0m. (GCL on Windows only) Made a low-level change to avoid multiplying stacks for GCL on Windows, since GCL 2.6.6 broke while doing this. Fixed bugs in linear arithmetic (rarely evidenced, it seems) involving using [47m<[0m to compare complex rational constants. Thanks to Robert Krug for helping with the fixes. Added a new event, [47m[assert-event][0m, for checking that forms evaluate to non-[47mnil[0m values. Thanks to Peter Dillinger for suggesting and collaborating on this addition.") (|NOTE-3-0{R}| (release-notes) "ACL2 Version 3.0(r) (June, 2006) Notes No significant changes have been made since Version 2.9 for support of non-standard analysis in particular. Please also see [note-3-0] for changes to Version 3.0 of ACL2.") (note-3-1 (release-notes) "ACL2 Version 3.1 (December, 2006) Notes NOTE! New users can ignore these release notes, because the documentation has been updated to reflect all changes that are recorded here. Please see [note-3-0-2] for a description of changes since Version 3.0.1, and also see [note-3-0-1] for additional changes since Version 3.0.") (|NOTE-3-1{R}| (release-notes) "ACL2 Version 3.1(r) (December, 2006) Notes No significant changes have been made since Version 3.0 for support of non-standard analysis in particular. Please also see [note-3-1] for changes to Version 3.1 of ACL2.") (note-3-2 (release-notes) "ACL2 Version 3.2 (April, 2007) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Before this release, a raw Lisp error could put the ACL2 user into the debugger of the host Common Lisp. Now, such cases will generally put the user back at the top-level loop after an informative message. For details, see [set-debugger-enable]; also see [break$]. Fixed a soundness bug that was allowing unknown packages to sneak into a book and wreak havoc. Thanks to Peter Dillinger for sending an interesting example that led us to an exploration resulting in finding this bug. (A comment in the source code for [47mnote-3-2[0m shows such an example.) That example led us to fix a couple of other bugs related to packages. See [hidden-death-package] if you are generally interested in such issues, and for associated examples, see comments in [47mnote-3-2[0m in the ACL2 source code. Fixed subtle soundness bugs related to [47m:[0m[47m[meta][0m rules by restricting evaluators (see [defevaluator]), as discussed in a new documentation topic: see [evaluator-restrictions]. Fixed a soundness bug that was allowing redefinition from [47m:[0m[47m[logic][0m to [47m:[0m[47m[program][0m mode. This prohibition had been in ACL2 for awhile but was accidentally removed in the preceding version. Fixed a soundness bug related to [47m[trace$][0m. Thanks to Peter Dillinger for bringing it to our attention and for useful discussions, and providing a proof of [47mnil[0m, the essence of which is illustrated as follows: (value-triple (trace$ (bar :entry (defun foo () 17)))) Thus, [47m[trace$][0m could be used to cause destructive raw Lisp behavior. Now, [47mtrace$[0m fails unless it is either given a list of symbols or else there is an active trust tag (see [defttag]); otherwise, consider using [47mtrace![0m instead. Closed a loophole that could be viewed as compromising soundness. It was possible to write files during book certification by exploiting [47m[make-event][0m expansion, but that is no longer the case by default. A new function [47m[open-output-channel!][0m is identical as a function to [47mopen-output-channel[0m, except that the new function may be called even during [47m[make-event][0m expansion and [47m[clause-processor][0m [hints], but requires that there is an active trust tag (see [defttag]). Thanks to Peter Dillinger for producing a convincing example (forging a [certificate] during book certification; see [open-output-channel!]) and to him, Sandip Ray, and Jared Davis for useful discussions on the topic. Added book [47mbooks/defexec/reflexive/reflexive.lisp[0m to illustrate reflexive functions. ACL2 now generates scripts that invoke the saved image with [47mexec[0m. (Previously this was only done for GCL and CLISP.) The benefit of this change can be to avoid the lingering of ACL2 processes after enclosing processes have exited. Thanks to Peter Dillinger for pointing out this issue. ACL2 has a better implementation of [47m([0m[47m[good-bye][0m[47m)[0m (hence of synonyms [47m([0m[47m[quit][0m[47m)[0m and [47m([0m[47m[exit][0m[47m)[0m). As a result, you should now be able to exit ACL2 and Lisp from within the ACL2 read-eval-print loop with any of the above; formerly, this was not supported for some Lisp implementations, and was slow in OpenMCL. Thanks to SBCL developer Harald Hanche-Olsen for useful advice. Fixed a bug in raw-mode (see [set-raw-mode]) that was causing hard errors when evaluating calls of [47m[er-progn][0m, or of macros expanding to such calls. Fixed a few Makefile dependencies, necessary only for parallel `make'. A new book, [47mmisc/defpun-exec-domain-example.lisp[0m, provides an example showing how partial functions which return a unique value for arguments in a specified domain can be efficiently executed with ACL2. Execution is achieved using the [47m[mbe][0m construct. Thanks to Sandip Ray for providing this example. Existing function [47m[mod-expt][0m computes [47m(mod (expt base exp) mod)[0m with great efficiency in GCL, but not in other Lisps. Now, the book [47marithmetic-3/floor-mod/mod-expt-fast.lisp[0m defines a function [47mmod-expt-fast[0m that should provide significantly improved performance for such expressions in other Lisps as well, though still probably not as fast as when using [47mmod-expt[0m in GCL. Thanks to Warren Hunt, with contributions from Robert Krug, for providing this book, Modified macro [break-on-error] to print an error message before entering a break, and to cause a hard error if the underlying Lisp cannot handle it (formerly, a raw Lisp break would occur). Thanks to Bob Boyer for bringing these issues to our attention. The book [47mbooks/misc/defpun.lisp[0m, as well as other books related to the [47mdefpun[0m macro, has been modified to avoid namespace collisions by prefixing function symbol names with [47m"DEFPUN-"[0m; for example [47mbase[0m has been replaced by [47mdefpun-base[0m. Thanks to Dave Greve for providing a first version of this update to [47mdefpun.lisp[0m. A theory, [47mbase[0m, in [47mbooks/arithmetic-3/bind-free/top.lisp[0m, has been renamed [47marithmetic-3-bind-free-base[0m, to avoid potential name conflicts. Fixed [47mbooks/arithmetic-3/bind-free/banner.lisp[0m to print (as before) a message about how to turn on non-linear arithmetic, by modifying the call of [47mvalue-triple[0m to use [47m:on-skip-proofs t[0m. Thanks to Robert Krug for bringing this issue to our attention. Modified [47mbooks/Makefile-subdirs[0m and [47mbooks/Makefile-psubdirs[0m so that they can be used with [47mbooks/Makefile-generic[0m. Thus, one can set things up so that `make' can be used to certify books both in the current directory and subdirectories, for example as follows. ACL2 = ../../saved_acl2 arith-top: top all all: top DIRS = pass1 bind-free floor-mod include ../Makefile-subdirs include ../Makefile-generic top.cert: top.lisp top.cert: bind-free/top.cert top.cert: floor-mod/floor-mod.cert top.cert: floor-mod/mod-expt-fast.cert An experimental extension of ACL2 is under development by Bob Boyer and Warren Hunt to support function memoization, hash conses, and an applicative version of hash tables. The default build of ACL2 does not include this extension, other than simple logic definitions of functions in new source file [47mhons.lisp[0m. Future versions of ACL2 may fully incorporate this experimental extension. The [47m[defevaluator][0m event macro has been modified primarily by adding a new constraint as follows, where [47mevl[0m is the evaluator. The idea is that for the evaluation of a function call, one may replace each argument by the quotation of its evaluation and then also replace the alist environment with [47mnil[0m. (DEFTHMD UNHIDE-evl-CONSTRAINT-0 (IMPLIES (AND (CONSP X) (SYNTAXP (NOT (EQUAL A ''NIL))) (NOT (EQUAL (CAR X) 'QUOTE))) (EQUAL (evl X A) (evl (CONS (CAR X) (KWOTE-LST (UNHIDE-evl-LIST (CDR X) A))) NIL)))) In order to support this change, there is another change: an evaluator maps [47mnil[0m to [47mnil[0m (note [47m(AND X (CDR (ASSOC-EQ X A)))[0m in place of [47m(CDR (ASSOC-EQ X A))[0m below). (DEFTHM UNHIDE-evl-CONSTRAINT-1 (IMPLIES (SYMBOLP X) (EQUAL (UNHIDE-evl X A) (AND X (CDR (ASSOC-EQ X A)))))) With the new [47m[defevaluator][0m, Dave Greve has been able to do a proof about beta reduction that seemed impossible before (see [47mbooks/misc/beta-reduce.lisp[0m). Thanks to Dave for suggesting an initial version of this change. Explicit compilation is now avoided for OpenMCL, resulting in fewer files to manage (no more files resulting from compilation) and, according to some tests, slightly faster run times. See [compilation]. Thanks to Bob Boyer and Warren Hunt for suggesting this possibility. Now, the [47mterm-evisc-tuple[0m (see [ld-evisc-tuple]) is overridden by state global [47muser-term-evisc-tuple[0m in all cases. Formerly, this was only the case when [47mterm-evisc-tuple[0m was called with non-[47mnil[0m first argument. Symbols with the dot ([47m.[0m) character are generally no longer printed with vertical bars. For example, before this change: ACL2 !>'ab.c |AB.C| ACL2 !> After this change: ACL2 !>'ab.c AB.C ACL2 !> Thanks to Jared Davis for suggesting this improvement. Fixed bugs in [47mguard[0m verification for theorems. The following examples illustrate these bugs. If either theorem's body is executed in raw Lisp there is likely to be a hard Lisp error, even though [47m[verify-guards][0m was supposed to ensure against that behavior. ; Example: Verify-guards failed to check that all functions in the theorem ; had already been guard-verified. (defun my-car (x) (car x)) (defthm my-car-compute-example (equal (my-car 3) (my-car 3))) (verify-guards my-car-compute-example) ; Example: Verify guards of a theorem whose body uses state improperly. (defthm bad-state-handler (if (state-p state) (equal (car state) (car state)) t) :rule-classes nil) (verify-guards bad-state-handler) See [gcl] for an example, developed with Warren Hunt and Serita Nelesen, that shows how to get fast fixnum (small integer) arithmetic operations in GCL. Fixnum declarations are now realized as [47m(signed-byte 30)[0m and [47m(unsigned-byte 29)[0m instead of what was generally [47m(signed-byte 29)[0m and [47m(unsigned-byte 28)[0m. MCL users may thus find better performance if they switch to OpenMCL. Note that some definitions have changed correspondingly; for example, [47m[zpf][0m now [47m[declare][0ms its argument to be of type [47m(unsigned-byte 29)[0m instead of [47m(unsigned-byte 28)[0m. A few [books] may thus need to be adjusted; for example, changes were made to books in [47mbooks/data-structures/memories/[0m. ACL2's rewriter now avoids removing certain true hypotheses and false conclusions. When a hypothesis rewrites to true or a conclusion rewrites to false, ACL2 formerly removed that hypothesis or conclusion. Now, it only does such removal when the hypothesis or conclusion is either a call of [47m[equal][0m or an equivalence relation (see [equivalence]), or else is sufficiently trivial (roughly, either redundant with another hypothesis or conclusion or else trivially true without considering the rest of the goal). A specific example may be found in source file [47msimplify.lisp[0m; search for ``; But we need to do even more work''. Thanks to Robert Krug for providing the idea for this improvement and its initial implementation. As is common with heuristic changes, you may find it necessary on occasion to rename some subgoals in your [hints]. And in this case, you might also find it necessary on rare occasions to add [47m:do-not '(generalize)[0m [hints]. A new function, [47mmfc-relieve-hyp[0m, allows (for example) for more powerful [47m[bind-free][0m hypotheses, by providing an interface to the rewriter's routine for relieving hypotheses. See [extended-metafunctions]. Thanks to Robert Krug for providing the idea for this feature and its initial implementation. Two improvements have been made to non-linear arithmetic (see [non-linear-arithmetic]). One allows for deducing strict inequality ([47m<[0m) for the result of certain polynomial multiplications, where previously only non-strict inequality ([47m<=[0m) was deduced. A second allows the use of the product of two polynomials when at least one of them is known to be rational. We had previously restricted the use of the product to the case where both were known to be rational. Thanks to Robert Krug for these improvements. (OpenMCL and Allegro CL only) Fixed ACL2's redefinitions of raw Lisp [47mtrace[0m and [47muntrace[0m in OpenMCL and Allegro CL so that when given no arguments, they return the list of traced functions. For [47mtrace[0m, this is an ANSI spec requirement. Note that [47m[trace$][0m and [47m[untrace$][0m continue to return [47mnil[0m in the ACL2 loop. Fixed a bug that was allowing the symbol [47m&whole[0m to appear in other than the first argument position for a [47m[defmacro][0m event, in violation of the Common Lisp spec (and leading to potentially surprising behavior). Thanks to Peter Dillinger for bringing this bug to our attention. It had been illegal to use [47m[make-event][0m under some calls of [47m[ld][0m. This has been fixed. Thanks to Jared Davis for bringing this issue to our attention with a simple example, in essence: (ld '((defmacro my-defun (&rest args) `(make-event '(defun ,@args))) (my-defun f (x) x))) ACL2 no longer prohibits certain [47m[make-event][0m forms when including uncertified [books]. Thanks to Peter Dillinger for first bringing this issue to our attention. Hard errors arose when using [break-rewrite] stack display commands, in particular [47m:path[0m and [47m:frame[0m, from inside the [proof-builder]. This has been fixed. Fixed a bug that could cause functions that call system built-ins [47mf-put-global[0m, [47mf-get-global[0m, or [47mf-boundp-global[0m to cause a raw Lisp error even when proving theorems. Thanks to Peter Dillinger, for reporting such a failure for the form [47m(thm (w '(1 2 3)))[0m. Renamed the formal parameters of function [47mset-equal[0m in distributed book [47mbooks/arithmetic-3/bind-free/normalize.lisp[0m so that more distributed books can be included together in the same session. In particular books [47mbooks/data-structures/set-theory[0m and [47mbooks/arithmetic-3/extra/top-ext[0m can now be included together. Thanks to Carl Eastlund for bringing this problem to our attention and to Robert Krug for suggesting the formals renaming as a fix. Metafunctions must now be executable. See [meta]. New utilities allow for user-defined simplifiers at the goal level, both verified and unverified (``trusted''), where the latter can even be defined by programs outside ACL2. See [clause-processor], which points to a new directory [47mbooks/clause-processors/[0m that contains examples of these new utilities, including for example a system (``SULFA'') contributed by Erik Reeber that implements a decision procedure (thanks, Erik). Also see [proof-builder-commands] for the new [proof-builder] command [47mclause-processor[0m (or for short, [47mcl-proc[0m). The rewriter has been tweaked to run faster in some cases involving very large terms. Thanks to Eric Smith and Jared Davis for providing a helpful example that helped us locate the source of this inefficiency. Added [47mbooks/make-event/defspec.lisp[0m. This book shows how one can mimic certain limited forms of higher-order statements in ACL2 by use of macros, [47m[make-event][0m, and [47m[table][0m events. Thanks to Sandip Ray for his contribution. A new release of the RTL library, [47mbooks/rtl/rel7/[0m, replaces the previous version, [47mbooks/rtl/rel6/[0m. Thanks to Hanbing Liu and David Russinoff for providing this new version. We thank David Russinoff for providing a proof of the law of quadratic reciprocity. See [47mbooks/quadratic-reciprocity/Readme.lsp[0m. Eliminated a slow array warning (see [slow-array-warning]) that could occur when exiting a [wormhole] after executing an [47m[in-theory][0m event in that wormhole. Thanks to Dave Greve for bringing this problem to our attention. A new accessor, [47m(mfc-rdepth mfc)[0m, provides a new field, the remaining rewrite stack depth, which has been added to metafunction context structures; see [extended-metafunctions]. Thanks to Eric Smith for suggesting this addition. The algorithms were modified for collecting up rule names and other information used in proofs, into so-called ``tag-trees''. Tag-trees are now free of duplicate objects, and this change can dramatically speed up some proofs that involve many different rules. Thanks to Eric Smith for doing some profiling that brought this issue to our attention, and for reporting that this change reduced proof time on an example by about 47% (from 3681.46 reported seconds down to 1954.69). All legal [47mxargs[0m keywords may now be used in [47m[verify-termination][0m [events]. In particular, this is the case for [47m:normalize[0m. (SBCL and CMUCL only) Fixed a problem with stobj array resizing functions that was causing a hard error in ACL2 images built on SBCL or CMUCL. A new [table], [47m[evisc-table][0m, allows you to introduce print abbreviations, for example for large constants. Moreover, a new reader macro --- [47m#,[0m --- makes it convenient to reference constants even inside a quote. See [evisc-table]. Thanks to Bob Boyer and Warren Hunt for useful discussions leading to this feature. The macros in [47mbooks/misc/expander.lisp[0m now have a new keyword argument, [47m:simplify-hyps-p[0m. The default behavior is as before, but now case splitting from hypothesis simplification can be avoided. For details, evaluate [47m(include-book "misc/expander" :dir :system)[0m and then [47m:doc! defthm?[0m and [47m:doc! symsym[0m. Thanks to Daron Vroon for sending a question that prompted this additional functionality. ACL2 failed to apply [47m:[0m[47m[restrict][0m hints to rules of class [47m:[0m[47m[definition][0m, except for the simplest sorts (see [simple]). This has been fixed. Thanks to Jared Davis for pointing out this bug by sending a small example. Added a new [47m:msg[0m argument to [47massert-event[0m; see [assert-event]. The implementation of [47mvalue-triple[0m has been modified to support this change. Fixed a bug in macro [47mio?[0m that now allows the [47mcommentp[0m argument to be [47mt[0m. This provides a way other than [47mcw[0m to print without modifying state, for example as follows. (Warning: Certain errors may leave you in a [wormhole], in which case use [47m:a![0m to abort.) ACL2 !>(prog2$ (io? event t state () (fms "Howdy~%" nil *standard-co* state nil)) (+ 3 4)) Howdy 7 ACL2 !>:set-inhibit-output-lst (proof-tree event) (PROOF-TREE EVENT) ACL2 !>(prog2$ (io? event t state () (fms "Howdy~%" nil *standard-co* state nil)) (+ 3 4)) 7 ACL2 !> ACL2 now disallows calls of [47m[progn!][0m inside function bodies, just as it already disallowed such calls of [47m[progn][0m, since in both cases the Common Lisp meaning differs from the ACL2 meaning. Redefinition of system functions now always requires an active trust tag (see [defttag]). This restriction was intended before, but there was a hole that allowed a second redefinition without an active trust tag. Thanks to Peter Dillinger for pointing out this bug. [47m[Verify-termination][0m has been disabled for a few more built-in functions that are in [47m:[0m[47m[program][0m mode. (If you are curious about which ones they are, evaluate [47m(f-get-global 'built-in-program-mode-fns state)[0m.) [Note added for Version_3.4: This state global has been changed to 'program-fns-with-raw-code.] Moreover, such functions now will execute only their raw Lisp code, so for example they cannot be called during macroexpansion. Thanks to Peter Dillinger and Sandip Ray for useful discussions on details of the implementation of this restriction. New untouchable state global variables, [47mtemp-touchable-vars[0m and [47mtemp-touchable-fns[0m, can control the enforcement of untouchability. See [remove-untouchable]. Thanks to Peter Dillinger for suggesting these features. The ``TTAG NOTE'' string was being printed by [47m[encapsulate][0m events whenever an active trust tag was already in effect (see [defttag]), even if the encapsulate event contained no [47m[defttag][0m event. This has been fixed. Thanks to Peter Dillinger for a query leading to this fix. Fixed a bug in [47m[progn!][0m that could leave the user in raw-mode (see [set-raw-mode]). This could occur when certifying a book with a [47mcompile-flg[0m value of [47mt[0m (see [certify-book]), when that book contained a [47m[progn!][0m event setting raw-mode to [47mt[0m without setting raw-mode back to [47mnil[0m: (progn! (set-raw-mode t) ...)") (note-3-2-1 (release-notes) "ACL2 Version 3.2.1 (June, 2007) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. (OpenMCL and multi-threaded SBCL only) Fixed a soundness bug in the evaluation of [47m[mbe][0m forms in the presence of Lisp feature [47m:acl2-mv-as-values[0m. Thanks to Sol Swords for reporting this problem and sending a simple proof of [47mnil[0m (which can be found in a comment in the ACL2 sources, in [47m(deflabel note-3-2-1 ...)[0m). Added a new utility, [47m[dmr][0m (Dynamically Monitor Rewrites), for watching the activity of the rewriter and some other proof processes. See [dmr]. We thank Robert Krug for useful contributions. Fixed a bug in evaluation of calls of [47m[with-prover-time-limit][0m. Fixed the writing of executable scripts when building ACL2, so that the build-time value of environment variable [47mACL2_SYSTEM_BOOKS[0m is no longer written there. Thanks to Dave Greve for discussing this change. Fixed bugs in [47m:[0m[47m[pl][0m (which are similarly present in the [proof-builder]'s [47msr[0m ([47mshow-rewrites[0m) command. The first bug was evident from the following forms sent by Robert Krug, which caused an error. (include-book "arithmetic-3/floor-mod/floor-mod" :dir :system) :pl (mod (+ 1 x) n) The second bug was due to a failure to take note of which rules are disabled, and could be seen by executing the following (very slow!). (defstub modulus () t) (include-book "arithmetic-3/floor-mod/floor-mod" :dir :system) :pl (mod (+ x y) (modulus)) Modified [47m[certify-book][0m so that by default, all executable-counterpart functions (sometimes called ``*1* functions'') are compiled. This is the behavior that was already supported with a [47mcompile-flg[0m argument of [47m:all[0m; the change is that argument [47mt[0m now has this behavior as well (and [47m:all[0m is supported only for legacy purposes). A new value for [47mcompile-flg[0m, [47m:raw[0m, gives the behavior formerly produced by value [47mt[0m, namely where executable-counterpart functions are not compiled. The above changes are irrelevant if compilation is suppressed; see [compilation]. Finally, if environment variable [47mACL2_COMPILE_FLG[0m is set, then after converting to upper-case this environment variable's value of [47m"T"[0m, [47m"NIL"[0m, or [47m":RAW"[0m will determine the value of the optional [47mcompile-flg[0m argument to be [47mt[0m, [47mnil[0m, or [47m:raw[0m, respectively, when this argument is not explicitly supplied. Modified [47m[include-book][0m so that [47m:comp[0m argument now acts like [47m:comp![0m, i.e., compiling a file that includes the file together with all executable counterpart (so-called ``*1*'') functions. A new argument, [47m:comp-raw[0m, has the behavior that [47m:comp[0m had formerly, i.e., compiling the actual book only. The function [47m[nonnegative-integer-quotient][0m is now computed in raw Lisp by calling [47m[floor][0m on its arguments. This change was suggested by Peter Dillinger, in order to avoid stack overflows such as reported by Daron Vroon. A new book, [47mbooks/misc/misc2/misc.lisp[0m, contains a proof of equivalence of [47m[nonnegative-integer-quotient][0m and [47m[floor][0m, and serves as a repository for other miscellaneous proofs, including those justifying ACL2 modifications such as this one. Enhanced [47m[accumulated-persistence][0m to break down results by useful vs. useless rule applications. In particular, this provides information about which rules were ever applied successfully, as requested by Bill Young. Added coverage of [47m:[0m[47m[meta][0m rules to the [47m[accumulated-persistence][0m statistics. Fixed a bug that was causing a [47m:[0m[47m[clause-processor][0m hint to fire on a subgoal of the goal to which it was attached, when the original application didn't change the clause. Thanks to Dave Greve for pointing out this bug and providing a useful example. Fixed a bug in handling of computed [hints] related to the [47mstable-under-simplificationp[0m parameter (see [computed-hints]). There were actually two bugs. A minor but confusing bug was that the same goal was printed twice upon application of such a hint. The major bug was that [47m:use[0m [hints] (as well as other ``top'' hints: [47m:by[0m, [47m:cases[0m, and [47m:clause-processor[0m) were not being applied properly. Thanks to Jared Davis for sending an example some time ago that showed the duplicate printing, and to Dave Greve for sending an example showing mis-application of [47m:[0m[47m[clause-processor][0m [hints]. Note that you may find that existing computed hints using the [47mstable-under-simplificationp[0m parameter no longer have the same behavior; see a comment about computed hints in [47mnote-3-2-1[0m, ACL2 source file [47mld.lisp[0m, for an example of how you might want to fix such computed hints. David Russinoff has contributed an updated version of [47mbooks/quadratic-reciprocity/[0m including minor modifications of the treatment of prime numbers and a proof that there exist infinitely many primes. Thanks to David for contributing this work, and to Jose Luis Ruiz-Reina for posing the challenge. Reduced the sizes of some [certificate] ([47m.cert[0m) files by relaxing the test that allows original [47m[defpkg][0m [events] to be placed there, rather than evaluating the import list term into an explicit list of symbols. Improved execution efficiency slightly for function [47mrcdp[0m in file [47mbooks/misc/records.lisp[0m, by using [47m[mbe][0m to introduce a tail-recursive body. The executable script generated by [47m[save-exec][0m (and by the normal build process) now includes a time stamp as a comment. Thanks to Jared Davis for suggesting this change in order to support his use of [47momake[0m. In the process, we also arranged that the startup banner for an executable created by [47m[save-exec][0m shows all of the build (save) times, not just the one for the original image. Sped up most redundant [47m[defpkg][0m [events] by avoiding evaluation and sorting of the imports list in the case of identical event forms. And, for [47m[defpkg][0m events that are not redundant, sped up their processing in Allegro CL (and perhaps other Lisps, but apparently not GCL) by using our own [47mimport[0m function. Modified [47m[add-include-book-dir][0m so that it refuses to associate a keyword with a different directory string than one it is already bound to. See [delete-include-book-dir] for how to remove the existing binding first. Thanks to Robert Krug for pointing out that without this change, one can find it difficult to debug a failure due to rebinding a keyword with [47m[add-include-book-dir][0m. Added a new value for the [47m:do-not-induct[0m hint (see [hints]), [47m:otf-flg-override[0m, which causes ACL2 to ignore the [47m:[0m[47m[otf-flg][0m when considering whether to abort the proof because of a [47m:do-not-induct[0m hint. Thanks to Daron Vroon for suggesting such an addition. Modified the printing of messages for entering and exiting raw mode (see [set-raw-mode]), so that in particular they are inhibited during [47m[include-book][0m or whenever [47mobservation[0ms are inhibited (see [set-inhibit-output-lst]). Thanks to Peter Dillinger for suggesting such a change. (For system hackers only.) The handling of [events] of the form [47m(progn! (state-global-let* ...))[0m had a bug that was causing bindings to be evaluated twice. Moreover, the use of system function [47m[state-global-let*][0m is suspect in raw Lisp. We have eliminated special treatment of [47mstate-global-let*[0m by [47mprogn![0m in favor of a new keyword argument, [47mstate-global-bindings[0m, that provides the intended functionality. See [progn!]. Moreover, special handling that allowed [47m[make-event][0m forms under [47mstate-global-let*[0m has been removed; the desired effect can be obtained using (progn! :state-global-bindings ...). Thanks to Peter Dillinger for pointing out the above bug and collaborating on these changes. Incorporated backward-compatible enhancements to [47mbooks/misc/expander.lisp[0m from Daron Vroon (documented near the top of that file). The specification of [47m:backchain-limit-lst[0m had required that only a single ([47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, or [47m:[0m[47m[meta][0m) rule be generated. We have weakened this restriction to allow more than one rule provided that each rule has the same list of hypotheses. For example, the rule class [47m(:rewrite :backchain-limit-lst 1)[0m is now legal for the corollary formula [47m(implies (f x) (and (g x) (h x)))[0m, where this was not formerly the case. Thanks to Dave Greve for bringing this issue to our attention.") (|NOTE-3-2-1{R}| (release-notes) "ACL2 Version 3.2.1(r) (June, 2007) Notes Please also see [note-3-2-1] for changes to Version 3.2.1 of ACL2.") (|NOTE-3-2{R}| (release-notes) "ACL2 Version 3.2(r) (April, 2007) Notes Changed the default distributed [books] directory for ACL2(r) from [47mbooks/[0m to [47mbooks/nonstd/[0m. See [include-book], in particular the discussion of ``Distributed Books Directory''. Added directory [47mbooks/arithmetic-3/[0m and its subdirectories to [47mbooks/nonstd/[0m. (But a chunk of theorems from [47marithmetic-3/extra/ext.lisp[0m are ``commented out'' using #-:non-standard-analysis because they depend on [47mbooks/rtl/rel7/[0m, which is not yet in [47mbooks/nonstd/[0m; feel free to volunteer to remedy this!) Incorporated changes from Ruben Gamboa to some (linear and non-linear) arithmetic routines in the theorem prover, to comprehend the reals rather than only the rationals. Please also see [note-3-2] for changes to Version 3.2 of ACL2.") (note-3-3 (release-notes) "ACL2 Version 3.3 (November, 2007) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 3.2.1 into new features, bug fixes, prover algorithm enhancements, and miscellaneous. Also see [note-3-2-1] for other changes since Version 3.2. [31;1mNEW FEATURES[0m A new ``gag-mode'' provides less verbose, more helpful feedback from the theorem prover, in support of The Method (see [the-method]). See [set-gag-mode]. We recommend the use of gag-mode, which may become the default in future ACL2 releases, and we welcome suggestions for improvement. We thank Robert Krug and Sandip Ray for helpful feedback in the design of [gag-mode]. Note that when proofs fail, then even without gag-mode and even if proof output is inhibited, the summary will contain a useful listing of so-called ``key checkpoints'' (see [set-gag-mode]). Added support for a leading `[47m~[0m' in filenames. Thanks to Bob Boyer for suggesting this enhancement. Note that since `[47m~/[0m' depends on the user, it is disallowed in [books] to be certified (see [certify-book]), since otherwise an [47m[include-book][0m form in a book, [47mb[0m, could have a different meaning at certification time than at the time [47m[include-book][0m is later executed on book [47mb[0m. Made a change to allow [47m(time$ FORM)[0m and [47m(with-prover-time-limit TIME FORM)[0m when [47mFORM[0m includes [47m[make-event][0m calls that change the ACL2 [world]. Thanks to Jared Davis for requesting such support for [47m[time$][0m. Computed [hints] (see [computed-hints]) may now produce a so-called ``error triple'', i.e., a result of the form [47m(mv erp val state)[0m, where a non-[47mnil[0m [47merp[0m causes an error, and otherwise [47mval[0m is the value of the hint. It remains legal for a computed hint to return a single ordinary value; indeed, the symbol form of a computed hint must still be a function that returns an ordinary single value. New hints provide additional control of the theorem prover, as follows. See [hints] for more details, and see new distributed book directory [47mbooks/hints/[0m for examples, in particular file [47mbasic-tests.lisp[0m in that directory for simple examples. o The hint [47m:OR (hints-1 ... hints-k)[0m causes an attempt to prove the specified goal using each [47mhints-i[0m in turn, until the first of these succeeds. If none succeeds, then the prover proceeds after heuristically choosing the ``best'' result, taking into account the goals pushed in each case for proof by induction. o A custom hint is a keyword that the user associates with a corresponding hint-generating function by invoking [47m[add-custom-keyword-hint][0m. Thus, a custom hint may be viewed as a convenient sort of computed hint. o A custom hint, [47m:MERGE[0m, is implemented in distributed book [47mbooks/hints/merge.lisp[0m. It is useful for combining hints. o A sophisticated yet useful custom hint is the [47m:CONSIDER[0m hint implemented in distributed book [47mbooks/hints/consider-hint.lisp[0m. With this hint, you can for example give the equivalent of a [47m:USE[0m hint without the need to supply an instantiation. Include that book in order to see documentation online with [47m:doc consideration[0m, and see the book [47mbooks/hints/consider-hint-tests.lisp[0m for examples. A new hint, [47m:[0m[47m[reorder][0m, allows the specification of which subgoals are to be considered first. Thanks to Sandip Ray for putting forward this idea. Enhanced [47mset-saved-output[0m by supporting a second argument of [47m:same[0m, which avoids changing which output is inhibited. Added macros [47mthm?[0m and [47mnot-thm?[0m to distributed book [47mbooks/make-event/eval.lisp[0m, so that it's easy to test within a certified book that a proof attempt succeeds or that it fails. Added printing function [47m[cw!][0m, which is analogous to [47m[cw][0m just as [47m[fmt!][0m is to [47m[fmt][0m, i.e., printing so that the result can be read back in. Thanks to Jared Davis for suggesting this enhancement (after doing his own implementation). The ACL2 customization file can now be specified using environment variable [47mACL2-CUSTOMIZATION[0m [note: starting with Version_4.0, [47mACL2_CUSTOMIZATION[0m]. See [ACL2-customization]. Thanks to Peter Dillinger for requesting this feature. Added new emacs capabilities for proof trees (all documented in emacs): o New function start-proof-tree-noninteractive, for example (start-proof-tree-noninteractive "*shell*") o C-z o Switch to another frame o C-z b Switch to prooftree buffer o C-z B Switch to prooftree buffer in "prooftree-frame" frame Added Common Lisp function, [47msearch[0m, as a macro in [47m[logic][0m mode, with limited support for keyword arguments. Thanks to Warren Hunt for requesting this addition. Sandip Ray has contributed a book, [47mbooks/make-event/defrefine.lisp[0m, that provides a collection of macros to aid in reasoning about ACL2 functions via refinement. Wrote and incorporated new utility for listing all the theorems in an included book. See [47mbooks/misc/book-thms.lisp[0m. Thanks to Jared Davis for requesting this functionality. The new distributed book [47mmisc/defp.lisp[0m generalizes the [47m[defpun][0m macro to allow more general forms of tail recursion. (Low-level printing improvement) A new function, [47mset-ppr-flat-right-margin[0m, allows the right margin for certain kinds of ``flat'' printing to exceed column 40. Thanks to Jared Davis for pointing out that state global variables [47m'fmt-hard-right-margin[0m and [47m'fmt-soft-right-margin[0m are not alone sufficient to extend the right margin in all cases. The event [47m[add-include-book-dir][0m can now take a relative pathname as an argument. Formerly, it required an absolute pathname. A new book, [47mbooks/misc/defopener.lisp[0m, provides a utility creating a theorem that equates a term with its simplification. ACL2 now provides limited support for the Common Lisp primitive [47mFLET[0m, which supports local function bindings. See [flet]. Thanks to Warren Hunt for requesting this feature. Added a definition of [47m[boole$][0m, a close analogue of Common Lisp function [47mboole[0m. Thanks to Bob Boyer for providing an initial implementation. [31;1mBUG FIXES[0m Fixed [47m[defstobj][0m to inhibit a potentially useless theory warning. Fixed a bug in the application of [47m[certify-book][0m to relative pathnames for files in other than the current directory. Thanks to Amr Helmy for bringing this bug to our attention. Fixed a bug in [47m:[0m[47m[pl][0m and [47m:[0m[47m[pr][0m for displaying rules of class [47m:[0m[47m[meta][0m. Thanks to Jared Davis for finding this bug and providing a fix. Formerly, [47m[set-default-backchain-limit][0m was not a legal event form for [47m[encapsulate][0m forms and [books]. This has been fixed. Thanks to Robert Krug and Sandip Ray for bringing this bug to our attention. Fixed the handling of [hints] in [proof-builder] commands for the prover, such as [47mbash[0m --- see [proof-builder-commands] --- so that the user can override the default settings of hints, in particular of [47m:do-not[0m and [47m:do-not-induct[0m hints attached to [47m"Goal"[0m. This fix also applies to the distributed book [47mmisc/bash.lisp[0m, where Robert Krug noticed that he got an error with [47m:hints (("Goal" :do-not '(preprocess)))[0m; we thank Robert for pointing out this problem. Fixed a bug in handling of [stobj]s occurring in guards of functions whose [guard]s have been verified. In such cases, a raw Lisp error was possible when proving theorems about non-''live'' [stobj]s. We thank Daron Vroon for sending us an example that highlighted this bug. The following (simpler) example causes such an error in previous versions of ACL2. (defstobj st fld) (defun foo (st) (declare (xargs :stobjs st :guard (fld st))) st) (thm (equal (foo '(3)) '(3))) The [dmr] feature for dynamic monitoring of rewrites had a bug, where the file used for communicating with emacs was the same for all users, based on who built the ACL2 executable image. This has been fixed. Thanks to Robert Krug for bringing this bug to our attention. Fixed a bug in some warnings, in particular the warning for including an uncertified book, that was giving an incorrect warning summary string. Inclusion of uncertified books erroneously re-used [47m[make-event][0m expansions that were stored in stale [certificate]s. This is no longer the case. Thanks to Jared Davis for bringing this bug to our attention. Fixed a bug that was disallowing calls of [47m[with-output][0m in [events] that were executing before calling [47m[certify-book][0m. Modified the functionality of [47mbinop-table[0m so other than binary function symbols are properly supported (hence with no action based on right-associated arguments). See [add-binop]. Fixed small [proof-builder] issues related to packages. Emacs commands [47mctrl-t d[0m and [47mctrl-t ctrl-d[0m now work properly with colon (`[47m:[0m') and certain other punctuation characters. The [47mp-top[0m command now prints ``[47m***[0m'' regardless of the current package. Fixed a bug that allowed [47m[certify-book][0m to succeed without specifying value [47mt[0m for keyword argument [47m:skip-proofs-okp[0m, even with [47m[include-book][0m [events] in the certification [world] depending on events executed under [47m[skip-proofs][0m. Improved [47m[show-accumulated-persistence][0m in the following two ways. Thanks to Robert Krug and Bill Young for requesting these improvements and for providing useful feedback. o It can provide more complete information when aborting a proof. o The [47m:frames[0m reported for a rule are categorized as ``useful'' and ``useless'' according to whether they support ``useful'' or ``useless'' [47m:tries[0m of that rule, respectively. See [accumulated-persistence] for further explanation. Modified [47m[make-event][0m so that the reported time and warnings include those from the expansion phase. In analogy with [47m[encapsulate][0m and [47m[progn][0m, the rules reported still do not include those from subsidiary events (including the expansion phase). A related change to [47m[ld][0m avoids resetting summary information (time, warnings) with each top-level form evaluation; [events] already handle this information themselves. Fixed [47m[set-inhibit-output-lst][0m so that all warnings are inhibited when [47mwarning![0m but not [47mwarning[0m is included in the list. Formerly, only soundness-related warnings were inhibited in this case. Thanks to Eric Smith for bringing this bug to our attention. Distributed directory [47mdoc/HTML/[0m now again includes installation instructions (which was missing in Version_3.2.1), in [47mdoc/HTML/installation/installation.html[0m. Some fixes have been made for [proof-tree] support. o [Proof-tree] output is no longer inhibited automatically during [47m[certify-book][0m, though it continues to be inhibited by default (i.e., ACL2 continues to start up as though [47m[set-inhibit-output-lst][0m has been called with argument [47m'(proof-tree)[0m). o Fixed a bug in Xemacs support for [proof-tree] help keys [47mC-z h[0m and [47mC-z ?[0m. o Fixed a bug in [proof-tree]s that was failing to deal with the case that a goal pushed for proof by induction is subsumed by such a goal to be proved later. Now, the proof-tree display regards such subsumed goals as proved, as is reported in the theorem prover's output. Fixed a bug that was disallowing [47m[value-triple][0m forms inside [47m[encapsulate][0m forms in a certification [world] (see [portcullis]). If the [47m:load-compiled-file[0m argument of a call of [47m[include-book][0m is [47m:comp[0m, then an existing compiled file will be loaded, provided it is more recent than the corresponding book (i.e., [47m.lisp[0m file). A bug was causing the compiled file to be deleted and then reconstructed in the case of [47m:comp[0m, where this behavior was intended only for [47m:comp![0m. Fixed a bug that was avoiding compilation of some executable counterparts (sometimes called ``*1* functions'') during [47m[certify-book][0m, and also during [47m[include-book][0m with [47m:load-compiled-file[0m value of [47m:comp[0m or [47m:comp![0m). Thanks to Eric Smith for sending a small example to bring this bug to our attention. Incorporated a fix from Eric Smith for a typo (source function [47mancestors-check1[0m) that could cause hard Lisp errors. Thanks, Eric! Fixed the following issues with packages and book [certificate]s. See [hidden-death-package] if you are generally interested in such issues, and for associated examples, see comments on ``Fixed the following issues with packages'' in [47mnote-3-3[0m in the ACL2 source code. o Reduced the size of [47m.cert[0m files by eliminating some unnecessary [47m[defpkg][0m events generated for the [portcullis]. o Fixed a bug that has caused errors when reading symbols from a [portcullis] that are in undefined packages defined in locally included books. o Fixed a bug that could lead to failure of [47m[include-book][0m caused by a subtle interaction between [47m[set-ignore-ok][0m and [47m[defpkg][0m events generated for the [portcullis] of a [certificate]. [31;1mPROVER ALGORITHM ENHANCEMENTS[0m Non-linear arithmetic (see [non-linear-arithmetic]) has been improved to be more efficient or more powerful in some cases. Thanks to Robert Krug for contributing these improvements. Improved certain (so-called ``[47m[type-set][0m'') reasoning about whether or not expressions denote integers. Thanks to Robert Krug for contributing code to implement this change, along with examples illustrating its power that are now distributed in the book [47mbooks/misc/integer-type-set-test.lisp[0m. Improved ACL2's heuristics for relieving hypotheses, primarily to use linear reasoning on conjuncts and disjuncts of the test of an [47m[if][0m expression. For example, given a hypothesis of the form [47m(if (or term1 term2) ...)[0m, ACL2 will now use linear reasoning to attempt to prove both [47mterm1[0m and [47mterm2[0m, not merely for [47mterm2[0m. Thanks to Robert Krug for supplying examples illustrating the desirability of such an improvement and for useful discussions about the fix. Made a slight heuristic change, so that when a hypothesis with [47m[let][0m or [47m[mv-let][0m subterms (i.e. [47m[lambda][0m subterms) rewrites to [47mt[0m, then that hypothesis is necessarily eliminated. Thanks to Jared Davis for sending an example that led us to develop this change, and thanks to Robert Krug for a helpful discussion. [31;1mMISCELLANEOUS[0m Added documentation on how to use [47m[make-event][0m to avoid duplicating expensive computations, thanks to Jared Davis. See [using-tables-efficiently]. Modified the error message for calls of undefined functions to show the arguments. Thanks to Bob Boyer for requesting this enhancement. Modified utilities [47m:[0m[47m[pr][0m, [47m:[0m[47m[pr!][0m, [47m:[0m[47m[pl][0m, and [47m:[0m[47m[show-bodies][0m to incorporate code contributed by Jared Davis. That code defines low-level source functions [47minfo-for-xxx[0m that collect information about rules, which is thus available to advanced users. Dynamic monitoring of rewrites (see [dmr]) has been improved in the following ways, as suggested by Robert Krug. o Some stale entries from the rewrite stack are no longer printed, in particular above [47mADD-POLYNOMIAL-INEQUALITIES[0m. o An additional rewrite stack entry is made when entering non-linear arithmetic (see [non-linear-arithmetic]). o An [47mADD-POLYNOMIAL-INEQUALITIES[0m entry is printed with a counter, to show how often this process is called. Modified [47m[save-exec][0m so that the newly-saved image will have the same raw Lisp package as the existing saved image. This is a very technical change that will likely not impact most users; for example, the package in the ACL2 read-eval-print loop (see [lp]) had already persisted from the original to newly-saved image. Thanks to Jared Davis for suggesting this change. Changed [47m[make-event][0m expansion so that changes to [47m[gag-mode][0m, [47m[set-print-clause-ids][0m, [47mset-fmt-soft-right-margin[0m, and [47mset-fmt-hard-right-margin[0m will persist after being evaluated during [47mmake-event[0m expansion. (Specifically, [47m*protected-system-state-globals*[0m has been modified; see [make-event-details].) Thanks to Jared Davis for bringing this issue to our attention. Output from the [proof-builder] is now always enabled when invoking [47m[verify][0m, even if it is globally inhibited (see [set-inhibit-output-lst]). Improved the message printed when an [47m:induct[0m hint fails, to give more information in some cases. Thanks to Rex Page for suggesting where an improvement could be made and providing useful feedback on an initial improvement. Added a warning for [congruence] rules (see [defcong]) that specify [47m[iff][0m as the second equivalence relation when [47m[equal][0m can be used instead. Those who heed these warnings can eliminate certain subsequent [47m[double-rewrite][0m warnings for [rewrite] rules with conclusions of the form [47m(iff term1 term2)[0m, and hence implicitly for Boolean conclusions [47mterm1[0m that are interpreted as [47m(iff term1 t)[0m. Thanks to Sarah Weissman for sending us an example that highlighted the need for such a warning. Modified macro [47m:[0m[47m[redef!][0m (which is for system implementors) so that it eliminates untouchables. Several improvements have been made to the experimental hons/memoization version of ACL2. See [hons-and-memoization]. The distributed books directory, [47m(@ distributed-books-dir)[0m, is now printed in the start-up message.") (|NOTE-3-3{R}| (release-notes) "ACL2 Version 3.3(r) (November, 2007) Notes Please also see [note-3-3] for changes to Version 3.3 of ACL2.") (note-3-4 (release-notes) "ACL2 Version 3.4 (August, 2008) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 3.3 into changes to existing features, new features, bug fixes, new and updated books, and Emacs support. Each change is described just once, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m Fixed a long-standing potential infinite loop in the rewriter. Thanks to Sol Swords for sending a concise example illustrating the looping behavior. (Those interested in details are welcome to look at the comment about loop behavior in source function [47mrewrite-equal[0m.) Incorporated a slight strengthening of non-linear arithmetic contributed by Robert Krug (thanks, Robert). With non-linear arithmetic enabled, the problem was essentially that ACL2 made the following ``optimization'': given inequalities [47m(< a u)[0m and [47m(< b v)[0m, for positive rational constants [47ma[0m and [47mb[0m terms [47mu[0m and [47mv[0m of which at least one is known to be rational, infer [47m(< (* a b) (* u v))[0m. Without this optimization, however, ACL2 now infers the stronger inequality obtained by direct multiplication of the two given inequalities. To see the effect of this change, submit the event [47m(set-non-linearp t)[0m followed by: (thm (implies (and (rationalp x) (< 3 x) (rationalp y) (< 4 y)) (< 0 (+ 12 (* -4 x) (* -3 y) (* x y))))) The utility [47m[set-checkpoint-summary-limit][0m has been modified in several ways: it now takes a single argument (no longer takes [47m[state][0m as an argument); a natural number [47mn[0m abbreviates the pair [47m(n . n)[0m; the argument is no longer evaluated, but it still optionally may be quoted; and a new value, [47mt[0m, suppresses all printing of the checkpoint summary. Thanks to Jared Davis for suggesting most of these improvements. There was formerly a restriction on [47m[mbe][0m that the [47m:exec[0m argument may not contain a call of [47m[mbe][0m. This restriction has been removed, thanks to a request from Jared Davis and Sol Swords. Thanks also to Sandip Ray, who pointed out that this restriction may have been in place in order that [47m[defexec][0m can guarantee termination using the [47m:exec[0m code; its [documentation] has therefore been updated to clarify this situation. Rules of class [47m:[0m[47m[rewrite][0m are now stored by performing certain logical simplifications on the left side of the conclusion: [47m(prog2$ X Y)[0m is replaced by [47mY[0m, [47m(mbe :logic X :exec Y)[0m is replaced by [47mX[0m (more precisely, the analogous change is made to the generated call of [47m[must-be-equal][0m); and [47m(the TYPE X)[0m is replaced by [47mX[0m (again, the change is actually made on the macroexpanded form). Thanks to Jared Davis and Sol Swords for requesting this change. An analogous change has also been made for rules of class [47m:[0m[47m[forward-chaining][0m. The [47m[trace$][0m utility has been reimplemented to work independently of the underlying Lisp trace. It thus works the same for every host Lisp, except as provided by an interface to the underlying host Lisp trace (the [47m:native[0m option). Note that the host Lisp trace continues to be modified for GCL, Allegro CL, and CCL (OpenMCL); see [trace]. See [trace$] for updated detailed documentation on tracing options, many of which are new, for example an [47m:evisc-tuple[0m option that can be set to [47m:no-print[0m if you want the function traced without the usual entry and exit printing. The previous [47m[trace$][0m had some issues, including the following, which have all been fixed. Thanks to Peter Dillinger for assistance in determining desired functionality of the new [47m[trace$][0m and for helping to test it. Recursive calls were not always shown in the trace for two reasons. (1) Compiler inlining could prevent recursive calls from being shown in the trace, in particular in CCL (OpenMCL). Thanks to Jared Davis and Warren Hunt for pointing out this issue and requesting a fix, and to Bob Boyer and Gary Byers for relevant helpful discussions. (2) ACL2's algorithm for producing executable counterparts prevented tracing of recursive calls even after [47m(set-guard-checking :none)[0m. Thanks to Peter Dillinger for requesting a fix. It was possible to exploit a bug in the interaction of multiple values and trace to prove a contradiction. An example is in a comment in [47m(deflabel note-3-4 ...)[0m in the ACL2 source code. Certain large structures could cause expensive computations for printing even when a [47m:cond[0m condition was specified and evaluated to [47mnil[0m. [47m[Trace!][0m now suppresses printing of the event summary, and returns the value that would be returned (if there is an active trust tag) by the corresponding call of [47m[trace$][0m. Some bugs have been fixed in the underlying native trace installed by ACL2 for GCL, Allegro CL, and CCL (OpenMCL), including the following. In GCL it had been impossible to use the variable [47mARGLIST[0m in a [47m:cond[0m expression. In Allegro CL and CCL, a [47m[trace$][0m bug mishandled tracing non-ACL2 functions when directives such as [47m:entry[0m and [47m:exit[0m were supplied. GCL trace now hides the world even when tracing non-ACL2 functions. Tracing in CCL no longer causes a Lisp error when untracing a traced function defined outside the ACL2 loop; for example [47m(trace$ len1)[0m followed by [47m(untrace$ len1)[0m no longer causes an error. The macro [47mwet[0m has been changed, for the better we think. see [wet]. The generation of goals for [forcing-round]s has been changed to avoid dropping assumptions formerly deemed ``irrelevant''. (A simple example may be found in a comment in source function [47munencumber-assumption[0m, source file [47mprove.lisp[0m.) Thanks to Jared Davis for sending us an example that led us to make this change. Modified the implementation of [47m[make-event][0m so that in the [certificate] of a book, [47m[local][0m events arising from [47m[make-event][0m forms are elided. For example, if [47m(make-event <form>)[0m expands to [47m(local <expanded-form>)[0m, then where the latter had been stored in the certificate, now instead [47m(local (value-triple :ELIDED))[0m will be stored. Thanks to Eric Smith for requesting this improvement. He has reported that a preliminary version of this improvement shrunk a couple of his [47m.cert[0m files from perhaps 40MB each to about 140K each. Now, a [47m[table][0m event that sets the entire table, [47m(table tbl nil alist :clear)[0m, is redundant (see [redundant-events]) when the supplied [47malist[0m is equal to the current value of the table. Thanks to Peter Dillinger for requesting this change. The event constructor [47m[progn!][0m now returns the value that is returned by evaluation of its final form if no error occurs, except that it still returns [47mnil[0m if that final evaluation leaves ACL2 in raw-mode. [47m:[0m[47m[Pso][0m and [47m:[0m[47m[psog][0m have been improved so that they show the key checkpoint summary at the end of a failed proof. (For a discussion of key checkpoints, see [set-gag-mode].) As a result, a call of [47m[set-checkpoint-summary-limit][0m now affects subsequent evaluation of [47m:[0m[47m[pso][0m and [47m:[0m[47m[psog][0m. In particular, you no longer need to reconstruct a proof (by calling [47m[thm][0m or [47m[defthm][0m) in order to see key checkpoints that were omitted due to the limit; just call [47m[set-checkpoint-summary-limit][0m and then run [47m:pso[0m or [47m:psog[0m. The [proof-builder] behaves a little differently under [gag-mode]. Now, proof-builder commands that call the theorem prover to create new proof-builder goals, such as [47mbash[0m and [47minduct[0m (see [proof-builder-commands]), will show key checkpoints when in [gag-mode]. As before, proof-builder commands [47mpso[0m and [47mpso![0m (and now, also [47mpsog[0m) --- see [pso], see [psog], and see [pso!] --- can then show the unedited proof log. However, unlike proof attempts done in the ACL2 loop, such proof attempts will not show a summary of key checkpoints at the end, because from a prover perspective, all such goals were considered to be temporarily ``proved'' by giving them ``byes'', to be dispatched by later proof-builder commands. A little-known feature had been that a [measure] of [47m0[0m was treated as though no measure was given. This has been changed so that now, a [measure] of [47mnil[0m is treated as though no measure was given. Expanded [47m*acl2-exports*[0m to include every documented symbol whose name starts with [47m"SET-"[0m. Thanks to Jared Davis for remarking that [47m[set-debugger-enable][0m was omitted from [47m*acl2-exports*[0m, which led to this change. The [trace] mechanism has been improved so that the [47m:native[0m and [47m:multiplicity[0m options can be used together for Lisps that support the trace [47m:exit[0m keyword. These Lisps include GCL and Allegro CL, whose native trace utilities have been modified for ACL2. For SBCL and CCL (OpenMCL), which use the built-in Lisp mechanism for returning multiple values in ACL2 (see [mv]), the use of [47m:multiplicity[0m with [47m:native[0m remains unnecessary and will be ignored. In support of this change, the modification of native Allegro CL tracing for ACL2 was fixed to handle [47m:exit[0m forms correctly that involve [47m[mv][0m. [31;1mNEW FEATURES[0m The command [47m:[0m[47m[redef!][0m is just like [47m:[0m[47m[redef][0m, but prints a warning rather than doing a query. The old version of [47m:redef![0m was for system hackers and has been renamed to [47m:[0m[47m[redef+][0m. Introduced a new utility for evaluating a function call using the so-called executable counterpart --- that is, executing the call in the logic rather than in raw Lisp. See [ec-call]. Thanks to Sol Swords for requesting this utility and participating in its high-level design. See [print-gv] for a new utility that assists with debugging guard violations. Thanks to Jared Davis for requesting more tool assistance for debugging guard violations. Improved the guard violation error message to show the positions of the formals, following a suggestion of Peter Dillinger. Added new [47m[guard-debug][0m capability to assist in debugging failed attempts at [guard] verification. See [guard-debug]. Thanks to Jared Davis for requesting a tool to assist in such debugging and to him, Robert Krug, and Sandip Ray for useful discussions. New utilities provide the formula to be proved by [47m[verify-guards][0m. See [verify-guards-formula] and see [guard-obligation], Thanks to Mark Reitblatt for making a request leading to these utilities. These utilities can be applied to a term, not just an event name; thanks to Peter Dillinger for correspondence that led to this extension. A new utility causes runes to be printed as lists in proof output from simplification, as is done already in proof summaries. See [set-raw-proof-format]. Thanks to Jared Davis for requesting this utility. An experimental capability allows for parallel evaluation. See [parallelism]. Thanks to David Rager for providing an initial implementation of this capability. Defined [47m[xor][0m in analogy to [47m[iff][0m. Thanks to Bob Boyer, Warren Hunt, and Sol Swords for providing this definition. Improved distributed file [47mdoc/write-acl2-html.lisp[0m so that it can now be used to build HTML documentation files for [documentation] strings in user [books]. See the comment in the definition of macro [47macl2::write-html-file[0m at the end of that file. Thanks to Dave Greve and John Powell for requesting this improvement. It is now possible to specify [47m:[0m[47m[hints][0m for non-recursive function definitions (which can be useful when definitions are automatically generated). See [set-bogus-defun-hints-ok]. Thanks to Sol Swords for requesting such a capability. Keyword argument [47m:dir[0m is now supported for [47m[rebuild][0m just as it has been for [47m[ld][0m. We relaxed the criteria for functional substitutions, so that a function symbol can be bound to a macro symbol that corresponds to a function symbol in the sense of [47m[macro-aliases-table][0m. So for example, a functional substitution can now contain the doublet [47m(f +)[0m, where previously it would have been required instead to contain [47m(f binary-+)[0m. We now allow arbitrary packages in raw mode (see [set-raw-mode]) --- thanks to Jared Davis for requesting this enhancement --- and more than that, we allow arbitrary Common Lisp in raw mode. Note however that for arbitrary packages, you need to be in raw mode when the input is read, not just when the input form is evaluated. Two new keywords are supported by the [47m[with-output][0m macro. A [47m:gag-mode[0m keyword argument suppresses some prover output as is done by [47m[set-gag-mode][0m. Thanks to Jared Davis for asking for a convenient way to set [gag-mode] inside a book, in particular perhaps for a single theorem; this keyword provides that capability. A [47m:stack[0m keyword allows sub-[events] of [47m[progn][0m or [47m[encapsulate][0m to ``pop'' the effect of a superior [47m[with-output][0m call. Thanks to Peter Dillinger for requesting such a feature. See [with-output]. The command [47m[good-bye][0m and its aliases [47m[exit][0m and [47m[quit][0m now all take an optional status argument, which provides the Unix exit status for the underlying process. Thanks to Florian Haftmann for sending a query to the ACL2 email list that led to this enhancement. Keyword commands now work for macros whose argument lists have lambda list keywords. For a macro with a [47mlambda[0m list keyword in its argument list, the corresponding keyword command reads only the minimum number of required arguments. See [keyword-commands]. It is now legal to [47m[declare][0m variables [47mignorable[0m in [47m[let*][0m forms, as in [47m(let* ((x (+ a b)) ...) (declare (ignorable x)) ...)[0m. Thanks to Jared Davis for requesting this enhancement. Added a warning when more than one hint is supplied explicitly for the same goal. It continues to be the case that only the first hint applicable to a given goal will be applied, as specified in the user-supplied list of [47m:hints[0m followed by the [47m[default-hints-table][0m. Thanks to Mark Reitblatt for sending a question that led both to adding this clarification to the [documentation] and to adding this warning. You may now use [47m[set-non-linear][0m, [47m[set-let*-abstraction][0m, [47mset-tainted-ok[0m, and [47m[set-ld-skip-proofs][0m in place of their versions ending in ``[47mp[0m''. Thanks to Jared Davis for suggesting consideration of such a change. All ``[47mset-[0m'' utilities now have a version without the final ``[47mp[0m'' (and most do not have a version with the final ``[47mp[0m''). Added a "Loop-Stopper" warning when a [47m:[0m[47m[rewrite][0m rule is specified with a [47m:[0m[47m[loop-stopper][0m field that contains illegal entries that will be ignored. Thanks to Jared Davis for recommending such a warning. Added a substantial documentation topic that provides a beginner's guide to the use of quantification with [47m[defun-sk][0m in ACL2. Thanks to Sandip Ray for contributing this guide, to which we have made only very small modifications. See [quantifier-tutorial]. [47m[Defun-sk][0m now allows the keyword option [47m:strengthen t[0m, which will generate the extra constraint that is generated for the corresponding [47mdefchoose[0m event; see [defchoose]. Thanks to Dave Greve for suggesting this feature. [31;1mBUG FIXES[0m Fixed a soundness bug related to the use of [47m[mbe][0m inside [47m[encapsulate][0m events. An example proof of [47mnil[0m (before the fix) is in a comment in [47m(deflabel note-3-4 ...)[0m in the ACL2 source code. We therefore no longer allow calls of [47m[mbe][0m inside [47m[encapsulate][0m events that have non-empty [signature]s. Fixed a bug related to the definition of a function supporting the macro [47m[value-triple][0m. Although this bug was very unlikely to affect any user, it could be carefully exploited to make ACL2 unsound: (defthm fact (equal (caadr (caddr (value-triple-fn '(foo 3) nil nil))) 'value) ; but it's state-global-let* in the logic :rule-classes nil) (defthm contradiction nil :hints (("Goal" :use fact :in-theory (disable (value-triple-fn)))) :rule-classes nil) Non-[47m[local][0m definitions of functions or macros are no longer considered redundant with built-ins when the built-ins have special raw Lisp code, because ACL2 was unsound without this restriction! A comment about redundant definitions in source function [47mchk-acceptable-defuns[0m shows how one could prove [47mnil[0m without this new restriction. Note that system utility [47m:[0m[47m[redef+][0m removes this restriction. Although ACL2 already prohibited the use of certain built-in [47m:[0m[47m[program][0m mode functions for [47m[verify-termination][0m and during macroexpansion, we have computed a much more complete list of functions that need such restrictions, the value of constant [47m*primitive-program-fns-with-raw-code*[0m. [This constant was renamed [47m*initial-program-fns-with-raw-code*[0m after Version 8.0.] Modified what is printed when a proof fails, to indicate more clearly which event failed. Fixed a problem with [47m[dmr][0m in CCL (OpenMCL) that was causing a raw Lisp break after an interrupt in some cases. Thanks to Gary Byers for a suggestion leading to this fix. Fixed bugs in [proof-builder] code for dealing with free variables in hypotheses. Upon an abort, the printing of [47m[pstack][0m and [gag-mode] summary information for other than GCL was avoided when inside a call of [47m[ld][0m. This has been fixed. (Windows only) Fixed bugs for ACL2 built on SBCL on Windows, including one that prevented [47m[include-book][0m parameters [47m:dir :system[0m from working, and one that prevented certain compilation. Thanks to Peter Dillinger for bringing these to our attention and supplying a fix for the second. Thanks also to Andrew Gacek for bringing [47m[include-book][0m issues to our attention. Also, fixed writing of file [47msaved_acl2[0m at build time so that for Windows, Unix-style pathnames are used. Fixed a hard Lisp error that could occur with keywords as [47m[table][0m names, e.g., [47m(table :a :a nil :put)[0m. Thanks to Dave Greve for bringing this problem to our attention and providing this example. Fixed handling of [47m:OR[0m [hints] so that proof attempts under an [47m:OR[0m hint do not abort (reverting to induction on the original input conjecture) prematurely. Thanks to Robert Krug for pointing out this problem and pointing to a possible initial fix. (SBCL and CLISP only) It is now possible to read symbols in the [47m"COMMON-LISP"[0m package inside the ACL2 command loop (see [lp]). This could cause a raw Lisp error in previous versions of ACL2 whose host Common Lisp was SBCL or CLISP. Thanks to Peter Dillinger for bringing this issue to our attention. Fixed a bug that was preventing certain [hints], such as [47m:do-not[0m hints, from being used after the application of an [47m:or[0m hint. Thanks to Robert Krug for bringing this bug to our attention. (Hons version only) Fixed a bug in the interaction of [47m[memoize][0m ([47m[hons][0m version only) with event processing, specifically in interaction with failures inside a call of [47m[progn][0m or [47m[encapsulate][0m. Thanks to Jared Davis for bringing this bug to our attention and sending an example. A simplified example may be found in a comment in source function [47mtable-cltl-cmd[0m, source file [47mhistory-management.lisp[0m; search for ``Version_3.3'' there. Fixed [47m[cw-gstack][0m so that its [47m:evisc-tuple[0m is applied to the top clause, instead of using [47m(4 5 nil nil)[0m in all cases. If no [47m:evisc-tuple[0m is supplied then [47m(term-evisc-tuple t state)[0m is used for the top clause, as it is already used for the rest of the stack. Fixed a bug in the interaction of [proof-tree]s with [47m:induct[0m hint value [47m:otf-flg-override[0m. Thanks to Peter Dillinger for reporting this bug and sending an example that evokes it. Fixed bugs in [47m:[0m[47m[pr][0m and [47m[find-rules-of-rune][0m for the case of rule class [47m:[0m[47m[elim][0m. Thanks to Robert Krug and Jared Davis for bringing these related bugs to our attention. Improved failure messages so that the key checkpoints are printed only once when there is a proof failure. Formerly, a proof failure would cause the key checkpoints to be printed for every [47m[encapsulate][0m or [47m[certify-book][0m superior to the proof attempt. Fixed a bug in generation of [guard]s for calls of [47m[pkg-witness][0m. Thanks to Mark Reitblatt for sending an example showing this bug. The bug can be in play when you see the message: ``HARD ACL2 ERROR in MAKE-LAMBDA-APPLICATION: Unexpected unbound vars ("")''. A distillation of Mark's example that causes this hard error is as follows. (defun foo (x) (declare (xargs :guard t)) (let ((y x)) (pkg-witness y))) The [47m[cond][0m macro now accepts test/value pairs of the form [47m(T val)[0m in other than the last position, such as the first such pair in [47m(cond (t 1) (nil 2) (t 3))[0m. Thanks to Jared Davis for sending this example and pointing out that ACL2 was sometimes printing goals that have such a form, and hence cannot be submitted back to ACL2. A few macros corresponding to [47m[cond][0m in some books under [47mbooks/rtl[0m and [47mbooks/bdd[0m were similarly modified. (A second change will probably not be noticeable, because it doesn't affect the final result: singleton [47m[cond][0m clauses now generate a call of [47m[or][0m in a single step of macroexpansion, not of [47m[if][0m. For example, [47m(cond (a) (b x) (t y))[0m now expands to [47m(OR A (IF B X Y))[0m instead of [47m(IF A A (IF B X Y))[0m. See the source code for [47mcond-macro[0m for a comment about this change.) Fixed a bug in the interaction of [proof-builder] command [47mDV[0m, including numeric (``diving'') commands, with the [47m[add-binop][0m event. Specifically, if you executed [47m(add-binop mac fn)[0m with [47mfn[0m having arity other than 2, a [proof-builder] command such as 3 or [47m(dv 3)[0m at a call of [47mmac[0m could have the wrong effect. We also fixed a bug in diving with [47mDV[0m into certain [47mAND[0m and [47mOR[0m calls. Thanks to Mark Reitblatt for bringing these problems to our attention with helpful examples. Fixed a couple of bugs that were causing an error, ``HARD ACL2 ERROR in RENEW-NAME/OVERWRITE''. Thanks to Sol Swords for bringing the first of these bugs to our attention. Fixed a bug that could cause [47m[certify-book][0m to fail in certain cases where there are [47m[local][0m [47m[make-event][0m forms. Fixed a bug in [47m[start-proof-tree][0m that could cause Lisp to hang or produce an error. Thanks to Carl Eastlund for sending an example to bring this bug to our attention. Fixed a bug in the proof output, which was failing to report cases where the current goal simplifies to itself or to a set including itself (see [specious-simplification]). Fixed a bug in [47m[with-prover-time-limit][0m that was causing a raw Lisp error for a bad first argument. Thanks to Peter Dillinger for pointing out this bug. The following was claimed in [47m:doc[0m [47m[note-3-3][0m, but was not fixed until the present release: Distributed directory [47mdoc/HTML/[0m now again includes installation instructions, in [47mdoc/HTML/installation/installation.html[0m. In certain Common Lisp implementations --- CCL (OpenMCL) and LispWorks, at least --- an interrupt could leave you in a break such that quitting the break would not show the usual summary of key checkpoints. This has been fixed. [31;1mNEW AND UPDATED BOOKS[0m Updated [47mbooks/clause-processors/SULFA/[0m with a new version from Erik Reeber; thanks, Erik. Added new books directory [47mtools/[0m from Sol Swords. See [47mbooks/tools/Readme.lsp[0m for a summary of what these books provide. The distributed book [47mbooks/misc/file-io.lisp[0m includes a new utility, [47mwrite-list![0m, which is like [47mwrite-list[0m except that it calls [47m[open-output-channel!][0m instead of [47m[open-output-channel][0m. Thanks to Sandip Ray for requesting this utility and assisting with its implementation. Added [47mrecord-update[0m macro supplied by Sandip Ray to distributed book [47mbooks/misc/records.lisp[0m. Sandip Ray has contributed books that prove soundness and completeness of different proof strategies used in sequential program verification. Distributed directory [47mbooks/proofstyles/[0m has three new directories comprising that contribution: [47msoundness/[0m, [47mcompleteness/[0m, and [47mcounterexamples/[0m. The existing [47mbooks/proofstyles/[0m directory has been moved to its subdirectory [47minvclock/[0m. Jared Davis has contributed a profiling utility for ACL2 built on CCL (OpenMCL). See [47mbooks/misc/oprof.lisp[0m. Thanks, Jared. ACL2 utilities [47m[getprop][0m and [47m[putprop][0m take advantage of under-the-hood Lisp (hashed) property lists. The new book [47mbooks/misc/getprop.lisp[0m contains an example showing how this works. Added the following new book directories: [47mbooks/paco/[0m, which includes a small ACL2-like prover; and [47mbooks/models/jvm/m5[0m, which contains the definition of one of the more elaborate JVM models, M5, along with other files including JVM program correctness proofs. See files [47mReadme.lsp[0m in these directories, and file [47mREADME[0m in the latter. Added [3mbooks[0m about sorting in [47mbooks/sorting[0m. See [47mReadme.lsp[0m in that directory for documentation. Added book [47mbooks/misc/computed-hint-rewrite.lisp[0m to provide an interface to the rewriter for use in computed hints. Thanks to Jared Davis for requesting this feature. Jared Davis has provided a pseudorandom number generator, in [47mbooks/misc/random.lisp[0m. Robert Krug has contributed a new library, [47mbooks/arithmetic-4/[0m, for reasoning about arithmetic. He characterizes it as being more powerful than its predecessor, [47mbooks/arithmetic-3/[0m, and without its predecessor's rewriting loops, but significantly slower than its predecessor on some theorems. Incorporated changes from Peter Dillinger to verify guards for functions in [47mbooks/ordinals/lexicographic-ordering.lisp[0m (and one in [47mordinal-definitions.lisp[0m in that directory). A new directory, [47mbooks/hacking/[0m, contains a library for those who wish to use trust tags to modify or extend core ACL2 behavior. Thanks to Peter Dillinger for contributing this library. Obsolete version [47mbooks/misc/hacker.lisp[0m has been deleted. Workshop contribution [47mbooks/workshops/2007/dillinger-et-al/code/[0m is still included with the workshops/ tar file, but should be considered deprecated. In [47mbooks/make-event/assert.lisp[0m, changed [47massert![0m and [47massert!-stobj[0m to return [47m(value-triple :success)[0m upon success instead of [47m(value-triple nil)[0m, following a suggestion from Jared Davis. [31;1mEMACS SUPPORT[0m Changed [47memacs/emacs-acl2.el[0m so that the fill column default (for the right margin) is only set (still to 79) in lisp-mode. Modified Emacs support in file [47memacs/emacs-acl2.el[0m so that names of events are highlighted just as [47m[defun][0m has been highlighted when it is called. Search in the above file for [47mfont-lock-add-keywords[0m for instructions on how to eliminate this change. The name of the temporary file used by some Emacs utilities defined in file [47memacs/emacs-acl2.el[0m has been changed to have extension [47m.lsp[0m instead of [47m.lisp[0m; thus it is now [47mtemp-emacs-file.lsp[0m. Also, `make' commands to `clean' books will delete such files (specifically, [47mbooks/Makefile-generic[0m has been changed to delete [47mtemp-emacs-file.lsp[0m).") (|NOTE-3-4{R}| (release-notes) "ACL2 Version 3.4(r) (August, 2008) Notes Please also see [note-3-4] for changes to Version 3.4 of ACL2. Fixed makefiles, [47mbooks/nonstd/Makefile[0m and [47mGNUmakefile[0m. The old set-up seemed to work fine as long as all books certified, but it was really broken, for example only certifying some of the books in [47mbooks/nonstd/nsa/[0m, and then only when required by books in other directories. Also fixed the ``[47mclean[0m'' target to clean links rather than to make links.") (note-3-5 (release-notes) "ACL2 Version 3.5 (May, 2009) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 3.4 into the following categories: changes to existing features, new features, heuristic improvements, bug fixes, new and updated books, Emacs support, and experimental [47m[hons][0m version. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m Many improvements have been made to ACL2's ``evisceration'' mechanism for hiding substructures of objects before they are printed, and to related documentation: o A new documentation topic explains evisc-tuples. See [evisc-tuple]. o A new interface, [47m[set-evisc-tuple][0m, has been provided for setting the four global evisc-tuples. See [set-evisc-tuple]. o A new mode, ``iprinting'', allows eviscerated output to be read back in. See [set-iprint]. o Function [47mdefault-evisc-tuple[0m has been deprecated and will probably be eliminated in future releases; use [47mabbrev-evisc-tuple[0m instead. Also eliminated is the brr-term-evisc-tuple (also the user-brr-term-evisc-tuple). The term-evisc-tuple controls printing formerly controlled by the brr-term-evisc-tuple or user-brr-term-evisc-tuple. o ACL2 output is done in a more consistent manner, respecting the intention of those four global evisc-tuples. In particular, more proof output is sensitive to the term-evisc-tuple. Again, see [set-evisc-tuple]. o A special value, [47m:DEFAULT[0m, may be provided to [47m[set-evisc-tuple][0m in order to restore these [evisc-tuple]s to their original settings. o (Details for heavy users of the evisc-tuple mechanism) (1) There are no longer [state] globals named [47muser-term-evisc-tuple[0m or [47muser-default-evisc-tuple[0m. (2) Because of the above-mentioned [47m:DEFAULT[0m, if you have referenced state globals directly, you should use accessors instead, for example [47m(abbrev-evisc-tuple state)[0m instead of [47m(@ abbrev-evisc-tuple)[0m. (3) For uniformity, [47m[set-trace-evisc-tuple][0m now takes a second argument, [47mstate[0m. Improved [47m[break-on-error][0m in several ways. First, it breaks earlier in a more appropriate place. Thanks to Dave Greve for highlighting this problem with the existing implementation. Also, [47m[break-on-error][0m now breaks on hard errors, not only soft errors (see [er], options [47mhard[0m and [47mhard?[0m). Thanks to Warren Hunt and Anna Slobodova for sending an example that showed a flaw in an initial improvement. Finally, new options cause printing of the call stack for some host Common Lisps. See [break-on-error]. Thanks to Bob Boyer for requesting this feature. [47m[Trace!][0m may now be used in raw Lisp (though please note that all soundness claims are off any time you evaluate forms in raw Lisp!). Thanks to Bob Boyer for feedback that led to this enhancement. ACL2 now searches for file [47macl2-customization.lsp[0m in addition to (and just before) its existing search for [47macl2-customization.lisp[0m; See [ACL2-customization]. Thanks to Jared Davis for suggesting this change, which supports the methodology that files with a [47m.lisp[0m extension are certifiable books (thus avoiding the need to set the [47mBOOKS[0m variable in makefiles; see [books-certification-classic]). Improved the error message for illegal [47m[declare][0m forms of the form [47m(type (satisfies ...))[0m. Thanks to Dave Greve for sending an example highlighting the issue. If trace output is going to a file (because [47m[open-trace-file][0m has been executed), then a note will be printed to that effect at the time that a call of [47m[trace$][0m or [47m[trace!][0m is applied to one or more [trace] specs. The notion of redundancy (see [redundant-events]) has been made more restrictive for [47m[mutual-recursion][0m events. Now, if either the old or new event is a [47m[mutual-recursion][0m event, then redundancy requires that both are [47m[mutual-recursion][0m events that define the same set of function symbols. Although we are not aware of any soundness bugs fixed by this modification, nevertheless we believe that it reduces the risk of soundness bugs in the future. The definition of [47mtrace*[0m has been moved to a book, [47mmisc/trace1.lisp[0m. A new version, used in ACL2s, is in book [47mmisc/trace-star.lisp[0m. [Trace] utilities [47m[trace$][0m and [47m[trace!][0m are still built into ACL2. [Note: File [47mmisc/trace1.lisp[0m was deleted after Version 4.2.] Certain [certificate] files will now be much smaller, by printing in a way that takes advantage of structure sharing. Certifying the following example produces a [47m.cert[0m file of over 3M before this change, but less than 1K after the change. (defun nest (i) ;; Makes an exponentially-sized nest of conses i deep. (if (zp i) nil (let ((next (nest (1- i)))) (cons next next)))) (make-event `(defconst *big* ',(nest 20))) Thanks to Sol Swords for providing the above example and to him as well as to Bob Boyer, Jared Davis, and Warren Hunt for encouraging development of this improvement. We have also applied this improvement to the printing of function definitions to files on behalf of [47m[certify-book][0m and [47m[comp][0m. Names of symbols are now printed with vertical bars according to the Common Lisp spec. Formerly, if the first character of a symbol name could be the first character of the print representation of a number, then the symbol was printed using vertical bars ([47m|..|[0m) around its name. Now, a much more restrictive test for ``potential numbers'' is used, which can result in fewer such vertical bars. Base 16 is now carefully considered as well; see [set-print-base]. Thanks to Bob Boyer for requesting this improvement. Note that macros [47mset-acl2-print-base[0m and [47mset-acl2-print-case[0m have been replaced by functions; see [set-print-base] and see [set-print-case]. The ACL2 reader now supports `[47m#.[0m' syntax in place of the `[47m#,[0m syntax formerly supported. Thanks to Bob Boyer for requesting this change. See [sharp-dot-reader]. NOTE that because of this change, `[47m#.[0m' no longer causes an abort; instead please use [47m(a!)[0m or optionally, if in the ACL2 loop, [47m:a![0m; see [a!]. Some small changes have been made related to [gag-mode]: o [Gag-mode] now suppresses some messages that were being printed upon encountering disjunctive splits from [47m:OR[0m [hints]. Thanks to Sol Swords for suggesting this improvement. o ACL2 had printed ``[47mQ.E.D.[0m'' with all output suppressed and [47m[gag-mode][0m enabled. Now, ``[47mQ.E.D.[0m'' will be suppressed when [47mPROVE[0m and [47mSUMMARY[0m output are suppressed, even if [47mgag-mode[0m is enabled. o The use of [47m[set-gag-mode][0m had drastic effects on the inhibited output (see [set-inhibit-output-lst]), basically inhibiting nearly all output (even most warnings) when turning on gag-mode and enabling all output except [47mproof-tree[0m output when turning off gag-mode. Now, [47m[set-gag-mode][0m only inhibits or enables proof ([47mPROVE[0m) output, according to whether gag-mode is being turned on or off (respectively). The related utility [47mset-saved-output[0m has also been modified, basically to eliminate [47m:all[0m as a first argument and to allow [47mt[0m and [47m:all[0m as second arguments, for inhibiting prover output or virtually all output, respectively (see set-saved-output). A [47m[defstub][0m event [signature] specifying output of the form [47m(mv ...)[0m now introduces a [47m:[0m[47m[type-prescription][0m rule asserting that the new function returns a [47m[true-listp][0m result. Thanks to Bob Boyer for sending the following example, which motivated this change. (defstub census (*) => (mv * *)) (defn foo (x) (mv-let (a1 a2) (census x) (list a1 a2))) Improved the efficiency of [47m[string-append][0m so that in raw Lisp, it calls [47m[concatenate][0m. Thanks to Jared Davis for suggesting this change, including the use of [47m[mbe][0m. A minor change was made to the definition of [47m[concatenate][0m to support this change, and the lemma [47mappend-to-nil[0m was added (see below). The checksum algorithm used for [certificate] files of [books] has been changed. Thanks to Jared Davis for contributing the new code. This change will likely not be noticed unless one is using the experimental [47m[hons][0m version of ACL2, where it can greatly speed up book certification and inclusion because of function memoization (of source function [47mfchecksum-obj[0m). Fewer calls are made to the checksum algorithm on behalf of [47m[certify-book][0m and a few other operations. Thanks to Jared Davis for providing data that helped lead us to these changes. Formatted printing directives [47m~p[0m, [47m~q[0m, [47m~P[0m, and [47m~Q[0m are deprecated, though still supported. See [fmt]. Instead, please use [47m~x[0m, [47m~y[0m, [47m~X[0m, and [47m~Y[0m (respectively). As a by-product, rule names in proof output are no longer hyphenated. A new keyword, [47m:multiplicity[0m, is available for tracing raw Lisp functions using the ACL2 [trace] utility. See [trace$]. Users may now control whether or not a slow array access results in a warning printed to the screen (which is the default, as before), and if so, whether or not the warning is followed by a break. See [slow-array-warning]. On linux-like systems (including Mac OS X and SunOS), [47m:[0m[47m[comp][0m will now write its temporary files into the [47m"/tmp"[0m directory, which is the value of [47m[state][0m global [47m'tmp-dir[0m. You can change that directory with [47m(assign tmp-dir "<your_temp_directory_path>")[0m. The messages printed for uncertified books have been enhanced. Thanks to Jared Davis for requesting such an improvement. A function definition that would be redundant if in [47m:[0m[47m[logic][0m mode is now considered redundant even if it (the new definition) is in [47m:[0m[47m[program][0m mode. That is, if a definition is ``downgraded'' from [47m:logic[0m to [47m:program[0m mode, the latter ([47m:program[0m mode) definition is considered redundant. Previously, such redundancy was disallowed, but we have relaxed that restriction because of a scenario brought to our attention by Jared Davis: include a book with the [47m:logic[0m mode definition, and then include a book with the [47m:program[0m mode definition followed by [47m[verify-termination][0m. Thanks, Jared. The ACL2 reader no longer accepts characters other than those recognized by [47m[standard-char-p][0m except for [47m#\Tab[0m, [47m#\Page[0m, and [47m#\Rubout[0m (though it still accepts strings containing such characters). As a result, no [47m[make-event][0m expansion is allowed to contain any such unacceptable character or string. Thanks to Sol Swords for sending an example that led us to make this restriction. A simple example is the following book: (in-package "ACL2") (defconst *my-null* (code-char 0)) (make-event `(defconst *new-null* ,*my-null*)) For this book, a call of [47m[certify-book][0m formerly broke during the compilation phase, but if there was no compilation, then a call of [47m[include-book][0m broke. Now, the error occurs upon evaluation of the [47m[make-event][0m form. ACL2 now collects up [guard]s from [47m[declare][0m forms more as a user might expect, without introducing an unexpected ordering of conjuncts. We thank Jared Davis for sending us the following illustrative example, explained below. (defun f (x n) (declare (xargs :guard (and (stringp x) (natp n) (= (length x) n))) (type string x) (ignore x n)) t) Formerly, a guard was generated for this example by unioning the conjuncts from the [47m:guard[0m onto a list containing the term [47m(string x)[0m generated from the [47mtype[0m declaration, resulting in an effective guard of: (and (natp n) (= (length x) n) (stringp x)) The guard of this guard failed to be verified because [47m(stringp x))[0m now comes after the call [47m(length x)[0m. With the fix, contributions to the guards are collected up in the order in which they appear. So in the above example, the effective guard is the specified [47m:guard[0m; the contribution [47m(stringp x)[0m comes later, and is thus dropped since it is redundant. NOTE by the way that if [47m:guard[0m and [47m:stobjs[0m are specified in the same [47m[xargs][0m form, then for purposes of collecting up the effective guard as described above, [47m:stobjs[0m will be treated as though it comes before the [47m:guard[0m. Modified [47m[close-output-channel][0m to try to do a better job flushing buffers. Thanks to Bob Boyer for helpful correspondence. The notion of ``subversive recursion'' has been modified so that some functions are no longer marked as subversive. See [subversive-recursions], in particular the discussion elaborating on the notion of ``involved in the termination argument'' at the end of that [documentation] topic. Formerly, [47m:[0m[47m[type-prescription][0m rules for new definitions inside [47m[encapsulate][0m forms were sometimes added as [constraint]s. This is no longer the case. See also discussion of the ``soundness bug in the forming of constraints'', which is related. [31;1mNEW FEATURES[0m It is now possible to affect ACL2's termination analysis (and resulting induction analysis). Thanks to Peter Dillinger for requesting this feature. The default behavior is essentially unchanged. But for example, the following definition is accepted by ACL2 because of the use of the new [47m:ruler-extenders[0m features; See [ruler-extenders]. (defun f (x) (declare (xargs :ruler-extenders :all)) (cons 3 (if (consp x) (f (cdr x)) nil))) The following lemma was added in support of the improvement to [47m[string-append][0m described above: (defthm append-to-nil (implies (true-listp x) (equal (append x nil) x))) A mechanism has been provided for users to contribute documentation. See [managing-ACL2-packages] for an example, which contains a link to an external web page on effective use of ACL2 packages, kindly provided by Jared Davis. ACL2 [documentation] strings may now link to external web pages using the new symbol, [47m~url[0m; see markup. Of course, those links appear in the web version of the documentation, but you made need to take a bit of action in order for these to appear as links in the Emacs Info version; see [documentation]. Added [47m[intersectp][0m (similar to [47m[intersectp-eq][0m and [47m[intersectp-equal][0m). The user now has more control over how ACL2 prints forms; See [print-control]. Thanks to Bob Boyer for useful discussions leading to this enhancement. Some Common Lisp implementations only allow the syntax [47mpkg-name::expression[0m when [47mexpression[0m is a symbol. The ACL2 reader has been modified to support a package prefix for arbitrary expressions; see [sharp-bang-reader]. Thanks to Hanbing Liu for a query that led to this feature and to Pascal J. Bourguignon for suggesting an implementation. Ill-formed [documentation] strings need not cause an error. See [47mset-ignore-doc-string-error[0m. Thanks to Bob Boyer for requesting this feature. Type declarations are now permitted in [47mlet*[0m forms; see [let*], see [declare], and see [type-spec]. (For Lisp programmers) Macro [47mwith-live-state[0m has been provided for programmers who refer to free variable [47mSTATE[0m, for example with macros that generate uses of [47mSTATE[0m, and want to avoid compiler warnings when evaluating in raw Lisp. For example, the following form can be submitted either inside or outside the ACL2 loop to get the desired effect (see [47mdoc-string[0m): [47m(with-live-state (f-put-global 'doc-prefix " " state))[0m. For another example use of this macro, see the definition of [47mtrace$[0m (ACL2 source file [47mother-events.lisp[0m). (System hackers only) Added [47m:[0m[47m[redef-][0m to undo the effect of [47m:[0m[47m[redef+][0m. See [redef-]. Function [47m[random$][0m is a built-in random number generator. See [random$]. Thanks to Sol Swords for requesting this feature and providing an initial implementation. [31;1mHEURISTIC IMPROVEMENTS[0m Sped up [guard] generation for some functions with large if-then-else structures in their bodies. Thanks to Sol Swords for sending an illustrative example. Sped up [guard] generation in some cases by evaluating ground (variable-free) subexpressions. Thanks to Bob Boyer for sending a motivating example: [47m(defn foo (x) (case x ((1 2) 1) ((3 4) 3) ... ((999 1000) 999)))[0m. Modified slightly a heuristic association of ``size'' with constants, which can result in significant speed-ups in proofs involving constants that are very large [47mcons[0m trees. Added a restriction in the linear arithmetic procedure for deleting polynomial inequalities from the linear database. Formerly, an inequality could be deleted if it was implied by another inequality. Now, such deletion requires that certain heuristic ``parent tree'' information is at least as restrictive for the weaker inequality as for the stronger. Thanks to Dave Greve for bringing a relevant example to our attention and working with us to figure out some surprising behavior, and to Robert Krug for making a key observation leading to the fix. (GCL especially) Improved compiled code slightly by communicating to raw Lisp the output type when a function body is of the form [47m(the character ...)[0m. This tiny improvement will probably only be observed in GCL, if at all. Applied a correction suggested by Robert Krug to the variant of [47m[term-order][0m used in parts of ACL2's arithmetic reasoning. [31;1mBUG FIXES[0m Fixed bugs in the handling of [47m[flet][0m expressions, one of which had the capability of rendering ACL2 unsound. Thanks to Sol Swords for pointing out two issues and sending examples. One example illustrated how ACL2 was in essence throwing away outer [47m[flet][0m bindings when processing an inner [47mflet[0m. We have exploited that example to prove a contradiction, as follows: this book was certifiable before this fix. (in-package "ACL2") (defun a (x) (list 'c x)) ; Example from Sol Swords, which failed to be admitted (claiming that ; function A is undefined) without the above definition of A. (defun foo1 (x y) (flet ((a (x) (list 'a x))) (flet ((b (y) (list 'b y))) (b (a (list x y)))))) (defthm not-true (equal (foo1 3 4) '(b (c (3 4)))) :hints (("Goal" :in-theory (disable (:executable-counterpart foo1)))) :rule-classes nil) (defthm contradiction nil :hints (("Goal" :use not-true)) :rule-classes nil) Sol's second example, below, pointed to a second bug related to computing output signatures in the presence of nested [47mflet[0m expressions, which we have also fixed: this form failed before the fix. :trans (flet ((foo (a) (list (flet ((bar (b) b)) a)))) x) Fixed a subtle soundness bug in the forming of constraints from deduced type prescriptions. As a result, when ACL2 prints a warning message labeling encapsulated functions as ``subversive'', ACL2 will no longer deduce [47m:[0m[47m[type-prescription][0m rules for those functions. Examples that exploit the bug in ACL2 Version_3.4 may be found in comments in ACL2 source function [47mconvert-type-set-to-term[0m (file [47mother-processes.lisp[0m) and especially in function [47mputprop-type-prescription-lst[0m (file [47mdefuns.lisp[0m). For more on the general issue of ``subversive recursions,'' see [subversive-recursions].) Fixed a soundness bug in the handling of inequalities by the [type-set] mechanism, which was using the inequality database inside the body of a [47m[lambda][0m. Fixed a long-standing soundness bug in [47m[compress1][0m and [47m[compress2][0m, whose raw Lisp code gave the logically incorrect result in the case of a single entry other than the [47m[header][0m, where that entry mapped an index to the [47m[default][0m value. Also fixed soundness bugs in [47m[compress1][0m, in the case of [47m:order >[0m, where the raw Lisp code could drop the [47m[header][0m from the result or, when the input alist had entries in ascending order, fail to return an alist in descending order. For example, the following book certified successfully. (in-package "ACL2") (defthm true-formula-1 (equal (compress1 'a '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5 :DEFAULT 1 :NAME A :ORDER <) (1 . 1))) '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5 :DEFAULT 1 :NAME A :ORDER <))) :hints (("Goal" :in-theory (disable (compress1)))) :rule-classes nil) (defthm ouch-1 nil :hints (("Goal" :use true-formula-1)) :rule-classes nil) (defthm true-formula-2 (equal (compress1 'a '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5 :DEFAULT NIL :NAME A :ORDER >) (1 . 1) (2 . 2))) '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5 :DEFAULT NIL :NAME A :ORDER >) (2 . 2) (1 . 1))) :hints (("Goal" :in-theory (disable (compress1)))) :rule-classes nil) (defthm ouch-2 nil :hints (("Goal" :use true-formula-2)) :rule-classes nil) (defthm true-formula-3 (equal (compress1 'a '((:HEADER :DIMENSIONS (3) :MAXIMUM-LENGTH 4 :NAME A :ORDER >) (1 . B) (0 . A))) '((:HEADER :DIMENSIONS (3) :MAXIMUM-LENGTH 4 :NAME A :ORDER >) (1 . B) (0 . A))) :hints (("Goal" :in-theory (disable (compress1)))) :rule-classes nil) (defthm ouch-3 nil :hints (("Goal" :use true-formula-3)) :rule-classes nil) Fixed a soundness bug involving measured subsets and [47m[verify-termination][0m, by changing [47m[verify-termination][0m so that it uses [47m[make-event][0m. See [verify-termination], in particular the discussion about [47m[make-event][0m near the end of that [documentation] topic. Peter Dillinger first raised the idea to us of making such a change; when we found this soundness bug, we were certainly happy to do so! Fixed a bug that could cause a hard Lisp error but not, apparently, unsoundness. The bug was in the lack of attention to the order of guard and type declarations when checking for redundancy. In the following example, the second definition was redundant during the first pass of the [47m[encapsulate][0m form. The second definition, however, was stored on the second pass with a guard of [47m(and (consp (car x)) (consp x))[0m, which caused a hard Lisp error when evaluating [47m(foo 3)[0m due to a misguided attempt to evaluate [47m(car 3)[0m in raw Lisp. The fix is to restrict redundancy of definitions so that the guard and type declarations must be in the same order for the two definitions. (encapsulate () (local (defun foo (x) (declare (xargs :guard (consp x))) (declare (xargs :guard (consp (car x)))) x)) (defun foo (x) (declare (xargs :guard (consp (car x)))) (declare (xargs :guard (consp x))) x)) ; Now we get a hard Lisp error from evaluation of the guard of foo: (foo 3) Fixed a bug in the guard violation report for function [47m[intern-in-package-of-symbol][0m. Thanks to Dave Greve for bringing this bug to our attention. Made a change to allow certain [hints], in particular certain [47m:[0m[47m[clause-processor][0m hints, that had previously caused errors during termination proofs by viewing the function being defined as not yet existing. Thanks to Sol Swords for bringing this issue to our attention with a nice example. ACL2 now properly handles interrupts (via control-c) issued during printing of the checkpoint summary. Previously it was possible on some platforms to make ACL2 hang when interrupting both during a proof and during the ensuing printing of the checkpoint summary. Thanks to Jared Davis and Sol Swords for bringing this problem to our attention. Fixed a bug that was preventing, inside some book [47m"b"[0m, the use of a [47m:dir[0m argument to [47m[include-book][0m that refers to a directory defined using [47m[add-include-book-dir][0m earlier in the book [47m"b"[0m. (We found this ourselves, but we thank John Cowles for observing it independently and sending us a nice example.) (GCL and CCL only) Fixed a bug in certain under-the-hood type inferencing. Thanks to Sol Swords for sending an example using [stobj]s defined with the [47m:inline[0m keyword, along with a helpful backtrace in CCL, and to Gary Byers for his debugging help. Fixed a bug in [47m[print-gv][0m, which was mishandling calls of functions with more than one argument. Fixed a bug in the handling of [47m[and][0m and [47m[or][0m terms by the [proof-builder] command [47mDV[0m, including numeric (``diving'') commands. Thanks for Mark Reitblatt for bringing this problems to our attention with a helpful example. Fixed printing of goal names resulting from the application of [47m:OR[0m [hints] so that they aren't ugly when working in other than the [47m"ACL2"[0m package. Thanks to Sol Swords for bringing this issue to our attention. Fixed [proof-tree] printing so that interrupts will not cause problems with hiding ordinary output because of incomplete proof-tree output. Thanks to Peter Dillinger for pointing out this issue. Fixed a hard error that could be caused by mishandling a [47m[force][0md hypothesis during [forward-chaining]. Thanks to Peter Dillinger for bringing this bug to our attention by sending a useful example. Fixed a bug that could cause simplifications to fail because of alleged ``specious simplification.'' This bug could appear when deriving an equality from the linear arithmetic database, and then attempting to add this equality to the current goal's hypotheses when it was already present. Thanks to Eric Smith for sending a helpful example (in July 2005!) that helped us debug this issue. Fixed a bug in processing of [47m:[0m[47m[type-set-inverter][0m rules. Fixed a bug that was causing an error, at least for an underlying Lisp of CCL (OpenMCL), when [47m[ec-call][0m was applied to a term returning multiple values. Thanks to Sol Swords for sending an example that brought this bug to our attention. Fixed handling of array orders to treat keyword value [47m:order :none[0m correctly from an array's [47m[header][0m. Previously, there were two problems. One problem was that [47m:order :none[0m was treated like the default for [47m:order[0m, [47m<[0m, while [47m:order nil[0m was treated in the manner specified by [47m:order :none[0m (see [arrays]). Now, both [47m:order :none[0m and [47m:order nil[0m are treated as [47m:order nil[0m had been treated, i.e., so that there is no reordering of the alist by [47m[compress1][0m. The other problem with this case of [47m:order[0m was that the [47m:maximum-length[0m field of the [47m[header][0m was not being respected: the length could grow without bound. Now, as previously explained (but not previously implemented) --- see [arrays] --- a [47m[compress1][0m call made on behalf of [47maset1[0m causes a hard error if the header of the supplied array specifies an [47m:order[0m of [47m:none[0m or [47mnil[0m. An [47mignorable[0m [47m[declare][0m form had caused an error in some contexts when it should have been allowed. In particular, this problem could arise when using an [47mignorable[0m declaration at the top level in a [47m[defabbrev][0m form. It could also arise upon calling [47m[verify-termination][0m when the corresponding [47m[defun][0m form contained an [47mignorable[0m declaration at the top level. These bugs have been fixed. Contrary to existing documentation (see [make-event-details]), the value of ``[47m[ld][0m special variable'' [47m[ld-skip-proofsp][0m was always set to [47mnil[0m during [47m[make-event][0m expansion, not merely when the [47mmake-event[0m form has a non-[47mnil[0m value for keyword parameter [47m:check-expansion[0m. This has been fixed. Thanks to Sol Swords for bringing this issue to our attention. We have disallowed the certification of a book when not at the top-level, either directly in the top-level loop or at the top level of [47m[ld][0m. Before this restriction, the following would certify a book with a definition such as [47m(defun foo (x) (h x))[0m that calls function [47mh[0m before defining it, if the certification was by way of the form such as: (er-progn (defun h (x) x) (certify-book "my-book")) But a subsequent [47m[include-book][0m of [47m"my-book"[0m would then fail, because [47mh[0m is not defined at the top level. Printing with [47m[fmt][0m directive [47m~c[0m now works properly even when the print-base is other than 10. Thanks to Sol Swords for reporting this bug and providing a fix for it. (SBCL, CMUCL, and CCL only) Fixed a bug in [47m[sys-call-status][0m in the case that the underlying Common Lisp is SBCL, CMUCL, or CCL (OpenMCL). Thanks to Jun Sawada for bringing this bug to our attention and providing a fix. Fixed a bug that was preventing [47m[local][0m [47m[defstobj][0m events in [47m[encapsulate][0m events. Thanks to Jared Davis for bringing this bug to our attention. Fixed a bug evidenced by error message ``Unexpected form in certification world'', which could result from attempting to certify a book after evaluating an [47m[encapsulate][0m form with a local [47m[defmacro][0m. Thanks to Jared Davis for pointing out this bug and sending the example: (encapsulate () (local (defmacro foo (x) `(table foo 'bar ,x))) (local (foo 3))) Formerly, evaluating a [47m[trace$][0m form inside a [wormhole] such as the [break-rewrite] loop could leave the user in a bad state after returning to the top level, in which that function could not be untraced. This has been fixed. Note however that when you proceed from a break in the [break-rewrite] loop, the tracing state will be the same as it was when you entered that break: all effects of calling [47m[trace$][0m and [47m[untrace$][0m are erased when you proceed from the break. A [47m:[0m[47m[guard][0m of [47m(and)[0m is no longer ignored. Thanks to Sol Swords for bringing this bug to our attention. A bug has been fixed that could result in needlessly weak induction schemes in the case that a recursive call is made in the first argument of [47m[prog2$][0m. This has been fixed by including [47m[prog2$][0m as a default ruler-extender in the new ruler-extenders feature (see above, and see [ruler-extenders]). For details on this bug see Example 11 in distributed book [47mbooks/misc/misc2/ruler-extenders-tests.lisp[0m. (For CCL/OpenMCL on Windows) ACL2 should now build on CCL (OpenMCL) on Windows. Thanks to David Rager for bringing this issue to our attention and helping with a fix that worked for CCL 1.2, and to the CCL team for improving handling of Windows-style filenames in CCL 1.3. [31;1mNEW AND UPDATED BOOKS[0m See {ReleaseVersionNumbers | https://code.google.com/p/acl2-books/wiki/ReleaseVersionNumbers} for a list of books in Version 3.5 of ACL2 but not Version 3.4. Run the shell command [47msvn log -r 94:HEAD[0m to see all changes to [47mbooks/[0m since the release of Version 3.4. Here are just a few highlights. Thanks largely to Jared Davis, many [47mMakefile[0ms have been improved to do automatic dependency analysis. See [books-certification-classic] for how to get your own [47mMakefile[0ms to do this by adding a line: [47m-include Makefile-deps[0m. Libraries [47mbooks/arithmetic-4/[0m and [47mbooks/rtl/rel7/[0m have been eliminated from the default book certification ([47mmake regression[0m), in favor of new libraries [47mbooks/arithmetic-5/[0m and [47mbooks/rtl/rel8/[0m contributed by Robert Krug and Hanbing Liu, respectively. They and Jun Sawada have arranged the compatibility of these libraries; i.e., it is possible to evaluate both of the following in the same session: (include-book "arithmetic-5/top" :dir :system) (include-book "rtl/rel8/lib/top" :dir :system) Library [47mbooks/rtl/rel1/[0m is no longer certified by default (though it is still distributed in support of ACL2(r); see [real]). [31;1mEMACS SUPPORT[0m Slightly modified [47mControl-t e[0m (defined in [47memacs/emacs-acl2.el[0m) to comprehend the notion of an ``ACL2 scope'', and added [47mControl-t o[0m to insert a superior [47m[encapsulate][0m defining such a scope. See the Emacs documentation for [47mControl-t e[0m (generally obtained after typing [47mControl-h k[0m). Modified distributed file [47memacs/emacs-acl2.el[0m so that if you put the following two forms in your [47m~/.emacs[0m file above the form that loads [47memacs/emacs-acl2.el[0m, then Emacs will not start up a shell. Thanks to Terry Parks for leading us to this modification. (defvar acl2-skip-shell nil) (setq acl2-skip-shell t) [31;1mEXPERIMENTAL HONS VERSION[0m Bob Boyer and others have contributed numerous changes for the experimental ``[47mhons[0m'' version of ACL2 (see [hons-and-memoization]). The ACL2 [47m[state][0m can now be queried with [47mhons-enabledp[0m so that a result of [47mt[0m says that one is in the experimental [47mhons[0m version, while [47mnil[0m says the opposite.") (|NOTE-3-5{R}| (release-notes) "ACL2 Version 3.5(r) (May, 2009) Notes Please also see [note-3-5] for changes in Version 3.5 of ACL2. This release incorporates improvements from Ruben Gamboa in support for non-standard analysis in ACL2(r), in the following ways: ACL2(r) now supports non-classical objects that are not also numeric, e.g., non-classical cons pairs. Consequently, the built-in [47mstandard-numberp[0m has been replaced with [47m[standardp][0m. If [47mf[0m is a classical function, the value [47m(f x1 ... xn)[0m is guaranteed to be standard when the [47mxi[0m are standard. ACL2(r) can now recognize this fact automatically, using [47mdefun-std[0m. For example, the following can be used to assert that the square root of 2 is a standard value. (defthm-std sqrt-2-rational (standardp (acl2-sqrt 2))) More generally, the expression [47m(f x1 ... xn)[0m can contain free variables, but the result is guaranteed to be standard when the variables take on standard variables, as in the following: (defthm-std sqrt-x-rational (implies (standardp x) (standardp (acl2-sqrt x)))) A potential soundness bug in [47m[encapsulate][0m was fixed. Specifically, when a classical, constrained function is instantiated with a lambda expression containing free variables, it may produce non-standard values depending on the values of the free variables. This means that the functional instantiation cannot be used to justify a non-classical theorem. For example, consider the following sequence: (encapsulate ((f (x) t)) (local (defun f (x) x))) (defthm-std f-x-standard (implies (standardp x) (standardp (f x)))) (defthm plus-x-standard (implies (standardp x) (standardp (+ x y))) :hints (("Goal" :use ((:functional-instance f-x-standard (f (lambda (x) (+ x y)))))))) (defthm plus-x-eps-not-standard (implies (standardp x) (not (standardp (+ x (/ (i-large-integer))))))) (defthm nil-iff-t nil :hints (("Goal" :use ((:instance plus-x-standard (y (/ (i-large-integer)))) (:instance plus-x-eps-not-standard))))) ACL2(r) also supports the introduction of non-classical functions with [47m[defchoose][0m. These behave just as normal functions introduced with [47m[defchoose][0m, but they have a non-classical choice property. Finally, ACL2(r) now comes with a revamped library supporting non-standard analysis, still distributed separately as [47mbooks/nonstd/[0m. The new library uses [47m[defchoose][0m to state more natural and useful versions of the IVT, MVT, etc. It also supports the introduction of inverse functions, e.g., logarithms. Finally, the library has much more extensive support for differentiation.") (note-3-6 (release-notes) "ACL2 Version 3.6 (August, 2009) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 3.5 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, distributed books, Emacs support, and experimental [hons-and-memoization] version. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that (starting with ACL2 Version 3.5) LispWorks is no longer supported as a platform for ACL2, as the LispWorks compiler could not handle the ACL2 sources; see comments in the ACL2 sources about ``function size'' being ``too large''. [31;1mCHANGES TO EXISTING FEATURES[0m In the [47m[xargs][0m [47m[declare][0m form, the function symbol (or symbols, plural, in the case of [47m[mutual-recursion][0m) being defined may now be used in the specified [47m:measure[0m and [47m:[0m[47m[guard][0m terms. Note that, the definition(s) of the new symbol(s) are still not used in the termination proof. Thanks to Daron Vroon for discussions leading to this addition for the measure and to Dave Greve for requesting such an enhancement for the guard. Processing of the [47m:guard-hints[0m in an [47m[xargs][0m [47m[declare][0m form is now delayed until the start of [guard] verification. As a result, the function symbol(s) being defined may now be used as one might expect in such hints, for example in an [47m:in-theory[0m form. Thanks to Jared Davis for suggesting that we make such an improvement and providing an example. Made a low-level change to [47m[make-event][0m in support of the ACL2s utility ``[47mdynamic-make-event[0m''. Thanks to Peter Dillinger for explaining the issue leading to this change. Modified the failure message printed when a measure conjecture fails to be proved, to indicate whether or not the hint [47m:ruler-extenders :all[0m would create a different measure conjecture. Thanks to Peter Dillinger for suggesting such a modification. A call of [47m[add-default-hints][0m had added hints to the end of the current list of default hints. Now, it adds them to the beginning of that list, so that they are tried first. However, [47m[add-default-hints][0m now takes a keyword argument, [47m:at-end[0m. If that argument is supplied and evaluates to other than [47mnil[0m, then the previous behavior occurs. When [47m[save-exec][0m is used to save ACL2 images, the build dates are now printed on separate lines at startup and in the executable script. Thanks To Bob Boyer for requesting some newlines. [47m[Forward-chaining][0m rules are now generated so that every [47m[let][0m (also [47m[let*][0m and [47m[lambda][0m) expression is expanded away, as is every call of a so-called ``guard holder'' ([47m[must-be-equal][0m, [47m[prog2$][0m, [47m[ec-call][0m, [47m[the][0m). These were formerly only expanded away in the conclusion. Thanks to Konrad Slind for a helpful email leading to this change. [47m[Current-theory][0m now causes a hard error when applied to a name not found in the current ACL2 logical [world], rather than simply returning [47mnil[0m. When the underlying Common Lisp is GCL, ACL2 no longer uses the [47m#n=[0m reader macro when writing out certain files, including [certificate] files. In all other Lisps, it now uses the [47m#n=[0m ``print-circle'' feature not only for [certificate] files and ``[47mexpansion.lsp[0m'' files written for example in support of [47m[make-event][0m, but also for files written in support of [47m:[0m[47m[comp][0m. This is all managed with new [state] global variable [47mprint-circle-files[0m; see [print-control]. Thanks to Dave Greve for pointing out that GCL is limited by default to 1024 indices for [47m#n=[0m. [31;1mNEW FEATURES[0m A documentation topic explains in some detail how [hints] work with the ACL2 proof ``waterfall'': see [hints-and-the-waterfall]. This topic may be useful to those who write computed hints (see [computed-hints]) or other advanced hints. Added a new hint keyword, [47m:no-thanks[0m, that avoids printing the usual ``Thanks'' message for [hints]. Thanks to Peter Dillinger for requesting this feature. Added a new hint keyword, [47m:backtrack[0m, that checks the goals produced by processing a goal, and can cause the goal to be re-processed using a new hint. See [hints]. Thanks to Pete Manolios for a conversation that led to the idea of this hint. Added a new class of hints, [override-hints], that is similar to [default-hints], except that override-hints are always applied, even if the user has supplied a hint explicitly for the goal. See [override-hints]. Thanks to Pete Manolios and Harsh Raju Chamarthi for useful discussions on this topic, including its application to testing. When a goal ready to be pushed for proof by induction is given the new hint ``[47m:do-not-induct :otf[0m'', it is indeed pushed for proof by induction, rather than causing immediate failure as in the case of the hint ``[47m:do-not-induct t[0m''. Instead, the proof fails when the goal is later picked to be proved by induction. Thanks to Peter Dillinger for discussions leading to this feature. Related to computed hints only: Each history entry in the list stored in variable [47mHIST[0m (see [computed-hints]) now has a [47m:CLAUSE[0m field, which provides access to a goal's parent, parent's parent, and so on (within the same induction and forcing round only). It is now possible to inhibit warnings produced by [47m[in-theory][0m [events] and [hints] that occur when certain built-in definitions and executable-counterparts are disabled: just evaluate [47m(assign verbose-theory-warning nil)[0m. Thanks to Jared Davis (and probably others in the past) for requesting such a mechanism. [31;1mHEURISTIC IMPROVEMENTS[0m A source function ([47mlinearize-lst[0m) was replaced by tail-recursive code, which can avoid a stack overflow. Thanks to Dave Greve for sending a helpful example. The heuristics for limiting [forward-chaining] have been slightly relaxed, to allow derivations based on the occurrence of all arguments of the forward-chaining rule's conclusion in the goal (after stripping leading calls of [47mNOT[0m). Thanks to Dave Greve for contributing this improvement and providing a motivating example. We simplified induction schemes by eliminating each hypothesis of the form [47m(not (equal term (quote const)))[0m for which some other hypothesis in the same case equates term with some (presumably other) quoted constant. Thanks to Dave Greve for requesting an improvement of this sort. [31;1mBUG FIXES[0m Fixed a soundness bug related to redundancy of [47m[encapsulate][0m events (see [redundant-events]) and [ruler-extenders]. A proof of [47mnil[0m in ACL2 Version 3.5 appears in a comment in [47m(deflabel note-3-6 ...)[0m in the ACL2 source code. The fix is to insist that in order for one [47m[encapsulate][0m event to be redundant with another, they must be evaluated with the same [default-ruler-extenders]. Analogous to this issue of [default-ruler-extenders] for [47m[encapsulate][0ms is an issue of the [default-verify-guards-eagerness], which has similarly been fixed. Fixed soundness bugs related to the handling of [subversive-recursions] for [constraint]s. Proofs of [47mnil[0m in ACL2 Version 3.5 appear in a comment in [47m(deflabel note-3-6 ...)[0m in the ACL2 source code. Fixed a bug that could cause the following error during calls of [47m[certify-book][0m in the presence of calls of [47m[skip-proofs][0m in the book: ACL2 Warning [Skip-proofs] in HARD ACL2 ERROR in FMT0: Illegal Fmt Syntax. The tilde-@ directive at position 0 of the string below is illegal because its variable evaluated to 0, which is neither a string nor a list. "~@0" Thanks to Dave Greve for reporting this bug and making available a very helpful test case. The [47m:corollary[0m of a rule (see [rule-classes]) failed to use the [47m[default-hints][0m of the logical [world]. This has been fixed. (CCL only) We removed a call, for CCL 1.3 (and beyond) only, of foreign function [47msync[0m in the closing of output channels. Thanks to Daron Vroon for reporting issues with such a call on a non-Intel platform. Fixed a bug in reporting failures when monitoring rewrite rules with free variables in the hypotheses, that could cause a hard Lisp error (from which ACL2 continues, however). Thanks to Eric Smith for sending a very helpful example with his bug report. Fixed the handling of [47m:induct[0m [hints], which had thrown away hint information from parent goals. For example, the [47m[thm][0m form below failed to prove even though the second hint is in some sense superfluous; induction occurs automatically at [47m"Goal'"[0m even without the hint on that. The failure was due to discarding the hint information on [47m"Goal"[0m. (in-theory (disable append)) (thm (equal (cdr (cons a (append (append x y) z))) (append x y z)) :hints (("Goal" :in-theory (enable append)) ("Goal'" :induct t) ; failed unless this line is commented out )) Fixed a bug in the [47m[args][0m command that was failing to show the formals of primitives (built-in functions like [47mconsp[0m that do not come with explicit definitions). Thanks to John Cowles for pointing out this bug. (At a lower level, the bug was that primitives failed to have [47m'stobjs-in[0m or [47m'stobjs-out[0m properties.) Fixed bugs in the utility supporting moving directories of certified books, sometimes used in Debian builds (as described in source function [47mmake-certificate-file[0m). Thanks to Alan Dunn for pointing out such a bug, in paths associated with [47m[defpkg][0m events in [portcullis] commands in [certificate]s (which are used for error reporting). There were also bugs, now fixed, that prevented renaming some book paths. Please note that this mechanism is not guaranteed to be sound; in particular, it can probably misbehave when macros are used to generate portcullis events. However, it seems likely that such issues will be very rare. Eliminated warnings that could arise when tracing a function with [47m[trace$][0m. Now, when [47m[trace$][0m is applied to a function without option [47m:native[0m, that function's declarations and documentation are discarded. Fixed a bug that could cause a failure when building an executable image using SBCL as the underlying Common Lisp. Thanks to Jun Sawada for reporting this failure. We made a similar fix for CMUCL. Fixed a bug in [47m[save-exec][0m in the case that an absolute pathname is supplied. Thanks to Jared Davis for bringing this bug to our attention. Fixed a bug in the use of [47m[trace$][0m with the [47m:native[0m and [47m:multiplicity[0m options that caused hard errors for some underlying Lisps. Fixed a bug in the interaction of [47m[trace$][0m and [47m:[0m[47m[comp][0m, which caused error as [47m[comp][0m tried to re-trace functions that it temporarily untraced. [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m See {ReleaseVersionNumbers | https://code.google.com/p/acl2-books/wiki/ReleaseVersionNumbers} for a list of books in Version 3.6 of ACL2 but not Version 3.5. For [3mchanges[0m to existing books rather than [3madditions[0m, see the {log entries | http://code.google.com/p/acl2-books/source/list} starting with revision r286 up through revision r329. It is no longer required to specify a value for environment (or `make') variable [47mACL2_SYSTEM_BOOKS[0m when running `make' in the distributed book directory, even when that directory is not under the directory containing the ACL2 executable. Thanks to Peter Dillinger for providing this improvement, by modifying [47mbooks/Makefile-generic[0m and, as needed, distributed book Makefiles. Thanks to Peter Dillinger, some books in support of the ACL2 Sedan (ACL2s) are more easily available for ACL2 users who do not use ACL2s. See [ACL2-sedan]. [31;1mEMACS SUPPORT[0m If the following form is evaluated before the load of [47memacs/emacs-acl2.el[0m, then variables are now set to reflect the directory containing that file. (if (boundp '*acl2-sources-dir*) (makunbound '*acl2-sources-dir*)) Fixed info-dir-entry line in generated info file (by patching [47mdoc/write-acl2-texinfo.lisp[0m). Thanks to Alan Dunn for providing this patch. [31;1mEXPERIMENTAL HONS VERSION[0m Bob Boyer and others have contributed numerous changes for the experimental ``[47mhons[0m'' version of ACL2 (see [hons-and-memoization]). A number of these have been crafted to work specifically with CCL (Clozure Common Lisp, formerly OpenMCL), which is now required as the underlying Lisp for the ``[47mhons[0m'' version of ACL2. A heuristic (source function [47mtoo-many-ifs[0m has been made more scalable (for the non-HONS version as well, in fact), but with no functional change. Thanks to Jared Davis for noticing performance issues and suggesting fixes. Other changes including the following, quoting Bob Boyer: The CCL CASE macro now does better than a dumb linear search in some CASEes. SH and CSH are functions to talk to the underlying Gnu-Linux from CCL. Good for repeated calling when you simply cannot afford the copying cost of a FORK because you are using, say, a dozen gigabytes. Added CCL compiler-macros for IF and OR, to support some 'coverage' analysis, cf. IF-REPORT, extending the profiling. Introduced the type 'mfixnum' so that things like counting honses and counting calls to memoized or profiled functions can run fast in CCL 64 bits and yet still run at all under 32 bits. Moved all HONSes to CCL's newish static space, which permits the address of a cons to be used as a hash key, as in most Lisps. (CCL moves most conses and most everything when it does a compacting-gc.) Quite a few changes in the memoize-fn reporting. Added a timer facility, cf. call-with-timeout. Good for running under throttle some gross thoughts like 'Is it true that you can't fit 12 pigeons into 11 holes' on some propositional calculus systems/functions. Added rwx-size, pid-owner-cmdlines, rss, and proc-stat to help see what is really going on virtually in Gnu-Linux. Fixed at least one bug in compact-print-file and helped make its integration into ACL2's read-object$ a little more sound. Still worried some about *print-readably* vs. readtable-case. Does anyone else stay awake late at night worrying about readtable-case? Revised how the *watch-dog-process* interrupts the main process for the thousandth time, cf. watch. Haven't changed it in weeks, which means that (a) it is getting tolerable or (b) I've run out of gas.") (note-3-6-1 (release-notes) "ACL2 Version 3.6.1 (September, 2009) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. The essential changes to ACL2 since Version 3.6 are the two bug fixes described below. There was also some functionality-neutral code refactoring, as requested by Daron Vroon in support of the ACL2 Sedan (see [ACL2-sedan]). Also see {ReleaseVersionNumbers | https://code.google.com/p/acl2-books/wiki/ReleaseVersionNumbers} for a list of books in Version 3.6.1 of ACL2 but not Version 3.6. For [3mchanges[0m to existing books rather than [3madditions[0m, see the {log entries | http://code.google.com/p/acl2-books/source/list} starting with revision r329 up through revision 350. Fixed a soundness bug in the handling of [ruler-extenders], specifically in the handling of [47m[let][0m-expressions. Thanks to Pete Manolios, who sent us a proof of [47mnil[0m, essentially as follows. In the termination proof for [47mfoo[0m below, the binding of [47mx[0m to [47m(cons t x)[0m was not substituted into the recursive call of [47mfoo[0m for purposes of the termination proof. (defun foo (x) (declare (xargs :ruler-extenders :all)) (let ((x (cons t x))) (if (endp (cdr x)) x (cons t (foo (cdr x)))))) (defthm foo-bad nil :hints (("Goal" :use ((:instance foo (x '(3)))) :in-theory (disable foo (foo)))) :rule-classes nil) Fixed a typo in code supporting [ruler-extenders] (specifically, swapped arguments in a recursive call of ACL2 source function [47mget-ruler-extenders2[0m, which could cause problems for functions defined using [47m[mutual-recursion][0m). Thanks to Daron Vroon for bringing this bug to our attention, pointing out the swapped arguments.") (|NOTE-3-6{R}| (release-notes) "ACL2 Version 3.6(r) (August, 2009) Notes Please also see [note-3-6] for changes in Version 3.6 of ACL2.") (note-4-0 (release-notes) "ACL2 Version 4.0 (July, 2010) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 3.6.1 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, distributed books, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Also see [note-3-6-1] for other changes since Version 3.6. [31;1mCHANGES TO EXISTING FEATURES[0m There have been extensive changes to the handling of compiled files for books, which may generally be invisible to most users. The basic idea is that when compiled files are loaded on behalf of [47m[include-book][0m, they are now loaded before events in the book are processed, not afterwards. This can speed up calls of [47minclude-book[0m, especially if the underlying Lisp compiles all definitions on the fly (as is the case for CCL and SBCL). One functional change is that for keyword argument [47m:load-compiled-file[0m of [47m[include-book][0m, the values [47m:comp-raw[0m, [47m:try[0m, and [47m:comp![0m are no longer legal. (Note that the handling of [47m:comp-raw[0m was actually broken, so it seems that this value wasn't actually used by anyone; also, the handling of [47m:comp![0m formerly could cause an error in some Lisp platforms, including SBCL.) Another change is that if [47m[include-book][0m is called with [47m:load-compiled-file t[0m, then each sub-book must have a compiled file or a so-called ``expansion file''; see [book-compiled-file]. In the unlikely event that this presents a problem, the makefile provides a way to build with compilation disabled; see [compilation]. Users of raw mode (see [set-raw-mode]) will be happy to know that [47m[include-book][0m now works if there is an up-to-date compiled file for the book, since [47m[portcullis][0m commands are now incorporated into that compiled file. The mechanism for saving expansion files has changed, and the [47m:save-expansion[0m argument of [47m[certify-book][0m has been eliminated; see [certify-book]. More discussion of ACL2's new handling of book compilation is described in a new documentation topic; see [book-compiled-file]. It was possible to get a hard Lisp error when certifying a book with a redundant [47m[defconst][0m form whose term is not identical to the existing [47m[defconst][0m form for the same name. The following example illustrates the problem, which has been fixed (as part of the change in handling of compiled files for books, described above). Imagine that after the initial [47m(in-package "ACL2")[0m form, file [47mfoo.lisp[0m has just the form [47m(defconst *a* (append nil nil))[0m. Then before the fix, we could have: ACL2 !>(defconst *a* nil) [[output omitted]] ACL2 !>(certify-book "foo" 1) [[initial output omitted] * Step 5: Compile the functions defined in "/v/joe/foo.lisp". Compiling /v/joe/foo.lisp. End of Pass 1. End of Pass 2. OPTIMIZE levels: Safety=0 (No runtime error checking), Space=0, Speed=3 Finished compiling /vjoe/foo.lisp. Loading /v/joe/foo.lisp Error: Illegal attempt to redeclare the constant *A*. The [47m[wormhole][0m facility has been changed to repair a bug that allowed guard violations to go undetected. The major change has to do with the treatment of what used to be called the ``pseudo-flag'' argument which has been replaced by a quoted lambda expression. See [note-4-0-wormhole-changes] for help in converting calls of [47m[wormhole][0m. Also see see [wormhole] and see [wormhole-eval]. The function [47massign-wormhole-output[0m has been eliminated but its functionality can be provided by [47m[wormhole-eval][0m. The ACL2 tutorial has been greatly expanded, for example to include a self-contained discussion of rewriting. See [ACL2-tutorial]. Formerly, the [47m[mbe][0m macro and [47m[must-be-equal][0m function were disallowed in any definition within an encapsulate having a non-empty signature. Now, these are allowed provided the definition has been declared to be non-executable (see [defun-nx]). As a result, [47m[defevaluator][0m [events] may now include [47m[must-be-equal][0m among the function symbols known by the evaluator; this had not previously been allowed. Thanks to Sol Swords for discussions leading to this relaxation for [47m[defevaluator][0m. [47m[Princ$][0m now prints strings more efficiently. Thanks to Jared Davis for suggesting the improvements to [47mprinc$[0m. The use of [47m[xargs][0m declaration [47m:non-executable t[0m no longer requires the absence of [47m[state][0m or declared [47m[stobj][0ms among the formal parameters of a function definition. As before, the use of [47m:non-executable t[0m turns off single-threadedness checking for the body, and also as before, attempts to execute the function will fail. Thanks to Sol Swords for requesting this relaxation (for automatic generation of so-called ``flag functions'' for definitions using [47m[mutual-recursion][0m). The [documentation] has been improved for explaining to advanced users the details of the ACL2 hint mechanism; see [hints-and-the-waterfall], and see the example about [47mnonlinearp-default-hint[0m in distributed book [47mbooks/hints/basic-tests.lisp[0m. Thanks to Robert Krug for useful discussions, in particular suggesting the above example as one to be explained with the documentation. The [47mtime$[0m macro has been enhanced to allow user control of the timing message that is printed, and of when it is printed. See [time$]. Thanks to Jared Davis for providing the essential design, helpful documentation (largely incorporated), and an initial implementation for raw Lisp. The [47m:ttags[0m argument to [47m[include-book][0m had been required when including a certified book that uses trust tags. This is no longer the case: essentially, [47m:ttags[0m defaults to [47m:all[0m except that warnings will be printed. Thanks to Jared Davis for requesting such a relaxation, and to him and Sandip Ray for useful discussions. The definition of [47m[mv-let][0m has been modified so that the single-step macroexpansion (see [trans1]) of its calls can be evaluated. Thanks to Pete Manolios for bringing this evaluation issue to our attention and ensuing discussions. All calls of so-called ``guard-holders'' --- [47m[prog2$][0m, [47m[must-be-equal][0m (from calls of see [mbe]), [47m[ec-call][0m, and [47m[mv-list][0m --- are now removed before storing hypotheses of rules of class [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m. Thanks to Sol Swords for requesting this enhancement and sending the following example in the case of [rewrite] rules. (defthm foo (prog2$ (cw "asdf") (and (equal (car (cons x y)) x) (equal (cdr (cons x y)) y)))) The handling of [47m[fmt][0m directive [47m~s[0m has been modified so that if the argument is a symbol that would normally be printed using vertical bars ([47m|[0m), then that symbol is printed as with [47m~f[0m. Thanks to Jared Davis for providing the following example showing that treatment of [47m~s[0m was a bit unexpected: [47m(cw "~s0.~%" '|fo\|o|)[0m. Error messages have been improved for ill-formed terms (in ACL2's so-called ``translation'' routines). Thanks to Jared Davis for requesting such an enhancement. Modified [47m[defun-sk][0m so that it executes in [47m:[0m[47m[logic][0m mode. Previously, evaluation of a [47m[defun-sk][0m event in [47m:[0m[47m[program][0m mode caused a somewhat inscrutable error, but now, [47m:[0m[47m[program][0m mode is treated the same as [47m:[0m[47m[logic][0m mode for purposes of [47m[defun-sk][0m. The ``system hacker'' commands [47m([0m[47m[redef+][0m[47m)[0m and [47m([0m[47m[redef-][0m[47m)[0m are now embedded event forms (see [embedded-event-form]), hence may be used in [books] as well as in [47m[progn][0m and [47m[encapsulate][0m [events]. Also, these two commands are now no-ops in raw Lisp. The function symbol [47mworldp[0m (in the [47m"ACL2"[0m package) has been renamed to [47mplist-worldp[0m. The function [47mgc$-fn[0m (resulting from macroexpansion of [47m[gc$][0m) is now in [47m:[0m[47m[logic][0m mode. Thanks to Jared Davis for requesting this change. The user now has control over whether compilation is used, for example whether or not [47m[certify-book][0m compiles by default, using function [47mset-compiler-enabled[0m. See [compilation]. Modified the conversion of relative to absolute pathnames in [portcullis] [command]s for book certification. Now, more pathnames remain as relative pathnames. The [47m"Ttags"[0m warning that can be printed by [47m[include-book][0m is now given even if [47m[set-inhibit-output-lst][0m has specified `[47mwarning[0m'. To suppress it, specify [47mwarning![0m instead, for example, [47m(set-inhibit-output-lst '(acl2::warning! acl2::proof-tree))[0m. On occasion, ACL2 prints the message ``Flushing current installed world'' as it cleans up when certain actions (installing a [world]) are interrupted. This operation has been sped up considerably. If your session includes many [events], you can probably speed up any such operation further by invoking [47m[reset-prehistory][0m. Thanks to Jared Davis for sending a query that led us to make this improvement. Calls of the form [47m(ec-call (must-be-equal logic exec))[0m are no longer allowed, since we do not have confidence that they would be handled correctly. The underlying function for [47m[good-bye][0m (and hence for [47m[exit][0m and [47m[quit][0m) is now in [47m:[0m[47m[logic][0m mode. Thanks to Jared Davis for requesting this enhancement. We now require that every function symbol in the [signature] of an [47m[encapsulate][0m event have a [47m:[0m[47m[logic][0m mode definition at the end of the first pass, not merely a [47m:[0m[47m[program][0m mode definition (which formerly was sufficient). You can still define such a function in [47m:program[0m mode, provided it is followed by a [47m:logic[0m mode definition (where of course both definitions are [local], since we are discussing functions introduced in the [signature]). Thanks to Carl Eastlund for bringing this issue to our attention. (Note: An analogous modification has been made for [47m:[0m[47m[bdd][0m [hints] as well.) The following functions now have raw Lisp implementations that may run faster than their ACL2 definitions: [47m[assoc-eq][0m, [47m[assoc-equal][0m, [47m[member-eq][0m, [47m[member-equal][0m, [47msubsetp-eq[0m, [47m[subsetp-equal][0m, [47m[remove-eq][0m, [47m[remove-equal][0m, [47m[position-eq][0m, and [47m[position-equal][0m. Thanks to Jared Davis for suggesting that we consider such an improvement. We now avoid infinite loops caused when tracing functions that implement [47m[trace$][0m. Thanks to Rob Sumners and Eric Smith for useful discussions. The implementation of [47m[trace!][0m has been modified slightly, to accommodate the fix for ``some holes in the handling of trust tags'' described later, below. This item applies unless the host Lisp is GCL. An interrupt (control-c) will now cause a proof to exit normally in most cases, by simulating a timeout, as though [47m[with-prover-time-limit][0m had been called with a time-limit of 0. If the first interrupt doesn't terminate the proof, a second one should do so (because a different, more ``severe'' mechanism is used after the first attempt). As a result, [47m[redo-flat][0m should work as one might expect even if a proof is interrupted. Thanks to Dave Greve for requesting this enhancement to [47m[redo-flat][0m. Technical note: for reasons related to this change, time-limits are no longer checked in evaluator functions ([47mev-fncall[0m, [47mev[0m, [47mev-lst[0m, [47mev-fncall-w[0m, [47mev-w[0m, and [47mev-w-lst[0m). It is now legal for [proof-builder] [macro-command]s to appear in [47m:[0m[47m[instructions][0m that are used in place of [47m:[0m[47m[hints][0m. Thanks to Sandip Ray for (most recently) requesting this feature. The value of [47m:command-conventions[0m for [47m[ld][0m special variable [47mld-post-eval-print[0m is now treated as though it were [47mt[0m if the value [47m[ld][0m special variable [47mld-error-triples[0m is [47mnil[0m. The following example illustrates this change. ACL2 !>(ld-post-eval-print state) ; default :COMMAND-CONVENTIONS ACL2 !>(ld-error-triples state) ; default T ACL2 !>(set-ld-error-triples nil state) *** Then, before the change: ACL2 !>(mv t 3 state) 3 *** Instead, after the change: ACL2 !>(mv t 3 state) (T 3 <state>) The default behavior of [47m[ld][0m has been changed. Formerly when an error occurred that halted a subsidiary call of [47mld[0m, then the parent [47mld[0m would continue. That is no longer the case. Consider the following example. (ld '((ld '((defun f (x) x) (defun bad (x)) ; ERROR -- missing the body )) (defun g (x) x))) Formerly, [47mg[0m would be defined in the resulting logical [world]. Now, the error halts not only the inner [47mld[0m but also the outer [47mld[0m. See [ld], and for details of the new default value for [47m:ld-error-action[0m, [47m:RETURN![0m, see [ld-error-action]. Also see the paragraph below about a new utility, [47m:[0m[47m[p!][0m. Thanks to Robert Krug and Sandip Ray for helpful discussions. Environment variable [47mACL2-CUSTOMIZATION[0m has been replaced by [47mACL2_CUSTOMIZATION[0m --- that is, the hyphen has been replaced by an underscore --- so that it can be set conveniently in the [47mbash[0m shell. See [ACL2-customization]. The ``[47mWarnings:[0m'' summary is now omitted when there are no warnings, where formerly ``[47mWarnings: None[0m'' was printed. Thanks to Jared Davis for suggesting this change. We have modified the generation of [47mconstraint[0ms for [47m[encapsulate][0m [events] in two primary ways, neither of them likely to affect many users. One change is that the virtual movement of definitions and theorems to in front of an [47m[encapsulate][0m event, or of definitions to behind that event, is no longer inhibited in the case of nested encapsulates with non-empty [signature]s. The following example illustrates the other change, as discussed below. (encapsulate ((f (x) t)) (local (defun f (x) x)) (defun g (x) (cons x (f x))) (defun h (x) (g x)) (defthm h-is-f (equal (car (h x)) x))) Previously, the [constraint] on [47mf[0m and [47mh[0m was essentially the conjunction of the definition of [47mh[0m and the theorem [47mh-is-f[0m. Now, the definition of [47mg[0m is conjoined as well; moreover, [47mg[0m receives the same [constraint] as do [47mf[0m and [47mh[0m, where previously [47mg[0m was only constrained by its definition. While we are not aware of a soundness bug caused by the previous approach, the new approach follows more precisely the intended notion of [constraint]. The use of [47m[trace$][0m (or [47m[trace!][0m) option [47m:multiplicity[0m had been required when option [47m:native[0m was supplied. This is no longer the case. Also, a bug has been fixed that had prevented [47m:multiplicity[0m from working properly in GCL and Allegro CL. Several errors have been eliminated that formerly occurred when the constraints for a function symbol were unknown because it was constrained using a dependent clause-processor (see [define-trusted-clause-processor]. Now, it is assumed that the [47msupporters[0m argument in a [47m[define-trusted-clause-processor][0m event is such that every ancestor of any function symbol constrained by the ``promised encapsulate'' of that event among, or ancestral in, those [47msupporters[0m. Thanks to Sol Swords, Sandip Ray, and Jared Davis for helpful discussions. The notion of [constraint] for functions introduced by [47m[defun][0m has been modified slightly. No longer do we remove from the body of the definition calls of so-called ``guard-holders'': [47m[prog2$][0m, [47m[must-be-equal][0m, [ec-call], and [mv-list], and uses of [47mthe-error[0m generated by [47m[the][0m. Also, we now expand calls of [47mthe-error[0m with the same aggressive heuristics applied to a number of other functions (technically, adding it to the list [47m*expandable-boot-strap-non-rec-fns*[0m). [31;1mNEW FEATURES[0m A new event, [47m[defattach][0m, allows evaluation of calls of constrained ([47m[encapsulate][0md) functions. In particular, users can now, in principle, soundly modify ACL2 source code; please feel free to contact the ACL2 implementors if you are interested in doing so. See [defattach]. Eric Smith has noticed that if you exit the [break-rewrite] loop using [47m:[0m[47m[a!][0m during an [47m[ld][0m of a file, then all changes to the logical [world] are discarded that were made during that call of [47m[ld][0m. A new utility, [47m:[0m[47m[p!][0m, pops just one level instead, and avoids discarding that work. (This change is related to an item above, ``The default behavior of [47m[ld][0m has been changed.'') Thanks to Eric for pointing out this issue. New function [47m[mv-list][0m is the identity function logically, but converts multiple values to lists. The first argument is the number of values, so an example form is as follows, where [47mfoo[0m returns three values: [47m(mv-list 3 (foo x y))[0m. Thanks to Sol Swords for requesting this feature and for reporting a soundness bug in one of our preliminary implementations. A new [47m[state][0m global variable, [47mhost-lisp[0m, has as its value a keyword whose value depends on the underlying Common Lisp implementation. Use [47m(@ host-lisp)[0m to see its value. It is now possible to write [documentation] for HTML without error when there are links to nonexistent documentation topics. See the comments in macro [47macl2::write-html-file[0m at the end of file [47mdoc/write-acl2-html.lisp[0m. When there are such errors, they should be easier to understand than previously. Thanks to Alan Dunn for providing the initial modifications. It is now possible to inhibit specified parts of the Summary printed at the conclusion of an event. See [set-inhibited-summary-types]. Also see [with-output], in particular the discussion of the new [47m:summary[0m keyword. Thanks to Sol Swords for requesting more control over the Summary. A new [47m:[0m[47m[hints][0m keyword, [47m:case-split-limitations[0m, can override the default case-split-limitations settings (see [set-case-split-limitations]) in the simplifier. Thanks to Ian Johnson for requesting this addition and providing an initial implementation. It is now possible to defer and avoid some ttag-related output; see [set-deferred-ttag-notes]. Thanks to Jared Davis for requesting less verbosity from ttag-related output. A new [command], [47m:[0m[47m[pl2][0m, allows you to restrict the rewrite rules printed that apply to a given term. See [pl2]. Thanks to Robert Krug for requesting such a capability. ACL2 now provides a utility for canonicalizing filenames, so that soft links are resolved; see [canonical-pathname]. Moreover, ACL2 uses this utility in its own sources, which can eliminate some issues. In particular, [47m[include-book][0m with argument [47m:ttags :all[0m no longer breaks when given a book-name differing from the book-name that was used at certification time; thanks to Sol Swords for reporting that problem. Also, certain errors have been eliminated involving the combination of packages in the certification world and trust tags; thanks to Jared Davis for sending an example of that problem. You can now suppress or enable guard-checking for an individual form; see [with-guard-checking]. Thanks to Sol Swords for requesting this feature. The [47m[walkabout][0m utility has been documented (thanks to Rob Sumners for suggesting this documentation). This utility can make it easy to explore a large [47mcons[0m tree. New interactive commands [47m(pp n)[0m and [47m(pp print-level print-length)[0m have been added to restrict how much of the current object is displayed. See [walkabout]. Rules of class [47m:[0m[47m[type-prescription][0m may now be provided a [47m:backchain-limit-lst[0m keyword. The default behavior is unchanged, but now [47m[type-set][0m is sensitive not only to the new [47m:backchain-limit-lst[0m of a [47m:[0m[47m[type-prescription][0m rule (if supplied) but to the [47m[default-backchain-limit][0m of the current logical [world]. Setting of backchain-limits can now specify either the new (type-set) limit or the old limit (for rewriting); see [set-default-backchain-limit] and see [set-backchain-limit]. Moreover, the functions [47m[default-backchain-limit][0m and [47m[backchain-limit][0m now take a second argument of [47m:ts[0m or [47m:rewrite[0m to specify which backchain-limit is desired. [31;1mHEURISTIC IMPROVEMENTS[0m The so-called ``too-many-ifs'' heuristic has been modified. Such a heuristic has been employed in ACL2 (and previous Boyer-Moore provers) for many years, in order to limit the introduction of calls of [47m[if][0m by non-recursive functions. Most users need not be concerned with this change, but two proofs in the regression suite (out of thousands) needed trivial adjustment, so user proofs could need tweaking. In one application, this modification sped up proofs by 15%; but the change in runtime for the regression suite is negligible, so such speedups may vary. Thanks to Sol Swords for providing a test from ACL2 runs at Centaur Technology, which was useful in re-tuning this heuristic. Guard proof obligations could have size quadratic in the number of clauses in a [47m[case][0m statement. This inefficiency has been removed with a change that eliminates a hypothesis of the form [47m(not (eql term constant))[0m when there is already a stronger hypothesis, equating the same term with a different constant. Thanks to Sol Swords for bringing this problem to our attention and suggesting an alternate approach to solving it, which we may consider in the future if related efficiency problems persist. We adjusted the heuristics for determining induction schemes in the presence of [ruler-extenders], when handling calls of a function symbol that is a ruler-extender, in either of two cases: either the function takes only one argument; or the function is [47m[prog2$][0m or [47m[ec-call][0m, and the first argument contains no recursive call. These cases are treated more directly as though the ruler-extender call is replaced by the unique (in the case of [47m[prog2$][0m and [47m[ec-call][0m, the second) argument. A new [47m:[0m[47m[type-prescription][0m rule, [47mtrue-listp-append[0m, has been added: (implies (true-listp b) (true-listp (append a b))) If you are interested in the motivation for adding this rule, see comments in [47mtrue-listp-append[0m in ACL2 source file [47maxioms.lisp[0m. The use of [47m:forward-chaining[0m lemmas has been improved slightly. In previous versions, a conclusion derived by forward chaining was discarded if it was derivable by type-set reasoning, since it was ``already provable.'' But this heuristic prevented the conclusion from triggering further forward chaining. This has been fixed. Thanks to Dave Greve for pointing out this problem. The fundamental utility that turns an [47mIF[0m expression into a set of clauses has been optimized to better handle tests of the form [47m(equal x 'constant)[0m and their negations. This eliminates an exponential explosion in large case analyses. But it comes at the inconvenience of sometimes reordering the clauses produced. The latter aspect of this change may require you to change some Subgoal numbers in proof hints. We apologize for the inconvenience. Certification can now run faster (specifically, the compilation phase) for books with very large structures generated by [47m[make-event][0m, when there is significant sharing of substructure, because of a custom optimization of the Lisp reader. Thanks to Sol Swords for bringing this efficiency issue to our attention. Jared Davis reported inefficiency in certain [47m[make-event][0m evaluation due to a potentially expensive ``bad lisp object'' check on the expansion produced by the [47mmake-event[0m. This check has been eliminated except in the case that the expansion introduces packages (for example, by including a book during the expansion phase that introduces packages). Thanks to Jared for providing a helpful example. The application of rules of class [47m:[0m[47m[induction][0m had the potential to loop (as commented in ACL2 source function [47mapply-induction-rule[0m). This has been fixed. Thanks to Daron Vroon and Pete Manolios for sending nice examples causing the loop. Heuristics have been tweaked so that false goals may be simplified to [47mnil[0m that had formerly been left unchanged by simplification, perhaps resulting in useless and distracting proofs by induction. Thanks to Pete Manolios for pointing out this issue by sending the following example: [47m(thm (<= (+ 1 (acl2-count x)) 0))[0m. (Technical explanation: When every literal in a clause simplifies to [47mnil[0m, even though we might not normally delete one or more such literals, we will replace the entire clause by the false clause.) Improved the efficiency of the built-in function, [47m[take][0m. Thanks to Bob Boyer for suggesting this improvement. ACL2 can now use evaluation to relieve hypotheses when applying [47m:[0m[47m[type-prescription][0m rules. Thanks to Peter Dillinger and Dave Greve for requesting this enhancement, and to Robert Krug for a relevant discussion long ago. Evaluation has been sped up during theorems for calls of [47m[mv-let][0m, by avoiding repeated evaluation of the expression to which its variables are bound. Thanks to Sol Swords for requesting this improvement and sending an illustrative example. Modified a heuristic to avoid the opening up non-recursive function calls on calls of [47m[hide][0m involving [47m[if][0m-expressions. For example, the [47m[thm][0m form below is now admitted (defun bar (x) (cons x x)) (thm (equal (bar (hide (if a b c))) (cons (hide (if a b c)) (hide (if a b c))))) [31;1mBUG FIXES[0m Fixed a soundness bug in destructor elimination, which was preventing some cases from being generated. Thanks to Eric Smith for reporting this bug and sending a helpful example. (Technical detail: the fixes were in ACL2 source functions [47mapply-instantiated-elim-rule[0m and [47meliminate-destructors-clause1[0m, and comments in the former contain Eric's example.) Fixed a bug that supported a proof of [47mnil[0m by exploiting the fact that [portcullis] [command]s were not included in check-sum computations in a book's [certificate]. For such a proof of [47mnil[0m, see the relevant comment in the ACL2 source file [47mld.lisp[0m under [47m(deflabel note-4-0 ...)[0m. Changed the implementation of [47m[add-include-book-dir][0m. The previous implementation could allow relative pathnames to be stored in the [portcullis] [command]s of [certificate]s of [books], which perhaps could lead to unsoundness (though we did not try to exploit this to prove [47mnil[0m). Thanks to Jared Davis for reporting a bug in our first new implementation. An additional change to both [47m[add-include-book-dir][0m and [47m[delete-include-book-dir][0m is that these now work in raw-mode (see [set-raw-mode]). (Thanks to Dave Greve for suggesting a reduction in the warnings we produced related to raw-mode.) Note that it is no longer permitted to make a direct call of the form [47m(table acl2-defaults-table :include-book-dir-alist ...)[0m; use [47m[add-include-book-dir][0m instead. Fixed a soundness bug related to [47m[xargs][0m keyword [47m:non-executable[0m. New macros, [47mdefun-nx[0m and [47mdefund-nx[0m, have been provided for declaring functions to be non-executable; see [defun-nx]. While we expect this bug to occur only rarely if at all in practice, the following example shows how it could be evoked. ;;;;;;;;;;;;;;;;;;;; ;;; Book sub.lisp ;;;;;;;;;;;;;;;;;;;; (in-package "ACL2") (defun f () (declare (xargs :guard t :non-executable t)) (mv-let (a b c) (mv 3 4) (declare (ignore a b)) c)) (defun g () (declare (xargs :guard t)) (prog2$ (mv-let (x y z) (mv 2 3 4) (declare (ignore x y z)) nil) (f))) (defthm g-nil (equal (g) nil) :hints (("Goal" :in-theory (disable (f)))) :rule-classes nil) ;;;;;;;;;;;;;;;;;;;; ;;; Book top.lisp ;;;;;;;;;;;;;;;;;;;; (in-package "ACL2") (include-book "sub") (defthm contradiction nil :hints (("Goal" :use g-nil)) :rule-classes nil) The modification described above pertaining to [47m[defun-nx][0m also prevents execution of non-executable functions that have been [trace]d. The following example illustrates the problem; now, the following [47m[defun][0m of [47mg[0m is illegal, and the problem disappears if [47m[defun-nx][0m is used instead. (defun g (x) ; Use defun-nx to avoid an error after Version_3.6.1. (declare (xargs :guard t :non-executable t)) x) (g 3) ; causes error, as expected (trace$ g) (g 3) ; returned 3 before the bug fix; after fix, causes error as expected A hard error was possible when attempting to include an uncertified book containing [events] of the form [47m(make-event '(local ...))[0m. This has been fixed. Thanks to Sol Swords for bringing this issue to our attention. Fixed a bug in the heuristic improvement described for Version_3.6 (see [note-3-6]) as ``We simplified induction schemes....'' The bug had prevented, in unusual cases such as the following (notice the impossible case), a proof by induction. (defun foo (a x) (and (consp x) (case a (0 (foo (car x) (cdr x))) (1 (foo (cdr x) (car x))) (0 (foo a (cons x x)))))) (in-theory (disable (:type-prescription foo))) (thm (atom (foo a x))) Macro [47m[cw-gstack][0m did not work with an [47m:evisc-tuple[0m argument. This has been fixed by changing [47mcw-gstack[0m so that it now evaluates its arguments. Thanks to Sol Swords for bringing this bug to our attention. Fixed a bug in [47m:[0m[47m[pso][0m during the printing of failure messages for termination proofs. Fixed a bug in the handling of [47m#.[0m (see [sharp-dot-reader]). Thanks to Bob Boyer for bringing this bug to our attention. Replaced a hard Lisp error with a clean error, in certain cases that a [47m:[0m[47m[hints][0m value is erroneously supplied as a non-[47mnil[0m atom. Example: [47m(thm (equal x x) :hints 3)[0m. Fixed a bug in the interaction of function tracing with conversion of a function from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m mode. The following example illustrates what had been wrong. (defun f (x) (declare (xargs :mode :program)) (car x)) (f 3) ; raw Lisp hard error (trace$ f) (f 3) ; raw Lisp hard error (still) (defun f (x) (car x)) ; upgrade f to :logic mode (f 3) ; clean guard violation; f is no longer traced (trace$) ; uh oh - f is shown as traced (untrace$ f) (f 3) ; OUCH: hard Lisp error because old :program mode definition of ; the executable counterpart (sometimes called *1*f) was restored! Made a fix so that when building ACL2 with `make' option [47mACL2_SAFETY=3[0m, there will no longer be any safety-0 compiled code generated. Thanks to Gary Byers for bringing this bug to our attention. Fixed a bug in the handling of [override-hints] that generate custom keyword hints (see [custom-keyword-hints]) involving the variable [47mstable-under-simplificationp[0m. Thanks to Ian Johnson for bringing this bug to our attention with explanation that included a helpful example, included as comment in the ACL2 source code for function [47mapply-override-hint[0m. The [47msaved_acl2[0m script in CLISP could contain unexpected characters where simple newlines were expected. Dave Greve found this in a Cygwin environment on Windows. Thanks to Dave for reporting this bug and experimenting with a fix, and thanks to the CLISP folks for providing helpful information. Fixed a bug that could make [47m:[0m[47m[oops][0m cause an error. Also, the [47m[oops][0m command can no longer take you back before a [47m[reset-prehistory][0m event. (GCL only) Fixed a bug that could occur when calling [47mtrace[0m in raw Lisp in GCL. Proof summaries have been improved, so that they account for [rune]s used in rewriting that takes place when generating goals to be proved in a forcing round. Thanks to Jared Davis for sending us an example illustrating this issue. Fixed a bug that (at least in CCL) could put extra backslashes (`[47m\[0m') in a pathname that ACL2 writes out to the executable script created by a build. Thanks to Gary Byers for explaining that the CCL behavior is legal (for our previous use of Common Lisp function [47mmerge-pathnames[0m). We closed some holes in the handling of trust tags (also known as ``ttags''; see [defttag]) by [47m[include-book][0m. The following example illustrates this rather subtle situation. Consider the following book. (in-package "ACL2") (make-event (er-progn (encapsulate () (defttag :foo) (value-triple "Imagine something bad here!")) (value '(value-triple :some-value))) :check-expansion t) Formerly, the following commands succeeded. (certify-book "test3" 0 t :ttags :all) :u (include-book "test3" :ttags nil) But because of [47m[make-event][0m keyword argument [47m:check-expansion t[0m, we know that the event [47m(defttag :foo)[0m is evaluated by the above [47m[include-book][0m form, and hence the [47m:ttags[0m argument of [47minclude-book[0m, above, should have specified [47m:foo[0m. The problem was that [47m[defttag][0m forms evaluated during [47m[make-event][0m expansion did not contribute to the trust tag information stored in the book's [certificate]. Note: Because of this change, one should avoid using [47m[make-event][0m with [47m:check-expansion t[0m when the expansion would introduce a [47m[defttag][0m event during [47m[include-book][0m but not [47m[certify-book][0m time. For an example illustrating this issue, see [make-event-details], specifically the new version of the section labeled ``A note on ttags'' at the end of that [documentation] topic. Closed a small loophole that had the potential, in rare circumstances, to violate atomicity of under-the-hood updates for ACL2 [arrays]. The following example was formerly allowed, but resulted in a guard-verified function (here, [47mg[0m) whose guard proof obligation is not a theorem outside the [47m[encapsulate][0m event. We now disallow [guard] verification for functions introduced non-[local]ly inside an [47m[encapsulate][0m event unless we determine that the proof obligations hold outside the [47m[encapsulate][0m event as well. (encapsulate ((f (x) t)) (local (defun f (x) (declare (xargs :guard t)) (consp x))) ;; ERROR! (defun g (x) (declare (xargs :guard (f x))) (car x))) The use of [47m:[0m[47m[comp][0m on [stobj] functions had potentially caused a hard Lisp error; for example, this could occur when [47m(defstobj foo fld)[0m was followed by [47m:comp foop[0m. This has been fixed. Fixed a bug that could cause a raw Lisp error when the first argument of [47m[with-local-stobj][0m is not a symbol. It had been possible to use the reserved keyword :computed-hints-replacement as the name of a custom keyword hint (see [custom-keyword-hints]). This has been fixed. Thanks to Dave Greve, who pointed out a confusing hint error message (which has also been fixed) that led us to this issue. Fixed a bug that could cause a hard Lisp error, instead of a graceful ACL2 error, if keyword [47m:backchain-limit-lst[0m in a rule class is given a cons that is not a true list, such as [47m(1 . 1)[0m. Eliminated an error that could occur when redefining a function as a macro and then compiling, as in the example below. (defun foo (x) x) :redef! (defmacro foo (x) x) :comp t Thanks to Eric Smith for sending the above example in his bug report. Fixed a bug that could result in an assertion when a [clause-processor] causes an error. [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m See the {log entries | http://code.google.com/p/acl2-books/source/list} for a record of books changed or added since the preceding release, with log entries. We note in particular the new [47msystem/[0m directory, which begins to specify ACL2 system code in anticipation of opening the architecture of ACL2 (see [defattach] for a relevant tool). Some system functions were changed slightly (but with the expectation of not generally affecting ACL2 behavior) in support of the development of this directory. Those interested in contributing to further such efforts are invited to contact the ACL2 implementors. New utilities have been provided for certifying most of the distributed books with more `make'-level parallelism. For example, we have obtained close to a 12x reduction in time by using `[47mmake -j 24 regression-fast[0m' on a 24-processor machine. For more information see [47mbooks/make-targets[0m, or to include the [47mbooks/workshops[0m in the regression run, see [47mbooks/regression-targets[0m. Thanks to Sol Swords for providing these nice utilities. The top-level makefile, [47mGNUmakefile[0m, has been fixed so that the build processes (which are inherently sequential) will ignore the [47m-j[0m option of `make'. Note that regressions can still, however, be done in parallel, as the [47m-j[0m option will be passed automatically to the appropriate `make' command. [31;1mEMACS SUPPORT[0m [31;1mEXPERIMENTAL VERSIONS[0m The HONS version, supported primarily by Bob Boyer and Warren Hunt (see [hons-and-memoization]), has undergone numerous improvements. For example, keyword argument [47m:FORGET[0m is now supported when calling [47m[memoize][0m from within the ACL2 loop, and system function [47mworse-than[0m is [memoize]d with the [47m:condition[0m that both terms are function applications (clearing the memo-table after each prover invocation). Thanks to Jared Davis and Sol Swords for investigating the memoization of [47mworse-than[0m, and with suitable [47mcondition[0m. Thanks also to Jared Davis for contributing structural modifications to the implementation of [47m[hons][0m. David Rager contributed modifications to the parallel version (see [parallelism]), which include taking advantage of atomic increments available at least since Version 1.0.21 of SBCL and Version 1.3 of CCL. Subtopics [Note-4-0-wormhole-changes] How to convert calls of wormhole for Version 4.0") (note-4-0-wormhole-changes (note-4-0) "How to convert calls of wormhole for Version 4.0 Here we describe how to convert an ``old-style'' call of [47m[wormhole][0m --- that is, a call suitable for ACL2 versions preceding 4.0 --- in which the [47mpseudo-flag[0m was [47mt[0m. In order to convert such a call (wormhole t 'name input form ...) to a new-style call, the following steps must be carried out. Note that the wormhole name must always be quoted now. First, eliminate the first argument, [47mt[0m, and add a new second argument that is the quoted lambda expression '(lambda (whs) (set-wormhole-entry-code whs :ENTER)) Setting the entry code to [47m:ENTER[0m is not necessary if you maintain the invariant (after initialization) that it is always [47m:ENTER[0m. In that case, the simpler quoted lambda will suffice: '(lambda (whs) whs) Second, change the [47mform[0m argument so that instead of talking about the state global variable [47mwormhole-output[0m it talks about the state global variable [47mwormhole-status[0m. Look for [47m(@ wormhole-output)[0m, [47m(assign wormhole-output ...)[0m, [47m(f-get-global 'wormhole-output ...)[0m and [47m(f-put-global 'wormhole-output ...)[0m in [47mform[0m and replace them with expressions involving [47mwormhole-status[0m. However, remember that the old data stored in [47mwormhole-output[0m is now in the [47mwormhole-data[0m component of the [47mwormhole-status[0m. Thus, for example, an old use of [47m(@ wormhole-output)[0m will typically be replaced by [47m(wormhole-data (@ wormhole-status))[0m and an old use of [47m(assign wormhole-output ...)[0m will typically be replaced by (assign wormhole-status (set-wormhole-data (@ wormhole-status) ...)) In summary, an old-style call like (wormhole t 'name input '(...1 (@ wormhole-output) ...2 ...3 (assign wormhole-output ...4) ...5) ...6) can become (wormhole 'name '(lambda (whs) (set-wormhole-entry-code whs :ENTER)) input '(...1 (wormhole-data (@ wormhole-status)) ...2 ...3 (assign wormhole-status (set-wormhole-data (@ wormhole-status) ...4) ...5) ...6) In any case, and especially if your [47mwormhole[0m call had a [47mpseudo-flag[0m other than [47mt[0m, we recommend that you see [wormhole].") (|NOTE-4-0{R}| (release-notes) "ACL2 Version 4.0(r) (July, 2010) Notes Please see [note-4-0] for changes in Version 4.0 of ACL2.") (note-4-1 (release-notes) "ACL2 Version 4.1 (September, 2010) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 4.1 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, distributed books, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m The [guard] associated with calls of the macro, [47m[search][0m, has been weakened so that now, given strings are no longer restricted to contain only standard characters unless the [47m:test[0m argument is [47m[char-equal][0m. Modified the writing of ``hidden [47m[defpkg][0m'' forms into [certificate] files (see [hidden-defpkg]), to support moving certificate files for distributed books, as is done by ACL2s (see [ACL2-sedan]) and Debian releases of ACL2. Thanks to Camm Maguire for reporting a problem with Debian releases of ACL2 that led to this change. Expanded the constant [47m*acl2-exports*[0m by adding [47mintersection-equal[0m to the list. Thanks to Jared Davis for requesting this change. The [47m:[0m[47m[comp][0m utility now compiles functions that have code conditionalized for raw Lisp only (presumably because a trust tag was active when they were defined). Previously, this was not the case when [47m:comp[0m was applied to more than a single function symbol. [31;1mNEW FEATURES[0m A new macro, [47m[top-level][0m, allows evaluation directly in the top level loop for forms that normally need to be evaluated inside function bodies, such as [47m[with-local-stobj][0m. See [top-level]. Thanks to Jared Davis for requesting such a utility. Added [47m[count][0m, a Common Lisp function, to ACL2. In support of that addition, also added rewrite rule [47meqlablep-nth[0m. [31;1mHEURISTIC IMPROVEMENTS[0m [None this time.] [31;1mBUG FIXES[0m We fixed a soundness bug that could occur when a function that returns multiple values is called in its own guard. Thanks to Sol Swords for reporting this bug and sending a small self-contained example, which is included in a comment in the function [47mchk-acceptable-defuns1[0m in ACL2 source file [47mdefuns.lisp[0m. It was possible to cause an error when giving theory hints during redefinition of functions. This has been fixed. Thanks to Ian Johnson for sending an example that nicely illustrated this problem. Fixed system function [47mio?[0m for the case that formal parameter [47mcommentp[0m is [47mt[0m and [47mvars[0m is non-empty. Thanks to David Rager for bringing to our attention the fact that [47mio?[0m was broken for such a combination of parameters. Not exactly a bug fix, but: [47m[defun-sk][0m was breaking when a [47m:[0m[47m[guard][0m is specified, so we have improved the documentation (see [defun-sk]) to explain how to provide verified guards for a function introduced by [47m[defun-sk][0m. Thanks to Jared Davis for bringing this issue to our attention. Made a fix to the handling of interrupts, which in rare cases might have left one in a state where all subsequent proof attempts were labeled as ``Aborting due to an interrupt''. Fixed [47m:[0m[47m[pso][0m and related utilities, so that when proof output is redirected to a file, all summary output goes to that file rather than to the terminal. (GCL on Windows only) Removed an inappropriate check, resulting in an error about ``pathname-device,'' that could prevent Windows GCL builds of ACL2. Thanks to Camm Maguire for reporting this problem and a helpful discussion. (Windows only) Modified the computation of canonical pathnames to avoid issues of case-insensitivity, in particular for the drive (e.g., [47m"C:"[0m vs. [47m"c:"[0m). Thanks to Harsh Raju Chamarthi for reporting this issue and helping with its debugging. (Windows only) The value of [47m(@ distributed-books-dir)[0m no longer will be missing the Windows drive prefix, for example, [47m"C:"[0m. Thanks to Harsh Raju Chamarthi for reporting this issue and helping with its debugging. [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m See the {log entries | http://code.google.com/p/acl2-books/source/list} for a record of books changed or added since the preceding release, with log entries. Modified [47mbooks/Makefile-generic[0m by adding a new [47mBOOKS_SKIP_COMP[0m variable, which is used in [47mMakefile[0ms in some subdirectories of [47mbooks/[0m, in order to avoid errors when compiling certified books for multiple Lisps. [31;1mEMACS SUPPORT[0m Distributed file [47memacs/emacs-acl2.el[0m has been modified so that the forms [47mcontrol-t e[0m and [47mcontrol-t control-e[0m now pick up package markers (see [sharp-bang-reader]), in the following sense: if the top-level form is preceded by a line starting with [47m#![0m, then that line is included in the inserted string. Thanks to Jared Davis for suggesting this enhancement and providing a preliminary implementation. [31;1mEXPERIMENTAL VERSIONS[0m For the [47mHONS[0m version there have been some changes to [47m[memoize][0m: [47m[Memoize][0m accepts a new keyword, [47m:recursive[0m, that is a synonym for the existing keyword [47m:inline[0m. Thanks to Sol Swords for requesting this addition. Moreover, it is now enforced that these keywords have Boolean values. [47m[Memoize][0m may now be called on [47m:[0m[47m[program][0m mode functions. Thanks to Sol Swords for requesting this enhancement. A bug has been fixed. Now, if [47m[memoize][0m is called with a [47m:condition-fn[0m (with value other than [47mnil[0m or [47mt[0m), then the [guard] of the memoized function and the [47m:condition-fn[0m must be the same. Previously, one could exploit the lack of such a check to get a hard Lisp error, for example as follows. (defun f (x) (declare (xargs :guard t)) x) (defun cf (x) (declare (xargs :guard (consp x))) (car x)) (memoize 'f :condition-fn 'cf) (f 3) Memoization is now illegal for built-in functions that use underlying raw Lisp in their implementations. To see why, consider the form [47m(gc$)[0m, which is a macro call expanding to [47m(gc$-fn nil)[0m. Previously, after evaluation of [47m(memoize 'gc$-fn)[0m, a call of [47mgc$[0m would no longer call the garbage collector, which had been invoked by raw Lisp code. Now, evaluation of [47m(memoize 'gc$-fn)[0m causes an error.") (|NOTE-4-1{R}| (release-notes) "ACL2 Version 4.1(r) (September, 2010) Notes Please see [note-4-1] for changes in Version 4.1 of ACL2.") (note-4-2 (release-notes) "ACL2 Version 4.2 (January, 2011) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 4.2 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, distributed books, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m The [47m[accumulated-persistence][0m utility can now do finer-grained tracking, providing data for individual hypotheses and the conclusion of a rule. See [accumulated-persistence]. To try this out, evaluate the form [47m(accumulated-persistence :all)[0m; then see [accumulated-persistence] for a discussion of display options using [47mshow-accumulated-persistence[0m. Thanks to Dave Greve for suggesting this new capability and collaborating on its design and implementation. The [47m[defattach][0m utility now permits the use of [47m:[0m[47m[program][0m mode functions, though this requires the use of a trust tag (see [defttag]). See [defattach] and for discussion of the new capability, see [defproxy], which explains how part of this change involves allowing [47m:[0m[47m[program][0m mode functions to be declared [non-executable]. Redefinition (see [ld-redefinition-action]) is no longer permitted for functions that have attachments (see [defattach]). In such cases, the attachment must be removed first, e.g. with [47m(defattach foo nil)[0m. Made small changes to [47m[mv-nth][0m and [47m[defun-sk][0m in order to permit guard verification of functions introduced with more than one quantified variable in a [47m[defun-sk][0m form. The change to [47m[mv-nth][0m is to weaken the [guard] by eliminating the requirement that the second argument satisfy [47m[true-listp][0m, and replacing the call of [47m[endp][0m in the definition body by a corresponding call of [47m[atom][0m. The new definition of [47m[mv-nth][0m is thus logically equivalent to the old definition, but with a weaker guard. Thanks to Sol Swords for sending the following example, for which the final [47m[verify-guards][0m form had failed but now succeeds. (defstub foo (a b c) nil) (defun-sk forall-a-b-foo (c) (declare (xargs :guard t :verify-guards nil)) (forall (a b) (foo a b c))) (verify-guards forall-a-b-foo) The implementations of [47m[prog2$][0m, [47m[time$][0m, [47m[with-prover-time-limit][0m, [47m[with-guard-checking][0m, [47m[mbe][0m (and [47m[must-be-equal][0m), and [47m[ec-call][0m have changed. See the discussion below of the new utility, [47m[return-last][0m. A consequence is that [47m[trace$][0m is explicitly disallowed for these and related symbols, which formerly could cause hard Lisp errors, because they are now macros. Tracing of return-last is also disallowed. Another consequence is that time$ now prints a more abbreviated message by default, but a version of the old behavior can be obtained with [47m:mintime nil[0m. The following utilities no longer print an observation about raw-mode transitions: [47mset-raw-mode-on[0m, [47m[set-raw-mode-on!][0m, [47m[set-raw-mode][0m, and [47mset-raw-mode-off[0m. Thanks to Jared Davis for suggestion this change in the case of [47m[include-book][0m (which proved awkward to restrict to that case). The system function [47mtranslate-and-test[0m now permits its [47mLAMBDA[0m form to refer to the variable [47mWORLD[0m, which is bound to the current ACL2 logical [world]. Modified abort handling to avoid talking about an interrupt when the error was caused by a Lisp error rather than an interrupt. The value of the constant [47m*acl2-exports*[0m, which is still a list, has been extended significantly, though only with the addition of symbols that one might reasonably have expected all along to belong to this list. A new distributed book, [47mbooks/misc/check-acl2-exports.lisp[0m, checks (at certification time) that no documented constant, macro, or function symbol in the [47m"ACL2"[0m package has been accidentally omitted from [47m*acl2-exports*[0m. Thanks to Dave Greve for helpful discussions related to this change. Improved the built-in `[47muntranslate[0m' functions to produce [47mlet*[0m expressions when appropriate (more to help with tools that call [47muntranslate[0m and the like, than to help with proof output). The utility [47m[redo-flat][0m now works for [47m[certify-book][0m failures, just as it continues to work for failures of [47m[encapsulate][0m and [47m[progn][0m. The following only affects users who use trust tags to add to list values of either of the [47m[state][0m global variables [47mprogram-fns-with-raw-code[0m or [47mlogic-fns-with-raw-code[0m. For functions that belong to either of the above two lists, [47mtrace$[0m will supply a default value of [47m:fncall[0m to keyword [47m:notinline[0m, to avoid discarding raw-Lisp code for the function. The [guard] of the macro [47m[intern][0m has been strengthened so that its second argument may no longer be either the symbol [47m*main-lisp-package-name*[0m or the string [47m"COMMON-LISP"[0m. That change supports another change, namely that the following symbols in the [47m"COMMON-LISP"[0m package are no longer allowed into ACL2: symbols in that package that are not members of the list constant [47m*common-lisp-symbols-from-main-lisp-package*[0m yet are imported into the [47m"COMMON-LISP"[0m package from another package. See [pkg-imports] and see [symbol-package-name]. To see why we made that change, consider for example the following theorem, which ACL2 was able to prove when the host Lisp is GCL. (let ((x "ALLOCATE") (y 'car)) (implies (and (stringp x) (symbolp y) (equal (symbol-package-name y) "COMMON-LISP")) (equal (symbol-package-name (intern-in-package-of-symbol x y)) "SYSTEM"))) Now suppose that one includes a book with this theorem (with [47m:[0m[47m[rule-classes][0m [47mnil[0m), using an ACL2 built on top of a different host Lisp, say CCL, that does not import the symbol [47mSYSTEM::ALLOCATE[0m into the [47m"COMMON-LISP"[0m package. Then then one can prove [47mnil[0m by giving this theorem as a [47m:use[0m hint. The axioms introduced by [47m[defpkg][0m have changed. See the discussion of [47m[pkg-imports][0m under ``NEW FEATURES'' below. The error message for free variables (e.g., in definition bodies and guards) now supplies additional information when there are governing IF conditions. Thanks to Jared Davis for requesting this enhancement and collaborating in its design. The command [47m:[0m[47m[redef-][0m now turns off redefinition. Improved proof output in the case of a [47m:[0m[47m[clause-processor][0m hint that proves the goal, so that the clause-processor function name is printed. The [47m[proof-builder][0m command `[47mthen[0m' now stops at the first failure (if any). It is no longer permitted to submit definitions in [47m:logic[0m mode for merely part of an existing [47m[mutual-recursion][0m event. Such an action left the user in an odd state and seemed a potential soundness hole. The function [47m[break$][0m is now in [47m:[0m[47m[logic][0m mode. Thanks to Jared Davis for requesting this enhancement. The macro [47m[verify-termination][0m now provides clearer output in the case that it is redundant. More important perhaps, as a courtesy it now causes an error when applied to a constrained function, since presumably such an application was unintended (as the constrained function could never have been in [47m:[0m[47m[program][0m mode). Note that if one desires different behavior, one can create one's own version of [47m[verify-termination][0m (but with a different name). Improved the [guard]s for the following functions, often weakening them, to reflect more precisely the requirements for calling [47m[eq][0m: [47malist-difference-eq[0m, [47mintersection-eq[0m, [47mintersection1-eq[0m, [47m[intersectp-eq][0m, [47mnot-in-domain-eq[0m, [47mset-difference-assoc-eq[0m, [47mset-equalp-eq[0m, and [47m[union-eq][0m. Thanks to Jared Davis for pointing out this issue for [47m[intersectp-eq][0m. (CCL only) Made a change that can reduce the size of a compiled file produced by [47m[certify-book][0m when the host Lisp is CCL, by discarding source information (for example, discarding [47m[local][0m events). [31;1mNEW FEATURES[0m See the discussion above about new statistics that can be gathered by the [47m[accumulated-persistence][0m utility. A new hint, [47m:[0m[47m[instructions][0m, allows use of the [proof-builder] at the level of [hints] to the prover. Thanks to Pete Manolios for requesting this feature (in 2001!). See [instructions]. (For system hackers) There are new versions of system functions [47mtranslate1[0m and [47mtranslate[0m, namely [47mtranslate1-cmp[0m and [47mtranslate-cmp[0m respectively, that do not take or return [47m[state][0m. See the Essay on Context-message Pairs for relevant information. Thanks to David Rager for collaborating on this enhancement. A new utility, [47m[return-last][0m, is now the unique ACL2 function that can pass back a multiple value result from one of its arguments. Thus, now the following are macros whose calls ultimately expand to calls of [47m[return-last][0m: [47m[prog2$][0m, [47m[time$][0m, [47m[with-prover-time-limit][0m, [47m[with-guard-checking][0m, [47m[mbe][0m (and [47m[must-be-equal][0m), and [47m[ec-call][0m. With an active trust tag, an advanced user can now write code that has side effects in raw Lisp; see [return-last]. Thanks to Jared Davis for requesting this feature. A new function, [47m[pkg-imports][0m, specifies the list of symbols imported into a given package. The axioms for [47m[defpkg][0m have been strengthened, taking advantage of this function. Now one can prove theorems using ACL2 that we believe could not previously be proved using ACL2, for example the following. (equal (symbol-package-name (intern-in-package-of-symbol str t)) (symbol-package-name (intern-in-package-of-symbol str nil))) Thanks to Sol Swords for a helpful report, which included the example above. See [pkg-imports] and see [defpkg]. Added function [47m[no-duplicatesp-eq][0m. Added a new hint keyword, [47m:[0m[47m[backchain-limit-rw][0m, to control the level of backchaining for [rewrite], [meta], and [linear] rules. This overrides, for the current goal and (as with [47m:[0m[47m[in-theory][0m hints) descendant goals, the default [backchain-limit] (see [set-backchain-limit]). Thanks to Jared Davis for requesting this feature. Support is now provided for creating and certifying books that do not depend on trust tags, in the case that the only use of trust tags is during [47m[make-event][0m expansion. See [set-write-ACL2x]. Thanks to Sol Swords for reporting a couple of bugs in a preliminary implementation. Function [47m(file-write-date$ filename state)[0m has been added, giving the write date of the given file. See [forward-chaining-reports] for how to get new reports on the forward chaining activity occurring in your proof attempts. Thanks to Dave Greve for inspiring the addition of this utility. It is now possible to use ACL2's printing utilities to return strings, by opening output channels to the keyword [47m:STRING[0m rather than to filenames. See [io]. Thanks to Jared Davis for a helpful conversation that led us to add this feature. [31;1mHEURISTIC IMPROVEMENTS[0m We have slightly improved the handling of [47m:[0m[forward-chaining] rules that contain free variables. Formerly, such rules might fire only once, when the first match for a free variable is discovered, and would not fire again even if subsequent forward chaining made available another match. This made it difficult to predict whether a rule with free variables would fire or not, depending as it did on the order in which newly derived conclusions were added. The new handling is a little slower but more predictable. Thanks to Dave Greve for sending a helpful example that led us to consider making such an improvement. We have slightly improved the so-called ``[type-set]'' heuristics to work a bit harder on terms of the form [47m(rec term)[0m, where [47mrec[0m is a so-called ``compound-recognizer'' function, that is, a function with a corresponding enabled [47m:[0m[47m[compound-recognizer][0m rule. Thanks to Jared Davis for sending a helpful example (found, in essence, in the modified function [47mtype-set-rec[0m, source file [47mtype-set-b.lisp[0m). We made three heuristic improvements in the way contexts (so-called ``type-alists'') are computed from goals (``clauses''). Although these changes did not noticeably affect timing results for the ACL2 regression suite, they can be very helpful for goals with many hypotheses. Thanks to Dave Greve for sending a useful example (one where we found a goal with 233 hypotheses!). The algorithm for substituting alists into terms was modified. This change is unlikely to affect many users, but in one example it resulted in a speed-up of about 21%. Thanks to Dave Greve for supplying that example. Sped up [47m[include-book][0m a bit by memoizing checksums of symbols. (This change pertains to ``normal'' ACL2 only, not the [47m[hons][0m version (see [hons-and-memoization], where such memoization already occurred.) We found about a 23% speed-up on an example from Dave Greve. Made a small change to the algorithm used to prove hypotheses of [47m:[0m[47m[type-prescription][0m rules (ACL2 source function [47mtype-set-relieve-hyps[0m). One change avoids a linear walk through the context (the ``type-alist'' structure), while the other could avoid storing unnecessary [47m[force][0md assumptions (into the so-called ``tag-tree''). [31;1mBUG FIXES[0m Fixed a long-standing soundness bug caused by the interaction of [47m[force][0md hypotheses with destructor [elim]ination. The fix was to avoid using forcing when building the context (so-called ``type-alist'') when the goal is considered for destructor elimination; those who are interested can see a discussion in source function [47meliminate-destructors-clause1[0m, which includes a proof of [47mnil[0m that no longer succeeds. A similar fix was made for generalization, though we have not exploited the previous code to prove [47mnil[0m in that case. Fixed a bug that allowed book certification to ignore [47mskip-proofs[0m around [47m[encapsulate][0m [events]. Thus, a book could contain an event of the form [47m(skip-proofs (encapsulate ...))[0m, and a call of [47m[certify-book][0m on that book could succeed even without supplying keyword [47m:skip-proofs-okp t[0m. This bug was introduced in Version 3.5 (May, 2009). Fixed a bug that could occur when including a book that attempts to redefine a function as a macro, or vice-versa. (For details of the issue, see the comment in the definition of variable [47m*hcomp-fn-macro-restore-ht*[0m in source file [47mother-events.lisp[0m.) (Windows only) Fixed handling of the Windows drive so that an executable image saved on one machine can be used on another, even with a different drive. Thanks to Harsh Raju Chamarthi for reporting this issue and doing a lot of testing and collaboration to help us get this right. Made a change to avoid possible low-level errors, such as bus errors, when quitting ACL2 by calling [47m[good-bye][0m or its synonyms. This was occurring in CCL, and we are grateful to Gary Byers for helping us find the source of those errors (which basically was that ACL2 was attempting to quit while already in the process of quitting). Fixed a bug in [47m[with-guard-checking][0m, which was being ignored in function bodies. Fixed a bug in [47m[top-level][0m, which was not reverting the logical [world] when an error resulted from evaluation of the given form. Thanks to Jared Davis for bringing this bug to our attention. Fixed a long-standing bug (back through Version 2.7) that was discarding changes to the connected book directory (see [cbd]) when exiting and then re-entering the top-level ACL2 loop (with [47m[lp][0m). In some host Lisps, it has been possible to be in a situation where it is impossible to interrupt checkpoint printing during the summary. We had thought this solved when the host Lisp was CCL, but Sol Swords sent us an example (for which we are grateful) illustrating that this behavior could occur. This has been fixed. Fixed a bug in a proof obligation generated for [47m:[0m[47m[meta][0m and [47m:[0m[47m[clause-processor][0m rules, that the [guard] on the metafunction or clause-processor function, [47mfn[0m, holds under suitable assumptions. Those assumptions include not only that the first argument of [47mfn[0m satisfies [47m[pseudo-termp][0m, but also that all [stobj] inputs satisfy the corresponding stobj recognizer predicates. We had erroneously considered stobj outputs of [47mfn[0m instead of stobj inputs. Thanks to Sol Swords for bringing this bug to our attention with a simple example, and correctly pointing us to the bug in our code. Fixed the following bugs in [47m[defattach][0m. We hadn't always been applying the full functional substitution when generating guard proof obligations. We had been able to hit an assertion when reattaching to more than one function. Attachment was permitted in the case of an untouchable function (see [remove-untouchable]). Finally, the guard proof obligation could fail in the case that the two functions have different formal parameter lists, as in the following example. (encapsulate ((foo (x) x :guard (symbolp x))) (local (defun foo (x) x))) (defun bar (x2) (declare (xargs :guard (symbolp x2))) x2) (defattach foo bar) Fixed a raw Lisp error that could be caused by including a book using [47m[make-event][0m to define a function symbol in a locally-introduced package. An example appears in a comment in ACL2 source function [47mwrite-expansion-file[0m. Made a change that can prevent an error near the end of book certification when the underlying Host Lisp is Allegro Common Lisp, in the case that environment variable [47mACL2_SYSTEM_BOOKS[0m has been set to the name of a directory with a parent that is a soft link. Thanks to Dave Greve for supplying an example to led us to this fix, which involves avoiding Allegro CL's implementation of the Common Lisp function, [47mtruename[0m. Fixed a bug that was failing to substitute fully using bindings of free variables in [47m[force][0md hypotheses. A related change is that instead of binding such a free variable to a new variable of the form [47m???-Y[0m, the new variable is now of the form [47mUNBOUND-FREE-Y[0m. Fixed a bug that could inhibit the printing of certain theory warnings (and probably, in the other direction, cause inappropriate such printing). We eliminated excessive [47m"Raw-mode"[0m warnings about [47m[add-include-book-dir][0m that could be generated by the use of raw-mode during [47m[include-book][0m. Thanks to Dave Greve for bringing this issue to our attention. Fixed the printing of results from forms within an [47m[encapsulate][0m, so that they are abbreviated according to the [47m[ld-evisc-tuple][0m. It is now possible to evaluate [stobj]-related forms after evaluating [47m:[0m[47m[set-guard-checking][0m [47m:none[0m or [47m:[0m[47m[set-guard-checking][0m [47mnil[0m, even in cases where such evaluation formerly caused a guard violation due to a bug in ACL2. Here is an example of an error that no longer occurs. ACL2 !>(defstobj st fld) Summary Form: ( DEFSTOBJ ST ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ST ACL2 !>(set-guard-checking :none) Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(fld st) ACL2 Error in TOP-LEVEL: The guard for the function call (FLD ST), which is (STP ST), is violated by the arguments in the call (FLD ST). [... etc. ...] You can understand how things now work by imagining that when a function introduced by [47m[defstobj][0m is called, [47m[guard][0m-checking values of [47m:none[0m or [47mnil[0m are temporarily converted to [47mt[0m. Thanks to Pete Manolios, Ian Johnson, and Harsh Raju Chamarthi for requesting this improvement. Fixed a bug in which the wrong attachment could be made when the same function has an attachment in a book and another in the certification world of that book (possibly even built into ACL2), if the load of a compiled file is aborted because a sub-book's compiled file is missing. The bug has been present since the time that [47m[defattach][0m was added (Version_4.0). An example may be found in a comment in the [47m[deflabel][0m for [47mnote-4-2[0m (ACL2 source file [47mld.lisp[0m). The [47m:[0m[47m[doc][0m and related utilities now cause a clean error when provided other than a symbol. Thanks to Jared Davis for pointing out the raw Lisp error that had occurred in such cases. It had been the case that in raw-mode (see [set-raw-mode]), it was possible to confuse [47m[include-book][0m when including a book in a directory different from the current directory. This has been fixed. Thanks to Hanbing Liu for bringing this problem to our attention with a small example. [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m Many changes have been made to the distributed books, thanks to an active ACL2 community. You can contribute books and obtain updates between ACL2 releases by visiting the ACL2 Books web page. [Note: This release note is obsolete, as it referenced the now-invalid URL, [47mhttp://acl2-books.googlecode.com/[0m.] There is new [47mMakefile[0m support for certifying just some of the distributed books. See [books-certification-classic], in particular discussion of the variable [47mACL2_BOOK_DIRS[0m. Thanks to Sandip Ray for requesting this enhancement. The [documentation] for [47m[make-event][0m now points to a new book, [47mbooks/make-event/defrule.lisp[0m, that shows how [47mmake-event[0m can be used to do macroexpansion before generating [events]. Thanks to Carl Eastlund for useful interaction on the acl2-help mailing list that led us to add this example. [31;1mEMACS SUPPORT[0m Incorporated a version of changes from Jared Davis to the [47mcontrol-t f[0m emacs utility (distributed file [47memacs/emacs-acl2.el[0m), so that one can fill a format string from anywhere within the string. [31;1mEXPERIMENTAL VERSIONS[0m We refrain from listing changes here to experimental versions, other than an enhancement to the [hons] version that can reduce sizes of [certificate] files, by applying [47m[hons-copy][0m to introduce structure sharing (ACL2 source function [47mmake-certificate-file1[0m).") (|NOTE-4-2{R}| (release-notes) "ACL2 Version 4.2(r) (January, 2011) Notes Please see [note-4-2] for changes in Version 4.2 of ACL2.") (note-4-3 (release-notes) "ACL2 Version 4.3 (July, 2011) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 4.2 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level and to distributed books, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m Significant changes have been made for list-processing primitives such as [47m[member][0m and [47m[assoc][0m; see [equality-variants]. In summary: instead of separate functions based on [47m[eq][0m, [47m[eql][0m, and [47m[equal][0m, there is essentially just one function, which is based on [47m[equal][0m; the [47m[eq][0m and [47m[eql][0m variants are logically just the [47m[equal][0m variant. For example, [47m[member-eq][0m and [47m[member][0m are macros that generate corresponding calls of [47m[member-equal][0m in the logic, although in raw Lisp they will execute using tests [47m[eq][0m and [47m[eql][0m, respectively. References to any of these in logical contexts such as [theories] are now references to the function based on [47m[equal][0m; for example, the hint [47m:in-theory (disable member)[0m is completely equivalent to the hint [47m:in-theory (disable member-equal)[0m. Distributed books have been modified as necessary to accommodate this change. While the need for such changes was relatively infrequent, changes were for example needed in contexts where terms are manipulated directly; for example, [47m[defevaluator][0m needs to mention [47m[member-equal][0m rather than [47m[member][0m, just as it was already the case to mention, say, [47m[binary-append][0m rather than [47m[append][0m. Again, see [equality-variants] for more information about equality variants. A few improvements were made in support of the modified treatment of equality variants discussed above. The changes include the following. o We now allow the use of macro aliases (see [macro-aliases-table] in [47m:trigger-fns[0m of rules (see [rule-classes]). o We now remove so-called ``guard holders'' (including calls of [47m[return-last][0m, hence of [47m[mbe][0m) in [47m:trigger-terms[0m of rules. o We also remove guard holders in formulas of [47m:[0m[47m[congruence][0m and [47m[type-prescription][0m rules. o Macros [47munion-eq[0m and [47mintersection-eq[0m can now take any positive number of arguments, and [47m[union-eq][0m can take zero arguments. (Thanks to Jared Davis for requesting this enhancement.) The same can be said for new macros [47m[union$][0m and [47m[intersection$][0m, respectively. o A few changes were made to built-in theorems from source file [47maxioms.lisp[0m, in particular disabling [47m:[0m[47m[type-prescription][0m rule [47mconsp-assoc-equal[0m (formerly two enabled rules, [47mconsp-assoc-eq[0m and [47mconsp-assoc[0m) but adding this theorem as a [47m:forward-chaining[0m rule, and similarly for [47mtrue-list-listp-forward-to-true-listp-assoc-equal[0m (and eliminating rule [47mtrue-list-listp-forward-to-true-listp-assoc-eq[0m; and disabling rule [47mtrue-listp-cadr-assoc-eq-for-open-channels-p[0m. Also, theorem [47mall-boundp-preserves-assoc[0m has been renamed to [47mall-boundp-preserves-assoc-equal[0m and also strengthened. o Some [guard]s were slightly improved (logically weaker or the same). Improved [47mget-output-stream-string$[0m to allow for a context and to do genuine error printing instead of using [47m[cw][0m. See [io]. Added the symbols [47m[flet][0m and [47m[with-local-stobj][0m to [47m*acl2-exports*[0m. A small change was made to the processing of more than one [47m:[0m[47m[guard][0m declaration for the same function. In particular, a guard of [47mt[0m is essentially ignored. Attachments are now allowed during evaluation of the first argument of [47m[prog2$][0m even in contexts (such as proofs) during which the use of attachments is normally prohibited. More generally, the second of the three arguments of [47m[return-last][0m has this property, except in the case of [47m[mbe][0m (or related macros like [47m[mbe1][0m), where the [47mexec[0m argument may provide the value. Thanks to Sol Swords for useful discussions leading us to implement this enhancement. The restriction has been removed that prohibited the use of [47m[mbe][0m inside [47m[encapsulate][0m [events] with a non-empty [signature]. This restriction was introduced in Version 3.4, but has not been necessary since Version 4.0, when we first started disallowing [guard] verification for functions introduced non-[local]ly inside such [47m[encapsulate][0m events. We weakened the checks involving common ancestors for evaluator and [meta] (and [clause-processor]) functions (see [evaluator-restrictions]) so that except in the [47m[mbe][0m case, the next-to-last argument of [47m[return-last][0m is not considered. Thanks to Sol Swords for bringing this issue to our attention. The macro [47m[append][0m no longer requires at least two arguments. Thanks to Dave Greve for requesting this enhancement. (Mostly for system hackers) Now, [47m[break-on-error][0m breaks at a more appropriate (earlier) time for certain system functions that do not return state, such as [47mtranslate11[0m. Thanks to David Rager for requesting this improvement. [47m[Show-accumulated-persistence][0m may take a new argument, [47m:runes[0m, which simply causes an alphabetical list of [rune]s to be printed out. Improved [47m[trace$][0m so that [47m:entry[0m, [47m:exit[0m, and [47m:cond[0m forms may reference [47mstate[0m even if the function being traced does not include [47mstate[0m as a formal. The system function [47macl2x-expansion-alist[0m now takes a second argument, namely [47m[state][0m. This change allows for more flexibility in the sorts of attachments that can be made to this function (see [defattach]). Thanks to Jared Davis and Sol Swords for requesting this enhancement and providing a preliminary implementation. An obscure [proof-builder] change, unlikely to affect users, replaces the state global variables [47merp[0m, [47mval[0m, [47mprint-macroexpansion-flg[0m, and [47mprint-prompt-and-instr-flg[0m by [47mpc-erp[0m, [47mpc-val[0m, [47mpc-print-macroexpansion-flg[0m, and [47mpc-print-prompt-and-instr-flg[0m, respectively. [State] globals [47mfmt-hard-right-margin[0m and [47mfmt-soft-right-margin[0m are now untouchable (see [set-fmt-hard-right-margin] and see [push-untouchable]). If you bind these [47mstate[0m globals with [47m[state-global-let*][0m, then you will need to do so with appropriate setters to restore their values, for example as follows. (state-global-let* ((fmt-hard-right-margin 500 set-fmt-hard-right-margin) (fmt-soft-right-margin 480 set-fmt-soft-right-margin)) ...) The error message has been improved for the case of evaluating an undefined function that has an attachment (see [defattach]). Thanks to Jared Davis for sending the following example, which illustrates the additional part of the message. ACL2 !>(defstub foo (x) t) [[... output omitted ...]] ACL2 !>(defattach foo identity) [[... output omitted ...]] ACL2 !>(defconst *x* (foo 3)) ACL2 Error in ( DEFCONST *X* ...): ACL2 cannot ev the call of undefined function FOO on argument list: (3) Note that because of logical considerations, attachments (including IDENTITY) must not be called in this context. [[... additional output omitted ...]] The directory string supplied to [47m[add-include-book-dir][0m no longer must terminate with the `[47m/[0m' character, as had been required in some Lisp implementations. Thanks to Sol Swords for bringing this issue to our attention. We no longer print induction schemes with [gag-mode]; use [47m:[0m[47m[pso][0m if you want to see them. Thanks to Dave Greve for this suggestion. It is now legal to supply a constant for a [stobj] array dimension. See [defstobj]. Thanks to Warren Hunt for requesting this enhancement. We cleaned up a few issues with [47m[defpkg][0m. o It is no longer illegal to submit a [47m[defpkg][0m form in raw-mode (see [set-raw-mode]). Thanks to Jun Sawada for reporting an example in which an [47m[include-book][0m form submitted in raw-mode caused an error because of a `hidden' [47m[defpkg][0m form (see [hidden-defpkg]). There will no longer be an error in such cases. o It had been the case that [local]ly including a book could make it possible to use a package defined by that book. Consider for example the following book, [47mfoo.lisp[0m. (in-package "ACL2") (local (include-book "arithmetic/top" :dir :system)) After certifying this book, it had been possible to admit the following events in a new session. (include-book "foo") (defconst acl2-asg::*foo* 3) (defconst *c* 'acl2-asg::xyz) In Version_4.3, neither of these [47m[defconst][0m events is admitted. o A hard Lisp error is now avoided that had been possible in rare cases when including books with hidden packages (see [hidden-defpkg]). An example may be found in a comment in the [47m[deflabel][0m for [47mnote-4-3[0m (in ACL2 source file [47mld.lisp[0m). The undocumented (but sometimes useful) functions [47mpackn1[0m and [47mpackn[0m are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Thanks to Sandip Ray for requesting this enhancement. It had been the case that when including a book, functions defined in the book's certification [world] (that is, in its [portcullis] [command]s) were typically not given compiled code. That has been fixed. The commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pl2][0m have been improved, primarily by printing information for more rule classes. See [pl] and see [pl2]. See also the item below about the new [proof-builder] command, [47mshow-type-prescriptions[0m. [31;1mNEW FEATURES[0m New macros [47m[mv?-let][0m and [47m[mv?][0m extend the functionality of [47m[mv-let][0m and [47m[mv][0m (respectively) to the case of a single value. Macro [with-local-state] is available for system programmers who wish bind [47m[state][0m locally, essentially using [with-local-stobj]. But this should only be done with extreme care, and it requires an active trust tag; see [with-local-state]. Formatted printing functions now have analogues that print to strings and do not take an output channel or [47m[state][0m as arguments. See [printing-to-strings]. The system function [47mancestors-check[0m is now available for verified modification by users, i.e., attachment using [47m(defattach ancestors-check <your_function>)[0m. Thanks to Robert Krug for providing the necessary proof support, which we modified only in small ways. New macros, [47mobservation-cw[0m and [47mwarning$-cw[0m, provide formatted printing of [47m[observation][0ms and warnings (respectively) without [47m[state][0m. Thanks to Harsh Raju Chamarthi and David Rager for requests leading to these utilities. [47mObservation-cw[0m is now used in some of the distributed books (thanks to Robert Krug for useful interaction for that). The [proof-builder] command [47mtype-alist[0m (see [proof-builder-commands]) now takes an optional third argument that causes the production of forward-chaining reports (see [forward-chaining-reports]). Thanks to Dave Greve for requesting such an enhancement. The reports generated by forward-chaining, [forward-chaining-reports], have been changed to indicate when a conclusion reached by forward chaining is [47mREDUNDANT[0m with respect to the type information already known. Thanks to Dave Greve for suggesting this enhancement. The utility [47m[with-prover-time-limit][0m is now legal for [events] (see [embedded-event-form]). For example, the following is now legal. (encapsulate () (with-prover-time-limit 2 (defthm append-assoc (equal (append (append x y) z) (append x (append y z)))))) The new utility [47m[with-prover-step-limit][0m is analogous to the utility [47m[with-prover-time-limit][0m, but counts ``prover steps'' rather than checking for time elapsed. See [with-prover-step-limit]. Also see [set-prover-step-limit] to provide a default step-limit. Note that just as [47m[with-prover-time-limit][0m may now be used to create [events], as discussed just above, [47m[with-prover-step-limit][0m may also be used to create [events]. Thanks to Carl Eastlund for requesting support for step-limits. The macro [47m[progn$][0m is analogous to [47m[prog2$][0m, but allows an arbitrary number of arguments. For example: ACL2 !>:trans1 (progn$ (f1 x) (f2 x) (f3 x)) (PROG2$ (F1 X) (PROG2$ (F2 X) (F3 X))) ACL2 !> Thanks to David Rager for contributing this macro. The macro [47m[defattach][0m may now be supplied the argument [47m:skip-checks :cycles[0m. In this case, as with argument [47m:skip-checks t[0m, a trust tag is required (see [defttag]), and no logical claims are made. The effect is to avoid the usual check that the extended ancestor relation has no cycles (see [defattach]). Thanks to Dave Greve for requesting this feature. You can now limit the printing of subgoal names when using [47m:[0m[47m[set-gag-mode][0m[47m :goals[0m. See [set-print-clause-ids]. Thanks to Karl Hoech for a suggestion leading to this enhancement. A new [proof-builder] command, [47mshow-type-prescriptions[0m, or [47mst[0m for short, provides information about [47m:[0m[47m[type-prescription][0m rules that match a given term. Thanks to Dave Greve for requesting this enhancement. See also the item above about related improvements to commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pl2][0m. [31;1mHEURISTIC IMPROVEMENTS[0m ACL2 now avoids some repeated attempts to rewrite hypotheses of rewrite rules. See [set-rw-cache-state] for a discussion of this behavior and how to avoid it. The default behavior has been observed to reduce by 11% the overall time required to complete a regression. Here are the directories that had the top three time decreases and top three time increases, shown in seconds. -368 coi/gacc (1064 down to 696: decrease of 35%) -220 workshops/1999/ste (664 down to 444: decrease of 33%) -148 unicode (331 down to 183: decrease of 45%) .... +7 workshops/2002/cowles-flat/support (229 up to 236: increase of 3%) +8 workshops/1999/ivy/ivy-v2/ivy-sources (508 up to 516: increase of 2%) +12 workshops/2009/hardin/deque-stobj (78 up to 91: increase of 17%) The so-called ``ancestors check,'' which is used to limit backchaining, has been strengthened so that two calls of [47m[equal][0m are considered the same even if their arguments appear in the opposite order. Thanks to Robert Krug for providing an implementation and a useful discussion. The check for [irrelevant-formals] in processing of [47m[defun][0ms has been made more efficient. Thanks to Eric Smith for reporting this issue in 2001 (!) and thanks to Warren Hunt for recently sending an example. For that example, we have seen the time for the [irrelevant-formals] check reduced from about 10 seconds to about 0.04 seconds. (GCL only) The macro [47m[mv][0m has been modified so that certain fixnum boxing can be avoided. (Allegro CL only) We have set to [47mnil[0m four Allegro CL variables that otherwise enable storing of certain source information (for details, see the discussion of ``cross-referencing'' in ACL2 source file [47macl2-init.lisp[0m). As a result of this change we have about a 6% speedup on the regression suite, but a 27% time reduction on an example that includes a lot of books. Exhaustive matching for the case of [free-variables] has been extended to [type-prescription] rules, in analogy to the default setting [47m:match-free :all[0m already in place for [rewrite], [linear], and [forward-chaining] rules. See [free-variables-type-prescription]. Thanks to Dave Greve for requesting this enhancement. [31;1mBUG FIXES[0m A soundness bug was fixed in some raw-Lisp code implementing the function, [47m[take][0m. Thanks to Sol Swords for pointing out this bug with (essentially) the following proof of [47mnil[0m. (defthmd take-1-nil-logic (equal (take 1 nil) '(nil)) :hints(("Goal" :in-theory (disable (take))))) (thm nil :hints (("Goal" :use take-1-nil-logic))) Calls of [47m[mbe][0m in ``safe-mode'' situations --- i.e., during evaluation of [47m[defconst][0m, [47m[value-triple][0m, and [47m[defpkg][0m forms, and during macroexpansion --- are now guard-checked. Thus, in these situations both the [47m:logic[0m and [47m:exec[0m forms will be evaluated, with an error if the results are not equal. Formerly, only the [47m:logic[0m form was evaluated, which was a soundness bug that could be exploited to prove [47mnil[0m. For such a proof and a bit of further explanation, see the example at the top of the comments for [47m(deflabel note-4-3 ..)[0m in ACL2 source file [47mld.lisp[0m. It had been possible to prove [47mnil[0m by proving the following theorem using ACL2 built on CCL and then proving its negation using ACL2 built on a different host Lisp. (defthm host-lisp-is-ccl (equal (cdr (assoc 'host-lisp *initial-global-table*)) :ccl) :rule-classes nil) This hole has been plugged by moving the setting of [47m'host-lisp[0m out of the constant [47m*initial-global-table*[0m. Fixed [47m[trace$][0m for arguments that are [stobj] accessors or updaters. It also gives an informative error in this case when the accessor or updater is a macro (because the introducing [47m[defstobj][0m event specified [47m:inline t[0m). Avoided a potential error that could occur when no user home directory is located. Our previous solution for Windows simply avoided looking for ACL2 customization files (see [ACL2-customization]) and [47macl2-init.lsp[0m files in a user's home directory. With this change, we handle such files the same for Windows as for non-Windows systems: we always look for ACL2 customization files (see [ACL2-customization]) and [47macl2-init.lsp[0m files in a user's home directory, but only if such a directory exists. Thanks to Hanbing Liu for reporting this issue. (GCL only) Fixed a bug that prevented the use of [47m[get-output-stream-string$][0m when the host Lisp is GCL. Fixed [47m[with-live-state][0m to work properly for executable counterparts (so-called ``*1*'' functions). Fixed a bug in the error message caused by violating the [guard] of a macro call. Fixed a bug in an error message that one could get when calling [47m[defattach][0m with argument [47m:skip-checks t[0m to attach to a [47m:[0m[47m[program][0m mode function symbol that was introduced with [47m[defun][0m. (This is indeed an error, but the message was confusing.) Thanks to Robert Krug for bringing this bug to our attention. Fixed a bug in the loop-checking done on behalf of [47m[defattach][0m, which could miss a loop. For an example, see the comment about loop-checking in the comments for [47m(deflabel note-4-3 ..)[0m in ACL2 source file [47mld.lisp[0m. Terms of the form [47m(hide <term>)[0m without free variables could be simplified, contrary to the purpose of [47m[hide][0m. This is no longer the case, Thanks to Dave Greve for reporting this issue. An infinite loop could occur when an error was encountered in a call of [47m[wormhole-eval][0m, for example with the following form, and this has been fixed. (wormhole-eval 'demo '(lambda () (er hard 'my-top "Got an error!")) nil) Fixed a bug in detection of package redefinition. While we have no example demonstrating this as a soundness bug, we cannot rule it out. Fixed a bug in the message produced by an erroneous call of [47m[flet][0m. Thanks to Jared Davis for reporting this bug and sending a helpful example. For a failed [47m[defaxiom][0m or [47m[defthm][0m event, we now avoid printing [rune]s that are used only in processing proposed rules to be stored, but not in the proof itself. Thanks to Dave Greve for sending us an example that led us to make this fix. ACL2 did not reliably enforce the restriction against non-[47m[local][0m [47m[include-book][0m [events] inside [47m[encapsulate][0m events, as illustrated by the following examples. ; not permitted (as expected) (encapsulate () (include-book "foo")) ; permitted (as expected) (encapsulate () (local (include-book "foo"))) ; formerly permitted (surprisingly); now, not permitted (local (encapsulate () (include-book "foo"))) Moreover, the corresponding error message has been fixed. Thanks to Jared Davis and Sandip Ray for relevant discussions. When [47m[include-book][0m is given a first argument that is not a string, a more graceful error now occurs, where previously an ugly raw Lisp error had occurred. Thanks to Eric Smith for bringing this bug to our attention. Fixed a bug in an error message that was printed when an unexpected expression has occurred where a [47m[declare][0m form is expected. (Since all functions are compiled when the host Lisp is CCL or SBCL, the following bug fix did not occur for those host Lisps.) After evaluation of [47m([0m[47m[set-compile-fns][0m[47m t)[0m, all defined functions are expected to run with compiled code; but this was not the case for functions exported from an [47m[encapsulate][0m event. This has been fixed. It had been the case that the [47m:[0m[47m[puff][0m command was broken for [47m[include-book][0m form whose book had been certified in a world with an [47m[add-include-book-dir][0m event. This has been fixed. Evaluation of [stobj] updaters (see [defstobj]) may no longer use attachments (see [defattach]). This is a subtle point that will likely not affect many users. Thanks to Jared Davis for bringing this issue to our attention; a slight variant of his example appears in a comment in ACL2 source function [47moneify-cltl-code[0m. It had been the case that even when a [stobj] creator function was declared to be untouchable (see [push-untouchable]), a [47m[with-local-stobj][0m form based on that same stobj was permitted. Now, such forms are not admitted. Thanks to Jared Davis for a query leading to this fix. Fixed a buggy message upon [guard] violations, which was suggesting the use of [47m(set-guard-checking :none)[0m in some cases when guard-checking was already set to [47m:none[0m. It had been possible to get a hard Lisp error when computing with [47m[ec-call][0m in [books]. The following is an example of such a book, whose certification no longer causes an error. (in-package "ACL2") (defun f (x) x) (defconst *c* (ec-call (f 3))) (defun g (x) (cons x x)) The command [47m:[0m[47m[pl2][0m, and also the [proof-builder] commands [47mrewrite[0m and [47mshow-rewrites[0m (and hence their respective aliases [47mr[0m and [47msr[0m), now take rule-id arguments that can be [47m:[0m[47m[definition][0m [rune]s. These commands dealt with definition rules already, e.g. :pl2 (append x y) binary-append but they did not allow explicit specification of [47m:definition[0m runes, e.g.: :pl2 (append x y) (:definition binary-append) The following example illustrates a bug in the processing of (admittedly obscure) [hints] of the form [47m:do-not-induct name[0m, where [47mname[0m is not [47mt[0m, [47m:otf-flg-override[0m, [47m:otf[0m, or [47mnil[0m. In this example, ACL2 had essentially ignored the hint and reverted to prove the original goal by induction, rather than to skip the goal temporarily as is expected for such hints. Thanks to David Rager for a helpful discussion. (thm (and (equal (append (append x y) z) (append x y z)) (equal (append (append x2 y2) z2) (append x2 y2 z2))) :hints (("Subgoal 1" :do-not-induct some-name))) Fixed a slight bug in the definitions of built-in [47m[theories][0m. For example, in a fresh ACL2 session the value of the following form is [47mnil[0m, but formerly included several [47m:[0m[47m[definition][0m [rune]s. (let ((world (w state))) (set-difference-theories (function-theory :here) (function-theory 'ground-zero))) [31;1mCHANGES AT THE SYSTEM LEVEL AND TO DISTRIBUTED BOOKS[0m Many changes have been made to the distributed books, as recorded in svn logs under the `Source' and 'Updates' links at the {ACL2 Books | http://acl2-books.googlecode.com/} web page. Here we list some of the more significant changes. o A large library has been graciously contributed by the formal verification group at Centaur Technology. See [47mbooks/centaur/[0m and, in particular, file [47mbooks/centaur/README[0m, which explains how the library depends on the experimental HONS extension (see [hons-and-memoization]). o Among the new books is an illustration of [47m[defattach][0m, [47mbooks/misc/defattach-example.lisp[0m, as well as a variant of defattach that avoids the need for [guard] verification, [47mbooks/misc/defattach-bang.lisp[0m. o Distributed book [47mbooks/misc/trace1.lisp[0m has been deleted. It had provided slightly more friendly [trace] output for new users, but distributed book [47mbooks/misc/trace-star.lisp[0m may be better suited for that purpose. ACL2 can once again be built on LispWorks (i.e., as the host Lisp), at least with LispWorks 6.0. Thanks to David Rager for useful conversations. Several changes have been made from previous LispWorks-based ACL2 executables: o ACL2 now starts up in its read-eval-print loop. o You can save an image with [47m[save-exec][0m. o Multiprocessing is not enabled. o The stack size is managed using a LispWorks variable that causes the stack to grow as needed. o When ACL2 is built a script file is written, as is done for other host Lisps. Thus, (assuming that no [47mPREFIX[0m is specified), [47msaved_acl2[0m is just a small text file that invokes a binary executable, which for Lispworks is [47msaved_acl2.lw[0m. The HTML documentation no longer has extra newlines in <pre> environments. Statistics on ACL2 code size may be found in distributed file [47mdoc/acl2-code-size.txt[0m. This file and other information can be found in a new [documentation] topic, [about-ACL2]. Fixed the build process to pay attention to environment variable [47mACL2_SYSTEM_BOOKS[0m (which may be supplied as a command-line argument to `make'). An ACL2 executable can thus now be built even when there is no [47mbooks/[0m subdirectory if a suitable replacement directory is supplied. Some warnings from the host Lisp are now suppressed that could formerly appear. For example, the warnings shown below occurs in Version 4.2 using Allegro CL, but not in Version 4.3. ACL2 !>(progn (set-ignore-ok t) (set-irrelevant-formals-ok t) (defun bar (x y) x)) [[.. output omitted ..]] BAR ACL2 !>:comp bar ; While compiling BAR: Warning: Variable Y is never used. ; While compiling (LABELS ACL2_*1*_ACL2::BAR ACL2_*1*_ACL2::BAR): Warning: Variable Y is never used. BAR ACL2 !> [31;1mEMACS SUPPORT[0m The distributed Emacs file [47memacs/emacs-acl2.el[0m now indents calls of [47mer@par[0m and [47mwarning$@par[0m the same way that calls of [47mdefun[0m are indented. [31;1mEXPERIMENTAL VERSIONS[0m The parallel version (see [parallelism]) now supports parallel evaluation of the ``waterfall'' part of the ACL2 prover; see [set-waterfall-parallelism]. Thanks to David Rager for doing the primary design and implementation work. A new macro, [47m[spec-mv-let][0m, supports speculative and parallel execution in the parallel version, courtesy of David Rager. Among the enhancements for the HONS version (see [hons-and-memoization]) are the following. [47m[Memoize][0md functions may now be traced (see [trace$]). Thanks to Sol Swords for requesting this enhancement. [47m[Memoize-summary][0m and [47m[clear-memoize-statistics][0m are now [47m:[0m[47m[logic][0m mode functions that return [47mnil[0m. Thanks to Sol Swords for this enhancement. [47m[Memoize][0m is now explicitly illegal for constrained functions. (Already such memoization was ineffective.) A new keyword argument, [47m:AOKP[0m, controls whether or not to allow memoization to take advantage of attachments; see [memoize] and for relevant background, see [defattach]. [47m[Memoize][0m is now illegal by default for [47m:[0m[47m[logic][0m mode functions that have not had their guards verified. See [memoize] (keyword [47m:ideal-okp[0m) and see [ACL2-defaults-table] (key [47m:memoize-ideal-okp[0m) for an explanation of this restriction and how to avoid it. [History] commands such as [47m:[0m[47m[pe][0m and [47m:[0m[47m[pbt][0m now display ``[47mM[0m'' or ``[47mm[0m'' to indicate memoized functions. See [pc].") (|NOTE-4-3{R}| (release-notes) "ACL2 Version 4.3(r) (July, 2011) Notes Please see [note-4-3] for changes in Version 4.3 of ACL2.") (note-5-0 (release-notes) "ACL2 Version 5.0 (August, 2012) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 4.3 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level and to distributed books, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. NOTE: ACL2 is now distributed under Version 2 of the GNU General Public License. [Added later: The license has changed since Version_5.0. See LICENSE.] Formerly, any later version had been acceptable. Moreover, books are no longer distributed from a University of Texas website, but rather, from Google Code at the {ACL2 Books Downloads | http://code.google.com/p/acl2-books/downloads/} page. [31;1mCHANGES TO EXISTING FEATURES[0m A fatal error now occurs if environment variable [47mACL2_CUSTOMIZATION[0m has a value other than [47mNONE[0m or the empty string, but is not the name of an existing file. Thanks to Harsh Raju Chamarthi for requesting such a change. Functions [47mread-acl2-oracle[0m (and [47mread-acl2-oracle@par[0m), [47mread-run-time[0m, and [47mmain-timer[0m are no longer untouchable (see [remove-untouchable]). We now avoid certain duplicate conjuncts in the [constraint] stored for [47m[encapsulate][0m [events]. For example, the constraint stored for the following event formerly included [47m(EQUAL (FOOP (CONS X Y)) (FOOP Y))[0m and [47m(BOOLEANP (FOOP X))[0m twice each, but no more. (encapsulate ((foop (x) t)) (local (defun foop (x) (declare (ignore x)) t)) (defthm foop-constraints (and (booleanp (foop x)) (equal (foop (cons x y)) (foop y))) :rule-classes ((:type-prescription :corollary (booleanp (foop x))) (:rewrite :corollary (equal (foop (cons x y)) (foop y)))))) The [47m:[0m[47m[guard][0m for a constrained function (see [signature]) may now mention function symbols introduced in the same [47m[encapsulate][0m event that introduces that function. Thanks to Nathan Wetzler for a helpful discussion leading to this improvement. The test for redundancy (see [redundant-events]) of [47m[encapsulate][0m [events] has been improved in cases involving redefinition (see [ld-redefinition-action]). Thanks to Jared Davis for providing the following example, which illustrates the problem. (redef!) (encapsulate () (defun g (x) (+ 3 x))) (g 0) ; 3, as expected (encapsulate () (defun g (x) (+ 4 x))) (g 0) ; 4, as expected ; Unfortunately, the following was flagged as redundant because it agreed ; with the first encapsulate above. That has been fixed; now, it is ; recognized as not being redundant. (encapsulate () (defun g (x) (+ 3 x))) The test for redundancy of [47m[defun][0m and [47m[defconst][0m events has been improved in the case that redefinition is active. In that case, redundancy now additionally requires that the ``translated'' body is unchanged, i.e., even after expanding macro calls and replacing constants (defined by [47m[defconst][0m) with their values. Thanks to Sol Swords for requesting this enhancement, and to Jared Davis for pointing out a bug in a preliminary change. See [redundant-events], in particular the ``Note About Unfortunate Redundancies''. Note that this additional requirement was already in force for redundancy of [47m[defmacro][0m events. The macro [47m[defmacro-last][0m and the [table] [47m[return-last-table][0m have been modified so that when they give special treatment to a macro [47mmac[0m and its raw Lisp counterpart [47mmac-raw[0m, a call [47m(return-last 'mac-raw ...)[0m can be made illegal when encountered directly in the top level loop, as opposed to inside a function body. See [return-last]. Thanks to Harsh Raju Chamarthi for showing us an example that led us to make this improvement. We removed a barrier to admitting function definitions, as we explain using the following example. (defun foo (m state) (declare (xargs :stobjs state)) (if (consp m) (let ((state (f-put-global 'last-m m state))) (foo (cdr m) state)) state)) Previously, ACL2 complained that it could not determine the outputs of the [47m[let][0m form, as is necessary in order to ensure that [47m[state][0m is returned by it. ACL2 now works harder to solve this problem as well as the analogous problem for [47m[mv-let][0m and, more generally for [47m[mutual-recursion][0m. (The main idea is to reverse the order of processing the [47m[if][0m branches if necessary.) We thank Sol Swords for contributing a version of the above example and requesting this improvement. It is no longer the case that [47m[break-on-error][0m causes a Lisp break when encountering an error during translation of user input into internal (translated) form (see [term]). The reason is that an improvement to the translation process, specifically the one described in the preceding paragraph, allows certain backtracking from ``errors'', which are intended to be silent rather than causing breaks into raw Lisp. Thanks to Jared Davis for sending an example leading to this change. (CCL and SBCL only) When the host Lisp is CCL or SBCL, then since all functions are compiled, a [47m[certify-book][0m command will no longer load the newly-compiled file (and similarly for [47m[include-book][0m with argument [47m:load-compiled-file :comp[0m). [47m[Set-write-acl2x][0m now returns an error triple and can take more values, some of which automatically allow including uncertified books when [47m[certify-book][0m is called with argument :acl2x t. The environment variable [47mCOMPILE_FLG[0m has been renamed [47mACL2_COMPILE_FLG[0m; see [certify-book]. The macros [47m[defthmd][0m and [47m[defund][0m no longer return an error triple with value [47m:SKIPPED[0m when proofs are being skipped. Rather, the value returned is the same as would be returned on success when proofs are not skipped. For those who use [47m[set-write-ACL2x][0m: now, when [47m[certify-book][0m is called without a [47m:ttagsx[0m argument supplied, then the value of [47m:ttagsx[0m defaults to the (explicit or default) value of the [47m:ttags[0m argument. The [47m:[0m[47m[pl][0m and [47m:[0m[47m[pl2][0m [command]s can now accept [term]s that had previously been rejected. For example, the command [47m:pl (member a (append x y))[0m had caused an error, but now it works as one might reasonably expect, treating [47m[member][0m as [47m[member-equal][0m (see [equality-variants] for relevant background). Thanks to Jared Davis for reporting this problem by sending the above example. We have eliminated some hypotheses in built-in [rewrite] rules [47mcharacterp-nth[0m and [47mordered-symbol-alistp-delete-assoc-eq[0m. Added the symbols [47m[f-get-global][0m, [47m[f-put-global][0m, and [47m[state-global-let*][0m to [47m*acl2-exports*[0m. Added to the [guard]s of [47m[push-untouchable][0m and [47m[remove-untouchable][0m the requirement that the second argument must be a Boolean. Thanks to Jared Davis for sending an example that led to this change. The built-in function [47mstring-for-tilde-@-clause-id-phrase[0m has been put into [47m:[0m[47m[logic][0m mode and had its guards verified, as have some subsidiary functions. A few new rules have been added in support of this work; search for [47mstring-for-tilde-@-clause-id-phrase[0m in ACL2 source file [47mboot-strap-pass-2.lisp[0m if interested. Thanks to David Rager for contributing an initial version of this improvement. All trust tags are now in the [keyword] package. The [47m[defttag][0m event may still take a symbol in an arbitrary package, but the trust tag created will be in the keyword package (with the same [47m[symbol-name][0m as the symbol provided). Similarly, non-[47mnil[0m symbols occurring in the [47m:ttags[0m argument of an [47m[include-book][0m or [47m[certify-book][0m command will be converted to corresponding keywords. See [defttag]. There have been several changes to [gag-mode]. It is now is initially set to [47m:goals[0m, suppressing most proof commentary other than key checkpoints; see [set-gag-mode]. (As before, see [pso] for how to recover the proof output.) Also, top-level induction schemes are once again printed when gag-mode is on, though these as well as printing of guard conjectures can be abbreviated (``eviscerated'') with a new [evisc-tuple]; see [set-evisc-tuple], in particular the discussion there of [47m:GAG-MODE[0m. Finally, the commentary printed within [gag-mode] that is related to [forcing-round]s is now less verbose. Thanks to Dave Greve and David Rager for discussions leading to the change in the printing of induction schemes under gag-mode; thanks to Warren Hunt for an email that led us to similar handling for printing of guard conjectures; and thanks to Robert Krug for a suggestion that led us to restore, in abbreviated form, important information about the sources of forcing round goals. An error now occurs if [47m[ld][0m is called while loading a compiled book. See [calling-ld-in-bad-contexts]. Thanks to David Rager for reporting a low-level assertion failure that led us to make this change. The [proof-builder] interactive loop is more robust: most errors will leave you in that loop, rather than kicking you out of the proof-builder and thus back to the main ACL2 read-eval-print loop. Thanks to David Hardin for suggesting this improvement in the case of errors arising from extra right parentheses. The summary at the end of a proof now prints the following note when appropriate: [NOTE: A goal of NIL was generated. See :DOC nil-goal.] See [nil-goal]. Improved [47m[dmr][0m to show the function being called in the case of explicit evaluation: ``[47m(EV-FNCALL function-being-called)[0m''. It is now permitted to bind any number of [stobjs] to themselves in the bindings of a [47m[let][0m expression. But if any stobj is bound to other than itself in [47m[let][0m bindings, then there still must be only one binding in that [47mLET[0m expression. The analogous relaxation holds for [47m[lambda][0m expressions. Thanks to Sol Swords for requesting such a change, which was needed for some code generated by macro calls. The macro [47m[top-level][0m now returns without error; See [top-level]. Formerly, this macro always returned an error triple [47m(mv t .. state)[0m, which meant that normal calls of [47m[ld][0m would stop after encountering a call of [47mtop-level[0m. Thanks to Jared Davis for bringing this issue to our attention. It is no longer the case that when you specify [47m[xargs][0m keyword [47m:non-executable t[0m in a [47m[defun][0m form rather than using [47m[defun-nx][0m, then the form of the body need match only the shape [47m(prog2$ (throw-nonexec-error ... ...) ...)[0m. We now require that the body of the definition of a function symbol, [47mfn[0m, with formals [47m(x1 ... xk)[0m, be of the form [47m(prog2$ (throw-nonexec-error 'fn (list x1 ... xk)) ...)[0m. This fixes the following odd behavior, which could be considered a bug. Consider a book that contains the following two events. (defun foo (x) (declare (xargs :guard t :non-executable t :mode :logic)) (prog2$ (throw-nonexec-error 'bar (list x)) (cons 3 x))) (defn h (x) (foo x)) After certifying this book and then including it in a new session, the behavior occurred that is displayed below; notice the mention of [47mBAR[0m. However, if the two forms were submitted directly in the loop, then the error message had mentioned [47mFOO[0m instead of [47mBAR[0m. This discrepancy has been eliminated, by rejecting the proposed definition of [47mfoo[0m because the name in the first argument of [47mthrow-nonexec-error[0m was [47m'bar[0m where now it must be [47m'foo[0m. ACL2 !>(h 3) ACL2 Error in TOP-LEVEL: ACL2 cannot ev the call of undefined function BAR on argument list: (3) To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> A tautology checker used in the ACL2 sources (function [47mif-tautologyp[0m) has been limited somewhat in the effort it makes to recognize a tautology. While we expect it to be rare for the effect of this change to be noticeable, we thank Sol Swords for sending us an example that motivated this change: a [guard] verification that took about 5 seconds in Version_4.3 now takes, on the same machine, about 0.07 seconds. The behavior of backquote ([47m`[0m) has been changed slightly to be compatible with its behavior in raw Lisp. The change is to allow the use of comma-atsign ([47m,@[0m) at the end of a list, as in the following example. (let ((x 3) (y 2) (z 7)) `(,x ,y ,@z)) Formerly, evaluation of this form had caused a guard violation in the ACL2 loop unless guard-checking was off (i.e., [47m[set-guard-checking][0m was invoked with [47mnil[0m or [47m:none[0m), in which case it returned [47m(3 2)[0m. But we observed evaluation of this form to return [47m(3 2 . 7)[0m in every host Lisp on which ACL2 runs (Allegro CL, CCL, CLISP, CMUCL, GCL, LispWorks, and SBCL). Now, ACL2 behaves like these Lisps. A call of the [47m[theory][0m macro had previously returned [47mnil[0m when applied to other than the name of name of a previously executed [47m[deftheory][0m event. Now, a hard error occurs. The [table] [47mbinop-table[0m has been replaced by the table [47m[untrans-table][0m. However, [47m[add-binop][0m and [47m[remove-binop][0m continue to have the same effect as before. See [add-macro-fn], which is a new feature discussed below. The function [47m[booleanp][0m is now defined using [47m[eq][0m instead of [47m[equal][0m, which may increase its efficiency. Thanks to Jared Davis for this change. For pairs [47m(key . val)[0m in the [47m[macro-aliases-table][0m, there had been a requirement that [47mval[0m is a known function symbol. Now, it only needs to be a symbol. (This change was made to support the new feature, [47m[defun-inline][0m, described elsewhere in these release notes.) [31;1mNEW FEATURES[0m A new ``tau system'' provides a kind of ``type checker.'' See [tau-system]. Thanks to Dave Greve for supplying a motivating example (on which this system can provide significant speedup), and to Sol Swords for sending a very helpful bug report on a preliminary implementation. Users may now arrange for additional summary information to be printed at the end of [events]. [Note added at Version_6.1: Formerly we pointed here to [47mprint-summary-user[0m, but now, see [finalize-event-user]; also see [note-6-1]]. Thanks to Harsh Raju Chamarthi for requesting this feature and participating in a design discussion. A new, advanced [proof-builder] command, [47mgeneqv[0m, shows the generated equivalence relation at the current subterm. Thanks to Dave Greve for an inquiry leading to this enhancement. A new reader macro, [47m#u[0m, permits the use of underscore characters in a number. See [sharp-u-reader]. Thanks to Jared Davis for requesting this capability. New [proof-builder] commands [47mpl[0m and [47mpr[0m provide interfaces to the ACL2 commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pr][0m, respectively. These can be useful if you want to see trivially-proved hypotheses, as now clarified in the [proof-builder] documentation for its [47mshow-rewrites[0m command. See [proof-builder-commands]. Thanks to Pete Manolios for suggesting such clarification and capability. It is now legal to call [non-executable] functions without the usual [signature] restrictions imposed on executable code. For example, the third event below was not admissible, but now it is. (defstobj foo fld) (defun-nx id (x) x) (defun f (foo) (declare (xargs :stobjs foo :verify-guards nil)) (cons 3 (id foo))) Thanks to Jared Davis for requesting this enhancement, in particular for calling non-executable functions in the [47m:logic[0m part of an [47m[mbe][0m call. Here is Jared's example, which is admissible now but formerly was not. (defstobj foo (fld)) (defun-nx my-identity (x) x) (defun my-fld (foo) (declare (xargs :stobjs foo)) (mbe :logic (my-identity foo) :exec (let ((val (fld foo))) (update-fld val foo)))) A new macro, [47m[non-exec][0m, allows the use of non-executable code, for example inside ordinary function definitions. Thanks to Sol Swords for requesting this enhancement. A new ``provisional certification'' process is supported that can allow [books] to be certified before their included sub-books have been certified, thus allowing for potentially much greater `make'-level parallelism. See [provisional-certification]. Thanks to Jared Davis for requesting this feature and for helpful discussions, based in part on rudimentary provisional certification schemes that he developed first at Rockwell Collins and later for his `Milawa' project. Also, thanks to Jared and to Sol Swords for testing this feature and for providing a fix for a bug in a preliminary implementation, and thanks to Sol for providing performance feedback and a crucial suggestion that led to an improved implementation. Event summaries now show the names of events that were mentioned in [hints] of type [47m:use[0m, [47m:by[0m, or [47m:clause-processor[0m. See [set-inhibited-summary-types]. Thanks to Francisco J. Martin Mateos for requesting such an enhancement (actually thanks to the community, as his request is the most recent but this has come up from time to time before). ACL2 now stores a data structure representing the relation ``Event A is used in the proof of Event B.'' See [dead-events], which explains this data structure and mentions one application: to identify dead code and unused theorems. Thanks to Shilpi Goel for requesting such a feature and for helpful feedback. A new [documentation] topic provides a guide to programming with state; see [programming-with-state]. Thanks to Sarah Weissman for suggesting that such a guide might be useful, and to David Rager for helpful feedback on a preliminary version. There also has been some corresponding reorganization of the documentation as well as creation of additional documentation (e.g., see [state-global-let*]). Now, most built-in functions and macros commonly used in programs (as opposed to [events] like [47m[defun][0m, for example) are subtopics of a new topic --- see [ACL2-built-ins] --- which is a subtopic of [programming], a topic that in turn has considerably fewer direct subtopics than before. It is now possible to bind extra variables in a [47m:USE[0m hint, thus avoiding the error message: ``The formula you wish to instantiate, ..., mentions only the variable(s) ...''. See [lemma-instance], in particular the discussion of keyword [47m:extra-bindings-ok[0m. Thanks to Sol Swords for requesting such an enhancement. The function [47mread-object-suppress[0m is like [47mread-object[0m except that it avoids errors and discards the value read. See [io]. A [stobj] may now be passed as an argument where another stobj is expected if the two are ``congruent''. See [defstobj], in particular, its discussion of the new [47m:congruent-to[0m keyword of [47mdefstobj[0m. Thanks to Sol Swords for requesting this enhancement and for useful discussions contributing to its design. A new top-level utility has been provided that shows the assembly language for a defined function symbol; see [disassemble$]. Thanks to Jared Davis for requesting such a utility and to Shilpi Goel for pointing out an inconvenience with the initial implementation. Note that it uses the distributed book [47mbooks/misc/disassemble.lisp[0m, which users are welcome to modify (see [community-books]). The macro [47mset-accumulated-persistence[0m is an alias for [47m[accumulated-persistence][0m. Thanks to Robert Krug for suggesting this addition. A new [documentation] topic lists lesser-known and advanced ACL2 features, intended for those with prior ACL2 experience who wish to extend their knowledge of ACL2 capabilities. See [advanced-features]. Thanks to Warren Hunt and Anna Slobodova for requesting such information. A new macro, [47m[deftheory-static][0m, provides a variant of [47m[deftheory][0m such that the resulting theory is the same at [47m[include-book][0m time as it was at [47m[certify-book][0m time. Thanks to Robert Krug for helpful discussions on this new feature and for updating his [47mbooks/arithmetic-5/[0m distributed books to use this feature. A new event, [47m[defabsstobj][0m, provides a new way to introduce single-threaded objects (see [stobj] and see [defstobj]). These so-called ``abstract [stobj]s'' permit user-provided logical definitions for primitive operations on stobjs, for example using an alist-based representation instead of a list-based representation for array fields. Moreover, the proof obligations guarantee that the recognizer is preserved; hence the implementation avoids executing the recognizer, which may be an arbitrarily complex invariant that otherwise would be an expensive part of [guard] checks. Thanks to Warren Hunt for a request leading us to design and implement this new feature, and thanks to Rob Sumners for a request leading us to implement a related utility, [47m[defabsstobj-missing-events][0m. See [defabsstobj]. Also thanks to Sol Swords for sending an example exhibiting a bug in the initial implementation, which has been fixed. A new command, [47m:psof <filename>[0m, is like [47m:pso[0m but directs proof replay output to the specified file. For large proofs, [47m:[0m[47m[psof][0m may complete much more quickly than [47m:[0m[47m[pso][0m. see [psof]. More generally, a new utility, [47m[wof][0m (an acronym for ``With Output File''), directs standard output and proofs output to a file; see [wof]. The new macro [47m[defnd][0m defines a function with [47m:[0m[47m[guard][0m [47mt[0m and [disable]s that function, in analogy to how [47m[defund][0m defines with [47m[defun][0m and then [disable]s. Thanks to Shilpi Goel for requesting this feature. The [47m:[0m[47m[pl2][0m command now shows [47m:[0m[47m[linear][0m rules; and a new [proof-builder] command, [47mshow-linears[0m (equivalently, [47msls[0m), is an analogue of the [proof-builder] [47mshow-rewrites[0m ([47msr[0m) command, but for [linear] rules. Thanks to Shilpi Goel for requesting this new proof-builder command. Finally, a corresponding new proof-builder command, [47mapply-linear[0m ([47mal[0m), is an analogue of the [proof-builder] [47mrewrite[0m ([47mr[0m) command, but for [linear] rules. The macros [47m[add-macro-fn][0m and [47m[remove-macro-fn][0m replace macros [47m[add-binop][0m and [47m[remove-binop][0m, respectively, though the latter continue to work. The new macros allow you to decide whether or not to display calls of binary macros as flat calls for right-associated arguments, e.g., [47m(append x y z)[0m rather than [47m(append x (append y z))[0m. See [add-macro-fn]. It is now possible to request that the host Lisp compiler inline calls of specified functions, or to direct that the host Lisp compiler not inline such calls. See [defun-inline] and see [defun-notinline]. We thank Jared Davis for several extensive, relevant conversations, and for finding a bug in a preliminary implementation. We also thank others who have engaged in discussions with us about inlining for ACL2; besides Jared Davis, we recall such conversations with Rob Sumners, Dave Greve, and Shilpi Goel. [31;1mHEURISTIC IMPROVEMENTS[0m Reading of ACL2 [47m[arrays][0m (see [aref1], see [aref2]) has been made more efficient (as tested with CCL as the host Lisp) in the case of consecutive repeated reads of the same named array. Thanks to Jared Davis and Sol Swords for contributing this improvement. Slightly modified the induction schemes stored, so that calls of so-called ``guard-holders'' (such as [47m[mbe][0m and [47m[prog2$][0m --- indeed, any call of [47m[return-last][0m --- and [47m[the][0m) are expanded away. In particular, calls of equality variants such as [47m[member][0m are treated as their corresponding function calls, e.g., [47m[member-equal][0m; see [equality-variants]. Guard-holders are also now expanded away before storing [constraint]s for [47m[encapsulate][0m [events], which can sometimes result in simpler constraints. Improved the performance of [47m[dmr][0m (technical note: by modifying raw Lisp code for function [47mdmr-flush[0m, replacing [47mfinish-output[0m by [47mforce-output[0m). We now avoid certain rewriting loops. A long comment about this change, including an example of a loop that no longer occurs, may be found in source function [47mexpand-permission-result[0m. Slightly strengthened [type-set] reasoning at the level of literals (i.e., top-level hypotheses and conclusions). See the comment in ACL2 source function [47mrewrite-atm[0m about the ``use of dwp = t'' for an example of a theorem provable only after this change. Strengthened the ability of [type-set] reasoning to make deductions about terms being integers or non-integer rationals. The following example illustrates the enhancement: before the change, no simplification was performed, but after the change, the conclusion simplifies to [47m(foo t)[0m. Thanks to Robert Krug for conveying the problem to us and outlining a solution. (defstub foo (x) t) (thm ; should reduce conclusion to (foo t) (implies (and (rationalp x) (rationalp y) (integerp (+ x (* 1/3 y)))) (foo (integerp (+ y (* 3 x)))))) [31;1mBUG FIXES[0m Fixed a class of soundness bugs involving each of the following functions: [47m[getenv$][0m, [47mget-wormhole-status[0m, [47m[cpu-core-count][0m, [47m[wormhole-p][0m, [47m[random$][0m, [47mfile-write-date$[0m, and [47mserialize-read-fn[0m, and (for the HONS version of ACL2) [47m[clear-memoize-table][0m and [47m[clear-memoize-tables][0m as well as (possible soundness bug) [47mserialize-write-fn[0m. For example, we were able to admit the following events, but that is no longer the case (neither for [47mgetenv$[0m as shown, nor analogously for other functions listed above). (defthm not-true (stringp (cadr (getenv$ "PWD" (build-state)))) :rule-classes nil) (defthm contradiction nil :hints (("Goal" :in-theory (disable (getenv$)) :use not-true)) :rule-classes nil) Fixed a soundness bug involving [47mwith-live-state[0m, which could cause an error in the use of [47m[add-include-book-dir][0m or [47m[delete-include-book-dir][0m in a book or its [portcullis] commands. See [with-live-state], as the documentation for this macro has been updated; in particular it is now untouchable (see [remove-untouchable]) and is intended only for system hackers. Thanks to Jared Davis for reporting a bug in the use of [47m[add-include-book-dir][0m after our first attempt at a fix. Fixed a soundness bug based on the use of [47m[skip-proofs][0m together with the little-used argument [47mk=t[0m for [47m[certify-book][0m. An example proof of [47mnil[0m appears in a comment in the ACL2 sources, in [47m(deflabel note-5-0 ...)[0m. Fixed a soundness bug that allowed users to define new [proof-builder] primitive commands. Before this fix, a book proving [47mnil[0m could be certified, as shown in a comment now in the introduction of the [table] [47mpc-command-table[0m in source file [47mproof-builder-a.lisp[0m. (Technical change, primarily related to [47m[make-event][0m:) Plugged a security hole that allowed [books]' [certificate]s to be out-of-date with respect to [47m[make-event][0m expansions, but not recognized as such. The change is to include the so-called expansion-alist in the certificate's checksum. An example appears in a comment in the ACL2 sources, in [47m(deflabel note-5-0 ...)[0m. Fixed a bug in [guard] verification due to expanding calls of primitives when translating user-level terms to internal form, so called ``translated terms'' (see [term]). While we have not observed a soundness hole due to this bug, we have not ruled it out. Before the bug fix, the following event was admissible, as guard verification succeeded (but clearly should not have). (defun f () (declare (xargs :guard t)) (car (identity 3))) For those who want details about this bug, we analyze how ACL2 generates [guard] proof obligations for this example. During that process, it evaluates ground subexpressions. Thus, [47m(identity '3)[0m is first simplified to [47m'3[0m; so a term must be built from the application of [47mcar[0m to [47m'3[0m. Guard-checking is always turned on when generating guard proof obligations, so now, ACL2 refuses to simplify [47m(car '3)[0m to [47m'nil[0m. However, before this bug fix, when ACL2 was building a term by applying [47mcar[0m to argument [47m'3[0m, it did so directly without checking guards; source code function [47mcons-term[0m is `smart' that way. After the fix, such term-building reduction is only performed when the primitive's guard is met. While calls of many event macros had been prohibited inside executable code, others should have been but were not. For example, the following was formerly allowed. (defun foo (state) (declare (xargs :mode :program :stobjs state)) (add-custom-keyword-hint :my-hint (identity nil))) (foo state) ; Caused hard raw Lisp error! Thus, several event macros (including for example [47m[add-custom-keyword-hint][0m) may no longer be called inside executable code. Fixed an assertion that could occur, for example, after reverting to prove the original goal by induction and generating a goal of [47mNIL[0m. Thanks to Jared Davis for sending us a helpful example to bring this bug to our attention. It was possible for [47m[defstobj][0m to generate raw Lisp code with excessively restrictive type declarations. This has been fixed. Thanks to Warren Hunt for reporting this bug and sending an example that illustrates it. See [stobj-example-2] for examples of such raw Lisp code; now, one finds [47m(and fixnum (integer 0 *))[0m where formerly the type was restricted to [47m(integer 0 268435455)[0m. Fixed a bug, ignoring the use of [47m:computed-hint-replacement[0m in certain cases involving a combination of computed hints and custom keyword hints. Thanks to Robert Krug for reporting this bug and sending a very helpful example. Fixed a bug in the output from [47m[defattach][0m, which was failing to list previous [events] in the message about ``bypassing constraints that have been proved when processing the event(s)''. (GCL only) Fixed a bug in [47m[set-debugger-enable][0m (which was only a bug in GCL, not an issue for other host Lisps). Fixed ACL2 trace output to indent properly for levels above 99 (up to 9999). Thanks to Warren Hunt for bringing this bug to our attention. Fixed a bug in the reporting of times in event summaries --- probably one that has been very long-standing! The times reported had often been too small in the case of compound [events], notably [47m[include-book][0m. Thanks to everyone who reported this problem (we have a record of emails from Eric Smith and Jared Davis on this issue). Fixed a bug in [47m:expand[0m [hints], where the use of [47m:lambdas[0m could prevent other parts of such a hint. For example, the following invocation of [47m[thm][0m failed before this fix was made. (defund foo (x) (cons x x)) (thm (equal (car (foo x)) x) :hints (("Goal" :expand (:lambdas (foo x))))) Certain ``program-only'' function calls will now cause hard Lisp errors. (The rather obscure reason for this fix is to support logical modeling of the ACL2 evaluator. A relevant technical discussion may be found in source function [47moneify-cltl-code[0m, at the binding of variable [47mfail_program-only-safe[0m.) There was an unnecessary restriction that [47m[flet][0m-bound functions must return all [stobj]s among their inputs. For example, the following definition was rejected because [47mstate[0m was not among the outputs of [47mh[0m. This restriction has been removed. (defun foo (state) (declare (xargs :stobjs state)) (flet ((h (state) (f-boundp-global 'x state))) (h state))) We fixed a bug, introduced in the preceding release (Version 4.3), in the check for irrelevant formals (see [irrelevant-formals]). That check had been too lenient in its handling of lambda ([let]) expressions, for example allowing the following definition to be admitted in spite of its first formal parameter obviously being irrelevant. (defun foo (x clk) (if (zp clk) :diverge (let ((clk (1- clk))) (foo x clk)))) Fixed a bug in the [47mmini-proveall[0m target in [47mGNUmakefile[0m. The fix includes a slight change to the [47m:mini-proveall[0m [command] (an extra event at the end). Thanks to Camm Maguire for reporting this bug. Fixed a bug that occurred when [47m[certify-book][0m was called after using [47m[set-fmt-soft-right-margin][0m or [47m[set-fmt-hard-right-margin][0m to set a small right margin. Fixed [47m[set-inhibit-warnings][0m so that it takes effect for a subsequent [47m[include-book][0m event. Thanks to Jared Davis and David Rager for queries that led to this fix. Hard Lisp errors are now avoided for certain [47m:[0m[47m[rewrite][0m rules: those whose [equivalence] relation is other than [47mequal[0m when the rule is originally processed, but is no longer a known equivalence relation when the rule is to be stored. Thanks to Jared Davis for sending a useful example, a minor variant of which is included in a comment in source function [47minterpret-term-as-rewrite-rule[0m (file [47mdefthm.lisp[0m). Fixed a bug in the ACL2 evaluator (source function [47mraw-ev-fncall[0m), which was unlikely to be exhibited in practice. Fixed a hard Lisp error that could occur for ill-formed [47m:[0m[47m[meta][0m [rule-classes], e.g., [47m(:meta :trigger-fns '(foo))[0m. It is now an error to include a [stobj] name in the [47m:renaming[0m alist (see [defstobj]). Some bogus warnings about non-recursive function symbols have been eliminated for rules of class [47m:[0m[47m[type-prescription][0m. (Allegro CL host Lisp only) Fixed an obsolete setting of compiler variable [47mcomp:declared-fixnums-remain-fixnums-switch[0m, which may have been responsible for intermittent (and infrequent) checksum errors encountered while including books during certification of the regression suite. Fixed a [proof-builder] bug that could result in duplicate goal names in the case of forced hypotheses. An example showing this bug, before the fix, appears in a comment in the ACL2 sources, in [47m(deflabel note-5-0 ...)[0m. We fixed a bug in a prover routine involved in [type-set] computations involving linear arithmetic. This bug has been around since at least as far back as Version_3.3 (released November, 2007). We are not aware of any resulting unsoundness, though it did have the potential to weaken the prover. For example, the following is proved now, but was not proved before the bug was fixed. (thm (implies (and (rationalp x) (rationalp y) (integerp (+ (* 1/3 y) x))) (integerp (+ y (* 3 x)))) :hints (("Goal" :in-theory (disable commutativity-of-+)))) Although all bets are off when using redefinition (see [ld-redefinition-action]), we wish to minimize negative effects of its use, especially raw Lisp errors. The examples below had caused raw Lisp errors, but no longer. (defstobj st fld :inline t) (redef!) (defstobj st new0 fld) (u) (fld st) ; previously an error, which is now fixed ; Fresh ACL2 session: (redef!) (defun foo (x) x) (defmacro foo (x) `(quote ,x)) (u) ; Fresh ACL2 session: (redef!) (defmacro foo (x) (cons 'list x)) (defun foo (x) x) Fixed a bug that could cause hard Lisp errors in an [47m[encapsulate][0m event. Thanks to Sol Swords for sending an example that exhibited this bug. Here is a simpler such example; the bug was in how it was checked whether the [guard] for a guard-verified function (here, [47mg[0m) depends on some function introduced in the [signature] of the [47m[encapsulate][0m (here, the function [47mf[0m). (encapsulate ((f (x) t)) (local (defun f (x) (declare (xargs :guard t)) x)) (defun g (x) (declare (xargs :guard (if (integerp x) (f x) t))) x)) Fixed a bug in [47mmfc-relieve-hyp[0m that we believe could prohibit its use on the last hypothesis. Thanks to Sol Swords for reporting this bug and providing a fix. The syntax [47m#![0m (see [sharp-bang-reader]) was broken after a skipped readtime conditional. For example, the following input line caused an error. #+skip #!acl2(quote 3) This bug has been fixed. Fixed a bug in the [break-rewrite] utility, which was evidenced by error messages that could occur when dealing with free variables. An example of such an error message is the following; we thank Robert Krug for sending us an example that produced this error and enabled us to produce a fix. HARD ACL2 ERROR in TILDE-@-FAILURE-REASON-PHRASE1: Unrecognized failure reason, ((MEM-ARRAY . X86) (ADDR QUOTE 9)). We fixed an obscure bug that we believe could interfere with [47m[defproxy][0m because of an incorrect [47m(declaim (notinline <function>))[0m form. [31;1mCHANGES AT THE SYSTEM LEVEL AND TO DISTRIBUTED BOOKS[0m Improvements have been made related to the reading of characters. In particular, checks are now done for ASCII encoding and for the expected [47m[char-code][0m values for [47mSpace[0m, [47mTab[0m, [47mNewline[0m, [47mPage[0m, and [47mRubout[0m. Also, an error no longer occurs with certain uses of non-standard characters. For example, it had caused an error to certify a book after a single [portcullis] [command] of [47m(make-event `(defconst *my-null* ,(code-char 0)))[0m; but this is no longer an issue. Thanks to Jared Davis for helpful correspondence that led us to make these improvements. The character encoding for reading from files has been fixed at ISO-8859-1. See [character-encoding]. Thanks to Jared Davis for bringing this portability issue to our attention (as this change arose in order to deal with a change in the default character encoding for the host Lisp, CCL), and pointing us in the right direction for dealing with it. In many cases, the character encoding for reading from the terminal is also ISO-8859-1; but this is not guaranteed. In particular, when the host Lisp is SBCL this may not be the case. Although the HTML documentation is distributed with ACL2, it had not been possible for users to build that documentation without omitting graphics, for example on the ACL2 home page. That has been fixed, as files [47mgraphics/*.gif[0m are now distributed. Compiler warnings are suppressed more completely than they had been before. For example, the following had produced a compiler warning when the host Lisp is CCL, but no longer does so. (defun f () (car 3)) (trace$ f) Removed support for ``tainted'' [certificate]s. One reason is that there are rarely incremental releases. A stronger reason is that for the compatibility of a new release is with the previous non-incremental release, it's not particularly relevant whether or not the new release is incremental. The `make' variable [47mBOOKS[0m can now be defined above the line that includes Makefile-generic. (For relevant background, see [books-certification-classic].) (SBCL only) ACL2 images built on SBCL now have an option, [47m--dynamic-space-size 2000[0m, that can avoid space problems that could previously have caused the session to die. The default value for variable [47mLISP[0m in file [47mGNUmakefile[0m is now [47mccl[0m. Thus, if you use `make' in the standard way to build an ACL2 executable, the default host Lisp is [47mccl[0m rather than [47mgcl[0m. [31;1mEMACS SUPPORT[0m [31;1mEXPERIMENTAL VERSIONS[0m For the version supporting the reals, ACL2(r) (see [real]), the supporting function [47mfloor1[0m has been defined in raw Lisp. This avoids an error such as in the following case. (defun f () (declare (xargs :guard t)) (floor1 8/3)) (f) ; had caused raw Lisp error, before the fix Among the enhancements for the parallel version, ACL2(p) (see [parallelism]), are the following. We thank David Rager for his work in developing ACL2(p) and these improvements in particular. The macro [47mset-parallel-evaluation[0m has been renamed [47m[set-parallel-execution][0m. Calls of the macro [47m[set-waterfall-printing][0m are no longer [events], so may not be placed at the top level of [books]. However, it is easy to create events that have these effects; see [set-waterfall-printing]. Note that now, [47m:[0m[47m[ubt][0m and similar commands do not change the settings for either waterfall-parallelism or waterfall-printing. The implementation of [47m[deflock][0m has been improved. Now, the macro it defines can provide a lock when invoked inside a [guard]-verified or [47m:[0m[47m[program][0m mode function. Previously, this was only the case if the function definition was loaded from raw Lisp, typically via a compiled file. The underlying implementation for waterfall parallelism (see [set-waterfall-parallelism]) has been improved. As a result, even the largest proofs in the regression suite can be run efficiently in [47m:resource-based[0m waterfall parallelism mode. Among these improvements is one that can prevent machines from rebooting because operating system limits have been exceeded; thanks to Robert Krug for bringing this issue to our attention. There is also a new flag for configuring the way waterfall parallelism behaves once underlying system resource limits are reached. This flag is most relevant to [47m:full[0m waterfall parallelism. see [set-total-parallelism-work-limit] for more information. The [47m[dmr][0m utility has the same behavior in ACL2(p) as it has in ACL2 unless waterfall-parallelism has been set to a non-[47mnil[0m value (see [set-waterfall-parallelism]), in which case statistics about parallel execution are printed instead of the usual information. The user can now build the regression suite using waterfall [parallelism]. See the distributed file [47macl2-customization-files/README[0m for details, and see [unsupported-waterfall-parallelism-features] for a disclaimer related to building the regression suite using waterfall parallelism. When building ACL2 with both the hons and parallelism extensions (what is called ``ACL2(p)'' or, equivalently, ``ACL2(hp)''), the functions that are automatically memoized by the hons extension are now automatically unmemoized and memoized when the user toggles waterfall parallelism on and off, respectively. Calling [47m[set-waterfall-parallelism][0m with a flag of [47mt[0m now results in the same settings as if it were called with a flag of [47m:resource-based[0m, which is now the recommended mode for waterfall parallelism. Thanks to Shilpi Goel for requesting this feature. The prover now aborts in a timely way in response to interrupts issued during a proof with waterfall parallelism enabled. (This had often not been the case.) Thanks to Shilpi Goel for requesting this improvement. Among the enhancements for the HONS extension (see [hons-and-memoization]) are the following. The compact-print code has been replaced by new serialization routines contributed by Jared Davis. This may improve performance when including books that contain [47m[make-event][0ms that expand to very large constants. You can also now save objects to disk without going into raw lisp; see [serialize] for details. Printing of certain messages has been sped up (by using Lisp function [47mforce-output[0m in place of [47mfinish-output[0m). Thanks to Jared Davis for contributing this improvement. [Stobj] array writes are perhaps twice as fast. It is now permitted to [memoize] functions that take user-defined [stobj]s as inputs, provided that no [stobj]s are returned. Even if stobjs are returned, memoization is permitted provided the condition is [47mnil[0m, as when profiling (see [profile]). Thanks to Sol Swords for an observation that led to this improvement and for useful conversations, including follow-up leading us to improve our initial implementation. Fixes have been made for memoizing with a non-[47mnil[0m value of [47m:ideal-okp[0m. Errors had occurred when memoizing with a [47m:condition[0m other than [47mt[0m for a [47m:[0m[47m[logic][0m mode function that had not been [guard]-verified, even with a non-[47mnil[0m value of [47m:ideal-okp[0m; and after successfully memoizing such a function (without such [47m:condition[0m), it had not been possible to [47m[unmemoize][0m it. Thanks to Sol Swords for reporting issues with the [47m:ideal-okp[0m argument of [47m[memoize][0m. If a book defined a function that was subsequently [memoize]d in that book, the function would no longer behaves as memoized upon completion of book certification (unless that [47m[certify-book][0m command was undone and replaced by evaluation of a corresponding [47m[include-book][0m command). This has been fixed. Thanks to David Rager for pointing out the problem by sending an example. We now support ACL2(h) built not only on 64-bit CCL but also on all supported host Ansi Common Lisps (i.e., all supported host Lisps except GCL). Thanks to Jared Davis for doing much of the work to make this improvement. Note that performance will likely be best for 64-bit CCL; for some Lisps, performance may be much worse, probably depending in part on the underlying implementation of hash tables.") (note-6-0 (release-notes) "ACL2 Version 6.0 (December, 2012) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 5.0 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. NOTE. But we start with one major change that is outside the usual categories: [31;1mLICENSE change[0m The ACL2 license has been changed from GPL Version 2 to a 3-clause BSD license, found in the [47mLICENSE[0m file distributed with ACL2. [31;1mCHANGES TO EXISTING FEATURES[0m Function [47m[fmt-to-string][0m and similar functions (see [printing-to-strings]) now use the default right margin settings; formerly the right margin had been set at 10,000. If you want the former behavior, you can use the [47m:fmt-control-alist[0m, as illustrated below. (fmt-to-string "~x0" (list (cons #\0 (make-list 30))) :fmt-control-alist `((fmt-soft-right-margin . 10000) (fmt-hard-right-margin . 10000))) The use of attachments (see [defattach]) has been made more efficient, avoiding some low-level checks (Common Lisp `[47mboundp[0m' checks). Thanks to Shilpi Goel for constructing an example that we used to help direct us to remove inefficiency. The following results for that example --- a Fibonacci program run on a machine interpreter in raw-mode (see [set-raw-mode]) --- give a sense of the potential speedup, though we note that a full ACL2(h) regression showed no significant speedup. ; Time before the change: ; 0.89 seconds realtime, 0.90 seconds runtime ; Time after the change: ; 0.75 seconds realtime, 0.75 seconds runtime ; Time when cheating to avoid the cost of attachments, by redefining a ; function to BE its attachment (so, this gives a lower bound on possible ; execution time): ; 0.72 seconds realtime, 0.72 seconds runtime Functions [47mread-acl2-oracle[0m and [47mread-acl2-oracle@par[0m are no longer untouchable (see [remove-untouchable]). We reported this change for Version_5.0 but it was not made; thanks to Jared Davis for bringing this to our attention. Function [47mget-timer[0m also is no longer untouchable. The function [47m[butlast][0m now behaves more reasonably on arguments violating its [guard]. For example, [47m(butlast '(1 2 3) -1)[0m is now provably equal to [47m(1 2 3)[0m instead of to [47m(1 2 3 nil)[0m. Thanks to Jared Davis for suggesting a change to the definition of [47mbutlast[0m. The utilities [47mmfc-ts[0m and [47mmfc-ap[0m (see [extended-metafunctions]) formerly never used forcing (see [force]). Now, by default, forcing is allowed during execution of these functions if and only if it is permitted in the rewriting environment where they are called. Moreover, these and the [47mmfc-xx[0m utilities --- [47mmfc-rw[0m, [47mmfc-rw+[0m, and [47mmfc-relieve-hyp[0m --- are now macros that take (optional) keyword arguments [47m:forcep[0m and [47m:ttreep[0m. The [47m:forcep[0m argument is [47m:same[0m by default, providing the forcing behavior inherited from the environment (as described above); but it can be the symbol [47mt[0m or [47mnil[0m, indicating that forcing is to be enabled or disabled, respectively. The [47m:ttree[0m argument is [47mnil[0m by default, but when it is [47mt[0m, then a second value is returned, which is a tag-tree. See [extended-metafunctions]. Many improvements have been made to the tau-system (see [tau-system]), including support for arithmetic intervals bounded by constants. Thus, for example, [47m(and (<= 0 x) (<= x 15))[0m is a tau predicate. The [documentation] has also been improved (see [introduction-to-the-tau-system]). Also see [time-tracker-tau] for discussion of how the new [47m[time-tracker][0m utility can help discover ways to detect slowdown related to the tau-system. The [47m[defthm][0m [events] printed by [47m[defabsstobj][0m, namely those that remain to be proved, are now given with [47m:rule-classes nil[0m since there is probably no intention to use them as rules. Thanks to Robert Krug for suggesting that we consider this change. The formal parameters for a macro definition (see [defmacro]) may now include [47m[state][0m and user-defined [47m[stobj][0ms. (However, macro formals may not be declared as stobjs; see [xargs].) Thanks to Jose Luis Ruiz-Reina for raising this issue and to Rob Sumners for helpful conversations --- both of these nearly 10 years ago! The utilities [47m[defun-inline][0m, [47m[defun-notinline][0m, [47m[defund-inline][0m, and [47m[defund-notinline][0m have been simplified, by taking advantage of the lifting of restrictions on formal parameters of macro definitions mentioned above (involving symbols that happen to be [stobj] names). Now, when any of the above four utilities is called with a given set of formal parameters, those formals will be used not only for the generated [47m[defun][0m event but also for the generated [47m[defmacro][0m event. (Previously, they had been renamed for the [47m[defmacro][0m event in order to respect the stobj name restriction that no longer exists.) Thanks to Jared Davis for pointing out the value of making this change. The [events] [47m[add-invisible-fns][0m and [47m[remove-invisible-fns][0m now convert arguments as appropriate using the [47m[macro-aliases-table][0m. For example, the event [47m(add-invisible-fns append car)[0m is now legal (though probably not a good idea), because [47madd-invisible-fns[0m is now sensitive to the fact that [47m[append][0m maps to [47m[binary-append][0m in the [47m[macro-aliases-table][0m. When [47m:[0m[47mpe[0m is applied to a built-in function that does not have a defining event, such as [47m[symbolp][0m, [47m:pe[0m now gives more useful output that points to the documentation instead of printing a call of [47mENTER-BOOT-STRAP-MODE[0m. Thanks to Anthony Knape for bringing this issue to our attention. The macros [47m[memoize][0m and [47m[unmemoize][0m now cause a warning rather than an error in ACL2 (and work as before in ACL2(h)). Terms are now parsed into [47m:[0m[47m[type-prescription][0m rules in a manner that removes [47m[let][0m bindings both at the top level and in the conclusion (but still not in the hypotheses of the rule). See [type-prescription]. Thanks to Jared Davis for requesting such an enhancement. Printing of numbers is now appropriately sensitive to the print radix; see [set-print-radix]. Thanks to Shilpi Goel for requesting this enhancement. The system function [47mexplode-atom[0m no longer includes the radix indicator. The new function [47mexplode-atom+[0m may be used for that purpose. [31;1mNEW FEATURES[0m Among the new features for system hackers are analogues of system function [47msimple-translate-and-eval[0m that do not return [47m[state][0m. (Thanks to David Rager for requesting this feature and helpful conversations on its implementation.) This and other low-level changes are typically documented in comments in the corresponding release note event, which in this case is [47m(deflabel note-6-0 ...)[0m. More built-in functions are now [guard]-verified (and in [47m:[0m[47m[logic][0m mode). Furthermore, a mechanism exists for marking yet more built-in functions as guard-verified based on [books] contributed by users; see Part II of {http://www.cs.utexas.edu/users/moore/acl2/open-architecture/ | http://www.cs.utexas.edu/users/moore/acl2/open-architecture/}. The current state of that enterprise may be viewed by evaluating the constant [47m*system-verify-guards-alist*[0m, which associates a community book name with a list of functions. When ACL2 is built in the normal way, each of those functions is marked as guard-verified when ACL2 is started up; but a special developer build can be used to check that the indicated book, together with its sub-books, proves that those functions are guard-verified. Metatheorems (see [meta]) may now have additional hypotheses, called ``meta-extract hypotheses'', that allow metafunctions to depend on the validity of certain terms extracted from the context or the logical [world]. See [meta-extract]. Thanks to Sol Swords for providing an initial implementation, together with very helpful discussions as well as a community book, [47mbooks/clause-processors/meta-extract-user.lisp[0m, that extends the power of meta-extract hypotheses. New utilities [47moracle-funcall[0m, [47moracle-apply[0m, and [47moracle-apply-raw[0m call a function argument on specified arguments. Thanks to Jared Davis for requesting this utility. A new utility makes it convenient to track time spent inside specified function calls or, more generally, during specified evaluation. See [time-tracker]. New runic designators make it easy to refer to macro names when building theories. Thus, for example, the object [47m(:i append)[0m may be used in theory expressions to designate the [rune] [47m(:induction binary-append)[0m. See [theories]. Thanks to Jared Davis for a useful discussion leading to this enhancement. [47m[Defabsstobj][0m [events] now take an optional [47m:congruent-to[0m keyword argument, much like [47m[defstobj][0m. Thanks to Sol Swords for requesting this feature and for suggesting a very nice optimization that avoids the need to prove additional lemmas. [47m[Flet][0m may now include [47minline[0m and [47mnotinline[0m declarations. Thanks to Jared Davis for requesting this feature. The utility [47mgc-verbose[0m controls printing of messages by the garbage collector, for certain host Lisps. See [gc-verbose]. Thanks to Shilpi Goel for requesting this utility. Added definitions of functions [47m[nat-listp][0m and [47m[ACL2-number-listp][0m. Thanks to Harsh Raju Chamarthi for requesting these additions. Many community books had varying definitions of these functions; these additions guarantee that all books must agree on how these two functions are defined. (Some community books have been changed in order that they remain certifiable, given these additions.) Note that a few built-in [47m:[0m[47m[forward-chaining][0m rules were modified in order to accommodate these additions, and the definition of [47m[integer-listp][0m was modified to call [47m[eq][0m instead of [47m[equal][0m, like the other such definitions. See [get-command-sequence] for a new utility that returns a list of [command]s between two given command descriptors. [31;1mHEURISTIC IMPROVEMENTS[0m We obtained a substantial speedup --- 13% observed for the regression suite, and 8% observed for the ACL2(h) regression suite --- by tweaking the [break-rewrite] implementation to eliminate virtually all of its overhead when it is not in use (the default, which holds until [47m:[0m[47m[brr][0m[47m t[0m is evaluated). Thanks to David Rager for a conversation involving ACL2(p) performance statistics that suggested looking at changing [break-rewrite] to boost performance. The heuristics for automatically expanding recursive function calls have been changed during proofs by induction. Now, during induction, more terms that suggested the induction scheme are automatically expanded. Thanks to David Rager for providing an example and having discussions with us that spurred us to develop this heuristic improvement. [31;1mBUG FIXES[0m Fixed a soundness bug in [47m[defabsstobj][0m based on [47m[guard][0ms that violated single-threadedness restrictions. Thanks to Sol Swords for bringing this bug to our attention and supplying a proof of [47mnil[0m, which we include as a comment in source file [47mld.lisp[0m, in [47m(deflabel note-6-0 ...)[0m. We also thank Sol for helpful discussions about [guard]s of functions introduced by [47mdefabsstobj[0m, which has led us to enhance the [documentation]; see [defabsstobj]. Fixed a soundness bug in [47m[defabsstobj][0m based on interrupted updates of abstract stobjs. As part of the fix a new keyword, [47m:PROTECT[0m, has been introduced for [47mdefabsstobj[0m exports, along with a new top-level [47mdefabsstobj[0m keyword, [47m:PROTECT-DEFAULT[0m; see [defabsstobj]. We do some analysis that we expect will avoid the use of [47m:PROTECT[0m in many cases, which is fortunate since the use of [47m:PROTECT t[0m may cause a slight slowdown in (abstract) stobj updates. Thanks to Sol Swords for bringing this bug to our attention and supplying a proof of [47mnil[0m, which we include as a comment in source file [47mother-events.lisp[0m, in the definition of function [47mset-absstobj-debug[0m. Fixed a raw Lisp error that occurred when tracing a [3mstobj[0m resize function, thanks to an error report from Warren Hunt, Marijn Heule, and Nathan Wetzler. Fixed a raw Lisp error that occurred for certain ill-formed signatures, as in the following example. ACL2 !>(encapsulate (((f (*) => * :guard t))) (local (defun f (x) (consp x)))) *********************************************** ************ ABORTING from raw Lisp *********** Error: value (F (*) => * :GUARD T) is not of the expected type SYMBOL. *********************************************** The notion of ``error triple'' (see [error-triple]) had been implemented ambiguously, with the result that for a [stobj], [47mst[0m, the result of evaluating the following two forms was the same: [47m(mv nil st state)[0m and [47m(mv t st state)[0m. Of course, these are just examples; in general, a result of [47m(mv erp val state)[0m was sometimes treated as an error triple even when [47mval[0m is a [stobj]. Now, [47m(mv erp val state)[0m is an error triple only when [47merp[0m and [47mval[0m are ordinary (non-[stobj]) values. Thanks to Warren Hunt and Marijn Heule for bringing this problem to our attention. The ``with-error-trace'' utility, [47m[wet][0m, now works in the non-error case when given a form that returns multiple values. (Note however that [47m[state][0m will be printed as [47mREPLACED-STATE[0m; and similarly, a user-defined [stobj], say [47mST[0m, will be printed as [47mREPLACED-ST[0m.) Some possible error messages for [47m[defabsstobj][0m have been fixed that had been ill-formed. Thanks to Sol Swords for bringing this bug to our attention. Fixed a bug that sometimes caused the times displayed in the summary for [47m[certify-book][0m to be smaller than the actual times. Fixed a bug in the [guard]s to system functions [47mfmt-char[0m and [47mfmt-var[0m, which are no longer [47m:[0m[47m[logic][0m-mode, guard-verified functions. (GCL only) Fixed a bug present in Gnu Common Lisp for [47m#u[0m (see [sharp-u-reader]). [31;1mCHANGES AT THE SYSTEM LEVEL[0m The [state] global variable [47m'distributed-books-dir[0m has been renamed [47m'system-books-dir[0m. On a related note, the [documentation] now refers to ``community books'' rather than ``distributed books'', and there is a corresponding new documentation topic; see [community-books]. Fixed a bug in the implementation of [47m[wet][0m (which is actually in the community book [47mbooks/misc/wet.lisp[0m). A directory, [47minterface/[0m, is no longer part of the ACL2 distribution. Rather, it is a subdirectory of the ACL2 community books. Thus, if you fetch those books in the usual way (see the installation instructions on the ACL2 home page), you will find a directory [47mbooks/interface/[0m. Subdirectory [47memacs/[0m of that [47minterface[0m directory provides Emacs support for [proof-tree]s as well an [47macl2-mode[0m. This change has been reflected in ACL2 file [47memacs/emacs-acl2.el[0m, so users will probably not be impacted if they load that file into Emacs. The community books file [47mbooks/Makefile-generic[0m now causes, by default, a backtrace to be printed when there is a raw Lisp error. Some changes have been made to how regressions are run, i.e., to how the community books are certified. (1) The standard regression now includes community books directory [47mbooks/centaur[0m. To skip these (for example, a Windows system has encountered difficulty with them even after installing Perl), include [47mACL2_CENTAUR=skip[0m with your `make' command. (2) A new `make' (or environment) variable, [47mACL2_JOBS[0m, specifies the number of parallel jobs to run, serving as a replacement for the [47m-j[0m argument of `make' that works for all community books, including those under directory [47mcentaur[0m; see [books-certification-classic]. (3) It is no longer necessary to do an ACL2(h) regression in order to build a copy of the documentation generated by Jared Davis's xdoc utility at [47mbooks/xdoc-impl/manual/preview.html[0m; a vanilla ACL2 regression will build this manual. (4) It is no longer necessary to set the [47mACL2[0m environment variable for ACL2(h) regressions if you want to use the executable [47msaved_acl2h[0m in the ACL2 sources directory. The ACL2 home page now has a search utility for documentation and books. Thanks to Shilpi Goel and David Rager for feedback on a preliminary version of this utility. (only for SBCL with 64-bit ACL2(h)) The value of SBCL command line option [47m--dynamic-space-size[0m for ACL2(h) on 64-bit platforms has been increased from 2000 to 16000 (as explained in a comment in the ACL2 source definition of [47m*sbcl-dynamic-space-size*[0m). [31;1mEMACS SUPPORT[0m [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m Among the enhancements for ACL2(r) (see [real]) are the following. Thanks to Ruben Gamboa for his helpful role in making the following improvements made with Ruben Gamboa in support for non-standard analysis in ACL2(r). Constrained functions can now be introduce as non-classical. See [signature]. [47m[Defun-sk][0m now takes a new keyword argument, [47m:CLASSICALP[0m, that determines whether or not the named function is classical. See [defun-sk]. Incorporated a bug fix from Ruben Gamboa for [47m[ceiling][0m. The default (for `bad' arguments) had been 1, but now we follow normal ACL2 practice by returning 0 in that case. Among the enhancements for the HONS extension (see [hons-and-memoization]) are the following. Macros [47m[with-fast-alist][0m, [47m[with-stolen-alist][0m, and [47m[fast-alist-free-on-exit][0m are now defined in ACL2(h), rather than being defined in the community book [47m"books/centaur/misc/hons-extra.lisp"[0m. Thanks to Jared Davis and Sol Swords for donating this code, and thanks to Jared for helpful discussions leading to this change. Among the enhancements for ACL2(p) (see [parallelism]) are the following. We thank David Rager for his work in developing ACL2(p) and for his helpful role in these improvements. A bug has been fixed that could leave one in a [wormhole], awaiting input, after an error, such as an error in an [47m:in-theory[0m hint during a proof. Thanks to Shilpi Goel for bringing this bug to our attention. A key checkpoint for a given goal is now printed only once. Previously, if a key checkpoint led to more than one goal pushed for proof by induction, the key checkpoint would be printed once for each such goal during the proof, and also once for each such goal in the summary at the end.") (note-6-1 (release-notes) "ACL2 Version 6.1 (February, 2013) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 6.0 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m More system functions are in [47m:[0m[47m[logic][0m mode, [guard]-verified. Evaluate (strip-cars (cdr (assoc-equal "system/top" *system-verify-guards-alist*))) for the list of functions checked to be guard-verifiable in the community books. (NOTE added after Version_8.3: The form is now [47m(strip-cars *system-verify-guards-alist*)[0m.) Thanks to those who have contributed to this effort, as shown in file headers in directory [47msystem/[0m of the community books. The macro [47m[defund][0m now avoids an error when [47m:mode :program[0m has been specified in an [47m[xargs][0m form of a [47m[declare][0m form, for example: [47m(defund f (x) (declare (xargs :mode :program)) x)[0m. It does this by avoiding the generation of [47m[in-theory][0m [events] in such cases. Thanks to David Rager and Jared Davis for requesting such a change, and for ensuing helpful discussions. Added a field [47m:UNIFY-SUBST[0m to metafunction contexts (see [extended-metafunctions]), accessed with function [47mmfc-unify-subst[0m. Thanks to Sol Swords for requesting this enhancement. The functions [47m[sys-call][0m and [47m[sys-call-status][0m are now [guard]-verified [47m:[0m[47m[logic][0m-mode functions. It had been the case that if any supporter of a dependent clause processor (see [define-trusted-clause-processor]) is among the ancestors of a given formula, then it was illegal to apply functional instantiation (see [lemma-instance]) to that formula. Now, this is illegal only if some such supporter is in the domain of the functional substitution. The tau system (see [tau-system], or if you are unfamiliar with the tau system, see [introduction-to-the-tau-system]) now allows the user to define and verify functions that compute bounds on arithmetic expressions. See [bounders]. The utility [47mprint-summary-user[0m has been replaced by [47m[finalize-event-user][0m, which is described below. If you previously attached a function to [47mprint-summary-user[0m, say [47mmy-print-summary-user[0m, then you can get the effect you had previously as follows. (defun my-finalize-event-user (state) (declare (xargs :mode :logic :stobjs state)) (prog2$ (my-print-summary-user state) state)) (defattach finalize-event-user my-finalize-event-user) It had been the case that when you [47m[ld][0m a file, the connected book directory (see [cbd]) was set to the canonical pathname of that file's directory for the duration of the [47mLD[0m call. This could cause problems, however, if the file is actually a soft link: an [47m[include-book][0m form in the book with a relative pathname for the book would be resolved with respect to the absolute pathname for that link, which is probably not what was intended. So soft links are no longer followed when computing the above connected book directory. The following example, which is how we discovered this problem, may clarify. We attempted to execute the form [47m(ld "top.lisp")[0m using ACL2(r) (see [real]) in community books directory [47mnonstd/arithmetic/[0m, where all of the [47m.lisp[0m files are soft links to files in [47marithmetic/[0m. Thus, the form [47m(include-book "equalities")[0m attempted to include [47marithmetic/equalities[0m instead of [47mnonstd/arithmetic/equalities[0m, which caused an error. We no longer document the use of value [47m:START[0m for [47m[with-prover-step-limit][0m. This value has always been used by the ACL2 implementation and may have semantics that change with new ACL2 versions. If you have reason to use this value, please contact the ACL2 implementors. [31;1mNEW FEATURES[0m By default, the prover now gives information about case splits. See [splitter]. Thanks to many ACL2 users, most recently David Rager, for requesting such a capability. Also thanks to David Rager and Jared Davis for helpful discussions, and thanks to Robert Krug for feedback on the initial implementation and documentation that led us to make improvements. New utilities [47m[initialize-event-user][0m and [47m[finalize-event-user][0m allow the user to run [state]-modifying code at the start and end of [events]. Thanks to Harsh Raju Chamarthi for requesting these capabilities. Note that [47m[finalize-event-user][0m replaces [47mprint-summary-user[0m. [31;1mHEURISTIC IMPROVEMENTS[0m Several heuristic improvements have been made to the tau system, even if you do not explicitly use the new capability for computing bounds on arithmetic expressions, mentioned above. See [tau-system], or if you are unfamiliar with the tau system, see [introduction-to-the-tau-system]. [31;1mBUG FIXES[0m A soundness bug has been fixed that exploited the use of expansion files (see [book-compiled-file]) together with [47m[defstobj][0m. For an example illustrating this bug, see the comment about ``Expansion/Defstobj Bug'' in the form [47m(deflabel note-6-1 ...)[0m in ACL2 source file [47mld.lisp[0m. We fixed a soundness bug involving system function [47m[canonical-pathname][0m and (most likely) other functions in the former value of constant [47m*unattachable-primitives*[0m. Thanks to Jared Davis and Sol Swords for bringing this bug to our attention by way of an example. We include a very slight variant of that example in a comment within the form [47m(deflabel note-6-1 ...)[0m in ACL2 source file [47mld.lisp[0m. There was a soundness bug that allowed attachments to prove [47mnil[0m in a consistent logical [world] involving [47m[defaxiom][0m [events]. This has been fixed, by requiring that no function symbol ancestral in a [47m[defaxiom][0m formula is allowed to get an attachment. See [defattach], in particular discussion of ``a restriction based on a notion of a function symbol syntactically supporting an event'', which concludes with a proof of [47mnil[0m that is no longer possible. (ACL2(h) only) We fixed a soundness bug in the interaction of memoization with congruent stobjs, in cases where the [47m:congruent-to[0m field of [47m[defstobj][0m was not the canonical representative in the congruence class. For an example illustrating this bug, see the comment about ``memoize/congruent stobj bug'' in the form [47m(deflabel note-6-1 ...)[0m in ACL2 source file [47mld.lisp[0m. Functions defined by [47m[defstobj][0m had failed to be compiled when certifying books, except in host Lisps that compile on-the-fly (CCL, SBCL). This has been fixed for all host Lisps. A related change, probably less significant, was made for [47m[defabsstobj][0m. Thanks to Sol Swords for reporting bugs that turned out to be mistakes in a preliminary implementation of this change. Fixed an assertion error involving linear arithmetic. Thanks to Sol Swords for sending an example illustrating the bug (now appearing as a comment in ACL2 source function [47mlinearize1[0m). Fixed a bug that was breaking the ACL2s build mechanism (see [ACL2-sedan]) by causing certain needless evaluation of ``hidden [47m[defpkg][0m'' forms in [certificate] files when executing a call of [47m[include-book][0m. The bug could also affect rare error messages arising from ill-formed [certificate] files. Thanks to Harsh Raju Chamarthi for bringing this bug to our attention by sending us an example script of the sort that was breaking during an ACL2s build. Fixed handling of pathnames by some low-level code (system function [47mour-truename[0m) that could cause errors, for example for host-Lisp GCL on some platforms when environment variable [47mHOME[0m points to a non-existent directory. Thanks to Camm Maguire for bringing this issue to our attention and helping with the debugging. Fixed a coding bug in generation of stobj resizing functions for a stobj named [47mOLD[0m. The following example illustrates the bug. (defstobj old (fld :type (array (unsigned-byte 31) (8)) :initially 0 :resizable t)) (resize-fld 10 old) ; The following returned 8 but should have returned 10: (fld-length old) Fixed a bug in [47m[defabsstobj-missing-events][0m (which macroexpanded incorrectly). Thanks to Sol Swords for bringing this bug to our attention. Fixed two bugs in the handling of step-limits. Thanks to Hanbing Liu for bringing the main such bug to our attention, which was that ACL2 could report a step-limit violation during [47m[certify-book][0m (in fact, during any compound event such as a call of [47m[encapsulate][0m or [47m[progn][0m), even without direct user involvement in managing step-limits (see [set-prover-step-limit] and see [with-prover-step-limit]). The other bug was that a bad argument to [47m[set-prover-step-limit][0m could result in a raw Lisp error, for example: [47m(progn (set-prover-step-limit '(a b)))[0m. [31;1mCHANGES AT THE SYSTEM LEVEL[0m The [47mbooks/[0m directory no longer needs to exist in order to build an ACL2 executable. Thanks to Robert Krug for pointing out that the installation instructions had suggested that this was already the case. Many changes have been made to the [community-books]. For example, some community books now include [47mstd/lists/rev.lisp[0m, which contains the rule [47mrevappend-removal[0m, which may cause some proofs involving [47m[revappend][0m to fail where they formerly succeeded, or vice-versa. When a proof fails that formerly succeeded, it may be useful for you to look over the [rune]s printed in the event summary. [31;1mEMACS SUPPORT[0m [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m For ACL2(p), [47m[wormhole-eval][0m is now locked by default; thanks to David Rager for suggesting this change. But there is a way to avoid the lock; see [wormhole-eval]. In particular, the lock is avoided in the implementations of [accumulated-persistence] and [forward-chaining-reports], which are not supported in ACL2(p) (see [unsupported-waterfall-parallelism-features]).") (note-6-2 (release-notes) "ACL2 Version 6.2 (June, 2013) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 6.1 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m The macro [47m[top-level][0m has been changed, so that evaluation of a form [47m(top-level x)[0m results in an error when evaluation of [47mx[0m results in an error. Thanks to Jared Davis for observing that when evaluating a file using [47m[ld][0m, an interrupt of a call of a [47m[top-level][0m call in that file would not prevent evaluation of later forms in the file. The macro [47m[the][0m no longer causes an error when [guard]-checking is [47m:NONE[0m. For example, it had been the case that evaluation of [47m(the integer t)[0m always caused an error; but now, there is no error after executing command [47m:[0m[47m[set-guard-checking][0m[47m :NONE[0m. Thanks to Jared Davis for asking for a way to avoid such errors. The error printed when attempting to ``reincarnate'' a package --- that is, to define a package that is not part of the ACL2 logical [world] but exists in raw Lisp because it was once part of the world --- is now much more instructive. In particular, it shows pathnames for the previous and proposed [47m[defpkg][0m events, and it shows the symbols that are imported by one but not the other. Thanks to Jared Davis for requesting this improvement. Functions [47m[open-input-channel][0m and [47m[open-output-channel][0m no longer cause an error when failing to open a channel because of a permissions problem, but instead return [47m(mv nil state)[0m. Thanks to Jared Davis for requesting this change. (Note: this change does not apply if the host Lisp is non-ANSI, i.e., if the host Lisp is non-ANSI GCL.) The advanced [meta-extract] mechanisms, provided for using facts from the [world] or metafunction context, have been enhanced in the following ways, in collaboration with Sol Swords. See [meta-extract] for more details. It is now permissible to use calls of [47mmeta-extract-global-fact[0m in hypotheses of [47m[clause-processor][0m rules, much as they are used in hypotheses of [47m[meta][0m rules. See [meta-extract]. Thanks to Sol Swords for requesting this feature. The utility [47mmeta-extract-global-fact[0m is now a macro, which expands to a corresponding call of the new function, [47mmeta-extract-global-fact+[0m. This new function takes an alternate, extra [state] as an argument; it is not to be executed, and it operates on the alternate state, whose logical [world] is intended to be the same as that of the ``live'' (usual) state. A new sort of value for the [47mobj[0m argument is supported for [47mmeta-extract-global-fact[0m (and [47mmeta-extract-global-fact+[0m), which results in a term equating a function application to its result. See [meta-extract], in particular the discussion of [47m:fncall[0m. It is now possible for [47mtrace$[0m to avoid printing prefixes of the form [47m"n> "[0m and [47m"<n "[0m, while also (optionally) avoiding indentation. See [trace$], in particular the discussion of [47m:fmt![0m. Thanks to Shilpi Goel for requesting this feature. It was possible for the [guard-debug] feature to generate duplicate calls of [47mextra-info[0m in hypotheses generated for guard verification. We have eliminated duplicates of this sort. When [47m[in-theory][0m returns without error, it returns a value [47m(:NUMBER-OF-ENABLED-RUNES k)[0m, where [47mk[0m is the length of the new current theory. (Formerly, [47mk[0m was returned.) This value is thus printed when an [47min-theory[0m event is submitted at the top level. Thanks to Gisela Rossi for feedback that led us to make this change. A new keyword parameter for [47m[ld][0m is [47m:ld-missing-input-ok[0m. Its default value is [47mnil[0m, which causes an error, as before, upon failure to open a specified file. Other legal values are [47mt[0m and [47m:WARN[0m; see [ld-missing-input-ok] and see [ld]. Extended [47m*acl2-exports*[0m, in particular adding [47mUNSIGNED-BYTE-P[0m and [47mSIGNED-BYTE-P[0m (thanks to a suggestion by Jared Davis) Even if the function [47mf[0m is defined to take one or more [stobj] arguments, the form [47m(ec-call (f ...))[0m is now legal if all arguments of the call of [47mf[0m are non-stobj objects, in any context where only ordinary object return values are expected. When the second argument of [47m[certify-book][0m is a symbol, that symbol formerly needed to be [47m?[0m or [47mt[0m, in the [47m"ACL2"[0m package. Now, the [symbol-package-name] of the second argument is ignored: any symbol whose [symbol-name] is [47m"?"[0m or [47m"T"[0m is treated the same in that argument position as the symbol [47m?[0m or [47mt[0m in the [47m"ACL2"[0m package, respectively. Thanks to Warren Hunt and Nathan Wetzler for suggesting consideration of a more relaxed criterion for that second argument. (For system hackers, not standard ACL2 users:) Utilities [47m[initialize-event-user][0m and [47m[finalize-event-user][0m now each take a list of three arguments, [47m(ctx body state)[0m. Thanks to Harsh Raju Chamarthi for requesting this change. [31;1mNEW FEATURES[0m It is now permissible to specify a [stobj] field that is itself either a stobj or an array of stobjs. A new primitive, [47m[stobj-let][0m, is provided in order to access or update such fields; see [stobj-let]. Thanks to Warren Hunt and Sol Swords for requesting the ability to specify nested stobjs. New accessor function [47m(mfc-world mfc)[0m returns the world component of a metafunction context. See [extended-metafunctions]. A new [47m[xargs][0m keyword, [47m:SPLIT-TYPES[0m, can be used to ``split'' the [type] declarations from the [guard] in the following sense. By default, or when [47m:SPLIT-TYPES[0m has value [47mnil[0m, one gets the existing behavior: the terms corresponding to type declarations are conjoined into the guard. However, if [47m:SPLIT-TYPES t[0m is specified, then that is not the case; instead, guard verification will require that these terms are proved under the hypothesis that the guard holds. In this way, one can add type declarations to assist the host Lisp compiler without cluttering the function's guard. See [xargs]. Thanks to Jared Davis for requesting this feature. Advanced users may want to see [quick-and-dirty-subsumption-replacement-step] for a way to turn off a prover heuristic. Thanks to those who have mentioned to us potential issues with this heuristic, most recently Dave Greve. [31;1mHEURISTIC IMPROVEMENTS[0m We made changes to the ``ancestors check'' heuristic (source function [47mancestors-check-builtin[0m), as follows. The heuristic could prevent a [rewrite] rule's hypothesis from being rewritten to true, even when that hypothesis is of the form [47m(force <term>)[0m. Now, forcing will take place as expected; see [force]. Thanks to Robert Krug for bringing this issue to our attention and sending an example, which we include as a comment in the ACL2 source code (see [47m(deflabel note-6-2 ...)[0m). The heuristic is now delayed until after we check whether the hypothesis is already known, using [type-set] reasoning alone (in particular, not using rewriting), to be true or to be false. We believe that this is now the ``right'' order for those two operations. We saw a slight speed up in the regression tests (about a percent) with this change, but that might be in the noise. A technical change makes the heuristic slightly less aggressive in preventing backchaining. Roughly speaking, ordering checks based on function symbol counts could suffice to permit backchaining, where now variable counts also suffice. Thanks to Robert Krug for showing us an example where backchaining led to a term with no free variables that was nevertheless subject to the ancestors check, preventing it from being rewritten. (For those who use [47m[defattach][0m to attach to [47mancestors-check[0m) We have used [47mdefrec[0m to introduce an `[47mancestor[0m' data structure. A new function, [47mstrip-ancestor-literals[0m, should be used to obtain the literals from a list of ancestors, although [47mstrip-cars[0m will still work at this time. When we rewrite the current literal of the current clause we assume the falsity of the other literals and of the conclusions produced by forward chaining. We have changed the order in which those assumptions are made, which affects the type-alist used during rewriting. This has three effects: the new type-alist, which is sometimes stronger than the old one, may allow additional rules to fire, the choice of free vars may be different, and the order of the literals in forced subgoals may be different. Should ``legacy'' proofs fail under the new type-alist, we recommend looking for rules that are fired in the new proof that were not fired (on that same subgoal) in the old one. Thanks to Dave Greve for sending us an example that led us to make this change. [31;1mBUG FIXES[0m We fixed a soundness bug that could be exploited by calling system functions [47macl2-magic-mfc[0m or [47macl2-magic-canonical-pathname[0m. Thanks to Sol Swords for bringing this bug to our attention. We fixed a soundness bug in the handling of [stobj]s, in which strings were recognized as stobjs in raw Lisp. Thanks to Jared Davis for sending us a proof of [47mnil[0m that exploited this bug. We now have a much simpler example of this bug, as follows. (defstobj st fld) (defthm bad (stp "abc") :rule-classes nil) (defthm contradiction nil :hints (("Goal" :in-theory (disable (stp)) :use bad)) :rule-classes nil) We fixed bugs in extended metafunctions (see [extended-metafunctions]). The macro [47mmfc-ap[0m no longer takes a [47m:TTREEP[0m keyword argument, because this argument could allow returning a tag tree that does not properly account for forcing. The remaining [47mmfc-xx[0m macros --- [47mmfc-relieve-hyp[0m, [47mmfc-rw+[0m, [47mmfc-rw[0m, and [47mmfc-ts[0m --- still take a [47m:TTREEP[0m keyword argument, but the corresponding functions when [47m:TTREEP[0m is [47mt[0m --- [47mmfc-relieve-hyp-ttree[0m, [47mmfc-rw+-ttree[0m, [47mmfc-rw-ttree[0m, and [47mmfc-ts-ttree[0m --- were introduced with incorrect output signatures. A complication is that [47mmfc-relieve-hyp-ttree[0m was improperly defined in raw Lisp in a way that actually matched the incorrect signature! All of these bugs have been fixed. Perhaps any of them could have made it possible to prove [47mnil[0m, though we have not tried to do so. (Windows only) On Windows, it had been possible for ACL2 not to consider two pathnames to name the same file when the only difference is the case of the drive, e.g., `[47mC:[0m' vs. `[47mc:[0m'. This has been fixed. Thanks to Sol Swords for reporting this issue. Fixed a bug in the storing of rules for the tau system; see [tau-system]. (The error message mentions PARTITION-SIGNATURE-HYPS-INTO-TAU-ALIST-AND-OTHERS.) Thanks to Sol Swords for reporting this bug and sending a simple example to illustrate it. It had been possible to admit the missing [47m[defthm][0m events printed by [47m[defabsstobj][0m, and yet get an error when subsequently submitting the same [47mdefabsstobj[0m event, stating: ``Note discrepancy with existing formula''. The problem could occur when an expression of the form [47m(or X Y)[0m occurred in one of those missing events, because ACL2 created it from the term [47m(if X 't Y)[0m but then translated [47m(or X Y)[0m to [47m(if X X Y)[0m, resulting in a mismatch. This has been fixed. Thanks to Jared Davis for reporting this bug using a simple example. A hard Lisp error was possible for certain illegal functional substitutions (see [lemma-instance]). Thanks to Sol Swords for reporting this bug. We fixed a bug in the case that an exported function of a [47m[defabsstobj][0m event had a [guard] of [47mt[0m. Thanks to Jared Davis for sending a simple example when reporting this bug. We now avoid an infinite loop that could occur when attempting to close the standard character output channel (see [standard-co]). Instead, an error message explains how to accomplish what was probably intended. Thanks to Shilpi Goel for bringing this issue to our attention. (Windows only) Fixed a bug that was causing a hard error on Windows when ACL2 encountered filenames starting with the tilde character ([47m~[0m), for example, [47m(ld "~/acl2-customization.lsp")[0m. Thanks to Sol Swords for bringing this bug to our attention. Also thanks to Harsh Raju Chamarthi for a useful conversation that led to a better fix than our first one. [31;1mCHANGES AT THE SYSTEM LEVEL[0m ACL2 may now be built on recent versions of a new host Lisp, ANSI Gnu Common Lisp (GCL). Traditional (non-ANSI) GCL was the original host Lisp underlying ACL2, and we are grateful for GCL support that we received from the late Bill Schelter and, more recently and particularly for ANSI GCL, from Camm Maguire. The `make' process suggested for book certification has changed substantially, thanks in large part to contributions from Jared Davis and Sol Swords. We have seen the new process provide better performance on machines with many cores, and we expect maintenance advantages such as eliminating the need for Makefiles in individual book directories. The ``classic'' process, which was based on community books file [47mbooks/Makefile-generic[0m, is still supported (see [books-certification-classic]) but may disappear in a future release of ACL2. See [books-certification]. Most changes should be invisible to the user, other than improved `make'-level parallelism, with the exception of the following. o Variable [47mACL2_JOBS[0m is no longer supported, nor is it necessary; simply use `make' option `-j' instead. o Regressions now use `make' option [47m-k[0m by default, which causes the regression to keep going after errors, rather than [47m-i[0m, which ignores errors. If you encounter problems because of this change, use [47mACL2_IGNORE=-i[0m with your `make' command. o The `regression' target works for the experimental extension, ACL2(h) (see [hons-and-memoization]); target `regression-hons' no longer exists. Please let us know if you run into problems with the new infrastructure, as we consider the legacy infrastructure to be deprecated and we will probably eliminate much of it in the future. In particular, circular dependencies were formerly prohibited at the directory level, but that is no longer the case, and we expect such cycles to occur in the future. Although ACL2 users don't typically modify raw Lisp variables, we have arranged to reset Lisp variable [47m*default-pathname-defaults*[0m if necessary at startup so that it will not interfere with ACL2, in particular by messing up the initial connected book directory (see [cbd]). Thanks to Jared Davis, Sol Swords, and Raymond Toy for helping us to identify this issue. [31;1mEMACS SUPPORT[0m [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m In ACL2(h), [47m[print-object$][0m no longer uses the serialize printer except in system applications as before (e.g., write out [47m.cert[0m files). Thanks to Dave Greve for bringing this issue to our attention. Jared Davis contributed changes related to the [47m[memoize][0m utility of ACL2(h), including some low-level changes as well as the following. o [47m[Never-memoize][0m specifies that a given function should never be memoized. o Removed [47mmemoize-let[0m, which may never have ever been used. o Removed the [47m:inline[0m keyword option to memoize, which was just an alias for the [47m:recursive[0m option. For ACL2(p), some anomalous behavior may no longer occur because prover calls (more specifically, trips through the ACL2 ``waterfall'') will return only after all sub-computations (threads) have finished. Thanks to David Rager for contributing this improvement. ACL2(pr), which includes [parallelism] (as for ACL2(p)) and non-standard analysis support for the [real]s (as for ACL2(r)), now builds and can certify the community [47mnonstd/[0m books. Thanks to David Rager for his contribution to this capability.") (note-6-3 (release-notes) "ACL2 Version 6.3 (October, 2013) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes since Version 6.2 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. [31;1mCHANGES TO EXISTING FEATURES[0m The evaluation of a term from a [47m[bind-free][0m hypothesis had been expected to produce an alist binding free variables to terms. While that is still legal, it is also legal for that evaluation to produce a list of such alists: then each is considered, until one of them permits all remaining hypotheses to be relieved. See [bind-free]. Thanks to Sol Swords for requesting this enhancement. ACL2 continues to provide a way to specify keyword command abbreviations for the top-level loop; see [ld-keyword-aliases]. However, [47m[ld-keyword-aliases][0m is now a [table] rather than a [state] global; it is thus no longer a so-called [ld] special. The functionality of [47mset-ld-keyword-aliases[0m has essentially been preserved, except that it is now an event (see [events]), hence it may appear in a book; it is [local] to a book (or [47m[encapsulate][0m event); and the [47m[state][0m argument is optional, and deprecated. A non-local version ([47mset-ld-keyword-aliases![0m) has been added, along with corresponding utilities [47madd-keyword-alias[0m and [47madd-keyword-alias![0m for adding a single keyword alias. See [ld-keyword-aliases]. Thanks to Jared Davis for correspondence that led us to make this change. The [proof-builder] command [47m(exit t)[0m now exits without a query (but still prints an event to show the [47m:INSTRUCTIONS[0m). Thanks to Warren Hunt for feedback leading us to make this change. We made the following minor changes to the behavior of [47mdmr[0m; see [dmr]. First, if [47mdmr[0m monitoring is enabled, then [47m(dmr-start)[0m will have no effect other than to print a corresponding observation, and if monitoring is disabled, then [47m(dmr-stop)[0m will have no effect other than to print a corresponding observation. Second, it had been the case that when [47m(dmr-start)[0m is invoked, the debugger was always automatically enabled with value [47mt[0m (see [set-debugger-enable]), and the debugger remained enabled when [47m(dmr-stop)[0m was invoked. Now, the debugger is only enabled by [47m(dmr-start)[0m if it is not already enabled and does not have setting [47m:never[0m. Moreover, if such automatic enabling takes place, then the old setting for the debugger is restored by [47m(dmr-stop)[0m unless [47m[set-debugger-enable][0m has first been called after that automatic enabling. Finally, if the value of [state] global variable [47m'debugger-enable[0m is [47m:bt[0m, then the new value will be [47m:break-bt[0m, not [47mt[0m. When a call of [47m[progn][0m is executed in the ACL2 loop, its constituent [events] and their results are printed, just as was already done for calls of [47m[encapsulate][0m. Thanks to Jared Davis for a conversation causing us to consider this change. (CCL only) When [47m[set-debugger-enable][0m is invoked with an argument that prints a backtrace and CCL is the host Lisp, the backtrace will be limited to 10,000 stack frames. (We have seen more than 65,000 stack frames before this change.) This limit is the value of raw Lisp variable [47m*ccl-print-call-history-count*[0m, which may be assigned another positive integer value to serve as the maximum number of stack frames to be printed. Improvements have been made pertaining to the disabling (inhibiting) of individual types of warning. Now, inhibited warnings are implemented in a straightforward way using a separate [table] for this purpose, the [47minhibit-warnings-table[0m, rather than using the [47m[ACL2-defaults-table][0m. See [set-inhibit-warnings], and see [set-inhibit-warnings!] for a variant that is not [47m[local][0m to an [47m[encapsulate][0m or a book in which it occurs. Thanks to Sol Swords for sending examples showing how [47m[set-inhibit-warnings][0m did not always behave as one might reasonably expect when books are involved. It had been the case that [47m[lp][0m took a single argument, [47m'raw[0m. This argument was not documented and also caused an error, so it has been eliminated. The functionality of [47m[make-event][0m has been significantly expanded. First: if the expansion is of the form [47m(:OR e1 e2 ...)[0m, then event forms [47me1[0m, [47me2[0m, and so on are evaluated, in order, until the evaluation of some [47mek[0m completes without error. In that case, the expansion is treated simply as [47mek[0m. With this capability, alternative expansions can be attempted and the successful one does not need to be evaluated again. See the new version of community book [47mbooks/make-event/proof-by-arith.lisp[0m for an example. Second, an expansion may be of the form [47m(:DO-PROOFS e)[0m, in which case the event [47me[0m is evaluated with proofs [31;1mnot[0m skipped; see [ld-skip-proofsp]. Third, new keyword [47m:EXPANSION?[0m can be used to avoid storing expansions in certificate files. See [make-event]. When a [47m[defun][0m event prints a failure message in the summary, that message now indicates when the failure is due to a failed proof of guard verification or a failed proof of the measure theorem. Thanks to Shilpi Goel for requesting this enhancement. [31;1mNEW FEATURES[0m ACL2 can now be instructed to time activities using real time (wall clock time) instead of run time (typically, cpu time). See [get-internal-time]. Thanks to Jared Davis for asking to be able to obtain real-time reports in event summaries. A new utility, [47m[sys-call+][0m, is similar to existing utility [47m[sys-call][0m in that it executes a command. Unlike [47msys-call[0m, however, [47msys-call+[0m returns values that include output from the command (in addition to the exit status), rather than simply printing the command. See [sys-call+]. The new macro [47m[verify-guards+][0m extends the functionality of [47m[verify-guards][0m by permitting macro-aliases (see [macro-aliases-table]). See [verify-guards+]. Thanks to Jared Davis for requesting this feature and suggesting the use of [47m[make-event][0m in its implementation. We have also modified [47m[verify-guards][0m to print a friendlier error message when its argument is a macro-alias. See [last-prover-steps] for a new utility that returns the number of prover steps most recently taken. [31;1mHEURISTIC IMPROVEMENTS[0m The processing of [47m:use[0m and [47m:by[0m [hints] has been changed in the following two rather subtle ways, thanks to suggestions from Sol Swords. o For [47m:by[0m hints, the simplest check was an equality check, rather than a more general subsumption check. That equality check was made after removing so-called ``guard holders'' ([47m[must-be-equal][0m, [47m[prog2$][0m, [47m[ec-call][0m, [47m[the][0m) from both the previous theorem and the purported theorem. Now, guard-holder removal has been strengthened, so that the results are also put into so-called quote-normal form, for example replacing [47m(cons '3 '4)[0m by [47m'(3 . 4)[0m. o For a [lemma-instance] provided to a [47m:use[0m or [47m:by[0m hint that is a [47m:functional-instance[0m, if a [47m:do-not[0m hint (see [hints]) has specified that [47mpreprocess-clause[0m is not to be used, then preprocessing will not be used on the constraints. We eliminated certain warnings about being ``weak'' for every [47m:[0m[47m[type-prescription][0m rule whose conclusion designates that the function call can be equal to one of its arguments, e.g., [47m(or (integerp (foo y)) (equal (foo y) y))[0m. In many cases (such as the one above), such warnings about ``weak'' simply aren't correct. [31;1mBUG FIXES[0m Fixed a soundness bug that was permitting a [stobj] to be bound by a [47m[let][0m or [47m[mv-let][0m form, without being among the outputs of that form. Thanks to Jen Davis and Dave Greve for reporting this bug. Their report included an example which forms the basis for a proof of [47mnil[0m, included as a comment in the form [47m(deflabel note-6-3 ...)[0m in ACL2 source file [47mld.lisp[0m. (GCL only) Fixed an obscure soundness bug due to an error in the GCL implementation of [47m[set-debugger-enable][0m. For details, see the relevant comment in the ACL2 source code under [47m(deflabel note-6-3 ...)[0m. Fixed a bug in the case of a field of a (concrete) stobj that is an abstract stobj (see [nested-stobjs]). Thanks to David Rager for bringing this bug to our attention. Splitter output for type [47mif-intro[0m (see [splitter]) could formerly occur even when at most one subgoal is generated. This has been fixed. Fixed a bug in [47m[wof][0m, hence in [47m[psof][0m (which uses [47mwof[0m), that was causing the printing of a bogus error message. A small logical bug has been fixed in the logical definition of [47m[sys-call-status][0m. Formerly it always returned [47m(mv nil state)[0m whenever the oracle of the state is non-empty (see [state]). Fixed a bug that was causing an error upon evaluation of the form [47m(set-prover-step-limit nil)[0m. Thanks to David Russinoff for reporting this error. The [47m:measure[0m (if supplied) is now ignored when checking redundancy with respect to a non-recursive definition that is not defined within a [47m[mutual-recursion][0m. (See [redundant-events] and see [xargs].) It had been possible to get a low-level ACL2 error in this situation. Thanks to Jared Davis for reporting this bug with a helpful example. Eliminated a potential error when using [47m[comp][0m to compile an uncompiled function defined under [47m[progn!][0m, which we observed in LispWorks. [31;1mCHANGES AT THE SYSTEM LEVEL[0m The ACL2 sources are now publicly available between ACL2 releases, using svn; see the new ``[47macl2-devel[0m'' project hosted by Google code at [47mhttp://acl2-devel.googlecode.com[0m. Although such a copy of ACL2 is likely to work well with the latest svn (trunk) revision of the ACL2 community books (see [community-books]), please take seriously the warning message printed at startup: ``The authors of ACL2 consider svn distributions to be experimental; they may be incomplete, fragile, and unable to pass our own regression.'' That message also provides instructions for bug reports. If you decide to use svn versions of either the community books or ACL2, then you should use both, as they tend to be kept in sync. We fully expect ACL2 releases to continue from time to time, as usual. Thanks to Jared Davis for his efforts in setting up the new acl2-devel project and svn repository, and to him and David Rager for convincing us to distribute ACL2 sources via svn between releases. Thanks to a suggestion from Jared Davis, over 30 built-in functions are now declared to be inline in order to boost performance. (The list may be found by searching ACL2 source file [47maxioms.lisp[0m for ``[47m(declaim (inline[0m''.) Better support has been provided for command line arguments, especially those supplied directly by the user when calling ACL2. For one, problems with quoting have been solved using [47m"$@"[0m in place of [47m$*[0m. Also, the function [47m[save-exec][0m now allows specification of arguments, both for the host Lisp as well as ``inert'' arguments that can be passed along to calls of programs (as with [47m[sys-call][0m). A keyword argument, [47m:return-from-lp[0m, specifies a form to evaluate before quitting the read-eval-print loop at startup. See [save-exec]. Also see the source function [47muser-args-string[0m and its comments, source file [47macl2-init.lisp[0m, for more information. Thanks to Jared Davis for suggesting the use of [47m"$@"[0m, as well as modifications to [47m[save-exec][0m and helpful conversations about that. A rather extensive overhaul has taken place for the function proclaiming mechanism. As before, this is only used when the host Lisp is GCL. However, building an executable is now faster for some Lisps, including GCL, by avoiding repeated recompilation and perhaps repeated initialization. (CCL only) We increased stack sizes when the host Lisp is CCL. The default for recent CCL versions is equivalent to specifying `[47m-Z 2M[0m' on the command line, but saved ACL2 scripts (including experimental versions ACL2(h), ACL2(p), ACL2(r), and combinations of them) to `[47m-Z 64M[0m', representing a 32-fold increase. Thanks to Jared Davis for pointing us to community books file [47mbooks/centaur/ccl-config.lsp[0m and to Sol Swords for helpful discussions. (SBCL only) Fixed [47msave-exec[0m for host Lisp SBCL to provide the same export of variable [47mSBCL_HOME[0m that was provided in the original [47msaved_acl2[0m script. (GCL only) We made changes, following suggestions from Camm Maguire (whom we thank for these suggestions), to support ACL2 builds on recent versions of GCL (2.6.8 and 2.6.10; we recommend against using GCL 2.6.9, since issues there were fixed in 2.6.10). Specifically, we no longer set the hole size, and we allocate contiguous pages sufficient to run an ACL2 regression without failing due to memory limitations. [31;1mEMACS SUPPORT[0m Modified file [47memacs/emacs-acl2.el[0m to eliminate some warnings that were appearing in a recent Emacs version, replacing [47m(end-of-buffer)[0m by [47m(goto-char (point-max))[0m and [47mnext-line[0m by [47mforward-line[0m. Thanks to Warren Hunt for bringing the warnings to our attention. [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m (Allegro CL only) ACL2(h) now avoids blow-ups in hash table sizes that could be caused by [fast-alist-fork]. Thanks to Jared Davis for helping to debug this problem, and to David Rager for contributing the community book [47mbooks/parsers/earley/earley-parser.lisp[0m, which highlighted this problem. (SBCL only) Fixed a bug that was causing a Lisp break after turning on [waterfall-parallelism]. Thanks to David Rager for confirming that our proposed fix is correct.") (note-6-4 (release-notes) "ACL2 Version 6.4 (January, 2014) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 6.3 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. See also [note-6-4-books] for a summary of changes made to the ACL2 Community Books since ACL2 6.3, including the build system. Changes to Existing Features [Gag-mode] no longer saves prover output when [47mPROVE[0m output is inhibited (see [set-inhibit-output-lst]). This may improve performance slightly when certifying community books using their [47mMakefile[0m or [build::cert.pl]; in particular, GCL 2.6.8 running on a Mac can now certify the book [47mbooks/tau/bounders/elementary-bounders.lisp[0m without running out of space, even without explicitly turning off [gag-mode] (which had been done shortly before the Version 6.3 release). When [include-book] fails to find a readable [certificate] ([47m.cert[0m) file, the error message now distinguishes between the case that this file is missing and the case that read permission is missing. (GCL only) Time reporting has been improved when the host Lisp is Gnu Common Lisp. A key change was made in the computation of runtime (for example, to report in event summaries), so that it includes the ``child runtime''. See [get-internal-time]. Also, the utility [47m[time$][0m now gives improved information by including child runtime information, which can be significant; for example, it probably includes compile time, while the ``seconds runtime'' statistic (still) does not. Recent versions of GCL might also provide system runtime and child system runtime. See [time$]. Thanks to Camm Maguire for suggesting these improvements to [47mtime$[0m and providing an initial implementation for them. Fixed a bug in an ACL2 system function, [47mour-truename[0m, which returns the ``true name'' for a file name, when supplied with an optional second argument. Thanks to Camm Maguire for bringing this bug to our attention. The wording in theory warnings has been improved, to avoid giving the impression that you are newly disabling a built-in rule in the case that it merely remains disabled. As requested by Sol Swords, erroneous evaluations of system function [47mmagic-ev-fncall[0m that had produced a message, [47mmsg[0m, will now also return that message. The following example, sent by Sol, illustrates the fix: before, evaluation of [47m(magic-ev-fncall 'cons '(a) state nil nil)[0m printed a message (to the comment window) and then returned [47m(mv t nil)[0m, but now it returns [47mmv t <msg>[0m, where [47m<msg>[0m denotes the message (printed with the [47m[fmt][0m [47m~@[0m directive). Fixed [47m:[0m[47m[pbt][0m to avoid printing the bodies of [47m[defconst][0m forms. Thanks to Jared Davis for pointing out the large output when the body is a large character string. A new output type, [47mhistory[0m, now controls the printing of history-related information; see [47m[set-inhibit-output-lst][0m. The unused output type, [47mexpansion[0m, is no longer supported, i.e., is no longer a member of the list [47m*valid-output-names*[0m. Because of this change, printing of information when undoing, as by [47m:[0m[47m[u][0m, will now take place even when [47mevent[0m output is inhibited (if [47mhistory[0m output is not inhibited); we thank Sol Swords for requesting that change. The [47m:[0m[47m[loop-stopper][0m field of a rule of class [47m:[0m[47m[rewrite][0m, should still be a list of lists [47m(var1 var2 fn1 fn2 ... fnk)[0m, where [47mvar1[0m and [47mvar2[0m are variables and the [47mfni[0m are symbols. But formerly each [47mfni[0m was required to be a function symbol; now, it can be a macro alias for a function symbol (see [47m[add-macro-alias][0m). For example, the following is a valid [47m:[0m[47m[loop-stopper][0m field: [47m((x y +))[0m. The restrictions on utilities [47moracle-apply[0m and [47moracle-funcall[0m have been updated in order to avoid potentially confusing or inappropriate results, by imposing the following new requirements on their first argument, which must still be a function symbol. That symbol must not be [47mif[0m (formerly the illegal symbol was [47m[return-last][0m); it must not be a key of the alist, [47m*ttag-fns-and-macros*[0m; it must not be untouchable (see [47m[remove-untouchable][0m); and it must not be a [47m[stobj][0m creator (see [47m[defstobj][0m). The [table] guard on [47m[dive-into-macros-table][0m has been strengthened in order to avoid calling untouchable functions (see [47m[remove-untouchable][0m). New Features We have added a tool for writing out useful information about a book's event names when certifying the book. See [bookdata]. Thanks to Dave Greve for requesting this tool and participating in its specification. There are new analogues of [47m[add-include-book-dir][0m and [47m[delete-include-book-dir][0m: [47m[add-include-book-dir!][0m and [47m[delete-include-book-dir!][0m, respectively. The new utilities are similar to their existing counterparts, except that their effects are not [local] to enclosing [books] or [47m[encapsulate][0m events. Thanks to Shilpi Goel for requesting this enhancement. The class of [congruence] rules has been broadened considerably, so that one can restrict to patterns. For example, a congruence rule can now state that an equivalence is maintained for the term [47m(mv-nth 1 (f (cons u v) y 'a))[0m when rewriting [47my[0m. See [patterned-congruence]. Thanks to Sol Swords for requesting this feature. Heuristic Improvements (None to report this time.) Bug Fixes Fixed a soundness bug in the handling of hypotheses of conditional [47m:[0m[47m[definition][0m rules invoked during rewriting by applying [47m:[0m[47m[expand][0m [hints]. See (defxdoc note-6-4 ...) in community book [47msystem/doc/acl2-doc.lisp[0m for a proof of [47mnil[0m in ACL2 Version_6.3 that exploits this bug. It had been possible to update a [stobj] (either an ordinary stobj or an abstract stobjs) so that it no longer satisfies its recognizer predicate. This soundness bug has been fixed. Thanks to Jared Davis and Sol Swords for pointing out this bug, making useful observations about the issue, and sending proofs of [47mnil[0m, one of which may be found in a Lisp comment in the defxdoc form for [47mnote-6-4[0m. Fixed a long-standing soundness bug (found at least as far back as Version 1.9!) in the checking done for [congruence] rules. There had failed to be a check that the new variable on the right-hand side of the conclusion is indeed new. The following example is shown in detail as a comment in function [47minterpret-term-as-congruence-rule[0m, ACL2 source file [47mdefthm.lisp[0m, where it is used to prove [47mnil[0m in Version 6.3. (implies (e y1 y2) (equal (h y2 y1) (h y2 y2))) Fixed a bug in the ACL2 character reader that was causing an end-of-file error when reading from a string ending in [47m"#\c"[0m, for [47mc[0m a character or non-terminating sequence of characters. Thanks to Jared Davis for sending the following example, whose evaluation in raw Lisp had caused an error. (let* ((*readtable* *acl2-readtable*) (stream (make-string-input-stream "#\\a")) (x1 (read stream nil :EOF)) (x2 (read stream nil :EOF))) (list x1 x2)) (GCL only) Improved the automatic proclaiming mechanism used for GCL builds, in particular to avoid computing a return type when a term is detected that could come from a call of [47m[non-exec][0m, and to do a more complete job for calls of [47m[return-last][0m. (CCL only) A CCL bug was treating filenames of the form [47m"~/user/..."[0m as [47m"~/..."[0m. Thanks to Gary Byers for sending us a CCL-specific form that is now included in the ACL2 sources, which avoids this problem. Attempts to submit [47m[congruence][0m rules had unfortunate consequences in the case that the function ``symbol'' is [47m[if][0m or [47m[quote][0m: for [47mif[0m, rules were appropriately ignored because of the special handling that ACL2 already gives to calls of [47m[if][0m for congruence-based reasoning, while for [47mquote[0m, it was possible to get a hard Lisp error. Now, attempts to submit such rules will result in a clear ACL2 error. It had been possible to get a confusing raw Lisp error when submitting a [47m[defstobj][0m event whose first argument is not a symbol, as in: [47m(defstobj (fld :type integer :initially 0))[0m. That user error is now reported gracefully by ACL2. When an [47m[include-book][0m form is executed for a non-existent book, we no longer get a bogus warning about a missing compiled file. (Of course the compiled file is missing when the book itself is missing! So there's no need to report this fact.) Thanks to Caleb Eggensperger for bringing this issue to our attention. Changes at the System Level The ACL2 system [documentation] has been reworked for the [xdoc] framework developed by Jared Davis. While the ACL2 User's Manual can still be built, it is now possible for the ACL2 community to contribute to the ACL2 system documentation, in community book [47mbooks/system/doc/acl2-doc.lisp[0m; see comments near the top of that book. Now that both the ACL2 system documentation and much of the community books documentation are written in [xdoc] format, we hope the ACL2 community will add links from the ACL2 system documentation topics to book documentation topics. Note that [47m:[0m[doc] still works at the terminal, but it is based on the new system, and other terminal-based access to the documentation has been eliminated (for example [47m:more[0m). Thanks to Jared for all his work contributing to this enhancement. Fixed community books [47mbooks/Makefile-generic[0m and also [47mbooks/Makefile[0m, which now has filename [47mbooks/GNUmakefile[0m, to work with Cygwin (Windows). Thanks to Harsh Raju Chamarthi for his substantial help. The guard for system function [47mev-fncall-w[0m now includes an arity check. EMACS Support There is now an Emacs utility for browsing the hypertext documentation for ACL2 and the community books. This browser, ACL2-Doc, essentially serves as a replacement for Emacs Info, which can no longer be used to browse the documentation. ACL2-Doc can be used not just for the ACL2 User's Manual but also for the ACL2+Books Manual. It is loaded automatically into Emacs if you load the file [47memacs/emacs-acl2.el[0m. See [ACL2-doc] and [documentation]. Experimental/Alternate Versions (None to report this time.)") (note-6-5 (release-notes) "ACL2 Version 6.5 (August, 2014) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 6.4 into the following categories of changes: existing features, new features, heuristic improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. See also [note-6-5-books] for a summary of changes made to the ACL2 Community Books since ACL2 6.4, including the build system. Changes to Existing Features The [47m[brr@][0m command now supports inputs [47m:initial-ttree[0m and [47m:final-ttree[0m. Thanks to David Rager for a request leading to these enhancements. See [ttree] for a discussion of the tag-tree structures returned for these inputs. (GCL only) A restriction for structure-sharing (as described in a remark, ``Remark on print-circle-files''; see [print-control]) involving GCL has been removed, since this is no longer required for the latest GCL versions (2.6.8 and 2.6.10). Thanks to Jared Davis and Camm Maguire for useful discussions and this GCL improvement. The keyword commands [47m:exit[0m and [47m:quit[0m are disabled inside [brr], in order to avoid accidental exits from ACL2. Thanks to David Rager for suggesting such a change. For calls of [47m[make-event][0m made during the [47m[include-book][0m phase of [47m[certify-book][0m, keyword [47m:check-expansion[0m no longer causes evaluation of the first argument of [47mmake-event[0m; rather, the value of [47m:check-expansion[0m is simply used as the expansion. Thanks to Sol Swords for suggesting this change, which made it reasonable to ignore such [47mmake-event[0m forms when determining the ``rolling back'' before that [47minclude-book[0m phase, as described in the next section. The form [47m(reset-prehistory nil)[0m now is a no-op if [state] global [47m'[0m[47mskip-reset-prehistory[0m has a non-[47mnil[0m value. Thanks to Sol Swords for requesting this feature (in support of infrastructure for certifying the [community-books]). The output from [47m:[0m[47m[pr][0m, [47m:[0m[47m[pr!][0m, [47m:[0m[47m[pl][0m, and [47m:[0m[47m[show-bodies][0m has been tweaked. Thanks to a suggestion from Ben Selfridge, such output now shows the hypotheses (the [47mHyps[0m field) above the left-hand side and right-hand side of a [rewrite] rule ([47mLhs[0m and [47mRhs[0m, respectively). The [47mEquiv[0m field has also been moved up before the [47mLhs[0m field in such output for rewrite rules, and this field has been added for [elim] rules. Finally, the [47mHyps[0m field now appears above the [47mTerm[0m field in such output for [type-prescription] rules. Rules of class [47m:[0m[47m[linear][0m may now be [monitor]ed. Thanks to David Rager for requesting this enhancement. When forcing (see [47m[force][0m) is applied, we now always see the appropriate [executable-counterpart] [rune], [47m(:executable-counterpart force)[0m, in the proof output and summary; this hadn't previously been the case. Thanks to Robert Krug for bringing this issue to our attention. The default value for the [47m:write-port[0m keyword argument of [47m[certify-book][0m is now [47mt[0m, as was already claimed by the documentation. Thus, a [47m.port[0m file will be written when a book is certified, making it more likely that a subsequent [47m[include-book][0m will complete without error even if the book has been modified without recertification. Note that a change by Sol Swords to the build system for the [community-books] now sets an environment variable to guarantee that [47mwrite-port[0m is true, independent of this change. On a related note: the unadvertised environment variable [47mACL2_WRITE_PORT[0m is now handled more appropriately, by interning its upcased argument into the ACL2 package. The following changes can make it easier to include books that are uncertified or have corrupted compiled files. Thanks to Sol Swords for sending helpful, relevant examples and for subsequent discussions helping to lead to these changes. * It is no longer illegal to call [47mset-compiler-enabled[0m within [books]. See [compilation], which shows how to do this in order to avoid loading the compiled file not only for a book specified by [47m[include-book][0m but also for all books included under that book. Also see [compilation] for an analogous utility, [47m(set-port-file-enabled nil state)[0m, to avoid loading [47m.port[0m files. (For background on [47m.port[0m files, see [uncertified-books]). * In situations where it is legal to include an uncertified book (typically, any time other than during [47m[certify-book][0m, ACL2 nonetheless could fail to do so when an error occurred while reading a [certificate] file. ACL2 can now instead include the book successfully as an uncertified book. * When hard raw Lisp errors occur during loading of compiled files on behalf of an [47m[include-book][0m event, that event can now complete successfully much as though the compiled file were simply missing. (SBCL only) The function [47m[setenv$][0m is now supported in SBCL, which had been the one supported host Lisp for which [47msetenv$[0m had not been supported. Thanks to Jared Davis for pointing the way to this improvement. Built-in [equality-variants] have been modified in order to support suitable guard-checking. For example, evaluation of the form [47m(member-eq 3 '(4 5))[0m, or equivalently, [47m(member 3 '(4 5) :test 'eq)[0m, had produced a value of [47mnil[0m, but now we get what one should have expected: a guard violation (since [47m[member-eq][0m is intended to compare symbols). Thanks to Yan Peng for raising a question on the acl2-help mailing list that led us to make this improvement. When the [47m:[0m[47m[pe][0m command is supplied the macro alias for a function symbol (see [macro-aliases-table]), the system will now print [events] not only for the macro symbol but also for the corresponding function symbol. Thanks to Cuong Chau, Jared Davis, Shilpi Goel, Sol Swords, and Warren Hunt for requesting this enhancement. Some evaluations of forms [47m(mbe :logic L :exec E)[0m are more efficient or avoid guard violations, by evaluation of the [47m:exec[0m form ([47mE[0m) instead of the [47m:logic[0m form ([47mL[0m). If the [47m[mbe][0m call is in a [47m:[0m[47m[program][0m mode function definition, the [47m:exec[0m code will be evaluated, where unlike before, this is true even when guard-checking is [47m:all[0m or [47m:none[0m (see [set-guard-checking]). If the [47mmbe[0m call is in a [47m:[0m[47m[logic][0m mode function definition, the change is that the [47m:exec[0m code will be evaluated when there is a superior call of a [47m:program[0m mode function, except when guard-checking is [47m:all[0m or [47m:none[0m or in a couple of technical cases (see a comment in the source code for constant [47m**1*-as-raw*[0m [formerly [47m*mbe-as-exec*[0m] for details). This use of [47m:exec[0m code had been defeated when the superior [47m:program[0m mode function had an ``invariant-risk'' of making ill-guarded stobj updates. However, there is no change in the case of safe-mode, which is used during evaluation of [47m[defconst][0m, [47m[value-triple][0m, and [47m[defpkg][0m forms, and during macroexpansion: the [47m:logic[0m and [47m:exec[0m forms are still both evaluated and checked for equality. Thanks to Jared Davis for reporting this issue and for helpful chats about it. For more information, see the comment about ``mbe and invariant-risk'' in the form [47m(defxdoc note-6-5 ...)[0m in [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m. The utility [47m[save-exec][0m has a new (optional) keyword argument, [47m:init-forms[0m, which specifies a list of forms to evaluate when first entering the ACL2 read-eval-print loop, [47m[lp][0m. Thanks to Jared Davis for requesting this enhancement. New Features A [47m[defstobj][0m event may now include the keyword argument [47m:non-memoizable[0m. When its value if [47mt[0m, then for ACL2(h) builds (see [hons-and-memoization]), code will run somewhat faster. In a little test doing just reads and writes to a stobj array in ACL2(h), it took 26% less time when the stobj to be written was introduced by [47m[defstobj][0m using [47m:non-memoizable t[0m. Thanks to Warren Hunt for requesting this feature and helping to develop the test. See [47m[set-print-base-radix][0m for a utility that may be preferable to [47m[set-print-base][0m, since it essentially calls [47m[set-print-radix][0m automatically. Thanks to David Rager, Shilpi Goel, and David Hardin for participating in an acl2-help mailing list discussion that motivated this feature. Heuristic Improvements One of the steps performed by [47m[certify-book][0m has traditionally been to check for local incompatibilities (see [local-incompatibility]) after admitting all the events in the book. This step involved rolling back the logical [world] to what it was at the start of certification, and then including the book (see [include-book]). As an optimization, we now avoid rolling back the world more than necessary; see [47m[certify-book][0m, specifically the discussion of Step 3. We thank Sol Swords for requesting this optimization and for making a suggestion that improved it, pertaining to [47m[make-event][0m (described above). We also thank Jared Davis for alerting us to an issue that turned out to be caused by a bug in our initial implementation. Sol has reported a nearly 20% reduction in time for certifying a certain large collection of books. The test for redundancy of [47m[encapsulate][0m [events] has been made more efficient. Also, while the criterion itself remains unchanged, the documentation has been made more accurate; see [redundant-encapsulate]. We observed more than a 2% reduction in time for the ``everything'' regression target, but we observed more than 23% of the time eliminated for the form [47m(time$ (include-book "doc/top" :dir :system))[0m after building the documentation. Thanks to David Rager for bringing that particular book to our attention, as one that took a long time to include. The function [47m[pairlis$][0m is now tail-recursive, hence potentially more efficient. More precisely, its definition for the logic remains unchanged, but using [47m[mbe][0m, for execution it calls a new tail-recursive function, [47mpairlis$-tailrec[0m. Thanks to Jared Davis for requesting this improvement. [Linear] arithmetic has been strengthened slightly so that immediately after simplification has ``settled down'' (see [hints-and-the-waterfall]), the unrewritten conclusion of a [47m:[0m[47m[linear][0m rule may be used when normally this would not be the case. Thanks to Robert Krug for reminding us of examples we had encountered that could benefit from some such a change, and for pointing us to some relevant source code. This improvement generally causes an extra pass through the simplifier; hence we have observed approximately a 2% slowdown in the regression suite. Note that machinery is now in place for installing additional ``desperation heuristics''; perhaps the ACL2 community will have some to suggest. Bug Fixes We fixed a soundness bug in how the [tau-system] processed calls of [47mif[0m. Thanks to Dmitry Nadezhin for reporting this bug by sending a simple example that exploited it to prove [47mnil[0m. To see that example, see the comment about ``tau soundness bug'' in the form [47m(defxdoc note-6-5 ...)[0m in [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m. We fixed a soundness bug for nested [stobj]s (see [stobj-let]). In the case of a stobj producer variable that is not a child stobj, it had been possible to update that stobj without returning it. Thanks to Sol Swords for reporting this bug and providing a corresponding proof of [47mnil[0m, which is included in a comment in the form [47m(defxdoc note-6-5 ...)[0m in [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m.) We fixed a soundness bug in the case of a [stobj] with a field that is a resizable array of stobjs. Thanks to Sol Swords for sending a proof of [47mnil[0m exploiting this bug, together with some helpful analysis attributing the bug to a mistake in the generated logical definition of the corresponding resize function. (His example is included in a comment in the form [47m(defxdoc note-6-5 ...)[0m in [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m.) (ACL2(h) only) We fixed a soundness bug involving the interaction of [47m[stobj-let][0m and [47m[memoize][0m, which thus is only a bug in ACL2(h) (see [hons-and-memoization]), not in ACL2. The fix was to add code to [47mstobj-let[0m that clears the memoization table for the parent stobj if any child stobj is updated. An example proof of [47mnil[0m before this fix may be found in the ACL2 source file [47mtranslate.lisp[0m, in a comment in the function [47mstobj-let-fn-raw[0m. (Allegro CL and CMUCL only) We fixed bugs in function [47m[princ$][0m when invoked in an ACL2 image with Allegro CL or CMUCL as the host Lisp implementation. In Allegro CL, when printing a complex number in base 16, lower case characters were produced, for example printing [47m#C(c d)[0m instead of the characters predicted by the axioms, namely [47m#C(C D)[0m. In some recent versions of CMUCL, after executing the forms [47m(set-print-base 16 state)[0m and [47m(set-print-case :downcase state)[0m, hex digits were printed in lower case, unlike other host Lisps and contrary to the ACL2 axioms: for example, 1000 base 10 was printed as [47m3e8[0m rather than as predicted by the ACL2 axioms, [47m3E8[0m. Thanks to Jared Davis for bringing these bugs to our attention, and also for pointing out excessive printing of a big note about such printing in Allegro CL. We now avoid that note altogether, which had warned that printing numbers in base 16 can be slow for Allegro CL. In fact, that performance issue has been eliminated: for example, after evaluating [47m(defconst *c* (expt 2 200000))[0m and [47m(set-print-base 16 state)[0m, the form [47m(time$ (pprogn (princ$ *c* *standard-co* state) state))[0m reports taking about 3 seconds before the change but about 1/100 seconds after the change. Thanks to David Margolies of Franz Inc. for passing along a remark from a colleague that showed how to make this improvement. The utility [47m[sys-call+][0m can now only be called if there is an active [trust-tag], which is the restriction that was already in place for [47m[sys-call][0m. This plugs a potential soundness hole. We have made several system functions untouchable (see [remove-untouchable]), in order to prevent soundness bugs. We thank Jared Davis and Sol Swords for sending us an example that used a call of one of these functions to prove [47mnil[0m. We have placed that example into a comment in Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-6-5 ...)[0m. The [47mbrr[0m command, [47m:wonp[0m, had not been installed for use after [47m:eval[0m even though this was claimed in the documentation (see [brr-commands]). This has been fixed. Thanks to David Rager for bringing this issue to our attention. Fixed a bug in [47m[make-event][0m that could cause [47m[include-book][0m to fail with a bogus message about ``the set of ttags permitted in the current context.'' Thanks to Sol Swords and Anna Slobodova for reporting this bug, and to Sol for sending a small example that illustrated the problem. Fixed a bug that was wrongly disallowing certain calls of exported functions for abstract stobjs (see [defabsstobj]). Thanks to Sol Swords for reporting this bug, supplying an example illustrating the bug, and suggesting a nice fix. A slight variant of his example is included in a comment in Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-6-5 ...)[0m. When a macro symbol [47mmac[0m was a macro-alias for a function symbol [47mf[0m (see [macro-aliases-table]), then the form [47m(verify-guards+ mac)[0m caused an error when encountered while including an uncertified book. This problem has been fixed. Thanks to Jared Davis for pointing out the problem and sending a simple example to illustrate it. Technical Note: the actual problem was that [47m[verify-guards+][0m generates a call of [47m[make-event][0m with an [47m:expansion?[0m argument, and that argument needed to be ignored (as it now is, after the fix) when including an uncertified book. The [47m[walkabout][0m utility could cause hard Lisp errors when the current package is other than [47m"ACL2"[0m. This has been fixed. Thanks to Sol Swords for bringing this bug to our attention and suggesting a fix. Changes at the System Level (SBCL only) Fixed the executable script generated for SBCL so that [47mSBCL_HOME[0m is set to the SBCL [47mobj/sbcl-home/[0m directory if it exists, since that fix seems needed for some recent versions of SBCL (1.1.14 in particular). File [47mGNUmakefile[0m in the ACL2 sources directory wasn't passing the value of shell variable [47mACL2[0m from target [47mcertify-books-fresh[0m to target [47mcertify-books[0m, and similarly for target [47mbooks/system/doc/render-doc.cert[0m (invoked by target [47mDOC[0m). This has been fixed. We thank Jared Davis and Camm Maguire for helpful discussions. The "make DOC" command was not completing correctly when variable [47mACL2[0m was not set. Also, for host Lisp CMUCL at least, it stalled at the terminal unless a quit command was issued twice (as ACL2 was stuck without exiting). Those problems have been resolved. Thanks to Jim Ward for bringing these issues to our attention Improved the error message when encountering an illegal comma while reading input (i.e., for a comma not within a suitable nesting of backquotes). Thanks to Jared Davis for bringing this issue to our attention and for a helpful discussion. (GCL only) Arranged for state global [47m'tmp-dir[0m to be set to GCL's [47msi::*tmp-dir*[0m, even on Windows; this may be important for compilation on Windows. Thanks to Camm Maguire for pointing out the need to set [47m'tmp-dir[0m for ACL2 built on GCL on mingw. (GCL only) Now, [47m[gc$][0m may be called with no arguments, in which case the missing argument for [47msystem::gc[0m is [47mt[0m. EMACS Support Improvements to the [ACL2-Doc] browser include the following. * A new `[47mw[0m' command displays the topic name in the minibuffer, together with the manual name (ACL2+Books Manual or ACL2 User's Manual). * Improved the `[47mcontrol-t .[0m' command so that the default topic is selected just as in acl2-doc mode. (Technically: the same syntax table is used for `[47mcontrol-t .[0m' as is used in the [47macl2-doc[0m buffer for that command and the `[47mg[0m' command.) * Improved the search commands so that the display doesn't move when the next occurrence is already displayed on the screen. * Eliminated the deprecated commands `[47mControl-x a A[0m', `[47mControl-x a a[0m', and `[47mControl-t G[0m'. Experimental/Alternate Versions For ACL2(r), Ruben Gamboa found a bug in constraints for functions introduced with [47mdefun-std[0m, and also kindly provided a fix, which has been incorporated. Modified ACL2(hp) so that two system functions that had been [47m[unmemoize][0md when turning on [waterfall-parallelism] --- [47mfchecksum-obj[0m and [47mexpansion-alist-pkg-names-memoize[0m --- now remain memoized. This can greatly improve performance when using ACL2(hp) with [waterfall-parallelism] on, in particular community book [47mbooks/system/doc/render-doc-combined.lisp[0m. Made miscellaneous small improvements to ACL2(h). The utilities [47mhons-shrink-alist[0m and [47mhons-shrink-alist![0m have essentially been renamed to [47m[fast-alist-fork][0m and [47m[fast-alist-fork!][0m, respectively. The old names are deprecated but remain as macros that are macro-aliases for the respective new names (see [macro-aliases-table]). New utilities, [47m[fast-alist-clean][0m and [47m[fast-alist-clean!][0m are similar to the above but take just one argument and, if it is a fast alist, associates the result with the hash table link of that argument. Thanks to Jared Davis for providing a concrete proposal, together with the new names, for what had been only a concept.") (note-7-0 (release-notes) "ACL2 Version 7.0 (January, 2015) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 6.5 into the following categories of changes: existing features, new features, efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. A particularly major change with this release is that by default, ACL2 executables are [hons-enabled]: see [hons-and-memoization]. We expect this change to be backward compatible for current ACL2 users, other than a change to the name of the executable, as described below. * As before, there are two ways to build ACL2: either [hons-enabled], to produce ACL2(h) with executable name [47msaved_acl2h[0m; or not hons-enabled, to produce ``classic ACL2'', which we now call ACL2(c), with executable name [47msaved_acl2[0m. [Note: These defaults were changed after Version_7.0.] * Unlike before, the default build of ACL2 is now ACL2(h), hence with name [47msaved_acl2h[0m [after Version_7.0, once again [47msaved_acl2[0m]. It is still possible to build ACL2(c) (hence with name [47msaved_acl2[0m) [after Version_7.0, [47msaved_acl2c[0m], but this is not the default. * The change to building ACL2(h) by default may require you to change scripts and environment variables to point to [47msaved_acl2h[0m rather than [47msaved_acl2[0m. [This change is only for Version_7.0, not later versions.] Note that after the next ACL2 release, we might only support [hons-enabled] ACL2 builds. See also [note-7-0-books] for a summary of changes made to the ACL2 Community Books since ACL2 6.5, including the build system. Changes to Existing Features Three new theorems have been built into ACL2 to allow some additional simple arithmetic reasoning. For example, the following failed before this change, typically causing the user to include an arithmetic book; but that is no longer necessary. (thm (implies (natp x) (equal (expt 2 (+ 1 -1 x)) (expt 2 x)))) Thanks to Jared Davis for suggesting these, and for providing seven small modifications to the community books to keep proofs from failing after the changes. (So, if you have a proof failure involving `plus' ([47m+[0m) that formerly succeeded, consider disabling one or more of these rules.) Here are the three new built-in theorems. [31;1mTheorem: [0m<commutativity-2-of-+> (defthm commutativity-2-of-+ (equal (+ x (+ y z)) (+ y (+ x z)))) [31;1mTheorem: [0m<fold-consts-in-+> (defthm fold-consts-in-+ (implies (and (syntaxp (quotep x)) (syntaxp (quotep y))) (equal (+ x (+ y z)) (+ (+ x y) z)))) [31;1mTheorem: [0m<distributivity-of-minus-over-+> (defthm distributivity-of-minus-over-+ (equal (- (+ x y)) (+ (- x) (- y)))) [Type-set] reasoning has been improved for a few built-in functions, including [47mfirst-n-ac[0m, [47m[substitute][0m, [47m[nthcdr][0m, and [47m[subseq][0m, and thus for some functions whose computed type depends on one of these: for example, [47m[take][0m and therefore, also [47m[butlast][0m and [47m[subseq-list][0m, are now known to return [47m[true-listp][0m results. Thanks to Jared Davis for a request that led us to these changes. In particular, the definitions of [47mfirst-n-ac[0m and [47msubstitute-ac[0m have been modified to call [47m[revappend][0m instead of [47m[reverse][0m, and the following [47m:[0m[47m[type-prescription][0m rules have been added to source file [47maxioms.lisp[0m (and can be seen using [47m:[0m[pe]). * true-listp-first-n-ac-type-prescription * stringp-substitute-type-prescription * true-listp-substitute-type-prescription * true-listp-nthcdr-type-prescription * stringp-subseq-type-prescription * true-listp-subseq-type-prescription Technical note on the above change: in some cases, the built-in [47m:[0m[47m[type-prescription][0m rule has been changed, essentially for the better, but new rules have also been added. Consider for example the function, [47m[substitute][0m. This function calls [47msubstitute-ac[0m, which in turn now calls [47m[revappend][0m instead of [47m[reverse][0m, which allows ACL2 to deduce a [47m:type-prescription[0m rule saying that [47msubstitute[0m returns a string or a true-list. However, new [47m:type-prescription[0m rules [47mstringp-substitute-type-prescription[0m and [47mtrue-listp-substitute-type-prescription[0m allow the stronger conclusion that [47msubstitute[0m returns a string or true-list, respectively depending on whether [type-set] reasoning can deduce that the given sequence is or is not a string. The deduced [47m:type-prescription[0m rule can still be of some use in cases that type-set reasoning cannot establish whether or not the input sequence is a string. We removed support for processing legacy [documentation] strings (those starting with [47m":Doc-Section"[0m), since the [xdoc] system has been stable for some time. Thanks to Jared Davis for assisting in that effort and to David Rager for his encouragement. The ACL2 system and [community-books] still have code to support such processing, but it is essentially commented out: specifically, each such piece of code is prefixed by [47m#+acl2-legacy-doc[0m. We expect to delete such code entirely before the next release. The [47m[with-output][0m macro now takes a new keyword, [47m:evisc[0m, that specifies [evisc-tuple]s. Thanks to Warren Hunt for requesting a way to submit [47m[defun][0m forms in a way that avoids printing large [guard] goals during guard verification. The following example illustrates a way to arrange this. (defmacro defun/ (&rest args) (mv-let (evisc args) (cond ((eq (car args) :evisc) (mv (cadr args) (cddr args))) (t (mv '(:gag-mode (evisc-tuple 3 4 nil nil)) args))) `(with-output :evisc ,evisc (defun ,@args)))) ; example: (defun/ h (x) (declare (xargs :guard t)) (append (cons (make-list 10) x) x)) The utility [47m:[0m[47m[pl2][0m no longer automatically instantiates free variables; similarly for calls of [47m:[0m[47m[pl][0m on a term. Thanks to Eric Smith for sending an example showing the problem with the previous implementation. When the [ld-evisc-tuple] is non-[47mnil[0m, the utilities [47m:[0m[47m[pe][0m, [47m:[0m[47m[pc][0m, and [47m:[0m[47m[pcb!][0m now abbreviate their output accordingly. See [set-evisc-tuple]. Thanks to David Rager for bringing the need for this change to our attention. The utility [47m[disabledp][0m now accepts runic abbreviations such as [47m(:d append)[0m. (See [theories] for a discussion of runic abbreviations.) Thanks to Shilpi Goel for requesting this enhancement. Gc-verbose now takes an optional second argument, which is only relevant when the host Lisp is CCL, where that argument specifies verbosity for EGC. Nests of [47m[car][0m and [47m[cdr][0m calls are now printed (``untranslated'') differently. The old method availed itself of all 28 of the car-cdr macros. The new method only introduces 6 of them: [47mcadr[0m, [47mcaddr[0m, [47mcadddr[0m, [47mcddr[0m, [47mcdddr[0m, [47mcddddr[0m. It never introduces such macros as [47mcaar[0m or [47mcddaar[0m, preferring [47mcar[0ms and [47mcdr[0ms when necessary. Lisp programmers tend to recognize [47mcadr[0m, [47mcaddr[0m, and [47mcadddr[0m as the accessors for the 1st, 2nd, and 3rd (0-based) elements of a list. See community book [47mbooks/system/untranslate-car-cdr.lisp[0m for further discussion and a correctness proof. It is now possible to create more efficient [47m:[0m[47m[meta][0m rules by writing metafunctions that create ``implicit hypotheses.'' See [meta-implicit-hypothesis]. We improved a few built in rules: [47mlower-case-p-char-downcase[0m, [47mupper-case-p-char-upcase[0m, [47mlower-case-p-forward-to-alpha-char-p[0m, and [47mupper-case-p-forward-to-alpha-char-p[0m. We also improved the rule [47malpha-char-p-forward-to-characterp[0m by replacing it with two rules, [47malpha-char-p-forward-to-standard-char-p[0m and [47mstandard-char-p-forward-to-characterp[0m. The new rules are, as before, in ACL2 source file [47maxioms.lisp[0m. The reader macro sharp-comma ([47m#,[0m), which has been deprecated since ACL2 Version 3.5 (May, 2009), has been eliminated. Use sharp-dot ([47m#.[0m) instead; see [sharp-dot-reader]. A [47m[defthm][0m or [47m[defaxiom][0m event is now redundant when there is already a syntactically identical event in the logical [world], even if the rules suggested by the two [events] differ. See [redundant-events]. Thanks to Jared Davis and Sol Swords for sending the following example, which illustrates the change. Previously, the final event was not redundant, and hence failed. Now, it is redundant, even though the [47m:typed-term[0m suggested by the new [47m[type-prescription][0m rule is [47m(booleanp (foop x))[0m where the existing rule's [47m:typed-term[0m is [47m(foop x)[0m. (defund foop (x) (consp x)) (defthm booleanp-of-foop (booleanp (foop x)) :rule-classes :type-prescription) (in-theory (disable booleanp-compound-recognizer)) (defthm booleanp-of-foop (booleanp (foop x)) :rule-classes :type-prescription) In the case that summary output is inhibited but error output is not (see [set-inhibited-summary-types]), failed [events] did not print an error message. Now they do. When a call of [encapsulate] with empty [signature] introduces no [events], it now has no effect on the ACL2 logical [world]. Formerly, such an [encapsulate] form would create an event even in this case. For example, the form [47m(encapsulate nil (local (defun f (x) x)))[0m formerly created an event in the world, as well as a [command] when executed at the top-level; but now it is truly a no-op. See [encapsulate]. Note: An idiom sometimes used for testing is [47m(encapsulate () (local ...) (local ...) ...)[0m, that is, a trivial encapsulate where each sub-event is [local]. With this change, that idiom is now properly supported. (Formerly, the second such encapsulate was considered redundant with the first; but that is no longer the case, since the first will not be stored in the [world].) We replaced an error with a warning for cases where a classic [congruence] rule is unnecessary. Thanks to Jared Davis for sending us an example suggesting the need for a change. (See ACL2 source function [47mchk-acceptable-congruence-rule[0m for his example and more explanation.) We removed support for three [47m[declare][0m forms that had been permitted in ACL2(h) only, but were not advertised: [47mdynamic-extent[0m, [47minline[0m and [47mnotinline[0m, because they seem difficult or impossible to support correctly. For alternatives to using [47minline[0m and [47mnotinline[0m declarations, see [defun-inline] and [defun-notinline]. The nu-rewriter contained special provisions for rewriting expressions composed of [47m[nth][0m, [47m[update-nth][0m, and [47m[update-nth-array][0m, together with [47m[let][0m expressions and other applications of non-recursive functions or [47m[lambda][0m expressions. An email query was sent to the acl2 mailing list on 10/24/2014, giving people an opportunity to object to the removal of this feature. Nobody objected, so we have removed it in order to simplify the ACL2 code base. Thanks to David Rager for suggesting this sort of code clean-up. Note that some system functions, for example [47mall-equal[0m, have been deleted in support of this change. [Guard]s have been added for some system functions that support the implementation of the [tau-system]: [47mlower-bound-<=[0m, [47mupper-bound->=[0m, [47mlower-bound->[0m, [47mupper-bound-<[0m, and [47msqueeze-k[0m. Thanks to Dmitry Nadezhin for supplying these improvements (which he also used in modifications to the community book, [47mbooks/tau/bounders/elementary-bounders.lisp[0m). New Features The new command [47m:btm[0m has been added to the list of valid [brr-commands], to show the bottom-most frame in the path. Thanks to David Rager for requesting this feature. A new [47m[xargs][0m keyword, [47m:[0m[47m[measure-debug][0m, decorates each termination proof goal with [47m[extra-info][0m calls that show the source of the goal. Thanks to Jared Davis (first in 2008!), Sol Swords, and Anna Slobodova for requesting this feature. A new reader macro, [47m#{"""..."""}[0m, has been contributed by Jared Davis to support the writing of strings without escape characters. See his community book [47mbooks/system/fancy-string-reader-test.lisp[0m for examples. (For those who program in raw Lisp) A new Lisp variable, [47m*hard-error-is-error*[0m, has a default of [47mnil[0m that preserves existing behavior; but it can be set to a non-[47mnil[0m value in order to cause so-called ACL2 ``hard errors'' to result in Lisp errors whose condition, when printed with [47mformat[0m directive [47m~a[0m, is the same error message that ACL2 would otherwise print. See [hard-error]. Thanks to Jared Davis for requesting this feature. A new value for [47m[include-book][0m keyword argument [47m:uncertified-okp[0m is [47m:ignore-certs[0m, which specifies that all certificate files are to be ignored during inclusion of this book and all of its sub-books. See [include-book]. Thanks to Sol Swords for requesting this feature and for helpful discussions on its details. Efficiency Improvements The heuristics have changed for guessing the [47m:typed-term[0m field for a [47m:[0m[47m[type-prescription][0m rule when that field is not explicitly specified. Specifically, consider the case that the conclusion of the rule is a function call [47m(p u)[0m for some term [47mu[0m, such that there is an enabled [47m[compound-recognizer][0m rule for [47mp[0m. Formerly, the [47m:typed-term[0m was [47mu[0m in this case. Now, it must be the case that the most recent enabled such [47m[compound-recognizer][0m rule is `strong', in the following sense: if [47mts1[0m is the [type-set] implied by assuming the conclusion true and if [47mts2[0m is the [type-set] implied by assuming the conclusion false, then [47mts1[0m and [47mts2[0m are complementary. Thanks to Jared Davis for an email that prompted us to make this change. We have made several efficiency improvements (arguably heuristic in nature), which may apply in many settings but especially in handling of several forms during the execution of [47m[include-book][0m --- most notably [47mwith-output[0m forms, as [47m(with-output ... FORM)[0m is now essentially just [47mFORM[0m during [47minclude-book[0m. For some details, including statistics showing up to 1/3 of [47m[include-book][0m time eliminated by these changes (and even significant time saved outside [47minclude-book[0m), see the comment about ``efficiency improvements'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-7-0 ...)[0m. Thanks to Sol Swords for noticing inefficiencies that led us to these improvements, and for helpful discussions. The [dmr] utility has been made much more efficient, yielding a performance penalty of perhaps 10% instead of perhaps more than a factor of 30 (3000%). We made a low-level implementation tweak that resulted in a speed-up of 2.6% in wall-clock time for a CCL-based regression (using ``[47mmake[0m'' with [47m-j 8[0m and target ``everything''). (Technical note: We eliminated the Lisp special variable [47m*attached-fn-called*[0m, using another variable [47m*aokp*[0m instead. Special variable bindings can apparently be expensive!) Some space has been saved in ACL2 executables by avoiding the duplication of certain constants. Specifically: for each event [47m(defconst name (quote val))[0m in the ACL2 source files, [47mval[0m is stored in the Lisp image in several places, but not all of these had been identical: they were all [47m[equal][0m, but not all [47m[eq][0m. (We believe that these were already all [47meq[0m for user-defined [47m[defconst][0m events.) For example, in Linux builds of ACL2(h) on host Lisp CCL, we have seen a space saving of approximately 18.9 MB, which is 12.6%. Thanks to Jared Davis for pointing out duplicate strings that he noticed using his [spacewalk] tool. Bug Fixes We fixed two bugs in [47m[spec-mv-let][0m. The first was pointed out to us by Jared Davis using essentially the following example, where the result should be [47mnil[0m given that [47mspec-mv-let[0m is intended to have the semantics of [47m[mv?-let][0m. ACL2 !>(set-ignore-ok t) T ACL2 !>(let ((a t) (xval nil)) (spec-mv-let (yval) xval (mv?-let (xval) a (if xval yval nil)))) T ACL2 !> The second [47m[spec-mv-let][0m bug was to allow the two lists of bound variables to intersect. In the following example, given that [47mspec-mv-let[0m is semantically just [47mmv?-let[0m, the result should have been 46, not 34. This has been fixed. Thanks to David Rager for encouraging these two fixes and checking them over. ACL2 !>(set-ignore-ok t) T ACL2 !>(spec-mv-let (x) 17 (mv?-let (x) 23 (if t (+ x x) "bad"))) 34 ACL2 !> The guard for function [alpha-char-p] was strengthened to require that its argument is a standard character. The previous guard required only that the argument is a character, and was a soundness bug; for a proof of [47mnil[0m before this fix, see the comment about ``alpha-char-p'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-7-0 ...)[0m. Errors were possible when evaluating functions [47m[pkg-imports][0m and [47m[pkg-witness][0m while including a book with a compiled (or expansion) file. Such errors have been eliminated. Fixed a bug in [47moracle-apply-raw[0m. (GCL CLtL1 only) Fixed a bug that was preventing [47m[set-debugger-enable][0m from taking full effect in non-ANSI GCL. (GCL only) The utility [47m[gc-verbose][0m was broken, but has been fixed. Fixed a bug in [provisional-certification] that incorrectly caused an error during the convert step for [47m[verify-guards+][0m forms. More generally, this error occurred when encountering a [47m[make-event][0m form with a non-[47mnil[0m value supplied for the [47m:expansion?[0m keyword. Thanks to David Rager for reporting this bug. A raw Lisp error could occur with [guard]-checking turned off, because type declarations were mistakenly left in the executable counterparts (so-called ``*1* functions'') when ACL2 processed function definitions. The following example shows how a type violation could occur in some Lisps (we saw this in SBCL but not in CCL, for example). (defun f (x) (declare (xargs :guard (natp x))) (let ((y (1+ x))) (declare (type (integer 0 *) y)) y)) (set-guard-checking nil) ; Possible raw Lisp error: ; "The value -2 is not of type UNSIGNED-BYTE." (f -3) Thanks to Jared Davis for sending us an example that brought this bug to our attention. Fixed a bug that was causing a low-level assertion, saying: ``Implementation error: see 'replace-free-rw-cache-entry.'' Thanks to Anna Slobodova for bringing this bug to our attention via an example, and to Sol Swords for simplifying that example. The [iprint] feature, which allows abbreviated output to be read back in, did not work as one might expect when using the [break-rewrite] feature (see [brr]). Thanks to David Rager for reporting this problem. More generally: the problem was that values associated with [iprint] indices during a [wormhole], for example after breaking on a [rewrite] rule, were forgotten when exiting the wormhole. (Technical note for those interested: the fix restores the main iprinting structure after exiting a wormhole, just before reading the next top-level form. That restoration uses raw Lisp, with logic-only code based on [47m[read-ACL2-oracle][0m.) The example below failed before the fix but now works. (set-evisc-tuple (evisc-tuple 3 3 nil nil) :iprint t :sites :all) (defthm my-rule (equal (car (cons x x)) x)) (brr t) (monitor '(:rewrite my-rule) t) (thm (equal (car (cons a a)) a) :hints (("Goal" :do-not '(preprocess)))) ; Now entering a :brr break: (make-list 10) ; printed without evisceration ; Set evisceration with iprinting: (set-evisc-tuple (evisc-tuple 3 3 nil nil) :iprint t :sites :all) (make-list 10) ; printed with evisceration (a!) ; quit break-rewrite ; The following formerly caused a hard Lisp error, because although #@3# ; was printed in the output from (make-list 10) just above, iprint index 3 ; was lost when exiting the break-rewrite wormhole. Now, this works ; because iprinting information from the wormhole is retained. '#@3# There was a bug in how so-called ``hidden packages'' were handled by [47m[encapsulate][0m forms (see [hidden-death-package]), which was preventing package axioms from being visible in certain contexts. (Technical remark: packages that were hidden after the second pass but not the first were treated as not-hidden, even though their package axioms were not introduced.) That, in turn, could cause an [47m[include-book][0m form to fail when the book contains a [47m[deftheory-static][0m form. Here is an example failure. First, in a fresh ACL2 session evaluate the form [47m(defpkg "FOO" nil)[0m and then evaluate the form [47m(certify-book "foo" 1)[0m, where file [47mfoo.lisp[0m is as follows. (in-package "ACL2") (defun foo::foo (x) x) (deftheory-static foo-theory (current-theory :here)) Now evaluate the following sequence of forms. In previous versions of ACL2, the final ([47m[include-book][0m) form failed. (encapsulate () (local (include-book "foo")) (defun h (x) x)) (encapsulate () (local (include-book "foo")) (defun h2 (x) x)) (include-book "foo") ; failed before the fix We have cleaned up handling of interrupts and aborts when inside the [break-rewrite] loop, or indeed any [wormhole]. Thanks to David Russinoff for bringing to our attention a case in which ACL2 quit a proof with ``Aborting due to an interrupt'' when in fact no interrupts had taken place. Here is an example where that no longer happens but did, previously. (For a different example, see the comment in the ACL2 sources definition of macro [47mbind-acl2-time-limit[0m.) (defun foo (x) (cons x x)) (brr t) (monitor '(:definition foo) t) (thm (equal (foo y) z)) (defun h (x) (declare (xargs :mode :program)) (car x)) ; Raw Lisp error: (h 3) ; Previously, unexpected proof abort "due to interrupt": (thm (equal (append (append x y) x y) (append x y x y))) When aborting with [47m:[0m[47m[a!][0m inside the [break-rewrite] loop from within the [proof-builder], a raw Lisp error could subsequently occur saying, ``Attempt to execute *wormhole-cleanup-form* twice!''. This has been fixed. Thanks to Sol Swords for reporting a bug in our original fix. Here is an example that formerly caused that behavior. (defthm silly (implies (null x) (equal (append x y) y))) (defconst *c* (make-list 10)) :brr t :monitor (:rewrite silly) t (verify (equal (append x (append *c* y)) (append y (append *c* x)))) bash :go :a! bash ; formerly caused error The utility [47m[redo-flat][0m no longer worked when interrupting a proof (with Control-c), due to a bug in Version 7.0. This has been fixed. Thanks to Dave Greve for reporting this problem. Changes at the System Level As mentioned near the top of this [documentation] topic, default builds of ACL2 are now [hons-enabled]. (GCL only) GCL Versions prior to 2.6.12 are no longer supported. Modified code used in distributing Debian releases that allows books certified in one directory to be distributed in another. This change, together with the fact that such relocation is [31;1mnot[0m truly supported, is explained in comments in source function [47mmake-certificate-file-relocated[0m. Thanks to Camm Maguire for discussions leading to this change. (GCL only) Modified how home directory is calculated. Thanks to Camm Maguire for help in making this change. (SBCL only) Fixed a check done at build time that was preventing builds in SBCL 1.2.2 because of its new backquote implementation. Thanks to Harsh Raju Chamarthi and Pete Manolios for bringing this issue to our attention. Development snapshots of ACL2 (and of the [community-books]) are now available between releases from {an ACL2 github repository | https://github.com/acl2/acl2}; they are no longer available via svn. Thanks to David Rager and Jared Davis for taking the lead on this conversion. As a result, the banner printed at startup for those snapshots has changed slightly. For a quick start guide for using git with ACL2, see [git-quick-start]. (CCL only) Control-d now quits ACL2 in raw Lisp just as it has done for a long time in the loop and, for ACL2(h) (i.e., [hons-enabled] ACL2), even in raw Lisp. (Should essentially affect GCL only) Significant re-work has been done for function proclaiming, which is still only done when the host Lisp is GCL. In particular, the build process now has extra steps even for other Lisps though for them, the extra steps are trivial (technical details may be found in the comment labeled ``Essay on Proclaiming'' in source file acl2-fns.lisp). We now use GCL's automatic proclaiming mechanism to calculate function types during the build (boot-strap), as we have seen it perform better than our own. Thanks to Camm Maguire for helpful discussions, in particular for explaining that mechanism and for pointing out that the re-proclaiming that had been done previously during the build could lead to buggy behavior. For Makefile targets for testing such as [47mregression[0m, the default ACL2 image used is now the same one that would be built for the same Makefile variables. In particular, the command [47mmake regression[0m is equivalent to [47mmake regression ACL2_HONS=h[0m, which uses the executable [47msaved_acl2h[0m, not [47msaved_acl2[0m as was formerly the case. Thanks to Harsh Raju Chamarthi for finding a bug in a first attempt to make this change. EMACS Support Hons-enabled and Experimental Versions (For [hons-enabled] executables only) Fixed a soundness bug related to function memoization. For a proof of [47mnil[0m exploiting this bug in Version 6.5, see the comment about ``pons-addr-of-argument'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-7-0 ...)[0m. Thanks to Jared Davis for improving our original fix: by noting its applicability to [47m[hons-clear][0m (not just [47m[hons-wash][0m); by tweaking our fix so that it works even if a [47mcontrol-c[0m interrupts ([47mhons-clear[0m or) [47mhons-wash[0m; and later by finding another bug in source function [47mpons-addr-of-argument[0m and suggesting a fix, which we incorporated. (For [hons-enabled] executables only) Fixed a soundness bug due to the fact that function [47mnever-memoize-fn[0m returned [47mnil[0m in the logic but returned [47mt[0m in raw Lisp. For a proof of [47mnil[0m exploiting this bug in Version 6.5, see the comment about ``never-memoize-fn'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-7-0 ...)[0m. Static honsing for [hons-enabled] ACL2, an efficiency enhancement formerly only available for CCL, is now incorporated into builds on sufficiently recent GCL versions. ACL2 executables that were [hons-enabled] could fail to use previously-compiled definitions for [47m[memoize][0md functions when [47m[include-book][0m is invoked. This has been fixed. (For [hons-enabled] executables only built on other than CCL or SBCL) Calls of [47m[memoize][0m only compile the memoized definition when the original function is compiled, rather than unconditionally as before. Several changes been made to function memoization (see [memoize]). Here is a list of changes visible at the user level; for implementation details, see [note-7-0-memoize]. * It is now legal to call [47m[memoize][0m on functions with special raw-Lisp code (such as [47m[len][0m) provided the value of the [47m:inline[0m keyword argument is [47mnil[0m. * Bug fix: Fixed bug that was making [47m[memsum][0m attribute the count of making of hash tables to ``Heap bytes allocated'' instead of to ``Number of calls to mht.'' * Memoize keyword [47m:trace[0m is no longer supported, as the [47m[trace$][0m utility provides much more flexibility. * Bug fix: Fixed a bug in handling of the [47m:commutative[0m argument of [47m[memoize][0m that could cause a hard Lisp error. For a book that exhibits this bug, see the comment about ``:commutative'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-0 ...)[0m. * When [47m[memoize][0m is called with keyword argument [47m:commutative[0m having value [47mt[0m, the benefit of that argument can apply to rational number arguments even when not using static honsing. Moreover, now only one argument needs to be a rational or to be ``static'' according to the implementation (technically: to have an [47mhl-staticp[0m value). * Bug fix: Calls of [47m[memoize][0m with keyword argument [47m:commutative t[0m were sometimes inappropriately treated as redundant [redundant-events]. This has been fixed. Here is a simple example of what formerly went wrong. (defn f (x y) (equal x y)) (memoize 'f :commutative t) (unmemoize 'f) (memoize 'f :commutative t) ; was redundant, so did not memoize * (For those who memoized directly in raw Lisp) [47mMemoize-fn[0m now requires its first argument to be a defined (fboundp) function symbol. (It seemed odd and needlessly arcane to allow memoize-fn to define an undefined function.) * (For those who memoized directly in raw Lisp) [47mMemoize-fn[0m now causes an error when it fails. * Bug fix: It had been possible to lose a memoization setting of [47m:aokp t[0m when many functions were memoized. For an example, see the comment about ``rememoize-all'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-0 ...)[0m. * We eliminated undocumented utilities [47mmemoize-on[0m and [47mmemoize-off[0m, which were not used as far as we know. * When a memoized function call fails to satisfy the specified condition, that call is no longer counted as a ``hit'', at least by default. This can be changed with raw Lisp variable, [47m*condition-nil-as-hit*[0m. * The utility [47m[memsum][0m had reported one more pons call and (CCL only) one more byte than was correct, and could perhaps report one call when there were actually zero. That has all been fixed. * Bug fix: Some sorting of results based on ``self'' time and ``other functions'' time had been wrong. (Technical remark: the problem was that the implementation confused ``ticks'' with ``time''.) This has been fixed. * Statistics reporting (see [memsum]) often has a more uniform look. It is now done with a right margin of 79 instead of 70. For [47m[memsum][0m, thanks to a suggestion from Warren Hunt, the [47mdefun[0m formerly printed to start each entry is now omitted, and after the name is printed at the start, a newline is printed before the ``hits'' or ``hits/calls'' information is printed. A related change: when [47m*report-hits*[0m and [47m*report-calls*[0m are both [47mnil[0m, ``calls'' is no longer printed. Other cosmetic changes were also made to [47m[memsum][0m output. * The output from [47m[memsum][0m on the line ``Time of all outermost calls'' no longer includes a percentage, which had been at best misleading and at worst nonsensical. Suppose for example that [47mf[0m calls [47mg[0m, which does all the work. Then [47mmemsum[0m had reported 50% of the ``Time of all outermost calls'' for each of [47mf[0m and [47mg[0m, even though 100% of the time was spent under each. * On Mac OS (Darwin), the physical memory is now accurately computed (using shell command ``sysctl hw.memsize'', which works in some versions of Mac OS, maybe all recent ones; tested on 10.6 and 10.7). Before, the physical memory value had been assumed to be 2^32 bytes. The physical memory value is used in CCL for triggering garbage collections. (Technical remark: this is implemented in function [47mstart-sol-gc[0m.) * Bug fix: in the pons summary, misses had been reported instead of hits on the ``hits/calls'' line. * Fixed [47m[memsum][0m so that package names are printed with the symbols. Also, printing is done with respect to the current package, not the [47m"ACL2"[0m package. * It is now legal to [profile] functions that take [47m[state][0m as an argument. Thanks to Sol Swords for requesting this change. In the course of making this change, we took a conservative approach and put the same requirement regarding illegal memoization of functions involving user-defined [47m[stobj][0ms: that is, when memoization must have value [47mnil[0m for the [47m:condition[0m keyword, it must also have value [47mnil[0m for the [47m:inline[0m keyword. We can perhaps remove this additional restriction if necessary. * For every built-in memoized function defined in the ACL2 logic, the memoization is done in the usual way (during the ACL2 build), using the [47m[memoize][0m event during the ACL2 build. Such functions can thus be [47m[unmemoize][0md by users in the usual way. Thanks to David Rager for requesting this enhancement. * A new [47mmemoize[0m keyword, [47m:stats[0m, can control whether statistics will be saved for reporting with [47m(memsum)[0m. * Memoization in [hons-enabled] ACL2(p) is no longer affected by calls of [47m[set-waterfall-parallelism][0m. (ACL2(p) only, either [hons-enabled] or not) The function [Cpu-core-count] is now sensitive to environment variable [47mACL2_CORE_COUNT[0m. See [cpu-core-count]. Thanks to Jared Davis for requesting this enhancement. Support for multi-threading has been added for memoization. Thanks to Jared Davis for contributing an initial implementation. Note that this may slow down [hons-enabled] ACL2(p) by several percent on memoization-intensive applications. Undocumented function [47mmf-multiprocessing[0m is available for low-level system hackers to turn on/off this feature, which by default is off for [hons-enabled] ACL2 and on for [hons-enabled] ACL2(p). (ACL2(p) only, either [hons-enabled] or not) We fixed a bug in [47m[pand][0m, which we believe was also a bug in [47m[por][0m, [47m[pargs][0m, and [47m[plet][0m. (Technical remark: this bug had a low-level cause, pertaining to maintenance of a Lisp variable, [47m*ld-level*[0m, that holds the number of nested calls of [47m[ld][0m.) Thanks to Jared Davis for reporting this bug and to David Rager for assisting in its repair. Below is a slightly simplified version of Jared's example, which formerly caused an assertion error but now works as expected. (defmacro pand* (x y) `(spec-mv-let (yval) ,y (mv?-let (xval) ,x (if xval yval nil)))) (defn f3 (x) (pand* x x)) (defn f4 (x) (pand x (f3 x))) (value-triple (f4 5)) (Only for [hons-enabled] executables on Windows) Certain memory management is avoided on Windows (technically: by avoiding a call of source function [47mstart-sol-gc[0m), where it was causing errors. Thanks to Harsh Raju Chamarthi and Sol Swords for testing on Windows that led us to this change. Subtopics [Note-7-0-memoize] ACL2 Version 7.0 Notes on Changes to Memoization Implementation") (note-7-0-memoize (note-7-0) "ACL2 Version 7.0 Notes on Changes to Memoization Implementation See [memoize] for a user-level introduction to function memoization. Here we summarize technical changes made in Version 7.0 of ACL2 to the implementation of function memoization; most ACL2 users should have no need to read further in this topic. We thank Jared Davis for helpful conversations. The function [47mmemoize-init[0m now resets the table [47m*memo-max-sizes*[0m, which is used when creating memo tables and pons tables. This change may be irrelevant, since generally memoize-init is only called at startup. But it seemed appropriate to reset it along with all other globals involved in the memoization implementation. Lisp variable *print-pretty* is no longer globally set to [47mt[0m by certain memoization code. Probably this change will not generally be observable. The utility [47m[clear-memoize-statistics][0m now resets data for the pons summary, but implementation function [47mclear-memo-tables[0m no longer does so (it only calls [47mclear-memoize-tables[0m). Avoided some recklessness in computing statistics related to ponsing (specifically, replaced [47mvery-unsafe-incf[0m by macro [47msafe-incf-pons[0m, which is a wrapper for [47msafe-incf[0m). [47mClear-memo-tables[0m no longer takes [47m&rest[0m arguments, since it is merely a wrapper for [47m[clear-memoize-tables][0m, which does not (and did not) take [47m&rest[0m arguments. For the utility [47mpons-summary[0m, we no longer use [47mour-syntax-nice[0m; so far example, [47m*print-case*[0m is not bound to [47m:downcase[0m. Function [47minternal-real-ticks[0m (formerly [47minternal-real-time[0m) now uses [47m[logand][0m in its implementation, which should improve performance. It also replaces, for non-static-hons implementations, the call [47m(get-internal-real-time)[0m by [47m(the mfixnum (get-internal-real-time))[0m, which can also help performance. More principled, consistent use is made of [47mour-syntax[0m for suitable printing. Added ``TO DO'' comments near the top of source file [47mmemoize-raw.lisp[0m. Thanks to Jared Davis for suggesting some of these. We improved many comments in source file [47mmemoize-raw.lisp[0m. We did some renaming, including the following (note that this is probably not a complete list): - number-of-arguments -> mf-len-inputs - number-of-return-values -> mf-len-outputs - *compute-array* -> *callers-array* - maybe-count-pons-calls -> incf-pons-calls - maybe-count-pons-misses -> incf-pons-misses - print-alist -> mf-print-alist - shorten -> mf-shorten - outside-p -> outside-caller-p - ofni -> mf-make-symbol - ofnum -> mf-num-to-string - internal-real-time -> internal-real-ticks - dcls -> mf-dcls - hl-without-interrupts -> without-interrupts [which already existed] - *ma-initial-max-symbol-to-fixnum* -> *initial-max-symbol-to-fixnum* - REPLACEMENT: *initial-max-memoize-fns* -> *initial-2max-memoize-fns* We eliminated some dead code, including the following functions (probably not a complete list): [47mour-syntax-brief[0m, [47mofnm[0m, [47muses-state[0m, [47mglobal-restore-memoize[0m, [47mprine-alist[0m, [47mset-gc-threshold[0m, [47mour-gctime[0m, and [47mshort-symbol-name[0m, and all variants of format functions with names starting with "of" except for [47mofni[0m (now [47mmf-make-symbol[0m) and [47mofnum[0m (now [47mmf-num-to-string[0m). Also, we moved [47mmemoize-here-come[0m to community book [47mbooks/centaur/memoize/old/profile-raw.lsp[0m. Regarding [47mour-syntax-brief[0m: there had been one call, in [47mprint-call-stack[0m, but that call did not seem appropriate so we deleted it. The variable [47m*count-pons-calls*[0m was deleted. It had been set to [47mt[0m and was only used during macroexpansion of [47mincf-pons-calls[0m and [47mincf-pons-misses[0m (formerly [47mmaybe-count-pons-calls[0m and [47mmaybe-count-pons-misses[0m), where that macroexpansion was done at ACL2 build time --- hence user setting of [47m*count-pons-calls*[0m had no effect. We eliminated a needless error check that prevented loading [47mmemoize-raw.lisp[0m without [47m#+hons[0m, since we don't currently ever expect to try to do that. Miscellaneous additional code cleanup has been done. Here is a (probably very incomplete) list. * [47mFloat-ticks/second-init[0m uses a default rather than duplicating the default's code, and has improved treatment of errors. * Removed unused [47m:before[0m field of [47mmemoize-info-ht-entry[0m record. * The implementations of [47mnumber-of-arguments[0m and [47mnumber-of-return-values[0m (now called [47mmf-len-inputs[0m and [47mmf-len-outputs[0m, respectively) have been made cleaner, in particular, starting with an empty [47m*number-of-arguments-and-values-ht*[0m. * New macros such as [47mma-index[0m provide some abstraction, to give the illusion that [47m*memoize-call-array*[0m is two-dimensional. * We broke up some definitions, in particular substantially shortening [47mmemoize-fn[0m by moving parts of it into new functions [47mmemoize-fn-inner-body[0m, [47mmemoize-fn-outer-body[0m, and [47mmemoize-fn-def[0m. A benefit: it is easy to see the definition that is actually created when memoizing, by tracing [47mmemoize-fn-def[0m. * Added raw Lisp interface function [47mmf-note-arity[0m for informing [47mmemoize-fn[0m of input and output arities. * [47mCoerce-index[0m asserts that an index is in range rather than treating an out-of-range index as a symbol. * We renamed some variables to make them clearer. In particular, it is whether a variable stores time or ticks. * We now make complete and correct (we hope) the use of suitable [47mfixnum[0m and [47mmfixnum[0m declarations, many of which had been missing or incorrect. * Both [47m[memoize][0m and [47m[unmemoize][0m are now safe for control-c and unexpected errors. * We no longer set [47mccl::*save-definitions*[0m or [47mccl::*fasl-save-definitions*[0m to [47mt[0m. This may improve performance, but it may require explicitly calling [47mmf-note-arity[0m, as is now done in [47mbooks/centaur/aig/bddify.lisp[0m. However, this removes CCL-only behavior; in particular, we removed dependence on #+Clozure in [47mbooks/centaur/aig/bddify.lisp[0m for profiling [47mcount-branches-to[0m. * We use [47m#+ccl[0m instead of [47m#+Clozure[0m, for consistency with most of the rest of ACL2. * We no longer set [47mccl::*save-source-locations*[0m or [47mccl::*record-source-file*[0m to [47mt[0m, as there is no clear advantage to doing so, and in fact there is a comment near the end of source file [47macl2.lisp[0m suggesting that there could be slowdown from setting (at least) the first of these variables to [47mt[0m. * We slightly modified [47minternal-real-time[0m to improve its performance (see comments there). * We fixed a performance bug in function [47maddr-for[0m (parenthesis error was needlessly putting us in the ``large-case''). * Fixed a typo: declaim of fixnum type for [47m*initial-max-memoize-fns*[0m had instead been for nonexistent variable [47m*initial-2max-memoize-fns*[0m. * In [47mmemoize-fn[0m, we removed support for [47m:condition[0m to be a function symbol, which was at best confused. * The table [47m*never-memoize-ht*[0m is now populated mostly automatically, by [47minitialize-never-memoize-ht[0m. * Slight optimization: the form [47m(update-attached-fn-called ,*attached-fn-temp*)[0m, which had been in the definition of [47mmemoize-fn[0m but now is in [47mmemoize-fn-inner-body[0m, is conditioned on [47m,*attached-fn-temp*[0m.") (note-7-1 (release-notes) "ACL2 Version 7.1 (May, 2015) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 7.0 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. The default build is [hons-enabled], as for the previous release; but the generated executable is now [47msaved_acl2[0m, as discussed below. Please note that ACL2(c) (``classic ACL2'', i.e., ACL2 that is not [hons-enabled]) now builds as [47msaved_acl2c[0m, is deprecated, and will likely be unsupported or even eliminated in future releases. See also [note-7-1-books] for a summary of changes made to the ACL2 Community Books since ACL2 7.0, including the build system. Changes to Existing Features For both [47m[add-include-book-dir][0m and [47m[add-include-book-dir!][0m, the second argument is no longer evaluated (which we think could perhaps have been exploited to get unsound behavior, by arranging for the value of the second argument to depend on [47m[state][0m). Moreover, that argument can not only be a string, but also can be a [3msysfile[0m: an object [47m(:system . filename)[0m, where [47mfilename[0m is a file name. When filename is a relative pathname, the meaning of such an object is the file with that pathname under the system books directory. The event summary had not been printed when a proof is interrupted (that is, with Control-C). Now, summary information is printed for two summary types (see for example [set-inhibited-summary-types]): rules and hint-events. By default, [47m(memsum)[0m is now truncated to 100 entries rather than to 20 entries. (Implementation note: raw Lisp variable [47m*memoize-summary-limit*[0m is 100 instead of 20.) Calls of [47mTHE[0m no longer cause a [guard] violation when guard-checking is [47mnil[0m. Also see [the] and see [set-guard-checking]. Type declarations for [47m[let][0m and [47m[mv-let][0m forms are now [guard]-checked. Consider for example the definition: [47m(defun foo () (let ((x t)) (declare (type integer x)) x))[0m. Previously, evaluation of the call [47m(foo)[0m had failed to result in a guard violation error; now, it does, provided guard-checking is on (i.e., not [47mnil[0m or [47m:none[0m; see [set-guard-checking]). The symbols [47mctx[0m, [47mhist[0m, [47mpspv[0m, [47munquote[0m, and [47mvalue[0m have been added to [47m[*ACL2-exports*][0m. Thanks to Jared Davis for suggesting these additions. Consider [47m:use[0m or [47m:by[0m [hints] in which a variable bound using the [47m:instance[0m keyword is in the wrong package. For example, for the hint [47m:use ((:instance foo (x 3)))[0m, suppose that the lemma [47mfoo[0m mentions the variable [47mbar::x[0m, but not [47mx[0m. This situation formerly caused an error, but now, [47mx[0m indicates the variable [47mbar::x[0m from the lemma [47mfoo[0m. See [lemma-instance], in particular Condition (4), which has been updated accordingly. Thanks to David Rager for a remark that led us to implement this enhancement. The [47m[ld][0m special [47mld-error-action[0m may now have a value [47m(:exit N)[0m, where [47mN[0m is a natural number. If an error occurs for a call of [47mld[0m, then this value causes the ACL2 process to quit with exit status [47mN[0m. See [ld-error-action]. Note that [47mld-error-action[0m is set to this new value when using the [47mcert.pl[0m utility provided with the community books; see [build::pre-certify-book-commands]. Thanks to David Rager for presenting an example showing how this change can make it easier to locate certain certification failures, and thanks to Sol Swords for helping in the design of this enhancement. A "[Theory]" warning is still printed when [definition]s of certain built-in functions, such as [47m[mv-nth][0m, are [disable]d; similarly for some built-in [executable-counterpart] rules. However, we now print such warnings only when the disabling occurs, rather than every time an [47m[in-theory][0m event or hint is evaluated. For example, if you evaluate [47m(in-theory (disable mv-nth))[0m followed by [47m(in-theory (disable append))[0m, then the second event will no longer produce a warning about [47mmv-nth[0m. Thanks to Eric Smith for (most recently) suggesting such a change. (SBCL only) ACL2 built on SBCL now reports bytes usage, both in [47m[time$][0m and in [47m[memsum][0m, essentially exactly as has already been done for ACL2 built on CCL. Thanks to Jared Davis for suggesting this enhancement. (SBCL only) [Fast-alists] can now be garbage collected (we believe) in SBCL, as they had already been done in CCL. (Implementation note: The change was to use weak hash tables in the implementation of SBCL fast-alists.) Thanks to Jared Davis for suggesting this enhancement. The utility [47m[ec-call][0m can now be applied to calls of symbols introduced with [47m[defun-inline][0m, or with [47m[define][0m using keyword argument [47m:inline t[0m, thanks to a request from Jared Davis. For example, the following is now legal. (defun-inline foo (x) (cons x x)) (defun bar (x) (ec-call (foo x))) The [proof-builder] is now sensitive to the current [case-split-limitations]. New Features The Common Lisp function [47m[sleep][0m is now defined in ACL2. Thanks to Jared Davis for requesting this addition. Custom error messages may now be created for guard violations. See [set-guard-msg]. The new macro [47m[assert*][0m is like [47m[assert$][0m, except that [47massert*[0m only generates a [guard] proof obligation, not a runtime check. [47mAssert*[0m is defined using a new macro [mbt*], which is a variant of [47m[mbt][0m: a call of [47mmbt*[0m logically returns [47mt[0m, but generates the same [guard] proof obligation as [47mmbt[0m. Thanks to Shilpi Goel for a query that led us to add these macros. Heuristic and Efficiency Improvements We fixed an inefficiency that could occur in calls of [program]-mode functions that update [stobj]s. See the discussion of invariant-risk in the [documentation] topic, [program-wrapper]. Thanks to Jared Davis for bringing this issue to our attention. We improved the ``worse-than'' heuristic, providing modest speed-up and eliminating the use of memoization for it. Thanks to Jared Davis for useful discussions on the topic, and to Camm Maguire for an observation that led us to do some investigations that led to this improvement. For more information see comments in source function [47mworse-than-builtin-clocked[0m (source file [47mtype-set-b.lisp[0m). We avoid the cost of translating ACL2 terms (see [term]) to user-level syntax after applying the ``preprocess'' simplifier (see [hints-and-the-waterfall]), and also after applying either [47m:use[0m or [47m:by[0m [hints]. Thanks to David Rager for helpful discussions towards this change. Note: On rare occasions, this might change the prover flow as follows. * Consider the case that the input goal, "Goal", simplifies with the ``preprocess'' simplifier to a new goal that prints the same as "Goal". Formerly, this case avoided labeling the new goal as "Goal'"; it was as though the new goal was actually the user input. The new criterion for avoiding "Goal'" is somewhat weaker: the internal syntax must suitably match for "Goal" and its simplification, rather than their displayed forms. * Consider the application of a [47m:use[0m or [47m:by[0m hint. In such cases, the resulting constraint (if any) is simplified with the ``preprocess'' simplifier. Formerly, the rules used by that simplifier were not recorded if the printed version of the simplified constraint was equal to the original constraint, which was really a bug since the comparison was between the user-level syntax of the simplified constraint and the internal syntax of the original constraint. Now, ACL2 compares the internal syntax of each. We fixed an inefficiency that could occur in processing of [47m[make-event][0m forms. Thanks to Sol Swords for reporting and diagnosing the problem. (Technical note: The fix involves avoiding, in most cases, looking up world global [47m'boot-strap-flg[0m by using a new state global instead of the same name.) We changed the heuristics for equality substitution so that so-called [3mcross-fertilization[0m, where an equality substitution is made on only one side of the goal's conclusion, is not made when generalization is turned off, as with the hint [47m:do-not '(generalize)[0m. Instead, the equality is used throughout the goal in that case. Thanks to David Hardin for bringing an example to our attention that led us to make this change. Some clause-building (essentially, goal-building) operations already avoided duplication, but now consider clauses to be ``duplicates'' when the only difference is commuted arguments of [47m[equal][0m or [47m[iff][0m. (Note: This change was made in support of [47m[assert*][0m and [47m[mbt*][0m, mentioned above.) (SBCL only) It had been the case for host Lisp SBCL that the use of [47m[defun-inline][0m to define functions in [books] had failed to result in inlined code, when those functions were called after including those books. This has been fixed (and appears not to have been a problem for host Lisp CCL). Thanks to Jared Davis for bringing this issue to our attention. Bug Fixes A potential soundness issue could result from the application of [meta]functions and [clause-processor]s: although ACL2 checked that their outputs contain only legal [term]s, it did not check for the absence of calls of certain ``forbidden'' function symbols. For example, [sys-call] should be prohibited unless there is an active trust tag (see [defttag]), but a metafunction was able to introduce a call of [47msys-call[0m. We have added the necessary checks, in a way that we hope has negligible impact on performance. To avoid that impact or to learn more about this issue, see [set-skip-meta-termp-checks]; this new utility, which requires a trust tag, avoids not only the new checks but even the above-mentioned checks for legal terms. The edited log below illustrates a bug that we have fixed, involving the processing of [47m[include-book][0m [events] in the certification [world] whose filename starts with the tilde ([47m~[0m) character. ~/temp/incl$ cat sub/bad.acl2 (include-book "~/acl2/acl2/books/arithmetic/top") ~/temp/incl$ acl2h [[.. output elided ..]] ACL2 !>(ld "sub/bad.acl2") [[.. output elided ..]] ACL2 !>(certify-book "foo" 1) HARD ACL2 ERROR in ABSOLUTE-PATHNAME-STRING-P: Implementation error: Forgot to apply expand-tilde-to-user-home-dir before calling absolute- pathname-string-p. Please contact the ACL2 implementors. ACL2 Error in TOP-LEVEL: Evaluation aborted. To debug see :DOC print- gv, see :DOC trace, and see :DOC wet. ACL2 !> Fixed several issues with the [47m:puff[0m command, and updated its documentation accordingly. See [puff]. Fixed a bug in the [proof-builder]'s [47mwrap[0m command. Thanks to Keshav Kini for sending a simple example that illustrated this bug. (Allegro CL only) Fixed a bug in [47m[trace!][0m, which for example was evidenced when evaluating [47m(trace! (nth :native t))[0m. Fixed a bug in the printing of user-level terms that failed to account for [47m[untrans-table][0m entries for [47m[nth][0m, [47m[update-nth][0m, and [47m[update-nth-array][0m, when printing the first argument as a symbolic constant corresponding to a [stobj] argument. Thanks to Warren Hunt for reporting this issue with an example much like the following. When submitting the forms below, ACL2 output for the final form displayed the user-level term [47m(update-nth *fld* v st)[0m instead of the expected form, [47m(!nth *fld* v st)[0m. (defstobj st fld) (defmacro !nth (x y z) `(update-nth ,x ,y ,z)) (add-macro-fn !nth update-nth) (thm (equal (update-fld v st) xxx) :hints (("Goal" :in-theory (disable update-nth)))) Fixed a failure to [guard]-check [type] declarations for [47m[let][0m and [47m[mv-let][0m forms. Consider for example: (defun foo (x) (let ((a (car x))) (declare (type string a)) a)) Previously, the call [47m(foo '(3 4))[0m did not cause a guard violation, even though it should have done so. (Indeed, the event [47m(verify-guards foo)[0m failed, and continues to fail.) Fixed a bug in redundancy checking for [47m[mutual-recursion][0m events that specify [47m:[0m[47m[ruler-extenders][0m in an [47m[xargs][0m [47m[declare][0m form. Thanks to Sol Swords for sending an example that illustrates the bug: a [47m[mutual-recursion][0m event that, when executed twice, caused an error the second time rather than being redundant (see [redundant-events]). The bug was actually in how ACL2 stores information about the [ruler-extenders] used in definitions: the [47m:ruler-extenders[0m specified for the first [47m[defun][0m was being mistakenly stored for the second [47mdefun[0m. This mishandling of redundancy for [47m[mutual-recursion][0m events appears to be the only consequence of that bug. The following bug was probably not observable, but violated our claim that the system behaves as logically specified. When a [guard] check failed during execution, the error message that was printed could differ slightly from what is logically specified. (Technical detail: the error actually printed by source function [47mev-fncall-rec[0m was appropriately showing the original guard, but the specification function [47mev-fncall-rec-logical[0m was showing the untranslation of the translated guard.) This has been fixed. The [47msave[0m and [47mretrieve[0m commands for the [proof-builder] (see [ACL2-pc::save] and [ACL2-pc::retrieve]) now cause an error when the supplied name is not a symbol; similarly for the [47m:event-name[0m argument of [47m[verify][0m. The behavior wasn't as expected for non-symbol names; for example, after issuing the instruction [47m(save 'abc)[0m in the [proof-builder], the command [47m(retrieve 'abc)[0m failed to resume the proof-builder session. (Notice the erroneous use of the quoted symbol [47m'abc[0m, i.e., [47m(quote abc)[0m, rather than of the symbol [47mabc[0m.) Thanks to Keshav Kini for bringing this problem to our attention. We fixed the following two bugs in the processing of backchain limits stored for rules. Thanks to Dave Greve for bringing these to our attention. * For rules of class [47m:[0m[47m[type-prescription][0m, the specification of [47m:backchain-limit-lst[0m within the [47m:[0m[47m[rule-classes][0m could be ignored or cause a hard Lisp error. * For rules of class [47m:[0m[47m[meta][0m, preceding calls of [47m[set-default-backchain-limit][0m were ignored. Fixed a bug in the processing of certain operations on pathnames containing [47m".."[0m. Changes at the System Level By default, the ACL2 executable once again is named [47msaved_acl2[0m, though unlike previous versions, this executable is [hons-enabled]. Correspondingly, the ACL2(c) executable (that is, the executable that is not [hons-enabled]) is by default [47msaved_acl2c[0m. Thanks to David Hardin for suggesting these changes. Links from the home page to user's manual topics now point to the ACL2+Books combined manual, not the ACL2 (only) User's Manual, except for the one link that explicitly points to the latter. Thanks to David Hardin for feedback leading to this change, which was incorporated into the ACL2 Version 7.0 home page several days after the release of that version. Garbage collection notification has been turned off by default, not only for ACL2(c) as before, but also for (the default build) ACL2(h). Thanks to Eric Smith for suggesting this change. See [ACL2-customization] and see [gc-verbose] for how to turn such notification back on in your own environment. It is now possible to move the system books directory after certifying its books, without invalidating their status as certified. Users should generally not notice this change. We thank Harsh Raju Chamarthi and Camm Maguire for reporting problems with hacks we have produced over the years to support distribution of books with their [certificate] files. Those hacks are no longer necessary: as a byproduct of this change, we have deleted both the [community-books] directory [47mbooks/fix-cert/[0m and the source function [47mmake-certificate-file-relocated[0m. For a bit more detail see the final remark in the topic [full-book-name]. We also thank Eric Smith, Jared Davis, and Sol Swords for reporting bugs in our initial implementations of this enhancement. The [47mcertify-books[0m target for [47mmake[0m now excludes other expensive directories in addition to [47mworkshops[0m. (SBCL only) Modified the handling of environment variable [47mSBCL_HOME[0m. Thanks to Jared Davis for pointing out a problem leading to this change, namely, failure on his platform when evaluating [47m(require :sb-sprof)[0m in raw Lisp. Intended compiler optimizations are now guaranteed to be in place. We observed, thanks to communication from Jared Davis, that when ACL2 is built using SBCL 1.2.10, ACL2 starts up without the compiler optimizations that had been installed during the build. Perhaps that has been true for other SBCL versions or even other Lisps. Now, ACL2 explicitly restores those optimizations when it starts up. We observed a 5% time reduction for SBCL-based regression after this change. Environment variable [47mACL2_WRITE_PORT[0m is now ignored when doing [provisional-certification]. Thanks to Sol Swords for discussing this issue, which arose from a failure in [community-books] directory [47mbooks/workshops/2011/verbeek-schmaltz/sources/[0m, which uses [provisional-certification]. (GCL only) A few tweaks were made in support of GCL changes starting with pre-releases of GCL 2.6.13 in late April 2015 (but these tweaks are backward compatible with older GCL releases). Resulting ACL2 builds for a new GCL show dramatic speed-ups for a single user, perhaps cutting between a third and half the time, with less dramatic improvements when running regressions with [47m-j 8[0m. Thanks to Camm Maguire for pointing us to the changes and for improving GCL. EMACS Support The commands [47mControl-t e[0m and [47mControl-t Control-e[0m, defined in file [47memacs/emacs-acl2.el[0m, now check that the [47m*acl2-shell*[0m buffer exists, has a live process, and has a last line matching the specification in [47m*acl2-insert-pats*[0m, which has Emacs documentation (using [47mControl-h v[0m) but is set to a default based on shell prompts. Thanks to David Rager, Jared Davis, and Shilpi Goel for helpful discussions leading to this change. We installed the following two patches to file [47memacs/emacs-acl2.el[0m, both contributed by Keshav Kini. * Emacs highlighting for forms starting with "[47m(def[0m" now works when the "[47mdef[0m" symbol has a package prefix, for example, "[47m(fty::deflist[0m". * The Control-d character is no longer explicitly bound to the default, [47mdelete-char[0m, but instead is unbound in [47mcomint-mode-map[0m, so that the global binding of Control-d will take effect. Thus, users who bind Control-d themselves will no longer have that binding overridden in shell-mode (or comint-mode). We made several improvements to the [ACL2-doc] Emacs browser for ACL2 [documentation]. * Fixed a bug that could occur when Emacs variable [47mlarge-file-warning-threshold[0m is [47mnil[0m. Thanks to Bob Boyer for bringing this bug to our attention. * Links are now in color (blue, by default). See [ACL2-doc] for instructions on how to change or remove this color. Thanks to Jared Davis for suggesting the use of color. We are open to suggestions for improvements; this might be just a first step. * Allow limiting search and index commands to ancestors (sub-topics, sub-sub-topics, etc.) of a command (including the command itself), by supplying a prefix argument. * New [47m"p"[0m, [47m"<"[0m, and [47mControl-TAB[0m commands are analogues of [47m"n"[0m, [47m","[0m, and [47mTAB[0m --- for search, index, and next-link commands, respectively --- to go backward instead of forward. Experimental Versions (For ACL2(p) users only; see [parallelism]) If parallel execution is enabled (see [set-parallel-execution]), as it is by default in ACL2(p), then [47mhons-wash[0m and [47mhons-clear[0m may be no-ops (other than to print a warning), in order to avoid thread-unsafe behavior. (However, In CCL you are unlikely to see this restriction unless you are running more than one thread.) To get around this restriction, you can instead use [47m[hons-wash!][0m or [47m[hons-clear!][0m, which however require a [trust-tag]. Thanks to Bob Boyer for bringing this issue to our attention.") (note-7-2 (release-notes) "ACL2 Version 7.2 (January, 2016) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 7.1 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. See also [note-7-2-books] for a summary of changes made to the ACL2 Community Books since ACL2 7.1, including the build system. Changes to Existing Features The utility [47m[with-guard-checking][0m is now limited to forms that do not reference the ACL2 [state]. A related new utility, [47m[with-guard-checking-error-triple][0m, may be used for forms that evaluate to [error-triple]s. For an example showing a bug when [47mwith-guard-checking[0m was applied to forms that access [state], see the comment about ``with-guard-checking'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-2 ...)[0m. We thank Jared Davis for sending us an example showing that our preliminary fix was not adequate; for details, and for how a trust tag can avoid the new restriction (at the potential cost of unsoundness), see the remark for advanced users in the documentation for [with-guard-checking]. Several built-in functions are now in [47m:[0m[47m[logic][0m mode with [guard]s verified: [47m[term-order][0m, [47mmerge-sort-term-order[0m, [47m[arity][0m, [47m[termp][0m, [47m[term-listp][0m, and [47m[term-list-listp][0m --- new functions [47marities-okp[0m and [47mplist-worldp-with-formals[0m; and (thanks to Eric Smith for the suggestions) [47mcollect-by-position[0m, [47mmake-lambda-application[0m, [47m>=-len[0m, [47mall->=-len[0m, [47mstrip-cadrs[0m, and [47malist-to-doublets[0m. (Technical note: This enhancement followed the usual process: adding or extending community books in directory [47mbooks/system/[0m, including any new such books in [47mbooks/system/top.lisp[0m, and updating source constant [47m*system-verify-guards-alist*[0m.) Deprecated utilities [47mclear-hash-tables[0m and [47mwash-memory[0m have been eliminated. For [47mclear-hash-tables[0m, you can get the same effect by first invoking [47m[clear-memoize-tables][0m, and then invoking either [47m(hons-clear t)[0m or instead, if your executable uses static honsing, [47m(hons-wash)[0m. For [47mwash-memory[0m you can invoke [47m(clear-memoize-tables)[0m and then [47m(hons-wash)[0m. Thanks to Jared Davis for helpful discussions. The [command]s [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubu][0m have been changed. Their previous functionality is available with the commands [47m:[0m[47m[ubt?][0m and [47m:[0m[47m[ubu?][0m, respectively. Now, [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubu][0m behave much more like [47m:[0m[47m[ubt!][0m and [47m:[0m[47m[ubu!][0m (which have not been changed), in that they do not cause queries; however, unlike [47m:[0m[47m[ubt!][0m and [47m:[0m[47m[ubu!][0m, the [command]s [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubu][0m do report errors. Thanks to Eric Smith for requesting this change. Now, [47m:[0m[47m[puff*][0m has an optional argument that can avoid rollback of the world when there is an error. See [puff*]. After invoking [47m:[0m[47m[redef][0m and redefining functions in a [47m[mutual-recursion][0m event, it was necessary to answer [47mY[0m repeatedly in order to complete the redefinitions. A new option, [47mY![0m, will complete the remaining such redefinitions without further query. Thanks to Eric Smith for requesting this feature. A harmless but somewhat annoying superfluous declaration [47m(DECLARE (XARGS :NON-EXECUTABLE T))[0m was, by default, included in the generated [47m[defun][0m for a [47m[defun-sk][0m event. This has been fixed. Thanks to Eric Smith for bringing this issue to our attention. The [proof-builder] command [47mshow-rewrites[0m (or [47msr[0m; see [ACL2-pc::show-rewrites]) now shows additional bindings of free variables that would be generated when a third argument of [47mt[0m is supplied for the [47mrewrite[0m (or [47mr[0m; see [ACL2-pc::rewrite]) command. Thanks to Ben Selfridge for noting that this information was missing. Note that we also made a few trivial formatting changes for [47msr[0m. The redundancy check for [47m[encapsulate][0m [events] has changed in two small ways. One change is described below (see ``Redundancy checking for [47m[encapsulate][0m''). The other change is the redundancy check now properly identifies a previous subsidiary [47m[make-event][0m form with its expansion, ignoring the [47mrecord-expansion[0m wrapper. See the example labeled ``Redundant after Version_7.1 (as of mid-September 2015)'' in community book [47mbooks/make-event/local-elided.lisp[0m. A new mechanism for controlling the checking for [invariant-risk] replaces the raw Lisp global variable [47m*ignore-invariant-risk*[0m, which is obsolete. See [set-check-invariant-risk]. In particular, the default is now to print a (new) warning when encountering potential slowdown due to invariant-risk. Note that more functions are now subject to the invariant-risk check; see the discussion below in the section on Bug Fixes that pertains to invariant-risk. The (undocumented) system utility [47mwith-ubt![0m, which continues to be used in [47m[trace!][0m and [47m[disassemble$][0m and is now also used in [47m[set-check-invariant-risk][0m, now binds [ld] special [47m[ld-pre-eval-print][0m to [47mnil[0m. Thus, when [47mwith-ubt![0m is invoked, subsidiary forms will not be printed to the screen even when the above LD special is non-nil. Formerly, [47m[certify-book][0m, [47m[include-book][0m, and [47m[puff][0m operated with guard-checking off; technically, with [state] global [47mguard-checking-on[0m bound to [47mnil[0m. Now, that value is bound to [47mt[0m, which matches the default value in the top-level loop. Thanks to Eric Smith for suggesting this change to [47mcertify-book[0m and to Jared Davis for a helpful conversation about it. For [guard] proof obligations, all conjuncts from [stobj] declarations (supplied as [47m:stobjs[0m keywords in [47m[xargs][0m declarations) preceded all other conjuncts (i.e., from [47m[type][0m declarations or [47m[xargs][0m [47m:guard[0m declarations). Previously, this was only true within a given [47m[declare][0m form. Thanks to Dave Greve for bringing this issue to our attention. A new runic abbreviation has been added: [47m:r[0m, which abbreviates [47m:rewrite[0m. For example, you may use [47m(:r app-assoc)[0m in a theory expression to denote the [rune] [47m(:rewrite app-assoc)[0m. See [theories]. It is now possible to [monitor] rules by supplying a symbol or other runic designator other than a theory (see [theories]), thus relaxing the previous requirement that a [rune] is supplied. For example, the form [47m:monitor nth t[0m is legal, as is [47m:monitor (:d nth) t[0m, where before the corresponding command would necessarily have been [47m:monitor (:definition nth) t[0m. Thanks to Eric Smith for requesting this enhancement. Suitable [warnings] are now printed when attempting to [monitor] [simple] rules of class [47m:[0m[47m[definition][0m. These had only been printed for simple rules of class [47m:[0m[47m[rewrite][0m, because of potential inefficiency in computing for such warnings in the case of large [47m[mutual-recursion][0m [events], but that problem has been addressed in the ACL2 source code using [fast-alists]. ACL2 sometimes produces smaller [47m.cert[0m files, by avoiding certain macroexpansion. Formerly, for each macro call encountered in a certification world or [make-event] expansion, ACL2 performed repeated single-step macroexpansion until an event form was obtained, and replaced the original form with that result. The reason for this replacement was to modify certain [47m[include-book][0m forms involving relative pathnames (though only under specific conditions). Now, no such replacement is made except when such a modification is made to an [47minclude-book[0m call. This change could result in smaller [certificate] ([47m.cert[0m) files; for example, if a [portcullis] [command] is a macro call, [47m(foo)[0m, that expands into a very large [47m[defun][0m or [47m[defthm][0m event, the certificate file will contain [47m(foo)[0m rather than its macroexpansion. Of course, this change could result in longer times for processing an [47m[include-book][0m forms, because now macroexpansion may need to be done when they are processed; but such macroexpansion has always been necessary for all forms [3mwithin[0m a book, so such behavior is at least more consistent than before. If you really want a portcullis macro call to be expanded, wrap it in a [47m[make-event][0m call, for example, [47m(make-event '(foo))[0m instead of [47m(foo)[0m. The macros [47m[defund][0m and [47m[defthmd][0m now produce less output. In fact, the output is the same as for [47m[defun][0m and [47m[defthm][0m, respectively, except for the printing of the return value, which (as before) looks like [47m(:DEFUND NAME)[0m or [47m(:DEFTHMD NAME)[0m. Thanks to Jared Davis for suggesting such a change. Remaining traces of legacy documentation have generally been eliminated, including all vestiges of the obsolete command, [47mdefdoc[0m. ([Documentation] is now generally provided through the [xdoc] system.) In particular, optional and keyword arguments, [47mdoc[0m, have been eliminated for the following macros. * [47m[defabsstobj][0m * [47m[defabsstobj-missing-events][0m * [47m[defaxiom][0m * [47m[defchoose][0m * [47m[deflabel][0m * [47m[defstobj][0m * [47m[defstub][0m * [47m[deftheory][0m * [47m[defthm][0m * [47mdefthm-std[0m (defined only in ACL2(r); see [real]) * [47m[defttag][0m * [47m[in-arithmetic-theory][0m * [47m[include-book][0m * [47m[push-untouchable][0m * [47m[regenerate-tau-database][0m * [47m[remove-untouchable][0m * [47m[reset-prehistory][0m * [47m[thm][0m * [47m[verify-guards][0m Note that [47m[defabbrev][0m, [47m[defconst][0m, [47m[defmacro][0m, [47m[defpkg][0m, and [47m[defun][0m may still be supplied documentation strings, as a nod to Common Lisp. In particular, for [47mdefun[0m and [47mdefmacro[0m this can ease the porting of Common Lisp code to ACL2. Several source-level definitions have changed, many of them unadvertised. Some are for unadvertised event commands like [47mdefthm-fn[0m, which no longer have a [47mdoc[0m argument (see ``traces of legacy documentation have generally been eliminated'' above). Others, like [47mflambda-applicationp[0m, are macros that were formerly defined with [47m[defabbrev][0m but now are defined with [47m[defmacro][0m; thanks to Eric Smith for suggesting such simplifications. In prover output, terms of the form [47m(not (not expr))[0m had been printed simply as [47mexpr[0m. That could cause confusion; for example, the following form would lead to the checkpoint [47m(EQUAL (ALISTP X) (ALISTP X))[0m, where actually the checkpoint was [47m(EQUAL (NOT (NOT (ALISTP X))) (ALISTP X))[0m. This ``feature'' has been eliminated. Thanks to Shilpi Goel for bringing this issue to our attention and supplying an illustrative example. A warning was formerly printed when encountering a macro call with duplicate keys, for example [47m(foo 3 :y 4 :y 5)[0m where [47m:y[0m is a keyword argument of the macro, [47mfoo[0m. Now, this is an error by default, in order to make it easier for users to catch bugs due to accidental repetition of a keyword argument. However, the utility [47m[set-duplicate-keys-action][0m can be used to allow such duplicate keys, with or without a warning. Thanks to Jared Davis for requesting these changes. Warnings are no longer printed for [47m:use[0m hints applied to functional instances of enabled rules. Thanks to Eric Smith for suggesting this change. The second (optional) argument of [47mshow-accumulated-persistence[0m may now have a new value, [47m:list[0m, which causes the results to be displayed as a single list with entries of the form [47m(frames tries xrune)[0m. Thanks to David Rager for requesting a way to display useless [rune]s, sorted in a manner that can help with automating the creation of [47min-theory[0m forms that [47mdisable[0m unnecessary runes; also thanks for his helpful discussions in designing its functionality. See [accumulated-persistence]; in particular, [47m(show-accumulated-persistence :useless :list)[0m can display a list of runes to consider disabling. The utility [47m[print-gv][0m now takes additional keyword arguments, [47m:conjunct[0m and [47m:substitute[0m, which respectively show a specific conjunct of the [guard] evaluation that produced [47mnil[0m, and avoid [47m[flet][0m in favor of substituting actuals (even at the risk of duplication). See [print-gv], and see [set-print-gv-defaults] for a utility that sets default values for the keyword arguments. Thanks to Eric Smith for requesting these enhancements and for helpful discussions. Note that the system default value for the [47m:evisc-tuple[0m keyword is now the value of the form [47m(print-gv-evisc-tuple)[0m. [State] global variable [47mglobal-enabled-structure[0m is now untouchable (see [remove-untouchable]). Users may see a change in the order, number, and size of termination proof obligations because of an optimization that removes trivial equality tests generated by [47m[case][0m and [47m[cond][0m statements. (The removal of the tests can affect subsumption, which is how the order and number of proof obligations may change.) Once again, all documented constant, function, and macro symbols in the [47m"ACL2"[0m package are included in the constant, [47m[*ACL2-exports*][0m. Community book [47mbooks/misc/check-acl2-exports.lisp[0m has been updated for the current documentation system to enforce this invariant in the future. Thanks to Jared Davis for pointing out that the symbol [47m[extend-pe-table][0m was missing from [47m*acl2-exports*[0m and would be a good addition; that led us to this change. As also suggested by Jared, we added the symbols [47m[exists][0m and [47m[forall][0m to [47m*acl2-exports*[0m, as well. The quantifier [47m[forall][0m or [47m[exists][0m used in the body of a [47m[defun-sk][0m call must now be in the [47m"ACL2"[0m package. Many users will not notice this change, since the symbols [47mforall[0m and [47mexists[0m in the [47m"ACL2"[0m package are now in the list [47m[*ACL2-exports*][0m; see the paragraph just above. Thanks to Alessandro Coglio for a remark leading to this change. Definitions are no longer redundant that have different values specified for their [47m[xargs][0m keyword, [47m:normalize[0m. (See [redundant-events].) Although we are not aware of a need to make this change, this change eliminates a possible unsoundness. It is now the case that [47mopen-output-channel[0m and [47mopen-output-channel![0m will attempt to create missing directories as needed. (This had formerly been observed to be the case in CCL but not other Lisp implementations.) Thanks to Jared Davis for requesting this enhancement. New Features It is now possible to make ACL2 avoid the well-formedness checks done when metafunctions and clause processors are run. By default, when a metafunction or clause processor is run, ACL2 calls [47m[termp][0m or [47m[term-list-listp][0m, respectively, on the new value to make sure it is well-formed. Now, if you prove and provide a [47m:[0m[47m[well-formedness-guarantee][0m with the [47m:meta[0m or [47m:clause-processor[0m rule-class, you can skip these checks. This can speed up the use of metafunctions and clause processors on big terms and formulas. It is now possible to ensure the integrity of statistics produced by [47m[memsum][0m after functions are [memoize]d. See [protect-memoize-statistics]. Thanks to Alessandro Coglio for noticing oddities in those statistics and to Jared Davis for providing an implementation of this new feature. Function [47m[read-file-into-string][0m provides an efficient way to return the contents of a file as a string, without returning an ACL2 [state]. Thanks to Jared Davis for pointing out a logical flaw in the initial implementation. A new function, [47mget-skipped-proofs-p[0m, can tell system programmers whether or not a given event name was introduced with proofs skipped, as with [47m[skip-proofs][0m or using [47m[set-ld-skip-proofsp][0m. See [system-utilities]. Thanks to Eric Smith for requesting such a capability. A new [table] permits the association of names with substitute event forms, for use by [history] commands that print event forms, including [47m:[0m[47m[pe][0m, [47m:[0m[47m[pc][0m, [47m:[0m[47m[pcb][0m, and [47m:[0m[47m[pcb!][0m. See [extend-pe-table]. Thanks to Eric Smith for requesting such a capability. Note that [47m:[0m[47m[pe!][0m now avoids use of this table. A new macro, [47mffn-symb-p[0m, has been introduced and then used in the source code to simplify some definitions. Thanks to Jared Davis for a remark that led us to define and introduce this macro. See [system-utilities] for a description of this and many other low-level system utilities. It is now possible to give [hints] that specify the use of termination or [guard] theorems for existing function symbols. See [lemma-instance], [termination-theorem-example], and [guard-theorem-example]. Also see [gthm] and [tthm] for related query utilities. Thanks to Alessandro Coglio and Eric Smith for requesting these features. See [set-print-gv-defaults] for a new utility for setting default values for the keyword arguments of [47m[print-gv][0m. Thanks to Eric Smith for requesting this feature and for helpful discussions. For [history] commands and the function [47m[disabledp][0m, the notion of ``[disable]d'' is now computed inside the [break-rewrite] loop with respect to the [enable]d status at the current point of the current proof attempt, rather than with respect to the global state. Thanks to David Rager for suggesting this enhancement. Note that this change only affects [history] commands and [47m[disabledp][0m, not other utilities (for example [47m[tau-status][0m and [47m[guard-obligation][0m).x New system utility [47m[getpropc][0m is a convenient abbreviation for [47m[getprop][0m. A new utility causes some warnings to be printed in a ``raw'' s-expression format. See [set-raw-warning-format]. Thanks to Shilpi Goel for requesting this utility. The macro [47maccumulated-persistence-oops[0m undoes the effect of accidentally clearing statistics with [47m(accumulated-persistence t)[0m or [47m(accumulated-persistence :all)[0m. See [accumulated-persistence]. Thanks to Jared Davis for requesting this feature. Heuristic and Efficiency Improvements The redundancy check for [47m[defconst][0m has been sped up in cases with a very large term, as in the following example. Thanks to David Rager and Jared Davis for helpful related discussions. (defun make-tree (n) (declare (type (integer 0 *) n)) (if (zp n) nil (let ((x (make-tree (1- n)))) (cons x x)))) (make-event `(defconst *a* (hons-copy ',(make-tree 50)))) ; Redundant, and formerly very slow: (make-event `(defconst *a* (hons-copy ',(make-tree 50)))) Processing of [47m[defpkg][0m forms may be faster, thanks to a change suggested by Jared Davis (who observed significant speedup in SBCL). Optimizations have been made that can speed up [47m[include-book][0m for some large books, as follows. In particular, for the form [47m(time$ (include-book "centaur/sv/tutorial/alu" :dir :system))[0m we have seen a 25% reduction (on Mac OS) for the first item below, and an additional 29% reduction (also on Mac OS) for the second item. * Various optimizations have been made for [theory] manipulation, including some to make processing more efficient for [47m[defund][0m and [47m[defthmd][0m. Thanks to Sol Swords for bringing this issue to our attention in GitHub Issue #401 and for reporting bugs in our initial implementations. * Redundancy checking for [47m[encapsulate][0m [events] can be much faster. The only functional change (with one small exception, described in an item above) is to check for a sub-event of the proposed [47mencapsulate[0m event that is attempting to introduce a new name; if no such name is found, then the redundancy check is skipped, and the proposed [47mencapsulate[0m event is evaluated. This new check is quite thorough (see [redundant-encapsulate]), so we expect it to be rare that an [47mencapsulate[0m event that was formerly redundant is no longer redundant. [Certify-book] is faster in some cases; for example, we found the time required to certify a book whose only event is [47m(include-book "centaur/gl/gl" :dir :system)[0m was reduced from 57 seconds to 10 seconds. (Implementation note: The change was to avoid installing worlds in function [47mdefpkg-items[0m. That had probably been done in order to speed up calls of [47msimple-translate-and-eval[0m in [47mdefpkg-items-rec[0m, but that speed-up seems to be dwarfed by the expense of [47mextend-world1[0m in such cases.) We tweaked a part of the so-called ``clausify'' process for doing Boolean simplification towards producing subgoals of a given goal, namely, the so-called ``subsumption-replacement-loop'' (specifically, source function [47mfind-subsumer-replacement[0m). Thanks to Jared Davis for helpful discussions that led us to make this change. [47m[Defevaluator][0m is faster, especially so when many functions are to be interpreted by the new evaluator. The new version is a refactored version of community book [47mbooks/tools/defevaluator-fast.lisp[0m used with the permission of its original authors Sol Swords and Jared Davis. Thanks! The Common Lisp code generated for [stobj] accessors and updaters has been improved in the case that the [47m:type[0m is [47mT[0m or of the form [47m(array T ...)[0m. In particular, we have seen efficiency improvements for host Lisp CCL when the value read from or written to the array is a fixnum (integers that are sufficiently small in absolute value). Thanks to Bob Boyer and Gary Byers for helpful discussions that led to this improvement. Bug Fixes We fixed a soundness bug pertaining to [local] [47m[defpkg][0m [events]. See community books directory [47mmisc/hidden-defpkg-checks/[0m for an example that exploits this bug to prove [47mnil[0m in Version 7.1 and perhaps some other previous ACL2 versions. Thanks to Sol Swords for helping us set up that test (specifically, suggesting addition of the comment ``[47m; no_port[0m'' after an [47m[include-book][0m call that is not to be put into a [47m.port[0m file). The use of [47m[set-deferred-ttag-notes][0m during [47m[make-event][0m expansion could cause some TTAG NOTE messages never to be printed. Thanks to Jared Davis for a remark that led us to discover this bug, which could be considered a soundness bug since the TTAG NOTE mechanism is a key part of the soundness story. With this change, the effects of [47mset-deferred-ttag-notes[0m persist past [47mmake-event[0m expansion. It was possible to use [47m:[0m[47m[program][0m mode functions to write past the end of an array, leading to unsoundness. This has been fixed. Now, updaters for [stobj] array fields are marked as having so-called ``invariant-risk'', even when the element type of the array is [47mt[0m (unconstrained). Also marked with invariant-risk are built-in functions [47m[aset1][0m and [47m[aset2][0m. See [program-wrapper], [invariant-risk] and [set-check-invariant-risk], which is discussed above in the section Changes to Existing Features. Thanks to Jared Davis and Sol Swords for sending an example to illustrate the bug. When ACL2 was interrupted while debugging was on (see [set-debugger-enable]), it was possible later to get the following error repeatedly: HARD ACL2 ERROR in TIME-TRACKER: It is illegal to specify :START for tag :TAU, because tracking for this tag is already in an active state. This problem has been fixed, by defining a new keyword argument for [47m[time-tracker][0m, [47m:start![0m, and using it to track the use of the [tau-system]; see [time-tracker] and [time-tracker-tau]. ACL2 would cause an error at startup when the value of environment variable [47mACL2_SYSTEM_BOOKS[0m was a string starting with the tilde character ([47m~[0m). This has been fixed. Thanks to Shilpi Goel and Warren Hunt for bringing this bug to our attention. (GCL only) It had not been possible to define a [stobj] with more than 64 fields in GCL. We have removed that restriction. (Technical note: GCL disallows calls of the function, [47mvector[0m, with more than 64 arguments. So instead we now build a list of stobj fields that is coerced to a vector, rather than calling [47mvector[0m directly.) Fixed [47m[deftheory-static][0m by declaring the [world] to be [47mignorable[0m, thus avoiding errors for forms that don't reference the world. Thanks to Jared Davis for pointing out this bug with the example, [47m(deftheory-static my-theory '(car-cons))[0m. Fixed a bug that was causing the [47mhiding-cars[0m component of the [47m[ld-evisc-tuple][0m to be ignored when printing evaluation results. We avoid an error in the case that [47m[skip-proofs][0m is used around a definition with no tests above a recursive call, as in the following example. (skip-proofs (defun foo (x) (declare (xargs :measure (acl2-count x))) (identity (cond ((zp x) 17) (t (foo (1- x))))))) Thanks to Dave Greve for bringing this bug to our attention. Note that such a definitional event may be unsound (not surprisingly, because of the use of [47mskip-proofs[0m). For example, the following form succeeds: [47m(thm nil :hints (("Goal" :induct (foo x))))[0m. Several improvements have been made to avoid errors in the execution of [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m. Thanks to Eric Smith for reporting this issue. (Technical implementation note: a bug in source function [47mfind-longest-common-retraction1-event[0m, used in reverting logical [world]s, was fixed in support of this work.) When the [47m[default-defun-mode][0m was [47m:[0m[47m[logic][0m, then a [47m[mutual-recursion][0m form with [47m[xargs][0m declaration of [47m:[0m[47m[program][0m mode, which also had one or more [47m[defund][0m [events], would cause a error when attempting to [disable] new function symbols after admitting their definitions. This has been fixed. Thanks to Jared Davis for bringing this bug to our attention (GitHub Issue #464). We fixed some printing bugs for [47m:[0m[47m[psof][0m, [47m:[0m[47m[pso][0m, and raw proof format (see [set-raw-proof-format]). Both [47m:[0m[47m[psof][0m and [47m:[0m[47m[pso][0m were printing explicit splitter notes (see [splitter]) --- and worse yet, and thanks to David Rager for pointing this out, [47m:[0m[47m[psof][0m was printing them to the terminal. Those explicit splitter notes were not appropriate during proof replay, where instead parenthetical phrases like ``[47m(if-intro)[0m'' are sufficient; those phrases continue to be printed during proof replay, just as when [gag-mode] is off. Raw proof format had a couple of whitespace bugs, but more important was its failure to indicate any information about splitters; so now it prints the same explicit splitter notes as are printed for gag-mode. Insufficient checking has been fixed for [signature]s. Thanks to Jared Davis for sending the example [47m((f * *) => * :formals (x) :guard (natp x))[0m, which was not flagged as illegal by ACL2 even though the specified arity of 2 did not match the length of the specified [47m:formals[0m. There could also be mismatches between the [stobj]s specified, for example, with [47m(((f * st1) => * :formals (x st2) :guard (natp x)))[0m, that were not flagged as illegal. The inclusion of uncertified books was leading to some incorrect messages about other books that are also uncertified. This has been fixed (though the messages can still be verbose at times). Thanks to Eric Smith for sending an example to bring this problem to our attention. There were some incorrect error messages produced for bad calls of [47m[ec-call][0m; these have been fixed. Fixed a bug in [memoization] that could occur when multiprocessing is turned on, as in the call [47m(acl2::mf-multiprocessing t)[0m in community book [47mbooks/centaur/vl/server/server-raw.lsp[0m. Thanks to Sol Swords for reporting a bad report from [47m[memsum][0m when profiling function [47minclude-book-fn[0m before including system book [47m"doc/top"[0m. [Guard] violation error messages printed [47m'ACL2_INVISIBLE::|The Live State Itself|[0m where they should have printed [47mSTATE[0m; similarly for the utility [47m[print-gv][0m, which also failed to print entirely in user-level ``untranslated'' syntax. These problems have been fixed. Thanks to Eric Smith for bringing the ``[47mSTATE[0m'' bug to our attention. Infinite loops occurred for calls of [47m(close-output-channel *standard-co* state)[0m after redirecting standard output using [47mset-standard-co[0m. A clean error now occurs instead. We fixed a bug in [47m[state-global-let*][0m --- actually, in its supporting system utility [47macl2-unwind-protect[0m --- that allowed capture of a lexical variable, [47mtemp[0m, to produce bad results, for example as follows. (defun foo (temp state) (declare (xargs :stobjs state :mode :program)) (state-global-let* ((x 3)) (pprogn (fms "TEMP = ~x0~%X = ~x1~%" (list (cons #0 temp) (cons #1 (@ x))) *standard-co* state nil) (value nil)))) (foo 17 state) ; should show TEMP = 17 and X = 3, but caused Lisp error ACL2 no longer prints a message for a failed [47m:induct[0m hint (in the case that [gag-mode] is off), saying that a definition is [disable]d when that is not the case. (CCL only, probably only 32-bit CCL) We fixed a bug manifested with an error, ``is not of the expected type (UNSIGNED-BYTE 32).'' (Technical note: Function [47mccl::set-lisp-heap-gc-threshold[0m requires a fixnum, but was passed a bignum.) Thanks to Harsh Raju Chamarthi for sending us a log that exhibited this bug, namely [47mbooks/oracle/stv-invariant-extraction-pitfall/alu.lisp[0m, which seems to have evoked the bug by using an unusually large amount of memory. One might reasonably expect that for a [rewrite] or [linear] rule with a hypothesis of the form [47m(force ...)[0m or [47m(case-split ...)[0m, an attempt to relieve that hypothesis should be successful when forcing is enabled. The situation is a bit tricky if the hypothesis has free variables, but even then, one would expect success if the [47m:match-free[0m value is the default, [47m:all[0m, or if no suitable bindings are found. Such attempts had however not always been successful; but they are now, and the relevant documentation on [free-variables] has been clarified. For an example exhibiting the bug, see the comment about ``free variables'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-2 ...)[0m. An inappropriate warning has been eliminated for some [type-prescription] rules, for example the following. (defthm foo (implies (alistp mem) (or (equal (assoc loc mem) nil) (consp (assoc loc mem)))) :rule-classes :type-prescription) The warning had claimed that the rule ``may be weaker than you expect'' because the theorem itself ``is not provable using type-set reasoning''. But the theorem is provable when [guard-holders] are removed, as could generally be expected; so now, the check is applied after removing guard-holders from the theorem. The [guard]s stored for [macros] now include [type] declarations. Formerly the guards stored for macros were based only on the [47m:[0m[47m[xargs][0m [47m:guard[0m keyword. Consider for example the following definition. (defmacro foo (x) (declare (type integer x)) x) (defun bar (y) (foo y)) Formerly, no error occurred when processing the definition of [47mbar[0m, because the guard stored for [47mfoo[0m was [47mt[0m. Now, the guard stored for [47mfoo[0m is [47m(integerp x)[0m; since the variable [47my[0m is not an integer (it is a symbol), the attempted [47m[defun][0m for [47mbar[0m causes an error. Changes at the System Level ACL2 is now defined to incorporate its [hons-enabled] features. We formerly supported building ACL2 without these features, resulting in so-called Classic ACL2, also called ``ACL2(c)''. Such builds are no longer supported: although it is still technically possible to build ACL2(c), we do not stand behind such builds; in particular, we do not test them, and we have removed the [47mGNUmakefile[0m target, [47msaved_acl2c[0m. (CCL only) Starting with CCL Version 16384, EGC (the ephemeral garbage collector) is enabled in ACL2 by default, in place of a ``[47mstart-sol-gc[0m'' memory management scheme, but with some of the delay in full garbage collection that had been provided by that scheme. That scheme is still available to users, under a different name and inside the ACL2 loop; see [set-gc-strategy]. (Note that both [47mset-gc-strategy[0m and [47mgc-strategy[0m have been added to [47m[*ACL2-exports*][0m.) Thanks to Gary Byers for CCL improvements leading to this change, and to him, Bob Boyer, Jared Davis, and Sol Swords for helpful discussions. The default behavior can be restored to the previous behavior at ACL2 build time, by setting [47mMake[0m variable [47mACL2_EGC_ON=nil[0m when building an ACL2 executable. A new mechanism allows importing of theorems into the ACL2 source code, thus extending the existing mechanism for importing termination and guard verification for system functions (see the item above about [47m[term-order][0m, [47mmerge-sort-term-order[0m, and so on). Using this mechanism, some theorems have been imported from a new community book, [47mbooks/system/termp.lisp[0m. (For an example of how ACL2 developers use this mechanism, see the call of [47msystem-events[0m in ACL2 source file [47mboot-strap-pass-2.lisp[0m.) File [47mGNUmakefile[0m in the (top-level) ACL2 sources directory now sets environment variable [47mTIME_CERT[0m so that regressions will generate timing information. (SBCL only) The [47m--control-stack-size[0m argument for ACL2 executables saved for SBCL is now 64 (formerly 16). Thanks to Jared Davis for requesting this increase. The existing utility [47m[get-event-data][0m is now documented. Moreover, it can be used for determining whether an interrupt (Control-C) occurred during execution of an event. (This capability is used in a new utility, [47m[removable-runes][0m.) See [get-event-data]. The startup banner now shows the git commit hash for development snapshots. Thanks to Bob Boyer for suggesting such a modification and to Jared Davis for bringing to our attention the appropriate git command for retrieving the hash. (CMUCL only) It is now the case for CMUCL that [47m[setenv$][0m modifies the environment of the underlying Lisp process. Thanks to Jared Davis for this suggestion, and for pointing out that CCL and SBCL [at least] already have this behavior. A new optimize declaration for [47m[defun][0m, [47m(:stack-access 3)[0m, can result in some speed up for evaluations done when the host Lisp is CCL (but is likely to be a no-op in other host Lisps). Thus, you may write: [47m(defun foo (x) (declare (optimize (:stack-access 3))) ...)[0m. Thanks to Gary Byers and the CCL team for their excellent compiler work, including the new [47mstack-access[0m feature, and to Bob Boyer and Warren Hunt for helpful discussions. To build ACL2 on CCL with this feature, add the variable setting [47mACL2_STACK_ACCESS=3[0m to the [47mmake[0m command that you invoke to build ACL2. NOTE: The use of ACL2_STACK_ACCESS relies on recognition by CCL of the [47m:stack-access[0m keyword for optimize expressions, hence will only have effect for CCL versions starting with 16678. (CMUCL only) Updated saved_acl2 for CMUCL to use maximum heap for CMU Common Lisp snapshot-2016-01 and beyond. Thanks to Raymond Toy for updating CMUCL such that one can specify with [47m-dynamic-space-size 0[0m that the maximum heap is used. EMACS Support We made several improvements in the [ACL2-doc] browser. * A bug has been fixed in the [47mS[0m command ([47macl2-doc-re-search[0m). * The help message is displayed more often (but only, we think, when appropriate) in the echo area (i.e., below the mode line). * The [47mq[0m command ([47macl2-doc-quit[0m) now can be run from any buffer in [47macl2-doc[0m mode, for example after typing the [47mH[0m command. Moreover, all such buffers will be buried after [47mq[0m; formerly, if you quit from the main [47macl2-doc[0m buffer you could have been left in the [47macl2-doc-history[0m buffer. [47m[Verify-termination][0m calls are now indented like [47m[defun][0m calls. Thanks to Alessandro Coglio for suggesting this change to [47memacs/emacs-acl2.el[0m. The [ACL2-doc] Emacs browser now allows handling of topics with square brackets. This fix was necessary because a new topic, [47mSV::4VEC-[=[0m, broke acl2-doc; it wouldn't initialize. The fix simply replaces characters [47m#\[[0m and [47m#\][0m with [47m#\<[0m and [47m#\>[0m, respectively. It's not a perfect fix, but it seems awkward to try to escape [47m#\[[0m (which Emacs Lisp thinks starts a vector). See community book [47msystem/doc/render-doc-base.lisp[0m. Experimental Versions Fixed some interleaved output that could appear with [waterfall-parallelism] enabled. Thanks to Eric Smith for reporting this problem and to David Rager for a helpful chat.") (note-7-3 (release-notes) "ACL2 Version 7.3 (December, 2016) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 7.2 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. Changes to the [books] are no longer summarized in a documentation topic, but can be found by browsing the {ACL2+Books GitHub repository | https://github.com/acl2/acl2/}, in particular, the raw {commit log | https://github.com/acl2/acl2/commits/master}. Changes to Existing Features The name of ACL2's interactive goal manager has been changed from ``proof-checker'' to ``(interactive) proof-builder''. Thanks to several people in the ACL2 community for feedback leading to this more descriptive name. In particular, we thank Stephen Westfold for noting that as a new user, references in the [documentation] to ``proof-checker'' didn't help him to realize that ACL2 has an interactive proof capability similar to what is found in some other interactive theorem provers. Now, [set-raw-warning-format] causes all warnings to be printed in a raw format, not merely those warnings for which custom raw-warning-format code has been developed. Thanks to Shilpi Goel for recommending this enhancement. Utilities for formatted printing to strings no longer take an [47m:[0m[47m[iprint][0m keyword argument, and they never print using [iprinting]. See [printing-to-strings]. The reason is that for each iprint index, [47mi[0m, that is bound during creation of the result string, that binding would disappear after the string is returned; so it would be misleading or an error to read [47m#@i#[0m after that return. For a similar reason, when raw Lisp errors occur because variable [47m*hard-error-is-error*[0m is non-[47mnil[0m (see [hard-error]), iprinting is not used. Any [47m:[0m[47m[measure][0m supplied in an [47m[xargs][0m declaration of a [47m[defun][0m form must be a legal [term]. Formerly, this requirement only applied to [47m:[0m[47m[logic][0m mode definitions, but now it also applies to [47m:[0m[47m[program][0m mode definitions. Thanks to Jared Davis for pointing out that this restriction wasn't applied to [47m:program[0m mode definitions. For a [47m[defun][0m form, it is now illegal by default for a non-recursive definition to have a [47m:[0m[47m[measure][0m in an [47m[xargs][0m declaration (other than [47m:measure nil[0m, which means ``no measure'') unless the definition is within a [47m[mutual-recursion][0m. Thanks to Eric Smith for suggesting this restriction. See [set-bogus-measure-ok] for a way to avoid this new default behavior. Several symbols have been added to the list [47m[*ACL2-exports*][0m. It is now legal to specify a [47m:clause-processor[0m hint using a symbol, regardless of the signature of the relevant clause-processor function. A symbol had only been legal when that function took a single input. Now, the function may also take a hint argument followed by zero or more [47mstobj[0m arguments, in which case the hint is implicitly [47mnil[0m and the stobjs are passed appropriately. See [clause-processor]. Thanks to Eric Smith for requesting this enhancement. By default, the checksum values in [certificate] files for [books] have been replaced by a faster (though somewhat less secure) mechanism. See [book-hash] for an explanation, including a way to restore the use of checksums. (Our experiments in certifying all community [books] showed about a 7% reduction in total time. Speed-up for [47m[include-book][0m may be somewhat greater; for example, on a modern Macbook Pro the form (time$ (include-book "centaur/vl/mlib/datatype-tools" :dir :system)) took 21.67 seconds after certifying books in a default manner, but only 15.80 seconds after certifying books using [47mACL2_BOOK_HASH_ALISTP=t[0m --- a 27% reduction.) Thanks to Bob Boyer for emphasizing slowdown from checksum computation, to Jared Davis and Eric Smith for several helpful emails, and to the ACL2 community in general for continuing to push for faster evaluation of [47m[include-book][0m calls. The utility [47m[show-accumulated-persistence][0m now prints results in base 10 with radix [47mnil[0m (see [set-print-base] and [set-print-radix]). Thanks to Sol Swords for pointing out the odd printing that formerly could result when evaluating [47m(set-print-base-radix 16 state)[0m before calling [47mshow-accumulated-persistence[0m. We have changed how ACL2 automatically computes [type-prescription] rules for [47m[defun][0m forms --- so-called ``runic type-prescriptions'' --- in the following cases: * (1) when including a certified book; and * (2) in the second pass for a call of [47m[encapsulate][0m or [47m[certify-book][0m. For (1), ACL2 retrieves runic type-prescriptions from the book's [certificate]. For (2), ACL2 combines the runic type-prescription rule that is computed as usual with the rule previously computed in the first pass. Because of (1), the runic type-prescription rule for a function symbol introduced by an included book is no longer sensitive to the current logical [world]; previously, for example, that rule could be different if one first includes other books. Also, some [47m[include-book][0m calls may complete more quickly because of (1); for example, we saw a reduction in time of 4.7% for [47m(include-book "doc/top" :dir :system)[0m. Because of (2), runic type-prescriptions may be stronger than was previously the case. Thanks to Jared Davis for suggesting this enhancement and for helpful discussions during its development. This change can be viewed as just one of the hundreds of heuristic components of ACL2 that need not be understood in any detail by users; that said, those who are curious about implementation details are welcome to read the comment entitled ``Essay on Cert-data'' in the ACL2 source code. The utility [47m[save-exec][0m now causes an error if the directory of its first argument does not exist; for example, [47m(save-exec "subdir/my-acl2")[0m causes an error if there is no subdirectory [47m"subdir"[0m of the current directory. Thanks to Jared Davis for pointing out that some Lisps (in particular, CCL) would create a missing directory in such a case, while others (in particular, SBCL) would not. Slightly improved the printing of terms (the so-called ``[untranslate]'' utility) to avoid producing terms of the form [47m(not (not u))[0m in some cases. Thanks to Eric Smith for feedback leading to this change. The function being defined (or functions, plural, if using [47m[mutual-recursion][0m) may now be among the declared [ruler-extenders]. Thanks to Alessandro Coglio for an email that led us to make this change. The utility [47m:[0m[47m[pso][0m, along with other proof-replay utilities including [47m[psof][0m and [47m[psog][0m, now works with [47m[defthmd][0m and [47m[defund][0m. More generally, saved proofs are only wiped out by newer proofs, not by other [events] such as [47m[in-theory][0m events. The [47m:exec[0m code in calls of [47m[mbe][0m no longer affects termination proofs or induction schemes produced for function definitions. This had formerly only been the case for certain ``top-level'' calls in the if-then-else structure of the definition's body. The macro [47mlogicalp[0m is now deprecated, replaced by the function symbol [47mlogicp[0m. (For efficiency, [47mlogicp[0m is inlined in raw Lisp; [47mlogicalp[0m is for now simply a macro abbreviating [47mlogicp[0m.) Moreover, these utilities no longer call the function [47msymbol-class[0m. (See [system-utilities] for discussion of such utilities.) The latter change, which avoids consideration of the [47m'theorem[0m property of a symbol, can be helpful in proofs; indeed, this change simplifies reasoning about the new function [47mlogic-fnsp[0m (see the ``Bug Fixes'' section below). Several improvements have been made for utilities that show guard proof obligations. * The low-level system utility [47m[guard-obligation][0m no longer returns [47m[state][0m. Thanks to Alessandro Coglio for requesting this enhancement. * The utilities [47m[verify-guards-formula][0m and [47m[guard-obligation][0m take a new argument, [47mrrp[0m (``return redundant p''). When this argument is [47mnil[0m, which is the default for [47mverify-guards-formula[0m, these utilities will avoid returning the symbol [47m'redundant[0m even in the case that the given function symbol is already guard-verified. Thanks to Eric Smith for requesting this enhancement. * Documentation has been improved for utilities that show guard proof obligations, in particular with the addition of a new topic, [guard-formula-utilities], which explains their differences. * The utilities [47m[guard-theorem][0m and [47m[gthm][0m now do some simplification of the guard theorem by default. See [guard-theorem] and [gthm]. Thanks to Alessandro Coglio and Eric Smith for useful discussions. * The utility [47m[gthm][0m has two improvements: it takes a second optional argument, [47mguard-debug[0m; and it returns a single value (an untranslated [term]), rather than an [error-triple] whose value component is that untranslated term. The function [47m[guard-theorem][0m has been changed to support the new optional argument. Some recursive, [logic]-mode built-in functions did not have proper [measure]s stored in the ACL2 logical [world]: specifically, those whose suitability for logic mode is established in the community book [47mbooks/system/top.lisp[0m and the books included under that book. This has been fixed for all such functions except for the two ([47mmerge-sort-term-order[0m and [47mmerge-term-order[0m) whose measures use functions defined only in books, not in ACL2. Thanks to Eric Smith for a request leading to this enhancement. (If you are interested in implementation-level information about the mechanism tying books to verification of termination and guards for built-in functions, see comments in source-code constant [47m*system-verify-guards-alist*[0m.) The utilities [47m[print-gv][0m and [47m[set-print-gv-defaults][0m now accept a natural number for the keyword argument, [47m:substitute[0m, so that only certain large repeated terms cause the result to use [47m[flet][0m. See [print-gv]. Thanks to Eric Smith for suggesting such a change and helping to design it. ACL2 formerly caused a raw Lisp error when attempting to define a function that was already defined in raw Lisp but not in ACL2. Now an ordinary ACL2 error occurs instead. Thanks to Eric Smith for a question leading to this change. Functions [47mall-ffn-symbs[0m and [47mall-ffn-symbs-lst[0m are now in [guard]-verified [47m:[0m[47m[logic][0m mode. Thanks to Eric Smith for a helpful relevant conversation. Several other functions are now in guard-verified [47m:logic[0m mode, thanks to discussions with Eric and also Alessandro Coglio, including [47mformalized-varlistp[0m, [47mlatest-body[0m, [47mlogical-namep[0m, [47mmacro-args[0m, [47mstobjs-out[0m, [47mtermify-clause-set[0m, [47mthrow-nonexec-error-p[0m, and [47mthrow-nonexec-error-p1[0m. For a complete list, compare the old and new values of constant [47m*system-verify-guards-alist*[0m. It had been necessary to evaluate [47m(set-state-ok t)[0m in order to call [47m[verify-termination][0m on a [47m:[0m[47m[program][0m mode function that takes [47m[state][0m as a formal parameter but does not declare [47mstate[0m explicitly as a [stobj]. Thanks to Eric Smith for pointing out this issue. Here is an example that had failed but now succeeds. (set-state-ok t) (defun foo (state) (declare (xargs :mode :program)) state) (set-state-ok nil) (verify-termination foo) ; formerly failed To evaluate a form [47m(set-iprint t :hard-bound N)[0m, ACL2 will first replace [47mt[0m by [47m:reset-enable[0m. This behavior has been expanded to apply to [47m(set-iprint nil :hard-bound N)[0m and [47m(set-iprint :same :hard-bound N)[0m as well: the first argument will be converted to [47m:reset[0m or [47m:reset-enable[0m. See [set-iprint]. This change fixes a bug in the interaction between hard-bounds and rollovers. For an example that formerly exhibited this bug, see a comment about ``hard-bounds and rollovers'' in [47m(defxdoc note-7-3 ...)[0m in community book [47mbooks/system/doc/acl2-doc.lisp[0m. The following improvements have been made to [47m[defun-sk][0m. See [defun-sk] for detailed documentation. * [47mDefun-sk[0m now modifies the [pe-table], with the effect that if you introduce a function [47mNAME[0m with [47mdefun-sk[0m, then subsequent evaluation of [47m:pe NAME[0m will show the [47mdefun-sk[0m form rather than the underlying [47mdefun[0m form. As usual, you can invoke [47m:[0m[47m[pe!][0m instead, in order to see that [47mdefun[0m form. * When [47mdefun-sk[0m was supplied with keyword argument [47m:strengthen t[0m, the name of the generated theorem was always in the [47m"ACL2"[0m package. Now it is in the same package as the function symbol being defined. Thanks to Alessandro Coglio for suggesting this change. * [47mDefun-sk[0m now accepts [47m[declare][0m forms immediately after the formal parameters, as is the case for [47m[defun][0m. Thanks to Eric Smith for suggesting this enhancement. The [47m:witness-dcls[0m keyword is still supported as well, but may become deprecated in the future. * An issue involving [guard] verification for [47mdefun-sk[0m forms has been addressed. Thanks to Alessandro Coglio for suggesting this improvement. * Syntax checking now produces improved error messages for [47mdefun-sk[0m. The error message for a call of a undefined symbol now mentions defined symbols in other packages with the same name, in case that is what the user intended. The message also points to a new documentation topic, [near-misses], which provides a way (using certain books) to find approximate matches that are defined. Thanks to Jared Davis for suggesting such a change. ACL2 now accepts [47m#\Return[0m as legal notation for the character with [47m[char-code][0m 13, and it prints that character as [47m#\Return[0m rather than moving the cursor (e.g., to the beginning of the line). Thanks to Alessandro Coglio, Eric McCarthy, and Eric Smith for requesting this change, to help with the printing of failed subgoals that mention this character. The macro [47m[good-bye][0m no longer requires its argument to be a (natural) number. Any argument is now valid, and as before, is evaluated; if that argument is not an integer, it is treated as 0. The same change applies to the aliases for [47m[good-bye][0m, namely [47m[exit][0m and [47m[quit][0m. Thanks to Eric Smith for suggesting this change. When some subgoal in a set of key checkpoints is [47mNIL[0m, then such a subgoal will be printed first in the corresponding list, provided of course that the list isn't entirely ignored because of a checkpoint-summary-limit of 0. See [nil-goal], which has been updated. Thanks to Eric Smith for suggesting that [47mNIL[0m subgoals should be seen in the checkpoints in spite of the checkpoint-summary-limit (see [SET-CHECKPOINT-SUMMARY-LIMIT]). A new keyword argument, [47m:ctx[0m, is available for [47mvalue-triple[0m. See [value-triple]. [Definition] rules with non-[47mnil[0m values of [47m:install-body[0m (the default) are now permitted to have equivalence relations other than [47m[equal][0m. For macros such as [47m[prog2$][0m that invoke [47m[return-last][0m, an argument to be evaluated with attachments (see [defattach]) was failing to use attachments in some cases involving non-guard-verified functions. This has been fixed. For an example, see the relevant comment in the form [47m(defxdoc note-7-3 ...)[0m in community book [47mbooks/system/doc/acl2-doc.lisp[0m. The [47m:[0m[47m[termination-theorem][0m [lemma-instance] has been improved so that old function symbols may be replaced with corresponding new function symbols, either automatically or explicitly by the user. See [lemma-instance] and see [termination-theorem-example]. Thanks for Alessandro Coglio and Eric Smith for helpful discussions, including pointing out the previous deficiency. A new key, [47m:user[0m, is now legal for the [47m[ACL2-defaults-table][0m. Its value must be an association list. The key is reserved for users, who may assume that the ACL2 system does not give it any special handling; see [ACL2-defaults-table]. Thanks to Eric Smith for a helpful discussion leading to this change. A new macro, [47m(with-guard-checking-event x form)[0m, is now legal for event contexts; see [embedded-event-form]. Thanks to Eric Smith for helpful discussions leading to this change. For many years, it has been the case that when a [constraint] is proved that arises from a [47m:functional-instance[0m lemma instance (see [lemma-instance]), that information is stored so that the same constraint is not re-proved on behalf of a later such lemma instance. However, this had not been the case when the original lemma instance was inside an [47m[encapsulate][0m event. Now, that information is stored provided the [47mencapsulate[0m event has an empty [signature] list and is not ``empty'' (that is, stores at least one event). Thanks to Eric Smith for sending us an example to point out this problem. The [proof-builder]'s [47mbash[0m and [47mreduce[0m commands no longer fail when the [47m:hints[0m for [47m"Goal"[0m include [47m:do-not-induct t[0m. Thus, it is no longer necessary to edit out such [47m:do-not-induct[0m [hints] when editing a proof-builder command by copying hints from an event being developed. By default, the [proof-builder] command [47m:s[0m now uses contextual information when doing linear arithmetic. The new keyword argument [47m:linear[0m can be set to [47mnil[0m to get the previous behavior. See [ACL2-pc::s]. Thanks to Eric Smith for requests that led us to make this change. Warning and error messages produced upon [47m[theory-invariant][0m violations now include additional explanation. Thanks to David Hardin and Grant Passmore for helpful remarks leading us to make this change. Those messages also now show where the theory invariant was defined: a book pathname, or ``top-level'' if directly in the loop. The summary of ``Key checkpoint'' goals, at the end of a failed proof attempt, has been improved. It now indicates, inside the ``***'' banners, every case in which proof has been aborted due to a [47m:DO-NOT-INDUCT[0m hint or generation of a goal of [47mNIL[0m. The [proof-builder] command, [47mnoise[0m, no longer prints [proof-tree] information, which can be obtained with the new command, [47mnoise![0m. The [47mquiet[0m command is unchanged, but a [47mquiet![0m command turns off the printing of goal identifiers (as with [47m[set-print-clause-ids][0m). When [47m[defund][0m and [47m[defthmd][0m [events] fail, their output no longer concludes with distracting output that mentions [47m[with-output][0m. New Features New optional arguments allow the [47m[pso][0m utility to restrict output to a single goal or a segment of the output (say, between two specified goals); similarly for related utilities [47m[pso!][0m, [47m[psof][0m, and [47m[psog][0m. Thanks to David Rager for a recent query leading to this enhancement. The function [47m[cons-with-hint][0m provides an alternative to [cons] that can sometimes avoid consing. Thanks to Jared Davis and Sol Swords for suggesting this function and providing an implementation and documentation. A few ACL2 source functions now call [47mcons-with-hint[0m. Function [47m[file-length$][0m computes efficiently the number of bytes in a specified file. Function [47m[delete-file$][0m deletes a given file. Thanks to Eric Smith for requesting this utility. New macros [47m[active-or-non-runep][0m and [47m[incompatible!][0m are similar to [47m[active-runep][0m and [47m[incompatible][0m (respectively), except that the new macros essentially consider non-[rune]s to be enabled. Thanks to Eric Smith for feedback leading to these additions. It is now possible to [47m[declare][0m formal parameters of [47m[defun][0m events to be irrelevant. See [irrelevant-formals]. Thanks to Eric Smith for requesting this feature. The [47m[deftheory][0m event now accepts a new keyword, [47m:redundant-okp[0m, to allow a limited form of redundancy (see [redundant-events]). Thanks to Eric Smith for requesting such support. A new macro, [47m[defthy][0m, abbreviates [47mdeftheory[0m calls by adding [47m:redundant-okp t[0m. The [47m[fmt][0m family of functions has a new tilde directive, [47m~S[0m, which behaves like [47m~s[0m except that margins are ignored. Thanks to Jared Davis for requesting this feature. The iprinting utility has a new keyword option, [47m:share[0m, which causes iprint indices to be re-used (using so-called ``iprint sharing'' and ``iprint eager sharing''). See [set-iprint]. Thanks to David Rager for suggesting a notion of iprint sharing. A new function, [47m[set-serialize-character-system][0m, can be used to turn off (or on) the [serialize-write] capability, which is on by default, for writing certain files during book certification, including [certificate] files. This capability has been useful for working around issues with 32-bit CCL; thanks to Waqar Ahmed for working through that issue with us. ACL2 now supports the reading of rational numbers expressed in floating-point (scientific notation) syntax, using prefixes [47m"#f"[0m and [47m"#fx"[0m for base 10 and base 16, respectively. See [sharp-f-reader]. Thanks to Dmitry Nadezhin for suggesting this enhancement. Heuristic and Efficiency Improvements The raw-Lisp definition of [47m[defpkg][0m has been modified in a way that may improve performance for some host Lisps. Thanks to Bob Boyer for emails pointing to the (surprising) use of compilation by [47m[include-book][0m in CCL, which is eliminated (at least in some cases) by this change. [Type-set] reasoning has been improved in several basic ways. * The first, for which we thank Jared Davis and Sol Swords for providing an example, is illustrated in a comment in the form [47m(defxdoc note-7-3 ...)[0m in Community Books file [47msystem/doc/acl2-doc.lisp[0m) * When [definition] bodies and [guard]s are simplified, as they are by default --- see the new documentation for [normalize] --- [type-set] reasoning is now subjected to a [backchain-limit] of 1 (unless it is already 0 globally). Thanks to Jared Davis for sending an example, for which [47m[include-book][0m time has been cut to less than 10% of what it had been, without changing the results of [normalization]. (That said, regression timings suggest that this change will not be noticed for most books.) * The collection of primitive [type-set]s supported by ACL2 has been changed, by splitting the type of positive integers into two sets: the set consisting solely of the number 1, and the set of integers greater than 1. Thanks to Jared Davis for suggesting this change, and to him and Sol Swords for pointing out deficiencies in our initial implementation. For a discussion of changes made to community books to accommodate this change, see the comment immediately above the form [47m(defxdoc note-7-3 ...)[0m in community book [47mbooks/system/doc/acl2-doc.lisp[0m. Note that ACL2 has a newly-added function, [47m[bitp][0m, whose built-in [compound-recognizer] rule specifies that the value recognized by [47mbitp[0m is either [47m0[0m or [47m1[0m, that is, a member of the union of the primitive types [47m{0}[0m and [47m{1}[0m. [31;1mTheorem: [0m<bitp-compound-recognizer> (defthm bitp-compound-recognizer (equal (bitp x) (or (equal x 0) (equal x 1))) :rule-classes :compound-recognizer) ACL2 can reason a bit more powerfully about existing functions in some cases. For example, it now proves the following theorem without including any books, which was not the case previously. (thm (implies (and (rationalp x) (not (integerp x))) (< 1 (denominator x)))) You may need to change some of your books, however. For example, if you want to [disable] a function that always returns 1, then as was previously the case for such functions that always return 0 instead (or t, or nil), you'll want to disable the [type-prescription] rule for that function, too. * When a term of the form [47m(integerp (+ k term))[0m is assumed true or false, for an integer constant [47mk[0m, ACL2 now essentially attempts to add suitable type information for [47mterm[0m rather than for [47m(+ k term)[0m. (Source function [47mstrengthen-recog-call[0m shows precisely what is done.) We also made analogous improvements for terms of the form [47m(rationalp (+ k term))[0m and [47m(rationalp (* k term))[0m. Example theorem now provable that was not provable previously: (thm (implies (and (zp k) ; either k <= 0 or k is not an integer (integerp (+ 1 k)) (< 0 (+ 1 k)) (acl2-numberp k)) (equal 2 (+ 2 (* 2 k))))) We eliminated a rather technical check during book certification. (A bit of technical detail: we check for hidden packages in [47m[make-event][0m expansions, and an optimization eliminated that check for events in the book occurring before the first such event that introduced a new package, if any. But if no events in the book introduced a new package, then we were checking all such expansions; now, we check none of them.) Calls of the utility [47m[clear-memoize-table][0m formerly discarded relevant hash tables, building new ones when necessary. Now, the hash tables are typically retained but cleared (using Common Lisp function [47mclrhash[0m), although heuristics may determine that tables are ``too large'', in which case the former discarding behavior applies. Thanks to Jared Davis and Sol Swords for contributing this change, which they found to speed up certain computations significantly. We expect that it will likely not slow others down significantly. Note that (as they have pointed out) the behavior of related utility [47m[clear-memoize-tables][0m remains unchanged; it continues to discard relevant hash tables. The generation of raw Lisp definitions of [stobj] creator functions have been made potentially more efficient for stobjs with many fields. Thanks to Sol Swords and Jared Davis for reporting this issue and suggesting a fix, which we adopted (in source function [47mdefstobj-raw-init[0m) with some small changes. We now avoid certain inefficiencies with [47m[mbe][0m. The definition of [47mf8[0m below has taken 83.63 seconds in Version 7.2 built on CCL as the host Lisp, but with that same machine and host Lisp the time was merely 0.11 second after this change. (Technical note: the explosion was in the time required to compile the so-called ``*1* function''.) (defmacro id (x) `(mbe :logic (identity ,x) :exec (identity ,x))) (defun f8 (x) (id (id (id (id (id (id (id (id x))))))))) The heuristics for the ``eliminate-irrelevance'' clause processor (see [hints]) no longer drop applications of zero-ary functions or their negations, e.g., [47m(P)[0m or [47m(NOT P)[0m. Thanks to Marijn Heule for feedback that led us towards modifying our initial change (twice!). Several low-level efficiency improvements, which can speed up [read-object], may also speed up some other operations. * Finding a package from a string can be faster (low-level raw Lisp function [47mfind-package-fast[0m). * The implementation of low-level raw Lisp function [47mbad-lisp-objectp[0m was tweaked to use type recognizers, which are faster in some Lisps than corresponding recognizer predicates; for example, the test [47m(consp x)[0m has been replaced by the test [47m(typep x 'cons)[0m. * New raw Lisp function [47mbad-lisp-consp[0m processes conses on behalf of [47mbad-lisp-objectp[0m, and now [47mbad-lisp-consp[0m is memoized at startup instead of [47mbad-lisp-objectp[0m. Note that we continue to use memoization option [47m:forget t[0m, which throws away memoization information when exiting the top-level call of the function. With this change, we avoid the overhead of memoization when checking non-cons values, which was perhaps of limited value anyhow. There could be slowdown when large EQ strings occur repeatedly inside a cons pair, but we expect such slowdown to be at most negligible in practice. * New utility [47m[set-bad-lisp-consp-memoize][0m can turn off memoization of the new raw Lisp function [47mbad-lisp-consp[0m. Bug Fixes A soundness bug exploited the possibility that pathnames contain illegal ACL2 characters. Consider the following bash shell commands, which create a file whose name is the euro sign and create a soft link, [47m"foo"[0m, to that file. Thanks to Eric McCarthy for helpful discussions showing us how to create such a file, which ultimately led us to discover this bug. mkdir $'\xe2\x82\xac' ln -s $'\xe2\x82\xac' foo Then the following book certified on a Mac, but now one gets an error message complaining about a character with code 8364. (in-package "ACL2") (make-event `(defconst *c* ,(char (canonical-pathname "foo" t state) 44))) (defthm bad nil :rule-classes nil :hints (("Goal" :in-theory (theory 'minimal-theory) :use ((:instance char-code-linear (x *c*)))))) The utility [47m[getenv$][0m now causes an error if the value it would otherwise return is not an ACL2 string, for example because it contains a character whose [47m[char-code][0m exceeds 255. Many other changes, less visible to the user, have been made in how ACL2 deals with strings that come from outside ACL2, in particular, file names (see the related item just above). The handling of [meta]functions allowed an invariant to be violated, that conjectures in the prover are always 100% [logic] mode. An example is in a comment in the ACL2 source code under [47m(deflabel note-7-3 ...)[0m. We have not exploited this bug to show that it leads to unsoundness, but that seems possible. Our fix is to extend the checks that all applications of metafunctions and [clause-processor]s produce [term]s, to check additionally that those terms are all in logic mode. An analogous change applies to [well-formedness-guarantee]s, using new functions [47m[logic-termp][0m, [47m[logic-term-listp][0m, and [47m[logic-term-list-listp][0m, where [47mlogic-termp[0m checks not only [47m[termp][0m but also the new predicate [47mlogic-fnsp[0m, and similarly for the others ([47mlogic-term-listp[0m calls [47mlogic-fns-listp[0m and [47mlogic-term-list-listp[0m calls [47mlogic-fns-list-listp[0m). A bug has been fixed that could cause hard Lisp error when using the [iprint] utility. Specifically, calling [47m[set-iprint][0m with a small [47m:hard-bound[0m could cause a hard Lisp error during ``rollover'', as with the following example. (set-iprint :reset-enable :hard-bound 200) (set-iprint t :hard-bound 1000) (f-get-global 'iprint-ar state) (set-evisc-tuple (evisc-tuple 3 4 nil nil) :iprint t :sites :all) (thm (equal (append (append x y) x y x y x y x y) (append x y x y x y x y x y))) (pso) (pso) (pso) Thanks to David Rager for bringing this bug to our attention and for describing how it occurred in his environment. The fix is to convert the argument [47mt[0m of [47m[set-iprint][0m to [47m:reset-enable[0m when keyword argument [47m:hard-bound[0m is supplied. The keyword [47m:computed-hints-replacement[0m appeared in the source code a few times where [47m:computed-hint-replacement[0m was intended. This has been fixed. We are not aware of any examples in practice where this makes a noticeable difference; in particular, no [community-books] were modified to accommodate this fix. Redefinition can support certain uses of [47m[make-event][0m within [47m[encapsulate][0m forms, where formerly an error occurred. (Technical note: Small examples appear as comments in source function [47mchk-embedded-event-form[0m; search there for ``redefinition''.) Thanks to Jared Davis for sending us an example that exhibited this problem. Strictly speaking, we don't really view this as a bug; we have clarified in the documentation for [ld-redefinition-action] that redefinition may behave in unexpected ways. We now avoid creating directories when reading rather than writing: * It is no longer the case that [47m[include-book][0m creates a directory when attempting to include a book in a non-existent directory. Thanks to Jared Davis for bringing this bug to our attention. * In Version 7.2, we arranged that [47mopen-output-channel[0m and [47mopen-output-channel![0m attempt to create directories as needed. Unfortunately, that change also caused this behavior for [47mopen-input-channel[0m. That has been fixed. Thanks to Sol Swords for pointing out that certifying books in CCL using [47mcert.pl[0m could cause creation of directories when including books; with this fix, that is no longer the case. When submitting a call of [47m[define-trusted-clause-processor][0m with an unsuitable signature, the resulting error message was causing a raw Lisp error. This has been fixed. Thanks to Eric Smith for reporting this bug. Contrary to its documentation, a [47m[define-trusted-clause-processor][0m event was never redundant in the case that the values for keyword arguments [47m:label[0m and [47m:partial-theory[0m were both [47mnil[0m (or omitted). Thanks to Eric Smith for pointing out this bug. Now, redundancy of the resulting [47m[encapsulate][0m event succeeds because a subsidiary [47m[deflabel][0m event is generated by default. (The previous behavior can be obtained by explicitly supplying the keyword argument [47m:label nil[0m.) Also, the obsolete keyword argument, [47m:doc[0m, has been deleted for [47mdefine-trusted-clause-processor[0m. It had been possible to get a [slow-array-warning] from computed hints (see [computed-hints]) that directly modify so-called enabled structures. This has been fixed by providing a suitable way for users to call system function [47mload-hint-settings-into-rcnst[0m, as is done in the [community-books] utility [easy-simplify-term], which calls a function [47measy-simplify-term1-fn[0m that updates an enabled structure. Thanks to Jared Davis for sending an example that exhibited this problem through the computed hint [47m[logbitp-reasoning][0m. Also thanks to Sol Swords for a helpful discussion that brought our attention to the community book mentioned above. Avoided an assertion [47m(ASSERT$ ACTUAL-ELEMENT ...)[0m that could occur when including uncertified books, in particular when an included sub-book was originally certified in a different directory from where it now resides. Thanks to Eric Smith for reporting this bug and sending a helpful example. Fixed function [47mget-skipped-proofs-p[0m so that it returns [47mnil[0m on built-in functions. Thanks to Eric Smith for bringing up this issue, for example by pointing out that [47m(get-skipped-proofs-p 'len (w state))[0m evaluated to [47mt[0m; now, it evaluates to [47mnil[0m. The utility [47m[unmonitor][0m was failing to carry out its task when applied to a [rune]. This was due to a bug in ACL2 source function [47mdelete-assoc-equal-lst[0m, which has been fixed. The utility [47m:[0m[47m[psof][0m now prints the [47mRules[0m, [47mHint-events[0m, and [47mSplitter rules[0m fields to the specified file instead of the terminal. It also prints the interactive [proof-builder] prompt to that file instead of the terminal. On rare occasions it seems that after book certification, the compiled file was older than the corresponding [47m.cert[0m file, which prevented subsequent [47m[include-book][0m forms from loading that compiled file. (Technical note: The problem was that we erroneously relied on Lisp function [47mrename-file[0m to preserve write-dates.) This has been fixed. Thanks to Gary Byers for confirming that Lisp does not guarantee that [47mrename-file[0m preserves write-dates, and to Camm Maguire for reporting a related failure. We fixed the [47m:[0m[47m[puff][0m command so that it will no longer fail on [47m[include-book][0m commands followed by later [47minclude-book[0m events. Thanks to Eric Smith for reporting the problem via a helpful example. Some symbols were printed in a way that could not be read back in, but are now printed with surrounding [47m|...|[0m. Thanks to Sol Swords for reporting this problem for symbols with the Tab character. Now that we are more careful to print symbols readably in every host Lisp, but in a consistent manner for all host Lisps, you may find more symbols printed with surrounding [47m|...|[0m than is necessary for your host Lisp. It was possible to corrupt the system by evaluating ill-[guard]ed arguments on [program]-mode functions with raw Lisp code when guard-checking is off. For example, after evaluating the forms [47m(set-guard-checking nil)[0m and [47m(verbose-pstack 23)[0m, the form [47m(thm (equal x x))[0m caused a raw Lisp error. Now, the ill-guarded call above of [47m[verbose-pstack][0m causes a guard violation, even with guard-checking off. In host Lisps that do not compile on-the fly --- that is, in host Lisps other than CCL and SBCL --- an error occurred when trying to evaluate certain calls of [47m[comp][0m, including [47m(comp t)[0m during [47m[make-event][0m expansion. This has been fixed; here is an example that can be evaluated successfully now but not formerly. (make-event (er-progn (comp t) (value '(value-triple nil)))) ACL2 now avoids some needless escaping of symbol names with vertical bars, as in the case of [47mcar[0m in base 16, among others supplied by Eric Smith, whom we thank for the bug report: ACL2 !>(set-print-base-radix 16 state) <state> ACL2 !>'car |CAR| ACL2 !> Vertical bars are used for symbols whose names are so-called ``potential numbers'', which Common Lisp defines using several criteria. Consecutive letters disqualify a token from being a potential number, and ACL2's mistake was in failing to treat characters [47m#\A[0m through [47m#\F[0m as letters. We fixed a bug in the interaction between iprinting and brr. For an example, see the comment about ``interaction between iprinting and brr'' in the form [47m(defxdoc note-7-3 ...)[0m in community book [47mbooks/system/doc/acl2-doc.lisp[0m. Thanks to Shilpi Goel for pointing out a somewhat related problem introduced by a change originally made after Version_7.2, which also has been fixed. The documentation for [47m[ld][0m specified that ``If [47m[standard-co][0m and [47m[proofs-co][0m are equal strings, only one channel to that file is opened and is used for both.'' This was only the case when [47mproofs-co[0m was a canonical absolute (full) pathname. This has been fixed; now, the criterion is that [47mstandard-co[0m and [47mproofs-co[0m are strings that represent the same file. It is no longer illegal for [47m[defstub][0m to use an old style output signature with variables that are not among the formals. For example, the following is now legal (note that [47mu[0m is not among the list [47m(x y)[0m of formal parameters): [47m(defstub foo (x y) (mv u x))[0m. Thanks to Eric Smith for pointing out that this behavior is allowed by the documentation (specifically, see the discussion of ``Old Style'' in the documentation for [signature]). We fixed a bug in the implementation of [47m[defattach][0m, which could cause the wrong constraints to be generated in the case of more than one function argument. For a proposed [definition] rule with a missing (or empty) [47m:CLIQUE[0m but a non-empty [47m:CONTROLLER-ALIST[0m, the error message was ill-formed. This has been fixed. Calls of the macro [47m[add-custom-keyword-hint][0m are no longer illegal [events] in the context of [47m[local][0m. Tweaked [47m[break-on-error][0m to avoid rare error involving [47mSTATE[0m. Changes at the System Level It was possible for a backtrace to be printed to the terminal by SBCL and CMUCL, even when output is redirected to a file. This has been fixed. Moreover, we now print, just above a backtrace (with ACL2 function [47mprint-call-history[0m), the full pathname of the book under certification, in case this problem arises again. Also, limited the number of frames in CMUCL to the default in SBCL, namely, 1000. When building the executable with `[47mmake[0m', ACL2 now prints a message of the form ``[47mSuccessfully built <ACL2_executable_pathname>[0m'' as the last line of the log. Thanks to Eric Smith for suggesting this change. Note that the exit status continues to be 0 upon success and non-zero upon failure. An error now occurs when attempting to build ACL2 or certify the [community-books] (in the usual way, using [47mmake[0m) in a directory whose name contains at least one space. Thanks to Eric Smith for discussion leading to this change. Although the issue may only be with the infrastructure for certifying community books, we cause an error for the ACL2 build as well, to make installers aware of the problem with spaces as soon as possible; thus, we added this check in both the top-level [47mGNUmakefile[0m and in [47mbooks/GNUmakefile[0m. Note that the installation instructions (file [47minstallation/installation.html[0m) already said to install ACL2 ``in a directory whose pathname does not contain whitespace''; now, this requirement is enforced. (If some in the community would like to update the infrastructure for certifying books to support spaces in the build directory, they are welcome to do so and then remove the check for spaces in [47mbooks/GNUmakefile[0m, at which time we would be happy to remove corresponding code in the top-level [47mGNUmakefile[0m as well.) The [47mrdtsc[0m feature is now used in function [memoization] not only for host Lisp CCL but also for SBCL. Thanks to Bob Boyer for suggesting this change and providing helpful code. With a trust tag, it is now possible to apply [47m[verify-termination][0m to functions with under-the-hood raw Lisp code. See [verify-termination-on-raw-program-okp]. An argument has been added to the built-in function, [47mrecursivep[0m. The old call [47m(recursivep fn wrld)[0m has been replaced by the equivalent new call [47m(recursivep fn t wrld)[0m in some community books. See [system-utilities] for a discussion of [47mrecursivep[0m. Thanks to Alessandro Coglio for suggesting this change. There is now some documentation on ACL2 system development [formerly in the topic, system-development, and its subtopics; now expanded into the Developer's Guide (see [DEVELOPERS-GUIDE])]. These replace the pages under web directory [47mhttp://www.cs.utexas.edu/users/moore/acl2/open-architecture/[0m. Thanks to Eric Smith for encouraging us to move that documentation to XDOC. The Common Lisp variable [47m*debug-io*[0m is now used in printing backtraces, but also is bound to [47m*standard-output*[0m when entering the ACL2 read-eval-print loop, which is done at start-up (see [lp]). These changes avoid unfortunate printing of backtraces when certifying certain books that mess with [47m*debug-io*[0m using trust tags (see [DEFTTAG]), such as community book (see [COMMUNITY-BOOKS]). [47mbooks/centaur/vl2014/server/server.lisp[0m. Thanks to Jared Davis for a tip that helped us to debug that issue (ACL2 GitHub Issue #634). We improved ACL2's implementation of the [47m#.[0m read macro so that it no longer prints additional errors after the first. Also, the error message now mentions :DOC [sharp-dot-reader], pointing in particular to a relevant remark when the failure occurs during book certification. (SBCL only) Increased the value of [47m--dynamic-space-size[0m written to the executable scripts to 24000, from 16000, in support of building the manual. EMACS Support The text-based display of [documentation] has been improved, that is, for output from [47m:[0m[47m[doc][0m at the terminal and also for the [47m[ACL2-doc][0m Emacs browser. * Links are inserted much more reliably. That is, the surrounding of text by square brackets for text-based display now virtually always creates links that can be followed to topics in the [ACL2-doc] browser. In particular, that browser now handles names properly that contain the [47m:[0m character. * Text in square brackets, for example [1], is no longer recognized as a link (though Emacs still highlights it). Thanks to Mihir Mehta for pointing out this issue. * Automatic insertion of links for expressions [47m@('(name ...)')[0m, as [47m@('([name] ...)')[0m, should not happen for text-based display. This was however done when generating short strings for subtopics in [ACL2-doc]; that no longer happens. * The [47msee?[0m directive (see [xdoc::preprocessor]) now inserts links; it did not do so before (for text-based display). * Certain ``raw'' topics, such as DEFXDOC-RAW, are now included that formerly were only included in the web-based manual. * Text within ``[47m<stv> ... </stv>[0m'' is now replaced by the text ``[47m{STV display}[0m''. A general mechanism is in place for extending this behavior to other tags (see [47mxdoc-tag-elide-alist[0m [after Version 8.5, [47mxdoc-tag-alist[0m]) in [community-books] file 'books/xdoc/display.lisp'). * In the [ACL2-doc] browser, when the ``i'' ([47macl2-doc-index[0m) command is invoked without a prefix argument, the mode line shows the number of matches. (The remaining matches continue to be accessible using the ``,'' [47m(acl2-doc-index-next)[0m command.) Incorporated changes to [47memacs/emacs-acl2.el[0m put forward by Keshav Kini (thanks!), as follows. * Now, [47mmeta-x new-shell[0m avoids buffer names that already exist. * An error occurs when attempting to switch to a non-existent ACL2 shell buffer, rather than creating such a buffer with no process. * For a new shell, call [47mshell[0m instead of [47mmake-comint[0m. * Did a bit of refactoring and improved some error messages. Experimental Versions As before, [brr] does not work in ACL2(p) with [waterfall-parallelism] enabled; see [unsupported-waterfall-parallelism-features]. But now it is an error to try to enable both brr and waterfall-parallelism. Thanks to David Rager for helpful discussions pertaining to this change.") (note-7-4 (release-notes) "ACL2 Version 7.4 (March, 2017) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 7.3 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. Changes to the [books] can be found by browsing the {ACL2+Books GitHub repository | https://github.com/acl2/acl2/}, in particular, the raw {commit log | https://github.com/acl2/acl2/commits/master}. Also note that with each release, some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features The utility [47m[read-file-into-string][0m is now a macro, not a function. It no longer takes [47mstate[0m as an argument (though its expansion reads the state), and it has new keyword arguments that allow one to read successive segments of the file. See [read-file-into-string]. The test has been slightly relaxed for determining whether any supporting events are missing for [47m[defabsstobj][0m. Thanks to Sol Swords for sending an example to illustrate the issue, together with analysis of the problem. New Features Heuristic and Efficiency Improvements We now avoid the [invariant-risk] slowdown in the case of a [47m:[0m[47m[logic][0m mode function with guard [47mt[0m. For relevant examples see [program-wrapper]. A technical change in the handling of [type-set] computations can, in rare cases, result in better built-in [type-prescription] rules for functions. Bug Fixes Fixed a soundness bug, introduced about 10 years ago, that could occur with [47m:use[0m or [47m:by[0m [lemma-instance]s when a variable occurs free in a lambda of a functional substitution. For an explanation see a comment in [47m(defxdoc note-7-4 ...)[0m in community book [47mbooks/system/doc/acl2-doc.lisp[0m; also, a proof of [47mnil[0m (in Version 7.3) that exploits this bug can be found in a comment in the definition of function [47mremove-capture-in-constraint-lst[0m in the ACL2 source code. This may be the first time that a proved ``theorem'' in the [community-books] has been discovered to be a non-theorem ([47mtr-to-array-of-array-to-tr[0m in [47mbooks/projects/legacy-defrstobj/typed-records.lisp[0m). Thanks to Sol Swords for pointing out that this directory of books isn't used elsewhere; we temporarily excluded it from the regression by adding a [47mcert_pl_exclude[0m file, until Sol Swords repaired the proof a couple of days later. Also thanks to Ruben Gamboa for fixing proofs in the [47mnonstd/[0m books that failed after the bug fix. Fixed a bug in [proof-builder] commands [47mx[0m and [47mexpand[0m, which usually gave a misleading error message when attempting to expand a constrained function. Fixed bugs in the tracking and disabling of [compound-recognizer] rules. Thanks to Dmitry Nadezhin for pointing out this bug, indeed, sending an example and analyzing it to point to system function [47mterm-and-typ-to-lookup[0m, which was indeed the one that had the bug. Avoided a rare error in [47m[hons-wash][0m that has happened when there is a second garbage collection after [47mhons-wash[0m has commenced. Thanks to Keshav Kini for telling us about the problem and providing a patch, which we used almost verbatim. Changes at the System Level An ACL2 customization file is no longer loaded by default (when it exists) when invoking `[47mmake[0m' from the top-level ACL2 directory. This change is not necessary for `[47mmake regression[0m' because the build system for the books already takes care of it. However we need this change for `[47mmake DOC[0m', at the least; thanks to Eric Smith for bringing our attention to a failure of `[47mmake DOC[0m'. (Really a books change, but affects building the manual:) By default, it is now an error if when saving the ACL2+books or ACL2-only manuals (web-based or text-based), a syntax error (marked by ``xdoc error'') is encountered. See [47m[xdoc::save][0m and [47m[xdoc::save-rendered][0m: both now have an error argument with default [47mnil[0m so that by default, those new errors are not signaled; but in accordance with the change above, that new error argument is [47mt[0m for the standard ways of building the ACL2+books and ACL2-only manuals. Also, two arguments have been eliminated for [47mxdoc::save-rendered[0m. An invocation of `[47mmake update[0m' to build an ACL2 executable initiates a build only when necessary (that is, when at least one source file or supporting file, like [47mGNUmakefile[0m, has changed). Thanks to Eric Smith for the suggestion. Removed the following `[47mmake[0m' targets, which were suspect after this change (the first definitely no longer worked) and are unnecessary: [47msaved_acl2[0m, [47msaved_acl2p[0m, [47msaved_acl2r[0m, and [47msaved_acl2pr[0m. WARNING: [47mmake update[0m should be used with care, since it does not rebuild the desired executable when it already exists and is more recent than the sources. For example, if you change Lisp implementations without changing the [47mPREFIX[0m variable --- perhaps even only changing the version of your Lisp --- then use [47mmake[0m or [47mmake large[0m, not [47mmake update[0m. New `[47mmake[0m' target [47mclean-all[0m removes all generated files in the main ACL2 directory and its [47mdoc/[0m subdirectory, while existing target [47mclean[0m, which has been renamed [47mclean-lite[0m, cleans all of those except files [47m*saved_acl2*[0m (and [47mdoc.lisp.backup[0m), essentially as before. Thanks to Eric Smith for suggestions leading to this change, and to Keshav Kini for suggesting consideration of target [47mdistclean[0m as an alias for [47mclean-all[0m, which it now is. The target [47mclean[0m is deprecated but, consistent with prior usage, acts as [47mclean-lite[0m for now. A successful build using `[47mmake[0m' shows only four lines for [47m'fgrep -i compiler make.log[0m' instead of five. (GCL only) Installed a patch from Camm Maguire (GCL maintainer) to fix a GCL compiler bug. Also turned off SGC to avoid an ``mprotect failure'' error (community book [47mbooks/centaur/fty/tests/deftagsum-scale.lisp[0m). Fixed a bug that was causing an assertion failure, instead of a clean error, when attempting to apply [47m:[0m[47m[monitor][0m to undefined primitives, e.g., [47m:monitor cons t[0m. Thanks to Keshav Kini for reporting this bug and sending us an initial fix. Fixed a bug in the [break-rewrite] commands [47m:go![0m and [47m:go$[0m, which was causing an error message to be printed. EMACS Support Made minor [ACL2-doc] improvements: fixed a bug in `[47mu[0m' command's error message when already at the top topic; fixed a bug that was displaying the "Parent list:" field in reverse order; and eliminated the warning when loading a large manual (combined manual is at about 70M bytes now; new threshold is 80M bytes). Improved [ACL2-doc] to work with other manuals; see [ACL2-doc], specifically Section ``Selecting a Manual''. Note that the command for initially bringing up the ACL2 User's Manual, instead of the ACL2+Books manual, has changed from [47m(defvar *acl2-doc-top-default* 'TOP)[0m to [47m(defvar *acl2-doc-manual-name* 'acl2-only)[0m. Added new [ACL2-doc] commands, `[47m/[0m' and `[47mW[0m', to go to an ACL2 definition. By default the search is through both the ACL2 sources and books. The search can be continued even outside acl2-doc by using a numeric prefix argument with [47mcontrol-t /[0m, which is just the `[47m/[0m' command made available outside acl2-doc. These two commands differ only in the defaults presented in the minibuffer. The default for `[47m/[0m' is based on the text at the cursor. (This is much like the similar built-in Emacs command, [47mmeta-.[0m; indeed, `[47m/[0m' is next to `[47m.[0m' on standard keyboards.) For `[47mW[0m', the default is based on the page's topic name (as shown by the `[47mw[0m' command). See [ACL2-doc] for details. Installed a patch for [47mcontrol-t control-e[0m from Keshav Kini, so that when there are more than two windows and one has the ACL2 shell buffer showing, then that one receives the form. Consider for example windows A, B, and C, where the cursor is showing in A and the shell buffer is showing in C. Previously, the shell buffer could be placed in B to receive the form. Now, the form will go into C. The [47m:evisc-tuple[0m keyword for [47m[trace$][0m was being ignored when [47m:native t[0m was also supplied. Since the use of [47m:native t[0m sends the tracing command to raw Lisp, this wasn't really a bug, since no raw Lisp we know of supports the [47m:evisc-tuple[0m keyword. However, we have improved our custom modifications of the native [47mtrace[0m for host Lisps CCL and Allegro CL so that [47m:evisc-tuple[0m is no longer ignored for these Lisps. Experimental Versions A new rewrite rule for ACL2(r), [47mrealp-implies-acl2-numberp[0m, is analogous to the existing rule [47mrationalp-implies-acl2-numberp[0m. Thanks to Dmitry Nadezhin for suggesting the addition of this rule, which he observed is necessary for some ACL2(r) proofs.") (note-8-0 (release-notes) "ACL2 Version 8.0 (December, 2017) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 7.4 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-0-books] for a summary of changes made to the ACL2 Community Books since ACL2 7.4, including the build system. Also note that with each release, some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features The macro, [47m[case-match][0m, now treats keywords as constants when they occur in patterns. For example, the following form evaluates to 3 where formerly an error occurred: (let ((x '(:foo 3))) (case-match x ((:foo y) y) (& 17))) Thanks to Keshav Kini for suggesting this improvement. Several changes have been made to [47m[sys-call][0m and [47m[sys-call+][0m, and a new utility, [47m[sys-call*][0m, has been added. These stem from feedback from an observation by Eric Smith: [47msys-call[0m could invoke the operating system when simplifying terms (see [sys-call] for an example). We thank Eric for helpful discussions. Changes include: * When [47m[sys-call][0m is invoked during a proof (from a prover call or invocation of the [proof-builder]), it no longer can make a (potentially dangerous) call to the operating system. If such an invocation occurs during evaluation of a clause-processor or metafunction, an error will be signaled. * [47m[Sys-call+][0m continues to call the OS during proofs, but now it only does so when applied to the actual ``live'' ACL2 [state]. * A new utility, [47m[sys-call*][0m, combines some features of [47m[sys-call][0m and [47m[sys-call+][0m; it takes [47mstate[0m and takes effect even during proofs like [47msys-call+[0m, but like [47msys-call[0m it does not capture output. Thus, it can be a good choice in place of [47msys-call[0m for clause-processors and metafunctions, now that [47msys-call[0m would cause an error. * The guards are no longer [47mt[0m. Now, the guard for all three functions specifies the application of a string (the command) to a true list of strings (the arguments). * The [executable-counterpart] of [47m[sys-call][0m is disabled by default. Several symbols have been added to the list [47m[*ACL2-exports*][0m, including [47mLET[0m (thanks to Eric Smith for that suggestion). When a single-threaded object is being used where an ordinary object is expected, the error message has been improved to show the enclosing form. Moreover, such an error message can now appear when congruent stobjs are involved, where formerly the error was blamed on the shape of the result. Thanks to Sol Swords for bringing the latter problem to our attention with a helpful example. (See a comment in ACL2 source function [47mtranslate11-call[0m for a simplified version of that example.) The banner printed when there is a raw Lisp error now points to a new [documentation] topic, [raw-lisp-error]. Thanks to Keshav Kini for most recently pointing out that [47m[fmt][0m can cause a raw Lisp error. When suppressing output of all types other than [47merror[0m --- see [set-inhibit-output-lst] --- then errors may be reported with considerably less noise than before, because of the following changes. Thanks to Eric Smith, Alessandro Coglio, and Stephen Westfold for helpful discussions and feedback. * When all output is inhibited except error output, the generic failure message for events is suppressed for [47m[encapsulate][0m, [47m[progn][0m, [47m[progn!][0m, and [47m[make-event][0m. * When a call of [47m[make-event][0m specifies keyword [47m:on-behalf-of[0m with value [47m:quiet[0m or [47m:quiet![0m, an error for [47mmake-event[0m expansion is generally suppressed; see [make-event-details]. * A failed call of [47m[progn][0m no longer prints [47m"PROGN failed!"[0m; similarly for [47m[progn!][0m. Some warnings have been made more compact for including uncertified books. Thanks to Eric Smith for suggesting such an improvement. The (minimal) support for infix printing has been removed. (See the Essay on infix printing in ACL2 source file [47maxioms.lisp[0m for more information.) However, as a result it is now possible to call certain functions during evaluation of [47m[defconst][0m forms, and during macroexpansion --- in general, during any evaluation when so-called ``safe mode'' is active and a function with raw Lisp code is encountered. For example, the following form was formerly rejected but is now accepted. (defconst *c* (fms-to-string "abc~x0" (list (cons #\0 (expt 2 4))))) Thanks to Eric Smith for suggesting such a change. The role of [ruler-extenders] for redundancy of [47m[defun][0m forms has been simplified; see [redundant-events]. Thanks to Alessandro Coglio for contributing a patch for this change. Moreover, there was a bug: the redundancy check for definitions could allow the new definition to be redundant even when it specified more than one value for [47m:ruler-extenders[0m, which is illegal. This has been fixed. Thanks to Alessandro Coglio for bringing this issue to our attention. Modified the built-in rule [47mcomplex-0[0m to one that is simpler but equivalent, and modified the definition of [47m[conjugate][0m so that it always returns a number (essentially by ``fixing'' its argument). We thank Keshav Kini for suggesting such changes, and for helpful discussions we also thank Alessandro Coglio and Sol Swords, who suggested the definition of [47mconjugate[0m that we ultimately installed. The system-level utility, [47mtrans-eval[0m, now prints a warning by default when its call modifies a user-defined [47m[stobj][0m. This feature can be defeated but it may be best to allow the warning to be printed. See [trans-eval] and, especially, see [user-stobjs-modified-warnings]. A related change is that in order to call [47m[ld][0m in the body of a definition, a new keyword argument, [47m:ld-user-stobjs-modified-warning[0m, must be supplied. See [ld]. (Note: This issue was raised some time ago by Sol Swords.) Substantially improved error messages for illegal applications of theory functions (see [THEORY-FUNCTIONS]) [47m[enable][0m, [47m[disable][0m, [47m[set-difference-theories][0m, [47m[union-theories][0m, and [47m[intersection-theories][0m. Theory warnings have been enhanced to report enabling or disabling of the definition [rune] for an undefined [primitive] like [cons]. Thanks to Eric Smith for pointing out that ACL2 quietly lets one enable or disable undefined primitives to no effect, and also for feedback leading to improvements on the initial implementation of this change. For details, see [theories-and-primitives], specifically the last section, which pertains to primitives. Removed the symbol [47mlet-beta-reduce[0m from the list [47m*initial-untouchable-fns*[0m because [47mlet-beta-reduce[0m is not a known function symbol. The [47m:do-not-induct[0m hint no longer accepts keyword arguments other than [47m:otf-flg-override[0m and [47m:otf[0m, which would produce illegal theorem names in the report of skipped goals. Thanks to Eric Smith for a query that led us to clean this up. Duplicate hypotheses have been eliminated for events generated by [47m[defabsstobj][0m. Thanks to David Rager for bringing this issue to our attention and for helpful conversations. It is now legal for the bindings of a [47m[stobj-let][0m form to call accessors of a stobj, [47mst1[0m, on a stobj [47mst2[0m that is congruent to [47mst1[0m. See [nested-stobjs]. Thanks to Sol Swords for requesting and explaining this feature, implementing it, and providing tests. To see tests, search for ``how congruent stobjs may be used in stobj-let'' in [community-book] [47mbooks/system/tests/nested-stobj-tests.lisp[0m. A low-level error starting with ``HARD ACL2 ERROR in FIND-MAPPING-PAIRS-TAIL'' has been eliminated. This error could formerly occur when using redefinition; see comments in ACL2 source function [47mfind-mapping-pairs-tail1[0m for two simple examples. We thank Yan Peng for bringing this issue to our attention. Note that although we make some effort to support redefinition, we do not guarantee that it always works well; for a relevant warning, see [ld-redefinition-action]. Several related changes have been made in ``second-order'' capabilities. * The function [47m[magic-ev-fncall][0m could invoke functions that should not be invoked because they require a trust tag (see [defttag]) or they are untouchable (see [push-untouchable]). A check is now in place to prevent this; see [magic-ev-fncall]. For example, evaluation of the form [47m(magic-ev-fncall 'sys-call '("pwd" nil) state t nil)[0m no longer prints the current directory; instead it results in an error. * It was possible for system function [47mev-fncall-w[0m to subvert such a check by placing it under a [program-wrapper]; so [47mev-fncall-w[0m is now untouchable. * A new function, [47mev-fncall-w![0m, always performs the check, and may be used in place of [47mev-fncall-w[0m. But consider instead using the documented [logic]-mode function [47m[magic-ev-fncall][0m. * The first argument of [47mmagic-ev-fncall[0m no longer needs to be in [logic] mode. * [47mMagic-ev-fncall[0m can execute considerably more quickly than before; thanks to Eric Smith for sending an example that helped us to implement this improvement. * Both [47moracle-apply[0m and [47moracle-funcall[0m have been eliminated. Use [47m[magic-ev-fncall][0m where you would otherwise use one of those. Expressions in [table] [events] may now use not only the variable, [47mWORLD[0m, but also the variable, [47mENS[0m. See [table]. New Features A new utility, [47m[apply$][0m, provides a weak version of the Common Lisp second-order utility, [47mapply[0m. Using this new primitive the user can define functions like [47mmap[0m, which can apply certain function symbols and lambda expressions. Added utility [47m[checkpoint-summary-limit][0m. Thanks to Mihir Mehta for an email leading to this addition. A new utility, [47m[set-register-invariant-risk][0m, provides a way to avoid inclusion of the [invariant-risk] check in code generated by ACL2 for executable-counterpart functions (see [evaluation]). The effect of [47mset-register-invariant-risk[0m is limited to the enclosing book or [47m[encapsulate][0m event. Thanks to Eric Smith for a discussion leading to this feature. The new functions [47mread-object-with-case[0m and [47mprint-object$-preserving-case[0m are variants of [47mread-object[0m and [47mprint-object$[0m, respectively. The function [47mread-object-with-case[0m lets you specify that case is preserved, inverted, or converted to lower case or (as with [47mread-object[0m) to upper case. The function [47mprint-object$-preserving-case[0m prints symbols without escaping them for case; for example, the symbol in the current package with name [47m"abc"[0m is printed as [47mabc[0m, not as [47m|abc|[0m as would be printed by [47mprint-object$[0m. See [io]. New macro [47mwith-output![0m is the same as [47m[with-output][0m except for two differences: [47mwith-output![0m can be called in code, but it does not generate an event form. Now [47mcomplex-definition[0m is a disabled rewrite rule (formerly [rule-classes] [47mnil[0m). Also added (enabled) rules [47mdefault-pkg-imports[0m, [47mdefault-code-char[0m, and [47mdefault-intern-in-package-of-symbol[0m. All of these may be found in ACL2 source file [47maxioms.lisp[0m. Thanks to Keshav Kini for email that led us to add these rules. New function [47m[get-enforce-redundancy][0m queries the [world] on whether redundancy is being enforced. Thanks to Eric Smith for requesting this feature. It is now possible to obtain output that is less likely to depend on the directory where it was created, by evaluating the form [47m(assign script-mode t)[0m. (This capability supports the new tool, [47m[run-script][0m.) We added support for more detailed reports on the progress of forward-chaining. However these reports are only available on an experimental basis by redefining the system function [47mforward-chain1[0m as directed by a comment at the top of that [47mdefun[0m. Users who find this level of reporting useful are encouraged to tell us as we could incorporate it into the documentation topic, [forward-chaining-reports]. Normally, hard error messages (see [er]) are not inhibited. A new [state] global, [47mINHIBIT-ER-HARD[0m, inhibits hard error messages when [47mERROR[0m output is inhibited; see [set-inhibit-output-lst]. Heuristic and Efficiency Improvements The checking done for [invariant-risk] has been relaxed, so that it no longer causes any slowdown in calls of [47m:[0m[47m[logic][0m-mode functions. A low-level system function, [47mcross-prod[0m (which is used by [tau-system]), now uses tail-recursion, which may avoid some stack overflows. [Forward-chaining] was improved so that if a [47m:forward-chaining[0m rule produces a conclusion that is a disjunction, the system watches for later [type-set] information about the disjuncts. E.g., if we forward-chain to [47m(OR p q)[0m and later in the same forward-chaining process [47mq[0m becomes false, then [47mp[0m is made true. We thank Dave Greve for providing an example requiring this. An optimization for removing [stobj] recognizers, long applied to bodies of executable definitions, is now also applied to [guard]s. Thanks to Sol Swords for suggesting this change and its implementation. The function [47m[resize-list][0m is now defined using [47m[mbe][0m so that its execution is tail-recursive. Thanks to Martin Simmons of LispWorks Technical Support for diagnosing a stall in the certification of community book [47mbooks/centaur/truth/perm4.lisp[0m as being due to a stack overflow caused by an invocation of [47mresize-list[0m. Based on his advice we no longer automatically grow the stack in LispWorks; this will ease debugging when compilation is done with safety 3. The maximum stack size is 399998, at least in our 64-bit LispWorks build. Bug Fixes Soundness bugs have been fixed in the handling of [47m[stobj-let][0m, due to aliasing that could take place by binding two different but congruent stobjs to the same stobj. To see examples, search for ``soundness'' in [community-book] [47mbooks/system/tests/nested-stobj-tests.lisp[0m. We are very grateful to Sol Swords not only for bringing this to our attention, but especially for his contributions to a fix through helpful conversations and by providing code and examples. A bug in the [proof-builder]'s command, [47mrewrite[0m (or equivalently, [47mr[0m; see [ACL2-pc::rewrite]), avoided creating necessary subgoals, which can presumably be unsound. That bad behavior could occur when the third (and optional) argument of that command was a non-[47mnil[0m value other than [47mt[0m. The built-in evaluator functions for ACL2 relied on a system function, [47mev-fncall-w[0m, that was not a function! We do not see how to exploit this oddity to prove [47mnil[0m, since [47mev-fncall-w[0m is guaranteed never to be in [logic] mode. However, it is clearly undesirable. In the following example, the two [47mev-fncall-w[0m calls gave different answers on the same inputs --- [47m(mv nil 7)[0m and [47m(mv nil 12)[0m --- but now the second call results in an error. (defun foo (x y) (+ x y)) (assign old-w (w state)) (ev-fncall-w 'foo '(3 4) (@ old-w) nil nil nil t nil) (u) (defun foo (x y) (* x y)) (ev-fncall-w 'foo '(3 4) (@ old-w) nil nil nil t nil) The check for the requisite theorems supporting a [47m[defabsstobj][0m event included a case where the check was too weak, and it also could cause an unexpected assertion. The first of these could probably cause unsoundness. Thanks to Sol Swords for finding these issues and providing fixes. A small change in [47m[defstobj][0m can lead to improved automation for some [47m[guard][0m proofs involving [47m[stobj-let][0m. Thanks to Sol Swords for sending an example, which guided us to add a test (as suggested by Eric Smith) in community book [47msystem/tests/nested-stobj-formals.lisp[0m. Formatted printing (with [47m[fmt][0m, [47m[cw][0m, etc.) failed to respect newlines encountered while processing [47m~s[0m and [47m~S[0m directives. This has been fixed; see [47mbooks/system/tests/fmt-to-string.lisp[0m for examples that behave well now but formerly did not. Thanks to Eric Smith for pointing out this problem and sending, in essence, the following example. (cw "~s0" (string-append-lst (make-list 100 :initial-element (coerce '(#\A #\B #\C #\D #\E #\F #\G #\H #\I #\J #\Newline) 'string)))) A bug that was in the [tau-system] is illustrated by the following example sent by Grant Passmore, in which tau discovers that the function being defined always returns [47mnil[0m, hence implies everything. Tau no longer causes an error in this situation. (defun f (x) (> x 0)) (defun g (x) (< x 0)) (defun h (x) (and (f x) (g x))) Moreover, tau ``knows'' that the function [47mh[0m above is contradictory, as evidenced by the successful proof of the [47mthm[0m below. (thm (implies (h x) (consp x)) :hints (("Goal" :in-theory '((:e tau-system))))) Fixed a bug in [47m:[0m[47m[pe!][0m that could result in an error in [47m:pe! :here[0m when the most recent command is an [47m[encapsulate][0m event. It was possible to be in raw-mode, when including an uncertified book with a call of [47m[progn!][0m that first sets raw-mode [47m[set-raw-mode][0m and then causes a raw Lisp error. This has been fixed. It is now possible to invoke [47m[verify-termination][0m without an error occurring due to the presence of untouchable variables or functions in the definition (which hadn't prevented earlier admission in [program] mode). Thanks To Eric Smith for bringing this issue to our attention. ACL2 has supported, and continues to support, [47m[defun][0m forms that include the ACL2 [state] as an argument without declaring [47mstate[0m explicitly to be a [stobj]. This is done by first evaluating [47m(set-state-ok t)[0m. But in that case, the guard for such a function erroneously failed to include [47m(state-p state)[0m, which can have unfortunate consequences; see [47mbooks/system/tests/state-p-in-guard.lisp[0m in the [community-books]. This has been fixed. Thanks to Alessandro Coglio for contributing a fix and for helpful conversations. Fixed bugs in reporting of errors and warnings by [47m[defchoose][0m when pertaining to ignored variables. Thanks to Eric Smith for bringing one of these to our attention. Fixed a bug in the [proof-builder]: [hints] on the [47mprove[0m command were not being passed down to induction. Thanks to Mihir Mehta for bringing this bug to our attention with a reproducible example. Fixed a low-level bug (in source functions [47mnote-relieve-hyp-failure[0m), discovered by using the new community book [47mbooks/system/check-system-guards.lisp[0m. That book, which is useful for system development, checks all top-level calls of built-in functions that are in [logic] mode, [guard]-verified. Changes at the System Level When building the combined manual, an error occurs if there is more than the single expected broken link. Thanks to Alessandro Coglio for helpful discussions. [3mNotes.[0m (1) This uses a new keyword argument available in [47m[xdoc::save][0m, [47m:broken-links-limit[0m. (2) There is no such limit for saving the text-based manual. As usual, several [documentation] improvements have been made, for example, clarification made in the topic [local-incompatibility] thanks to Keshav Kini and Yan Peng. A new documentation topic, [evaluation], is probably long overdue: it explains ACL2 evaluation with a focus on the notions of the ``executable-counterpart function'' (sometimes called the ``*1* function'') and the ``submitted function'' (sometimes called the ``raw-Lisp function''). Environment variable [47mSBCL_USER_ARGS[0m allows one to pass runtime-options to calls of ACL2 built on SBCL, without having to call [47m[save-exec][0m. Thanks to Sol Swords for requesting this capability. Example: (export SBCL_USER_ARGS="--lose-on-corruption" ; ./sbcl-saved_acl2) There is a new documentation topic, [talks], which has a link from the ACL2 home page (with Applications, Tours, and Tutorials/Demos). Additional contributions to this topic are welcomed! For SBCL, the runtime option [47m--disable-ldb[0m is now supplied by the [47msaved_acl2[0m script, which avoids passing control to the lowest-level ([47mldb[0m) debugger (from which recovery is probably impossible). Without this option, a parallel run of [47mcert.pl[0m (see [build::cert.pl]) can stall out when a single failure passes control to the [47mldb[0m debugger. Some infinite loops are now avoided in the debugger for SBCL (and perhaps some other Lisp implementations). Thanks to Keshav Kini for sending an example and suggesting a fix, which we incorporated, as well as for helpful conversations. Implementation note: the definition of constant [47m*our-standard-io*[0m in ACL2 source file [47minterface-raw.lisp[0m explains the issue. Warnings were being produced by [47m[include-book][0m in CCL, and perhaps some other Lisps, when including a book that redefines a function as a macro or vice-versa. We have eliminated those raw Lisp warnings. It is now checked that the [47mbooks/[0m directory exists before attempting any operations using [47m'make'[0m on that directory. Thanks to Keshav Kini for suggesting this check, since there are source-only distributions, without the books. (SBCL only) The setting of environment variable [47mSBCL_HOME[0m has been tweaked to be more robust. In particular, we expect it to be unnecessary, and even inadvisable, to set [47mSBCL_HOME[0m manually. Thanks to Keshav Kini for contributing this change. (CMUCL only) ACL2 Version 8.0 cannot be reliably run on CMUCL, so we have disabled building ACL2 on CMUCL. The CMUCL implementor is aware of the problem, and we are hoping for a fix before the next ACL2 release The [state] global variables, [47mserialize-character-system[0m and [47mserialize-character[0m, are now preserved after [47m[make-event][0m expansion. This change for [47mserialize-character-system[0m allows the use of [47mmake-event[0m to avoid a stack overflow when writing out a [certificate] file; see [set-serialize-character-system]. EMACS Support Now, tags table [47mTAGS-acl2-doc[0m is automatically built when building the manual unless environment variable [47mTAGS_ACL2_DOC[0m has value [47mSKIP[0m. It can also be built by using the new event [47m[xdoc::save-rendered-event][0m. See [ACL2-doc] and see [xdoc::save-rendered-event]. Thanks to Eric Smith and David Rager for discussions leading to this enhancement. That tags table can also be built when building ACL2; see [ACL2-doc]. Made miscellaneous fixes for [ACL2-doc]: added [47mShift-<tab>[0m (more precisely, [47m<backtab>[0m to do the same thing as [47mControl-<tab>[0m (thanks to Eric McCarthy for the suggestion), avoided the use of [47msetf[0m (not always defined without requiring the [47mcl[0m package), avoided a potential error (when variable [47mlarge-file-warning-threshold[0m is [47mnil[0m), and avoided an infinite loop on some platforms when quitting acl2-doc. Defined `[47mmeta-,[0m' in [47memacs/emacs-acl2.el[0m to be Emacs function [47mtags-loop-continue[0m, which is how it has traditionally been defined by Emacs but might be defined differently in some versions of Emacs 25 (and perhaps later). [31;1mNOTE[0m: Put [47m(setq *preserve-tags-loop-continue* t)[0m in your [47m.emacs[0m file before loading ACL2 file [47memacs/emacs-acl2.el[0m, if you want to avoid redefining `[47mmeta-,[0m'. Thanks to Keshav Kini and Mihir Mehta for helpful discussions. Removed both non-ascii characters from [47memacs/emacs-acl2.el[0m. Thanks to Keshav Kini for the suggestion. For documentation printed at the terminal with [47m:[0m[47m[doc][0m, links (enclosed in in square brackets, ``[..]'') continue to be printed with respect to the [47m"ACL2"[0m package (that is, as though the current package were [47m"ACL2"[0m). Now, however, where a link formerly might be printed as ``[acl2::foo]'', it is now printed as ``[foo]''; that is, a package prefix of [47m"ACL2"[0m (regardless of case) is not printed. Experimental Versions Improved [type-set] reasoning for the function, [47m[imagpart][0m. Thanks to Keshav Kini for identifying the problem and suggesting a code change, and for sending an example of a theorem that formerly failed to be proved in ACL2(r). Improved [type-set] reasoning for the function, [47m[complex][0m. Thanks to Keshav Kini for identifying the problem and sending a patch, which we installed, together with examples of theorems that formerly failed to be proved in ACL2(r) but now prove, in particular: (thm (implies (and (real/rationalp a) (not (rationalp a))) (not (complex-rationalp (complex a b))))) Since [47m[wormhole][0m uses a lock (and has for some time), we modified [47m[observation-cw][0m so that it uses the same wormhole printing in ACL2(p) (instead of using [47m[cw][0m) that is used in regular ACL2. Thanks to David Rager for a helpful discussion. If you see an increase in hangs while using ACL2(p), please contact the implementors. Fixed an infinite loop that could be caused with parallelism enabled when there is an error, when Lisp variable [47m*hard-error-is-error*[0m has been set to a non-[47mnil[0m value in raw Lisp (see [hard-error]).") (note-8-1 (release-notes) "ACL2 Version 8.1 (September, 2018) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.0 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-1-books] for a summary of changes made to the ACL2 Community Books since ACL2 8.0, including the build system. Also note that with each release, it is typical that the value of constant [47m[*ACL2-exports*][0m has been extended, and that some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features The evaluation of [table] guards now allows attachments. This is important for the implementation of [47m[apply$][0m (see below). A new keyword argument for [47m[defun-sk][0m, [47m:constrain[0m, can specify that the newly-introduced function is constrained rather than defined. See [defun-sk]. Note that by constraining the function we make it possible to attach to it, and also to introduce it as a [guard]-verified function. We also made a minor change to [47mdefun-sk[0m, by moving the call of [47m[extend-pe-table][0m out of the generated [47m[encapsulate][0m form. (Of interest only to users of [47m[apply$][0m.) When invoking [47m[defwarrant][0m or [47m[defun$][0m, a so-called `[warrant]' is introduced. Warrants are now always [guard]-verified, with a guard of [47mt[0m. Moreover, warrants are now executable in the top-level loop; for example, after successfully processing [47m(defwarrant foo)[0m or [47m(defun$ foo ...)[0m, [47m(warrant foo)[0m will evaluate to [47mt[0m in the loop. (Note: each warrant has an attachment, [47mtrue-apply$-warrant[0m, that always returns [47mt[0m; see [defattach].) Thanks to Dmitry Nadezhin for requesting these enhancements. It is now required to include the system book [47mprojects/apply/apply-lemmas.lisp[0m before evaluating a call of [47mdefun$[0m or [47m[defwarrant][0m. This requirement, which is enforced with an error that prints the necessary [47m[include-book][0m form, avoids stack overflows that could occur when that book is not included. When performing [47m[make-event][0m expansion under a surrounding [local] context, it is no longer illegal to set the [ACL2-defaults-table]. For example, the following event formerly caused an error but is now legal. (local (make-event (er-progn (set-ignore-ok t) (defun foo (x) x) (value `(value-triple ,(length (w state))))))) Information printed when giving [47m:use[0m [hints] has been improved for the case that a [lemma-instance] is a [47m:[0m[47m[termination-theorem][0m or a [47m:[0m[47m[guard-theorem][0m. Formerly, only the name was shown in the `[47mHint-events[0m' [summary] and in the proof output; now, one will see ``names'' of the form [47m(:termination-theorem NAME)[0m and [47m(:guard-theorem NAME)[0m. We improved redundancy checking for [47m[defun][0m forms so that it is not sensitive to whether [47m[state][0m has a [47m:stobjs[0m declaration. The [warnings] for weak [type-prescription] rules have been eliminated. These warnings were issued when a rule was insufficient to prove itself by [type-set] reasoning, but it seems more appropriate to parse the formula into a type-prescription rule before applying that check (for example, expanding away [guard-holders], which was already done, and beta reducing lambda applications, which was not). Then the chance of not proving the result seems remote. Thanks to Keshav Kini for an example and a conversation leading to this improvement. The [checksum] computation that can support certifying or including [books] --- which is not used by default, but see [book-hash] for how to enable it --- has been improved. Specifically, at least one of the [community-books] (namely, [47mbooks/centaur/aignet/rwlib.lisp[0m) formerly caused a stack overflow (with host Lisp SBCL, at least) before making this change. (Technical note: the change is to avoid memoization for calls of [47mfchecksum-obj[0m with stack depth exceeding [47m10000[0m.) Thanks to Keshav Kini for reporting this issue and for related helpful communications. When a [break-rewrite] command such as [47m:eval[0m or [47m:go[0m shows that a rule fails because a [backchain-limit] is exceeded, more information is printed than before. Now, the responsible rule(s) or global backchain-limit is indicated. Thanks to Alessandro Coglio and Eric Smith for requesting this enhancement. The fancy string reader now accepts a string with three string quotes followed by a closing curly brace. See [fancy-string-reader], in particular the final paragraph. Thanks to Sol Swords for contributing this enhancement. The ACL2 [47m[untranslate][0m function, which converts the internal representation of [term]s to user-level syntax, can now return calls of [47m[mbe][0m, [47m[mbt][0m, [47m[ec-call][0m, [47m[cw][0m, [47m[time$][0m, and [47m[mv-let][0m. Thanks to Alessandro Coglio, Eric Smith, and Stephen Westfold for discussions leading to some of these changes. Such terms rarely occur in practice because definitional bodies are stored with calls of [guard-holders] and [47mcw[0m expanded. However, here is an example of how they could arise. First consider the following definition. (defun g (n) (declare (xargs :normalize nil)) (ec-call (natp n))) Here is a log before the change. ACL2 !>(verify (equal (g x) yyy)) ->: 1 ->: p (G X) ->: x-dumb ->: p (LET ((N X)) (EC-CALL1 NIL (NATP N))) ->: After the change, the log instead ends as follows. ->: p (LET ((N X)) (EC-CALL (NATP N))) ->: It is now illegal by default to attach to built-in functions. To overcome this default behavior, see [defattach-system]. Improvements have been made to functions in the [47m[fmt][0m family, including for example [47m[fms][0m, [47m[fmt-to-string][0m, and [47m[cw][0m. (Also see discussion of [47m[fmx-cw][0m under ``New Features,'' below.) * Many [guard]s have been strengthened, for example to imply that the [47malist[0m argument must satisfy [47m[character-alistp][0m. Thanks to Eric Smith for pointing out that an expression like [47m(fmt-to-string "~x0" 3)[0m could cause a raw Lisp error (rather than causing a guard violation). * Eliminated raw Lisp errors from ill-formed calls. Thanks to Jared Davis for pointing out this problem in 2010 (!) with the example [47m(cw "Bad: ~&0.~%" 5)[0m, and for Eric Smith for prodding us much more recently with the example [47m(cw "~&0" 'x)[0m. * The utility [47m[fmx][0m no longer prints an initial newline. Of course, a call [47m(fmx "<some-string>" ...)[0m can be modified to generate an initial newline (thus providing the former behavior) by adding the newline tilde-directive, [47m"~%"[0m, that is, [47m(fmx "~%<some-string>" ...)[0m. The previously-undocumented built-in-function, [47m[packn][0m, now has a slightly different behavior. Formerly, it always returned a symbol in the [47m"ACL2"[0m package. Now, the package of the symbol returned is the package of the first symbol in [47mlst[0m whose package is not [47m"COMMON-LISP"[0m if any, else [47m"ACL2"[0m. Thanks to Keshav Kini for suggesting this change and providing its implementation. The [guard] on [47m[apply$][0m (also the guard on [47mapply$-lambda[0m) has been strengthened to require that a [lambda] be applied to the correct number of arguments. The under-the-hood implementation for applying lambdas has been made slightly more efficient as a result, though that improvement may usually be trivial. Perhaps more important is that guard verification may now catch bugs in the application of lambdas that were missed previously. The [47m:dir[0m argument to [47m[ld][0m was previously ignored when the first argument of the call of [47mld[0m is not a string. Now, that is an error. If you get this error, just remove the (previously ignored) [47m:dir[0m argument. The function [47m[magic-ev-fncall][0m sometimes printed a message in the error case in addition to returning that message. It now only returns that message. Thanks to Sol Swords for bringing to our attention that certification of a community book, [47mbooks/projects/x86isa/proofs/popcount/popcount.lisp[0m, was printing a warning about [47m"Meta-level function Problem"[0m for thousands of lines. The definition of [47m[msgp][0m has been strengthened to require that for a [47mcons[0m pair, the [47mcdr[0m must satisfy [47m[character-alistp][0m. The [proof-builder] command, [47mquiet![0m, now inhibits all output except [47merror[0m output (and that too, if already inhibited). Warnings have been modified that are labeled ``[Non-rec]'', generated for rules with problematic occurrences of non-recursive function symbols. Now they take into account rules of class [47m:[0m[47m[definition][0m. Thanks to Mihir Mehta for bringing this issue to our attention. It is no longer required to specify [47m:install-body nil[0m in a [definition] rule when the function symbol is a member of the value of the constant [47m*definition-minimal-theory*[0m. Thanks to Eric Smith for pointing out that the utility, [47m[install-not-normalized][0m, was failing on, for example, [47m[eq][0m. This change fixes that problem. Technical note for system hackers only: Because of this change, the value of [47m(body fn t wrld)[0m is no longer guaranteed to get the original definition of [47mfn[0m when fn is in [47m*definition-minimal-theory*[0m; for that purpose use the new utility, [47mbbody[0m. Many error messages now show variables according to order of appearance, where formerly the order was reversed. Thanks to Eric Smith for supplying an example of a top-level form, [47m+ a b c[0m, for which the error message reported variables in reverse order: ``Global variables, such as C, B and A, are not allowed.'' The message now says ``A, B, and C'' instead of ``C, B and A.'' For [47m[value-triple][0m, the keyword argument [47m:on-skip-proofs[0m provides new behavior if it is given the value, [47m:interactive[0m. In that case, evaluation is still done under a call of [47m[skip-proofs][0m, as when the value of [47m:on-skip-proofs[0m is [47mt[0m; but evaluation is skipped when the reason proofs are being skipped is only that a book is being included or the second pass is being made through an [47m[encapsulate][0m. Thanks to Eric Smith for requesting this feature. Both [47m[fmt-to-comment-window][0m and [47mfmt-to-comment-window![0m have an extra argument, [47mprint-base-radix[0m, which is the same as the first argument to the new utilities, [47m[cw-print-base-radix][0m and [47m[cw-print-base-radix!][0m (see below). The undocumented constants [47m*primitive-program-fns-with-raw-code*[0m, [47m*primitive-logic-fns-with-raw-code*[0m, and [47m*primitive-macros-with-raw-code*[0m have been renamed respectively to [47m*initial-program-fns-with-raw-code*[0m, [47m*initial-logic-fns-with-raw-code*[0m, and [47m*initial-macros-with-raw-code*[0m. Thanks to Alessandro Coglio for suggesting these improved names. The [47m[save-exec][0m utility now utilizes a relative pathname in the [47msaved_acl2[0m script, which can allow it and a corresponding image file to be moved, even across filesystems --- though if there is an image file, then probably the Lisp executable must have the same pathname even after the move. Thanks to Eric Smith for suggesting this capability and providing a hint for how to implement it, to Sol Swords for pointing out a limitation of the initial implementation, and to {this website | https://serverfault.com/questions/40144/how-can-i-retrieve-the-absolute-filename-in-a-shell-script-on-mac-os-x} for making that solution robust. The [47m[defevaluator][0m macro, and more generally the notion of evaluator, have been changed to include two new [constraint]s inserted after constraints 0 through 5. The new constraints are as follows, where [47m<ev>[0m refers to the evaluator. (IMPLIES (AND (NOT (CONSP X)) (NOT (SYMBOLP X))) (EQUAL (<ev> X A) NIL)) (IMPLIES (AND (CONSP X) (NOT (CONSP (CAR X))) (NOT (SYMBOLP (CAR X)))) (EQUAL (<ev> X A) NIL)) These new constraints generated by [47m[defevaluator][0m are named [47m<ev>-CONSTRAINT-6[0m and [47m<ev>-CONSTRAINT-7[0m unless the keyword argument [47m:namedp t[0m is supplied, in which case they are named [47m<ev>-OF-NONSYMBOL-ATOM[0m and [47m<ev>-OF-BAD-FNCALL[0m. Thus by default (or if [47m:namedp[0m is [47mnil[0m), this change increases by one the indices on constraints for the specified function symbols, because they start at 8 instead of 6 --- [47m<ev>-CONSTRAINT-8[0m, [47m<ev>-CONSTRAINT-9[0m, and so on. Note that if you use functional instantiation to prove a theorem about one evaluator given a theorem about another evaluator, you'll need to enable the new rules (i.e., [47mev-constraint-6[0m and [47mev-constraint-7[0m or, if you use option [47m:namedp t[0m, [47mev-of-nonsymbol-atom[0m and [47mev-of-bad-fncall[0m). Thanks to Sol Swords for both suggesting and implementing this extension. [47m[Let][0m-expressions are no longer eliminated from right-hand sides of [rewrite] rules. See [rewrite]. This change improves efficiency of the rewriter in some cases, by retaining subexpressions shared on the right-hand side as the rewrite rule is applied. Thanks to Eric Smith for requesting this change. It was possible to declare a function symbol to be [untouchable] and yet still execute it using [47m[apply$][0m, thus violating the spirit of untouchables. That is no longer allowed. Here is an example of such execution that was formerly permitted, but is no longer. (include-book "projects/apply/apply-lemmas" :dir :system) (defun$ f (x) (declare (xargs :guard t)) (cons x x)) (push-untouchable f t) (apply$ 'f '(3)) New Features The [summary] now shows, by default, the list of doublets [47m(f g)[0m for which [47mf[0m is a system function with attachment [47mg[0m (see [defattach]), when [47mg[0m differs from the initial attachment to [47mf[0m. (Warning: The following describes advanced features that can likely be ignored by most users. They are available using the new utility, [47m[defattach-system][0m.) Three new system-level functions may be given attachments: [47mremove-trivial-equivalences-enabled-p[0m, [47massume-true-false-aggressive-p[0m, and [47mrewrite-if-avoid-swap[0m. (Thanks to Eric Smith for suggesting these, and to him and Alessandro Coglio for helpful discussions.) By default, these have the attachments [47mconstant-t-function-arity-0[0m, [47mconstant-nil-function-arity-0[0m, and [47mconstant-nil-function-arity-0[0m, respectively, which provide the existing system behavior. But these attachments may be changed by the user. * [47mRemove-trivial-equivalences-enabled-p[0m may receive the attachment [47mconstant-nil-function-arity-0[0m to avoid the [47mremove-trivial-equivalences[0m heuristic, which substitutes the equality (or even equivalence) of a variable to a term into the rest of the goal. (However, perhaps similar heuristics will still be used, for example as part of the [tau-system].) * [47mAssume-true-false-aggressive-p[0m may receive the attachment [47mconstant-t-function-arity-0[0m to strengthen the rewriter's use of the [type-alist] when diving into [47mif[0m terms. A common use is to rewrite what amounts to [47m(if (or test1 test2) (if test1 _ x) _)[0m; then the [type-alist] will note that [47mtest2[0m is true when rewriting [47mx[0m. This change may slow down ACL2 considerably in some cases, and should rarely if ever be necessary when calling the prover; but it can be useful in applications that call the rewriter directly. * [47mRewrite-if-avoid-swap[0m may receive the attachment [47mconstant-t-function-arity-0[0m to cause the rewriter --- specifically, source function [47mrewrite-if[0m --- to avoid swapping true and false branches of a call of [47mIF[0m, which could formerly happen when the test is a call of [47mNOT[0m. When the environment variable [47mACL2_CUSTOMIZATION_QUIET[0m is set and not [47m""[0m, there will generally be no output from ACL2 customization. A special value of [47m"all"[0m for this variable will cause continued minimal output after startup. See [ACL2-customization]. New utilities, [47m[fmx-cw][0m and [47m[fmx!-cw][0m, are essentially the same as [47m[cw][0m and [47m[cw!][0m (respectively), except that [47mfmx-cw[0m and [47mfmx!-cw[0m are well-[guard]ed, which can catch errors in the use of tilde-directives. Thanks to Eric Smith for requesting such a capability. For example: ACL2 !>(fmx-cw "Hello ~s0." '(world)) ACL2 Error in TOP-LEVEL: Guard violation for FMX-CW-FN: Illegal Fmt Syntax. The tilde-s directive at position 6 of the string below is illegal because its variable evaluated to (WORLD), which is not a symbol, a string, or a number. "Hello ~s0." ACL2 !> New utilities, [47m[cw-print-base-radix][0m and [47m[cw-print-base-radix!][0m, are like [47m[cw][0m and [47m[cw!][0m, respectively, except for an additional argument that specifies the print-base and, optionally, the print-radix. Thanks to Eric Smith for requesting [47m[cw-print-base-radix][0m. A new event macro, [47m[set-in-theory-redundant-okp][0m, allows [47m[in-theory][0m events to be [redundant], which prevents [47m[defund][0m and [47m[defthmd][0m [events] from laying down [47m[command][0m markers (as seen, for example, using [47m:[0m[47m[pbt][0m). Thanks to Eric Smith for asking for a way for [47min-theory[0m events to be redundant. Heuristic and Efficiency Improvements The implementation of [wormhole]s has been tweaked to avoid an efficiency problem. In the old implementation, an update to the wormhole status was avoided in the case of equal old and new status values. That update avoided some consing, but the equality test could be very slow; indeed, [47m:[0m[47m[print-gv][0m could be slow because of its use of wormholes. The new wormhole implementation --- specifically, the new raw Lisp implementation of [47m[wormhole-eval][0m --- avoids that equality test, and also can avoid consing by its use of destructive operations. That fixes one reason [47m:print-gv[0m could be slow; a second change, made to the implementation of [47m:print-gv[0m, is to pass [47mnil[0m as the wormhole-status ([47mwhs[0m) argument of [47mmake-wormhole-status[0m. See [make-wormhole-status] for a discussion of how that use of [47mnil[0m can avoid an expensive equality test. Thanks to Alessandro Coglio and Eric Smith for sending an example that illustrated the problem. The following improvements have been made for evaluating calls of the form [47m(apply$ '(lambda ...) ...)[0m. * An optimization had failed to be fully in place, causing such calls to run slowly. That optimization compiles and caches ``tame compliant'' lambdas: lambda forms whose [guard]s are verified by the [tau-system] and that are [3mtame[0m (see [apply$]). The optimization had been used in the unadvertised use of ``The Rubric'' prior to the release of ACL2 Version 8.0. Warnings about non-tame-compliant lambdas will now appear when appropriate, as had been the case in Version 7.4. * The optimization above has been improved so that instead of three cache lines, there is an efficient implementation using 1000 cache lines. That is probably many more than are needed, but the large size is harmless. The additional cache lines dramatically improve speed when more than three lambdas are actively being applied; see [community-books] file [47mbooks/system/tests/apply-timings.lisp[0m. * ACL2 no longer causes an error when the cache is in an inconsistent state; instead, the cache is suitably reset quietly. Rewriting of calls of [47m[implies][0m has been optimized in the cases that the rewritten arguments are equal or at least one is a constant. Thanks to Eric Smith for pointing out an incompleteness in the rewriting of [47mimplies[0m calls. The algorithm has been tweaked for generating a [type-prescription] rule to store for a given definition, so that the rule is sometimes stronger than was previously the case. Bug Fixes There was a soundness bug in the automatic functional instantiation that can be applied for a [47m:termination-theorem[0m [lemma-instance]. Thanks to Eric Smith for sending an example to illustrate this bug, for suggesting its cause, and for permission to include that example in a comment in the ACL2 sources definition of the constant, [47m*non-instantiable-primitives*[0m. Bugs have been fixed in the [tau-system] that caused unsoundness (going all the way back through Version 6.0, released December, 2012). The problem was with conversion of a non-strict inequality with 0 to a strict inequality when the quantity is known not to be 0; for example, [47m(<= x 0)[0m was converted to [47m(< x 0)[0m when [47mx[0m was known to be non-zero. But of course, this conversion is only valid when [47mx[0m is known to be a number. Thanks to Yan Peng for sending an example that illustrates the bug, which in its essence was the ability of ACL2 to prove this formula, which for example is false when [47mx = t[0m: [47m(or (< x 0) (= x 0) (> x 0))[0m. If you encounter a failure in a proof that formerly succeeded, the fix might be to add a call of [47m[ACL2-numberp][0m to the hypotheses of your theorem. Fixed two bugs in [47m[apply$][0m: we now [47m[disable][0m the [executable-counterpart] of [47mgood-bye-fn[0m to prevent quitting ACL2 entirely during a proof, and we avoid the error ``ACL2 cannot ev the call of non-executable function ANCESTORS-CHECK...'' by allowing attachments to be used when checking table guards (as discussed above). Thanks to Dmitry Nadezhin for sending replayable examples that exhibited these bugs. Fixed [guard]s for functions [47m[enabled-runep][0m, [47m[enabled-numep][0m, [47mdisabledp-fn[0m, and [47mdisabledp-fn-lst[0m, thus eliminating bogus guard violations. Thanks to Alessandro Coglio and Eric Smith for sending an example that illustrated the bug for [47menabled-runep[0m. Technical note: this fix was made by replacing calls of [47mbounded-nat-alistp[0m (which is no longer defined) by calls of [47mnat-alistp[0m (which is newly defined). We also made a corresponding tweak to the definition of [47menabled-numep[0m. Warnings labeled with ``Double-rewrite'' failed to take into account patterned [congruence] rules. This has been fixed. Thanks to Mihir Mehta for pointing out the problem with a helpful example. It is now possible, once again, to [monitor] rules of class [47m:[0m[47m[linear][0m. This capability has (accidentally) been unavailable since Version 7.4. Thanks to Dmitry Nadezhin for reporting the bug with a helpful example. It was possible for users to change the attachments to built-in functions [47mbadge-userfn[0m and [47mapply$-userfn[0m, which support the implementation of [47m[apply$][0m. This is now prevented. For [47m[defequiv][0m, a [47m:doc[0m keyword argument was allegedly (in the documentation) supported but caused an ugly error. The [47m:doc[0m keyword argument is now fully eliminated. Thanks to Eric Smith for pointing out this issue. Fixed [47m:[0m[47m[pso][0m and related utilities [47m:[0m[47m[pso!][0m, [47m:[0m[47m[psof][0m, and [47m:[0m[47m[psog][0m, to avoid printing some error messages. Thanks to Keshav Kini for sending us an example to bring this bug to our attention. Also tweaked these utilities to avoid accumulating later event failure messages into the saved output for a previous proof attempt, and to avoid some bogus output when invoked before the first proof attempt of the session. When an invocation of [47m[defthmd][0m resulted in a macroexpansion error, the failure did not cause an error message to be printed. This has been fixed. Related tweaks improve error reporting, including a clearer error message when attempting to supply [47m:rule-classes nil[0m with [47mdefthmd[0m. Thanks to Keshav Kini for reporting these issues. When [47m[defattach][0m was provided the argument [47m:skip-checks nil[0m, a hard error was signaled. This has been fixed. The [47m[case-match][0m macro did not properly handle the [47m!sym[0m construct when the symbol, [47m!sym[0m, is not in the [47m"ACL2"[0m package. This has been fixed. Thanks to Alessandro Coglio for reporting this bug. Fixed handling of some guard violation error messages for built-in functions. For example, the form [47m(apply$-lambda 3 nil)[0m produces a guard violation, but before this fix, the error message reported an implementation error. Fixed the [47m:[0m[47m[puff][0m command to avoid certain errors involving [local] [events]. Redundancy notes could be seen during [47m[include-book][0m while loading the compiled file for a book. These notes (along with, perhaps, some other output) have been eliminated. Thanks to Eric Smith for pointing us to this problem with a reproducible example. We eliminated an obscure hard error mentioning the source function [47massume-true-false-if[0m, which could occur in the middle of a proof. Thanks to Dave Greve for pointing out this problem by sending us an illustrative example that we could run. It was possible to get a raw Lisp error from ill-formed calls of [47m[ec-call][0m not intended for execution, for example, [47m(defun foo (x) (non-exec (ec-call x)))[0m. This has been fixed. Certain syntactic requirements are normally applied to function bodies but not to theorems. However, these were being applied under calls of [47m[flet][0m. Consider the following example. (thm (flet ((foo (x) (car x))) (foo (mv-nth 1 (mv x x))))) This was rejected with an error: ``The expected number of return values for (MV X X) is 1 but the actual number of return values is 2.'' This has been fixed. Thanks to Eric Smith for bringing this problem to our attention. A bug has been fixed in the logical definition of the function, [47mread-file-into-string2[0m, which supports the macro, [47m[read-file-into-string][0m. Thanks to Keshav Kini for finding this bug and to Mihir Mehta for a query leading to Keshav's investigation. The previous release was supposed to include a new utility, [47m[checkpoint-summary-limit][0m, but that was missing. Thanks to Keshav Kini for pointing this out (and supplying the expected implementation). Fixed a bug in the guard for built-in function [47mwarning1-cw[0m, which could be seen for example by evaluating the form [47m(warning$-cw 'my-ctx "The :REWRITE rule ~x0 loops forever." 'foo)[0m. Thanks to Keshav Kini for bringing this issue to our attention. The definitions of the macros [47m[logand][0m, [47m[logior][0m, [47m[logxor][0m, and [47m[logeqv][0m were such that when any of these was applied to a single argument, the expansion was simply that argument. For example, [47m(logand (foo a))[0m expanded to [47m(foo a)[0m. These definitions failed to reflect the fact that in Common Lisp, an error may be signaled if that single argument does not evaluate to an integer. For example, the following definition was admitted: [47m(defun f (x) (declare (xargs :guard t)) (logand x))[0m; yet a raw Lisp error was signaled when attempting to evaluate [47m(f 'x)[0m, in ACL2 built on Allegro Common Lisp. This bug has been fixed: now, when any of these four macros is applied to a single argument, [47ma[0m, the expansion is [47m(the integer a)[0m. Thanks to Eric Smith for bringing this bug to our attention. Fixed [47m:[0m[47m[args][0m to avoid hard ACL2 error when applied to [47mIF[0m and to provide a clearer error message for Common Lisp functions not in ACL2. Thanks to Eric McCarthy for sending examples to point out these issues. A bug has been fixed that could cause an error when processing a legal [47m[flet][0m form, because the processing of a binding could interfere inappropriately with the processing of a subsequent binding, as in the following example. (defun f (x) x) (flet ((f (x) (cons x x)) (g (x) (f x))) ; processed with bad binding of stobjs-out for f (g 3)) Fixed an error message saying that ``It is illegal for supporters of DEFAXIOM events to receive attachments'' that failed during printing. Thanks to Nathan Guermond for sending an example to point out this bug. Changes at the System Level Fixed the use of `[47m<a href='URL'>...</a>[0m' so that if [47mURL[0m has the ampersand character in it, all will be well for both the web-based manual and text-based rendering (as when [47m:[0m[47m[doc][0m is used at the terminal or [47m[ACL2-doc][0m is used) provided that character is written as [47m&[0m in the documentation string. Previously, the web-based manual could fail to display the page for [47m&[0m in the documentation string, while with [47m&[0m used, the web-based manual could display the page but the text-based rendering showed [47m&[0m instead of simply [47m&[0m. Thanks to Cuong Chau for pointing out that the topic [47m[double-rewrite][0m was not being displayed in the online manual (back when [47m&[0m was used in the URL in the documentation string). The "clean" target of "make" has been deprecated since ACL2 Version 7.4 (released in March, 2017). Its replacement is target "clean-lite"; or, use target "clean-all" (or equivalently, "distclean") if you want a more thorough cleaning. (SBCL only) ACL2 has been updated so that it builds on recent SBCL versions. In particular, the build was broken for SBCL 1.4.7, as SBCL changed the ``RDTSC'' timing capability used in [memoization]. Thanks to Keshav Kini for help with this issue, which has been resolved in ACL2 source file [47mmemoize-raw.lisp[0m, as explained in the comment there about ``read-cycle-counter''. (CCL only) Raw Lisp error messages now mention the caller. Thanks to Eric Smith for pointing out that this information wasn't being provided in the ACL2 loop even though it was being provided in raw Lisp. EMACS Support Removed setting of the buffer coding system from [47memacs/emacs-acl2.el[0m. Thanks to Keshav Kini for suggesting this change. This should avoid certain modifications of ``unusual'' characters when saving a file. Experimental Versions The utility [47m[with-local-state][0m no longer causes an error in ACL2(p) with [parallel-execution] enabled. Thus, neither do [47m[fmt-to-string][0m and related utilities, which call [47mwith-local-state[0m.") (note-8-2 (release-notes) "ACL2 Version 8.2 (May, 2019) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.1 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-2-books] for a summary of changes made to the ACL2 Community Books since ACL2 8.1, including the build system. Also note that with each release, it is typical that the value of constant [47m[*ACL2-exports*][0m has been extended, and that some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features The built-in function [47m[fix-true-list][0m is now a macro that expands to a new built-in function, [47m[true-list-fix][0m, whose definition follows the efficient definition of [list-fix] that was in [community-book] [47mbooks/std/lists/list-fix.lisp[0m. In that book, [list-fix] is now a macro that expands to [47mtrue-list-fix[0m. The use of macro-aliases (see [add-macro-alias]) should generally make this change backward compatible for users of [47m[list-fix][0m. Thanks to Mihir Mehta for taking the lead on implementing these changes and to Jared Davis for permission to integrate definitions and documentation from his Kookamara books into the ACL2 sources. Made some improvements pertaining to [47m[apply$][0m: * A quoted lambda object that may ultimately be passed as the ``function'' for a call of [47m[apply$][0m may now have a [47m[declare][0m form. See also the discussion of [47mlambda$[0m below. * The macro [47m[warrant][0m no longer causes an error for the 800+ ACL2 primitives that are built into the definition of [47m[apply$][0m. Instead, it simply avoids generating (needless) conjuncts for those primitives. * The rewriter can now evaluate ground terms that involve calls of [47m[apply$][0m or [47m[badge][0m on user-defined function symbols. Note that correctness of such an evaluation depends on the truth of corresponding warrants, which will be [force]d if not known. * The event formerly named [47mdef-warrant[0m is now [47m[defwarrant][0m. This event may now be [redundant]; hence [47m[defun$][0m may also be redundant. * The [47m:[0m[47m[args][0m command now prints the [badge] and [warrant] for a function, and it avoids printing a package prefix in the case of [unknown-constraints]. * The optimization for caching ``tame compliant'' lambdas, introduced in the preceding release (see [note-8-1]), has been improved. It is no longer illegal to supply an abstract stobj as the so-called ``foundational'' (formerly ``concrete'') stobj in a [47m[defabsstobj][0m event. Thanks to Sol Swords for initiating a discussion leading to this enhancement. Calls of the function [47msynp[0m were formerly required to result from macroexpansion of [47m[syntaxp][0m or [47m[bind-free][0m calls, or at least nearly so. That restriction has been lifted, although the restrictions on calls of [47msynp[0m, [47msyntaxp[0m, and [47mbind-free[0m remain for hypotheses of rules of class [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, and [47m:[0m[47m[linear][0m, or resulting from evaluation of hypotheses of [47m:[0m[47m[meta][0m rules. Thanks to Sol Swords for requesting this change, so that [47m[defevaluator][0m forms can include [47msynp[0m. For calls of [47m:[0m[47m[pso][0m and related utilities ([47m:[0m[47m[pso!][0m, [47m:[0m[47m[psof][0m, and [47m:[0m[47m[psog][0m), the Time reported in the summary is now the original time, not time related to running [47m:[0m[47m[pso][0m. The macro [47mdelete-assoc[0m has been renamed [47m[remove1-assoc][0m, to reflect more clearly that at most one pair is removed, and also for consistency with Common Lisp nomenclature (where ``delete'' operations are generally destructive and ``remove'' operations are not). Moreover, other functions and macros whose name has prefix [47m"DELETE-ASSOC"[0m have been similarly renamed to have prefix [47m"REMOVE1-ASSOC"[0m; for example, [47mdelete-assoc-eq[0m has been renamed [47mremove1-assoc-eq[0m. (The old [47m"DELETE-ASSOC"[0m-based names still exist as macros --- indeed, as macro-aliases for their renamed versions (see [add-macro-alias]) --- but those may be deleted in the future.) Analogous functions and macros have been introduced that remove all pairs with a given key, rather than only one; see [remove-assoc]. (These and related theorems formerly appeared in the [community-book], [47mbooks/centaur/misc/remove-assoc.lisp[0m.) Thanks to Alessandro Coglio for a query and subsequent discussion leading to these changes. The [system-utilities] [47mall-ffn-symbs[0m and [47mall-ffn-symbs-lst[0m are now defined just as macro abbreviations for calls of system utility [47mall-fnnames1[0m, thus eliminating some source code duplication. We may deprecate [47mall-ffn-symbs[0m and [47mall-ffn-symbs-lst[0m in the future. The implementation of [47m[verify-termination][0m has been improved so that it no longer can generate (expand to) the form [47m(value-triple :redundant)[0m. Redundancy is now handled for [47mverify-termination[0m by checking redundancy of the generated [47m[defun][0m form. For an example that failed before this change, see [community-book] [47mbooks/system/tests/verify-termination/top.lisp[0m. Improvements have been made to the [summary] printed on conclusion of an event. It had been possible to have duplicates in the [47m"Hint-events"[0m field of the summary; that has been fixed. Also, the handling of [47m:[0m[47m[instructions][0m within [hints] has changed in the following two ways, to be consistent with the use of [47m:instructions[0m at the top level (rather than within [47m:hints[0m). The [47m"Rules"[0m and [47m"Hint-events"[0m fields of the summaries incorporate information from calls of the [proof-builder]. Also, the [47m"Hint-events"[0m field no longer contains [47m(:CLAUSE-PROCESSOR PROOF-BUILDER-CL-PROC)[0m. A new variable, [47mTRACE-LEVEL[0m, may be used in calls of [47mtrace$[0m; see [trace$]. This replaces the use of the state global variable of the same name, which has been eliminated, thus avoiding an error involving [47mTRACE-LEVEL[0m that is mentioned below. [47m[Defun-sk][0m is now sensitive to the [default-verify-guards-eagerness], and guard verification is always delayed to near the end of the generated event to avoid failures due to the small theory present at [47mdefun[0m time. Thanks to Alessandro Coglio for emails on leading to these improvements. Some additional small tweaks have been made to [47mdefun-sk[0m, in particular to check that there are not two or more distinct values associated with [47m[xargs][0m keywords [47m:verify-guards[0m, [47m:non-executable[0m, or (even if not distinct) [47m:guard-hints[0m. The function [47m[integer-range-p][0m now uses a [47m[type][0m [declaration] in place of the [47m:[0m[47m[guard][0m, which may slightly improve efficiency. Thanks to Eric Smith for suggesting this possibility. The macro, [47m[thm][0m, may now be used in event contexts, in particular in calls of [47m[encapsulate][0m and [47m[progn][0m and in [books]. (See [embedded-event-form].) Thanks to Ruben Gamboa for an email that led to this change. The [47m:[0m[47m[pf][0m command now does a more complete job of showing induction schemes for induction rules. (Some corresponding code cleanup has also been done.) [Warnings] about using [enable]d rules have been improved. Now, when using an [executable-counterpart] rule (which, admittedly, is unusual; it is equivalent to using the corresponding [definition] rule), the warning will correctly recommend disabling the definition rule instead of the executable-counterpart rule. The logical definition of [47mread-file-into-string2[0m (in support of [47m[read-file-into-string][0m) has been simplified, and no longer involves [untouchable] functions symbols. Thanks to Mihir Mehta for a query that led to this enhancement. The built-in function [47m[take][0m now has a recursive definition, exactly along the lines of the old theorem [47mtake-redefinition[0m from the community book [47mbooks/std/lists/take.lisp[0m (written by Jared Davis); this theorem has now been removed. The definition of [47mtake[0m uses [47m[mbe][0m, where the [47m:exec[0m component calls [47mfirst-n-ac[0m as before for execution efficiency. We thank Mihir Mehta for providing this enhancement, including updates to the books. New Features A new macro, [47m[loop$][0m, is an ACL2 version of the Common Lisp [47mloop[0m macro. A new construct, [47mlambda$[0m, may be used in place of [47mlambda[0m to be passed as the ``function'' for a call of [47m[apply$][0m. The syntactic requirements for such uses of [47mlambda$[0m are much less strict than for quoted [47mlambda[0m objects; in particular, the body need not be in translated form (see [term]). A new macro, [47m[partial-encapsulate][0m, allows one to introduce constrained functions without specifying all of the [constraint]s. This functionality was already available using a trust tag, by way of a rather convoluted application of [47m[define-trusted-clause-processor][0m; however, [47m[partial-encapsulate][0m may be used without a trust tag. See [partial-encapsulate], which in particular points to an example of typical usage, in [47mbooks/demos/partial-encapsulate.lisp[0m. Thanks to Sol Swords for requesting such a capability. There is now, by default, a limit of 9 on the nesting depth of inductions; see [induction-depth-limit] and to modify this default, see [set-induction-depth-limit]. A new [evisc-tuple], the [47m[brr-evisc-tuple][0m, controls printing inside the break-rewrite loop. See [brr-evisc-tuple] and [set-evisc-tuple]. Many of the [brr-commands] now abbreviate (``eviscerate'') by default using the new [47m[brr-evisc-tuple][0m (see above), and for each for those a corresponding command with suffix ``+'' print in full. For example, such commands include [47m:path[0m and [47m:path+[0m; see [brr-commands] for the full list of commands. Thanks to Stephen Westfold and others at the 2018 Developer's Workshop for discussing this issue. A new signature is legal for [47m[clause-processor][0ms, to support the return of rules and event names to be printed in the summary. See [make-summary-data]. [47m[Apply$][0m now handles functions that return multiple values. This has widespread ramifications. The structure of badges has changed. There is no longer an ``authorization-flag'' and there is now an ``out-arity'' slot in the badge. See [badge]. Every badged non-primitive function symbol now has a warrant. If [47mfn[0m is a warranted function symbol and returns more than one result then [47m(apply$ 'fn ...)[0m returns a list of the results, just as [47mfn[0m does in the logic. See [47m[apply$][0m. The warrant of a multi-valued function is just like that for a single-valued function except that [47m[mv-list][0m is used to coerce the output of the multi-valued function to a list. See [47m[warrant][0m. All [47mLAMBDA[0m objects and [47m[lambda$][0m expressions must be single-valued, but can use multi-valued functions to compute that value. Heuristic and Efficiency Improvements [47m[Make-event][0m expansions have often been reduced in size. (Technical note: [47mrecord-expansion[0m has been inserted only on expansions done directly under [47m[encapsulate][0m events, and some changes have also been made in how and when [local] events are elided from expansions.) The reduction in total sizes of [47m.cert[0m files for a complete (``everything'') regression was 8.8%, though in some cases the reduction was substantially larger: for example, the size of [47mbooks/centaur/fty/tests/deftranssum.cert[0m was reduced from 22,474,113 bytes to 16,910,530 bytes, a reduction of nearly 25%. A tweak to the rewriter can significantly speed up the use of hypothesis-free [meta] rules on large terms. Thanks to Mertcan Temel for sending an example that motivated this change, whose time was cut from 67 seconds to 19 seconds. Some small optimizations have been made for the generation of executable-counterpart (so-called ``*1*'') code (see [evaluation]). It has long been the case that certain prover routines, including handling of output from [meta] functions, transformed results into so-called ``quote-normal form'', where for example the [term] [47m(cons '3 '4)[0m is replaced by [47m(quote (3 . 4))[0m. Now, that transformation avoids recurring inside calls of [47m[hide][0m. We thank Mertcan Temel, who had a class of examples that motivated this change. One such example took 856.27 seconds of `prove' time before this change, but only 270.14 seconds after this change, thus eliminating 68.5% of the time. Proofs involving very large terms could be slowed down by checking those terms for calls of [47m[if][0m, in support of reporting [splitter]s of type if-intro. That check is now limited by avoiding subterms that are calls of [47m[hide][0m. Thanks to Mertcan Temel for supplying examples, one of which exhibited a proof time of 302.06 seconds that was reduced to 123.57 seconds with this change, and thanks to Sol Swords and Alessandro Coglio for helpful comments on possible enhancements. Bug Fixes Fixed a bug, probably a soundness bug (though we haven't tried to prove [47mnil[0m by exploiting it). The bug is in the computation of the ``immediate-canonical-ancestors'' of a function symbol, which is used in the implementations of [memoization] and [47m[defattach][0m, as well as in interactions between attachments and both [47m[defaxiom][0m events and [47m:[0m[47m[meta][0m rules. Thanks to Sol Swords for pointing out this bug and presenting a helpful example. Fixed three [proof-builder] bugs: * Fixed the proof-builder command, [47mdv[0m (see [ACL2-pc::dv]), for diving into calls of [47m[list][0m and [47m[list*][0m. * Fixed a bug in the proof-builder command, [47mgeneqv[0m. Thanks to Shilpi Goel for reporting this bug with an example. * The proof-builder numeric ``diving'' commands [47m1[0m, [47m2[0m, [47m3[0m, etc. --- and more generally, the [47mdv[0m command --- were broken when the current subterm is of the form [47m(if 't .. ..)[0m. This has been fixed. Thanks to Keonho Lee for reporting this bug. Eliminated a hard error labeled as ``Implementation error'' that could occur when submitting a [47m:[0m[47m[congruence][0m rule during the second pass of [47m[encapsulate][0m or the local incompatibility check in Step 3 of [47m[certify-book][0m. The error occurred when the equivalence relation of the rule had been defined locally, hence was missing during that second pass or local incompatibility check. Now, a useful ordinary (``soft'') error occurs, with a useful message. Thanks to Nathan Guermond for reporting this bug with a helpful example. It had been possible to enter an infinite loop after certain errors involving [wormhole]s and state global variables; now, a clean error occurs instead. The specific error motivating this change involved the combination of both tracing certain system functions (for example, [47mpop-accp-fn[0m) and calling [47m[accumulated-persistence][0m. That specific error has been eliminated by the change to [47m[trace$][0m involving variable [47mTRACE-LEVEL[0m that is mentioned in an item above. Fixed a bogus error produced by [47mdefchoose[0m forms containing unused variables with [47mignorable[0m declarations. Also eliminated an extra warning in the case of more than one bound variable with at least one of them unused, which could occur after [47m(set-ignore-ok :warn)[0m has been evaluated. Thanks to Sol Swords for finding these bugs and for supplying code that we installed to fix them. Fixed an inefficiency in book certification due to calling [47m[fast-alist-free-on-exit][0m on the wrong objects. Thanks to Sol Swords for pointing out this problem. The [47mmake TAGS[0m command could fail to do a proper check that the [47metags[0m program is installed, resulting in a failure when attempting to build an ACL2 executable. This has been fixed. Thanks to Johannes Altmanninger for reporting this problem in GitHub Issue #955. When a function that calls [47m[apply$][0m (or [47m[apply$-userfn][0m, [47m[badge][0m, or [47m[badge-userfn][0m) has been [memoize]d with a non-[47mnil[0m value for argument [47m:aokp[0m, its memo table may need to be flushed when removing a [badge]. (Such removal typically occurs by undoing a call of [47m[defun$][0m or [47m[defwarrant][0m, perhaps because they are [local] to an [47m[encapsulate][0m event or to a book.) However, such flushing was not being done. That has been fixed. See new [community-book] [47mbooks/system/tests/apply-with-memoization.lisp[0m for examples. Among the changes made to the source files that are related to this fix: the ``Essay on Memoization with Attachments'' has been enhanced to discuss the implementation of such flushing; and functions [47mdoppelganger-apply$-userfn[0m and [47mdoppelganger-badge$-userfn[0m (formerly called [47mconcrete-apply$-userfn[0m and [47mconcrete-badge$-userfn[0m), which are still not advertised, are now introduced with [47m[partial-encapsulate][0m (hence have unknown constraints) and are now [untouchable]. Changes at the System Level The [documentation] topic, [system-utilities], is now about only utilities that pertain to the ACL2 system implementation, rather than arbitrary built-in utilities. Thus, each of the following now has its own topic, rather than being described in [system-utilities]. (Thanks to Alessandro Coglio for suggesting this reorganization.) * [47m[alist-keys-subsetp][0m * [47m[alist-to-doublets][0m * [47m[cons-count-bounded][0m * [47m[evens][0m * [47m[keyword-listp][0m * [47m[merge-sort-lexorder][0m * [47m[odds][0m * [47m[packn][0m * [47m[packn-pos][0m * [47m[pairlis-x2][0m * [47m[pairlis-x1][0m Documentation pertaining to [47m[apply$][0m and related topics has been extended significantly. (GCL only) Eliminated compiler output (by setting GCL raw Lisp variables [47m*compile-verbose*[0m and [47m*load-verbose*[0m to [47mnil[0m). A new documentation topic, [efficiency], suggests some ways to speed up proofs and evaluation. The ACL2 community is encouraged to extend (and more generally, improve) this topic! (LispWorks only) Bytes allocated are now reported in LispWorks (formerly, only in CCL and SBCL) by [47m[time$][0m and [47m[memsum][0m. A new documentation topic, [make-event-example-3], explains the new implementation of [47m[thm][0m, thus providing insight into several common implementation techniques used with [47m[make-event][0m. A new documentation topic, [rule-classes-introduction], provides a basic guide to which sorts of rules to create from your theorems. Thanks to Mihir Mehta for encouraging the development of this topic. Fixed ``[47mmake STATS[0m'' (which is invoked by ``[47mmake DOC[0m'') to generate a result file [47mdoc/acl2-code-size.txt[0m that gives accurate statistics on code size on Linux. (The relevant [47mgrep[0m commands in file [47mdoc/create-acl2-code-size[0m needed the [47m-a[0m option on Linux.) Updated the CCL installation instructions formerly at :DOC ccl-updates. The topic is now [ccl-installation]. This now replaces the installation instructions file [47minstallation/ccl.html[0m; thus, the ACL2 community is now welcome to improve these instructions. Thanks to Eric Smith for discussion that led to this change and to Keshav Kini and Alessandro Coglio for helpful feedback. The makefile target [47mcertify-books[0m has been deprecated in both [47mGNUmakefile[0m and [47mbooks/GNUmakefile[0m. Thanks to the acl2-books email list (in particular we got feedback from Alessandro Coglio, Shilpi Goel, David Rager, Eric Smith, and Sol Swords, all helpful) for working through this issue. A message is now printed when loading file [47m~/acl2-init.lsp[0m at startup. EMACS Support Fixed the [ACL2-doc] browser so that it can handle topic names with the single-quote ([47m'[0m) and comma ([47m,[0m) characters, by escaping them. Fixed Emacs support for the [proof-builder] dive command (see [ACL2-pc::dive]), [47mcontrol-t control-d[0m, to eliminate trailing zeros, since those are (and have been) disallowed by that command. A new [47m[ACL2-doc][0m command is the question-mark character ([47m?[0m), which goes to a page with one-line command summaries. Thanks to Warren Hunt for a request leading to this enhancement. Experimental Versions") (note-8-3 (release-notes) "ACL2 Version 8.3 (April, 2020) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.2 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-3-books] for a summary of changes made to the ACL2 Community Books since ACL2 8.2, including the build system. Also note that with each release, it is typical that the value of constant [47m[*ACL2-exports*][0m has been extended, and that some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features It is now permitted for an evaluator to be ancestral in a metafunction or clause-processor. See [evaluator-restrictions], or see the source code comment ``Essay on Correctness of Meta Reasoning'', for discussion of the remaining restrictions. Thanks to Sol Swords for requesting this improvement and for many helpful discussions. Moreover, he found a bug in a proof in the above Essay, which has been fixed; he made a key observation that led to completion of that fix. Also thanks to Rob Sumners for helpful discussions. The [accumulated-persistence] utility no longer overcounts accumulated frames due to nested (recursive) rule applications. Although that shortcoming was documented, it was unfortunate and we thank Sol Swords for an email that nudged us into making this improvement and provided helpful insight, and Eric Smith for suggesting this improvement more than 10 years ago (!). In a (new-style) signature, any symbol whose [47m[symbol-name][0m is [47m"*"[0m now designates a non-[stobj] argument. Formerly, only the symbol [47m*[0m in the [47m"ACL2"[0m package could be used in that way. Thanks to Jared Davis for suggesting (in 2007!) that we consider such a change. More functions can now be given [warrant]s. In particular: the requirement of a natural number measure for recursive definitions has been relaxed to allow lexicographic combinations of natural numbers as defined by the [47mllist[0m function in the Community Books at [47mbooks/ordinals/[0m, and it is possible to warrant some functions that use local [stobj]s as long as they don't call [47m[apply$][0m. See [defwarrant]. The function [47m[symbol-name-lst][0m is now a [guard]-verified [logic]-mode function (formerly it was a [program]-mode function). Thanks to Alessandro Coglio for suggesting that it might be good to document this function, which led us to this change (and to its being documented). The pattern language for the macro, [47m[case-match][0m, now includes the case [47m(quote~ sym)[0m, where [47msym[0m is a symbol and this case matches any symbol whose [47m[symbol-name][0m is [47m(symbol-name sym)[0m. The following symbols, when used in special syntactic roles in the macro [47m[loop$][0m, may be in any package: [47mfor[0m, [47min[0m, [47mon[0m, [47mfrom[0m, [47mto[0m, [47mby[0m, [47mof-type[0m, [47mwhen[0m, [47muntil[0m, [47msum[0m, [47mcollect[0m, [47malways[0m, [47mthereis[0m, and [47mappend[0m. Thanks to Mertcan Temel for requesting this enhancement. [47m:Expand[0m [hints] now act more reliably for [equality-variants], by expanding away [guard-holders]. Thanks to Sol Swords for supplying this enhancement and sending the following example that works now but formerly failed: (defthm member-of-cons (equal (member x (cons x y)) (cons x y)) :hints(("Goal" :in-theory (disable member) :expand ((member x (cons x y)))))) An analogous improvement has been made for [47m:by[0m, [47m:use[0m, and [47m:hands-off[0m hints. The macros [47m[defequiv][0m, [47m[defrefinement][0m, and [47m[defcong][0m now conform to the following principle discussed in a new [documentation] topic, [packages-for-generated-symbols]: ideally, utilities generate symbols in the [47m[current-package][0m, at least by default. These three macros now have a [47m:package[0m keyword argument whose default value is [47m:current[0m; with this value the macros conform to the above principle. See their [documentation] topics. To get the previous behavior, use the [47m:legacy[0m value. (Another way to deal with failures caused by this change may be to fix packages when referring to generated symbols, such as changing [47macl2::x-equiv[0m to [47mx-equiv[0m.) In particular, the [47m:legacy[0m option was used to update definitions in the [community-books] for macros that generate [47m[defcong][0m forms. Also, all three macros now do some error-checking (rather than leaving that entirely to the generated [47m[defthm][0m form), and the unsupported [47m:doc[0m keyword argument has been removed from these macros. Thanks to Pete Manolios for suggesting all of these changes, and for providing not only implementations but also modifications to the [community-books]. The translation of a term [47m(and t u0)[0m is [47m(if 't u1 'nil)[0m, where [47mu1[0m is the translation of [47mu0[0m. That term, [47m(if 't u1 'nil)[0m, is now generally displayed to the user (``[untranslate]d'') as [47m(and t u0)[0m, but formerly it was displayed as [47mu0[0m, which could be confusing. Thanks to Stephen Westfold, who sent an example showing how, when using the [proof-builder]'s [47mREWRITE[0m command to replace a subterm [47ma0[0m by [47mt[0m in a term [47m(and a b)[0m could lead to confusion, since the resulting [47m(and t b)[0m was printed only as [47mb[0m. Note: For Boolean contexts, the analogous change was also made for terms [47m(and u0 t)[0m. It no longer causes an error to call [47m[trans-eval][0m on an expression that references a locally-bound [47m[stobj][0m, that is, one bound by [47m[with-local-stobj][0m or [47m[stobj-let][0m. The user is responsible for understanding that when calling [47mtrans-eval[0m, all stobj variables in the supplied expression refer to globally-bound stobjs, that is, stobjs stored in the [47muser-stobj-alist[0m field of the ACL2 [47m[state][0m. See the new documentation topic, [trans-eval-and-locally-bound-stobjs], for relevant discussion. (Another topic, [user-stobjs-modified-warnings], may also be helpful for understanding the interaction of [47mtrans-eval[0m with stobjs.) Thanks to Sol Swords for suggesting this change and convincing us of its suitability. The [47m[defstobj][0m event now supports [stobj]s with fields that are hash tables in raw Lisp but are represented logically as association lists. Thanks to Sol Swords for providing not only the design but also the implementation, which was moved from community book [47mbooks/add-ons/hash-stobjs.lisp[0m into the ACL2 sources (with small modifications to both the new code and existing code). That book still provides lemmas that may be helpful for reasoning about hash-table fields, as well as some tests. See also [47m[defstobj][0m. Added suitable [guard]s, with custom error messages, to [47m[add-invisible-fns][0m and to [47m[remove-invisible-fns][0m. Also removed confusing messages for each in the case of redundancy. Thanks to Pete Manolios for pointing us to a bug in the documentation for the latter (which we have fixed), which led us to the addition of guards. The notion of [3muntouchable[0m macro is no longer directly supported. Specifically: the form [47m(push-untouchable SYM t)[0m is now illegal if [47mSYM[0m is already the name of a macro; and after this call of [47m[push-untouchable][0m it is illegal to define [47mSYM[0m as a macro. However, a macro can be made effectively untouchable by defining it with the new utility, [47m[defmacro-untouchable][0m. Note that the alleged support for untouchable macros was already incomplete, as explained in an example in the form [47m(defxdoc note-8-3 ...)[0m in [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m. The [event] macro, [47m[thm][0m, is now treated like [47m[defthm][0m in the following way: if keyword [47m:hints[0m is supplied, then the hints are checked syntactically when skipping proofs (see [ld-skip-proofsp]) except during [47m[include-book][0m or the second pass of [47m[encapsulate][0m. For example, evaluation of the form [47m(thm (equal x x) :hints bad-hints)[0m now causes an error after evaluating [47m(set-ld-skip-proofsp t state)[0m, while before this change, it did not. The default slow-alist-action (see [slow-alist-warning]) is now [47m:break[0m instead of [47m:warning[0m in ACL2. (It remains [47m:warning[0m in ACL2(p); see [unsupported-waterfall-parallelism-features].) For a user-defined [47m:[0m[47m[induction][0m rule to be applied, it is no longer required for the induction scheme associated with a recursive definition to be enabled. For an example of the effect of this change, see the [community-book], [47mbooks/system/tests/induction-rule-with-disabled-scheme.lisp[0m. Thanks to Pete Manolios for reporting this issue, including the sending of the events in that book. Also see [induction] (as that documentation has been updated). An undocumented kind of [fake-rune] is no longer reported by [47m[show-accumulated-persistence][0m. Thanks to Eric Smith for bringing this issue to our attention. The algorithm for removing [guard-holders] has been modified to avoid diving into calls of [47m[hide][0m. However, it is possible to obtain the former behavior; see [guard-holders]. Since its earliest years, ACL2 uses evaluation to simplify ground terms (terms with no free variables). ACL2 would sometimes generate a call of [47m[hide][0m around a term that fails to evaluate because of an attempt to call a constrained function. Now, that call incorporates a comment saying which constrained function is responsible for the failure. See [comment]. Also see [hide] for how to fix proof failures caused by this new behavior by using [47m:expand[0m [hints] or even by turning off this new behavior using [47m[defattach][0m. Thanks to Rob Sumners (in 2003), Francisco J. Martin-Mateos (in 2004), and Anna Slobodova (in 2005), perhaps among others, for discussions leading to this enhancement. Both [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m have been made more robust. Related changes include: * A new table, [47mpuff-included-books[0m, generally prevents the same book from being puffed more than once. * Book directories are tracked more carefully, which can prevent errors. * We no longer allow [47m:puff*[0m to puff non-trivial [47m[encapsulate][0m events. (For a technical discussion of reasons for this change, see comments in function [47mpuffed-command-sequence[0m in ACL2 source file [47mld.lisp[0m.) * Changes to the [47m[ACL2-defaults-table][0m no longer persist outside the scope of a puffed [47mencapsulate[0m event. * A [47m[theory-invariant][0m event no longer stores the event [47m(in-theory (current-theory :here))[0m in the [world]. New Features A new [47m[xargs][0m keyword, [47m:guard-simplify[0m (default [47mt[0m), controls certain simplifications that may be applied to the guard conjecture while generating the initial goal. Setting it to [47mnil[0m skips all simplifications that depend on the set of currently [enable]d rules. See [verify-guards]. Thanks to Sol Swords for designing this feature and providing its implementation, along with documentation and corresponding adjustments to the community books. Now [47m[defstub][0m accepts the same keywords as [47m[encapsulate][0m, both for the new-style signatures and for the old-style signatures. Thanks to Alessandro Coglio for suggesting and implementing this enhancement. New function [47m(maybe-flush-and-compress1 name ar)[0m calls [47m(flush-compress name)[0m and then returns [47m(compress1 name ar)[0m, except that all this is skipped if the given array is already compressed. A new utility, [47m[swap-stobjs][0m, does what its name suggests: it swaps [stobj]s. Thus, if [47mst1[0m and [47mst2[0m are stobjs then after returning from execution of a call [47m(swap-stobjs st1 st2)[0m of [47mswap-stobjs[0m, the global value of stobj [47mst1[0m will be the old value of [47mst2[0m and the global value of stobj [47mst2[0m will be the old value of [47mst1[0m. See [swap-stobjs]. Thanks to Sol Swords for requesting this feature and for helpful discussions about it. By invoking [47m(set-absstobj-debug :ignore)[0m, which requires an active trust tag (see [defttag]), one can defeat invariance checks for abstract stobj fields that otherwise are protected by specifying [47m:protect t[0m (or by using the [47m:protect-default[0m keyword to get that effect). See [defabsstobj]. Thanks to Sol Swords for suggesting consideration of adding some such capability. In a few preliminary tests we found an average drop of about 3.5% in the time it took to run the tests. It is now permitted to define functions in which recursive calls occur from inside [47m[loop$][0m statements. See [47m[loop$-recursion][0m. Such functions do not automatically suggest induction schemes. Furthermore, care must be taken when formulating inductively provable theorems about such functions. See [loop$-recursion-induction] and [47m[definductor][0m. You can now change the second line in the startup banner for a GitHub version of ACL2 obtained between releases. See [startup-banner]. Thanks to Andrew Walter for requesting this enhancement. Heuristic and Efficiency Improvements ACL2 keeps a complete list of all the runes in the tau database (see [introduction-to-the-tau-system]). Formerly this list was duplicate-free, but that is no longer the case. As a result we have seen some faster performance; in particular, this change has cut 17% from the time to include the community book, [47m"centaur/sv/top"[0m. Made slight efficiency improvement for [table] update ([47m:put[0m) events. Improved efficiency of the maintenance of [stobj]-related arrays (the so-called stobj accessor arrays) by using the new function, [47m[maybe-flush-and-compress1][0m. That code is related to printing stobj field accesses using field names rather than indices. (For background on printing untranslated terms, see [term].) For example, after evaluating the form [47m(defstobj st fld)[0m, the form (thm (equal (fld st) xxx) :hints (("Goal" :in-theory (disable nth)))) produces the (untranslated) goal [47m(EQUAL (NTH *FLD* ST) XXX)[0m rather than [47m(EQUAL (NTH 0 ST) XXX)[0m. A further change has been to reduce the frequency of ensuring that those [arrays] are up-to-date. (Technical note: this latter change is to source function [47mupdate-wrld-structures[0m, which has an explanatory comment, including an example of a 2.6% time reduction.) Improved the speed of [theory] updates by avoiding repeated length computations. As a result, we have seen about a 5% time reduction on MacOS, and between 3% and 4% on Linux, for executing the form, [47m(include-book "centaur/sv/top" :dir :system)[0m. The definition of the macro [47m[ec-call][0m has been tweaked to speed up compilation in some cases when the host Lisp is SBCL. In particular, for admitting the definition of [47mapply$-prim[0m in [community-book] [47mbooks/projects/apply-model-2/apply-prim.lisp[0m with host Lisp SBCL, we have seen the time decrease from 1294.33 seconds to 8 seconds. A heuristic for ``lazy'' rewriting of calls of [47mmv-nth[0m has been made much more efficient in some cases. Thanks to Sol Swords for investigating performance issues leading him to implement such a change, and for making modifications to [community-books] so that they continue to certify after the change. Those interested in implementation details may start with source function [47msimplifiable-mv-nth1[0m. The raw Lisp representation of [stobj]s has been improved to avoid some indirection in two ways: a scalar field (one that is not an array or hash table) with non-trivial type had been wrapped in a one-element array, but no longer; and if there is only one field, and it is an array or hash table, then that field is the entire stobj. (The first change is however avoided when the host Lisp is GCL.) Thanks to Warren Hunt and Sol Swords for suggesting these changes. Technical note: in the course of making these changes, a bug was exposed in source function [47mraw-ev-fncall[0m; that has been fixed. Reduced the computation and consing for [theory] management, which might reduce time by a percent or two when including some books. (Technical note. The idea was to expand the cases in which the use of [47m[compress1][0m is replaced by more efficient code. That code is specific to enabled structures and may be found in ACL2 source function [47mupdate-enabled-structure-array[0m. We also arranged, in [47mload-theory-into-enabled-structure[0m, to double the array size when that exceeds the expansion by a minimal suitable multiple of 500.) Changed how [compound-recognizer] rules are stored in the logical [world] (per function symbol, rather than in a single alist), which a few experiments suggest might reduce time by a couple percent or so. A tweak was made to how properties are ordered when stored in the ACL2 logical [world], which experiments show provides small speed-ups. (Technical note: the change is to constant [47m*current-acl2-world-key-ordering*[0m, and also, functions [47m[symbol-class][0m and [47m[logicp][0m avoid calling [47m[getprop][0m for the symbol, [47mcons[0m.) ACL2 now avoids [summary] calculations during [47m[include-book][0m. We have seen this change cut more than 9% of the time for the event [47m(include-book "centaur/sv/top" :dir :system)[0m. We now avoid translation of [47m[default-hints][0m for termination proofs during [47m[include-book][0m. We have seen this change cut more than 4% of the time for the event [47m(include-book "centaur/sv/top" :dir :system)[0m. ACL2 now saves, in [certificate] files, the translated bodies of [47m[defun][0m and [47m[defthm][0m [events]. (See [term] for a discussion of translated terms.) This can speed up [47m[include-book][0m; for example, we have measured approximately a 3% reduction in time for the event, [47m(include-book "centaur/sv/top" :dir :system)[0m, but with a space trade-off of about 41% more bytes allocated. (Implementation note: the relevant algorithms and code are discussed in an expanded version of the Essay on Cert-data in the ACL2 source code.) Thanks to Eric Smith for pointing out a bug (which we then fixed) in a preliminary implementation of this feature. Some stack overflows may be avoided by a change to a built-in system function, [47mcons-count-bounded-ac[0m, so that it is now tail recursive as it CDRs the list, rather than as it takes the CAR. Thanks to Shilpi Goel for reporting the problem with an example and to Sol Swords for suggesting this fix. That example exhibited a second stack overflow, due to a built-in memoized system function that is no longer called when computing a call of the built-in system function, [47mpkg-names[0m. The second pass of [47m[encapsulate][0m now uses [fast-alists] when calculating new triples in the logical [world] (in ACL2 system function [47mnew-trips[0m). We have seen this change result in cutting the time by 4.7% and the bytes allocated by 34% for including the community book, [47m"centaur/sv/top"[0m. Computation of the [guard] proof obligation has been sped up in some cases involving evaluation of ground terms (terms without free variables). Thanks to Warren Hunt for sending us an example that prompted us to make this change. Bug Fixes As noted in the documentation for [lemma-instance], ACL2 may avoid proving some constraints required for [functional-instantiation] that were previously proved. There was such support even in the case that the previous proof was done on behalf of a [47m[defattach][0m event, but that support has been made more complete (by keeping more functional substitutions in canonical form). A hard Lisp error has been fixed that could occur (probably only rarely) after adding rules of class [47m:[0m[47m[definition][0m that introduce recursion. The function [47m[meta-extract-formula][0m could return a non-trivial value (i.e., not [47m'T[0m) when applied to a [program]-mode function. We thank Sol Swords for reporting this bug with a proof of [47mnil[0m that exploited it. This soundness bug has been fixed. That work led us to fix the following related bugs (which could also be soundness bugs, though we have not checked). First, the function [47m[fncall-term][0m could similarly return a non-trivial value when applied to a program-mode function. Second, the utility [47m[mfc-rw][0m, as well as other such [47mmfc-xx[0m utilities in support of [extended-metafunctions] and [47m[meta-extract-contextual-fact][0m, could be called on terms containing program-mode function symbols. Eliminated an error occurring when attempting to compute the guard proof obligation for a constrained function, in particular, when using the [47m:[0m[47m[gthm][0m utility on such a function (also see [guard-theorem]). Thanks to Alessandro Coglio for pointing out this bug and for noting that [47mt[0m could be a reasonable result for the guard theorem in such cases. Fixed ACL2 raw Lisp error caused by [add-default-hints!]. Thanks to Pete Manolios for debugging this problem. Fixed a bug in the [proof-builder] command [47mapply-linear[0m (and its abbreviation, [47mal[0m), which was making it impossible to save an event after an interactive session that includes such a command. Thanks to Mihir Mehta for bringing this bug to our attention and sending an example. Fixed a bug in [47m[defun-sk][0m, which was generating a [47m[verify-guards][0m or [47mverify-guards?[0m event with [47m:guard-hints[0m instead of [47m:hints[0m. Thanks to Alessandro Coglio for reporting this bug and providing the fix. The use of [47m:stack :pop[0m in the macro [47m[with-output][0m failed to restore [gag-mode] properly. For example, the use of [47m(with-output :stack :push :gag-mode nil (with-output :stack :pop <form>))[0m failed to run [47m<form>[0m with the existing value for gag-mode (default: [47m:goals[0m). Thanks to Mihir Mehta for a query that led us to make this fix. Technical note: state global [47minhibit-output-lst-stack[0m is now a list of pairs [47m(inhibit-output-lst . gag-mode)[0m; see [with-output]. The [proof-builder]'s [47mDV[0m command was broken for expressions of the form [47m(if t term1 term2)[0m; for example, [47m(verify (if t x y))[0m followed by [47m1[0m, [47m2[0m, or [47m3[0m caused a raw Lisp error. Thanks to Stephen Westfold for bringing this bug to our attention and pointing out the fix. We fixed a bug in the implementation of [47m[encapsulate][0m that could cause a hard ACL2 error (``Unexpected expansion-alist ... for second pass of encapsulate''). Thanks to Pete Manolios for sending an example that exhibited this bug. (A slightly simplified version of his example may be found in a comment in the definition of function [47mencapsulate-pass-2[0m, ACL2 source file [47mother-events.lisp[0m.) [47m[Defstobj][0m now provides a suitable error message, instead of an implementation error, when new names are duplicated after renaming. Here are examples that now have improved error messages. (defstobj st x :renaming ((create-st x))) (defstobj st fld :renaming ((fld create-st))) (defstobj st fld1 fld2 :renaming ((fld1 fld) (fld2 fld))) We fixed an obscure error message when attempting to [memoize] either [47mIF[0m or [47mRETURN-LAST[0m, and we improved the [memoize] documentation to mention these and other restrictions on what can be memoized. Fixed erroneous [type] declarations in array copying functions. (Technical notes. (1) It's not clear that these bugs have ever had any effect. (2) Those source code functions have been renamed by dropping their [47m"stobj-"[0m prefixes from [47mstobj-copy-array-xxx[0m, now that one of them has application to other than stobjs, in new code mentioned above for enabled structures.) Fixed the process of translating the [type-spec], [47mstandard-char[0m, into a [term]. For example, the following definition failed but now succeeds: [47m(defun foo (x) (declare (type standard-char x)) (cons 3 x))[0m. Fixed a bug that could cause the wrong [stobj] to be displayed by [47m[print-gv][0m, when congruent stobjs with a single bit-array field are involved. See a comment in ACL2 source function [47mapply-user-stobj-alist-or-kwote[0m for an example of this bug. When including a book that is uncertified because of a stale [certificate] file, ACL2 was inappropriately using information about [type-prescription] rules (specifically, those computed by the system at definition time) that was stored in that certificate. This has been fixed, thanks to a bug report from Eric Smith about a related feature mentioned above, on saving translated bodies in certificate files. Moreover, the relevant system function, [47minclude-book-fn1[0m, has been modified to do a better job of ignoring certificate files of uncertified books. The utility [47mset-saved-output[0m has been badly broken for years, but without complaints (other than from one of us shortly before the release), suggesting that it hasn't been directly called by users. So we have eliminated it. Changes at the System Level The makefile target [47mcertify-books[0m has been removed from [47mGNUmakefile[0m and [47mbooks/GNUmakefile[0m. It was deprecated in the preceding release, where we thanked the acl2-books email list (in particular we got feedback from Alessandro Coglio, Shilpi Goel, David Rager, Eric Smith, and Sol Swords, all helpful) for working through this issue. The keyword [47m:ACL2[0m is now a member of the Lisp global, [47m*features*[0m, which allows other programs to use read-time conditionals [47m#+acl2[0m / [47m#-acl2[0m to indicate the presence or absence of ACL2. Thanks to Andrew Walter for suggesting that this might be useful, for example for Quicklisp code. EMACS Support The command `[47mCtl-t p[0m' now works in Emacs 25. The [ACL2-doc] browser for ACL2+books documentation can be extended with a new command, [47mU[0m, to open a URL (or in some cases, a file) in a browser. See file [47memacs/acl2-doc-open-url.el[0m for more information. Experimental Versions") (note-8-4 (release-notes) "ACL2 Version 8.4 (August, 2021) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.3 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-4-books] for a summary of changes made to the ACL2 Community Books since ACL2 8.3, including the build system. Also note that with each release, it is typical that the value of constant [47m[*ACL2-exports*][0m has been extended, and that some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features [47m[Apply$][0m, [47m[lambda$][0m, and [47m[loop$][0m may be used with [badge]d [47m:[0m[47m[program][0m mode functions in top-level evaluation. To assign a badge to a [47mprogram[0m mode function, use the new feature [47m[defbadge][0m. For calls of the form [47m(HIDE (COMMENT "..." ...))[0m, the string is a bit more descriptive. See [comment] and see [hide]. Thanks to Mark Greenstreet for helpful discussions leading to this change. The [events] [47m[defun-nx][0m and [47m[defund-nx][0m now [disable] the [executable-counterpart] [rune] for the new function symbol. Thus, after either of these introduces function symbol [47mf[0m, the ACL2 rewriter will no longer attempt to simplify a call of [47mf[0m on concrete arguments by using evaluation (unless of course that executable-counterpart is enabled first). Thanks to Mark Greenstreet for an email leading to this change. The implementation of this change also fixes a bug: when the [default-defun-mode] is program mode, [47m[defund-nx][0m now [disable]s the definition [rune] for the new function, but that was not previously the case. Some built-in functions supporting the macro, [47m[position][0m, now [47m[fix][0m (coerce) their accumulator argument to a natural number. Thanks to Mihir Mehta for supplying the initial such changes, for the purpose of avoiding numeric type hypotheses. After that, thanks to email correspondence from Warren Hunt, we added built-in [47m:[0m[47m[type-prescription][0m rules for those same functions so that ACL2 [type-set] reasoning infers that [47mposition[0m always returns either [47mnil[0m or a natural number. The macro [47m[defconst][0m no longer accepts an optional documentation string (which was already being ignored). Thanks to Eric Smith and Alessandro Coglio for suggesting this change, which avoids potential confusion; consider for example [47m(defconst *c* () "abc")[0m. Two improvements have been made in support of the [47m[case-match][0m macro. (1) The built-in constant [47m[*ACL2-exports*][0m now includes the [47m"ACL2"[0m package symbol, [47mquotep~[0m. (2) The built-in function [47msymbol-name-equal[0m is now a [guard]-verified [47m:[0m[47m[logic][0m mode function. Thanks to Stephen Westfold for email leading to these changes: for (1), pointing out that the special role of [47mquotep~[0m for the [47m[case-match][0m macro applies only to that [47m"ACL2"[0m package symbol, not to other symbols with the same name; and for (2), pointing out that the expansion of a [47mcase-match[0m call that invokes [47mquotep~[0m for matching was introducing [47m:[0m[47m[program][0m mode code. A call of [47m[comment][0m is more often inserted when the prover inserts a call of [47m[hide][0m. See [comment] for a discussion of such ways in which [47mcomment[0m is used. When a [rewrite] rule's conclusion is of the form [47m(equiv term1 term2)[0m where [47mequiv[0m is a known [equivalence] relation, ACL2 generally creates the rule to rewrite an instance of [47mterm1[0m to the corresponding instance of [47mterm2[0m, in a context where it is sufficient to preserve [47mequiv[0m. However, if that rule is illegal, for example because it would rewrite a variable, then the rule is effectively treated as [47m(equal (equiv term1 term2) t)[0m. This behavior is not new, but now an explanatory [observation] is printed when this happens, as for [47mfoo[0m in the following example. Thanks to Mihir Mehta for suggesting such an enhancement. (defun my-equiv (x y) (equal x y)) (defequiv my-equiv) (in-theory (disable my-equiv)) ; optional (avoids warnings for the next form) (defthm foo (my-equiv x (car (cons x x)))) A trust tag (see [defttag]) is now required to set the [ld-prompt] to a non-Boolean value, other than the [brr] prompt, since that can cause printing of the prompt to modify state in rather arbitrary ways. Improved translation of function calls, especially those that involve congruent [stobj]s, including better error messages, much improved code comments, and simplified code. Thanks to Sol Swords for sending an example with a misleading error message. The error message has been improved when a [47m:[0m[47m[linear][0m rule is illegal due to simplification of its conclusion to a constant by ground evaluation. Thanks to Eric Smith for suggesting such an improvement. It is no longer an error to repeat a [47m[defun-sk][0m event after removing or adding the [xargs] [declaration], [47m:guard t[0m; the latter is now essentially redundant. It is similarly no longer an error to repeat a [47mdefun-sk[0m event by adding, removing, or changing keyword [47m:guard-hints[0m in an [47mxargs[0m declaration. Thanks to Alessandro Coglio for reporting these issues. The set of [47m[apply$][0m primitives has been expanded. These are built-in function symbols that do not need a [warrant] when reasoning about the application of [47mapply$[0m to them or using them in [47m[loop$][0m. Thanks to Alessandro Coglio for noting that some built-in [47m:[0m[47m[logic][0m-mode functions do not have warrants, in particular, [47m[sublis-var][0m. Improved [47m[defwarrant][0m to be a no-op for [47m[apply$][0m primitives. ACL2 now points out when specious simplification takes place; see [specious-simplification]. Formerly this was the case only with [gag-mode] turned off; still, [47mprove[0m output needs to be on for any such message to be printed (see [set-inhibit-output-lst]). Thanks to Mihir Mehta for a query that led to this enhancement. For [47m[fmt][0m directives [47m~f[0m and [47m~F[0m, ACL2 now uses the alist component of the [47mevisc-tuple[0m argument and the global [47m[evisc-table][0m. Previously it used these only for directives [47m~x[0m, [47m~y[0m, [47m~X[0m, and [47m~Y[0m (and deprecated directives [47m~p[0m etc.; see [fmt]). Thanks to Eric Smith for a query leading to this enhancement. Reporting has been improved when encountering possible invariance violations for abstract [stobj]s. Now, when that happens an ``illegal-state'' is entered, as indicated by the prompt, and instructions are printed for how to proceed at your own risk. See [illegal-state]. A [47m[table][0m's guard may now reference the ACL2 [state]. Thus, it may now be a term involving (at most) the variables [47mWORLD[0m, [47mENS[0m, and [47mSTATE[0m. It is now always redundant to [47m[unmemoize][0m a function symbol that is not currently [memoize]d. See [redundant-events]. The ``basic'' ruler-extenders (see [rulers]) now include not only the symbols [47m[return-last][0m and [47m[mv-list][0m but also the symbol [47m[if][0m. As before, the termination analysis always continues through the true and false branches of [47mIF[0m calls; but now, by default, it also continues through the first argument of an [47mIF[0m call. Thanks to Eric Smith for suggesting this improvement and testing it on some proprietary books. When supplying [47mstate[0m as an argument to [47m[defun-nx][0m (or [47m[defund-nx][0m), it is no longer necessary to declare [47mstate[0m as a [stobj] or use [47m[set-state-ok][0m. Thanks to Eric Smith for suggesting the possibility of this change. It had been the case that if [47m[defun-nx][0m or [47m[defund-nx][0m is used for a recursive definition, and that form specifies a value for [47m:ruler-extenders[0m that omits [47m[return-last][0m (see [rulers] for relevant background), then the definition generally fails to be admitted. (This is due to the generated [47m[defun][0m's use of [47m[prog2$][0m, which is a macro that abbreviates a call of [47m[return-last][0m, which blocks the termination analysis.) That has been fixed, by ensuring that [47mdefun-nx[0m and [47mdefund-nx[0m arrange that [47mreturn-last[0m is always among the ruler-extenders of the generated [47m[defun][0m form. Thanks to Eric Smith for noticing this issue and for a helpful discussion. Improved handling of [linear] rules: cause an error with a helpful message when a linear rule is no longer created during [47m[include-book][0m or the second pass of an [47m[encapsulate][0m form, and optimize by avoiding certain calculations when the [47m:trigger-terms[0m keyword is supplied. Thanks to Eric Smith for sending an example that illustrates the former issue, essentially as included in a comment in [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-8-4 ...)[0m. The [event] macros [47m[value-triple][0m and [47m[assert-event][0m have been changed to be more flexible, in particular by providing an option to allow the given form to return multiple values. They are also more efficient, as they no longer evaluate using [safe-mode] by default. (Technical note: As a consequence of implementation changes, one will rarely if ever see ``hard'' errors (see [er]) from these utilities.) Thanks to Eric Smith for requesting that a single utility encompass what is provided by the built-in utility [47m[assert-event][0m and the [community-books] utilities [47m[assert!][0m and [47m[assert!-stobj][0m. That single utility is now [47m[assert-event][0m, which in turn uses [47mvalue-triple[0m to check the supplied assertion. The ACL2 [47m[bdd][0m package can now reason using the implicit rewrite rule [47m(equal (consp (cons x y)) t)[0m. Thanks to Warren Hunt for requesting this enhancement. The [event] macro [47m[with-output][0m has been improved with several changes and new features (and correspondingly, so has [47mwith-output![0m). In addition to improvements to its documentation, these include the following; see [47m[with-output][0m for more information. * The keyword argument [47m:summary[0m has been replaced by keyword arguments [47m:summary-on[0m and [47m:summary-off[0m, which control inhibited summary types in analogy to how keyword arguments [47m:on[0m and [47m:off[0m control inhibited output. * The keyword arguments [47m:on[0m and [47m:off[0m may now take value [47mnil[0m. * So-called ``on-off specs'', [47m(:on-off sym1 ... symk)[0m are now allowed for keyword arguments [47m:on[0m and [47m:off[0m, which let you turn on or off all output types except the specified [47msymi[0m. On-off specs are similarly supported for keyword arguments [47m:summary-on[0m and [47m:summary-off[0m. * There is a new keyword for [47m[with-output][0m, [47m:ctx[0m, which supports a sort of global override of [event] contexts. See [with-output] and see [ctx]. * There is better error checking, in particular for duplicate keywords. The value returned by a successful event [47m(encapsulate ... ev_i ... ev_n)[0m is no longer always [47mT[0m. See [encapsulate]. Two event macros produce much less output than before, as follows. Thanks to Alessandro Coglio for requesting these changes and to him and Eric Smith for helpful discussions. * [47m[Defstub][0m is not only quieter but also does a bit more error checking. * [47m[Defun-sk][0m has a new [47m:verbose[0m argument for when output is desired after all. For the [47m:logic[0m and [47m:exec[0m components of a [47m[defabsstobj][0m export, [signature]s no longer need to match. Thanks to Sol Swords for suggesting this improvement. Now, the only such requirements are that the lengths of the input signatures are equal and the lengths of the output signatures are equal. The utility [47m[set-guard-checking][0m now prints messages to [47m(standard-co state)[0m rather than to [47m*standard-co*[0m. (Of course, these are the same by default.) In a proposed [linear] rule, hypotheses that are calls of [47m[bind-free][0m are now accounted for when considering whether each of the [47m:trigger-terms[0m has sufficient free variables (see [linear], in particular condition (b) there, and see [bind-free]). Thanks to Dave Greve for reporting this issue. The example below has the indicated failure in ACL2 Version 8.3 but is now accepted. (defstub f (x) t) (defstub g (x) t) ; The following two events are the same except that the first supplies ; :trigger-terms while the second does not (instead computing trigger terms ; heuristically). These should either both fail or both succeed; now they ; both succeed. ; FAILED, but now SUCCEEDS after the fix since then variables y and z are ; considered to occur (free) in the hypotheses when determining ; whether the hypotheses and trigger term include enough variables to cover ; those in the conclusion. (defaxiom ax1 (implies (bind-free '((z . z))) ; or, (bind-free '((z . z)) (y z)) (< (f x) (g y))) :rule-classes ((:linear :trigger-terms ((f x))))) ; SUCCEEDED even before the fix: the bind-free hypothesis fools ACL2 ; into believing that otherwise-free variables may be bound by the ; bind-free alist. (defaxiom ax2 (implies (bind-free '((z . z))) ; or, (bind-free '((z . z)) (y z)) (< (f x) (g y))) :rule-classes :linear) The report for [47m:[0m[47m[brr][0m when a hypothesis fails to be relieved shows repeated attempts to bind free variables not only as before --- that is, when a hypothesis has free variables --- but also when the hypothesis is a call of [47m[bind-free][0m that returns a list of substitutions. Thanks to Dave Greve for bringing up this issue. It is now an error for a [47m:[0m[47m[linear][0m rule's conclusion to generate a polynomial whose terms are all determined to be non-numeric. Thanks to Eric Smith for suggesting such a check. Here is an example of such a rule that was formerly admitted but useless but now causes an error. (defthm bad-rule (equal (< (foo x) x) nil) :rule-classes :linear) In executable code, calls of [47m[hide][0m in [47m[let][0m-bindings or [47m[lambda][0m bodies are no longer considered to represent [47m[ignore][0m declarations. We thank Alessandro Coglio for raising and discussing this issue. Below is a log, based on that discussion, that was produced using ACL2 before this change. After this change, the second and third calls of [47m:[0m[47m[trans][0m will now result in errors, as noted in comments below. Previously ACL2 treated the [47mhide[0m calls in those two input expressions as though they represented [47mignore[0m declarations, in the sense of translation of the first form shown below. That is still the case when translating for theorems rather than executable code; for details see the ``Essay on Using Hide for Ignored Let-bindings'' in the ACL2 source code. ACL2 !>:trans (let ((x 0)) (declare (ignore x)) 1) ((LAMBDA (X) '1) (HIDE '0)) => * ACL2 !>:trans ((LAMBDA (X) '1) (HIDE '0)) ; error after this change ((LAMBDA (X) '1) (HIDE '0)) => * ACL2 !>(untranslate '((LAMBDA (X) '1) (HIDE '0)) nil (w state)) (LET ((X (HIDE 0))) 1) ACL2 !>:trans (LET ((X (HIDE 0))) 1) ; error after this change ((LAMBDA (X) '1) (HIDE '0)) => * ACL2 !> The [47m[defabsstobj][0m keyword, [47m:CONCRETE[0m, has been changed to [47m:FOUNDATION[0m. Although the use of [47m:CONCRETE[0m is still supported in this release (Version 8.4), it generates a warning that this usage is deprecated and will likely not be supported after this release. Also, documentation and comments now typically speak of ``foundational stobj'' for the underlying stobj of the abstract stobj (which can be supplied explicitly by the [47m:FOUNDATION[0m keyword) rather than ``corresponding concrete stobj''; this reflects the fact that the foundational stobj may itself be an abstract stobj (which is not new for this release). Strengthened error-checking for [47m[stobj-let][0m to insist that if an updater is supplied explicitly in a binding, then it must be a valid updater. This check was formerly made only if the variable bound in that binding is among the producer variables (see [nested-stobjs]). For example, the following now causes an error, but it was formerly accepted in spite of the fact that [47mxyz[0m is not the updater for the accessor, [47mtop1-fld[0m; in fact [47mxyz[0m is not even defined! (defstobj sub1 sub1-fld1) (defstobj top1 (top1-fld :type sub1)) (defun f1 (top1) (declare (xargs :stobjs top1)) (stobj-let ((sub1 (top1-fld top1) xyz)) ; bad updater! (val) (sub1-fld1 sub1) val)) The function symbol [47msymbol<[0m replaces the function symbol [47msymbol-<[0m. More generally, for every built-in function symbol and theorem name containing [47m"SYMBOL-<"[0m, that string in its [47m[symbol-name][0m is replaced by [47m"SYMBOL<"[0m. The function [47mlogical-defun[0m is similarly replaced by [47mget-defun-event[0m. Thanks to Alessandro Coglio for suggesting these changes. Note that the old function names still work in ACL2 Version 8.4, as they are macro-aliases for the corresponding new function names (see [add-macro-alias]); however, they are deprecated and will probably not be supported in later ACL2 versions. (A deprecation warning is printed each time one of those macros is expanded.) The keyword [47m:witness-dcls[0m of [47m[defun-sk][0m is deprecated and will probably be unsupported in future ACL2 releases. Use [47m[declare][0m forms instead; see [47m[defun-sk][0m. New Features It is now possible to assign [47m[badge][0ms to [47m:[0m[47m[program][0m mode functions, which allows them to be used by [47m[apply$][0m, [47m[lambda$][0m and [47m[loop$][0m during top-level evaluation. See [47m[defbadge][0m, which assigns badges but not [warrant]s and which can handle both [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m mode functions. A new option for [47m[certify-book][0m, provided with keyword option [47m:useless-runes[0m or environment variable [47mACL2_USELESS_RUNES[0m, makes it possible to speed up repeated certification of a book, sometimes substantially. See [useless-runes]. Thanks to Sol Swords for reporting a bug (in ACL2 source function [47mread-file-iterate-safe[0m) and supplying a fix, which we have incorporated. Also thanks to Eric Smith for requesting that each tuple in a generated ``useless-runes'' file be printed on a single line starting after a space, thus supporting grep-like tools. Finally, thanks to Alessandro Coglio and Eric Smith for discussions leading to creation of [47m.sys/[0m subdirectories to hold useless-runes files. A new keyword for [47m[defstobj][0m, [47m:non-executable[0m, can be given value [47mt[0m to skip memory allocation for the new [stobj], by avoiding creation of a ``live'' (mutable) stobj. See [defstobj]. Thanks to Warren Hunt for encouraging development of this feature. The rewriter now rewrites the bodies of certain quoted [lambda] objects. However, some restrictions apply. See [rewrite-lambda-object]. In addition some new lemmas and a new metafunction have been added to the book [47mprojects/apply/top[0m, which users are still encouraged to include in sessions dealing with [47m[apply$][0m. The new metafunction is named [47mrelink-fancy-scion[0m and can also cause [47mlambda[0m objects to be transformed. See the discussion of that metafunction in [rewrite-lambda-object]. Added [47m[toggle-inhibit-warning][0m and [47m[toggle-inhibit-warning!][0m to add or delete a warning string from the [47minhibit-warnings-table[0m, rather than setting that entire table as is done by [47m[set-inhibit-warnings][0m. It is now possible to instruct the prover to respect requests to [disable] the [definition] of the primitive, [47m[mv-nth][0m, rather than continuing to expand that definition. See [theories-and-primitives], in particular the note for advanced users at the end of that topic. Thanks to Alessandro Coglio for requesting this feature. A new utility, [47m[memoize-partial][0m, allows memoization for functions that were admitted by adding a formal parameter that decreases on each recursive call (sometimes called a ``limit'' or a ``clock''). Normally that extra parameter can severely impede the utility of memoization; however, the function actually executed does not have that extra parameter. This allows for more memoization hits. Thanks to Mertcan Temel for an inquiry leading to this enhancement, and for helpful discussions. A new rule-class (see [rule-classes]) has been added, named [47m:[0m[47m[rewrite-quoted-constant][0m. Rules in this class can cause the rewriter to replace one quoted constant by an equivalent one under a given [equivalence] relation. See [rewrite-quoted-constant]. The [47m[loop$][0m parser produces more informative error messages on ill-formed [47mloop$[0m statements. A new [47m[memoize][0m keyword, [47m:invoke[0m, supports the replacement of calls of one function by another. In that sense it is similar to [47m[defattach][0m; the difference is that with [47m(memoize f :invoke g)[0m, it is necessary first to prove the equality of [47mf[0m and [47mg[0m; therefore, ACL2 will compute calls of [47mf[0m by calling [47mg[0m even during proofs. In particular, the tool [add-io-pairs] is built on top of this capability; it allows evaluating a function call by fast lookup of a verified input-output pair. Thanks to Eric McCarthy, Alessandro Coglio, and Eric Smith for requesting the latter capability and providing helpful feedback. A new [xargs] keyword for [47m[defun][0m, [47m:type-prescription[0m, can be supplied as a formula in the shape of a [type-prescription] rule. It is checked to be implied by the built-in type-prescription rule computed for the newly-defined function. Thus, it can serve as documentation for the expected type returned by the function; if the implication is not equivalence, a warning is printed. Thanks to Alessandro Coglio and Eric Smith for the suggestion. [Table]s may now supply custom error messages for table [47m:guard[0m failures. This is accomplished by supplying a table [47m:guard[0m that returns two values instead of one. For a return [47m(mv okp msg)[0m, if [47mokp[0m is non-[47mnil[0m then the table guard is considered to be true, that is, it has the same meaning as a non-[47mnil[0m single-value return. Also, [47m(mv nil nil)[0m has the same meaning and effect as a [47mnil[0m single-value return: the table guard fails, and a generic error message is printed about the illegal key/value pair. The new case is a return of [47m(mv nil msg)[0m, where [47mmsg[0m should be a [47m[msgp][0m --- a string or a cons suitable for printing with the [47m[fmt][0m directive, [47m~@[0m. In that case, [47mmsg[0m is printed (using the [47m[fmt][0m directive, [47m~@[0m) instead of a generic error message. This new feature is now used in some built-in tables. See [table]. The [proof-builder] command [47m[type-alist][0m has a new optional argument that supports printing the type-alist in an alist format. Thanks to Mihir Mehta for requesting this feature. A new summary type, [47mREDUNDANT[0m, controls whether a message is printed indicating a redundant event (see [redundant-events]), which however will still always take place if [47mEVENT[0m output is not inhibited (see [set-inhibit-output-lst]). See [summary]. A [47mdefabsstobj[0m event may now specify child [stobj] fields, for use by [47m[stobj-let][0m. See [defabsstobj], and see [community-books] file [47mbooks/system/tests/abstract-stobj-nesting/README[0m for a brief guide to the examples in that directory. Thanks to Sol Swords for requesting this feature and helping to design it, as well as for his helpful discussions, feedback, and test files. The [47m:congruent-to[0m keyword is now supported for [47m[defabsstobj][0m. [47m[Stobj-let][0m now allows aliases in the bindings in some cases where this is safe because updating is not involved. Thanks to Sol Swords for suggesting such a change. Added a function [47m[ctxp][0m to recognize valid contexts, which are used for printing error message (see [ctx]). Thanks to Eric Smith for requesting this addition and to Alessandro Coglio for suggesting that it be disabled, for efficiency. The utilities [47m[brr][0m and [47m[monitor][0m now each take an optional argument that avoids output. A new utility, [47m[monitor!][0m, is a combination of these two with their new optional arguments of [47mt[0m, thus also avoiding output. Thanks to Eric Smith for requesting a version of [47mmonitor[0m that turns on [47mbrr[0m. A new utility, [47m[get-guard-checking][0m, returns the [guard]-checking value most recently installed, either [47mt[0m (when the ACL2 executable was built) or presumably by [47m[set-guard-checking][0m. Thanks to Eric McCarthy for suggesting this utility. The function [47m[aset1-trusted][0m may be used in place of [47m[aset1][0m to avoid [invariant-risk], but is therefore [untouchable]. Added a new utility, [47m[print-object$+][0m, that is like [47m[print-object$][0m but instead of taking [47mSTATE[0m, [47m[print-object$+][0m is a macro that takes keyword arguments to customize the output. See [print-object$+]. Thanks to Eric Smith for requesting such additional print control. Heuristic and Efficiency Improvements We changed the lightweight ``preprocess'' simplifier for ``[simple]'' rules in the prover's [waterfall], in the case that the term is the application of a defined function symbol to constant (quoted) arguments. As before, if the [executable-counterpart] rule for that function symbol is [enable]d, then the call is evaluated in Lisp; and if that evaluation fails (typically because a constrained function is called), then an attempt is made to rewrite the term by applying a [simple] rule. The change is for how failure is handled, that is, in the case that evaluation fails and the term is not rewritten. Formerly, the term was surrounded by a call of [47m[hide][0m. Now, that is only done by the main rewriter, not by the ``preprocess'' simplifier. Thanks to Eric Smith for a communication on the acl2-help list, on a thread started by Mark Greenstreet, that led us towards making this change. Mark's failed proof now succeeds after this change, but here is a simpler example. Formerly, the commented-out [47m:do-not[0m hint was required for the proof of the [47m[thm][0m call below to succeed, because the definition of [47mg[0m is not simple and hence the ``preprocess'' simplifier replaced [47m(g 3)[0m by a term [47m(hide (comment ...) (g 3))[0m before the rewriter could apply the definition of [47mg[0m. (defstub f (x) t) (defun g (x) (cons x (f x))) (thm (equal (car (g 3)) 3) ;; :hints (("Goal" :do-not '(preprocess))) ) The ACL2 rewriter has a ``being-openedp'' heuristic that prevents loops, by saving a stack based on what is currently being rewritten. This can prevent the use of a [definition] or [rewrite] rule. Now the heuristic is turned off when the term's function symbol has a non-recursive definition and simplification has just settled down (see [hints-and-the-waterfall]). To restore the old behavior, i.e., to use the heuristic in all cases --- thus providing backward compatibility when a proof fails --- evaluate the form: [47m(defattach-system being-openedp-limited-for-nonrec constant-nil-function-arity-0)[0m. When a command executed in a logical [world], [47mw[0m, is interrupted, the world is reverted to [47mw[0m. That reversion process could be very slow if the interrupt was taken during the installation of the new world, as indicated by the messages: Flushing current installed world. Reversing the new world. Installing the new world. That process has been sped up significantly. Moreover, the new process avoids a bug reported by Eric Smith, who we thank for sending an example of how the process was interacting badly with [47m[reset-prehistory][0m. Code implementing that interaction was introduced in Version 4.0 to speed up the process; that code has been eliminated, as it is no longer necessary. ACL2's [type-set] reasoning has been slightly strengthened to comprehend Boolean combinations of strong [compound-recognizer] calls on a single variable when building a context (a so-called [type-alist]). (By a ``strong compound-recognizer call'' we mean a unary function that recognizes a union of primitive ACL2 types and has, either explicitly or implicitly, a corresponding [compound-recognizer] rule; examples include [47m[stringp][0m, [47m[integerp][0m, and [47m[true-listp][0m.) In particular, this change can strengthen the result of [forward-chaining]. Thanks to Eric Smith, who raised this issue by providing an example that we include in a comment, inside the form [47m(defxdoc note-8-4 ...)[0m in [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m. [Type-set] reasoning also has been improved for inequalities to take more advantage of the fact that the number 1 constitutes a singleton type. For example, after evaluating [47m(defstub foo (x) t)[0m ACL2 is now able to prove [47m(implies (< 2 x) (equal (foo (bitp x)) (foo nil)))[0m where previously it could not. In fact [47m2[0m can now be replaced by any rational number that is at least 1. The function [47m[compress1][0m has been made more efficient in the following ways. * [47mCompress1[0m is now faster when the [47m:ORDER[0m specified by the given [array]'s [header] is [47m<[0m or [47m>[0m and the alist is properly ordered: header first, then ascending (for [47m:ORDER <[0m) or descending (for [47m:ORDER >[0m) order of indices, with no value in the alist equal to the [47m:DEFAULT[0m specified by the header. In particular, this can cut the time to run [47mcompress1[0m on an alist containing only the header by more than half, which addresses a request made by Eric Smith (whom we thank for bringing this efficiency issue to our attention). * For the change noted just above, Eric also noticed that when the [default] is [47mnil[0m then there was no speedup. This led us to fix an existing bug (technical description: for an array with default [47mnil[0m, the alist was never considered to be in order). * Functions [47m[compress1][0m and [47m[compress2][0m no longer require the new and old dimensions to agree in order that the underlying raw lisp array is reused. Now it suffices for the new dimension (for [47mcompress1[0m; each dimension for [47mcompress2[0m) to be at least as great as the old. (You can still avoid reuse of the raw Lisp array by using [47m[flush-compress][0m.) Thanks to Eric Smith for suggesting this change. We found that [47m[accumulated-persistence][0m was measurably slowing down ACL2 even when it is off. We modified its implementation and measured a time reduction of 3.7% for a proof-intensive book. The modification includes a documented efficiency tweak to [47m[wormhole-eval][0m. The [linear-arithmetic] heuristics have long taken advantage of negated equality hypotheses. These heuristics have been strengthened to take further such advantage. Thanks to Warren Hunt for sending an example proof attempt that failed before this change but now succeeds, and for his encouragement to pursue an improvement to linear arithmetic that can benefit such proof attempts. The removal of [guard-holders] has been augmented to include removal of certain ``trivial'' lambda applications. See [guard-holders], in particular for how to restore the legacy behavior. Thanks to Alessandro Coglio for an example and Eric Smith for a subsequent suggestion that led to this enhancement. Bug Fixes A soundness bug, present since [47m[loop$][0m was introduced, was fixed. The bug was manifested when the keyword [47m:guard[0m was used as the [47mloop$[0m body, as in [47m(loop$ for v in lst collect :guard)[0m. (Note: It's not clear that this bug could be used to prove [47mnil[0m.) A soundness bug was fixed by changing [47m[defabsstobj][0m to avoid using [47m[mbe][0m in the definitions generated for the logic. The problem was that the [47m:logic[0m and [47m:exec[0m forms are not actually equal (they correspond, in the sense of the correspondence predicate), and this can be exploited by using a [47m:[0m[47m[guard-theorem][0m [lemma-instance]. For an example proof of [47mnil[0m in Version 8.3, see a comment about a [47mdefabsstobj[0m bug in the form [47m(defxdoc note-8-4 ...)[0m in file [47mbooks/system/doc/acl2-doc.lisp[0m. A soundness bug was fixed in the functions that print to strings, such as [47mfmt-to-string[0m; see [printing-to-strings]. The bug was a dependence of the result on the ACL2 [state], even though [47mstate[0m is not an argument to these functions. More specifically, the dependence was on the [47m[current-package][0m and the global [47m[evisc-table][0m. For examples see [community-books] [47mbooks/system/tests/fmt-to-string.lisp[0m and [47mbooks/system/tests/fmt-to-string-pkg.lisp[0m. Note: We also strengthened the [guard]s on these functions to require that the keys of the [47mfmt-control-alist[0m alist argument are all appropriate; in particular, the symbol [47mcurrent-package[0m in the [47m"ACL2"[0m package is a suitable key, but for example the keyword [47m:current-package[0m is not. It was possible to prove [47mnil[0m by counterfeiting [47mrecord-expansion[0m calls, which are normally only created by the implementation in support of [47m[make-event][0m calls. This soundness bug has been fixed. (The bug was perhaps impossible to hit in ordinary usage, where [47mrecord-expansion[0m is not used explicitly.) A proof of [47mnil[0m before this fix may be found in a comment in ACL2 source function, [47mcorresponding-encaps[0m. The mechanism for tracking [warrant]s needed during a proof had a bug, which might be a soundness bug if one uses [47m[apply$][0m or [47m[loop$][0m. That bug has been fixed. Fixed a bug that was preventing use of the RDTSC hardware instruction in SBCL on most x86-based platforms, and possibly erroneously attempting to make use of that instruction on some other platforms. Thanks to Keshav Kini for a query that led to this fix. Also restricted RDTSC to x86-based platforms, thanks to a suggestion by Curtis Dunham, to enable Arm builds of ACL2. The use of [47m[apply$][0m on calls of [47m[if][0m no longer cause raw Lisp errors. (The same is true for calls of the subroutine [47mapply$-prim[0m of [47mapply$[0m.) For example, these calls now evaluate without error: [47m(apply$ 'if '(nil nil nil))[0m and [47m(apply$-prim 'if '(nil nil nil))[0m. We made the following fixes to the [47m[accumulated-persistence][0m utility. * Applications of [type-prescription] rules that were erroneously labeled as ``useless'' are now appropriately labeled as ``useful''. * The documentation for [47m[accumulated-persistence][0m now correctly states that the form [47m(accumulated-persistence-oops)[0m undoes the clearing effect of [47m(accumulated-persistence t)[0m, rather than of [47m(accumulated-persistence nil)[0m. * Uses of [definition] rules because of [47m:[0m[47m[expand][0m hints, either explicitly given by the user or generated by ACL2's heuristics for doing induction, were not being recorded by [47m[accumulated-persistence][0m. They are now. Fixed a bug that was causing books to be included as ``uncertified'' after their certification stored checksums (see [book-hash]). Thanks to Keshav Kini for reporting this bug. ACL2 could occasionally simplify subterms of a call of [47m[hide][0m even without any applicable rules or [47m:expand[0m [hints]. (Technical note: the problematic source function was [47mnormalize[0m.) We considered this to be a bug, so it has been fixed. The notion of redundancy for [47m[defstobj][0m [events] was too weak, as evidenced by the following example. Consider the following book, named [47m"bug.lisp"[0m. (in-package "ACL2") (defstobj st fld) (defun foo (st) (declare (xargs :stobjs st)) (fld st)) After certifying this book, a raw Lisp error could occur after evaluating the following forms, because the compiled definition of [47mfoo[0m from including the book referenced a function, [47mfld[0m, which is now a macro. (defstobj st fld :inline t) (include-book "bug") ; The defstobj event in this book is redundant here. (foo st) The bug has been fixed by requiring a redundant [47m[defstobj][0m event to be syntactically identical to the pre-existing corresponding [47m[defstobj][0m event. A raw Lisp error would occur when the value of an [47m:[0m[47m[instructions][0m hint is not a true (null-terminated) list. ACL2 now produces an informative error message in that case. Improved [47m:[0m[47mprint-gv[0m to do its computation in the ACL2 [world] in which the [guard] violation took place. See [print-gv]; in particular, that topic concludes with a discussion of this issue. Thanks to Eric Smith for reporting this issue along with a simple example. The following [47m[defun-sk][0m bugs were fixed. * The [guard] was being ignored (that is, treated as [47mt[0m) when [47m:constrained t[0m was specified in a [47mdefun-sk[0m event. Thanks to Alessandro Coglio for reporting this bug. * [47m[Defun-sk][0m could fail when the formal parameters include [stobj]s or [47mstate[0m. * [47m[Defun-sk][0m provided no direct way to allow formals to be ignored. Now, [47mignorable[0m [declaration]s are permitted. For Lisps that do not compile on the fly (that is, Lisps other than CCL and SBCL), evaluation of [47m:comp t[0m effectively unmemoized functions that were not already compiled. This has been fixed. When a [stobj] hash-table's ``init'' function was called with size 0, an error could occur for host Lisp GCL, complaining that size 0 is not allowed for hash-tables. This has been fixed by using size 1 instead of 0 in this case. Reporting by [break-rewrite] has been fixed for cases when failure is due to a hypothesis with a [backchain-limit] of 0. There were actually two such bugs: one due to improper handling of [linear] rules (which might have occurred even for other backchain-limits besides 0), and one due to the erroneous assumption that backchaining has only just begun at the point of failure. Thanks to Mihir Mehta for sending an example that exhibited both bugs. A discussion of the second bug, including a simple example, may be found in a comment in the ACL2 source function, [47mtilde-@-failure-reason-phrase1-backchain-limit[0m. [47m:OR[0m [hints] that contain a single list (which satisfies [47m[keyword-value-listp][0m) were being mishandled. This has been fixed. Thanks to Dave Greve who sent an example [47m[defthm][0m event specifying [47m:hints (("Goal" :or ((:in-theory (e/d () ()) :nonlinearp t))))[0m, which formerly caused a Lisp error. Fixed a bug in tracking the [cbd] that could cause failures of [47m[include-book][0m in raw-mode. Thanks to Warren Hunt for a query leading to this fix. Fixed a bug that was preventing some deep [patterned-congruence] rules from being applied. This could occur when on the left-hand side, the outermost function symbol is the same as the next function symbol going in towards the variable that differs on the right-hand side. Thanks to Mihir Mehta for reporting this bug and including a replayable example. Fixed several issues with [47m[fmt][0m (and related printing utilities) pertaining to linebreaks. These include the following, many of which are illustrated in a new file, [47msystem/tests/fmt-tests-input.lsp[0m (search there for ``2020''). * A space past the [47m[fmt-soft-right-margin][0m now results in a linebreak even in the case of tilde-space (`[47m~ [0m'). * As before, for punctuation after a tilde-x (`[47m~x[0m') directive, ACL2 avoids printing in column 0 after a linebreak. This desirable behavior now extends to the case that `[47m~x[0m' is inside a tilde-atsign (`[47m~@[0m') directive. For example, after [47m(set-fmt-hard-right-margin 10 state)[0m try either [47m(fmx "~@0." (msg "~x0" '(ab de gh)))[0m or (fmx "~#0~[~x0~/~x0~]." '(ab de gh)). * Spaces are respected after tilde-y (`[47m~y[0m') directives. For example, [47m(cw "~y0 A~%" 3 4)[0m now prints the letter [47mA[0m in column 2 rather than column 0. Thanks to Eric Smith and Alessandro Coglio for suggesting this change. * An extra character is sometimes permitted before deciding that a tilde-x (`[47m~x[0m') directive causes a linebreak. * Tilde directives that cause no printing are often ignored when deciding whether to keep a punctuation mark with a pretty-printed expression. For example, when setting both right margins (soft and hard) to 10, the following no longer prints a comma in column 0: [47m(fmx "~x0~@1, more~%" 'aaaaaaaaaa "")[0m. * Fixed a [47m[double-rewrite][0m warning, which was breaking the word ``is''. Thanks to Mihir Mehta for pointing this out. After setting [state] global [47mtrace-co[0m, for example with [47m(f-put-global 'trace-co (@ standard-co) state)[0m (say, after setting standard-co to an open output channel), printing of the trace level such as ``[47m1>[0m'' and ``[47m<1[0m'' will now go to that channel. Formerly, this could fail after setting [47mtrace-co[0m directly rather than using [47m[open-trace-file][0m. There are improvements to [47m[certify-book][0m and [47m[include-book][0m, which pertain to the loading of compiled files by [47minclude-book[0m before events in the book are processed. That process supports preservation of [hons]es and [fast-alists], and reporting of ``stolen'' alists (see for example [with-stolen-alist]). Relevant tests, with implementation-level comments, may be found in the new [community-books] directory, [47mbooks/system/tests/early-load-of-compiled/[0m. Thanks to Sol Swords for helpful discussions. Improved a utility that builds sets of clauses, which improves the reliability of using a [lemma-instance] of the form [47m(:guard-theorem <name> nil)[0m. Thanks to Eric Smith for reporting this problem with a simple example, and to Dave Greve for following up with a related example; both now work as one would expect. Fixed printing of the ACL2 [state] in error messages, specifically when executing a non-executable function. Fixed a bug that could cause a raw Lisp error when processing a [linear] rule with a [47m[bind-free][0m hypothesis, when that hypothesis does not specify a list of variables (in its second argument). Thanks to Dave Greve for reporting this bug by sending a simple example. (Technical note: the fix was in the definition of source function all-vars-in-hyps.) For [47m[defabsstobj][0m, a suitable error now occurs when the [47m:LOGIC[0m version of an abstract [stobj] export has the foundational stobj as a formal parameter that is declared as a [stobj]. Formerly, a confusing hard error could occur in this case. An unfortunate ``Proof skipped'' could be printed during the [47minclude-book[0m phase of [47m[certify-book][0m for certain uses of [47m[make-event][0m, including calls of [47m[thm][0m. This has been fixed. Fixed an implementation error that was being reported when a [47m[stobj-let][0m form updates two array fields each with at least two indices that are not all natural numbers. For an example that caused this error, see [community-book] [47mbooks/system/tests/nested-stobj-two-updates.lisp[0m. Fixed a bug in resizing [stobj] arrays whose elements are specified to be [47m(signed-byte 30)[0m or a subtype of that type. Thanks to Eric Smith for reporting this bug with a reproducible example. For a [47m[stobj-let][0m call occurring in other than a definition body, the top-level bindings of variables to child stobj accessors was treated as [47m[let*][0m rather than as [47m[let][0m. That was at odds with the documentation, and has been fixed. Fixed a bug that caused an error when attempting to redefine a function for which a [47m:[0m[47m[compound-recognizer][0m rule has been proved. Thanks to Eric McCarthy for reporting this bug (GitHub Issue #1273) with a reproducible example. Raw mode now does a better job of maintaining global [stobj] values. Here is an example that illustrates the fix; also see [set-raw-mode], which has been extended to explain a related but remaining issue. (defstobj st2 (ar :type (array t (8)) :resizable t)) (set-raw-mode-on!) (resize-ar 20 st2) (ar-length st2) ; formerly 8, but now 20 as expected For any [47m[proof-builder][0m command of the form [47m(= term1 term2 atom ...)[0m, the keyword arguments were ignored. This has been fixed, and also the documentation for [47m[ACL2-pc::=][0m has been improved. Consider when a [community-book] is included using an ACL2 executable different from the one that certified the book, with those two executables being located in different directories. The book is now considered to be uncertified in that case. To avoid this issue see [include-book] for a discussion of environment variable [47mACL2_SYSTEM_BOOKS[0m. Changes at the System Level (SBCL only) Filenames are now read as ASCII (specifically, ISO-8859-1) when the host Lisp is SBCL, which formerly was not the case. Thanks to Stephen Westfold for suggesting this change. ACL2 can once again be built on CMU Common Lisp (CMUCL) (though we have only done minimal testing). The problem turned out to be with ACL2, not CMUCL: low-level Lisp code in the ACL2 sources was destructively modifying a quoted constant. (For implementation details, see [47m*fncall-cache*[0m in source file [47mtranslate.lisp[0m.) The bug was discovered when considering modification of the build process to compile ACL2 source files when the host Lisp is SBCL. Thanks to Stas Boukarev for pointing us in the right direction to debug this error. There is now a way to save the untranslated bodies of built-in [47m:[0m[47m[program][0m mode functions. WARNING: This is not officially supported! But it may be useful for tools such as a linter. See [47mGNUmakefile[0m: search there for [47m:acl2-save-unnormalized-bodies[0m, where you will see that a more general capability is actually available for evaluating forms before the build begins. Thanks to Eric Smith for correspondence leading to this enhancement. Starting with ACL2 Version 7.0, the availability of hash consing (see [47m[hons][0m) and the other features described in [hons-and-memoization] have been part of a default ACL2 build; meanwhile, support for ``classic'' ACL2 has essentially been discontinued. These features require a certain Lisp action (implementation note: pushing [47m:hons[0m onto [47m*features*[0m) that had been done during the ACL2 build by the `[47mmake[0m' process (with code in [47mGNUmakefile[0m). Now that action is taken unconditionally in the ACL2 source code. Thanks to Petter Gustad for reporting an error when attempting to build ACL2 without using `[47mmake[0m'; this change should fix that bug. With this change you can no longer attempt to build ``classic'' ACL2(c) without editing ACL2 source file [47minit.lisp[0m; environment variable [47mACL2_HONS[0m no longer has any effect. (On a related technical note: An obscure feature [47m:memoize-hack[0m seems not to be used anywhere, and has been eliminated.) (SBCL only) Handling in ACL2 of the SBCL ``read-cycle-counter'' has been modified to reflect its handling in recent SBCL versions (starting around late 2018 or early 2019). This avoids an ACL2 build error on some platforms. Thanks to John R. Strohm for reporting such a problem (on a Raspberry Pi). (SBCL only) Increased the number of special variables that can be created, which allowed community book [47mbooks/kestrel/apt/schemalg-template-proofs.lisp[0m to certify. Fixed builds that use a relative pathname for the LISP environment variable (for host Lisps CCL, SBCL, Allegro CL, and CMUCL; GCL and LispWorks didn't seem to have this problem). Thanks to Mihir Mehta for bringing this issue to our attention; and thanks to Andrew Walter for reporting a problem with our first solution for SBCL and proposing an alternative, which we adopted. Fixed the process for running ACL2 without building an executable image. Some initialization that was missing from that process is now included. Also, added the missing command, (lp), to the instructions in section ``Running Without Building an Executable Image'' on the ``Obtaining and Installing ACL2'' web page (accessible from the ``Obtaining, Installing, and License'' link on the ACL2 home page). Thanks to Petter Gustad for an inquiry leading to these improvements. When invoking `[47mmake[0m' to build the ACL2 executable, output from the build process is now written to file [47mmake.log[0m. The terminal output is now minimal. If there is already a file [47mmake.log[0m, it is first moved to [47mmake.log.bak[0m. See file [47mGNUmakefile[0m for additional documentation. Thanks to Alessandro Coglio and Eric Smith for suggesting this change, and to David Rager for pointing out associated changes to make for Jenkins builds. The startup banner now has a cleaner look (see [startup-banner]). Thanks to Alessandro Coglio and Eric Smith for key suggestions for improvement. (CCL only) When an attempt to build ACL2 fails, a more informative error message is printed when the error is caused by invoking CCL as a soft link on the Unix PATH rather than as a regular file. Thanks to Mertcan Temel for feedback leading to this change. A script [47mbin/acl2[0m has been added below the main ACL2 directory. It may be used in place of [47msaved_acl2[0m, invoked from any directory. If the [47mbin[0m subdirectory is on one's Unix [47mPATH[0m then of course [47macl2[0m will invoke this script (unless a different [47macl2[0m is in a directory that is earlier on that path). Thanks to Alessandro Coglio for suggesting that an [47macl2[0m script be made available with ACL2, and to him and Eric Smith for subsequent discussions on that topic. When an error occurs while loading an [ACL2-customization] file, ACL2 quits with exit code 1. Thanks to Eric Smith for suggesting the quit and to Eric McCarthy for suggesting exit code 1 in that case. ACL2 now does a more thorough job of doing proofs when ``[47mmake proofs[0m'' is executed. In particular, proofs were formerly skipped but are now performed for [47m[defun][0m forms containing the explicit [47m[xargs][0m [declaration], [47m:mode :logic[0m, and for [47m[defthm][0m events evaluated with [default-defun-mode] [47m:logic[0m outside the so-called ``pass 2 files''. EMACS Support The [ACL2-doc] search commands (`[47ms[0m' and `[47mS[0m') were seen to use all available memory on a linux system, during the process of initializing the [47macl2-doc-search[0m buffer that is used for doing the searching. That problem has been solved: that buffer is now loaded from a file that is built by the manual-building process and is downloaded by the acl2-doc `[47mD[0m' command. Highlighting in lisp-mode (inside Emacs) has been improved, both by recognizing more keywords and by highlighting of some new arguments, in particular the first argument of [47mdefthm[0m. Thanks to Vivek Ramanathan, both for pointing out the [47mdefthm[0m issue and for suggesting code that was incorporated into the changes. The [ACL2-doc] browser now queries when first loading an ACL2+books manual if you have a newer web-based version. A ``yes'' response will use the (out-of-date) manual, while a ``no'' response will generally produce a new query asking if you want to download the manual from the web. This change was made in support of building the manual more quickly, as the acl2-doc manual is no longer built by default. See [ACL2-doc] for how to do that build and other details. Thanks to Alessandro Coglio, Eric Smith, and Sol Swords for discussions about speeding up the build of the manual. Fixed certain hangs in the [ACL2-doc] browser. For example, when standing on whitespace near the left margin of topic [*ACL2-exports*], the '[47mg[0m' command could formerly hang. Experimental Versions ACL2(p) now runs much more reliably on host Lisp SBCL (by taking advantage of a locking mechanism provided by SBCL). Thanks to David Rager for providing this improvement. In ACL2(p), [47m[set-waterfall-parallelism][0m no longer causes an error when there are [47m[override-hints][0m if the argument is the existing value of the [state] global, [47m'waterfall-parallelism[0m, or upon a transition of [waterfall-parallelism] to [47mnil[0m. Thanks to David Rager for raising this issue (see GitHub Issue #1171) and discussing its resolution.") (note-8-5 (release-notes) "ACL2 Version 8.5 (July, 2022) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.4 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-5-books] for a summary of changes made to the ACL2 Community Books since ACL2 8.4, including the build system. Also note that with each release, it is typical that the value of constant [47m[*ACL2-exports*][0m has been extended, and that some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Changes to Existing Features Weakened hypotheses from built-in theorems (thus strengthening them) [47msymbol-equality[0m, [47mtrue-listp-first-n-ac-type-prescription[0m, [47mordered-symbol-alistp-getprops[0m, [47madd-pair-preserves-all-boundp[0m, and [47msymbol<-asymmetric[0m. Eliminated built-in theorem [47mmain-timer-type-prescription[0m entirely (that rule was already deduced by ACL2 at definition time). Simplified guards slightly for built-in functions [47mserialize-write-fn[0m and [47mserialize-read-fn[0m. Thanks to Eric Smith for correspondence, based on his linter, leading to these improvements. The utility [47m[without-evisc][0m formerly always (or nearly always) returned the [error-triple] [47m(mv nil :invisible state)[0m after printing the result. Now it generally returns [47m(mv t nil state)[0m when evaluation of the given form causes an error. See [without-evisc]. Thanks to Karthik Nukala and Eric Smith for reporting the former (undesirable) behavior. One would get an error when including an uncertified book when a [47m:type-prescription[0m specified in an [47m[xargs][0m [declaration] failed a validity check, even when no such failure occurs when that book is certified. (That could happen because type-prescription information from locally included books is saved in the book's [certificate] file and is used when checking such [47m:type-prescription[0m declarations.) This situation now generates a warning rather than an error. Thanks to Karthik Nukala and Eric Smith for sending an example that pointed out this problem. Output from [47m:[0m[47m[oops][0m may now be inhibited as [47mOBSERVATION[0m output, by using [47m[set-inhibit-output-lst][0m or [47m[with-output][0m. [Raw-mode] has been fixed so that reasonable results are printed when multiple values are returned by a function defined in raw-mode or raw Lisp (rather than in the logic). The following examples illustrate the problem and the fixed behavior. The utilities [47madd-raw-arity[0m and [47mremove-raw-arity[0m are no longer necessary (and they had no effect anyhow, at least in recent ACL2 versions), so they have been removed. (defstobj st fld) (set-raw-mode-on!) (defun f1 (st) st) (f1 st) ; printed a vector; now prints <st> (defun f2 (state) state) (f2 state) ; printed ACL2_INVISIBLE::|The Live State Itself|; ; now prints <state> (defun bar (x st state) (mv x st state)) (bar 3 st state) ; printed 3; now prints (3 <st> <state>) The keyword [47m:concrete[0m for [47m[defabsstobj][0m and the keyword [47m:witness-dcls[0m for [47m[defun-sk][0m are no longer supported, as they were deprecated in ACL2 Version 8.4 in favor of [47m:foundation[0m and [47m[declare][0m forms, respectively. Also: the following symbols, deprecated in ACL2 Version 8.4, are no longer names of [events]. logical-defun merge-sort-symbol-< merge-symbol-< strict-merge-sort-symbol-< strict-merge-sort-symbol-<-cdrs strict-merge-symbol-< strict-symbol-<-sortedp symbol-< The string [47m"Proof succeeded"[0m or [47m"Proof skipped"[0m was formerly printed when [47mSUMMARY[0m output is not inhibited (see [set-inhibit-output-lst]), but now that printing takes place instead when [47mPROVE[0m output is not inhibited. Thanks to Pete Manolios for pointing out a printing issue that is resolved with this change. Some error messages were improved for the [proof-builder], primarily when refusing a command to dive into an [47mOR[0m expression. Thanks to Warren Hunt for bringing this issue to our attention. There was a restriction on certain events, notably [47m[defconst][0m and [47m[defmacro][0m events, to ensure that they are not ancestrally dependent on [47m[loop$][0m or [47m[lambda$][0m expressions. That restriction has been removed in the case that the body of the event is a quoted constant. A [47m[defwarrant][0m event may complete more quickly because a generated hint now [disable]s the function. Functions that take or return [stobj]s may now have [badge]s and [warrant]s. One cannot (yet) take advantage of these in general because one cannot put a [stobj] into a list, as required for the second argument of [47m[apply$][0m. However, this change supports the use of stobjs in [47m[loop$][0m expressions that use the new keyword, [47mDO[0m. The function [47mthe-check[0m, which is generated by calls of [47m[the][0m, is now a [guard-holder]. Printing of checkpoints now takes place any time [47mSUMMARY[0m output is enabled (see [set-inhibit-output-lst]. Formerly, both [47mSUMMARY[0m and [47mERROR[0m output needed to be enabled. Related tweaks, probably not user-visible, were made in support of utilities for obtaining and displaying checkpoints programmatically: see [checkpoint-list] (which mentions related utilities as well), and we thank to Eric Smith for requesting such utilities. The guard formula utilities (see [guard-formula-utilities]) continue to perform simplification as before, except that way to specify the level of simplification has changed. Thanks to Eric Smith for a query and subsequent discussion that led to these changes. See [guard-simplification] for a detailed explanation; below is a summary. (The reason for these changes is that the value [47mT[0m formerly meant different things in the two cases below --- all simplification and limited simplification, respectively --- and the value [47mNIL[0m also meant different things in those two cases --- limited simplification and no simplification, respectively.) * For [47m[xargs][0m keyword [47m:guard-simplify[0m and related utilities [47m[guard-obligation][0m and [47m[verify-guards-formula][0m: The default value for simplification remains [47mT[0m. However, the value is now [47m:LIMITED[0m for specifying reduced simplification; formerly it was [47mNIL[0m, which is now illegal. * For [47m:[0m[47m[guard-theorem][0m [lemma-instance]s and the related utility [47m[gthm][0m (also the low-level utility, [47mguard-theorem[0m): The default simplification is unchanged but now corresponds to a new default value, [47m:LIMITED[0m; formerly it was [47mT[0m, which is now illegal. The value [47mNIL[0m continues to be appropriate for avoiding simplification. Improved [47m[untranslate][0m so that when untranslating a translated [term], an attempt is made to call [47m[mv][0m where appropriate. Thanks to Alessandro Coglio and Eric Smith for requesting this enhancement. The improvement also restores type declarations under [47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m (see [declare] and [type-spec]); and it also restores [47m[ignore][0m declarations in [47m[let][0m and [47m[let*][0m forms, where previously that was only the case for [47m[mv-let][0m forms. In addition, a new utility, [47m[maybe-convert-to-mv][0m, may be called explicitly to convert an untranslated term to one that calls [47mmv[0m in leaves reached via transversal of the true and false branches of its top-level [47mIF[0m tree, where the traversal appropriately passes through [47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m forms, as well as calls of [47m[prog2$][0m, [47m[mbe][0m, [47m[mbt][0m, [47m[ec-call][0m, [47m[time$][0m, and a few other macros related to [47m[return-last][0m as well as [47mreturn-last[0m itself. See examples under a comment about ``preserving executability'' in the [community-book], [47mbooks/system/tests/untranslate.lisp[0m. (Note: The changes also include a bug fix that avoids generating an [47m[mv-let][0m expression when there are fewer than two bound variables.) The second argument of [47m[certify-book][0m is no longer allowed to be the symbol, [47mT[0m, or any symbols whose [47m[symbol-name][0m is [47m"T"[0m. (This option seems to have been essentially unused but it complicated the source code.) When an [event] fails while [useless-runes] are being read, the failure message now makes note of that fact. See [useless-runes-failures]. Thanks to Mertcan Temel for pointing out that such failures may present a confusing problem for (especially) new users. Failed attempts to [47m[memoize][0m or [47m[profile][0m now generally result in less noisy error output. Also, a more useful error message is printed when attempting to [47m[memoize][0m or [47m[profile][0m a function that is introduced either by [47m[defabsstobj][0m or by [47m[defstobj][0m with keyword argument [47m:inline t[0m, and hence is a macro in raw Lisp; thanks to Shilpi Goel for suggesting this improvement. When the [break-rewrite] utility reports rewriting a hypothesis to [47mnil[0m, it adds a note pointing to a new :doc topic, [tail-biting], that explains a way that this can happen. New Features A new [47m[loop$][0m keyword, [47mDO[0m, supports an imperative style of programming in loops. In particular, [47mDO[0m [47mloop$[0m expressions may use [47msetq[0m and [47mmv-setq[0m for assigning to one or several variables (respectively), they may reference and return [stobj]s, and they may return multiple values. See [loop$]. One can now suppress output from [47m[cw][0m, [47m[cw!][0m, [47m[fmt-to-comment-window][0m, and [47m[fmt-to-comment-window!][0m, and from utilities that use these such as [47m[time$][0m, by inhibiting a new output type, [47mCOMMENT[0m. (Thus, that symbol has been added to the value of [47m*valid-output-names*[0m.) See [set-inhibit-output-lst] and [with-output]. Thanks to Eric McCarthy for a conversation via GitHub Issue #1293 that led to this enhancement. Moreover, new macros [47m[cw+][0m and [47m[cw!+][0m and new functions [47m[fmt-to-comment-window+][0m and [47m[fmt-to-comment-window!+][0m never suppress output; the [47m"+"[0m suffix is intended to indicate that feature. Thus, these new utilities behave like the previous utilities without the [47m"+"[0m suffix. Thanks to Eric Smith, Karthik Nukala, and Alessandro Coglio for observing inappropriate suppression of output from the utility [47m[er-soft+][0m and the connection of this problem to the addition of the [47mCOMMENT[0m output type; it was resolved by using [47mfmt-to-comment-window+[0m in place of [47mfmt-to-comment-window[0m in the implementation of a utility underlying [47mer-soft+[0m (see [community-book] [47mbooks/tools/er-soft-logic.lisp[0m). You can now arrange that an interrupt will kill a proof immediately by evaluating [47m(assign abort-soft nil)[0m, and you can restore the default behavior --- where an interrupt instructs the proof to quit cleanly at an appropriate opportunity --- by evaluating [47m(assign abort-soft t)[0m. Note that this can interfere with [47m:[0m[47m[redo-flat][0m; see [abort-soft]. Thanks to Eric Smith for reporting an inability to abort a series of proof attempts using the [47m[prove$][0m utility, which led to this enhancement. A [stobj] may now have a field of type [47mSTOBJ-TABLE[0m, which associates arbitrary stobj names with corresponding stobjs. As of this writing, that feature should be considered experimental; see [stobj-table]. Thanks to Rob Sumners for suggesting the idea and to him and Sol Swords for useful design discussions. The utility [47m[wet][0m has a new keyword option, [47m:fullp[0m, that allows it to work even when there is a raw Lisp error. Thanks to Eric Smith for requesting that [47mwet[0m be able to work in such cases. Rewriting of [lambda] objects (see [rewrite-lambda-object]) may now be [disable]d, by disabling the [executable-counterpart] [rune] for (trivial function), [47mrewrite-lambda-modep[0m --- for example, with a hint [47m:in-theory (disable (:e rewrite-lambda-modep))[0m. Also improved a couple of warnings and a bit of documentation pertaining to such rewriting. The undocumented [47mlast-ld-result[0m feature has been replaced by a new documented feature, a [ld-history] that records command input/output history. Thanks to Eric Smith for requesting this feature. The [47m[ld][0m utility accepts a new keyword argument, [47m:useless-runes[0m, which functions much the same as does the [47m:useless-runes[0m keyword argument of [47m[certify-book][0m. See [useless-runes]. Thanks to Eric Smith for requesting this feature (which may have been requested previously as well). A new [event], [47m[set-inhibit-er][0m, allows the user to turn off error output of various types. The related utility [47m[toggle-inhibit-er][0m can turn on or off a single type of error output. Non-[local] versions of these utilities are [47m[set-inhibit-er!][0m and [47m[toggle-inhibit-er!][0m. Many error messages cannot yet be controlled this way, but this may be remedied somewhat with community feedback. Thanks to Eric Smith for a request to inhibit step-limit error output, which led to this enhancement. The functions [47m[l<][0m, [47mlexp[0m, and [47md<[0m, originally defined in [community-book] [47mbooks/ordinals/lexicographic-book.lisp[0m, are now built into ACL2. However, it is still useful to include an ordinals book, for example [community-book] [47mbooks/ordinals/ordinals[0m, if you want to reason about such functions. A [stobj] field of [47mHASH-TABLE[0m type may now specify an element type; for example, [47m(hash-table eql nil integer)[0m specifies a test of [47meql[0m, no size restriction, and the element type, [47minteger[0m, indicating that only integers are stored in the hash table. The [47m:initially[0m keyword of such a field is no longer ignored, but instead provides the value returned when looking up a key that is not bound in the hash table. Moreover, the element type may be a stobj, indicating that the values in the hash table are all instances of that child stobj; see [nested-stobjs]. In that case, the [47m:initially[0m keyword would be meaningless because one always gets a fresh instance of the child stobj when looking up an unbound key; hence [47m:initially[0m is illegal for any hash-table field with a stobj element type. Thanks to Rob Sumners for requesting this enhancement and for helpful discussions about its design. It is now possible to certify a book in a logical [world] that contains [local] [events]. Thus, a book's [certificate] file may include local events among its [portcullis] commands, which will be skipped when including the book. A key application of this new capability is to save an ACL2 executable (using [47m[save-exec][0m) after [local]ly including set [47mB[0m of books at the top level, and then --- in fresh ACL2 sessions started by running that executable --- certify other books that may include some books of [47mB[0m. Those inclusions would then be [redundant] during certification of a book, but not later when the book is included. If [47mB[0m is a large set of large books, then this process can be much more efficient than doing certifications from a basic ACL2 executable, which would involve running [47m[include-book][0m on all required books from [47mB[0m. Of course, one could previously have saved such an executable and certified books on top of it, but then all of [47mB[0m would be included whenever including those books, which could be slow and also could result in many more rules than desired. Thanks to Sol Swords and others at Intel Corp. for requesting this enhancement and engaging in initial discussions. The new macro [47m[trust-mfc][0m supports testing [extended-metafunctions] outside the prover. Thanks to Sol Swords for requesting such a utility. A new macro, [47m[with-global-stobj][0m, allows reading and writing of a [stobj] in the body of a function without having to pass it as a formal parameter, by accessing the stobj from the ACL2 [state]. See [with-global-stobj]. Thanks to Rob Sumners and Sol Swords for requesting this feature (originally, to support a global [stobj-table]) and for helpful discussions about its design. The [meta-extract] feature has been extended to allow [linear] lemmas to be extracted from the [world] and trusted by clause processors and metafunctions. In particular, a new sort of value for the [47mobj[0m argument is supported for [47mmeta-extract-global-fact[0m (and [47mmeta-extract-global-fact+[0m), which results in a term representing a linear lemma extracted from a function symbol's [47mlinear-lemmas[0m property. See [meta-extract], in particular the discussion of [47m:linear-lemma[0m. Thanks to Sol Swords for providing this enhancement. A new utility, [47m[disable-ubt][0m, is similar to [47m(reset-prehistory t)[0m except that it does not change command numbering. Added a built-in [47m:[0m[47m[forward-chaining][0m rule, [47msymbol-listp-forward-to-eqlable-listp[0m, which replaces the rule [47msymbol-listp-forward-to-true-listp[0m. Note that the old rule is subsumed,together with other rules, by the new one. Thanks to Warren Hunt for observing that not built into ACL2 as a [47m:forward-chaining[0m rule. Heuristic and Efficiency Improvements Improved the efficiency of some computations involving calls of [47m[defattach][0m with option [47m:aokp t[0m, in particular, of [47m[include-book][0m events for books including such calls. Thanks to Mertcan Temel for reporting this efficiency issue and sending an [47minclude-book[0m event, whose execution time was reduced from 24 seconds to 10 seconds by this change. Evaluation of some large forms caused stack overflows (from ACL2 source function [47mbad-lisp-consp[0m). This is probably much less likely now. Thanks to Eric Smith for reporting this issue to the acl2-help list with a helpful example, which formerly caused a stack overflow for ACL2 built on SBCL but no longer does so. The function [47m[princ$][0m now prints characters more rapidly. In some cases, [47m[include-book][0m calls may run a bit faster thanks to a couple of small changes. The primary change is for heuristic [loop-stopper] generation when the conclusion of a [rewrite] rule contains a [lambda] expression. Formerly all such expressions were expanded away. Now, they are expanded away in the left-hand side, and both the unexpanded and expanded versions of the left-hand side are compared to the unexpanded right-hand side (see the final Remark in the [loop-stopper] documentation). We have seen a 7% reduction of time for the event, [47m(include-book "projects/x86isa/top" :dir :system)[0m. Book certification has (in the past, and still) an optimization that avoids needless rolling back of the [world] during the [47m[include-book][0m phase; see [certify-book], in particular the discussion of ``roll back''. Any [local] event within an [47m[encapsulate][0m form was reason to roll back the world to before that [47mencapsulate[0m event. That is no longer the case unless the [47m[encapsulate][0m form introduces packages in the first pass through that [47mencapsulate[0m form that are hidden or missing after the second pass through it, presumably because of a [local] [47minclude-book[0m event in that [47mencapsulate[0m form. The function [47m[len][0m is significantly more efficient than before. (Also, its raw Lisp implementation is simpler, though as before it causes an error for extremely (impossibly?) long lists (in Lisp parlance, whose length is not a fixnum).) Thanks to Stephen Westfold for encouraging this change and suggesting a suitable [47mdeclaim[0m form, and thanks to Eric Smith for providing helpful tests. Bug Fixes A soundness bug in [47m[defstobj][0m has been fixed that allowed a field to contain the [type-spec] [47m(SATISFIES pred)[0m when [47mpred[0m has a [guard] other than [47mt[0m, which generated an unsound guard theorem. Thanks to Eric Smith for sending the following example. (defstobj s (field :type (satisfies evenp) :initially 4)) (defthm bad nil :rule-classes nil :hints (("Goal" :use (:instance (:guard-theorem fieldp) (x t))))) A soundness bug was due to incompleteness of the prohibition against [local] [portcullis] [command]s. For an example, see a comment in the form [47m(defxdoc note-8-5 ...)[0m, [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m. This has been fixed by allowing local events among the portcullis commands (and treating them properly; see relevant discussion, including how [47m[save-exec][0m may be helpful, in the ``New Features'' section above). The use of [47m[set-guard-checking][0m before calling [47m[certify-book][0m was making it possible for a subsequent [47m[include-book][0m to fail for that book. For example, in a fresh ACL2 session one could evaluate the [command] [47m(set-guard-checking :none)[0m followed by [47m(table foo 0 (car 3))[0m, and then certify a book; but including that book would then fail with a [guard] violation, because the [47mset-guard-checking[0m call was not saved in the [certificate] file, hence was not evaluated when attempting to include the book. This has been fixed by treating that situation much as [local] [portcullis] commands are now treated (see discussion about that in the ``New Features'' section above). The situation is explained now in the final Remark in the documentation for [local-incompatibility]. Fixed an error that could occur when the [break-rewrite] utility is displaying failure information for an attempt to apply a [linear] rule containing [free-variables]. Thanks to Karthik Nukala and Eric Smith for sending a bug report with a replayable example. Strengthened syntax checking for accessor expressions in [47m[stobj-let][0m bindings. See a comment about this in [47m(defxdoc note-8-5 ...)[0m. The writing of [useless-runes] files was sensitive to the global [evisc-table], which could cause failures when reading those files. This has been fixed. An error could occur when encountering a [redundant] [47m[defwarrant][0m event while including a book. This has been fixed, by arranging that a [47mdefwarrant[0m event always expands to the same [47m[encapsulate][0m form. An assertion error was fixed, occurring with a call of [47m[certify-book][0m when the value of environment variable [47m"ACL2_USELESS_RUNES"[0m was (erroneously) [47m"0"[0m. When the [hints] specified for a goal include [47m:do-not-induct NAME[0m for some symbol [47mNAME[0m other than [47mt[0m, [47m:otf[0m, [47m:otf-flg-override[0m, or [47mnil[0m, then that goal is to be skipped, giving it a ``bye'' as with a [47m:by[0m hint. This would fail however when the [induction-depth-limit] is reached: that is, the proof would fail immediately rather than continuing so that the skipped goal is printed upon failure at the end. The following example now has the desired behavior; thanks to Alessandro Coglio for raising this issue by sending a [proof-builder] example, where the [47m:induct[0m command failed for (as it turns out) the same reason. (set-induction-depth-limit 1) (thm (equal (append (append x y) z) (append x y z)) :hints (("Goal" :induct t :do-not-induct foo :do-not *do-not-processes*))) Fixed a bug in processing macro arguments with more than one occurrence of the symbol, [47m:allow-other-keys[0m. Thanks to Eric Smith for pointing out this bug and providing a fix. Here is an example that was failing but is now handled without error (notice that [47m:allow-other-keys[0m is in a value position, not a keyword position, so the duplication is legal). ACL2 !>(defmacro foo (x &key y) `(list ,x ,y)) Summary Form: ( DEFMACRO FOO ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !>(foo 3 :y 4 :z 5 :allow-other-keys t :w :allow-other-keys) ACL2 Error in macro expansion: ACL2 prohibits multiple :allow-other- keys because implementations differ significantly concerning which value to take. ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (foo 3 :y 4 :z 5 :allow-other-keys t :w :allow-other-keys) (3 4) ? Pretty-printed output could be misaligned when an output string specified by the [evisc-table] contains a newline. Such output is now printed a bit differently, with reasonable alignment. Printing of results has been improved in [raw-mode] in cases of [multiple-value] return, so that [stobj] names are used even when at least one returned value is not an ACL2 object. The [trace] level is no longer reset when entering [break-rewrite] or any other [wormhole]. Thanks to Khairul Azhar Kasmiran for raising this issue and pointing to relevant source code ({GitHub Issue #1395 | https://github.com/acl2/acl2/issues/1395}). When the [47m:[0m[47m[pr!][0m command prints [47m:[0m[47m[rewrite][0m rules about the [47m[pkg-imports][0m of one or more [packages], it now prints such rules only for relevant packages, not ones introduced earlier than specified by the argument of [47m:pr![0m (as was done previously). Thanks to Eric Smith for bringing this bug to our attention. A bug in [47m[defattach][0m has been fixed, which was causing the keywords within an argument [47m(fi gi :kwdi1 vali1 ...)[0m to be associated with the wrong such argument. When printing the name of a symbol or package that consists entirely of '[47m.[0m' (dot) characters, the name is escaped with vertical bars, for example, [47m|..|[0m. Note that the CL HyperSpec, Section 2.3.4 Symbols as Tokens says: ``Any token that is not a potential number, does not contain a package marker, and does not consist entirely of dots will always be interpreted as a symbol.'' Thanks to Eric McCarthy and Eric Smith for pointing out that there can be errors when reading such a name when it is not escaped. It was possible to get a violation of fast alist discipline (see [slow-alist-warning] when certifying a book that uses [47m[must-fail][0m. This has been fixed. It had been possible to undo commands (for example, using [47m:[0m[47m[ubt][0m when inside the [break-rewrite] interactive loop. This destroyed the utility of that loop by erasing keyword aliases (see [ld-keyword-aliases]). Thanks to Warren Hunt for reporting this problem. The solution uses the new utility mentioned above, [47m[disable-ubt][0m, which may be useful for other [47m[wormhole][0m invocations that take advantage of the [47m[ld-keyword-aliases][0m [table]. Changes at the System Level The [hons-enabled] features of ACL2 ([47m[hons][0m, [memoization], and [fast-alists]) have been included in ACL2 builds by default since Version 7.0 (January, 2015) and in all ACL2 builds since Version 7.2 (January, 2016). Now, essentially all support for building ACL2 without these features has been removed. The function [47m(hons-enabledp state)[0m and the feature [47m:hons[0m both remain, but are always true and are deprecated, scheduled for removal very soon after the next release. The feature [47m:acl2-mv-as-values[0m was always true when feature [47m:hons[0m was present, hence was always true; so it has been removed (and [47m#-acl2-mv-as-values[0m code has been eliminated). For ACL2 builds when the host Lisp is SBCL, the Lisp optimization level is now 1 for [47mSPACE[0m, which apparently can result in more inlining than the former level of 0, and which has been seen to speed up an application while reducing memory bytes allocated. The default optimization level for [47mSPACE[0m can be set to 1 for any Lisp at build time by running [47mmake[0m with argument [47mACL2_SPACE=1[0m, and the level can be set similarly to any legal value, for example by using [47mACL2_SPACE=3[0m for level 3. We can easily change the default for other Lisps as well, and might do so when there is evidence that this would be useful. The function [47mbind-macro-args[0m, and several of its subfunctions, are now in [47m:[0m[47m[logic][0m mode with verified [guard]s. Thanks to Eric Smith for verifying guards as per [verify-guards-for-system-functions]. ACL2 will now generally signal an error if a filename contains consecutive directory separators, i.e., [47m"//"[0m (in non-Windows systems). (SBCL only) A build-time parameter was changed so that some non-x86 64-bit platforms, notably Arm, are built with [47m--dynamic-space-size 32000[0m, as for x86-64 platforms, instead of [47m2000[0m. Thanks to Stephen Westfold for pointing out this oversight. A new documentation topic, [guarantees-of-the-top-level-loop], explains the logical meaning of evaluation in the ACL2 read-eval-print loop, including discussion of attachments (see [defattach]), [badge]s, [warrant]s. The implementation of backquote has been optimized to use quoted expressions for constant subterms (other than [lambda] objects) rather than consing new structure. This can give a significant reduction in code size. Thanks to Stephen Westfold for providing his implementation. When an error is encountered while reading an expression, the remaining input is cleared. Thanks to Eric McCarthy for pointing out that this wasn't the case, giving the example, [47m(LET ((. 3)) (+ . 4))[0m, as one that was giving many errors. (CCL only) Disabled raw lisp compiler macro for [47mmemq[0m. For example, the following definition no longer causes a raw Lisp error when submitted to ACL2: [47m(defun foo (x) (member-eq x 'a))[0m. Thanks to Shannon Spires for the suggestion. EMACS Support It is now possible to have more than one [ACL2-doc] buffer. A new buffer is created by using [47mShift-<Return>[0m to follow a link. Commands that are naturally specific to a given buffer (such as searching and going back) are buffer-local. Thanks to Mayank Manjrekar for the idea and for supplying an implementation (including documentation), which has been incorporated into the [ACL2-doc] source file, [47macl2-doc.el[0m (loaded from a suitable directory; see [emacs]). A bug has been fixed in [ACL2-doc] that would cause an error when attempting to bring up the acl2-only manual. The key binding Control-TAB has been removed for the [ACL2-doc] browser, to avoid conflict with other uses of that key. Thanks to Alessandro Coglio for the idea. New [47m[ACL2-doc][0m command [47mG[0m is similar to [47mg[0m, prompting for a topic name, but puts that topic into a new buffer. Thanks to Warren Hunt for requesting this feature. When [47m[ACL2-doc][0m fails in an attempt to download the manual, a more helpful error message says how to attempt the download outside Emacs, and the minibuffer points to an Emacs variable holding that message, [47macl2-doc-download-error[0m (which is also described in the [ACL2-doc] documentation topic). Thanks to Warren Hunt for discussion leading to this enhancement. Files from the [47memacs/[0m directory in the ACL2 distribution have been copied to directory [47mbooks/emacs/[0m. The original [47memacs/[0m directory will continue to be maintained for Emacs 24 (though those who have used it comfortably with more recent versions may wish to continue to load files from the [47memacs/[0m directory). The [47mbooks/emacs/[0m directory is intended for use with recent versions of ACL2, and the ACL2 community is welcome to modify it. Thanks to Warren Hunt for noting that users of recent Emacs versions could experience problems using files maintained for Emacs 24. Experimental Versions An error could formerly occur when using the precomputed [useless-runes] files in ACL2(r). The [useless-runes] feature has now been turned off for ACL2(r). Thanks to Eric McCarthy for this change. Warnings about ``fast alist discipline violated'' (see [slow-alist-warning]) could appear in ACL2(p) when [useless-runes] were being read, say using [47m[certify-book][0m option [47m:useless-runes :read[0m. These have been eliminated. Note that they didn't show up during regressions in Version 8.4 because the use of ``[47mmake[0m'' was set up to avoid using useless-runes with ACL2(p).") (note-8-6 (release-notes) "ACL2 Version 8.6 (October, 2024) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.5 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also [note-8-6-books] for a summary of changes made to the ACL2 Community Books since ACL2 8.5, including the build system. [3mDARPA Note.[0m The following statement applies to items below that are marked with ``See DARPA Note above'': Release was approved by DARPA with ``DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.'' Changes to Existing Features Some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions. Among the most significant such built-in functions are the following. * [47mOne-way-unify[0m (see [47mbooks/system/brr-near-missp.lisp[0m) * [47m[Genvar][0m (see [47mbooks/system/brr-near-missp.lisp[0m) * [47m[Fmt][0m, [47m[error1][0m (which supports macros [47m(er soft ...)[0m and [47m[er-soft][0m), and related printing utilities --- and some code was modified to support their conversion to [47m:[0m[47m[logic][0m mode [See DARPA Note above.] Note that because of the [47m[error1][0m change noted above, [47m(er soft ...)[0m can now be used in [47m:logic[0m mode code. The connected book directory (that is, the [cbd]) now elaborates relative [pathname]s to absolute pathnames not only for book operations, but for all file operations. For example, [47m(open-input-channel "foo" :character state)[0m now interprets filename [47m"foo"[0m relative to the cbd, where formerly it was generally interpreted relative to the directory in which ACL2 was invoked. (Technical note: ACL2 accomplishes the new behavior by arranging that [47m[set-cbd][0m modifies not only the cbd but also the Lisp global, [47m*default-pathname-defaults*[0m.) Thanks to Alessandro Coglio, Eric McCarthy, and Eric Smith for suggesting consideration of such a change and for helpful discussions. The function [47mhons-enabledp[0m is no longer defined, and [47m:hons[0m has been removed from the Lisp global, [47m*features*[0m (so, readtime conditionals [47m#+hons[0m and [47m#-hons[0m should be avoided, especially since [47m#+hons[0m is always false even though the system is [hons-enabled]). These were both deprecated in the preceding release (ACL2 Version 8.5). Note that the [hons-enabled] features of ACL2 have been included in all builds by default since Version 7.0 (January, 2015) and in all builds since Version 7.2 (January, 2016). The [proof-builder] now takes into account various aspects of rewriting specified by the logical [world] that it formerly ignored (pertaining to [match-free], [case-split-limitations], [untouchable] functions, non-linear arithmetic (see [set-non-linearp]), the [backchain-limit] for rewriting, and the [rw-cache-state]). The utilities [47mset-inhibit-er-soft[0m, [47mset-inhibit-er-soft![0m, [47mtoggle-inhibit-er-soft[0m, and [47mtoggle-inhibit-er-soft![0m have been renamed by dropping the suffix ``[47m-soft[0m'', hence they are now the following, respectively: [47mset-inhibit-er[0m, [47mset-inhibit-er![0m, [47mtoggle-inhibit-er[0m, and [47mtoggle-inhibit-er![0m. The relevant table has similarly been renamed from [47minhibit-er-soft-table[0m to [47minhibit-er-table[0m. These changes reflect their relevance for the new utilities, [47m[er-hard][0m and [47m[er-hard][0m, in addition to [47m[er-soft][0m. The macro [47m[warrant][0m now [47m[force][0ms the warrants listed. [47m:[0m[47m[Induction][0m rules now support the use of [47m[syntaxp][0m hypotheses. The utility [47m[read-file-into-string][0m has been improved in the following ways. * The value of the [47m:start[0m argument may now be any natural number less than the length of the input file. (Formerly one needed to use this utility to read the preceding bytes first, which can be much slower.) Thanks to Eric McCarthy, Eric Smith, and Grant Jurgensen for requesting this improvement and for helpful discussions. * While the default behavior is the same for when the corresponding Lisp stream is closed, a new keyword argument, [47m:close[0m, can be supplied to control that behavior. * Miscellaneous clean-up has been made in the implementation. * Restrictions have been tightened a bit to avoid what could be considered a soundness bug. See discussion about that in the section on ``Bugs'' below. The [47m[trace$][0m option [47m:evisc-tuple :print[0m, which continues to use raw Lisp printing, has undergone the following improvements when printing entry and exit values. Thanks to Eric McCarthy for a query that led to these improvements. * Values are now pretty-printed. * Array values are no longer displayed as [stobj]s. (This includes stobjs themselves, since they are arrays.) The use of [47m(:executable-counterpart rewrite-lambda-modep)[0m to control the behavior of lambda object rewriting by the prover (see [rewrite-lambda-object]) has been elaborated. Warnings for non-recursive functions in left-hand sides of rewrite rules (similarly for linear, forward-chaining, and type-prescription rules) now consider bodies of lambda objects that could be rewritten (see [rewrite-lambda-object]). The output is more informative when [47m:[0m[47m[pr][0m is applied to an undefined primitive, such as [47mcar[0m or [47mbinary-+[0m, or a macro-alias for one of those, such as [47m+[0m. Thanks to Eric Smith for pointing out odd output for examples like [47m:pr binary-+[0m. The definition of [47m[pseudo-termp][0m has been simplified by dropping a superfluous [47m[true-listp][0m check. Thanks for the suggestion from Eric Smith. A new lemma, [47mpseudo-termp-consp-forward[0m, has been added to prevent some existing proofs from failing due to the change. The failure message regarding [useless-runes] (see [useless-runes-failures]) has been restricted to the case that a proof was attempted by the event (though there may be rare exceptions). Thanks to Eric Smith for requesting such a change. Certain guard proof obligations for [47mDO[0m [47m[loop$][0ms (so-called special conjectures (e), (f), and (g)) have been combined into one conjecture with a conjunction of three conditions in the conclusion to speed up proofs. See the comment starting with ``Special conjectures (e), (f), and (g)'' in the function [47mspecial-conjectures[0m in the source file [47mhistory-management.lisp[0m. The rewriter has been changed to handle certain calls of [47mev$[0m faster. See [rewriting-calls-of-apply$-ev$-and-loop$-scions]. A few new lemmas have been added to the standard [47mapply$[0m book to simplify applications of [47massoc-equal-safe[0m faster. [Time-limit] and [theory-invariant] errors may now be inhibited much as [step-limit] errors, by using [47m(set-inhibit-er "Time-limit")[0m or [47m(set-inhibit-er "Theory")[0m, respectively. Thanks to Eric Smith for requesting this enhancement and its use in the implementation of the utility, [47m[prove$][0m. A new command, [47m(cmds c1 c2 ... cn)[0m, has been added to [47m[walkabout][0m. The documentation for [redundant-events] includes the following, which however was not enforced when the new event is in [47m:[0m[47m[program][0m mode; that has been fixed. 4. If either the old or new event is a mutual-recursion event, then redundancy requires that both are mutual-recursion events that define the same set of function symbols. A new feature, called ``transparent'' functions, can allow one to avoid the restriction on a rule of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m that there are no common ancestors of its evaluator and meta function. See [evaluator-restrictions] for relevant background, and see [transparent-functions] for documentation of the new feature. Thanks to Mertcan Temel for requesting a way to work around that restriction, and thanks to Sol Swords for suggesting (and naming) the notion of transparent functions. We are also grateful to Sol for providing a very helpful sketch of a correctness proof. When there is an attachment to a common ancestor of the evaluator and meta function of a proposed rule of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m, the resulting error message now includes ancestor paths leading from the evaluator or meta function to a common ancestor. A new [47m[walkabout][0m command, [47mup[0m, moves up a level and exits the [47mwalkabout[0m loop when already at the top level. It is thus equivalent to the existing command, [47m0[0m, which is still supported although [47mup[0m is highlighted in the documentation; see [walkabout]). Thanks to Eric Smith for suggesting [47mup[0m. Arranged that [iprinting] that takes place during [break-rewrite] or [47m[cw][0m is better reflected outside break-rewrite. For examples, see [community-books] input file [47mbooks/system/tests/iprint-and-brr-input.lsp[0m, which contains comments on problematic interactions between break-rewrite and iprinting in Version 8.5, and which generates (via the [47m[run-script][0m utility) the output in file [47miprint-and-brr-log.txt[0m in that directory. Note that [47m[read-object][0m now updates data structures so that it can read back in what was just printed by [47m[cw][0m; see a comment in the definition of [47mread-object[0m in the ACL2 source code. When a defined function has a [47m[declare][0m form with [47m(optimize ...)[0m, that is now included in a declare form of the executable-counterpart function (see [evaluation]), which had not been the case. It had been the case that for type [declaration]s of [47m[flet][0m definitions in a surrounding [47m[defun][0m form, they were dropped in the [47mdefun[0m form's executable-counterpart (see [evaluation]). Now they are included. The behavior of [47m[pso][0m and related utilities ([47m[pso!][0m, [47m[psof][0m, and [47m[psog][0m) has been modified to avoid introducing warnings that were not originally printed. For example, the output generated by [47m:pso[0m below no longer prints the warning that had been suppressed for the [47mdefthm[0m event below. (set-inhibit-output-lst '(warning proof-tree)) (defthm foo t :hints (("Goal" :use car-cons)) :rule-classes nil) :pso The above change has additional, small output effects, probably for the better. For example, output from the form [47m(with-output :off (error summary) (thm (equal x y)))[0m no longer prints the line shown below (at the end). ACL2 Error [Failure] in ( THM ...): See :DOC failure. When an event fails, then if it involves definition [rune]s for [47m[loop$][0m [scion]s, the failure message may suggest including the book [47mprojects/apply/top[0m if it hasn't already been included. That book provides quite a few lemmas about [47m[loop$][0m scions. Replaced [47m[length][0m calls in the defun of [47m[pseudo-termp][0m with calls of a new macro, [47mlen$[0m, which is a call of [47m[mbe][0m that invokes [47m[length][0m in the [47m:exec[0m code and [47m[len][0m in the [47m:logic[0m code. Thanks to Eric Smith for requesting such an enhancement, and for discussing specifics of it, so as to avoid the need for at least one unfortunate rule that if [47m(pseudo-termp term)[0m then [47m(not (stringp (cdr term)))[0m, apparently needed because [47mlength[0m behaves specially on strings. When there is an error from evaluation of a form encountered by [47m[ld][0m, in a session where the value of [47m[ld-error-triples][0m is the default of [47mt[0m and the value of [47m[ld-error-action][0m is of the form [47m(:EXIT N)[0m, then ACL2 quits with exit status [47mN[0m in some cases where formerly it did not. The following explanation is rather technical; see [ld-error-action] for relevant background. This behavior was already present in the case that the ``error on evaluation'' was from an evaluation result [47m(mv erp val state)[0m where [47merp[0m is non-[47mnil[0m; but it has been extended to the case that [47merp[0m is [47mnil[0m and [47mval[0m is of the form [47m(:STOP-LD . x)[0m, as is returned by default by [47mld[0m upon an evaluation error. A key effect of this change is for the case that a [47m.acl2[0m file produces an error from a call of [47m[build::cert.pl][0m. The following example illustrates; explanation follows below. ;;; foo.acl2 (ld '((defun g (x) y)) :ld-error-action :return!) ;;; foo.lisp (in-package "ACL2") Before this change, the command `[47mcert.pl foo[0m' resulted in a hard Lisp error (as seen in [47mfoo.cert.out[0m). To see why, first note that [47mcert.pl[0m executes a sequence of commands as follows (several omitted as shown with ``[47m...[0m''). ... (set-ld-error-action (quote (:exit 1)) state) ... ; instructions from .acl2 file foo.acl2: (ld '((defun g (x) y)) :ld-error-action :return!) ... #!ACL2 (set-ld-error-action (quote :continue) state) ... The call of [47mld[0m above returns [47m(mv nil (:STOP-LD 2) state)[0m. Because [47mld-error-action[0m at the top level no longer has the default value of [47m:CONTINUE[0m, that result is considered an error (see [ld-error-action]) and top-level evaluation halts. Before this change, then ACL2 did not quit since the value was of the form [47m(mv nil _ state)[0m; instead, ACL2 would quit the top-level call of [47mld[0m, leaving us in raw Lisp. But in raw Lisp, the [47m#![0m reader macro (see [sharp-bang-reader]) is undefined; hence an error would be signaled. After the fix, the return value of [47m(mv nil (:STOP-LD 2) state)[0m is treated as an error, so because [47mld-error-action[0m is [47m(:EXIT N)[0m, ACL2 immediately exits with status [47mN[0m. The pretty-printer has been improved by a contribution from Stephen Westfold to support appropriate indentation, including more conventional pretty-printing for calls of common macros such as [47m[defun][0m and [47m[defmacro][0m. See [ppr-special-syms]; we thank Stephen also for supplying the substance of that documentation. Thanks too to Stephen for suggesting several user-defined macros to be pretty-printed with this mechanism, which we have modified by adding suitable [47m[table][0m events (e.g., for [47m[define][0m). Runtime [guard] violation messages from [47mDO[0m [47m[loop$][0m expressions are now much more readable. They also now include a pointer to the [do-loop$] documentation, which has new, relevant explanation (first in brief, later in detail) regarding such messages. Four obsolete fields of the ACL2 [state] have been removed: [47mbig-clock-entry[0m, [47mt-stack[0m, [47m32-bit-integer-stack[0m, and [47mlist-all-package-names-lst[0m, as have some related built-in, undocumented definitions and theorems, including [47mold-check-sum-obj[0m and supporting functions. Improved [47m[hide][0m calls in prover output from failed execution of [warrant]s, by adding suitable notes about attachments or warrant functions not being executable during proofs. Thanks to Eric McCarthy for a remark that led to this change. State globals [47minhibit-output-lst[0m, [47minhibited-summary-types[0m, and [47mld-level[0m are now [untouchable]. The macros [47m[set-inhibit-output-lst][0m and [47m[set-inhibited-summary-types][0m still allow you to modify the values of these variables. Thanks to Peter Dillinger for correspondence (years ago!) leading to these changes. The macro [47m[state-global-let*][0m no longer requires explicitly supplying a setter for certain built-in [state] global variables. See [47m[state-global-let*][0m. A proposed [47m[defaxiom][0m [event] is no longer [redundant] with an existing [47m[defthm][0m event. Before this change, the following book could (perhaps unfortunately) be certified, even without [47m[certify-book][0m option [47m:skip-proofs-okp t[0m. (in-package "ACL2") (local (defthm foo (equal (car (cons x x)) x))) (defaxiom foo (equal (car (cons x x)) x)) The prover sometimes reduces a goal without hypotheses (technically speaking, a one-element [clause]) to [47mnil[0m using type reasoning (see [TYPE-REASONING]). This heuristic has not changed, but formerly there was no explanation given. Now ACL2 reports the rules (of class [47m:[0m[47m[type-prescription][0m) that were used. The default for [47m[memoize][0m keyword argument [47m:verbose[0m has been changed from [47mt[0m to [47mnil[0m, which (by default) eliminates noise from the output. When a proof attempt is halted so that it reverts to prove the original goal by induction, the top-level checkpoints are printed under the [summary] under the banner, ``[47mKey checkpoints before reverting to proof by induction[0m''. This was normally the case already, but not in the special case that the proof is eventually aborted either because a goal of [47mNIL[0m is produced or because proof by induction is not allowed (due to a [47m:DO-NOT-INDUCT[0m hint or an [induction-depth-limit] being exceeded). Thanks to Eric Smith for a chat that helped lead to this improvement. For most built-in [table]s, error messages for guard failures have been improved, by use of a new macro that is also available to ACL2 users: [47m[set-table-guard][0m. That utility may be used to set a [table] guard in a way that produces a user-friendly error message when the guard fails. The prover may now print a parenthetical remark about ``dropping false conclusion''. That remark points to a new documentation topic, which provides explanation: see [clause]. [State] global [47mtrace-co[0m is now untouchable. ACL2 now warns when the hypothesis of a [type-prescription] or [forward-chaining] rule is a call of [47m[syntaxp][0m or [47m[bind-free][0m, since these get no special treatment for such rules. The utility [47m[get-event-data][0m now returns data from the proof done on behalf of a [47m[thm][0m event, rather than from the surrounding [47m[make-event][0m call used for implementing [47mthm[0m. Thanks to Eric Smith for requesting this change. In the case that a proof is interrupted after [47m(set-debugger-enable t)[0m and then aborted, ACL2 formerly printed failures in a special way, in particular showing the [pstack]. This is no longer the case: all [event] failures are printed in the same way. A new key, [47mEVENT[0m, is available for [47m[get-event-data][0m. Thanks to Eric Smith for a discussion leading to this addition. Most ACL2 reader errors are now ACL2 hard errors rather than raw Lisp errors (as they were formerly). As a result, such errors can sometimes be ``caught'' by suitable programming. Thanks to Grant Jurgensen and Eric Smith for requesting this change. Note that input is still flushed in these cases, perhaps more thoroughly than before. [47m[Break-rewrite][0m, [47m[brr-commands][0m, [47m[monitor][0m, and [47m[unmonitor][0m have been radically changed but in a largely backwards compatible way. It is now possible to cause interactive breaks when a monitored rule is tried but fails to match the target. See [47m[monitor][0m, in particular, see the ``near-miss'' break criteria in [47m[monitor][0m for a discussion. Changes to [47m[break-rewrite][0m largely just correct anomalous behavior. One significant behavioral change is that the list of monitored runes is locally bound by [47mbreak-rewrite[0m, so that while it can be changed in inferior breaks, when control returns to superior levels (and to the top-level) the list of monitored runes is unchanged. Related changes are discussed in the following three items. [See DARPA Note above for this work, including the following three items.] * The [47m[brr][0m-command [47m:[0m[47m[p!][0m (see [brr-commands]) has been redefined so that in [break-rewrite] it is a no-op. (Actually, it did not always work as advertised in [break-rewrite]! Its behavior outside of break-rewrite is unchanged.) A comment in the source code definition of [47mp![0m explains why. * The function [47mget-wormhole-status[0m is deprecated, and its new name is [47m[get-persistent-whs][0m. * The macro [47mshow-brr-evisc-tuple[0m has been eliminated, but [47m[brr-evisc-tuple][0m is available instead. The definition of [47mbounded-integer-alistp[0m has been modified by adding a guard [47m(posp n)[0m and removing the [47m(integerp n)[0m test from the body of its [47m[defun][0m. [See DARPA Note above.] As before, when calling [47m[break$][0m from a [wormhole] --- for example when inside [break-rewrite] --- one is left at a raw Lisp prompt. However, when returning from that prompt (e.g., with [47m:q[0m if the host Lisp is CCL), one no longer stays in the wormhole, as noted by a message, ``Aborting to top level from a wormhole break (see :DOC wormhole).'' [See DARPA Note above.] The function [47miprint-oracle-updates[0m, which is called by [47m[read-object][0m, is now [disable]d, because it was made more complicated to accommodate the conversion of function [47meviscerate-top[0m into [47m:[0m[47m[logic][0m mode. [See DARPA Note above.] The utilities [47m:[0m[47m[pe][0m and [47m:[0m[47m[pr][0m now provide more useful output when applied to function symbols that are built into ACL2 without a defining event. Thanks to Warren Hunt for discussions leading to this improvement. The [47m[guard][0ms and bodies have changed slightly for some built-in function definitions, as follows. * For functions [47m[princ$][0m, [47mprin1$[0m, [47m[explode-atom][0m, and [47mexplode-atom+[0m, the guard now requires of the first argument only that it be an atom; it no longer must be a ``good atom'', i.e., a number, a character, a string, or a symbolp. As a result, the definition bodies of [47m[princ$][0m, [47mprin1$[0m, and [47m[explode-atom][0m have been tweaked slightly. * The guards for [47mpackn1[0m, [47m[packn-pos][0m, [47mfind-first-non-cl-symbol[0m, and [47m[packn][0m have similarly been weakened to require only [47m[atom-listp][0m instead of [47mgood-atom-listp[0m, and the definition of [47mgood-atom-listp[0m has been removed. * The guard for [47m(prin1$ x channel state)[0m now requires [47m(symbolp channel)[0m; it was a bug that this conjunct was formerly omitted. * Several functions that take [47m[state][0m had guards requiring that built-in [state] globals --- those bound in [47minitial-global-table[0m --- are bound in the global-table of the [state] (using [47mf-boundp-global[0m or [47mboundp-global[0m). However, the predicate [47mstate-p1[0m, which recognizes ACL2 [state]s, implies that these conditions all hold; so, they have been removed from those guards. Such a test has also been removed from the definition of [47mmain-timer[0m. The utility, [47m[break-on-error][0m, now causes a much cleaner error when invoked in [raw-mode]. The installation of breaks by [47mbreak-on-error[0m works even in raw-mode --- it's just that evaluation of a call of [47mbreak-on-error[0m must not take place in raw-mode. Also, the effect of [47mbreak-on-error[0m, to cause breaks on errors, works better after entering raw-mode than it did previously, when evaluation of a form [47m(er hard ....)[0m would fail to enter the debugger: that has been fixed. Evaluation of [47m(er soft ....)[0m continues to invoke such breaks whether or not in raw-mode. A new aspect of [47mbreak-on-error[0m is that breaks occur not only for hard and soft errors, but also when aborting to the top level (which is what happens when [47m(er hard ...)[0m is called in raw-mode). Thanks to Eric McCarthy for reporting issues that led to these improvements. When [47m[ld][0m is invoked with a non-[47mnil[0m value of keyword [47m:ld-missing-input-ok[0m and the input file is missing, the value returned is now [47m:missing-input[0m instead of [47m:eof[0m. When [47m[defbadge][0m is applied to a function symbol that is built into ACL2 with a [badge], such as [47m[nth][0m, the result is a no-op and an [observation] is printed to that effect. (Formerly the [47mbadge-table[0m was needlessly extended and ACL2 reported that the function symbol was being given a badge.) Suppose that a [47m[verify-guards][0m event for a defined function symbol, [47mfn[0m, does not include a [47m:hints[0m keyword, but the existing definition of [47mfn[0m includes a [47m:guard-hints[0m keyword in its [47m[xargs][0m [declaration]. Then, unlike previously, the value of that [47m:guard-hints[0m keyword is now used as the value of [47m:hints[0m for that [47mverify-guards[0m event. The keywords [47m:guard-debug[0m and [47m:guard-simplify[0m of [47mverify-guards[0m similarly now default to values of the corresponding [47mxargs[0m in the old definition, if supplied there. This change brings the behavior of [47mverify-guards[0m in line with that of [47m[verify-termination][0m. See [verify-guards] for a discussion of the case of [47m[mutual-recursion][0m, where only the definition of [47mfn[0m is relevant for keyword values, not other definitions in its clique. A hint of the form [47m:induct X[0m is now an error if [47mX[0m is an atom other than [47mt[0m or a quoted constant, since those do not suggest any induction scheme. Thanks to Eric Smith for raising the question of what [47m:induct nil[0m should do and helping with examples showing that the current behavior is not really consistent. Thanks to Alessandro Coglio for suggesting that [47m:induct nil[0m cause an error since it serves no purpose and could be confused with [47m:do-not-induct t[0m, which is quite different. The built-in [47m[defaxiom][0m events [47mcode-char-char-code-is-identity[0m and [47mchar-code-code-char-is-identity[0m no longer have [47m[force][0md hypotheses. Thanks to Alessandro Coglio for pointing out that these [rewrite] rules were rather unique as built-in rewrite rules that force hypotheses. Note that the original versions of these two rules, stated as [47m[defthm][0m events with suffix [47m"-FORCED"[0m added to the names, may be found in community book [47mbooks/std/basic/code-char-char-code-with-force.lisp[0m; including this books (perhaps [local]ly) may rescue a proof that now fails because of the change. Fixed an induction message when limiting the number of cases, in particular, replacing ``we had to fold ... into a single IF-expression'' by ``we had to termify ... (see :DOC termify)'' and explaining in the new [documentation] topic, [termify]. It is now legal to introduce more than one [elim] rule for the same function symbol. Thanks to Eric Smith for pointing out that the current implementation was inconsistent in accepting a replacement [elim] rule when including a book but not at the top level. It is no longer illegal to read a [stobj] when in a [wormhole] state, for example, when inside [break-rewrite]. In [gag-mode] (which is on by default), when the prover notes that a forcing round is pending, it now lists the names of the rules that are responsible. A hash-table or stobj-table field of a [stobj] may now specify a size that is a constant symbol with a suitable value. See [defstobj] and see [stobj-table]. The meaning is the same as if the size had been given as the value of that constant. Thanks to Warren Hunt for requesting this enhancement. The fifth formal of [47m[do$][0m now represents the values returned rather than a default value. This change supports a bug fix; see the item below regarding ``About a bug in DO$ in ACL2 Version 8.5''. The sixth and seventh arguments of [47m[do$][0m have been combined into a record that also contains a list of the names of all the [47m[stobj][0ms in the [47mDO[0m [47mloop$[0m. In the new record, the measure term is stored in untranslated form. The record is only used in the hard error produced when the evaluation of a [47mDO$[0m term fails to terminate and is not relevant to the logical value of the [47mDO$[0m term. It is now legal for the parent stobj of a [47m[stobj-let][0m expression to occur free in the producer when no producer variable is bound in the bindings. For an example, see the section ``Allow the parent stobj of a stobj-let expression to occur free in the producer when no variable bound in the bindings occurs in the producer.'' in [community-book] [47mbooks/system/tests/nested-stobj-tests.lisp[0m. Built-in function [47mbounded-integer-alistp2[0m has been modified to remove [47m[integerp][0m tests on formals [47mi[0m and [47mj[0m from the body and instead require them to satisfy [47m[posp][0m in the [guard]. ACL2 versions of Lisp `fixnum' notions have been made more generous. Specifically, the value of [47m*fixnum-bits*[0m has been increased from 30 to 61, which has increased the value of [47m(fixnum-bound)[0m from 2^29-1 to 2^60-1. Thanks to Eric Smith for requesting an increase. One effect of this change is to increase the value of [47m*default-step-limit*[0m accordingly, so that the steps computed by [with-prover-step-limit] will no longer be limited to fewer than 2^29. [31;1mNOTE[0m. The previous such ``fixnum'' behavior can be obtained by building ACL2 with environment variable [47mACL2_SMALL_FIXNUMS[0m set to a non-empty value. In fact, such a setting is necessary for a 32-bit Lisp such as CMUCL. However, such ACL2 builds are not as fully tested as the usual builds and thus may be less reliable, and they are not guaranteed to work compatibly with ordinary ACL2 builds on the same set of books. Changed the bound [47m*maximum-positive-32-bit-integer*[0m that was used for array lengths (and eliminated that constant), replacing it by the larger value from macro call [47m(array-maximum-length-bound)[0m, which is the same as [47m(fixnum-bound)[0m, i.e., [47m1152921504606846975[0m. Thanks to Eric Smith for suggesting that we consider such a change and for updating books under [47mbooks/kestrel/[0m. Note: For CMUCL (or any 32-bit Lisp) the bound has actually decreased, since [47m(fixnum-bound)[0m is [47m2^30-1[0m in that case. The [47m[case-match][0m macro now generates an [47mignorable[0m [47m[declare][0m form in a clause, for any variable occurring more than once in the pattern. This can free the user from the need to do so. The following example illustrates this change: it now evaluates without error, but before this change one needed to add [47m(declare (ignorable x))[0m or [47m(declare (ignore x))[0m as shown. (let ((e '(a a))) ; same problem for '(a b) instead of '(a a) (case-match e ((x x) ;; Formerly needed (declare (ignorable x)) or (declare (ignore x)) here. t) (& nil))) The [guard]s for functions that operate on characters or strings sometimes insisted that the inputs contain only standard characters. That restriction has been lifted, and the definitions of [47m[alpha-char-p][0m, [47m[upper-case-p][0m, [47m[lower-case-p][0m, [47m[char-downcase][0m, and [47m[char-upcase][0m have been adjusted to handle non-standard characters. The predicate [47mstate-p[0m, which recognizes ACL2 [state] objects, now requires that [47m[print-base-p][0m hold of state global [47mprint-base[0m. Also, function [47mprint-base-p[0m is now [disable]d by default. The predicate [47mstandard-string-alistp[0m has been deleted, while a related predicate [47m[string-alistp][0m has been added. The [break-rewrite] facility will now cause an interactive break on a monitored rewrite rule if the rule's equivalence relation fails to refine any of the equivalence relations known to be permitted while rewriting the target. See [geneqv] for a discussion of how [congruence] rules are used to compute permitted equivalence relations and [refinement-failure] for advice about how to investigate and fix refinement failures during rewriting. The message for evaluation failures during proofs has been modified slightly, clarifying the case of substitution and, especially, suggesting :DOC [comment] for explanations (which has been updated accordingly). Thanks to David Russinoff for an acl2-help list query leading to this improvement. It is no longer illegal for a [47m[defstobj][0m event both to specify keyword argument [47m:NON-EXECUTABLE T[0m and to use the [47m:CONGRUENT-TO[0m keyword argument. [47mLambda[0m objects in positions of [ilk] [47m:FN[0m are now subjected to a size limitation. See [47m[explain-giant-lambda-object][0m. New Features ACL2 now supports floating-point operations. See [df]. Regarding this new feature: Release was approved by DARPA with ``DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.'' Note for system programmers: the new [3mdf expressions[0m affect translation as well as stobjs-in and stobjs-out; see [system-utilities], specifically discussion mentioning ``df''. Thanks to Warren Hunt for his encouragement and support in this effort, towards ACL2 usage in scientific computations. The new zero-ary attachable system function, [47m[heavy-linear-p][0m, allows for enhanced use of [linear-arithmetic] during rewriting, specifically with the test (first) argument of a call of [47mIF[0m. Thanks to Eric Smith for suggesting the development of such a feature, which can be useful in rewriting-based tools. There is a new `[47mmake[0m' target to build an ACL2 executable using [47msave-exec[0m. See [save-exec], in particular the new discussion at the end of that topic. Thanks to Eric Smith for requesting such a utility. New utilities [47m[get-cpu-time][0m and [47m[get-real-time][0m return the cpu time and real (wall clock) time that has elapsed since the start of the ACL2 session. Thanks to Eric McCarthy for suggesting the addition of such utilities. The new utility [47m[er-hard][0m is analogous to [47m[er-soft][0m, but for hard errors instead of soft errors (see [er]). A new command, [47m:[0m[47m[tc][0m (translate and clean), has been added. It translates a given form and then ``cleans it up'', returning a logically equivalent but often simpler term in which logically irrelevant but operationally important tags have been removed. The variants [47m:[0m[47m[tca][0m and [47m:[0m[47m[tcp][0m use different degrees of ``cleaning.'' These are particularly useful for seeing the logical meanings of [47m[loop$][0m terms as well as terms involving [47m[mbe][0m and [47m[return-last][0m. A directory of [books] may now be relocated so that those books are still treated as certified. This is supported by a new [47m[project-dir-alist][0m, which associates keywords with ``project directories'' and is set using environment variable [47mACL2_PROJECTS[0m; see [project-dir-alist]. By default, the [47mproject-dir-alist[0m has only one entry, which associates the keyword [47m:SYSTEM[0m with the [community-books] directory, [47mbooks/[0m. The [47mproject-dir-alist[0m generalizes the notion of system books directory, assigning meaning to the [47m:dir[0m argument of [47m[include-book][0m and [47m[ld][0m and to [sysfile] arguments of [47m[add-include-book-dir][0m and [47m[add-include-book-dir!][0m. Thanks to Sol Swords for requesting such a capability and for helpful design discussions. (Technical Note: Implementation-level changes are summarized in comments in the form [47m(defxdoc note-8-6 ...[0m) in [community-book] [47msystem/doc/acl2-doc.lisp[0m.) A new [break-rewrite] command, [47m:pot-list[0m, shows the list of the polynomials that are assumed in the current context. See [brr-commands] and see [brr@]. Thanks to Alessandro Coglio and Eric Smith for conversations leading to this enhancement. It is now possible to cause [47m[make-event][0m to do proofs during its expansion phase even in a context where proofs are generally skipped (see [ld-skip-proofsp]). See [make-event], in particular the discussion there labeled as ``(4)''. Thanks to Eric Smith for requesting such a feature. The induction mechanism in the prover can now deduce induction suggestions from some [47mDO[0m [47mloop$[0ms. See [stating-and-proving-lemmas-about-loop$s] for a brief discussion. A new [47m:[0m[47m[linear][0m rule, [47macl2-count-car-cdr-linear[0m, is now built into ACL2, as follows. Thanks to Eric Smith for suggesting this improvement (slightly renamed here) to what we originally added. [31;1mTheorem: [0m<acl2-count-car-cdr-linear> (defthm acl2-count-car-cdr-linear (implies (consp x) (equal (acl2-count x) (+ 1 (acl2-count (car x)) (acl2-count (cdr x))))) :rule-classes :linear) The Common Lisp utility, [47m[macrolet][0m, is now supported in ACL2. Thanks to Alessandro Coglio for discussion leading us to make this addition. See [macrolet]. The utilities [47m[with-output][0m and [47m[with-output!][0m have been enhanced in the following two ways; see [with-output] for details. * A new keyword, [47m:inhibit-er-hard[0m, can be supplied a non-[47mnil[0m value to turn off hard errors when error output is inhibited. Thanks to Eric Smith for a conversation leading to this enhancement. * The keyword [47m:off[0m for the utility [47m[with-output][0m (also [47m[with-output!][0m) can take on a new value, [47m:all![0m, which is treated exactly the same as using arguments [47m:off :all :gag-mode nil :inhibit-er-hard t[0m. The new utility [47m[with-cbd][0m creates a scope for an indicated value of the connected book directory (see [cbd]). Calls of [47mwith-cbd[0m are allowed in [books] as well as in [47m[encapsulate][0m and [47m[progn][0m [events]; see [embedded-event-form]. Thanks to Sol Swords for requesting that [47mwith-cbd[0m be legal in embedded events. Thanks to Sol Swords and Mertcan Temel for reporting a bug in an initial implementation. The new utility, [47m[with-current-package][0m, evaluates a given form with respect to an indicated [current-package]. Thanks to Sol Swords for requesting this utility. See [fast-cert] for a ``fast-cert'' mode for faster, but possibly unsound, book certification, in particular when using a saved executable that contains [local] events. Thanks to Sol Swords for requesting such a capability and for helpful design discussions. Added utility [47m[set-warnings-as-errors][0m, which can change [warnings] to hard [errors]. Thanks to Mark Greenstreet for the idea and for discussions that were helpful in refining it. A new [47m[ld][0m special, [47m[ld-always-skip-top-level-locals][0m, has the effect of skipping [47m[local][0m top-level forms. Thanks to Sol Swords for requesting such a capability, to support faster loading of [47m.port[0m files by the build system (see [47m[build::cert.pl][0m). The symbol, [47mnumber[0m, is now a legal [type-spec]. It is now permitted for a [stobj] [47ms[0m to occur more than once as an actual parameter in a function call, provided each such occurrence is in a position where a stobj congruent to [47ms[0m is expected (possibly [47ms[0m itself). Thanks to Sol Swords for providing a relevant example, which appears in a comment in the definition of function [47mstobjs-in-out[0m in the ACL2 sources. A new utility, [with-brr-data], together with related query utilities, allows one to find the source of a term in prover output. Thanks to Sol Swords for requesting something like this in 2008 (!) and to Eric Smith for requesting a related utility (see [community-books] [47mkestrel/utilities/brr-data-failures.lisp[0m and [47mkestrel/utilities/brr-data-all.lisp[0m). See [with-brr-data]. [47m[Make-event][0m takes a new keyword, [47msave-event-data[0m. When that keyword is non-[47mnil[0m, event-data from the expansion saved is preserved; see the new section at the end of [make-event-details]. This new feature was motivated by the desire to preserve a proof's event-data in calls of [47m[thm][0m, as described in the ``Changes'' section above. New utilities allow one to explore what has changed when an event fails in a book that formerly certified. See [saving-event-data]. Thanks to Eric Smith for requesting such a capability and for helpful bug reports for early versions of these utilities. A new legal value for [47m[set-verify-guards-eagerness][0m, [47m3[0m, causes guard verification even when [47m:verify-guards nil[0m has been [declare]d. This can be helpful when a [47m[verify-termination][0m event in a book is intended to verify [guard]s but a [local]ly included book declares [47m:verify-guards nil[0m in the corresponding [47mverify-termination[0m event. (Technical note: That issue occurs because [47mverify-termination[0m invokes [47m[make-event][0m, and the expansion is saved when locally including the sub-book.) When environment variable [47mACL2_WRITE_BOOKDATA[0m has a non-empty value, then files of the form [47m*__bookdata.out[0m will be written; see [bookdata] for explanation and an exception. Thanks to Eric Smith for requesting this enhancement. [47m[Thm][0m now takes an optional [47m:instructions[0m keyword argument, like [47m[defthm][0m. Thanks to Warren Hunt for requesting this enhancement. New utilities [47m[trans*][0m and [47m[trans*-][0m can show repeated macroexpansions of a form leading to its final translation, where [47mtrans*[0m also shows [47m[make-event][0m expansions. Thanks to Warren Hunt for requesting a utility that does repeated macroexpansion. A new command has been added to the [proof-builder-commands], to display the linear arithmetic database. See [ACL2-pc::pot-lst]. Thanks to Dave Greve for bringing forward the idea of such a command. The utility [47m[set-raw-proof-format][0m now takes a new legal value, [47m:clause[0m, which is like [47mt[0m except that in addition to printing [rune]s as lists in output from the simplifier, it prints all goals as [clause]s. Thanks to Eric Smith for encouraging such an enhancement. It is possible to cause ACL2 to increase its effort in [type-reasoning]. See [set-dwp]. Thanks to Eric Smith for correspondence leading to this feature. The new documentation topic, [induction-coarse-v-fine-grained], discusses how appropriately setting ruler-extenders can sometimes improve the induction scheme suggested by a recursive function, especially one involving [47m[let][0m and [47m[let*][0m bindings containing conditional recursive calls. For that new topic, new related books [47mbooks/demos/ppr1-experiments.lisp[0m and [47mbooks/demos/ppr1-experiments-thm-1-ppr1.lisp[0m, and related edits of existing :DOC topics ([advanced-features], [definductor], [defun], [induction], [rulers], [verify-termination], and [xargs]): Release was approved by DARPA with ``DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.'' A new supported value for [47m(@ script-mode)[0m, [47mskip-ldd-n[0m, directs the [47m[run-script][0m tool to prevent [history] commands such as [47m:[0m[47m[pe][0m from printing event numbers. That can make the output less sensitive to ACL2 changes. For an example, see the use of [47m(assign script-mode 'skip-ldd-n)[0m in [community-book] file [47mbooks/demos/floating-point-input.lsp[0m. A new [stobj] field keyword, [47m:element-type[0m, is legal for an array field. It specifies the raw Lisp element type of the array. Its value can be the element type specified by the value of the [47m:type[0m for that array field. That is the default value, and the other legal value is [47mt[0m, but these may change in the future. See [defstobj] and see [defstobj-element-type]. A new [47mbrr[0m command, [47m:[0m[47m[explain-near-miss][0m, when issued in a break caused by a near miss, will try to pinpoint how the rule's pattern failed to match the current target. A new utility, [47m[compare-objects][0m, highlights the differences between two [47mcons[0m-trees. Now [47m[defabsstobj][0m accepts the [47m:non-executable[0m keyword, in analogy to support for that keyword by defstobj. Thanks to Yahya Sohail and Warren Hunt for discussions leading to this enhancement. New functions [47m[add-global-stobj][0m and [47m[remove-global-stobj][0m change whether there is a global (``live'') stobj for a given stobj name, thus modifying the effect of the keyword [47m:non-executable[0m of events [47m[defstobj][0m and [47m[defabsstobj][0m. Thanks to Yahya Sohail and Warren Hunt for discussions leading to the addition of these utilities. A new [47m[defabsstobj][0m keyword, [47m:attachable[0m, allows a single abstract [stobj] to have more than one foundation and associated functions for execution, without the need to recertify the book that introduces the stobj. See [47m[attach-stobj][0m. Thanks to Warren Hunt and Yahya Sohail for requesting this feature. We thank Sol Swords, Warren, and especially Yahya for helpful input on its high-level design. Heuristic and Efficiency Improvements Added a ``desperation heuristic'' to compute a stronger context, for the extra try at simplification made after a goal is not changed by simplification. Thanks to Warren Hunt and Vivek Ramanathan for supplying an example of a theorem whose proof had a surprising failure but now succeeds. (Technical Remark describing this change: When a [clause] has most recently settled down at the time that the simplify process is invoked (a so-called ``desperation heuristics'' attempt), then the literals are reordered before building the [type-alist], so that the literals that involve at most one variable precede the other literals.) Generation of guard [clause]s (and, probably rarely, other goals) has been sped up in certain extreme cases. For details, see [system-attachments], specifically the discussion of CONJOIN-CLAUSE-SETS-BOUND in the ``Summary of attachable system functions''. Thanks to Alessandro Coglio for sending an example that led to our discovery of the quadratic behavior eliminated by this change. Duplicate entries in [type-alist]s (proof contexts) are now avoided in many cases. (Implementation note: some calls extending the type-alist with an existing term/type-set pair are now avoided in source function [47massume-true-false-rec[0m.) Thanks to Eric Smith for pointing out that there can be type-alists with many consecutive identical entries. Sped up macroexpansion for several common macros, with roughly a 2% to 3% speedup observed for including several large books during development of this change. Tweaked [linear-arithmetic] to avoid consideration of an equality between two terms that are both known (via their [type-set]s) to be non-numeric. The utility [47m[set-cbd][0m is more efficient when setting to the current [47m[cbd][0m, including the common case of calls to [47mset-cbd[0m by [47m[ld][0m and (hence) [47m[wormhole][0m. New built-in [rewrite] rules [47mall-boundp-initial-global-table-alt[0m and [47mall-boundp-initial-global-table[0m may help with reasoning about [47mstate-p1[0m. Use [47m:[0m[47m[pe][0m to see their [events]. The latter is [disable]d by default and may useful to [enable] when developing proofs that rely on built-in [state] globals being bound. ACL2 has a procedure for evaluating ground [term]s (terms without free variables) that is used in the generation of [guard] obligations as well as in [linear-arithmetic] and [forward-chaining]. This procedure was not used on subterms of bodies of [lambda] expressions, but now it is. Thanks to Eric Smith for requesting this enhancement (in particular for generation of guard obligations). The ACL2 [type-reasoning] mechanism has been strengthened slightly for an [47mif[0m expression being assumed true or false, when that expression has a subterm of the form [47m(equal term 'c)[0m, or [47m(equal 'c term)[0m and [47mc[0m is [47m0[0m, [47m1[0m, [47mt[0m, or [47mnil[0m. Thanks to Warren Hunt for sending an example involving [forward-chaining] that led to this improvement. [31;1mIMPORTANT NOTE:[0m If this change causes a proof to fail that formerly succeeded, you can fix it by preceding it with the following (implicitly [local]) event. (defattach-system use-enhanced-recognizer constant-nil-function-arity-0) For a book's event of the form [47m(defconst *NAME* (quote VAL))[0m that results from [47m[make-event][0m expansion, [47mVAL[0m is no longer duplicated between that book's [certificate] file and its compiled file. Thanks to Sol Swords for requesting this enhancement. This lack of duplication also applies to any such [47mdefconst[0m event in a book that is in the scope of a [47m[progn][0m or [47m[encapsulate][0m event when there is at most one [47mmake-event[0m call in that scope; similarly for such [47mdefconst[0m events within calls of [47m[skip-proofs][0m, [47m[with-output][0m, [47m[with-guard-checking][0m, or [47m[with-prover-step-limit][0m. Each new stobj was being created twice at [47m[include-book][0m time, once when the book's compiled file is loaded and once when the [47m[defstobj][0m or [47m[defabsstobj][0m event is processed. The former initialization is unnecessary and has been eliminated. A limit has been placed on generation of equality hypotheses by linear arithmetic. For example, if a goal has hypotheses (technically: negative literals) [47m(<= term1 term2)[0m and [47m(<= term2 term1)[0m, it may generate the hypothesis [47m(equal term1 term2)[0m. This is now indicated by the phrase "equality generation from inequalities" found in proof output if you have evaluated the form [47m(set-gag-mode nil)[0m, and it is now indicated in the proof [summary] by the presence of the [rune], [47m(:FAKE-RUNE-FOR-LINEAR-EQUALITIES NIL)[0m. By default, there is a limit of five ``levels'' of such equality generation, for example in goals [47m"Subgoal 2"[0m, [47m"Subgoal 2.1"[0m, [47m"Subgoal 2.1.3.4.5"[0m, [47m"Subgoal 2.1.3.4.5'"[0m, and [47m"Subgoal 2.1.3.4.5''"[0m --- in general, such addition of equalities can only be performed five times along a chain of goals where each is a descendant (not necessarily an immediate subgoal) of the one before, and each induction and forcing round provides a fresh start. You can change that default from 5 to [47mn[0m, where [47mn[0m is a natural number, by evaluating the following form. (table equational-polyp-limit-table t n) Thanks to Eric Smith for sending an example with looping behavior, which motivated the change above (as a way to break such loops). Bug Fixes Fixed a soundness bug based on rules of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m that would be exported from an [47m[encapsulate][0m event with a non-[47mnil[0m [signature] list. A proof of [47mnil[0m in Version 8.5 may be found in the [community-books] file, [47mbooks/system/tests/transparent-functions-input.lsp[0m; search for this paragraph there. Fixed a soundness bug in [47m[open-input-channel][0m and [47m[open-output-channel][0m. The [guard] in each case required the first argument, a file name, to be a string; but these functions pass that argument to a function --- [47mmake-input-channel[0m and [47mmake-output-channel[0m, respectively --- that required the string to contain only standard characters (see [standard-char-p]). That was possible because [47mopen-input-channel[0m and [47mopen-output-channel[0m were invoked under [47m[skip-proofs][0m in the ACL2 sources. This bug has been fixed, and those uses of [47mskip-proofs[0m eliminated, with removal of the restriction to standard characters for virtually all guards, including the guards for Common Lisp functions [47m[char-downcase][0m and [47m[char-upcase][0m. Thanks to Eric Smith for reporting this bug, including a proof of [47mnil[0m by giving a [47m:use[0m hint for an [47m:instance[0m of [47m(:guard-theorem open-input-channel)[0m. Eric also supplied events, incorporated into ACL2 source file [47maxioms.lisp[0m, that removed the [47m[skip-proofs][0m wrappers from five definitions. Fixed a soundness bug that exploited incorrect generation of raw Lisp code for the recognizer of a [stobj] field of a stobj. More precisely, the bug occurred when a concrete stobj has a field whose type is the name of either a concrete or abstract stobj. Here is an example. First certify the following book, sub.lisp. (in-package "ACL2") (defstobj lo lo-fld) (defstobj hi (hi-fld :type lo)) Then before the bug was fixed, the following book was certifiable. (in-package "ACL2") (include-book "sub") (defthm thm1 ; logically correct (hi-fldp '(nil)) :rule-classes nil :hints (("Goal" :in-theory (disable (:e hi-fldp))))) (defthm thm2 ; "proved" by unsound execution (not (hi-fldp '(nil))) :rule-classes nil) (thm ; proof of nil nil :hints (("Goal" :use (thm1 thm2)))) It was probably a soundness bug to allow a [47m[defaxiom][0m event to designate a rule of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m in its [47m:[0m[47m[rule-classes][0m. That is no longer allowed; [47m[skip-proofs][0m may be used instead if one believes that the proposed formula is a theorem. The function [47m[read-file-into-string][0m has been modified to avoid what might be considered a soundness bug. The change involves causing an error for two reads of the same file without first incrementing the file-clock of the [state]. See [read-file-into-string] for details, in particular for how to avoid that error by evaluating [47m(increment-file-clock state)[0m after calling [47mread-file-into-string[0m. Formerly the error was avoided if the write-date of the file didn't change between the two reads, but the following example shows how this permitted two calls with identical arguments to produce different results, logically causing [47mread-file-into-string[0m to violate the axiom [47mx = x[0m. First run the following shell commands. echo 'test1' > tmp1.txt ; echo 'test2' > tmp2.txt cp -p tmp1.txt tmp.txt Then start ACL2 and run a command as follows. ACL2 !>(read-file-into-string "tmp.txt") "test1 " ACL2 !> Now suspend ACL2 with [47mcontrol-Z[0m and run the following shell command. cp -p tmp2.txt tmp.txt Now resume ACL2 with [47mfg[0m, and optionally submit some trivial form (say, [47m3[0m) just to get the prompt back. Note that the file-clock of the [47mstate[0m hasn't changed. (Probably the [47mstate[0m hasn't changed; at any rate, the parts of the state relevant to [47mread-file-into-string[0m haven't changed.) So the following call has arguments identical to those in the corresponding call above, yet yields a different result. ACL2 !>(read-file-into-string "tmp.txt") "test2 " ACL2 !> After the change to [47mread-file-into-string[0m, its call just above causes an error. Plugged a potential soundness hole in [47m[defwarrant][0m (though we have not actually observed unsoundness), with changes that will probably be invisible to users. Thanks to Sol Swords for bringing this issue to our attention. Fixed a bug in system function [47mbounded-integer-listp[0m, which may have allowed illegal [proof-builder] commands to be attempted. Thanks to Grant Jurgensen for pointing out this bug. Consider calls of [47m[defthm][0m and [47m[thm][0m that create subgoals before reverting to prove the original goal by induction. The Rules summary printed at the end should exclude rules used only before the start of that induction proof. That was formerly the case for [47mdefthm[0m but not [47mthm[0m, but now it is the case for both. You can see the change for the following call, whose Rules summary formerly included [47m(:ELIM CAR-CDR-ELIM)[0m but no longer does so. (thm (equal (append (append x y) z) (append x y z)) :hints (("Goal" :expand ((:free (b) (append x b)) (:free (a b) (append (cons (car x) a) b)))))) Fixed bugs in the definition of source macro [47mposition-ac[0m. Thanks to Eric Smith for pointing them out. Several improvements were made to the [47mFOR[0m [47m[loop$][0m utility (also see [for-loop$], to reflect more accurately the Common Lisp [47mloop[0m utility. This matters because in [guard]-verified code, [47mloop$[0m becomes [47mloop[0m. Here are the most user-visible such changes. * Run-time [guard]-checking for [47m[loop$][0m operators [47mSUM[0m and [47mAPPEND[0m did not include a check that the value produced at each iteration is a number or true list, respectively. That has been fixed so that, for example, the expression [47m(loop$ for v in '(1 a 2) sum v)[0m now causes a guard violation (because [47ma[0m is not a number), where previously it did not. * For a form [47m(loop$ for tail on lst ...)[0m, the target term, [47mlst[0m, no longer needs to satisfy [47m[true-listp][0m. For example, the form [47m(loop$ for tail on '(a b . c) collect tail)[0m no longer causes a [guard] violation. * Run-time [guard]-checking for an expression [47m(loop$ for tail on lst ...)[0m now includes a check for the target, [47mlst[0m, that its final tail (i.e., [47m(last-cdr lst)[0m) satisfies the declared type of the corresponding iteration variable. For example, evaluation of the [47m[loop$][0m expression below now produces a guard violation as shown, but it formerly did not produce a guard violation. ACL2 !>(loop$ for tail of-type cons on '(a b c) collect tail) ACL2 Error [Evaluation] in TOP-LEVEL: The guard condition (CONSP LOOP$-LAST-CDR), which was generated from a type declaration, has failed. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> Corresponding run-time checking was added for the types of the lower and upper bounds [47mlo[0m and [47mhi[0m, the increment [47minc[0m, and the last value tested, in expressions [47m(loop$ for i from lo to hi by inc ...)[0m. Fixed a low-level bug in source function [47mtranslate-declaration-to-guard1-gen[0m that was incorrectly creating untranslated [term]s in some cases from [type] declarations of the form [47m(type (signed-byte _) _)[0m or [47m(type (unsigned-byte _) _)[0m. Here is an example of an event that is rejected without the bug fix. (defun foo (n) (apply$ (lambda$ (x) (declare (type (signed-byte 8) x) (xargs :guard (signed-byte-p 8 x) :split-types t)) (+ 3 x)) (nfix n))) Suppose a book is certified in a [world] where a [portcullis] [command] generates a [47m[local][0m call of [47m[make-event][0m. Then that event is now ignored when subsequently including that book. Previously it may not have been ignored, because the [47mlocal[0m wrapper could be ignored when writing the book's [certificate]. Some handling of exceptional cases in [hints] has been cleaned up, as follows. Thanks to Eric Smith for a discussion that led to these changes. * [Warnings] for repeating a goal name in the hints now appear even when the repetition is only up to case. For example, such a warning is generated now for [47m:hints (("Goal" :use foo) ("GOAL" :use bar))[0m where formerly it was not. The discussion of this situation in documentation topic [hints] has been improved. * It was incorrectly documented in topic [hints], in the discussion of [47m:do-not[0m hints, that it is illegal to associate a goal name with the empty list of [hints], as in [47m("Goal")[0m. This behavior was actually allowed; an empty such hint was simply ignored. This continues to be allowed (for backward compatibility) but the documentation has been updated; also, these empty hints are now ignored for purposes of the warnings mentioned above (formerly they were considered when looking for repetition of goal names). A bug in the [brr] commands [47m:eval$[0m, [47m:go$[0m, and [47m:ok$[0m was fixed so they now behave as described in the documentation for [brr-commands]. When a certified book is included, the logical [world] will no longer be marked as having seen a [47m[skip-proofs][0m call due to [47m[ld][0m special [47m[ld-skip-proofsp][0m having a non-[47mnil[0m value at that time. Thus, that situation no longer disqualifies such a world from supplying the [portcullis] commands to a book to be certified without keyword argument [47m:skip-proofs-okp t[0m of [47m[certify-book][0m. Thanks to Sol Swords for pointing out this bug. Fixed a bug that was causing calls of [47m[wormhole][0m to signal an error. Fixed a bug that could cause a [47m[do-loop$][0m expressions to be inappropriately rejected due to an allegedly ignored variable. An example is below. (include-book "projects/apply/top" :dir :system) ; BUG: The following was formerly necessary, but no longer is. (set-ignore-ok t) (defun f (a b) (loop$ with x = a with y = b do ; The use of (set-ignore-ok t) was needed, but shouldn't have been, ; whether or not the next line is included. :measure (+ (len x) (len y)) (cond ((consp y) (let ((z y)) (progn (setq y (cdr x)) (setq x (cdr z))))) (t (return y))))) Fixed the failed redundancy check when setting a [table] guard that returns two values. For example, the form [47m(table foo nil nil :guard (mv t nil))[0m was not formerly seen as [redundant] when evaluating it a second time. Fixed a bug that was causing [47m[cw-gstack][0m to report ``Rewriting (to simplify) the first argument'' when rewriting the second argument of a call of [47m[implies][0m, and fixed an analogous bug for [47m[return-last][0m. Fixed a bug in [47m[intersection$][0m that prevented it from being called with keyword argument [47m:test 'equal[0m. Thanks to Anna Slobodova for bringing this bug to our attention. Certain error messages from [47m[translate][0m and [47m[untranslate][0m are now inhibited when they should be (where formerly they weren't). Thanks to Eric Smith for bringing this problem to our attention. Fixed a bug that in rare cases, for direct prover calls (e.g., with [47m[prove$][0m, could cause an error reporting ``HARD ACL2 ERROR in pop-warning-frame''. Thanks to Eric Smith for bringing this bug to our attention. Note that with this change, then when an [event]'s evaluation causes a hard error (see [er] and [hard-error]): [summary] information may be printed that was formerly omitted; and a superfluous extra failure message may be omitted that was formerly printed. The function [47m[delete-file$][0m executed in a way that diverged from its logical definition: successful deletion caused return values of [47m(mv t state)[0m but this was provably impossible according to the logical definition. This has been fixed. Fixed the [useless-runes] feature to work properly when reading a useless-runes file while certifying a book in a package other than the [47m"ACL2"[0m package. The fix is to ensure that the useless-runes file is read while in the [47m"ACL2"[0m package, which is the same package used when the file was written. Fixed a bug in handling of the [47m[ld][0m keyword [47m:ld-missing-input-ok[0m, by eliminating an error in the case that the specified input file's directory does not exist. The fix avoids executing some of the [47mld[0m code that was formerly executed. Thanks to Alessandro Coglio and Eric Smith for bringing this bug to our attention. An error formerly occurred if one first evaluated [47m(defwarrant FN)[0m for some [47mFN[0m and then attempted to include a certified book containing [47m(defbadge FN)[0m. That has been fixed. Thanks to Mertcan Temel for reporting this bug. Such a [47m[defbadge][0m event is now a no-op, which is reported by an [47m[observation][0m except during [47m[include-book][0m and except during the second pass of an [47m[encapsulate][0m event. Moreover, the [47m[defwarrant][0m event now returns the value [47m:WARRANTED[0m instead of [47mT[0m --- more precisely, it returns a [value-triple] whose value component is [47m:WARRANTED[0m --- and similarly for [47m[defbadge][0m and [47m:BADGED[0m. We fixed a bug that caused the [tau-system] sometimes to cause a raw Lisp error when the [executable-counterpart]s of certain primitive recognizers were [disable]d. Thanks to Eric Smith for reporting this bug and providing an example of it. We fixed a bug that might cause suitable induction schemes to be eliminated because of inappropriate consideration of [47m:[0m[47m[definition][0m rules. Some [proof-builder] commands, including [47m:claim[0m and [47m:casesplit[0m, are more robust (specifically, when claiming or splitting on certain terms that are trivially true). Thanks to Drew Walter for supplying an illustrative example. A bug in [47m[trace$][0m could trigger raw Lisp errors when the [47m:entry[0m, [47m:exit[0m, or [47m:cond[0m option specified an ill-guarded expression. For example, after evaluating [47m(defun f (x) x)[0m and then [47m(trace$ (f :entry (car x)))[0m, evaluation of [47m(f 3)[0m caused a raw Lisp error due to evaluation of [47m[car][0m on the value, 3. This has been fixed. (Technical Remark: the fix was to replace the expression with the same ``oneify'' process that is used for generating definitions of executable-counterpart functions; [evaluation].) Eliminated the built-in [47m:[0m[47m[type-prescription][0m rule [47mtrue-listp-take[0m, thanks to Eric Smith, who pointed out that the same rule is already installed as the built-in [47m:type-prescription[0m rule for [47m[take][0m. Fixed a bug in handling of [47m[do-loop$][0m expressions that return multiple values, when encountered during proofs. An example labeled with ``Version 8.5'' is near the end of [community-book] [47mprojects/apply/loop-tests.lisp[0m. A bug in [47m[do$][0m, hence in [47m[do-loop$][0m expressions, was that single-threadedness (for [stobj]-based computations) can be violated when a loop terminates prematurely because the measure fails to decrease. The bug, which has been fixed, is explained in detail in a comment in ACL2 source file [47mapply.lisp[0m, entitled ``About a bug in DO$ in ACL2 Version 8.5''. Fixed a bug in [47m[fmt][0m and related functions, where a right square bracket immediately following a [47m~&[0m or [47m~v[0m directive failed to be printed, for example: [47m(fmx "hello ~&0]~|" '(world))[0m. Fixed a bug that could cause an implementation error during a proof, when printing a term with a [47m[do$][0m call. (The bug was in untranslating certain applications of [47m[nth][0m, [47m[update-nth][0m, or [47m[update-nth-array][0m during a proof.) [47m[With-global-stobj][0m no longer produces an invalid result when its first argument names a non-executable [stobj]. Previously, the call of [47mread-state[0m below could return the nonsensical result 637624320. (defstobj st fld :non-executable t) (defun read-state (state) (declare (xargs :stobjs state)) (with-global-stobj st (fld st))) (read-state state) Fixed two bugs when attempting to redefine with [47m[defabsstobj][0m. The visible bug was a printing error. A second bug, not visible to the user because of the first bug, was a low-level bug that prevented one of the supporting names from being recorded in the [world] as a supporter of the given stobj. Changes at the System Level The `[47mmake[0m' target, [47msave-exec[0m, now builds [47mcustom-saved_acl2[0m unconditionally. Thanks to Grant Jurgensen for pointing out (in GitHub Issue #1422) that there can be untracked implicit dependencies that make this necessary. Implementations underlying the functions [47m[sys-call][0m, [47m[sys-call+][0m, and [47m[sys-call*][0m have been cleaned up. In particular, we now expect them to indicate precisely the case of a non-error process return as follows: 0 for [47m[sys-call-status][0m, and [47mnil[0m for the first return value of [47msys-call+[0m and [47msys-call*[0m. Also, a bug has been fixed for [47msys-call+[0m in the case of GCL as the host Lisp. Thanks to Eric Smith for queries leading to these changes. Significantly extended documentation topic [system-attachments], which now lists all built-in system attachments, many with brief documentation. Thanks to Eric Smith for suggesting this enhancement. Significant new [documentation] topics, together with subtopics and books supporting those topics, include the following. [See DARPA Note above.] * [Start-here] provides a guide for those getting started with ACL2. * [Recursion-and-induction] has been extensively modified from past, standalone versions by J Moore, and is now integrated with the rest of the [documentation]. Thanks to Vivek Ramanathan for helpful feedback. * [Gentle-introduction-to-acl2-programming] has also been updated from past standalone versions and integrated into the rest of the documentation. * [Loop$-primer] provides an extensive primer on the ACL2 [47m[loop$][0m feature. * [Type-reasoning] gives a basic introduction to what has sometimes been called ``type-set reasoning'' but is now generally referred to as ``type reasoning''. This new topic is now referenced in many other built-in documentation topics. Thanks to Warren Hunt for communication leading to this new topic. * [Soundness] discusses what we can conclude when we use ACL2 to prove a formula or to compute the value of an expression. Allow [47m[ld][0m output in [raw-mode] to go to other than the channel, [47m*standard-co*[0m. Thanks to Vivek Ramanathan and Warren Hunt for an example illustrating the issue. (For system hackers only) The feature [47m:acl2-loop-only[0m is now true inside the ACL2 read-eval-print loop. Therefore, the function [47mlp![0m is no longer supported or necessary, since [47m(lp)[0m enters the loop with feature [47m:acl2-loop-only[0m true, just as [47m(lp!)[0m did previously. (CCL only) [Stobj] array code now has a workaround for a {CCL bug | https://github.com/Clozure/ccl/issues/446} found by Yahya Sohail, in the case of reading a stobj array of integers where the element type includes at least one negative number and one non-fixnum. That bug has been around since at least as far back as 2017, and was fixed on June 12, 2023. For those using a CCL version with the bug, this fix may slow down such stobj array reads a bit in the case described above; one measurement showed about 37% more time for such a read. Thanks to Yahya for the bug report, to Warren Hunt for encouraging a workaround, and to the CCL developers (in particular Gary Palter) for fixing the CCL bug. The undocumented utility, [47mthm-fn[0m --- which is used in several [community-books] --- now has an additional formal (at the end), [47mevent-form[0m. That argument can generally be passed as [47mnil[0m for appropriate behavior. Code for [47m[set-cbd][0m has been tweaked to add assurance that the [47m[cbd][0m always ends in a forward slash (`[47m/[0m'), as specified. Thanks to Stephen Westfold for a comment leading to this modification. Updated file [47mGNUmakefile[0m in the top-level directory so that when an ACL2 executable is built, files are updated in subdirectory [47mbooks/build/[0m to support the use of [47m[build::cert.pl][0m. Thanks to Eric Smith for the idea, and thanks to Eric and also Sol Swords for help with the implementation. The notion of ACL2 [state] is formalized in function [47mstate-p1[0m, which has implicitly changed because it depends on the constant [47m*initial-global-table*[0m, whose value has changed. That constant's value, which is still an alist, now includes additional pairs, which are from the constant [47m*initial-ld-special-bindings*[0m; thus, [47m*initial-global-table*[0m now specifies a value for each so-called ``[47m[ld][0m special''. The previous ACL2 release (Version 8.5) arranged that when a raw Lisp error is encountered, any available input is cleared from the input channel. However, this can lead to discarding of valid input or an attempt to read values from within a comment; see [community-books] files [47mclear-input-1.lsp[0m and [47mclear-input-2.lsp[0m, respectively, in directory [47mbooks/system/tests/[0m. So now, input is cleared on error only when reading from the terminal (technically, from [47m[*standard-oi*][0m). Improved certain build-time error messages. These improvements are particularly helpful when the host Lisp is SBCL or CMUCL, so that the error message is printed properly into make.log (instead of showing up as an error call at the terminal), and also when the host Lisp is LispWorks, so that verbose debugging information is avoided (since these are ACL2 errors for which that information is very unlikely to be helpful). Thanks to Alessandro Coglio for a recent Zulip query that led us to make this change. A new documentation topic and its subtopics describe uses of ACL2 and its predecessor, Nqthm, in modeling state machines. See [operational-semantics], which notes that others are welcome to add to these topics; see the discussion of ``Request for Suggestions from ACL2 Users''. The new topic incorporates an annotated bibliography pointing to more than 40 topics in a new [47m"BIB"[0m package. EMACS Support A set of tools for assisting in the conversion of certain HTML to [47m[xdoc][0m may be found, without much documentation, in [47memacs/html-to-xdoc.el[0m. [See DARPA Note above.] When new [ACL2-doc] buffers are created by using the [47mG[0m or [47mShift-<Return>[0m commands, their name reflects the topic name, e.g., [47macl2-doc<REWRITE>[0m if the topic visited in the new buffer is [47mREWRITE[0m. Note that the new buffer name stays the same even if other topics are visited there; its name reflects its topic at the time it was created. Thanks to Warren Hunt for requesting such an enhancement. Note that the former behavior can be restored by evaluating the form [47m(setq *acl2-doc-short-new-buffer-names* t)[0m in Emacs. The initialization file for recent Emacs versions, [47mbooks/emacs/emacs-acl2.el[0m, now correctly loads related files --- notably [47macl2-doc.el[0m --- from that same directory, rather than from the [47memacs/[0m directory that is directly under the top level of the ACL2 distribution. [Documentation] printed to the terminal or in the [ACL2-Doc] Emacs browser can respect certain [xdoc::markup] that was formerly ignored, but is no longer (by default), as follows. * Fonts are largely respected. For example, text marked as underline is now underlined, and text marked as having typewriter font now has a grey background. This closes GitHub Issue 1487. Thanks to Grant Jurgensen for helpful feedback on the original plan, which had been to use delimiting underscores rather than Select Graphic Rendition (SGR) control sequences. See [xdoc::terminal] for details and for ways to customize behavior, including avoidance of SGR. * Images now appear in [ACL2-Doc] (but not with [47m:[0m[47mdoc[0m at the terminal), instead of [47m{IMAGE}[0m, on systems that can display graphics inside Emacs. Thanks to Warren Hunt for requesting this enhancement. The documentation for [ACL2-Doc] says of the search commands [47ms[0m and [47mS[0m, ``go to that topic with the cursor put immediately after the found text''. But the cursor was at the end of the found text, not immediately after it. That has been fixed. For the [ACL2-doc] browser, the download ([47mD[0m) command now accesses, by default, an [47mhttps[0m address instead of an [47mhttp[0m address. Thanks to Warren Hunt for suggesting this change. In [ACL2-doc], modified the [47mTAB[0m and [47mShift-TAB[0m (sometimes known as [47m<backtab>[0m) commands so that they alert the user when wrapping. Experimental Versions The note ``Note: No checkpoints to print.'' that might be printed on proof failure is now the same in ACL2(p) as in ACL2, unless [waterfall-parallelism] is enabled (in which case ``no checkpoints'' is followed by `` from gag-mode'' as before).") (note-8-7 (release-notes) "ACL2 Version 8.7 (xxx, 20xx) Notes NOTE! New users can ignore these release notes, because the [documentation] has been updated to reflect all changes that are recorded here. Below we roughly organize the changes to ACL2 since Version 8.6 into the following categories of changes: existing features, new features, heuristic and efficiency improvements, bug fixes, changes at the system level, Emacs support, and experimental versions. Each change is described in just one category, though of course many changes could be placed in more than one category. Note that only ACL2 system changes are listed below. See also note-8-7-books for a summary of changes made to the ACL2 Community Books since ACL2 8.6, including the build system. Changes to Existing Features The output generated by the induction routine has been slightly changed. Now, if term [47mt0[0m suggested the induction scheme but other terms, [47mt1[0m, ... [47mtk[0m, either suggested the same scheme or schemes that merged with [47mt0[0m's to create the selected scheme, the induction output includes the sentence ``[47mWe will induct according to a scheme suggested by t0, while accommodating t1, ..., tk[0m''. The terms mentioned are all preferentially expanded by the simplifier when they arise in the subgoals produced by that induction. The fact that the terms are preferentially expanded is not new. What's new is that ACL2 now lists all the accommodated terms. When the [summary] prints ``Modified system attachments'', it now sorts that information before printing it. Improved the error message when the package name is missing immediately after `#!', as in #!(foo). It was the case that in an [event] [47m(add-macro-alias mac fn)[0m, [47m(add-macro-fn mac fn)[0m, or [47m(add-binop mac fn)[0m, if [47mfn[0m was a macro name then this event generally had no effect. Now, if in addition an event [47m(add-macro-alias fn fn2)[0m has first been admitted (and no later such event has been admitted), then in these three events, [47mfn[0m will be treated as [47mfn2[0m. See [add-macro-alias]. Thanks to Grant Jurgensen for sending an example that showed how a confusing [47m[in-theory][0m error could occur before this change, in the situation described above: after the change, [47m(in-theory (disable mac))[0m is treated as a directive to [disable] [47mfn2[0m; but before the change it was treated as an attempt to [disable] the macro, [47mfn[0m, which caused an error. The utility [47m:[0m[47m[trans*][0m new uses the [47m:TERM[0m [evisc-tuple] (see [set-evisc-tuple]) to print terms, as was already being done by [47m:[0m[47m[trans][0m. The behavior and documentation for [47m[read-file-into-string][0m have been cleaned up and put in sync. Thanks to Eric Smith and Grant Jurgensen for communication that led to these improvements. New Features The new function symbol [47mstrict-table-guard[0m returns its single argument unchanged, but has a special meaning when a [table]'s [47m:guard[0m is a call of that function symbol. In that case, a term supplied for updating the table --- that is, for the [47m:put[0m and [47m:clear[0m operations --- must have no free variables, even though variables [47mWORLD[0m and [47mENS[0m are normally permitted. See [table]. A new feature provides ways to stop certain infinite loops in the waterfall. It is now possible to specify a limit on how many times the waterfall can produce a new subgoal along a branch. It is also possible to specify that the prover should check for ``simple'' loops in the waterfall. The default setting for this new feature limits the branch length to 1000 and enables checking for duplicate goals. See [47m[set-subgoal-loop-limits][0m for details. Thanks to Eric Smith for suggesting that we consider supporting loop detection at the goal level. A new feature provides help in debugging failed proofs involving functional instantiation. In particular, it helps you answer the question ``where did this subgoal come from?'' when looking at a subgoal produced by functionally instantiating a constraint. See [47m[set-constraint-tracking][0m. Heuristic and Efficiency Improvements Applications that use functions with floating-point inputs or outputs (see [df]) may generate less memory usage, at least in SBCL releases strictly after SBCL Version 2.9 and SBCL github versions after mid-October, 2024. Thanks to Stas Boukarev for enhancing SBCL to support this improvement (made by adding suitable proclaiming in ACL2). Avoided a potential quadratic blowup in [guard] generation by improving how guard obligations are simplified. Specifically, improved the simplification of ground subterms so that [47m(if x y y)[0m can simplify to [47my[0m; other uses in ACL2 of ground subterm simplification similarly benefit. Thanks to Eric Smith for sending the following example, which now generates a simpler guard proof obligation. (defun foo (x y) (declare (xargs :guard t)) (let ((x (+ 1 x))) (case x (1 (natp x)) (2 (consp x)) (3 (rationalp x)) (otherwise (+ x y))))) Sped up [47m[include-book][0m by significantly reducing time in translating calls of [47m[with-output][0m and some other macros (for some technical details see ACL2 source function [47mmacroexpand1*-cmp[0m) and in creatiion of the so-called post-alist in a [certificate] (for relevant code, which shows the use of [fast-alists], see ACL2 source function [47maccumulate-post-alist[0m). For examples showing reduction by about 1/3 in include-book time, see the comment ``Here are sample time reports (...) for include-book speedups due to...'' in the form [47m(defxdoc note-8-7 ...)[0m in [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m. Thanks to Eric Smith for sending an example book for which to speed up [47m[include-book][0m. When a function, constant, or macro was defined within an [47m[encapsulate][0m form, its definition was evaluated in Lisp with each pass of evaluating the [47mencapsulate[0m form, and similarly for the definition of its executable-counterpart (see [evaluation]). For CCL and SBCL, that implies that such function definitions were compiled with each pass. Now, with a few exceptions, these definitions are saved in the first pass of evaluating the [47mencapsulate[0m form and retrieved, rather than re-evaluated, in the second pass. The exceptions include the following. * No definition is stored or retrieved that is within the scope of an [47mencapsulate[0m form with a non-empty list of [signature]s. * No definition of the executable-counterpart of a function symbol is retrieved when that symbol has a non-redundant [logic]-mode definition in the scope of [47m[local][0m that was evaluated within the first pass of the same [47mencapsulate[0m. * No [local] definition is stored that is within two or more nested [47mencapsulate[0m events. Thanks to Eric Smith for asking if a function defined within an encapsulate can be expected to be compiled twice, once for each pass of the encapsulate. Implementation-level details are explained in the section entitled ``Appendix 2: Extension for Encapsulate'' in the ACL2 source code comment, ``Essay on Hash Table Support for Compilation''. In particular, the end of that Essay discusses an enhancement that saves compiled code for redundant [47mdefun[0ms. Bug Fixes Fixed a soundness bug in the [proof-builder] that could cause goals from [47m[force][0md hypotheses to be created incorrectly. (This bug has been around for at least 10 years and probably for 30 years!) Fixed a soundness bug based on the use of [47m[swap-stobjs][0m on two [stobj]s of which one is ``live''. See [live-stobj-in-proof]. Thanks to Sol Swords for reporting this bug, including an example and analysis of possible fixes in his report. (Technical Note. We have added code to check for live [stobj]s in proofs, which was sufficient to fix the bug. But the situation described above is caught by a change to [47mswap-stobjs[0m, which now signals an error in the relevant case (exactly one live stobj input).) Fixed a soundness bug due to the interaction of [stobj]s and [47m[defattach][0m. The fundamental problem was that [47mdefattach[0m events can cause a stobj recognizer to become false; see [community-book] [47mbooks/system/tests/stobj-attach-unsoundness.lisp[0m. The solution is to disallow attachments for certain supporters of stobj primitives; see [stobj-attachment-restrictions]. Thanks to Sol Swords for reporting the bug, analyzing it quite thoroughly, contributing the book mentioned above, modifying other books as necessary, and providing preliminary code to fix the bug, and for helpful conversations. A Lisp error is now avoided when saving event-data (see [saving-event-data] and submitting certain ill-formed attempts at [events]. Thanks to Eric Smith for sending the following example. (assign event-data-fal 'event-data-fal) (defuns foo (x) x) Fixed a bug in the interaction of [47m[memoize-partial][0m with utilities [47m[save-and-clear-memoization-settings][0m and [47m[restore-memoization-settings][0m. The latter utilities no longer have an effect on functions created by [47m[memoize-partial][0m (or, and this is quite obscure, on memoization from calls of [47m[memoize][0m with a non-[47mnil[0m value of the keyword, [47m:total[0m). An attachable stobj (see [attach-stobj]) was created by the executable ([47m:EXEC[0m) function associated with its stobj creator (see [defabsstobj]), even when that stobj was given an attachment. This bug has been fixed: the stobj is now created by the [47m:EXEC[0m of the attachment's creator. Fixed a bug in [47m[trans*][0m when its use encounters a call of [47m[make-event][0m with the [47m:on-behalf-of[0m keyword. Thanks to Grant Jurgensen for reporting this bug using a simple example. According to the documentation for [47m[table][0m, the variable [47mENS[0m is allowed in both the key and value expressions when updating the table, that is, using the [47m:put[0m and [47m:clear[0m operations. However, [47mENS[0m was not being allowed in the key expression. That has been fixed. (SBCL only) Fixed a bug, for ACL2 hosted on SBCL, that was preventing inlining of functions whose name ends in [47m"$INLINE"[0m, such as those generated by [47m[defun-inline][0m. Thanks to Grant Jurgensen for reporting this bug with a helpful example. A [47m[defabsstobj][0m event contains [3mfunction specs[0m that are each either a symbol or a list of the form [47m(fn :kwd1 val1 ... :kwdn valn)[0m. Each [47mvali[0m must be a symbol, but when this was not the case, a raw Lisp error could occur. Now a clean error message is printed, and this requirement on the [47mvali[0m has been made explicit in the documentation for [47m[defabsstobj][0m. ACL2 rejected some valid [47m:type[0m fields in defstobj forms. This has been fixed; see [defstobj], where the ``Remark on [47mSATISFIES[0m'' has been extended to describe the requisite [guard] verification. Thanks to J. David Taylor for reporting this issue (as Issue 1852 in the ACL2 GitHub repository) and including the following examples that ACL2 rejected (but now accepts). (defstobj st (a :type (complex rational) :initially #c(0 1))) (defstobj st (a :type (string 1) :initially "a")) The following additional example from Issue 1852 is still rejected, because [47m[evenp][0m has a non-trivial [guard]; its argument must be an integer. (defstobj st (a :type (satisfies evenp) :initially 0)) However, the following variant produces a term, [47m(and (integerp x) (evenp x))[0m, that is trivially guard-verifiable, so it is accepted by ACL2 (but was not accepted before the bug fix). (defstobj st (a :type (and integer (satisfies evenp)) :initially 0)) Fixed a bug that was causing errors for [stobj]s introduced with [47m[defstobj][0m keyword argument [47m:non-executable t[0m in the presence of large arrays. This should not have caused an error, since that keyword argument prevents attempts at contructing the stobj (with its arrays). Fixed a bug in [47m:[0m[47m[pr][0m to work on function symbols introduced by [47m[defstobj][0m (GitHub Issue 1851). Thanks to David Taylor for reporting this bug. Fixed a [proof-builder] bug that could occasionally cause two goals to exist with the same name. The [47m:native[0m option of [47m[trace!][0m and [47m[trace$][0m did not work as one would reasonably expect when SBCL is the host Lisp; now it does. Some ill-formed hard errors, for example from calls of [47m[er][0m, caused raw Lisp errors. This has been fixed. Thanks to Eric Smith for reporting this bug with an example. [47mDO[0m [47m[Loop$][0m expressions (see [do-loop$]) are now allowed that have no [47mWITH[0m clauses. Formerly, an expression [47m(loop$ do ...)[0m caused an error with a rather nonsensical message. For a [47mDO[0m [47m[loop$][0m expression returning a [stobj] that participates in its measure, it was possible to get an inappropriate runtime measure error. (An example appears in a comment in the definition of [47m[do$][0m in the ACL2 sources.) This bug has been fixed by modifying the definition of [47m[do$][0m to respect singled-threadedness. A [47mDO[0m [47m[loop$][0m expression returning a [stobj] could cause a confusing error; see ACL2 source function [47mchk-for-live-stobj[0m for an example. This bug has been fixed so that no error occurs. ACL2 did an incomplete job of excluding certain forms from being evaluated in the top-level loop, including calls of [47m[swap-stobjs][0m, parallelism primitives ([47m[pand][0m, [47m[por][0m, [47m[pargs][0m, and [47m[plet][0m) when parallel evaluation is enabled (ACL2(p) only), and [47m[return-last][0m calls. For example, no error was signalled by the following, even though the two stobjs were not swapped (as shown below). (defstobj st1 (fld1)) (defstobj st2 (fld2) :congruent-to st1) (update-fld1 1 st1) (update-fld2 2 st2) (assert-event (and (equal (fld1 st1) 1) (equal (fld2 st2) 2))) ; The following is equivalent to (swap-stobjs st1 st2), and it ; now causes an error but it did not cause an error in Version 8.6: (mv-let (st1 st2) (swap-stobjs st1 st2) (mv st1 st2)) ; The following succeeds, showing that st1 and st2 were not actually swapped: (assert-event (and (equal (fld1 st1) 1) (equal (fld2 st2) 2))) This bug has been fixed. [Stobj] creators are once again disallowed in execution contexts (but are still allowed in theorems). This requirement was relaxed (perhaps inadvertently) in Version 8.5. The following example shows a problem with relaxing that restriction, as these events are accepted in Versions 8.5 and 8.6, but no longer. (defstobj st fld) ; Admitted in Versions 8.5 and 8.6, but no longer: (defun foo () (declare (xargs :guard t)) (create-st)) (update-fld 3 st) (assert-event (equal (fld st) 3)) ; Should not change global value of st: (foo) ; But (fld st) has indeed changed: (assert-event (equal (fld st) nil)) We fixed a low-level bug in [47m[include-book][0m, which we have only observed using ACL2 built on host Lisp SBCL with safety 3 (an optimization setting that causes more runtime checks at the cost of longer run times). (Technical note: The bug was in bogus type declarations in the definition of ACL2 source macro [47mwith-hcomp-bindings[0m.) Thanks to Jim White for reporting the bug. Changes at the System Level Modifications have been made that allow ACL2 to be hosted on GCL Version 2.7.0 and presumably later [gcl] versions; previously only GCL versions before 2.7.0 could host ACL2. Essentially the only user-visible change (other than error prevention) is the introduction of [47m[list$][0m, a macro equivalent to [47m[list][0m that can be used without a GCL 2.7.0 restriction on the number of arguments. The most sweeping implementation-level change is the replacement of an array in support of so-called [3mstatic honses[0m, the [3msbits array[0m, by a structure that avoids a reduced bound on array dimensions imposed by GCL 2.7.0. Details may be found in a Lisp comment in the form [47m(defxdoc note-8-7 ...)[0m in [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m. Thanks to Camm Maguire for his help with this project, including (but by no means limited to) his contribution of a new sbits implementation. The ACL2-only manual is no longer advertised on the ACL2 home page. The ACL2+Books manual is favored both because it does not have the broken links found in the ACL2-only manual and because the ACL2+Books manual is helpful for informing new users about the libraries provided by the [community-books]. Thanks to Eric Smith for encouraging this change. Note that the ACL2-only manual may continue to be built in directory [47mdoc/manual/[0m when certifying [47mbooks/system/doc/acl2-manual.lisp[0m. (Directory [47mdoc/manual/[0m is not to be confused with [47mbooks/doc/manual/[0m, where the ACL2+Books manual is built.) For the built-in [47m:[0m[47m[doc][0m command at the terminal: changed the top topic of that ``acl2-only'' manual from [47mACL2[0m to [47mTOP[0m. The structures of the documentation trees for that version of the manual and the usual ACL2+Books manual are now consistent. Thanks to Eric Smith for suggesting that those two manual structures be consistent. Replaced information about mailing lists in the [installation] instructions using a link to a corresponding, new documentation topic, [mailing-lists]. So now, the community can make suitable updates to that page. Thanks to Eric Smith for suggesting this change. The installation instructions have been moved into the manual; see [installation]. Thanks to Eric Smith for suggesting this change, which will allow the ACL2 community (specifically, the acl2-books community) to improve those instructions. By default, the directory where an ACL2 executable is to be built must not have a pathname that contains spaces, as before. However, now there is a `[47mmake[0m' variable, [47mACL2_ALLOW_SPACES_IN_DIRECTORIES[0m, that may be set to a non-empty value in order to build an ACL2 executable in such a directory, as noted in the error message. That message points out that there may be errors, however, when certifying books. Thanks to Eric Smith for a discussion leading to this change. References to the old ``bleeding edge'' manual ({https://www.cs.utexas.edu/users/moore/acl2/manuals/latest/' | https://www.cs.utexas.edu/users/moore/acl2/manuals/latest/}) have been replaced by references to the new one ({https://acl2.org/doc/ | https://acl2.org/doc/}). The documentation for [47m[do-loop$][0m has been extended to illustrate how to signal a soft error from within the body of a [47mDO[0m [47m[loop$][0m expression. EMACS Support Experimental Versions") (note1 (pointers) "See [note-1-1].") (note2 (pointers) "See [note-1-2].") (note3 (pointers) "See [note-1-3].") (note4 (pointers) "See [note-1-4].") (note5 (pointers) "See [note-1-5].") (note6 (pointers) "See [note-1-6].") (note7 (pointers) "See [note-1-7].") (note8 (pointers) "See [note-1-8].") (note8-update (pointers) "See [note-1-8-update].") (note9 (pointers) "See [note-1-9].") (nqthm-to-acl2 (acl2-tutorial) "ACL2 analogues of Nqthm functions and commands Example Forms: :nqthm-to-acl2 prove-lemma ; Display ACL2 topic(s) and/or print ; information corresponding to Nqthm ; PROVE-LEMMA command. (nqthm-to-acl2 'prove-lemma) ; Same as above. General Form: (nqthm-to-acl2 name) where [47mname[0m is a notion documented for Nqthm: either a function in the Nqthm logic, or a command. If there is corresponding information available for ACL2, it will be printed in response to this command. This information is not intended to be completely precise, but rather, is intended to help those familiar with Nqthm to make the transition to ACL2. We close with two tables that contain all the information used by this [47mnqthm-to-acl2[0m command. The first shows the correspondence between functions in the Nqthm logic and corresponding ACL2 functions (when possible); the second is similar, but for commands rather than functions. Nqthm functions --> ACL2 ---------------------------------------- ADD1 --> 1+ ADD-TO-SET --> ADD-TO-SET-EQUAL and ADD-TO-SET-EQ AND --> AND APPEND --> APPEND and BINARY-APPEND APPLY-SUBR --> No correspondent, but see the documentation for DEFEVALUATOR and META. APPLY$ --> No correspondent, but see the documentation for DEFEVALUATOR and META. ASSOC --> ASSOC-EQUAL, ASSOC and ASSOC-EQ BODY --> No correspondent, but see the documentation for DEFEVALUATOR and META. CAR --> CAR CDR --> CDR CONS --> CONS COUNT --> ACL2-COUNT DIFFERENCE --> - EQUAL --> EQUAL, EQ, EQL and = EVAL$ --> No correspondent, but see the documentation for DEFEVALUATOR and META. FALSE --> Nqthm's F corresponds to the ACL2 symbol NIL. FALSEP --> NOT and NULL FORMALS --> No correspondent, but see the documentation for DEFEVALUATOR and META. GEQ --> >= GREATERP --> > IDENTITY --> IDENTITY IF --> IF IFF --> IFF IMPLIES --> IMPLIES LEQ --> <= LESSP --> < LISTP --> CONSP LITATOM --> SYMBOLP MAX --> MAX MEMBER --> MEMBER-EQUAL, MEMBER and MEMBER-EQ MINUS --> - and UNARY-- NEGATIVEP --> MINUSP NEGATIVE-GUTS --> ABS NLISTP --> ATOM NOT --> NOT NUMBERP --> ACL2-NUMBERP, INTEGERP and RATIONALP OR --> OR ORDINALP --> O-P ORD-LESSP --> O< PACK --> See intern and coerce. PAIRLIST --> PAIRLIS$ PLUS --> + and BINARY-+ QUOTIENT --> / REMAINDER --> REM and MOD STRIP-CARS --> STRIP-CARS SUB1 --> 1- TIMES --> * and BINARY-* TRUE --> The symbol T. UNION --> UNION-EQUAL and UNION-EQ UNPACK --> See symbol-name and coerce. V&C$ --> No correspondent, but see the documentation for DEFEVALUATOR and META. V&C-APPLY$ --> No correspondent, but see the documentation for DEFEVALUATOR and META. ZERO --> The number 0. ZEROP --> ZP Nqthm commands --> ACL2 ---------------------------------------- ACCUMULATED-PERSISTENCE --> ACCUMULATED-PERSISTENCE ADD-AXIOM --> DEFAXIOM ADD-SHELL --> There is no shell principle in ACL2. AXIOM --> DEFAXIOM BACKQUOTE-SETTING --> Backquote is supported in ACL2, but not currently documented. BOOT-STRAP --> GROUND-ZERO BREAK-LEMMA --> MONITOR BREAK-REWRITE --> BREAK-REWRITE CH --> PBT See also :DOC history. CHRONOLOGY --> PBT See also :DOC history. COMMENT --> DEFLABEL COMPILE-UNCOMPILED-DEFNS --> COMP CONSTRAIN --> See :DOC encapsulate and :DOC local. DATA-BASE --> Perhaps the closest ACL2 analogue of DATA-BASE is PROPS. But see :DOC history for a collection of commands for querying the ACL2 database (``world''). Note that the notions of supporters and dependents are not supported in ACL2. DCL --> DEFSTUB DEFN --> DEFUN and DEFMACRO DEFTHEORY --> DEFTHEORY DISABLE --> DISABLE DISABLE-THEORY --> See :DOC theories. The Nqthm command (DISABLE-THEORY FOO) corresponds roughly to the ACL2 command (in-theory (set-difference-theories (current-theory :here) (theory 'foo))). DO-EVENTS --> LD DO-FILE --> LD ELIM --> ELIM ENABLE --> ENABLE ENABLE-THEORY --> See :DOC theories. The Nqthm command (ENABLE-THEORY FOO) corresponds roughly to the ACL2 command (in-theory (union-theories (theory 'foo) (current-theory :here))). EVENTS-SINCE --> PBT FUNCTIONALLY-INSTANTIATE --> ACL2 provides a form of the :USE hint that corresponds roughly to the FUNCTIONALLY-INSTANTIATE event of Nqthm. See :DOC lemma-instance. GENERALIZE --> GENERALIZE HINTS --> HINTS LEMMA --> DEFTHM MAINTAIN-REWRITE-PATH --> BRR MAKE-LIB --> There is no direct analogue of Nqthm's notion of ``library.'' See :DOC books for a description of ACL2's mechanism for creating and saving collections of events. META --> META NAMES --> NAME NOTE-LIB --> INCLUDE-BOOK PPE --> PE PROVE --> THM PROVEALL --> See :DOC ld and :DOC certify-book. The latter corresponds to Nqthm's PROVE-FILE,which may be what you're interested in,really. PROVE-FILE --> CERTIFY-BOOK PROVE-FILE-OUT --> CERTIFY-BOOK PROVE-LEMMA --> DEFTHM See also :DOC hints. R-LOOP --> The top-level ACL2 loop is an evaluation loop as well, so no analogue of R-LOOP is necessary. REWRITE --> REWRITE RULE-CLASSES --> RULE-CLASSES SET-STATUS --> IN-THEORY SKIM-FILE --> LD-SKIP-PROOFSP TOGGLE --> IN-THEORY TOGGLE-DEFINED-FUNCTIONS --> EXECUTABLE-COUNTERPART-THEORY TRANSLATE --> TRANS and TRANS1 UBT --> UBT and U UNBREAK-LEMMA --> UNMONITOR UNDO-BACK-THROUGH --> UBT UNDO-NAME --> See :DOC ubt. There is no way to undo names in ACL2 without undoing back through such names. However, see :DOC ld-skip-proofsp for information about how to quickly recover the state.") (nth (lists acl2-built-ins) "The nth element (zero-based) of a list [47m(Nth n l)[0m is the [47mn[0mth element of [47ml[0m, zero-based. If [47mn[0m is greater than or equal to the length of [47ml[0m, then [47mnth[0m returns [47mnil[0m. [47m(Nth n l)[0m has a [guard] that [47mn[0m is a non-negative integer and [47ml[0m is a [47m[true-listp][0m. [47mNth[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<nth> (defun nth (n l) (declare (xargs :guard (and (integerp n) (>= n 0) (true-listp l)))) (if (endp l) nil (if (zp n) (car l) (nth (- n 1) (cdr l))))) Subtopics [Eighth] Eighth member of the list [Fifth] Fifth member of the list [First] First member of the list [Fourth] Fourth member of the list [Ninth] Ninth member of the list [Nth-aliases-table] A [table] used to associate names for nth/update-nth printing [Rest] Rest ([47m[cdr][0m) of the list [Second] Second member of the list [Seventh] Seventh member of the list [Sixth] Sixth member of the list [Tenth] Tenth member of the list [Third] Third member of the list") (nth-aliases-table (stobj nth update-nth) "A [table] used to associate names for nth/update-nth printing Example: (table nth-aliases-table 'st0 'st) This example associates the symbol [47mst0[0m with the symbol [47mst[0m. As a result, when the theorem prover prints terms of the form [47m(nth n st0)[0m or [47m(update-nth n val st0)[0m, where [47mst[0m is a [stobj] whose [47mn[0mth accessor function is [47mf-n[0m, then it will print [47mn[0m as [47m*f-n*[0m. General Form: (table nth-aliases-table 'alias-name 'name) This event causes [47malias-name[0m to be treated like [47mname[0m for purposes of the printing of terms that are calls of [47mnth[0m and [47mupdate-nth[0m. (Note however that [47mname[0m is not recursively looked up in this table.) Both must be symbols other than [47m[state][0m. See [term], in particular the discussion there of untranslated terms. For a convenient way to add entries to this [table], see [add-nth-alias]. To remove entries from the [table] with ease, see [remove-nth-alias]. Subtopics [Add-nth-alias] Associate one symbol with another for printing of [47m[nth][0m/[47m[update-nth][0m terms [Remove-nth-alias] Remove a symbol alias for printing of [47m[nth][0m/[47m[update-nth][0m terms") (nthcdr (lists acl2-built-ins) "Final segment of a list [47m(Nthcdr n l)[0m removes the first [47mn[0m elements from the list [47ml[0m. The following is a theorem. (implies (and (integerp n) (<= 0 n) (true-listp l)) (equal (length (nthcdr n l)) (if (<= n (length l)) (- (length l) n) 0))) For related functions, see [take] and see [butlast]. The [guard] of [47m(nthcdr n l)[0m requires that [47mn[0m is a nonnegative integer and [47ml[0m is a true list. [47mNthcdr[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<nthcdr> (defun nthcdr (n l) (declare (xargs :guard (and (integerp n) (<= 0 n) (true-listp l)))) (if (zp n) l (nthcdr (+ n -1) (cdr l))))") (null (basics acl2-built-ins) "Recognizer for the empty list [47mNull[0m is the function that checks whether its argument is [47mnil[0m. For recursive definitions it is often preferable to test for the end of a list using [47m[endp][0m instead of [47mnull[0m; see [endp]. [47mNull[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<null> (defun null (x) (declare (xargs :guard t)) (eq x nil))") (number-subtrees (hons-and-memoization acl2-built-ins) "[47m(number-subtrees x)[0m returns the number of distinct subtrees of X, in the sense of [47m[equal][0m In the logic, [47mnumber-subtrees[0m is defined as the length of [47m[cons-subtrees][0m. Under the hood, we first [47m[hons-copy][0m X to obtain a normed version, then count the number of unique conses in X using an EQ hash table. [31;1mFunction: [0m<number-subtrees> (defun number-subtrees (x) (declare (xargs :guard t)) (len (cons-subtrees x 'number-subtrees)))") (numbers (programming) "Numbers in ACL2 and operations on them See [numbers-introduction] for introductory background. See [arithmetic] for libraries of [books] for arithmetic reasoning. Subtopics [*] Multiplication macro [+] Addition macro [-] Macro for subtraction and negation [/] Macro for division and reciprocal [/=] Test inequality of two numbers [1+] Increment by 1 [1-] Decrement by 1 [<] Less-than [<=] Less-than-or-equal test [=] Test equality of two numbers [>] Greater-than test [>=] Greater-than-or-equal test [Abs] The absolute value of a real number [ACL2-number-listp] Recognizer for a true list of numbers [ACL2-numberp] Recognizer for numbers [Allocate-fixnum-range] Set aside fixnums in GCL [Ash] Arithmetic shift operation [Bitp] A recognizer for the set of bits, {0,1} [Boole$] Perform a bit-wise logical operation on 2 two's complement integers [Ceiling] Division returning an integer by truncating toward positive infinity [Char-code] The numeric code for a given character [Code-char] The character corresponding to a given numeric code [Complex] Create an ACL2 number [Complex-rationalp] Recognizes complex rational numbers [Complex/complex-rationalp] Recognizer for complex numbers [Conjugate] Complex number conjugate [Denominator] Divisor of a ratio in lowest terms [Df] Support for floating-point operations [Evenp] Test whether an integer is even [Explode-nonnegative-integer] The list of [characters] in the radix-r form of a number [Expt] Exponential function [Fix] Coerce to a number [Floor] Division returning an integer by truncating toward negative infinity [Ifix] Coerce to an integer [Imagpart] Imaginary part of a complex number [Int=] Test equality of two integers [Integer-length] Number of bits in two's complement integer representation [Integer-listp] Recognizer for a true list of integers [Integer-range-p] Recognizer for integers between two bounds. [Integerp] Recognizer for whole numbers [Logand] Bitwise logical `and' of zero or more integers [Logandc1] Bitwise logical `and' of two ints, complementing the first [Logandc2] Bitwise logical `and' of two ints, complementing the second [Logbitp] The [47mi[0mth bit of an integer [Logcount] Number of ``on'' bits in a two's complement number [Logeqv] Bitwise logical equivalence of zero or more integers [Logior] Bitwise logical inclusive or of zero or more integers [Lognand] Bitwise logical `nand' of two integers [Lognor] Bitwise logical `nor' of two integers [Lognot] Bitwise not of a two's complement number [Logorc1] Bitwise logical inclusive or of two ints, complementing the first [Logorc2] Bitwise logical inclusive or of two ints, complementing the second [Logtest] Test if two integers share a `1' bit [Logxor] Bitwise logical exclusive or of zero or more integers [Max] The larger of two numbers [Min] The smaller of two numbers [Minusp] Test whether a number is negative [Mod] Remainder using [47m[floor][0m [Mod-expt] Exponential function [Nat-listp] Recognizer for a true list of natural numbers [Natp] A recognizer for the natural numbers [Nfix] Coerce to a natural number [Nonnegative-integer-quotient] Natural number division function [Numbers-introduction] Numbers in ACL2 [Numerator] Dividend of a ratio in lowest terms [Oddp] Test whether an integer is odd [Plusp] Test whether a number is positive [Pos-listp] Recognizer for a true list of positive integers [Posp] A recognizer for the positive integers [Random$] Obtain a random value [Rational-listp] Recognizer for a true list of rational numbers [Rationalp] Recognizer for rational numbers (ratios and integers) [Real/rationalp] Recognizer for rational numbers (including real number in ACL2(r)) [Realfix] Coerce to a real number [Realpart] Real part of a complex number [Rem] Remainder using [47m[truncate][0m [Rfix] Coerce to a rational number [Round] Division returning an integer by rounding off [Sharp-d-reader] Read a rational number as a representable rational (see [df]) [Sharp-f-reader] Read a rational number in floating-point syntax [Sharp-u-reader] Allow underscore characters in numbers [Signed-byte-p] Recognizer for signed integers that fit in a specified bit width [Signum] Indicator for positive, negative, or zero [The-number] Coerce an expected number to a number [Truncate] Division returning an integer by truncating toward 0 [Unary--] Arithmetic negation function [Unary-/] Reciprocal function [Unsigned-byte-p] Recognizer for natural numbers that fit in a specified bit width [Zero-test-idioms] How to test for 0 [Zerop] Test an acl2-number against 0 [Zip] Testing an ``integer'' against 0 [Zp] Testing a ``natural'' against 0 [Zpf] Testing a nonnegative fixnum against 0") (numbers-introduction (numbers) "Numbers in ACL2 ACL2 numbers are precisely represented and unbounded. They can be partitioned into the following subtypes: ACL2 Numbers | |- Rationals | | | |- Integers | | |- Positive integers 3 | | |- Zero 0 | | |- Negative Integers -3 | | | |- Non-Integral Rationals | | | | | |- Positive Non-Integral Rationals 19/3 | | |- Negative Non-Integral Rationals -22/7 | |- Complex Rational Numbers #c(3 5/2) ; i.e., 3 + (5/2)i Signed integer constants are usually written (as illustrated above) as sequences of decimal digits, possibly preceded by [47m+[0m or [47m-[0m. Decimal points are not allowed. Integers may be written in binary, as in [47m#b1011[0m (= 23) and [47m#b-111[0m (= -7). Octal may also be used, [47m#o-777[0m = -511. Non-integral rationals are written as a signed decimal integer and an unsigned decimal integer, separated by a slash. Complex rationals are written as #c(rpart ipart) where rpart and ipart are rationals. Of course, 4/2 = 2/1 = 2 (i.e., not every rational written with a slash is a non-integer). Similarly, #c(4/2 0) = #c(2 0) = 2. The common arithmetic functions and relations are denoted by [47m+[0m, [47m-[0m, [47m*[0m, [47m/[0m, [47m=[0m, [47m<[0m, [47m<=[0m, [47m>[0m and [47m>=[0m. However there are many others, e.g., [47mfloor[0m, [47mceiling[0m, and [47mlognot[0m. See any Common Lisp language documentation. The primitive predicates for recognizing numbers are illustrated below. The following ACL2 function will classify an object, x, according to its numeric subtype, or else return 'NaN (not a number). We show it this way just to illustrate programming in ACL2. (defun classify-number (x) (cond ((rationalp x) (cond ((integerp x) (cond ((< 0 x) 'positive-integer) ((= 0 x) 'zero) (t 'negative-integer))) ((< 0 x) 'positive-non-integral-rational) (t 'negative-non-integral-rational))) ((complex-rationalp x) 'complex-rational) (t 'NaN)))") (numbers_in_acl2 (pages_written_especially_for_the_tours) "Numbers in ACL2 ACL2 numbers are precisely represented and unbounded. They can be partitioned into the following subtypes: ACL2 Numbers | |- Rationals | | | |- Integers | | |- Positive integers 3 | | |- Zero 0 | | |- Negative Integers -3 | | | |- Non-Integral Rationals | | | | | |- Positive Non-Integral Rationals 19/3 | | |- Negative Non-Integral Rationals -22/7 | |- Complex Rational Numbers #c(3 5/2) ; i.e., 3 + (5/2)i Signed integer constants are usually written (as illustrated above) as sequences of decimal digits, possibly preceded by [47m+[0m or [47m-[0m. Decimal points are not allowed. Integers may be written in binary, as in [47m#b1011[0m (= 23) and [47m#b-111[0m (= -7). Octal may also be used, [47m#o-777[0m = -511. Non-integral rationals are written as a signed decimal integer and an unsigned decimal integer, separated by a slash. Complex rationals are written as #c(rpart ipart) where rpart and ipart are rationals. Of course, 4/2 = 2/1 = 2 (i.e., not every rational written with a slash is a non-integer). Similarly, #c(4/2 0) = #c(2 0) = 2. The common arithmetic functions and relations are denoted by [47m+[0m, [47m-[0m, [47m*[0m, [47m/[0m, [47m=[0m, [47m<[0m, [47m<=[0m, [47m>[0m and [47m>=[0m. However there are many others, e.g., [47mfloor[0m, [47mceiling[0m, and [47mlognot[0m. See any Common Lisp language documentation. The primitive predicates for recognizing numbers are illustrated below. The following ACL2 function will classify an object, x, according to its numeric subtype, or else return 'NaN (not a number). We show it this way just to illustrate programming in ACL2. (defun classify-number (x) (cond ((rationalp x) (cond ((integerp x) (cond ((< 0 x) 'positive-integer) ((= 0 x) 'zero) (t 'negative-integer))) ((< 0 x) 'positive-non-integral-rational) (t 'negative-non-integral-rational))) ((complex-rationalp x) 'complex-rational) (t 'NaN)))") (numerator (numbers acl2-built-ins) "Dividend of a ratio in lowest terms Completion Axiom ([47mcompletion-of-numerator[0m): (equal (numerator x) (if (rationalp x) (numerator x) 0)) [Guard] for [47m(numerator x)[0m: (rationalp x)") (nvariablep (pointers) "See [system-utilities].") (o-finp (ordinals acl2-built-ins) "Recognizes if an ordinal is finite We introduce the function [47mo-finp[0m which returns [47mt[0m for any ordinal that is finite, else [47mnil[0m. This function is equivalent to the function [47m[atom][0m, and is introduced so that we can [47m[disable][0m its definition when dealing with ordinals (also see [make-ord]). [31;1mFunction: [0m<o-finp> (defun o-finp (x) (declare (xargs :guard t)) (atom x))") (o-first-coeff (ordinals acl2-built-ins) "Returns the first coefficient of an ordinal An ACL2 ordinal is either a natural number or, for an infinite ordinal, a list whose elements are exponent-coefficient pairs (see [o-p]). In the latter case, this function returns the [47m[cdr][0m of the first pair in the list. In the case of a natural number, this function returns the ordinal itself (since a natural number, n, can be thought of as (w^0)n). For the corresponding exponent, see [o-first-expt]. [31;1mFunction: [0m<o-first-coeff> (defun o-first-coeff (x) (declare (xargs :guard (or (o-finp x) (consp (car x))))) (if (o-finp x) x (cdar x)))") (o-first-expt (ordinals acl2-built-ins) "The first exponent of an ordinal An ACL2 ordinal is either a natural number or, for an infinite ordinal, a list whose elements are exponent-coefficient pairs (see [o-p]). In the latter case, this function returns the [47m[car][0m of the first pair in the list. In the case of a natural number, the value returned is 0 (since a natural number, [47mn[0m, can be thought of as (w^0)n). For the corresponding coefficient, see [o-first-coeff]. [31;1mFunction: [0m<o-first-expt> (defun o-first-expt (x) (declare (xargs :guard (or (o-finp x) (consp (car x))))) (if (o-finp x) 0 (caar x)))") (o-infp (ordinals acl2-built-ins) "Recognizes if an ordinal is infinite [47mO-infp[0m is a macro. [47m(O-infp x)[0m opens up to [47m(not (o-finp x))[0m.") (o-p (ordinals acl2-built-ins) "A recognizer for the ordinals up to epsilon-0 Using the nonnegative integers and lists we can represent the ordinals up to [47mepsilon-0[0m. The ordinal representation used in ACL2 has changed as of Version_2.8 from that of Nqthm-1992, courtesy of Pete Manolios and Daron Vroon; additional discussion may be found in ``Ordinal Arithmetic in ACL2'', {proceedings of ACL2 Workshop 2003 | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}. Previously, ACL2's notion of ordinal was very similar to the development given in ``New Version of the Consistency Proof for Elementary Number Theory'' in The Collected Papers of Gerhard Gentzen, ed. M.E. Szabo, North-Holland Publishing Company, Amsterdam, 1969, pp 132-213. The following essay is intended to provide intuition about ordinals. The truth, of course, lies simply in the ACL2 definitions of [47mo-p[0m and [47m[o<][0m. Very intuitively, think of each non-zero natural number as by being denoted by a series of the appropriate number of strokes, i.e., 0 0 1 | 2 || 3 ||| 4 |||| ... ... Then ``[47momega[0m,'' here written as [47mw[0m, is the ordinal that might be written as w |||||..., i.e., an infinite number of strokes. Addition here is just concatenation. Observe that adding one to the front of [47mw[0m in the picture above produces [47mw[0m again, which gives rise to a standard definition of [47mw[0m: [47mw[0m is the least ordinal such that adding another stroke at the beginning does not change the ordinal. We denote by [47mw+w[0m or [47mw*2[0m the ``[47mdoubly infinite[0m'' sequence that we might write as follows. w*2 |||||... |||||... One way to think of [47mw*2[0m is that it is obtained by replacing each stroke in [47m2[0m [47m(||)[0m by [47mw[0m. Thus, one can imagine [47mw*3[0m, [47mw*4[0m, etc., which leads ultimately to the idea of ``[47mw*w[0m,'' the ordinal obtained by replacing each stroke in [47mw[0m by [47mw[0m. This is also written as ``[47momega[0m squared'' or [47mw^2[0m, or: 2 w |||||... |||||... |||||... |||||... |||||... ... We can analogously construct [47mw^3[0m by replacing each stroke in [47mw[0m by [47mw^2[0m (which, it turns out, is the same as replacing each stroke in [47mw^2[0m by [47mw[0m). That is, we can construct [47mw^3[0m as [47mw[0m copies of [47mw^2[0m, 3 2 2 2 2 w w ... w ... w ... w ... ... Then we can construct [47mw^4[0m as [47mw[0m copies of [47mw^3[0m, [47mw^5[0m as [47mw[0m copies of [47mw^4[0m, etc., ultimately suggesting [47mw^w[0m. We can then stack [47momega[0ms, i.e., [47m(w^w)^w[0m etc. Consider the ``limit'' of all of those stacks, which we might display as follows. . . . w w w w w That is epsilon-0. Below we begin listing some ordinals up to [47mepsilon-0[0m; the reader can fill in the gaps at his or her leisure. We show in the left column the conventional notation, using [47mw[0m as ``[47momega[0m,'' and in the right column the ACL2 object representing the corresponding ordinal. ordinal ACL2 representation 0 0 1 1 2 2 3 3 ... ... w '((1 . 1) . 0) w+1 '((1 . 1) . 1) w+2 '((1 . 1) . 2) ... ... w*2 '((1 . 2) . 0) (w*2)+1 '((1 . 2) . 1) ... ... w*3 '((1 . 3) . 0) (w*3)+1 '((1 . 3) . 1) ... ... 2 w '((2 . 1) . 0) ... ... 2 w +w*4+3 '((2 . 1) (1 . 4) . 3) ... ... 3 w '((3 . 1) . 0) ... ... w w '((((1 . 1) . 0) . 1) . 0) ... ... w 99 w +w +w4+3 '((((1 . 1) . 0) . 1) (99 . 1) (1 . 4) . 3) ... ... 2 w w '((((2 . 1) . 0) . 1) . 0) ... ... w w w '((((((1 . 1) . 0) . 1) . 0) . 1) . 0) ... ... Observe that the sequence of [47mo-p[0ms starts with the natural numbers (which are recognized by [47m[natp][0m). This is convenient because it means that if a term, such as a measure expression for justifying a recursive function (see [o<]) must produce an [47mo-p[0m, it suffices for it to produce a natural number. The ordinals listed above are listed in ascending order. This is the ordering tested by [47m[o<][0m. The ``[47mepsilon-0[0m ordinals'' of ACL2 are recognized by the recursively defined function [47mo-p[0m. The base case of the recursion tells us that natural numbers are [47mepsilon-0[0m ordinals. Otherwise, an [47mepsilon-0[0m ordinal is a list of [47m[cons][0m pairs whose final [47m[cdr][0m is a natural number, [47m((a1 . x1) (a2 . x2) ... (an . xn) . p)[0m. This corresponds to the ordinal [47m(w^a1)x1 + (w^a2)x2 + ... + (w^an)xn + p[0m. Each [47mai[0m is an ordinal in the ACL2 representation that is not equal to 0. The sequence of the [47mai[0m's is strictly decreasing (as defined by [47m[o<][0m). Each [47mxi[0m is a positive integer (as recognized by [47m[posp][0m). Note that infinite ordinals should generally be created using the ordinal constructor, [47m[make-ord][0m, rather than [47m[cons][0m. The functions [47m[o-first-expt][0m, [47m[o-first-coeff][0m, and [47m[o-rst][0m are ordinals destructors. Finally, the function [47m[o-finp][0m and the macro [47m[o-infp][0m tell whether an ordinal is finite or infinite, respectively. The function [47m[o<][0m compares two [47mepsilon-0[0m ordinals, [47mx[0m and [47my[0m. If both are integers, [47m(o< x y)[0m is just [47mx<y[0m. If one is an integer and the other is a [47m[cons][0m, the integer is the smaller. Otherwise, [47m[o<][0m recursively compares the [47m[o-first-expt][0ms of the ordinals to determine which is smaller. If they are the same, the [47m[o-first-coeff][0ms of the ordinals are compared. If they are equal, the [47m[o-rst][0ms of the ordinals are recursively compared. Fundamental to ACL2 is the fact that [47m[o<][0m is well-founded on [47mepsilon-0[0m ordinals. That is, there is no ``infinitely descending chain'' of such ordinals. See [proof-of-well-foundedness]. [31;1mFunction: [0m<o-p> (defun o-p (x) (declare (xargs :guard t)) (if (o-finp x) (natp x) (and (consp (car x)) (o-p (o-first-expt x)) (not (eql 0 (o-first-expt x))) (posp (o-first-coeff x)) (o-p (o-rst x)) (o< (o-first-expt (o-rst x)) (o-first-expt x)))))") (o-rst (ordinals acl2-built-ins) "Returns the rest of an infinite ordinal An ACL2 infinite ordinal is a list whose elements are exponent-coefficient pairs (see [o-p] and see [o-infp]). The first exponent and first coefficient of an ordinal can be obtained by using [47m[o-first-expt][0m and [47m[o-first-coeff][0m respectively. To obtain the rest of the ordinal (for recursive analysis), use the [47mo-rst[0m function. It returns the rest of the ordinal after the first exponent and coefficient are removed. [31;1mFunction: [0m<o-rst> (defun o-rst (x) (declare (xargs :guard (consp x))) (cdr x))") (o< (ordinals acl2-built-ins) "The well-founded less-than relation on ordinals up to [47mepsilon-0[0m If [47mx[0m and [47my[0m are both [47mo-p[0ms (see [o-p]) then [47m(o< x y)[0m is true iff [47mx[0m is strictly less than [47my[0m. [47mo<[0m is well-founded on the [47m[o-p][0ms. When [47mx[0m and [47my[0m are both nonnegative integers, [47mo<[0m is just the familiar ``less than'' relation ([47m[<][0m). [47mo<[0m plays a key role in the formal underpinnings of the ACL2 logic. In order for a recursive definition to be admissible it must be proved to ``terminate.'' By terminate we mean that the arguments to the function ``get smaller'' as the function recurs and this sense of size comparison must be such that there is no ``infinitely descending'' sequence of ever smaller arguments. That is, the relation used to compare successive arguments must be well-founded on the domain being measured. The most basic way ACL2 provides to prove termination requires the user to supply (perhaps implicitly) a mapping of the argument tuples into the ordinals with some ``measure'' expression in such a way that the measures of the successive argument tuples produced by recursion decrease according to the relation [47mo<[0m. The validity of this method rests on the well-foundedness of [47mo<[0m on the [47m[o-p][0ms. Without loss of generality, suppose the definition in question introduces the function [47mf[0m, with one formal parameter [47mx[0m (which might be a list of objects). Then we require that there exist a measure expression, [47m(m x)[0m, that always produces an [47m[o-p][0m. Furthermore, consider any recursive call, [47m(f (d x))[0m, in the body of the definition. Let [47mhyps[0m be the conjunction of terms, each of which is either the test of an [47m[if][0m in the body or else the negation of such a test, describing the path through the body to the recursive call in question. Then it must be a theorem that (IMPLIES hyps (O< (m (d x)) (m x))). When we say [47mo<[0m is ``well-founded'' on the [47m[o-p][0ms we mean that there is no infinite sequence of [47m[o-p][0ms such that each is smaller than its predecessor in the sequence. Thus, the theorems that must be proved about [47mf[0m when it is introduced establish that it cannot recur forever because each time a recursive call is taken [47m(m x)[0m gets smaller. From this, and the syntactic restrictions on definitions, it can be shown (as on page 44 in ``A Computational Logic'', Boyer and Moore, Academic Press, 1979) that there exists a function satisfying the definition; intuitively, the value assigned to any given [47mx[0m by the alleged function is that computed by a sufficiently large machine. Hence, the logic is consistent if the axiom defining [47mf[0m is added. See [o-p] for a discussion of the ordinals and how to compare two ordinals. The definitional principle permits the use of relations other than [47mo<[0m but they must first be proved to be well-founded on some domain. See [well-founded-relation-rule]. Roughly put, alternative relations are shown well-founded by providing an order-preserving mapping from their domain into the ordinals. See [defun] for details on how to specify which well-founded relation is to be used. [31;1mFunction: [0m<o<> (defun o< (x y) (declare (xargs :guard (and (o<g x) (o<g y)))) (cond ((o-finp x) (or (o-infp y) (< x y))) ((o-finp y) nil) ((not (equal (o-first-expt x) (o-first-expt y))) (o< (o-first-expt x) (o-first-expt y))) ((not (= (o-first-coeff x) (o-first-coeff y))) (< (o-first-coeff x) (o-first-coeff y))) (t (o< (o-rst x) (o-rst y)))))") (o<= (ordinals acl2-built-ins) "The less-than-or-equal relation for the ordinals [47mo<=[0m is a macro and [47m(o<= x y)[0m expands to [47m(not (o< y x))[0m. See [o<].") (o> (ordinals acl2-built-ins) "The greater-than relation for the ordinals [47mO>[0m is a macro and [47m(o> x y)[0m expands to [47m(o< y x)[0m. See [o<].") (o>= (ordinals acl2-built-ins) "The greater-than-or-equal relation for the ordinals [47mO>=[0m is a macro and [47m(o>= x y)[0m expands to [47m(not (o< x y))[0m. See [o<].") (obdd (bdd) "Ordered binary decision diagrams with rewriting See [bdd] for information on this topic.") (observation (io acl2-built-ins) "Print an observation Here is a typical application of [47mobservation[0m. ACL2 !>(let ((ctx 'top-level) (name 'foo)) (observation ctx "Skipping processing of name ~x0." name)) ACL2 Observation in TOP-LEVEL: Skipping processing of name FOO. <state> ACL2 !> [47mObservation[0m prints an initial ``[47mACL2 Observation...: [0m'', and then prints the indicated message using formatted printing (see [fmt]). Notice in the example above that evaluation of a call of [47mobservation[0m returns [47m[state][0m. Indeed, [47mobservation[0m is actually a macro whose expansion takes and returns the ACL2 [47m[state][0m. A similar utility, [47mobservation-cw[0m, is available that does not take or return [47mstate[0m; rather, it returns [47mnil[0m as the suffix ``[47mcw[0m'' suggests that a ``comment window'' is the target of this printing, rather than the state. For example: ACL2 !>(let ((ctx 'top-level) (name 'foo)) (observation-cw ctx "Skipping processing of name ~x0." name)) ACL2 Observation in TOP-LEVEL: Skipping processing of name FOO. NIL ACL2 !> [47mObservation-cw[0m takes exactly the same arguments as [47mobservation[0m, but [47mobservation-cw[0m does its printing in a so-called ``wormhole''; see [wormhole]. General Forms: (observation ctx fmt-string fmt-arg1 fmt-arg2 ... fmt-argk) (observation-cw ctx fmt-string fmt-arg1 fmt-arg2 ... fmt-argk) where [47mctx[0m generally evaluates to a symbol (but see below), and [47mfmt-string[0m together with the [47mfmt-argi[0m are suitable for passing to [47m[fmt][0m. Output begins and ends with a newline. Recall from the example above that the output from a call of [47mobservation[0m (or [47mobservation-cw[0m) begins with ``[47mACL2 Observation[0m'' and additional characters ending in ``[47m: [0m'', for example ``[47m in TOP-LEVEL: [0m'', followed by formatted output produced from [47mfmt-string[0m with the given [47mfmt-argi[0m. The characters printed immediately following the string ``[47mACL2 Observation[0m'' depend on the value of [47mctx[0m. If [47mctx[0m is [47mnil[0m, nothing is printed. If [47mctx[0m is a non-[47mnil[0m symbol, it is printed using [47m[fmt][0m directive [47m~x[0m. If [47mctx[0m is a [47m[cons][0m pair whose [47m[car][0m is a symbol, formatted printing is applied to the string "(~x0 ~x1 ...)", where [47m#\0[0m and [47m#\1[0m are bound respectively to that car and cdr. Otherwise, [47mctx[0m is printed using [47m[fmt][0m directive [47m~@[0m. We next discuss situations in which printing is inhibited for [47mobservation[0m and [47mobservation-cw[0m. No printing is done when [47mobservation[0m is among the inhibited output types; see [set-inhibit-output-lst]. Moreover, no printing is done by [47mobservation[0m during [47m[include-book][0m. If you want to avoid printing from [47mobservation-cw[0m during [47m[include-book][0m, then you need to manage that yourself.") (observation-cw (pointers) "See [observation].") (obtaining-common-lisp (installation) "Obtaining Common Lisp A requirement for installing ACL2 is to install a suitable Common Lisp implementation. ACL2 can be hosted by several Common Lisp implementations, as listed alphabetically below. The most commonly-used of these are SBCL and CCL, which can be obtained without charge. Regardless of which Common Lisp you choose, it is highly recommended that you install a 64-bit implementation. While 32-bit Lisps are supported by the core ACL2 system, using a 32-bit Lisp may result in reduced performance as well as certification failures for certain [community-books]. If you are unsure whether your installed Common Lisp is 64-bit or not, try running the following: ;; If you are in an ACL2 REPL, first do :q to exit to Common Lisp. ;; Evaluates to t if in a 64-bit Lisp. (>= most-positive-fixnum (1- (expt 2 60))) Allegro Common Lisp {Allegro Common Lisp | https://franz.com/} is a commercial implementation. It has been maintained for many years, but it generally runs ACL2 more slowly than most other implementations, and there are other issues; see [allegro-cl]. Clozure Common Lisp (CCL) {CCL | https://ccl.clozure.com/} is available without charge. See [ccl-installation] for instructions on how to fetch and install CCL. Quoting the {CCL website | https://ccl.clozure.com/}: Clozure CL (often called CCL for short) is a free Common Lisp implementation with a long history. Some distinguishing features of the implementation include fast compilation speed, native threads, a precise, generational, compacting garbage collector, and a convenient foreign-function interface. As of this writing (July 2025), CCL does not run natively on Arm-based Macs. There is an effort in progress to remedy that. CMU Common Lisp (CMUCL) {CMUCL | https://cmucl.org} is available without charge. Follow the {Download | https://cmucl.org/download.html} link on {the CMUCL website | https://cmucl.org} to obtain CMUCL. It has been maintained for many years, but it generally runs ACL2 more slowly than most other implementations. At the time of writing (July, 2025), CMUCL does not offer a 64-bit version. GNU Common Lisp (GCL) {GCL | https://www.gnu.org/software/gcl/} is available without charge. You can {download a binary Debian package for ACL2 | https://tracker.debian.org/pkg/acl2}. Thanks to Camm Maguire for maintaining this package. Note however that it may take some time after each ACL2 release for this package to be updated for that release. Otherwise, it should be easy to obtain and build GCL yourself. Note that ACL2 requires ANSI GCL version 2.6.12 or later. See {[47mhttps://www.gnu.org/software/gcl/[0m | https://www.gnu.org/software/gcl/} for instructions. If you encounter difficulties, see [gcl] and perhaps consider the following instructions for obtaining an older version and then building the executable [47mgcl/gcl/bin/gcl[0m. git clone git://git.sv.gnu.org/gcl.git cd gcl/gcl git checkout Version_2_6_13pre ./configure --enable-ansi && make LispWorks {LispWorks | https://www.lispworks.com/} is a commercial implementation. You may ask the vendor for an evaluation license for the full product if you are considering purchasing a license. Steel Bank Common Lisp (SBCL) {SBCL | https://sbcl.org/} is available without charge. See [sbcl-installation-brief] for instructions on how to fetch and install SBCL. [31;1mImportant[0m: For maximum performance, build from source using the options indicated in [sbcl-installation] when building with [47mmake.sh[0m. Subtopics [Allegro-cl] Allegro Common Lisp as a host for ACL2 [Ccl-installation] Installing Clozure Common Lisp (CCL) [Sbcl-installation] Installing Steel Bank Common Lisp (SBCL) [Sbcl-installation-brief] Installing Steel Bank Common Lisp (SBCL)") (oddp (numbers acl2-built-ins) "Test whether an integer is odd [47m(oddp x)[0m is true if and only if [47mx[0m is odd, i.e., not even in the sense of [47m[evenp][0m. The [guard] for [47moddp[0m requires its argument to be an integer. [47mOddp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<oddp> (defun oddp (x) (declare (xargs :guard (integerp x))) (not (evenp x)))") (odds (lists acl2-built-ins) "The odd-indexed members of a list The call [47m(odds x)[0m returns the restriction of the true-list [47mx[0m to its odd-indexed members (with zero-based indexing). Note that if [47mx[0m is a list [47m(k1 a1 k2 a2 ... kn an)[0m that satisfies the predicate [47m[keyword-value-listp][0m, then [47m(odds x)[0m lists the values [47mai[0m of [47mx[0m. [31;1mFunction: [0m<odds> (defun odds (l) (declare (xargs :guard (true-listp l))) (evens (cdr l)))") (ok-if (break-rewrite) "Conditional exit from [47mbreak-rewrite[0m Recall that one way to exit from a [break-rewrite] interactive break is to type the command [47m:ok[0m. See [brr-commands]. The [47m:ok[0m command exits silently, without printing the result of attempting to apply the rule that caused the break. The [47m:ok-if[0m command takes a term as an argument and is like [47m:ok[0m but exits only if the term evaluates to non-[47mnil[0m. Example Form: :ok-if (null (brr@ :wonp)) General Form: :ok-if expr where [47mexpr[0m is a term involving no free variables other than [47mstate[0m and returning one non-[47mstate[0m result which is treated as Boolean. This form is intended to be executed from within [47mbreak-rewrite[0m (see [break-rewrite]). Consider first the simple situation that the [47m(ok-if term)[0m is a command read by [47mbreak-rewrite[0m. Then, if the term is non-[47mnil[0m, [47mbreak-rewrite[0m exits and otherwise it does not. More generally, [47mok-if[0m returns an ACL2 error triple [47m(mv erp val state)[0m. (See [ld] or see [programming-with-state] for more on error triples.) If any form being evaluated as a command by [47mbreak-rewrite[0m returns the triple returned by [47m(ok-if term)[0m then the effect of that form is to exit [break-rewrite] if term is non-[47mnil[0m. Thus, one might define a function or macro that returns the value of [47mok-if[0m expressions on all outputs and thus create a convenient new way to exit [47mbreak-rewrite[0m. The exit test, [47mterm[0m, generally uses [47mbrr@[0m to access context sensitive information about the attempted rule application. See [brr@]. [47mOk-if[0m is useful inside of command sequences produced by break conditions. See [monitor]. [47m:ok-if[0m is most useful after an [47m:eval[0m command has caused [47mbreak-rewrite[0m to try to apply the rule because in the resulting break environment [47mexpr[0m can access such things as whether the rule succeeded, if so, what term it produced, and if not, why. There is no need to use [47m:ok-if[0m before [47m:eval[0ming the rule since the same effects could be achieved with the break condition on the rule itself. Perhaps we should replace this concept with [47m:eval-and-break-if[0m? Time will tell.") (old-and-new-event-data (pointers) "See [saving-event-data].") (on_the_naming_of_subgoals (pages_written_especially_for_the_tours) "On the Naming of Subgoals [47mSubgoal *1/2[0m is the [31;1minduction step[0m from the scheme, obtained by instantiating the scheme with our conjecture. We number the cases ``backward'', so this is case ``2'' of the proof of ``*1''. We number them backward so you can look at a subgoal number and get an estimate for how close you are to the end.") (oops (history) "Undo a [47m:u[0m or [47m:[0m[47m[ubt][0m The keyword [command] [47m:oops[0m will undo the most recent [47m:[0m[47m[ubt][0m (or [47m:u[0m, which we here consider just another [47m:[0m[47m[ubt][0m). A second [47m:oops[0m will undo the next most recent [47m:[0m[47m[ubt][0m, a third will undo the [47m:[0m[47m[ubt][0m before that one, and a fourth [47m:oops[0m will return the logical [world] to its configuration before the first [47m:oops[0m. Consider the logical world (see [world]) that represents the current extension of the logic and ACL2's rules for dealing with it. The [47m:[0m[47m[ubt][0m and [47m:u[0m [command]s ``roll back'' to some previous [world] (see [ubt]). Sometimes these [command]s are used to inadvertently undo useful work and user's wish they could ``undo the last undo.'' That is the function provided by [47m:oops[0m. [47m:Oops[0m is best described in terms of an implementation. Imagine a ring of four [world]s and a marker ([47m*[0m) indicating the current ACL2 [world]: * w0 / \ w3 w1 \ / w2 This is called the ``kill ring'' and it is maintained as follows. When you execute an event the current [world] is extended and the kill ring is not otherwise affected. When you execute [47m:[0m[47m[ubt][0m or [47m:u[0m, the current [world] marker is moved one step counterclockwise and that [world] in the ring is replaced by the result, say [47mw0'[0m, of the [47m:[0m[47m[ubt][0m or [47m:u[0m. w0 / \ *w0' w1 \ / w2 If you were to execute [events] at this point, [47mw0'[0m would be extended and no other changes would occur in the kill ring. When you execute [47m:oops[0m, the marker is moved one step clockwise. Thus the kill ring becomes * w0 / \ w0' w1 \ / w2 and the current ACL2 [world] is [47mw0[0m once again. That is, [47m:oops[0m ``undoes'' the [47m:[0m[47m[ubt][0m that produced [47mw0'[0m from [47mw0[0m. Similarly, a second [47m:oops[0m will move the marker to [47mw1[0m, undoing the undo that produced [47mw0[0m from [47mw1[0m. A third [47m:oops[0m makes [47mw2[0m the current [world]. Note however that a fourth [47m:oops[0m restores us to the configuration previously displayed above in which [47mw0'[0m has the marker. In general, the kill ring contains the current [world] and the three most recent [world]s in which a [47m:[0m[47m[ubt][0m or [47m:u[0m were done. While [47m:[0m[47m[ubt][0m may appear to discard the information in the [events] undone, we can see that the [world] in which the [47m:[0m[47m[ubt][0m occurred is still available. No information has been lost about that [world]. But [47m:[0m[47m[ubt][0m does discard information! [47m:[0m[47m[Ubt][0m discards the information necessary to recover from the third most recent [47m[ubt][0m! An [47m:oops[0m, on the other hand, discards no information, it just selects the next available [world] on the kill ring and doing enough [47m:oops[0mes will return you to your starting point. We can put this another way. You can freely type [47m:oops[0m and inspect the [world] that you thus obtain with [47m:[0m[47m[pe][0m, [47m:[0m[47m[pc][0m, and other [history] [command]s. You can repeat this as often as you wish without risking the permanent loss of any information. But you must be more careful typing [47m:[0m[47m[ubt][0m or [47m:u[0m. While [47m:oops[0m makes [47m:[0m[47m[ubt][0m seem ``safe'' because the most recent [47m:[0m[47m[ubt][0m can always be undone, information is lost when you execute [47m:[0m[47m[ubt][0m. We note that [47m:ubt[0m and [47m:u[0m may remove compiled definitions (but note that in some Lisps, including CCL (OpenMCL) and SBCL, functions are always compiled). When the original world is restored using [47m:oops[0m, restored functions will not generally be compiled (except for Lisps as above), though the user can remedy this situation; see [comp]. Finally, we note that our implementation of [47moops[0m can use a significant amount of memory, because of the saving of old logical [world]s. Most users are unlikely to experience a memory problem, but if you do, then you may want to disable [47moops[0m by evaluating [47m(reset-kill-ring 0 state)[0m; see [reset-kill-ring].") (open-input-channel (pointers) "See [io].") (open-input-channel-p (pointers) "See [io].") (open-output-channel (pointers) "See [io].") (open-output-channel! (io acl2-built-ins) "When trust tags are needed to open output channels Use this function in place of [47mopen-output-channel[0m if you want to open a channel for output at times this would otherwise be prohibited, for example during [47m[make-event][0m expansion and [47m[clause-processor][0m [hints]. If this functionality doesn't quite seem like what you need, take a look at the definition of [47mopen-output-channel![0m in axioms.lisp, specifically the binding of [47m[state][0m global variable [47mwrites-okp[0m. The following example, taken from (no longer available) community book [47mbooks/hons-archive/hons-archive.lisp[0m, illustrates the latter approach. (defmacro har-zip! (x filename &key sortp) "See :doc hons-archive" `(mv-let (erp val state) (progn! :state-global-bindings ((temp-touchable-vars t set-temp-touchable-vars)) (state-global-let* ((writes-okp t)) (let ((state (har-zip-fn ,x ,filename ,sortp state))) (mv nil nil state)))) (declare (ignore erp val)) state)) The book below illustrates the soundness loophole plugged in ACL2 Version_3.2 related to file writes during book certification. ; The following example is adapted (with only very slight changes) ; from one written by Peter Dillinger. It illustrates the prohibition ; against writing files enforced by with-output-channel during book ; certification (more specifically, during make-event expansion). ; This book certifies in ACL2 Version_3.1 before the fix discussed in the ; paragraph about it being ``possible to write files during book ; certification'' in :DOC NOTE-3-2. The fix was actually made to ACL2 ; function open-output-channel. ; After the fix, in order for certification to succeed one needs to do ; two things. First, in raw lisp: ; (push :after-writes-okp-fix *features*) ; Second, certify with this command: ; (certify-book "writes-okp" 0 nil :ttags (:writes-okp)) (in-package "ACL2") (local (defun write-objects-to-channel (obj-lst chan state) (declare (xargs :mode :program :stobjs state :guard (true-listp obj-lst))) (if (consp obj-lst) (pprogn (print-object$ (car obj-lst) chan state) (write-objects-to-channel (cdr obj-lst) chan state) state) state))) #+after-writes-okp-fix (defttag :writes-okp) (local (defun write-objects-to-file (obj-lst filename state) (declare (xargs :mode :program :stobjs state :guard (and (stringp filename) (true-listp obj-lst)))) (mv-let (chan state) #-after-writes-okp-fix (open-output-channel filename :object state) #+after-writes-okp-fix (open-output-channel! filename :object state) (if chan (pprogn (write-objects-to-channel obj-lst chan state) (close-output-channel chan state) (value :done)) (er soft 'write-object-to-file "Could not open for writing: ~x0" filename))))) (local (defconst *nil.lisp* '((in-package "ACL2") (defthm bad nil :rule-classes nil)))) (local (defconst *nil.cert* '((IN-PACKAGE "ACL2") "ACL2 Version 3.1" :BEGIN-PORTCULLIS-CMDS :END-PORTCULLIS-CMDS NIL (("/home/peterd/test/nil.lisp" "nil" "nil" ((:SKIPPED-PROOFSP) (:AXIOMSP) (:TTAGS)) . 134094174)) 62589544 ))) (local (make-event (er-progn (write-objects-to-file *nil.lisp* "nil.lisp" state) (write-objects-to-file *nil.cert* "nil.cert" state) (value '(value-triple :invisible))))) (local (include-book "nil" :load-compiled-file nil)) (defthm bad nil :rule-classes nil)") (open-output-channel-p (pointers) "See [io].") (open-trace-file (trace) "Redirect trace output to a file Example: (open-trace-file "foo") ; trace output will go to file foo General Form: (open-trace-file filename) ; trace output will go to file filename Output from [47m[trace$][0m normally goes to the screen, i.e., [47m[standard-co][0m. But it can be redirected to a file as shown above. See [close-trace-file] for how to send trace output back to the screen. [47mOpen-trace-file[0m does not work as would reasonably be expected during [47m[make-event][0m expansion. Use [47m[open-trace-file!][0m instead within [47mmake-event[0m.") (operational-semantics (documentation acl2 about-acl2) "Modeling State Machines ``[3mThe meaning of a program is defined by its effect on the state vector[0m'' --- John McCarthy, Towards a Mathematical Science of Computation (1962). Users of ACL2 (see [bib::kmm00a] and [bib::kmm00b]) and its predecessor, Nqthm (see [bib::bm97]), have long modeled state machines and verified interesting properties of programs running on those machines. The basic idea is to represent the state of the machine (including its programs) by an ACL2 object and then define an interpreter that computes a ``final'' state from an initial state. In this documentation topic we fill out that sketch of the methodology without being specific about any particular machine. We then dive into details in subsidiary topics. Request for Suggestions from ACL2 Users If you have ideas for additions or other improvements to the documentation of the ACL2 approach to operational semantics, please add suitable documentation or simply send your comments to the ACL2 developers. Note that we have intentionally limited our literature survey to models and proof methods in ACL2 and Nqthm. Widening the focus to operational semantics in general is simply beyond the scope of this documentation topic. But if you see omissions or errors in our discussion of ACL2 or Nqthm models and proof methods, please either fix them or bring them to our attention, making your suggestions as detailed as possible, e.g., what documentation topic are you looking at and precisely how would you change it? If your change involves citing a paper or Nqthm or ACL2 file that we have left out, please include the appropriate bibliographic information as well as a URL to the paper or file if possible. The following documentation topics are of concern: Recommended Order of Topics * operational-semantics (the current topic) * [operational-semantics-1__simple-example] * [operational-semantics-2__other-examples] * [operational-semantics-3__annotated-bibliography] * [operational-semantics-4__how-to-find-things] * [operational-semantics-5__history-etc] Prerequisites You won't be able to prove theorems about ACL2 functions interpreting another language unless you can prove theorems about ACL2 functions. An excellent way to test yourself is to think of a program you'd like to verify in that other programming language. Code a function in ACL2 that computes the same answer using the same algorithm, as nearly as possible in an applicative setting. So for example, if your program destructively modifies an array in that other programming language, perhaps model the array in ACL2 as a list but access elements with [47m[nth][0m and ``modify'' elements with [47m[update-nth][0m. Then prove that the ACL2 function is correct with ACL2. If you can do that, you're ready to try to embed that other language (or some fragment of it) in ACL2 and reason about such programs with ACL2. Generic Description of the Methodology How Machines Are Modeled In the approach ACL2 users most often take to model state machines the first step is to represent the relevant parts of the machine's state as an ACL2 object. Then the user defines a single-step (or ``small step'') function to compute the next state from the current one (and possibly some inputs). Finally, the user defines a recursive function that iterates the single-step transition from a given initial state a given number of times or until some halting condition is detected in the state. That function is often called the ``run'' function and is our operational semantic model. See [operational-semantics-1__simple-example] for a model of an extremely simple machine, the way we configure ACL2 to prove things about it, some example proofs and other uses of the model. The argument that controls the maximum number of steps taken is often called a ``clock'' but it has nothing to do with the passage of time. In some models the clock is just a natural number. In others it may be a finite list of inputs to be successively transferred into the state on each cycle. In any case, the clock guarantees that the run function terminates, which is a prerequisite for functions defined recursively in ACL2. But do not be fooled into thinking that all programs running on the machine always terminate. By appropriate use of quantification one can often prove that a given program never terminates or only terminates under certain pre-conditions. This is discussed further in [operational-semantics-1__simple-example]. Uses of Such a Model Such a model can be used as a prototype for the machine: the model can be executed on concrete states for testing purposes. But because ACL2 is a formal system, it is also possible to do symbolic simulation of the model and to prove theorems involving the model. Such theorems might be loosely classified as being ``about'' a particular program running on the machine or ``about'' the machine itself. An example of the first might be that a certain program for the machine computes the factorial function. An example of the second might be that when the machine is run [47m(+ i j)[0m steps from state [47ms0[0m the result is the same as running it [47mi[0m steps from state [47ms0[0m to get some state, [47msi[0m, and then running it [47mj[0m steps from [47msi[0m. Such theorems are sometimes called ``sequential execution'' or ``semi-colon'' theorems because they allow a long run to be broken up into a composition of shorter runs. One can even prove theorems relating one such model to another. But from the logical perspective there is no practical distinction between these ``kinds'' of theorems: they are just ordinary theorems about ACL2 functions. Proving Theorems about A Model To facilitate such proofs it is common to develop a book of rewrite (and other kinds of) rules that do such things as normalize compositions of functions used in the construction of states and clock expressions. The basic idea is to control the expansions of the step and run functions to contain case explosions that would otherwise occur. E.g., we usually configure the ACL2 database so that * the step function only expands on a state when it is possible to determine what the ``next instruction'' is, rather than considering all possible cases, * when the clock is constant (or, more precisely, when it is possible to determine the explicit number of steps the clock will allow) the run function is eliminated by expanding it to a composition of steps, and * when the clock is given by a composition of functions, as in (+ 4 (loop-clk x y z)), a sequential composition rule is used to break it into a composition of runs. Such a configuration of ACL2 generally makes it possible to prove certain styles of theorems by following a well-understood methodology. For example, to express a conjecture about the final state produced by a program on the machine, one might write an implication whose hypothesis characterizes an acceptable initial state and whose conclusion is an equality whose left-hand side is a call of run on that state and a clock expression that measures exactly how many steps it will take to reach the halt state or return, and whose right-hand side is the symbolic expression of the correct final state. The two states just mentioned and the clock expression are usually terms involving variables denoting values found in relevant locations in the initial state. A very strong total correctness theorem for a factorial program might be something like ``if a natural number, [47mn[0m, is found in the memory location used for the program's input, and the state is run [47m(clk n)[0m steps, then the halt flag is set in the resulting state, and [47m(fact n)[0m, aka, [3mn![0m, is found in the memory location used for the program's return value --- and the program counter is set to the correct next instruction and no other part of the state has changed.'' Alternatively, the theorem might only express some post-condition of the final state. The examples in [operational-semantics-1__simple-example] will make this clearer. The methodology for proving such theorems is demonstrated there too. The clock term, [47m(clk n)[0m above, is a constructive expression of an existential quantifier meaning ``there exists a clock that drives the machine from the given initial state to the given final state.'' It is also sometimes possible to prove that no such clock exists. There are tools that can, for simple programs, generate appropriate clock terms. Of course, the problem is undecidable. Proofs of such theorems are most often done by induction, appealing to similar lemmas about the effects of loops and subroutine calls. But proofs using inductive assertions and other mathematical techniques can be used. The methodology described above generally limits the human to creative contributions (like identifying invariants being maintained) and relegates to ACL2 the tedious unwinding of possibly long chains of symbolic computation. The previously mentioned documentation topic, [operational-semantics-1__simple-example], carries out this entire program for a simple machine, explicates the methodology, and uses it to prove a variety of theorems. Following this approach, users of Nqthm and ACL2 have modeled and verified properties of many interesting machines. More precise references to the work mentioned below as well as models and proofs about other machines --- and other kinds of properties, like absence of deadlock --- may be found in [operational-semantics-2__other-examples]. Advice After you are familiar with how to use ACL2 and have studied some of the models described here, you are ready to try to develop your own models. We offer three pieces of advice. * Start small, e.g., model half a dozen routine instructions and master the methodology so that you can ``automatically'' prove things about simple programs. Be sure that your proofs don't rely on the small size of the model; in particular, don't repeatedly enumerate all possible instructions. Then add one new feature to the model and elaborate the methodology. You will often find there are multiple ways to represent the state and state changes. By starting small you will be able to iterate more quickly to find the best way to formalize new features and cope with the resulting complexity. * Consider the necessity of introducing multiple layers of abstraction. For example your most realistic model might have finite bounds on all resources, but it might be worth your while to ``duplicate'' the model with unbounded resources but with meters that record the maximal extent of the resources used. Then prove a theorem relating the two models. * As usual with ACL2, think carefully about how the prover will use the lemmas you prove. They are not just expressing mathematical relations but are used operationally to transform the formulas being proved. Overview of the Remaining Topics on Operational Semantics Our discussion of the details of operational semantics in ACL2 is structured as follows. * [operational-semantics-1__simple-example] --- carries out the generic methodology to formalize and prove theorems about a very simple machine, called M1. M1 is a toy Java Virtual Machine (JVM) supporting just stack-based arithmetic and branch instructions. We highly recommend this section, though users already familiar with this style of model may wish just to skim it. * [operational-semantics-2__other-examples] --- briefly summarizes some other examples of operational models with citations to the relevant source documents. The topic has several goals. One is to show how we can handle programming features omitted from M1, e.g., subroutine call and return, data types, threads, monitors, etc. A second goal is to demonstrate that the methodology allows really large complex models, like of the JVM or the x86, that can be executed in ACL2 to emulate the machine in question and as the basis of formal proofs about the machine. A third goal is to point out alternative ACL2 proof styles and tools that may be of use while trying to prove theorems about state machines. * [operational-semantics-3__annotated-bibliography] --- is just what it says: an annotated bibliography. The annotations you see in this bibliography are akin simply to keywords. But if you select a given citation you'll generally see a discussion of how the work fits into the scheme of things. This section is an alternative way to browse through Nqthm and ACL2 examples of state machines, proofs, proof styles, and tools. * [operational-semantics-4__how-to-find-things] --- the various topics on operational semantics cite papers and files that are not part of the ACL2 documentation; for example, in these topics you might see utterances such as ``Nqthm source file [47mprove.lisp[0m'', ``ACL2 source file [47mrewrite.lisp[0m'', ``Nqthm proof script [47mexamples/hunt/fm8501.lisp[0m'' and ``ACL2 directory [47mbooks/models/jvm/m1/[0m''; this brief topic explains how to dereference these utterances. * [operational-semantics-5__history-etc] --- a discussion of early work in the 1970s and 1980s by members of the Boyer-Moore community to model state machines, and how that work influenced the evolution of Nqthm and ACL2. Subtopics [Operational-semantics-1__simple-example] M1: definition, rules, clocks, proofs [Operational-semantics-2__other-examples] Examples of other models and proof techniques [Operational-semantics-3__annotated-bibliography] Annotated bibliography for operational-semantics [Operational-semantics-4__how-to-find-things] Citation conventions for doc operational-semantics [Operational-semantics-5__history-etc] A quick history of our style of modeling state machines") (operational-semantics-1__simple-example (operational-semantics) "M1: definition, rules, clocks, proofs Organization of This Topic As a hypertext document, this topic is ``flat,'' not structured as a tree of subtopics. We implemented it this way to make it easier to search. * Introduction * Setting up a Symbol Package * The Definition of M1 * Programming M1 * ``Teaching'' the Prover How to Control M1 * Arithmetic * Resolving ``Reads'' and ``Writes'' * Keeping ``Abstractions'' Abstract * Controlling Case Explosion due to Step * Clock Expressions * Expanding [47mm1[0m * Playing with Program *pi*: Execution, Symbolic Execution, and Proof of Correctness * The Clock for Factorial * Computing with M1 * Symbolic Execution of M1 Code * Proving Theorems about M1 Programs * Step 0: The Specification * Step 1: The Semantic Function * Step 2: Relate the Semantic Function to the Code * Step 3: Relate the Semantic Function to the Specification * Step 4: Total Correctness * More M1 Programs and Proofs * More Elaborate Models of the JVM: From M1 to M6 Introduction In this topic we explain, by example, the most common way to formalize a computing machine in ACL2 and then reason about it. The machine we have in mind will be called ``M1'' and is a ``toy'' version of the Java Virtual Machine or ``JVM.'' More precisely, it is a simple stack machine having a fixed number of registers, hereafter called ``local variables,'' and an execute-only program memory. There will only be eight instructions. We will then write and verify a factorial program for it and mention many more M1 programs that have been verified --- and which we urge you to solve as practice problems. Despite its simplicity, M1 is equivalent to a Turing machine and, in fact, that fact is among the theorems proved about M1. Full references are given when we survey the M1 results available. (Historical Aside: What we're calling M1 was called ``Small-Machine'' in Nqthm. See [bib::bm96] and the methodology described here was essentially fully developed before ACL2, Java, or the JVM came along.) M1 does not support bytecode verification, method invocation (procedure call) and return, data objects other than ACL2's unbounded numbers, threads, exceptions, and many other features of modern machines and languages. However, M1 is an excellent place to start when learning how to formalize a machine and to prove theorems about it. Furthermore, it is the starting place of a series of machine models in the JVM family that we explore more fully at the end of this documentation topic. Our discussion of this simple machine is quite long! The reason is that we're not trying just to explain the M1 model and how to prove correctness theorems about M1 programs; we're trying to explain how to create your own model, how to configure ACL2 to manipulate it, and how to phrase correctness conjectures so that ACL2 can prove them. We're using a simple machine as the vehicle. The ACL2 book defining M1 and all the necessary configuration lemmas, [47mmodels/jvm/m1/m1.lisp[0m, is less than 8K bytes, and the script for proving an M1 factorial program correct, [47mmodels/jvm/m1/fact.lisp[0m, is less than 6K bytes. If we strip out the comments, those two files combined are less than 8K bytes or about 5 pages. But this doc topic is about 64K bytes or about 35 pages. So don't despair. It takes longer to explain how to do it than to do it! You can find the definition of M1 and all of the work done with it on the ACL2 directory [47mbooks/models/jvm/m1[0m. It might be easiest to fire up your ACL2 system and do this. (include-book "models/jvm/m1/m1" :dir :system) (in-package "M1") Then, to see the definition of any symbol mentioned below you could just issue the [47m:[0m[47m[pe][0m command. For example, to see the definition of the function [47mexecute-ILOAD[0m, aka [47mexecute-iload[0m, you could type [47m:pe execute-iload[0m to the interactive prompt in your ACL2 session. This doc topic will not exhibit all the functions but will give examples of each ``kind'' of function involved in M1. Setting up a Symbol Package All of the functions defined to describe M1 are in a new symbol package named [47m"M1"[0m. This allows us to avoid name clashes with functions like [47mpop[0m, [47mprogram[0m, and [47mpc[0m that are predefined in the default [47m"ACL2"[0m symbol package. (defpkg "M1" (set-difference-eq (union-eq *acl2-exports* *common-lisp-symbols-from-main-lisp-package*) '(push pop pc program step nth update-nth nth-update-nth))) Note that we put all the usual ACL2 symbols and Common Lisp symbols in the new package, except for a few whose names clash with names we want to define for use in our model. See the ACL2 file [47mbooks/models/jvm/m1/m1.acl2[0m. The Definition of M1 See the ACL2 file [47mbooks/models/jvm/m1/m1.lisp[0m for all of the functions mentioned below. The [3mstate[0m, [47ms[0m, of M1 will be given by a list of four elements, accessed with the functions named below. * [47mpc[0m --- a natural number giving the position in [47m(program s)[0m of the next instruction * [47mlocals[0m --- a list containing the values, by position, of the local variables of the program * [47mstack[0m --- a list representing a stack of intermediate results, the [47mcar[0m being the topmost value * [47mprogram[0m --- a list of instructions (see below) States will be constructed with (defun make-state (pc locals stack program) (cons pc (cons locals (cons stack (cons program nil))))) Thus, [47m(make-state pc locals stack program)[0m is just [47m(list pc locals stack program)[0m. The state accessors just select the appropriate elements of a state, e.g., [47m(stack (make-state pc locals stack program))[0m is just [47mstack[0m. To ``abstractly'' treat a list as a stack we define (defun push (x y) (cons x y)) ; return a new stack with x on top of stack y (defun top (stack) (car stack)) ; return topmost element of stack (defun pop (stack) (cdr stack)) ; remove topmost element and return that stack To access and update the elements of a list by 0-based positions we define (defun nth (n list) (if (zp n) (car list) (nth (- n 1) (cdr list)))) (defun update-nth (n v list) (if (zp n) (cons v (cdr list)) (cons (car list) (update-nth (- n 1) v (cdr list))))) Thus, [47m(nth 3 '(10 20 30 40 50))[0m is [47m40[0m and [47m(update-nth 3 45 '(10 20 30 40 50))[0m is [47m(10 20 30 45 50)[0m. The eight M1 instructions are * [47m(ICONST i)[0m --- push [47mi[0m onto the stack and advance the pc by 1 * [47m(ILOAD i)[0m --- push the value of the [47mi[0mth local onto the stack and advance the pc by 1 * [47m(ISTORE i)[0m --- pop the topmost value from the stack, store it as the value of the [47mi[0mth local, and advance the pc by 1 * [47m(IADD)[0m --- pop the topmost value, [47mu[0m, and value just under it, [47mv[0m, from the stack, push [47m(+ v u)[0m onto the stack, and advance the pc by 1 * [47m(ISUB)[0m --- pop the topmost value, [47mu[0m, and value just under it, [47mv[0m, from the stack, push [47m(- v u)[0m onto the stack, and advance the pc by 1 * [47m(IMUL)[0m --- pop the topmost value, [47mu[0m, and value just under it, [47mv[0m, from the stack, push [47m(* v u)[0m onto the stack, and advance the pc by 1 * [47m(GOTO i)[0m --- advance the pc by [47mi[0m * [47m(IFEQ i)[0m --- pop the topmost value from the stack and if it is 0, then advance the pc by [47mi[0m and otherwise advance the pc by 1 In the case of both [47mGOTO[0m and [47mIFEQ[0m, the pc may be ``advanced'' by a negative amount. To access the components of an instruction we define (defun op-code (inst) (nth 0 inst)) ; return the op-code of instruction inst (defun arg1 (inst) (nth 1 inst)) ; return the operand of instruction inst For each instruction we define the function that takes the instruction and a state and returns the next state. For example, (defun execute-ICONST (inst s) (make-state (+ 1 (pc s)) (locals s) (push (arg1 inst) (stack s)) (program s))) (defun execute-ILOAD (inst s) (make-state (+ 1 (pc s)) (locals s) (push (nth (arg1 inst) (locals s)) (stack s)) (program s))) (defun execute-ISTORE (inst s) (make-state (+ 1 (pc s)) (update-nth (arg1 inst) (top (stack s)) (locals s)) (pop (stack s)) (program s))) (defun execute-IADD (inst s) (declare (ignore inst)) (make-state (+ 1 (pc s)) (locals s) (push (+ (top (pop (stack s))) (top (stack s))) (pop (pop (stack s)))) (program s))) (defun execute-IFEQ (inst s) (make-state (if (equal (top (stack s)) 0) (+ (arg1 inst) (pc s)) (+ 1 (pc s))) (locals s) (pop (stack s)) (program s))) The other instructions are analogous. Many users define an ACL2 macro, typically named [47mmodify[0m that takes a machine state and some keyword argument and builds a new state from the given one, with new values for the keys specified with keywords. So for example, in that idiom one might replace the [47mmake-state[0m call in [47mexecute-IADD[0m by (modify s :pc (+ 1 (pc s)) :stack (push (+ (top (pop (stack s))) (top (stack s))) (pop (pop (stack s))))) omitting any mention of [47mlocals[0m and [47mprogram[0m because they are not changed. But for beginners we prefer the [47mmake-state[0m idiom because it is more explicit. We wrap all those ``execute'' functions up into a big-switch. (defun do-inst (inst s) ; do instruction inst to state s (if (equal (op-code inst) 'ILOAD) (execute-ILOAD inst s) (if (equal (op-code inst) 'ICONST) (execute-ICONST inst s) (if (equal (op-code inst) 'IADD) (execute-IADD inst s) (if (equal (op-code inst) 'ISUB) (execute-ISUB inst s) (if (equal (op-code inst) 'IMUL) (execute-IMUL inst s) (if (equal (op-code inst) 'ISTORE) (execute-ISTORE inst s) (if (equal (op-code inst) 'GOTO) (execute-GOTO inst s) (if (equal (op-code inst) 'IFEQ) (execute-IFEQ inst s) s))))))))) Observe that if [47mdo-inst[0m is called on an unknown instruction it returns the state unchanged. Thus [47m(do-inst '(HALT) s)[0m is just [47ms[0m. To access the next instruction in a state we define (defun next-inst (s) (nth (pc s) (program s))) In some of our theorems about [47mm1[0m it is convenient to have a way to say ``the machine has reached the [47m(HALT)[0m instruction, i.e., the [47mpc[0m points to [47m(HALT)[0m,'' so we define (defun haltedp (s) (equal (next-inst s) '(HALT))) To ``step'' the machine just once we define (defun step (s) (do-inst (next-inst s) s)) Finally we define [47mm1[0m to step [47mn[0m times. (defun m1 (s n) (if (zp n) s (m1 (step s) (- n 1)))) In a model like this one, where we control the length of the run by a natural-number step count, we often call the second argument of [47mm1[0m the ``clock.'' One might think of it as counting ``cycles'' but not ``run time.'' Some authors call the argument ``fuel''. In some models the ``clock'' might actually be a list and be called by a different name depending on how that list is used. We've seen it called ``schedule'' (because it specifies which process is to step next), ``inputs'' (because it specifies what signals appear on certain pins in the each cycle), and ``oracle'' (because it specifies ``random'' choices). Programming M1 Below we exhibit an M1 program for computing factorial. For convenience we define a constant with this program as its value so we can refer to it. We name the constant ``pi'' for ``program''. In the comments to the right of the instructions we show the position (i.e., the corresponding pc) of the instruction and pseudocode for the nearby snippet of code. In this program we will have just two local variables, called ``[47mn[0m'' and ``[47mans[0m'' in the pseudocode, in positions 0 and 1 respectively of the [47mlocals[0m. We'll compute [47m(fact n)[0m and leave the result in [47mans[0m and on top of the stack. (defconst *pi* ; pc pseudo-code '((iconst 1) ; 0 [Block 1] (istore 1) ; 1 ans := 1; (iload 0) ; 2 loop: [Block 2] (ifeq 10) ; 3 if n=0 then goto exit (i.e., pc+10); (iload 1) ; 4 [Block 3] (iload 0) ; 5 (imul) ; 6 (istore 1) ; 7 ans := ans * n; (iload 0) ; 8 [Block 4] (iconst 1) ; 9 (isub) ; 10 (istore 0) ; 11 n := n - 1; (goto -10) ; 12 goto loop; [Block 5] (iload 1) ; 13 exit: [Block 6] (halt))) ; 14 return ans; We've put blank lines in the display to break the program into blocks, which we've numbered. We'll describe each block's effect now, just to drive home how [47mm1[0m behaves. We will use these blocks in some examples later. Block 1 is the ``compilation'' of ``ans := 1;'' The [47m(iconst 1)[0m pushes [47m1[0m onto the stack and the [47m(istore 1)[0m pops it off into local 1, which we're calling ``[47mans[0m''. We have labeled the top of Block 2 ``[47mloop[0m.'' Although it is not syntactically obvious in this assembly-like code, subsequent code will jump back to [47mpc[0m 2. Block 2 is the compilation of ``if [47mn[0m=0, then goto exit,'' where we labeled [47mpc[0m 13 ``[47mexit[0m.'' In particular, the [47m(iload 0)[0m at [47mpc[0m 2 pushes the value of ``[47mn[0m'') onto the stack. The instruction at [47mpc[0m 3, [47m(ifeq 10)[0m, pops it off and tests it against [47m0[0m. If [47mn[0m=0, the [47mifeq[0m increments the [47mpc[0m by 10, transferring control to [47mpc[0m 13. Block 3 is the compilation of ``ans := ans * n;''. Walk that code segment to understand. Block 4 is the compilation of ``n := n - 1;''. Block 5 jumps back to [47mpc[0m 2 (i.e., [47mloop[0m). In particular, the [47m(goto -10)[0m at [47mpc[0m 12 adds -10 to the [47mpc[0m. Block 6 is the compilation of ``return [47mans[0m.'' It just pushes local 1 onto the stack and halts, leaving the [47mpc[0m at 14. If all we wanted to do with [47mm1[0m is run programs on it, we're done! [47mM1[0m as defined above can be run on concrete input to produce concrete results. For example, to compute factorial of 6 we would start with this state: (make-state 0 ; pc - first instruction (list 6 0) ; locals - n = 6, ans = 0 nil ; stack - empty *pi*) ; program and run it with [47mm1[0m. Of course, we need to specify the ``clock,'' the number of steps we want to take. In the absence of any better idea, we could just try 1000 and see if the final state is at [47mpc[0m 14, which is the [47m(HALT)[0m. M1 !>(m1 (make-state 0 ; pc (list 6 0) ; locals nil ; stack *pi*) ; program 1000) (14 (0 720) ; pc and locals (720) ; stack ((ICONST 1) ; program (ISTORE 1) (ILOAD 0) (IFEQ 10) (ILOAD 1) (ILOAD 0) (IMUL) (ISTORE 1) (ILOAD 0) (ICONST 1) (ISUB) (ISTORE 0) (GOTO -10) (ILOAD 1) (HALT))) Notice that the machine reached the [47m(HALT)[0m at [47mpc[0m 14 and [47m720[0m is on top of the stack. We also may note that local 0 has been zeroed out and local 1 contains 720. We will deal with the clock situation more carefully later. It should be noted that our definition of [47mm1[0m actually executes 1000 steps if that's what the clock says. In particular, the [47mHALT[0m instruction is a no-op, making no state change, and [47mm1[0m just continues to bang away while sitting on that instruction until the clock runs out. We could, of course, define [47mm1[0m differently, so as to return [47ms[0m whenever when [47m(step s)[0m = [47ms[0m. But we'll keep [47mm1[0m simple. ``Teaching'' the Prover How to Control M1 We'll now turn our attention to configuring ACL2 to prove things about M1 programs. This basically consists of proving lemmas to be used as [47m:[0m[47mrewrite[0m rules and, sometimes, disabling functions so that their calls don't expand automatically. We'll explain the motivations of our configuration as we go, but true understanding of the motivation won't come until we prove an M1 program correct. Be patient. This section only exhibits some of the rules we introduce. All of the necessary rules can be found in the same file in which M1 is defined, the ACL2 file [47mbooks/models/jvm/m1/m1.lisp[0m. By the way, the sequence in which these definitions and lemmas appear below is not identical to the sequence in the [47mm1.lisp[0m file, but they're all there. In telling the story we just found the sequence below a little more natural. Arithmetic To be able to reason about simple arithmetic, we include one of the standard arithmetic books. (include-book "arithmetic-5/top" :dir :system) Resolving ``Reads'' and ``Writes'' The local variables are read and written positionally using [47mnth[0m and [47mupdate-nth[0m. It is helpful to have the following lemmas to resolve reads after writes and eliminate shadowed writes. (These lemmas are not necessary in most of our [47mm1[0m proofs because the locals are generally expressed as ``semi-concrete'' list (i.e., a [47mcons[0m tree with symbolic expressions in the [47mcar[0m positions) of a fixed length, like [47m(list a b c)[0m and reads and writes always address an explicitly specified position, like [47m2[0m, so even after a sequence of [47mm1[0m instructions storing values, the symbolic expression of the locals will be a fixed length semi-concrete list. For example [47m(update-nth 2 (+ u v) (list a b c d))[0m is automatically rewritten to [47m(list a b (+ u v) d)[0m just by the definition of [47mupdate-nth[0m. But in more general situations, where the position of the local variable is not an explicit constant or the symbolic expression of the current values of the locals in the state is not an explicit [47mcons[0m tree, the lemmas below are crucial. (defthm nth-add1! (implies (natp n) (equal (nth (+ 1 n) list) (nth n (cdr list))))) (defthm nth-update-nth (implies (and (natp i) (natp j)) (equal (nth i (update-nth j v list)) (if (equal i j) v (nth i list))))) (defthm update-nth-update-nth-1 (implies (and (natp i) (natp j) (not (equal i j))) (equal (update-nth i v (update-nth j w list)) (update-nth j w (update-nth i v list)))) :rule-classes ((:rewrite :loop-stopper ((i j update-nth))))) (defthm update-nth-update-nth-2 (equal (update-nth i v (update-nth i w list)) (update-nth i v list))) Keeping ``Abstractions'' Abstract To allow us to reason about ``abstract'' structures represented by [47mcons[0mes, without expanding their definitions, we prove such lemmas as (defthm stacks (and (equal (top (push x s)) x) (equal (pop (push x s)) s) ; These next two are needed because some push expressions evaluate to ; list constants, e.g., (push 1 (push 2 nil)) becomes '(1 2) and '(1 ; 2) pattern-matches with (cons x s) but not with (push x s). (equal (top (cons x s)) x) (equal (pop (cons x s)) s))) We prove the analogous rules about state accessors and [47mmake-state[0m, e.g., [47m(equal (pc (make-state pc locals stack program)) pc)[0m. Then we disable all the defined functions just mentioned so they never expand. Controlling Case Explosion due to Step Next we introduce a crucial rule for controlling the expansion of [47mstep[0m. The term [47m(step s)[0m can always be expanded into that big-switch that considers all the possible [47mop-code[0ms. That is generally a disaster. Think of what would happen if [47m(step (step s))[0m were automatically expanded when we have no information about [47ms[0m: the inner [47mstep[0m would introduce a 9-way case split and the outer one would turn that into an 81-way case split considering all of the possibilities for the first two instructions. We want to expand [47mstep[0m only when we know something definite about the instruction that is to be executed. So we prove this logically trivial theorem. (defthm step-opener (implies (consp (next-inst s)) (equal (step s) (do-inst (next-inst s) s)))) The conclusion is just the definition of [47mstep[0m! So the hypothesis is completely unnecessary from a logical perspective. But operationally, if this rule has been proved and then [47mstep[0m is disabled, the rewriter will expand [47m(step s)[0m only if [47m(next-inst s)[0m can be proved to satisfy [47mconsp[0m. The most common way for [47m(next-inst s)[0m to be a [47mconsp[0m is when both the [47mpc[0m and the [47mprogram[0m in state [47ms[0m are quoted constants and [47mprogram[0m is a well-formed program. But we don't want to require exactly that because it is too restrictive. For example, in machine models supporting subroutine calls, the typical correctness theorem for a subroutine says very little about the entire ``program space'' but deals with an [47minvoke[0m- or [47mjsr[0m-type instruction to a place where the code for the subroutine is found. (If you inspect [47mbooks/models/jvm/m2/examples.lisp[0m and look at [47mexample4[0m you will see such a correctness theorem.) As models get more complex you may have to adjust [47mstep-opener[0m accordingly, though this simple version is surprisingly effective. Having established [47mstep-opener[0m, we disable [47mstep[0m so that the only way it ever expands is when the [47mnext-inst[0m is provably a [47mconsp[0m. (in-theory (disable step)) [31;1mSymbolic Execution Example 1[0m To illustrate the rules just described, consider the symbolic expression (step (step (make-state 0 (list n ans) stack *pi* ; '((ICONST 1) ; 0 [Block 1] ; (ISTORE 1) ; 1 ans := 1; ; ... ; 2 ; ...) ; ... ))) Note that the outer [47mstep[0m cannot be expanded because [47mstep[0m is disabled and we can't determine the [47mnext-instr[0m of the (unsimplified) inner [47mstep[0m. But [47mstep-opener[0m fires on the inner [47mstep[0m because [47mnext-inst[0m of the above [47mmake-state[0m just rewrites to [47m'(ICONST 1)[0m using the definitions of [47mpc[0m, [47mprogram[0m, and [47mnth[0m. So the term above is rewritten to (step (make-state 1 (list n ans) (push 1 stack) *pi* ; '((ICONST 1) ; 0 [Block 1] ; (ISTORE 1) ; 1 ans := 1; ; ... ; 2 ; ...) ; ... )) using [47mstep-opener[0m, [47mnext-inst[0m, [47mdo-inst[0m, [47mexecute-iconst[0m, [47mnth[0m, and [47mupdate-nth[0m. [47mExecute-iconst[0m just advanced the [47mpc[0m from 0 to 1 and symbolically pushed a [47m1[0m into the [47mstack[0m. But now [47mstep-opener[0m can fire on that outer [47mstep[0m because we see that the [47mnext-inst[0m of this state is [47m(ISTORE 1)[0m. So the term rewrites to (make-state 2 (list n 1) stack *pi* ; '((ICONST 1) ; 0 [Block 1] ; (ISTORE 1) ; 1 ans := 1; ; ... ; 2 ; ...) ; ... ) We've just symbolically executed the first two instructions of [47m*pi*[0m on a symbolic state containing two unspecified locals and an unspecified stack. This simplification is completely automatic. [31;1mSymbolic Execution Example 2[0m We'll show one more symbolic execution of a snippet from program [47m*pi*[0m. This time, let's start at top of the loop in [47m*pi*[0m, [47mpc[0m 2, and run down through the [47m(GOTO -10)[0m where the program jumps back to the loop. That takes 11 [47mstep[0ms. Furthermore, assume that [47mn[0m (local 0) is a non-0 natural number and [47mans[0m (local 1) is a natural number. (m1 (make-state 2 (list n ans) stack *pi*) 11) = (step (step (step (step (step (step (step (step (step (step (step (make-state 2 (list n ans) stack *pi* ; '(... ; ... ; (ILOAD 0) ; 2 loop: [Block 2] ; (IFEQ 10) ; 3 ; (ILOAD 1) ; 4 [Block 3] ; (ILOAD 0) ; 5 ; (IMUL) ; 6 ; (ISTORE 1) ; 7 ; (ILOAD 0) ; 8 [Block 4] ; (ICONST 1) ; 9 ; (ISUB) ; 10 ; (ISTORE 0) ; 11 ; (GOTO -10) ; 12 [Block 5] ; ...) )))))))))))) (Exceedingly deep nests of [47mstep[0ms can cause stack overflow in the ACL2 rewriter. We discuss this problem the presentation of the [47mm1-opener[0m lemma below.) We won't show the step-by-step results of this symbolic execution (thank goodness!), but the first two instructions just move the [47mpc[0m from 2 to 4 because [47mn[0m is not 0. The next four replace [47mans[0m by [47m(* ans n)[0m, the next four replace [47mn[0m by [47m(- n 1)[0m, and the last [47mstep[0m sets the [47mpc[0m to the top of the loop at [47mpc[0m 2 again. Despite the pushing and popping on the stack, by the time we get back to the top of the loop, the stack is unchanged. The result is (make-state 2 (list (- n 1) (* ans n)) stack *pi* ; '(... ; ... ; (ILOAD 0) ; 2 loop: [Block 2] ; (IFEQ 10) ; 3 ; (ILOAD 1) ; 4 [Block 3] ; (ILOAD 0) ; 5 ; (IMUL) ; 6 ; (ISTORE 1) ; 7 ; (ILOAD 0) ; 8 [Block 4] ; (ICONST 1) ; 9 ; (ISUB) ; 10 ; (ISTORE 0) ; 11 ; (GOTO -10) ; 12 [Block 5] ; ...) ) We'll see this expression again later. What's important is that with the [47mstep[0m rules we have in place, ACL2 will automatically do symbolic evaluation of concrete code sequences. Clock Expressions Many (most?) of our theorems about specific M1 programs will involve a clock expression which specifies exactly how many steps we want the machine to take. It is not as hard as you might think to create functions that compute this --- provided you can prove that the clock function terminates, which is of course generally undecidable but frequently trivial. And, proofs via clock functions are not only equivalent to proofs by inductive assertions but that has been proved with ACL2 and tools are provided to convert back and forth between the two proof styles (see [bib::rm04]). Clock functions for [47mm1[0m are recursive functions defined that use arithmetic expressions to compute the lengths of code segments. However, a key part of our strategy for controlling proofs is to use the structure of the clock function and its arithmetic expressions to decompose ``long'' runs of [47mm1[0m into compositions of shorter runs. In order to do that, we must prevent the prover from rearranging our clocks! That is, [47m(m1 s (+ i j))[0m will decompose differently than [47m(m1 s (+ j i))[0m, but the arithmetic library might rearrange the clock, e.g., by using the commutativity of addition. So instead of using [47m+[0m to express the addition of two clocks we define [47mclk+[0m to be [47m+[0m, but we'll disable its definition to protect clocks from arithmetic reasoning. We will arrange for [47mclk+[0m to take more than just two arguments and will reveal that it is associative. (defun binary-clk+ (i j) (+ (nfix i) (nfix j))) (defthm clk+-associative (equal (binary-clk+ (binary-clk+ i j) k) (binary-clk+ i (binary-clk+ j k)))) (defmacro clk+ (&rest args) (if (endp args) 0 (if (endp (cdr args)) (car args) `(binary-clk+ ,(car args) (clk+ ,@(cdr args)))))) Thus [47m(clk+ a b c)[0m is just an abbreviation for [47m(binary-clk+ a (binary-clk+ b c))[0m, and the prover will rewrite [47m(clk+ (clk+ a b) (clk+ d e))[0m to the [47mbinary-clk+[0m version of [47m(clk+ a b c d)[0m. The key fact about clocks and [47mm1[0m is captured in the following rewrite rule, which is sometimes called the ``sequential execution'' rule or the ``semi-colon rule.'' (defthm m1-clk+ (equal (m1 s (clk+ i j)) (m1 (m1 s i) j))) Having proved this, we disable [47mbinary-clk+[0m so that we have complete control over how long runs decompose. Expanding [47mm1[0m Of course, [47mm1[0m must eventually expand. The following rule effectively makes the prover open [47mm1[0m only when the clock is a natural number constant. (We say ``effectively'' because we assume that all clock expressions are phrased in terms of [47mclk+[0m.) The rule below exploits the fact that the prover sees [47m7[0m, for example, as [47m(+ 1 6)[0m. (defthm m1-opener (and (equal (m1 s 0) s) (implies (natp i) (equal (m1 s (+ 1 i)) (m1 (step s) i))))) We then disable [47mm1[0m. [31;1mObscure Remark[0m: Experiments with the [47mcodewalker[0m tool (see the ACL2 book [47mbooks/projects/codewalker/codewalker.lisp[0m, specifically the discussion of ``snorkling'') suggest that nests of [47mstep[0ms more than several hundred deep (depending on the complexity of [47mstep[0m) can cause stack overflow. One way to handle that is to modify [47mm1-opener[0m, above, using a [47m[syntaxp][0m hypothesis so that it doesn't fire if [47mi[0m is, say, larger than 200. Then prove a variant for ``large'' natural numbers, [47mi[0m, that transforms [47m(m1 s i)[0m into p [47m(m1 (m1 s 200) (- i 200))[0m, using [47m[syntaxp][0m to limit the application to [47ms[0m terms that are [3mnot[0m calls of either [47mm1[0m or [47mstep[0m, and [47mi[0m terms that are quoted natural numbers. This variant can be derived from [47mm1-clk+[0m. (Note: a hint is necessary to keep our other rules from interfering with the obvious proof.) The effect of this more sophisticated variant of [47mm1-opener[0m is that an expression like [47m(m1 s 900)[0m is rewritten first to [47m(m1 (m1 s 200) 700)[0m; the sophisticated rule won't fire on the outer [47mm1[0m because it is applied to an [47mm1[0m term, but the conventional [47mm1-opener[0m will fire on the inner [47m(m1 s 200)[0m because of the small clock. That will reduce the inner [47mm1[0m to a semi-explicit state, and then another 200 steps will be taken from the 700, etc. We do not recommend doing this until you start to get stack overflows, but we point out the possibility to highlight the tricks you can use to control expansions. But for the rest of this discussion we assume we just have the conventional [47mm1-opener[0m. The rules shown above have the effect of rewriting the following [47mm1[0m call successively into the last term below. (m1 (make-state 0 (list n ans) stack *pi*) (clk+ 2 (loop-clk n))) = {by m1-clk+} (m1 (m1 (make-state 0 (list n ans) stack *pi*) 2) (loop-clk n)) = {by m1-opener} (m1 (step (step (make-state 0 (list n ans) stack *pi*))) (loop-clk n)) = {by step-opener} (m1 (make-state 2 (list n 1) stack *pi*) (loop-clk n)) The last simplification above is just the symbolic evaluation of the first two instructions of [47m*pi*[0m, as we shown Symbolic Execution Example 1. We'll see the final [47mm1[0m expression again later, when we prove [47m*pi*[0m computes the factorial function. Playing with Program *pi*: Execution, Symbolic Execution, and Proof of Correctness In this section use program [47m*pi*[0m to compute factorial on a concrete state, essentially using our formal model as a prototype of the envisioned machine. We show two examples, [47mn[0m = 6 and [47mn[0m = 1000. The latter requires several thousand [47mm1[0m steps and allows us to time the execution speed of [47mm1[0m. We then show the theorem prover doing symbolic execution of a snippet of [47m*pi*[0m to help us ``reverse engineer'' the loop. Finally, we prove that when program [47m*pi*[0m is run on a natural number [47mn[0m in local 0, it halts and leaves [47m(fact n)[0m on top of the stack, where [47mfact[0m is defined in the classic recursive way. In fact, we prove something stronger and explain why. The Clock for Factorial If we start at [47mpc[0m 0, how many steps must we take to reach the [47mhalt[0m? We take 2 steps to reach the instruction labeled [47mloop[0m at [47mpc[0m 2. We'll then travel around the loop some ``unknown'' number of times as a function of [47mn[0m before exiting and reaching the [47mHALT[0m. (Technically the iteration might also depend on [47mans[0m but in this case it does not.) Let [47m(loop-clk n)[0m be the number of steps we take from [47mpc[0m 2 to the [47mHALT[0m. After defining [47mloop-clk[0m we can define the clock for [47m*pi*[0m to be (defun clk (n) (clk+ 2 (loop-clk n))) To derive a definition for [47mloop-clk[0m just walk the code starting at [47mpc[0m 2. The code tests whether [47mn[0m is zero and if so jump to 13 where it puts [47mans[0m on the stack and halt. Thus, if [47mn[0m is zero, we take 3 steps. If [47mn[0m is not zero (which takes 2 steps to determine), we multiply [47mn[0m into [47mans[0m (at [47mpc[0ms 4-7, which takes 4 steps), decrement [47mn[0m (at [47mpc[0ms 8-11, which takes 4 steps), and then at [47mpc[0m 12 the code jumps back to loop (which takes 1 step). So after a total of 2+4+4+1 = 11 steps we're back at [47mpc[0m 2 having decremented [47mn[0m by 1. So here is how many steps we take from [47mpc[0m 2 to the [47mhalt[0m: (defun loop-clk (n) (if (zp n) 3 (clk+ 11 (loop-clk (- n 1))))) Question: how many steps does it take to compute [47m6![0m? Answer: [47m(clk 6)[0m = 71. Computing with M1 If we fire up ACL2, include the [47mm1[0m book, select the [47m"M1"[0m symbol package, and define [47m*pi*[0m, [47mloop-clk[0m, and [47mclk[0m as shown above, we can use [47mm1[0m to compute various factorials. M1 !>(m1 (make-state 0 ; pc (list 6 0) ; locals n = 6 and ans = 0 nil ; stack (empty) *pi*) ; program (clk 6)) (14 (0 720) (720) ((ICONST 1) (ISTORE 1) (ILOAD 0) (IFEQ 10) (ILOAD 1) (ILOAD 0) (IMUL) (ISTORE 1) (ILOAD 0) (ICONST 1) (ISUB) (ISTORE 0) (GOTO -10) (ILOAD 1) (HALT))) Observe the final state: the [47mpc[0m is [47m14[0m, which points to the [47m(HALT)[0m. Local 0, i.e., [47mn[0m, has been zeroed out but local 1, i.e., [47mans[0m, contains [47m720[0m. Furthermore, [47m720[0m has been pushed onto the stack. The [47mprogram[0m, of course, is unchanged. And by the way, 720 = 6*5*4*3*2*1. Of course, we can define factorial recursively in ACL2 and check the [47mm1[0m computation. M1 !>(defun fact (n) (if (zp n) 1 (* n (fact (- n 1))))) The admission of FACT is trivial, ... ... M1 !>(fact 6) 720 We can compute larger factorials with [47mm1[0m, of course. Here's how we compute [47m1000![0m with [47mm1[0m. M1 !>(m1 (make-state 0 (list 1000 0) nil *pi*) (clk 1000)) It takes SBCL about 0.02 seconds to compute the answer. The answer is a natural number with 2,568 decimal digits, so we won't show it here, but you can try it on your own. [47m(Clk 1000)[0m is 11,005, so during this particular computation, ACL2 was executing 550,250 M1 instructions per second. Our model would run faster if we used a single-threaded object (see [47mstobj[0m) to hold the state and faster still if we verified the guards of [47mm1[0m. We point to discussions and examples of these ideas at the end of this topic. Symbolic Execution of M1 Code We can use the theorem prover to help us reverse engineer code. For example, what does the loop in [47m*pi*[0m do? We actually posed the question in Symbolic Execution Example 2 above, i.e., what is [47m(m1 (make-state 2 (list n ans) stack *pi*) 11)[0m when [47mn[0m and [47mans[0m are natural numbers and [47mn[0m is not [47m0[0m. We can pose a (non-)theorem to the prover to see. The lefthand side of the equality just simplifies to the nest of 11 [47mstep[0ms from Symbolic Execution Example 2. The righthand side, below, is the variable [47m???[0m, so this formula is obviously not a theorem, but the prover will simplify the formula and print the checkpoint. (thm (implies (and (natp n) (< 0 n) (natp ans)) (equal (m1 (make-state 2 (list n ans) stack *pi*) 11) ???))) Of course, the proof attempt fails. But if you look at the checkpoint you should recognize the simplified expression as being from Example 2. Goal'' (IMPLIES (AND (INTEGERP N) (<= 0 N) (< 0 N) (INTEGERP ANS) (<= 0 ANS)) (EQUAL (MAKE-STATE 2 (LIST (+ -1 N) (* ANS N)) STACK '((ICONST 1) (ISTORE 1) (ILOAD 0) (IFEQ 10) (ILOAD 1) (ILOAD 0) (IMUL) (ISTORE 1) (ILOAD 0) (ICONST 1) (ISUB) (ISTORE 0) (GOTO -10) (ILOAD 1) (HALT))) ???)) Proving Theorems about M1 Programs In this section we prove that [47m*pi*[0m computes factorial. [31;1mStep 0: The Specification[0m We've already specified, informally, that we intend that [47m*pi*[0m computes [47m(fact n)[0m when [47mn[0m is a natural number. This is just shorthand for the more precise understanding that if we start at [47mpc[0m 0 with a natural, [47mn[0m, in local 0 and run program [47m*pi*[0m [47m(clk n)[0m steps, the final state has [47mpc[0m 14 (meaning execution reached the [47m(HALT)[0m), local 0 has been zeroed, local 1 contains [47m(fact n)[0m, and [47m(fact n)[0m is on top of the otherwise unchanged initial [47mstack[0m. [31;1mStep 1: The Semantic Function[0m Define an ACL2 function that ``does what the loop does.'' We sometimes call this the [3msemantic function[0m corresponding to the loop. (defun helper (n ans) (if (zp n) ans (helper (- n 1) (* ans n)))) The function above captures [47m*pi*[0m's behavior from entry to the loop at [47mpc[0m 2 through the halt at [47mpc[0m 14. Programs that have elaborate initialization and finalizations and/or multiple loops require defining a series of functions for each segment and loop. But for this program, we can capture all of [47m*pi*[0m's behavior by calling the semantic function on the values the locals have upon entering the loop, i.e., [47m(helper n 1)[0m. [31;1mStep 2: Relate the Semantic Function to the Code[0m Prove that the loop does what we said it would do. (defthm loop-correct (implies (and (natp n) (natp ans)) (equal (m1 (make-state 2 (list n ans) stack *pi*) (loop-clk n)) (make-state 14 (list 0 (helper n ans)) (push (helper n ans) stack) *pi*)))) This proof is completely ``automatic'' --- but only because we stated the theorem exactly right, in terms of [47mhelper[0m to ``explain'' what the loop is doing with the second local, [47mans[0m. Once you get used to this style of proof, Step 2 is not really very creative: it just says what the program does operationally, using tail recursion in place of iteration. Of course, recursion is ACL2's bread and butter. The proof of [47mloop-correct[0m is by the induction as suggested by [47m(helper n ans)[0m. The induction scheme is (AND (IMPLIES (AND (NOT (ZP N)) (:P (* ANS N) (+ -1 N) STACK)) (:P ANS N STACK)) (IMPLIES (ZP N) (:P ANS N STACK))) If you work it out you'll see that in the induction conclusion [47m(loop-clk n)[0m expands to [47m(clk+ 11 (loop-clk (- n 1)))[0m, and then the machinery we've been talking about reduces the induction conclusion to the induction hypothesis. Do it for yourself. You will see the simplifications done earlier in Symbolic Execution Example 2. (There is another basic case we haven't explicitly discussed: what happens when we're at the top of the loop but [47mn[0m is [47m0[0m? That case is handled by symbolic execution: [47m(loop-clk n)[0m is 3, the [47mIFEQ[0m jumps to the exit to push [47mans[0m onto the stack and advance the [47mpc[0m to the [47m(HALT)[0m at 14.) [31;1mStep 3: Relate the Semantic Function to the Specification[0m (defthm helper-is-fact (implies (and (natp n) (natp ans)) (equal (helper n ans) (* ans (fact n))))) This is proved ``automatically.'' Generally speaking, Step 3 is the most creative step because it requires explaining how the ``iterative'' (tail-recursive) accumulation of the answer relates to the recursive computation of the answer. [31;1mStep 4: Total Correctness[0m Combine the foregoing into the statement of the total correctness of [47m*pi*[0m. (defthm correctness-of-*pi* (implies (natp n) (equal (m1 (make-state 0 (list n ans) stack *pi*) (clk n)) (make-state 14 (list 0 (fact n)) (push (fact n) stack) *pi*)))) This is proved ``automatically'' because of our setup. [47m(Clk n)[0m expands to [47m(clk+ 2 (loop-clk n))[0m and the crucial [47mm1-clk+[0m (``sequential execution'') rule shows it is equivalent to (m1 (step (step (make-state 0 (list n ans) stack *pi*))) (loop-clk n)) But then the [47mstep[0m rules can reduce that to: (m1 (make-state 2 (list n 1) stack *pi*) (loop-clk n)) at which point the [47mloop-correct[0m lemma can fire and produce (make-state 14 (list 0 (helper n 1)) (push (helper n 1) stack) *pi*) and then [47m(helper n 1)[0m is rewritten [47m(fact n)[0m by [47mhelper-is-fact[0m and arithmetic, reducing the lefthand side to the righthand side. (The above description is inaccurate only in the sequencing of the various rewrites.) Q.E.D. Of course, from [47mcorrectness-of-*pi*[0m we can easily derive weaker but simpler results to ``advertise.'' (defthm corollary-of-correctness-of-*pi* (implies (and (natp n) (equal s_init (make-state 0 (list n ans) stack *pi*)) (equal s_fin (m1 s_init (clk n)))) (and (equal (top (stack s_fin)) (fact n)) (equal (next-inst s_fin) '(HALT))))) Viewing these results from a higher level, one might argue that the corollary above is a ``better'' theorem than [47mcorrectness-of-*pi*[0m. It just says, simply, if you have an initial state poised to execute [47m*pi*[0m on [47mn[0m and you run it [47m(clk n)[0m steps to some ``final'' state, that final state has [47m(fact n)[0m on top of the stack and is halted. The full correctness result we proved says some ``irrelevant'' things: in the final state, [47mn[0m is 0, [47m(fact n)[0m is also in local 1, and the original stack is intact under the answer. But those facts are not irrelevant! They (or something like them) are mathematically necessary for the inductive proof. Remember, inductive proofs only work on sufficiently strong theorems. Furthermore, we really must care about these other issues even from the high level perspective. If, for example, our program is just a subroutine of a larger system (on a machine that supports procedure call and return) we [3mreally need to know[0m that the stack is not disturbed since the results of prior computations may be sitting in it for use for future computations. In a setting where we're concerned about privacy and security (in a machine with addressable memory) [3mwe really need to know[0m that information hasn't been moved from private space to public space. In a setting where programs are in writable memory, [3mwe really need to know[0m that our program hasn't been overwritten by some subroutine. More M1 Programs and Proofs The proofs described above can be seen in the ACL2 book [47mbooks/models/jvm/m1/fact.lisp[0m. If the proof script here is taken as a template for all such proofs you'll find it a bit ``fragile'' in the sense that lemmas proved in one step of the template may get in the way of proofs in subsequent steps. That is generally dealt with by disabling certain lemmas when their work has been done. But, except for this issue of controlling rewriting a little more restrictively via disabling, this proof of the correctness of [47m*pi*[0m serves as a good template for clock-based total correctness proofs of single-loop [47mm1[0m programs. There are many other examples of proofs of [47mm1[0m programs on the directory [47mbooks/models/jvm/m1[0m. Here is a brief guide. * [47mbooks/models/jvm/m1/template.lisp[0m: a ``robust'' template for proving the total correctness of one-loop [47mm1[0m programs. The template is overly robust in the sense that it introduces often irrelevant intermediate functions, lemmas, and disable events. In the vast majority of cases the proofs can be carried out with fewer events. But until you understand how ACL2 behaves it's best to just rotely follow the template. * the files listed below contain simple one-loop [47mm1[0m programming and proof challenges. Each file follows the template above. We recommend that you [3mnot[0m look at the solutions and instead read the challenge programming/proof problem at the top of the file and then follow the template for yourself. We also recommend you do these problems in the order listed, as they gradually get harder. * [47mbooks/models/jvm/m1/sum.lisp[0m * [47mbooks/models/jvm/m1/sumsq.lisp[0m * [47mbooks/models/jvm/m1/fact.lisp[0m * [47mbooks/models/jvm/m1/power.lisp[0m * [47mbooks/models/jvm/m1/expt.lisp[0m * [47mbooks/models/jvm/m1/alternating-sum.lisp[0m * [47mbooks/models/jvm/m1/alternating-sum-variant.lisp[0m * [47mbooks/models/jvm/m1/fib.lisp[0m * [47mbooks/models/jvm/m1/lessp.lisp[0m * [47mbooks/models/jvm/m1/even-solution-1.lisp[0m * [47mbooks/models/jvm/m1/even-solution-2.lisp[0m * [47mbooks/models/jvm/m1/sign.lisp[0m * the files below deal with two-loop programs in which the loops are nested. The solutions use the same basic naming scheme as the template. * [47mbooks/models/jvm/m1/div.lisp[0m * [47mbooks/models/jvm/m1/bexpt.lisp[0m * [47mbooks/models/jvm/m1/m1-fact-on-neg-runs-forever.lisp[0m: we prove that if [47mn[0m is negative, the factorial program [47m*pi*[0m never reaches the halt. This problem is probably not suitable for you to work out on your own. But you can probably do others like it after understanding the proofs here. We prove the theorem two different ways. The first is a classic clock-style proof but the clock function decomposes an arbitrary natural number [47mk > 1[0m into the form 2 + 11 + 11 + ... + 11 + [47m(mod (- k 2) 11)[0m and then an inductive proof shows that the program never gets out of the loop --- and there's no [47mHALT[0m in the loop. The second uses the inductive assertion style proof carried out directly by symbolic evaluation of the operational semantics and induction. For an explanation of the use of inductive assertions with this style of operational semantics see [bib::moore03b]. That paper deals with the M5 machine (ACL2 directory [47mbooks/models/jvm/m5/[0m) but is easily understood in the context of M1. * [47mbooks/models/jvm/m1/m1-half-via-inductive-assertions.lisp[0m: define a program that halves its natural number input and terminates iff the input was even. Prove it. This example is discussed in [bib::moore03b] as an M5 program. It uses the inductive assertion method. * [47mbooks/models/jvm/m1/magic.lisp[0m illustrates the importance of termination. It presents a program that just successively replaces the top of the stack by its successor, starting from [47m0[0m. If you look at the state at the right moment, you can find any natural number you want on top of the stack. So this program ``implements'' every natural valued function --- if terminating isn't a requirement! In that sense, we prove this program implements fib and also implements factorial. (Of course, we could also constrain a function to return a natural and prove that the program implements that function, but we don't bother.) * [47mbooks/models/jvm/m1/funny-fact.lisp[0m: this shows a two-loop program in which one loop follows another rather than being nested inside the other. The first loop pushes successive naturals from [47mn[0m down to [47m1[0m onto the stack. The second loop repeatedly multiplies the top two elements together. Prove that implements factorial. Note: this ``bytecode'' program violates a basic principle of the Java bytecode verifier, which insists that the stack is always the same length upon every arrival at every instruction. * [47mbooks/models/jvm/m1/wormhole-abstraction.lisp[0m: yet another proof of a factorial program, but it shows a way you can avoid explicitly specifying intermediate values you don't care about. This idea was first demonstrated by Dave Greve of Collins Aerospace. * [47mbooks/models/jvm/m1/m1-with-stobj.lisp[0m: [47mM1[0m has been defined in a ``constructor'' style: every new state constructed as a list of four elements where all the elements are specified. In more realistic machines, e.g., ACL2 directory [47mbooks/projects/x86isa/[0m, the state is a single-threaded object (see [stobj]) that is destructively modified to effect state changes. This produces much more efficient runtime execution. However, it slightly changes the form of correctness proofs. In [47mm1-with-stobj.lisp[0m we define the M1 machine using a single-threaded object as the state. Then, in * [47mbooks/models/jvm/m1/m1-with-stobj-clock-example.lisp[0m we implement multiplication by repeated additions (avoiding use of the [47mIMUL[0m instruction) on that version of M1 and prove it correct. * [47mbooks/models/jvm/m1/defsys.lisp[0m: a verifying compiler from a very simple ``Toy Lisp'' to [47mm1[0m. Toy Lisp is just the subset of ACL2 composed of variable symbols, quoted numeric constants, the function symbols [47m+[0m, [47m-[0m, [47m*[0m (primitively supported by M1), the form [47m(MV a1 ... an)[0m for returning multiple values, the form [47m(IFEQ a b c)[0m (which is just ACL2's [47m(if (equal a 0) b c)[0m), and calls of primitive and defined Toy Lisp functions. The compiler takes a list of Toy Lisp ``modules,'' each of which specifies a symbolic name, formals, pre-conditions, post-conditions, and a Toy Lisp implementation. An example module is (lessp :formals (x y) :input (and (natp x) ; pre-condition (natp y)) :output (if (< x y) 1 0) ; post-condition :code (ifeq y ; Toy Lisp implementation 0 (ifeq x 1 (lessp (- x 1) (- y 1))))) The compiler implements a call/return protocol so that one Toy Lisp function can use another. The compiler produces M1 code for each module. In addition, it produces the clock function for each module and it generates events that prove that the M1 code implements input/output specification. The result is an M1 state poised to call the module [47mmain[0m on whatever arguments are on the [47mm1[0m [47mstack[0m. [31;1mWarning:[0m As of August, 2024, the comments in [47mdefsys.lisp[0m are out of date! * [47mbooks/models/jvm/m1/theorems-a-and-b.lisp[0m: a proof that M1 can compute anything a Turing machine can compute. See the paper [bib::moore14]. * The ACL2 file [47mbooks/projects/codewalker/README[0m describes a tool called ``codewalker.'' Codewalker is a utility for exploring code in any programming language specified by an ACL2 operational model. Three main facilities are provided: the abstraction of a piece of code into an ACL2 ``semantic function'' that returns the same machine state, the definition the ``clock function'' for the code, and the ``projection'' of the semantic function into another function that computes the final value of a given state component using only the values of the relevant initial state components. No paper about codewalker is available. But the first 50 pages of [47mcodewalker.lisp[0m is a comment providing documentation. In addition, several examples are provided in other files. For example, the ACL2 book [47mbooks/projects/codewalker/demo-fact.lisp[0m uses codewalker to verify an M1 factorial program. By the way, the version of M1 used there is defined on the [47mcodewalker/[0m directory rather than the [47mbooks/models/jvm/m1/[0m directory to allow the two versions to drift apart. The M1 used by the codewalker demo is defined in [47mbooks/projects/codewalker/m1-version-3.lisp[0m and it uses a single-threaded object (see [stobj]) representation of the state. More Elaborate Models of the JVM: From M1 to M6 M1 is only the start of a series of models of the JVM. M1 lacks a bytecode verifier, method invocation, threads, and other features which are explored in the more elaborate models, all of which are found on the ACL2 directory [47mbooks/models/jvm/[0m. * The ACL2 directory [47mbooks/models/jvm/guard-verified-m1/[0m is another version of [47mm1[0m that differs in two ways. First, instead of using the constructor style of creating new states (e.g., with [47m(list pc locals stack program)[0m) it uses a single-threaded object (see [stobj]). This slightly changes the forms of correctness theorems and lemmas. Second, the definition of [47mm1[0m on the [47mbooks/models/jvm/guard-verified-m1/[0m directory has been guard verified. This involves attaching a guard to every ``[47mexecute[0m'' function and lifting that up to the level of the [47mm1[0m function. The guards include the notion of a ``good state'' which includes the notion of a well-formed program. But that necessarily involves the requirement that, say, when every [47mIADD[0m instruction is encountered the stack has at least two numbers on it. The [47mgood-statep[0m predicate is essentially a simple [3mbytecode verifier[0m for [47mm1[0m: it tells us that if a state is good (meaning, the program in it is good), then executing the program guarantees all the properties necessary for error-free execution. Verifying the guards of this version of [47mm1[0m demonstrates ``verification of the bytecode verifier.'' The directory also contains the examples found in the unguarded version of [47mm1[0m on [47mbooks/models/jvm/m1[0m. The reason we provide two functionally equivalent versions of [47mm1[0m is that when teaching how to use ACL2 to specify a machine operationally, it is easiest to start with the unguarded [47mm1[0m. * M2, on the ACL2 directory [47mbooks/models/jvm/m2/[0m is essentially M1 with method invocation (both static and virtual), return, and class instances including a demonstration of inheritance. See [bib::moore99a]. In that paper the machine is named ``tjvm'' for ``Toy JVM'' but its proper name is M2. The paper and ACL2 scripts illustrate how to reason about procedure call and return. * M5, on the ACL2 directory [47mbooks/models/jvm/m5/[0m is a closer approximation to the JVM. M5 was written by George Porter, as an undergraduate project. M5 supports 195 JVM instructions, including those for several kinds of arithmetic, arrays, and objects, threads and monitors. The handling of integer arithmetic is accurate, e.g., all integers are bounded and addition, say, wraps around. Floating point is not accurate and we regard it as a mere placeholder. The directory contains proofs of properties for several M5 programs, including iterative and recursive ones (dealt with via clock-based proofs), some partial correctness proofs about programs that do not always terminate (dealt with via the inductive assertion method), and the correctness of an applicative insertion sort method (on Objects representing cons trees). See [bib::mp02] and [bib::moore03a]. A proof of a mutual-exclusion property, called ``the Apprentice Challenge,'' is described in the papers and the corresponding books containing proofs are available on the [47mm5/[0m directory. * M6, on the ACL2 directory [47mbooks/models/jvm/m6/[0m is the best approximation to the JVM. M6 was written as part of Hanbing Liu's PhD dissertation, supported by Sun Microsystems. The M6 state includes an ``external class table'' where classes reside until they are loaded. M6 can execute most J2ME Java programs (except those with significant I/O or floating-point). It was primarily designed to model dynamic class loading, class initialization, and bytecode verification. The entire Sun CLDC API library (672 methods in 87 classes) was translated into the external representation and is available for loading, constituting about 500 pages of data. The model included 21 out of 41 native APIs that appeared in Sun's CLDC API library. The M6 description itself is about 160 pages of ACL2. See [bib::liu06]. Quick Index to Related Topics * [operational-semantics] * operational-semantics-1__simple-example --- current topic * [operational-semantics-2__other-examples] * [operational-semantics-3__annotated-bibliography] * [operational-semantics-4__how-to-find-things] * [operational-semantics-5__history-etc]") (operational-semantics-2__other-examples (operational-semantics) "Examples of other models and proof techniques The topic [operational-semantics-1__simple-example] deals with a simple machine, M1, and focuses on the ``clock''-based proof style. In this section we point to other machine models, different ACL2 proof styles, and tools in the ACL2 Community Books that may be of interest. We limit our discussion here to operational semantics. But it is worth noting that a valuable way to explore the diversity of ACL2 applications and extensions is to browse the ACL2 Workshop series. See the ``ACL2 Workshops, UT Seminar, and Course Materials'' link on the {ACL2 homepage | http://www.cs.utexas.edu/users/moore/acl2/}. Then visit the Program for each workshop. Many of the papers include supplemental material in the form of ACL2 proof scripts are in the ACL2 Community Books regression suite and thus available locally if you've installed ACL2. They're under the directory [47mbooks/workshops/[0m, which is organized by the year of the workshop and the name of the author(s), e.g., [47mbooks/workshops/2023/passmore/[0m. Other Machines As noted in [operational-semantics-5__history-etc], a ``handheld calculator'' was formalized in Chapter 17 [bib::bm79], using the precursor to Nqthm. That machine was essentially M1 without the branch or jump instructions. That is, all programs were just straightline sequences of stack-based arithmetic operations. The Bendix 930 flight control computer discussed in [bib::bm80] was a more traditional von Neumann machine, also modeled in the precursor to Nqthm. The 30 page model is listed in Section 15 of [bib::bm80]. The Computational Logic, Inc. (CLI) Verified Stack was formalized and verified with Nqthm. The CLI Verified Stack was a hardware-software stack consisting of a gate-level description of a microprocessor, its instruction set architecture, an assembler/linker/loader for a stack based assembly language with subroutine call and return, a compiler for a simple subset of a Pascal-like language, a simple operating system kernel, and some applications programs. Each component of the stack was verified with respect to the component immediately below in such a way that the correctness theorems could be composed. The result was that if a program in the high-level language was verified (with respect to the operational semantics of the high-level language) then compiling, assembling, linking, and loading the binary image onto the gate-level machine and running it would, with mathematical certainty, deliver the results verified at the high level. The stack was described in the 1989 special issue of the [3mJournal of Automated Reasoning[0m, [bib::bhmy89]. In 1992, a hardware description language was formalized and another microprocessor was described and verified to implement a slightly different machine code. That microprocessor was fabricated, the assembler/linker/loader was retargeted to the new machine code and verified, so that the entire stack was then ported to a fabricated microprocessor. A second compiler (for a Lisp subset) and a game-playing applications program were also written and verified. The CLI Stack was a project by Bill Bevier, Bishop Brock, Art Flatau, Warren A. Hunt, Jr., Matt Kaufmann, J Moore, Matt Wilding, and Bill Young, of Computational Logic, Inc. The CLI Verified Stack convinced us that this style of operational semantics was viable not just for program verification but for stacking and relating machines. For more details, including papers, books, dissertations, and proof scripts, start at the annotation for [bib::bhmy89] and visit the citations. [3m[Personal aside by Moore: I believe the CLI Verified Stack to be a seminal achievement in formal methods.][0m The most elaborate machine model created with Nqthm was of the Motorola MC68020, modeled by Yuan Yu [bib::yu92]. He and Boyer used that model to verify many MC68020 machine code programs produced by a variety of standard compilers. Perhaps most notably they verified the machine code for Hoare's Quick Sort and 21 of the 22 functions in the Berkeley Unix C string library (as compiled with [47mgcc -o[0m). For a shorter description of the work, see [bib::by96]. Of course, state machines are not limited to modeling computational engines. See [bib::bgm90] for a real-time control problem formalized with a ``clocked'' state machine where the ``clock'' specifies the change in the physical environment at each sampling cycle. In addition, games can often be formalized with state machines where the ``clock'' specifies opponents' moves. Strategies can be analyzed via proof. See the Nqthm script analyzing the game of Tic Tac Toe, [47mexamples/basic/tic-tac-toe.events[0m or [bib::wilding93] for a description of the verification of a winning strategy for the game of Nim. See the ACL2 scripts for playing Towers of Hanoi, [Tutorial1-Towers-of-Hanoi], [47mbooks/misc/hanoi.lisp[0m, and the Bottle Game (played in the 1995 movie [3mDie Hard 2[0m), [47mbooks/projects/die-hard-bottle-game/top.lisp[0m. But for the rest of this discussion we focus on modeling and proving properties of compute engines with ACL2. The first major external applications of ACL2 after it was developed at Computational Logic, Inc., were at Motorola Government Systems, in Scottsdale, Arizona, between 1993 and 1997, and at Advanced Micro Devices, Inc. (AMD), in Austin, Texas, in 1995. Only the first of these two projects employed operational semantics --- and it was a [3mtour de force[0m. A CLI employee, Bishop Brock, relocated to Scottsdale and embedded with a design group there to formalize the evolving design of the Motorola ``Complex Arithmetic Processor'' (CAP) digital signal processor (DSP), using the operational semantic techniques developed with Nqthm and described above. A timeline of the entire ACL2 part of the CAP DSP project may be found in [bib::bkm96]. Here is a brief description of the CAP design taken from Section 2.1 of [bib::bkm96]. The CAP design follows the `Harvard architecture', i.e., there are separate program and data memories. The design includes 252 programmer-visible data and control registers. There are six independently addressable data and parameter memories. The data memories are logically partitioned into `source' and `destination' memories; the sense of the memories may be switched under program control. The arithmetic unit includes four multiplier-accumulators and a 6-adder array. The CAP executes a 64-bit instruction word, which in the arithmetic units is further decoded into a 317-bit, low-level control word. The instruction set includes no-overhead looping constructs and automatic data scaling. As many as 10 different registers are involved in the determination of the next program counter. A single instruction can simultaneously modify well over 100 registers. In practice, instructions found in typical applications simultaneously modify several dozen registers. Finally, the CAP has a three-stage instruction pipeline which contains many programmer-visible pipeline hazards. Brock, with help from Warren Hunt, J Moore, and Matt Kaufmann, developed a bit- and cycle-accurate model of the CAP design. We believe this was the first time an entire commercial microprocessor was formally specified, see [bib::bh99]. Brock validated the design by running the ACL2 model against Motorola's SPW engineering model of the processor. For example, he compared the results of executing an end-to-end application (a QPSK modem) on both the SPW model and the ACL2 model and found the final states bit-exact for all programmer visible registers. Before turning to the verification of CAP applications programs Brock undertook the logical elimination of the CAP pipeline. He defined a predicate that syntactically detected pipeline hazards in microcode and he implemented a simpler ACL2 machine model without the pipeline. Then, following Burch and Dill's method of comparing states after flushing the pipeline via symbolic evaluation, he proved with ACL2 that the two models were equivalent [3mprovided the microcode was hazard free[0m. Then Brock, [3met al[0m, proved several microcode programs correct, again following the proof methodology we sketched in section ``Proving Theorems about M1 Programs'' of [47moperational-semantics-1__simple-example[0m, where the main subtasks were our so-called Steps 2 and 3: verify that the execution of the pipeline-free model on hazard-free microcode implements semantic function of the program, and then verify that the semantic function implements the more abstract specification. An example of the second (generally harder) step is described in [bib::bm05]. These two results could then be chained together, along with the verification (by execution) that the hazard predicate detected no hazards in the microcode and the proof of the equivalence (modulo the absence of hazards) of the pipelined and non-pipelined models, to conclude that the microcode runs correctly on the pipelined model. It is noteworthy that ACL2 executed the pipeline-free microcode interpreter several times faster than the hardware simulator could execute the SPW model --- with assurance that the answers were equivalent to the pipelined model on hazard-free microcode. In addition, the ACL2 hazard predicate, being an executable ACL2 function on microcode programs, was executed on over fifty microcode programs written by Motorola engineers and extracted from the ROM mechanically. Hazards were found in some of these. See [bib::bh99]. This can be considered another practical application of formal methods since the hazard detection predicate was formally verified to be a sufficient condition for the pipelined and non-pipelined machines to be equivalent. Unfortunately, Motorola canceled the entire CAP effort before the device was fabricated, despite the success of the formal methods component of the project. The ACL2 proof scripts are not in the ACL2 Community Books regression suite. We now move on to other operational models. In [operational-semantics-1__simple-example] (and on the ACL2 directory [47mbooks/models/jvm/m1/[0m) we describe a very simple operational definition of a machine, called M1, supporting a little stack-based arithmetic and some branch instructions. That machine was used to teach students how to formalize machines and verify their programs. M1 was the beginning of an evolutionary sequence of machines approximating an accurate model of the Java Virtual Machine. The machines in that evolutionary sequence show how we can formalize and reason about method invocation (virtual and static), return, object creation including inheritance, threads, dynamic class loading, and bytecode verification. The machines are described, with appropriate citations to papers and ACL2 books, in the final section of [operational-semantics-1__simple-example]. The use of the inductive assertion method with an operational semantics of this style is quite interesting. As noted in [bib::mmrv06], no other tools are required beyond the operational semantics and a theorem prover. It is possible for the theorem prover to use the operational semantics directly to generate and prove the ``verification conditions'' one gets by exploring all possible program paths between assertions in the code. One can use the method to prove either partial or total correctness, the former meaning ``correct if it terminates'' and the latter meaning ``terminating and correct at termination.'' The most complicated machine formalized (as of 2024) with ACL2 is the x86 instruction set architecture. The model evolved from simpler models, exploiting lessons learned from earlier Nqthm and ACL2 work. In the case of x86, the ``toy'' was the y86 as informally described in [bib::boh03]. The ACL2 directory [47mbooks/models/y86/[0m contains several models of the 32-bit y86 described in the First Edition of [bib::boh03]. In particular, see the ACL2 book [47mbooks/models/y86/y86-basic/y86/y86.lisp[0m, by Warren Hunt, for the model. For a proof of correctness of Sean Anderson's bit twiddling ``population count'' in y86 machine code, see the ACL2 book [47mbooks/models/y86/y86-basic/py86/popcount.lisp[0m. The proof of that particular straightline piece of code is just by symbolic evaluation and the ACL2 verified ``bit-blasting'' solver [gl] by Sol Swords. From the y86, the model of the x86 evolved through several iterations reported in [bib::hk12], [bib::ghk13], and [bib::ghkg14], to Shilpi Goel's monumental x86 model [bib::goel16] and [bib::ghk17]. The model specifies over 400 x86 instructions and the model includes architectural features like segmentation and paging. It can be executed in either of two modes. When running in the application-program level, it executes about 3.3 million x86 instructions per second. When running in the system-level mode it executes about 912,000 x86 instructions per second. The model has been validated extensively against actual x86 hardware, which is the reason so much attention has been paid to execution efficiency. X86 machine code programs have been verified. See [bib::goel16] and [bib::ghk17]. Proof Methods and Tools The paper [bib::moore99b] shows how we can reason about a system involving multiple processes interacting with a shared memory. The paper describes two operational models, one in which the model switches between multiple processes according to an ``oracle'' and the other which models just a single process but in which the memory changes ``spontaneously.'' The two models are then related by proved lemmas so that one can switch back and forth between views. The lemmas are used to verify a safety property (using one model) and a progress property (using the other). All the proofs are carried out via the clock-based methodology. We have focused on the clock-based proof methodology. But an advantage of creating ``toy'' models is that it is easy to explore other proof methodologies and then try to apply them to larger models. The papers [bib::rm04] and [bib::rhmm07] establish that the clock-function approach to verification is equivalent to the use of inductive assertions and to stepwise invariants. In fact, ACL2 tools are provided for converting between clock-based proofs and inductive assertion-style proofs. The paper [bib::sawada00] describes the modeling and verification of a pipelined machine. The paper [bib::manolios00] shows an alternative method based on Well-founded Equivalence Bisimulations. Briefly, it introduces a notion of correctness that implies that the instruction set architecture and micro-architecture machines have the same observable infinite paths, up to stuttering. The paper [bib::sh98] deals with a machine with precise exceptions and speculative execution. An ACL2 tool to help manage states in operational models is described in [bib::moore15] and a tool for determining whether two symbolic terms representing machine addresses may be equal is described in [bib::moore17]. These tools are available among the ACL2 Community Books. A tool for deriving the meaning of and clock function for a piece of code from the code and the operational semantics model is described in the ACL2 file [47mbooks/projects/codewalker/README[0m. Quick Index to Related Topics * [operational-semantics] * [operational-semantics-1__simple-example] * operational-semantics-2__other-examples --- current topic * [operational-semantics-3__annotated-bibliography] * [operational-semantics-4__how-to-find-things] * [operational-semantics-5__history-etc]") (operational-semantics-3__annotated-bibliography (operational-semantics) "Annotated bibliography for operational-semantics This topic provides proper bibliographic citations to the work mentioned in the ACL2 documentation topic [operational-semantics] and its subtopics. Each citation (e.g., [bib::bhmy89]) is a link, at which you may find additional information about the publication and its relation to operational semantics. When Nqthm or ACL2 files are mentioned you will have to dereference those names following the instructions in [operational-semantics-4__how-to-find-things]. Quick Index to Related Topics * [operational-semantics] * [operational-semantics-1__simple-example] * [operational-semantics-2__other-examples] * operational-semantics-3__annotated-bibliography --- current topic * [operational-semantics-4__how-to-find-things] * [operational-semantics-5__history-etc] Subtopics [Bib::bevier87] W. R. Bevier, [3mVerified Operating System Kernel[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/bevier.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1987. [31;1mRelevance:[0m first verified operating system and a component of the CLI stack [Bib::bgm90] R. S. Boyer, M. W. Green, and J S. Moore, ``{The Use of a Formal Simulator to Verify a Simple Real Time Control Program | http://www.cs.utexas.edu/users/moore/publications/controller.pdf}'', in W.H.J. Feijen, A.J.M. van Gasteren, D. Gries, and J. Misra, editors, [3mBeauty is Our Business: A Birthday Salute to Edsger W. Dijkstra[0m, Springer-Verlag Texts and Monographs in Computer Science, pp. 54-66, 1990. [31;1mRelevance:[0m operational semantics modeling a hybrid physical/digital system [Bib::bh97] B. Brock and W. A. Hunt, Jr., ``{Formally Specifying and Mechanically Verifying Programs for the Motorola Complex Arithmetic Processor DSP | https://ieeexplore.ieee.org/document/628846}'', in [3m1997 IEEE International Conference on Computer Design[0m, IEEE Computer Society, pp. 31-36, October, 1997. [31;1mRelevance:[0m first public announcement of the CAP DSP formalization (this short article was superseded by [bib::bh99]) [Bib::bh99] B. Brock and W. A. Hunt, Jr., ``{Formal Analysis of the Motorola CAP DSP'' | https://link.springer.com/chapter/10.1007/978-1-4471-0523-7_5#citeas}, in M. Hinchey and J. Bowen, editors, [3mIndustrial-Strength Formal Methods[0m, Springer-Verlag, pp. 81-115, 1999. [31;1mRelevance:[0m first industrial application of operational semantics with ACL2 and the first complete formal specification of a commercially designed microprocessor [Bib::bhmy89] W.R. Bevier, W.A. Hunt, Jr., J S. Moore, and W.D. Young, [3mSpecial Issue on System Verification[0m, [3mJournal of Automated Reasoning[0m, [31;1m5[0m(4), pp. 409-530, 1989. [31;1mRelevance:[0m Computational Logic Inc. (CLI) Verified Stack --- a seminal achievement in formal methods and operational semantics [Bib::bkm96] B. Brock, M. Kaufmann, and J S. Moore, ``{ACL2 Theorems about Commercial Microprocessors | http://www.cs.utexas.edu/users/moore/publications/bkm96.pdf}'', in M. Srivas and A. Camilleri, editors, [3mFormal Methods in Computer-Aided Design (FMCAD'96)[0m, Springer-Verlag, LNCS [31;1m1166[0m, pp. 275-293, doi 10.1007/BFb0031816, 1996. [31;1mRelevance:[0m early (mid-1990s) applications of ACL2 in industry (Motorola CAP DSP via operational semantics and the AMD K5 FDIV via a shallow embedding) [Bib::bm05] B. Brock and J S. Moore, ``{A Mechanically Checked Proof of a Comparator Sort Algorithm | https://www.cs.utexas.edu/~moore/publications/csort/main.pdf}'', in M. Broy, J. Gruenbauer, D. Harel, and C. A. R. Hoare, editors, [3mEngineering Theories of Software Intensive Systems[0m, Springer NATO Science Series II, [31;1m195[0m, pp. 141-175, 2005. [31;1mRelevance:[0m an example of proving that the state transformation effected by running a CAP model on commercial microcode implements the high level specification [Bib::bm73] R. S. Boyer and J S. Moore, ``{Proving Theorems about LISP Functions | https://www.cs.utexas.edu/~moore/publications/bm-ijcai-73.pdf}'', in [3mProceedings of the Third International Joint Conference on Artificial Intelligence (IJCAI)[0m, Stanford University, pp. 486-493, 1973. [31;1mRelevance:[0m journal article about the Edinburgh Pure Lisp Theorem Prover (PLTP) [Bib::bm79] R. S. Boyer and J S. Moore, [3m{A Computational Logic | https://archive.org/details/acl_20240626}[0m, Academic Press, 1979. [31;1mRelevance:[0m implementation details of the prover that became Nqthm [Bib::bm80] R. S. Boyer and J S. Moore, ``{On Why It Is Impossible to Prove that the BDX930 Dispatcher Implements a Time-Sharing System | https://www.cs.utexas.edu/~moore/publications/BDX930-Report-1978-81.pdf}'', in Sections 14 and 15 of P.M. Melliar-Smith, K. Levitt, R. Schwartz, R. Boyer, J Moore, D. Hare, R. Shostak, M. Moriconi, M. Green, and W.D. Elliot, [3mInvestigation, Development, and Evaluation of Performance Proving for Fault-Tolerant Computer Final Report, covering the period September 1978 to June 1982[0m, SRI, July 1982. [31;1mRelevance:[0m operational semantic model of (a fragment) of a 1970s flight control computer [Bib::bm96] R. S. Boyer and J S. Moore, ``{Mechanized Formal Reasoning about Programs and Computing Machines | https://www.cs.utexas.edu/~moore/publications/bm96.pdf}'', in R. Veroff, editor, [3mAutomated Reasoning and Its Applications: Essays in Honor of Larry Wos[0m, MIT Press, 1966. [31;1mRelevance:[0m the basic Nqthm/ACL2 style of operational semantics as a book chapter [Bib::bm97] R. S. Boyer and J S. Moore, [3m{ A Computational Logic Handbook, Second Edition | https://drive.google.com/file/d/0B2yFYLn0Spf1TloxMjNxdzBWN1E/}[0m, Academic Press, New York, 1997. [31;1mRelevance:[0m Nqthm user's manual [Bib::boh03] R. E. Bryant and D. R. O'Hallaron, [3mComputer Systems: A Programmer's Perspective[0m, Prentice-Hall. First edition 2003, second edition 2011, third edition 2015. [31;1mRelevance:[0mone of the most popular and influential textbooks on modern computer systems; its relevance here is that the book introduced the y86. [Bib::by96] R. S. Boyer and Y. Yu, ``{Automated Proofs of Object Code for a Widely Used Microprocessor | https://dl.acm.org/doi/10.1145/227595.227603}'', [3mJournal of the ACM[0m [31;1m43[0m(1), pp. 166-192, January, 1996. [31;1mRelevance:[0m operational model of the Motorola 68020 and verification of object code generated by commercial compilers [Bib::flatau92] A. D. Flatau [3mA verified implementation of an applicative language with dynamic storage allocation[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/flatau.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1992 (minus some appendices). [31;1mRelevance:[0m a second verified compiler hosted on the CLI Verified Stack [Bib::ghk13] S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Abstract Stobjs and Their Application to ISA Modeling | http://eptcs.org/content.cgi?ACL22013}'', in R. Gamboa and J. Davis, editors, [3mProceedings of ACL2 Workshop 2013[0m, Electronic Proceedings in Theoretical Computer Science, Volume 114, pp. 54-69, 2013. [31;1mRelevance:[0m an ACL2 feature introduced to support operational semantic models [Bib::ghk17] S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Engineering a Formal, Executable x86 ISA Simulator for Software Verification | https://link.springer.com/chapter/10.1007/978-3-319-48628-4_8}'', in M. Hinchey, J. P. Bowen, and E.-R. Olderog, editors, [3mProvably Correct Systems[0m Springer, pp. 173-209, 2017. [31;1mRelevance:[0m operational model of the x86 at both the user- and system-level and code proofs [Bib::ghkg14] S. Goel, W. A. Hunt, Jr., M. Kaufmann, and S. Ghosh, ``{Simulation and Formal Verification of x86 Machine-Code Programs that Make System Calls | http://www.cs.utexas.edu/users/hunt/FMCAD/FMCAD14/proceedings/18_goel.pdf}'', in [3mProceedings of Formal Methods in Computer-Aided Design (FMCAD'14)[0m, pp. 91-98, 2014. [31;1mRelevance:[0m modeling and verifying machine-code programs that exhibit non-determinism [Bib::goel16] S. Goel, [3m{Formal Verification of Application and System Programs Based on a Validated x86 ISA Model | https://repositories.lib.utexas.edu/server/api/core/bitstreams/858b2f9b-5532-4b2a-bed1-fb889a265f6c/content}[0m, University of Texas at Austin, Ph.D. dissertation, 2016. [31;1mRelevance:[0m details of the x86 model [Bib::hb92] W. A. Hunt, Jr. and B. Brock, ``{A Formal HDL and its use in the FM9001 Verification | https://royalsocietypublishing.org/doi/abs/10.1098/rsta.1992.0024}'', [3mProceedings of the Royal Society[0m, North Holland, April, 1992. [31;1mRelevance:[0m a formalized hardware description language and the verification of a fabricated microprocessor described with it; this describes three foundational achievements in formal methods [Bib::hk12] W. A. Hunt, Jr. and M. Kaufmann, ``{Towards a Formal Model of the x86 ISA | http://apps.cs.utexas.edu/tech_reports/reports/tr/TR-2075.pdf}'', University of Texas at Austin, Computer Science Department Technical Report TR-12-07, May, 2012. [31;1mRelevance:[0m a ``toy model'' of the x86, built as a warm up exercise [Bib::hkms17] W. A. Hunt, Jr., M. Kaufmann, J S. Moore, and A. Slobodova, ``{Industrial hardware and software verification with ACL2 | https://royalsocietypublishing.org/doi/10.1098/rsta.2015.0399}'' in P. Gardner, P. O'Hearn, M. Gordon, G. Morrisett and F. B. Schneider, editors), [3mVerified Trustworthy Software Systems[0m, Philosophical Transactions A, Royal Society Publishing, [31;1m374[0m, DOI 10.1098/rsta.2015.0399, September, 2017. [31;1mRelevance:[0m how ACL2 is used in industry, and why [Bib::hunt85] W. A. Hunt, Jr., [3mFM8501: A Verified Microprocessor[0m, University of Texas at Austin, Ph.D. dissertation, 1985 (also published as a book of the same title, Springer-Verlag LNAI 795, Heidelberg, 1994. [31;1mRelevance:[0m first microprocessor verified at the gate level and the bottommost component of the CLI stack [Bib::kmm00a] M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: An Approach | https://www.cs.utexas.edu/~moore/publications/acl2-books/car/index.html}[0m, Kluwer Academic Publishers, 2000. [31;1mRelevance:[0m introduction to ACL2 [Bib::kmm00b] M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: ACL2 Case Studies | https://www.cs.utexas.edu/~moore/publications/acl2-books/acs/index.html}[0m, Kluwer Academic Publishers, 2000. [31;1mRelevance:[0m tutorial examples of ACL2 applications [Bib::liu06] H. Liu, [3m{Formal Specification and Verification of a JVM and its Bytecode Verifier | https://www.cs.utexas.edu/~moore/publications/liu-dissertation.pdf}[0m, University of Texas at Austin, Ph.D. dissertation, 2006 [31;1mRelevance:[0m most complete ACL2 model of the JVM [Bib::manolios00] P. Manolios, ``{Correctness of Pipelined Machines | https://dl.acm.org/doi/10.5555/646186.683220}'', in W. A. Hunt, Jr and S. D. Johnson, editors, [3mFormal Methods in Computer-Aided Design (FMCAD 2000)[0m, Springer-Verlag LNCS [31;1m1954[0m, Heidelberg, pp. 161-178, 2000. [31;1mRelevance:[0m an alternative approach to verifying operational models of a pipelined machine [Bib::mccarthy62] J. McCarthy, ``{Towards a mathematical science of computation | http://jmc.stanford.edu/articles/towards/towards.pdf},'' [3mProceedings of the Information Processing Cong. 62[0m, North-Holland, Munich, West Germany, pp. 21-28, August, 1962. [31;1mRelevance:[0m a seminal paper in the history of formal operational semantics [Bib::mmrv06] J. Matthews, J S. Moore, S. Ray and D. Vroon, ``{ Verification Condition Generation via Theorem Proving | http://ece.ufl.edu/wp-content/uploads/sites/119/publications/lpar06.pdf}'', in [3mProceedings of 13th International Conference on Logic for Programming, Artificial Intelligence, and Reasoning (LPAR 2006)[0m, LNCS [31;1m4246[0m, pp. 362-376, 2006. [31;1mRelevance:[0m how to conduct inductive assertion-style proofs from an operational semantics without a verification condition generator [Bib::moore03a] J S. Moore, ``{Proving Theorems about Java and the JVM with ACL2 | https://www.cs.utexas.edu/~moore/publications/marktoberdorf-02/main_final.pdf}'', in M. Broy and M. Pizka, editors, [3mModels, Algebras and Logic of Engineering Software[0m, IOS Press, Amsterdam, pp. 227-290, 2003. [31;1mRelevance:[0m M5: a JVM model with method invocation, classes, and threads, with some example proofs including about mutual-exclusion [Bib::moore03b] J S. Moore, ``{ Inductive Assertions and Operational Semantics | https://www.cs.utexas.edu/~moore/publications/trecia/long.pdf}'', in D. Geist, editor, CHARME 2003,, Springer Verlag, LNCS [31;1m2860[0m, pp. 289-303, 2003. [31;1mRelevance:[0mThe URL above points to a longer version of the paper presented at CHARME. Using a subset of M5 the paper shows how partial symbolic evaluation of a program can be used to generate and prove verification conditions produced from inductive assertions [Bib::moore14] J S. Moore, ``{ Proof Pearl: Proving a Simple Von Neumann Machine Turing Complete | https://www.cs.utexas.edu/~moore/publications/m1-is-turing-equiv.pdf}'' in G. Klein and R. Gamboa, editors, [3mInteractive Theorem Proving, ITP 2014[0m, Springer LNCS [31;1m8558[0m, doi.org/10.1007/978-3-319-08970-6_26, 2014. [31;1mRelevance:[0mM1 can compute anything a Turing machine can. (The paper ought to be re-titled ``Proving M1 Turing Equivalent.'') [Bib::moore15] J S. Moore, ``{ Stateman: Using Metafunctions to Manage Large Terms Representing Machine States | https://www.cs.utexas.edu/~moore/publications/stateman.pdf},'' in M. Kaufmann and D. Rager, editors, [3mProceedings of the 13th International Workshop on the ACL2 Theorem Prover[0m, EPTCS, [31;1m192[0m, pp. 93-109, 2015. [31;1mRelevance:[0m some ACL2 tools for managing the terms representing states of operational models [Bib::moore17] J S. Moore, ``{ Computing Verified Machine Address Bounds during Symbolic Exploration of Code | https://www.cs.utexas.edu/~moore/publications/ainni.pdf},'' in J. Bowen, H. Langmaack and E.-R. Olderog, editors, [3mProvably Correct Systems[0m, Springer, pp. 151-172, 2017. [31;1mRelevance:[0m an ACL2 tool for determining whether two symbolic machine addresses may be equal [Bib::moore19] J S. Moore, ``{Milestones from The Pure Lisp Theorem Prover to ACL2 | https://doi.org/10.1007/s00165-019-00490-3}'', [3mFormal Aspects of Computing[0m, Springer, DOI https://doi.org/10.1007/s00165-019-00490-3, 2019. [31;1mRelevance:[0m how the Edinburgh Pure Lisp Theorem Prover (PLTP) evolved into ACL2 [Bib::moore73] J S. Moore, ``{Computational Logic: Structure Sharing and Proof of Program Properties | http://www.era.lib.ed.ac.uk/handle/1842/2245}, University of Edinburgh, Ph.D. dissertation, 1973. [31;1mRelevance:[0m details of the Edinburgh Pure Lisp Theorem Prover (PLTP) [Bib::moore96] J S. Moore, [3mPiton: A Mechanically Verified Assembly-Level Language[0m, J S. Moore, Automated Reasoning Series, Kluwer Academic Publishers, 1996. [31;1mRelevance:[0m verified assembler/linker/loader and a component of the CLI Verified Stack [Bib::moore99a] J S. Moore, ``{Proving Theorems about Java-like Byte Code | https://www.cs.utexas.edu/~moore/publications/tjvm/main.pdf},'' in E.-R. Olderog and B. Steffen, editors, [3mCorrect System Design -- Recent Insights and Advances[0m, LNCS [31;1m1710[0m, pp. 139-162, 1999. [31;1mRelevance:[0m M2: a JVM model similar to M1 but with method invocation (i.e., subroutine call) [Bib::moore99b] J S. Moore, ``{A Mechanically Checked Proof of a Multiprocessor Result via a Uniprocessor View | https://www.cs.utexas.edu/~moore/publications/multi-v-uni.pdf}'', J S. Moore, [3mFormal Methods in System Design[0m, [31;1m14[0m(2), pp. 213-228, March, 1999. [31;1mRelevance:[0m proving a relationship between two state machines [Bib::mp02] J S. Moore and G. Porter, ``{The Apprentice Challenge | https://www.cs.utexas.edu/~moore/publications/m5/apprentice.pdf}'', [3mACM TOPLAS[0m, [31;1m24[0m(3), pp. 1-24, May, 2002. [31;1mRelevance:[0m M5 and mutual-exclusion via monitors: an unbounded number of JVM threads competing for access to a shared resource [Bib::mp67] J. McCarthy and J. Painter, ``{Correctness of a Compiler for Arithmetic Expressions | http://jmc.stanford.edu/articles/mcpain/mcpain.pdf}'', [3mProceedings of Symposia in Applied Mathematics[0m, [31;1m19[0m, American Mathematical Society, 1967. [31;1mRelevance:[0m an early (perhaps the first) compiler proof [Bib::plotkin04a] G. D. Plotkin, ``{ A Structural Approach to Operational Semantics | https://homepages.inf.ed.ac.uk/gdp/publications/sos_jlap.pdf}'', Computer Science Department, Aarhus University, Denmark, DAIMI FN-19, 1981 (reprised in a 2004 submission to the [3mThe Journal of Logic and Algebraic Programming[0m). [31;1mRelevance:[0m Plotkin's introduction of the term ``structural operational semantics'' [Bib::plotkin04b] G. D. Plotkin, ``{ The origins of structural operational semantics | https://www.sciencedirect.com/science/article/pii/S1567832604000268}'', [3mThe Journal of Logic and Algebraic Programming[0m, [31;1m60[0m and [31;1m61[0m, pp. 3-15, July and December 2004. [31;1mRelevance:[0m an interesting historical account of the most popular (non-ACL2) approach to operational semantics [Bib::rhmm07] S. Ray, W. A. Hunt, Jr., J. Matthews, and J S. Moore, `{A Mechanical Analysis of Program Verification Strategies | https://link.springer.com/article/10.1007/s10817-008-9098-1},'' [3mJournal of Automated Reasoning[0m, [31;1m40[0m(4), pp. 245-269, May, 2008. [31;1mRelevance:[0m stepwise invariants, clock functions, and inductive assertion proof styles are all equivalent [Bib::rm04] S. Ray and J S. Moore, ``{Proof Styles in Operational Semantics | https://www.ece.ufl.edu/wp-content/uploads/sites/119/publications/fmcad04.pdf},'' in A. J. Hu and A. K. Martin, editors, [3mFormal Methods in Computer-Aided Design (FMCAD-2004)[0m, Springer, LNCS [31;1m3312[0m, pp. 67-81, 2004. [31;1mRelevance:[0m ACL2 tools for transforming inductive assertion-style proofs to clock function style and vice versa [Bib::sawada00] J. Sawada, ``Verification of a Simple Pipelined Machine Model,'' in M. Kaufmann, P. Manolios, J S. Moore, editors, [3mComputer-Aided Reasoning: ACL2 Case Studies[0m, Kluwer Academic Publishers, Chapter 9, pp. 137-150, 2000. (See also pubs::pubs-books.) [31;1mRelevance:[0m operational model of a pipelined machine and its verification [Bib::sh98] J. Sawada and W. A. Hunt, Jr, ``{Processor Verification with Precise Exceptions and Speculative Execution | https://link.springer.com/chapter/10.1007/BFb0028740}'', in A. J. Hu and M. Y. Vardi, editors, [3mComputer Aided Verification, (CAV '98)[0m, Springer-Verlag LNCS [31;1m1427[0m, Heidelberg, pp. 135-146, 1998. [31;1mRelevance:[0m proof method for dealing with exceptions and speculative execution [Bib::wilding92] M. M. Wilding, [3mMachine-checked real-time system verification[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/wilding.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1996. [31;1mRelevance:[0m a non-trivial applications program on the CLI Verified Stack [Bib::wilding93] M. M. Wilding, ``{A Mechanically Verified Application for a Mechanically Verified Environment | https://link.springer.com/content/pdf/10.1007/3-540-56922-7_22}, in C. Courcoubetis, editor, [3mProceedings of Computer-Aided Verification -- CAV '93[0m, Springer-Verlag, LNCS [31;1m697[0m, Heidelberg, pp. 268-279, DOI:10.1007/3-540-56922-7_22, 1993. [31;1mRelevance:[0m functional correctness and resource utilization of a Nim-playing program on the CLI Verified Stack [Bib::young88] W. D. Young, [3mA Verified Code Generator for a Subset of Gypsy[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/young.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1988. [31;1mRelevance:[0m a verified compiler (from a small Pascal-like subset to an assembly language) and a component of the CLI Verified Stack [Bib::yu92] Y. Yu, [3mAutomated proofs of object code for a widely used microprocessor[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/yu.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1992. [31;1mRelevance:[0m details of the operational model of the Motorola 68020") (operational-semantics-4__how-to-find-things (operational-semantics) "Citation conventions for doc operational-semantics In the documentation topic [operational-semantics] and its supporting subtopics, references to published books and papers appear as ordinary documentation topics, except all the labels are in the "BIB" package, e.g., [bib::mccarthy62] or [bib::kmm00a]. When finding them with the [47m:[0m[47m[doc][0m keyword command or in the [ACL2-doc] Emacs-based browser, you must type the ``bib::'' prefix. When finding them in the ``Jump to'' box of your browser you must not include the ``bib::'' prefix. In [operational-semantics] and its supporting subtopics we also make frequent reference to Nqthm and ACL2 directories and proof scripts, such as [47mexamples/hunt/fm8501.events[0m and [47mbooks/projects/x86isa/[0m. In this topic we explain how to dereference those citations to find the directory or file we mean. By the way, the active development of Nqthm ended in 1992, three years after ACL2 development began. For about 10 years Nqthm and ACL2 were both in use. Since then Nqthm has been maintained by Boyer and most of its proof scripts are not only still available but can still be processed. Documentation for Nqthm may be found in [bib::bm97]. The Nqthm source code and proof scripts are available in two places, ftp://ftp.cs.utexas.edu/pub/boyer/nqthm/nqthm-1992/ and https://drive.google.com/drive/folders/18z-uwg8E_3NxIijLoxYE-_NS-klqYI7R While it is possible to download individual files from these sites, we recommend that you download the entire [47mnqthm-1992[0m distribution as follows. In particular, download the gzipped tar file: ftp://ftp.cs.utexas.edu/pub/boyer/nqthm/nqthm-2nd-edition.tar.gz to a directory where you want the Nqthm source code and regression suite, connect to that directory, and extract the files as follows. tar xfz nqthm-2nd-edition.tar.gz That will create the directory [47mnqthm-1992/[0m. You do not have to build the Nqthm image or do a regression if all you want to do is inspect either the Nqthm source code (which consists of the files [47mnqthm-1992/*.lisp[0m) or the files in the regression suite ([47mnqthm-1992/examples/[0m). You can just explore the relevant files locally. If you want to build Nqthm and do a regression, see the Nqthm installation instructions in [47mnqthm-1992/README[0m. The ACL2 system, as it stood in 2000, is documented in two textbooks; see pubs::pubs-books. These books are a good place for a beginner to start, even though some of the material is out-of-date. Up-to-date user-level [documentation] of ACL2 is available online as described in the User's Manuals link on the homepage (below), and a wealth of information is available there. Some of it is organized for the experienced user trying to get information about a particular feature, but there is a documentation topic, [start-here], that provides many starting points for the beginning ACL2 user. Source code, input files, [installation] instructions, extensive online documentation and other material is available from the {ACL2 homepage | http://www.cs.utexas.edu/users/moore/acl2/}: https://www.cs.utexas.edu/~moore/acl2/ That page provides instructions for obtaining the latest ACL2 numbered release. However, many ACL2 users obtain an up-to-date {snapshot of ACL2 from GitHub | https://github.com/acl2/acl2}: https://github.com/acl2/acl2 As with Nqthm, to explore ACL2 source files or prover input files we recommend that you see [installation] and follow the instructions there. That includes placing a copy of the latest sources and input scripts (but not prover output) in a directory on your computer. The filenames suffixed with [47m.lisp[0m at the top-level of that directory constitute the ACL2 source code. The ACL2 regression suite consists of thousands of files called ``[books]'' and are available under the [47mbooks/[0m subdirectory. So, for example, you'll find a toy model of the JVM at [47mbooks/models/jvm/m1/m1.lisp[0m. If you want to see proofs you must build ACL2 on your machine and run a full regression as described in the [installation] instructions. Quick Index to Related Topics * [operational-semantics] * [operational-semantics-1__simple-example] * [operational-semantics-2__other-examples] * [operational-semantics-3__annotated-bibliography] * operational-semantics-4__how-to-find-things --- current topic * [operational-semantics-5__history-etc]") (operational-semantics-5__history-etc (operational-semantics) "A quick history of our style of modeling state machines As informally explained in [operational-semantics] and illustrated in [operational-semantics-1__simple-example] and [operational-semantics-3__annotated-bibliography], the common ACL2 style in which state machines are modeled involves representing the relevant part of the state as an ACL2 object, defining a single-step function for computing state transitions, and then defining a total recursive run function for iterating the step function until it ``halts'' or some specified number of steps has been taken. This approach to operational semantics is different from ``structural operational semantics'' described by Plotkin in his 1981 paper ``A Structural Approach to Operational Semantics'' (see [bib::plotkin04a]). Plotkin formalized machines operationally but as inference rules (reminiscent of Hoare logic). See also [bib::plotkin04b], where Plotkin elaborates on the origins of that approach. Furthermore, the origins paper appears in a two volume special issue of [3mThe Journal of Logic and Algebraic Programming[0m which contains many other papers on structural operational semantics. To distinguish the approach taken commonly in the ACL2 community from structural operational semantics we might call it ``ACL2-style'' operational semantics. But its only connection to ACL2 is that ACL2 happens to be the logic in which our models are expressed. Other settings supporting recursion and induction could also be used. Boyer and Moore used this approach in the 1970s, inspired in part by McCarthy's seminal papers (``Recursive Functions of Symbolic Expressions and Their Computation by Machine,'' 1960, ``A Basis for a Mathematical Theory of Computation,'' 1963, and ``Correctness of a Compiler for Arithmetic Expressions,'' with James Painter, 1967). But we would be hard-pressed to attribute this style of operational semantics even to McCarthy. In the first place, mathematicians have used formal state machines at least since since Goedel's 1931 incompleteness paper: he modeled proofs as objects (specifically, integers) and defined a non-terminating function that stepped through all possible proofs looking for a particular proof. In the second place, machine designers and programmers have been writing software to emulate other machines for almost as long as computers have existed. ACL2 is just another programming language in which such software can be written --- albeit one that comes with a logical foundation and theorem prover allowing one to reason about programs running on the machine or even properties of the machine itself. In fact, such operational semantics models played an important role in the evolution of ACL2. ACL2 evolved from earlier theorem provers by Boyer and Moore. Those earlier provers were the Edinburgh Pure Lisp Theorem prover, aka PLTP (see [bib::bm73] and [bib::moore73]), (1971--73), Thm (1974--79), and Nqthm (1980--95) (see [bib::bm97]). The dates are approximate. Boyer and Moore began working on ACL2 on August 14, 1989 and the first ACL2 proof (associativity of [47mappend[0m) was done on November 3, 1989. Matt Kaufmann officially joined the ACL2 development team in August, 1993, although he had become an invaluable contributor years before that. See ``[47m; Commemorative Plaque[0m'' in the ACL2 source file [47mprove.lisp[0m. For a description of the evolution from PLTP, through Thm, and Nqthm, to ACL2, including proper bibliographic citations, see [bib::moore19]. Boyer and Moore's first foray into operational semantics for a computing machine shows up in Chapter 17 of [bib::bm79] where they used Thm to prove a version of the McCarthy-Painter theorem verifying an expression compiler for a simple machine [bib::mp67]. At the time, Boyer and Moore were employed at SRI and were working part-time on the Software Implemented Fault Tolerance (SIFT) project. Their task was to verify that a certain small fragment of machine code for the Bendix 930 (BDX930) flight-control computer implemented a simple time-sharing system. (Personal aside by J Moore: Having such an ambitious goal, in 1979, astounds me in 2024, but it was a side-effect of youthful energy combined with naivete and the excitement (and hype?) of that early period in the history of mechanized formal methods.) To attack the problem they formalized the necessary subset of the BDX930 instruction set operationally. But Thm was not able to process the ``large'' system of definitions (30 pages). The problem was, in part, due to the representation of logical constants in Thm's implementation. E.g., the logical constant [47m1[0m was represented as the ground term [47m(add1 (zero))[0m, and the logical constant pair containing [47m1[0m in its [47mcar[0m and [47m2[0m in its [47mcdr[0m was the ground term: (cons (add1 (zero)) (add1 (add1 (zero)))) So Thm was rewritten to represent the constant [47m1[0m as [47m(quote 1)[0m and the constant pair above as (quote (1 . 2)). This required a major rewrite (affecting virtually every routine in the system that inspected terms) and was a significant step toward Nqthm. (Note: another formalization problem pushed Boyer and Moore in the same direction: the desire to support verified ``metafunctions,'' which required the formalization in the logic of a weak interpreter, [47mV&C$[0m, for the logic.) The BDX930 model was admitted to the improved ``Thm'' (now more like Nqthm) but Boyer and Moore then realized that the machine code implemented a time-sharing system only if every SIFT process, when compiled from the native Pascal, respected a bevy of unstated invariants on the machine code. They wrote a ``minority report'' explaining this. That report was contained in Sections 14 and 15 of the SIFT final report for the period September 1978 to June 1982. Section 14 describes the problem and Section 15 lists the 30 page BDX930 model. See [bib::bm80], which has the provocative title ``WHY IT IS IMPOSSIBLE TO PROVE THAT THE BDX930 DISPATCHER IMPLEMENTS A TIME-SHARING SYSTEM.'' Boyer and Moore left SRI for the University of Texas at Austin in 1981 and Nqthm was fully formed shortly thereafter. The combination of Nqthm and some brilliant students led to a remarkable string of projects, including the FM8501 (and later the FM9001), the Computational Logic, Inc., verified stack, and the Motorola 68020 model and its use in the emulation and verification of machine code produced from the Berkeley C String Library by [47mgcc -o[0m. (See [operational-semantics-3__annotated-bibliography] for proper citations.) These projects pushed Nqthm to its limits: models were large and running them as software prototypes of the compute engines they modeled was relatively slow. That spurred Boyer and Moore to abandon the home grown Lisp supported by Nqthm and build a theorem prover for a subset of Common Lisp: ACL2. That way, operational models were just Common Lisp functions and could be run at Common Lisp speeds. Of course, pressure on Kaufmann and Moore to improve ACL2 to provide higher capacity and more efficiency to load and process models of commercial processors continues to this day. See Sections 8 and 9 of [bib::hkms17]. Among many other changes made in response to industrial requests, many of which relate to operational models, are such things the invention of guards as an extralogical device to ensure that compiled code complies with the axioms, support for inlining and other directives to the compiler, the [47m[mbt][0m directive, performance improvements in certification and the inclusion of certified files into a session, congruent single-threaded objects, nested single-threaded objects, patterned congruence rules, and an attachment mechanism for stobjs so that different memory models can be executed. See [stobj]s. Quick Index to Related Topics * [operational-semantics] * [operational-semantics-1__simple-example] * [operational-semantics-2__other-examples] * [operational-semantics-3__annotated-bibliography] * [operational-semantics-4__how-to-find-things] * operational-semantics-5__history-etc --- current topic") (optimize (pointers) "See [declare].") (or (basics acl2-built-ins) "Disjunction [47mOr[0m is the macro for disjunctions. [47mOr[0m takes any number of arguments and returns the first that is non-[47mnil[0m, or [47mnil[0m if there is no non-[47mnil[0m element. (Note: If you are seeking documentation for the [47m:or[0m hint, see [hints].) In the ACL2 logic, the macroexpansion of [47m(or x y)[0m is an [47mIF[0m term that appears to cause [47mx[0m to be evaluated twice: ACL2 !>:trans (or x y) (IF X X Y) => * ACL2 !> If [47mx[0m were replaced by an expression whose evaluation takes a long time, then such an expansion would be inefficient. However, don't be fooled: you can expect Common Lisp implementations to avoid this problem, say by generating a new variable, for example: ACL2 !>:q ; Exit the ACL2 loop and go into raw Common Lisp Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ACL2>(macroexpand '(or x y)) (LET ((#:G5374 X)) (IF #:G5374 #:G5374 Y)) T ACL2> [47mOr[0m is a Common Lisp macro. See any Common Lisp documentation for more information. [31;1mMacro: [0m<or> (defmacro or (&rest args) (or-macro args)) [31;1mFunction: [0m<or-macro> (defun or-macro (lst) (declare (xargs :guard t)) (if (consp lst) (if (consp (cdr lst)) (list 'if (car lst) (car lst) (or-macro (cdr lst))) (car lst)) nil))") (ordinals (miscellaneous) "Ordinals in ACL2 Ordinals are used in ACL2 for proving termination in the admission of recursive function definitions. For a proof that the ACL2 ordinals are well-founded, see [proof-of-well-foundedness]. The representation of ordinals changed in ACL2 Version_2.8, and is due to Pete Manolios and Daron Vroon. They have also defined algorithms for ordinal arithmetic, created a library of theorems to reason about ordinal arithmetic, and written the rest of this documentation in order to explain this change. We thank them for their efforts. Although they have provided the implementation and even modified the community books as needed, we have looked over their work and are maintaining it (and this documentation); if there are any bugs, they should be considered ours (Matt Kaufmann and J Moore). A book is included for compatibility with the representation before Version_2.8. For books that contain events relying on the previous ordinal implementation, insert the following lines before the first such event: (include-book "ordinals/e0-ordinal" :dir :system) (set-well-founded-relation e0-ord-<) The new ordinal representation is based on a slightly different version of Cantor Normal Form than that used by the old ordinals. An advantage of the new representation is that it is exponentially more succinct than the old representation. While pre-Version_2.8 ACL2 versions provided built-in functions for checking if an object is an ordinal and for comparing two ordinals, they did not provide support for reasoning about and constructing ordinals. The community books directory [47mbooks/ordinals[0m provides such support. First, it provides efficient algorithms for ordinal arithmetic (including addition, subtraction, multiplication, and exponentiation). The algorithms and their complexity are described in the following paper. Manolios, Panagiotis & Vroon, Daron. Algorithms for ordinal arithmetic. Baader, Franz (ed), 19th International Conference on Automated Deduction--CADE-19. Pages 243-257 of LNAI, vol. 2741. Springer-Verlag. Second, the algorithms are mechanically verified and libraries of theorems which can be used to automate reasoning involving the ordinals are provided. For details, see the following paper. Manolios, Panagiotis & Vroon, Daron. Ordinal arithmetic in ACL2. Kaufmann, Matt, & Moore, J Strother (eds). Fourth International Workshop on the ACL2 Theorem Prover and Its Applications (ACL2-2003), July, 2003. See {http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/ | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}. We now describe aspects of the above mentioned books in more detail. The new ordering function is [47m[o<][0m and the new ordinal recognizer is [47m[o-p][0m. See also [47m[natp][0m, [47m[posp][0m, [47m[o<=][0m, [47m[o>][0m, [47m[o>=][0m, [47m[o-first-expt][0m, [47m[o-first-coeff][0m, [47m[o-rst][0m, [47m[make-ord][0m, [47m[o-finp][0m, and [47m[o-infp][0m. The old ordinals were based on the following formulation of Cantor Normal Form: For any ordinal, [47ma < epsilon-0[0m, there exist natural numbers [47mp[0m and [47mn[0m, and ordinals [47ma1 >= a2 >= ... >= an > 0[0m such that [47ma > a1[0m and [47ma = w^(a1) + w^(a2) + ... + w^(an) + p[0m. Thus, a predicate recognizing ACL2's old ordinals is given by the following definition. (defun e0-ordinalp (x) (if (consp x) (and (e0-ordinalp (car x)) (not (equal (car x) 0)) (e0-ordinalp (cdr x)) (or (atom (cdr x)) (not (e0-ord-< (car x) (cadr x))))) (and (integerp x) (>= x 0)))) The new representation is based on a corollary to the above theorem, which we get by the left distributive property of ordinal multiplication over ordinal addition. Thus, [47mw^a + w^a = (w^a)2[0m, [47mw^a + w^a + w^a = (w^a)3[0m and so forth. The corollary is as follows: For any ordinal, [47ma < epsilon-0[0m, there exist natural numbers [47mp[0m and [47mn[0m, positive integers [47mx1, x2, ..., xn[0m and ordinals [47ma1 > a2 > ... > an > 0[0m such that [47ma > a1[0m and [47ma = w^(a1)x1 + w^(a2)x2 + ... + w^(an)xn + p[0m. Instead of representing an ordinal as a list of non-increasing ordinals, we represent it as a list of exponent-coefficient pairs, such that the exponents are strictly decreasing (see [o-p]). Note that this representation is exponentially more efficient than the old representation. The ordinal arithmetic functions: [47mo+[0m, [47mo-[0m, [47mo*[0m, and [47mo^[0m are defined in the ordinals library (in the community books directory [47mbooks/ordinals[0m). To use them, include the book [47mordinals-without-arithmetic[0m or [47mordinals[0m, depending on whether you want the arithmetic books included or not ([47mordinals[0m includes community book [47mbooks/arithmetic/top-with-meta[0m). To use the old ordinals, include the book [47me0-ordinal[0m and run the command [47m(set-well-founded-relation e0-ord-<)[0m The community book [arithmetic/natp-posp] is a book for reasoning about [47mposp[0m and [47mnatp[0m. We recommend using this book if you have to reason about [47mposp[0m and [47mnatp[0m. It is included in community book [47mbooks/arithmetic/top[0m, which is included in community book [47mbooks/arithmetic/top-with-meta[0m, which is included in community book [47mbooks/ordinals/ordinals[0m. If you have a good reason to use the old definitions of the ordinals (e.g., because of legacy code and theorems), then we provide a convenient way to do this. The book [47mordinal-isomorphism[0m proves that the new ordinals are order-isomorphic to the old ordinals and thus theorems proved in one context can be directly transferred to the other. For an example of how to do this, look at the book [47mdefmul[0m in the community books directory [47mbooks/workshops/2000/ruiz/multiset[0m. The ordinals books have been used to prove non-trivial theorems. For a good example, see the books in the community books directory [47mbooks/workshops/2003/sustik/support[0m, where Matyas Sustik proves Dickson's lemma. Finally, many termination proofs can be carried out with weaker orderings than the ordinals up to [47mepsilon-0[0m. For example, many inductive theorem provers only know that the lexicographic ordering on natural numbers is well-founded. The book [47mlexicographic-ordering[0m contains a definition of such an ordering [47ml<[0m whose arguments are either a list of natural numbers, or a natural number. In the book we prove that [47ml<[0m is well-founded (that is, we prove a [47m:well-founded-relation[0m [47m[defthm][0m and provide a macro [47mllist[0m to simplify the generation of measure functions. We also show how to use [47ml<[0m to prove that the famous Ackermann function terminates. Finally, since [47ml<[0m does something reasonable with natural numbers, it gets along with [47m[ACL2-count][0m, the default measure chosen by ACL2. Subtopics [Make-ord] A constructor for ordinals. [O-finp] Recognizes if an ordinal is finite [O-first-coeff] Returns the first coefficient of an ordinal [O-first-expt] The first exponent of an ordinal [O-infp] Recognizes if an ordinal is infinite [O-p] A recognizer for the ordinals up to epsilon-0 [O-rst] Returns the rest of an infinite ordinal [O<] The well-founded less-than relation on ordinals up to [47mepsilon-0[0m [O<=] The less-than-or-equal relation for the ordinals [O>] The greater-than relation for the ordinals [O>=] The greater-than-or-equal relation for the ordinals [Proof-of-well-foundedness] A proof that [47m[o<][0m is well-founded on [47m[o-p][0ms") (otf-flg (defthm thm xargs) "Allow more than one initial subgoal to be pushed for induction This keyword argument for certain [events] controls whether the theorem prover will abandon its initial work upon encountering the second subgoal to push for proof by induction: [47m:otf-flg[0m is [47mnil[0m for that behavior, but [47mt[0m if it should instead continue ``Onward Through the Fog'' and complete [waterfall] processing before starting any proof by induction. The default value for [47m:otf-flg[0m is [47mnil[0m except during processing of [47m[defun][0m events, where the default is [47mt[0m for both termination and [guard] proofs (see [defun]). Note that the default for [47m:otf-flg[0m is thus [47mt[0m for processing [47m[verify-termination][0m events, since they abbreviate [47mdefun[0m events. However, the default for [47m:otf-flg[0m is [47mnil[0m for processing [47m[verify-guards][0m events. Further Explanation Suppose you submit a conjecture to the theorem prover and the system splits it up into many subgoals. Any subgoal not proved by other methods is eventually set aside for an attempted induction proof. But upon setting aside the second such subgoal, the system chickens out and decides that rather than prove n>1 subgoals inductively, it will abandon its initial work and attempt induction on the originally submitted conjecture. The [47m:otf-flg[0m (Onward Thru the Fog) allows you to override this chickening out. When [47m:otf-flg[0m is [47mt[0m, the system will push all the initial subgoals and proceed to try to prove each, independently, by induction. Even when you don't expect induction to be used or to succeed, setting the [47m:otf-flg[0m is a good way to force the system to generate and display all the initial subgoals. For [47m[defthm][0m and [47m[thm][0m, [47m:otf-flg[0m is a keyword argument that is a peer to [47m:[0m[47m[rule-classes][0m and [47m:[0m[47m[hints][0m. It may be supplied as in the following examples; also see [defthm]. (thm (my-predicate x y) :rule-classes nil :otf-flg t) (defthm append-assoc (equal (append (append x y) z) (append x (append y z))) :hints (("Goal" :induct t)) :otf-flg t) The [47m:otf-flg[0m may be supplied to [47m[defun][0m via the [47m[xargs][0m declare option. When you supply an [47m:otf-flg[0m hint to [47mdefun[0m, the flag is effective for the termination proofs and the guard proofs, if any.") (other-releases (pointers) "See [releases].") (other_requirements (pages_written_especially_for_the_tours) "Other Requirements {IMAGE} (see [The_End_of_the_Flying_Tour]) ACL2 is distributed on the Web without fee. There is a [31;1mlicense[0m agreement based on the 3-clause BSD license. See the file LICENSE in the ACL2 distribution. ACL2 currently runs on [31;1mUnix[0m, [31;1mLinux[0m, [31;1mWindows[0m, and [31;1mMacintosh OS X[0m operating systems. It can generally be built in any of the following Common Lisps (but see [allegro-cl] for a caveat about Allegro Common Lisp): * [31;1mAllegro Common Lisp[0m, * [31;1mCCL[0m (formerly OpenMCL) * [31;1mCMU Common Lisp[0m, * [31;1mGCL[0m (Gnu Common Lisp), * [31;1mLispWorks[0m, and * [31;1mSBCL[0m (Steel Bank Common Lisp) {IMAGE} (see [The_End_of_the_Flying_Tour])") (output-controls (acl2 io) "Methods for controlling the output produced by the ACL2 prover This topic pertains primarily to processing of [events], often involving the prover. For a general discussion about redirection of ACL2 output to a file, see [output-to-file]. Subtopics [Finalize-event-user] User-supplied code to complete [events], e.g., with extra [summary] output [Gag-mode] Verbosity of proof output [Get-event-data] Obtain data stored after at the conclusion of an event [Goal-spec] To indicate where a hint is to be used [Initialize-event-user] User-supplied code to initiate [events] [Pso] Show the most recently saved output [Pso!] Show the most recently saved output, including [proof-tree] output [Psof] Show the most recently saved output [Psog] Show the most recently saved output with [gag-mode] [Saving-event-data] Save data stored for subsidiary [events] [Set-duplicate-keys-action!] Non-[47m[local][0m version of [47m[set-duplicate-keys-action][0m [Set-gag-mode] Modify the nature of proof output [Set-inhibit-er] Control the error output [Set-inhibit-er!] Control error output non-[47m[local][0mly [Set-inhibit-output-lst] Control output [Set-inhibit-warnings] Control warnings [Set-inhibit-warnings!] Control warnings non-[47m[local][0mly [Set-inhibited-summary-types] Control which parts of the [summary] are printed [Set-let*-abstractionp] To shorten many prettyprinted [clause]s [Set-print-clause-ids] Cause subgoal numbers to be printed when [47m'prove[0m output is inhibited [Set-raw-proof-format] Proof output with [rune]s as lists and maybe clausal goals [Set-raw-warning-format] Print some warnings in a ``raw'', s-expression format [Set-warnings-as-errors] Changing [warnings] to hard [errors] (and vice-versa) [Summary] The summary printed at the conclusion of an event [Toggle-inhibit-er] Add or delete an error output string from the [47minhibit-er-table[0m [Toggle-inhibit-er!] Toggle an [47minhibit-er-table[0m entry non-[47m[local][0mly [Toggle-inhibit-warning] Add or delete a warning string from the [47minhibit-warnings-table[0m [Toggle-inhibit-warning!] Toggle an [47minhibit-warnings-table[0m entry non-[47m[local][0mly [Warnings] Warnings emitted by the ACL2 proof process [With-output] Suppressing or turning on specified output for an event [Wof] Direct standard output and proofs output to a file") (output-to-file (io) "Redirecting output to a file For a general discussion of ACL2 input/output and of the ACL2 read-eval-print loop, see [io] and see [ld] (respectively). Here we use an example to illustrate how to use some of the options provided by [47mld[0m to redirect ACL2 output to a file, other than the printing of the prompt (which continues to go to the terminal). There are two [47mld[0m specials that control output from the [47mld[0m command: [47m[proofs-co][0m for proof output and [47m[standard-co][0m for other output. The following example shows how to use these to redirect output to a file [47m"tmp.out"[0m. The following command opens a character output channel to the file [47m"tmp.out"[0m and redirects proof output to that channel, i.e., to file [47m"tmp.out"[0m. (mv-let (chan state) (open-output-channel "tmp.out" :character state) (set-proofs-co chan state)) Next, we redirect standard output to that same channel. (set-standard-co (proofs-co state) state) Now we can load an input file, in this case file [47m"tmp.lisp"[0m, and output will be redirected to file [47m"tmp.out"[0m. (The use of [47m:ld-pre-eval-print t[0m is optional; see [ld].) (ld "tmp.lisp" :ld-pre-eval-print t) Having completed our load operation, we restore both proof output and standard output to the terminal, as follows. (set-standard-co *standard-co* state) (close-output-channel (proofs-co state) state) (set-proofs-co *standard-co* state) The following variant of the above example shows how to redirect output as above except without changing the global settings of the two [47m[ld][0m specials, [47m[proofs-co][0m and [47m[standard-co][0m. This approach uses a notion of ``global variables'' stored in the ACL2 [state]; see [assign] and see [@]. (mv-let (chan state) (open-output-channel "tmp.out" :character state) (assign tmp-channel chan)) (ld "tmp.lisp" :ld-pre-eval-print t :proofs-co (@ tmp-channel) :standard-co (@ tmp-channel)) (close-output-channel (@ tmp-channel) state)") (override-hints (hints) "A list of hints given priority in every proof attempt This is an advanced feature, originally implemented to help system designers to create ``modes'' that control the way hints are supplied to the theorem prover. Please see [default-hints] for the much more usual way to install hints that may be applied by default. Examples: ACL2 !>(override-hints (w state)) ((computed-hint-1 clause keyword-alist processor) (computed-hint-2 clause keyword-alist stable-under-simplificationp)) [47mOverride-hints[0m returns a list of computed hints (see [computed-hints]) which, unlike other computed hints, may mention the variable [47mKEYWORD-ALIST[0m. Before reading further, please see [hints-and-the-waterfall] to review the basics of how [hints] are applied during a proof. In particular, we assume familiarity with the notion of selecting a hint to be applied to the current goal. If there are override-hints, that hint selection is tentative, because if it reduced to [47mnil[0m after the application of override-hints, then that hint will be skipped and the attempt will continue for selecting an applicable hint. (Craft your override-hints so that [47m:no-op t[0m is returned in such cases instead of [47mnil[0m, if you don't want the hint to be skipped.) But we must explain what is meant by ``the application of override-hints'', and we do that now. Suppose that there are override-hints when a hint is selected for the current goal. That selected hint is a keyword-alist, which is an alternating list of hint keywords and their values, whose source is either an explicit hint [47m(goal-name :key1 val1 ... :keyn valn)[0m where the [47m:keyi[0m are allowed to be custom hint keywords (which are expanded away; see [custom-keyword-hints]), or else is the non-[47mnil[0m keyword-alist produced by evaluating a computed hint. Then the override-hints are applied to that keyword-alist as follows, one at a time, in order of their occurrence in the list of override-hints (as determined by the use of [47m[set-override-hints][0m and [47m[add-override-hints][0m). The first override-hint is evaluated, in the usual manner of evaluating computed hints but with the variable [47mKEYWORD-ALIST[0m bound to the above keyword-alist. That evaluation produces a result that should also be a keyword-alist, or else an error occurs. Any custom keyword hints are then eliminated from that keyword-alist. The resulting keyword-alist must not contain the [47m:ERROR[0m hint keyword and must not start with the [47m:COMPUTED-HINT-REPLACEMENT[0m keyword; otherwise an error occurs. With [47mKEYWORD-ALIST[0m bound to this result, the second override-hint is similarly evaluated. This process continues, and the keyword-alist returned by the final override-hint is the one used when processing the goal at hand. Except: If that keyword-alist is [47mnil[0m, then the next hint among the pending hints is tentatively selected and the process repeats, applying each override hint to that new tentative selection. Of course we might obtain [47mnil[0m again, in which case we tentatively select the next pending hint; and so on. If finally no hint is selected for the current goal, then [47mKEYWORD-ALIST[0m is bound to [47mnil[0m and the override-hints are applied as described above. But note that this final step is skipped if hint selection is being performed because [47mstable-under-simplificationp[0m has just become true, rather than at the top of the waterfall. (Otherwise the override-hints could easily keep firing uselessly yet putting us back at the top of the waterfall, with no change to the given goal, resulting in an infinite loop.) As mentioned above, the [47m:COMPUTED-HINT-REPLACEMENT[0m keyword is illegal for the value of an override-hint. But a selected hint may be a computed hint that evaluates to a keyword-alist beginning with prefix [47m:COMPUTED-HINT-REPLACEMENT val[0m. What value does ACL2 return for such a computed hint in the presence of override-hints? First, this prefix is stripped off before passing the resulting keyword-alist to the override-hints as described above. If the result of applying override-hints to that keyword-alist is not [47mnil[0m, then the prefix is put back on the front of that resulting keyword-alist after doing internal processing of the hint, including expansion of any custom keyword hints. Otherwise, the application of override-hints to the computed hint is [47mnil[0m, so this hint is not selected after all. [31;1mWARNING[0m: Unlike ordinary computed hints, a value of [47mnil[0m for an override-hint is not ignored. That is: When an ordinary computed hint evaluates to [47mnil[0m, it is deemed not to apply, and the next available hint is consulted. But when an override-hint is evaluated, the result is always supplied for the next binding of the variable [47mKEYWORD-ALIST[0m, even if that result is [47mnil[0m. If you want an override-hint to be a no-op, return as the expression the variable [47mKEYWORD-ALIST[0m rather than an expression that evaluates to [47mnil[0m. This feature can be used in order to implement a form of additive hints. Suppose for example that you want a hint that turns off generalization. A simple but inadequate solution is: (add-default-hints '((quote (:do-not '(generalize))))) The problem is that if there is any explicit hint supplied for a given goal, then it will be the one selected, and the above will be ignored. But suppose that the explicit hint supplied is of the form [47m("Subgoal x.y" :do-not '(fertilize))[0m. What we would really want in this case is to generate the hint for the indicated subgoal that binds [47m:do-not[0m to a list indicating that both fertilization _and_ generalization are disabled for that goal. A solution is to merge, for example as follows. (The use of [47m[prog2$][0m and [47m[cw][0m is of course optional, included here to provide debug printing.) (add-override-hints '((let* ((tmp (assoc-keyword :do-not KEYWORD-ALIST)) (new-keyword-alist (cond (tmp (list* :do-not `(cons 'generalize ,(cadr tmp)) (remove-keyword :do-not KEYWORD-ALIST))) (t (list* :do-not ''(generalize) KEYWORD-ALIST))))) (prog2$ (cw "New: ~x0~|" new-keyword-alist) new-keyword-alist)))) REMARKS (1) The utilities [47m[add-override-hints][0m, [47m[add-override-hints!][0m, [47m[set-override-hints][0m, [47m[set-override-hints!][0m, [47m[remove-override-hints][0m, and [47m[remove-override-hints!][0m are also available, in complete analogy to their default-hints versions. (2) The community book [47mhints/basic-tests.lisp[0m illustrates the use of override-hints and illuminates a number of corner cases; search in that file for ``Test override-hints.'' (3) The community book [47mhints/merge-hint.lisp[0m provides support for merging hints that might be useful for writers of override-hint expressions (see the examples at the end of that file). (4) Override-hints are used in the processing of [47m:BACKTRACK[0m hints (see [hints]). Subtopics [Add-override-hints] Add to the [override-hints] [Add-override-hints!] Add non-[local]ly to the [override-hints] [Remove-override-hints] Delete from the list of [override-hints] [Remove-override-hints!] Delete non-[local]ly from the list of [override-hints] [Set-override-hints] Set the [override-hints] [Set-override-hints!] Set the [override-hints] non-[local]ly") (overview_of_the_expansion_of_endp_in_the_base_case (pages_written_especially_for_the_tours) "Overview of the Expansion of ENDP in the Base Case [47mSubgoal *1/1[0m is the [31;1mBase Case[0m of our induction. It simplifies to [47mSubgoal *1/1'[0m by expanding the [31;1mENDP[0m term in the hypothesis, just as we saw in the earlier proof of [47mSubgoal *1/2[0m.") (overview_of_the_expansion_of_endp_in_the_induction_step (pages_written_especially_for_the_tours) "Overview of the Expansion of ENDP in the Induction Step In this message the system is saying that [47mSubgoal *1/2[0m has been rewritten to the [47mSubgoal *1/2'[0m, by expanding the definition of [31;1mendp[0m. This is an example of [31;1msimplification[0m, one of the main proof techniques used by the theorem prover. Click here (see [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_0}]) if you would like to step through the simplification of [47mSubgoal *1/2[0m.") (overview_of_the_final_simplification_in_the_base_case (pages_written_especially_for_the_tours) "Overview of the Final Simplification in the Base Case The [31;1mBut[0m is our signal that the goal is proved. Click here (see [The_Final_Simplification_in_the_Base_Case_{Step_0}]) to step through the proof. It is very simple.") (overview_of_the_proof_of_a_trivial_consequence (pages_written_especially_for_the_tours) "Overview of the Proof of a Trivial Consequence {IMAGE} (see [The_End_of_the_Walking_Tour]) {IMAGE} ACL2 !>[31;1m(defthm trivial-consequence[0m [31;1m(equal (app (app (app (app x1 x2) (app x3 x4)) (app x5 x6)) x7)[0m [31;1m(app x1 (app (app x2 x3) (app (app x4 x5) (app x6 x7))))))[0m ACL2 Warning (see [The_WARNING_about_the_Trivial_Consequence]) [Subsume] in ( DEFTHM TRIVIAL-CONSEQUENCE ...): The previously added rule ASSOCIATIVITY-OF-APP subsumes the newly proposed :REWRITE rule TRIVIAL-CONSEQUENCE, in the sense that the old rule rewrites a more general target. Because the new rule will be tried first, it may nonetheless find application. By the simple :rewrite rule ASSOCIATIVITY-OF-APP (see [The_First_Application_of_the_Associativity_Rule]) we reduce the conjecture to Goal' (EQUAL (APP X1 (APP X2 (APP X3 (APP X4 (APP X5 (APP X6 X7)))))) (APP X1 (APP X2 (APP X3 (APP X4 (APP X5 (APP X6 X7))))))). But we reduce the conjecture to T, by primitive type reasoning. Q.E.D. Summary Form: ( DEFTHM TRIVIAL-CONSEQUENCE ...) Rules: ((:REWRITE ASSOCIATIVITY-OF-APP) (:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: Subsume (see [The_Summary_of_the_Proof_of_the_Trivial_Consequence]) Time: 0.20 seconds (prove: 0.02, print: 0.00, other: 0.18) TRIVIAL-CONSEQUENCE {IMAGE} You might explore the links before moving on. {IMAGE} (see [The_End_of_the_Walking_Tour])") (overview_of_the_simplification_of_the_base_case_to_t (pages_written_especially_for_the_tours) "Overview of the Simplification of the Base Case to T {IMAGE} (see [The_End_of_the_Proof_of_the_Associativity_of_App]) Subgoal *1/1 (see [Overview_of_the_Expansion_of_ENDP_in_the_Base_Case]) (IMPLIES (ENDP A) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). By the simple :definition ENDP we reduce the conjecture to Subgoal *1/1' (IMPLIES (NOT (CONSP A)) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). But (see [Overview_of_the_Final_Simplification_in_the_Base_Case]) simplification reduces this to T, using the :definition APP and primitive type reasoning. {IMAGE} (see [The_End_of_the_Proof_of_the_Associativity_of_App])") (overview_of_the_simplification_of_the_induction_conclusion (pages_written_especially_for_the_tours) "Overview of the Simplification of the Induction Conclusion In this message the system is saying that [47mSubgoal *1/2'[0m has been rewritten to T using the rules noted. The word ``[31;1mBut[0m'' at the beginning of the sentence is a signal that the goal has been proved. Click here (see [The_Simplification_of_the_Induction_Conclusion_{Step_0}]) to step through the proof of [47mSubgoal *1/2'[0m.") (overview_of_the_simplification_of_the_induction_step_to_t (pages_written_especially_for_the_tours) "Overview of the Simplification of the Induction Step to T {IMAGE} (see [Overview_of_the_Simplification_of_the_Base_Case_to_T]) Subgoal *1/2 (see [On_the_Naming_of_Subgoals]) (IMPLIES (AND (NOT (ENDP A)) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). By the simple :definition ENDP (see [Overview_of_the_Expansion_of_ENDP_in_the_Induction_Step]) we reduce the conjecture to Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). But (see [Overview_of_the_Simplification_of_the_Induction_Conclusion]) simplification reduces this to T, using the :definition APP, the :rewrite rules CDR-CONS and CAR-CONS and primitive type reasoning. {IMAGE} (see [Overview_of_the_Simplification_of_the_Base_Case_to_T])") (p! (ld) "To pop up (at least) one level of ACL2's command loop Logically speaking, [47m(p!) = nil[0m. If you are already at the top level of the ACL2 command loop, rather than being in a subsidiary call of [47m[ld][0m, then the keyword then a call of [47m(p!)[0m returns [47mnil[0m and has no other effect. Otherwise, [47m(p!)[0m is evaluated inside a call of [47m[ld][0m that was made inside ACL2's command loop. In that case, the current computation is aborted and treating as causing an error, and control returns to the superior call of [47mld[0m. Here is a more detailed description of the effect of [47m(p!)[0m when not at the top level of the ACL2 command loop. The current call of [47mLD[0m is treated as though [47mld-error-action[0m is [47m:RETURN![0m (the default; here we ignore the case [47m(:exit N)[0m) and hence immediately returns control to the superior call of [47m[ld][0m. If all calls of [47m[ld][0m were made with the default [47mld-error-action[0m of [47m:RETURN![0m, then all superior calls of [47mld[0m will then complete until you are back at top level of the ACL2 loop. For more information, see [ld-error-action]. If you are at an ACL2 prompt (as opposed to a raw Lisp break), then you may type [47m:p![0m in place of [47m(p!)[0m; see [keyword-commands]. If you are actually in a break caused by [break-rewrite], [47m:p![0m and [47m(p!)[0m just print a message and otherwise are no-ops. (A comment in the source code definition of [47mp![0m explains why break-rewrite cannot support ``popping up one level'' in the sense that you would probably expect.)") (package (pointers) "See [packages].") (package-reincarnation-import-restrictions (packages) "Re-defining undone [47m[defpkg][0ms ACL2 imposes the following restriction on redefining packages. Note that for the notion of a package definition being ``undone'', the undoing might have been by use of [47m:[0m[47m[ubt][0m, or it might have been because the [47mdefpkg[0m form was evaluated by a [local] event that disappeared during the second pass of an [47m[encapsulate][0m or [47m[include-book][0m event. Suppose [47m(defpkg "pkg" imports)[0m has been evaluated successfully and then has been undone. Then any future attempt in the same session to define [47m"pkg"[0m as a package must specify an identical imports list. Reasons for the restriction We will see below that the restriction above is necessary for avoiding unsoundness. But first consider the following simple example, which shows that the package doesn't entirely disappear when undone. ACL2 !>(defpkg "FOO" nil) Summary Form: ( DEFPKG "FOO" ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) "FOO" ACL2 !>(assign x 'foo::a) FOO::A ACL2 !>(u) ; undoes the defpkg event 0:x(EXIT-BOOT-STRAP-MODE) ACL2 !>(@ x) FOO::A ACL2 !>(eq (@ x) 'acl2::a) NIL ACL2 !> Suppose that (without the restriction) the package [47m"FOO"[0m can now be introduced as [47m(defpkg "FOO" '(a))[0m. Then will [47m(eq (@ x) 'acl2::a)[0m evaluate to [47mnil[0m as before, since we didn't make another assignment to [47mx[0m? Or would that equality evaluate to [47mt[0m since the only symbol in package [47m"FOO"[0m whose [47m[symbol-name][0m is [47m"A"[0m is [47macl2::a[0m? Each result is plausible so to avoid confusion, it might be best if [47m(@ x)[0m is now undefined. But that would require somehow removing all symbols in the [state] whose package is [47m"FOO"[0m when undoing the [47mdefpkg[0m event, which can be inefficient and --- more importantly --- may not make sense if there are [stobj]s that include such symbols. What a mess! A more important reason for the restriction is that it prevents unsoundness. Consider the following two books. ;;; book1.lisp ;;; Portcullis command: (defpkg "FOO" '()) (in-package "ACL2") (defthm thm1 (equal (symbol-package-name (intern$ "A" "FOO")) "FOO")) ;;;;;; ;;; book2.lisp ;;; Portcullis command: (defpkg "FOO" '(a)) (in-package "ACL2") (defthm thm2 (equal (symbol-package-name (intern$ "A" "FOO")) "ACL2")) After each of these two books is certifiable in a (separate) fresh ACL2 session, consider the following two events. (encapsulate () (local (include-book "book1")) (defthm thm1 (equal (symbol-package-name (intern$ "A" "FOO")) "FOO"))) (encapsulate () (local (include-book "book2")) (defthm thm1 (equal (symbol-package-name (intern$ "A" "FOO")) "ACL2"))) Each is accepted in a separate, fresh ACL2 session. But if we could admit the first and then the second in the same session, we could of course prove [47mnil[0m. Fortunately, if we try that, then ACL2 implements the restriction by complaining about the second as follows, when encountering the [47m(local (include-book "book2"))[0m form in the second [47mencapsulate[0m. ACL2 Error in ACL2-INTERFACE: We cannot reincarnate the package "FOO" because it was previously defined with a different list of imported symbols. A final reason for the restriction stems from the reinstallation of saved logical [world]s, as in error recovery and the [47m:[0m[47m[oops][0m [command]. Suppose that the new [47m[defpkg][0m attempts to import some symbol, [47ma::sym[0m, not imported by the previous definition of [47m"pkg"[0m. Because it was not imported in the original package, the symbol [47mpkg::sym[0m, different from [47ma::sym[0m, may well have been created and may well be used in some saved [world]s. Those saved [world]s are Common Lisp objects being held for you ``behind the scenes.'' In order to import [47ma::sym[0m into [47m"pkg"[0m now we would have to unintern [47mpkg::sym[0m, rendering those saved [world]s ill-formed. So because of saved [world]s, we do not clear out a package when it is undone. A logical view of the restriction The restriction on redefining packages is based on the following part of the logical foundation of ACL2. [31;1mLogical Persistence of Packages.[0m When a package is introduced by [47m[defpkg][0m in an ACL2 session, its definition is considered to persist logically even if that [defpkg] [event] is undone. That principle certainly rules out the new definition of an undone package with different imports. It also explains why package definitions from [local]ly included [books] are included in a book's [portcullis] commands; see [hidden-defpkg]. Note that this is a [3mlogical[0m principle; if you undo a [47m[defpkg][0m event, then ACL2 will prevent you from referencing that package explicitly unless you first reintroduce it --- with the same imports, because of the restriction.") (packages (programming) "Collections of symbols that act as namespaces. Packages are collections of symbols. They can be used to avoid name conflicts when working on large ACL2 projects. See [working-with-packages] for the best practices in setting up and using packages. Subtopics [*ACL2-exports*] Symbols that are often imported into new [packages] to provide easy access to ACL2 functionality. [*common-lisp-symbols-from-main-lisp-package*] Symbols that are often imported into new packages to provide easy access to Common Lisp functionality. [ACL2-user] A package the ACL2 user may prefer [Defpkg] Define a new symbol package [Hidden-death-package] Handling [47m[defpkg][0m [events] that are [47m[local][0m [Hidden-defpkg] Handling defpkg events that are local [In-package] Select current package [Intern] Create a new symbol in a given package [Intern$] Create a new symbol in a given package [Intern-in-package-of-symbol] Create a symbol with a given name [Managing-ACL2-packages] User-contributed documentation on packages [Package-reincarnation-import-restrictions] Re-defining undone [47m[defpkg][0ms [Packages-for-generated-symbols] Convention for packages of generated symbols [Pkg-imports] List of symbols imported into a given package [Pkg-witness] Return a specific symbol in the indicated package [Sharp-bang-reader] Package prefix that is not restricted to symbols [Symbol-package-name] The name of the package of a symbol (a string)") (packages-for-generated-symbols (packages) "Convention for packages of generated symbols ACL2 utilities, whether defined in the ACL2 sources or in books, will ideally provide the following default behavior when feasible: generated symbols should be in the [47m[current-package][0m. This is the ACL2 version of the general principle enforced by almost all programming languages: names introduced are, by default, in the current namespace. We do not claim that ACL2 currently adheres to this principle in all cases, but our hope that this situation is improved over time. Indeed, the utilities [47m[defequiv][0m, [47m[defrefinement][0m and [47m[defcong][0m have been improved to conform to this principle; see [note-8-3]. We hope that future utilities, not only in ACL2 but also in the [community-books], will respect this principle when feasible. Conforming to this principle requires using [47m[make-event][0m in a top level form to determine the [47m[current-package][0m from [47m[state][0m and then passing this package to functions that generate symbols. The section [47mSymbol generation utilities[0m of ACL2 source file [47mdefthm.lisp[0m contains utilities that are useful for generating symbols. The code was adapted from similar code in [47m[ACL2s][0m; see the community book [47macl2s/utilities.lisp[0m which includes even more such utilities. To see an example of a utility that generates symbols in the current package, see [47mbooks/acl2s/defunc.lisp[0m, which contains the [47m[ACL2s::defunc][0m utility. Other examples include [47m[defequiv][0m, [47m[defrefinement][0m and [47m[defcong][0m in [47mdefthm.lisp[0m.") (packn (symbols acl2-built-ins) "Build a symbol from a list The call [47m(packn lst)[0m returns a symbol whose name is a concatenation of string representations of the atoms in the [47m[atom-listp][0m, [47mlst[0m. The symbol's package is the package of the first symbol in [47mlst[0m whose package is not [47m"COMMON-LISP"[0m if any, else [47m"ACL2"[0m.") (packn-pos (symbols acl2-built-ins) "Build a symbol in a specified package from a list The function [47mpackn-pos[0m behaves like [47m[packn][0m, except that for the call [47m(packn-pos lst witness)[0m, the returned symbol's package will instead be the package of the symbol, [47mwitness[0m.") (pages_written_especially_for_the_tours (acl2-tutorial) "Pages Written Especially for the Tours The ACL2 Home Page is generated from ACL2's online documentation strings. (How else could we achieve the total integration of ACL2's online documentation with the home page?) This page is just an artifact of the structure of our documentation strings: each string must belong to a ``major section'' of the documentation database. This page is not structured to be used by a person browsing via the Web. It contains, in an arbitrary order, the pages written specifically for the Web user. Furthermore, browsing the pages below as text, in particular using the ACL2 :DOC command, is often unsatisfying because because of the lack of support for displaying gif files or for going ``back'' to a node just visited. If you wish to look at the pages below, we strongly recommend that you do so via a HTML-based Web browser. Indeed, you should simply visit ACL2's Home Page and take one of the [Tours]. Generally, the topics listed above will not be of use to the ACL2 user. Subtopics [A_Flying_Tour_of_ACL2] A Flying Tour of ACL2 [A_Sketch_of_How_the_Rewriter_Works] A Sketch of How the Rewriter Works [A_Tiny_Warning_Sign] A Tiny Warning Sign [A_Trivial_Proof] A Trivial Proof [A_Typical_State] A Typical State [A_Walking_Tour_of_ACL2] A Walking Tour of ACL2 [ACL2_Characters] ACL2 Characters [ACL2_Conses_or_Ordered_Pairs] ACL2 Conses or Ordered Pairs [ACL2_Strings] ACL2 Strings [ACL2_Symbols] ACL2 Symbols [ACL2_System_Architecture] ACL2 System Architecture [ACL2_as_an_Interactive_Theorem_Prover] ACL2 as an Interactive Theorem Prover [ACL2_as_an_Interactive_Theorem_Prover_{cont}] ACL2 as an Interactive Theorem Prover (cont) [ACL2_is_an_Untyped_Language] ACL2 is an Untyped Language [About_Models] About Models [About_Types] About Types [About_the_ACL2_Home_Page] About the ACL2 Home Page [About_the_Admission_of_Recursive_Definitions] About the Admission of Recursive Definitions [About_the_Prompt] About the Prompt [An_Example_Common_Lisp_Function_Definition] An Example Common Lisp Function Definition [An_Example_of_ACL2_in_Use] An Example of ACL2 in Use [Analyzing_Common_Lisp_Models] Analyzing Common Lisp Models [Common_Lisp] Common Lisp [Common_Lisp_as_a_Modeling_Language] Common Lisp as a Modeling Language [Corroborating_Models] Corroborating Models [Evaluating_App_on_Sample_Input] Evaluating App on Sample Input [Flawed_Induction_Candidates_in_App_Example] Flawed Induction Candidates in App Example [Free_Variables_in_Top-Level_Input] Free Variables in Top-Level Input [Functions_for_Manipulating_these_Objects] Functions for Manipulating these Objects [Guards_in_ACL2] Guards [Guessing_the_Type_of_a_Newly_Admitted_Function] Guessing the Type of a Newly Admitted Function [Guiding_the_ACL2_Theorem_Prover] Guiding the ACL2 Theorem Prover [Hey_Wait!__Is_ACL2_Typed_or_Untyped{Q}] Hey Wait! Is ACL2 Typed or Untyped? [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}] How Long Does It Take to Become an Effective User? [How_To_Find_Out_about_ACL2_Functions] How To Find Out about ACL2 Functions [How_To_Find_Out_about_ACL2_Functions_{cont}] How To Find Out about ACL2 Functions (cont) [Modeling_in_ACL2] Modeling in ACL2 [Models_in_Engineering] Models in Engineering [Models_of_Computer_Hardware_and_Software] Models of Computer Hardware and Software [Name_the_Formula_Above] Name the Formula Above [Nontautological_Subgoals] Prover output omits some details [Numbers_in_ACL2] Numbers in ACL2 [On_the_Naming_of_Subgoals] On the Naming of Subgoals [Other_Requirements] Other Requirements [Overview_of_the_Expansion_of_ENDP_in_the_Base_Case] Overview of the Expansion of ENDP in the Base Case [Overview_of_the_Expansion_of_ENDP_in_the_Induction_Step] Overview of the Expansion of ENDP in the Induction Step [Overview_of_the_Final_Simplification_in_the_Base_Case] Overview of the Final Simplification in the Base Case [Overview_of_the_Proof_of_a_Trivial_Consequence] Overview of the Proof of a Trivial Consequence [Overview_of_the_Simplification_of_the_Base_Case_to_T] Overview of the Simplification of the Base Case to T [Overview_of_the_Simplification_of_the_Induction_Conclusion] Overview of the Simplification of the Induction Conclusion [Overview_of_the_Simplification_of_the_Induction_Step_to_T] Overview of the Simplification of the Induction Step to T [Perhaps] Perhaps [Popping_out_of_an_Inductive_Proof] Popping out of an Inductive Proof [Proving_Theorems_about_Models] Proving Theorems about Models [Revisiting_the_Admission_of_App] Revisiting the Admission of App [Rewrite_Rules_are_Generated_from_DEFTHM_Events] Rewrite Rules are Generated from DEFTHM Events [Running_Models] Running Models [Subsumption_of_Induction_Candidates_in_App_Example] Subsumption of Induction Candidates in App Example [Suggested_Inductions_in_the_Associativity_of_App_Example] Suggested Inductions in the Associativity of App Example [Symbolic_Execution_of_Models] Symbolic Execution of Models [Tours] The Tours [The_Admission_of_App] The Admission of App [The_Associativity_of_App] The Associativity of App [The_Base_Case_in_the_App_Example] The Base Case in the App Example [The_End_of_the_Flying_Tour] The End of the Flying Tour [The_End_of_the_Proof_of_the_Associativity_of_App] The End of the Proof of the Associativity of App [The_End_of_the_Walking_Tour] The End of the Walking Tour [The_Event_Summary] The Event Summary [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_0}] The Expansion of ENDP in the Induction Step (Step 0) [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_1}] The Expansion of ENDP in the Induction Step (Step 1) [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_2}] The Expansion of ENDP in the Induction Step (Step 2) [The_Falling_Body_Model] The Falling Body Model [The_Final_Simplification_in_the_Base_Case_{Step_0}] The Final Simplification in the Base Case (Step 0) [The_Final_Simplification_in_the_Base_Case_{Step_1}] The Final Simplification in the Base Case (Step 1) [The_Final_Simplification_in_the_Base_Case_{Step_2}] The Final Simplification in the Base Case (Step 2) [The_Final_Simplification_in_the_Base_Case_{Step_3}] The Final Simplification in the Base Case (Step 3) [The_First_Application_of_the_Associativity_Rule] The First Application of the Associativity Rule [The_Induction_Scheme_Selected_for_the_App_Example] The Induction Scheme Selected for the App Example [The_Induction_Step_in_the_App_Example] The Induction Step in the App Example [The_Instantiation_of_the_Induction_Scheme] The Instantiation of the Induction Scheme [The_Justification_of_the_Induction_Scheme] The Justification of the Induction Scheme [The_Proof_of_the_Associativity_of_App] The Proof of the Associativity of App [The_Q.E.D._Message] The Q.E.D. Message [The_Rules_used_in_the_Associativity_of_App_Proof] The Rules used in the Associativity of App Proof [The_Simplification_of_the_Induction_Conclusion_{Step_0}] The Simplification of the Induction Conclusion (Step 0) [The_Simplification_of_the_Induction_Conclusion_{Step_1}] The Simplification of the Induction Conclusion (Step 1) [The_Simplification_of_the_Induction_Conclusion_{Step_10}] The Simplification of the Induction Conclusion (Step 10) [The_Simplification_of_the_Induction_Conclusion_{Step_11}] The Simplification of the Induction Conclusion (Step 11) [The_Simplification_of_the_Induction_Conclusion_{Step_12}] The Simplification of the Induction Conclusion (Step 12) [The_Simplification_of_the_Induction_Conclusion_{Step_2}] The Simplification of the Induction Conclusion (Step 2) [The_Simplification_of_the_Induction_Conclusion_{Step_3}] The Simplification of the Induction Conclusion (Step 3) [The_Simplification_of_the_Induction_Conclusion_{Step_4}] The Simplification of the Induction Conclusion (Step 4) [The_Simplification_of_the_Induction_Conclusion_{Step_5}] The Simplification of the Induction Conclusion (Step 5) [The_Simplification_of_the_Induction_Conclusion_{Step_6}] The Simplification of the Induction Conclusion (Step 6) [The_Simplification_of_the_Induction_Conclusion_{Step_7}] The Simplification of the Induction Conclusion (Step 7) [The_Simplification_of_the_Induction_Conclusion_{Step_8}] The Simplification of the Induction Conclusion (Step 8) [The_Simplification_of_the_Induction_Conclusion_{Step_9}] The Simplification of the Induction Conclusion (Step 9) [The_Summary_of_the_Proof_of_the_Trivial_Consequence] The Summary of the Proof of the Trivial Consequence [The_Theorem_that_App_is_Associative] The Theorem that App is Associative [The_Time_Taken_to_do_the_Associativity_of_App_Proof] The Time Taken to do the Associativity of App Proof [The_WARNING_about_the_Trivial_Consequence] The WARNING about the Trivial Consequence [Using_the_Associativity_of_App_to_Prove_a_Trivial_Consequence] Using the Associativity of App to Prove a Trivial Consequence [What_Is_ACL2{Q}] What Is ACL2? [What_is_Required_of_the_User{Q}] What is Required of the User? [What_is_a_Mathematical_Logic{Q}] What is a Mathematical Logic? [What_is_a_Mechanical_Theorem_Prover{Q}] What is a Mechanical Theorem Prover? [What_is_a_Mechanical_Theorem_Prover{Q}_{cont}] What is a Mechanical Theorem Prover? (cont) [You_Must_Think_about_the_Use_of_a_Formula_as_a_Rule] You Must Think about the Use of a Formula as a Rule") (pairlis (lists alists) "See [pairlis$] The Common Lisp language allows its [47mpairlis[0m function to construct an alist without specifying a single order! So we have to define our own version: See [pairlis$].") (pairlis$ (lists alists acl2-built-ins) "Zipper together two lists The Common Lisp language allows its [47m[pairlis][0m function to construct an alist in any order! So we have to define our own version, [47mpairlis$[0m. It returns the list of pairs obtained by [47m[cons][0ming together successive respective members of the given lists until the first list runs out. (Hence in particular, if the second argument is [47mnil[0m then each element of the first argument is paired with [47mnil[0m.) The [guard] for [47mpairlis$[0m requires that its arguments are true lists. [31;1mFunction: [0m<pairlis$> (defun pairlis$ (x y) (declare (xargs :guard (and (true-listp x) (true-listp y)))) (mbe :logic (cond ((endp x) nil) (t (cons (cons (car x) (car y)) (pairlis$ (cdr x) (cdr y))))) :exec (pairlis$-tailrec x y nil)))") (pairlis-x1 (lists alists acl2-built-ins) "Cons a given element to each member of a list The call [47m(pairlis-x1 x1 lst)[0m conses [47mx1[0m onto each element of the true-list, [47mlst[0m.") (pairlis-x2 (lists alists acl2-built-ins) "Cons each element of a list with a given element The call [47m(pairlis-x2 lst x2)[0m creates an alist consing each element of [47mlst[0m, a true-list, with [47mx2[0m.") (pand (parallel-programming acl2-built-ins) "Parallel, Boolean version of [47m[and][0m This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism], and see [parallel-programming], which has a disclaimer. Example Forms: (pand (subsetp-equal x y) (subsetp-equal y x)) (pand (declare (granularity (and (> (length x) 500) (> (length y) 500)))) (subsetp-equal x y) (subsetp-equal y x)) General Form: (pand (declare (granularity expr)) ; optional granularity declaration arg1 ... argN) where [47mN >= 0[0m and each [47margi[0m and [47mexpr[0m are arbitrary terms. [47mPand[0m evaluates its arguments in parallel. It returns a Boolean result: [47mnil[0m if any argument evaluates to [47mnil[0m, else [47mt[0m. Note that [47mpand[0m always returns a Boolean result, even though [47mand[0m can return a non-[47mnil[0m value other than [47mt[0m, namely the value of its last argument. (A moment's reflection will make it clear that in order for [47m[por][0m to parallelize efficiently, it needs to return a Boolean value; so [47mpand[0m returns a Boolean value for consistency with [47m[por][0m.) Another difference between [47mpand[0m and [47m[and][0m is that for a call of [47mpand[0m, even if an argument evaluates to [47mnil[0m, a subsequent argument may be evaluated. Consider the following example (where [47mcw[0m prints a string; see [cw]). (defun bar () (pand (equal (make-list 100000) nil) ; evaluates to nil (cw "hello world~%"))) When [47m(bar)[0m is evaluated, the above arguments of [47mpand[0m can execute in parallel, causing ``[47mhello world[0m'' to be printed to the terminal. If we had used [47mand[0m rather than [47mpand[0m, then since [47m(equal (make-list 100000) nil)[0m evaluates to [47mnil[0m, the above call of [47m[cw][0m would be avoided and no such printing would take place. Even with [47mpand[0m, such printing [3mmight[0m not take place, depending on resources, timing of thread creation, and whether or not parallel execution is enabled (see [set-parallel-execution]). Note that unlike the case for [47m[and][0m, the definition of [47mpand[0m does not provide [47m(consp x)[0m as a [guard] to [47m(car x)[0m in the call of [47mpand[0m below: (defun h (x) (declare (xargs :guard t)) (pand (consp x) (equal (car x) 'foo))) As a result, [guard] verification will fail for the above definition. If [47mpand[0m were replaced by [47mand[0m, then [guard] verification would succeed. See [parallelism-tutorial] for another example. Also see [parallelism-at-the-top-level] for restrictions on evaluating parallelism primitives from within the ACL2 top-level loop. Finally see [early-termination] to read how [47mpand[0m can offer more efficiency than [47m[and][0m by avoiding evaluation of some of its arguments.") (parallel (parallelism) "Evaluating forms in parallel See [parallelism].") (parallel-execution (parallel-programming) "For ACL2(p): configure parallel execution See [set-parallel-execution] for how to configure parallel execution for calls of [47m[plet][0m, [47m[pargs][0m, [47m[pand][0m, [47m[por][0m (but not [47m[spec-mv-let][0m).") (parallel-programming (parallelism) "Parallel programming in ACL2(p) Here we document support for parallel programming in ACL2(p), an experimental extension of ACL2; also see [parallelism]. One of ACL2's strengths lies in its ability to execute industrial models efficiently. The ACL2 source code provides an experimental parallel execution capability that can increase the speed of explicit evaluation, including simulator runs using such models, and it can also decrease the time required for proofs that make heavy use of the evaluation of ground terms. The parallelism primitives are [47m[plet][0m, [47m[pargs][0m, [47m[pand][0m, [47m[por][0m, and [47m[spec-mv-let][0m. [47m[Pand][0m and [47m[por][0m terminate early when an argument is found to evaluate to [47mnil[0m or non-[47mnil[0m, respectively, thus potentially improving on the efficiency of lazy evaluation. [47m[Spec-mv-let][0m is a modification of [47m[mv-let][0m that supports speculative and parallel execution. Of the above five parallelism primitives, all but [47m[spec-mv-let][0m allow for limiting parallel execution (spawning of so-called ``threads'') depending on resource availability. Specifically, the primitives allow specification of a size condition to control the [granularity] under which threads are allowed to spawn. You can use such [granularity] declarations in recursively-defined functions to implement data-dependent parallelism in their execution. We recommend that in order to learn to use the parallelism primitives, you begin by reading examples: see [parallelism-tutorial]. That section will direct you to further documentation topics. In addition to providing parallel programming primitives, ACL2(p) also provides the ability to execute the main ACL2 proof process in parallel. See [set-waterfall-parallelism] for further details. [3mDisclaimer[0m. The parallelism primitives have been designed for executing purely functional code, but some ACL2 functions do interesting things ``under the hood'' in order to achieve their effects. For example, [hons] primitives such as [47m[hons-wash][0m may not have the intended effect when executed under the parallelism primitives. Subtopics [Deflock] Define a wrapper macro that provides mutual exclusion in ACL2(p) [Early-termination] Early termination for [47m[pand][0m and [47m[por][0m. [Error-triples-and-parallelism] How to avoid error triples in ACL2(p) [Granularity] Limit the amount of parallelism [Pand] Parallel, Boolean version of [47m[and][0m [Parallel-execution] For ACL2(p): configure parallel execution [Parallelism-at-the-top-level] Parallel execution in the ACL2 top-level loop [Parallelism-performance] Performance issues for parallel execution [Parallelism-tutorial] A tutorial on how to use the parallelism library. [Pargs] Parallel evaluation of arguments in a function call [Plet] Parallel version of [47m[let][0m [Por] Parallel, Boolean version of [47m[or][0m [Spec-mv-let] Modification of [47m[mv-let][0m supporting speculative and parallel execution [With-output-lock] Provides a mutual-exclusion mechanism for performing output in parallel") (parallel-proof (parallelism) "Parallel proof in ACL2(p) Here we document support for parallel proof in ACL2(p), an experimental extension of ACL2; also see [parallelism], and for parallel programming in particular, see [parallel-programming]. Subtopics [ACL2p-key-checkpoints] Key checkpoints in ACL2(p) [Default-total-parallelism-work-limit] For ACL2(p): returns the default value for global [47mtotal-parallelism-work-limit[0m [Parallel-pushing-of-subgoals-for-induction] Consequences of how parallelized proofs of subgoals are pushed for induction [Unsupported-waterfall-parallelism-features] Proof features not supported with waterfall-parallelism enabled [Waterfall-parallelism] For ACL2(p): configuring the parallel execution of the waterfall [Waterfall-printing] For ACL2(p): configuring the printing within the parallelized waterfall") (parallel-pushing-of-subgoals-for-induction (parallel-proof) "Consequences of how parallelized proofs of subgoals are pushed for induction This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. The following discussion, concerning the naming of subgoals pushed for proof by induction and the timeliness of aborting when two or more goals are pushed for proof by induction, only applies when waterfall parallelism is enabled (see [set-waterfall-parallelism]). When two sibling subgoals (e.g. 4.5 and 4.6) both push goals to be proved by induction (e.g., 4.6 pushes *1 and 4.5 pushes *2), a name is assigned to the second pushed subgoal (e.g., *2) as if the first push hasn't happened (e.g., *2 is mistakenly called *1). In such a case, we say what the name _could_ be. The following non-theorem illustrates how this works. (set-waterfall-parallelism :full) (thm (equal (append (car (cons x x)) y z) (append x x y))) There is another consequence of the way the parallelized waterfall pushes subgoals for proof by induction. Without waterfall parallelism enabled, ACL2 sometimes decides to abort instead of pushing a goal for later proof by induction, preferring instead to induct on the original conjecture. But with waterfall parallelism enabled, the prover no longer necessarily immediately aborts to prove the original conjecture. Suppose for example that sibling subgoals, Subgoal 4.6 and Subgoal 4.5, each push a subgoal for induction. If the waterfall is performing the proof of each of these subgoals in parallel, the proof will no longer abort immediately after the second push occurs, that is at Subgoal 4.5. As a result, the prover will continue through Subgoal 4.4, Subgoal 4.3, and beyond. It is not until the results of combining the proof results of Subgoal 4.6 with the results from the remaining sibling subgoals (4.5, 4.4, and so on), that the proof attempt will abort and revert to prove the original conjecture by induction. This example illustrates behavior that is rather like the case that [47m:[0m[47m[otf-flg][0m is [47mt[0m, in the sense that the abort does not happen immediately, but also rather like the case that [47m:[0m[47m[otf-flg][0m is [47mnil[0m, in the sense that the abort does occur before getting to Subgoal 3.") (parallelism (acl2) "Experimental extension for parallel execution and proofs This documentation topic relates to an experimental extension of ACL2, ACL2(p), created initially by David L. Rager. See [compiling-ACL2p] for how to build an executable image that supports parallel execution. Also see community books directory [47mbooks/parallel/[0m for examples. For a completely different sort of parallelism, at the system level, see [provisional-certification]. IMPORTANT NOTE. We hope and expect that every evaluation result is correctly computed by ACL2(p), and that every formula proved using ACL2(p) is a theorem of the ACL2 logic (and in fact is provable using ACL2). However, we do not guarantee these properties. Since ACL2(p) is intended to be an aid in efficient evaluation and proof development, we focus less on ironclad soundness and more on providing an efficient and working implementation. Nevertheless, if you encounter a case where ACL2(p) computes an incorrect result, or produces a proof where ACL2 fails to do so (and this failure is not discussed in [unsupported-waterfall-parallelism-features]), please notify the implementors. The ACL2 source code provides experimental parallel execution and proof capabilities. For example, one of ACL2's strengths lies in its ability to simulate industrial models efficiently, and it can also decrease the time required for proofs about such models both by making use of parallel evaluation and by dispatching proof subgoals in parallel. While we aim to support Clozure Common Lisp (CCL), Steel Bank Common Lisp (SBCL), and Lispworks, SBCL and Lispworks both currently sometimes experience problems when evaluating the ACL2 proof process (the ``waterfall'') in parallel. Therefore, CCL is the recommend Lisp for anyone that wants to use parallelism and isn't working on fixing those problems. Subtopics [Compiling-ACL2p] Compiling ACL2(p) [Cpu-core-count] The number of cpu cores [Parallel] Evaluating forms in parallel [Parallel-programming] Parallel programming in ACL2(p) [Parallel-proof] Parallel proof in ACL2(p) [Parallelism-build] Building an ACL2 executable with parallel execution enabled [Set-parallel-execution] For ACL2(p): enabling parallel execution for four parallelism primitives [Set-total-parallelism-work-limit] For ACL2(p): set thread limit for parallelism primitives [Set-total-parallelism-work-limit-error] For ACL2(p): control the action taken when the thread limit is exceeded [Set-waterfall-parallelism] For ACL2(p): configuring the parallel execution of the waterfall [Set-waterfall-parallelism-hacks-enabled] For ACL2(p): enable waterfall-parallelism hacks [Set-waterfall-parallelism-hacks-enabled!] For ACL2(p): enabling waterfall parallelism hacks [Set-waterfall-printing] For ACL2(p): configuring the printing that occurs within the parallelized waterfall [Unsupported-parallelism-features] ACL2 features not supported in ACL2(p) [Waterfall-parallelism-for-book-certification] For ACL2(p): using waterfall parallelism during book certification") (parallelism-at-the-top-level (parallel-programming) "Parallel execution in the ACL2 top-level loop This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. Calls of parallelism primitives made explicitly in the ACL2 top-level loop, as opposed to inside function bodies, will never cause parallel execution. Such calls will either execute with serial execution or will cause an error; see [set-parallel-execution]. For a way around this restriction, see [top-level]. Consider for example the following call of [47m[pargs][0m in the ACL2 top-level loop. Instead of executing [47mpargs[0m, ACL2 macroexpands away this call, leaving us with serial execution of the arguments to the [47m[cons][0m call, or else causes an error (see [set-parallel-execution]). If there is no error, then (pargs (cons (expensive-fn-1 4) (expensive-fn-2 5))) expands into: (cons (expensive-fn-1 4) (expensive-fn-2 5)) One trivial way to enable parallel execution of a form is to surround it with a call to macro [top-level]. Consider the following example. (top-level (pargs (cons (expensive-fn-1 4) (expensive-fn-2 5)))) Then in an executable image that supports parallel execution --- see [compiling-ACL2p] for instructions on how to build such an executable --- [47m(expensive-fn-1 4)[0m and [47m(expensive-fn-2 5)[0m can evaluate in parallel. A second way to enable parallel execution of a form is to place it inside a function body. For example, consider the following definition. (defun foo (x y) (pargs (cons (expensive-fn-1 x) (expensive-fn-2 y)))) Then in an executable image that supports parallel execution, submission of the form [47m(foo 4 5)[0m can cause parallel execution of [47m(expensive-fn-1 4)[0m and [47m(expensive-fn-2 5)[0m. Note that [guard]s need not be verified in order to obtain [parallel] execution. The only restrictions on parallel execution are to use an ACL2 executable supporting it, to avoid calling parallelism primitives directly in the top-level loop, to have sufficient resources (especially, threads) available, and to avoid explicitly disabling parallel execution (see [set-parallel-execution]).") (parallelism-build (parallelism) "Building an ACL2 executable with parallel execution enabled See [compiling-ACL2p].") (parallelism-performance (parallel-programming) "Performance issues for parallel execution This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. See [granularity] for an important construct that limits the spawning of parallel computations, which can be important when a computation is too short-lived to warrant a separate thread. There are times in which parallelism provides no speedup because of garbage collection in the underlying Lisp implementation. The following example illustrates this phenomenon. If you change the [47m[granularity][0m declaration so that the depth bound is 3, 4, or larger instead of 2, you may still find no speedup. In all cases you may find that parallelism results in a significantly greater time spent in garbage collection. (include-book "finite-set-theory/osets/sets" :dir :system) (defun set::pmergesort-exec (x depth) (declare (xargs :mode :program)) (cond ((endp x) nil) ((endp (cdr x)) (set::insert (car x) nil)) (t (mv-let (part1 part2) (set::split-list x nil nil) (pargs (declare (granularity (< depth 2))) (set::union (set::pmergesort-exec part1 (1+ depth)) (set::pmergesort-exec part2 (1+ depth)))))))) (defconst *x* (reverse (fromto 1 400000))) (time$ (length (set::pmergesort-exec *x* 0))) (set-parallel-execution nil) (time$ (length (set::pmergesort-exec *x* 0)))") (parallelism-tutorial (parallel-programming) "A tutorial on how to use the parallelism library. This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. In this topic we introduce the ACL2 parallelism primitives using the example of a doubly-recursive Fibonacci function, whose basic definition is as follows. See [parallelism] for a very high-level summary of the parallelism capability described here, and see [compiling-ACL2p] for how to build an executable image that supports parallel execution. Here, we assume that such an executable is being used. [31;1mSerial Fibonacci[0m (defun fib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (+ (fib (- x 1)) (fib (- x 2)))))) [31;1mIntroducing[0m [47m[Pargs][0m A simple way to introduce parallelism into this function definition is to wrap the addition expression with a call of [47m[pargs][0m, and the arguments to the addition will be computed in parallel whenever resources are available. As a result, we end up with a very similar and thus intuitive function definition. Note that we replaced [47m[+][0m by [47m[binary-+][0m, since [47m[pargs][0m expects a function call, not a macro call. (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (pargs (binary-+ (pfib (- x 1)) (pfib (- x 2))))))) [31;1mIntroducing the Granularity Problem[0m After you submit the above two versions of the Fibonacci function, test them with the following forms. (time$ (fib 10)) (time$ (pfib 10)) Now increase the argument by increments of 5 to 10 until you find your curiosity satisfied or your patience wearing thin. You can interrupt evaluation if necessary and return to the ACL2 loop. You will immediately notice that you have not increased execution speed, at least not by much, by introducing parallelism. First, consider the computation of [47m(pfib 4)[0m. Assuming resources are available, [47m(pfib 4)[0m will create a thread for computing [47m(pfib 3)[0m and another thread for [47m(pfib 2)[0m. It is easy to imagine that setting up each thread takes much longer than the entire computation of [47m(fib 4)[0m. Second, we must realize that if we have two threads available for computing [47m(fib 10)[0m, then the evaluation of [47m(fib 8)[0m will probably complete before the evaluation of [47m(fib 9)[0m. Once [47m(fib 8)[0m finishes, parallelism resources will become available for the next recursive call made on behalf of [47m(fib 9)[0m. If for example that call is [47m(fib 3)[0m, we will waste a lot of cycles just handing work to the thread that does this relatively small computation. We need a way to ensure that parallelism resources are only used on problems of a "large" size. Ensuring that only "large" problems are spawned is called the ``granularity problem.'' In summary: We want to tell ACL2 that it can evaluate the arguments of [47m[pargs][0m in parallel only when the parameter of [47mpfib[0m is greater than some threshold. Our tests using CCL have suggested that 27 is a reasonable threshold. [31;1mExplicit Programming for the Granularity Problem[0m One way to avoid the granularity problem is to duplicate code as follows. (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (if (> x 27) ; the granularity test (pargs (binary-+ (pfib (- x 1)) (pfib (- x 2)))) (binary-+ (pfib (- x 1)) (pfib (- x 2))))))) Duplicating code is fundamentally a bad design principle, because it can double the work for future maintenance. A ``granularity form'' is an expression (declare (granularity <form>)) that can allow threads to be spawned (without duplicating code) whenever the evaluation of [47m<form>[0m results in a non-[47mnil[0m value. It may be placed inside any call of a parallelism primitive, in a position documented separately for each primitive. Here is a definition of [47mpfib[0m using this feature for a call of the parallelism primitive [47m[pargs][0m. (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (pargs (declare (granularity (> x 27))) (binary-+ (pfib (- x 1)) (pfib (- x 2))))))) Test each version as follows (or substitute your own natural number for 33). (time$ (fib 33)) (time$ (pfib 33)) [31;1mAnother Granularity Issue Related to Thread Limitations[0m Our implementation of parallelism primitives has the property that once a thread is assigned a computation, that assignment stays in effect until the computation is complete. In particular, if a thread encounters a parallelism primitive that spawns child threads, the parent thread stays assigned, waiting until the child computations complete before it can continue its own computation. In the meantime, the parent thread reduces the number of additional threads that Lisp can provide by 1, rather than being reassigned to do other work. How can this lack of reassignment affect the user? Consider, for example, the application of a recursive function to a long list. Imagine that this function is written so that the body contains a recursive call, for example as [47m(pargs (process (car x)) (recur (cdr x)))[0m. Each such [47m[pargs][0m call that spawns child work must wait for its children, one of which is the work of evaluating [47m(recur (cdr x))[0m, to complete. There is an ACL2 limit on how much pending work can be in the system, limiting the number of [47m[pargs][0m calls that can result in parallel execution. For example, if the ACL2 limit is k and each call of [47m[pargs][0m actually spawns threads for evaluating its arguments, then after k [47mcdr[0ms there will be no further parallel execution. Possible solutions may include reworking of algorithms (for example to be tree-based rather than list-based) or using appropriate granularity forms. We hope that future implementations will allow thread ``re-deployment'' in order to mitigate this problem. This problem applies to [47m[plet][0m, [47m[pargs][0m, [47m[pand][0m, [47m[por][0m, and [47m[spec-mv-let][0m. [31;1mIntroducing[0m [47m[Plet][0m We can use a [47m[let][0m binding to compute the recursive calls of [47mfib[0m and then add the bound variables together, as follows. (defun fib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (let ((a (fib (- x 1))) (b (fib (- x 2)))) (+ a b))))) By using the parallelism primitive [47m[plet][0m, we can introduce parallelism much as we did using [47m[pargs][0m, with an optional granularity form, as follows. (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((or (zp x) (<= x 0)) 0) ((= x 1) 1) (t (plet (declare (granularity (> x 27))) ((a (pfib (- x 1))) (b (pfib (- x 2)))) (+ a b))))) Notice that this time, we were able to use [47m+[0m rather than being forced to use [47mbinary-+[0m. Unlike [47m[pargs][0m, which expects a function call (not a macro call), [47m[plet][0m allows macros at the top level of its body. [31;1mIntroducing[0m [47m[Pand][0m (By Way of a Tree Validation Example) Consider ``genetic trees'' that contains leaves of DNA elements, in the sense that each tip is one of the symbols [47mA[0m, [47mG[0m, [47mC[0m, or [47mT[0m. First we define the function [47mvalid-tip[0m which recognizes whether a tip contains one of these symbols. (defun valid-tip (tip) (declare (xargs :guard t)) (or (eq tip 'A) (eq tip 'G) (eq tip 'C) (eq tip 'T))) Now we define a function that traverses the tree, checking that every tip is valid. (defun valid-tree-serial (tree) (declare (xargs :guard t)) (if (atom tree) (valid-tip tree) (and (valid-tree-serial (car tree)) (valid-tree-serial (cdr tree))))) We also define a parallel version. (defun valid-tree-parallel (tree) (declare (xargs :guard t)) (if (atom tree) (valid-tip tree) (pand (valid-tree-parallel (car tree)) (valid-tree-parallel (cdr tree))))) Before we can time the functions, we need to create test trees. We have found that test trees need to be approximately 1 gigabyte before we clearly see speedup, and we make them asymmetric to demonstrate the ability of our implementation to adapt to asymmetric data. We can create the trees with the execution of the following forms. (defun make-valid-binary-tree (x) (declare (xargs :mode :program)) (if (< x 0) (cons (cons 'C 'G) (cons 'A 'T)) (cons (make-valid-binary-tree (- x 2)) ; 2 to make asymmetric (make-valid-binary-tree (- x 1))))) (defconst *valid-tree* (make-valid-binary-tree 30)) ; takes awhile (defconst *invalid-tree* (cons *valid-tree* nil)) ; nil is invalid tip We can time our functions with the forms: (time$ (valid-tree-serial *valid-tree*)) (time$ (valid-tree-parallel *valid-tree*)) Unfortunately, the serial version runs faster than the parallelism version; however, there is more to this story. [31;1mDemonstrating Early Termination with an Invalid Tree[0m Now observe this magic: (time$ (valid-tree-serial *invalid-tree*)) (time$ (valid-tree-parallel *invalid-tree*)) The serial version took awhile, while the parallel version finished almost immediately. The test for validation was split into testing the [47m[car][0m and the [47m[cdr][0m of the [47m*invalid-tree*[0m root, and since the [47mcdr[0m was equal to [47mnil[0m, its test returned immediately. This immediate return quickly interrupted the computation associated with the [47mcar[0m, and returned the result. [31;1mGranularity with[0m [47m[Pand][0m We can also define a parallel version with a granularity form: (defun valid-tree-parallel (tree depth) (declare (xargs :guard (natp depth))) (if (atom tree) (valid-tip tree) (pand (declare (granularity (< depth 5))) (valid-tree-parallel (car tree) (1+ depth)) (valid-tree-parallel (cdr tree) (1+ depth))))) We can test this form by executing our previous forms. You will probably find some speedup on a machine with several cores available, but more speedup can likely be obtained with an expensive test on the leaves in place of [47mvalid-tip[0m. (time$ (valid-tree-serial *valid-tree*)) (time$ (valid-tree-parallel *valid-tree* 0)) [31;1mIntroducing[0m [47m[Por][0m [47m[Por][0m can be used in the same way as [47m[pand][0m, but with early termination occurring when an argument evaluates to a non-[47mnil[0m value, in which case the value returned is [47mt[0m. Finally, [47m[por][0m also supports the use of a [granularity] form.") (pargs (parallel-programming acl2-built-ins) "Parallel evaluation of arguments in a function call This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism], and see [parallel-programming], which has a disclaimer. Example Forms: (pargs (binary-+ (fibonacci (- x 1)) (fibonacci (- x 2)))) (pargs (declare (granularity (> x 35))) (binary-+ (fibonacci (- x 1)) (fibonacci (- x 2)))) General Form: (pargs (declare (granularity expr)) ; optional granularity declaration (f arg1 ... argN)) where [47mN >= 0[0m and each [47margi[0m and [47mexpr[0m are arbitrary terms. Logically, [47mpargs[0m is just the identity macro, in the sense that the above forms can logically be replaced by [47m(f arg1 ... argN)[0m. However, this [47mpargs[0m form may parallelize the evaluation of arguments [47marg1[0m through [47margN[0m before applying function [47mf[0m to those results. If the above [47m[granularity][0m declaration is present, then its expression ([47mexpr[0m above) is first evaluated, and if the result is [47mnil[0m, then such parallelism is avoided. Even if parallelism is not thus avoided, parallelism may be limited by available resources. Since macros can change expressions in unexpected ways, it is illegal to call [47mpargs[0m on a form that is a macro call. To parallelize computation of arguments to a macro, see [plet]. See [parallelism-at-the-top-level] for restrictions on evaluating parallelism primitives from within the ACL2 top-level loop.") (partial-encapsulate (events encapsulate) "Introduce functions with some constraints unspecified See [encapsulate] for relevant background. [47mPartial-encapsulate[0m is a variant of [47mencapsulate[0m for which some of the constraints are implicit. This is an advanced capability that is useful when one installs special-purpose code, possibly in raw Lisp, using a trust tag (see [defttag]). Introduction The syntax for [47mpartial-encapsulate[0m is the same as the syntax of [47mencapsulate[0m, except for the addition of an argument, [47msupporters[0m, which is described below. General Form: (partial-encapsulate (signature ... signature) (f1 ... fk) ; supporters ev1 ... evn) where, as for [47mencapsulate[0m: each [47msignature[0m is a well-formed [signature], each describing a different function symbol, and each [47mevi[0m is an embedded event form (see [embedded-event-form]). The additional argument (shown above) is a true-list of function symbols, the [3msupporters[0m: it is an error if any such symbol, [47mfi[0m, is not a known function symbol at the time the [47mpartial-encapsulate[0m call is evaluated, the exception being that [47mfi[0m may be introduced in one of the signatures. A [47mpartial-encapsulate[0m form must satisfy the following three requirements in addition to those of the corresponding [47mencapsulate[0m form: it must have at least one signature, it must not occur within any other [47mencapsulate[0m or [47mpartial-encapsulate[0m form that has at least one signature, and every function symbol that it introduces must be specified in one of the signatures. A call of [47mpartial-encapsulate[0m introduces its signature functions together with its exported theorems, exactly as though it had been the call of [47mencapsulate[0m with the same signatures and events, however with one difference: the [47mpartial-encapsulate[0m logically incorporates additional constraints that are not mentioned. This is discussed further below, but for now let us note that because of this difference, a successful evaluation of a [47mpartial-encapsulate[0m form results in a special ``unknown-constraints'' designation for the functions introduced by the signatures. Any attempt to access the constraints for those functions will thus fail. Consider the following example, which introduces [47mf[0m as a constrained function symbol that is constrained not only by the property that [47mf[0m returns a boolean, but also by additional, unspecified (implicit) constraints. (partial-encapsulate ((f (x) t)) nil (local (defun f (x) (declare (xargs :guard t)) (consp x))) (defthm booleanp-f (booleanp (f x)) :rule-classes :type-prescription)) (defthm symbolp-f (symbolp (f y))) (encapsulate ((g (x) t)) (local (defun g (x) (consp x))) (defthm booleanp-g (booleanp (g x)))) Then the following fails, even though it would succeed if we replace [47mpartial-encapsulate[0m by [47mencapsulate[0m above. The reason is that the partial-encapsulate form allows for constraints beyond just the property that [47mf[0m is boolean. Imagine that special code had been inserted (using a trust tag) for reasoning about [47mf[0m when proving a theorem like [47msymbolp-f[0m that we were now trying to functionally instantiate. ; Functional instantiation FAILS because of unknown-constraints on f (defthm symbolp-g (symbolp (g y)) :hints (("Goal" :by (:functional-instance symbolp-f (f g))))) Supporters and corresponding encapsulate A [47mpartial-encapsulate[0m represents any [47mencapsulate[0m form that introduces the same function symbols, has the same signatures, and extends the constraints introduced such that every function symbol occurring in at least one of the additional constraints must either be mentioned in one of the [47mevi[0m or be among the list of supporters, [47m(f1 ... fk)[0m. We may refer to such an [47mencapsulate[0m form as a ``corresponding encapsulate''. The user of [47mpartial-encapsulate[0m should keep in mind such a set of additional constraints. The supporters should thus include all function symbols in the theorems exported from the intended corresponding encapsulate, except that signature functions are always included among the supporters whether specified or not, and hence their inclusion is optional. The list of supporters is used for generating proof obligations for a [47m:functional-instance[0m [lemma-instance]. Specifically, the supporters serve as the ``ancestors'' of the partial encapsulate's signature functions, in the constraint-generation algorithm described in the documentation for [constraint]. Thus, if supporters are missing that occur in the intended corresponding encapsulate, then functional instantiation may be unsound because some proof obligations fail to be generated. Note that in the typical application described next, where the implicit constraints all specify evaluation results for calls of signature functions as discussed below, the specified list of supporters can simply be [47mnil[0m. Applications A trust tag (see [defttag]) is not needed for evaluation of a partial-encapsulate form. However, for a typical application of partial-encapsulate --- redefinition of a constrained function in raw Lisp --- a trust tag is of course necessary (see [defttag]). In such a case, the corresponding encapsulate may be viewed as extending the original partial-encapsulate with all theorems of the form [47m(equal (f a1 ... ak) val)[0m, ranging over all computations [47m(f a1 ... ak)[0m ever to be evaluated (a finite but potentially huge set) where [47mval[0m is the value returned for [47m(f a1 ... ak)[0m. It is the responsibility of the creator of such an application to ensure that all evaluations satisfy the original constraints of the partial-encapsulate. Note that in this sort of application --- that is, where the implicit constraints all arise from function evaluations --- the supporters argument may soundly be [47mnil[0m, since only the signature functions are involved in the implicit constraints (and those functions are automatically included among the supporters, even when not specified by the user). For examples of such an application, including explanatory comments, see [community-books] and [47mbooks/demos/partial-encapsulate.lisp[0m and [47mbooks/demos/include-raw-examples/mem-access-sound/mem.lisp[0m. Partial-encapsulates are, in essence, also used in the implementation of dependent clause-processors, where the list of supporters might well be non-[47mnil[0m. See [define-trusted-clause-processor]. Implementation This section is provided as a reference for those interested, but can probably be safely skipped by most readers. Consider the following example. ACL2 !>:trans1 (partial-encapsulate ((f0 (x) t)) (g0) (local (defun f0 (x) x)) (defthm f0-prop (implies (integerp x) (integerp (f0 x))))) (ENCAPSULATE ((F0 (X) T)) (LOCAL (DEFUN F0 (X) X)) (DEFTHM F0-PROP (IMPLIES (INTEGERP X) (INTEGERP (F0 X)))) (SET-UNKNOWN-CONSTRAINTS-SUPPORTERS G0)) ACL2 !> This example illustrates that a [47mpartial-encapsulate[0m call expands to a call of [47mencapsulate[0m obtained by removing the supporters argument, but with the following extra event inserted after given list of events, where [47m(f1 ... fk)[0m is the specified list of supporters. (set-unknown-constraints-supporters f1 ... fk) The macro, [47mset-unknown-constraints-supporters[0m, extends a table, [47munknown-constraints-table[0m. As evaluation of the partial-encapsulate concludes, the world is extended so that each signature function has a [47m'constraint-lst-etc[0m property indicating that its constraints are unknown, but with supporters (``ancestors'', as discussed above) according to that table. This macro call can thus be inserted non-[local]ly within an encapsulate, anywhere after the local function definitions, to make an encapsulate behave like a partial-encapsulate.") (partition-rest-and-keyword-args (pointers) "See [system-utilities].") (pathname (books-reference) "Introduction to filename conventions in ACL2 The notion of pathname objects from Common Lisp is not supported in ACL2, nor is the function [47mpathname[0m. However, ACL2 supports file operations, using conventions for naming files based on those of the Unix (trademark of AT&T) operating system, so that the character [47m/[0m is used to terminate directory names. Some file names are ``absolute'' (complete) descriptions of a file or directory; others are ``relative'' to the current working directory or to the connected book directory. See [cbd] for how relative pathnames are elaborated to absolute pathnames. We emphasize that even for users of Windows-based systems or Macintosh computers, ACL2 file names are in the Unix style. We will call these [3mACL2 pathnames[0m, often omitting the ``ACL2.'' Pathnames starting with the directory separator ([47m/[0m) or the tilde character ([47m~[0m) are absolute pathnames. All other pathnames are relative pathnames. An exception is in the Microsoft Windows operating system, where it is illegal for the pathname to start with a tilde character but the drive may be included, e.g., [47m"c:/home/smith/acl2/book-1.lisp"[0m. In fact, the drive [3mmust[0m be included in the portcullis of a book; see [portcullis]. Note also that some host Common Lisps will not support pathnames starting with [47m"~"[0m, for example [47m~smith[0m, though ACL2 will generally support those starting with [47m"~/"[0m regardless of the host Common Lisp. Consider the following examples. The filename string "/home/smith/acl2/book-1.lisp" is an absolute pathname, with top-level directory [47m"home"[0m, under that the directory [47m"smith"[0m and then the directory [47m"acl2"[0m, and finally, within that directory the file [47m"book-1.lisp"[0m. If the connected book directory is [47m"/home/smith/"[0m (see [cbd]), then the filename string above also corresponds to the relative filename string "acl2/book1.lisp". Finally, we note that (on non-Windows systems) the pathname [47m"~"[0m and pathnames starting with [47m"~/"[0m are illegal in books being certified. Otherwise, a subsidiary [47m[include-book][0m form would have a different meaning at certification time than at a later time when the certified book is included by a different user.") (patterned-congruence (rule-classes) "Removing restrictions on classic [congruence] rules This topic assumes familiarity with the basics of congruence rules; see [congruence]. Some aspects of congruence rules carry over to patterned congruence rules; in particular, they may be [disable]d, but they are not tracked for reporting in the [summary]. We begin our discussion by showing some patterned congruence rules and using them to illustrate some terminology. Example forms: ; ``Shallow'' patterned congruence rule: (implies (e1 y1 y2) (e2 (f1 3 y1 (cons x x)) (f1 3 y2 (cons x x)))) ; ``Deep'' patterned congruence rule: (implies (e1 y1 y2) (e2 (mv-nth 1 (foo x y1 z)) (mv-nth 1 (foo x y2 z)))) ; ``Deep'' patterned congruence rule: (implies (e1 y1 y2) (e2 (mv-nth 1 (foo x (g y1) z)) (mv-nth 1 (foo x (g y2) z)))) In the example forms above, [47me1[0m and [47me2[0m are known equivalence relations, which (as for classic congruence rules) we call the ``inner'' and ``outer'' equivalences. The examples above are not classic, because the ``function symbol'' of the rule --- [47mf1[0m in the first example, [47mmv-nth[0m in the second and third examples --- is not being applied to distinct variables. The first example is called ``shallow'' because the ``variable'' of the rule, [47my1[0m, is a top-level argument of the ``lhs'' of the rule, which is the first call of [47mf1[0m; the others do not have this property, as [47my1[0m is buried under further function calls. We invite you to browse the community book [47mdemos/patterned-congruences.lisp[0m, which provides several examples of patterned congruence rules and their use, as well as several examples of formulas that are illegal as patterned congruence rules for various reasons. We now define the class of patterned congruence rules. The general form of a patterned congruence rule is (implies (equiv1 x y) (equiv2 lhs rhs)), where the rule is not classic (see [congruence]) and the following conditions hold. [47mEquiv1[0m and [47mequiv2[0m are known equivalence relations, which (as in the classic case) we call the ``inner'' and ``outer'' equivalences, respectively. The terms [47mlhs[0m and [47mrhs[0m are function calls, and we call these the [47mlhs[0m and [47mrhs[0m of the rule, respectively. The variable [47mx[0m occurs in [47mlhs[0m and the variable [47my[0m occurs in [47mrhs[0m. These must be the only occurrences of [47mx[0m and [47my[0m in either [47mlhs[0m or [47mrhs[0m, and [47mrhs[0m must be the result of substituting [47my[0m for [47mx[0m in [47mlhs[0m. None of the following may occur as a function symbol of [47mlhs[0m (or, equivalently, [47mrhs[0m): [47mif[0m, [47mimplies[0m, [47mequal[0m, or a [47m[lambda][0m. Patterned congruence rules are used, much like classic congruence rules, by the ACL2 rewriter to determine which equivalence relations to maintain as it dives into a term. Recall (see [congruence]) that if it suffices for the rewriter to maintain [47me2[0m when rewriting a term, then it suffices to maintain [47me1[0m when rewriting an argument of that term provided there is an applicable congruence rule with outer equivalence [47me2[0m and inner equivalence [47me1[0m. An analogous principle holds for patterned congruence rules, which by the way consider refinements of the outer equivalence just as is done by classic congruence rules. But there is a new wrinkle because the lhs of a patterned congruence rule is a function call that can have non-variable arguments. Consider the following events. (defun e1 (x y) (equal x y)) (defequiv e1) (defun f10 (x) (list 3 x x)) (defun f11 (x y) (declare (ignore y)) x) (defthm e1-implies-iff-f11-cong-2 (implies (e1 y1 y2) (iff (f11 (f10 x) y1) (f11 (f10 x) y2))) :rule-classes (:congruence)) (in-theory (disable f11 (:t f11) e1)) The following proof fails, because the indicated call of [47mf10[0m expands before the rewriter is applied to [47mb2[0m --- otherwise [47mb2[0m would rewrite to [47mb1[0m because [47m(e1 b1 b2)[0m is known in that context and by the rule above, it suffices to maintain [47me1[0m when rewriting [47mb2[0m. (thm (implies (e1 b1 b2) (iff (f11 (f10 a) b1) (f11 (f10 a) ; expands before b2 is rewritten b2)))) On the other hand, the following succeeds because the rewrite discussed above does indeed take place when the indicated call of [47mf10[0m does not expand. (thm (implies (e1 b1 b2) (iff (f11 (f10 a) b1) (f11 (f10 a) ; does not expand b2))) :hints (("Goal" :in-theory (disable f10)))) This inherent sequentiality of matching is important for soundness, as is illustrated by examples using the function [47msome-consp[0m in the aforementioned community book, [47mdemos/patterned-congruences.lisp[0m. The example above illustrates the following point: as the rewriter dives into a term, then when matching is attempted using a patterned congruence rule, rewriting has already taken place to the left of the current subterm. By contrast, note that this pass through the rewriter will not yet have completed rewriting of terms to the right of the current subterm when matching a patterned congruence rule. Patterned congruence rules are used primarily during the process of [3mrewriting[0m. In particular, unlike classic congruence rules, they are [3mnot[0m used to do equality substitution at the goal level or in [proof-builder] commands such as [47m=[0m and [47mequiv[0m. The simplest way to understand this point may be with the following trivial example. (defstub foo (x y z) t) (thm (implies (equal u (* a b)) (foo u u b))) The theorem fails, of course, but what is interesting is that ACL2 simplifies it by replacing the variable [47mu[0m by the term [47m(* a b)[0m throughout the goal and then dropping the equality, to produce the following goal. (FOO (* A B) (* A B) B) This sort of substitution can also be made when [47mequal[0m is replaced by a known equivalence relation, if a classic congruence rule for [47mfoo[0m justifies the substitution. But that is not the case for our implementation of patterned congruence rules. The discussion above is intended to suffice for effective use of patterned congruence rules. If you are interested in their [3mimplementation[0m, we invite you to read the long comment entitled ``Essay on Patterned Congruences and Equivalences'' in ACL2 source file [47mrewrite.lisp[0m.") (pbt (history) "Print the [command]s back through a [command] descriptor Examples: :pbt :max ; print back through the most recent command :pbt :x ; print back through the most recent command :pbt fn ; print back through the introduction of fn :pbt 5 ; print back through the fifth command executed :pbt (:x -4) ; print back through the most recent five commands See [command-descriptor]. [47mPbt[0m takes one argument, a [command] descriptor, and prints the [command]s from [47m:max[0m (aka [47m:x[0m) through the one described. See [command-descriptor] for a description of what a [command] descriptor is. See [pc] for a description of the format used to display [command]s. [47mPbt[0m will print the [command]s that [47m[ubt][0m will undo.") (pc (history) "Print the [command] described by a [command] descriptor Examples: :pc 3 ; print the third command executed :pc :max ; print the most recent command :pc :x ; print the most recent command :pc fn ; print the command that introduced fn See [command-descriptor]. [47mPc[0m takes one argument, a [command] descriptor, and prints the [command] identified by that descriptor, doing so in full unless the [ld-evisc-tuple] is non-nil, in which case it abbreviates using that evisc-tuple; see [evisc-tuple]. See [command-descriptor]. For example: ACL2 !>:pc foo LVd 52 (DEFUN FOO (X) X) [47mPc[0m always prints a space first, followed by four (possibly blank) characters (``LVd'' above) explained below. Then [47mpc[0m prints the [command] number, a number uniquely identifying the [command]'s position in the sequence of [command]s since the beginning of the user's session. Finally, the [command] itself is printed. While [47mpc[0m always prints a space first, some [history] [command]s, for example [47m:[0m[47m[pcs][0m and [47m:[0m[47m[pe][0m, use the first column of output to delimit a region of [command]s or to point to a particular event (perhaps as modified using [47m[extend-pe-table][0m) within a [command]. For example, [47m:pcs 52 54[0m will print something like /LVd 52 (DEFUN FOO (X) X) LV 53 (DEFUN BAR (X) (CONS X X)) \ 54 (DEFTHM FOO-BAR (EQUAL (CAR (BAR X)) (FOO X))) : ... 127 (DEFUN LATEST (X) X) Here, the two slash characters in the first column are intended to suggest a bracket delimiting [command]s 52 through 54. The last [command] printed by [47m[pcs][0m is always the most recent [command], i.e., the [command] at [47m:here[0m, and is separated from the rest of the display by an ellipsis if some [command]s are omitted. Similarly, the [47m:[0m[47m[pe][0m [command] will print a particular event (perhaps as modified using [47m[extend-pe-table][0m) within a [command] block and will indicate that event by printing a ``[47m[>][0m'' in the first column. The symbol is intended to be an arrow pointing at the event in question. For example, [47m:[0m[47m[pe][0m [47mtrue-listp-app[0m might print: 1 (INCLUDE-BOOK "list-book") \ > (DEFTHM TRUE-LISTP-APP (EQUAL (TRUE-LISTP (APP A B)) (TRUE-LISTP B))) using the arrow to indicate the event itself. The slash printed to connect the [command], [47m[include-book][0m, with the event, [47m[defthm][0m, is intended to suggest a tree branch indicating that the event is inferior to (and part of) the [command]. The mysterious characters sometimes preceding a [command] have the following interpretations. The first two have to do with the function symbols introduced by the [command] and are blank if no symbols were introduced. At any time we can classify our function symbols into disjoint sets, which we will here name with characters. The ``[47mP[0m'' functions are those in [47m:[0m[47m[program][0m mode. The ``[47mL[0m'' functions are those in [47m:[0m[47m[logic][0m mode whose [guard]s have not been verified. The ``[47mV[0m'' functions are those in [47m:[0m[47m[logic][0m mode whose [guard]s have been verified. You may also see the use of (lower-case) ``[47mv[0m'' to indicate functions introduced by [47m[encapsulate][0m. Note that [47m[verify-termination][0m and [47m[verify-guards][0m cause function symbols to be reclassified. If a [command] introduces function symbols then the first mysterious character indicates the class of the symbols at the time of introduction and the second character indicates the current class of the symbols (if the current class is different from the introductory class). Thus, the display PLd 52 (DEFUN FOO (X) X) tells us that [command] 52 introduced a [47m:[0m[47m[program][0m function but that some [command] after 52 changed its mode to [47m:[0m[47m[logic][0m and that the [guard]s of [47mfoo[0m have not been verified. That is, [47mfoo[0m's termination has been verified even though it was not verified as part of the [command] that introduced [47mfoo[0m. Had a subsequent [command] verified the [guard]s of [47mfoo[0m, the display would contain a [47mV[0m where the [47mL[0m is. The display P d 52 (DEFUN FOO (X) X) indicates that [47mfoo[0m was introduced in [47m:[0m[47m[program][0m mode and still is in that mode. The third character indicates the [enable]d/[disable]d status of the [rune]s introduced by the [command]. If the status character is blank then all the [rune]s (if any) introduced are [enable]d. If the status character is ``[47mD[0m'' then some [rune]s were introduced and they are all [disable]d. If the status character is ``[47md[0m'' then at least one, but not all, of the [rune]s introduced is [disable]d. Thus, in the display L d 52 (DEFUN FOO (X) X) we see that some [rune] introduced by [command] 52 is [disable]d. As noted in the documentation for [rune], a [47m[defun][0m [command] introduces many [rune]s, e.g., the axiomatic definition rule, [47m(:definition fn)[0m, the executable-counterpart rule, [47m(:executable-counterpart fn)[0m, and [type-prescription]s, [47m(:type-prescription fn)[0m. The display above does not say which of the [rune]s based on [47mfoo[0m is [disable]d, but it does tell us one of them is; see [disabledp] for how to obtain the disabled runes for a given function symbol. Remark for users of the [break-rewrite] utility. Inside the [47m:[0m[47m[brr][0m loop, the status character shows whether rules are disabled at the current point of the proof that is currently underway, rather than whether rules are disabled globally. For example, if you break while the prover is working on Subgoal 3, and the [hints] supplied for the proof specify [47m("Subgoal 3" :in-theory (disable foo))[0m, then regardless of whether or not rules associated with [47mfoo[0m are enabled globally, the status character indicates whether they are enabled while processing Subgoal 3. Finally, a fourth character is printed, indicating whether functions are [memoize]d. A symbol may be memoized if it is a function symbol that is not constrained (i.e., introduced by [47m[defchoose][0m or in the [signature] of an [47m[encapsulate][0m event). If the command introduces no symbol that may be memoized, then a space is printed. Otherwise, if every memoizable symbol is memoized, an ``[47mM[0m'' is printed. Otherwise, an ``[47mm[0m'' is printed.") (pcb (history) "Print the [command] block described by a [command] descriptor Examples: :pcb :max ; print the most recent command block :pcb :x ; print the most recent command block :pcb fn ; print the command block that introduced fn :pcb 5 ; print the fifth command block See [command-descriptor]. [47mPcb[0m takes one argument, a [command-descriptor], and prints in an abbreviated format the [command] block of the command described. See [pc] for description of the format in which [command]s are displayed. The command block of a command consists of the command itself and all of the [events] it created. If the command created a single event and that event is in fact the command (i.e., if the command typed was just an event such as a [47m[defun][0m or [47m[defthm][0m rather than a macro that expanded to some event forms), then [47mpcb[0m just prints the command (unless the event is replaced using [47m[extend-pe-table][0m). [47mPcb[0m sketches the command and all of the [events] it created, rather than printing them fully. If you wish to see just the command, in its entirety, use [47m[pc][0m. If you wish to see one of the [events] within the block, in its entirety, use [47m[pe][0m. If you wish to see the command sketched and all of the events it created, in their entirety, use [47m[pcb!][0m. For a sequence of commands, see [pcs] and [gcs].") (pcb! (history) "Print in full the [command] block described by a [command] descriptor Examples: :pcb! :max ; print the most recent command block :pcb! :x ; print the most recent command block :pcb! fn ; print the command block that introduced fn :pcb! 5 ; print the fifth command block See [command-descriptor]. [47mPcb![0m takes one argument, a [command] descriptor, and prints the [command] block of the [command] described. Unlike [47m[pcb][0m, [47mpcb![0m prints the event forms in full (see [pcb] for details) --- unless the [ld-evisc-tuple] is non-nil, in which case it abbreviates using that evisc-tuple; see [evisc-tuple].") (pcs (history) "Print the sequence of [command]s between two [command] descriptors Examples: :pcs 1 5 ; print commands 1 through 5 :pcs 5 1 ; same as above :pcs :x (:x -3) ; print the 3 most recently executed commands :pcs fn assoc-of-fn ; print the commands between the one that introduced ; fn and the one that introduced assoc-of-fn [47mPcs[0m takes two arguments, both of which are [command] descriptors, and prints the [command]s between them with [47m[pc][0m. The order of the two descriptors is irrelevant. See [command-descriptor] for a description of [command] descriptors. See [pc] for a description of the format in which [command]s are displayed. For a related utility that simply returns a sequence of commands, see [get-command-sequence].") (pe (history) "Print the events named by a logical name Example: :pe fn ; sketches the command that introduced fn and ; prints in full the event within it that created fn. See [logical-name]. [47mPe[0m takes one argument, a logical name, and prints the event corresponding to the name, doing so in full unless the [ld-evisc-tuple] is non-nil, in which case it abbreviates using that evisc-tuple; see [evisc-tuple]. [47mPe[0m also sketches the [command] responsible for that event if the [command] is different from the event itself. To remind you that the event is inferior to the [command], i.e., you can only undo the entire [command], not just the event, the event is indented slightly from the [command] and a slash (meant to suggest a tree branch) connects them. See [pc] for a description of the format used to display a [command]. If the given logical name corresponds to more than one event, then [47m:pe[0m will print the above information for every such event. Here is an example of such behavior. ACL2 !>:pe nth -4270 (ENCAPSULATE NIL ...) \ >V (VERIFY-TERMINATION NTH) Additional events for the logical name NTH: PV -4949 (DEFUN NTH (N L) "Documentation available via :doc" (DECLARE (XARGS :GUARD (AND (INTEGERP N) (>= N 0) (TRUE-LISTP L)))) (IF (ENDP L) NIL (IF (ZP N) (CAR L) (NTH (- N 1) (CDR L))))) ACL2 !> If you prefer to see only the formula for the given name, for example if it is part of a large [47m[mutual-recursion][0m, see [pf]. See [extend-pe-table] for a way to specify a form to be printed in place of the actual event. To avoid such replacement, see [pe!].") (pe! (history) "Print events as with [47m[pe][0m but ignoring the [pe-table] This alternative to [47m[pe][0m temporarily clears the [pe-table] so that original [events] are displayed.") (pe-table (pointers) "See [extend-pe-table].") (peek-char$ (pointers) "See [io].") (perhaps (pages_written_especially_for_the_tours) "Perhaps The theorem prover's proof is printed in real time. At the time it prints ``Perhaps'' it does not know the proof will succeed.") (persistent-whs (pointers) "See [wormhole-status].") (pf (history) "Print the formula corresponding to the given name Examples: :pf (:definition fn) ; prints the definition of fn as an equality :pf fn ; same as above :pf (:rewrite foo) ; prints the statement of the rewrite rule foo :pf foo ; same as above :pf (:induction foo) ; prints the induction scheme associated with foo [47mpf[0m takes one argument, an event name or a [rune], and prints the formula associated with name. If the argument is the name of a macro associated with a function name by [macro-aliases-table], then the function name is used as the argument. If the argument names an [47m:[0m[47m[induction][0m rule, then the corresponding induction scheme is printed.") (pkg-imports (packages) "List of symbols imported into a given package Completion Axiom ([47mcompletion-of-pkg-imports[0m): (equal (pkg-imports x) (if (stringp x) (pkg-imports x) nil)) [Guard] for [47m(pkg-imports x)[0m: (stringp x) [47m(Pkg-imports pkg)[0m returns a duplicate-free list of all symbols imported into [47mpkg[0m, which should be the name of a package known to ACL2. For example, suppose [47m"MY-PKG"[0m was created by (defpkg "MY-PKG" '(ACL2::ABC COMMON-LISP::CAR)). Then [47m(pkg-imports "MY-PKG")[0m equals the list [47m(ACL2::ABC COMMON-LISP::CAR)[0m. Note that [47mCOMMON-LISP::CAR[0m is the same as [47mACL2::CAR[0m, which is printed as just [47mCAR[0m. If [47mpkg[0m is not a string, then [47m(pkg-imports pkg)[0m is [47mnil[0m. If [47mpkg[0m is a string but not the name of a package known to ACL2, then the value of the form [47m(pkg-imports pkg)[0m is unspecified, and its evaluation will fail to yield a value. By ``the symbols imported into [47mpkg[0m'' we mean the symbols imported into [47mpkg[0m by the [47m[defpkg][0m event that introduced [47mpkg[0m. There are no imports for built-in packages except for the [47m"ACL2"[0m package, which imports the symbols in the list value of the constant [47m*common-lisp-symbols-from-main-lisp-package*[0m. In particular, this is the case for the [47m"COMMON-LISP"[0m package. Users familiar with Common Lisp may find this surprising, since in actual Common Lisp implementations it is often the case that many symbols in that package are imported from other packages. However, ACL2 treats all symbols in the constant [47m*common-lisp-symbols-from-main-lisp-package*[0m as having a [47m[symbol-package-name][0m of [47m"COMMON-LISP"[0m, as though they were not imported. ACL2 admits a symbol imported into in the [47m"COMMON-LISP"[0m package only if it belongs to that list: any attempt to read any other symbol imported into the [47m"COMMON-LISP"[0m package, or to produce such a symbol with [47m[intern$][0m or [47m[intern-in-package-of-symbol][0m, will cause an error. The following axioms formalize properties of [47mpkg-imports[0m discussed above (use [47m:[0m[47m[pe][0m to view them). symbol-package-name-intern-in-package-of-symbol intern-in-package-of-symbol-is-identity symbol-listp-pkg-imports no-duplicatesp-pkg-imports completion-of-pkg-imports") (pkg-witness (packages acl2-built-ins) "Return a specific symbol in the indicated package For any string [47mpkg[0m that names a package currently known to ACL2, [47m(pkg-witness pkg)[0m is a symbol in that package whose [47m[symbol-name][0m is the value of constant [47m*pkg-witness-name*[0m. Logically, this is the case even if the package is not currently known to ACL2. However, if [47mpkg-witness[0m is called on a string that is not the name of a package known to ACL2, a hard Lisp error will result. [47m(Pkg-witness pkg)[0m has a guard of [47m(and (stringp pkg) (not (equal pkg "")))[0m. If [47mpkg[0m is not a string, then [47m(pkg-witness pkg)[0m is equal to [47m(pkg-witness "ACL2")[0m") (pl (history) "Print the rules for the given name or term Examples: :pl foo ; prints rules that rewrite some call of foo :pl quote ; prints rules that rewrite quoted constants :pl (+ x y) ; prints rules that rewrite (+ x y) :pl '(4 1 2 3) ; prints rules that rewrite '(4 1 2 3) Also see [pl2], which restricts output to rules that you specify for a given term. [47mPl[0m takes one argument, which should be a symbol or a term. First suppose that the argument is a symbol. Then it should be the symbol [47mquote[0m, a function symbol, or else a macro alias for a function symbol (see [macro-aliases-table]), which is treated as the corresponding function symbol. When the argument to [47mpl[0m is [47mquote[0m, [47mpl[0m displays the rules that rewrite quoted constants, i.e., the [47m:[0m[47m[rewrite-quoted-constant][0m rules. Otherwise, [47m:pl[0m displays rules that apply to terms whose top function symbol is the one specified, specifically, rules of class [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[meta][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[forward-chaining][0m, [47m:[0m[47m[elim][0m, and [47m:[0m[47m[induction][0m. For each class, rules are displayed in order from the most recently submitted rule to the oldest, with two exceptions: [47m:rewrite[0m, [47m:definition[0m, and [47m:meta[0m rules are considered as one ``class'' for this purpose; and only the current (most recent) [47m:elim[0m rule is displayed. Otherwise the argument should be a term. Note that the term may have user-level syntax (that is, it may be an untranslated term; see [term]), for example one that is obtained from the theorem prover's output; in particular, macro calls are permitted. When supplied a term, [47m:pl[0m displays rules that are (possibly) applicable to the given term, in order (as above, most recent rule first) for each of these four cases: first [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[definition][0m rules, then [47m:meta[0m rules, then [47m:[0m[47m[linear][0m rules, and finally [47m:[0m[47m[type-prescription][0m rules. Each rule is displayed with additional information, such as the hypotheses that remain after applying some simple techniques to discharge them that are likely to apply in any context. (Those techniques include [type-reasoning], [forward-chaining], and some attempts to deal with [free-variables] including handling of binding hypotheses, [47m[syntaxp][0m and [47m[bind-free][0m.) It is important to remember that rules displayed as ``applicable'' by [47mpl[0m may in fact not be used because of logical requirements, like failure to relieve the hypotheses in the context in which the target occurs, or because of heuristics such as those controlled by the [47m:[0m[47m[loop-stopper][0m. A reminder of this can sometimes be seen in the output of [47mpl[0m. For example, if the list of un-discharged hypotheses contains [47mnil[0m then the hypotheses of this instance the rule are known, by trivial means, to be unsatisfiable. Similarly, [47m:[0m[47m[rewrite-quoted-constant][0m rules of form [47m[2][0m are not actually applied unless a certain computation produces a quoted constant. For example, ACL2 !>(include-book "demos/rewrite-quoted-constant-examples" :dir :system) includes a form [47m[2][0m rule, named [47mform-2-rule[0m, which will rewrite any quoted constant occurring a position admitting [47mset-equalp[0m as a congruence. The rule will apply the function [47mdrop-dups-and-sort[0m to the constant and replace the constant by the result --- if the result is a quoted constant. That function coerces the constant to a [47m[true-listp][0m, drops duplicate elements, and sorts the list. Thus, [47m'(3 1 1 2 . 77)[0m in a [47mset-equalp[0m occurrence would be rewritten to [47m'(1 2 3)[0m. However, that replacement is only made if [47m(drop-dups-and-sort '(3 1 1 2 . 77))[0m is rewritten to a quoted constant. ACL2 !>:pl '(3 1 1 2 . 77) will include an entry for [47mform-2-rule[0m, but the entry reads: New term: (DROP-DUPS-AND-SORT '(3 1 1 2 . 77)) Hypotheses: <none> Equiv: SET-EQUALP Substitution: ((LST '(3 1 1 2 . 77))) WARNING: The new term above is only used if it rewrites to a quoted constant! How might the replacement not be made? One way is if [47mdrop-dups-and-sort[0m and its [47m[executable-counterpart][0m are both disabled and there are no [47m:rewrite[0m rules about that function. Note that for [47m:[0m[47m[meta][0m rules, only those are displayed that meet two conditions: the application of the metafunction returns a term different from the input term, and if there is a hypothesis metafunction then it also returns a term. (A subtlety: In the case of extended metafunctions (see [extended-metafunctions]), a trivial metafunction context is used for the application of the metafunction.) Note that some rule classes are not handled by [47m:pl[0m. In particular, if you want to see all [47m:[0m[47m[clause-processor][0m rules, issue the command [47m:print-clause-processor-rules[0m, and for trusted clause-processors, [47m(table trusted-cl-proc-table)[0m; see [clause-processor] and see [define-trusted-clause-processor].") (pl2 (history) "Print rule(s) for the given form Examples: :pl2 (+ x y) nil ; prints rules that apply to (+ x y) :pl2 (+ x y) foo ; prints rules named foo that apply to (+ x y) :pl2 (+ x y) (:rewrite foo) ; if the rule with rune (:rewrite foo) applies ; to (+ x y), then print it :pl2 (+ x y) (:type-prescription foo) ; as above, but for the indicated ; type-prescription rule [47mPl2[0m takes two arguments. The first is a term. The second is either [47mnil[0m or a ``rule-id'' that is either a symbol or a [rune]. The result is to print rules of class [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, [47m:meta[0m, [47m:[0m[47m[linear][0m, and [47m:[0m[47m[type-prescription][0m that apply to the given term. Indeed, [47m:pl2[0m prints exactly what is printed by applying [47m:[0m[47m[pl][0m to the first argument --- see [pl] --- except that if the second argument is not [47mnil[0m then it is used to filter the rules printed, as follows. If the rule-id is a symbol, then only rules whose name is that symbol will be printed. If the rule-id is a [rune], then at most one rule will be printed: the rule named by that rune (if the rule would be printed by [47m:[0m[47m[pl][0m).") (plet (parallel-programming acl2-built-ins) "Parallel version of [47m[let][0m This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism], and see [parallel-programming], which has a disclaimer. Example Forms: (plet ((a (fibonacci (- x 1))) (b (fibonacci (- x 2)))) (+ a b)) (plet (declare (granularity (> x 35))) ((a (fibonacci (- x 1))) (b (fibonacci (- x 2)))) (+ a b)) General Form: (plet (declare (granularity expr)) ; optional granularity declaration ((var1 val1) ... (varN valN)) (declare ...) ... (declare ...) ; optional declarations body) The syntax of [47mplet[0m is identical to the syntax of [47m[let][0m, except that [47mplet[0m permits an optional granularity declaration in the first argument position; see [granularity]. In the logic a call of [47mplet[0m macroexpands to the corresponding call of [47m[let][0m, where the granularity declaration (if any) is dropped. [47mPlet[0m cause the evaluation of each [47mvali[0m above to be done in parallel before processing the body. If the above [47m[granularity][0m declaration is present, then its expression ([47mexpr[0m above) is first evaluated, and if the result is [47mnil[0m, then such parallelism is avoided. Even if parallelism is not thus avoided, parallelism may be limited by available resources. See [parallelism-at-the-top-level] for restrictions on evaluating parallelism primitives from within the ACL2 top-level loop.") (plist-worldp (pointers) "See [system-utilities].") (plusp (numbers acl2-built-ins) "Test whether a number is positive [47m(Plusp x)[0m is true if and only if [47mx > 0[0m. The [guard] of [47mplusp[0m requires its argument to be a rational ([real], in ACL2(r)) number. [47mPlusp[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<plusp> (defun plusp (x) (declare (xargs :guard (real/rationalp x))) (> x 0))") (pointers (documentation) "Links pointing to relevant documentation topics Subtopics [&allow-other-keys] See [macro-args]. [&body] See [macro-args]. [&key] See [macro-args]. [&optional] See [macro-args]. [&rest] See [macro-args]. [&whole] See [macro-args]. [*df-pi*] See [df]. [Abstract-stobj] See [defabsstobj]. [Accumulated-persistence-oops] See [accumulated-persistence]. [ACL2-unwind-protect] See [system-utilities]. [ACL2p] See [parallelism]. [ACL2r] See [real]. [ACL2s] See [ACL2-sedan]. [Add-ld-keyword-alias] See [ld-keyword-aliases]. [Add-ld-keyword-alias!] See [ld-keyword-aliases]. [Add-suffix] See [system-utilities]. [Add-suffix-to-fn] See [system-utilities]. [Add-to-set-eq] See [add-to-set]. [Add-to-set-eql] See [add-to-set]. [Add-to-set-equal] See [add-to-set]. [Adjust-ld-history] See [ld-history]. [All-attachments] See [system-utilities]. [All-calls] See [system-utilities]. [All-fnnames] See [system-utilities]. [All-fnnames-lst] See [system-utilities]. [All-fnnames1] See [system-utilities]. [All-vars] See [system-utilities]. [Always$] See [loop$]. [Always$+] See [loop$]. [Append$] See [loop$]. [Append$+] See [loop$]. [Apropos] See [finding-documentation]. [Arglistp] See [system-utilities]. [Array] See [arrays]. [Assertions] See [errors]. [Assoc-eq] See [assoc]. [Assoc-equal] See [assoc]. [Auto-instance] See [defthm<w]. [Backchain-limit-rw] See [hints] for information about the keyword [47m:backchain-limit-rw[0m. [Backtrack] See [hints] for information about the keyword [47m:backtrack[0m. [Bibliography] See publications. [Binary-df*] See [df]. [Binary-df+] See [df]. [Binary-df-log] See [df]. [Binary-df/] See [df]. [Body] See [system-utilities]. [Book-makefiles] See [books-certification]. [By] See [hints] for information about the keyword [47m:by[0m. [Cases] See [hints] for information about the keyword [47m:cases[0m. [Ccl-updates] See [ccl-installation]. [Certifiable] See [certify-book]. [Certify-book-failure] See [certify-book-debug]. [Certifying-books] See [books-certification]. [Check-invariant-risk] See [set-check-invariant-risk]. [Check-sum] See [checksum]. [Close-input-channel] See [io]. [Close-output-channel] See [io]. [Coherence] See [wormhole-status]. [Collect$] See [loop$]. [Collect$+] See [loop$]. [Comma] See [backquote]. [Comma-atsign] See [backquote]. [Community-book] See [community-books]. [Computed-hint] See [computed-hints]. [Conjoin] See [system-utilities]. [Conjoin2] See [system-utilities]. [Cons-term] See [system-utilities]. [Cons-term*] See [system-utilities]. [Context] See [ctx]. [Cw-gstack-for-subterm] See [with-brr-data]. [Cw-gstack-for-subterm*] See [with-brr-data]. [Cw-gstack-for-term] See [with-brr-data]. [Cw-gstack-for-term*] See [with-brr-data]. [D<] See [l<]. [Declaration] See [declare]. [Default-state-vars] See [system-utilities]. [Default-verify-guards-eagerness] See [set-verify-guards-eagerness]. [Defined-constant] See [system-utilities]. [Df*] See [df]. [Df+] See [df]. [Df-] See [df]. [Df-abs] See [df]. [Df-abs-fn] See [df]. [Df-acos] See [df]. [Df-acos-fn] See [df]. [Df-acosh] See [df]. [Df-acosh-fn] See [df]. [Df-asin] See [df]. [Df-asin-fn] See [df]. [Df-asinh] See [df]. [Df-asinh-fn] See [df]. [Df-atan] See [df]. [Df-atan-fn] See [df]. [Df-atanh] See [df]. [Df-atanh-fn] See [df]. [Df-cos] See [df]. [Df-cos-fn] See [df]. [Df-cosh] See [df]. [Df-cosh-fn] See [df]. [Df-exp] See [df]. [Df-exp-fn] See [df]. [Df-expt] See [df]. [Df-expt-fn] See [df]. [Df-log] See [df]. [Df-minus-1] See [df]. [Df-pi] See [df]. [Df-rationalize] See [df]. [Df-round] See [df]. [Df-sin] See [df]. [Df-sin-fn] See [df]. [Df-sinh] See [df]. [Df-sinh-fn] See [df]. [Df-sqrt] See [df]. [Df-sqrt-fn] See [df]. [Df-string] See [df]. [Df-tan] See [df]. [Df-tan-fn] See [df]. [Df-tanh] See [df]. [Df-tanh-fn] See [df]. [Df/] See [df]. [Df/=-fn] See [df]. [Df0] See [df]. [Df1] See [df]. [Df<] See [df]. [Df<-fn] See [df]. [Df<=] See [df]. [Df=] See [df]. [Df=-fn] See [df]. [Df>] See [df]. [Df>=] See [df]. [Dfp] See [df]. [Disjoin] See [system-utilities]. [Disjoin2] See [system-utilities]. [Do-not-induct] See [hints] for information about the keyword [47m:do-not-induct[0m. [Double-float] See [df]. [Doublet-listp] See [system-utilities]. [Dumb-negate-lit] See [system-utilities]. [Dumb-occur] See [system-utilities]. [Dumb-occur-var] See [system-utilities]. [Dynamically-monitor-rewrites] See [dmr]. [Enabled-numep] See [system-utilities]. [Enabled-runep] See [system-utilities]. [Ephemeral-whs] See [wormhole-status]. [Er-cmp] See [context-message-pair]. [Er-let*] See [programming-with-state]. [Er-let*-cmp] See [context-message-pair]. [Er-progn-cmp] See [context-message-pair]. [Error] See [hints] for information about the keyword [47m:error[0m. [Ev$-list] See [apply$]. [Event] See [events]. [Event-data] See [saving-event-data]. [Execution] See [evaluation]. [Expand] See [hints] for information about the keyword [47m:expand[0m. [Extended-syntaxp] See [syntaxp]. [External-format] See [character-encoding]. [Fake-rune] See [rune]. [Fargn] See [system-utilities]. [Fargs] See [system-utilities]. [Fast-alist] See [fast-alists]. [Fast-alist-discipline] See [slow-alist-warning]. [Fcons-term] See [system-utilities]. [Fcons-term*] See [system-utilities]. [Fdefun-mode] See [system-utilities]. [Ffn-symb] See [system-utilities]. [Ffn-symb-p] See [system-utilities]. [Ffnnamep] See [system-utilities]. [Ffnnamep-lst] See [system-utilities]. [First-keyword] See [system-utilities]. [First-n-ac] See [take]. [Fix-pkg] See [system-utilities]. [Flambda-applicationp] See [system-utilities]. [Flambdap] See [system-utilities]. [Flatten-ands-in-lit] See [system-utilities]. [Floating-point] See [df]. [Fms!-to-string] See [printing-to-strings]. [Fms-to-string] See [printing-to-strings]. [Fmt!-to-string] See [printing-to-strings]. [Fmt-hard-right-margin] See [set-fmt-hard-right-margin]. [Fmt-soft-right-margin] See [set-fmt-hard-right-margin]. [Fmt-to-string] See [printing-to-strings]. [Fmt1!-to-string] See [printing-to-strings]. [Fmt1-to-string] See [printing-to-strings]. [Fmx!-cw] See [fmx-cw]. [Fn-rune-nume] See [system-utilities]. [Fn-symb] See [system-utilities]. [Fncall-term] See [meta-extract]. [Forced] See [force]. [Formals] See [system-utilities]. [Fquotep] See [system-utilities]. [From-df] See [df]. [Fsubcor-var] See [system-utilities]. [Function-symbolp] See [system-utilities]. [Gcs] See [get-command-sequence]. [Genvar] See [system-utilities]. [Get-brr-local] See [system-utilities]. [Get-check-invariant-risk] See [set-check-invariant-risk]. [Get-defun-event] See [system-utilities]. [Get-event] See [system-utilities]. [Get-in-theory-redundant-okp] See [set-in-theory-redundant-okp]. [Get-output-stream-string$] See [io]. [Get-register-invariant-risk] See [set-register-invariant-risk]. [Get-serialize-character] See [with-serialize-character]. [Get-skipped-proofs-p] See [system-utilities]. [Getting-started] See [ACL2-tutorial]. [Guard-checking] See [set-guard-checking]. [Guard-hints] See [xargs] for information about the keyword [47m:guard-hints[0m. [Guard-holder] See [guard-holders]. [Guard-msg-table] See [set-guard-msg]. [Guards] See [guard]. [Hands-off] See [hints] for information about the keyword [47m:hands-off[0m. [Hash-tables] See [defstobj]. [If-intro] See [splitter]. [Ignorable] See [declare]. [Ignore] See [declare]. [Ilks] See [ilk]. [Immed-forced] See [splitter]. [Implicate] See [system-utilities]. [Induct] See [hints] for information about the keyword [47m:induct[0m. [Inline] See [defun-inline]. [Interrupts] See [abort-soft]. [Intersection-eq] See [intersection$]. [Intersection-equal] See [intersection$]. [Intersectp-eq] See [intersectp]. [Intersectp-equal] See [intersectp]. [Io?] See [system-utilities]. [Iprint] See [set-iprint]. [Iprinting] See [set-iprint]. [Keyword] See [keywordp]. [Known-package-alist] See [system-utilities]. [Lambda-applicationp] See [system-utilities]. [Lambda-body] See [system-utilities]. [Lambda-formals] See [system-utilities]. [Ld-history-entry-error-flg] See [ld-history]. [Ld-history-entry-input] See [ld-history]. [Ld-history-entry-stobjs-out] See [ld-history]. [Ld-history-entry-stobjs-out/value] See [ld-history]. [Ld-history-entry-user-data] See [ld-history]. [Ld-history-entry-value] See [ld-history]. [Ld-user-stobjs-modified-warning] See [user-stobjs-modified-warnings]. [Legal-constantp] See [system-utilities]. [Legal-variablep] See [system-utilities]. [Let-mbe] See [equality-variants-details]. [Lex-fix] See [l<]. [Lexp] See [l<]. [Lisp-programmer-introduction] See [introduction-to-programming-in-ACL2-for-those-who-know-lisp]. [Logicp] See [system-utilities]. [Loop$-do] See [do-loop$]. [Loop$-for] See [for-loop$]. [Make-lambda] See [system-utilities]. [Make-lambda-application] See [system-utilities]. [Make-lambda-term] See [system-utilities]. [Make-list-ac] See [make-list]. [Match-free] See [free-variables]. [Maybe-convert-to-mv] See [system-utilities]. [Measure-theorem] See [termination-theorem]. [Member-eq] See [member]. [Member-equal] See [member]. [Memoization] See [memoize]. [Meta-extract-contextual-fact] See [meta-extract]. [Meta-extract-formula] See [meta-extract]. [Meta-extract-global-fact] See [meta-extract]. [Meta-extract-global-fact+] See [meta-extract]. [Meta-extract-rw+-term] See [meta-extract]. [Mfc] See [metafunction-context]. [Mfc-ancestors] See [extended-metafunctions]. [Mfc-ap] See [extended-metafunctions]. [Mfc-clause] See [extended-metafunctions]. [Mfc-rdepth] See [extended-metafunctions]. [Mfc-relieve-hyp] See [extended-metafunctions]. [Mfc-rw] See [extended-metafunctions]. [Mfc-rw+] See [extended-metafunctions]. [Mfc-ts] See [extended-metafunctions]. [Mfc-type-alist] See [extended-metafunctions]. [Mfc-unify-subst] See [extended-metafunctions]. [Mfc-world] See [extended-metafunctions]. [Mode] See [xargs] for information about the keyword [47m:mode[0m. [Multiple-value] See [mv-let]. [Nfix-list] See [l<]. [No-duplicatesp-eq] See [no-duplicatesp]. [No-duplicatesp-equal] See [no-duplicatesp]. [No-op] See [hints] for information about the keyword [47m:no-op[0m. [No-thanks] See [hints] for information about the keyword [47m:no-thanks[0m. [Non-executable] See [xargs] for information about the keyword [47m:non-executable[0m. [Nonlinearp] See [hints] for information about the keyword [47m:nonlinearp[0m. [Normalization] See [normalize]. [Note1] See [note-1-1]. [Note2] See [note-1-2]. [Note3] See [note-1-3]. [Note4] See [note-1-4]. [Note5] See [note-1-5]. [Note6] See [note-1-6]. [Note7] See [note-1-7]. [Note8] See [note-1-8]. [Note8-update] See [note-1-8-update]. [Note9] See [note-1-9]. [Nvariablep] See [system-utilities]. [Observation-cw] See [observation]. [Old-and-new-event-data] See [saving-event-data]. [Open-input-channel] See [io]. [Open-input-channel-p] See [io]. [Open-output-channel] See [io]. [Open-output-channel-p] See [io]. [Optimize] See [declare]. [Other-releases] See [releases]. [Package] See [packages]. [Partition-rest-and-keyword-args] See [system-utilities]. [Pe-table] See [extend-pe-table]. [Peek-char$] See [io]. [Persistent-whs] See [wormhole-status]. [Plist-worldp] See [system-utilities]. [Position-eq] See [position]. [Position-equal] See [position]. [Pound-bang-reader] See [sharp-bang-reader]. [Pound-dot-reader] See [sharp-dot-reader]. [Pound-u-reader] See [sharp-u-reader]. [Prettyify-clause] See [system-utilities]. [Print-object$-preserving-case] See [io]. [Print-summary-user] See [finalize-event-user]. [Programp] See [system-utilities]. [Proof-supporters-alist] See [dead-events]. [Put-assoc-eq] See [put-assoc]. [Put-assoc-eql] See [put-assoc]. [Put-assoc-equal] See [put-assoc]. [Quotep] See [system-utilities]. [Rassoc-eq] See [rassoc]. [Rassoc-equal] See [rassoc]. [Raw-mode] See [set-raw-mode]. [Read-byte$] See [io]. [Read-char$] See [io]. [Read-object] See [io]. [Read-object-suppress] See [io]. [Read-object-with-case] See [io]. [Recursivep] See [system-utilities]. [Redefine] See [ld-redefinition-action]. [Redefining] See [ld-redefinition-action]. [Redundant] See [redundant-events]. [Regression] See [books-certification]. [Remove-assoc-eq] See [remove-assoc]. [Remove-assoc-equal] See [remove-assoc]. [Remove-duplicates-eq] See [remove-duplicates]. [Remove-duplicates-equal] See [remove-duplicates]. [Remove-eq] See [remove]. [Remove-equal] See [remove]. [Remove-guard-holders] See [guard-holders]. [Remove1-assoc-eq] See [remove1-assoc]. [Remove1-assoc-equal] See [remove1-assoc]. [Remove1-eq] See [remove1]. [Remove1-equal] See [remove1]. [Reorder] See [hints] for information about the keyword [47m:reorder[0m. [Reset-print-control] See [print-control]. [Restrict] See [hints] for information about the keyword [47m:restrict[0m. [Rewrite-cache] See [set-rw-cache-state]. [Rize] See [df]. [Ruler] See [rulers]. [Ruler-extenders] See [rulers]. [Runes-diff] See [saving-event-data]. [Rw-cache] See [set-rw-cache-state]. [Saving-and-restoring] See [save-exec]. [Set-accumulated-persistence] See [accumulated-persistence]. [Set-difference-eq] See [set-difference$]. [Set-difference-equal] See [set-difference$]. [Set-fast-cert] See [fast-cert]. [Set-ld-always-skip-top-level-locals] See [ld-always-skip-top-level-locals]. [Set-ld-error-action] See [ld-error-action]. [Set-ld-error-triples] See [ld-error-triples]. [Set-ld-evisc-tuple] See [ld-evisc-tuple]. [Set-ld-keyword-aliases] See [ld-keyword-aliases]. [Set-ld-keyword-aliases!] See [ld-keyword-aliases]. [Set-ld-missing-input-ok] See [ld-missing-input-ok]. [Set-ld-post-eval-print] See [ld-post-eval-print]. [Set-ld-pre-eval-filter] See [ld-pre-eval-filter]. [Set-ld-pre-eval-print] See [ld-pre-eval-print]. [Set-ld-prompt] See [ld-prompt]. [Set-ld-query-control-alist] See [ld-query-control-alist]. [Set-ld-redefinition-action] See [ld-redefinition-action]. [Set-ld-skip-proofs] See [ld-skip-proofsp]. [Set-ld-skip-proofsp] See [ld-skip-proofsp]. [Set-ld-user-stobjs-modified-warning] See [user-stobjs-modified-warnings]. [Set-ld-verbose] See [ld-verbose]. [Set-let*-abstraction] See [set-let*-abstractionp]. [Set-non-linear] See [set-non-linearp]. [Set-print-circle] See [print-control]. [Set-print-escape] See [print-control]. [Set-print-length] See [print-control]. [Set-print-level] See [print-control]. [Set-print-lines] See [print-control]. [Set-print-readably] See [print-control]. [Set-print-right-margin] See [print-control]. [Set-proofs-co] See [proofs-co]. [Set-ruler-extenders] See [rulers]. [Set-serialize-character] See [with-serialize-character]. [Set-slow-alist-action] See [slow-alist-warning]. [Set-standard-co] See [standard-co]. [Set-standard-oi] See [standard-oi]. [Set-temp-touchable-fns] See [remove-untouchable]. [Set-temp-touchable-vars] See [remove-untouchable]. [Set-trace-co] See [trace-co]. [Show-accumulated-persistence] See [accumulated-persistence]. [Single-threaded-objects] See [stobj]. [Split-types] See [xargs] for information about the keyword [47m:split-types[0m. [Stable-under-simplificationp] See [computed-hints]. [Step-limit] See [with-prover-step-limit]. [Stobj-let] See [nested-stobjs]. [Stobjp] See [system-utilities]. [Stobjs] See [xargs] for information about the keyword [47m:stobjs[0m. [Stobjs-in] See [system-utilities]. [Stobjs-out] See [system-utilities]. [Subcor-var] See [system-utilities]. [Sublis-fn] See [system-utilities]. [Sublis-fn-lst-simple] See [system-utilities]. [Sublis-fn-simple] See [system-utilities]. [Sublis-var] See [system-utilities]. [Subsequencep] See [system-utilities]. [Subsetp-eq] See [subsetp]. [Subsetp-equal] See [subsetp]. [Subst-expr] See [system-utilities]. [Subst-var] See [system-utilities]. [Suitably-tamep-listp] See [tame]. [Sum$] See [loop$]. [Sum$+] See [loop$]. [Symbol-class] See [system-utilities]. [Symbol-doublet-listp] See [system-utilities]. [Table-alist] See [table]. [Tag-tree] See [ttree]. [Tamep] See [tame]. [Tamep-functionp] See [tame]. [Tamep-lambdap] See [tame]. [Thereis$] See [loop$]. [Thereis$+] See [loop$]. [Time-limit] See [with-prover-time-limit]. [To-df] See [df]. [To-dfp] See [df]. [Too-many-ifs] See [efficiency]. [Top-level-loop] See [guarantees-of-the-top-level-loop]. [Trans-eval-default-warning] See [user-stobjs-modified-warnings]. [Trans-eval-no-warning] See [user-stobjs-modified-warnings]. [Translate] See [system-utilities]. [Translate-cmp] See [system-utilities]. [Translate-hints] See [system-utilities]. [Translate1] See [system-utilities]. [Translate1-cmp] See [system-utilities]. [Translate11] See [system-utilities]. [Trust-tag] See [defttag]. [Ttag] See [defttag]. [Type] Disambiguation page for [3mtype[0m-related concepts. [Typespec-check] See [meta-extract]. [The_Tours] See [tours]. [Unary-df-] See [df]. [Unary-df-log] See [df]. [Unary-df/] See [df]. [Undoing] See [undo]. [Union-eq] See [union$]. [Union-equal] See [union$]. [Unknown-constraints] See [partial-encapsulate]. [Until$] See [loop$]. [Until$+] See [loop$]. [Untouchable-marker] See [defmacro-untouchable]. [Untranslate-preprocess] See [user-defined-functions-table]. [Use] See [hints] for information about the keyword [47m:use[0m. [Value] See [system-utilities]. [Value-cmp] See [context-message-pair]. [Variablep] See [system-utilities]. [Verify-guards-eagerness] See [set-verify-guards-eagerness]. [Waterfall] See [hints-and-the-waterfall]. [Weak-ld-history-entry-p] See [ld-history]. [When$] See [loop$]. [When$+] See [loop$]. [With-output!] See [with-output]. [With-prover-step-limit!] See [with-prover-step-limit]. [Wormhole-coherence] See [wormhole-status]. [Write-byte$] See [io].") (popping_out_of_an_inductive_proof (pages_written_especially_for_the_tours) "Popping out of an Inductive Proof Recall that our induction scheme (click here (see [The_Proof_of_the_Associativity_of_App]) to revisit it) had two cases, the induction step ([47mSubgoal *1/2[0m) and the base case ([47mSubgoal *1/1[0m). Both have been proved!") (por (parallel-programming acl2-built-ins) "Parallel, Boolean version of [47m[or][0m This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism], and see [parallel-programming], which has a disclaimer. Example Forms: (por (subsetp-equal x y) (subsetp-equal y x)) (por (declare (granularity (and (> (length x) 500) (> (length y) 500)))) (subsetp-equal x y) (subsetp-equal y x)) General Form: (por (declare (granularity expr)) ; optional granularity declaration arg1 ... argN) where [47mN >= 0[0m and each [47margi[0m and [47mexpr[0m are arbitrary terms. [47mPor[0m evaluates its arguments in parallel. It returns a Boolean result: [47mt[0m if any argument evaluates to non-[47mnil[0m, else [47mnil[0m. Note that while [47m[or][0m returns the first non-[47mnil[0m value from evaluating its arguments left-to-right (if any such value is not [47mnil[0m) [47m[por][0m always returns a Boolean result, in support of efficiency (see [early-termination]) in light of the nondeterministic order in which argument values are returned. Another difference between [47mpor[0m and [47m[or][0m is that for a call of [47mpor[0m, even if the an argument's value is not [47mnil[0m, a subsequent argument may be evaluated. See [pand] for a discussion of the analogous property of [47mpand[0m. In particular, [guard]s generated from calls of [47mpor[0m may not assume for an argument that the preceding arguments evaluated to [47mnil[0m. See [parallelism-tutorial] for another example. Also see [parallelism-at-the-top-level] for restrictions on evaluating parallelism primitives from within the ACL2 top-level loop. Finally see [early-termination] to read how [47mpor[0m can offer more efficiency than [47m[or][0m by avoiding evaluation of some of its arguments.") (portcullis (books-tour) "The gate guarding the entrance to a certified book The certificate (see [certificate] for general information) of a certified book contains a portcullis and a [keep]. These names come from castle lore. The portcullis of a castle is an iron grate that slides up through the ceiling of the tunnel-like entrance. The portcullis of a book ensures that [47m[include-book][0m does not start to read the book until the appropriate context has been created. Technically, the portcullis consists of the [version] number of the certifying ACL2, a list of [command]s used to create the ``certification [world]'' and an alist specifying [book-hash] values for all the [books] included in that [world]. The portcullis is constructed automatically by [47m[certify-book][0m from the [world] in which [47m[certify-book][0m is called, but that [world] must have certain properties described below. After listing the properties we discuss the issues in a more leisurely manner. Each [command] in the portcullis must be either a [47m[defpkg][0m form or an embedded event form (see [embedded-event-form]). Consider a book to be certified. The book is a file containing event forms. Suppose the file contains references to such symbols as [47mmy-pkg::fn[0m and [47macl2-arith::cancel[0m, but that the book itself does not create the packages. Then a hard Lisp error would be caused merely by the attempt to read the expressions in the book. The corresponding [47m[defpkg][0ms cannot be written into the book itself because the book must be compilable and Common Lisp compilers differ on the rules concerning the inline definition of new packages. The only safe course is to make all [47m[defpkg][0ms occur outside of compiled files. More generally, when a book is certified it is certified within some logical [world]. That ``certification [world]'' contains not only the necessary [47m[defpkg][0ms but also, perhaps, function and constant definitions and maybe even references to other [books]. When [47m[certify-book][0m creates the [certificate] for a file it recovers from the certification [world] the [command]s used to create that [world] from the initial ACL2 [world]. Those [command]s contribute to the portcullis for the certified book. In addition, [47m[certify-book][0m records in the portcullis certain [3mbook-hash[0m values (see [book-hash]) for all the [books] included in the certification [world]. [47m[Include-book][0m presumes that it is impossible even to read the contents of a certified book unless the portcullis can be ``raised.'' To raise the portcullis we must be able to execute (possibly redundantly, but certainly without error), all of the [command]s in the portcullis and then verify that the [books] thus included were identical to those used to build the certification [world] (up to book-hash). This raising of the portcullis must be done delicately since [47m[defpkg][0ms are present: we cannot even read a [command] in the portcullis until we have successfully executed the previous ones, since packages are being defined. Note that when [47minclude-book[0m evaluates portcullis commands, it skips proofs and ignores [local] events. Clearly, a book is most useful if its certification takes place with as few non-[local] events as possible that extend the initial logical [world]. If, for example, your certification [world] happens to contain a [47m[defpkg][0m for [47m"MY-PKG"[0m and a non-local definition of a function [47mfoo[0m, then those definitions become part of the portcullis for the book. Every time the book is included, those names will be defined and will have to be either new or redundant (see [redundant-events]). But if those names were not necessary to the certification of the book, their presence would unnecessarily restrict the utility of the book. See [keep] to continue the guided tour of [books].") (pos-listp (numbers lists acl2-built-ins) "Recognizer for a true list of positive integers The predicate [47mpos-listp[0m tests whether its argument is a true list of positive integers. [31;1mFunction: [0m<pos-listp> (defun pos-listp (l) (declare (xargs :guard t)) (cond ((atom l) (eq l nil)) (t (and (posp (car l)) (pos-listp (cdr l))))))") (position (lists strings acl2-built-ins) "Position of an item in a string or a list General Forms: (position x seq) (position x seq :test 'eql) ; same as above (eql as equality test) (position x seq :test 'eq) ; same, but eq is equality test (position x seq :test 'equal) ; same, but equal is equality test [47m(Position x seq)[0m is the least index (zero-based) of the element [47mx[0m in the string or list [47mseq[0m, if [47mx[0m is an element of [47mseq[0m. Otherwise [47m(position x seq)[0m is [47mnil[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with items of [47mseq[0m. The [guard] for a call of [47mposition[0m depends on the test. In all cases, the second argument must satisfy [47m[stringp][0m or [47m[true-listp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mposition[0m and its variants: [47m(position-eq x seq)[0m is equivalent to [47m(position x seq :test 'eq)[0m; [47m(position-equal x seq)[0m is equivalent to [47m(position x seq :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mposition-equal[0m. [47mPosition[0m is defined by Common Lisp. See any Common Lisp documentation for more information. [31;1mMacro: [0m<position> (defmacro position (x seq &key (test ''eql)) (declare (xargs :guard (or (equal test ''eq) (equal test ''eql) (equal test ''equal)))) (cond ((equal test ''eq) (cons 'let-mbe (cons (cons (cons 'x (cons x 'nil)) (cons (cons 'seq (cons seq 'nil)) 'nil)) '(:logic (position-equal x seq) :exec (position-eq-exec x seq))))) ((equal test ''eql) (cons 'let-mbe (cons (cons (cons 'x (cons x 'nil)) (cons (cons 'seq (cons seq 'nil)) 'nil)) '(:logic (position-equal x seq) :exec (position-eql-exec x seq))))) (t (cons 'position-equal (cons x (cons seq 'nil)))))) [31;1mFunction: [0m<position-equal> (defun position-equal (x seq) (declare (xargs :guard (or (stringp seq) (true-listp seq)))) (if (stringp seq) (position-ac x (coerce seq 'list) 0) (position-equal-ac x seq 0))) [31;1mFunction: [0m<position-equal-ac> (defun position-equal-ac (item lst acc) (declare (xargs :guard (and (true-listp lst) (acl2-numberp acc)))) (cond ((endp lst) nil) ((equal item (car lst)) (mbe :exec acc :logic (fix acc))) (t (position-equal-ac item (cdr lst) (1+ acc))))) [31;1mMacro: [0m<position-ac> (defmacro position-ac (item lst acc &key (test ''eql)) (declare (xargs :guard (or (equal test ''eq) (equal test ''eql) (equal test ''equal)))) (cond ((equal test ''eq) (cons 'let-mbe (cons (cons (cons 'item (cons item 'nil)) (cons (cons 'lst (cons lst 'nil)) (cons (cons 'acc (cons acc 'nil)) 'nil))) '(:logic (position-equal-ac item lst acc) :exec (position-ac-eq-exec item lst acc))))) ((equal test ''eql) (cons 'let-mbe (cons (cons (cons 'item (cons item 'nil)) (cons (cons 'lst (cons lst 'nil)) (cons (cons 'acc (cons acc 'nil)) 'nil))) '(:logic (position-equal-ac item lst acc) :exec (position-ac-eql-exec item lst acc))))) (t (cons 'position-equal-ac (cons item (cons lst (cons acc 'nil)))))))") (position-eq (pointers) "See [position].") (position-equal (pointers) "See [position].") (posp (numbers acl2-built-ins) "A recognizer for the positive integers [47m(posp x)[0m is logically equivalent to [47m(not (zp x))[0m (see [zp]) and also to [47m(and (natp x) (not (equal x 0)))[0m. The community book [arithmetic/natp-posp] has some lightweight rules for reasoning about [47mposp[0m and [47mnatp[0m, and is included in the [arithmetic-1] library. For a somewhat heavier and more comprehensive alternative, you may wish to instead see the [arith-equivs] book. [31;1mFunction: [0m<posp> (defun posp (x) (declare (xargs :guard t)) (and (integerp x) (< 0 x)))") (post-induction-key-checkpoints (introduction-to-the-theorem-prover) "Reading post-induction key checkpoints Each post-induction key checkpoint is a theorem if and only if the original conjecture was a theorem. The reason is that each subgoal produced by induction concludes with the original formula and simplification preserves equivalence. So if you see a post-induction key checkpoint that is not a theorem, stop looking at the checkpoints! Your original conjecture is not a theorem! Fix it. If you're convinced all the post-induction conjectures are theorems, ask whether each has the hypotheses you'd need to prove it. If the case analysis feels inappropriate or induction hypotheses seem to be missing, then ACL2 might have done the wrong induction. Find the induction scheme it did by reading the first induction message printed after the conjecture was submitted. If it is wrong, then extend ACL2's induction analysis or tell ACL2 what induction to do, as explained shortly. But before you decide the induction hypothesis is missing, look closely for contradictions among the hypotheses of the checkpoint formula. For example, perhaps one of the hypotheses is [47m(MEMBER e x)[0m and another is [47m(NOT (MEMBER e' x'))[0m where [47me[0m, [47mx[0m, [47me'[0m, and [47mx'[0m are possibly complicated expressions. Is it possible that [47me[0m and [47me'[0m are equal and [47mx[0m and [47mx'[0m are equal? If so, then the two hypotheses are contradictory and the checkpoint would be proved if you could find rules that would simplify those expressions to their common forms. So look for theorems about those subexpressions. Or maybe you can get [47me[0m and [47me'[0m to reduce to some common [47md[0m but but find that [47mx[0m and [47mx'[0m are really different. Then ask whether (implies (member d x) (member d x')) If you could prove that, the key checkpoint would be proved. Of course, you may need other hypotheses from the checkpoint to state your theorems. If you have been working your way through the tutorial introduction to the theorem prover, use your browser's [31;1mBack Button[0m now to [introduction-to-key-checkpoints].") (pound-bang-reader (pointers) "See [sharp-bang-reader].") (pound-dot-reader (pointers) "See [sharp-dot-reader].") (pound-u-reader (pointers) "See [sharp-u-reader].") (ppr-special-syms (io) "A [table] to control indentation for pretty-printing ACL2 output is generally pretty-printed: that is, spacing and indentation are controlled to enhance readability and aesthetics of the output. Indentation may be controlled by using the table, [47mppr-special-syms[0m as described below. We thank Stephen Westfold for enhancing the pretty-printer with support for [47mppr-special-syms[0m. The initial value of the [47mppr-special-syms[0m table is given by the constant [47m*ppr-special-syms*[0m as follows. It associates each key, a symbol, with a corresponding [3mspecial-term-num[0m as discussed below. [31;1mDefinition: [0m<*ppr-special-syms*> (defconst *ppr-special-syms* '((case . 1) (case-match . 1) (defabsstobj . 1) (defaxiom . 1) (defchoose . 3) (defcong . 2) (defconst . 1) (defmacro . 2) (defstobj . 1) (defthm . 1) (defthmd . 1) (defun . 2) (defun-inline . 2) (defun-sk . 2) (defund . 2) (encapsulate . 1) (if . 2) (lambda . 1) (lambda$ . 1) (let . 1) (let* . 1) (mutual-recursion . 0) (mv-let . 2) (table . 1))) The [47mppr-special-syms[0m table is extended for some common macros in the files where they are defined, for example for [47m[define][0m and [47m[b*][0m. For calls of special forms and macros in the [47mppr-special-syms[0m table, their bodies are indented by 2 rather than in the usual default manner. To support this we allow a [3mspecial-term-num[0m to be associated with a symbol. Arguments of such symbols in the function position beyond the special-term-num position are indented by 2. Earlier arguments are printed normally. For example, the symbol, [47mlet[0m, has a special-term-num of 1, so the first argument is printed normally and subsequent arguments are indented by 2, as follows. (LET ((A B) (C D)) (F A C)) Since `if' has a special-term-num of 2, the first two arguments are printed normally and the other is indented by 2, for example as follows. (IF (P A B) (F A B) (G A B)) Macros often have as their first argument a symbol, so these are treated specially by putting them on the first line and any remaining arguments before the body arguments begin on the same line if there is space. For example, [47mdefun[0m has special-term-num 2, which is evident in the following output. (DEFUN FOO (X Y Z) (F X Y Z)) Keyword pairs in macro calls can occur in other places than at the end of an argument list, so keyword pairing is done more aggressively, as in the following output. (DEFINE FOO ((X P1) (Y P2)) :GUARD (P3 X Y) (F X Y Z))") (pprogn (programming-with-state acl2-built-ins) "Evaluate a sequence of forms that return [state] Example Form: (pprogn (cond ((or (equal (car l) #\) (equal (car l) slash-char)) (princ$ #\ channel state)) (t state)) (princ$ (car l) channel state) (mv (cdr l) state)) The convention for [47mpprogn[0m usage is to give it a non-empty sequence of forms, each of which (except possibly for the last) returns state (see [state]) as its only value. The [state] returned by each but the last is passed on to the next. The value or values of the last form are returned as the value of the [47mpprogn[0m. If you are using single-threaded objects you may wish to define an analogue of this function for your own [stobj]. General Form: (PPROGN form1 form2 ... formk result-form) This general form is equivalent, via macro expansion, to: (LET ((STATE form1)) (LET ((STATE form2)) ... (LET ((STATE formk)) result-form)))") (pr (history) "Print the rules stored by the event with the given name Examples: :pr fn ; prints the rules from the definition of fn (including any ; :type-prescription rule and :definition rule) :pr assoc-append ; if assoc-append is a rewrite rule, prints that rule Also see [pr!], which is similar but works at the command level instead of at the event level, and see [pl], which displays all rewrite rules for calls of [47mfn[0m, not just those introduced at definition time. [47mPr[0m takes one argument, a logical name, and prints the rules associated with it. In each case it prints the rune, the current enabled/disabled status, and other appropriate fields from the rule. It may be helpful to read the documentation for various kinds of rules in order to understand the information printed by this command. For example, the information printed for a linear rule might be: Rune: (:LINEAR ABC) Enabled: T Hyps: ((CONSP X)) Concl: (< (ACL2-COUNT (CAR X)) (ACL2-COUNT X)) Max-term: (ACL2-COUNT (CAR X)) Backchain-limit-lst: (3) The [47mhyps[0m and [47mconcl[0m fields for this rule are fairly self-explanatory, but it is useful to see [linear] to learn about maximal terms (which, as one might guess, are stored under ``Max-term''). Currently, this function does not print [congruence] rules, [equivalence] rules, or [refinement] rules. Moreover, [induction] rules that are created by recursive definitions will not show up with [47m:pr[0m. The expert user might also wish to use [47m[find-rules-of-rune][0m. See [find-rules-of-rune].") (pr! (history) "Print rules stored by the command with a given command descriptor Examples: :pr! fn ; prints the rules from the definition of fn (including any ; :type-prescription rule and :definition rule), as well as all other ; rules created by the command that created by fn (which could be ; many rules if, for example, fn was defined by an include-book ; command). :pr! :max ; prints all the rules stored by the most recent command Also see [pr], which is similar but works at the event level instead of at the command level. [47m[Pr][0m takes one argument, a command descriptor, and prints the rules created by the corresponding event. In each case it prints the rune, the current enabled/disabled status, and other appropriate fields from the rule. See [pr] for further details.") (practice-formulating-strong-rules (introduction-to-the-theorem-prover) "A few simple checkpoints suggesting strong rules Consider these definitions: (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) (defun nats-below (j) (if (zp j) '(0) (cons j (nats-below (- j 1))))) We assume you are familiar with such ACL2 built-ins as [47mappend[0m, [47mmember[0m, [47msubsetp[0m and [47mtrue-listp[0m. When we use throw-away names like [47mFOO[0m, [47mBAR[0m, and [47mMUM[0m below we mean to suggest some arbitrary function you shouldn't think about! We're just trying to train your eye to ignore irrelevant things. Below are some terms that should suggest rewrite rules to you. Imagine that each of these terms occurs in some Key Checkpoint. What rules come to mind? Try to think of the strongest rules you can. Term 1: [47m(TRUE-LISTP (APPEND (FOO A) (BAR B)))[0m Answers: See [practice-formulating-strong-rules-1] Term 2: [47m(TRUE-LISTP (REV (FOO A)))[0m Answers: See [practice-formulating-strong-rules-2] Term 3: [47m(MEMBER (FOO A) (APPEND (BAR B) (MUM C)))[0m Answers: See [practice-formulating-strong-rules-3] Term 4: [47m(SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))[0m Answers: See [practice-formulating-strong-rules-4] Term 5: [47m(SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))[0m Answers: See [practice-formulating-strong-rules-5] Term 6: [47m(MEMBER (FOO A) (NATS-BELOW (BAR B)))[0m Answers: See [practice-formulating-strong-rules-6] We recommend doing all of these little exercises. When you're finished, use your browser's [31;1mBack Button[0m to return to [strong-rewrite-rules].") (practice-formulating-strong-rules-1 (introduction-to-the-theorem-prover) "Rules suggested by [47m(TRUE-LISTP (APPEND (FOO A) (BAR B)))[0m What rules come to mind when looking at the following subterm of a Key Checkpoint? Think of [3mstrong[0m rules (see [strong-rewrite-rules]). (TRUE-LISTP (APPEND (FOO A) (BAR B))) Obviously, you must think about the conditions under which [47m(APPEND x y)[0m returns a true-list. Recall that [47mAPPEND[0m concatenates [47mx[0m and [47my[0m, with [47my[0m being the terminal sublist. Its definition is equivalent to (defun append (x y) (if (endp x) y (cons (car x) (append (cdr x) y)))) Technical Note: [47mAppend[0m is really a macro that permits you to write calls of [47mappend[0m with more than two arguments. In a sense, [47mappend[0m ``expects'' its arguments to be lists ending in [47mnil[0m, so-called [47mtrue-listp[0ms. (Such expectations are formalized in ACL2 by the notion of the ``[guard]'' {ICON} (see [A_Tiny_Warning_Sign]) of the function, but we strongly recommend not investigating guards until you're good at using the system.) New users frequently start every new theorem by listing all their expectations on the arguments of functions in the problem. For example, if the new user wants to make some statement about when [47m(append x y)[0m is a [47mtrue-listp[0m, it is not uncommon for him or her first to write: (implies (and (true-listp x) (true-listp y)) ...) to get ``comfortable.'' Then, thinking about when [47m(append x y)[0m is a [47mtrue-listp[0m is easy: it always returns a [47mtrue-listp[0m. It's always a [47mtrue-listp[0m.'' This thinking produces the theorem: (defthm true-listp-append-really-weak (implies (and (true-listp x) (true-listp y)) (true-listp (append x y)))) You'll note we gave it a name suggesting it is ``really weak.'' One sense in which it is weak is that it has an unnecessary hypothesis. If [47my[0m is a [47mtrue-listp[0m, then [47m(append x y)[0m is too, whether [47mx[0m is a [47mtrue-listp[0m or not. In ACL2, all functions are total. Logically speaking, it doesn't matter whether [47mendp[0m expects its argument to be a [47mtrue-listp[0m or not, it behaves. [47m(Append x y)[0m either returns [47my[0m or a [47mcons[0m whose second argument is generated by [47mappend[0m. Thus, if [47my[0m is a [47mtrue-listp[0m, the answer is too. So here is an improved version of the rule: (defthm true-listp-append-weak (implies (true-listp y) (true-listp (append x y)))) We still think of it as ``weak'' because it has a hypothesis that limits its applicability. The strong version of the rule is (defthm true-listp-append-strong (equal (true-listp (append x y)) (true-listp y))). That is, [47mappend[0m returns a [47mtrue-listp[0m [3mprecisely[0m when its second argument is a [47mtrue-listp[0m. We recommend that the strong version be made a [47m:[0m[47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule. The weak version of the rule allows us to reduce [47m(TRUE-LISTP (APPEND x y))[0m to true if we can show that [47m(TRUE-LISTP y)[0m is true. But suppose [47m(TRUE-LISTP y)[0m is actually false. Then [47m(TRUE-LISTP (APPEND x y))[0m would not simplify under the weak version of the rule. But under the strong version it would simplify to [47mNIL[0m. Technical Note: The weak version of the rule is a useful [47m:[0m[47m[type-prescription][0m {ICON} (see [A_Tiny_Warning_Sign]) rule. The type mechanism cannot currently exploit the strong version of the rule. The strategy of ``getting comfortable'' by adding a bunch of hypotheses before you know you need them is not conducive to creating strong rules. We tend to state the main relationship that we intuit about some function and then add the hypotheses we need to make it true. In this case, there were no necessary hypotheses. But if there are, we first identify them and then we ask ``what can I say about the function if these hypotheses aren't true?'' and try to strengthen the statement still further. Use your browser's [31;1mBack Button[0m now to return to [practice-formulating-strong-rules].") (practice-formulating-strong-rules-2 (introduction-to-the-theorem-prover) "Rules suggested by [47m(TRUE-LISTP (REV (FOO A)))[0m What rules come to mind when looking at the following subterm of a Key Checkpoint? Think of [3mstrong[0m rules (see [strong-rewrite-rules]). (TRUE-LISTP (REV (FOO A))) The definition of [47mrev[0m in this problem is (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) Since the definition terminates with an [47mendp[0m test and otherwise [47mcdr[0ms the argument, the author of [47mrev[0m was clearly expecting [47mx[0m to be a [47mtrue-listp[0m. (Indeed, the ``[guard]'' {ICON} (see [A_Tiny_Warning_Sign]) for [47mrev[0m must include [47m(true-listp x)[0m since that is [47mendp[0m's guard.) So you're naturally justified in limiting your thoughts about [47m(rev x)[0m to [47mx[0m that are true-lists. This gives rise to the theorem: (defthm true-listp-rev-weak (implies (true-listp x) (true-listp (rev x)))) This is the kind of thinking illustrated in the earlier [47mappend[0m example (see [practice-formulating-strong-rules-1]), and, to paraphrase Z in [3mMen in Black[0m, it exemplifies ``everything we've come to expect from years of training with typed languages.'' But logically speaking, the definition of [47mrev[0m does not require [47mx[0m to be a [47mtrue-listp[0m. It can be any object at all: ACL2 functions are total. [47mRev[0m either returns [47mnil[0m or the result of appending a singleton list onto the right end of its recursive result. That call of [47mappend[0m always returns a [47mtrue-listp[0m since the singleton list is a true list. (See [practice-formulating-strong-rules-1].) So this is a theorem and a very useful [47m:[0m[47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule: (defthm true-listp-rev-strong (true-listp (rev x))). Use your browser's [31;1mBack Button[0m now to return to [practice-formulating-strong-rules].") (practice-formulating-strong-rules-3 (introduction-to-the-theorem-prover) "Rules suggested by [47m(MEMBER (FOO A) (APPEND (BAR B) (MUM C)))[0m What rules come to mind when looking at the following subterm of a Key Checkpoint? Think of [3mstrong[0m rules (see [strong-rewrite-rules]). (MEMBER (FOO A) (APPEND (BAR B) (MUM C))) Since [47m(append x y)[0m contains all the members of [47mx[0m and all the members of [47my[0m, [47me[0m is a member of [47m(append x y)[0m precisely when [47me[0m is a member of [47mx[0m or of [47my[0m. So a strong statement of this is: (defthm member-append-strong-false (equal (member e (append x y)) (or (member e x) (member e y)))) However, this is not a theorem because [47mmember[0m is not Boolean. [47m(Member e x)[0m, for example, returns the first tail of [47mx[0m that starts with [47me[0m, or else [47mnil[0m. To see an example of this formula that evaluates to [47mnil[0m, let e = 3 x = '(1 2 3) y = '(4 5 6). Then the left-hand side, [47m(member e (append x y))[0m evaluates to [47m(3 4 5 6)[0m while the right-hand side evaluates to [47m(3)[0m. However, the two sides are propositionally equivalent (both either [47mnil[0m or non-[47mnil[0m together). So this is a useful [47m:[0m[47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule: (defthm member-append-strong (iff (member e (append x y)) (or (member e x) (member e y)))). It tells the system that whenever it encounters an instance of [47m(MEMBER e (APPEND x y))[0m in a propositional occurrence (where only its truth value is relevant), it should be replaced by this disjunction of [47m(MEMBER e x)[0m and [47m(MEMBER e y)[0m. The following two formulas are true but provide much weaker rules and we would not add them: (implies (member e x) (member e (append x y))) (implies (member e y) (member e (append x y))) because they each cause the system to backchain upon seeing [47m(MEMBER e (APPEND x y))[0m expressions and will not apply unless one of the two side-conditions can be established. There is a rewrite rule that is even stronger than [47mmember-append-strong[0m. It is suggested by the counterexample, above, for the [47mEQUAL[0m version of the rule. (defthm member-append-really-strong (equal (member e (append x y)) (if (member e x) (append (member e x) y) (member e y)))) While [47mmember-append-strong[0m only rewrites [47mmember-append[0m expressions occurring propositionally, the [47m-really-strong[0m version rewrites [3mevery[0m occurrence. However, this rule will be more useful than [47mmember-append-strong[0m only if you have occurrences of [47mmember[0m in non-propositional places. For example, suppose you encountered a term like: (CONS (MEMBER e (APPEND x y)) z). Then the [47m-strong[0m rule does not apply but the [47m-really-strong[0m rule does. Furthermore, the [47m-really-strong[0m rule, by itself, is not quite as good as the [47m-strong[0m rule in propositional settings! For example, if you have proved the [47m-really-strong[0m rule, you'll notice that the system still has to use induction to prove (IMPLIES (MEMBER E A) (MEMBER E (APPEND B A))). The [47m-really-strong[0m rule would rewrite it to (IMPLIES (MEMBER E A) (IF (MEMBER E A) (APPEND (MEMBER E A) B) (MEMBER E B))) which would further simplify to (IMPLIES (MEMBER E A) (APPEND (MEMBER E A) B)) What lemma does this suggest? The answer is the rather odd: (implies x (append x y)) which rewrites propositional occurrences of [47m(APPEND x y)[0m to [47mT[0m if [47mx[0m is non-[47mnil[0m. This is an inductive fact about [47mappend[0m. A problem with the [47m-really-strong[0m rule is that it transforms even propositional occurrences of [47mmember[0m into mixed propositional and non-propositional occurrences. (defthm member-append-really-strong (equal (member e (append x y)) ; <-- even if this is a propositional occurrence (if (member e x) (append (member e x) y) ; <-- the member in here is not! (member e y)))) So if you are using the [47m-really-strong[0m lemma in a situation in which all your [47mmember[0m expressions are used propositionally, you'll suddenly find yourself confronted with non-propositional uses of [47mmember[0m. Our advice is not to use the [47m-really-strong[0m version unless your application is inherently using [47mmember[0m in a non-propositional way. Use your browser's [31;1mBack Button[0m now to return to [practice-formulating-strong-rules].") (practice-formulating-strong-rules-4 (introduction-to-the-theorem-prover) "Rules suggested by [47m(SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))[0m What rules come to mind when looking at the following subterm of a Key Checkpoint? Think of [3mstrong[0m rules (see [strong-rewrite-rules]). (SUBSETP (APPEND (FOO A) (BAR B)) (MUM C)) When is [47m(append x y)[0m a subset of [47mz[0m? When everything in [47mx[0m is in [47mz[0m and everything in [47my[0m is in [47mz[0m. We would make it a rewrite rule: (defthm subsetp-append-1-strong (equal (subsetp (append x y) z) (and (subsetp x z) (subsetp y z)))) We put the ``[47m-1-[0m'' in the name because there is a comparable theorem for when the [47mappend[0m is in the second argument of the [47msubsetp[0m; see [practice-formulating-strong-rules-5]. This strong rule is better than the conditional rule; (defthm subsetp-append-1-weak (implies (and (subsetp x z) (subsetp y z)) (subsetp (append x y) z))) for all the usual reasons. Use your browser's [31;1mBack Button[0m now to return to [practice-formulating-strong-rules].") (practice-formulating-strong-rules-5 (introduction-to-the-theorem-prover) "Rules suggested by [47m(SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))[0m What rules come to mind when looking at the following subterm of a Key Checkpoint? Think of [3mstrong[0m rules (see [strong-rewrite-rules]). (SUBSETP (FOO A) (APPEND (BAR B) (MUM C))) When is [47mx[0m a subset of [47m(append y z)[0m? Clearly it is if [47mx[0m is a subset of [47my[0m or [47mx[0m is a subset of [47mz[0m. We could write that: (defthm subsetp-append-2-weak (implies (or (subsetp x y) (subsetp x z)) (subsetp x (append y z)))) The rule generated from this is: ``if you ever encounter (an instance of) [47m(SUBSETP x (APPEND y z))[0m, backchain to the [47mor[0m above and try to establish it. If you can establish it, replace the target by [47mT[0m.'' This does not fully characterize the situation though. For example, [47m'(1 2 3 4)[0m is a subset of [47m(append '(1 3) '(2 4))[0m without being a subset of either argument of the [47mappend[0m. However, no obvious equivalence comes to mind --- indeed, to express any of the ideas floating around here requires defining and introducing more functions, which is not recommended unless those functions are already in the problem. For example, if you defined the concept of ``[47mset-minus[0m'' so that [47m(set-minus x y)[0m consists of those elements of [47mx[0m not in [47my[0m, then you could prove: (defthm subset-append-2-strong-but-messy (equal (subsetp x (append y z)) (and (subsetp (set-minus x z) y) (subsetp (set-minus x y) z)))) But this rewrite rule would ``trade'' [47mappend[0m away and introduce [47mset-minus[0m. That might be a good strategy if [47mset-minus[0m were already in the problem. But if it were not, it might not be. We wouldn't recommend this rule unless it were helpful in normalizing the expressions in the problem. We recommend sticking with the weak version of the rule, (defthm subsetp-append-2-weak (implies (or (subsetp x y) (subsetp x z)) (subsetp x (append y z)))). This illustrates the fact that sometimes there is no strong version of a rule! Use your browser's [31;1mBack Button[0m now to return to [practice-formulating-strong-rules].") (practice-formulating-strong-rules-6 (introduction-to-the-theorem-prover) "Rules suggested by [47m(MEMBER (FOO A) (NATS-BELOW (BAR B)))[0m What rules come to mind when looking at the following subterm of a Key Checkpoint? Think of [3mstrong[0m rules (see [strong-rewrite-rules]). (MEMBER (FOO A) (NATS-BELOW (BAR B))) The definition of [47mNATS-BELOW[0m is (defun nats-below (j) (if (zp j) '(0) (cons j (nats-below (- j 1))))) Thus, [47m(nats-below 7)[0m is [47m(7 6 5 4 3 2 1 0)[0m. So when is [47mk[0m a member of [47m(nats-below j)[0m? The weakest version is (defthm member-nats-below-weak (implies (and (natp k) (natp j) (<= k j)) (member k (nats-below j)))) But clearly we could improve this to: (defthm member-nats-below-weak-better (implies (and (natp k) (natp j)) (iff (member k (nats-below j)) (<= k j)))) or even (defthm member-nats-below-weak-better (implies (natp j) (iff (member k (nats-below j)) (and (natp k) (<= k j))))) Clearly though, we'd like to get rid of the [47m(natp j)[0m hypothesis and the neatest plausible version is: (defthm member-nats-below-weak-neatest (iff (member k (nats-below j)) (and (natp j) (natp k) (<= k j)))) But it is not a theorem! For example, if [47mj[0m is [47m-1[0m and [47mk[0m is 0, then the left-hand side above returns [47mt[0m, because [47m(nats-below j)[0m is [47m(0)[0m, but the right-hand side is [47mnil[0m. But this suggests a strategy for dealing with necessary hypotheses, like [47m(natp j)[0m. We can move them into an [47mIF[0m on the right-hand side! Something like this might be a useful rewrite rule: (iff (member k (nats-below j)) (if (natp j) (and (natp k) (<= k j)) ...)). We know, from [47mmember-nats-below-weak-better[0m, that if [47m(natp j)[0m is true, the [47mmember[0m is equivalent to [47m(and (natp k) (<= k j))[0m. So now consider what we know if [47m(natp j)[0m is false. If we can think of some term it's equivalent to and that term is simpler than the [47mmember[0m expression, we have a strong rule. But by inspection of the definition of [47mnats-below[0m, we see that when [47m(natp j)[0m is false, [47m(nats-below j)[0m is the list [47m(0)[0m because [47m(zp j)[0m is t. That is, [47mnats-below[0m treats all non-natural arguments like they were [47m0[0m. Thus, when [47m(natp j)[0m is false, [47m(member k (nats-below j))[0m is [47m(member k '(0))[0m, which is [47m(equal k 0)[0m. So the strong version is (defthm member-nats-below-strong (iff (member k (nats-below j)) (if (natp j) (and (natp k) (<= k j)) (equal k 0)))) This is a great [47m:[0m[47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule. It gets rid of the [47mmember[0m and [47mnats-below[0m and introduces arithmetic. This example illustrates the idea of putting an [47mif[0m on the right-hand-side of the equivalence. Many users tend to limit themselves to propositional forms inside [47miff[0m or to simple expressions inside of [47mequal[0m. But it is quite natural to use [47mif[0m to express what the answer is: if [47mj[0m is a natural, then [47mk[0m is in [47m(nats-below j)[0m precisely if [47mk[0m is a natural less than or equal to [47mj[0m; if [47mj[0m is not a natural, then [47mk[0m is in [47m(nats-below j)[0m precisely if [47mk[0m is [47m0[0m. The one weakness of the rule above is that it only rewrites [47m(member x (nats-below y))[0m when an instance of that target term occurs in a propositional setting, e.g., when the governing equivalence relation is [47miff[0m. But, thanks to Andrei Koltsov, an even stronger version is available as an unconditional [47mequal[0mity rewrite: (defthm member-nats-below-stronger (equal (member x (nats-below y)) (if (natp x) (if (natp y) (if (<= x y) (nats-below x) nil) (if (= x 0) '(0) nil)) nil))) The key observation is that when [47mx[0m and [47my[0m are both naturals and [47m(<= x y)[0m, the result that [47mmember[0m computes can be expressed with [47mnats-below[0m. You may wonder whether this stronger rule allows the immediate proof of the earlier [47mmember-nats-below-strong[0m and the answer is yes, because from the definition of [47mnats-below[0m ACL2 has observed that [47m(nats-below x)[0m is a [47mcons[0m whenever [47mx[0m is a natural. Use [47mif[0m to lay out the cases you must consider, if you can think of a simpler, equivalent expression for every possible case. Use your browser's [31;1mBack Button[0m now to return to [practice-formulating-strong-rules].") (pre-built-binary-distributions (about-acl2) "Pre-built binary distributions of ACL2 Visit the ``Recent changes to this page'' link on the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/} to see if there are other shortcuts available. [31;1mWARNING[0m: Some of these packages might be for old versions of ACL2. We recommend that you use the latest version of ACL2 (Version 8.6). Linux/Mac/Windows Binaries in ACL2s The ACL2 Sedan (see [ACL2-sedan]), also known as ACL2s, is an Eclipse-based IDE for ACL2 that is distributed with pre-certified books and pre-built binaries, though it is not always based on the latest ACL2 version. The ACL2 Sedan is distributed via a Homebrew package for Linux and macOS users, and as a Windows Subsystem for Linux distro for Windows users. See [ACL2s::ACL2s-installation] for instructions for installing the ACL2 Sedan. Note that these instructions are typically intended for students at Northeastern, but hopefully are useful for anyone interested in installing ACL2s. Windows In the past, a Windows Installer for ACL2 has included a Unix environment, pre-certified standard and workshop books, and a copy of Gnu Emacs. This capability has largely been superseded; see [windows-installation]. macOS ACL2 versions are sometimes been made available {under MacPorts | https://ports.macports.org/port/acl2/}. Some folks maintain {a Homebrew package | https://formulae.brew.sh/formula/acl2} that tracks the latest stable version of ACL2. Debian GNU Linux A Debian Gnu Linux package is available, which is likely to work on other Linux systems as well. Thanks to Camm Maguire for maintaining this package, and for pointing out that as Debian packages are simply [47mar[0m and [47mtar[0m archives, they can be unpacked on any linux system, and who has said: ``If someone is running Debian, all they want to do is 'apt-get install acl2', doing likewise for any optional add-on package they wish as well, e.g. emacs, infix, etc.'' Alternatively, Debian GNU Linux users may wish to {download the ACL2 Debian package for Linux | http://packages.qa.debian.org/a/acl2.html}. An alternate location you might want to check is {[47mbackports.debian.org[0m | http://backports.debian.org}. Docker images Some folks maintain Docker images for ACL2. Below is a nonexhaustive list of such images; feel free to add to this list. DH refers to Docker Hub and GHCR refers to the GitHub Container Registry. * DH: {atwalter/acl2 | https://hub.docker.com/r/atwalter/acl2/}, GHCR: {mister-walter/acl2 | https://github.com/mister-walter/acl2-docker/pkgs/container/acl2} * DH: {atwalter/acl2s | https://hub.docker.com/r/atwalter/acl2s/}, GHCR: {mister-walter/acl2s | https://github.com/mister-walter/acl2s-docker/pkgs/container/acl2s}") (prettyify-clause (pointers) "See [system-utilities].") (primitive (programming acl2-built-ins) "Primitive functions built into ACL2 without definitions The ACL2 [ground-zero] [theory] includes axioms about some built-in functions that are not given explicit definitions, such as [47m[<][0m, [47m[car][0m, and [47m[symbolp][0m. We sometimes call such functions [3mprimitives[0m. The built-in constant [47m*primitive-formals-and-guards*[0m is an alist that associates each primitive with its list of formals and its [guard]; that is, each element of that alist is of the form [47m(name formals guard)[0m. The value of this constant is displayed below. [31;1mDefinition: [0m<*primitive-formals-and-guards*> (defconst *primitive-formals-and-guards* '((acl2-numberp (x) 't) (bad-atom<= (x y) (if (bad-atom x) (bad-atom y) 'nil)) (binary-* (x y) (if (acl2-numberp x) (acl2-numberp y) 'nil)) (binary-+ (x y) (if (acl2-numberp x) (acl2-numberp y) 'nil)) (unary-- (x) (acl2-numberp x)) (unary-/ (x) (if (acl2-numberp x) (not (equal x '0)) 'nil)) (< (x y) (if (rationalp x) (rationalp y) 'nil)) (car (x) (if (consp x) 't (equal x 'nil))) (cdr (x) (if (consp x) 't (equal x 'nil))) (char-code (x) (characterp x)) (characterp (x) 't) (code-char (x) (if (integerp x) (if (< x '0) 'nil (< x '256)) 'nil)) (complex (x y) (if (rationalp x) (rationalp y) 'nil)) (complex-rationalp (x) 't) (coerce (x y) (if (equal y 'list) (stringp x) (if (equal y 'string) (character-listp x) 'nil))) (cons (x y) 't) (consp (x) 't) (denominator (x) (rationalp x)) (equal (x y) 't) (if (x y z) 't) (imagpart (x) (acl2-numberp x)) (integerp (x) 't) (intern-in-package-of-symbol (str sym) (if (stringp str) (symbolp sym) 'nil)) (numerator (x) (rationalp x)) (pkg-imports (pkg) (stringp pkg)) (pkg-witness (pkg) (if (stringp pkg) (not (equal pkg '"")) 'nil)) (rationalp (x) 't) (realpart (x) (acl2-numberp x)) (stringp (x) 't) (symbol-name (x) (symbolp x)) (symbol-package-name (x) (symbolp x)) (symbolp (x) 't)))") (princ$ (io acl2-built-ins) "Print an atom Use [47mprinc$[0m to do basic printing of atoms (i.e., other than [47mcons[0m pairs). In particular, [47mprinc$[0m prints a string without the surrounding double-quotes and without escaping double-quote characters within the string. Note that [47mprinc$[0m is sensitive to the print-base, print-radix, and print-case; see [set-print-base-radix] and see [set-print-case]. [47mPrinc$[0m returns [47m[state][0m. Examples: ACL2 !>(princ$ "Howdy ho" (standard-co state) state) Howdy ho<state> ACL2 !>(pprogn (princ$ "Howdy ho" (standard-co state) state) (newline (standard-co state) state)) Howdy ho <state> ACL2 !>(princ$ "ab\"cd" *standard-co* state) ab"cd<state> ACL2 !> ACL2 !>(princ$ 17 *standard-co* state) 17<state> ACL2 !>(set-print-base 16 state) ; might be nicer to use set-print-base-radix <state> ACL2 !>(princ$ 17 *standard-co* state) 11<state> ACL2 !>(set-print-radix t state) <state> ACL2 !>(princ$ 17 *standard-co* state) #x11<state> ACL2 !>(princ$ 'xyz *standard-co* state) XYZ<state> ACL2 !>(set-print-case :downcase state) <state> ACL2 !>(princ$ 'xyz *standard-co* state) xyz<state> ACL2 !> The [guard] for [47m(princ$ x channel state)[0m is essentially as follows; see [io] for an explanation of guards of certain built-in functions that take [state], such as [47mprinc$[0m. (and (or (acl2-numberp x) (characterp x) (stringp x) (symbolp x)) (state-p1 state-state) (symbolp channel) (open-output-channel-p1 channel :character state-state)) See [fmt] for more sophisticated printing routines, and see [io] for general information about input and output. Subtopics [Newline] Print a newline to a given output channel") (print-base-p (io acl2-built-ins) "Recognizer for print bases that are understood by functions such as [explode-nonnegative-integer] and [explode-atom]. [31;1mFunction: [0m<print-base-p> (defun print-base-p (print-base) (declare (xargs :guard t)) (and (member print-base '(2 8 10 16)) t))") (print-cl-cache (apply$) "Information about the cache supporting [47mapply$[0m General Form: (print-cl-cache) Logically this function always returns [47mNIL[0m but it prints to the comment window information about the cache that supports the application of quoted [47mLAMBDA[0m objects by [47m[apply$][0m. The name stands for Print Compiled Lambda Cache. In general there is a non-empty cache line for each [47mLAMBDA[0m object used in a [47mdefun[0m or seen by [47mverify-guards[0m or by [47mapply$[0m in the evaluation theory. But the cache has a maximal size. If a new [47mLAMBDA[0m object is seen when the cache is full, the least recently used line is re-used for the new [47mLAMBDA[0m object. By default the maximal cache size is 1000. This can be changed -- with the side-effect of clearing the cache -- by exiting the ACL2 loop with [47m:q[0m and doing [47m(setq *cl-cache* k)[0m, where [47mk[0m is the new maximal size. When [47mprint-cl-cache[0m is called it prints a block about each non-empty cache line enumerated from 0, and listed in the order that the cache is searched when a [47mLAMBDA[0m object is [47mapply$[0md. Each block contains: * [47m:lambda-object[0m - a fully translated [47mLAMBDA[0m object * [47m:status[0m - one of four keywords with the following meanings: * [47m:GOOD[0m - the [47mLAMBDA[0m object is well-formed and Common Lisp compliant (``guard verified'') in the current world * [47m:BAD[0m - the [47mLAMBDA[0m object is not well-formed or not Common Lisp compliant (``guard verified'') in the current world, but (with high probability) there is a world in which it is well-formed and compliant * [47m:UGLY[0m - the [47mLAMBDA[0m object is so ill-formed it can never be [47m:GOOD[0m in any world, e.g., [47m(LAMBDA (T) (CONS 3 . 4))[0m * [47m:UNKNOWN[0m - we do not know the status of this object in the current world and leave it to [47mapply$[0m to determine the proper status the next time this object is [47mapply$[0md. * [47m:abs-event-no[0m - the absolute event number (in the current world) at which the [47mLAMBDA[0m object was proved to have status [47m:GOOD[0m, or [47mNIL[0m if its status is not [47m:GOOD[0m * [47m:extracts[0m - some parts of the [47mLAMBDA[0m object sufficient to confirm well-formedness. Well-formedness must be re-confirmed if the world is retracted to before the object became [47m:GOOD[0m * [47m:problem[0m - One of the following values. * [47mNIL[0m - no problem; status is [47m:GOOD[0m * [47mNOT-WELL-FORMED[0m - the [47mLAMBDA[0m is syntactically plausible but not well-formed but could, perhaps, become well-formed in a suitable extension of the current world, e.g., the body calls an undefined function (but perhaps it can be defined), the body contains a [47m:program[0m mode function (but perhaps that could be upgraded to [47m:logic[0m mode), the body contains an unbadged or unwarranted function symbol (but perhaps [47mdefbadge[0m or [47mdefwarrant[0m could resolve the issue), etc. * [47m(GUARD-USES-NON-COMPLIANT-FNS . fns)[0m - [47mfns[0m is a list of function symbols used in the guard of the [47mLAMBDA[0m object that have not yet had their guards verified. * [47m(BODY-USES-NON-COMPLIANT-FNS . fns)[0m - [47mfns[0m is a list of function symbols used in the body of the [47mLAMBDA[0m object that have not yet had their guards verified. * [47m(UNPROVED-GUARD-CLAUSES . cl-set)[0m - [47mcl-set[0m is the list of guard conjectures -- written as clauses -- that tau was unable to prove. * [47mRE-VALIDATION-INTERRUPTED[0m - an interrupt aborted the updating of this cache line * [47m:hits[0m - The number of times [47mapply$[0m has seen this [47mLAMBDA[0m object * [47m:guard-code[0m - [47mNIL[0m or the string ``<code>'' indicating that the guard has been compiled * [47m:lambda-code[0m - [47mNIL[0m or the string ``<code>'' indicating that the [47mLAMBDA[0m object has been compiled Using This Information to Speed Up LAMBDA Application [3mRemember:[0m A lot of programmers spend enormous amounts of time and effort optimizing code that runs adequately fast! Do not make the mistake of investing your time here unless you really have a critical ACL2 top-level read-eval-print form that you [3mknow[0m runs too slowly! If you see a [47mLAMBDA[0m object in the cache with [47m:status[0m [47m:BAD[0m then it is being interpreted. If you believe it can be converted to [47m:GOOD[0m and thus compiled, [3mand you believe you will [47mapply$[0m[3m it often enough in the future to warrant trying to speed it up,[0m then here are some tips. To be converted from [47m:BAD[0m to [47m:GOOD[0m a [47mLAMBDA[0m has to be both well-formed and [guard] verified. The cache doesn't try to verify objects that are not well-formed. So first make sure your object is well-formed and then once it is make sure it is guard verified. If the [47m:problem[0m is [47mNOT-WELL-FORMED[0m the [47m:lambda-object[0m does not pass the [47m[well-formed-lambda-objectp][0m test. That predicate gives no hint as to why, but if you call [47m:[0m[47m[translam][0m on the [47m:lambda-object[0m it might give you more information. E.g., ACL2 !>:translam (lambda (x) (bar x)) ACL2 Error in TRANSLAM: The body of a LAMBDA object or lambda$ term should be fully badged but BAR is used in (BAR X) and has no badge. Other typical problems are that a function which was formerly in [47m:logic[0m mode is now in [47m:program[0m mode because of an undo, or the [47mLAMBDA[0m object is not [tame], as in ACL2 !>:translam (lambda (x) (apply$ (cons x 'nil) 'sq)) ACL2 Error in TRANSLAM: The body of a LAMBDA object or lambda$ term must be tame and (APPLY$ (CONS X 'NIL) 'SQ) is not. Here the [47mLAMBDA[0m is unfixable because the arguments to [47mapply$[0m are in the wrong order. Typing the object correctly may fix the problem. In any case, you may need to extend the world to convert functions to [47m:logic[0m mode, obtain [warrant]s (or at least [badge]s for functions that return multiple results), or even use a different [47mLAMBDA[0m object. When you think you've got a well-formed [47mLAMBDA[0m object, you can get the cache to update itself by applying the (new?) object in the (new?) world, ACL2 !>(apply$ '(lambda (x) (apply$ 'sq (cons x 'nil))) '(5)) 25 ACL2 !>(print-cl-cache) and see if the status is [47m:GOOD[0m and, if not, what the [47m:problem[0m is. If the problem is one of [47mGUARD-USES-NON-COMPLIANT-FNS[0m, [47mBODY-USES-NON-COMPLIANT-FNS[0m, or [47mUNPROVED-GUARD-CLAUSES[0m, the [47mLAMBDA[0m object is well-formed but not guard verified. Again, you may need to further extend the world by calling [47m[verify-guards][0m on the listed function symbols in first two problems or call [47mverify-guard[0m on the lambda object itself for an opportunity to supply [47m:hints[0m to prove the guard [clause]s listed in the third problem. For example, suppose we define [47msqu[0m with a guard of [47mnatp[0m, (defun$ squ (x) (declare (type (satisfies natp) x)) (* x x)) And suppose we define [47mnfixer[0m to always return a natural number but in such a way as its type-prescription is weak. (defun$ nfixer (x) (if (equal x (car (cons x x))) (nfix x) nil)) Furthermore, let's disable [47mnfixer[0m so the prover has no way of discovering the proper type. (in-theory (disable nfixer)) If we then ACL2 !>(apply$ '(lambda (x) (squ (nfixer x))) '(5)) 25 and use [47mprint-cl-cache[0m, we see that the [47m:problem[0m is that [47mNFIXER[0m is not guard verified. So we ACL2 !>(verify-guards nfixer) and try the [47mapply$[0m and the [47mprint-cl-cache[0m again. This time the [47m:problem[0m is [47m(UNPROVED-GUARD-CLAUSES ((NATP (NFIXER X))))[0m. So tau couldn't prove that [47mNFIXER[0m returns a [47mNATP[0m. We can thus ACL2 !>(verify-guards (lambda (x) (squ (nfixer x))) :hints (("Goal" :in-theory (enable nfixer)))) The [47mverify-guards[0m should succeed. Successful calls of [47mverify-guards[0m on [47mLAMBDA[0m objects updates the cache, so we don't have to ``trick'' the cache into updating itself by [47mapply$[0ming the [47mlambda[0m again. We can now just do [47m(print-cl-cache)[0m and see the [47m:status[0m is [47m:GOOD[0m. Whether all this work is worth is depends on how often you're going to execute this [47mLAMBDA[0m object! A Single Performance Comparison Suppose we have defined [47msqu[0m and [47mnfixer[0m, disabled [47mnfixer[0m, and verified the guards of [47mnfixer[0m as above. Additionally, define the [scion] that maps a predicate over a list and checks that the predicate holds for every element. (defun$ always$ (pred lst) (if (endp lst) t (and (apply$ pred (list (car lst))) (always$ pred (cdr lst))))) and define the function that builds a list of the first [47mn+1[0m naturals and use it to define the misleadingly named constant [47m*million*[0m which contains the first million and one naturals. (defun nats-ac (n ac) (if (zp n) (cons 0 ac) (nats-ac (- n 1) (cons n ac)))) (defconst *million* (nats-ac 1000000 nil)) Now observe that [47m(lambda (x) (natp (squ (nfixer x))))[0m suffers the same problem we witnessed above: tau cannot prove the guard clause because [47mnfixer[0m is disabled. So we can do an experiment! How long does it take to run this [47m:BAD[0m lambda object over the list [47m*million*[0m? And then, how long does it take to do it again after verifying its guards and turning its status to [47m:GOOD[0m? ACL2 !>(time$ (always$ '(lambda (x) (natp (squ (nfixer x)))) *million*)) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 4.35 seconds realtime, 4.35 seconds runtime ; (128,000,160 bytes allocated). T ACL2 !>(verify-guards (lambda (x) (natp (squ (nfixer x)))) :hints (("Goal" :in-theory (enable nfixer)))) ...[successful but output elided]... ACL2 !>(time$ (always$ '(lambda (x) (natp (squ (nfixer x)))) *million*)) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.19 seconds realtime, 0.19 seconds runtime ; (32,000,064 bytes allocated). T So we dramatically sped up the computation. But we almost certainly spent longer than the original 4.35 seconds debugging the problems and converting the object's status to [47m:GOOD[0m. So unless we're going to be doing this repeatedly in the future, it probably wasn't worth it!") (print-control (io) "Advanced controls of ACL2 printing See [io] for a summary of printing in ACL2. Here we document some advanced ways to control what is printed by ACL2's primary printing routines. See [47m[set-print-base-radix][0m, [47m[set-print-base][0m, [47m[set-print-radix][0m, and [47m[set-print-case][0m for discussions of the most common ways to control what is printed. Indeed, these are the only ways to control the behavior of [47m[princ$][0m and [47mprin1$[0m. See [47m[set-fmt-hard-right-margin][0m for how to set the right margin for prover output and, more generally, output from formatted printing functions (see [47m[fmt][0m). Note that [47mset-print-right-margin[0m, mentioned below, does not affect such printing. The rest of this topic is for advanced users of ACL2. We refer to Common Lisp behavior, as described in any good Common Lisp documentation. [31;1mPrint-control variables[0m. [47m[Set-print-base][0m, [47m[set-print-radix][0m, and [47m[set-print-case][0m assign to corresponding so-called ``[state] global variables'' [47m'print-base[0m, [47m'print-radix[0m, and [47m'print-case[0m, which can be accessed using the expressions [47m(@ print-base)[0m, [47m(@ print-radix)[0m, and [47m(@ print-case)[0m, respectively; see [assign]. Here is a table showing all print-control variables, their setters, and their defaults. Also see [47m[set-print-base-radix][0m. print-base set-print-base 10 print-case set-print-case :upcase print-circle set-print-circle nil [but see remark on print-circle-files, below] print-escape set-print-escape t print-length set-print-length nil print-level set-print-level nil print-lines set-print-lines nil print-pretty set-print-pretty nil print-radix set-print-radix nil print-readably set-print-readably nil print-right-margin set-print-right-margin nil Each ACL2 print-control variable [47mprint-xxx[0m can correspond in function to Common Lisp variable [47m*PRINT-XXX*[0m. Specifically, the evaluation of forms [47m(set-print-base t)[0m, [47m(set-print-radix t)[0m, and [47m(set-print-case t)[0m affects ACL2 printing functions in much the same way that setting to [47mt[0m Common Lisp variables [47m*PRINT-BASE*[0m, [47m*PRINT-RADIX*[0m, and [47m*PRINT-CASE*[0m, respectively, affects Common Lisp printing. The same is true for [47mprint-escape[0m, except that this does not affect [47m[princ$][0m or [47mprin1$[0m, which correspond to Common Lisp functions [47mprinc[0m and [47mprin1[0m: [47mprinc[0m treats [47m*PRINT-ESCAPE*[0m as [47mnil[0m while [47mprin1[0m treats [47m*PRINT-ESCAPE*[0m as [47mt[0m. Moreover, all print-control variables not mentioned in this paragraph are set to their defaults in [47m[princ$][0m and [47mprin1$[0m, as indicated by ACL2 constant [47m*print-control-defaults*[0m, except that [47mprint-readably[0m is set to [47mnil[0m in [47mprinc$[0m. [47m[Fmt][0m and its related functions are sensitive to state globals [47m'print-base[0m, [47m'print-radix[0m, [47m'print-case[0m, [47m'print-escape[0m, and [47m'print-readably[0m, in analogy with Common Lisp functions that don't fix [47m*PRINT-ESCAPE*[0m or [47m*PRINT-READABLY*[0m. But the [47m[fmt][0m functions do not respect settings of other print-control variables; for example, they act as though [47m'print-circle[0m is [47mnil[0m. Since ACL2 output is produced using the same underlying print routines as the [47m[fmt][0m functions, it also is insensitive to all print-control variables except for the five above. To control the print-level and print-length used for producing ACL2 output, see [set-evisc-tuple]. [Print-object$] and [print-object$-preserving-case] are sensitive to the values of all of the print-control variables except for [47m'print-escape[0m. Evaluate [47m(reset-print-control)[0m to restore all print-control variables to their original settings, as stored in constant [47m*print-control-defaults*[0m. (Remark on [47mprint-circle-files[0m: ACL2 typically binds [47m'print-circle[0m to [47mt[0m before writing [certificate] files, or auxiliary files that are compiled when [47m[make-event][0m forms are present in a book, or files in support of [47m:[0m[47m[comp][0m commands. This binding allows for structure sharing that can keep these files from growing large. End of Remark.) (Remark for those using ACL2 built on CLtL1 (non-ANSI) Gnu Common Lisp (GCL): Note that Common Lisp variables [47m*PRINT-LINES*[0m, [47m*PRINT-MISER-WIDTH*[0m, [47m*PRINT-READABLY*[0m, [47m*PRINT-PPRINT-DISPATCH*[0m, and [47m*PRINT-RIGHT-MARGIN*[0m do not have any effect for such GCL versions.)") (print-gv (guard debugging) "Print a form whose evaluation caused a guard violation By default, ACL2 checks input constraints on functions, known as [guard]s. When guards are violated, an informative message is printed; but sometimes it is useful to investigate why the guard check fails. The utility [47mprint-gv[0m is provided for that purpose. (Alternatively, you may prefer to avoid guards entirely with [47m(set-guard-checking :none)[0m; see [set-guard-checking].) Example Forms: (print-gv) :print-gv ; same as above (print-gv ; same as above, showing all system defaults :conjunct nil :evisc-tuple (print-gv-evisc-tuple) :substitute nil) (print-gv :substitute 20) (print-gv :evisc-tuple (evisc-tuple 4 4 nil nil)) (print-gv :evisc-tuple (evisc-tuple 4 4 nil nil)) (print-gv :evisc-tuple (evisc-tuple 4 ; print-level 5 ; print-length (world-evisceration-alist state nil) nil ; hiding-cars )) General Form: (print-gv :conjunct c :substitute s :evisc-tuple e) where the keyword arguments are optional. These arguments have the following effects and system defaults, but note that the defaults can be changed by the user; see [set-print-gv-defaults]. * The [47m:conjunct[0m argument is [47mnil[0m by default, indicating that a form is to be displayed whose evaluation represents the [guard] evaluation that produced [47mnil[0m. A value of [47mt[0m indicates that ACL2 should parse the guard into conjuncts, and display the conjunct that actually evaluated to [47mnil[0m. It does this by evaluating each conjunct in turn until one produces a result of [47mnil[0m. * The [47m:evisc-tuple[0m argument should be an [evisc-tuple]. Its default is the value of the expression [47m(print-gv-evisc-tuple)[0m, which specifies hiding only the ACL2 logical [world], so that the symbol [47m<world>[0m is printed instead of the actual world. See [evisc-tuple] for a discussion of evisc-tuples. * The [47m:substitute[0m argument is [47mnil[0m by default, indicating that the displayed form uses [47m[flet][0m, which avoids duplicate occurrences of actual parameters. A value of [47mt[0m indicates that ACL2 should instead substitute those actuals into the guard. Otherwise the value should be a natural number [47mn[0m, which behaves the same as [47mnil[0m except when large duplicated terms are to be avoided in the precise sense below, in which case the behavior is the same as [47mt[0m, that is, [47mflet[0m is used. The latter case (using [47mflet[0m) applies when some variable in the guard or (if [47m:conjunct t[0m is specified) conjunct has at least two occurrences, and corresponds to an actual parameter with at least [47mn[0m conses. Note that the number of conses is counted in the ``translated'' term (guard or conjunct); see [term]. Again, the user can change these defaults; see [set-print-gv-defaults]. For example, one might wish to evaluate [47m(set-print-gv-defaults :substitute 20)[0m so that [47m[flet][0m is used only when that avoids certain duplicated large terms, as discussed just above. [31;1mRemarks[0m * (1) [47mPrint-gv[0m starts by temporarily replacing the current installed ACL2 [world] with the world that was installed at the time the guard violation took place. The current world is re-installed when [47mprint-gv[0m returns. We illustrate this point with an example at the end of this topic. * (2) The output from [47mprint-gv[0m always goes to the terminal. (Specifically, the output goes to the value of the constant [47m[*standard-co*][0m.) * (3) While [47mprint-gv[0m is a utility for debugging [guard] violations, see [guard-debug] for a different sort of utility, which assists in debugging failed proofs arising from guard verification. To see how one might use [47mprint-gv[0m, consider the following definition. (defun foo (x) (declare (xargs :guard (and (integerp x) (posp (+ -2 x)) (posp (+ 3 x)) (posp (+ -4 x))))) x) Now suppose we evaluate a call of foo and obtain a guard violation. ACL2 !>(foo 1) ACL2 Error in TOP-LEVEL: The guard for the function call (FOO X), which is (AND (INTEGERP X) (POSP (+ -2 X)) (POSP (+ 3 X)) (POSP (+ -4 X))), is violated by the arguments in the call (FOO 1). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. Let us investigate this guard failure. First we use [47mprint-gv[0m to obtain a form that represents our guard violation. Just for fun, we'll check that it indeed evaluates to [47mnil[0m. ACL2 !>:print-gv (FLET ((FOO{GUARD} (X) (DECLARE (IGNORABLE X)) (AND (INTEGERP X) (POSP (+ -2 X)) (POSP (+ 3 X)) (POSP (+ -4 X))))) (FOO{GUARD} 1)) ACL2 !>(FLET ((FOO{GUARD} (X) (DECLARE (IGNORABLE X)) (AND (INTEGERP X) (POSP (+ -2 X)) (POSP (+ 3 X)) (POSP (+ -4 X))))) (FOO{GUARD} 1)) NIL This form doesn't tell us which of the four conjuncts actually evaluated to [47mnil[0m. We can fix that by using the [47m:conjunct[0m keyword argument. ACL2 !>(print-gv :conjunct t) Showing guard conjunct (#2 of 4) that evaluates to nil: (FLET ((FOO{GUARD} (X) (POSP (+ -2 X)))) (FOO{GUARD} 1)). ACL2 !> But here's another way to analyze the guard failure. Let's change [47m[and][0m to [47m[list][0m in the result of [47m:print-gv[0m, to see which conjuncts are false. Of course, the user can massage the guard form in any way that might be helpful. ACL2 !>(FLET ((FOO{GUARD} (X) (DECLARE (IGNORABLE X)) (list (INTEGERP X) (POSP (+ -2 X)) (POSP (+ 3 X)) (POSP (+ -4 X))))) (FOO{GUARD} 1)) (T NIL T NIL) ACL2 !> The [47mNIL[0m results show that the second and fourth conjuncts of the guard were false in our particular case. If you use local [stobj]s (see [with-local-stobj]) or stobj fields of stobjs, you may need to edit the output of [47mprint-gv[0m in order to evaluate it. Consider the following example. (defstobj st fld) (defun g (x st) (declare (xargs :guard (consp x) :stobjs st) (ignore x)) (fld st)) (defun test () (with-local-stobj st (mv-let (result st) (mv (g 3 st) st) result))) (test) Then [47m:print-gv[0m yields the result shown below. (FLET ((G{GUARD} (X ST) (DECLARE (IGNORABLE X ST)) (AND (STP ST) (CONSP X)))) (G{GUARD} 3 |<some-stobj>|)) In this example you could replace ``[47m|<some-stobj>|[0m'' by ``[47mst[0m'' to obtain a result of [47mnil[0m. But similar cases may require the use of a local stobj that is no longer available, in which case you may need to be creative in order to take advantage of [47m:print-gv[0m. Here is such an example. (defstobj st2 fld2) (defun g2 (st2) (declare (xargs :guard (null (fld2 st2)) :stobjs st2)) (mv 0 st2)) (defun test2 () (with-local-stobj st2 (mv-let (result st2) (let ((st2 (update-fld2 17 st2))) (g2 st2)) result))) (test2) In this case, [47m:print-gv[0m yields the following. (FLET ((G2{GUARD} (ST2) (DECLARE (IGNORABLE ST2)) (AND (ST2P ST2) (NULL (FLD2 ST2))))) (G2{GUARD} |<some-stobj>|)) But if you replace ``[47m|<some-stobj>|[0m'' by ``[47mst[0m'', the guard holds; it is only the local stobj, which is no longer available, that produced a guard violation (because its field had been updated to a cons). ACL2 !>(FLET ((G2{GUARD} (ST2) (DECLARE (IGNORABLE ST2)) (AND (ST2P ST2) (NULL (FLD2 ST2))))) (G2{GUARD} st2)) T ACL2 !> We conclude with an example that illustrates point (1) above, regarding the installation of the [world] that was in place at the time the guard violation took place. In the following, the [47m[progn][0m call fails when the form [47m(foo 3)[0m causes a guard violation. (progn (defn g (x) (consp x)) (defun foo (x) (declare (xargs :guard (g x))) (car x)) (value-triple (foo 3))) We can then issue [47mprint-gv[0m: ACL2 !>:print-gv (FLET ((FOO{GUARD} (X) (DECLARE (IGNORABLE X)) (G X))) (FOO{GUARD} 3)) ACL2 !> However, if you try to evaluate this form, you will get an error because the function [47mg[0m is not currently defined. This problem can be solved by preceding [47m:print-gv[0m with [47m:redo-flat[0m, to re-run the events up to the one that failed; see [redo-flat]. Subtopics [Set-print-gv-defaults] Set default keyword values for [47m[print-gv][0m") (print-object$ (io acl2-built-ins) "Print an object to an open object output channel General Form: (print-object$ x channel state) where [47mx[0m is any ACL2 object and [47mchannel[0m is an open object output channel. See [io]. Remarks A newline is printed just above [47mx[0m. To eliminate that newline or print a given comment instead, see [print-object$+]. [47mPrint-object$[0m pays attention to the values of [print-control] variables. To provide them as keyword arguments rather than assigning them globally, see [print-object$+]. By default, the output of [47mprint-object$[0m is human-readable. To use [serialize] printing instead, first set the serialize character using [47m[set-serialize-character][0m. For a related utility, see [47m[write-list][0m.") (print-object$+ (io acl2-built-ins) "Print an object to an open output channel in a specified manner General Form: (print-object$+ x ; an ACL2 object channel ; an open object output channel &key header ; nil or a comment string (see below) serialize-character ; as in with-serialize-character print-base print-case ... ; print-control variables ) This macro is a more flexible variant of [47m[print-object$][0m. Any of the print-control variables may be provided as a keyword; see [print-control]. All arguments are evaluated. The [47m:header[0m is printed so that it immediately precedes [47mx[0m. By default, a single newline is what is printed for the header. If [47m:header[0m is specified as [47mnil[0m then no such header is printed. Otherwise, the value [47m:header[0m should be a string for which the first non-whitespace character (if any) on each line is a semicolon ([47m;[0m). If the last character of the string is not a newline, then a newline will be printed to separate the string from [47mx[0m. The [47m:serialize-character[0m keyword argument has a default of [47mnil[0m. If it is supplied a value other than [47mnil[0m or [47m'nil[0m (even if it is supplied an expression other than those two constants), then it is an error to supply other keyword arguments. Otherwise printing is done without serialization (see [serialize]).") (print-object$-preserving-case (pointers) "See [io].") (print-summary-user (pointers) "See [finalize-event-user].") (printing-to-strings (io) "Printing to strings instead of files or standard output Each of ACL2's formatted printing functions, [47mFM*[0m, has an analogous macro [47mFM*-TO-STRING[0m indicated below. These functions do not include a channel or [47m[state][0m as an argument, and [47mFM*-TO-STRING[0m returns the string that [47mFM*[0m would print to the state, in place of [47mstate[0m; see [fmt]. The legal keyword arguments are described below. General Forms: result (fms-to-string string alist &key ...) ; string (fmt-to-string string alist &key ...) ; (mv col string) (fmt1-to-string string alist column &key ...) ; (mv col string) (fms!-to-string string alist &key ...) ; string (fmt!-to-string string alist &key ...) ; (mv col string) (fmt1!-to-string string alist column &key ...) ; (mv col string) The legal keyword arguments are as follows. They are all optional with a default of [47mnil[0m. [47m:Evisc-tuple[0m is evaluated, and corresponds exactly to the [47mevisc-tuple[0m argument of the corresponding [47mFM*[0m function; see [fmt]. [47m:Fmt-control-alist[0m should typically evaluate to an alist that maps print-control variables to values; see [print-control]. Any alist mapping variables to values is legal, however. By default the print controls are set according to the value of constant [47m*fmt-control-defaults*[0m; [47m:fmt-control-alist[0m overrides these defaults. For example, [47m*fmt-control-defaults*[0m sets the right margin just as it is set in the initial ACL2 [state], by binding [47mfmt-soft-right-margin[0m and [47mfmt-hard-right-margin[0m to their respective defaults of [47m*fmt-soft-right-margin-default*[0m and [47m*fmt-hard-right-margin-default*[0m. The following example shows how you can override those defaults, in this case arranging to print flat by setting the right margin to a large number. (fmt-to-string "~x0" (list (cons #\0 (make-list 30))) :fmt-control-alist `((fmt-soft-right-margin . 10000) (fmt-hard-right-margin . 10000))) Also see [io] for a discussion of the utility [47mget-output-stream-string$[0m, which allows for accumulating the results of more than one printing call into a single string but requires the use of [47m[state][0m. [31;1mRemarks on deviation from the [47m[fmt][0m[31;1m functions.[0m 1. The [47m[evisc-table][0m is ignored by these functions that print to strings. Use the [47m:evisc-tuple[0m keyword instead. 2. [Iprinting] is turned off during evaluation of calls of these functions, even if it is enabled globally. The reason is that for each iprint index, [47mi[0m, that is bound during creation of the result string, that binding would disappear after the string is returned; so it would be misleading or an error to read [47m#@i#[0m after that return. 3. The following remark is subtle; see [fmt!] for relevant background. By default, there is identical behavior for each pair of functions of the form [47mfm<..>-to-string[0m and [47mfm<..>!-to-string[0m: both functions act like the [47mfm<..>![0m function, which is to say, they both avoid printing a backslash ([47m\[0m) when the right margin is exceeded, so that the results can be read by ACL2. If you include the pair [47m(:WRITE-FOR-READ NIL)[0m in [47m:fmt-control-alist[0m, then the [47mfm<..>-to-string[0m functions will be free to insert such backslashes; but that pair will have no effect on the [47mfm<..>!-to-string[0m functions.") (probe-file (io programming-with-state) "Determine whether a file exists ACL2 does not directly support the Common Lisp function, [47mprobe-file[0m, which indicates whether or not a given file exists. But see [canonical-pathname] and see [file-write-date$] for ways to check in ACL2 whether a file exists.") (profile (events) "Turn on profiling for one function NOTE: An alternative to this utility, which has significantly less functionality but doesn't use [hons-enabled] features of ACL2, may be found in community book [47mbooks/misc/profiling.lisp[0m. See [hons-and-memoization] for a general discussion of [memoization], on which this [47mprofile[0m utility is built, and the related features of hash consing and applicative hash tables. [47mProfile[0m can be useful in Common Lisp debugging and performance analysis, including examining the behavior of ACL2 functions. Example: (profile 'fn) ; keep count of the calls of fn (profile 'fn ; as above, with some memoize options :trace t :forget t) (memsum) ; report statistics on calls of memoized functions (e.g., fn) (clear-memoize-statistics) ; clear memoization (and profiling) statistics Evaluation of [47m(profile 'fn)[0m redefines [47mfn[0m so that a count will be kept of the calls of FN. The information recorded may be displayed, for example, by invoking [47m([0m[47m[memoize-summary][0m[47m)[0m or (equivalently) [47m(memsum)[0m. If you wish to gather fresh statistics for the evaluation of a top-level form, see [clear-memoize-statistics]. [47mProfile[0m is just a macro that calls [47m[memoize][0m to do its work. [47mProfile[0m gives the two keyword parameters [47m:condition[0m and [47m:recursive[0m of [47m[memoize][0m the value [47mnil[0m. Other keyword parameters for [47mmemoize[0m, which must not include [47m:condition[0m, [47m:condition-fn[0m, or [47m:recursive[0m, are passed through. To eliminate profiling, use [47m[unmemoize][0m; for example, to eliminate profiling for function [47mfn[0m, evaluate [47m(unmemoize 'fn)[0m. Functions [47m[profile-all][0m and [47m[profile-ACL2][0m are available for profiling all functions or all ACL2 functions, respectively.") (prog2$ (progn$ acl2-built-ins) "Execute two forms and return the value of the second one See [hard-error], see [illegal], and see [cw] for examples of functions to call in the first argument of [47mprog2$[0m. Also see [progn$] for an extension of [47mprog2$[0m that handles than two arguments. Semantically, [47m(Prog2$ x y)[0m equals [47my[0m; the value of [47mx[0m is ignored. However, [47mx[0m is first evaluated for side effect. Since the ACL2 [programming] language is applicative, there can be no logical impact of evaluating [47mx[0m. However, [47mx[0m may involve a call of a function such as [47m[hard-error][0m or [47m[illegal][0m, which can cause so-called ``hard errors'', or a call of [47m[cw][0m to perform output. Here is a simple, contrived example using [47m[hard-error][0m. The intention is to check at run-time that the input is appropriate before calling function [47mbar[0m. (defun foo-a (x) (declare (xargs :guard (consp x))) (prog2$ (or (good-car-p (car x)) (hard-error 'foo-a "Bad value for x: ~x0" (list (cons #\0 x)))) (bar x))) The following similar function uses [47m[illegal][0m instead of [47mhard-error[0m. Since [47millegal[0m has a guard of [47mnil[0m, [guard] verification would guarantee that the call of [47millegal[0m below will never be made (at least when guard checking is on; see [set-guard-checking]). (defun foo-b (x) (declare (xargs :guard (and (consp x) (good-car-p (car x))))) (prog2$ (or (good-car-p (car x)) (illegal 'foo-b "Bad value for x: ~x0" (list (cons #\0 x)))) (bar x))) We conclude with a simple example using [47m[cw][0m from the ACL2 sources. (defun print-terms (terms iff-flg wrld evisc-tuple) ; Print untranslations of the given terms with respect to iff-flg, following ; each with a newline. ; We use cw instead of the fmt functions because we want to be able to use this ; function in print-type-alist-segments (used in brkpt1), which does not return ; state. (if (endp terms) terms (prog2$ (cw "~Y01" (untranslate (car terms) iff-flg wrld) evisc-tuple) (print-terms (cdr terms) iff-flg wrld evisc-tuple))))") (progn (events) "Evaluate some [events] Example Form: (progn (defun foo (x) x) (defmacro my-defun (&rest args) (cons 'defun args)) (my-defun bar (x) (foo x))) General form: (progn event1 event2 ... eventk) where [47mk[0m >= 0 and each [47meventi[0m is a legal embedded event form (see [embedded-event-form]). Each event is evaluated, in sequence. If any event fails, the entire [47mprogn[0m call is deemed to have failed, and the logical [world] is rolled back to what it was immediately before the [47mprogn[0m call was evaluated. A utility is provided to assist in debugging failures of such execution; see [redo-flat]. See [set-inhibit-output-lst] for how to control the printing done for each event. By default, each event is printed before it is evaluated and a suitable value is printed after successful completion. (Technical note: successful completion produces a multiple-value return that is an [error-triple] [47m(mv nil val state)[0m; then the value [47mval[0m is printed.) Printing of both the event and its value can both be inhibited by including the symbol, [47mEVENT[0m, in your call of [47mset-inhibit-output-lst[0m. NOTE: If the [47meventi[0m above are not all legal embedded event forms (see [embedded-event-form]), consider using [47m[er-progn][0m or (with great care!) [47m[progn!][0m instead. If your goal is simply to execute a sequence of top-level forms that are not necessarily all legal embedded event forms, consider using [47mld[0m instead; see [ld]. For a related event form that does allow introduction of [constraint]s and [47m[local][0m [events], see [encapsulate]. ACL2 does not allow the use of [47mprogn[0m in definitions. Instead, the macro [47m[er-progn][0m can be used for sequencing [state]-oriented operations; see [er-progn] and see [state]. If you are using single-threaded objects (see [stobj]) you may wish to define a version of [47m[er-progn][0m that cascades the object through successive changes. ACL2's [47m[pprogn][0m is the [47mstate[0m analogue of such a macro. Remark on return value. As with all [events], a call of [47mprogn[0m returns an [error-triple], [47m(mv erp val state)[0m, where [47merp[0m is nil when the event is successfully admitted. In that case, this is the error-triple returned by the final event in the [47mprogn[0m call, or [47m(mv nil nil state)[0m if the form is just [47m(progn)[0m.") (progn! (events) "Evaluate some forms, not necessarily [events] [31;1mWARNING![0m This event is intended for advanced users who, in essence, want to build extensions of ACL2. See see [defttag], in particular, the ``WARNING'' there, and see the warning about [stobj]s at the end of this documentation topic. [47mProgn![0m can be used like [47m[progn][0m, even in [books]. But unlike [47m[progn][0m, [47mprogn![0m does not require its constituent forms to be [events] (see [embedded-event-form]), except that the first form cannot be a symbol unless it is [47m:state-global-bindings[0m (advanced feature, described below). However, see [make-event] for a ``Restriction to the Top Level'' that still applies under a call of [47mprogn![0m. Because [47mprogn![0m allows non-events, it differs from [47mprogn[0m in another important respect: [47mprogn![0m is illegal unless there is an active ttag; see [defttag]. See community book [hacker] for two macros, [with-raw-mode] and [with-redef-allowed], each defined in terms of [47mprogn![0m, that allow arbitrary forms in contexts that would normally require legal embedded event forms. Given a form [47m(progn! form1 form2 ... formk)[0m, ACL2 will evaluate each [47mformi[0m in turn (for i from 1 to k). If a form returns more than one value (see [mv]) where the first value returned is not [47mnil[0m, then no later form will be evaluated and the result returned by the [47mprogn![0m call will be [47m(mv erp val state)[0m for some non-[47mnil[0m value [47merp[0m, signifying an error (see [ld-error-triples]). Otherwise the evaluation is considered to have succeeded, and will continue with later forms. The value returned by a call of [47mprogn![0m with no such error is of the form [47m(mv nil v state)[0m, where [47mv[0m depends on the last form as follows. If the last form evaluates to a single value, then [47mv[0m is that value, except if the value is a [stobj], say [47mST[0m, then [47mv[0m is the symbol [47mREPLACED-ST[0m. Otherwise the last form evaluates to some [47m(mv nil x ...)[0m, and [47mv[0m is [47mx[0m unless after the final form's evaluation we are in raw-mode (see [set-raw-mode]), in which case the [47mprogn![0m call returns [47mnil[0m (so that ACL2 can at least print the result --- imagine Lisp returning a pathname object from a [47mload[0m call, for example). The normal undoing mechanism does not generally apply to forms within a [47mprogn![0m that are not legal ACL2 [events] (see [embedded-event-form]). In particular, note that a non-[47m[local][0m call of [47mprogn![0m in an [47m[encapsulate][0m event will generally be evaluated twice: once on each pass. This fact is worth keeping in mind if you are using [47mprogn![0m to change the state of the system; ask yourself if it is acceptable to apply that state-changing operation more than once. Please note that [47mprogn![0m may differ from [47m[progn][0m in the following sense: definitions within a call of [47mprogn![0m might not be compiled. For example, consider the following book. (in-package "ACL2") (defttag :test) (progn (defun f1 (x) x)) (progn! (defun f2 (x) x)) If the underlying Lisp is GCL 2.6.7, then after including this certified book (where the default certification took place, creating a compiled file), then [47mf1[0m is a compiled function but [47mf2[0m is not. For other Lisps supported by ACL2, both [47mf1[0m and [47mf2[0m are compiled, though we are not sure that every function under every call of [47mprogn![0m would similarly be compiled. We now describe, for system hackers only, a sophisticated extension of [47mprogn![0m not mentioned above: support for keyword argument [47m:state-global-bindings[0m. If the first argument of [47mprogn![0m is this keyword, then the second argument is treated as a list of bindings as expected by ACL2 system function [47m[state-global-let*][0m. Thus, in the ACL2 loop, (progn! :state-global-bindings bindings form1 form2 ... formk) is treated as follows: (progn! (state-global-let* bindings (progn! form1 form2 ... formk))) However, in raw Lisp the former is just: (progn form1 form2 ... formk) Thus, one should use the [47m:state-global-bindings[0m argument with care, since the behavior in the ACL2 loop can differ from that in Common Lisp. The intention is that one bind only [state] global variables that are relevant to evaluation of the forms within the ACL2 loop and are harmlessly ignored for evaluation of those forms in raw Lisp. Here is a typical sort of example, as [state] global [47mld-redefinition-action[0m is not relevant to the evaluation of [47m[defun][0m in raw Lisp. (progn! (remove-untouchable 'ld-redefinition-action nil) (progn! :state-global-bindings ((ld-redefinition-action '(:doit . :overwrite))) (defun foo (x) (cons x x))) (push-untouchable 'ld-redefinition-action nil)) Finally, we point out a pitfall of [47mprogn![0m related to [stobj]s. The following book can cause a hard Lisp error, depending on the host Common Lisp and whether certifying or including it, when certified with a non-[47mnil[0m value for [47mcompile-flg[0m (see [certify-book]). (in-package "ACL2") (defstobj st fld) (defttag :my-ttag) (progn! (update-fld 3 st)) The problem is that the [stobj] variable [47mst[0m is not known to raw Lisp. The compilation problem disappears if the last form above is replaced with the following two forms. (include-book "hacking/hacker" :dir :system) (with-raw-mode (let ((live-st (cdr (assoc-eq 'st *user-stobj-alist*)))) (update-fld 3 live-st)))") (progn$ (basics acl2-built-ins) "Execute a sequence of forms and return the value of the last one This macro expands to a corresponding nest of calls of [47mprog2$[0m; see [prog2$]. The examples below show how this works: the first case below is typical, but we conclude with two special cases. ACL2 !>:trans1 (progn$ (f1 x) (f2 x) (f3 x)) (PROG2$ (F1 X) (PROG2$ (F2 X) (F3 X))) ACL2 !>:trans1 (progn$ (f1 x) (f2 x)) (PROG2$ (F1 X) (F2 X)) ACL2 !>:trans1 (progn$ (f1 x)) (F1 X) ACL2 !>:trans1 (progn$) NIL ACL2 !> Subtopics [Prog2$] Execute two forms and return the value of the second one") (program (defun-mode) "To set the default [defun-mode] to [47m:[0m[47m[program][0m Example: ACL2 !>:program ACL2 p!> Typing the keyword [47m:program[0m sets the default [defun-mode] to [47m:program[0m. Functions defined in [47m:program[0m mode are logically undefined but can be executed on constants outside of deductive contexts. See [defun-mode]. Calls of the following macros are ignored (skipped) when in [47m:program[0m mode. local verify-guards verify-termination defaxiom defthm deftheory in-theory in-arithmetic-theory regenerate-tau-database theory-invariant defchoose Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. See [defun-mode] for a discussion of the [defun-mode]s available and what their effects on the logic are. See [default-defun-mode] for a discussion of how the default [defun-mode] is used. This event is equivalent to [47m(table acl2-defaults-table :defun-mode :program)[0m, and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs. See [ACL2-defaults-table]. Recall that the top-level form [47m:program[0m is equivalent to [47m(program)[0m; see [keyword-commands]. Thus, to change the default [defun-mode] to [47m:program[0m in a book, use [47m(program)[0m, which is an embedded event form, rather than [47m:program[0m, which is not a legal form for [books]. See [embedded-event-form]. See [program-wrapper] for how to use program-mode functions to avoid expensive [guard] checks. Subtopics [Program-wrapper] Avoiding expensive [guard] checks using [program]-mode functions") (program-only (guard) "Functions that cannot be in [logic] mode Functions are considered to be ``program-only'' when they are in [program] mode and they belong to the list [47m(@ program-fns-with-raw-code)[0m. For such a function, its executable-counterpart (see [evaluation]) always checks the guard. If the guard fails, then even if guard-checking is off, an error is signaled because a program-only function is assumed to have an executable-counterpart that should only execute the raw Lisp definition. Moreover, an error is always signaled when in [safe-mode] (e.g., during macroexpansion), because there is no guarantee that evaluation of the raw Lisp code will be ``safe''. The constant [47m*initial-program-fns-with-raw-code*[0m provides the initial value of [47m(@ program-fns-with-raw-code)[0m. The value of that constant is the list of ACL2 source functions that have special raw-Lisp code. It is important that these [program]-mode functions not be converted to [logic] mode. Otherwise, one could arrange to prove a contradiction. To see how, consider the following example, which takes advantage of an unsound use of [47m:[0m[47m[q][0m to prove that a call of a program-only function, [47mp-o[0m, returns two different values on the same input (an obvious contradiction). (defun p-o (x) (declare (xargs :guard t)) (er hard? 'p-o "Attempted logical evaluation of ~x0." (list 'p-0 x))) :q ; exit the ACL2 read-eval-print loop (defun p-o (x) (declare (xargs :guard t)) (atom x)) (lp) ; re-enter the ACL2 read-eval-print loop (defthm p-0-nil-is-nil (equal (p-o nil) nil) :hints (("Goal" :in-theory (disable (:e p-o))))) (defthm p-o-nil-is-t (equal (p-o nil) t)) In the ACL2 source one often finds a definition marked with readtime conditionals, such as the following. (defun p-o (x) (declare (xargs :guard t)) #-acl2-loop-only (atom x) #+acl2-loop-only (er hard? 'p-o "Attempted logical evaluation of ~x0." (list 'p-0 x))) The [47macl2-loop-only[0m annotations arrange that when ACL2 is built, one gets the effect described above, where the [47m#+acl2-loop-only[0m code is used in the definition known to ACL2 and the [47m#-acl2-loop-only[0m code is used in the definition known to raw Lisp. All function symbols with such definitions are in the list mentioned above, that is, the value of the constant [47m*initial-program-fns-with-raw-code*[0m. In summary: The contradiction proved above explains the restriction that [47m[logic][0m-mode functions may not call [program]-mode functions. See [safe-mode-cheat-sheet] for possible workarounds, which however may compromise soundness.") (program-wrapper (program programming advanced-features) "Avoiding expensive [guard] checks using [program]-mode functions Application programs can benefit from avoiding expensive [guard] checks. Imagine that [47mexpensive-guard-fn[0m is a function whose calls may be slow to evaluate, and that [47mexpensive-fn[0m is a function whose guard calls [47mexpensive-guard-fn[0m. So, when you call [47mexpensive-fn[0m at the top level, whether directly in the ACL2 read-eval-print loop or during [47m[make-event][0m expansion, the guard check may be slow. If you are confident that the guard check will pass, you may thus prefer to avoid it. The following contrived example shows how to avoid that guard check by using a [3mprogram-mode wrapper[0m: a function in [program] mode that calls the intended function directly. The example below illustrates that idea by defining [47mexpensive-fn-wrapper[0m as a program-mode wrapper for [47mexpensive-fn[0m. That wrapper has a computationally inexpensive guard, typically [47mt[0m, which avoids any expensive guard check: after the inexpensive guard check, the remaining computation takes place using raw Lisp computation, which doesn't do any guard checking. (See [evaluation] for relevant background.) (defun fib (n) ; Fibonacci function, just for an example of slow computation (declare (xargs :guard (natp n))) (if (zp n) 0 (if (eql n 1) 1 (+ (fib (- n 1)) (fib (- n 2)))))) (defun expensive-guard-fn (n) (declare (xargs :guard t)) (and (natp n) (natp (fib n)))) (defun expensive-fn (n) (declare (xargs :guard (expensive-guard-fn n))) (* 2 n)) ; The following may take about a second, virtually all in the guard check. (time$ (expensive-fn 40)) (defun expensive-fn-wrapper (n) (declare (xargs :mode :program)) (expensive-fn n)) ; The following is virtually instantaneous. (time$ (expensive-fn-wrapper 40)) This trick isn't necessary if your function call is made on behalf of a superior call of a function that is guard-verified (or in program mode, since that essentially brings us back to the wrapper situation). Consider the following definition, building on the example above. (defun f (n) (declare (xargs :guard (natp n))) (expensive-fn n)) ; The following is virtually instantaneous. (time$ (f 40)) Then evaluation of [47m(f 40)[0m is virtually instantaneous, for the same reason that evaluation of [47m(expensive-fn-wrapper 40)[0m is virtually instantaneous: after the top-level guard check passes, the rest of the computation takes place without guard checks. Note however that if we change the definition by removing guard verification, then the trick is once again helpful, as shown by continuing the examples above. ; Define a logic-mode function that is not guard-verified: (defun g (n) (expensive-fn n)) ; The following may take about a second, virtually all in the guard check. (time$ (g 40)) Remark. This trick may be less effective if you see an [47m"Invariant-risk"[0m warning, which prevents computation from taking place within raw Lisp, thus avoiding guard checks; see [invariant-risk].") (programming (acl2) "Programming in ACL2 This [documentation] topic is a parent topic under which we include documentation topics for built-in functions, macros, and special forms, as well as topics for notions important to programming with ACL2. If you don't find what you're looking for, see the Index or see individual topics that may be more directly appropriate; for example, see [events] for top-level event constructors like [47m[defun][0m. A subtopic, [ACL2-built-ins], contains as subtopics (displayed in a flat list) most of the topics in the [documentation] hierarchy that appear under this `programming' topic. If you are unfamiliar with Lisp, we suggest you start by reading [gentle-introduction-to-ACL2-programming]. If you are already familiar with Common Lisp (or even some other Lisp variant), then you may find it helpful to start with the topic, [introduction-to-programming-in-ACL2-for-those-who-know-lisp]. Also see [debugging] for utilities that can aid in programming. Subtopics [ACL2-built-ins] ''Catch-all'' topic for built-in ACL2 functions [Advanced-features] Some advanced features of ACL2 [Alists] Operations on association lists, which bind keys to values. [Apply$] Apply a badged function or tame lambda to arguments [Arrays] ACL2 arrays and operations on them [Basics] Basic control structures for [programming] like [if] and [cond], binding operators like [let] and [flet], multiple-value constructs like [mv], and so forth. [Characters] Characters in ACL2 and operations on them [Compilation] Compiling ACL2 functions [Conses] A [31;1mcons[0m is an ordered pair. In ACL2, data structures like [lists], [alists], etc., are made up of conses. [Declare] Extra declarations that can occur in function definitions, [let] bindings, and so forth. [Defabbrev] A convenient form of macro definition for simple expansions [Defconst] Define a constant [Defmacro] Define a macro [Defmacro-untouchable] Define an ``untouchable'' macro [Defpkg] Define a new symbol package [Defun] Define a function symbol [Efficiency] Efficiency considerations [Equality-variants] Versions of a function using different equality tests [Errors] Support for causing runtime errors, breaks, assertions, etc. [Evaluation] Evaluating ACL2 expressions [Fast-alists] Alists with hidden hash tables for faster execution [Get-internal-time] Runtime vs. realtime in ACL2 timings [Guard] Restricting the domain of a function [Hons] [47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m. [Introduction-to-programming-in-ACL2-for-those-who-know-lisp] Introduction to programming in ACL2 for Lisp users [Invariant-risk] Potential slowdown for [program]-mode updates to [stobj]s or [arrays] [Io] Input/output facilities in ACL2 [Irrelevant-formals] Formals that are used but only insignificantly [Lists] Lists of objects, the classic Lisp data structure. [Loop$] Iteration with an analogue of the Common Lisp [47mloop[0m macro [Loop$-primer] Primer for using [47m[loop$][0m [Mbe] Attach code for execution [Memoize] Turn on memoization for a specified function [Mutual-recursion] Define some mutually recursive functions [Numbers] Numbers in ACL2 and operations on them [Packages] Collections of symbols that act as namespaces. [Primitive] Primitive functions built into ACL2 without definitions [Program-wrapper] Avoiding expensive [guard] checks using [program]-mode functions [Programming-with-state] Programming using the von Neumannesque ACL2 [state] object [Redefining-programs] An explanation of why we restrict redefinitions [Revert-world] Evaluate without (ultimately) changing the [world] [Set-check-invariant-risk] Affect certain [program]-mode updates to [stobj]s or [arrays] [Set-duplicate-keys-action] Control action for macro calls with duplicate keyword arguments [Set-register-invariant-risk] Avoid [invariant-risk] checking for specified functions [Sleep] Sleep for some number of seconds [State] The von Neumannesque ACL2 state object [Stobj] Single-threaded objects or ``von Neumann bottlenecks'' [Strings] Strings are atomic objects that contain character sequences, like [47m"Hello World"[0m. [Symbols] Symbols in ACL2 and operations on them [System-attachments] System-level algorithms that users can modify with attachments [System-utilities] Some built-in programming utilities pertaining to the ACL2 system [Time$] Time the evaluation of a given form [Unmemoize] Turn off memoization for the specified function") (programming-knowledge-taken-for-granted (introduction-to-the-theorem-prover) "Background knowledge in ACL2 programming for theorem prover tutorial This brief review of the programming language is presented as a sequence of questions and answers meant to test your knowledge of the ACL2 programming language. If you want a gentle introduction to the programming language, see [gentle-introduction-to-ACL2-programming]. Before we get started with the programming drill, let us remind you that all we're interested in here is the language, not the ``program development environment.'' It's impossible to program in ACL2 or any other language without a decent environment, one that at the very least includes a way to prepare and edit files of programs. The two most popular program development environments among ACL2 users are [Emacs] {ICON} (see [A_Tiny_Warning_Sign]) and the Eclipse-based [ACL2-Sedan] {ICON} (see [A_Tiny_Warning_Sign]). The Sedan provides the most support for the new user, including real-time syntax checking and a facility for testing among many other features. But in this drill we're not interested in the program development environment, we're interested in your understanding of the ACL2 language. [31;1mQ[0m: What do you think this command does? (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) [31;1mA[0m: It defines a function named [47mrev[0m that takes one argument, treats it like a list, and reverses the order of the elements in that list. To figure this out from the definition, you have to know that [47mappend[0m concatenates two lists. Logically speaking, the [47mdefun[0m of [47mrev[0m adds the axiom: (rev x) = (if (endp x) nil (append (rev (cdr x)) (list (car x)))), implicitly quantified for all [47mx[0m. [31;1mQ[0m: Given the [47mdefun[0m of [47mrev[0m above, what are the [3mformal parameters[0m? What is the [3mbody[0m of the definition? Write down a [3mcall[0m of [3mappend[0m that occurs in the body of [47mrev[0m. What are the [3mactuals[0m of that call? [31;1mA[0m: The [3mformals[0m of [47mrev[0m is the list of variables after the first [47mrev[0m in the [47mdefun[0m, namely [47m(x)[0m. We say [47mx[0m is the first (and only) [3mformal[0m here. The [3mbody[0m of [47mrev[0m is the entire [47mif[0m-expression. The only [3mcall[0m of [47mappend[0m in the body is (append (rev (cdr x)) (list (car x))) and the [3mactuals[0m of that call are, respectively, [47m(rev (cdr x))[0m and [47m(list (car x))[0m. [31;1mQ[0m: What do you get if you evaluate [47m(rev '(a b c d))[0m? [31;1mA[0m: [47m(D C B A)[0m. [31;1mQ[0m: How did [47mrev[0m change the case of the elements, e.g., lowercase [47ma[0m was in the input list but uppercase [47mA[0m was in the output? [31;1mA[0m: This is a trick question. [47mRev[0m doesn't change the case of the elements. ACL2 typically converts to upper case when reading symbols (see [symbols] {ICON} (see [A_Tiny_Warning_Sign]) for details). The symbol [47ma[0m is read in as the symbol [47mA[0m. Thus, when writing function names, for example, we can write [47mrev[0m, [47mRev[0m, [47mREV[0m, or even [47mReV[0m and always be referring to the function [47mREV[0m. By default, ACL2 prints symbols in uppercase. [31;1mQ[0m: What does [47m(rev '((a b c) "Abc" "a" b #\c))[0m return? [31;1mA[0m: [47m(#\c B "a" "Abc" (A B C))[0m. If you thought the answer was either of these, then you need to think or read more carefully: (#\C B "A" "ABC" (A B C)) (#\c B "a" "Abc" (C B A)) The first wrong answer above is wrong because Lisp is ``case insensitive'' only for symbols, not for character objects like [47m#\c[0m (the lowercase character c) or for strings. Furthermore, [47m"A"[0m is a string, not a symbol; it is different from [47mA[0m. The second wrong answer above is wrong because [47mrev[0m does not go into the individual elements of the list, it just reverses the order of the elements. So it doesn't change the element [47m(A B C)[0m to [47m(C B A)[0m. [31;1mQ[0m: In the question about what [47m(rev '(a b c d))[0m returns, we put a quote mark before the [47m(a b c d)[0m but not before the answer, [47m(D C B A)[0m. Why? [31;1mA[0m: The phrase ``[3mx[0m evaluates to [3my[0m'' treats [3mx[0m as a [3mterm[0m to be evaluated and [3my[0m as an [3mobject[0m. [47m(Rev '(a b c d))[0m is a term to be evaluated and denotes a call of the function [47mrev[0m on the value of the argument term [47m'(a b c d)[0m. The value of that argument term is the object [47m(a b c d)[0m. The value of the call of [47mrev[0m is the object [47m(d c b a)[0m. If you have an object, [3mobj[0m, and you wish to create a term whose value is [3mobj[0m, then you put a quote mark in front of it, [3m'obj[0m. [31;1mQ[0m: Can [47mrev[0m be applied to something other than a list? [31;1mA[0m: Yes, every ACL2 function can be applied to any object. ACL2 is an untyped programming language: every variable ranges over the entire universe of objects. In normal usage, [47mrev[0m is applied to lists but there is nothing about the syntax of the language that prevents it being applied to non-lists. [31;1mQ[0m: So what does [47m(rev 23)[0m evaluate to? [31;1mA[0m: [47mNil[0m. [31;1mQ[0m: Why? [31;1mA[0m: Because [47m(endp 23)[0m is [47mt[0m, because [47mendp[0m is defined: (defun endp (x) (not (consp x))) Thus, if [47mrev[0m is applied to anything that is not a cons, it returns [47mnil[0m. [31;1mQ[0m: So what does [47m(rev '(a b c . d))[0m evaluate to? [31;1mA[0m: [47m(c b a)[0m. To explain why requires demonstrating that you know what [47m(a b c . d)[0m means. It is the object computed by evaluating: (cons 'a (cons 'b (cons 'c 'd))). That is, it is a list whose ``terminal marker'' is the atom [47mD[0m. [47mRev[0m treats that list exactly as it treats the [47mnil[0m-terminated list of the same elements, [47m(a b c)[0m, because [47m(endp 'D)[0m = [47m(endp nil)[0m = [47mt[0m. [31;1mQ[0m: What does [47m(rev 1 2 3)[0m evaluate to? [31;1mA[0m: That's a trick question. [47mRev[0m takes one argument, not three. So [47m(rev 1 2 3)[0m is an ill-formed term. [31;1mQ[0m: What does [47m(rev '(a b c . d . nil))[0m evaluate to? [31;1mA[0m: That is a trick question. There is no such object. In Lisp's ``dot notation'' every dot must be followed by a well-formed object and then a close parenthesis. Usually that ``well-formed object'' is an atom. If it is not an atom, i.e., if it is a cons, then the entire expression could have been written without that dot. For example, [47m(a b c . (d e))[0m is an object, but it could be written [47m(a b c d e)[0m. [31;1mQ[0m: Do [47m(rev (rev x))[0m and [47mx[0m always evaluate to the same object? [31;1mA[0m: No. [47m(Rev (rev 23))[0m evaluates to [47mnil[0m, not [47m23[0m. [31;1mQ[0m: Do [47m(rev (rev x))[0m and [47mx[0m always evaluate to the same object when [47mx[0m is a cons? [31;1mA[0m: No. [47m(rev (rev '(a b c . d)))[0m evaluates to [47m(a b c)[0m, not [47m(a b c . d)[0m. [31;1mQ[0m: When are [47m(rev (rev x))[0m and [47mx[0m equal? [31;1mA[0m: When the terminal marker of [47mx[0m is [47mnil[0m. [31;1mQ[0m: Can you define a Lisp function that recognizes [47mnil[0m-terminated lists? [31;1mA[0m: Yes, but it is not necessary for the user to define that concept because Common Lisp provides such a function which is logically defined as follows: (defun true-listp (x) (if (consp x) (true-listp (cdr x)) (equal x nil))). This can be paraphrased: [47m(true-listp x)[0m means that if [47mx[0m is a [47mcons[0m, its [47mcdr[0m is a [47mtrue-listp[0m and if [47mx[0m is not a [47mcons[0m, it must be [47mnil[0m. Thus, [47m(true-listp '(a b c))[0m is [47mt[0m and [47m(true-listp '(a b c . d))[0m is [47mnil[0m. [31;1mQ[0m: Can you write a Lisp formula that says ``If [47mz[0m is a [47mnil[0m-terminated list then reversing the result of reversing [47mz[0m is [47mz[0m''? [31;1mA[0m: Yes: (implies (true-listp z) (equal (rev (rev z)) z)). [31;1mQ[0m: Is this all there is to ACL2 programming? [31;1mA[0m: No! ACL2 provides many other features. For a full list of all the primitive functions in ACL2 see [programming] {ICON} (see [A_Tiny_Warning_Sign]). Some highlights for the beginner are mentioned below, but all of the links below ought to be tagged with the {ICON} (see [A_Tiny_Warning_Sign]) sign. * [47m[list][0m: build a [47mnil[0m-terminated list from the values of [3mn[0m terms, e.g., [47m(list x (+ 1 x) (+ 2 x))[0m returns [47m(3 4 5)[0m if [47mx[0m is [47m3[0m. * [list*]: build a non-[47mnil[0m terminated list of [3mn[0m objects from the values of [3mn+1[0m terms, e.g., [47m(list* x (+ 1 x) (+ 2 x) (* -1 x))[0m returns the list [47m(3 4 5 . -3)[0m if [47mx[0m is [47m3[0m. * [47m[and][0m, [47m[or][0m, [47m[not][0m, [47m[implies][0m, [47m[iff][0m: The propositional connectives. [47mAnd[0m and [47mor[0m are allowed to take a varying number of arguments, e.g., [47m(and p q r)[0m is just an abbreviation for [47m(and p (and q r))[0m. In Lisp, [47mand[0m returns [47mnil[0m if any of its arguments evaluates to [47mnil[0m; otherwise it returns the value of the last argument! Thus, [47m(and t t 3)[0m returns [47m3[0m! If you object to the idea that [47mand[0m is not Boolean, don't give it non-Boolean arguments! Similarly, [47mor[0m returns the value of the first argument that evaluates to non-[47mnil[0m, or [47mnil[0m if they all evaluate to [47mnil[0m. Both [47mand[0m and [47mor[0m can be thought of as ``lazy'' in that they don't always have to evaluate all their arguments. This is really accomplished by treating [47mand[0m and [47mor[0m as abbreviations for [47mif[0m nests. * [47m[+][0m, [47m[*][0m, [47m[-][0m, [47m[/][0m, [47m[floor][0m, [47m[mod][0m, [47m[<][0m, [47m[<=][0m, [47m[>=][0m, [47m[>][0m: the Lisp elementary arithmetic operators. Both [47m+[0m and [47m*[0m allow varying numbers of arguments. All the arithmetic operators default non-numeric arguments to [47m0[0m. If you don't like the idea that [47m(+ 1 2 t)[0m is [47m3[0m, don't ask [47m+[0m to add [47mt[0m to something! * [47m[natp][0m, [47m[integerp][0m, [47m[rationalp][0m, [47m[characterp][0m, [47m[stringp][0m, [47m[symbolp][0m, [47m[consp][0m: the recognizers for the primitive data types. The first three recognize subsets of the ACL2 numeric universe. The naturals are a subset of the integers, the integers are a subset of the rationals, and the rationals are a subset of the objects recognized by [47m[ACL2-numberp][0m, which also includes the [47m[complex-rationalp][0ms. The other recognizers listed above recognize characters, strings, symbols, and conses. * [47m[cond][0m: a convenient way to write a cascading nest of [47mif[0ms, e.g., (cond ((not (natp x)) 'non-natural) ((equal x 0) 'zero) ((evenp x) 'positive-even) (t 'positive-odd)) abbreviates (if (not (natp x)) 'non-natural (if (equal x 0) 'zero (if (evenp x) 'positive-even 'positive-odd))). * [47m[case][0m: a convenient way to case split on the identity of an object. (case key (non-natural -1) (zero 0) ((positive-even positive-odd) 'positive-natural) (otherwise 'unknown)) abbreviates (cond ((eql key 'non-natural) -1) ((eql key 'zero) 0) ((member key '(positive-even positive-odd)) 'positive-natural) (t 'unknown)). * user defined macros: using [47m[defmacro][0m {ICON} (see [A_Tiny_Warning_Sign]) you can introduce your own abbreviations. We recommend you not do this until you're good at list processing since macros are functions that build objects representing terms. * [47m[mutual-recursion][0m: allows you to define mutually-recursive functions. * [47m[mv][0m and [47m[mv-let][0m: allow functions to return ``multiple-values''. In Lisp, such functions return vectors of values, the vectors are represented as lists of values, but the implementations are generally more efficient. For example, [47m(mv x y z)[0m returns a ``vector'' consisting of the values of [47mx[0m, [47my[0m, and [47mz[0m. (mv-let (a b c) (foo x) (bar a b c x)) evaluates [47m(foo x)[0m, treats the result as a vector of three values, binds the variables [47ma[0m, [47mb[0m, and [47mc[0m to those three values, and evaluates and returns [47m(bar a b c x)[0m. ACL2 also provides many other features, such as single-threaded objects which may be ``destructively modified'' (see [stobj] {ICON} (see [A_Tiny_Warning_Sign]), including a very special single-threaded object that records the [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign]) of the ACL2 system), file input and output (see [io] {ICON} (see [A_Tiny_Warning_Sign])), applicative arrays (see [arrays] {ICON} (see [A_Tiny_Warning_Sign])) and property lists (see [getprop] {ICON} (see [A_Tiny_Warning_Sign])) and other facilities necessary for it to be a practical programming language. However, we [31;1mstrongly[0m recommend that as a new user you stay away from these features until you are good at proving theorems about elementary list processing! If this little drill made sense to you, you know enough of the programming language to get started. Use your browser's [31;1mBack Button[0m now to return to [introduction-to-the-theorem-prover]. If you are uncomfortable with ACL2 programming, we recommend that you study [gentle-introduction-to-ACL2-programming] and {http://www.cs.utexas.edu/users/moore/publications/acl2-programming-exercises1.html | http://www.cs.utexas.edu/users/moore/publications/acl2-programming-exercises1.html}. However, we strongly recommend that you first invest in learning either the [Emacs] or Eclipse-based [ACL2-Sedan] program development environments, since it is foolish to try to learn how to program in a stand-alone read-eval-print loop! While getting started, many users find the Hyper-Card a handy index into the documentation for the ACL2 language: {http://www.cs.utexas.edu/users/moore/publications/hyper-card.html | http://www.cs.utexas.edu/users/moore/publications/hyper-card.html} Once you are comfortable with the ACL2 programming language, use your browser's [31;1mBack Button[0m to return to [introduction-to-the-theorem-prover].") (programming-with-state (state programming) "Programming using the von Neumannesque ACL2 [state] object This [documentation] section introduces some common techniques for programming using the ACL2 state object. A prerequisite is thus a basic understanding of that object; see [state]. We hope this section is useful, and we invite suggestions for improvements and additions. A supplement to this section is the ACL2 source code, which uses most (and probably all) of the techniques discussed here. That code is thus a source of many examples, which can serve as ``templates'' to guide one's own programming with state. Recall that ``ACL2'' stands for ``A Computational Logic for Applicative Common Lisp''. In particular, the language is applicative: there are no global variables or side effects. For many purposes this does not feel restrictive; for example, an ACL2 user who is programming in raw Lisp may well be more comfortable coding a factorial function applicatively, using recursion, rather than using iteration with repeated assignment to the same variable. However, there are situations that call for reading or modifying the system state, such as performing input and output, signaling errors, saving information from one computation for use in a later one, or reading and updating system-level or environmental data. This section provides an introductory guide for writing functions that traffic in state. We emphasize that this guide is intended as an introduction; more complete documentation may often be found by following links to documentation of individual utilities, and again, more examples may be found by searching the ACL2 source code for uses of the functions and macros mentioned below. The rest of this section is organized as follows. ENABLING PROGRAMMING WITH STATE STATE GLOBALS AND THE ACL2 LOGICAL WORLD A REMARK ON GUARDS ERRORS AND ERROR TRIPLES SEQUENTIAL PROGRAMMING BINDING VARIABLES USING ERROR TRIPLES BINDING STATE GLOBAL VARIABLES INPUT AND OUTPUT TIMINGS ENVIRONMENT AND SYSTEM REMARKS ON EVENTS AND LD ADVANCED TOPICS ENABLING PROGRAMMING WITH STATE In order to submit a definition that takes [47m[state][0m as a formal parameter, you must either declare [47mstate[0m as a [47m:[0m[47m[stobj][0m (see [xargs]) or first evaluate the following form at the top level: [47m(set-state-ok t)[0m. Consider for example the following trivial definition. (defun foo (state) (mv 3 state)) If you submit the above definition in a fresh ACL2 session, you will get this error message. ACL2 Error in ( DEFUN FOO ...): The variable symbol STATE should not be used as a formal parameter of a defined function unless you are aware of its unusual status and the restrictions enforced on its use. See :DOC set-state-ok. If first you evaluate [47m(set-state-ok t)[0m, you can admit the above definition. Alternatively, you can declare [47mstate[0m as a [47m:[0m[47m[stobj][0m, as follows. (defun foo (state) (declare (xargs :stobjs state)) (mv 3 state)) A difference in the two approaches is that for the latter, a [guard] proof obligation is generated by default. See the section below entitled ``A remark on guards''. STATE GLOBALS AND THE ACL2 LOGICAL WORLD Recall (see [state]) that one of the fields of the ACL2 state object is the global-table, which logically is an alist associating symbols, known as ``state globals'' or ``state global variables'', with values. But no such alist actually exists in the implementation. Instead, ACL2 provides utilities for reading state globals --- see [@] and see [f-get-global] --- and utilities for writing them --- see [assign] and see [f-put-global]. The following log shows how they work; further explanation follows below. ACL2 !>(assign my-var (+ 3 4)) 7 ACL2 !>(@ my-var) 7 ACL2 !>(f-put-global 'my-var (+ 1 5) state) <state> ACL2 !>(f-get-global 'my-var state) 6 ACL2 !> Note that the first result is indented by one space. This is ACL2's way to indicate that the [47m[assign][0m expression returned an ``error triple'' and that no error was signaled. We discuss error triples in more detail below; also see [error-triple]. As illustrated above, the output signatures of the utilities for assigning to state globals differ from each other as follows: [47m[f-put-global][0m returns [47mstate[0m, but [47m[assign][0m returns an error triple [47m(mv nil val state)[0m where [47mval[0m is the value assigned to the state global. The output signatures of the utilities for reading, [47m@[0m and [47mf-get-global[0m, are identical. In fact, the form [47m(f-get-global 'my-var state)[0m is the single-step macroexpansion of the form [47m(@ my-var)[0m, as can be confirmed using [47m[trans1][0m. ACL2 !>:trans1 (@ my-var) (F-GET-GLOBAL 'MY-VAR STATE) ACL2 !> State globals are useful for conveying persistent state information. Consider for example the utility [47m[set-inhibit-output-lst][0m. The form [47m(set-inhibit-output-lst '(prove proof-tree))[0m is approximately equivalent to (assign inhibit-output-lst '(prove proof-tree)). We say ``approximately'' because [47mset-inhibit-output-lst[0m additionally does some error checking to ensure that all the tokens in the new list are legal. When deciding whether to print output, the ACL2 system reads the value of state global variable [47minhibit-output-lst[0m. A particularly useful state global is [47mcurrent-acl2-world[0m, whose value is the ACL2 logical [world]. Because the ACL2 world is commonly accessed in applications that use the ACL2 state, ACL2 provides a function that returns the world: [47m(w state) = (f-get-global 'current-acl2-world state)[0m. While it is common to read the world, only functions [47mset-w[0m and [47mset-w![0m are available to write the world, but these are untouchable and should generally be avoided except by system implementors (see [remove-untouchable]). You may wish to modify state globals within a book, but this can be slightly problematic because only legal event forms (see [embedded-event-form]) may go into [books]. Fortunately there is a workaround using [47mmake-event[0m; see [make-event], in particular the section ``Examples Illustrating How to Access State''. A REMARK ON GUARDS For a function definition (see [defun]), if [47mstate[0m is specified as a [stobj] as with the form [47m(declare (xargs :stobjs state))[0m, then the [guard] for that function is considered to include the condition [47m(state-p state)[0m. By default, [guard] verification will then be performed. (Note for advanced system hackers: There is also a stronger predicate, [47m(state-p+ state)[0m, which for example implies the guards for [47mfmt[0m and related functions. We can illustrate this point by modifying the example above as follows, to read the value of state global [47mgag-mode[0m. (defun foo (state) (declare (xargs :stobjs state)) (f-get-global 'gag-mode state)) If you try this in a fresh ACL2 session, the proof will fail with the following key checkpoint, which says that the state global [47mgag-mode[0m is bound in the global-table of the state. (IMPLIES (STATE-P1 STATE) (ASSOC-EQUAL 'GAG-MODE (NTH 2 STATE))) How can we deal with this proof failure? One way is simply to ignore the issue by defining the function in [47m:[0m[47m[program][0m mode, as follows. (defun foo (state) (declare (xargs :stobjs state :mode :program)) (f-get-global 'gag-mode state)) Perhaps a better way is to strengthen the guard to assert that the indicated state global is bound, as follows. (defun foo (state) (declare (xargs :guard (boundp-global 'gag-mode state) :stobjs state)) (f-get-global 'gag-mode state)) Also see [guard-miscellany] for discussion of guard generation from [47m[xargs][0m fields of [declare] forms, specifically, for keywords [47m:guard[0m, [47m:stobjs[0m, and [47m:dfs[0m. ERRORS AND ERROR TRIPLES When evaluation returns three values, where the first two are ordinary objects and the third is the ACL2 state, the result may be called an ``error triple''. (Whether it is treated as an error triple depends on the programmer.) Error triples are often denoted [47m(mv erp val state)[0m, and common ACL2 programming idioms treat [47merp[0m as a flag indicating whether an error is being signaled and [47mval[0m as the ``value'' computed. Also see [error-triple]. Even ACL2 users who are not programmers encounter error triples, because these are the values returned by evaluation of ACL2 [events]. Consider the following log, where the only user input is the [47mdefun[0m form following the [prompt]. ACL2 !>(defun foo (x) x) Since FOO is non-recursive, its admission is trivial. We observe that the type of FOO is described by the theorem (EQUAL (FOO X) X). Summary Form: ( DEFUN FOO ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !> All output above results from explicit calls of output functions, except for the next-to-last line, which contains [47mFOO[0m. Notice the single-space indentation preceding [47mFOO[0m. That space indicates that in fact, the value returned by evaluation of the [47mdefun[0m form is the error triple whose error flag is [47mnil[0m and whose computed value is [47mFOO[0m. By default, ACL2 prints any error triple [47m(mv nil val state)[0m by inserting a space before printing [47mval[0m. You can change the default by setting state global [47m[ld-post-eval-print][0m to [47mt[0m; notice how the same result is printed below. ACL2 !>:u 0:x(EXIT-BOOT-STRAP-MODE) ACL2 !>(set-ld-post-eval-print t state) (NIL T <state>) ACL2 !>(defun foo (x) x) Since FOO is non-recursive, its admission is trivial. We observe that the type of FOO is described by the theorem (EQUAL (FOO X) X). Summary Form: ( DEFUN FOO ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) (NIL FOO <state>) ACL2 !> The way error triples are printed by [47mld[0m is controlled not only by state global [47mld-post-eval-print[0m, but also by state global [47mld-error-triples[0m. These are examples of ``ld specials''; see [ld], see [ld-post-eval-print], and see [ld-error-triples]. It is so common to produce an error triple whose first (error flag) component is [47mnil[0m that ACL2 provides a handy macro, [47mvalue[0m, for this purpose. Thus, [47m(value <expression>)[0m is equivalent to [47m(mv nil <expression> state)[0m. Also see [value-triple] for a similar construct that is a legal event form. We turn now to the topic of errors. The macro [47m[er][0m ``causes'' an error, but there are really two quite different kinds of errors: ``soft'' and ``hard'' errors. We use the term ``soft error'' to refer to a form that returns an error triple [47m(mv erp val state)[0m for which [47merp[0m is non-[47mnil[0m. Soft errors do not interrupt the normal flow of evaluation: the error triple is returned to the caller which interprets the [47merp[0m flag and [47mval[0m as directed by the programmer. Macros discussed below make it convenient to think about soft errors as short-circuiting the computation. Hard errors, on the other hand, do actually rip control away from the current evaluation and return it to the top-level loop. Logically speaking, expressions that cause hard errors return [47mnil[0m in the error case, but the [47mnil[0m is never seen in actual evaluation because control does not return to the caller. Note that the function [47m[abort!][0m, which you can invoke by typing [47m:[0m[47m[a!][0m, always returns to the top level. Note that ACL2 can prove that [47m(abort!)[0m returns [47mnil[0m but that this cannot be confirmed by computation. ACL2 !>(thm (equal (abort!) nil)) Q.E.D. Summary Form: ( THM ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL) (:TYPE-PRESCRIPTION ABORT!)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Proof succeeded. ACL2 !>(equal (abort!) nil) Abort to ACL2 top-level ... ACL2 !> (What actually happens with a hard error, including non-default cases, is a bit subtle; most readers will probably want to skip this paragraph. The read-eval-print loop implemented by [47m[ld][0m is implemented by a call of the ACL2 evaluator function, [47mtrans-eval[0m, on each input form. If a hard error occurs during evaluation of an input form, its [47mtrans-eval[0m call will return with a soft error. [47m[Ld][0m, in turn handles that soft error appropriately; see [ld-error-action].) The most common way to signal errors is the macro [47m[er][0m, which prints a formatted error message and returns a soft or hard error as specified by the call. Note however that soft errors are signaled using [47m:[0m[47m[program][0m mode functions. Since the output signatures of soft and hard errors are different --- hard errors ``return'' a single value while soft errors return a triple --- mixing them in an expression requires embedding the hard error form in (an irrelevant) triple, as illustrated below. All branches of the expression must produce an error triple if any branch does. ACL2 !>(defun chk-find-or-abort (e x state) (declare (xargs :mode :program)) (if (endp x) (value ; Note use of VALUE! (er hard 'chk-find-or-abort "Did not find ~x0!" e)) (if (not (integerp (car x))) (er soft 'chk-find-or-abort "Non-integer, ~x0, in list!" (car x)) (if (eql (car x) e) (value x) (chk-find-or-abort e (cdr x) state))))) Summary Form: ( DEFUN CHK-FIND-OR-ABORT ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) CHK-FIND-OR-ABORT ACL2 !>(chk-find-or-abort 3 '(1 2 3 4 5) state) (3 4 5) ACL2 !>(chk-find-or-abort 3 '(1 A 3 4 5) state) ACL2 Error in CHK-FIND-OR-ABORT: Non-integer, A, in list! ACL2 !>(chk-find-or-abort 3 '(1 2 4 5) state) HARD ACL2 ERROR in CHK-FIND-OR-ABORT: Did not find 3! ... ACL2 !> See [er] for further discussion of errors. For some other individual topics related to errors see [assert$], see [break-on-error], see [error1], see [hard-error], see [illegal], and see [ld-error-triples]. In the next section we discuss soft errors further, in the context of programming. SEQUENTIAL PROGRAMMING This section describes handy ways to modify state in steps, using macros that implement a sequence of [47m[let][0m or [47m[mv-let][0m bindings. For example, suppose you want to assign the values 1 and 2 to two state globals [47mone-var[0m and [47mtwo-var[0m, respectively. Because of ACL2's syntactic restrictions on [47m[state][0m, it is not legal simply to write [47m(f-put-global 'two-var 2 (f-put-global 'one-var 1 state))[0m. However, [47m[let][0m comes to the rescue as follows. (let ((state (f-put-global 'one-var 1 state))) (let ((state (f-put-global 'two-var 2 state))) state)) It is so common to bind state successively in such a manner that ACL2 provides a macro, [47m[pprogn][0m, for this purpose. Thus, an equivalent solution to the problem above is (pprogn (f-put-global 'one-var 1 state) (f-put-global 'two-var 2 state) state) or, more simply, as follows. (pprogn (f-put-global 'one-var 1 state) (f-put-global 'two-var 2 state)) See [pprogn]. Note that the last form is allowed to return multiple values; the only requirement on the last form is that its value include [47mstate[0m. It is also common to update the state using a sequence of forms such that each returns an error triple, where the intention is for evaluation to short-circuit immediately if a soft error is encountered. Suppose [47m<expr1>[0m and [47m<expr2>[0m are expressions that return error triples, where the [47mstate[0m components of the error triples might be updated, and one wishes to evaluate [47m<expr1>[0m and then [47m<expr2>[0m, returning the (multiple) values returned by [47m<expr2>[0m unless the error triple returned by [47m<expr1>[0m is a soft error, in which case that error triple is returned. One can of course do so as follows. (mv-let (erp val state) <expr1> (cond (erp (mv erp val state)) (t <expr2>))) But ACL2 provides a handy macro, [47m[er-progn][0m, for this purpose. The following code is equivalent to the code just above. (er-progn <expr1> <expr2>) See [er-progn] for more details. Note that unlike [47m[pprogn][0m, the return [signature] for the last expression must be the same as that of the others: an error triple. Let's consider how to use [47mpprogn[0m and [47mer-progn[0m together. In the following example [47mf1[0m and [47mf2[0m both return [47mstate[0m, while each of [47mg1[0m and [47mg2[0m returns an error triple. The following code modifies state by executing these in the order [47mf1[0m, [47mg1[0m, [47mf2[0m, and finally [47mg2[0m, returning [47m(mv nil val state)[0m where [47mval[0m is the value component of the error triple returned by [47mg2[0m --- except we return a soft error if [47mg1[0m or [47mg2[0m returns a soft error. (pprogn (f1 x state) (er-progn (g1 x state) (pprogn (f2 x state) (g2 x state)))) Finally, consider the [events] [47m[progn][0m and [47m[progn!][0m. These have similar behavior to that of [47m[er-progn][0m. However, [47m[progn][0m and [47m[progn!][0m may only be used in event contexts, for example at the top level or immediately underneath a call of [47m[encapsulate][0m or [47m[progn][0m, while [47m[er-progn][0m has no such restriction. So when writing code, use [47mer-progn[0m rather than [47m[progn][0m or [47m[progn!][0m. In particular, the body of a [47m[defun][0m must not have any calls of [47mprogn[0m (or of [47mprogn![0m either), and the same restriction holds for any code to be executed, such as the body of a [47m[make-event][0m form. BINDING VARIABLES USING ERROR TRIPLES In this section we discuss the macro [47mer-let*[0m, which is a variant of the special form, [47m[let*][0m, that is useful when programming with state. A related utility that avoids the use of state is [47mer-let*-cmp[0m; see [context-message-pair]. The macro [47mer-let*[0m is useful when binding variables to the value components of error triples. It is actually quite similar to [47mer-progn[0m, described above, except that [47mer-let*[0m binds variables. First consider the following example. (er-let* ((x1 (f1 state)) (x2 (f2 x1 state))) (value (cons x1 x2))) The code just above is essentially equivalent to writing the following. (mv-let (erp x1 state) (f1 state) (cond (erp (mv erp x1 state)) (t (mv-let (erp x2 state) (f2 x1 state) (cond (erp (mv erp x2 state)) (t (value (cons x1 x2)))))))) As suggested by the example above, [47mer-let*[0m has the same syntax as [47mlet*[0m, except that declarations are not supported. (But note that [47mignore[0m declarations are not needed; all variables that are bound are also used, at least in the error case. Consider replacing [47m(cons x1 x2)[0m by [47mnil[0m in the example displayed immediately above, and note that [47mx1[0m and [47mx2[0m are still used.) However, unlike [47mlet*[0m, [47mer-let*[0m requires that for each binding [47m(var expr)[0m, the expression [47mexpr[0m must evaluate to an error triple and, moreover, it requires that the second argument (the ``body'') of [47mer-let*[0m must evaluate to an error triple. If one of the variable expressions (e.g., the [47mf1[0m and [47mf2[0m calls above) signals an error, its error triple is returned as the value of the [47mer-let*[0m. Of course, soft errors can be ``caught'' by using [47m[mv-let][0m instead of [47mer-let*[0m and simply ignoring the error flag or, more generally, by returning a non-erroneous error triple even if the error flag was on. BINDING STATE GLOBAL VARIABLES In this section we introduce a utility, [47m[state-global-let*][0m, that is an analogue of [47mlet*[0m for state global variables. Consider the following example. (state-global-let* ((inhibit-output-lst (add-to-set-eq 'summary (@ inhibit-output-lst)))) (thm (equal x x))) This form binds state global variable [47minhibit-output-lst[0m to the result of adding the symbol, [47msummary[0m, to the current value of that state global. Thus (see [set-inhibit-output-lst]), the usual [summary] is not printed when evaluating this call of [47m[thm][0m. See [state-global-let*] for more complete [documentation]. INPUT AND OUTPUT In ACL2, most input and output involves the ACL2 state. See [io]. TIMINGS For how to obtain the time elapsed since the start of the ACL2 session, see [read-run-time]. For a utility for saving times into the ACL2 state and for printing those saved times, see the community book [47mmisc/save-time.lisp[0m. To time an evaluation (though this really isn't about state), see [time$]. ENVIRONMENT AND SYSTEM Next, we mention briefly some ways in which ACL2 interacts with its environment using the ACL2 state. For how to read and write environment variables, see [getenv$] and see [setenv$]. For how to run a command in the host operating system, see [sys-call], [sys-call+], and [sys-call*]. REMARKS ON EVENTS AND LD In general, undefined or surprising behavior may occur when using ACL2 [events] or calling [ld] in your programs. In some cases ACL2 enforces restrictions against these uses. We strongly discourage using [47m[ld][0m in programs, as it has been designed to be called only at the top level of a read-eval-print loop. However, you may wish to read or write [47m[ld][0m specials in your programs; see [ld]. There is also a restriction on contexts in which [47m[make-event][0m may be called: it may only be called in a context where an event is expected, such as the top level, in a book, or as an argument of [47m[encapsulate][0m or [47m[progn][0m. The reason is that ACL2 does very subtle and careful tracking of [47m[make-event][0m expansions; and it is only able to do this in event contexts, where it is able to carry out such tracking accurately. ADVANCED TOPICS ACL2 provides the function [47mtrans-eval[0m to evaluate an arbitrary form (after translating it to a [term], i.e., into internal form). For more information, we refer to reader to comments in the definition of [47mtrans-eval[0m in the ACL2 source code. There are also many examples of its use in the ACL2 sources. For a function that provides the true absolute filename, with soft links resolved, see [canonical-pathname]. For a function that returns a checksum on the characters in a channel, see [checksum]. To obtain a random number, see [random$]. If you are programming in raw-mode (see [set-raw-mode]) or in raw Lisp, use the variable [47m*the-live-state*[0m in place of the variable [47mstate[0m. We invite suggestions for additional advanced topics. Subtopics [@] Get the value of a global variable in [47m[state][0m [Assign] Assign to a global variable in [47m[state][0m [Canonical-pathname] The true absolute filename, with soft links resolved [Cbd] Connected book directory string [Er-progn] Perform a sequence of state-changing ``error triples'' [Error-triple] A common ACL2 programming idiom [F-boundp-global] Check whether a global variable in [47m[state][0m has a value [F-get-global] Get the value of a global variable in [47m[state][0m [F-put-global] Assign to a global variable in [47m[state][0m [Get-cpu-time] Read elapsed cpu time [Get-real-time] Read elapsed real time [Getenv$] Read an environment variable [Last-prover-steps] The number of prover steps most recently taken [Makunbound-global] Remove the value assigned to a global variable in [47m[state][0m [Pprogn] Evaluate a sequence of forms that return [state] [Probe-file] Determine whether a file exists [Read-ACL2-oracle] Pop the oracle field of the state [Read-run-time] Read elapsed runtime [Setenv$] Set an environment variable [State-global-let*] Bind [state] global variables [With-live-state] Allow a reference to [47mstate[0m in raw Lisp") (programp (pointers) "See [system-utilities].") (prohibition-of-loop$-and-lambda$ (defconst defmacro defpkg) "Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms Certain events, including [47m[defconst][0m, [47m[defmacro][0m, and [47m[defpkg][0m, prohibit the use of [47m[loop$][0m and [47m[lambda$][0m. The prohibition of [47mloop$[0ms is due to their use of [47mlambda$[0ms, so we focus on why [47mlambda$[0ms are prohibited here. [47mLambda$[0m is prohibited in these events because of the way [books] are loaded. To speed up the execution of [47minclude-book[0m the compiled file for a book is loaded before the events in the book are processed. But the evaluation of [47mlambda$[0m expressions in raw Lisp depends on the [47mlambda$[0ms having been translated and recorded in the logical world and in the lambda cache (see [47m[print-cl-cache][0m). So the execution of these events can't depend on [47mlambda$[0m. If you have submitted an event that provoked an error citing this topic you must restate the event to avoid those prohibited constructions. [3mUnfortunately, you must also consider ancestral occurrences of the prohibited constructions![0m We first give two examples of the problem to drive home the message and then we discuss various ways the problem can be dealt with. Examples of Prohibited Forms ACL2 !>(defconst *2^10* (apply$ (lambda$ (x) (expt 2 x)) '(10))) ACL2 Error in ( DEFCONST *2^10* ...): We prohibit certain events, including DEFCONST, DEFPKG, and DEFMACRO, from being ancestrally dependent on loop$ and lambda$ expressions. But at least one of these prohibited expressions occurs in this event. See :DOC prohibition-of-loop$-and- lambda$. We will discuss how to avoid such errors in the next section. Here is an example of an ancestral use of [47mlambda$[0m in a macro. Suppose we wish to define the macro [47mrat[0m so that [47m(rat "123.4567")[0m expands to the rational [47m1234567/10000[0m. Our idea is to use [47mloop$[0m in the definition of the function [47mstring-to-rat[0m and then to call [47mstring-to-rat[0m in our macro. (We don't recommend this particular use of [47mloop$[0ms to parse a string into a rational but we use it here to make a point later.) (defun string-to-rat (str) (let* ((lst (coerce str 'list)) (right-of-pt (length (cdr (loop$ for d in lst as tail on lst thereis (if (eql #. d) tail nil)))))) (loop$ for tail on lst when (not (eql (car tail) #.)) sum (* (- (char-code (car tail)) 48) (expt 10 (- (loop$ for d in tail sum (if (eql d #.) 0 1)) (+ 1 right-of-pt))))))) (defmacro rat (str) (string-to-rat str)) The attempt to define the macro will provoke the error shown above for [47m(defconst *2^10* ...)[0m. Avoiding These Errors The only way to avoid these errors is to not use [47mlambda$[0m or [47mloop$[0m in these events! We can fix the particular [47mdefconst[0m example above simply with (defconst *2^10* (apply$ 'expt '(2 10))) or, better yet, by (defconst *2^10* (expt 2 10)) since there is reason [47mapply$[0m is involved at all. When it is hard to avoid the prohibited constructs you might be able to use [47mmake-event[0m to do the necessary computation during the creation of the event, though this technique seems mainly applicable to [47mdefconst[0m and much less useful to the [47mdefmacro[0m case. (make-event `(defconst *2^10* ',(apply$ (lambda$ (x) (expt 2 x)) '(10)))) However, in general, removing all uses of [47mloop$[0m and [47mlambda$[0m can require a lot of re-coding. For example, fixing the [47mrat[0m macro requires several old-fashioned recursive definitions to carry out the iterations done with [47mloop$[0m. (defun old-fashioned-string-to-rat1 (lst power) (cond ((endp lst) 0) ((eql (car lst) #.) (old-fashioned-string-to-rat1 (cdr lst) power)) (t (+ (* (- (char-code (car lst)) 48) (expt 10 power)) (old-fashioned-string-to-rat1 (cdr lst) (- power 1)))))) (defun left-of-pt (lst) (cond ((endp lst) 0) ((eql (car lst) #.) 0) (t (+ 1 (left-of-pt (cdr lst)))))) (defun old-fashioned-string-to-rat (str) (let ((lst (coerce str 'list))) (old-fashioned-string-to-rat1 lst (- (left-of-pt lst) 1)))) (defmacro rat (str) (old-fashioned-string-to-rat str)) Another way to eliminate [47mloop$[0m and [47mlambda$[0m is to replace the offending expressions with their translations. There is no prohibition of fully-translated quoted [47m[lambda][0m objects, just of [47mlambda$[0m expressions. (defun string-to-rat (str) ((LAMBDA (LST) ((LAMBDA (RIGHT-OF-PT LST) (SUM$+ '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) (DECLARE (IGNORABLE LOOP$-GVARS LOOP$-IVARS)) ((LAMBDA (RIGHT-OF-PT TAIL) (BINARY-* (BINARY-+ '-48 (CHAR-CODE (CAR TAIL))) (EXPT '10 (BINARY-+ (SUM$ '(LAMBDA (LOOP$-IVAR) (DECLARE (IGNORABLE LOOP$-IVAR)) ((LAMBDA (D) (IF (EQL D '#.) '0 '1)) LOOP$-IVAR)) TAIL) (UNARY-- (BINARY-+ '1 RIGHT-OF-PT)))))) (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) (CONS RIGHT-OF-PT 'NIL) (WHEN$+ '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) (DECLARE (IGNORABLE LOOP$-GVARS LOOP$-IVARS)) ((LAMBDA (TAIL) (NOT (EQL (CAR TAIL) '#.))) (CAR LOOP$-IVARS))) 'NIL (LOOP$-AS (CONS (TAILS LST) 'NIL))))) (LENGTH (CDR (THEREIS$+ '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) (DECLARE (IGNORABLE LOOP$-GVARS LOOP$-IVARS)) ((LAMBDA (D TAIL) (IF (EQL '#. D) TAIL 'NIL)) (CAR LOOP$-IVARS) (CAR (CDR LOOP$-IVARS)))) 'NIL (LOOP$-AS (CONS LST (CONS (TAILS LST) 'NIL)))))) LST)) (COERCE STR 'LIST))) If we define [47mstring-to-rat[0m as above then we can define the [47mrat[0m macro as originally desired and the [47mdefmacro[0m is accepted. But there are several arguments against this approach in general: * [47mDefconst[0m, [47mdefmacro[0m and [47mdefpkg[0m not only prohibit [47mloop$[0m and [47mlambda$[0m but also prohibit all uses of [47mapply$[0m and scions if user-defined functions are involved in the function objects. This is because to compute logically with them one must have [warrant] hypotheses and there is no provision for supplying warrants with these events. See [ignored-attachment]. It turns out that the hideous example above does not mention any user-defined functions in the function objects, so this restriction doesn't stop us here. * Eliminating [47mloop$[0m in favor of scions sacrifices execution speed if the [47mloop$[0ms are guard verified. A guard-verified [47mloop$[0m executes in raw Lisp as a Common Lisp [47mloop[0m, whereas its translation into nested calls of [47mloop$[0m scions, even if guard verified, involves far more function calls. * It is much harder to ``maintain'' code derived this way! There may be cases where no user-defined functions are involved, efficiency doesn't matter, and the [47mloop$[0m scion translation of a [47mloop$[0m is as perspicuous as the [47mloop$[0m itself. So don't dismiss this approach out of hand.") (project-dir-alist (books events) "Support for moving project directories (also [47m:dir[0m arguments) This topic describes the [47mproject-dir-alist[0m, which supports the relocation of book directories so that their [books] are still treated as certified. Each such directory is treated as a [3mproject[0m, which is represented by a [keyword]. In particular, the keyword, [47m:SYSTEM[0m, represents the [community-books] as such a project. The [47mproject-dir-alist[0m also provides one way to interpret the [47m:dir[0m keyword argument of [47m[include-book][0m and [47m[ld][0m. It is theoretically possible to undermine soundness by using this capability inappropriately (see below for some discussion of appropriate usage). For the utmost security, perform a fresh certification of your entire collection of books without using this capability. See [certificate], specifically the discussion there about placing a ``burden'' on the user. To see the [47mproject-dir-alist[0m in your session, evaluate the form [47m(project-dir-alist (w state))[0m. We start below by introducing the [47mproject-dir-alist[0m and explaining how to set it up. Next we describe its effects. We conclude by discussing some details, limitations, and restrictions. What is the [47mproject-dir-alist[0m and how is it established? The [47mproject-dir-alist[0m is an association list that maps keywords to directory names. If we map keyword [47m:K[0m to directory [47m"<dir>"[0m, we say that the project name [47mK[0m is associated with project directory [47m"<dir>"[0m. The way to establish the [47mproject-dir-alist[0m is to set environment variable [47mACL2_PROJECTS[0m to the name of a file, which we will call the ``projects file''. The projects file may have lines of the following form, where we write [47m:K[0m to denote an arbitrary keyword and [47m"<dir>"[0m to denote a directory name inside double-quotes. :K "<dir>" Such a line associates the project name [47mK[0m with the project directory [47m"dir"[0m. Each remaining line in a projects file should either be blank (i.e., contain only whitespace) or else be a comment line, that is, a line for which the first non-whitespace character is a semicolon ([47m;[0m). The projects file is read when ACL2 starts up. ACL2 creates the [47mproject-dir-alist[0m by using each line as above to associate the keyword [47m:K[0m with the directory represented by [47m"<dir>"[0m, which may be a relative or absolute pathname. Relative pathnames are interpreted with respect to the directory of the projects file. If the keyword [47m:SYSTEM[0m is not specified in the projects file, then the [47mproject-dir-alist[0m will additionally include a pair that associates [47m:SYSTEM[0m with the [community-books] directory, which is generally the [47mbooks/[0m subdirectory of your ACL2 distribution. That value for [47m:SYSTEM[0m can be overridden either by specifying it explicitly with [47m:SYSTEM[0m in the projects file or by setting environment variable [47mACL2_SYSTEM_BOOKS[0m to that value --- where if both overrides are used, they must not conflict. The values of the environment variables mentioned above, [47mACL2_PROJECTS[0m and [47mACL2_SYSTEM_BOOKS[0m, are pathnames that can be either relative or absolute. A relative pathname is interpreted with respect to the directory in which ACL2 is invoked. The final character need not be ``[47m/[0m''; if it's not, then that character will be added at the end before adding to the [47mproject-dir-alist[0m. The [47mproject-dir-alist[0m must have no duplicate keys and no duplicate directory names. Effects of the [47mproject-dir-alist[0m There are the following two effects of the association of a keyword [47m:K[0m with a directory [47m"<dir>"[0m in the [47mproject-dir-alist[0m. [31;1m(1) [47m:K[0m[31;1m specifies a project directory that may be moved.[0m Consider first the default case, where there is a single association in the [47mproject-dir-alist[0m: [47m:SYSTEM[0m is associated with the [community-books] directory. Suppose that the community books and their certificates are moved to a new directory, [47m"<dir>"[0m. Then if you run ACL2 in an environment where the [47mproject-dir-alist[0m associates [47m:SYSTEM[0m with [47m"<dir>"[0m, the relocated community books will still be treated as certified. The case of [47m:SYSTEM[0m described above generalizes naturally, as follows. Let [47mS[0m be a set of books certified with a given [47mproject-dir-alist[0m, each of which includes only other books in [47mS[0m. (For example, [47mS[0m contains just the community books directory in the special case above.) Also assume that the absolute pathname of every book in [47mS[0m has a prefix among the directories in that [47mproject-dir-alist[0m. Then all books in [47mS[0m, along with their [certificate] files, can be moved and those books will still be considered to be certified in any ACL2 session with a suitable [47mproject-dir-alist[0m, as follows. For every keyword [47m:K[0m mapped to directory [47m"<dir>"[0m in the original [47mproject-dir-alist[0m (the one at certification time), the new [47mproject-dir-alist[0m should map [47m:K[0m to the directory [47m"<dir2>"[0m to which [47m"<dir>"[0m was moved. [31;1m(2) [47m:K[0m[31;1m can be used as a [47m:dir[0m[31;1m keyword, to reference [47m"<dir>"[0m[31;1m.[0m The optional [47m:dir[0m keyword argument of [47m[include-book][0m and [47m[ld][0m can have value [47m:K[0m, in which case the pathname argument is interpreted with respect to [47m"<dir>"[0m. This behavior is the same as when [47m:K[0m is bound to [47m"<dir>"[0m using [47m[add-include-book-dir][0m or [47m[add-include-book-dir!][0m. Additional details [31;1mPrefixes.[0m Suppose [47m:K1[0m and [47m:K2[0m are keywords bound in the [47mproject-dir-alist[0m to [47m"<dir1>"[0m and [47m"<dir2>"[0m, respectively, where [47m"<dir1>"[0m is a prefix of [47m"<dir2>"[0m (hence is strictly shorter, since duplicates are disallowed, as noted above). Then it may be simplest to maintain that property --- that the value of [47m:K1[0m is a prefix of the value of [47m:K2[0m --- when creating a new [47mACL2_PROJECTS[0m directory to reflect relocation of these directories of books. The actual requirement is that directories under the old value of [47m:K2[0m need to be moved to the same relative locations under the new value of [47m:K2[0m, and all other directories under the old value of [47m:K1[0m need to be moved to the same relative locations under the new value of [47m:K1[0m. [31;1m[47m[Save-exec][0m[31;1m.[0m By default, an executable created with [47m[save-exec][0m will have an unchanged [47mproject-dir-alist[0m. However, a new [47mproject-dir-alist[0m will be created as described above if environment variable [47mACL2_PROJECTS[0m is set; also, if environment variable [47mACL2_SYSTEM_BOOKS[0m is set, then the existing [47mproject-dir-alist[0m will be modified to map [47m:SYSTEM[0m to the value of [47mACL2_SYSTEM_BOOKS[0m. Additional Limitations and Restrictions (Already noted above) [31;1mNo duplicates.[0m There must be no duplicate keys or duplicate directory names in the [47mproject-dir-alist[0m. [31;1mNo overlap.[0m No keyword may be bound with [47m[add-include-book-dir][0m or [47m[add-include-book-dir!][0m that is also bound in the [47mproject-dir-alist[0m. [31;1mAvoid using absolute pathnames in books.[0m Consider a form that contains an absolute pathname, such as [47m(defconst *c* "/u/home/jones/bk")[0m. If that form is in a book [47mB[0m that is moved, then of course it remain in [47mB[0m after the move. That is certainly fine, unless one expects this pathname to change as [47mB[0m is moved. That said, an absolute pathname that extends a project directory is OK in an [47m[include-book][0m form among the [portcullis] commands for a book, in the following sense: it is replaced in that book's [certificate] by referencing the project's keyword name to avoid using an absolute pathname. Subtopics [Sysfile] File representation using ACL2 project directories") (prompt (ld) "The prompt printed by [47m[ld][0m The prompt printed by ACL2 conveys information about various ``modes.'' See [default-print-prompt] and see [ld-prompt] for details. The prompt in raw Lisp, including [breaks] from the ACL2 loop, can be adjusted by ACL2 to include the string [47m"[RAW LISP[0m"], at least for most Common Lisp implementations. That change can help to remind users not to submit ACL2 forms there. That adjustment is made by executing the following form in raw Lisp (for example, after typing [47m:[0m[47m[q][0m). (install-new-raw-prompt) To return to printing the original Lisp prompt in raw lisp, evaluate the following in raw Lisp. (install-old-raw-prompt)") (proof-builder (acl2 debugging) "An interactive tool for controlling ACL2's proof processes. Call this up with [47m(verify ...)[0m. The [3minteractive proof-builder[0m provides a way to explore the development of ACL2 proofs below the level of the ACL2 prover (as typically used by [47m[thm][0m and [events] such as [47m[defthm][0m). To use this tool, invoke the [47m[verify][0m command, for example as follows. ACL2 !>(verify (equal (append (append x y) z) (append x (append y z)))) ->: Then at the [47m"->:"[0m prompt, one submits commands that operate on a stack of goals, starting with the single goal that was supplied to [47mVERIFY[0m as shown above. The final command (or ``instruction'') can be an [47mexit[0m command, which can print out a [47m[defthm][0m event if the goal stack is empty; see [proof-builder-commands], in particular the [47mexit[0m command. That resulting [47mdefthm[0m event includes an [47m:[0m[47m[instructions][0m parameter, which directs replay of the interactive proof-builder commands (for example during certification of a book containing that event; see [books]). If you exit the interactive proof-builder's loop, you may re-enter that session at the same point using the command [47m(verify)[0m, i.e., with no arguments. The commands [47msave[0m and [47mretrieve[0m may be invoked to manage more than one session. The interactive proof-builder can be invoked on a specific subgoal, and the resulting [47m:instructions[0m can be given as a hint to the theorem prover for that subgoal. See [instructions]. A tutorial is available {here | http://www.cs.utexas.edu/users/kaufmann/tutorial/rev3.html}. That tutorial illustrates more than just the interactive proof-builder. The portion relevant to the proof-builder may be accessed directly {here | http://www.cs.utexas.edu/users/kaufmann/tutorial/rev3.html#slide29}. See [set-evisc-tuple] for how to arrange that output is printed in abbreviated form. In general, the interactive proof-builder uses the [47m:TERM[0m [evisc-tuple] described in that documentation. Individual proof-builder commands are documented in subsection [proof-builder-commands]. Note that the package name (see [symbol-package-name] is irrelevant for these commands (though not their arguments); for example [47m(dive 3)[0m, [47m(acl2::dive 3)[0m, [47m(acl2-pc::dive 3)[0m, and [47m(:dive 3)[0m are all equivalent. For a list of perhaps the most commonly used commands, see [proof-builder-commands-short-list]. The proof-builder supports user-defined macros, which are tactics that generate proof-builder instructions. See [define-pc-macro]. [3mRemark.[0m The ``pc-'' prefix, for example in ``define-pc-macro'' above, stems from an earlier name for the proof-builder, which was ``proof-checker''. That also accounts for the string [47m"PC"[0m in the package name, [47m"ACL2-PC"[0m. Subtopics [Define-pc-help] Define a macro command whose purpose is to print something [Define-pc-macro] Define a proof-builder macro command [Define-pc-meta] Define a proof-builder meta command [Dive-into-macros-table] Right-associated function information for the [proof-builder] [Instructions] Instructions to the interactive proof-builder [Macro-command] Compound command for the interactive proof-builder [Proof-builder-commands] List of commands for the interactive proof-builder [Proof-builder-commands-short-list] Perhaps the most commonly used [proof-builder] commands [Proof-checker] Old name for [proof-builder] [Retrieve] Re-enter a (specified) [proof-builder] state [Toggle-pc-macro] Change an ordinary macro command to an atomic macro, or vice-versa [Unsave] Remove a [proof-builder] state [Verify] Enter the interactive proof-builder") (proof-builder-commands (proof-builder) "List of commands for the interactive proof-builder This documentation section contains documentation for individual commands that can be given inside the interactive [proof-builder] loop that is entered using [47m[verify][0m. For a summary of (arguably) the most useful commands, see [proof-builder-commands-short-list]. Subtopics [ACL2-pc::=] (atomic macro) attempt an equality (or equivalence) substitution [ACL2-pc::ACL2-wrap] (macro) same as [47m(lisp x)[0m [ACL2-pc::add-abbreviation] (primitive) add an abbreviation [ACL2-pc::al] (macro) same as apply-linear [ACL2-pc::apply-linear] (primitive) apply a linear rule [ACL2-pc::bash] (atomic macro) call the ACL2 theorem prover's simplifier [ACL2-pc::bdd] (atomic macro) prove the current goal using bdds [ACL2-pc::bk] (atomic macro) move backward one argument in the enclosing term [ACL2-pc::bookmark] (macro) insert matching ``bookends'' comments [ACL2-pc::casesplit] (primitive) split into two cases [ACL2-pc::cg] (macro) change to another goal. [ACL2-pc::change-goal] (primitive) change to another goal. [ACL2-pc::cl-proc] (macro) same as [47mclause-processor[0m [ACL2-pc::claim] (atomic macro) add a new hypothesis [ACL2-pc::clause-processor] (atomic macro) use a clause-processor [ACL2-pc::comm] (macro) display instructions from the current interactive session [ACL2-pc::commands] (macro) display instructions from the current interactive session [ACL2-pc::comment] (primitive) insert a comment [ACL2-pc::contradict] (macro) same as [47mcontrapose[0m [ACL2-pc::contrapose] (primitive) switch a hypothesis with the conclusion, negating both [ACL2-pc::demote] (primitive) move top-level hypotheses to the conclusion [ACL2-pc::dive] (primitive) move to the indicated subterm [ACL2-pc::do-all] (macro) run the given instructions [ACL2-pc::do-all-no-prompt] (macro) run the given instructions, halting once there is a ``failure'' [ACL2-pc::do-strict] (macro) run the given instructions, halting once there is a ``failure'' [ACL2-pc::doc] (macro) access documentation inside the interactive proof-builder [ACL2-pc::drop] (primitive) drop top-level hypotheses [ACL2-pc::dv] (atomic macro) move to the indicated subterm [ACL2-pc::elim] (atomic macro) call the ACL2 theorem prover's elimination process [ACL2-pc::equiv] (primitive) attempt an equality (or congruence-based) substitution [ACL2-pc::ex] (macro) exit after possibly saving the state [ACL2-pc::exit] (meta) exit the interactive proof-builder [ACL2-pc::expand] (primitive) expand the current function call without simplification [ACL2-pc::fail] (macro) cause a failure [ACL2-pc::finish] (macro) require completion of instructions; save error if inside [47m:[0m[47m[hints][0m [ACL2-pc::forwardchain] (atomic macro) forward chain from an implication in the hyps [ACL2-pc::free] (atomic macro) create a ``free variable'' [ACL2-pc::geneqv] (macro) show the generated equivalence relation maintained at the current subterm [ACL2-pc::generalize] (primitive) perform a generalization [ACL2-pc::goals] (macro) list the names of goals on the stack [ACL2-pc::help] (macro) proof-builder help facility [ACL2-pc::hyps] (macro) print the hypotheses [ACL2-pc::illegal] (macro) illegal instruction [ACL2-pc::in-theory] (primitive) set the current proof-builder theory [ACL2-pc::induct] (atomic macro) generate subgoals using induction [ACL2-pc::lemmas-used] (macro) print the runes (definitions, lemmas, ...) used [ACL2-pc::lisp] (meta) evaluate the given form in Lisp [ACL2-pc::negate] (macro) run the given instructions, and ``succeed'' if and only if they ``fail'' [ACL2-pc::nil] (macro) used for interpreting [47mcontrol-d[0m [ACL2-pc::noise] (meta) run instructions with prover output [ACL2-pc::noise!] (meta) run instructions with prover and proof-tree output [ACL2-pc::nx] (atomic macro) move forward one argument in the enclosing term [ACL2-pc::orelse] (macro) run the first instruction; if (and only if) it ``fails'', run the second [ACL2-pc::p] (macro) prettyprint the current term in the usual user-level (untranslated) syntax [ACL2-pc::p-top] (macro) prettyprint the conclusion, highlighting the current term [ACL2-pc::pl] (macro) print the rules for a given name [ACL2-pc::pot-lst] (macro) display the linear arithmetic database based on the current context [ACL2-pc::pp] (macro) prettyprint the current term in internal (translated) form [ACL2-pc::pr] (macro) print the rules for a given name [ACL2-pc::print] (macro) print the result of evaluating the given form [ACL2-pc::print-all-concs] (macro) print all the conclusions of (as yet unproved) goals [ACL2-pc::print-all-goals] (macro) print all the (as yet unproved) goals [ACL2-pc::print-main] (macro) print the original goal [ACL2-pc::pro] (atomic macro) repeatedly apply promote [ACL2-pc::promote] (primitive) move antecedents of conclusion's [47mimplies[0m term to top-level hypotheses [Proof-builder-commands-short-list] Perhaps the most commonly used [proof-builder] commands [ACL2-pc::protect] (macro) run the given instructions, reverting to existing state upon failure [ACL2-pc::prove] (primitive) call the ACL2 theorem prover to prove the current goal [ACL2-pc::pso] (macro) print the most recent proof attempt from inside the proof-builder [ACL2-pc::pso!] (macro) print the most recent proof attempt from inside the proof-builder [ACL2-pc::psog] (macro) print the most recent proof attempt from inside the proof-builder [ACL2-pc::put] (macro) substitute for a ``free variable'' [ACL2-pc::quiet] (meta) run instructions without prover output [ACL2-pc::quiet!] (meta) run instructions without prover output [ACL2-pc::r] (macro) same as rewrite [ACL2-pc::reduce] (atomic macro) call the ACL2 theorem prover's simplifier [ACL2-pc::reduce-by-induction] (macro) call the ACL2 prover without induction, after going into induction [ACL2-pc::remove-abbreviations] (primitive) remove one or more abbreviations [ACL2-pc::repeat] (macro) repeat the given instruction until it ``fails'' [ACL2-pc::repeat-rec] (macro) auxiliary to [47mrepeat[0m [ACL2-pc::replay] (macro) replay one or more instructions [ACL2-pc::restore] (meta) remove the effect of an UNDO command [ACL2-pc::retain] (atomic macro) drop all [31;1mbut[0m the indicated top-level hypotheses [ACL2-pc::retrieve] (macro) re-enter the proof-builder [ACL2-pc::rewrite] (primitive) apply a rewrite rule [ACL2-pc::run-instr-on-goal] (macro) auxiliary to THEN [ACL2-pc::run-instr-on-new-goals] (macro) auxiliary to [47mthen[0m [ACL2-pc::runes] (macro) print the runes (definitions, lemmas, ...) used [ACL2-pc::s] (primitive) simplify the current subterm [ACL2-pc::s-prop] (atomic macro) simplify propositionally [ACL2-pc::save] (macro) save the proof-builder state (state-stack) [ACL2-pc::sequence] (meta) run the given list of instructions according to a multitude of options [ACL2-pc::show-abbreviations] (macro) display the current abbreviations [ACL2-pc::show-linears] (macro) display the applicable [linear] rules [ACL2-pc::show-rewrites] (macro) display the applicable [rewrite] rules [ACL2-pc::show-type-prescriptions] (macro) display the applicable [type-prescription] rules [ACL2-pc::skip] (macro) ``succeed'' without doing anything [ACL2-pc::sl] (atomic macro) simplify with lemmas [ACL2-pc::sls] (macro) same as SHOW-LINEARS [ACL2-pc::split] (atomic macro) split the current goal into cases [ACL2-pc::sr] (macro) same as SHOW-REWRITES [ACL2-pc::st] (macro) same as SHOW-TYPE-PRESCRIPTIONS [ACL2-pc::succeed] (macro) run the given instructions, and ``succeed'' [ACL2-pc::th] (macro) print the top-level hypotheses and the current subterm [ACL2-pc::then] (macro) apply one instruction to current goal and another to new subgoals [ACL2-pc::top] (atomic macro) move to the top of the goal [ACL2-pc::type-alist] (macro) display the [type-alist] from the current context [ACL2-pc::undo] (meta) undo some instructions [ACL2-pc::unsave] (macro) remove a proof-builder state [ACL2-pc::up] (primitive) move to the parent (or some ancestor) of the current subterm [ACL2-pc::use] (atomic macro) use a lemma instance [ACL2-pc::wrap] (atomic macro) execute the indicated instructions and combine all the new goals [ACL2-pc::wrap-induct] (atomic macro) same as induct, but create a single goal [ACL2-pc::wrap1] (primitive) combine goals into a single goal [ACL2-pc::x] (atomic macro) expand and (maybe) simplify function call at the current subterm [ACL2-pc::x-dumb] (atomic macro) expand function call at the current subterm, without simplifying") (proof-builder-commands-short-list (proof-builder proof-builder-commands) "Perhaps the most commonly used [proof-builder] commands The list of subtopics below includes what are arguably the most useful, and most commonly used, [proof-builder] commands. Subtopics [ACL2-pc::=] (atomic macro) attempt an equality (or equivalence) substitution [ACL2-pc::bash] (atomic macro) call the ACL2 theorem prover's simplifier [ACL2-pc::bk] (atomic macro) move backward one argument in the enclosing term [ACL2-pc::cg] (macro) change to another goal. [ACL2-pc::claim] (atomic macro) add a new hypothesis [ACL2-pc::comm] (macro) display instructions from the current interactive session [ACL2-pc::contrapose] (primitive) switch a hypothesis with the conclusion, negating both [ACL2-pc::demote] (primitive) move top-level hypotheses to the conclusion [ACL2-pc::drop] (primitive) drop top-level hypotheses [ACL2-pc::dv] (atomic macro) move to the indicated subterm [ACL2-pc::exit] (meta) exit the interactive proof-builder [ACL2-pc::expand] (primitive) expand the current function call without simplification [ACL2-pc::goals] (macro) list the names of goals on the stack [ACL2-pc::in-theory] (primitive) set the current proof-builder theory [ACL2-pc::induct] (atomic macro) generate subgoals using induction [ACL2-pc::nx] (atomic macro) move forward one argument in the enclosing term [ACL2-pc::p] (macro) prettyprint the current term in the usual user-level (untranslated) syntax [ACL2-pc::p-top] (macro) prettyprint the conclusion, highlighting the current term [ACL2-pc::prove] (primitive) call the ACL2 theorem prover to prove the current goal [ACL2-pc::r] (macro) same as rewrite [ACL2-pc::replay] (macro) replay one or more instructions [ACL2-pc::restore] (meta) remove the effect of an UNDO command [ACL2-pc::retrieve] (macro) re-enter the proof-builder [ACL2-pc::runes] (macro) print the runes (definitions, lemmas, ...) used [ACL2-pc::s] (primitive) simplify the current subterm [ACL2-pc::s-prop] (atomic macro) simplify propositionally [ACL2-pc::save] (macro) save the proof-builder state (state-stack) [ACL2-pc::show-rewrites] (macro) display the applicable [rewrite] rules [ACL2-pc::split] (atomic macro) split the current goal into cases [ACL2-pc::sr] (macro) same as SHOW-REWRITES [ACL2-pc::th] (macro) print the top-level hypotheses and the current subterm [ACL2-pc::top] (atomic macro) move to the top of the goal [ACL2-pc::undo] (meta) undo some instructions [ACL2-pc::up] (primitive) move to the parent (or some ancestor) of the current subterm [ACL2-pc::use] (atomic macro) use a lemma instance [ACL2-pc::x] (atomic macro) expand and (maybe) simplify function call at the current subterm [ACL2-pc::x-dumb] (atomic macro) expand function call at the current subterm, without simplifying") (proof-checker (proof-builder) "Old name for [proof-builder] See [proof-builder]. Historically, this tool was misnamed the ``proof-checker'', but since the tool is used for building and exploring (what could be called) proofs rather than for checking them, its name was changed to ``proof-builder'' in 2016.") (proof-of-well-foundedness (ordinals) "A proof that [47m[o<][0m is well-founded on [47m[o-p][0ms The soundness of ACL2 rests in part on the well-foundedness of [47m[o<][0m on [47m[o-p][0ms. This can be taken as obvious if one is willing to grant that those concepts are simply encodings of the standard mathematical notions of the ordinals below [47mepsilon-0[0m and its natural ordering relation. But it is possible to prove that [47m[o<][0m is well-founded on [47m[o-p][0ms without having to assert any connection to the ordinals and that is what we do here. The community book [47mbooks/ordinals/proof-of-well-foundedness[0m carries out the proof outlined below in ACL2, using only that the natural numbers are well-founded. Before outlining the above mentioned proof, we note that in the analogous documentation page of ACL2 Version_2.7, there is a proof of the well-foundedness of [47me0-ord-<[0m on [47me0-ordinalp[0ms, the less-than relation and recognizer for the old ordinals (that is, for the ordinals appearing in ACL2 up through that version). Manolios and Vroon have given a proof in ACL2 Version_2.7 that the current ordinals (based on [47m[o<][0m and [47m[o-p][0m) are order-isomorphic to the old ordinals (based on [47me0-ord-<[0m and [47me0-ordinalp[0m). Their proof establishes that switching from the old ordinals to the current ordinals preserves the soundness of ACL2. For details see their paper: Manolios, Panagiotis & Vroon, Daron. Ordinal arithmetic in ACL2. Kaufmann, Matt, & Moore, J Strother (eds). Fourth International Workshop on the ACL2 Theorem Prover and Its Applications (ACL2-2003), July, 2003. See {http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/ | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}. We now give an outline of the above mentioned proof of well-foundedness. We first observe three facts about [47m[o<][0m on ordinals that have been proved by ACL2 using only structural induction on lists. These theorems can be proved by hand. (defthm transitivity-of-o< (implies (and (o< x y) (o< y z)) (o< x z)) :rule-classes nil) (defthm non-circularity-of-o< (implies (o< x y) (not (o< y x))) :rule-classes nil) (defthm trichotomy-of-o< (implies (and (o-p x) (o-p y)) (or (equal x y) (o< x y) (o< y x))) :rule-classes nil) These three properties establish that [47m[o<][0m orders the [47m[o-p][0ms. To put such a statement in the most standard mathematical nomenclature, we can define the macro: (defmacro o<= (x y) `(not (o< ,y ,x))) and then establish that [47mo<=[0m is a relation that is a simple, complete (i.e., total) order on ordinals by the following three lemmas, which have been proved: (defthm antisymmetry-of-o<= (implies (and (o-p x) (o-p y) (o<= x y) (o<= y x)) (equal x y)) :rule-classes nil :hints (("Goal" :use non-circularity-of-o<))) (defthm transitivity-of-o<= (implies (and (o-p x) (o-p y) (o<= x y) (o<= y z)) (o<= x z)) :rule-classes nil :hints (("Goal" :use transitivity-of-o<))) (defthm trichotomy-of-o<= (implies (and (o-p x) (o-p y)) (or (o<= x y) (o<= y x))) :rule-classes nil :hints (("Goal" :use trichotomy-of-o<))) Crucially important to the proof of the well-foundedness of [47m[o<][0m on [47m[o-p][0ms is the concept of ordinal-depth, abbreviated [47mod[0m: (defun od (l) (if (o-finp l) 0 (1+ (od (o-first-expt l))))) If the [47mod[0m of an [47m[o-p][0m [47mx[0m is smaller than that of an [47m[o-p][0m [47my[0m, then [47mx[0m is [47m[o<][0m [47my[0m: (defun od-1 (x y) (if (o-finp x) (list x y) (od-1 (o-first-expt x) (o-first-expt y)))) (defthm od-implies-ordlessp (implies (and (o-p x) (< (od x) (od y))) (o< x y)) :hints (("Goal" :induct (od-1 x y)))) Remark. A consequence of this lemma is the fact that if [47ms = s(1)[0m, [47ms(2)[0m, ... is an infinite, [47m[o<][0m descending sequence of [47m[o-p][0ms, then [47mod(s(1))[0m, [47mod(s(2))[0m, ... is a ``weakly'' descending sequence of non-negative integers: [47mod(s(i))[0m is greater than or equal to [47mod(s(i+1))[0m. [3mLemma Main.[0m For each non-negative integer [47mn[0m, [47m[o<][0m well-orders the set of [47m[o-p][0ms with [47mod[0m less than or equal to [47mn[0m . Base Case. n = 0. The o-ps with 0 od are the non-negative integers. On the non-negative integers, o< is the same as <. Induction Step. n > 0. We assume that o< well-orders the o-ps with od less than n. If o< does not well-order the o-ps with od less than or equal to n, consider, D, the set of infinite, o< descending sequences of o-ps of od less than or equal to n. The first element of a sequence in D has od n. Therefore, the o-first-expt of the first element of a sequence in D has od n-1. Since o<, by IH, well-orders the o-ps with od less than n, the set of o-first-expts of first elements of the sequences in D has a minimal element, which we denote by B and which has od of n-1. Let k be the minimum integer such that for some infinite, o< descending sequence s of o-ps with od less than or equal to n, the first element of s has an o-first-expt of B and an o-first-coeff of k. Notice that k is positive. Having fixed B and k, let s = s(1), s(2), ... be an infinite, o< descending sequence of o-ps with od less than or equal to n such that s(1) has a o-first-expt of B and an o-first-coeff of k. We show that each s(i) has a o-first-expt of B and an o-first-coeff of k. For suppose that s(j) is the first member of s either with o-first-expt B and o-first-coeff m (m neq k) or with o-first-expt B' and o-first-coeff B' (B' neq B). If (o-first-expt s(j)) = B', then B' has od n-1 (otherwise, by IH, s would not be infinite) and B' is o< B, contradicting the minimality of B. If 0 < m < k, then the fact that the sequence beginning at s(j) is infinitely descending contradicts the minimality of k. If m > k, then s(j) is greater than its predecessor; but this contradicts the fact that s is descending. Thus, by the definition of o<, for s to be a decreasing sequence of o-ps, (o-rst s(1)), (o-rst s(2)), ... must be a decreasing sequence. We end by showing this cannot be the case. Let t = t(1), t(2), ... be an infinite sequence of o-ps such that t(i) = (o-rst s(i)). Then t is infinitely descending. Furthermore, t(1) begins with an o-p B' that is o< B. Since t is in D, t(1) has od n, therefore, B' has od n-1. But this contradicts the minimality of B. Q.E.D. Theorem. [47m[o<][0m well-orders the [47m[o-p][0ms. Proof. Every infinite,[47m o<[0m descending sequence of [47m[o-p][0ms has the property that each member has [47mod[0m less than or equal to the [47mod[0m, [47mn[0m, of the first member of the sequence. This contradicts Lemma Main. Q.E.D.") (proof-supporters-alist (pointers) "See [dead-events].") (proof-tree (debugging) "Proof tree displays A view of ACL2 proofs may be obtained by way of ``proof tree displays,'' which appear in proof output (see [proofs-co]) when proof-tree output is enabled (see below) When ACL2 starts a proof and proof-tree output is enabled, the proof output begins with the following string. << Starting proof tree logging >> Then for each goal encountered during the proof, a corresponding proof tree display (as described below) is printed into the proof output: first the characters in the constant string [47m*proof-tree-start-delimiter*[0m are printed, then the proof tree display, and finally the characters in the constant string [47m*proof-tree-end-delimiter*[0m. External tools may present proof tree displays in a separate window. In particular, a tool distributed with the ACL2 community books customizes the emacs environment to provide window-based proof tree displays together with commands for traversing the proof transcript; see the discussion of ``ACL2 proof-tree support'' in file [47memacs-acl2.el[0m distributed with ACL2 (in either of two directories; see [emacs]). The command [47m:start-proof-tree[0m enables proof-tree output, while [47m:stop-proof-tree[0m disables proof-tree output; see [start-proof-tree] and see [stop-proof-tree]. Here is an example of a proof tree display, with comments. Lines marked with ``c'' are considered ``checkpoints,'' i.e., goals whose scrutiny may be of particular value. ( DEFTHM PLUS-TREE-DEL ...) ;currently proving PLUS-TREE-DEL 1 Goal preprocess ;"Goal" creates 1 subgoal by preprocessing 2 | Goal' simp ;"Goal'" creates 2 subgoals by simplification c 0 | | Subgoal 2 PUSH *1 ;"Subgoal 2" pushes "*1" for INDUCT ++++++++++++++++++++++++++++++ ;first pass thru waterfall completed c 6 *1 INDUCT ;Proof by induction of "*1" has | <5 more subgoals> ; created 6 top-level subgoals. At ; this point, one of those 6 has been ; proved, and 5 remain to be proved. ; We are currently working on the ; first of those 5 remaining goals. See [proof-tree-examples] for many examples that contain proof tree displays. But first, we summarize the kinds of lines that may appear in a proof tree display. The simplest form of a proof tree display is a header showing the current event, followed by list of lines, each having one of the following forms. n <goal> <process> ... Says that the indicated goal created [47mn[0m subgoals using the indicated process. Here ``...'' refers to possible additional information. c n <goal> <process> ... As above, but calls attention to the fact that this goal is a ``checkpoint'' in the sense that it may be of particular interest. Some displays may overwrite ``c'' with ``>'' to indicate the current checkpoint being shown in the proof transcript. | <goal> ... | | <k subgoals> Indicates that the goal just above this line, which is pointed to by the rightmost vertical bar (``|''), has [47mk[0m subgoals, none of which have yet been processed. | <goal> ... | | <k more subgoals> As above, except that some subgoals have already been processed. ++++++++++++++++++++++++++++++ Separates successive passes through the ``waterfall''. Thus, this ``fencepost'' mark indicates the start of a new proof by induction or of a new forcing round. See [proof-tree-examples] for detailed examples. See [checkpoint-forced-goals] to learn how to mark goals as checkpoints that [force] the creation of goals in forcing rounds. Finally, see [proof-tree-details] for some points not covered elsewhere. Subtopics [Checkpoint-forced-goals] Cause forcing goals to be checkpointed in proof trees [Proof-tree-details] Proof tree details not covered elsewhere [Proof-tree-examples] Proof tree example [Start-proof-tree] Start displaying proof trees during proofs [Stop-proof-tree] Stop displaying proof trees during proofs") (proof-tree-details (proof-tree) "Proof tree details not covered elsewhere See [proof-tree] for an introduction to proof trees, and for a list of related topics. Here we present some details not covered elsewhere. 1. When proof tree display is enabled (because the command [47m:[0m[47m[stop-proof-tree][0m has not been executed, or has been superseded by a later [47m:[0m[47m[start-proof-tree][0m command), then time summaries will include the time for proof tree display. This time includes the time spent computing with proof trees, such as the pruning process described briefly above. Even when proof trees are not displayed, such as when their display is turned off in the middle of a proof, this time will be printed if it is not 0. 2. When a goal is given a [47m:bye[0m in a proof (see [hints]), it is treated for the purpose of proof tree display just as though it had been proved. 3. Several [state] global variables affect proof tree display. [47m(@ proof-tree-indent)[0m is initially the string [47m"| "[0m: it is the string that is laid down the appropriate number of times to effect indentation. [47m(@ proof-tree-buffer-width)[0m is initially the value of [47m(fmt-soft-right-margin state)[0m, and is used to prevent printing of the annotation ``([force]d ...)'' in any greater column than this value. However, [47m(assign proof-tree-buffer-width nil)[0m to avoid any such suppression. Finally, [47m(@ checkpoint-processors)[0m is a list of processors from the constant list [47m*preprocess-clause-ledge*[0m, together with [47m:induct[0m. You may remove elements of [47m(@ checkpoint-processors)[0m to limit which processes are considered checkpoints, but note that this can affect what is printed by gag-mode (see [set-gag-mode]). 4. When [47m:[0m[47m[otf-flg][0m is not set to [47mt[0m in a proof, and the prover then decides to revert to the original goal and prove it by induction, the proof tree display will reflect this fact as shown here: c 0 | | Subgoal 2 PUSH (reverting) 5. The usual [failure] message is printed as part of the prooftree display when a proof has failed.") (proof-tree-examples (proof-tree) "Proof tree example See [proof-tree] for an introduction to proof trees, and for a list of related topics. Here we present a detailed example followed by a shorter example that illustrates proof by induction. Consider the [guard] proof for the definition of a function [47mcancel_equal_plus[0m; the body of this definition is of no importance here. The first proof tree display is: ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess | <18 subgoals> This is to be read as follows. At this stage of the proof we have encountered the top-level goal, named "Goal", which generated 18 subgoals using the ``preprocess'' process. We have not yet begun to work on those subgoals. The corresponding message from the ordinary prover output is: By case analysis we reduce the conjecture to the following 18 conjectures. Note that the field just before the name of the goal ([47m"Goal"[0m), which here contains the number 18, indicates the number of cases (children) created by the goal using the indicated process. This number will remain unchanged as long as this goal is displayed. The next proof tree display is: ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 1 | Subgoal 18 simp | | <1 subgoal> | <17 more subgoals> which indicates that at this point, the prover has used the simplification (``simp'') process on Subgoal 18 to create one subgoal (``<1 subgoal>''). The vertical bar (``|'') below ``Subgoal 18'', accompanied by the line below it, signifies that there are 17 siblings of Subgoal 18 that remain to be processed. The next proof tree displayed is: ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 1 | Subgoal 18 simp c 2 | | Subgoal 18' ELIM | | | <2 subgoals> | <17 more subgoals> Let us focus on the fourth line of this display: c 2 | | Subgoal 18' ELIM The ``c'' field marks this goal as a ``checkpoint'', i.e., a goal worthy of careful scrutiny. In fact, any goal that creates children by a process other than ``preprocess'' or ``simp'' is marked as a checkpoint. In this case, the destructor-elimination (``[elim]'') process has been used to create subgoals of this goal. The indentation shows that this goal, Subgoal 18', is a child of Subgoal 18. The number ``2'' indicates that 2 subgoals have been created (by [elim]). Note that this information is consistent with the line just below it, which says ``<2 subgoals>''. Finally, the last line of this proof tree display, | <17 more subgoals> is connected by vertical bars (``|'') up to the string [47m"Subgoal 18"[0m, which suggests that there are 17 immediate subgoals of Goal remaining to process after Subgoal 18. Note that this line is indented one level from the second line, which is the line for the goal named [47m"Goal"[0m. The display is intended to suggest that the subgoals of Goal that remain to be proved consist of Subgoal 18 together with 17 more subgoals. The next proof tree display differs from the previous one only in that now, Subgoal 18' has only one more subgoal to be processed. ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 1 | Subgoal 18 simp c 2 | | Subgoal 18' ELIM | | | <1 more subgoal> | <17 more subgoals> Note that the word ``more'' in ``<1 more subgoal>'' tells us that there was originally more than one subgoal of Subgoal 18. In fact that information already follows from the line above, which (as previously explained) says that Subgoal 18' originally created 2 subgoals. The next proof tree display occurs when the prover completes the proof of that ``1 more subgoal'' referred to above. ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess | <17 more subgoals> Then, Subgoal 17 is processed and creates one subgoal, by simplification: ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 1 | Subgoal 17 simp | | <1 subgoal> | <16 more subgoals> ... and so on. Later in the proof one might find the following successive proof tree displays. ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess | <9 more subgoals> ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 0 | Subgoal 9 simp (FORCED) | <8 more subgoals> These displays tell us that Subgoal 9 simplified to [47mt[0m (note that the ``0'' shows clearly that no subgoals were created), but that some rule's hypotheses were [force]d. Although this goal is not checkpointed (i.e., no ``c'' appears on the left margin), one can cause such goals to be checkpointed; see [checkpoint-forced-goals]. In fact, the proof tree displayed at the end of the ``main proof''(the 0-th forcing round) is as follows. ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 0 | Subgoal 9 simp (FORCED) 0 | Subgoal 8 simp (FORCED) 0 | Subgoal 7 simp (FORCED) 0 | Subgoal 6 simp (FORCED) 0 | Subgoal 4 simp (FORCED) 0 | Subgoal 3 simp (FORCED) This is followed by the following proof tree display at the start of the forcing round. 18 Goal preprocess 0 | Subgoal 9 simp (FORCED [1]Subgoal 4) 0 | Subgoal 8 simp (FORCED [1]Subgoal 6) 0 | Subgoal 7 simp (FORCED [1]Subgoal 1) 0 | Subgoal 6 simp (FORCED [1]Subgoal 3) 0 | Subgoal 4 simp (FORCED [1]Subgoal 5) 0 | Subgoal 3 simp (FORCED [1]Subgoal 2) ++++++++++++++++++++++++++++++ 6 [1]Goal FORCING-ROUND 2 | [1]Subgoal 6 preprocess | | <2 subgoals> | <5 more subgoals> This display shows which goals to ``blame'' for the existence of each goal in the forcing round. For example, Subgoal 9 is to blame for the creation of [1]Subgoal 4. Actually, there is no real goal named [47m"[1]Goal"[0m. However, the line 6 [1]Goal FORCING-ROUND appears in the proof tree display to suggest a ``parent'' of the six top-level goals in that forcing round. As usual, the numeric field before the goal name contains the original number of children of that (virtual, in this case) goal --- in this case, 6. In our example proof, Subgoal 6 eventually gets proved, without doing any further forcing. At that point, the proof tree display looks as follows. ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 0 | Subgoal 9 simp (FORCED [1]Subgoal 4) 0 | Subgoal 7 simp (FORCED [1]Subgoal 1) 0 | Subgoal 6 simp (FORCED [1]Subgoal 3) 0 | Subgoal 4 simp (FORCED [1]Subgoal 5) 0 | Subgoal 3 simp (FORCED [1]Subgoal 2) ++++++++++++++++++++++++++++++ 6 [1]Goal FORCING-ROUND | <5 more subgoals> Notice that the line for Subgoal 8, 0 | Subgoal 8 simp (FORCED [1]Subgoal 6) no longer appears. That is because the goal [1]Subgoal 6 has been proved, along with all its children; and hence, the proof of Subgoal 8 no longer depends on any further reasoning. The final two proof tree displays in our example are as follows. ( DEFUN CANCEL_EQUAL_PLUS ...) 18 Goal preprocess 0 | Subgoal 7 simp (FORCED [1]Subgoal 1) ++++++++++++++++++++++++++++++ 6 [1]Goal FORCING-ROUND 2 | [1]Subgoal 1 preprocess 1 | | [1]Subgoal 1.1 preprocess 1 | | | [1]Subgoal 1.1' simp c 3 | | | | [1]Subgoal 1.1'' ELIM | | | | | <1 more subgoal> ( DEFUN CANCEL_EQUAL_PLUS ...) <<PROOF TREE IS EMPTY>> The explanation for the empty proof tree is simple: once [1]Subgoal 1.1.1 was proved, nothing further remained to be proved. In fact, the much sought-after ``Q.E.D.'' appeared shortly after the final proof tree was displayed. Let us conclude with a final, brief example that illustrates proof by induction. Partway through the proof one might come across the following proof tree display. ( DEFTHM PLUS-TREE-DEL ...) 1 Goal preprocess 2 | Goal' simp c 0 | | Subgoal 2 PUSH *1 | | <1 more subgoal> This display says that in the attempt to prove a theorem called [47mplus-tree-del[0m, preprocessing created the only child Goal' from Goal, and Goal' simplified to two subgoals. Subgoal 2 is immediately pushed for proof by induction, under the name ``*1''. In fact if Subgoal 1 simplifies to [47mt[0m, then we see the following successive proof tree displays after the one shown above. ( DEFTHM PLUS-TREE-DEL ...) 1 Goal preprocess 2 | Goal' simp c 0 | | Subgoal 2 PUSH *1 ( DEFTHM PLUS-TREE-DEL ...) 1 Goal preprocess 2 | Goal' simp c 0 | | Subgoal 2 PUSH *1 ++++++++++++++++++++++++++++++ c 6 *1 INDUCT | <5 more subgoals> The separator ``+++++...'' says that we are beginning another trip through the waterfall. In fact this trip is for a proof by induction (as opposed to a forcing round), as indicated by the word ``INDUCT''. Apparently *1.6 was proved immediately, because it was not even displayed; a goal is only displayed when there is some work left to do either on it or on some goal that it brought (perhaps indirectly) into existence. Once a proof by induction is completed, the ``PUSH'' line that refers to that proof is eliminated (``pruned''). So for example, when the present proof by induction is completed, the line c 0 | | Subgoal 2 PUSH *1 is eliminated, which in fact causes the lines above it to be eliminated (since they no longer refer to unproved children). Hence, at that point one might expect to see: ( DEFTHM PLUS-TREE-DEL ...) <<PROOF TREE IS EMPTY>> However, if the proof by induction of *1 necessitates further proofs by induction or a forcing round, then this ``pruning'' will not yet be done.") (proofs-co (io acl2-built-ins) "The proofs character output channel [47mProofs-co[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(proofs-co state)[0m and the updater is [47m(set-proofs-co val state)[0m. [47mProofs-co[0m must be an open character output channel. It is to this channel that [47m[defun][0m, [47m[defthm][0m, and the other event [command]s print their commentary. ``Proofs-co'' stands for ``proofs character output.'' The initial value of [47mproofs-co[0m is the same as the value of [47m[*standard-co*][0m.") (proper-consp (lists acl2-built-ins) "Recognizer for proper ([47mnil[0m-terminated) non-empty lists [47mProper-consp[0m is the function that checks whether its argument is a non-empty list that ends in [47mnil[0m. Also see [true-listp]. [31;1mFunction: [0m<proper-consp> (defun proper-consp (x) (declare (xargs :guard t)) (and (consp x) (true-listp x)))") (props (world) "Print the ACL2 properties on a symbol Example: :props assoc-eq [47mProps[0m takes one argument, a symbol, and prints all of the properties that are on that symbol in the ACL2 [world].") (protect-memoize-statistics (memoize) "Ensure the integrity of memoization statistics even upon aborts Example Forms: (f-put-global 'protect-memoize-statistics t state) (assign protect-memoize-statistics t) ; same effect as above By default, if calls of [47m[memoize][0md functions are aborted, then statistics reported by [memsum] for those calls will often be incorrect. Since aborts are relatively rare, this seems a reasonable default, since avoiding such inaccuracy incurs some additional computation time. However, evaluation of either of the forms above will arrange that for functions memoized [3mafter[0m such evaluation, the accuracy of the statistics will not be adversely affected by aborts (again, at the expense of some additional computation time). Once again: evaluation of a form displayed above only affects behavior for future calls of [47m[memoize][0m, not for functions already memoized at the time of that form's evaluation (unless the function is subsequently [unmemoize]d and then once again [memoize]d). To revert to the default state in which performance is preferred to accuracy of memoization statistics after aborts, evaluate either of the following forms. (f-put-global 'protect-memoize-statistics nil state) (assign protect-memoize-statistics nil) ; same effect as above The following demo illustrates the effect of assigning to protect-memoize-statistics. (defun foo (n) (declare (xargs :guard (natp n))) (progn$ (sleep n) n)) ; OPTIONALLY: (assign protect-memoize-statistics t) (memoize 'foo) (clear-memoize-statistics) ; for good measure (memsum) ; should have nothing to report (foo 1) (memsum) ; reports 1 call, 1 second ; Now: submit this and then abort with an interrupt it after about 3 seconds. (foo 15) ; See explanation below. (memsum) If the ``OPTIONAL'' form above is omitted, we get the default behavior: the statistics from [47m[memsum][0m will show 2 calls of [47mfoo[0m taking only took 1 second total, for an average of only 0.5 seconds, because no time was recorded for the aborted call. However, if the ``OPTIONAL'' form above is included, then you will see statistics that look accurate.") (proving_theorems_about_models (pages_written_especially_for_the_tours) "Proving Theorems about Models {IMAGE} (see [What_is_Required_of_the_User{Q}]) But ACL2 is a [31;1mlogic[0m. We can [31;1mprove theorems about the model[0m. {IMAGE} [31;1mTheorem. MC 'mult is a multiplier[0m (implies (and (natp x) (natp y)) (equal (lookup 'z (mc (s 'mult x y) (mclk x))) (* x y))). This theorem says that a certain program running on the [31;1mmc[0m machine will correctly multiply [31;1many two natural numbers[0m. It is a statement about an [31;1minfinite[0m number of test cases! We know it is true about the model because we [31;1mproved[0m it. Of course, models of actual machines usually only accept a finite number of different inputs. For example, engineers at Advanced Micro Devices (AMD), Centaur, and IBM have produced ACL2 models of floating point units that operate on double precision IEEE floating point numbers. These are finite models. But the size of their inputs is sufficiently large that they are verified by the same mathematical methods used to prove theorems about infinite state systems like our little [47mmc[0m. {IMAGE} (see [What_is_Required_of_the_User{Q}])") (provisional-certification (books-certification) "Certify a book in stages for improved book-level parallelism Provisional certification is a process that can increase parallelism when certifying books in parallel, typically using `make', when certifying a collection of [books]. We got this idea from Jared Davis, who developed rudimentary provisional certification schemes first at Rockwell Collins and later for his `Milawa' project. Our design has also benefited from conversations with Sol Swords. Warning: as of November 2014, enabling provision certification via the [47mACL2_PCERT[0m flag can not be reliably enabled at the Makefile level (as is shown below). See {Github Issue 255 | https://github.com/acl2/acl2/issues/255} for more information. To invoke provisional certification, see [books-certification]. For example, you could issue the following command. cert.pl --pcert-all -j 4 `find . -name '*.lisp'` Alternatively, see [books-certification-classic] for a discussion of classic ACL2 `make'-based certification (which may disappear in a future ACL2 release); here we extend those instructions to show how to use provisional certification. (Also, you may wish to look at community books file [47mbooks/system/pcert/Makefile[0m for an example.) We begin by describing a few ways to do that. A simple way is to add the line `[47mACL2_PCERT=t[0m' to a `make' command that you use for book certification, for example as follows. make -j 4 ACL2_PCERT=t The following works too, in a bash shell. (export ACL2_PCERT=t ; time make -j 4) Alternatively, add the line ACL2_PCERT ?= t to the [47mMakefile[0m residing in the directory, placed above the line that specifies the `[47minclude[0m' of file [47mMakefile-generic[0m. A successful `make' will result in creating the desired [certificate] ([47m.cert[0m) files. Warning: If you put the line ``[47mACL2_PCERT ?= t[0m'' below the include of [47mMakefile-generic[0m, it might have no effect. For example, try editing community books file [47mbooks/system/pcert/Makefile[0m by moving the line ``[47mACL2_PCERT ?= t[0m'' to the bottom of the file, and watch ``[47mmake top.cert[0m'' fail to invoke provisional certification. The description above may be sufficient for you to use provisional certification. We provide additional documentation below for the reader who wants to understand more about this process, for example when not using `make'. Below we assume prior familiarity with [books], in particular [47m[certify-book][0m and [47m[include-book][0m. The remainder of this [documentation] topic is divided into sections: Summary, Correctness Claim and Issues, Combining Pcertify and Convert into Pcertify+, and Further Information. [31;1mSummary[0m Recall that certification of a book, [47mbk[0m, produces a [certificate] file [47mbk.cert[0m. The provisional certification process produces this file as well, but as the last of the following three steps. All of these steps are carried out by calls of [47m[certify-book][0m using its [47m:pcert[0m keyword argument. We typically call these steps ``procedures'', to distinguish them from the steps of an individual call of [47m[certify-book][0m. * The ``Pcertify'' procedure (sometimes called the ``Create'' procedure) is invoked by calling [47m[certify-book][0m with keyword argument [47m:pcert :create[0m. It produces a file [47mbk.pcert0[0m, sometimes called the ``[47m.pcert0[0m'' file (pronounced ``dot pee cert zero''). Proofs are skipped during this procedure, which can be viewed as an elaborate syntax check, augmented by compilation if specified (as it is by default). * The ``Convert'' procedure is invoked by calling [47m[certify-book][0m with keyword argument [47m:pcert :convert[0m. It creates file [47mbk.pcert1[0m from [47mbk.pcert0[0m, by doing proofs for all events in [47mbk.lisp[0m. Note that the third argument (the `[47mcompile-flg[0m' argument) is ignored by such a call of [47mcertify-book[0m unless its value is [47m:all[0m (either explicitly or by way of environment variable [47mACL2_COMPILE_FLG[0m). A subtlety is that if there is a compiled file at least as recent as the corresponding [47m.pcert0[0m file, then that compiled file's write date will be updated to the current time at the end of this procedure. The usual [local-incompatibility] check at the end of [47m[certify-book][0m is omitted for the Convert procedure, since it was performed towards the end of the Create procedure. * The ``Complete'' procedure is invoked by calling [47m[certify-book][0m with keyword argument [47m:pcert :complete[0m. It checks that every included book (including every one that is [47m[local][0mly included) has a [47m.cert[0m file that is at least as recent as the corresponding book. The effect is to move [47mbk.pcert1[0m to [47mbk.cert[0m. Note that all arguments of [47mcertify-book[0m other than the [47m:pcert[0m argument are ignored for this procedure, other than for some trivial argument checking. You can combine the Pcertify and Convert procedures into a single procedure, Pcertify+, which may be useful for books that contain expensive [47m[include-book][0m [events] but do few proofs. We defer discussion of that feature to the section below, ``Combining Pcertify and Convert into Pcertify+''. The main idea of provisional certification is to break sequential dependencies caused by [47m[include-book][0m, that is, so that a book's proofs are carried out even when it includes books (sometimes called ``sub-books'') that have not themselves been fully certified. For example, suppose that a proof development consists of books [47mA.lisp[0m, [47mB.lisp[0m, and [47mC.lisp[0m, where file [47mA.lisp[0m contains the form [47m(include-book "B")[0m and file [47mB.lisp[0m contains the form [47m(include-book "C")[0m. Normally one would first certify [47mC[0m, then [47mB[0m, and finally, [47mA[0m. However, the provisional certification process can speed up the process on a multi-core machine, as follows: the Pcertify (pronounced ``pee certify'') procedure respects this order but (one hopes) is fast since proofs are skipped; the Convert procedure essentially completes the certification in parallel by doing proofs and creating [47m.pcert1[0m files based on [47m.pcert0[0m files; and the Complete procedure respects book order when quickly renaming [47m.pcert1[0m files to [47m.cert[0m files. In our example, the steps would be as follows, but note that we need not finish all Pcertify steps before starting some Convert steps, nor need we finish all Convert steps before starting some Complete steps, as explained further below. * Pcertify books "C", "B",and then "A", sequentially, skipping proofs but doing compilation. * Do proofs in parallel for the books using the Convert procedure, where each book relies on the existence of its own [47m.pcert0[0m file as well as a [47m.cert[0m, [47m.pcert0[0m, or [47m.pcert1[0m file for each of its included sub-books. Write out a [47m.pcert1[0m file for the book when the proof succeeds. * Rename the [47m.pcert1[0m file to a corresponding [47m.cert[0m file when a [47m.cert[0m file exists and is up-to-date for each included book. The Convert step can begin for [47mbk.lisp[0m any time after [47mbk.pcert0[0m is built. The Complete step can begin for this book any time after [47mbk.pcert1[0m and every [47msub-bk.cert[0m are built, for [47msub-bk[0m a sub-book of [47mbk[0m. The new procedures --- Pcertify, Convert, and Complete --- are invoked by supplying a value for the keyword argument [47m:pcert[0m of [47m[certify-book][0m, namely [47m:create[0m, [47m:convert[0m, or [47m:complete[0m, respectively. Typically, and by default, the [47mcompile-flg[0m argument of [47m[certify-book][0m is [47mt[0m for the Pcertify procedure, so that [compilation] can take full advantage of parallelism. This argument is treated as [47mnil[0m for the other procedures except when its value is [47m:all[0m in the Convert procedure, as mentioned above. For those who use [47m[make-event][0m, we note that expansion is done in the Pcertify procedure; the later steps use the expansion resulting from that procedure. The reason is that although a call of [47m[make-event][0m is similar to a macro call, a difference is that the expansion of a [47mmake-event[0m form can depend on the [state]. Therefore, we insist on doing such an expansion only once, so that all books involved agree on the expansion. We say more about [47mmake-event[0m below. [31;1mCorrectness Claim and Issues[0m The Basic Claim for certification is the same whether or not the provisional certification process is employed: all books should be certified from scratch, with no files written to the directories of the books except by ACL2. Moreover, no trust tags should be used (see [defttag]), or else it is the responsibility of the user to investigate every occurrence of ``[47mTTAG NOTE[0m'' that is printed to standard output. But common practice is to certify a set of books in stages: certify a few books, fix some books, re-certify changed books, certify some more books, and so on. In practice, we expect this process to be sound even though it does not meet the preconditions for the Basic Claim above. In particular, we expect that the use of [book-hash] values in [certificate]s will make it exceedingly unlikely that a book is still treated as certified after any events in the book or any sub-book, or any [portcullis] [command]s of the book or any sub-book, have been modified. Provisional certification makes it a bit easier for a determined user to subvert correctness. For example, the Complete procedure only checks write dates to ensure that each sub-book's [47m.cert[0m file is no older than the corresponding [47m.lisp[0m file, but it does not look inside [47m.cert[0m files of sub-books; in particular it does not look at their [book-hash] information. Of course, the automatic dependency analysis provided by classic ACL2 `make'-based certification avoids accidental problems of this sort. And, book-hash information will indeed be applied at [47m[include-book][0m time, at least for sub-books included non-[local]ly. In short: while we believe that the provisional certification process can be trusted, we suggest that for maximum trust, it is best for all books in a project to be certified from scratch without the provisional certification process. [31;1mCombining Pcertify and Convert into Pcertify+[0m You can combine the Pcertify and Convert procedure into a single procedure, Pcertify+, which may be useful for books that contain expensive [47m[include-book][0m [events] but do few proofs. If you are using `make' to do provisional certification as described above, just set `make' variable [47mACL2_BOOKS_PCERT_ARG_T[0m to the list of books for which you want the Pcertify+ procedure performed instead of separate Pcertify and Convert procedures. Either of two common methods may be used to set this variable, as illustrated below for the case that books [47msub.lisp[0m and [47mmid.lisp[0m are the ones on which you want Pcertify+ performed. One method is to add the following to your directory's Makefile, above the [47minclude[0m of [47mMakefile-generic[0m. ACL2_BOOKS_PCERT_ARG_T = sub mid Alternatively, you can specify the desired books on the command line, for example as follows. make -j 4 ACL2_BOOKS_PCERT_ARG_T='sub mid' Note that the books are given without their [47m.lisp[0m extensions. At the ACL2 level, the Pcertify+ procedure is performed when the value [47mt[0m is supplied to the [47m:pcert[0m keyword argument of [47m[certify-book][0m. Thus, [47m:pcert t[0m can be thought of as a combination of [47m:pcert :create[0m and [47m:pcert :convert[0m. However, what ACL2 actually does is to perform the Pcertify step without skipping proofs, and at the end of the [47mcertify-book[0m run, it writes out both the [47m.pcert0[0m and [47m.pcert1[0m file, with essentially the same contents. (We say ``essentially'' because the implementation writes [47m:PCERT-INFO :PROVED[0m to the end of the [47m.pcert0[0m file, but not to the [47m.pcert1[0m file.) [31;1mFurther Information[0m Some errors during provisional certification cannot be readily solved. For example, if there are circular directory dependencies (for example, some book in directory D1 includes some book in directory D2 and vice-versa), then classic ACL2 `make'-based certification will quite possibly fail. For another example, perhaps your directory's Makefile is awkward to convert to one with suitable dependencies. When no fix is at hand, it might be best simply to avoid provisional certification. If you are using classic ACL2 `make'-based certification, you can simply add the following line to your directory's [47mMakefile[0m, or use ``[47mACL2_PCERT= [0m'' on the `make' command line, to avoid provisional certification. override ACL2_PCERT = We invite anyone who has troubleshooting tips to contact the ACL2 developers with suggestions for adding such tips to this section. Our next remark is relevant only to users of [47m[make-event][0m, and concerns the interaction of that utility with state global [47m[ld-skip-proofsp][0m. Normally, the global value of [47m[ld-skip-proofsp][0m is unchanged during [47mmake-event[0m expansion, except that it is bound to [47mnil[0m when the [47mmake-event[0m form has a non-[47mnil[0m [47m:check-expansion[0m argument. But during the Pcertify procedure (not the Pcertify+ procedure), [47m[ld-skip-proofsp][0m is always bound to [47mnil[0m at the start of [47mmake-event[0m expansion. To see why, consider for example the community book [47mbooks/make-event/proof-by-arith.lisp[0m. This book introduces a macro, [47mproof-by-arith[0m, that expands to a call of [47m[make-event][0m. This [47mmake-event[0m form expands by trying to prove a given theorem using a succession of included arithmetic books, until the proof succeeds. Now proofs are skipped during the Pcertify procedure, and if proofs were also skipped during [47mmake-event[0m expansion within that procedure, the first arithmetic book's [47m[include-book][0m form would always be saved because the theorem's proof ``succeeded'' (as it was skipped!). Of course, the theorem's proof could then easily fail during the Convert step. If you really want to inhibit proofs during [47mmake-event[0m expansion in the Pcertify step, consider using a form such as the following: [47m(state-global-let* ((ld-skip-proofsp nil)) ...)[0m. Finally, we describe what it means for there to be a valid [certificate] file for including a certified book. Normally, this is a file with extension [47m.cert[0m. However, if that [47m.cert[0m file does not exist, then ACL2 looks for a [47m.pcert0[0m file instead; and if that also does not exist, it looks for a [47m.pcert1[0m file. (To see why does the [47m.pcert0[0m file take priority over the [47m.pcert1[0m file, note that the Convert procedure copies a [47m.pcert0[0m file to a [47m.pcert1[0m file, so both might exist --- but the [47m.pcert1[0m file might be incomplete if copying is in progress.) Once the candidate certificate file is thus selected, it must be valid in order for the book to be considered certified (see [certificate]). For the certificate file as chosen above, then in order for a compiled file to be loaded, it must be at least as recent as that certificate file. Again, as discussed above, a [47m.pcert0[0m or [47m.pcert1[0m file may serve as a valid certificate file when the [47m.cert[0m file is missing. But when that happens, a warning may be printed that a ``provisionally certified'' book has been included. No such warning occurs if environment variable [47mACL2_PCERT[0m has a non-empty value, or if that warning is explicitly inhibited (see [set-inhibit-warnings] and see [set-inhibit-output-lst]).") (pseudo-term-listp (term acl2-built-ins) "A predicate for recognizing lists of term-like s-expressions See [pseudo-termp] for a predicate that recognizes a term-like s-expression. The predicate [47mpseudo-term-listp[0m tests whether its argument is a list of those. [31;1mFunction: [0m<pseudo-term-listp> (defun pseudo-term-listp (lst) (declare (xargs :guard t)) (cond ((atom lst) (equal lst nil)) (t (and (pseudo-termp (car lst)) (pseudo-term-listp (cdr lst))))))") (pseudo-termp (term acl2-built-ins) "A predicate for recognizing term-like s-expressions Example Forms: (pseudo-termp '(car (cons x 'nil))) ; has value t (pseudo-termp '(car x y z)) ; also has value t! (pseudo-termp '(delta (h x))) ; has value t (pseudo-termp '(delta (h x) . 7)) ; has value nil (not a true-listp) (pseudo-termp '((lambda (x) (car x)) b)) ; has value t (pseudo-termp '(if x y 123)) ; has value nil (123 is not quoted) (pseudo-termp '(if x y '123)) ; has value t If [47mx[0m is the quotation of a term, then [47m(pseudo-termp x)[0m is [47mt[0m. However, if [47mx[0m is not the quotation of a term it is not necessarily the case that [47m(pseudo-termp x)[0m is [47mnil[0m. See [term] for a discussion of the various meanings of the word ``term'' in ACL2. In its most strict sense, a term is either a legal variable symbol, a quoted constant, or the application of an [47mn[0m-ary function symbol or closed [47mlambda[0m-expression to [47mn[0m terms. By ``legal variable symbol'' we exclude constant symbols, such as [47mt[0m, [47mnil[0m, and [47m*ts-rational*[0m. By ``quoted constants'' we include [47m't[0m (aka [47m(quote t)[0m), [47m'nil[0m, [47m'31[0m, etc., and exclude constant names such as [47mt[0m, [47mnil[0m and [47m*ts-rational*[0m, unquoted constants such as [47m31[0m or [47m1/2[0m, and ill-formed [47mquote[0m expressions such as [47m(quote 3 4)[0m. By ``closed lambda expression'' we exclude expressions, such as [47m(lambda (x) (cons x y))[0m, containing free variables in their bodies. Terms typed by the user are translated into strict terms for internal use in ACL2. The predicate [47mtermp[0m checks this strict sense of ``term'' with respect to a given ACL2 logical world; See [world]. Many ACL2 functions, such as the rewriter, require certain of their arguments to satisfy [47mtermp[0m. However, if regarded simply from the perspective of an effective [guard] for a term-processing function, [47mtermp[0m checks many irrelevant things. (Does it really matter that the variable symbols encountered never start and end with an asterisk?) We have therefore introduced the notion of a ``pseudo-term'' and embodied it in the predicate [47mpseudo-termp[0m, which is easier to check, does not require the logical [world] as input, and is often perfectly suitable as a [guard] on term-processing functions. A [47mpseudo-termp[0m is either a symbol, a true list of length 2 beginning with the word [47mquote[0m, the application of an [47mn[0m-ary pseudo-[47mlambda[0m expression to a true list of [47mn[0m pseudo-terms, or the application of a symbol to a true list of [47mn[0m [47mpseudo-termp[0ms. By an ``[47mn[0m-ary pseudo-[47mlambda[0m expression'' we mean an expression of the form [47m(lambda (v1 ... vn) pterm)[0m, where the [47mvi[0m are symbols (but not necessarily distinct legal variable symbols) and [47mpterm[0m is a [47mpseudo-termp[0m. Metafunctions may use [47mpseudo-termp[0m as a [guard].") (pso (output-controls) "Show the most recently saved output Evaluate [47m:pso[0m in order to print output that was generated in an environment where output was being saved, as in [gag-mode], which is active when ACL2 is invoked. Also see [gag-mode]. Example Forms: :pso ; Print saved output. (pso) ; equivalent to the above (pso :all) ; equivalent to the above (pso :all nil) ; equivalent to the above (pso "Subgoal *1/2''") ; Print saved output only for "Subgoal *1/2''". (pso '"Subgoal *1/2'5'" "Subgoal *1/2'14'") ; Print saved output starting with the output ; for '"Subgoal *1/2'5'" and ending just ; before the output for "Subgoal *1/2'14'". (pso '("Subgoal *1/2'5'" "Subgoal *1/2''") '("Subgoal *1/2'14'" "Subgoal *1/2'12'") ; Print saved output ; starting with the output for either ; "Subgoal *1/2'5'" or "Subgoal *1/2''" ; (whichever comes first) ; and stopping just before the output for either ; "Subgoal *1/2'14'" or "Subgoal *1/2'12'" ; (whichever comes first). General Form: (pso start-goals-spec ; optional: default is :ALL stop-goals-spec ; optional: default is NIL ) where both arguments are optional and have the defaults shown above. Thus, the keyword command [47m:pso[0m is equivalent to each of [47m(pso)[0m, [47m(pso :all)[0m, and [47m(pso :all nil)[0m; see [keyword-commands]. The optional arguments restrict the output to specified goals, as follows; but the examples above probably provide an easier way to understand those arguments than the following explanation. * [47mStart-goals-spec[0m represents [3mthe set of start goal names[0m. Its effects are described below. The value [47m:all[0m represents the set of all goal names, a string represents the set consisting of just that one goal name, and a list represents the set of all goal names in that list. * [47mStop-goals-spec[0m represents [3mthe set of stop goal names[0m. Its effects are described below, following the same conventions as above except that [47m:all[0m is not allowed. * Printing begins immediately if [47mstart-goals-spec[0m is [47m:all[0m, else begins with the first goal whose name is in the set of start goal names. * If the set of stop goal names is empty (as is the case when the second optional argument is omitted), then printing takes place only for the first goal whose name is in the set of start goal names. Otherwise, printing continues starting with that goal, stopping only when a goal in the list of stop goal names is encountered, without any printing for that goal. Note that saved prover output is cleared at every top-level prover call, including such calls made by: [events] (e.g., [47m[defthm][0m and [47m[defun][0m), [47m[thm][0m, and [proof-builder] commands that invoke the prover. A single event can make more than one top-level prover call, for example: in the case of [47m[defun][0m, one call made for termination and another for guard verification; and in the case of [47m[defthm][0m, one call made for the proposed theorem and one for each [corollary]. If you want to see more than one proof log for a single top-level form, then instead of using [47m:pso[0m, first evaluate [47m(set-gag-mode nil)[0m. The ``Time'' printed in the summary shows the original times for the proof attempt, not the times for processing the [47m:pso[0m command. Also see [pso!], [psog], [psof], [set-gag-mode], [set-inhibit-output-lst], and [set-print-clause-ids].") (pso! (output-controls) "Show the most recently saved output, including [proof-tree] output [47m:Pso![0m provides output just like [47m:pso[0m, except that [proof-tree] is included; see [47m[pso][0m. [47mPso![0m takes the same optional arguments as [47mpso[0m; see [pso], and also see [psog] and [psof].") (psof (output-controls) "Show the most recently saved output For a similar utility, see [pso]. But unlike [47m:pso[0m, [47m:psof[0m takes a filename argument and writes output to that file, instead of printing to the terminal. For large proofs, [47m:[0m[47m[psof][0m may complete much more quickly than [47m:[0m[47m[pso][0m. The first line of output from [47m:psof[0m directs the Emacs editor to use auto-revert mode. You can change the frequency of auto-reverting the buffer connected to a file by evaluating a suitable command in Emacs. For example, the command [47m(setq auto-revert-interval .1)[0m arranges for auto-revert mode to update as needed every 1/10 of a second. [47mPsof[0m takes the same optional arguments as [47mpso[0m; see [pso], and also see [pso!] and [psog].") (psog (output-controls) "Show the most recently saved output with [gag-mode] [47m:Psog[0m is like [47m:pso[0m --- see [pso] --- but unlike [47m:pso[0m, [47m:psog[0m displays the output in [gag-mode]; more precisely, with gag-mode equal to [47mt[0m. [47mPsog[0m takes the same optional arguments as [47mpso[0m; see [pso], and also see [pso!] and [psof].") (pstack (debugging) "Seeing what the prover is up to General Forms: (pstack) ; inspect break (pstack t) ; inspect break, printing all calls in abbreviated form (pstack :all) ; as above, but only abbreviating the ACL2 world When the form [47m(pstack)[0m is executed during a break from a proof, or at the end of a proof that the user has aborted, a ``process stack'' (or ``prover stack'') will be printed that gives some idea of what the theorem prover has been doing. Moreover, by evaluating [47m(verbose-pstack t)[0m before starting a proof (see [verbose-pstack]) one can get trace-like information about prover functions, including time summaries, printed to the screen during a proof. This feature is currently quite raw and may be refined considerably as time goes on, based on user suggestions. For example, the usual control of printing given by [set-inhibit-output-lst] is irrelevant for printing the pstack. The use of [47m(pstack t)[0m or [47m(pstack :all)[0m should only be used by those who are comfortable looking at functions in the ACL2 source code. Otherwise, simply use [47m(pstack)[0m. Entries in the pstack include the following (listed here alphabetically, except for the first). [47mpreprocess-clause[0m, [47msimplify-clause[0m, etc. (in general,[47mxxx-clause[0m): top-level processes in the prover ``waterfall'' [47mclausify[0m: splitting a goal into subgoals [47mev-fncall[0m: evaluating a function on explicit arguments [47mev-fncall+[0m: evaluating a function on explicit arguments while assuming that [warrant] hypotheses are true [47mev-fncall-meta[0m: evaluating a metafunction [47mforward-chain[0m: building a context for the current goal using [47m[forward-chaining][0m rules [47minduct[0m: finding an induction scheme [47mpop-clause[0m: getting the next goal to prove by induction [47mprocess-assumptions[0m: creating forcing rounds [47mremove-built-in-clauses[0m: removing built-in [clause]s (see [built-in-clause]) [47mprocess-equational-polys[0m: deducing interesting equations [47mremove-trivial-equivalences[0m: removing trivial equalities (and equivalences) from the current goal [47mrewrite-atm[0m: rewriting a top-level term in the current goal [47msetup-simplify-clause-pot-lst[0m: building the linear arithmetic database for the current goal [47mstrip-branches[0m, [47msubsumption-replacement-loop[0m: subroutines of [47mclausify[0m [47mwaterfall[0m: top-level proof control Subtopics [Verbose-pstack] Seeing what the prover is up to (for system hackers)") (puff (history) "Replace a compound [command] by its immediate subevents Example Forms: ACL2 !>:puff :max ACL2 !>:puff :x ACL2 !>:puff 15 ACL2 !>:puff "book" General Form: :puff cd where [47mcd[0m is a [command] descriptor (see [command-descriptor]) for a ``puffable'' [command] (see below). [47mPuff[0m replaces the [command] at [47mcd[0m by the immediate subevents of the [command], executed as [command]s. [47mPuff[0m then prints, using [47m[pcs][0m, the [47mpuff[0med region. We consider [47mpuff[0m to be a sort of hack; it is generally robust and sound, but that is not guaranteed. If any existing ACL2 event resulted from [47mpuff[0m, ACL2 considers proofs to have been skipped, and thus [47m[certify-book][0m is disallowed until such events have been undone (see [ubt]). Other than the few exceptions noted later below, a ``puffable'' [command] is an [47m[encapsulate][0m, [47m[include-book][0m, or [47m[certify-book][0m [command], or any command other than those consisting of a single primitive event. For example, since [47m[defun][0m is a primitive event, a [47m[defun][0m command is not puffable. But a macro form that expands into one or more [events] is puffable. The only primitive events that are puffable are calls of [47m[encapsulate][0m or [47m[include-book][0m. In this sense, [47m[make-event][0m is not considered primitive --- that is, it can be puffed --- and moreover, an immediate subevent that is a call of [47mmake-event[0m is generally replaced by its expansion (see [make-event]). A puffable [command] contains (interesting) subevents, namely, the events in the body of the [47m[encapsulate][0m, in the file of the book included, or in the [command] block. The puff [command] ``lifts'' the immediate subevents of the indicated [command] so that they become [command]s themselves. The [command] [47m[puff*][0m recursively puffs the newly introduced [command]s. See [puff*], which also gives an example illustrating both [47mpuff[0m and [47m[puff*][0m. [47mPuff[0m undoes the [command] at [47mcd[0m and replaces it by its immediate subevents. Thus, in general the length of the [history] grows when a puff [command] is executed. If [47mpuff[0m causes an error (see below), the logical [world] remains unchanged from its initial configuration. The intended use of [47mpuff[0m is to allow the user access to the [events] ``hidden'' inside compound [command]s. For example, while trying to prove some theorem, [47mp[0m, about a constrained function, [47mfn[0m, one might find that the [47m[encapsulate][0m, [47mcd[0m, that introduced [47mfn[0m failed to include an important [constraint], [47mq[0m. Without [47mpuff[0m, the only way to proceed is to undo back through [47mcd[0m, create a suitable [47m[encapsulate][0m that proves and exports [47mq[0m as well as the old [constraint]s, re-execute the new [47m[encapsulate][0m, re-execute the [events] since [47mcd[0m, and then try [47mp[0m again. Unfortunately, it may be hard to prove [47mq[0m and additional [events] may have to be inserted into the [47m[encapsulate][0m to prove it. It may also be hard to formulate the ``right'' [47mq[0m, i.e., one that is provable in the [47m[encapsulate][0m and provides the appropriate facts for use in the proof of [47mp[0m. Using [47mpuff[0m, the user can erase the [47m[encapsulate][0m at [47mcd[0m, replacing it by the [events] in its body. Now the formerly constrained function, [47mfn[0m, is defined as its witness. The user can experiment with formulations and proofs of [47mq[0m suitable for [47mp[0m. Of course, to get into the ultimately desired [state] --- where [47mfn[0m is constrained rather than defined and [47mq[0m is exported by an [47m[encapsulate][0m at [47mcd[0m --- the user must ultimately undo back to [47mcd[0m and carry out the more tedious program described above. But by using [47mpuff[0m it is easier to experiment. Similar applications of [47mpuff[0m allow the user of a book to expose the top-level [events] in the book as though they had all been typed as [command]s. The user might then ``partially undo'' the book, keeping only some of the events in it. [47mPuff[0m operates as follows. First, it determines the list of immediate subevents of the [command] indicated by [47mcd[0m. It causes an error if there is only one subevent and that subevent is identical to the [command] --- i.e., if the [command] at [47mcd[0m is a primitive. Next, [47mpuff[0m undoes back through the indicated [command]. This not only erases the [command] at [47mcd[0m but all the [command]s executed after it. Finally, [47mpuff[0m re-executes the subevents of (the now erased) [47mcd[0m followed by all the [command]s that were executed afterwards. Observe that the [command]s executed after [47mcd[0m will generally have higher [command] numbers than they did before the puff. For example, suppose 100 [command]s have been executed and that [47m:puff 80[0m is then executed. Suppose [command] 80 contains 5 immediate subevents (i.e., is an encapsulation of five [events]). Then, after puffing, [command] 80 is the first event of the puffed [command], [command] 81 is the second, and so on; 104 [command]s appear to have been executed. When puffing an [47m[encapsulate][0m or [47m[include-book][0m, the [47m[local][0m [command]s are executed. Note that this will replace constrained functions by their witnesses. Here are some details and a few exceptions. * An [47m[encapsulate][0m command that generates [unknown-constraints], such as one generated by the macro [47m[define-trusted-clause-processor][0m, is not puffable. * When an [47m[encapsulate][0m has a non-empty [signature], it is not puffable if the `puff' command issued is [47m:[0m[47m[puff*][0m, rather than [47m:[0m[47mpuff[0m. That is because puffing may fail in this case, as discussed immediately below, and it may be annoying to deal with the failure, for example if [47m:puff*[0m takes a long time to run. * An attempt to puff may fail for an [47m[encapsulate][0m with a non-empty [signature] that contains at least one use of [47m[make-event][0m and also comes from a certified book. The reason is that local definitions may be elided. Here is an example of such a book. (in-package "ACL2") (encapsulate ((f (x) t)) (make-event '(local (defun f (x) (cons x x)))) (defthm f-prop (consp (f x)))) If we first certify this book, then we include it in a new ACL2 session, and next we issue the command [47m:puff 1[0m, then we can see that the local definition in our [47mencapsulate[0m event has been elided: ACL2 !>:pcb! 1 1 (ENCAPSULATE ((F (X) T)) (RECORD-EXPANSION (MAKE-EVENT '(LOCAL (DEFUN F (X) (CONS X X)))) (LOCAL (VALUE-TRIPLE :ELIDED))) (DEFTHM F-PROP (CONSP (F X)))) (DEFTHM F-PROP (CONSP (F X))) ACL2 !> Now an attempt to execute the command, [47m:puff 1[0m, causes an error because [47mf[0m lacks a definition. ACL2 !>:puff 1 ACL2 Error in ( DEFTHM F-PROP ...): The symbol F (in package "ACL2") has neither a function nor macro definition in ACL2. Please define it. See :DOC near-misses. Note: this error occurred in the context (F X). ACL2 !> * Similarly, a [47m[local][0m event that involves [47m[make-event][0m expansion may be elided when the event is from a book whose [47m[include-book][0m form has been puffed. This will result in an error if the elided event is necessary to support later events in the [47mpuff[0m of the command. Here is an example, where the attempt to puff an [47minclude-book[0m for this book will fail, giving an error for [47m( DEFUN G ...)[0m stating that the symbol [47mF[0m has not been defined. (in-package "ACL2") (make-event '(local (defun f (x) x))) (local (defun g (x) (f x))) * An attempt to [47mpuff[0m an [47m[include-book][0m command may fail for a book that has been modified, as described later in this documentation topic. * The [47mpuff[0m of an [47m[include-book][0m command for an uncertified book will simply expose the contents of the book. However, if the book is certified then the [47mpuff[0m will replace each event by its [47m[make-event][0m expansion. Also, ACL2 considers that (certified) book to have been included; future attempts to include that book will be considered to be [redundant]. Finally, we note that it is an error to [47mpuff[0m in the presence of [47m[include-book][0m [events] for certified books that have been altered since they were included. (Note that this restriction only applies to [47m[include-book][0m, not to [47m[certify-book][0m.) To be specific, suppose [47m"arith"[0m is a certified book that has been included in a session. Suppose that after [47m"arith"[0m was included, the source file is modified. (This might happen if the user of [47m"arith"[0m is not its author and the author happens to be working on a new version of [47m"arith"[0m during the same time period.) Now suppose the user tries to [47mpuff[0m the [command] that included [47m"arith"[0m. The attempt to obtain the subevents in [47m"arith"[0m will discover that the [book-hash] of [47m"arith"[0m has changed and an error will be caused. No change is made in the logical [world]. A similar error is caused if, in this same situation, the user tries to puff any command that occurred before the inclusion of [47m"arith"[0m! That is, [47mpuff[0m may cause an error and leave the [world] unchanged even if the [command] puffed is not one involving the modified book. This happens because in order to reconstruct the [world] after the puffed [command], [47mpuff[0m must obtain the [events] in the book and if the book's source file has changed there is no assurance that the reconstructed [world] is the one the user intends. Warning: We do not detect changes to uncertified [books] that have been included and are then puffed or re-included! The act of including an uncertified book leaves no trace of the [book-hash] value for the book. Furthermore, the act prints a warning message disclaiming soundness. In light of this, [47m:puff[0m quietly ``re-''executes the current contents of the book.") (puff* (history) "Replace a compound [command] by its subevents Example Forms: ACL2 !>:puff* :max ACL2 !>:puff* :x ACL2 !>:puff* 15 ACL2 !>(puff* 15) ; same as just above ACL2 !>(puff* 15 t) ; same as just above, but keep partial results ACL2 !>:puff* "book" General Forms: :puff* cd (puff* 'cd) ; argument can be any expression evaluating to cd (puff* 'cd b) ; where b is t or nil where [47mcd[0m is a [command] descriptor (see [command-descriptor]). See [puff] for the definition of ``puffable'' and for a description of the basic act of ``puffing'' a [command]. [47mPuff*[0m is just the recursive application of [puff]: it puffs not only the indicated command, but all of the commands thus generated, and recursively until none of the resulting commands can be puffed. As noted in the documentation for [puff], [47m:puff[0m should be viewed as a sort of hack; hence so should [47mpuff*[0m. [47mPuff*[0m prints the region [puff]ed, using [47m[pcs][0m. Thus, to [puff] a [command] is to replace it by its immediate subevents, each of which is executed as a [command]. To [47mpuff*[0m a [command] is to replace the [command] by each of its immediate subevents and then to [47mpuff*[0m each of the puffable [command]s among the newly introduced ones. NOTE: because one call of [47m:puff*[0m may give rise to many calls of [47m:puff[0m, it can take considerable time for a call of [47m:puff*[0m to complete when many books are involved. For example, suppose [47m"ab"[0m is a book containing the following (in-package "ACL2") (include-book "a") (include-book "b") Suppose that book [47m"a"[0m only contained [47m[defun][0ms for the functions [47ma1[0m and [47ma2[0m and that [47m"b"[0m only contained [47m[defun][0ms for [47mb1[0m and [47mb2[0m. Now consider an ACL2 [state] in which only two [command]s have been executed, the first being [47m(include-book "ab")[0m and the second being [47m(include-book "c")[0m. Thus, the relevant part of the display produced by [47m:[0m[47m[pbt][0m 1 would be: 1 (INCLUDE-BOOK "ab") 2 (INCLUDE-BOOK "c") Call this [state] the ``starting [state]'' in this example, because we will refer to it several times. Suppose [47m:puff 1[0m is executed in the starting [state]. Then the first [command] is replaced by its immediate subevents and [47m:pbt 1[0m would show: 1 (INCLUDE-BOOK "a") 2 (INCLUDE-BOOK "b") 3 (INCLUDE-BOOK "c") Contrast this with the execution of [47m:puff* 1[0m in the starting [state]. [47mPuff*[0m would first [puff] [47m(include-book "ab")[0m to get the [state] shown above. But then it would recursively [47mpuff*[0m the puffable [command]s introduced by the first [puff]. This continues recursively as long as any [puff] introduced a puffable [command]. The end result of [47m:puff* 1[0m in the starting [state] is 1 (DEFUN A1 ...) 2 (DEFUN A2 ...) 3 (DEFUN B1 ...) 4 (DEFUN B2 ...) 5 (INCLUDE-BOOK "c") Observe that when [47mpuff*[0m is done, the originally indicated [command], [47m(include-book "ab")[0m, has been replaced by the corresponding sequence of primitive [events]. Observe also that puffable [command]s elsewhere in the [history], for example, [command] 2 in the starting [state], are not affected (except that their [command] numbers grow as a result of the splicing in of earlier [command]s). [47m:Puff*[0m may cause an error, for example because of a name conflict caused by two different local lemmas with the same name, or because a [47m[local][0m event in a book has been elided (see [puff]). By default, the logical [world] is reverted to its value before that execution of [47mpuff*[0m. However, if the optional Boolean second argument is [47mt[0m, then the world is preserved from the successful [47m:puff[0m commands executed before the failed one. That behavior can help with debugging, since both the warning message and the return value tell you which command could not be puffed successfully.") (push-untouchable (defttag) "Add name or list of names to the list of untouchable symbols Untouchables are functions that cannot be called, as well as [state] global variables (see [programming-with-state]) that cannot be modified or unbound. Macros can also be untouchable in some sense; see [defmacro-untouchable]. Examples: (push-untouchable my-var nil) (push-untouchable set-mem t) General Form: (push-untouchable name{s} fn-p) where [47mname{s}[0m is a non-[47mnil[0m symbol or a non-[47mnil[0m true list of symbols, and [47mfn-p[0m is any value (but generally [47mnil[0m or [47mt[0m). If [47mname{s}[0m is a symbol it is treated as the singleton list containing that symbol. The effect of this event is to union the given symbols into the list of ``untouchable variables'' in the current world if [47mfn-p[0m is [47mnil[0m, else to union the symbols into the list of ``untouchable functions''. This event is redundant if every symbol listed is already a member of the appropriate untouchables list (variables or functions). There is a further restriction on which function names may be made untouchable: If a function symbol, [47mg[0m, may be introduced into a proof by a metatheorem (via the metafunction or the hypothesis metafunction) or by a clause processor and the metatheorem or clause processor has a [47m:[0m[47m[well-formedness-guarantee][0m then [47mg[0m may not be made untouchable. As noted above, macros may not be made directly untouchable; the macro [47m[defmacro-untouchable][0m is provided for that purpose. Thus, it is an error to evaluate [47m(push-untouchable F t)[0m if [47mF[0m is already a macro name, and it is also an error to define [47mF[0m as a macro when [47mF[0m has been made an untouchable function using [47m(push-untouchable F t)[0m. When a symbol is on the untouchables list it is syntactically illegal for any event to call a function of that name, if [47mfn-p[0m is non-[47mnil[0m, or to change the value of a state global variable of that name, if [47mfn-p[0m is [47mnil[0m. Thus, the effect of pushing a function symbol, [47mname[0m, onto untouchables is to prevent any future event from using that symbol as a function, or as a state global variable (according to [47mfn-p[0m). This is generally done to ``fence off'' some primitive function symbol from ``users'' after the developer has used the symbol freely in the development of some higher level mechanism. Also see [remove-untouchable].") (put-assoc (alists acl2-built-ins) "Modify an association list by associating a value with a key General Forms: (put-assoc name val alist) (put-assoc name val alist :test 'eql) ; same as above (eql as equality test) (put-assoc name val alist :test 'eq) ; same, but eq is equality test (put-assoc name val alist :test 'equal) ; same, but equal is equality test [47m(Put-assoc name val alist)[0m returns an alist that is the same as the list [47malist[0m, except that the first pair in [47malist[0m with a [47m[car][0m of [47mname[0m is replaced by [47m(cons name val)[0m, if there is one. If there is no such pair, then [47m(cons name val)[0m is added at the end. Note that the order of the keys occurring in [47malist[0m is unchanged (though a new key may be added). The [guard] for a call of [47mput-assoc[0m depends on the test. In all cases, the last argument must satisfy [47m[alistp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the last argument must satisfy [47m[eqlable-alistp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the last argument must satisfy [47m[symbol-alistp][0m. See [equality-variants] for a discussion of the relation between [47mput-assoc[0m and its variants: [47m(put-assoc-eq name val alist)[0m is equivalent to [47m(put-assoc name val alist :test 'eq)[0m; [47m(put-assoc-equal name val alist)[0m is equivalent to [47m(put-assoc name val alist :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mput-assoc-equal[0m. [31;1mFunction: [0m<put-assoc-equal> (defun put-assoc-equal (name val alist) (declare (xargs :guard (alistp alist))) (cond ((endp alist) (list (cons name val))) ((equal name (caar alist)) (cons (cons name val) (cdr alist))) (t (cons (car alist) (put-assoc-equal name val (cdr alist))))))") (put-assoc-eq (pointers) "See [put-assoc].") (put-assoc-eql (pointers) "See [put-assoc].") (put-assoc-equal (pointers) "See [put-assoc].") (putprop (world acl2-built-ins) "Update fast property lists General form: (putprop symbol key value world-alist) See [world] for discussion of both utilities [47m[getprop][0m and [47mputprop[0m. Also see community book [47mbooks/misc/getprop.lisp[0m for an example that illustrates the use of ACL2 utilities [47mgetprop[0m and [47mputprop[0m to take advantage of under-the-hood Lisp (hashed) property lists. [31;1mFunction: [0m<putprop> (defun putprop (symb key value world-alist) (declare (xargs :guard (and (symbolp symb) (symbolp key) (plist-worldp world-alist)))) (cons (cons symb (cons key value)) world-alist))") (q (lp) "Quit ACL2 (type [47m:q[0m) --- reenter with [47m(lp)[0m Example: ACL2 !>:Q The keyword command [47m:q[0m typed at the top-level of the ACL2 loop will terminate the loop and return control to the Common Lisp top-level (or, more precisely, to whatever program invoked [47m[lp][0m). To reenter the ACL2 loop, execute [47m(acl2::lp)[0m in Common Lisp. You will be in the same state as you were when you exited with [47m:q[0m, unless during your stay in Common Lisp you messed with the data structures representing the ACL2 [state] (including files, property lists, and single-threaded objects). You may also issue the command [47m(value :q)[0m to exit the ACL2 loop. More generally, if the result of evaluating a form in the ACL2 loop is the [error-triple] [47m(nil :q state)[0m, the ACL2 loop will be exited. WARNING: The issuance of commands to raw Lisp may render your ACL2 session unsound. Furthermore, evaluation of forms after exiting the ACL2 loop with [47m:q[0m (or [47m(value :q)[0m, etc.) is not guaranteed to agree with their evaluation in the ACL2 loop. Specifically, Common Lisp may read an expression with the backquote character ([47m`[0m) differently from how ACL2 reads the expression. (The technical reason, in Common Lisp parlance, is that ACL2 installs its own readtable in the ACL2 loop, which includes a custom backquote reader.) Results of evaluation may have surprising differences depending on whether evaluation takes place in the ACL2 loop or in raw Lisp, as illustrated by the following log produced using an ACL2 executable built on SBCL. ACL2 !>(car (quote `(a b c))) QUOTE ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). * (car (quote `(a b c))) SB-INT:QUASIQUOTE * To minimize discrepancies (including that one) between ACL2 and raw Lisp, use [raw-mode] instead of exiting the ACL2 loop. Unlike all other keyword commands, typing [47m:q[0m is not equivalent to invoking the function [47mq[0m. There is no function [47mq[0m.") (quantifier-tutorial (defun-sk) "A Beginner's Guide to Reasoning about Quantification in ACL2 The initial version of this tutorial was written by Sandip Ray. Additions and revisions are welcome. Sandip has said: ``This is a collection of notes that I wrote to remind myself of how to reason about quantifiers when I just started. Most users after they have gotten the hang of quantifiers probably will not need this and will be able to use their intuitions to guide them in the process. But since many ACL2 users are not used to quantification, I am hoping that this set of notes might help them to think clearly while reasoning about quantifiers in ACL2.'' Many ACL2 papers start with the sentence ``ACL2 is a quantifier-free first-order logic of recursive functions.'' It is true that the [3msyntax[0m of ACL2 is quantifier-free; every formula is assumed to be universally quantified over all free variables in the formula. But the [3mlogic[0m in fact does afford arbitrary first-order quantification. This is obtained in ACL2 using a construct called [47mdefun-sk[0m. See [defun-sk]. Many ACL2 users do not think in terms of [quantifiers]. The focus is almost always on defining recursive functions and reasoning about them using induction. That is entirely justified, in fact, since proving theorems about recursive functions by induction plays to the strengths of the theorem prover. Nevertheless there are situations where it is reasonable and often useful to think in terms of quantifiers. However, reasoning about quantifiers requires that you get into the mindset of thinking about theorems in terms of quantification. This note is about how to do this effectively given ACL2's implementation of quantification. This does not discuss [47m[defun-sk][0m in detail, but merely shows some examples. A detailed explanation of the implementation is in the ACL2 [documentation] (see [defun-sk]); also see [conservativity-of-defchoose]. [Note: Quantifiers can be used for some pretty cool things in ACL2. Perhaps the most interesting example is the way of using quantifiers to introduce arbitrary tail-recursive equations; see the paper ``Partial Functions in ACL2'' by Panagiotis Manolios and J Strother Moore. This note does not address applications of quantifiers, but merely how you would reason about them once you think you want to use them.] Assume that you have some function [47mP[0m. I have just left [47mP[0m as a unary function stub below, since I do not care about what [47mP[0m is. (defstub P (*) => *) Now suppose you want to specify the concept that ``there exists some [47mx[0m such that [47m(P x)[0m holds''. ACL2 allows you to write that directly using quantifiers. (defun-sk exists-P () (exists x (P x))) If you submit the above form in ACL2 you will see that the theorem prover specifies two functions [47mexists-p[0m and [47mexists-p-witness[0m, and exports the following constraints: 1. (defun exists-P () (P (exists-P-witness))) 2. (defthm exists-P-suff (implies (p x) (exists-p))) Here [47mexists-P-witness[0m is a new function symbol in the current ACL2 theory. What do the constraints above say? Notice the constraint [47mexists-p-suff[0m. It says that if you can provide any [47mx[0m such that [47m(P x)[0m holds, then you know that [47mexists-p[0m holds. Think of the other constraint (definition of [47mexists-p[0m) as going the other way. That is, it says that if [47mexists-p[0m holds, then there is some [47mx[0m, call it [47m(exists-p-witness)[0m, for which [47mP[0m holds. Notice that nothing else is known about [47mexists-p-witness[0m than the two constraints above. [Note: [47mexists-p-witness[0m above is actually defined in ACL2 using a special form called [47mdefchoose[0m. See [defchoose]. This note does not talk about [47mdefchoose[0m. So far as this note is concerned, think of [47mexists-p-witness[0m as a new function symbol that has been generated somehow in ACL2, about which nothing other than the two facts above is known.] Similarly, you can talk about the concept that ``for all [47mx[0m [47m(P x)[0m holds.'' This can be specified in ACL2 by the form: (defun-sk forall-P () (forall x (P x))) This produces the following two constraints: 1. (defun forall-P () (P (forall-p-witness))) 2. (defthm forall-p-necc (implies (not (P x)) (not (forall-p)))) To understand these, think of [47mforall-p-witness[0m as producing some [47mx[0m which does not satisfy [47mP[0m, if such a thing exists. The constraint [47mforall-p-necc[0m merely says that if [47mforall-p[0m holds then [47mP[0m is satisfied for every [47mx[0m. (To see this more clearly, just think of the contrapositive of the formula shown.) The other constraint (definition of [47mforall-p[0m) implies that if [47mforall-p[0m does not hold then there is some [47mx[0m, call it [47m(forall-p-witness)[0m, which does not satisfy [47mP[0m. To see this, just consider the following formula which is immediately derivable from the definition. (implies (not (forall-p)) (not (P (forall-witness)))) The description above suggests that to reason about quantifiers, the following Rules of Thumb, familiar to most any student of logic, are useful. RT1: To prove [47m(exists-p)[0m, construct some object [47mA[0m such that [47mP[0m holds for [47mA[0m and then use [47mexists-P-suff[0m. RT2: If you assume [47mexists-P[0m in your hypothesis, use the definition of [47mexists-p[0m to know that [47mP[0m holds for [47mexists-p-witness[0m. To use this to prove a theorem, you must be able to derive the theorem based on the hypothesis that [47mP[0m holds for something, whatever the something is. RT3: To prove [47mforall-P[0m, prove the theorem [47m(P x)[0m (that is, that [47mP[0m holds for an arbitrary [47mx[0m), and then simply instantiate the definition of [47mforall-p[0m, that is, show that [47mP[0m holds for the witness. RT4: If you assume [47mforall-p[0m in the hypothesis of the theorem, see how you can prove your conclusion if indeed you were given [47m(P x)[0m as a theorem. Possibly for the conclusion to hold, you needed that [47mP[0m holds for some specific set of [47mx[0m values. Then use the theorem [47mforall-p-necc[0m by instantiating it for the specific [47mx[0m values you care about. Perhaps the above is too terse. In the remainder of the note, we will consider several examples of how this is done to prove theorems in ACL2 that involve quantified notions. Let us consider two trivial theorems. Assume that for some unary function [47mr[0m, you have proved [47m(r x)[0m as a theorem. Let us see how you can prove that (1) there exists some x such that [47m(r x)[0m holds, and (2) for all [47mx[0m [47m(r x)[0m holds. We first model these things using [47m[defun-sk][0m. Below, [47mr[0m is simply some function for which [47m(r x)[0m is a theorem. (encapsulate (((r *) => *)) (local (defun r (x) (declare (ignore x)) t)) (defthm r-holds (r x))) (defun-sk exists-r () (exists x (r x))) (defun-sk forall-r () (forall x (r x))) ACL2 does not have too much reasoning support for quantifiers. So in most cases, one would need [47m:use[0m hints to reason about quantifiers. In order to apply [47m:use[0m [hints], it is preferable to keep the function definitions and theorems disabled. (in-theory (disable exists-r exists-r-suff forall-r forall-r-necc)) Let us now prove that there is some [47mx[0m such that [47m(r x)[0m holds. Since we want to prove [47mexists-r[0m, we must use [47mexists-r-suff[0m by RT1. We do not need to construct any instance here since [47mr[0m holds for all [47mx[0m by the theorem above. (defthm exists-r-holds (exists-r) :hints (("Goal" :use ((:instance exists-r-suff))))) Let us now prove the theorem that for all [47mx[0m, [47m(r x)[0m holds. By RT3, we must be able to prove it by definition of [47mforall-r[0m. (defthm forall-r-holds (forall-r) :hints (("Goal" :use ((:instance (:definition forall-r)))))) [Note: Probably no ACL2 user in his or her right mind would prove the theorems [47mexists-r-holds[0m and [47mforall-r-holds[0m above. The theorems shown are only for demonstration purposes.] For the remainder of this note we will assume that we have two stubbed out unary functions [47mM[0m and [47mN[0m, and we will look at proving some quantified properties of these functions. (defstub M (*) => *) (defstub N (*) => *) Let us now define the predicates [47mall-M[0m, [47mall-N[0m, [47msome-M[0m, and [47msome-N[0m specifying the various quantifications. (defun-sk all-M () (forall x (M x))) (defun-sk all-N () (forall x (N x))) (defun-sk some-M () (exists x (M x))) (defun-sk some-N () (exists x (N x))) (in-theory (disable all-M all-N all-M-necc all-N-necc)) (in-theory (disable some-M some-N some-M-suff some-N-suff)) Let us prove the classic distributive properties of quantification: the distributivity of universal quantification over conjunction, and the distributivity of existential quantification over disjunction. We can state these properties informally in ``pseudo ACL2'' notation as follows: 1. (exists x: (M x)) or (exists x: (N x)) <=> (exists x: (M x) or (N x)) 2. (forall x: (M x)) and (forall: x (N x)) <=> (forall x: (M x) and (N x)) To make these notions formal we of course need to define the formulas at the right-hand sides of 1 and 2. So we define [47msome-MN[0m and [47mall-MN[0m to capture these concepts. (defun-sk some-MN () (exists x (or (M x) (N x)))) (defun-sk all-MN () (forall x (and (M x) (N x)))) (in-theory (disable all-MN all-MN-necc some-MN some-MN-suff)) First consider proving property 1. The formal statement of this theorem would be: [47m(iff (some-MN) (or (some-M) (some-N)))[0m. How do we prove this theorem? Looking at RT1-RT4 above, note that they suggest how one should reason about quantification when one has an ``implication''. But here we have an ``equivalence''. This suggests another rule of thumb. RT5: Whenever possible, prove an equivalence involving quantifiers by proving two implications. Let us apply RT5 to prove the theorems above. So we will first prove: [47m(implies (some-MN) (or (some-M) (some-N)))[0m How can we prove this? This involves assuming a quantified predicate [47m(some-MN)[0m, so we must use RT2 and apply the definition of [47msome-MN[0m. Since the conclusion involves a disjunction of two quantified predicates, by RT1 we must be able to construct two objects [47mA[0m and [47mB[0m such that either [47mM[0m holds for [47mA[0m or [47mN[0m holds for [47mB[0m, so that we can then invoke [47msome-M-suff[0m and [47msome-N-suff[0m to prove the conclusion. But now notice that if [47msome-MN[0m is true, then there is already an object, in fact [47msome-MN-witness[0m, such that either [47mM[0m holds for it, or [47mN[0m holds for it. And we know this is the case from the definition of [47msome-MN[0m! So we will simply prove the theorem instantiating [47msome-M-suff[0m and [47msome-N-suff[0m with this witness. The conclusion is that the following event will go through with ACL2. (defthm le1 (implies (some-MN) (or (some-M) (some-N))) :rule-classes nil :hints (("Goal" :use ((:instance (:definition some-MN)) (:instance some-M-suff (x (some-MN-witness))) (:instance some-N-suff (x (some-MN-witness))))))) This also suggests the following rule of thumb: RT6: If a conjecture involves assuming an existentially quantified predicate in the hypothesis from which you are trying to prove an existentially quantified predicate, use the witness of the existential quantification in the hypothesis to construct the witness for the existential quantification in the conclusion. Let us now try to prove the converse of le1, that is: [47m(implies (or (some-M) (some-N)) (some-MN))[0m Since the hypothesis is a disjunction, we will just prove each case individually instead of proving the theorem by a [47m:[0m[47mcases[0m hint. So we prove the following two lemmas. (defthm le2 (implies (some-M) (some-MN)) :rule-classes nil :hints (("Goal" :use ((:instance (:definition some-M)) (:instance some-MN-suff (x (some-M-witness))))))) (defthm le3 (implies (some-N) (some-MN)) :rule-classes nil :hints (("Goal" :use ((:instance (:definition some-N)) (:instance some-MN-suff (x (some-N-witness))))))) Note that the hints above are simply applications of RT6 as in [47mle1[0m. With these lemmas, of course the main theorem is trivial. (defthmd |some disjunction| (iff (some-MN) (or (some-M) (some-N))) :hints (("Goal" :use ((:instance le1) (:instance le2) (:instance le3))))) Let us now prove the distributivity of universal quantification over conjunction, that is, the formula: [47m(iff (all-MN) (and (all-M) (all-N)))[0m Applying RT5, we will again decompose this into two implications. So consider first the one-way implication: [47m(implies (and (all-M) (all-N)) (all-MN))[0m. Here we get to assume [47mall-M[0m and [47mall-N[0m. Thus by RT4 we can use [47mall-M-necc[0m and [47mall-N-necc[0m to think as if we are given the formulas [47m(M x)[0m and [47m(N x)[0m as theorems. The conclusion here is also a universal quantification, namely we have to prove [47mall-MN[0m. Then RT3 tells us to proceed as follows. Take any object [47my[0m. Try to find an instantiation [47mz[0m of the hypothesis that implies [47m(and (M y) (N y))[0m. Then instantiate [47my[0m with [47mall-MN-witness[0m. Note that the hypothesis lets us assume [47m(M x)[0m and [47m(N x)[0m to be theorems. Thus to justify we need to instantiate [47mx[0m with [47my[0m, and in this case, therefore, with [47mall-MN-witness[0m. To make the long story short, the following event goes through with ACL2: (defthm lf1 (implies (and (all-M) (all-N)) (all-MN)) :rule-classes nil :hints (("Goal" :use ((:instance (:definition all-MN)) (:instance all-M-necc (x (all-MN-witness))) (:instance all-N-necc (x (all-MN-witness))))))) This suggests the following rule of thumb which is a dual of RT6: RT7: If a conjecture assumes some universally quantified predicate in the hypothesis and its conclusion asserts a universally quantified predicate, then instantiate the ``necessary condition'' ([47mforall-mn-necc[0m) of the hypothesis with the witness of the conclusion to prove the conjecture. Applying RT7 now we can easily prove the other theorems that we need to show that universal quantification distributes over conjunction. Let us just go through this motion in ACL2. (defthm lf2 (implies (all-MN) (all-M)) :rule-classes nil :hints (("Goal" :use ((:instance (:definition all-M)) (:instance all-MN-necc (x (all-M-witness))))))) (defthm lf3 (implies (all-MN) (all-N)) :rule-classes nil :hints (("Goal" :use ((:instance (:definition all-N)) (:instance all-MN-necc (x (all-N-witness))))))) (defthmd |all conjunction| (iff (all-MN) (and (all-M) (all-N))) :hints (("Goal" :use ((:instance lf1) (:instance lf2) (:instance lf3))))) The rules of thumb for universal and existential quantification should make you realize the duality of their use. Every reasoning method about universal quantification can be cast as a way of reasoning about existential quantification, and vice versa. Whether you reason using universal and existential quantifiers depends on what is natural in a particular context. But just for the sake of completeness let us prove the duality of universal and existential quantifiers. So what we want to prove is the following: 3. (forall x (not (M x))) = (not (exists x (M x))) We first formalize the notion of [47m(forall x (not (M x)))[0m as a quantification. (defun-sk none-M () (forall x (not (M x)))) (in-theory (disable none-M none-M-necc)) So we now want to prove: [47m(equal (none-M) (not (some-M)))[0m. As before, we should prove this as a pair of implications. So let us prove first: [47m(implies (none-M) (not (some-M)))[0m. This may seem to assert an existential quantification in the conclusion, but rather, it asserts the [3mnegation[0m of an existential quantification. We are now trying to prove that something does not exist. How do we do that? We can show that nothing satisfies [47mM[0m by just showing that [47m(some-M-witness)[0m does not satisfy [47mM[0m. This suggests the following rule of thumb: RT8: When you encounter the negation of an existential quantification think in terms of a universal quantification, and vice-versa. Ok, so now applying RT8 and RT3 you should be trying to apply the definition of [47msome-M[0m. The hypothesis is just a pure (non-negated) universal quantification so you should apply RT4. A blind application lets us prove the theorem as below. (defthm nl1 (implies (none-M) (not (some-M))) :rule-classes nil :hints (("Goal" :use ((:instance (:definition some-M)) (:instance none-M-necc (x (some-M-witness))))))) How about the converse implication? I have deliberately written it as [47m(implies (not (none-M)) (some-M))[0m instead of switching the left-hand and right-hand sides of [47mnl1[0m, which would have been equivalent. Again, RH8 tells us how to reason about it, in this case using RH2, and we succeed. (defthm nl2 (implies (not (none-M)) (some-M)) :rule-classes nil :hints (("Goal" :use ((:instance (:definition none-M)) (:instance some-M-suff (x (none-M-witness))))))) So finally we just go through the motions of proving the equality. (defthmd |forall not = not exists| (equal (none-M) (not (some-M))) :hints (("Goal" :use ((:instance nl1) (:instance nl2))))) Let us now see if we can prove a slightly more advanced theorem which can be stated informally as: If there is a natural number [47mx[0m which satisfies [47mM[0m, then there is a least natural number [47my[0m that satisfies [47mM[0m. [Note: Any time I have had to reason about existential quantification I have had to do this particular style of reasoning and state that if there is an object satisfying a predicate, then there is also a ``minimal'' object satisfying the predicate.] Let us formalize this concept. We first define the concept of existence of a natural number satisfying [47mx[0m. (defun-sk some-nat-M () (exists x (and (natp x) (M x)))) (in-theory (disable some-nat-M some-nat-M-suff)) We now talk about what it means to say that [47mx[0m is the least number satisfying [47mM[0m. (defun-sk none-below (y) (forall r (implies (and (natp r) (< r y)) (not (M r)))))) (in-theory (disable none-below none-below-necc)) (defun-sk min-M () (exists y (and (M y) (natp y) (none-below y)))) (in-theory (disable min-M min-M-suff)) The predicate [47mnone-below[0m says that no natural number less than [47my[0m satisfies [47mM[0m. The predicate [47mmin-M[0m says that there is some natural number [47my[0m satisfying [47mM[0m such that [47mnone-below[0m holds for [47my[0m. So the formula we want to prove is: [47m(implies (some-nat-M) (min-M))[0m. Since the formula requires that we prove an existential quantification, RT1 tells us to construct some object satisfying the predicate over which we are quantifying. We should then be able to instantiate [47mmin-M-suff[0m with this object. That predicate says that the object must be the least natural number that satisfies [47mM[0m. Since such an object is uniquely computable if we know that there exists some natural number satisfying [47mM[0m, let us just write a recursive function to compute it. This function is [47mleast-M[0m below. (defun least-M-aux (i bound) (declare (xargs :measure (nfix (- (1+ bound) i)))) (cond ((or (not (natp i)) (not (natp bound)) (> i bound)) 0) ((M i) i) (t (least-M-aux (+ i 1) bound)))) (defun least-M (bound) (least-M-aux 0 bound)) Let us now reason about this function as one does typically. So we prove that this object is indeed the least natural number that satisfies [47mM[0m, assuming that [47mbound[0m is a natural number that satisfies [47mM[0m. (defthm least-aux-produces-an-M (implies (and (natp i) (natp bound) (<= i bound) (M bound)) (M (least-M-aux i bound)))) (defthm least-<=bound (implies (<= 0 bound) (<= (least-M-aux i bound) bound))) (defthm least-aux-produces-least (implies (and (natp i) (natp j) (natp bound) (<= i j) (<= j bound) (M j)) (<= (least-M-aux i bound) j))) (defthm least-aux-produces-natp (natp (least-M-aux i bound))) (defthmd least-is-minimal-satisfying-m (implies (and (natp bound) (natp i) (< i (least-M bound))) (not (M i))) :hints (("Goal" :in-theory (disable least-aux-produces-least least-<=bound) :use ((:instance least-<=bound (i 0)) (:instance least-aux-produces-least (i 0) (j i)))))) (defthm least-has-m (implies (and (natp bound) (m bound)) (M (least-M bound)))) (defthm least-is-natp (natp (least-M bound))) So we have done that, and hopefully this is all that we need about [47mleast-M[0m. So we disable everything. (in-theory (disable least-M natp)) Now of course we note that the statement of the conjecture we are interested in has two quantifiers, an inner [47mforall[0m (from [47mnone-below[0m) and an outer [47mexists[0m (from [47mmin-M[0m). Since ACL2 is not very good with quantification, we hold its hands to reason with the quantifier part. So we will first prove something about the [47mforall[0m and then use it to prove what we need about the [47mexists[0m. RT9: When you face nested quantifiers, reason about each nesting separately. So what do we want to prove about the inner quantifier? Looking carefully at the definition of [47mnone-below[0m we see that it is saying that for all natural numbers [47mr[0m < [47my[0m, [47m(M r)[0m does not hold. Well, how would we want to use this fact when we want to prove our final theorem? We expect that we will instantiate [47mmin-M-suff[0m with the object [47m(least-M bound)[0m where we know (via the outermost existential quantifier) that [47mM[0m holds for [47mbound[0m, and we will then want to show that [47mnone-below[0m holds for [47m(least-M bound)[0m. So let us prove that for any natural number (call it [47mbound[0m), [47mnone-below[0m holds for [47m(least-M bound)[0m. For the final theorem we only need it for natural numbers satisfying [47mM[0m, but note that from the lemma [47mleast-is-minimal-satisfying-m[0m we really do not need that [47mbound[0m satisfies [47mM[0m. So we are now proving: [47m(implies (natp bound) (none-below (least-M bound)))[0m. Well since this is a standard case of proving a universally quantified predicate, we just apply RT3. We have proved that for all naturals [47mi[0m < [47m(least-M bound)[0m, [47mi[0m does not satisfy [47mM[0m (lemma [47mleast-is-minimal-satisfying-M[0m), so we merely need the instantiation of that lemma with [47mnone-below-witness[0m of the thing we are trying to prove, that is, [47m(least-M bound)[0m. The theorem below thus goes through. (defthm least-is-minimal (implies (natp bound) (none-below (least-M bound))) :hints (("Goal" :use ((:instance (:definition none-below) (y (least-M bound))) (:instance least-is-minimal-satisfying-m (i (none-below-witness (least-M bound)))))))) Finally we are in the outermost existential quantifier, and are in the process of applying [47mmin-M-suff[0m. What object should we instantiate it with? We must instantiate it with [47m(least-M bound)[0m where [47mbound[0m is an object which must satisfy [47mM[0m and is a natural. We have such an object, namely [47m(some-nat-M-witness)[0m which we know have all these qualities given the hypothesis. So the proof now is just RT1 and RT2. (defthm |minimal exists| (implies (some-nat-M) (min-M)) :hints (("Goal" :use ((:instance min-M-suff (y (least-M (some-nat-M-witness)))) (:instance (:definition some-nat-M)))))) If you are comfortable with the reasoning above, then you are comfortable with quantifiers and probably will not need these notes any more. In my opinion, the best way of dealing with ACL2 is to ask yourself why you think something is a theorem, and the rules of thumb above are simply guides to the questions that you need to ask when you are dealing with quantification. Here are a couple of simple exercises for you to test if you understand the reasoning process. [31;1mExercise 1[0m. Formalize and prove the following theorem. Suppose there exists [47mx[0m such that [47m(R x)[0m and suppose that all [47mx[0m satisfy [47m(P x)[0m. Then prove that there exists [47mx[0m such that [47m(P x) & (R x)[0m. (See {http://www.cs.utexas.edu/users/moore/acl2/contrib/quantifier-exercise-1-solution.html | http://www.cs.utexas.edu/users/moore/acl2/contrib/quantifier-exercise-1-solution.html} for a solution.) [31;1mExercise 2[0m. Recall the example just before the preceding exercise, where we showed that if there exists a natural number [47mx[0m satisfying [47mM[0m then there is another natural number [47my[0m such that [47my[0m satisfies [47mM[0m and for every natural number [47mz[0m < [47my[0m, [47mz[0m does not. What would happen if we remove the restriction of [47mx[0m, [47my[0m, and [47mz[0m being naturals? Of course, we will not talk about [47m<[0m any more, but suppose you use a total order on all ACL2 objects such as [<<]. More concretely, consider the definition of [47msome-M[0m above. Let us now define two other functions: (include-book "misc/total-order" :dir :system) (defun-sk none-below-2 (y) (forall r (implies (<< r y) (not (M r))))) (defun-sk min-M2 () (exists y (and (M y) (none-below-2 y)))) The question is whether [47m(implies (some-M) (min-M2))[0m is a theorem. Can you prove it? Can you disprove it? See [47m[solution-to-ACL2-quantifier-exercise-2][0m for a solution. Subtopics [Solution-to-ACL2-quantifier-exercise-2] A solution to [47m[quantifier-tutorial][0m Exercise 2") (quantifiers (defun-sk) "Issues about quantification in ACL2 ACL2 supports first-order quantifiers [47m[exists][0m and [47m[forall][0m by way of the [47m[defun-sk][0m event. However, proof support for quantification is quite limited. Therefore, you may prefer using recursion in place of [47mdefun-sk[0m when possible (following common ACL2 practice). For example, the notion ``every member of [47mx[0m has property [47mp[0m'' can be defined either with recursion or explicit quantification, but proofs may be simpler when recursion is used. We illustrate this point with two proofs of the same informal claim, one of which uses recursion which the other uses explicit quantification. Notice that with recursion, the proof goes through fully automatically; but this is far from true with explicit quantification (especially notable is the ugly hint). The informal claim for our examples is: If every member [47ma[0m of each of two lists satisfies the predicate [47m(p a)[0m, then this holds of their [47m[append][0m; and, conversely. See [quantifiers-using-recursion] for a solution to this example using recursion. See [quantifiers-using-defun-sk] for a solution to this example using [47m[defun-sk][0m. Also See [quantifiers-using-defun-sk-extended] for an elaboration on that solution. But perhaps first, see [defun-sk] for an ACL2 utility to introduce first-order quantification in a direct way. Examples of the use of [47mdefun-sk[0m are also available: see [defun-sk-example] and see [Tutorial4-Defun-Sk-Example] for basic examples, and see [quantifier-tutorial] for a more complete, careful beginner's introduction that takes you through typical kinds of quantifier-based reasoning in ACL2. Subtopics [Quantifiers-using-defun-sk] Quantification example [Quantifiers-using-defun-sk-extended] Quantification example with details [Quantifiers-using-recursion] Recursion for implementing quantification") (quantifiers-using-defun-sk (quantifiers) "Quantification example See [quantifiers] for the context of this example. It should be compared to a corresponding example in which a simpler proof is attained by using recursion in place of explicit quantification; see [quantifiers-using-recursion]. (in-package "ACL2") ; We prove that if every member A of each of two lists satisfies the ; predicate (P A), then this holds of their append; and, conversely. ; Here is a solution using explicit quantification. (defstub p (x) t) (defun-sk forall-p (x) (forall a (implies (member a x) (p a)))) (defthm member-append (iff (member a (append x1 x2)) (or (member a x1) (member a x2)))) (defthm forall-p-append (equal (forall-p (append x1 x2)) (and (forall-p x1) (forall-p x2))) :hints (("Goal" ; ``should'' disable forall-p-necc, but no need :use ((:instance forall-p-necc (x (append x1 x2)) (a (forall-p-witness x1))) (:instance forall-p-necc (x (append x1 x2)) (a (forall-p-witness x2))) (:instance forall-p-necc (x x1) (a (forall-p-witness (append x1 x2)))) (:instance forall-p-necc (x x2) (a (forall-p-witness (append x1 x2)))))))) Also see [quantifiers-using-defun-sk-extended] for an elaboration on this example.") (quantifiers-using-defun-sk-extended (quantifiers) "Quantification example with details See [quantifiers-using-defun-sk] for the context of this example. (in-package "ACL2") ; We prove that if every member A of each of two lists satisfies the ; predicate (P A), then this holds of their append; and, conversely. ; Here is a solution using explicit quantification. (defstub p (x) t) (defun-sk forall-p (x) (forall a (implies (member a x) (p a)))) ; The defun-sk above introduces the following axioms. The idea is that ; (FORALL-P-WITNESS X) picks a counterexample to (forall-p x) if there is one. ; (DEFUN FORALL-P (X) ; (LET ((A (FORALL-P-WITNESS X))) ; (IMPLIES (MEMBER A X) (P A)))) ; ; (DEFTHM FORALL-P-NECC ; (IMPLIES (NOT (IMPLIES (MEMBER A X) (P A))) ; (NOT (FORALL-P X))) ; :HINTS (("Goal" :USE FORALL-P-WITNESS))) ; The following lemma seems critical. (defthm member-append (iff (member a (append x1 x2)) (or (member a x1) (member a x2)))) ; The proof of forall-p-append seems to go out to lunch, so we break into ; directions as shown below. (defthm forall-p-append-forward (implies (forall-p (append x1 x2)) (and (forall-p x1) (forall-p x2))) :hints (("Goal" ; ``should'' disable forall-p-necc, but no need :use ((:instance forall-p-necc (x (append x1 x2)) (a (forall-p-witness x1))) (:instance forall-p-necc (x (append x1 x2)) (a (forall-p-witness x2))))))) (defthm forall-p-append-reverse (implies (and (forall-p x1) (forall-p x2)) (forall-p (append x1 x2))) :hints (("Goal" :use ((:instance forall-p-necc (x x1) (a (forall-p-witness (append x1 x2)))) (:instance forall-p-necc (x x2) (a (forall-p-witness (append x1 x2)))))))) (defthm forall-p-append (equal (forall-p (append x1 x2)) (and (forall-p x1) (forall-p x2))) :hints (("Goal" :use (forall-p-append-forward forall-p-append-reverse))))") (quantifiers-using-recursion (quantifiers) "Recursion for implementing quantification The following example illustrates the use of recursion as a means of avoiding proof difficulties that can arise from the use of explicit quantification (via [47m[defun-sk][0m). See [quantifiers] for more about the context of this example. (in-package "ACL2") ; We prove that if every member A of each of two lists satisfies the ; predicate (P A), then this holds of their append; and, conversely. ; Here is a solution using recursively-defined functions. (defstub p (x) t) (defun all-p (x) (if (atom x) t (and (p (car x)) (all-p (cdr x))))) (defthm all-p-append (equal (all-p (append x1 x2)) (and (all-p x1) (all-p x2))))") (quick-and-dirty-subsumption-replacement-step (debugging) "(advanced topic) controlling a heuristic in the prover's clausifier This topic is probably only of interest to those who are undertaking particularly complex proof developments. The ACL2 prover's handling of propositional logic uses a heuristic that we believe might cause the prover to slow down significantly or even to trigger a stack overflow. However, we believe these negative effects are only felt on very large formulas --- formulas that are likely to cause similar degradation of many other parts of ACL2. The following two events turn off that heuristic (by eliminating calls to source function [47mquick-and-dirty-subsumption-replacement-step[0m, after which this [documentation] topic is named). (defun quick-and-dirty-srs-off (cl1 ac) (declare (ignore cl1 ac) (xargs :mode :logic :guard t)) nil) (defattach-system quick-and-dirty-srs quick-and-dirty-srs-off) However, if you feel the need to try this out, please remember that the proof is likely to fail anyway since other parts of ACL2 will probably be stressed. A more basic problem with your proof strategy may exist: the formulas are getting extraordinarily large. A common approach for avoiding such problem include disabling functions (see [in-theory]). Other less common approaches might help if you are sufficiently desperate, such as defining your own [47mIF[0m function to use in place of the built-in [47mIF[0m. For an example of where this capability has proven useful, see [without-subsumption]. That tool uses [47m[set-case-split-limitations][0m as well, since that is another way to control the prover's handling of propositional logic. To turn the heuristic back on: (defattach-system quick-and-dirty-srs quick-and-dirty-srs-builtin)") (quit (good-bye) "Quit entirely out of Lisp Same as [47m[good-bye][0m.") (quote (basics acl2-built-ins) "Create a constant The form [47m(quote x)[0m evaluates to [47mx[0m. See any Common Lisp documentation. Also see [unquote]. Subtopics [Unquote] Obtain the object being quoted") (quotep (pointers) "See [system-utilities].") (r-and-i-abbreviations-for-terms (recursion-and-induction) "Recursion and Induction: Abbreviations for Terms Recall that a term is a variable symbol, a quoted constant, or a function application written as a sequence, enclosed in parentheses, consisting of a function symbol of arity [3mn[0m followed by [3mn[0m terms. See Terms (see [R-AND-I-TERMS]). However, we implement certain conventions that allow terms to be abbreviated. The conventions allow case to be ignored (when writing symbols), certain constants to be written without being quoted, and certain primitive functions to be given more arguments than their arity implies. The ACL2 implementation also supports a powerful macro facility inherited from Lisp, but we do not discuss macros in this course. When input is being read in and parsed into lexical tokens, the characters in tokens parsed as Lisp symbols are converted to upper case. Thus, the following are three different ways to type in the same symbol: [47mNIL[0m, [47mNil[0m, and [47mnil[0m. Similarly, [47m(cons 'e x)[0m and [47m(Cons 'E x)[0m are both read the same way as [47m(CONS 'E X)[0m. It may seem strange to have different ways to write the same symbol but you're very familiar with the similar conventions applied to numbers: 123, +123, and 0123 are three different ways to write the same integer. If you wish to type a symbol whose name includes lower case characters you must surround the whole symbol with vertical bars. E.g., [47m|nil|[0m is a different symbol than [47mnil[0m. But in this course we do not use symbols whose names include lower case characters. The conversion to upper case only happens when parsing symbols. Strings and character objects are not automatically converted to upper case. Thus, [47m"NIL"[0m, [47m"Nil"[0m and [47m"nil"[0m are three different strings, and [47m#\a[0m is a different character object than [47m#\A[0m. In this document, when we write symbols we generally write them in lower case typewriter font, e.g., [47mnil[0m, and we capitalize them when used as the first word of a sentence, e.g., [47mNil[0m. Occasionally we write them in all upper case, e.g., [47mNIL[0m, to emphasize that particular symbol or to further distinguish the symbol from a nearby English word with the same spelling, as in the sentence ``[47mAND[0m and [47mOR[0m denote conjunction and disjunction.'' But regardless of the case we use --- whether lower case, captialized, or upper case --- we are referring to the same upper case symbol. The next convention allows you to drop the single quote mark on certain constants. The definition of a term requires constants to be quoted. E.g., since [47mevenp[0m is a function symbol of arity 1, [47m(evenp '3)[0m is a term but [47m(evenp 3)[0m is not because [47m3[0m is neither a variable symbol, a [3mquoted[0m constant, or a function application. But we accept the latter as an abbreviation of the former because what else could it mean? To see that ambiguity is lurking if quote marks are dropped, consider [47m(member 'e '(a b c))[0m, where [47mmember[0m is a function symbol of arity 2. What happens if we drop either or both of the quote marks? Then we might still get a term that means something completely different. Here, the function [47mmember[0m means ``is the first argument an element of the second?'' * [47m(member 'e '(a b c))[0m: is the constant symbol [47me[0m an element of the constant list [47m(a b c)[0m? * [47m(member e '(a b c))[0m: is the value of the variable [47me[0m an element of the constant list [47m(a b c)[0m? * [47m(member 'e (a b c))[0m: is the constant symbol [47me[0m an element of the list computed by applying the function [47ma[0m to the values of variables [47mb[0m and [47mc[0m? * [47m(member e (a b c))[0m: is the value of the variable [47me[0m an element of the list computed by applying the function [47ma[0m to the values of variables [47mb[0m and [47mc[0m? Meaning changes if quote marks are dropped from symbols and lists. When the symbol [47me[0m is quoted in a term it denotes the constant [47me[0m; when [47me[0m is not quoted it is a variable symbol and takes on whatever value that variable has been assigned in the environment. Similarly, when a list is quoted it denotes that list constant; when it is not quoted it denotes the application of its first element to the values of the other elements. But unquoted numbers, character objects, and strings used as terms cannot be confused with variable symbols or function applications, so by convention they just abbreviate their own quotations. More precisely, the quote convention for atomic objects is as follows: If [3mx[0m is the symbol [47mT[0m, the symbol [47mNIL[0m, an integer, a character object, or a string, and [3mx[0m is used where a term is expected, then [3mx[0m abbreviates the quoted constant [47m'[0m[3mx[0m. Next we deal with quoted parenthesized expressions. In the following, an [3mexpression[0m is an integer, a character object, a string, a symbol, an optionally dotted parenthesized sequence of expressions, or a single quote mark followed by an expression. By [3moptionally dotted parenthesized sequence of expressions[0m we mean a parenthesized non-empty sequence of expressions, optionally containing a dot (.) between the last two expressions in the sequence. For example ``[47m(A 123 B)[0m'' and ``[47m(A 123 . B)[0m'' are both optionally dotted parenthesized sequences of expressions. (There's no dot in the first expression; the dot in the second one changes the meaning.) We'll be precise in a moment, but [47m'(A 123 B)[0m is an abbreviation for [47m(cons 'A (cons '123 (cons 'B 'nil)))[0m, which could also be written [47m(cons 'A (cons 123 (cons 'B nil)))[0m. Meanwhile, [47m'(A 123 . B)[0m is an abbreviation for [47m(cons 'A (cons '123 'B))[0m which could also be written [47m(cons 'A (cons 123 'B))[0m. More generally, a single quote mark followed by an optionally dotted parenthesized sequence of expressions, when used as a term, denotes a [47mcons[0m term as follows, using these four rules: [3mNULL Rule:[0m If '() is used as a term, it abbreviates [47m'nil[0m. [3mSingleton Rule:[0m If [47m'([3mx[0m[47m)[0m is used as a term it abbreviates [47m(cons '[3mx[0m[47m 'nil)[0m. [3mDotted Pair Rule:[0m If [47m'([3mx[0m[47m . [3my[0m[47m)[0m is used as a term it abbreviates [47m(cons '[3mx[0m[47m '[3my[0m[47m)[0m. [3mList Rule:[0m If [47m'([3mx[0m[47m [3m\alpha[0m[47m)[0m is used as a term and [3m\alpha[0m is any non-empty sequence of expressions it abbreviates [47m(cons '[3mx[0m[47m '([3m\alpha[0m[47m))[0m. Note the new pair of parentheses around [47m[3m\alpha[0m[47m[0m. Thus, for example, the rules above mean that if [47m'(A B C)[0m is used as a term then it denotes [47m(cons 'A '(B C))[0m, which denotes [47m(cons 'A (cons 'B '(C)))[0m, which denotes [47m(cons 'A (cons 'B (cons 'C 'nil)))[0m. If [47m'(A B . C)[0m is used as a term it denotes [47m(cons 'A (cons 'B 'C))[0m. It remains to deal with cases like [47m'[0m[47m'A[0m and [47m'[0m[47m'(A 'B)[0m involving nested single quote marks. Expressions involving nested single quote marks will not arise in this course. But we specify their meaning for completeness. [3mYou may consider the following paragraph and the subsequent example as optional![0m Let [3m\alpha[0m be an expression that does not start with a single quote mark. Consider a sequence of two or more single quote marks followed by [3m\alpha[0m and suppose it is used as a term. It denotes a [47mcons[0m derived as follows. Replace [3m\alpha[0m and the single quote mark immediately before it with [47m(quote [3m\alpha[0m[47m)[0m. Repeat that replacement until all but the first single quote mark remains. Then apply the four rules above. Thus, [47m'[0m[47m'(A 'B)[0m, when used as a term, denotes the term derived by the following sequence of steps [47m'[0m[47m'(A 'B)[0m [47m'(quote (A 'B))[0m [47m(cons 'quote '((A 'B)))[0m [47m(cons 'quote (cons '(A 'B) 'nil))[0m [47m(cons 'quote (cons (cons 'A '('B)) 'nil))[0m [47m(cons 'quote (cons (cons 'A (cons '[0m[47m'B 'nil)) 'nil))[0m [47m(cons 'quote (cons (cons 'A (cons '(quote B) 'nil)) 'nil))[0m [47m(cons 'quote (cons (cons 'A (cons (cons 'quote '(B)) 'nil)) 'nil))[0m [47m(cons 'quote (cons (cons 'A (cons (cons 'quote (cons 'B 'nil)) 'nil)) 'nil))[0m Note that every occurrence of single quote now marks a quoted constant. [3mEnd of optional material.[0m When [47m(list [3mx_1[0m[47m ... )[0m is used as a term, it abbreviates [47m(cons [3mx_1[0m[47m (list ... ))[0m. When [47m(list)[0m is used as a term, it abbreviates [47mnil[0m. Thus [47m(list a b c)[0m abbreviates [47m(cons a (cons b (cons c nil)))[0m. For the purposes of this course you may imagine that [47mAND[0m and [47mOR[0m are defined as function symbols of two arguments. But we use them as though they were function symbols of varying numbers of argument. When [47mAND[0m and [47mOR[0m are provided more than two arguments it just abbreviates the corresponding right-associated nest. Thus, [47m(and p q r s)[0m, when used where a term is expected, abbreviates [47m(and p (and q (and r s)))[0m. In the actual ACL2 implementation, [47mAND[0m and [47mOR[0m are ``macros.'' (Maybe explore term abbreviation in ACL2? But abbreviation is complicated in ACL2 by the presence of a powerful macro facility. To learn about ACL2 term abbreviation, explore <<[term]>>, paying special attention to ``untranslated'' terms. Maybe also explore <<[macros]>>.) [31;1mProblem 7. [0m Show the term abbreviated by each of the following: 1. [47m(cons 1 '(2 3))[0m 2. [47m(equal "Hello" hello)[0m 3. [47m(and (or a1 a2 a3) (or b1 b2 b3) (or c1 c2 c3))[0m 4. [47m(equal x '(or a1 a2 a3))[0m 5. [47m(cons cons '(cons cons 'cons))[0m The art of displaying a Lisp term in a way that it can be easily read by a person is called [3mpretty printing[0m. We recommend the following heuristics. First, write clearly and count your parentheses. Second, try never to write a single line with more than about 30 non-blank characters on it. Third, if a function call will not fit on a line, break it into multiple lines, indenting each argument the same amount. Below we show one term pretty printed with successively narrower margins. (Note that the display is a term only if [47mapp[0m is a function symbol of arity two.) We find the second and third lines of the first display below excessively long. Each display shows exactly the same term. Note how we break terms to indent arguments the same amount and how we sometimes slide the arguments under the function symbol to save horizontal space. Personally, we find the second display below (the one labeled ``[47mwidth 46[0m'') the easiest to read. We show the others merely to illustrate how more space can be saved when one finds oneself close to the right margin. |<---------------------------- width 70 ---------------------------->| (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))) |<---------------- width 46 ---------------->| (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))) |<------------ width 38 ------------>| (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))) |<---------- width 34 ---------->| (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))) |<------- width 28 ------->| (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))) |<---- width 23 ----->| (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))) Next: Function Definitions (see [R-AND-I-FUNCTION-DEFINITIONS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-acl2-arithmetic (r-and-i-arithmetic) "Recursion and Induction: ACL2 Arithmetic The techniques we have studied so far suffice to prove the most elementary facts of natural number arithmetic. In fact, we could conduct our entire study of recursion and induction in the domain of number theory. But it is more fun to deal with less familiar ``data structures'' where basic properties can be discovered. So we will skip past formal arithmetic with a few brief remarks. ACL2 provides the numbers as a data type distinct from conses, symbols, strings, and characters. They are not lists of [47mnil[0ms! The naturals are among the integers, the integers are among the rationals, and the rationals are among the ACL2 numbers. The complex rationals are also among the ACL2 numbers; in fact they are complex numbers whose real and imaginary parts are rational and whose imaginary parts are non-[47m0[0m. Here are a few commonly used functions in ACL2. [47m(natp x)[0m - recognizes natural numbers [47m(integerp x)[0m - recognizes integers [47m(rationalp x)[0m - recognizes rationals [47m(zp x)[0m - [47mt[0m if x is [47m0[0m or not a natural; [47mnil[0m otherwise [47m(nfix x)[0m - [47mx[0m if [47mx[0m is a natural; [47m0[0m otherwise [47m(+ x y)[0m - sum of the numbers [47mx[0m and [47my[0m [47m(- x y)[0m - difference of the numbers [47mx[0m and [47my[0m [47m(* x y)[0m - product of the numbers [47mx[0m and [47my[0m [47m(/ x y)[0m - rational quotient of the numbers [47mx[0m and [47my[0m [47m(< x y)[0m - predicate recognizing that the number [47mx[0m is less than the number [47my[0m [47m(<= x y)[0m - predicate recognizing that the number [47mx[0m is less than or equal to the number [47my[0m The functions [47m+[0m, [47m-[0m, [47m*[0m, [47m/[0m, [47m<[0m, and [47m<=[0m default their arguments to [47m0[0m in the sense that if some argument is not an ACL2 number then [47m0[0m is used instead. The predicate [47mzp[0m is commonly used in recursive definitions that treat an argument as though it were a natural number and count it down to zero. Here is a ``definition'' that accesses the [47mn[0mth element of a list, treating [47mn[0m as a natural. (This definition is unacceptable under our current Principle of Structural Recursion because [47m(consp x)[0m does not rule the recursive call. We will return to this point momentarily.) (defun nth (n x) (if (zp n) (car x) (nth (- n 1) (cdr x)))) Thus, [47m(nth 2 '(A B C D))[0m is [47mC[0m. [47m(Nth 0 '(A B C D))[0m is [47mA[0m. Interestingly, [47m(nth -1 '(A B C D))[0m is also [47mA[0m, because [47m-1[0m satisfies [47mzp[0m. Thus, we can use [47mnth[0m with any first argument. (In ACL2, [47mnth[0m is defined differently, but equivalently.) The numbers are axiomatized with the standard axioms for rational fields. See [reference 3] (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY]). [31;1mHenceforth, you may use arithmetic freely in your proofs and assume any theorem of ACL2 arithmetic. That is, you may assume any ACL2 theorem that can be written with the function symbols described above and use it in routine arithmetic simplification. But be careful about what you assume![0m For example, the following familiar arithmetic facts are not (quite) theorems: (equal (+ x 0) x) ; Additive Identity (iff (equal (+ x y) (+ x z)) ; Additive Cancellation (equal y z)) Why aren't the formulas above theorems? In addition, the following strange fact is a theorem: (not (equal (* x x) 2)) That is, we can prove that the square root of 2 is not rational and hence not in ACL2. (Maybe explore ACL2 arithmetic? You won't need ACL2 arithmetic libraries to do the problems here. But that is good because there is probably not an area of mathematics that the typical computer science student knows better than arithmetic. Furthermore, you likely know much more about arithmetic than ACL2 does when it is first fired up. Its performance can be improved by including ``certified books'' of definitions and theorems about arithmetic. The ACL2 Community Books Repository [4] contains thousands of books created by the community. To load a book into an ACL2 session the command <<[47m[include-book][0m>> is used. But there are many kinds of arithmetic books to choose from depending on what sort of operations are involved in your conjectures. You might explore books on elementary <<[arithmetic]>> including some number theory books, or books on the arithmetic of <<[bit-vectors]>> (which deal with concepts like shifting or bitwise logical operations on number), or floating point books (see <<[rtl]>>; these are useful for verifying implementations of floating point operations) or a book on the <<[gl]>> utility (which provides a bit-blaster for finite arithmetic), or <<[algebra]>> books (e.g., properties of rings and fields), to name a few.) Next: Inadequacies of Structural Recursion (see [R-AND-I-INADEQUACIES-OF-STRUCTURAL-RECURSION]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-annotated-bibliography (recursion-and-induction) "Recursion and Induction: Annotated Bibliography Annotated Bibliography The following resources are useful for understanding the ACL2 logic and theorem prover, as well as its relation to both the earlier Nqthm logic and the Common Lisp programming language. These resources are not necessary for you to do the exercises in these notes. But if you are considering learning how to use the ACL2 or just wondering why anyone would bother, you might browse this annotated bibliography. * [0] R. S. Boyer and J S. Moore. [3mA Computational Logic Handbook[0m. Academic Press, London, 1997 (Second Edition). See [3m{https://www.cs.utexas.edu/users/boyer/ftp/nqthm/ | https://www.cs.utexas.edu/users/boyer/ftp/nqthm/}[0m for source code and regression suite This book is the user's manual for the Boyer-Moore theorem prover, Nqthm, of the 1980s. The ACL2 project started in 1989, when Boyer and Moore set themselves the goal of re-implementing Nqthm so that it supported an efficient, functional (applicative) subset of Common Lisp and was coded in that same subset. (They almost succeeded but had to use imperative code to implement functional versions of some utilities.) So this reference, [0], describes the precursor of ACL2. This book is the second edition of the Nqthm manual which was first published in 1988. The url above contains the Nqthm source code and input and output files for the prover. Most of these files were developed by the Nqthm user community. The files include many proofs of classic list-processing and elementary number theory theorems but also proofs of Goedel's incompleteness theorem, Gauss's law of quadratic reciprocity, the Paris-Harrington Ramsey theorem, and the ``verified stack'' of Computational Logic, Inc. The verified stack, first reported in 1989 and then ported to a verified fabricated microprocessor in 1992, consisted of a gate-level implementation of a microprocessor, an assembler, linker, and loader, a compiler, an operating system, and some applications, all of which were verified with Nqthm to ``stack'' so that a theorem proved about an application written in one of two high level languages and proved correct with respect to that high-level semantics runs correctly on the microprocessor. These results are only briefly mentioned in [0] but that book does contain citations that describe them in detail. Further development of Nqthm was halted because Nqthm users were building formal models that were so big they strained the capacity of the prover and were too slow to run as simulators for the modeled systems. For example, when the ACL2 project was getting started, a student of Boyer was formalizing the Motorola 68020 microprocessor with the goal of verifying the Berkeley C String Library. (That Nqthm project was completed successfully in 1993 and the files are available at the url above.) * [1] M. Kaufmann, P. Manolios, and J S. Moore, editors. [3mComputer-Aided Reasoning: ACL2 Case Studies[0m. Kluwer Academic Press, Boston, MA., 2000. See [3m{https://www.cs.utexas.edu/users/moore/publications/acl2-books/acs/index.html | https://www.cs.utexas.edu/users/moore/publications/acl2-books/acs/index.html}[0m. This book is a collection of papers by ACL2 users, assembled in 2000, describing, in a textbook-like style. applications of ACL2. It contains examples from graph theory, calculus, model checking, language simulators, microprocessor design including hardware description languages, floating-point implementations, compiler verification, and other topics. While the Kluwer hardback edition of the book is out of print, the url above includes instructions for obtaining a paperback copy (for which the authors of [1] and [2] hold the copyright). * [2] M. Kaufmann, P. Manolios, and J S. Moore. [3mComputer-Aided Reasoning: An Approach[0m. Kluwer Academic Press, Boston, MA., 2000. [3m{https://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html | https://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html}[0m. This book is essentially a textbook for students wishing to learn how to use the ACL2 system. It starts with a description of the ACL2 programming language, then formalizes the logic with axioms and rules of inference, and then discusses how to prove theorems with the system. The book includes exercises. While the Kluwer hardback edition of the book is out of print, the url above includes instructions for obtaining a paperback copy (for which the authors of [1] and [2] hold the copyright). * [3] M. Kaufmann and J S. Moore. A precise description of the ACL2 logic. In [3m {https://www.cs.utexas.edu/users/moore/publications/km97a.pdf | https://www.cs.utexas.edu/users/moore/publications/km97a.pdf}[0m Dept. of Computer Science, University of Texas at Austin, 1997. The title says it all. The ACL2 logic is a first-order logic of total recursive functions providing mathematical induction and several extension principles including symbol package definition and recursive function definition. The logic is a formalization of an extension of a functional subset of Common Lisp. This paper describes the logic in detail, more in the style of a logic book than the style used in these notes. The paper also explains the connection between theorems in the logic and evaluation in Common Lisp, which very roughly speaking is that, given enough time and computing resources, any instance of a guard-verified (aka a ``gold'' theorem in the terminology of this 1997 paper) will compute to non-[47mnil[0m in Common Lisp. (Maybe explore <<[47m[verify-guards][0m>>?) * [4] M. Kaufmann and J S. Moore. The ACL2 home page. [3m{http://www.cs.utexas.edu/users/moore/acl2/ | http://www.cs.utexas.edu/users/moore/acl2/}[0m Dept. of Computer Science, University of Texas at Austin, 2022. This web page contains the latest release of the ACL2 system in Common Lisp source code form. The system is largely implemented in the subset of Common Lisp the prover supports. ACL2 is distributed without fee under a 3-clause BSD license. A new release is currently made about once per year and the web page also contains links to all past releases going back to 1996. The home page includes instructions for installing any of several Common Lisp implementations and instructions for downloading and building ACL2. The web page contains the online user's manual and instructions for how to download the regression suite from {the ACL2 GitHub repository | https://github.com/acl2/acl2}. The regression suite, called the ACL2 <<[Community-Books]>>, contains thousands of verified files created by the ACL2 user community containing definitions and theorems. If you scan down to the [31;1mSubtopics[0m section of the <<[top]>> node of the manual you will find a list of many topics for which certified <<[books]>> are available. To take just one example from that top-level list of Subtopics, scroll down to Hardware Verification. In that Subtopic you find directories dealing with symbolic simulation, register transfer logic (including tools for reasoning about floating point implementations), a Verilog translator, an x86 ISA model, and many other topics. There are many other nodes besides Hardware Verification. In fact, the tree of books listed among the Subtopics is simply too big and too rapidly changing to try to summarize here. We encourage you to explore, or ask <<[ACL2-help]>> about resources (if any) for a particular topic. * [5] P. Manolios and D. Vroon. Ordinal arithmetic in acl2. In [3mACL2 Workshop 2003[0m, Boulder, Colorado, July 2003. {http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/ | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}. The termination of recursive functions in ACL2 and the induction principle are both based on the ordinals and the well-foundedness of ordinal ``less than''. The description of ACL2 in [2] above includes a formalization of the ordinals up to \epsilon_0 (``epsilon naught'') represented in ACL2 with conses and natural numbers based on a version of Cantor Normal Form. That representation was superseded in 2004 by the representation described in this paper, which implements a slightly different version of the normal form that is exponentially more efficient. The paper also describes algorithms for manipulating ordinals in this representation. * [6] K. Pitman (editor). [3mCommon Lisp Hyper Spec[0m. LispWorks, Ltd, 1996. {http://www.lispworks.com/documentation/HyperSpec/Front/ | http://www.lispworks.com/documentation/HyperSpec/Front/}. This is an online hypertext presentation of the Common Lisp specification as described in [7]. * [7] G. L. Steele, Jr. [3mCommon Lisp The Language, Second Edition[0m. Digital Press, 30 North Avenue, Burlington, MA. 01803, 1990. This is the definitive specification of Common Lisp. ACL2 only formalizes a small subset of the language described by Steele. But ACL2's documentation of some primitives refers to Steele's descriptions. By the way, we do not recommend the ACL2 documentation as a way to learn to how to program in full Common Lisp. Indeed, we don't recommend [6] or [7] for that purpose either. Many good introductions to Common Lisp are available via the web. There are many implementations of Common Lisp available and the [installation] instructions list several; see [obtaining-common-lisp]. * [8] W. A. Hunt, Jr., M. Kaufmann, J S. Moore and A. Slobodova. Industrial Hardware and Software Verification with ACL2. In [3mVerified Trustworthy Software Systems[0m, P. Gardner, P. O'Hearn, M. Gordon, G. Morrisett and F. B. Schneider, Phil. Trans. R. Soc. A, [31;1m375[0m, The Royal Society, ISSN 1364-503X, DOI 10.1098/rsta.2015.0399 (Article Number 20150399), 2017. The ACL2 system has seen sustained industrial use since the mid-1990s. Companies that have used ACL2 regularly include AMD, Centaur Technology, IBM, Intel, Kestrel Institute, Motorola/Freescale, Oracle and Collins (formerly Rockwell Collins). This paper describes how ACL2 came to be used in industry, what it is used for, and how it is used. The paper highlights ACL2's use in the microprocessor industry, specifically by Centaur Technology on modules in their x86 microprocessors. The paper was written in 2017. Since then the formal verification team at Centaur Technology has moved to Intel, where ACL2 is used in the same way today (2022). Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS])") (r-and-i-arithmetic (recursion-and-induction) "Recursion and Induction: Arithmetic We will next discuss arithmetic, in two steps. First, we'll challenge you to use what we have already got to define ``natural numbers'' (non-negative integers) and the elementary operations on them. This is called ``Peano'' arithmetic after the 19th century Italian mathematician Giuseppe Peano who first wrote down formal axioms describing the natural numbers. After you've explored the foundations of arithmetic, we'll talk about briefly about the more familiar arithmetic of integers and rationals. Next: Peano Arithmetic (see [R-AND-I-PEANO-ARITHMETIC]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS])) Subtopics [R-and-i-peano-arithmetic] Recursion and Induction: Peano Arithmetic [R-and-i-ACL2-arithmetic] Recursion and Induction: ACL2 Arithmetic") (r-and-i-axioms (recursion-and-induction) "Recursion and Induction: Axioms A formal mathematical theory is given by a formal syntax for [3mformulas[0m, a set of formulas designated as [3maxioms[0m, and some formula manipulation [3mrules of inference[0m that allow one to derive [3mnew[0m formulas from [3mold[0m ones. A [3mproof[0m of a formula [3mp[0m is a derivation of [3mp[0m from the given axioms using the given rules of inference. If a formula can be proved, it is said to be a [3mtheorem[0m. Formulas are given [3msemantics[0m similar to those described for terms. Given an [3massignment[0m of values to variable symbols and an interpretation of the function symbols, every formula is given a truthvalue by the semantics. Given an interpretation, a formula is [3mvalid[0m if it is given the value true under every possible assignment to the variable symbols. A [3mmodel[0m of a theory is an interpretation that makes all the axioms valid. Provided the rules of inference are validity preserving, every theorem is valid, i.e., [3malways true[0m. We assume you know all that, and won't go into it further. The whole point of a practical formal theory is to use proof to determine truth: one way to determine if a formula is true is to prove it. If [3m\alpha[0m and [3m\beta[0m are terms, then [3m\alpha[0m = [3m\beta[0m is a [3mformula[0m. If [3mp[0m and [3mq[0m are formulas, then each of the following is a formula: * [3mp[0m --> [3mq[0m * [3mp[0m & [3mq[0m * [3mp[0m \/ [3mq[0m * ~[3mp[0m * [3mp[0m <-> [3mq[0m. If [3m\alpha[0m and [3m\beta[0m are terms, then [3m\alpha[0m != [3m\beta[0m is just an abbreviation for the formula ~([3m\alpha[0m = [3m\beta[0m). We extend the notation [3mterm[0m/[3m\sigma[0m in the obvious way so that we can apply substitution [3m\sigma[0m to formulas, replacing all the variables bound by [3m\sigma[0m in all the terms of the formula. The axioms we will use for the initial part of our study are given below. Note that Axioms 1 and 8 are actually axiom schemas, i.e., they describe an infinite number of axioms. [31;1mAxiom[0m | [31;1m1.[0m | [47m'[0m[3m\alpha[0m != [47m'[0m[3m\beta[0m, | | | where [3m\alpha[0m and [3m\beta[0m are distinct integers, characters, strings, or symbols | [31;1mAxiom[0m | [31;1m2.[0m | [47mx[0m != [47mnil[0m --> [47m(if x y z)[0m = [47my[0m | [31;1mAxiom[0m | [31;1m3.[0m | [47mx[0m = [47mnil[0m --> [47m(if x y z)[0m = [47mz[0m | [31;1mAxiom[0m | [31;1m4.[0m | [47m(equal x y)[0m = [47mnil[0m \/ [47m(equal x y)[0m = [47mt[0m | [31;1mAxiom[0m | [31;1m5.[0m | [47mx[0m = [47my[0m <-> [47m(equal x y)[0m = [47mt[0m | [31;1mAxiom[0m | [31;1m6.[0m | [47m(consp x)[0m = [47mnil[0m \/ [47m(consp x)[0m = [47mt[0m | [31;1mAxiom[0m | [31;1m7.[0m | [47m(consp (cons x y))[0m = [47mt[0m | [31;1mAxiom[0m | [31;1m8.[0m | [47m(consp '[0m[3m\alpha[0m[47m)[0m = [47mnil[0m, | | | where [3m\alpha[0m is an integer, character, string, or symbol | [31;1mAxiom[0m | [31;1m9.[0m | [47m(car (cons x y))[0m = [47mx[0m | [31;1mAxiom[0m | [31;1m10.[0m | [47m(cdr (cons x y))[0m = [47my[0m | [31;1mAxiom[0m | [31;1m11.[0m | [47m(consp x)[0m = [47mt[0m --> [47m(cons (car x) (cdr x))[0m = [47mx[0m | [31;1mAxiom[0m | [31;1m12.[0m | [47m(consp x)[0m = [47mnil[0m --> [47m(car x)[0m = [47mnil[0m | [31;1mAxiom[0m | [31;1m13.[0m | [47m(consp x)[0m = [47mnil[0m --> [47m(cdr x)[0m = [47mnil[0m | One axiom described by Axiom (schema) 1 is [47m't[0m != [47m'nil[0m. Others are [47m'nil[0m != [47m'3[0m and [47m'"Hello"[0m != [47m'Hello[0m. We refer to all of these as Axiom 1. One axiom described by Axiom (schema) 8 is [47m(consp 'nil)[0m = [47mnil[0m. Others are [47m(consp '3)[0m = [47mnil[0m and [47m(consp 'Hello)[0m = [47mnil[0m. We refer to all of these as Axiom 8. Note that if [3m\phi[0m is an axiom or theorem and [3m\sigma[0m is a substitution, then [3m\phi[0m/[3m\sigma[0m is a theorem, by the Rule of Instantiation. We assume you are familiar with the rules of inference for propositional calculus and for equality. For example, we take for granted that you can recognize simple propositional tautologies, reason by cases, and substitute equals for equals. For example, we show a theorem below that you should be able to prove, using nothing but your knowledge of propositional calculus and equality (and Axiom 1). The proof shown below uses the Deduction Law of propositional calculus: we can prove [3mp[0m --> [3mq[0m by assuming [3mp[0m as a ``Given'' and deriving [3mq[0m. [31;1mTheorem.[0m (consp x) = t & x = (car z) --> (consp (car z)) != nil [31;1mProof.[0m 1. | | [47m(consp x) = t[0m | | [3m{Given}[0m | 2. | | [47mx = (car z)[0m | | [3m{Given}[0m | 3. | | [47mt != nil[0m | | [3m{Axiom 1}[0m | 4. | | [47m(consp x) != nil[0m | | [3m{Equality Substitution, line 1 into line 3}[0m | 5. | | [47m(consp (car z)) != nil[0m | | [3m{Equality Substitution, line 2 into line 4}[0m | | | Q.E.D. | | | We will not write proofs in this style. We will simply say that the formula is a theorem ``by propositional calculus, equality, and Axiom 1.'' Recall that each function definition adds an axiom. The definition (defun tree-copy (x) (if (consp x) (cons (tree-copy (car x)) (tree-copy (cdr x))) x)) adds the axiom [31;1mAxiom[0m tree-copy (tree-copy x) = (if (consp x) (cons (tree-copy (car x)) (tree-copy (cdr x))) x) Thus, by the Rule of Instantiation [31;1mTheorem.[0m (tree-copy (cons a b)) = (if (consp (cons a b)) (cons (tree-copy (car (cons a b))) (tree-copy (cdr (cons a b)))) (cons a b)) Next: Terms as Formulas (see [R-AND-I-TERMS-AS-FORMULAS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-characters (r-and-i-data-types) "Recursion and Induction: Characters We will not use character objects in this document. In case you come across such an object in your exploration of ACL2, some characters are [47m#\a[0m, [47m#\A[0m, [47m#\Newline[0m and [47m#\Space[0m. It is actually possible in ACL2 to ``construct'' and ``deconstruct'' characters in terms of naturals. For example, one can construct [47m#\A[0m from [47m65[0m, the ASCII code for uppercase `A'. (Maybe explore <<[characters]>>?) Next: Strings (see [R-AND-I-STRINGS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-data-types (recursion-and-induction) "Recursion and Induction: Data Types ACL2 provides five data types: numbers, characters, strings, symbols, and ordered pairs. Next: Numbers (see [R-AND-I-NUMBERS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS])) Subtopics [R-and-i-numbers] Recursion and Induction: Numbers [R-and-i-characters] Recursion and Induction: Characters [R-and-i-strings] Recursion and Induction: Strings [R-and-i-symbols] Recursion and Induction: Symbols [R-and-i-pairs] Recursion and Induction: Pairs [R-and-i-identity] Recursion and Induction: Identity [R-and-i-data-types-exercises] Recursion and Induction: Data Types Exercises") (r-and-i-data-types-exercises (r-and-i-data-types) "Recursion and Induction: Data Types Exercises [31;1mProblem 1. [0m Each of the utterances below is supposed to be a single object. Say whether it is a number, string, symbol, pair, or ill-formed (i.e., does not represent a single object in our language). 1. [47mMonday[0m 2. [47m[3m\pi[0m[47m[0m 3. [47mHelloWorld![0m 4. [47m--1[0m 5. [47m-1[0m 6. [47m*PI*[0m 7. [47m31415x10**-4[0m 8. [47m(A . B . C)[0m 9. [47mHello World![0m 10. [47mif[0m 11. [47minvokevirtual[0m 12. [47m((1) . (2))[0m 13. [47m<=[0m 14. [47m((A . 1) (B . 2) (C . 3))[0m 15. [47mHello_World![0m 16. [47m+[0m 17. [47mlo-part[0m 18. [47m31415926535897932384626433832795028841971693993751058209749445923[0m 19. [47m(1 . (2 . 3))[0m 20. [47m(1 . 2 3)[0m 21. [47m"Hello World!" [0m 22. [47m((1) (2) . 3)[0m 23. [47m()[0m [31;1mProblem 2. [0m Group the constants below into equivalence classes. That is, some items below are equal to others even though they are displayed differently; group equal constants together. 1. [47m(1 . (2 3))[0m 2. [47m(nil . (nil nil))[0m 3. [47m((nil nil) . nil)[0m 4. [47m(1 (2 . 3) 4)[0m 5. [47m(nil nil)[0m 6. [47m(1 (2 . 3) . (4 . ()))[0m 7. [47m(HelloWorld !)[0m 8. [47m(1 (2 3 . ()) 4)[0m 9. [47m((A . t) (B . nil)(C . nil))[0m 10. [47m(()())[0m 11. [47m(1 2 3)[0m 12. [47m(() () . nil)[0m 13. [47m(A B C)[0m 14. [47m(a . (b . (c)))[0m 15. [47m(HELLO WORLD !)[0m 16. [47m((a . t) (b) . ((c)))[0m Next: Terms (see [R-AND-I-TERMS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-definitional-principle (recursion-and-induction) "Recursion and Induction: The Definitional Principle Below we give a new definitional principle that subsumes the previously given Principle of Structural Recursion. The definition [47m(defun[0m [3mf[0m [47m([0m[3mv_1[0m ... [3mv_n[0m[47m)[0m [3m\beta[0m[47m)[0m is [3madmissible[0m if and only if 1. [3mf[0m is a new function symbol, 2. the [3mv_i[0m are distinct variable symbols, 3. [3m\beta[0m is a term that mentions no variable other than the [3mv_i[0m and calls no new function symbol other than (possibly) [3mf[0m, and 4. there is a term [3mm[0m (called the [3mmeasure[0m) such that the following are theorems: * [3mOrdinal Conjecture[0m [47m(o-p[0m [3mm[0m[47m)[0m * [3mMeasure Conjecture(s)[0m For each recursive call of [47m([0m[3mf a_1[0m ... [3ma_n[0m[47m)[0m in [3m\beta[0m and the conjunction [3mq[0m of tests ruling it, [47m(implies[0m [3mq[0m [47m(o<[0m [3mm[0m/[3m\sigma[0m [3mm[0m[47m))[0m where [3m\sigma[0m is [47m{[0m[3mv_1[0m<--[3ma_1[0m, ... , [3mv_n[0m<--[3ma_n[0m[47m}[0m. If that definition is admissible, then it adds the axiom: [47m([0m[3mf[0m [3mv_1[0m ... [3mv_n[0m[47m) = [0m[3m\beta[0m. In each of the problems below, admit the proposed definition, i.e., identify the measure and prove the required theorems. (Maybe explore <<[47m[defun][0m>>? Note in particular how the user can explicitly specify the measure and well-founded relation alleged to decrease. When specified, the system will attempt to prove it decreases as per the Definitional Principle. If no measure is specified by the user, the system attempts to find an argument whose [47m[ACL2-count][0m decreases according to [47m[o<][0m.) [31;1mProblem 95. [0m (defun tree-copy (x) (if (atom x) x (cons (tree-copy (first x)) (tree-copy (rest x))))) [31;1mProblem 96. [0m (defun ack (x y) (if (zp x) 1 (if (zp y) (if (equal x 1) 2 (+ x 2)) (ack (ack (- x 1) y) (- y 1))))) [31;1mProblem 97. [0m Recursion like that in [47mack[0m allows us to define functions that cannot be defined if we are limited to ``primitive recursion'' where a given argument is decremented in every recursive call. That is, the new definitional principle is strictly more powerful than the old one. This can be formalized and proved within our system (after we extend the principle of induction below). If you are inclined towards metamathematics, feel free to pursue the formalization and ACL2 proof of this. The existence of non-primitive recursive functions, dating from 1928, by Wilhelm Ackermann, a student of David Hilbert, was one of the important milestones in our understanding of the power and limitations of formal mathematics culminating in Goedel's results of the early 1930s. [31;1mProblem 98. [0m (defun f1 (i j) (if (and (natp i) (natp j) (< i j)) (f1 (+ 1 i) j) 1)) [31;1mProblem 99. [0m (defun f2 (x) (if (equal x nil) 2 (and (f2 (car x)) (f2 (cdr x))))) [31;1mProblem 100. [0m (defun f3 (x y) (if (and (endp x) (endp y)) 3 (f3 (cdr x) (cdr y)))) [31;1mProblem 101. [0m Suppose [47mp[0m, [47mm[0m, [47mup[0m, and [47mdn[0m (``down'') are undefined functions. Suppose however that you know this about [47mp[0m, [47mm[0m, and [47mdn[0m: [31;1mTheorem[0m dn-spec (and (o-p (m x)) (implies (p x) (o< (m (dn x)) (m x)))) Then admit (defun f4 (x y q) (if (p x) (if q (f4 y (dn x) (not q)) (f4 y (up x) (not q))) 4)) Note that [47mf4[0m is swapping its arguments. Thus, if [47mq[0m starts at [47mt[0m, say, then in successive calls the first argument is [47mx[0m, [47my[0m, [47m(dn x)[0m, [47m(up y)[0m, [47m(dn (dn x))[0m, [47m(up (up y))[0m, etc. I thank Anand Padmanaban for helping me think of and solve this problem. Next: The Induction Principle (see [R-AND-I-INDUCTION-PRINCIPLE]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-definitions-revisited (recursion-and-induction) "Recursion and Induction: Definitions Revisited [31;1mProblem 27. [0m Suppose we define (defun f (x) 1) and then prove some theorems and then ``redefine'' [47mf[0m with (defun f (x) 2) Now prove that [47m(equal 'June' 'July)[0m, using the theorems that [47m(equal (f x) 1)[0m, proved before redefining [47mf[0m, and [47m(equal (f x) 2)[0m, proved after. Flesh out your argument using axioms presented earlier (see [r-and-i-axioms] and see [r-and-i-definitions-revisited]). A consequence is that since anything provable is valid, then the formula [47m(equal 'June 'July) != nil[0m is true, hence [47m'June[0m = [47m'July[0m, a contradiction! In the following Problems we explore further such consequences of permitting ``bad'' definitions. [31;1mProblem 28. [0m Suppose we define (defun f (x) (cons x y)) Prove [47m(equal 1 2)[0m. (Remark. The definition [47mf[0m in this problem has nothing to do with the definition of [47mf[0m in the previous problem! We tend to ``re-use'' function names like [47mf[0m, [47mg[0m and [47mh[0m from time to time simply to avoid inventing new names.) [31;1mProblem 29. [0m Suppose we define (defun f (x) (not (f x))) Prove [47m(equal t nil)[0m. These problems should disturb you! We often think of ``definitions'' as being logically innocuous, allowing us to abbreviate complicated expressions. And we think of proof as a way to determine truth. So it is disturbing if after making a ``definition'' we are suddenly able to prove things we know aren't true, like that [47mJune[0m is [47mJuly[0m or that [47mt[0m is [47mnil[0m! Something has gone terribly wrong. To prevent this kind of logical inconsistency, we impose some restrictions on our ability to introduce definitions. The restrictions we'll impose will prevent us from defining many useful functions but guarantee that we don't ruin the logic with ``definitions'' like those shown above. ACL2 is much more generous in its restrictions but they are spiritually similar: both here and in ACL2 the restrictions on definitions will guarantee that every defined function terminates. We do not explain in this document why termination is enough to avoid inconsistencies. One way to make sure a function terminates is to insist that there is an argument that is being [47mcar[0m'd and/or [47mcdr[0m'd at least once every time the function recurs and that before it recurs the definition tests that the argument is a [47mcons[0m-pair. For example, [47m(defun f (x) (not (f x)))[0m is disallowed by this restriction, and so is [47m(defun f (x) (not (f (cdr x))))[0m. But (defun f (x) (if (consp x) (and (not (f (car x))) (not (f (cdr (cdr x))))) t)) is allowed because [47mx[0m is [47mcar[0m'd and/or [47mcdr[0m'd in every recursion and the function tests [47m(consp x)[0m before recurring. We say [47m(consp x)[0m ``rules'' the two recursive calls above. So we have to define the notions of a ``[47mcar[0m/[47mcdr[0m'' nest and what terms ``rule'' the recursive calls. A [3mcar/cdr nest around[0m [3mv[0m is [47m(car[0m [3mv[0m[47m)[0m, [47m(cdr[0m [3mv[0m[47m)[0m, or a [47mcar[0m/[47mcdr[0m nest around [47m(car[0m [3mv[0m[47m)[0m or [47m(cdr[0m [3mv[0m[47m)[0m. Thus, [47m(car (cdr (car x)))[0m is a [47mcar[0m/[47mcdr[0m nest around [47mx[0m. The idea in this next definition is to take a term [3m\beta[0m and a particular occurrence [3mr[0m of some subterm in [3m\beta[0m and define the set of tests that rule [3mr[0m. Then, if you have a function definition like [47m(defun[0m [3mf[0m [47m([0m[3mv_1[0m ... [3mv_k[0m[47m)[0m [3m\beta[0m[47m)[0m you can let [3mr[0m be a particular recursive call of [3mf[0m in [3m\beta[0m and then determine which tests rule that call. The [3mrulers[0m of an occurrence of a term [3mr[0m in another term [3m\beta[0m is the set defined as follows: 1. if [3m\beta[0m is [47m(if[0m [3mp[0m [3mx[0m [3my[0m[47m)[0m and [3mr[0m is in [3mx[0m, then the rulers of [3mr[0m in [3m\beta[0m is the set obtained by adding [3mp[0m to the set of rulers of [3mr[0m in [3mx[0m; 2. if [3m\beta[0m is [47m(if[0m [3mp[0m [3mx[0m [3my[0m[47m)[0m and [3mr[0m is in [3my[0m, then the rulers of [3mr[0m in [3m\beta[0m is the set obtained by adding [47m(NOT[0m [3mp[0m[47m)[0m to the set of rulers of [3mr[0m in [3my[0m; 3. otherwise, the rulers of [3mr[0m in [3m\beta[0m is the empty set. Thus, in the term [47m(if a (if b (h c) (h d)) (g c))[0m, both [47ma[0m and [47mb[0m rule the first occurrence of [47mc[0m and the occurrence of [47m(h c)[0m. In addition, [47ma[0m and [47m(not b)[0m rule the occurrences of [47md[0m and [47m(h d)[0m. Finally, [47m(not a)[0m rules the second occurrence of [47mc[0m and [47m(g c)[0m. Note that our definition of ``rulers'' does not include every test that has to be true in order to reach the occurrence in question. For example, [47mp[0m does not rule the occurrence of [47ma[0m in [47m(car (if p a b))[0m even though the only way evaluation can reach [47ma[0m is if [47mp[0m is true. The rulers of the occurrence of [47ma[0m in that term is the empty set, because that term is not a call of [47mif[0m. However, [47mp[0m does rule the occurrence of [47ma[0m in the equivalent term [47m(if p (car a) (car b))[0m. The reason we've defined rulers this way has to do with heuristics in the ACL2 theorem prover. [31;1mPrinciple of Structural Recursion:[0m A definition, [47m(defun[0m [3mf[0m [47m([0m[3mv_1[0m ... [3mv_n[0m[47m)[0m [3m\beta[0m[47m)[0m will be allowed (for now) only if it satisfies these four restrictions: 1. The symbol being defined, [3mf[0m, must be ``new,'' i.e., not already in use as a function symbol in any axiom. 2. The formal variables, [3mv_1[0m, ... , [3mv_n[0m, must be distinct variable symbols. 3. The body, [3m\beta[0m, must be a term, it must use no new function symbol other than (possibly) [3mf[0m, and the only variable symbols in it are among the formals. 4. There is an [3mi[0m such that [47m(consp[0m [3mv_i[0m[47m)[0m rules every recursive call of [3mf[0m in [3m\beta[0m and for every recursive call ([3mf[0m [3ma_1[0m ... [3ma_n[0m) in [3m\beta[0m, [3ma_i[0m is a [47mcar[0m/[47mcdr[0m nest around [3mv_i[0m. We call [3mv_i[0m a [3mmeasured formal[0m. An acceptable definition adds the axiom [47m([0m[3mf[0m [3mv_1[0m ... [3mv_n[0m[47m) = [0m[3m\beta[0m. (Maybe explore <<[47m[defun][0m>>? Be advised, however, that ACL2's Definitional Principle does not insist on the last condition above, about there being a [47mcar[0m/[47mcdr[0m nest in a certain argument of every recursive call. Instead it insists that ``some measure of the arguments decreases'' in every recursive call. We'll make that clearer later. But ACL2's Definitional Principle allows all the definitions described above.) [31;1mProblem 30. [0m Explain why these restrictions rule out the spurious definitions of [47mf[0m in the problems above. [31;1mProblem 31. [0m Is the following definition allowed under the above restrictions? (defun f (x) (if (consp x) (if (consp (cdr x)) (f (cdr (cdr x))) nil) t)) [31;1mProblem 32. [0m Is the following definition allowed? (defun f (x y) (if (consp x) (f (cons nil x) (cdr y)) y)) [31;1mProblem 33. [0m Is the following definition allowed? (defun f (x y) (if (consp x) (f (cons nil y) (cdr x)) y)) [31;1mProblem 34. [0m Is the following definition allowed? (defun f (x) (if (not (consp x)) x (f (cdr (cdr x))))) [31;1mProblem 35. [0m Is the following sequence of definitions allowed? (defun endp (x) (not (consp x))) (defun f (x) (if (endp x) nil (cons nil (f (cdr x))))) [31;1mProblem 36. [0m Is the following definition allowed? (defun f (x y) (if (consp x) (f (cdr x) (cons nil y)) y)) [31;1mProblem 37. [0m Is the following definition allowed? (defun f (x y) (if (consp x) (f (cdr x) (f (cdr x) y)) y)) [31;1mProblem 38. [0m Is the following sequence of definitions allowed? (defun f (x) (if (consp x) (g (cdr x)) x)) (defun g (x) (if (consp x) (f (cdr x)) x)) Next: Structural Induction (see [R-AND-I-STRUCTURAL-INDUCTION]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-function-definitions (recursion-and-induction) "Recursion and Induction: Function Definitions To define a function, we use the form [47m(defun[0m [3mf[0m ([3mv_1[0m ... [3mv_n[0m) [3m\beta[0m[47m)[0m where [3mf[0m is the function symbol being defined, the [3mv_i[0m are the formal variables or simply [3mformals[0m, and [3m\beta[0m is the body of the function. Operationally, a definition means that to compute [47m([0m[3mf[0m [3ma_1[0m ... [3ma_n[0m[47m)[0m one can evaluate the actuals, [3ma_i[0m, bind the formals, [3mv_i[0m , to those values, and compute [3m\beta[0m instead. Logically speaking, a definition adds the axiom that [47m([0m[3mf[0m [3mv_1[0m ... [3mv_n[0m[47m)[0m is equal to [3m\beta[0m. Here are the Lisp definitions of the standard propositional logic connectives: (defun not (p) (if p nil t)) (defun and (p q) (if p q nil)) (defun or (p q) (if p p q)) (defun implies (p q) (if p (if q t nil) t)) (defun iff (p q) (and (implies p q) (implies q p))) Note that in Lisp, [47mand[0m and [47mor[0m are not Boolean valued. E.g., [47m(and t 3)[0m and [47m(or nil 3)[0m both return [47m3[0m. This is unimportant if they are only used propositionally, e.g., [47m(and t 3)[0m <-> [47m(and 3 t)[0m <-> [47mt[0m, if ``<->'' means [47miff[0m. In Lisp, any non-nil value is propositionally equivalent to [47mt[0m. Here is a recursive definition that copies a [47mcons[0m-structure. (defun tree-copy (x) (if (consp x) (cons (tree-copy (car x)) (tree-copy (cdr x))) x)) For example, the term [47m(tree-copy '((1 . 2) . 3))[0m has the value [47m((1 . 2) . 3)[0m. (Maybe explore <<[47m[defun][0m>>? Be advised, however, that ACL2's Definitional Principle imposes restrictions that may not make sense just yet.) In the exercises below you may wish to define auxiliary (``helper'') functions as part of your solutions. [31;1mProblem 8. [0m Define [47mapp[0m to concatenate two lists. For example [47m(app '(1 2 3) '(4 5 6))[0m evaluates to [47m(1 2 3 4 5 6)[0m. [31;1mProblem 9. [0m Define [47mrev[0m to reverse a list. For example, [47m(rev '(1 2 3))[0m evaluates to [47m(3 2 1)[0m. [31;1mProblem 10. [0m Define [47mmapnil[0m to ``copy'' a list, replacing each element by [47mnil[0m. Thus, [47m(mapnil '(1 2 3))[0m evaluates to [47m(nil nil nil)[0m. [31;1mProblem 11. [0m The result of ``swapping'' the pair [47m([3mx[0m[47m . [3my[0m[47m)[0m is the pair [47m([3my[0m[47m . [3mx[0m[47m)[0m. Define [47mswap-tree[0m to swap every cons in a binary tree. Thus, [47m(swap-tree '((1 . 2) . (3 . 4)))[0m evaluates to [47m((4 . 3) . (2 . 1))[0m. [31;1mProblem 12. [0m Define [47mmem[0m to take two arguments and determine if the first one occurs as an element of the second. Thus, [47m(mem '2 '(1 2 3))[0m evaluates to [47mt[0m and [47m(mem '4 '(1 2 3))[0m evaluates to [47mnil[0m. [31;1mProblem 13. [0m Define the list analogue of subset, i.e., [47m(sub x y)[0m returns [47mt[0m or [47mnil[0m according to whether every element of [47mx[0m is an element of [47my[0m. [31;1mProblem 14. [0m Define [47mint[0m to take two lists and to return the list of elements that appear in both. Thus [47m(int '(1 2 3 4) '(2 4 6))[0m evaluates to [47m(2 4)[0m. [31;1mProblem 15. [0m Define [47m(tip e x)[0m to determine whether [47me[0m occurs as a tip of the binary tree [47mx[0m. [31;1mProblem 16. [0m Define [47m(flatten x)[0m to make a list containing the tips of the binary tree [47mx[0m. Thus, [47m(flatten '((1 . 2) . (3 . 4)))[0m evaluates to [47m(1 2 3 4)[0m. [31;1mProblem 17. [0m Define [47mevenlen[0m to recognize lists of even length. Thus, [47m(evenlen '(1 2 3))[0m evaluates to [47mnil[0m and [47m(evenlen '(1 2 3 4))[0m evaluates to [47mt[0m. Next: Axioms (see [R-AND-I-AXIOMS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-identity (r-and-i-data-types) "Recursion and Induction: Identity Since a pair can typically be written down in several different ways, you might ask how can you tell whether one display is equal to another? For example, how can you determine that [47m(1 . (2 . (3 . nil)))[0m is the same pair as [47m(1 2 3)[0m, which is also the same pair as [47m(1 . (2 3))[0m? One way is to write each constant in a canonical form. If their canonical forms are different, the two constants are different. For integers, the standard canonical form is to use base 10 and to drop leading [47m0[0ms and ``+'' signs. For symbols, it is to write everything in upper case. For conses, the canonical form is to eschew the use of the three conventions noted in the previous section and to use dot notation exclusively. Next: Data Types Exercises (see [R-AND-I-DATA-TYPES-EXERCISES]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-inadequacies-of-structural-recursion (recursion-and-induction) "Recursion and Induction: Inadequacies of Structural Recursion Recall that to avoid logical contradictions introduced by ``bad'' definitions, we imposed four restrictions. The fourth restriction is very constraining: we can only recur on a [47mcar[0m/[47mcdr[0m component of some argument and must ensure that that argument satisfies [47mconsp[0m before the recursion. The intent of this restriction was to guarantee that the newly defined function terminates. It is beyond the scope of these notes to explain why termination is linked to consistency, but the intuitive explanation is that if the recursion cannot go on forever then, for every combination of constants to which we apply the function, we could compute a value satisfying the definitional equation (given enough computational resources). From this observation we can conclude there exists a mathematical function satisfying the definitional equation -- namely, the one that maps inputs to the computed outputs. Thus, given a model of the theory before we added the definition, we could extend it to a model of the theory with the new definition added. This establishes the consistency of the extended theory. (Remark. In fact, our definitions produce [3mconservative extensions[0m, which we will briefly discuss below.) The problem with the current version of our fourth restriction is that it is too syntactic -- it insists, literally, on the use of [47mconsp[0m, [47mcar[0m, and [47mcdr[0m. In the ACL2 definitional principle, the fourth restriction is less syntactic: it requires that we be able to [3mprove[0m that the recursion terminates. That is, when we propose a new definition, a conjecture is generated and if this conjecture can be proved as a theorem, then we know the function terminates. The basic idea of this conjecture is to establish that some measure of the function's arguments decreases in size as the function recurs, and this decreasing cannot go on forever. If the size were, say, a natural number, then we would know the decreasing could not go on forever, because the arithmetic less-than relation, [47m<[0m, is [3mwell-founded[0m on the natural numbers. We discuss well-foundedness more in the next section. [31;1mProblem 82. [0m Define [47m(cc x)[0m to return the number of conses in [47mx[0m. The name stands for ``cons count.'' [31;1mProblem 83. [0m Prove that [47mcc[0m always returns a non-negative [47minteger[0m. [31;1mProblem 84. [0m If we define (defun atom (x) (not (consp x))) (defun first (x) (car x)) (defun rest (x) (cdr x)) then the following ``definition'' of [47mtree-copy[0m is logically equivalent to the acceptable version, but it is considered unacceptable by our syntactic fourth restriction: (defun tree-copy (x) (if (atom x) x (cons (tree-copy (first x)) (tree-copy (rest x))))) Write down a conjecture that captures the idea that the argument to [47mtree-copy[0m is getting smaller (as measured by [47mcc[0m) as the function recurs. [31;1mProblem 85. [0m Prove the conjecture above. Note that since [47mcc[0m is a natural number, this proof establishes that [47mtree-copy[0m terminates on all objects. [31;1mProblem 86. [0m Define [47m(rm e x)[0m to return the result of removing the first occurrence (if any) of [47me[0m from [47mx[0m. Thus, [47m(rm 3 '(1 2 3 4 3 2 1))[0m is [47m(1 2 4 3 2 1)[0m. [31;1mProblem 87. [0m Show that the following function terminates. (defun f23 (e x) (if (mem e x) (f23 e (rm e x)) 23)) Note that no [47mcar[0m/[47mcdr[0m nest around [47mx[0m is equal to the result of [47m(rm 3 '(1 2 3))[0m. Thus, [47mf23[0m exhibits a kind of recursion we have not seen previously -- but we know it terminates. [31;1mProblem 88. [0m It is obvious that [47m(f23 e x)[0m always return [47m23[0m. Can you prove that with our current logical machinery? The key to these termination proofs is that the less-than relation is well-founded on the natural numbers. But consider this famous function, known as Ackermann's function, (defun ack (x y) (if (zp x) 1 (if (zp y) (if (equal x 1) 2 (+ x 2)) (ack (ack (- x 1) y) (- y 1))))) Observe that [47mack[0m can generate some very large numbers. For example, [47m(ack 4 3)[0m is [47m65536[0m. [31;1mProblem 89. [0m [47mAck[0m always terminates. Why? Don't feel compelled to give a formal proof, just an informal explanation. In the next three sections of this document we will discuss a well-founded relation far more powerful than less-than on the natural numbers. We will then connect that well-foundedness machinery to a new version of the Definitional Principle, so that we can admit many interesting recursive functions, including [47mack[0m. We will also connect the well-foundedness machinery to a new version of the Induction Principle, so that we can prove that [47m(f23 e x)[0m is [47m23[0m -- and far more interesting theorems. Next: The Ordinals (see [R-AND-I-ORDINALS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-induction-principle (recursion-and-induction) "Recursion and Induction: The Induction Principle The Induction Principle allows one to derive an arbitrary formula, [3m\psi[0m, from * [3mBase Case[0m : [47m(implies (and (not[0m [3mq_1[0m[47m) ... (not[0m [3mq_k[0m[47m))[0m [3m\psi[0m[47m)[0m, and * [3mInduction Step(s)[0m : For each 1<=[3mi[0m<=[3mk[0m, [47m(implies (and [0m[3mq_i[0m[47m [0m[3m\psi[0m/[3m\sigma_{i,1}[0m ... [3m\psi[0m/[3m\sigma_{i,h_i}[0m[47m)[0m [47m [0m[3m\psi[0m[47m)[0m, provided that for terms [3mm[0m, [3mq_1[0m,...[3mq_k[0m, and substitutions [3m\sigma_{i,j}[0m (1<=[3mi[0m<=[3mk[0m, 1<=[3mj[0m<=[3mh_i[0m), the following are theorems: * [3mOrdinal Conjecture[0m : [47m(o-p[0m [3mm[0m[47m)[0m, and * [3mMeasure Conjecture(s)[0m : For each 1<=[3mi[0m<=[3mk[0m and 1<=[3mj[0m<=[3mh_i[0m, [47m(implies [0m[3mq_i[0m[47m (o< [0m[3mm[0m/[3m\sigma_{i,j}[0m [3mm[0m[47m))[0m. Next: Relations Between Recursion and Induction (see [R-AND-I-RELATIONS-BETWEEN-RECURSION-AND-INDUCTION]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-introduction (recursion-and-induction) "Recursion and Induction: Introduction The language we will use is a subset of Lisp called ACL2. ACL2, which stands for [3mA Computational Logic for Applicative Common Lisp[0m, is both a functional programming language based on Common Lisp and a first-order mathematical theory with induction. There is a mechanical theorem prover for ACL2, but we do not discuss it here. A good way to learn to use that theorem prover is first to master the art of recursive definition and inductive proof. This course on Recursion and Induction uses a tiny fragment of full ACL2. We describe just enough formal machinery to study recursion and induction in an interesting context. This document is self-contained. You'll need nothing besides this document, a pencil and paper (or a computer), and time and space to think. In the interest of scholarly completeness, we provide an annotated bibliography; see [r-and-i-annotated-bibliography]. But none of the documents listed there is necessary for the problems here. These notes are meant to be read linearly, like a text book. Each section ends with a link to the next section. For example, the link to the section after this one looks like this, Data Types (see [R-AND-I-DATA-TYPES]); but don't go there yet! Throughout these notes you will see see links to resources on the web and some of those links take you out of the [3mRecursion and Induction[0m notes and into ACL2's online manual. Those ``external'' links appear like this, ``(Maybe explore <<...>>?)''. These links lead to related discussions of issues and features of the ACL2 system. You'll need to be connected to the web to access some of these pages, unless you have installed ACL2 on your system and built the full manual and books documentation. See the [installation] instructions. We provide this material for students who want to explore further. But these links are technically irrelevant to the student who is focused on working the exercises here, even if your ultimate goal is to learn how to use ACL2. First, learn how to do the exercises here. In a second pass, where you're trying to get ACL2 to do your proofs, you might want to explore. And remember, it is easy for explorers to get lost! [31;1mIf you are working your way through [3mRecursion and Induction[0m[31;1m and decide to follow one of these explorer links be sure to use the ``Back'' feature of your browser to return to these notes.[0m Next: Data Types (see [R-AND-I-DATA-TYPES]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-more-inadequacies-of-the-definitional-principle (recursion-and-induction) "Recursion and Induction: More Inadequacies of the Definitional Principle Next: Mutual Recursion Inadequacies (see [R-AND-I-MUTUAL-RECURSION-INADEQUACIES]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS])) Subtopics [R-and-i-mutual-recursion-inadequacies] Recursion and Induction: Mutual Recursion Inadequacies [R-and-i-problematic-nested-recursion] Recursion and Induction: Problematic Nested Recursion") (r-and-i-more-problems (recursion-and-induction) "Recursion and Induction: More Problems [31;1mProblem 106. [0m Here is a way to flatten a binary tree without using an auxiliary function. Admit this definition. (defun flatten! (x) (if (atom x) (cons x nil) (if (atom (car x)) (cons (car x) (flatten! (cdr x))) (flatten! (cons (caar x) (cons (cdar x) (cdr x))))))) [31;1mProblem 107. [0m Prove [47m(equal (flatten! x) (flatten x))[0m. [31;1mProblem 108. [0m Here is a clever way to determine if two binary trees have the same fringe. Admit this function (and its subroutine). (defun samefringe (x y) (if (or (atom x) (atom y)) (equal x y) (and (equal (car (gopher x)) (car (gopher y))) (samefringe (cdr (gopher x)) (cdr (gopher y)))))) where (defun gopher (x) (if (or (atom x) (atom (car x))) x (gopher (cons (caar x) (cons (cdar x) (cdr x)))))) [31;1mProblem 109. [0m Prove (equal (samefringe x y) (equal (flatten x) (flatten y))) [31;1mProblem 110. [0m The curious recursions in [47mgopher[0m and [47msamefringe[0m are due to John McCarthy, who viewed [47mgopher[0m as a model of a co-routine. Explain what he was thinking. [31;1mProblem 111. [0m Below is a model of the functional behavior of QuickSort. Note that [47mrel[0m is defined as a ``higher order'' function that can apply any of four relations. (defun rel (fn x y) (if (equal fn '<<=) (<<= x y) (if (equal fn '>>=) (<<= y x) (if (equal fn '<<) (and (<<= x y) (not (equal x y))) (and (<<= y x) (not (equal x y))))))) (defun filter (fn x e) (if (endp x) nil (if (rel fn (car x) e) (cons (car x) (filter fn (cdr x) e)) (filter fn (cdr x) e)))) (defun qsort (x) (if (endp x) nil (if (endp (cdr x)) x (app (qsort (filter '<< (cdr x) (car x))) (cons (car x) (qsort (filter '>>= (cdr x) (car x)))))))) Prove that [47mqsort[0m produces an ordered permutation of its input. [31;1mProblem 112. [0m Prove that the length of a list of distinct natural numbers is no greater than its maximum element plus one. This is sometimes called the Pigeon Hole Principle. [31;1mProblem 113. [0m Imagine a simple list being treated as a ``memory.'' If [3ma[0m is a natural number less than the length of the memory, then [3ma[0m is an ``address'' and we can use [47mnth[0m to fetch the contents. This is ``dereferencing'' [3ma[0m. If [3ma[0m is not an address, we will say it is ``data.'' Now consider the idea of taking an object and a memory and dereferencing until we get to data. The following function counts the steps; it returns the symbol [47minfinite[0m if a loop is detected. (defun deref-cnt (ptr mem seen) (if (addressp ptr mem) (if (mem ptr seen) 'infinite (inc (deref-cnt (nth ptr mem) mem (cons ptr seen)))) 0)) where (defun len (x) (if (consp x) (+ 1 (len (cdr x))) 0)) (defun inc (x) (if (integerp x) (+ 1 x) 'infinite)) (defun addressp (ptr m) (and (natp ptr) (< ptr (len m)))) Admit [47mderef-cnt[0m. [31;1mProblem 114. [0m This is a fact every undergraduate knows. The number of times you can dereference (without being in a loop) is bounded by the size of the memory (plus one for the initial probe). Prove it. (<= (deref-cnt ptr mem nil) (+ 1 (len mem))) Since [47mderef-cnt[0m returns the non-number [47minfinite[0m if it is a loop, and since ACL2 arithmetic treats non-numbers as [47m0[0m, this theorem is trivial when the process loops. You may therefore explicitly add the hypothesis [47m(integerp (deref-cnt ptr mem nil))[0m if you are uncomfortable dealing with the non-numeric defaults. [31;1mProblem 115. [0m Here is the familiar definition of the Fibonacci function and a more efficient one (``fast Fibonacci''). (defun fib (i) (if (zp i) 0 (if (equal i 1) 1 (+ (fib (- i 1)) (fib (- i 2)))))) (defun ffib (i j k) (if (zp i) j (if (equal i 1) k (ffib (- i 1) k (+ j k))))) Prove they are equal in the following sense (equal (ffib n 0 1) (fib n)) [31;1mProblem 116. [0m Prove (equal (rotn (len x) x) x) where (defun rot (x) (if (endp x) nil (app (cdr x) (cons (car x) nil)))) (defun rotn (n x) (if (zp n) x (rotn (- n 1) (rot x)))) [31;1mProblem 117. [0m In this problem we explore binary arithmetic. Let a [3mbit vector[0m be a list of Booleans; it is convenient to suppose that the least significant bit is the car. A bit vector represents a natural number in the usual binary encoding. Define [47m(vadd x y)[0m to return a bit vector representing the sum of the numbers represented by the bit vectors [47mx[0m and [47my[0m. Formally specify and prove that [47mvadd[0m is correct. Obviously, this problem can be expanded to include other binary arithmetic operations and implementations. Next: More Inadequacies of the Definitional Principle (see [R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-mutual-recursion-inadequacies (r-and-i-more-inadequacies-of-the-definitional-principle) "Recursion and Induction: Mutual Recursion Inadequacies [31;1mProblem 118. [0m Mutual recursion is (still) not allowed by our statement of the Definitional Principle. However, suppose that somehow the axioms produced by the following pair of definitions were available. (defun fx (x) (if (consp x) (cons (fx (car x)) (gx (cdr x))) x)) (defun gx (x) (if (consp x) (cons (gx (car x)) (fx (cdr x))) x)) Prove (equal (fx x) x) [31;1mProblem 119. [0m Develop a methodology for dealing with mutual recursion. That is, explain how you can use our Definitional Principle to introduce two functions [47mfx[0m and [47mgx[0m that can be shown to satisfy the ``defining equations'' for [47mfx[0m and [47mgx[0m above. Your methodology should work for any clique of mutually recursive functions that can be shown to terminate under the [47mo<[0m relation. [31;1mProblem 120. [0m We say [47mx[0m is an [3mexpression[0m if (a) [47mx[0m is a symbol or (b) [47mx[0m is a list of the form [47m([0m[3mf[0m [3me_1[0m ... [3me_n[0m[47m)[0m, where [3mf[0m is a symbol and the [3me_i[0m are expressions. Define [47m(expr x)[0m to recognize expressions. [31;1mProblem 121. [0m An [3mexpression substitution[0m is a list of 2-tuples of the form [47m([0m[3mv[0m [3mexpr[0m[47m)[0m, where [3mv[0m is a symbol and [3mexpr[0m is an expression. Define [47msubstitution[0m to recognize expression substitutions. [31;1mProblem 122. [0m Define [47m(slash x s)[0m so that it substitutes the expression substitution [47ms[0m into the expression [47mx[0m, e.g., it returns [47mx[0m/[47ms[0m. [31;1mProblem 123. [0m Prove that if [47ms[0m is an expression substitution and [47mx[0m is an expression, then [47m(slash x s)[0m is an expression. (Maybe explore <<[mutual-recursion]>>?) Next: Problematic Nested Recursion (see [R-AND-I-PROBLEMATIC-NESTED-RECURSION]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-numbers (r-and-i-data-types) "Recursion and Induction: Numbers The only numbers we will use are the integers, written in the usual way, e.g., [47m-3[0m, [47m0[0m, and [47m123[0m. ACL2 allows integers to be written in other ways, e.g., [47m00123[0m, [47m+123[0m, [47m246/2[0m, [47m#b1111011[0m, [47m#o173[0m and [47m#x7B[0m are all ways to write [47m123[0m. However, we will always write them in conventional decimal notation. ACL2 also supports rationals, e.g., [47m1/3[0m and [47m22/7[0m, and complex rationals, e.g., [47m#c(5 2)[0m, which is more commonly written 5 + 2[3mi[0m. Lisp, but not ACL2, supports floating point numbers, e.g., [47m3.1415[0m and [47m31415E-4[0m. (Maybe explore <<[numbers]>>?) Next: Characters (see [R-AND-I-CHARACTERS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-ordinals (recursion-and-induction) "Recursion and Induction: The Ordinals The ordinals are an extension of the naturals that captures an essential notion of ordering. They were invented by Georg Cantor in the late nineteen century. While controversial during Cantor's lifetime, ordinals are among the richest and deepest mines of mathematics. We only scratch the surface here. Think of each natural number as denoted by a sequence of strokes, i.e., 0 0 1 | 2 | | 3 | | | 4 | | | | ... ... \omega | | | | | ... The limit of that progression is the ordinal [3m\omega[0m, an infinite sequence of strokes. Ordinal addition is just concatenation. Observe that adding one to the front of [3m\omega[0m produces [3m\omega[0m again, which gives rise to a standard definition of [3m\omega[0m: the least ordinal such that adding another stroke at the beginning does not change the ordinal. We denote by [3m\omega[0m + [3m\omega[0m or [3m\omega[0m\times2 the ``doubly infinite'' sequence that we might write as follows. \omega \times 2 | | | | | ... | | | | | ... One way to think of [3m\omega[0m\times2 is that it is obtained by replacing each stroke in 2 (| |) by [3m\omega[0m. Thus, one can imagine [3m\omega[0m\times3, [3m\omega[0m\times4, etc., which leads ultimately to the idea of [3m\omega[0m\times[3m\omega[0m, the ordinal obtained by replacing each stroke in [3m\omega[0m by [3m\omega[0m. This is also written as [3m\omega[0m^2. \omega^2 | | | | | ... | | | | | ... | | | | | ... | | | | | ... | | | | | ... ... We can analogously construct [3m\omega[0m^3 by replacing each stroke in [3m\omega[0m by [3m\omega[0m^2 (which, it turns out, is the same as replacing each stroke in [3m\omega[0m^2 by [3m\omega[0m). That is, we can construct [3m\omega[0m^3 as [3m\omega[0m copies of [3m\omega[0m^2, and so on. This ultimately suggests [3m\omega[0m^[3m\omega[0m. We can then stack [3m\omega[0ms, i.e., [3m\omega[0m^([3m\omega[0m^[3m\omega[0m), etc. Consider the limit of all of those stacks, [47m [3m\omega[0m[47m^([3m\omega[0m[47m^([3m\omega[0m[47m^([3m\omega[0m[47m^([3m\omega[0m[47m^([3m\omega[0m[47m^([3m\omega[0m[47m^ ... )))))). [0m That limit is [3m\epsilon_0[0m. (As the subscript suggests, there are lots more ordinals! But ACL2 stops with [3m\epsilon_0[0m.) Despite the plethora of ordinals, we can represent all the ones below [3m\epsilon_0[0m in ACL2, using lists. Below we begin listing some ordinals up to [3m\epsilon_0[0m; the reader can fill in the gaps at his or her leisure. We show in the left column the conventional notation and in the right column the ACL2 object representing the corresponding ordinal. ordinal | | ACL2 representation | | | | 0 | | 0 | 1 | | 1 | 2 | | 2 | 3 | | 3 | ... | | ... | [3m\omega[0m | | ((1 . 1) . 0) | [3m\omega[0m + 1 | | ((1 . 1) . 1) | [3m\omega[0m + 2 | | ((1 . 1) . 2) | ... | | ... | [3m\omega[0m\times2 | | ((1 . 2) . 0) | ([3m\omega[0m\times2) + 1 | | ((1 . 2) . 1) | ... | | ... | [3m\omega[0m\times3 | | ((1 . 3) . 0) | ([3m\omega[0m\times3) + 1 | | ((1 . 3) . 1) | ... | | ... | [3m\omega[0m^2 | | ((2 . 1) . 0) | ... | | ... | [3m\omega[0m^2 + [3m\omega[0m\times4 + 3 | | ((2 . 1) (1 . 4) . 3) | ... | | ... | [3m\omega[0m^3 | | ((3 . 1) . 0) | ... | | ... | [3m\omega[0m^[3m\omega[0m | | ((((1 . 1) . 0) . 1) . 0) | ... | | ... | [3m\omega[0m^[3m\omega[0m + [3m\omega[0m^99 + [3m\omega[0m\times4 + 3 | | ((((1 . 1) . 0) . 1) (99 . 1) (1 . 4) . 3) | ... | | ... | [3m\omega[0m^([3m\omega[0m^2) | | ((((2 . 1) . 0) . 1) . 0) | ... | | ... | [3m\omega[0m^([3m\omega[0m^[3m\omega[0m) | | ((((((1 . 1) . 0) . 1) . 0) . 1) . 0) | ... | | ... | We say an ordinal is ``finite'' if it is not a cons and we define [47m(o-finp x)[0m to recognize finite ordinals. Of course, if [47mx[0m is an ordinal and finite, it is a natural number. But by defining [47mo-finp[0m this way we ensure that if an ordinal is not finite we can recur into it with [47mcdr[0m. To manipulate ordinals we define functions that access the first exponent, the first coefficient, and the rest of the ordinal: (defun o-first-expt (x) (if (o-finp x) 0 (car (car x)))) (defun o-first-coeff (x) (if (o-finp x) x (cdr (car x)))) (defun o-rst (x) (cdr x)) For example, if [47mx[0m is the representation of [3m\omega[0m^e\times[3mc[0m + [3mr[0m then [47m(o-first-expt x)[0m is [3me[0m, [47m(o-first-coeff x)[0m is [3mc[0m and [47m(o-rst x)[0m is [3mr[0m. Here is the definition of [47mo-p[0m, the function that recognizes ordinals. (defun o-p (x) (if (o-finp x) (natp x) (and (consp (car x)) (o-p (o-first-expt x)) (not (equal 0 (o-first-expt x))) (natp (o-first-coeff x)) (< 0 (o-first-coeff x)) (o-p (o-rst x)) (o< (o-first-expt (o-rst x)) (o-first-expt x))))) (The ACL2 definition is syntactically different but equivalent.) The function [47mo<[0m is the ``less than'' relation on ordinals. We show its definition below. But study the definition of [47mo-p[0m first. It says that an ordinal is a list of pairs, terminated by a natural number. Each pair [47m(e . c)[0m consists of an exponent [47me[0m and a coefficient [47mc[0m and represents ([3m\omega[0m^e)\times[3mc[0m. The exponents are themselves ordinals and the coefficients are non-0 naturals. Importantly, the exponents are listed in strictly descending order. The list represents the ordinal sum of its elements plus the final natural number. Thus, ordinals can be viewed as polynomials. By insisting on the ordering of exponents we can readily compare two ordinals, using [47mo<[0m below, in much the same way we can compare polynomials. (defun o< (x y) (if (o-finp x) (or (not (o-finp y)) (< x y)) (if (o-finp y) nil (if (equal (o-first-expt x) (o-first-expt y)) (if (equal (o-first-coeff x) (o-first-coeff y)) (o< (o-rst x) (o-rst y)) (< (o-first-coeff x) (o-first-coeff y))) (o< (o-first-expt x) (o-first-expt y)))))) (The ACL2 definition is syntactically different but equivalent.) [31;1mProblem 90. [0m Which is smaller, ordinal a or ordinal b? 1. a = [47m23[0m, b = [47m100[0m 2. a = [47m1000000[0m, b = [47m((1 . 1) . 0)[0m 3. a = [47m((2 . 1) . 0)[0m, b = [47m((1 . 2) . 0)[0m 4. a = [47m((3 . 5) (1 . 25) . 7)[0m, b = [47m((3 . 5) (2 . 1) . 3)[0m 5. a = [47m((((2 . 1) . 0) . 5) . 3)[0m, b = [47m((((1 . 1) . 0) . 5) (1 . 25) . 7)[0m [31;1mProblem 91. [0m The [47mo<[0m operation can be reduced to lexicographic comparison. Define [47mm2[0m so that it constructs ``lexicographic ordinals'' from two arbitrary natural numbers. Specifically, show that the following is a theorem: (implies (and (natp i1) (natp j1) (natp i2) (natp j2)) (and (o-p (m2 i1 j1)) (iff (o< (m2 i1 j1) (m2 i2 j2)) (if (equal i1 i2) (< j1 j2) (< i1 i2))))) The crucial property of [47mo<[0m is that it is [3mwell-founded on the ordinals[0m. That is, there is no infinite sequence of ordinals, [3mx_i[0m such that ... [3mx_3[0m [47mo<[0m [3mx_2[0m [47mo<[0m [3mx_1[0m [47mo<[0m [3mx_0[0m. [31;1mProblem 92. [0m What is the longest decreasing chain of ordinals starting from the ordinal [47m10[0m? What is the longest decreasing chain of ordinals starting from the ordinal [47m((1 . 1) . 0)[0m? [31;1mProblem 93. [0m Construct an infinitely descending [47mo<[0m chain of objects. Note that by the well-foundedness of [47mo<[0m on the ordinals, your chain will not consist entirely of ordinals! [31;1mProblem 94. [0m Prove that [47mo<[0m is well-founded on our ordinals, i.e., those recognized by [47mo-p[0m. Caution: Using the logical machinery we have developed here, it is not possible to state that [47mo<[0m is well-founded on the ordinals: that requires an existential quantifier and infinite sequences. However, it can be done in a traditional set theoretic setting. That is, the theorem that [47mo<[0m is well-founded is a ``meta-theorem'', it can be proved about our system but it cannot be proved within our system. Our definitional and induction principles are built on the assumption that [47mo<[0m is well-founded on the ordinals recognized by [47mo-p[0m. Thus, if some ordinal measure of the arguments of a recursive function decreases according to [47mo<[0m in every recursive call, the recursion cannot go on forever. The representation of ordinals described here is a version of Cantor's Normal Form. See [reference 5] (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY]) or the online documentation topics <<[ordinals]>> and <<[o-p]>>, from which some of the examples above have been chosen. Next: The Definitional Principle (see [R-AND-I-DEFINITIONAL-PRINCIPLE]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-pairs (r-and-i-data-types) "Recursion and Induction: Pairs Pairs are written in Lisp's [3mdot notation[0m. Instead of conventional Cartesian notation, e.g., < [47m1[0m, [47m2[0m >, Lisp replaces the angle brackets with parentheses and the comma with a dot, [47m(1 . 2)[0m. Thus, [47m((1 . 2) . (3 . 4))[0m is the pair containing the pair [47m(1 . 2)[0m in its left component and the pair [47m(3 . 4)[0m in its right. In high school, you might have written this object as <<1, 2>,<3, 4>>. Note that exactly one object must follow the dot; for example, the notation [47m((1 . 2) . 3 4)[0m is illegal. However, one or more objects may precede the dot, as discussed below. In Lisp, pairs are called [3mconses[0m. Non-conses are called [3matoms[0m. The left component is called the [3mcar[0m and the right component is called the [3mcdr[0m (pronounced ``cudder''). (Remark. The names come from the original implementation of Lisp on the IBM 704. That machine had a 36-bit word that was logically divided into two parts, the ``address'' and the ``decrement.'' Lisp used such words to represent a [47mcons[0m cell. The address part pointed to the left component and the decrement part pointed to the right component. Thus, the operations were [47mcar[0m (``contents of address of register'') and [47mcdr[0m (``contents of decrement of register'').) Lisp provides three conventions for writing parenthesized constants. * [47mNil[0m can be written [47m()[0m. * A pair of the form [47m([3mx[0m[47m . nil)[0m may be written [47m([3mx[0m[47m)[0m. * A pair of the form [47m([3mx[0m[47m . ([3my[0m[47m ...))[0m may be written [47m([3mx[0m[47m [3my[0m[47m ...)[0m. Thus, the cons [47m(1 . (2 . (3 . nil)))[0m may be written [47m(1 2 3)[0m. This suggests the most common use of conses: to represent linked lists or sequences. The special role of [47mnil[0m in these conventions is the only sense in which [47mnil[0m is ``the empty list.'' Any object can be treated as a list! If a cons is being treated as a list, then its car is the first element and its cdr is treated as a list of the remaining elements. If an atom is treated as a list, it is treated as the empty list. [47mNil[0m is just the most common atom used in this way. Thus, the elements of [47m(1 . (2 . (3 . nil)))[0m are [47m1[0m, [47m2[0m, and [47m3[0m, respectively. The length of this list is three. If [47m((1 . 2) . (3 . 4))[0m is treated as a list, its elements are [47m(1 . 2)[0m and [47m3[0m; its length is two. The [47m4[0m is just the terminal atom. [47m((1 . 2) . (3 . nil))[0m and [47m((1 . 2) . (3 . 4))[0m are different objects, but when treated as lists they have the same two elements. Here is a list of the symbols naming the summer months: [47m(June July August)[0m. It could also be written [47m(JUNE . (JULY . (AUGUST . NIL)))[0m and many other ways. (Maybe explore <<[conses]>>?) Next: identity (see [R-AND-I-IDENTITY]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-peano-arithmetic (r-and-i-arithmetic) "Recursion and Induction: Peano Arithmetic Recall that the integers are being treated as atomic objects in this document. But we can explore elementary arithmetic by thinking of a list of [3mn[0m [47mnil[0ms as a representation for the natural number [3mn[0m. We will call such a list a ``nat.'' Thus, [47m(nil nil nil)[0m is a nat, but [47m3[0m is a natural number. [31;1mProblem 65. [0m Define [47m(nat x)[0m to recognize nats. [31;1mProblem 66. [0m Define [47m(plus x y)[0m to take two arbitrary lists (even ones that are not nats) and to return the nat representing the sum of their lengths. By defining [47mplus[0m this way we ensure that it always returns a nat and that it is commutative. [31;1mProblem 67. [0m Define [47m(times x y)[0m to take two arbitrary lists and to return the nat representing the product of their lengths. [31;1mProblem 68. [0m Define [47m(power x y)[0m to take two arbitrary lists and to return the nat representing the exponentiation of their lengths, i.e., if [47mx[0m and [47my[0m are of lengths [3mi[0m and [3mj[0m, then [47m(power x y)[0m should return the nat representing [3mi^j[0m. [31;1mProblem 69. [0m Define [47m(lesseqp x y)[0m to return [47mt[0m or [47mnil[0m according to whether the length of [47mx[0m is less than or equal to that of [47my[0m. [31;1mProblem 70. [0m Define [47m(evennat x)[0m to return [47mt[0m or [47mnil[0m according to whether the length of [47mx[0m is even. [31;1mProblem 71. [0m Prove (implies (nat i) (equal (plus i nil) i)) [31;1mProblem 72. [0m Prove (equal (plus (plus i j) k) (plus i (plus j k))) [31;1mProblem 73. [0m Prove (equal (plus i j) (plus j i)) [31;1mProblem 74. [0m Prove (equal (times (times i j) k) (times i (times j k))) [31;1mProblem 75. [0m Prove (equal (times i j) (times j i)) [31;1mProblem 76. [0m Prove (equal (power b (plus i j)) (times (power b i) (power b j))) [31;1mProblem 77. [0m Prove (equal (power (power b i) j) (power b (times i j))) [31;1mProblem 78. [0m Prove (lesseqp i i) [31;1mProblem 79. [0m Prove (implies (and (lesseqp i j) (lesseqp j k)) (lesseqp i k)) [31;1mProblem 80. [0m Prove (equal (lesseqp (plus i j) (plus i k)) (lesseqp j k)) [31;1mProblem 81. [0m Prove (implies (and (evennat i) (evennat j)) (evennat (plus i j))) Next: ACL2 Arithmetic (see [R-AND-I-ACL2-ARITHMETIC]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-problematic-nested-recursion (r-and-i-more-inadequacies-of-the-definitional-principle) "Recursion and Induction: Problematic Nested Recursion [31;1mProblem 124. [0m The following function cannot be admitted. Explain why. (defun f5 (x) (if (zp x) 0 (+ 1 (f5 (f5 (- x 1)))))) When the function being defined, [3mf[0m, is called recursively on the value of a nested recursive call, e.g., [47m([0m[3mf[0m ... ([3mf[0m ... [47m))[0m, we say the definition exhibits [3mnested recursion[0m. We have already seen some examples of nested recursion: (defun mcflatten (x a) (if (consp x) (mcflatten (car x) (mcflatten (cdr x) a)) (cons x a))) (defun ack (x y) (if (zp x) 1 (if (zp y) (if (equal x 1) 2 (+ x 2)) (ack (ack (- x 1) y) (- y 1))))) [31;1mProblem 125. [0m What makes the recursion in [47mf5[0m, which cannot be admitted, different from that in [47mmcflatten[0m and [47mack[0m, which can be admitted? It is often possible to deal with problematic nested recursion, by admitting a different but related definition and then proving that it is equivalent to the one you wanted. The next few problems illustrate this. [31;1mProblem 126. [0m Admit the following (defun f5 (x) (if (zp x) 0 (if (< (nfix (f5 (- x 1))) (nfix x)) (+ 1 (f5 (f5 (- x 1)))) 'undef))) [31;1mProblem 127. [0m Prove (implies (natp x) (<= (f5 x) x)) [31;1mProblem 128. [0m Prove (equal (f5 x) (if (zp x) 0 (+ 1 (f5 (f5 (- x 1)))))) You may think that problematic nested recursion never arises in actual formal models. Think again! Consider a graph reachability algorithm, as might be implemented in the mark phase of a garbage collector. Suppose a memory location can hold a pair of addresses, a single address, or data. Given an initial address, mark all the reachable addresses, avoiding any possible cycles in the data. When the mark algorithm arrives at an address, [3mptr[0m, containing a pair, it marks that address, explores and marks one of the addresses, and then explores and marks the other. The algorithm terminates because marking increases the number of marked addresses in memory and the number of addresses is bounded. But note that when the algorithm explores and marks the second address it does so on the memory produced by exploring and marking the first address and the parent. This is problematic nested recursion: if the inner recursion [3munmarked[0m some of the marked addresses, the outer sweep might get caught in a cycle. But we cannot prove that the algorithm does not unmark things until we have admitted the model! [31;1mProblem 129. [0m Let [47mm[0m be a list representing a RAM, with 0-based addressing modeled by [47mnth[0m. An address is legal if it is a natural less than the length of the memory. If an address contains a pair, we explore both the [47mcar[0m and the [47mcdr[0m. If an address contains an address, we explore that address. Cycles may be present. The function below collects the list of all addresses reachable from a given one. This definition exhibits problematic nested recursion. (defun reachables (ptr m seen) (if (addressp ptr m) (if (mem ptr seen) seen (if (consp (nth ptr m)) (reachables (car (nth ptr m)) m (reachables (cdr (nth ptr m)) m (cons ptr seen))) (reachables (nth ptr m) m (cons ptr seen)))) seen)) Use the method suggested by the [47mf5[0m problems to define a function satisfying the equation above. [31;1mProblem 130. [0m Consider the problem of reversing a list. Our standard definition, [47mrev[0m, uses an auxiliary function, [47mapp[0m. The tail-recursive version, [47mrev1[0m, uses an additional formal parameter. Below is a definition of reverse that has only one parameter and no auxiliary functions. This definition was proposed by Rod M. Burstall in the early 1970s as an entertaining puzzle. It exhibits problematic nested recursion. (defun rmb (x) (if (consp x) (if (consp (cdr x)) (cons (car (rmb (cdr x))) (rmb (cons (car x) (rmb (cdr (rmb (cdr x))))))) (cons (car x) nil)) nil)) Show how this definition can be derived from an admissible one. [31;1mProblem 131. [0m Suppose [47mrmb[0m is known to satisfy the ``defining equation'' that would be added by the [47mdefun[0m above had it been admissible. That is, suppose that is the only equation known for [47mrmb[0m. Prove (equal (rmb x) (rev x)) Next: Still More Problems (see [R-AND-I-STILL-MORE-PROBLEMS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-relations-between-recursion-and-induction (recursion-and-induction) "Recursion and Induction: Relations Between Recursion and Induction Informally speaking, a recursive definition is ``ok'' if there is an ordinal measure that decreases in every recursive call. Thus, the recursion cannot go on forever. In a simple recursion on naturals down to 0 by -1, the value of the function on 5 is determined recursively by its value on 4, which is determined recursively by its value on 3, which is determined recursively by its value on 2, which is determined recursively by its value on 1, which is determined recursively by its value on 0, which is specified explicitly in the definition. An inductive proof is ``ok'' if there is an ordinal measure that decreases in every induction hypothesis. Thus, any concrete instance of the conjecture could be proved by ``pumping'' forward a finite number of times from the base cases. Given a simple inductive proof over the naturals, the conjecture is true on 0 because it was proved explicitly in the base case, so it is true on 1 by the induction step, so it is true on 2 by the induction step, so it is true on 3 by the induction step, so it is true on 4 by the induction step, so it is true on 5 by the induction step. Clearly these two concepts are duals. The formal statements of the two principles look more different than they are. They both require us to prove that a measure returns an ordinal and that some substitutions make the measure decrease under some tests. But there seems to be a lot less indexing going on in the Definitional Principle than in the Induction Principle. That is due to language and the two different uses of the principles. The Definitional Principle is designed to tell us whether a definitional equation is ok. The Induction Principle is designed to tell us whether a set of formulas is an ok inductive argument. So the Definitional Principle talks about the tests in [47mIF[0ms and the substitution built from each recursive call, whereas the Induction Principle talks about the tests in the [3mi[0mth formula and the substitution that created the [3mj[0mth induction hypothesis of the [3mi[0mth formula. But the key insight is: [3mEvery ok definition suggests an ok induction[0m! We call this the induction [3msuggested by[0m the definition. It is easiest to see this by considering a particular, generic definition and thinking about what had to be proved to admit it, what induction it suggests, what has to be proved for that induction to be legal, and when the suggested induction might be useful. Suppose the following definition has been admitted, justified by measure term [47m(m x a)[0m. Note that the body is an [47mIF[0m-tree, and there are three tips in the [47mIF[0m-tree; the first tip contains two recursive calls, the second tip contains one recursive call, and the third tip contains no recursive calls. (defun f (x a) (if (test1 x a) (if (test2 x a) (h ; tip 1 (f (d1 x a) (a1 x a)) ; rec call 1,1 (f (d2 x a) (a2 x a))) ; rec call 1,2 (g ; tip 2 (f (d3 x a) (a3 x a)))) ; rec call 2,1 (b x a))) ; tip 3 To admit this definition we had to prove: [3mOrdinal Conjecture[0m (o-p (m x a)) [3mMeasure Conjecture 1,1[0m (implies (and (test1 x a) (test2 x a)) (o< (m (d1 x a) (a1 x a)) (m x a))) [3mMeasure Conjecture 1,2[0m (implies (and (test1 x a) (test2 x a)) (o< (m (d2 x a) (a2 x a)) (m x a))) [3mMeasure Conjecture 2,1[0m (implies (and (test1 x a) (not (test2 x a))) (o< (m (d3 x a) (a3 x a)) (m x a))) Suppose we want to prove [47m(p x a)[0m, by induction according to the scheme ``suggested'' by [47m(f x a)[0m. Here is the scheme: [3mBase Case[0m ; for tip 3 (implies (not (test1 x a)) (p x a)) [3mInduction Step 1[0m ; for tip 1 (implies (and (test1 x a) (test2 x a) (p (d1 x a) (a1 x a)) ; for rec call 1,1 (p (d2 x a) (a2 x a))) ; for rec call 1,2 (p x a)) [3mInduction Step 2[0m ; for tip 2 (implies (and (test1 x a) (not (test2 x a)) (p (d3 x a) (a3 x a))) ; for rec call 2,1 (p x a)) This induction is produced by the following parameter choices in the Induction Principle: [3m\psi[0m | [47m(p x a)[0m | [3mm[0m | [47m(m x a)[0m | [3mq_1[0m | [47m(and (test1 x a) (test2 x a))[0m | [3mq_2[0m | [47m(and (test1 x a) (not (test2 x a)))[0m | [3m\sigma_{1,1}[0m | [47m{x <-- (d1 x a), a <-- (a1 x a)}[0m | [3m\sigma_{1,2}[0m | [47m{x <-- (d2 x a), a <-- (a2 x a)}[0m | [3m\sigma_{2,1}[0m | [47m{x <-- (d3 x a), a <-- (a3 x a)}[0m | It should be obvious to you how these choices are determined from the definition of [47mf[0m with measure [47m(m x a)[0m. For example, [3mq_1[0m is the conjunction of the tests leading to the first tip containing recursive calls of [47mf[0m, and the substitutions [3m\sigma_{1,j}[0m are the substitutions derived from the recursive calls in that tip. The measure conjectures required by the Induction Principle for this choice of parameters are exactly the same as the measure conjectures verified when the Definitional Principle was used to admit [47mf[0m! That is, to use an induction suggested by an already-admitted recursive function, no additional measure conjectures have to be proved. (Remark on ``exactly the same'' above. We have propositionally simplified the defining condition for the Base Case. The Induction Principle says it is [47m(and (not [3mq_1[0m[47m) (not [3mq_2[0m[47m))[0m and the literal instantiation of that here would be [47m(and (not (and (test1 x a) (test2 x a))) (not (and (test1 x a) (not (test2 x a)))))[0m, but that is propositionally equivalent to [47m(not (test1 x a))[0m.) But why might this induction be interesting or useful for proving [47m(p x a)[0m? The answer depends on [47m(p x a)[0m, of course. But the most common situation is that we choose the induction scheme suggested by some recursive function used in the conjecture to be proved. So suppose [47m(f x a)[0m occurs in [47m(p x a)[0m. Why is the suggested induction likely to be helpful? Consider the Base Case and the two Induction Steps. In the Base Case, the [47m(f x a)[0m occurring in [47m(p x a)[0m can be replaced by tip 3 of the definition of [47mf[0m, [47m(b x a)[0m because the test in the Base Case of the induction is the test leading to the non-recursive exit from the definition. So [47mf[0m has been eliminated from the proof of the Base Case. Now consider Induction Step 1. The [47m(f x a)[0m occurring in [47m(p x a)[0m can be replaced by tip 1 of the definition of [47mf[0m, namely (h ; tip 1 (f (d1 x a) (a1 x a)) ; rec call 1,1 (f (d2 x a) (a2 x a))) ; rec call 1,2 because the tests in Induction Step 1 are the tests leading to tip 1 of the definition. But notice that the induction hypothesis labeled ``for rec call 1,1'' in Induction Step 1 gives us a hypothesis about recursive call 1,1 --- because the occurrence of [47m(f x a)[0m in [47m(p x a)[0m becomes an occurrence of [47m(f (d1 x a) (a1 x a))[0m when we apply the substitution [3m\sigma_{1,1}[0m to it. Similarly, the induction hypothesis labeled ``for rec call 1,2'' gives us a hypothesis about call 1,2. Thus, the proof of Induction Step 1 boils down to proving, ``if the two recursive calls in this tip have the property we're proving, then [47mh[0m of those two calls has the property.'' While not exactly eliminating [47mf[0m from the proof, it provides us with all the information that we have a right to suppose about [47mf[0m in this case. Usually the proof of this step requires a lemma about [47mp[0m and [47mh[0m, e.g., ``if [47ma[0m and [47mb[0m have property [47mp[0m, then so does [47m(h a b)[0m.'' Such a lemma would eliminate [47mf[0m, and if we had that lemma the proof of Induction Step 1 would be done. The proof of Induction Step 2 is analogous. Thus, we see that there may well be some heuristic value in using the induction suggested by [47m(f x a)[0m whenever you are trying to prove a property of [47m(f x a)[0m. Occasionally it is necessary to use an induction suggested by a function not appearing in the conjecture, but when that occurs it is usually some easily recognized ``mash up'' of other functions appearing in the conjecture. [31;1mProblem 102. [0m Recall the previously admitted (defun f1 (i j) (if (and (natp i) (natp j) (< i j)) (f1 (+ 1 i) j) 1)) Prove [47m(equal (f1 i j) 1)[0m. [31;1mProblem 103. [0m Recall the previously admitted (defun f2 (x) (if (equal x nil) 2 (and (f2 (car x)) (f2 (cdr x))))) Prove [47m(equal (f2 x) 2)[0m. [31;1mProblem 104. [0m Recall the previously admitted (defun f3 (x y) (if (and (endp x) (endp y)) 3 (f3 (cdr x) (cdr y)))) Prove [47m(equal (f3 x y) 3)[0m. [31;1mProblem 105. [0m Recall the previously admitted (defun f4 (x y q) (if (p x) (if q (f4 y (dn x) (not q)) (f4 y (up x) (not q))) 4)) Prove [47m(equal (f4 x y q) 4)[0m. These simple inductive exercises drive home the point that once a function has been admitted (proved to terminate) then we can do inductions to ``unwind'' it. Students so frequently see induction limited to ``[3mp(n)[0m implies [3mp(n+1)[0m '' that it is easy to forget that every total recursive function gives rise to an induction that is appropriate for it. Next: More Problems (see [R-AND-I-MORE-PROBLEMS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-still-more-problems (recursion-and-induction) "Recursion and Induction: Still More Problems The next several problems will lead you to define a tautology checker in ACL2 and to prove that it is sound and complete. This is an excellent exercise if you are interested in theorem proving. [31;1mProblem 132. [0m An [3m[47mIF[0m[3m-expression[0m is a cons whose car is [47mIF[0m. A [3mquote[0m is a cons whose car is [47mQUOTE[0m. A [3mvariable[0m is anything besides an [47mIF[0m-expression or a quote. An [3mexpression[0m is a variable, a quote, or an [47mIF[0m-expression. Note: By these definitions, any object is an expression. But we typically think of [47mIF[0m-expressions as being of the form [47m(IF[0m [3ma_1[0m [3ma_2[0m [3ma_3[0m[47m)[0m and quotes being of the form [47m(QUOTE[0m [3ma[0m[47m)[0m. But rather than check that they are of this form we will just use [47mcar[0m and [47mcdr[0m to chew into [47mIF[0ms and quotes to access the desired substructure, which we will call ``arguments'' one, two, and three. An [3massignment[0m is a list of pairs, [47m([0m[3mvar[0m[47m . [0m[3mval[0m[47m)[0m, where [3mvar[0m is a variable and [3mval[0m is an arbitrary object (but is typically a Boolean). We define the [3mvalue[0m of an expression under an assignment as follows. The [3mvalue[0m of a variable is the [3mval[0m associated with that variable, or [47mnil[0m if the variable is not bound. The [3mvalue[0m of a quote is the first argument of the quote. The value of an [47mIF[0m-expression depends on the value, [3mv[0m, of the first argument. If [3mv[0m is [47mnil[0m, the value of the [47mIF[0m-expression is the value of its third argument; otherwise, it is the value of its second argument. Define these concepts. [31;1mProblem 133. [0m An expression is said to be in [3m[47mIF[0m[3m-normal form[0m if no [47mIF[0m-expression in the expression has an [47mIF[0m-expression in its first argument. Thus, [47m(IF A (IF B C D) D)[0m is in [47mIF[0m-normal form, but [47m(IF (IF A B 'NIL) C D)[0m is not. It is possible to put an expression into [47mIF[0m-normal form while preserving its value, by repeatedly transforming it with the rule: (IF (IF a b c) x y) = (IF a (IF b x y) (IF c x y)) Define the notion of [47mIF[0m-normal form and admit the function [47mnorm[0m that normalizes an expression while preserving its value. [31;1mProblem 134. [0m Given an expression in [47mIF[0m-normal form, define the function [47mtautp[0m that explores all feasible branches through the expression and determines that every output is non-[47mnil[0m. We say a branch is [3minfeasible[0m if, in order to traverse it during evaluation under an assignment, the assignment would have to assign some variable both [47mnil[0m and non-[47mnil[0m. [31;1mProblem 135. [0m Define [47mtautology-checker[0m to recognize whether an expression has a non-[47mnil[0m value under all possible assignments. [31;1mProblem 136. [0m Prove that your [47mtautology-checker[0m is [3msound[0m: if it says an expression is a tautology, then the value of the expression is non-[47mnil[0m, under any assignment. [31;1mProblem 137. [0m Prove that your [47mtautology-checker[0m is [3mcomplete[0m: if it fails to recognize an expression, then some assignment falsifies the expression. This concludes [3mRecursion and Induction[0m. Are you interested in learning how to use the ACL2 theorem prover? (Maybe explore <<[introduction-to-the-theorem-prover]>>?) Next: Annotated Bibliography (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-strings (r-and-i-data-types) "Recursion and Induction: Strings Strings in our subset of ACL2 are written as sequences of ASCII characters between successive [3mstring quotes[0m. For example, here is a string: [47m"Hello, World!"[0m. For the purposes of this document, we will treat strings as atomic objects, though it is actually possible to construct and deconstruct them in terms of lists of character objects. (Maybe explore <<[strings]>>?) Next: Symbols (see [R-AND-I-SYMBOLS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-structural-induction (recursion-and-induction) "Recursion and Induction: Structural Induction [31;1mProblem 39. [0m Given the definition (defun f (x) (if (consp x) (f (cdr x)) t)) can you prove the theorem [47m(equal (f x) t)[0m using the logical machinery we have described so far? ACL2 supports inductive proofs. Its Induction Principle is quite general and involves the notion of the ordinals and well-foundedness. We use a much simpler principle for now. A substitution [3m\sigma[0m is a [3m[47mcar[0m[3m/[47mcdr[0m[3m substitution[0m on [3mv[0m if the binding (image) of [3mv[0m under [3m\sigma[0m is a [47mcar[0m/[47mcdr[0m nest around [3mv[0m. The other bindings of [3m\sigma[0m are unrestricted. For example, [3m\sigma[0m = {[47mx <-- (car x), y <-- (cons (cdr x) y)[0m} is a [47mcar[0m/[47mcdr[0m substitution on [47mx[0m. [31;1mPrinciple of Structural Induction:[0m Let [47m[3m\psi[0m[47m[0m be the term representing a conjecture. [47m[3m\psi[0m[47m[0m may be proved by selecting an ``induction'' variable [47mx[0m, selecting a set of [47mcar[0m/[47mcdr[0m substitutions on [47mx[0m [3m\sigma_1[0m, ... , [3m\sigma_n[0m, and by proving the following subgoals: [3mBase Case:[0m (implies (not (consp x)) [3m\psi[0m) and [3mInduction Step:[0m (implies (and (consp x) ; [3mtest[0m [3m\psi[0m/[3m\sigma_1[0m ; [3minduction hypothesis 1[0m . . . [3m\psi[0m/[3m\sigma_n[0m) ; [3minduction hypothesis n[0m [3m\psi[0m) ; [3minduction conclusion[0m Here is an example Induction Step. (implies (and (consp x) [3m\psi[0m/{x <-- (car x), y <-- (app x y)} [3m\psi[0m/{x <-- (cdr (cdr x)), y <-- (cons x y)} [3m\psi[0m/{x <-- (cdr (cdr x)), y <-- y}) [3m\psi[0m) Let us use structural induction to prove a theorem about [47mtree-copy[0m. Recall the definition. (defun tree-copy (x) (if (consp x) (cons (tree-copy (car x)) (tree-copy (cdr x))) x)) [31;1mTheorem[0m [47m(equal (tree-copy x) x)[0m. [31;1mProof[0m. Name the formula above *1. We prove *1 by induction. One induction scheme is suggested by this conjecture -- namely the one that unwinds the recursion in [47mtree-copy[0m. If we let [3m\psi[0m denote *1 above then the induction scheme we'll use is (and (implies (not (consp x)) [3m\psi[0m) (implies (and (consp x) [3m\psi[0m/{x <-- (car x)} [3m\psi[0m/{x <-- (cdr x)}) [3m\psi[0m)). When applied to the goal at hand the above induction scheme produces the following two nontautological subgoals. Subgoal *1/2 (implies (not (consp x)) (equal (tree-copy x) x)). But simplification reduces this to [47mt[0m, using the definition of [47mtree-copy[0m and the primitive axioms. Subgoal *1/1 (implies (and (consp x) ; [3mhyp 1[0m (equal (tree-copy (car x)) (car x)) ; [3mhyp 2[0m (equal (tree-copy (cdr x)) (cdr x))) ; [3mhyp 3[0m (equal (tree-copy x) x)). But simplification reduces this to [47mt[0m, using the definition of [47mtree-copy[0m and the primitive axioms. That completes the proof of *1. [31;1mQ.E.D.[0m Let us look more closely at the reduction of Subgoal *1/1. Consider the left-hand side of the concluding equality. Here is how it reduces to the right-hand side under the hypotheses. (tree-copy x) = [3m{def [0m[47mtree-copy[0m[3m}[0m (if (consp x) (cons (tree-copy (car x)) (tree-copy (cdr x))) x) = [3m{hyp 1 and Axiom 6}[0m (if t (cons (tree-copy (car x)) (tree-copy (cdr x))) x) = [3m{Axioms 2 and 1}[0m (cons (tree-copy (car x)) (tree-copy (cdr x))) = [3m{hyp 2}[0m (cons (car x) (tree-copy (cdr x))) = [3m{hyp 3}[0m (cons (car x) (cdr x)) = [3m{Axioms 11 and 6 and hyp 1}[0m x This proof is of a very routine nature: induct so as to unwind some particular function appearing in the conjecture and then use the axioms and definitions to simplify each case to [47mt[0m. The problems below refer to function symbols defined in previous exercises. Try to prove them for the definitions you wrote. But if you cannot, then use the definitions we use in our solutions. For each conjecture below that is not a theorem, show a counterexample and then try to write the theorem ``suggested'' by the conjecture. For example, add a hypothesis that restricts some variable so that the conjecture holds; you may even need to introduce new concepts. [31;1mWarning:[0m Proving implications by induction is a little tricky. Suppose you're trying to prove [47m(implies (p x) (q x))[0m by induction and you choose the substitution that replaces [47mx[0m by [47m(cdr x)[0m. So the Induction Step will be Induction Step. (implies (and (consp x) (implies (p (cdr x)) (q (cdr x)))) (implies (p x) (q x))). By propositional calculus, this is the same as (implies (and (consp x) (implies (p (cdr x)) (q (cdr x))) (p x)) (q x)). Many students act like the induction hypothesis is that [47m(q (cdr x))[0m is true and use that to show [47m(q x)[0m is true. But the induction hypothesis is actually [47m(implies (p (cdr x)) (q (cdr x)))[0m. It tells us that [47m(q (cdr x))[0m is true [3mif[0m [47m(p (cdr x))[0m is true! So it often happens that you will use the [47m(p x)[0m hypothesis to prove [47m(p (cdr x))[0m is true. Only then can you use [47m(q (cdr x))[0m to work on [47m(q x)[0m. [31;1mProblem 40. [0m Prove (equal (app (app a b) c) (app a (app b c))). [31;1mProblem 41. [0m Prove (equal (app a nil) a) [31;1mProblem 42. [0m Prove (equal (mapnil (app a b)) (app (mapnil a) (mapnil b))) [31;1mProblem 43. [0m Prove (equal (rev (mapnil x)) (mapnil (rev x))) [31;1mProblem 44. [0m Prove (equal (rev (rev x)) x) [31;1mProblem 45. [0m Prove (equal (swap-tree (swap-tree x)) x) [31;1mProblem 46. [0m Prove (equal (mem e (app a b)) (or (mem e a) (mem e b))) [31;1mProblem 47. [0m Prove (equal (mem e (int a b)) (and (mem e a) (mem e b))) [31;1mProblem 48. [0m Prove (sub a a) [31;1mProblem 49. [0m Prove (implies (and (sub a b) (sub b c)) (sub a c)) [31;1mProblem 50. [0m Prove (sub (app a a) a) [31;1mProblem 51. [0m Define (defun mapnil1 (x a) (if (consp x) (mapnil1 (cdr x) (cons nil a)) a)) Formalize and then prove the remark ``On lists of [47mnil[0ms, [47mmapnil1[0m is commutative.'' [31;1mProblem 52. [0m Define [47m(perm x y)[0m so that it returns [47mt[0m if lists [47mx[0m and [47my[0m are permutations of each other; otherwise it returns [47mnil[0m. [31;1mProblem 53. [0m Prove (perm x x) [31;1mProblem 54. [0m Prove (implies (perm x y) (perm y x)). [31;1mProblem 55. [0m Prove (implies (and (perm x y) (perm y z)) (perm x z)) For several of the problems below it is necessary to have a total ordering relation. Let [47m<<=[0m be a non-strict total order, i.e., a Boolean function that enjoys the following properties: (and (<<= x x) ; Reflexive (implies (and (<<= x y) ; Anti-symmetric (<<= y x)) (equal x y)) (implies (and (<<= x y) ; Transitive (<<= y z)) (<<= x z)) (or (<<= x y) ; Total (<<= y x))) Actually, there is such a function in ACL2 and it is called [47mlexorder[0m. But we use the more suggestive name ``[47m<<=[0m'' here. On the integers, [47m<<=[0m is just [47m<=[0m, but it orders all ACL2 objects. [31;1mProblem 56. [0m Define [47m(ordered x)[0m so that it returns [47mt[0m or [47mnil[0m according to whether each pair of adjacent elements of [47mx[0m are in the relation [47m<<=[0m. For example, [47m(ordered '(1 3 3 7 12))[0m would evaluate to [47mt[0m and [47m(ordered '(1 3 7 3 12))[0m would evaluate to [47mnil[0m. [31;1mProblem 57. [0m Define [47m(isort x)[0m to take an arbitrary list and return an [47mordered[0m permutation of it. [31;1mProblem 58. [0m Prove (ordered (isort x)). [31;1mProblem 59. [0m Prove (perm (isort x) x). [31;1mProblem 60. [0m Prove (equal (isort (rev (isort x))) (isort x)). We thank Pete Manolios for suggesting this problem. [31;1mProblem 61. [0m Define (defun rev1 (x a) (if (consp x) (rev1 (cdr x) (cons (car x) a)) a)) Prove (equal (rev1 x nil) (rev x)) [31;1mProblem 62. [0m Prove (equal (mapnil1 x nil) (mapnil x)) [31;1mProblem 63. [0m Prove (not (equal x (cons x y))) [31;1mProblem 64. [0m Define (defun mcflatten (x a) (if (consp x) (mcflatten (car x) (mcflatten (cdr x) a)) (cons x a))) Prove (equal (mcflatten x nil) (flatten x)) Next: Arithmetic (see [R-AND-I-ARITHMETIC]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-substitutions (recursion-and-induction) "Recursion and Induction: Substitutions A [3msubstitution[0m is a set {[3mv_0[0m <-- [3mt_0[0m, [3mv_1[0m <-- [3mt_1[0m, ...} where each [3mv_i[0m is a distinct variable symbol and each [3mt_i[0m is a term. If, for a given substitution [3m\sigma[0m and variable [3mv[0m, there is an [3mi[0m such that [3mv[0m is [3mv_i[0m, we say [3mv[0m [3mis bound[0m by [3m\sigma[0m. If [3mv[0m is bound by [3m\sigma[0m, then the [3mbinding[0m of [3mv[0m in [3m\sigma[0m is [3mt_i[0m, for the [3mi[0m such that [3mv_i[0m is [3mv[0m. (In set theory, a substitution is just a finite function that maps the [3mv_i[0m to their respective [3mt_i[0m.) The result of [3mapplying[0m a substitution [3m\sigma[0m to a term [3mterm[0m is denoted [3mterm[0m/[3m\sigma[0m and is defined as follows. If [3mterm[0m is a variable, then [3mterm[0m/[3m\sigma[0m is either the binding of [3mterm[0m in [3m\sigma[0m or is [3mterm[0m itself, depending on whether [3mterm[0m is bound in [3m\sigma[0m. If [3mterm[0m is a quoted constant, [3mterm[0m/[3m\sigma[0m is [3mterm[0m. Otherwise, [3mterm[0m is [47m([0m[3mf[0m [3ma_1[0m ... [3ma_n[0m[47m)[0m and [3mterm[0m/[3m\sigma[0m is [47m([0m[3mf[0m [3ma_1[0m/[3m\sigma[0m ... [3ma_n[0m/[3m\sigma[0m[47m)[0m. [31;1mProblem 6. [0m Suppose [3m\sigma[0m is {x <-- (car a), y <-- (cdr x)} What term is [47m(car (cons x (cons y (cons '"Hello" z))))[0m/[3m\sigma[0m? Next: Abbreviations for Terms (see [R-AND-I-ABBREVIATIONS-FOR-TERMS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-symbols (r-and-i-data-types) "Recursion and Induction: Symbols Unlike many languages, Lisp provides symbols as primitive data objects. Some example symbols are [47mt[0m, [47mnil[0m, [47mLOAD[0m, [47mSTORE[0m, [47mICONST_0[0m, [47mprime-factors[0m, [47m++[0m, and [47mfile77[0m. For the purposes of this document, we will treat symbols as atomic objects, though it is actually possible to construct and deconstruct them in terms of strings. For the purposes of this document, a symbol is a sequence of alphabetic characters, digits, and/or certain signs (specifically, [47m+[0m, [47m-[0m, [47m*[0m, [47m/[0m, [47m=[0m, [47m<[0m, [47m>[0m, [47m?[0m, [47m![0m, [47m$[0m, [47m&[0m, and [47m_[0m (underscore)) that cannot be read as a number. Case is unimportant. Symbols are parsed to have the greatest length possible under the rules above. Thus, [47mxy[0m is one symbol, not two symbols ([47mx[0m and [47my[0m) written without intervening whitespace! Note that [47mt[0m and [47mT[0m are different ways to write the same symbol, as are [47mnil[0m, [47mNil[0m, and [47mNIL[0m. [47mT[0m and [47mnil[0m are called the [3mBoolean symbols[0m. [47mT[0m is frequently used to denote [3mtrue[0m and [47mnil[0m is used to denote [3mfalse[0m. For reasons that will become apparent, [47mnil[0m is also used as the [3mempty list[0m. (Maybe explore <<[symbols]>>?) Next: Pairs (see [R-AND-I-PAIRS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-table-of-contents (recursion-and-induction) "Recursion and Induction Table of Contents) Recursion and Induction Table of Contents * Preface and Acknowledgments (see [RECURSION-AND-INDUCTION]) * Introduction (see [R-AND-I-INTRODUCTION]) * Data Types (see [R-AND-I-DATA-TYPES]) * Terms (see [R-AND-I-TERMS]) * Substitutions (see [R-AND-I-SUBSTITUTIONS]) * Abbreviations for Terms (see [R-AND-I-ABBREVIATIONS-FOR-TERMS]) * Function Definitions (see [R-AND-I-FUNCTION-DEFINITIONS]) * Axioms (see [R-AND-I-AXIOMS]) * Terms as Formulas (see [R-AND-I-TERMS-AS-FORMULAS]) * Definitions Revisited (see [R-AND-I-DEFINITIONS-REVISITED]) * Structural Induction (see [R-AND-I-STRUCTURAL-INDUCTION]) * Arithmetic (see [R-AND-I-ARITHMETIC]) * Inadequacies of Structural Recursion (see [R-AND-I-INADEQUACIES-OF-STRUCTURAL-RECURSION]) * The Ordinals (see [R-AND-I-ORDINALS]) * The Definitional Principle (see [R-AND-I-DEFINITIONAL-PRINCIPLE]) * The Induction Principle (see [R-AND-I-INDUCTION-PRINCIPLE]) * Relations Between Recursion and Induction (see [R-AND-I-RELATIONS-BETWEEN-RECURSION-AND-INDUCTION]) * More Problems (see [R-AND-I-MORE-PROBLEMS]) * More Inadequacies of the Definitional Principle (see [R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE]) * Still More Problems (see [R-AND-I-STILL-MORE-PROBLEMS]) * Annotated Bibliography (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY])") (r-and-i-terms (recursion-and-induction) "Recursion and Induction: Terms For the purposes of this document, a [3mterm[0m is a variable symbol, a quoted constant, or a function application written as a sequence, enclosed in parentheses, consisting of a function symbol of arity [3mn[0m followed by [3mn[0m terms. Since [47mcar[0m is a function symbol of arity one and [47mcons[0m is a function symbol of arity two, and [47mx[0m and [47my[0m are variable symbols, then [47m(cons (car x) y)[0m is a term. In more conventional notation this term would be written [3mcons[0m ([3mcar[0m ([3mx[0m ), [3my[0m ). We call [47m(car x)[0m and [47my[0m the [3mactual expressions[0m or [3mactuals[0m of the [3mfunction call[0m [47m(cons (car x) y)[0m. Semantically, terms are interpreted with respect to (i) an assignment binding variable symbols to constants and (ii) an interpretation of function symbols as mathematical functions. For example, suppose the variables [47mx[0m and [47my[0m are bound, respectively, to the constants [47m1[0m and [47m(2 3 4)[0m, and suppose the function symbol [47mcons[0m is interpreted as the function that constructs ordered pairs (as it always is). Then the meaning or [3mvalue[0m of the term [47m(cons x y)[0m is [47m(1 . (2 3 4))[0m or, equivalently, [47m(1 2 3 4)[0m. That is, the value of a variable is determined by the variable assignment; the value of a quoted constant is that constant; and the value of a function application, [47m([0m[3mf[0m [3ma_1[0m ... [3ma_n[0m[47m)[0m, is the result of applying the mathematical function assigned to [3mf[0m to the values of the actuals, [3ma_i[0m. ACL2 provides an infinite number of [3mvariable symbols[0m, whose syntax is that of symbols. Some example variable symbols are [47mx[0m, [47ma1[0m, and [47mtemp[0m. The symbols [47mt[0m and [47mnil[0m are not legal variable symbols. A [3mquoted constant[0m is written by prefixing an integer, a character object, a string, or a symbol by a single quote mark. For example, [47m't[0m, [47m'nil[0m, [47m'-3[0m, [47m'[0m[47m#\A[0m, [47m'"Hello World!"[0m and [47m'LOAD[0m are quoted constants. Note that we do not consider [47m'(1 2 3)[0m a quoted constant. This is a mere technicality. We will shortly introduce some abbreviations that allow us to write [47m'(1 2 3)[0m as an abbreviation for [47m(cons '1 (cons '2 (cons '3 'nil)))[0m. ACL2 also has an infinite number of [3mfunction symbols[0m each of which has an associated [3marity[0m or number of arguments. For the moment we will concern ourselves with six primitive function symbols: [47mcons[0m, [47mcar[0m, [47mcdr[0m, [47mconsp[0m, [47mif[0m, and [47mequal[0m, described below. Note that we implicitly specify the arity of each primitive function symbol. [47m(cons [3mx[0m[47m [3my[0m[47m)[0m - construct and return the ordered pair [47m([3mx[0m[47m . [3my[0m[47m)[0m. [47m(car [3mx[0m[47m)[0m - return the left component of [3mx[0m, if [3mx[0m is a pair; otherwise, return [47mnil[0m. [47m(cdr [3mx[0m[47m)[0m - return the right component of [3mx[0m, if [3mx[0m is a pair; otherwise, return [47mnil[0m. [47m(consp [3mx[0m[47m)[0m - return [47mt[0m if [3mx[0m is a pair; otherwise return [47mnil[0m. [47m(if [3mx[0m[47m [3my[0m[47m [3mz[0m[47m)[0m - return [3mz[0m if [3mx[0m is [47mnil[0m; otherwise return [3my[0m. [47m(equal [3mx[0m[47m [3my[0m[47m)[0m - return [47mt[0m if [3mx[0m and [3my[0m are identical; otherwise return [47mnil[0m. With these primitives we cannot do anything interesting with numbers, characters, strings, and symbols. They are just tokens to put into or take out of pairs. But we can explore most of the interesting issues in recursion and induction in this setting! (Maybe explore <<[term]>>?) Note that if the terms [3m\alpha[0m and [3m\beta[0m both evaluate to the same value, [3mv[0m, then the term [47m(equal[0m [3m\alpha[0m [3m\beta[0m[47m)[0m evaluates to [47mt[0m. For example, the terms [47m(car (cons '3 '4))[0m and [47m'3[0m both evaluate to the value [47m3[0m, so the term [47m(equal (car (cons '3 '4)) '3)[0m evaluates to [47mt[0m. [31;1mProblem 3. [0m Which of the utterances below are terms? 1. [47m(car (cdr x))[0m 2. [47m(cons (car x y) z)[0m 3. [47m(cons 1 2)[0m 4. [47m(cons '1 '2)[0m 5. [47m(cons one two)[0m 6. [47m(cons 'one 'two)[0m 7. [47m(equal '1 (car (cons '2 '3)))[0m 8. [47m(if t 1 2)[0m 9. [47m(if 't '1 '2)[0m 10. [47m(car (cons (cdr hi-part) (car lo-part)))[0m 11. [47mcar(cons x y)[0m 12. [47mcar(cons(x,y))[0m 13. [47m(cons 1 (2 3 4))[0m [31;1mProblem 4. [0m For each constant below, write a term whose value is the constant. 1. [47m((1 . 2) . (3 . 4))[0m 2. [47m(1 2 3)[0m 3. [47m((1 . t) (2 . nil) (3 . t))[0m 4. [47m((A . 1) (B . 2))[0m [31;1mProblem 5. [0m For each term below, write the constant to which it evaluates. 1. [47m(cons (cons '1 '2) (cons (cons '3 '4) 'nil))[0m 2. [47m(cons '1 (cons '2 '3))[0m 3. [47m(cons 'nil (cons (cons 'nil 'nil) 'nil))[0m 4. [47m(if 'nil '1 '2)[0m 5. [47m(if '1 '2 '3)[0m 6. [47m(equal 'nil (cons 'nil 'nil))[0m 7. [47m(equal 'Hello 'HELLO)[0m 8. [47m(equal (cons '1 '2) (cons '1 'two))[0m Next: Substitutions (see [R-AND-I-SUBSTITUTIONS]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-and-i-terms-as-formulas (recursion-and-induction) "Recursion and Induction: Terms as Formulas Logicians typically make a careful distinction between terms (whose values range over objects in the domain, like the integers, etc.) and formulas (whose values range over the truthvalues). We have set up two systems of propositional calculus. At the level of formulas we have the traditional equality relation, =, and the logical operators &, \/, ~, -->, and <->. At the level of terms, we have the primitive function [47mequal[0m and the defined propositional functions [47mand[0m, [47mor[0m, [47mnot[0m, [47mimplies[0m, and [47miff[0m. In our term-level propositional calculus, [47mt[0m and [47mnil[0m play the role of truthvalues. Because terms can be written entirely with ASCII symbols (and easily entered on a keyboard!) we tend to write terms and use them as formulas. For example, we might say that (implies (and (consp x) (not (consp y))) (not (equal x y))) is a theorem, or even say ((consp x) & ~(consp y)) --> x != y is a theorem. But of course, the former cannot be a theorem because it is a term and only formulas are theorems, and the latter cannot be a theorem because it is not even a well-formed formula (it uses some terms as though they were formulas). If we use an ACL2 term [47mp[0m as though it were a formula then the term should be understood as an abbreviation for the formula [47mp[0m != [47mnil[0m. Thus, if we say term [47mp[0m is a theorem we mean it is a theorem that [47mp[0m is not [47mnil[0m. Since we assume the reader here is familiar with programming, we assume this isomorphism between one syntactic category and another is very familiar. If this makes sense to you, we suggest you just skip the rest of this section, including the problems below, and go to Definitions Revisited (see [R-AND-I-DEFINITIONS-REVISITED]). But if not, read on. This abuse of terminology is justified by the following theorems. [31;1mTheorem.[0m [47mNOT[0m is Logical Negation: [47m(not p)[0m != [47mnil[0m <-> ~ ([47mp[0m != [47mnil[0m). [31;1mProof.[0m We handle the two directions of the <->. Case 1. [47m(not p)[0m != [47mnil[0m --> ~ ([47mp[0m != [47mnil[0m). This is equivalent to its contrapositive: [47mp[0m != [47mnil[0m --> [47m(not p)[0m = [47mnil[0m. By the definition of [47mnot[0m and Axiom 2 and the hypothesis [47mp[0m!= [47mnil[0m, [47m(not p)[0m = [47m(if p nil t)[0m = [47mnil[0m. Case 2. ~ ([47mp[0m != [47mnil[0m) --> [47m(not p)[0m != [47mnil[0m. The hypothesis is propositionally equivalent to [47mp[0m = [47mnil[0m. By substitution of equals for equals, the conclusion is [47m(not nil)[0m != [47mnil[0m. By the definition of [47mnot[0m and Axioms 3 and 1, [47m(not nil)[0m = [47m(if nil nil t)[0m = [47mt[0m != [47mnil[0m. Q.E.D. [31;1mProblem 18. [0m Prove [47m(and p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) & ([47mq[0m != [47mnil[0m). [31;1mProblem 19. [0m Prove [47m(or p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) \/ ([47mq[0m != [47mnil[0m). [31;1mProblem 20. [0m Prove [47m(implies p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) --> ([47mq[0m != [47mnil[0m). [31;1mProblem 21. [0m Prove [47m(iff p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) <-> ([47mq[0m != [47mnil[0m). [31;1mProblem 22. [0m Prove [47m(equal x y)[0m != [47mnil[0m <-> ([47mx[0m = [47my[0m) Note that these theorems allow us to change the propositional functions to their logical counterparts as we move the ``!= [47mnil[0m'' into the term. Furthermore, we can always drop a ``!= [47mnil[0m'' anywhere it occurs in a formula since the term with which it appears would then be used as a formula and would mean the same thing. [31;1mProblem 23. [0m Using the theorems above, prove that (implies (and p (implies q r)) s) is equivalent to [47m (p & (q --> r)) --> s [0m which is equivalent to ((p & ~ q) --> s) & ((p & q & r) --> s) When writing proofs on paper or the board, we tend to use formulas and the short symbols =, &, \/, ~, -->, <-> instead of the longer term notation. [31;1mProblem 24. [0m Prove (equal (car (if a b c)) (if a (car b) (car c))) that is, prove [47m (car (if a b c)) = (if a (car b) (car c)) [0m [31;1mProblem 25. [0m Prove (equal (if (if a b c) x y) (if a (if b x y) (if c x y))) [31;1mProblem 26. [0m Prove (equal (tree-copy (cons a b)) (cons (tree-copy a) (tree-copy b))) Next: Definitions Revisited (see [R-AND-I-DEFINITIONS-REVISITED]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))") (r-eqlable-alistp (alists acl2-built-ins) "Recognizer for a true list of pairs whose [47m[cdr][0ms are suitable for [47m[eql][0m The predicate [47mr-eqlable-alistp[0m tests whether its argument is a [47m[true-listp][0m of [47m[consp][0m objects whose [47m[cdr][0ms all satisfy [47m[eqlablep][0m. [31;1mFunction: [0m<r-eqlable-alistp> (defun r-eqlable-alistp (x) (declare (xargs :guard t)) (cond ((atom x) (equal x nil)) (t (and (consp (car x)) (eqlablep (cdr (car x))) (r-eqlable-alistp (cdr x))))))") (r-symbol-alistp (alists acl2-built-ins) "Recognizer for association lists with symbols as values [47m(R-symbol-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of the form [47m(cons key val)[0m where [47mval[0m is a [47m[symbolp][0m. [31;1mFunction: [0m<r-symbol-alistp> (defun r-symbol-alistp (x) (declare (xargs :guard t)) (cond ((atom x) (equal x nil)) (t (and (consp (car x)) (symbolp (cdr (car x))) (r-symbol-alistp (cdr x))))))") (random$ (state numbers acl2-built-ins) "Obtain a random value Example: (random$ 10 state) ==> (mv 7 <state>) [47m(Random$ limit state)[0m, where [47mlimit[0m is a positive integer, returns a random non-negative integer together with a new [47m[state][0m. Logically, it simply returns the first element of a list that is a field of the ACL2 [47m[state][0m, called the [47macl2-oracle[0m (see [47m[read-ACL2-oracle][0m), together with the new state resulting from removing that element from that list. (Except, if that element is not in range as specified above, then 0 is returned.) However, [47mrandom$[0m actually invokes a Common Lisp function to choose the integer returned. Quoting from the Common Lisp HyperSpec(TM), {http://www.lispworks.com/documentation/HyperSpec/Front | http://www.lispworks.com/documentation/HyperSpec/Front}: ``An approximately uniform choice distribution is used... each of the possible results occurs with (approximate) probability 1/limit.'' Consider enabling rules [47mnatp-random$[0m and [47mrandom$-linear[0m if you want to reason about [47mrandom$[0m. [31;1mFunction: [0m<random$> (defun random$ (limit state) (declare (type (integer 1 *) limit) (xargs :stobjs state)) (mv-let (erp val state) (read-acl2-oracle state) (mv (cond ((and (null erp) (natp val) (< val limit)) val) (t 0)) state)))") (random-remarks-on-rewriting (rewrite rewrite-quoted-constant) "Some basic facts about the ACL2 rewriter The ACL2 rewriter is technically part of the simplifier, but in this documentation we often conflate the two and say things like ``the conclusion simplifies to [47mT[0m'' when in fact we should say ``the conclusion rewrites to [47mT[0m during simplification'' In addition, both the simplifier and the rewriter are enormously complicated and contain so many heuristics that users are not often helped by studying the details. For example, the rewriter takes 18 arguments (some of which are bundles of more rarely used arguments) and is part of a mutually recursive clique containing 50 functions as of Version 8.3, including the linear (and non-linear) arithmetic semi-decision procedures. The rewriter and its clique consume about 6500 lines of code. But to understand how [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[congruence][0m, [47m:[0m[47mforward-chaining[0m and other rules behave, the user has to have a fairly weak model of the simplifier and rewriter, so we sketch that here. In ACL2, the goals you see printed in proof output are represented internally as clauses. See [clause]. The job of the simplifier is to simplify a clause, returning a set of clauses whose conjunction is propositionally equivalent to the input clause. The most desirable output set is the empty set, because the conjunction over the empty set is [47mT[0m, which means the goal clause was proved. For related discussions, see [hints-and-the-waterfall], where we discuss how repeated simplifications are performed. Note that if you are trying to simplify the clause [47m(lit1 lit2 ... litk)[0m and you manage to rewrite, say, the [47mliti[0m to [47mT[0m, then the clause is true. Furthermore, when rewriting a literal of a clause you may assume all the other literals false because if one were true the clause would be true. Finally, when you rewrite a literal you are justified in replacing it with one that is propositional equivalent, since the literals are disjoined. The simplifier works by first generating several data structures, here called the ``context,'' which codify governing assumptions available for the rewriting of each literal. These data structures include the [type-alist] and [linear-arithmetic] data base. They are built using various rules derived from previously proved lemmas, including [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[forward-chaining][0m, and [47m:[0m[47m[linear][0m rules. It then calls the rewriter successively on each literal passing it the appropriate context and stipulating that the result of the rewriting must be propositionally equivalent to the input. The rewriter returns a suitable term. If the result is the unchanged, the simplifier just moves on to the next literal. If the result contains no [47mIF[0m-expressions, the simplifier just replaces the old literal with the new one. But if the new term contains [47mIF[0m-expressions, the simplifier splits them out into a set of clause segments, i.e., if the literal simplifies to [47m(IF a b c)[0m, then the simplifier gets two new clause segments, [47m((NOT a) b)[0m and [47m(a c)[0m, and then it splices each segment into the goal clause where the literal was, producing a set of new clauses, and then resumes rewriting literals in each new clause. Heuristics try to prevent excessive case splitting, e.g., see [case-split-limitations]. The job of the rewriter is to take a term, some context, and an equivalence relation, and return a ``simpler'' term that is equivalent to the input term under the assumptions in the context. The rewriter works by exploring the term, possibly changing the context and the equivalence relation as appropriate for the subterms it rewrites. * If the term is a variable, the rewriter just returns it (unless the context tells it something interesting about that variable, such as that the variable is equal to [47mnil[0m). Sometimes you might wish that the value of a bound variable be rewritten, usually because the value found on the alist was rewritten under a different equivalence relation than the variable is now being used. See [47mdouble-rewrite[0m. * If the term is a quoted constant, the rewriter tries to apply [47m:[0m[47m[rewrite-quoted-constant][0m rules to that constant. * If the term is [47m(IF a b c)[0m, it rewrites the test, [47ma[0m, under the equivalence relation [47mIFF[0m to get some (possibly) new term, [47ma'[0m. If [47ma'[0m is [47mnil[0m or is obviously different from [47mnil[0m (like [47mT[0m), the rewriter replaces the [47mIF[0m-term by [47mb[0m or [47mc[0m, appropriately, and rewrites that. If on the other hand, the rewriter can't decide whether [47ma'[0m is [47mnil[0m or not, it rewrites [47mb[0m to [47mb'[0m in an extended context in which [47ma'[0m is assumed non-[47mnil[0m and rewrites [47mc[0m to [47mc'[0m in an extended context in which [47ma'[0m is [47mnil[0m. In rewriting both branches it preserves the outer equivalence relation -- the one to be maintained while rewriting the [47mIF[0m-term. Then the rewriter returns [47m(IF a' b' c[0m'). * If the term is a call of an arithmetic inequality, like [47m(< a b)[0m, the rewriter rewrites [47ma[0m and [47mb[0m and then considers whether the context allows it deduce the truth or falsity of the inequality using a [linear-arithmetic] decision procedure. The decision procedure, which is complete for linear inequalities over the rationals, uses heuristics to decide many integer cases, to select the order in which inequalities are combined to eliminate variables, and to handle some [non-linear-arithmetic] problems. * If the term is a call of a function symbol, [47mfn[0m, on some argument terms, [47ma1[0m, ..., [47man[0m, the rewriter rewrites each argument, [47mai[0m to [47mai'[0m. For each argument the rewriter uses known [47m:[0m[47m[congruence][0m rules to determine which equivalence relations can be used to rewrite terms in that argument position so as to maintain the outer equivalence. Then, having transformed [47m(fn a1 ... an)[0m to [47m(fn a1' ... an[0m') the rewriter tries to apply [47m:[0m[47m[rewrite][0m rules to that transformed term, called the ``target.''. * Among the rewrite rules generally available for [47m(fn a1' ... an[0m') is the definition of [47mfn[0m itself. The rewriter considers ``expanding'' the call, i.e., replacing it by the body of [47mfn[0m after substituting the [47mai'[0m for the formal variables, if the definition is [enable]d, and then rewriting that. But heuristics are used to prevent the indefinite expansion of recursive definitions. For an elementary tutorial on the application of a [47m:[0m[47mrewrite[0m rule to a target term, see [introduction-to-rewrite-rules-part-1] and [introduction-to-rewrite-rules-part-2]. Those topics also lead to documentation on how to design effective rules. But just to summarize very briefly, we offer the following. [47m:Rewrite[0m rules take the general form (implies (and hyp1 ... hypk) (equiv lhs rhs)) where [47mequiv[0m is a known [equivalence] relation. Recall that the rewriter has a target term to rewrite in some context and is required to return a term that is equivalent modulo a given equivalence relation, here called the ``outer'' equivalence. Furthermore, if the target term is a function application, e.g., [47m(fn a1' ... an[0m'), the argument subterms have already been rewritten. If the rule in question is enabled and its [47mequiv[0m refines the outer equivalence, the rewriter tries to match [47mlhs[0m with the target. By ``match'' we mean it tries to find a substitution for the variables in [47mlhs[0m that make the instantiated [47mlhs[0m identical to the target. We discuss matching further below. Second, having found a suitable substitution, tries to ``relieve'' the hypotheses, as discussed below. If successful, that means each [47mhypi[0m, when instantiated with the substitution, is non-[47mnil[0m. Third, if all the hypotheses are relieved, the target is ``replaced'' by the result of rewriting [47mrhs[0m under the substitution. We discuss that step more below too. [31;1mMatching[0m: Technically, ACL2 uses a restriction of ordinary first-order unification -- the restriction being that only variables in the pattern (here the [47mlhs[0m of the rule) may be instantiated. Thus, the pattern [47m(G x (H x))[0m matches [47m(G (M A B) (H (M A B)))[0m by binding [47mx[0m to [47m(M A B)[0m. It does not match [47m(G (M A B) (H (M A A)))[0m even though those two terms ``unify'' by binding [47mx[0m to [47m(M A A)[0m and [47mB[0m to [47mA[0m. Our pattern matcher is the function [47mone-way-unify[0m in our source code. However, our pattern matcher knows some things about the structure of quoted constants. For example, the pattern [47m(CONS x y)[0m matches the quoted constant [47m'(A B C)[0m, by binding [47mx[0m to [47m'A[0m and [47my[0m to [47m'(B C)[0m. This can be seen by running [47mone-way-unify[0m on those two terms: ACL2 !>(one-way-unify '(cons x y) ''(A B C)) (T ((Y QUOTE (B C)) (X QUOTE A))) Note the quote marks in our input. Since [47mone-way-unify[0m expects both of its arguments to be fully translated formal terms, we have to quote every constant we write here. And since the arguments to [47mone-way-unify[0m are evaluated before the function is called, we have to quote the two terms. We see that [47mone-way-unify[0m returns two results. The first is [47mT[0m, meaning that a suitable substitution was found. The second is the substitution. Lisp's abbreviation convention for printed ``dotted pairs,'' its ``quote convention,'' its convention of reading symbols in uppercase, and our convention here of writing terms (and variables) in lower case but constants in upper case, all conspire to make the substitution a little hard to read for novices. Another way to display the exact same substitution is: ((y . '(B C)) (x . 'A)) i.e., [47mx[0m is bound to [47m'A[0m and [47my[0m is bound to [47m(B C)[0m. Below are some other examples, but we've re-displayed the substitutions. ACL2 !>(one-way-unify '(coerce x 'string) ''"Hello!") (T ((x . (#H #e #l #l #o #!)))) ACL2 !>(one-way-unify '(intern-in-package-of-symbol x y) ''ACL2::TEMP) (T ((y . 'TEMP) (x . '"TEMP"))) ACL2 !>(one-way-unify '(binary-+ '3 x) ''7) (T ((X . '4))) ACL2 !>(one-way-unify '(unary-- x) ''-7) (T ((X QUOTE 7))) ACL2 !>(one-way-unify '(unary-- x) ''7) (NIL NIL) ACL2 !>(one-way-unify '(binary-* '2 y) ''8) (T ((Y QUOTE 4))) ACL2 !>(one-way-unify '(binary-* x y) ''8) (NIL NIL) Note that the pattern matching algorithm is incomplete on quoted constants! For example, it fails to match [47m(unary-- x)[0m with [47m'7[0m even though [47m(unary-- '-7)[0m is [47m'7[0m. It similarly fails to match [47m(binary-* x y)[0m with [47m'8[0m even though [47m(binary-* '33 '8/33)[0m is [47m8[0m; indeed, there are in infinite number of suitable substitutions for this case, but [47mone-way-unify[0m is designed to return at most one so as to limit the applicability of rewrite rules to ``reasonable'' cases. [31;1mRelieving the Hypotheses[0m: The hypotheses of a rewrite rule are relieved one at a time starting with the left-most one. The basic strategy is just to rewrite each hypothesis, assuming the current context and if [47mIFF[0m equivalence relation. If the result comes back non-[47mNIL[0m the hypothesis is equivalent to [47mT[0m in the current context. But there are various special considerations. * Free variables: It is possible that a hypothesis contains variables that are not bound by the substitution generated by the match. We call these ``free variables'' and the system tries to bind them to make the instantiated hypothesis appear among the contextual assumptions. New bindings are accumulated as hypotheses are relieved. It is possible to find multiple successful substitutions, some possibly filtered out by subsequent hypotheses. See [47mfree-variables[0m and the documentation topics it cites. * Pragmas: It is possible to mark a hypothesis so that it is temporarily assumed true so that the rewrite rule can be applied. This essentially spawns another subgoal to prove the hypothesis and thus brings the full power of the prover (not just the rewriter) to bear on the hypothesis. See [47m[force][0m and [47m[case-split][0m. It is also possible to include hypotheses that are logically always true but which cause the attempt to apply the rule to fail if a certain user-specified computation so indicates. This can be used to restrict the application of a rule to certain syntactic situations. See [47msyntaxp[0m. [31;1mReplacement[0m: Before the target is replaced by the rewritten [47mrhs[0m, a heuristic check is made to prevent certain trivial forms of rewrite loops. See [47m[loop-stopper][0m. Otherwise, if the hypotheses are relieved (or assumed), the rewriter rewrites [47mrhs[0m under the substitution generated by the match and the hypotheses. It then makes certain heuristic checks to decide if replacing the target by this new term is a ``good idea'' in the opinion of the ACL2 implementors. The two main checks are designed to avoid runaway expansion of recursive functions (see [definition]), and introducing ``too many [47m[if][0ms'' (see [too-many-ifs]. The latter check is used to prevent unmanageable case explosions. (In general, the number of cases rises exponentially with the number of [47mIF[0ms.)") (rassoc (alists acl2-built-ins) "Look up value in association list General Forms: (rassoc x alist) (rassoc x alist :test 'eql) ; same as above (eql as equality test) (rassoc x alist :test 'eq) ; same, but eq is equality test (rassoc x alist :test 'equal) ; same, but equal is equality test [47m(Rassoc x alist)[0m is the first member of [47malist[0m whose [47m[cdr][0m is [47mx[0m, or [47mnil[0m if no such member exists. [47m(rassoc x alist)[0m is thus similar to [47m(assoc x alist)[0m, the difference being that it looks for the first pair in the given alist whose [47m[cdr][0m, rather than [47m[car][0m, is [47m[eql][0m to [47mx[0m. See [assoc]. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with the [47m[cdr][0ms of successive elements of [47mlst[0m. The [guard] for a call of [47mrassoc[0m depends on the test. In all cases, the second argument must satisfy [47m[alistp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[r-eqlable-alistp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[r-symbol-alistp][0m. See [equality-variants] for a discussion of the relation between [47mrassoc[0m and its variants: [47m(rassoc-eq x lst)[0m is equivalent to [47m(rassoc x lst :test 'eq)[0m; [47m(rassoc-equal x lst)[0m is equivalent to [47m(rassoc x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mrassoc-equal[0m. [31;1mFunction: [0m<rassoc-equal> (defun rassoc-equal (x alist) (declare (xargs :guard (alistp alist))) (cond ((endp alist) nil) ((equal x (cdr (car alist))) (car alist)) (t (rassoc-equal x (cdr alist))))) [47mRassoc[0m is defined by Common Lisp. See any Common Lisp documentation for more information.") (rassoc-eq (pointers) "See [rassoc].") (rassoc-equal (pointers) "See [rassoc].") (rational-listp (numbers lists acl2-built-ins) "Recognizer for a true list of rational numbers The predicate [47mrational-listp[0m tests whether its argument is a true list of rational numbers. [31;1mFunction: [0m<rational-listp> (defun rational-listp (l) (declare (xargs :guard t)) (cond ((atom l) (eq l nil)) (t (and (rationalp (car l)) (rational-listp (cdr l))))))") (rationalp (numbers acl2-built-ins) "Recognizer for rational numbers (ratios and integers) [47m(rationalp x)[0m is true if and only if [47mx[0m is an rational number.") (raw-lisp-error (common-lisp) "Raw lisp errors You may see a message about ``ABORTING from raw Lisp'' as in the following example. ACL2 !>(defun foo (x) (declare (xargs :mode :program)) (car x)) Summary Form: ( DEFUN FOO ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !>(foo 3) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Fault during read of memory address #x1D *********************************************** The message above might explain the error. If not, and if you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !> The ``Error:'' message, ``Fault during read of memory address #x1D'', is printed by the host Common Lisp implementation. In the example above, the function [47mfoo[0m has an implicit [guard] of [47mt[0m, which causes evaluation to invoke the Common Lisp function [47mcar[0m on argument [47m3[0m, resulting in the error. This sort of error may occur when calling a [47m:[0m[47m[program][0m mode function, because the guard hasn't been verified. See [defun-mode-caveat] for a discussion of the possibility that ACL2 is rendered unsound by a raw Lisp error. For further relevant background, see [evaluation]. Calls of [47m:program[0m mode functions are not the only sources of raw Lisp errors. Here is a non-exhaustive list of some such sources. * Calls of [47m:program[0m mode functions * Calls of [47m:logic[0m mode functions whose [guard]s were verified using [47m[skip-proofs][0m * Resource errors, e.g., when attempting to evaluate [47m(expt 2 (expt 2 1000000))[0m. (We have seen raw Lisp errors when evaluating that expression in ACL2 built on host Lisps CCL, SBCL, and Allegro CL.) * Illegal calls of certain functions and macros with special ``under the hood'' raw Lisp code, such as [47m[read-file-into-string][0m and [47m[return-last][0m * [47m[Defattach][0m using argument [47m:skip-checks t[0m * Reader errors (for examples see [reader] and see [set-iprint]) * Certain errors during proofs (for an example see [live-stobj-in-proof] Subtopics [Live-stobj-in-proof] Error messages about ``live'' [stobj]s during proofs") (raw-mode (pointers) "See [set-raw-mode].") (read-acl2-oracle (programming-with-state acl2-built-ins) "Pop the oracle field of the state ACL2 has a mutable `state' that contains a number of fields; see [state]. One of these fields is a list, called the [47macl2-oracle[0m field. There are no constraints on the elements of this list; thus, you will not be able to prove anything about those elements. However, as a convenience, ACL2 permits you to evaluate the form [47m(read-acl2-oracle state)[0m, which returns the multiple value [47m(mv nil nil state)[0m. The ACL2 implementation uses [47mread-acl2-oracle[0m, but you will likely find this function to be useless unless you do advanced, scurrilous things using trust tags (see [47m[defttag][0m). The following definition is the logical definition of [47mread-acl2-oracle[0m, but as explained above does not really characterize its behavior under the hood. [31;1mFunction: [0m<read-acl2-oracle> (defun read-acl2-oracle (state-state) (declare (xargs :guard (state-p1 state-state))) (mv (null (acl2-oracle state-state)) (car (acl2-oracle state-state)) (update-acl2-oracle (cdr (acl2-oracle state-state)) state-state)))") (read-byte$ (pointers) "See [io].") (read-char$ (pointers) "See [io].") (read-file-into-string (io) "The contents of a file (or part of it) as a string This macro returns the contents of the file, or a specified part of the file, as a string. Otherwise, it returns [47mnil[0m or causes an error. Although this macro implicitly takes the ACL2 [state], it differs from other ACL2 file-reading utilities in that it does not return the ACL2 [47mstate[0m, and it is generally [3mmuch[0m faster. Summary Example Forms: (read-file-into-string "foo.lisp") (read-file-into-string "foo.lisp" :start 0 :bytes nil) ; same as above (read-file-into-string "foo.lisp" :start 20000 :bytes 10000) (read-file-into-string "foo.lisp" :start 20000 :bytes 10000 :close t) General Form: (read-file-into-string filename ; a filename relative to the current directory :start s ; default 0 :bytes b ; default nil :close c ; default :default ) where [47mfilename[0m is a string, which is typically the name of a file, and the keyword arguments, which are optional and evaluated, are as follows: [47ms[0m has default [47m0[0m and its value is a natural number, where an error occurs if that number exceeds the length of the given file; [47mb[0m has default [47mnil[0m and its value is either a natural number or [47mnil[0m; and [47mc[0m has default [47m:default[0m and its value is otherwise considered to be false (when [47mnil[0m) or true (when not [47mnil[0m). The effects of these arguments are described below. For examples, see [community-books] file [47mbooks/system/tests/read-file-into-string.lisp[0m. Summary documentation Typical use of [47mread-file-into-string[0m will either return the contents of the given file (as a string) or will return specified segments of the file. Here is a log illustrating how we can read the full contents of a file and then read it in pieces. The form [47m(INCREMENT-FILE-CLOCK STATE)[0m is necessary in order to make certain successive calls; this is discussed further below. ACL2 !>(read-file-into-string "tmp.txt") "Hello world. " ACL2 !>(INCREMENT-FILE-CLOCK STATE) <state> ACL2 !>(read-file-into-string "tmp.txt" :start 0 :bytes 3) "Hel" ACL2 !>(read-file-into-string "tmp.txt" :start 3 :bytes 2) "lo" ACL2 !>(read-file-into-string "tmp.txt" :start 5) " world. " ACL2 !> For two successive calls of [47mread-file-into-string[0m on the same input string, the second call must generally start beyond the last byte that was read by the first call. An exception is made when the second call specifies [47m:bytes 0[0m, when [47m:start[0m is either omitted or has value 0; in that case, the empty string is returned without error. An exception is also made when the form [47m(INCREMENT-FILE-CLOCK STATE)[0m is evaluated between the two calls. It may seem odd to require a call of [47mincrement-file-clock[0m to avoid errors from successive reads. The reason stems from the fact that [47mincrement-file-clock[0m is a function. The concern is that the file may change between successive calls of [47mread-file-into-string[0m (perhaps made hours apart!), for reasons external to ACL2, in which case it could appear that [47mread-file-into-string[0m returns different values for the same inputs. By evaluating [47m(INCREMENT-FILE-CLOCK STATE)[0m, one is incrementing the file-clock field of the [47mstate[0m argument, so the next call is on a different [47mstate[0m argument. This is all explained logically by the definitions of [47mread-file-into-string[0m and its subroutines in ACL2, as shown in the final section of this documentation. (But the implementation of [47mread-file-into-string[0m involves raw Lisp code.) ACL2 causes various informative Lisp errors when functional semantics could otherwise be violated, and some of these errors are shown below. Note that ACL2 characters always fit into a single byte, which is why we can talk about ``bytes''. Compared with the usual [io] routines provided by ACL2, [47mread-file-into-string[0m is generally much more efficient, and also it does not return [47m[state][0m. Note that the macroexpansion of a call of this macro takes [47mstate[0m as an argument; so if you call it in the body of a function definition, then --- as usual for functions that take [47mstate[0m --- either [47m(set-state-ok t)[0m must have been evaluated or else a suitable [47m:stobjs[0m declaration, typically [47m:stobjs state[0m, must be provided (see [xargs]). The very large constant [47m*read-file-into-string-bound*[0m, whose definition is shown in the final section below, establishes a strict upper bound on the size of the string returned. If the file (or specified portion thereof) contains more bytes than this, then [47mnil[0m is returned. Detailed discussion of keyword arguments The result, when not [47mnil[0m or an error, is a string representing the specified file contents. For the default of [47m:start 0[0m and [47m:bytes nil[0m, or equivalently, when no keyword arguments are specified, the entire file contents are returned as a string. In general, [47m:start s[0m specifies the part of the file starting at byte position [47ms[0m of the file, and the [47m:bytes[0m argument specifies the number of consecutive bytes to be included starting at that position: [47m:bytes nil[0m specifies that the rest of the file is to be included, while for a natural number [47mb[0m, [47m:bytes b[0m specifies that only the next [47mb[0m bytes are to be included --- but, stopping at the end of the file if [47mb+s[0m exceeds the length [47mL[0m of the file. Below we call this case that [47mb+s>L[0m the [3mtruncation case[0m. The [47m:close[0m argument affects handling of the Lisp stream that is created for the specified file. When the value of [47m:close[0m is the default, [47m:default[0m, the criterion for closing the stream immediately after the read completes is that either [47m:bytes[0m has value [47mnil[0m (the default) or we are in the truncation case [47mb+s>L[0m described above. Once this stream is closed, a Lisp error occurs if [47mread-file-with-string[0m is called when either [47m:start[0m or [47m:bytes[0m specifies a non-zero value unless the file-clock of the state is advanced first by evaluating [47m(INCREMENT-FILE-CLOCK STATE)[0m. See [state] for a discussion of the logical role of the file-clock of the state. Here is a typical log showing such an error message from successive reads, together with the evaluation of [47m(INCREMENT-FILE-CLOCK STATE)[0m as a remedy. The next section, further below, discusses the closing of streams. ACL2 !>(read-file-into-string "tmp.txt") "Hello world. " ACL2 !>(read-file-into-string "tmp.txt") *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Apparently READ-FILE-INTO-STRING has previously closed the stream that is associated with file "tmp.txt". Consider evaluating (INCREMENT-FILE-CLOCK STATE). See :DOC read-file-into-string. While executing: READ-FILE-INTO-STRING2 *********************************************** The message above might explain the error. If not, and if you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !>(INCREMENT-FILE-CLOCK STATE) <state> ACL2 !>(read-file-into-string "tmp.txt") "Hello world. " ACL2 !> The implementation of [47mread-file-into-string[0m advances a pointer with each successive read while the stream is open. An error is signaled when attempting to call [47mread-file-into-string[0m with a [47m:start[0m value that points to a byte that is not beyond all bytes already read by previous calls (unless there is an intervening evaluation of [47m(INCREMENT-FILE-CLOCK STATE)[0m). Here is a sample log to illustrate this point. ACL2 !>(read-file-into-string "tmp.txt" :bytes 3) "Hel" ACL2 !>(read-file-into-string "tmp.txt" :start 3 :bytes 2) "lo" ACL2 !>(read-file-into-string "tmp.txt" :start 4) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: The :start value, 4, specified for a call of READ-FILE-INTO-STRING, is less than the position 5 immediately after a previous read of file "tmp.txt" at the same file-clock. Consider evaluating (INCREMENT-FILE-CLOCK STATE). See :DOC read-file-into-string. While executing: READ-FILE-INTO-STRING2 *********************************************** Closing streams A call of [47mread-file-into-string[0m on a given filename opens a Lisp stream connected to the given file. ACL2 keeps track of such an association of filenames with streams. If the stream remains open for numerous calls of [47mread-file-into-string[0m, the operating system could eventually complain because too many streams are open at the same time. Recall that if the value of [47m:bytes[0m is non-[47mnil[0m (hence, a natural number), then, except in the truncation case, the stream remains open. In such cases may want to specify [47m:close t[0m to prevent leaving too many streams open, unless you plan to read more bytes from the same file. If you decide to close the stream later, this can be accomplished efficiently without reading any bytes by evaluating the following form for your file, [47m"<file>"[0m. (read-file-into-string "<file>" :bytes 0 :close t) Logical definitions We close by showing the relevant ACL2 definitions in the logic. Thus, these do not show the special raw Lisp (under the hood) code in the definition of [47mread-file-into-string2[0m. [31;1mFunction: [0m<read-file-into-string1> (defun read-file-into-string1 (channel state ans bound) (declare (xargs :stobjs state :guard (and (symbolp channel) (open-input-channel-p channel :character state) (character-listp ans) (natp bound)))) (cond ((zp bound) (mv nil state)) (t (mv-let (val state) (read-char$ channel state) (cond ((not (characterp val)) (mv (coerce (reverse ans) 'string) state)) (t (read-file-into-string1 channel state (cons val ans) (1- bound)))))))) [31;1mDefinition: [0m<*read-file-into-string-bound*> (defconst *read-file-into-string-bound* (1- (ash 1 60))) [31;1mFunction: [0m<read-file-into-string2-logical> (defun read-file-into-string2-logical (filename start bytes state) (declare (xargs :stobjs state :guard (and (stringp filename) (natp start) (or (null bytes) (natp bytes))))) (non-exec (mv-let (erp val state) (mv-let (chan state) (open-input-channel filename :character state) (cond ((or (null chan) (not (state-p state))) (mv nil nil state)) (t (mv-let (val state) (read-file-into-string1 chan state nil *read-file-into-string-bound*) (pprogn (ec-call (close-input-channel chan state)) (mv nil val state)))))) (declare (ignore erp state)) (and (stringp val) (<= start (length val)) (subseq val start (if bytes (min (+ start bytes) (length val)) (length val))))))) [31;1mFunction: [0m<read-file-into-string2> (defun read-file-into-string2 (filename start bytes close state) (declare (xargs :stobjs state :guard (and (stringp filename) (natp start) (or (null bytes) (natp bytes)))) (ignore close)) (read-file-into-string2-logical filename start bytes state)) [31;1mMacro: [0m<read-file-into-string> (defmacro read-file-into-string (filename &key (start '0) bytes (close ':default)) (cons 'read-file-into-string2 (cons filename (cons start (cons bytes (cons close '(state)))))))") (read-object (pointers) "See [io].") (read-object-suppress (pointers) "See [io].") (read-object-with-case (pointers) "See [io].") (read-run-time (programming-with-state acl2-built-ins) "Read elapsed runtime By default, [47m(read-run-time state)[0m returns [47m(mv cpu-time state)[0m, where [47mcpu-time[0m is the elapsed cpu time in seconds since the start of the current ACL2 session and [47mstate[0m is the resulting ACL2 [state]. Thus, [47m(read-run-time state)[0m is, by default, equivalent to [47m(get-cpu-time state)[0m. But [47mread-run-time[0m can be made to return elapsed real time (wall clock time) instead, thus making it equivalent to [47m(get-real-time state)[0m. Note that time is returned in seconds in all of these cases. To specify that [47mread-run-time[0m shall use cpu time or real time: (assign get-internal-time-as-realtime t) ; use real time (assign get-internal-time-as-realtime nil) ; use cpu time See [get-internal-time] for more discussion of cpu time vs. real time. In both cases, the precision depends on the host Common Lisp; for example, in CCL as of this writing, the result is accurate to the microsecond. The logical definition probably won't concern many users, but for completeness, we say a word about it here. That definition uses the function [47m[read-ACL2-oracle][0m, which modifies [state] by popping the value to return from its acl2-oracle field. [31;1mFunction: [0m<read-run-time> (defun read-run-time (state-state) (declare (xargs :guard (state-p1 state-state))) (mv (cond ((or (null (acl2-oracle state-state)) (not (rationalp (car (acl2-oracle state-state))))) 0) (t (car (acl2-oracle state-state)))) (update-acl2-oracle (cdr (acl2-oracle state-state)) state-state))) Note that logically [47m(read-run-time state)[0m, [47m(get-real-time state)[0m, and [47m(get-cpu-time state)[0m are all equal (defined using the acl2-oracle), so for example ACL2 succeeds in the proof of [47m(thm (equal (get-real-time state) (get-cpu-time state)))[0m, even though the first returns elapsed real time and the second returns elapsed cpu time. However, there is no contradiction: either way, we are logically just reading the oracle of [47mstate[0m. In the ACL2 loop, successive calls of [47m(get-real-time state)[0m and [47m(get-cpu-time state)[0m would be operating on different values of [47mstate[0m (because their oracles differ). Subtopics [Get-cpu-time] Read elapsed cpu time [Get-real-time] Read elapsed real time") (reader (miscellaneous) "Reading expressions in the ACL2 read-eval-print loop The ACL2 read-eval-print loop reads expressions much like they are read in any Common Lisp read-eval-print loop. For example, you may use the single tick symbol ([47m'[0m) for [47mquote[0m and also the backquote symbol ([47m`[0m) with its escapes, comma ([47m,[0m) and comma-atsign ([47m,@[0m). See any Common Lisp reference or tutorial. ACL2-specific reader macros include its reading of expressions in a specified package (using [47m#![0m --- see [sharp-bang-reader]), its restriction of read-time evaluation to constants introduced by [47m[defconst][0m (using [47m#.[0m --- see [sharp-dot-reader]), and the ability to put underscores in numeric constants (using [47m#u[0m --- see [sharp-u-reader]). See [set-iprint] for how to make ACL2 print expressions like [47m#@2#[0m that can be read back in. Strictly speaking, there is nothing special about how the reader handles [keyword]s in the input. But see [keyword-commands] for how ACL2 may interpret a top-level keyword command. We conclude this topic with a log that illustrates features discussed above. Comments of the form [47m{{..}}[0m have been inserted manually. ACL2 !>(defconst *c* (+ 3 4)) Summary Form: ( DEFCONST *C* ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) *C* ACL2 !>'(a #.*c* 17) ;{{See :doc sharp-dot-reader. ; Notice that #.*c* is read as the value of *c*, thus, ; as 7 rather than as (+ 3 4).}} (A 7 17) ACL2 !>'(a #.(+ 5 6) 17) ;{{But this is not legal in ACL2, as #. must be followed by ; a known constant symbol.}} *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: ACL2 supports #. syntax only for #.*a*, where *a* has been defined by DEFCONST. Thus the form #.(+ 5 6) is illegal. *********************************************** ;{{Additional output here has been omitted in this log.}} ACL2 !>(defpkg "FOO" nil) Summary Form: ( DEFPKG "FOO" ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) "FOO" ACL2 !>#!foo'(a b c) ;{{See :doc sharp-bang-reader. The prefix "#!foo" causes ; the s-expression after it to be read into the "FOO" package.}} (FOO::A FOO::B FOO::C) ACL2 !>#x100a ;{{As in Common Lisp, "#x" causes the digits after it to be read in hex.}} 4106 ACL2 !>#ux10_0a ;{{The "#u" prefix allows underscores in the numeral after it. Those ; underscores are ignored, but can improve readability.}} 4106 ACL2 !>(set-iprint t) ;{{See :DOC set-print. This causes "#@1#" below to be printed.}} ACL2 Observation in SET-IPRINT: Iprinting has been enabled. ACL2 !>(set-evisc-tuple (evisc-tuple 3 ; print-level 4 ; print-length nil ; alist nil ; hiding-cars ) :sites :ld) ;{{Abbreviate the printing of top-level evaluation results. ; See :doc set-evisc-tuple.}} (:LD) ACL2 !>(make-list 10) (NIL NIL NIL NIL . #@1#) ACL2 !>'#@1# ;{{Note that the reader replaces #@1# with the value that was stored there.}} (NIL NIL NIL NIL . #@2#) ACL2 !>(without-evisc '(NIL NIL NIL NIL . #@1#)) ;{{See :doc without-evisc.}} (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL) ACL2 !>(set-evisc-tuple nil :sites :ld) (:LD) ACL2 !>(let ((x '(3 4))) `(a b ,x c)) ;{{As in Common Lisp, backquote can be escaped by comma.}} (A B (3 4) C) ACL2 !>(let ((x '(3 4))) `(a b ,@x c)) ;{{As in Common Lisp, backquote can be escaped by comma-atsign, which ; splices its value into the list.}} (A B 3 4 C) ACL2 !> Subtopics [Backquote] Variant of quotation introducing templates for data structures [Fancy-string-reader] A friendly syntax for strings literals that have backslashes and quotes. [Sharp-bang-reader] Package prefix that is not restricted to symbols [Sharp-d-reader] Read a rational number as a representable rational (see [df]) [Sharp-dot-reader] Read-time evaluation of constants [Sharp-f-reader] Read a rational number in floating-point syntax [Sharp-u-reader] Allow underscore characters in numbers") (real (acl2) "ACL2(r) support for real numbers ACL2 supports rational numbers but not real numbers. However, starting with Version 2.5, a variant of ACL2 called ``ACL2(r)'' supports the real numbers by way of non-standard analysis. ACL2(r) was conceived and first implemented by Ruben Gamboa in his Ph.D. dissertation work, supervised by Bob Boyer with active participation by Matt Kaufmann. ACL2(r) has the same source files as ACL2. After you download ACL2, you can build ACL2(r) by executing the following command on the command line in your acl2-sources directory, replacing [47m<your_lisp>[0m with a path to your Lisp executable: make large-acl2r LISP=<your_lisp> This will create an executable in your acl2-sources directory named [47msaved_acl2r[0m. Note that if you have fetched the [community-books], then you will already have the books to be certified with ACL2(r). They can be certified from your acl2-sources directory, shown here as [47m<DIR>[0m: make regression ACL2=<DIR>/saved_acl2r To check that you are running ACL2(r), see if the prompt includes the string ``[47m(r)[0m'', e.g.: ACL2(r) !> Or, look at [47m(@ acl2-version)[0m and see if ``[47m(r)[0m'' is a substring. In ACL2 (as opposed to ACL2(r)), when we say ``real'' we mean ``rational.'' Caution: ACL2(r) should be considered experimental: although we (Kaufmann and Moore) have carefully completed Gamboa's integration of the reals into the ACL2 source code, our primary concern has been to ensure unchanged behavior when ACL2 is compiled in the default manner, i.e., without the non-standard extensions. As for every release of ACL2, at the time of a release we are unaware of soundness bugs in ACL2 or ACL2(r). There is only limited documentation on the non-standard features of ACL2(r). We hope to provide more documentation for such features in future releases. Please feel free to query the authors if you are interested in learning more about ACL2(r). Gamboa's dissertation may also be helpful. ACL2(r) does not currently support the [useless-runes] feature. Subtopics [I-close] ACL2(r) test for whether two numbers are infinitesimally close [I-large] ACL2(r) recognizer for infinitely large numbers [I-limited] ACL2(r) recognizer for limited numbers [I-small] ACL2(r) recognizer for infinitesimal numbers [Real-listp] ACL2(r) recognizer for a true list of real numbers [Standard-part] ACL2(r) function mapping limited numbers to standard numbers [Standardp] ACL2(r) recognizer for standard objects") (real-listp (real lists acl2-built-ins) "ACL2(r) recognizer for a true list of real numbers The predicate [47mreal-listp[0m tests whether its argument is a true list of real numbers. This predicate is only defined in ACL2(r) (see [real]).") (real/rationalp (numbers acl2-built-ins) "Recognizer for rational numbers (including real number in ACL2(r)) For most ACL2 users, this is a macro abbreviating [47m[rationalp][0m. In ACL2(r) (see [real]), this macro abbreviates the predicate [47mrealp[0m, which holds for real numbers as well (including rationals). Most ACL2 users can ignore this macro and use [47m[rationalp][0m instead, but many community books use [47mreal/rationalp[0m so that these books will be suitable for ACL2(r) as well.") (realfix (numbers acl2-built-ins) "Coerce to a real number [47mRealfix[0m simply returns any real number argument unchanged, returning [47m0[0m on a non-real argument. Also see [nfix], see [ifix], see [rfix], and see [fix] for analogous functions that coerce to a natural number, an integer, a rational, and a number, respectively. [47mRealfix[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<realfix> (defun realfix (x) (declare (xargs :guard t)) (if (real/rationalp x) x 0))") (realpart (numbers acl2-built-ins) "Real part of a complex number Completion Axiom ([47mcompletion-of-realpart[0m): (equal (realpart x) (if (acl2-numberp x) (realpart x) 0)) [Guard] for [47m(realpart x)[0m: (acl2-numberp x)") (rebuild (ld) "A convenient way to reconstruct your old [state] Examples: ACL2 !>(rebuild "project.lisp") ACL2 !>(rebuild "project.lisp" t) ACL2 !>(rebuild "project.lisp" t :dir :system) ACL2 !>(rebuild "project.lisp" :all) ACL2 !>(rebuild "project.lisp" :query) ACL2 !>(rebuild "project.lisp" 'lemma-22) [47mRebuild[0m allows you to assume all the [command]s in a given file or list, supplied in the first argument. Because [47mrebuild[0m processes an arbitrary sequence of [command]s with [47m[ld-skip-proofsp][0m [47mt[0m, it is unsound! However, if each of these [command]s is in fact admissible, then processing them with [47mrebuild[0m will construct the same logical [state] that you would be in if you typed each [command] and waited through the proofs again. Thus, [47mrebuild[0m is a way to reconstruct a [state] previously obtained by proving your way through the [command]s. The second, optional argument to [47mrebuild[0m is a ``filter'' (see [ld-pre-eval-filter]) that lets you specify which [command]s to process. You may specify [47mt[0m, [47m:all[0m, [47m:query[0m, or a new logical name. [47mt[0m and [47m:all[0m both mean that you expect the entire file or list to be processed. [47m:query[0m means that you will be asked about each [command] in turn. A new name means that all [command]s will be processed as long as the name is new, i.e., [47mrebuild[0m will stop processing [command]s immediately after executing a [command] that introduces name. [47mRebuild[0m will also stop if any [command] causes an error. You may therefore wish to plant an erroneous form in the file, e.g., [47m(mv t nil state)[0m, (see [ld-error-triples]), to cause [47mrebuild[0m to stop there. The form [47m(i-am-here)[0m is such a pre-defined form. If you do not specify a filter, [47mrebuild[0m will query you for one. Inspection of the definition of [47mrebuild[0m, e.g., via [47m:[0m[47m[pc][0m [47mrebuild-fn[0m, will reveal that it is just a glorified call to the function [47m[ld][0m. See [ld] if you find yourself wishing that [47mrebuild[0m had additional functionality. If you supply the above ``filter'' argument, then you may also supply the keyword argument [47m:dir[0m, which is then passed to [47mld[0m; see [ld].") (recursion-and-induction (documentation acl2 about-acl2) "Recursion and Induction Recursion and Induction Preface and Acknowledgments These notes are for teaching yourself how to prove theorems about recursively defined functions using mathematical induction. Think of this as a college-level practical math course that just happens to focus on issues of concern in computing. We assume you're passingly familiar with notions from formal mathematical logic, like ``axioms'' and ``rules of inference'' (like instantiation and substitution of equals for equals) to derive ``new'' truths from ``old'' ones. We describe a very simple logical system and present many exercises for you to do. Our presentation is less formal than formal logicians would expect, and the ``proofs'' we expect of you would be considered just ``proof sketches'' by formal logicians. But we believe we're precise enough that if you follow our rules your ``proofs'' could be turned into formal proofs in conventional first-order mathematical logic. Unlike a traditional course in logic, we do not focus on metatheory but on lots of proofs about elementary algorithms expressed recursively. It helps if you're familiar with computer programming because our logic is a subset of the programming language Lisp and the exercises involve conjectures about simple list processing algorithms like member, union, reverse, etc. We do not assume prior familiarity with Lisp. In fact, the logic is a subset of the mechanized logic of the ACL2 system. ACL2 stands for ``A Computational Logic for Applicative Common Lisp'' and the ACL2 system includes a programming language and an ``automatic'' theorem prover. But this is not a course in mechanical theorem proving or how to use ACL2. In fact, we recommend that you not use the ACL2 system while doing these exercises. A good way to learn to use ACL2 --- or any of today's mechanical proof systems --- is to learn to do proofs by hand. It will teach you how to define functions that are convenient to analyze, how to state inductively provable theorems, how to decompose theorems into simpler ``lemmas'', and how to simplify terms using previously proved results. If your goal is to learn to prove theorems about recursively defined functions, work your way through these notes and do the exercises. It can help if you partner with someone else so you have someone to double-check your proofs. If your goal is learn to use the ACL2 system to prove theorems, we recommend that you start exactly the same way: work through these exercises by hand (ideally, all of them). Only then should you fire up the prover and try to use it to prove the same theorems you've proved by hand. It will be educational. The ACL2 system is a [3mvery[0m attentive partner. Our answers to all the exercises are available in the Answer Key, which may be found in the [community-books], file [47mdemos/r-and-i-answer-key-log.txt[0m. We urge you not to refer to the Answer Key except as a last resort (and, of course, to check your answers). That file is generated by ACL2 and has a certain amount of unavoidable boilerplate in it. You should read the Lisp comment at the top of the file for instructions on how to explore and interpret the file. This document started as course notes for [3mCS389R Recursion and Induction[0m, in the Department of Computer Science of the University of Texas at Austin. The course was created in 1981 by Robert S. Boyer and J Strother Moore. It has been offered almost every year since 1981, taught by Boyer, Moore, or Warren A. Hunt, Jr. Initially, the course used a subset of the logic of the Nqthm theorem prover [0], but around 2000 it was changed to a subset of the logic of the ACL2 prover [1,2,4]. (See [r-and-i-annotated-bibliography] for an annotated bibliography that elaborates references in square brackets, such as ``[0]''.) Mechanical theorem proving tools were not taught or used in the course. In the early 1980s, when Boyer and Moore co-taught the course, the logic was presented in a bare-bones style in a few pages. Several more pages listed problems for the students to work on. Students were expected to formalize concepts and come to the blackboard and present definitions and proofs. Their classmates were expected to question and critique what was being said. Often these classroom discussions just raised new problems that the students addressed in subsequent class meetings. Over time, the course notes were expanded to include explanations, examples, and more problems. Moore wrote the first version of this ACL2-based document in the early 2000s, building on joint work with Matt Kaufmann. That document was edited still further by Kaufmann, Moore, and Hunt after Hunt began teaching the course in 2004. In 2022, Kaufmann converted it from LaTeX pdf to the hypertext format of ACL2's online documentation and tied it into ACL2's documentation. Finally, we thank the many sponsors and supporters of the Nqthm and ACL2 projects over the last 40 years, as well as the many students who have so carefully studied and corrected these notes and the many users of Nqthm and ACL2. See the ACL2 [Acknowledgments] page. Next: Introduction (see [R-AND-I-INTRODUCTION]) (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS])) Subtopics [R-and-i-introduction] Recursion and Induction: Introduction [R-and-i-data-types] Recursion and Induction: Data Types [R-and-i-terms] Recursion and Induction: Terms [R-and-i-substitutions] Recursion and Induction: Substitutions [R-and-i-abbreviations-for-terms] Recursion and Induction: Abbreviations for Terms [R-and-i-function-definitions] Recursion and Induction: Function Definitions [R-and-i-axioms] Recursion and Induction: Axioms [R-and-i-terms-as-formulas] Recursion and Induction: Terms as Formulas [R-and-i-definitions-revisited] Recursion and Induction: Definitions Revisited [R-and-i-structural-induction] Recursion and Induction: Structural Induction [R-and-i-arithmetic] Recursion and Induction: Arithmetic [R-and-i-inadequacies-of-structural-recursion] Recursion and Induction: Inadequacies of Structural Recursion [R-and-i-ordinals] Recursion and Induction: The Ordinals [R-and-i-definitional-principle] Recursion and Induction: The Definitional Principle [R-and-i-induction-principle] Recursion and Induction: The Induction Principle [R-and-i-relations-between-recursion-and-induction] Recursion and Induction: Relations Between Recursion and Induction [R-and-i-more-problems] Recursion and Induction: More Problems [R-and-i-more-inadequacies-of-the-definitional-principle] Recursion and Induction: More Inadequacies of the Definitional Principle [R-and-i-still-more-problems] Recursion and Induction: Still More Problems [R-and-i-annotated-bibliography] Recursion and Induction: Annotated Bibliography [R-and-i-table-of-contents] Recursion and Induction Table of Contents)") (recursivep (pointers) "See [system-utilities].") (redef (ld) "A common way to set [ld-redefinition-action] Example and General Form: ACL2 !>:redef This command sets [47m[ld-redefinition-action][0m to [47m'(:query . :overwrite)[0m. This command allows redefinition of functions and other [events] without undoing, but with a query that requires the user to acknowledge that the redefinition is intentional. To avoid that query, see [redef!]. For more options and an important warning about the danger of using redefinition, including possible unsoundness, see [ld-redefinition-action].") (redef! (ld) "A common way to set [ld-redefinition-action] Example and General Form: ACL2 !>:redef! This command sets [47m[ld-redefinition-action][0m to [47m'(:warn! . :overwrite)[0m. This command allows redefinition of functions and other [events] without undoing, but with a warning. The command [47m:[0m[47m[redef][0m is similar, but queries the user first before doing the redefinition. For more options and an important warning about the danger of using redefinition, including possible unsoundness, see [ld-redefinition-action].") (redef+ (ld) "System hacker's redefinition [command] Example and General Form: ACL2 !>:redef+ ACL2 p!> This [command] is intended only for system hackers, not typical users. It sets [47m[ld-redefinition-action][0m to [47m'(:warn! . :overwrite)[0m, sets the default [defun-mode] to [47m:[0m[47m[program][0m, and invokes [47m[set-state-ok][0m with value [47mt[0m. It also introduces [47m(defttag :redef+)[0m, so that redefinition of system functions will be permitted; see [defttag]. It also removes as untouchable (see [push-untouchable]) all variables and functions. WARNING: This command is potentially unsafe and even unsound! For a relevant warning about redefinition, see [ld-redefinition-action]. Moreover, if the form [47m(redef+)[0m is used in a book, then including the book can leave you in a state in which dangerous actions are allowed, specifically: redefinition, and access to functions and variables normally prohibited because they are untouchable. To avoid this problem, insert the form [47m([0m[47m[redef-][0m[47m)[0m into your book after [47m(redef+)[0m. Note that undoing a [47m:redef+[0m command, say with [47m:[0m[47m[u][0m, only undoes the effects of [47m:redef+[0m on the ACL2 [world]; it does [3mnot[0m undo the other effects on the ACL2 [state]. The best way to undo the effects of [47m:redef+[0m is generally to execute [47m:[0m[47m[redef-][0m. To understand this point we look at the code for [47mredef+[0m. The output below has been edited to put world-changing parts in lower case. ACL2 !>:trans1 (redef+) (WITH-OUTPUT :OFF (SUMMARY EVENT) (PROGN (defttag :redef+) (PROGN! (SET-LD-REDEFINITION-ACTION '(:WARN! . :OVERWRITE) STATE) (program) (SET-TEMP-TOUCHABLE-VARS T STATE) (SET-TEMP-TOUCHABLE-FNS T STATE) (F-PUT-GLOBAL 'REDUNDANT-WITH-RAW-CODE-OKP T STATE) (set-state-ok t)))) ACL2 !> In particular, we see that redefinition remains active after undoing. In general, it is therefore best to execute [47m:redef-[0m before undoing [47m:redef+[0m. This [command] was introduced to support modification of ACL2 source code definitions. Thus, note that even system functions can be redefined with a mere warning. Be careful!") (redef- (ld) "Turn off system hacker's redefinition [command] Example and General Form: ACL2 !>:redef- ACL2 p!> This macro, for system hackers only, is a convenient way to reverse the effects of [47m:redef+[0m. See [redef+]. We do not guarantee that [47m:redef-[0m will restore everything one might expect to its state before the earlier [47m:redef+[0m. To see exactly what [47m:redef-[0m does, look at its code, for example by evaluating [47m:trans1 (redef-)[0m") (redefine (pointers) "See [ld-redefinition-action].") (redefined-names (world) "To collect the names that have been redefined Example and General Forms: (redefined-names state) This function collects names that have been redefined in the current ACL2 [state]. [47m:[0m[47m[Program][0m mode functions that were reclassified to [47m:[0m[47m[logic][0m functions are not collected, since such reclassification cannot imperil soundness because it is allowed only when the new and old definitions are identical. Thus, if [47m(redefined-names state)[0m returns [47mnil[0m then no unsafe definitions have been made, regardless of [47m[ld-redefinition-action][0m. See [ld-redefinition-action]. WARNING: This function does not report names that are not explicitly redefined in the current logical [world]. Consider for example: (encapsulate () (defun foo () t) (local (defun foo () nil)) (defthm foo-prop (equal (foo) nil) :rule-classes nil)) If you attempt to call [47m[certify-book][0m in the resulting world, ACL2 will appropriately refuse to do the certification: ACL2 Error in (CERTIFY-BOOK "foo" ...): At least one command in the current ACL2 world was executed while the value of state global variable 'LD-REDEFINITION-ACTION was not nil: (DEFUN FOO NIL T) Certification is therefore not allowed in this world. You can use :ubt to undo back through this command; see :DOC ubt. However, since the local redefinition of [47mfoo[0m is gone in the certification world, [47m(redefined-names state)[0m will return [47mnil[0m. (Technical aside, to be ignored except for those interested in implementation details: ACL2 inhibits [47mcertify-book[0m in this example because the definition of [47mfoo[0m is the value of [47m(global-val 'redef-seen (w state))[0m.)") (redefining (pointers) "See [ld-redefinition-action].") (redefining-programs (programming) "An explanation of why we restrict redefinitions ACL2 does not in general allow the redefinition of functions because logical inconsistency can result: previously stored theorems can be rendered invalid if the axioms defining the functions involved are changed. However, to permit prototyping of both [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m mode systems, ACL2 permits redefinition if the user has accepted logical responsibility for the consequences by setting [47m[ld-redefinition-action][0m to an appropriate non-[47mnil[0m value. The refusal of ACL2 to support the unrestricted redefinition of [47m:[0m[47m[program][0m mode functions may appear somewhat capricious. After all, what are the logical consequences of changing a definition if no axioms are involved? Three important points should be made before we discuss redefinition further. The first is that ACL2 does support redefinition (of both [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m functions) when [47m[ld-redefinition-action][0m is non-[47mnil[0m. The second is that a ``redefinition'' that does not change the mode, formals, guards, type declarations, stobjs, or body of a function is considered redundant and is permitted even when [47m[ld-redefinition-action][0m is [47mnil[0m. We recognize and permit redundant definitions because it is not uncommon for two distinct [books] to share identical function definitions. When determining whether the body of a function is changed by a proposed redefinition, we actually compare the untranslated versions of the two bodies. See [term]. For example, redundancy is not recognized if the old body is [47m(list a b)[0m and the new body is [47m(cons a (cons b nil))[0m. We use the untranslated bodies because of the difficulty of translating the new body in the presence of the old syntactic information, given the possibility that the redefinition might attempt to change the [signature] of the function, i.e., the number of formals, the number of results, or the position of single-threaded objects in either. The third important point is that a ``redefinition'' that preserves the formals, guard, types, stobjs, and body but changes the mode from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m is permitted even when [47m[ld-redefinition-action][0m is [47mnil[0m. That is what [47m[verify-termination][0m does. This note addresses the temptation to allow redefinition of [47m:[0m[47m[program][0m functions in situations other than the three described above. Therefore, suppose [47m[ld-redefinition-action][0m is [47mnil[0m and consider the cases. Case 1. Suppose the new definition attempts to change the formals or more generally the [signature] of the function. Accepting such a redefinition would render ill-formed other [47m:[0m[47m[program][0m functions which call the redefined function. Subsequent attempts to evaluate those callers could arbitrarily damage the Common Lisp image. Thus, redefinition of [47m:[0m[47m[program][0m functions under these circumstances requires the user's active approval, as would be sought with [47m[ld-redefinition-action][0m [47m'(:query . :overwrite)[0m. Case 2. Suppose the new definition attempts to change the body (even though it preserves the [signature]). At one time we believed this was acceptable and ACL2 supported the quiet redefinition of [47m:[0m[47m[program][0m mode functions in this circumstance. However, because such functions can be used in macros and redundancy checking is based on untranslated bodies, this turns out to be unsound! (Aside: Perhaps this is not an issue if the function takes [47m[state][0m or a user-defined [stobj] argument; but we do not further consider this distinction.) Such redefinition is therefore now prohibited. We illustrate such an unsoundness below. Let [47mfoo-thm1.lisp[0m be a book with the following contents. (in-package "ACL2") (defun p1 (x) (declare (xargs :mode :program)) (list 'if x 't 'nil)) (defmacro p (x) (p1 x)) (defun foo (x) (p x)) (defthm foo-thm1 (iff (foo x) x) :rule-classes nil) Note that the macro form [47m(p x)[0m translates to [47m(if x t nil)[0m. The [47m:[0m[47m[program][0m function [47mp1[0m is used to generate this translation. The function [47mfoo[0m is defined so that [47m(foo x)[0m is [47m(p x)[0m and a theorem about [47mfoo[0m is proved, namely, that [47m(foo x)[0m is true iff [47mx[0m is true. Now let [47mfoo-thm2.lisp[0m be a book with the following contents. (in-package "ACL2") (defun p1 (x) (declare (xargs :mode :program)) (list 'if x 'nil 't)) (defmacro p (x) (p1 x)) (defun foo (x) (p x)) (defthm foo-thm2 (iff (foo x) (not x)) :rule-classes nil) In this book, the [47m:[0m[47m[program][0m function [47mp1[0m is defined so that [47m(p x)[0m means just the negation of what it meant in the first book, namely, [47m(if x nil t)[0m. The function [47mfoo[0m is defined identically --- more precisely, the [3muntranslated[0m body of [47mfoo[0m is identical in the two [books], but because of the difference between the two versions of the [47m:[0m[47m[program][0m function [47mp1[0m the axioms defining the two [47mfoo[0ms are different. In the second book we prove the theorem that [47m(foo x)[0m is true iff [47mx[0m is nil. Now consider what would happen if the [signature]-preserving redefinition of [47m:[0m[47m[program][0m functions were permitted and these two [books] were included. When the second book is included the redefinition of [47mp1[0m would be permitted since the [signature] is preserved and [47mp1[0m is just a [47m:[0m[47m[program][0m. But then when the redefinition of [47mfoo[0m is processed it would be considered redundant and thus be permitted. The result would be a logic in which it was possible to prove that [47m(foo x)[0m is equivalent to both [47mx[0m and [47m(not x)[0m. In particular, the following sequence leads to a proof of nil: (include-book "foo-thm1") (include-book "foo-thm2") (thm nil :hints (("Goal" :use (foo-thm1 foo-thm2)))) It might be possible to loosen the restrictions on the redefinition of [47m:[0m[47m[program][0m functions by allowing [signature]-preserving redefinition of [47m:[0m[47m[program][0m functions not involved in macro definitions. Alternatively, we could implement definition redundancy checking based on the translated bodies of functions (though that is quite problematic). Barring those two changes, we believe it is necessary simply to impose the same restrictions on the redefinition of [47m:[0m[47m[program][0m mode functions as we do on [47m:[0m[47m[logic][0m mode functions.") (redo-flat (debugging) "Redo on failure of a [47m[progn][0m, [47m[encapsulate][0m, or [47m[certify-book][0m When one submits an [47m[encapsulate][0m, [47m[progn][0m, or [47m[certify-book][0m command and there is a failure, ACL2 restores its logical [world] as though the command had not been run. But sometimes one would like to debug the failure by re-executing all sub-events that succeeded up to the point of failure, and then re-executing the failed sub-event. Said differently, imagine that the [events] under an [47mencapsulate[0m, [47mprogn[0m, or [47mcertify-book[0m form were flattened into a list of events that were then submitted to ACL2 up to the point of failure. This would put us in the state in which the original failed event had failed, so we could now replay that failed event and try modifying it, or first proving additional events, in order to get it admitted. [47mRedo-flat[0m is provided for this purpose. Consider the following (rather nonsensical) example, in which the [47m[defun][0m of [47mf3[0m fails (the body is [47my[0m but the formal parameter list is [47m(x)[0m). (encapsulate () (defun f1 (x) x) (encapsulate () (local (defthm hack (equal (car (cons x y)) x)))) (encapsulate () (local (defthm hack (equal (+ x y) (+ y x))))) (encapsulate () (make-event '(defun f2 (x) x)) (progn (defthm foo (equal x x) :rule-classes nil) (defun f3 (x) y))) (defun f4 (x) x) (defun f5 (x) y)) After this attempt fails, you can evaluate the following form. (redo-flat) This will first lay down a [47m[deflabel][0m event, [47m(deflabel r)[0m, so that you can eventually remove your debugging work with [47m(:ubt! r)[0m. Then the successful sub-events that preceded the failure will be executed with proofs skipped (so that this execution is fast). Then, the failed event will be executed. Finally, a [47m:[0m[47m[pbt][0m command is executed so that you can see a summary of the events that executed successfully. You can eliminate some of the steps above by supplying keyword values, as follows, where those arguments are not evaluated. (redo-flat :succ succ ; Skip the successful sub-events if val is nil. :fail fail ; Skip the failed sub-event if val is nil. :label lab ; Skip deflabel if lab or succ is nil, else use (deflabel lab). :pbt val ; Skip the final :pbt if val, lab, or succ is nil. ) Also, you can avoid skipping proofs for the successful sub-events by supplying keyword [47m:succ-ld-skip-proofsp[0m with a valid value for [47mld-skip-proofsp[0m; see [ld-skip-proofsp]. For example, you might want to execute [47m(redo-flat :succ-ld-skip-proofsp nil)[0m if you use the [47mmust-fail[0m utility from community book [47mmake-event/eval.lisp[0m, since for example [47m(must-fail (thm (equal x y)))[0m normally succeeds but would cause an error if proofs are skipped. For another example: you may wish to do proofs when re-running certain [47m[make-event][0m forms, for example, when the expansion is [47m(:OR expr1 expr2)[0m and the proof initially succeeds for [47mexpr2[0m rather than [47mexpr1[0m (see [make-event]). If you prefer only to see the successful and failed sub-events, without any events being re-executed, you may evaluate the following form instead. (redo-flat :show t) For the example above, this command produces the following output. List of events preceding the failure: ((DEFUN F1 (X) X) (ENCAPSULATE NIL (LOCAL (DEFTHM HACK (EQUAL (CAR (CONS X Y)) X)))) (ENCAPSULATE NIL (LOCAL (DEFTHM HACK (EQUAL (+ X Y) (+ Y X))))) (MAKE-EVENT '(DEFUN F2 (X) X)) (DEFTHM FOO (EQUAL X X) :RULE-CLASSES NIL)) Failed event: (DEFUN F3 (X) Y) ACL2 !> [47mRedo-flat[0m uses a scheme that should not cause spurious name conflicts for [47m[local][0m events. Above, it is mentioned that events are ``flattened''; now we clarify this notion. Each sub-event that succeeds and is an [47m[encapsulate][0m or [47m[progn][0m is left intact. Only such events that fail are replaced by their component events. Thus, in the example above, there is no conflict between the two [47m[local][0m sub-events named ``[47mhack[0m,'' because these are contained in successful [47mencapsulate[0m sub-events, which are therefore not flattened. The [47m[progn][0m and two [47m[encapsulate][0m events surrounding the definition of [47mf3[0m are, however, flattened, because that definition failed to be admitted. Normally, [47mredo-flat[0m will have the desired effect even if you interrupted a proof (with control-c). However, [47mredo-flat[0m will not produce the desired result after an interrupt if you have enabled the debugger using [47m(set-debugger-enable t)[0m or if you have disabled the default ``soft'' interrupt behavior (see [abort-soft]).") (redundant (pointers) "See [redundant-events].") (redundant-encapsulate (encapsulate) "Redundancy of [47m[encapsulate][0m [events] For this [documentation] topic we assume familiarity with [47mencapsulate[0m events and the notion of redundancy for [events]; see [encapsulate] and see [redundant-events]. Until the final remark, we also assume that redefinition is off (see [ld-redefinition-action]). The typical way for an [47mencapsulate[0m event to be redundant is when a syntactically identical [47mencapsulate[0m has already been executed under the same [47m[default-defun-mode][0m, [47m[default-ruler-extenders][0m, and [47m[default-verify-guards-eagerness][0m. But more generally, the [47mencapsulate[0m events need not be syntactically identical; for example, it suffices that they agree when the contents of [47m[local][0m sub-events are ignored. Detailed criteria for redundancy are given below, but let us first look at a consequence of the point just made about ignoring the contents of [47m[local][0m sub-events. Consider the following sequence of two events. (encapsulate () (defun f (x) x) (local (defthm f-identity (equal (f x) x)))) (encapsulate () (defun f (x) x) (local (defthm false-claim (equal (f x) (not x))))) You might be surprised to learn that the second is actually redundant, even though [47mfalse-claim[0m is clearly not a theorem; indeed, its negation is a theorem! The following two points may soften the blow. First, this behavior is as specified above (and is specified more precisely below): the contents of [local] events are ignored when checking redundancy of [47m[encapsulate][0m events. Second, this behavior is sound, because the logical meaning of an [47m[encapsulate][0m event is taken from the events that it exports, which do not include events that are [local] to the [47mencapsulate[0m event. Some users, however, want to use [47m[encapsulate][0m events for testing in a way that is thwarted by this ignoring of [local] sub-events. Consider the following sort of example. (encapsulate () (local (defthm test1 ...))) (encapsulate () (local (defthm test2 ...))) Fortunately, in this case both [47mtest1[0m and [47mtest2[0m will be evaluated. To see why, first note that when a completed [encapsulate] event with empty [signature] has introduced no sub-[events], then it has no effect at all on the logical [world]. Thus, the first [47mencapsulate[0m event is not stored in the world; so, the second [47mencapsulate[0m event is not redundant, since it is executed in a world that contains no trace of the first [47mencapsulate[0m event. Also see community books [47mstd/testing/eval.lisp[0m, [47mmake-event/eval-check.lisp[0m, and [47mmake-event/eval-tests.lisp[0m for more ways to test in books. Here are detailed criteria for redundancy of [47m[encapsulate][0m [events]. First, based on a heuristic (but rather thorough) check, the proposed (new) [47mencapsulate[0m event must be seen as [3mpossibly[0m introducing a new name, for example because one of its sub-events, perhaps after some macroexpansion, is an invocation of [47m[defun][0m, of [47m[defthm][0m, or of certain other events that [3mmight[0m introduce a name, including [47m[make-event][0m. Second, the two [world]s in which each [47mencapsulate[0m event is evaluated must have the same [default-defun-mode]s, the same [default-ruler-extenders], and the same [default-verify-guards-eagerness]. Third, the existing and proposed [47mencapsulate[0m [events] must contain the same [signature]s and the same number of top-level sub-events; let [47mk[0m be that number. Finally: for each [47mi < k[0m, the [47mi[0mth top-level events [47mE1[0m and [47mE2[0m from the earlier and proposed [47mencapsulate[0ms must be related in one of the following ways. * [47mE1[0m and [47mE2[0m are equal; or * [47mE1[0m is of the form [47m(record-expansion E2 ...)[0m, with the exception noted below; or else * [47mE1[0m and [47mE2[0m are equal after replacing each sub-event of [47mE1[0m with its [47m[make-event][0m expansion and replacing each [47m[local][0m sub-event of [47mE1[0m or [47mE2[0m by [47m(local (value-triple :elided))[0m. Here, a sub-event of an event [47mE[0m is defined to be either [47mE[0m itself, or a sub-event of a constituent event of [47mE[0m in the case that [47mE[0m is a call of [47m[skip-proofs][0m, [47m[with-output][0m, [47m[with-prover-time-limit][0m, [47m[with-prover-step-limit][0m, [47mrecord-expansion[0m, [47m[time$][0m, [47m[progn][0m, [47m[progn!][0m, or [47m[encapsulate][0m itself. The second condition has the following exception: it does not apply when the new [47mencapsulate[0m event takes place within an [47m[include-book][0m event. (Allowing that would be unsound, as explained in a comment in ACL2 source function [47mcorresponding-encaps[0m.) [31;1mRemark[0m. We conclude with some discussion of redundancy of [47mencapsulate[0m events in the presence of redefinition (see [ld-redefinition-action]). Consider the following sequence of events. (encapsulate () (defun foo (x) x)) (redef!) ; Turn on redefinition. ; not redundant (encapsulate () (defun foo (x) (cons x x))) ; not redundant (encapsulate () (defun foo (x) x)) Note that the last [47mencapsulate[0m call is identical to an earlier event, namely the first one. However, ACL2 never sees that first event when determining whether the last event is redundant. The reason is that when ACL2 searches the world for a corresponding [47mencapsulate[0m event, it does not look back past the most recent definition of [47mfoo[0m. By contrast, consider what happens when, in a fresh ACL2 session, we evaluate the following sequence instead, obtained by wrapping a [47m[make-event][0m call around each [47m[defun][0m event. (encapsulate () (make-event '(defun foo (x) x))) (redef!) ; Turn on redefinition. ; not redundant (encapsulate () (make-event '(defun foo (x) (cons x x)))) ; redundant! (encapsulate () (make-event '(defun foo (x) x))) It may be surprising that the last [47mencapsulate[0m call is redundant. The reason is that it is identical to an earlier [47mencapsulate[0m event. Because of the use of [47mmake-event[0m in the final event, ACL2 does not determine that the last event is attempting to define [47mfoo[0m, so ACL2 does not limit its search backward through the world as it did in the previous example (where there were no uses of [47mmake-event[0m). The moral of the story: when redefinition is involved, it may be best not to rely on one's intuition about redundancy for [47mencapsulate[0m events.") (redundant-events (events) "Allowing a name to be introduced ``twice'' Sometimes an event will announce that it is ``redundant'', meaning that the form is not evaluated because ACL2 determines that its effect is already incorporated into the logical [world]. Thus, when this happens, no change to the logical [world] takes place. This feature permits two independent [books], each of which defines some name, to be included sequentially provided they use exactly the same definition. Note that by the definition above, a form can have no effect on the logical [world] yet not be considered to be redundant. Here is an example of such a form. (value-triple (cw "Hello world.~%")) When are two [logical-name] definitions considered ``the same''? It depends upon the kind of event that introduces that name. We consider these below in alphabetical order, followed by ``Note About'' comments. Macros in the [community-books] may also support redundancy; see their documentation for details, since below we only discuss ACL2 [events] that are built into ACL2. A [47m[defstobj][0m or [47m[defabsstobj][0m is redundant if there is already an identical such event in the logical [world]. A [47m[defattach][0m event is never redundant. (Reasons are provided in a comment in the ACL2 sources definition of defattach in the ACL2 logic.) Note that [47mdefattach[0m events do not define any names. A [47m[defaxiom][0m or [47m[defthm][0m event is redundant if there is already an axiom or theorem of the given name and the two [events] are syntactically identical. But there is the following more generous criterion, which applies unless the older event is a [47mdefthm[0m event and the newer event is a [47mdefaxiom[0m event: both the formula (after macroexpansion) and the [rule-classes] (after translation and certain ``truncation'') are syntactically identical. This ``truncation'' involves removing the [47m:HINTS[0m and [47m:INSTRUCTIONS[0m fields from a rule-class, and also removing the [47m:COROLLARY[0m field when it specifies the same term as the event. Note that a [47m[defthm][0m can be redundant with a [47m[defaxiom][0m but not vice-versa. (Remark for system hackers: [47mdefthm[0m/[47mdefaxiom[0m redundancy is implemented in ACL2 source function, [47mredundant-theoremp[0m.) A [47m[defconst][0m is redundant if the name is already defined either with a syntactically identical [47mdefconst[0m event or one that defines it to have the same value. A [47m[deflabel][0m event is never redundant. This means that if you have a [47m[deflabel][0m in a book and that book has been included (without error), then references to that label denote the point in [history] at which the book introduced the label. See the note about shifting logical names, below. A [47m[defmacro][0m event is redundant if there is already a macro defined with the same name and syntactically identical arguments, [guard], and body. A [47m[defpkg][0m event is redundant if a package of the same name with exactly the same imports has been defined. A [47m[defthm][0m event is redundant according to the criteria given above in the discussion of [47mdefaxiom[0m. A [47m[deftheory][0m event is redundant if keyword argument [47m:redundant-okp[0m is not [47mnil[0m and the theory is unchanged from the one already associated with the name. More precisely, the runic theory computed from the theory expression must be equal to the runic theory already associated with the name. (See [theories] for a discussion of runic theories. Also see [defthy] for a variant of [47mdeftheory[0m that supports redundancy by default.) Equality of runic theories is a rather severe restriction, since most theory expressions are sensitive to the context in which they occur. Consider the following example. (deftheory foo (disable append revappend) :redundant-okp t) (defthm my-car-cons (equal (car (cons x y)) x)) (deftheory foo (disable revappend append) :redundant-okp t) The second [47mdeftheory[0m event above is not redundant, because its computed runic theory includes the [rune] [47m(:rewrite my-car-cons)[0m, which is not in the runic theory previously associated with [47mfoo[0m. If we change the example either to eliminate the [47m[defthm][0m above or to change it to call [47m[defthmd][0m instead, then the second [47mdeftheory[0m event is redundant, because the runic theories are ordered, and hence the order of runic designators (here, [47mrevappend[0m and [47mappend[0m) is irrelevant. A [47m[defun][0m, [47m[defuns][0m, or [47m[mutual-recursion][0m event is redundant if for each function to be introduced, there has already been introduced a function with the same name, formals, and body (before macroexpansion), and with the same values [declare]d for the [47m:[0m[47m[guard][0m, [47m:[0m[47m[measure][0m, types, [47m:[0m[47m[ruler-extenders][0m, [47m:non-executable[0m, [47m:type-prescription[0m, [47m:[0m[47m[stobj][0m[47ms[0m, and [47m:[0m[47m[split-types][0m, provided that the [defun-mode]s are appropriate (see the ``Note About Appropriate Modes'' below). Moreover, the order of the combined [47m:[0m[47m[guard][0m and type declarations must be the same in both cases. Exceptions and clarifications: 1. If the new and existing function events have no explicit [ruler-extenders] (which are therefore syntactically equal), the [default-ruler-extenders] for the new and existing function events must be the same. 2. It is permissible for one definition to have a [47m:[0m[guard] of [47mt[0m and the other to have no explicit guard (hence, the guard is implicitly [47mt[0m). 3. The [47m:measure[0m check is avoided if the old definition is non-recursive (and not defined within a [47m[mutual-recursion][0m) or we are skipping proofs (for example, during [47m[include-book][0m). Otherwise, the new definition may have a [47m:measure[0m of [47m(:? v1 ... vk)[0m, where [47m(v1 ... vk)[0m enumerates the variables occurring in the measure stored for the old definition. 4. If either the old or new event is a [47m[mutual-recursion][0m event, then redundancy requires that both are [47m[mutual-recursion][0m events that define the same set of function symbols. 5. The [stobj]s declared by the two definitions are allowed to disagree on [47mstate[0m: one can declare [47mstate[0m among its declared [47m:stobjs[0m values while the other does not, regardless of whether or not [47m[set-state-ok][0m has been evaluated. That is, they only need to agree on the stobjs that are [3muser-defined[0m. 6. Redundancy may fail with an error about a name being ``already defined using special raw Lisp code'' or ``predefined in the "COMMON-LISP" package''. This applies to certain functions that are built into ACL2; it may also apply when definitions are overridden in raw Lisp using trust tags (see [defttag]), typically in books. The reason for causing an error is that if the proposed redundant definition is in a book, then when later including that book after it is certified, the compiled code for that definition will replace the original code, which is generally undesirable when the original code has special raw Lisp optimizations. If the earlier definition is in a book, then the error message will suggest including that book rather than trying to define the function redundantly. An [47m[encapsulate][0m event is most commonly redundant when a syntactically identical [47m[encapsulate][0m has already been executed under the same [47m[default-defun-mode][0m, [47m[default-ruler-extenders][0m, and [47m[default-verify-guards-eagerness][0m. The full criterion for redundancy of [47mencapsulate[0m events is more complex, for example ignoring contents of [47m[local][0m [events]; see [redundant-encapsulate]. An [47m[in-theory][0m event is never redundant by default, though that can be changed; see [set-in-theory-redundant-okp]. Note that it doesn't define any name. An [47m[include-book][0m event is redundant if the book has already been included. A call of [47m[make-event][0m is never redundant, as its argument is always evaluated to obtain the make-event expansion. However, that expansion may of course be redundant. A [47m[mutual-recursion][0m event is redundant according to the criteria in the discussion above for the case of a [47mdefun[0m event. A [47m[progn][0m event is never redundant: its subsidiary [events] are always considered. Of course, its sub-events may themselves be redundant. If all of its sub-events are redundant --- or more generally, if none of the sub-events changes the logical [world] --- then the [47mprogn[0m event also won't change the world. A [47m[push-untouchable][0m event is redundant if every name supplied is already a member of the corresponding list of untouchable symbols. A [47m[regenerate-tau-database][0m event is never redundant. Note that it doesn't define any name. A [47m[remove-untouchable][0m event is redundant if no name supplied is a member of the corresponding list of untouchable symbols. A [47m[reset-prehistory][0m event is redundant if it does not cause any change. A [47m[set-body][0m event is redundant if the indicated body is already the current body. A [47m[table][0m event not define any name. It is redundant when it sets the value already associated with a key of the table, or when it sets an entire table (using keyword [47m:clear[0m) to its existing value; see [table]. Setting a non-existent key to [47mnil[0m is not redundant, with the exception discussed next. [Memoization] is carried out using a [table], [47mmemoize-table[0m, that may associate a function symbol with [47mnil[0m when it is not memoized. It is redundant to [47m[unmemoize][0m a currently-unmemoized function symbol, thus associating it with [47mnil[0m in the [47mmemoize-table[0m --- even if that function symbol is not already a key of that table (this is the exception noted in the preceding paragraph). It is redundant to [47m[memoize][0m a function when the function is already identically memoized, that is, when the corresponding [47m[table][0m event is redundant. A [47m[verify-guards][0m event is redundant if the function has already had its [guard]s verified. [3mNote About Built-in (Predefined) Functions and Macros:[0m Redundancy is restricted for built-in macros and functions that have special raw Lisp code. Such redundancy is only legal in the context of [47m[local][0m. This restriction is needed for soundness, for technical reasons omitted here (details may be found in a long comment about redundant-events in source function [47mchk-acceptable-defuns-redundancy[0m). [3mNote About Appropriate Modes:[0m Suppose a function is being redefined and that the formals, guards, types, user-defined stobjs, and bodies are identical. When are the modes ([47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m) ``appropriate?'' Identical modes are appropriate. But what if the old mode was [47m:program[0m and the new mode is [47m:logic[0m? This is appropriate, provided the definition meets the requirements of the logical definitional principle. That is, you may redefine ``redundantly'' a [47m:program[0m mode function as a [47m:logic[0m mode function provide the measure conjectures can be proved. This is what [47m[verify-termination][0m does. Now consider the reverse style of redefinition. Suppose the function was defined in [47m:logic[0m mode and is being identically redefined in [47m:program[0m mode. ACL2 will treat the redefinition as redundant, provided the appropriate criteria are met (as though it were in :logic mode). [3mNote About Shifting Logical Names:[0m Suppose a book defines a function [47mfn[0m and later uses [47mfn[0m as a logical name in a theory expression. Consider the value of that theory expression in two different sessions. In session A, the book is included in a [world] in which [47mfn[0m is not already defined, i.e., in a [world] in which the book's definition of [47mfn[0m is not redundant. In session B, the book is included in a [world] in which [47mfn[0m is already identically defined. In session B, the book's definition of [47mfn[0m is redundant. When [47mfn[0m is used as a logical name in a theory expression, it denotes the point in [history] at which [47mfn[0m was introduced. Observe that those points are different in the two sessions. Hence, it is likely that theory expressions involving [47mfn[0m will have different values in session A than in session B. This may adversely affect the user of your book. For example, suppose your book creates a theory via [47m[deftheory][0m that is advertised just to contain the names generated by the book. But suppose you compute the theory as the very last event in the book using: (set-difference-theories (universal-theory :here) (universal-theory fn)) where [47mfn[0m is the very first event in the book and happens to be a [47m[defun][0m event. This expression returns the advertised set if [47mfn[0m is not already defined when the book is included. But if [47mfn[0m were previously (identically) defined, the theory is larger than advertised. The moral of this is simple: when building [books] that other people will use, it is best to describe your [theories] in terms of logical names that will not shift around when the [books] are included. The best such names are those created by [47m[deflabel][0m. [3mNote About Unfortunate Redundancies.[0m Notice that our syntactic criterion for redundancy of [47m[defun][0m [events] may not allow redefinition to take effect unless there is a syntactic change in the definition. The following example shows how an attempt to redefine a function can fail to make any change. (set-ld-redefinition-action '(:warn . :overwrite) state) (defmacro mac (x) x) (defun foo (x) (mac x)) (defmacro mac (x) (list 'car x)) (set-ld-redefinition-action nil state) (defun foo (x) (mac x)) ; redundant, unfortunately; foo does not change (thm (equal (foo 3) 3)) ; succeeds, showing that redef of foo didn't happen The call of macro [47mmac[0m was expanded away before storing the first definition of [47mfoo[0m for the theorem prover. Therefore, the new definition of [47mmac[0m does not affect the expansion of [47mfoo[0m by the theorem prover, because the new definition of [47mfoo[0m is ignored. One workaround is first to supply a different definition of [47mfoo[0m, just before the last definition of [47mfoo[0m above. Then that final definition will no longer be redundant. However, as a courtesy to users, we strengthen the redundancy check for function definitions when redefinition is active. If in the example above we remove the form [47m(set-ld-redefinition-action nil state)[0m, then the problem goes away: (set-ld-redefinition-action '(:warn . :overwrite) state) (defmacro mac (x) x) (defun foo (x) (mac x)) (defmacro mac (x) (list 'car x)) (defun foo (x) (mac x)) ; no longer redundant (thm (equal (foo 3) 3)) ; fails, as we would like To summarize: If a [47m[defun][0m form is submitted that meets the usual redundancy criteria, then it may be considered redundant even if a macro called in the definition has since been redefined. The analogous problem applies to constants, i.e., symbols defined by [47m[defconst][0m that occur in the definition body. However, if redefinition is currently active the problem goes away: that is, the redundancy check is strengthened to check the ``translated'' body, in which macro calls and constants defined by [47m[defconst][0m are expanded away. The above discussion for [47m[defun][0m forms applies to [47m[defconst][0m forms as well. However, for [47m[defmacro][0m forms ACL2 always checks translated bodies, so such bogus redundancy does not occur. Here is more complex example illustrating the limits of redefinition, based on one supplied by Grant Passmore. (defun n3 () 0) (defun n4 () 1) (defun n5 () (> (n3) (n4))) ; body is see normalized to nil (thm (equal (n5) nil)) ; succeeds, trivially (set-ld-redefinition-action '(:warn . :overwrite) state) (defun n3 () 2) (thm (equal (n5) nil)) ; still succeeds, sadly We may expect the final [47m[thm][0m call to fail because of the following reasoning: [47m(n5)[0m = [47m(> (n3) (n4))[0m = [47m(> 2 1)[0m = [47mt[0m. Unfortunately, the body of [47mn5[0m was simplified to [47mnil[0m when [47mn5[0m was admitted (see [normalize]), so the redefinition of [47mn3[0m is ignored during the final [47mthm[0m call. (Such normalization can be avoided; see [xargs] for discussion of the [47m:normalize[0m keyword.) So, given this unfortunate situation, one might expect at this point simply to redefine [47mn5[0m using the same definition as before, in order to pick up the new definition of [47mn3[0m. Such ``redefinition'' would, however, be redundant, for the same reason as in the previous example: no syntactic change was made to the definition. Even with redefinition active, there is no change in the body of [47mn5[0m, even with macros and constants (defined by [47m[defconst][0m) expanded; there are none such! The same workaround applies as before: redefine [47mn5[0m to be something different, and then redefine [47mn5[0m again to be as desired. A related phenomenon can occur for [47m[encapsulate][0m. As explained above, an [47mencapsulate[0m event is redundant if it is identical to one already in the database. (But a weaker condition applies in general; see [redundant-encapsulate].) Consider then the following contrived example. (defmacro mac (x) x) (encapsulate () (defun foo (x) (mac x))) (set-ld-redefinition-action '(:warn . :overwrite) state) (defmacro mac (x) (list 'car x)) (encapsulate () (defun foo (x) (mac x))) The last [47mencapsulate[0m event is redundant because it meets the criterion for redundancy: it is identical to the earlier [47mencapsulate[0m event. Even though redefinition is active, and hence ACL2 ``should'' be able to see that the new [47m[defun][0m of [47mfoo[0m is not truly redundant, nevertheless the criterion for redundancy of [47m[encapsulate][0m allows the new [47mencapsulate[0m form to be redundant. A workaround can be to add something trivial to the [47mencapsulate[0m, for example: (encapsulate () (deflabel try2) ; ``Increment'' to try3 next time, and so on. (defun foo (x) x)) Subtopics [Get-enforce-redundancy] Query the [world] on whether redundancy is being enforced [Get-guard-checking] Get the status most recently installed by [47m[set-guard-checking][0m [Set-enforce-redundancy] Require most events to be redundant [Set-in-theory-redundant-okp] Allow [47m[in-theory][0m events to be redundant") (refinement (rule-classes) "Record that one equivalence relation refines another See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Example: (defthm bag-equal-refines-set-equal (implies (bag-equal x y) (set-equal y x)) :rule-classes :refinement) Also see [defrefinement]. General Form: (implies (equiv1 x y) (equiv2 x y)) [47mEquiv1[0m and [47mequiv2[0m must be known equivalence relations. The effect of such a rule is to record that [47mequiv1[0m is a refinement of [47mequiv2[0m. This means that [47mequiv1[0m [47m:[0m[47m[rewrite][0m rules may be used while trying to maintain [47mequiv2[0m. See [equivalence] for a general discussion of the issues. The macro form [47m(defrefinement equiv1 equiv2)[0m is an abbreviation for a [47m[defthm][0m of rule-class [47m:refinement[0m that establishes that [47mequiv1[0m is a refinement of [47mequiv2[0m. See [defrefinement]. Suppose we have the [47m:[0m[47m[rewrite][0m rule (bag-equal (append a b) (append b a)) which states that [47m[append][0m is commutative modulo bag-equality. Suppose further we have established that bag-equality refines set-equality. Then when we are simplifying [47m[append][0m expressions while maintaining set-equality we use [47m[append][0m's commutativity property, even though it was proved for bag-equality. Equality is known to be a refinement of all equivalence relations. The transitive closure of the refinement relation is maintained, so if [47mset-equality[0m, say, is shown to be a refinement of some third sense of equivalence, then [47mbag-equality[0m will automatically be known as a refinement of that third equivalence. A rewrite rule may fail to fire because its equivalence relation is not known to be a refinement of any of those known to be permitted. See [47m[geneqv][0m for a discussion of how ACL2 uses [47m[congruence][0m rules to derive the permitted equivalences and how those equivalences are represented. See [refinement-failure] for advice on how to use [break-rewrite] to determine that a rule failed the refinement check and for advice about how to ``fix'' such a problem. [47m:refinement[0m lemmas cannot be disabled. That is, once one equivalence relation has been shown to be a refinement of another, there is no way to prevent the system from using that information. Furthermore, [47m:refinement[0m lemmas are not tracked and are thus not reported in the [summary]. Of course, individual [47m:[0m[47m[rewrite][0m rules can be disabled. More will be written about this as we develop the techniques.") (refinement-failure (introduction-to-the-theorem-prover break-rewrite) "what to do when a rewrite rule fails the refinement check One reason a [47m:[0m[47m[rewrite][0m rule may fail to fire is that its equivalence relation fails to be a known refinement of the generated equivalence relation (or ``[geneqv]'') governing the current target of the rewriter. In the following discussion we assume you are familiar with the notion of the generated equivalence relation. If not, please see [47m[geneqv][0m for the necessary background and details. Is a Rule Not Firing Because of a Refinement Failure? To determine whether refinement failure is the cause of a rule's failure to fire, enable [break-rewrite] with [47m(brr t)[0m and install a [47m[monitor][0m with [47m:rf[0m set to [47mt[0m on the rule, e.g., [47m(monitor rune '(:rf t))[0m, where [47mrune[0m evaluates to the [47m[rune][0m of the rule in question. You might also specify a [47m:condition[0m so that a break occurs only if the target is the translated term, [47mtterm[0m, you expected the rule to hit, (monitor rune '(:condition (equal (brr@ :target) 'tterm) :rf t)). Then try the proof again. (Note: if the rule being monitored is a [simple] abbreviation rule, be sure to supply the hint [47m:DO-NOT '(PREPROCESS)[0m as discussed in [47m[monitor][0m.) If a monitored rule fails to fire (under the monitored condition) because its equivalence relation is not known to refine the geneqv derived for that occurrence of the target, an interactive break will occur. The break header will name the rule, print the target, show the rule's equivalence relation, and show the geneqv. The header tells you the equivalence relation is not a refinement of the geneqv. You might wish to use the break-rewrite command [47m:path[0m or [47m:path+[0m to print the path down to the target from the top-level goal. That will show the geneqv derived for each active call of the rewriter and will help you understand why the current geneqv is what it is. While looking at the path make sure that the current occurrence of the target is the one you expected the rule to hit. If it is not, proceed to the next break with [47m:ok[0m. When you find the target you're looking for, focus your attention on the equivalence relation and geneqv. To fix the problem you need the former to be a refinement of the latter. When you understand how to make that happen, abort the failing proof attempt with [47m:a![0m and try to fix the problem. How to Fix a Refinement Failure There are two basic ways to ``fix'' a refinement failure: * (a) prove a [47m[refinement][0m rule that establishes that the equivalence relation used in the rule indeed refines one of the equivalence relations displayed in the geneqv, or * (b) prove a [47m[congruence][0m rule that will extend the geneqv derived for the current occurrence of the target. We illustrate these approaches below. But first you must keep in mind that the equivalence relation in the rule may not refine any possible geneqv derivable along the path. You may have to find a different proof or, at least, you may have to define some additional equivalence relations, refinement rules, and congruence rules, and prove a version of your lemma that uses a new relation. After all, this is a theorem proving problem and not all fixes are trivial! How Geneqvs Are Displayed As illustrated in the discussion of [geneqv], a generated equivalence is essentially a set of equivalence relations. ACL2 prints geneqvs in three different ways depending on the utility doing the printing. When reporting that an equivalence relation is not a refinement of a geneqv, the geneqv is printed simply as a list of equivalence relation names, e.g., [47m(EQV1 EQV2)[0m. Order is unimportant as this list represents a set. When reporting the path the rewriter took to the current target and the geneqvs for each active call of the rewriter along that path, each geneqv is printed as a list of doublets, where the first component of the doublet is the name of an equivalence relation and the second component is the name of the [congruence] rule responsible for adding that relation to the geneqv, e.g., ((EQV1 EQV1-IFF-CONGRUENCE-FOR-F) (EQV2 EQV2-IFF-CONGRUENCE-FOR-F)) This is just another presentation of [47m(eqv1 eqv2)[0m but we believe the congruence rule names may help you recall how equivalence relations get into the set. Finally, in [47m[trace$][0m, or the value returned by (brr@ :geneqv) or any other system utility that displays the actual internal representation of a geneqv you will see something like this: ((5603 EQV1 . (:congruence EQV1-IFF-CONGRUENCE-FOR-F)) (4957 EQV2 . (:congruence EQV2-IFF-CONGRUENCE-FOR-F))) where the equivalence relation names are paired with the runes (not just the names) of the responsible congruence rules and the numbers are unique session-dependent indices for those runes allowing quick determination of the enabled status of the rules. You will see the first two print conventions in the examples below. Some Generic Examples In the following discussion we introduce some functions that will allow us to explore refinement failures. The experiments reported below are carried out in the community book [47mbooks/demos/refinement-failure-test-book.lisp[0m whose input/output log may be found in [47mbooks/demos/refinement-failure-test-log.txt[0m. We're going to attempt to prove [47m(P (F (G A (BETA B))))[0m by rewriting the occurrence of [47m(BETA B)[0m to [47m(GAMMA B)[0m and appealing to a rule that establishes [47m(P (F (G A (GAMMA B))))[0m. But at every subterm level in the conjecture different equivalence relations are involved. Thus, many equivalence and congruence relations are involved and that makes this example hard to follow. Assume that [47mPEQ[0m, [47mFEQ[0m, [47mG2EQ1[0m, [47mG2EQ2[0m, and [47mG2EQ1![0m are known equivalence relations. Possibly Distracting Aside: In this section of this documentation we use names that follow a certain convention. These conventions help the authors keep the names straight! Perhaps they'll help you too. Names containing ``[47mEQ[0m'' are equivalence relations; they will serve as ``inside'' equivalences for the function symbol indicated by the first character in the name, ``[47mP[0m'', ``[47mF[0m'' or ``[47mG[0m''; if that first character is followed by ``2'' it means they apply to the second argument of the function, otherwise they apply to the first (and only) argument; and if there is more than one such inside equivalence relation for that function the name is suffixed with ``[47m1[0m'' or ``[47m2[0m''. The exclamation mark at the end of ``G2EQ1!'' is to remind us that the function is a refinement of [47mG2EQ1[0m. Thus [47mPEQ[0m is the inside equivalence for the first (only) argument of [47mP[0m-terms and [47mG2EQ1[0m is the inside equivalence for the second argument of [47mG[0m-terms and is one of two such relations. Imagine that we've proved two rewrite rules: * [47m(DEFTHM RULE (G2EQ1! (BETA X) (GAMMA X)))[0m * [47m(DEFTHM DONE (P (F (G X (GAMMA Y)))))[0m which is actually stored as [47m(DEFTHM DONE (IFF (P (F (G X (GAMMA Y)))) T))[0m. Clearly, our strategy to prove [47m(P (F (G A (BETA B))))[0m is to use [47mRULE[0m to replace the [47m(BETA B)[0m by [47m(GAMMA B)[0m, and then use [47mDONE[0m to reduce the conjecture to [47mT[0m. However, the problem is that [47mRULE[0m uses the equivalence relation [47mG2EQ1![0m. So the rewriter, which starts by maintaining [47mIFF[0m on the top-level [47mP[0m term, will have to evolve a geneqv so that by the time it reaches the occurrence of [47m(BETA B)[0m the geneqv at that target admits [47mG2EQ1![0m as a refinement. To do so we'll provide the following [47m[congruence][0m rules. As you read them, remember that the term we'll be working on is [47m(P (F (G A (BETA B))))[0m, i.e., our conjecture is a call of [47mP[0m, in which the 1st (and only) argument is a call of [47mF[0m, in which the 1st (and only) argument is a call of [47mG[0m, in which the 2nd argument is call of [47mBETA[0m. * [47mIFF[0m is maintained on a call of [47mP[0m provided [47mPEQ[0m is maintained on the 1st argument of [47mP[0m: * [3mevent[0m: [47m(DEFCONG PEQ IFF (P X) 1)[0m * [3mname[0m: [47mPEQ-IMPLIES-IFF-P-1[0m * [47mPEQ[0m is maintained on a call of [47mF[0m provided [47mFEQ[0m is maintained on the 1st argument of [47mF[0m: * [3mevent[0m: [47m(DEFCONG FEQ PEQ (F X) 1)[0m * [3mname[0m: [47mFEQ-IMPLIES-PEQ-F-1[0m * [47mFEQ[0m is maintained on a call of [47mG[0m provided [47mG2EQ1[0m is maintained on the 2nd argument of [47mG[0m: * [3mevent[0m: [47m(DEFCONG G2EQ1 FEQ (G X Y) 2)[0m * [3mname[0m: [47mG2EQ1-IMPLIES-FEQ-G-2[0m * [47mFEQ[0m is [3malso[0m maintained on a call of [47mG[0m provided [47mG2EQ2[0m is maintained on the 2nd argument of [47mG[0m: * [3mevent[0m: [47m(DEFCONG G2EQ2 FEQ (G X Y) 2)[0m * [3mname[0m: [47mG2EQ2-IMPLIES-FEQ-G-2[0m Note that there are two ways to maintain [47mFEQ[0m on a call of [47mG[0m: maintain either [47mG2EQ1[0m or [47mG2EQ2[0m on the second argument of [47mG[0m. But neither of those equivalence relations is used in our rewrite [47mRULE[0m. Our [47mRULE[0m uses [47mG2EQ1![0m, so assume we've proved: * [47mG2EQ1![0m refines [47mG2EQ1[0m: * [3mevent[0m: [47m(DEFREFINEMENT G2EQ1! G2EQ1)[0m * [3mname[0m: [47mG2EQ1!-REFINES-G2EQ1[0m Having arranged all of the above, imagine issuing the commands (brr T) (monitor '(:REWRITE RULE) '(:condition (and (equal (brr@ :target) '(BETA B)) '(:path+ :go)) :rf t)) (thm (P (F (G A (BETA B)))) :hints (("Goal" :do-not '(preprocess)))) Note: The [47m:condition[0m value above will cause a break only if the [47m:target[0m is [47m(BETA B)[0m, but when the break occurs it will issue the command [47m:PATH+[0m to print the path and then issue the command [47m:GO[0m to proceed from the break. Because we've just monitored a [simple] abbreviation rule, we include in the [47m[thm][0m command the hint to avoid preprocessing, as advised in the documentation for [47m[monitor][0m. Because we've done the equivalence, congruence, and refinement setup perfectly, our [47mRULE[0m will fire and we will get a break like this: (1 Breaking (:REWRITE RULE) on (BETA B): 1 ACL2 > The subsequent [47m:PATH+[0m command will show how the rewriter descended to here from the top-level goal and will display the geneqvs derived for each rewrite. 1 ACL2 >:path+ 1. Simplifying the clause ((P (F (G A (BETA B))))) 2. Rewriting (to simplify) the atom of the first literal, (P (F (G A (BETA B)))), Geneqv: (IFF) 3. Rewriting (to simplify) the first argument, (F (G A (BETA B))), Geneqv: ((PEQ PEQ-IMPLIES-IFF-P-1)) 4. Rewriting (to simplify) the first argument, (G A (BETA B)), Geneqv: ((FEQ FEQ-IMPLIES-PEQ-F-1)) 5. Rewriting (to simplify) the second argument, (BETA B), Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2) (G2EQ1 G2EQ1-IMPLIES-FEQ-G-2)) 6. Attempting to apply (:REWRITE RULE) to (BETA B) Preserving: G2EQ1! Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2) (G2EQ1 G2EQ1-IMPLIES-FEQ-G-2)) 1 ACL2 > Recall, from the discussion above, that sometimes geneqvs are printed merely as a list of equivalence relations, e.g., [47m(G2EQ2 G2EQ1)[0m, and other times, as above, are printed so as to include the name of the congruence relation responsible for each equivalence. Notice that in frame 4, where the rewriter is working on [47m(G A (BETA B))[0m it is to maintain the [47mFEQ[0m equivalence relation (which was justified from frame 3 by the rule [47mFEQ-IMPLIES-PEQ-F-1[0m where the rewriter was to maintain [47mPEQ[0m). But when the rewriter stepped from frame 4 to the second argument of [47m(G A (BETA B))[0m in frame 5, it used both [47mG2EQ1-IMPLIES-FEQ-G-2[0m and [47mG2EQ2-IMPLIES-FEQ-G-2[0m to derive the geneqv [47m(G2EQ2 G2EQ1)[0m. Then, when it attempted to apply [47mRULE[0m, whose equivalence relation is [47mG2EQ1![0m, it passed the refinement test because [47mG2EQ1![0m refines [47mG2EQ1[0m, which is one of the equivalences listed in the geneqv. When we proceed from the break, the proof completes successfully. But now imagine that we had failed to prove [47m(DEFREFINEMENT G2EQ1! G2EQ1)[0m. The [47mthm[0m command above would have caused this break: (1 Breaking (:REWRITE RULE) on (BETA B): The equivalence relation, G2EQ1!, of this rule is not a refinement of the current geneqv, (G2EQ2 G2EQ1). Use :path or :path+ to see how the geneqv evolved. See :DOC refinement-failure for advice about how to deal with this kind of problem. 1 ACL2 > The break header explains the problem: the rewriter does not know that [47mG2EQ1![0m refines [47mG2EQ1[0m or [47mG2EQ2[0m. Of course, [3mwe[0m do know that and the fix is simply to prove the ``forgotten'' [47m[defrefinement][0m. On the other hand, suppose we had proved the [47mdefrefinement[0m but had forgotten to prove that [47mFEQ[0m is maintained on a call of [47mG[0m when [47mG2EQ1[0m is maintained on the 2nd argument of [47mG[0m, i.e., [47m(DEFCONG G2EQ1 FEQ (G X Y) 2)[0m, aka [47mG2EQ1-IMPLIES-FEQ-G-2[0m. Then the [47mthm[0m command would produce the following break. (1 Breaking (:REWRITE RULE) on (BETA B): The equivalence relation, G2EQ1!, of this rule is not a refinement of the current geneqv, (G2EQ2). Use :path or :path+ to see how the geneqv evolved. See :DOC refinement-failure for advice about how to deal with this kind of problem. Note that the geneqv is printed in its simplest form, as a list of equivalence relation names; in this case only one name is included: [47mG2EQ2[0m. Of course, if we believed [47mG2EQ1![0m does refine [47mG2EQ2[0m, it would suffice to prove the corresponding refinement rule. But let's suppose we know [47mG2EQ1![0m doesn't refine [47mG2EQ2[0m. Instead, we know [47mG2EQ1![0m refines [47mG2EQ1[0m, which is not in the geneqv. Our problem then is to arrange for [47mG2EQ1[0m to be in the geneqv. Look at the path that got us here. 1 ACL2 >:path+ 1. Simplifying the clause ((P (F (G A (BETA B))))) 2. Rewriting (to simplify) the atom of the first literal, (P (F (G A (BETA B)))), Geneqv: (IFF) 3. Rewriting (to simplify) the first argument, (F (G A (BETA B))), Geneqv: ((PEQ PEQ-IMPLIES-IFF-P-1)) 4. Rewriting (to simplify) the first argument, (G A (BETA B)), Geneqv: ((FEQ FEQ-IMPLIES-PEQ-F-1)) 5. Rewriting (to simplify) the second argument, (BETA B), Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2)) 6. Attempting to apply (:REWRITE RULE) to (BETA B) Preserving: G2EQ1! Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2)) 1 ACL2 > In frame 4 we are to maintain [47mFEQ[0m on a call of [47mG[0m. In frame 5 we are rewriting the second argument of [47mG[0m and used [47mG2EQ2-IMPLIES-FEQ-G-2[0m to derive the new geneqv containing [47mG2EQ2[0m. We could get [47mG2EQ1[0m into that new geneqv is only we had a congruence rule that says [47mFEQ[0m is maintained on [47mG[0m when rewriting the second argument of [47mG[0m maintaining [47mG2EQ1[0m. That's just the ``forgotten'' [47m(DEFCONG G2EQ1 FEQ (G X Y) 2)[0m. Of course we could alternatively have chosen to prove [47m(DEFCONG G2EQ1! FEQ (G X Y) 2)[0m, but it is generally better to prove the strongest congruence rules we know. Finally, as documented in [refinement] and [congruence], refinement and congruence rules are not (always) tracked and usually do not show up in the [summary] printed at the end of proof attempts. The decision not to track every use of these rules was made to improve prover efficiency.") (regenerate-tau-database (events introduction-to-the-tau-system) "Regenerate the tau database relative to the current enabled theory General Form: (regenerate-tau-database) The tau database is regenerated by scanning the current logical world and re-processing every rule-generating event in it relative to the current enabled theory and current tau auto mode settings. See [introduction-to-the-tau-system] for background details. This command was intended to allow the user to remove a fact from the tau database, by regenerating the database without the fact. But as the following discussion highlights, [47mregenerate-tau-database[0m does not really solve the problem. We regard it as a placeholder for a more sophisticated mechanism. However, we have trouble understanding why a user might wish to remove a fact from the database and are awaiting further user experiences before designing the more sophisticated mechanism. Suppose, for example, that you wanted to remove a signature rule provided by some rule with name [3mrune[0m. You could disable [3mrune[0m and regenerate the database. We discuss why you might --- or might not --- want to do this later. But suppose you did it. Unfortunately, the database you get will not be just like the one you started with minus the signature rule. The reason is that the database you started with was generated incrementally and the current theory might have evolved. To take a simple example, your starting database might have included a rule that has been disabled since it was first added. Thus, the part of your starting database built before the disabling was constructed with the rule enabled and the part built afterwards has the rule disabled. You are unlikely to get the same database whether you enable or disable that rule now. You might hope that the avoidance of [47min-theory[0m events would eliminate the problem but it does not because even the [47m[ground-zero][0m theory is constructed incrementally from the ``pre-history'' commands used to boot up ACL2. Those pre-history commands include some global [47min-theory[0m commands. Since every session starts from the [47mground-zero[0m state, the starting database is already ``infected'' with global [47min-theory[0m commands. The reason we hope that it will not be necessary to remove tau facts is that the tau system is designed merely to be fast and benign (see [3mDesign Philosophy[0m in [introduction-to-the-tau-system]). The tau system's coverage should grows monotonically with the addition of rules. According to this understanding of tau, adding a signature rule, for example, may allow tau to prove some additional goals but will not prevent it from proving goals it could prove previously. If this is understanding of tau is accurate, we see no fundamental reason to support the removal of a fact. This, of course, ignores the possibility that the user wishes to explore alternative proof strategies or measure performance. We welcome user observations and experience on this issue.") (regression (pointers) "See [books-certification].") (release-notes (about-acl2) "Pointers to what has changed This section of the online [documentation] contains notes on the changes that distinguish successive released versions of ACL2. Each topic [47mnote-x-y[0m is a note describing what in ACL2 version X.Y was new in comparison to the preceding version of ACL2. The current version of ACL2 is the value of the constant [47m(@ acl2-version)[0m. Subtopics [Note-1-1] Acl2 Version 1.1 Notes [Note-1-2] Acl2 Version 1.2 Notes [Note-1-3] Acl2 Version 1.3 Notes [Note-1-4] Acl2 Version 1.4 Notes [Note-1-5] Acl2 Version 1.5 Notes [Note-1-6] Acl2 Version 1.6 Notes [Note-1-7] ACL2 Version 1.7 (released October 1994) Notes [Note-1-8] ACL2 Version 1.8 (May, 1995) Notes [Note-1-8-update] ACL2 Version 1.8 (Summer, 1995) Notes [Note-1-9] ACL2 Version 1.9 (Fall, 1996) Notes [Note-2-0] ACL2 Version 2.0 (July, 1997) Notes [Note-2-1] ACL2 Version 2.1 (December, 1997) Notes [Note-2-2] ACL2 Version 2.2 (August, 1998) Notes [Note-2-3] ACL2 Version 2.3 (October, 1998) Notes [Note-2-4] ACL2 Version 2.4 (August, 1999) Notes [Note-2-5] ACL2 Version 2.5 (June, 2000) Notes [Note-2-5{r}] ACL2 Version 2.5(r) (June, 2000) Notes [Note-2-6] ACL2 Version 2.6 (November, 2001) Notes [Note-2-6{r}] ACL2 Version 2.6(r) (November, 2001) Notes [Note-2-7] ACL2 Version 2.7 (November, 2002) Notes [Note-2-7{r}] ACL2 Version 2.7(r) (November, 2002) Notes [Note-2-8] ACL2 Version 2.8 (March, 2004) Notes [Note-2-8{r}] ACL2 Version 2.8(r) (March, 2003) Notes [Note-2-9] ACL2 Version 2.9 (October, 2004) Notes [Note-2-9{r}] ACL2 Version 2.9(r) (October, 2004) Notes [Note-2-9-1] ACL2 Version 2.9.1 (December, 2004) Notes [Note-2-9-2] ACL2 Version 2.9.2 (April, 2005) Notes [Note-2-9-3] ACL2 Version 2.9.3 (August, 2005) Notes [Note-2-9-4] ACL2 Version 2.9.4 (February, 2006) Notes [Note-2-9-5] Changes in Version 3.0 since Version 2.9.4 [Note-3-0] ACL2 Version 3.0 (June, 2006) Notes [Note-3-0{r}] ACL2 Version 3.0(r) (June, 2006) Notes [Note-3-0-1] ACL2 Version 3.0.1 (August, 2006) Notes [Note-3-0-1{r}] ACL2 Version 3.0.1(r) (August, 2006) Notes [Note-3-0-2] ACL2 Version 3.0.2 (December, 2006) Notes [Note-3-1] ACL2 Version 3.1 (December, 2006) Notes [Note-3-1{r}] ACL2 Version 3.1(r) (December, 2006) Notes [Note-3-2] ACL2 Version 3.2 (April, 2007) Notes [Note-3-2{r}] ACL2 Version 3.2(r) (April, 2007) Notes [Note-3-2-1] ACL2 Version 3.2.1 (June, 2007) Notes [Note-3-2-1{r}] ACL2 Version 3.2.1(r) (June, 2007) Notes [Note-3-3] ACL2 Version 3.3 (November, 2007) Notes [Note-3-3{r}] ACL2 Version 3.3(r) (November, 2007) Notes [Note-3-4] ACL2 Version 3.4 (August, 2008) Notes [Note-3-4{r}] ACL2 Version 3.4(r) (August, 2008) Notes [Note-3-5] ACL2 Version 3.5 (May, 2009) Notes [Note-3-5{r}] ACL2 Version 3.5(r) (May, 2009) Notes [Note-3-6] ACL2 Version 3.6 (August, 2009) Notes [Note-3-6{r}] ACL2 Version 3.6(r) (August, 2009) Notes [Note-3-6-1] ACL2 Version 3.6.1 (September, 2009) Notes [Note-4-0] ACL2 Version 4.0 (July, 2010) Notes [Note-4-0{r}] ACL2 Version 4.0(r) (July, 2010) Notes [Note-4-1] ACL2 Version 4.1 (September, 2010) Notes [Note-4-1{r}] ACL2 Version 4.1(r) (September, 2010) Notes [Note-4-2] ACL2 Version 4.2 (January, 2011) Notes [Note-4-2{r}] ACL2 Version 4.2(r) (January, 2011) Notes [Note-4-3] ACL2 Version 4.3 (July, 2011) Notes [Note-4-3{r}] ACL2 Version 4.3(r) (July, 2011) Notes [Note-5-0] ACL2 Version 5.0 (August, 2012) Notes [Note-6-0] ACL2 Version 6.0 (December, 2012) Notes [Note-6-1] ACL2 Version 6.1 (February, 2013) Notes [Note-6-2] ACL2 Version 6.2 (June, 2013) Notes [Note-6-3] ACL2 Version 6.3 (October, 2013) Notes [Note-6-4] ACL2 Version 6.4 (January, 2014) Notes [Note-6-5] ACL2 Version 6.5 (August, 2014) Notes [Note-7-0] ACL2 Version 7.0 (January, 2015) Notes [Note-7-1] ACL2 Version 7.1 (May, 2015) Notes [Note-7-2] ACL2 Version 7.2 (January, 2016) Notes [Note-7-3] ACL2 Version 7.3 (December, 2016) Notes [Note-7-4] ACL2 Version 7.4 (March, 2017) Notes [Note-8-0] ACL2 Version 8.0 (December, 2017) Notes [Note-8-1] ACL2 Version 8.1 (September, 2018) Notes [Note-8-2] ACL2 Version 8.2 (May, 2019) Notes [Note-8-3] ACL2 Version 8.3 (April, 2020) Notes [Note-8-4] ACL2 Version 8.4 (August, 2021) Notes [Note-8-5] ACL2 Version 8.5 (July, 2022) Notes [Note-8-6] ACL2 Version 8.6 (October, 2024) Notes [Note-8-7] ACL2 Version 8.7 (xxx, 20xx) Notes") (releases (about-acl2) "ACL2 releases The current ACL2 release on the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/index.html} is Version 8.6; see [note-8-6] for release notes. Below is a list of past releases and their corresponding past ACL2 home pages. (Note: Some older versions of the manuals have been made unreadable to avoid potential security issues.) * {Version 8.5 (July, 2022) | http://www.cs.utexas.edu/users/moore/acl2/v8-5/index.html} * {Version 8.4 (August, 2021) | http://www.cs.utexas.edu/users/moore/acl2/v8-4/index.html} * {Version 8.3 (April, 2020) | http://www.cs.utexas.edu/users/moore/acl2/v8-3/index.html} * {Version 8.2 (May, 2019) | http://www.cs.utexas.edu/users/moore/acl2/v8-2/index.html} * {Version 8.1 (September, 2018) | http://www.cs.utexas.edu/users/moore/acl2/v8-1/index.html} * {Version 8.0 (December, 2017) | http://www.cs.utexas.edu/users/moore/acl2/v8-0/index.html} * {Version 7.4 (March, 2017) | http://www.cs.utexas.edu/users/moore/acl2/v7-4/index.html} * {Version 7.3 (December, 2016) | http://www.cs.utexas.edu/users/moore/acl2/v7-3/index.html} * {Version 7.2 (January, 2016) | http://www.cs.utexas.edu/users/moore/acl2/v7-2/index.html} * {Version 7.1 (May, 2015) | http://www.cs.utexas.edu/users/moore/acl2/v7-1/index.html} * {Version 7.0 (January, 2015) | http://www.cs.utexas.edu/users/moore/acl2/v7-0/index.html} * {Version 6.5 (August, 2014) | http://www.cs.utexas.edu/users/moore/acl2/v6-5/index.html} * {Version 6.4 (January, 2014) | http://www.cs.utexas.edu/users/moore/acl2/v6-4/index.html} * {Version 6.3 (October, 2013) | http://www.cs.utexas.edu/users/moore/acl2/v6-3/index.html} * {Version 6.2 (June, 2013) | http://www.cs.utexas.edu/users/moore/acl2/v6-2/index.html} * {Version 6.1 (February, 2013) | http://www.cs.utexas.edu/users/moore/acl2/v6-1/index.html} * {Version 6.0 (December, 2012) | http://www.cs.utexas.edu/users/moore/acl2/v6-0/index.html} * {Version 5.0 (August, 2012) | http://www.cs.utexas.edu/users/moore/acl2/v5-0/index.html} * {Version 4.3 (July, 2011) | http://www.cs.utexas.edu/users/moore/acl2/v4-3/index.html} * {Version 4.2 (January, 2011) | http://www.cs.utexas.edu/users/moore/acl2/v4-2/index.html} * {Version 4.1 (September, 2010) | http://www.cs.utexas.edu/users/moore/acl2/v4-1/index.html} * {Version 4.0 (July, 2010) | http://www.cs.utexas.edu/users/moore/acl2/v4-0/index.html} * {Version 3.6.1 (September, 2009) | http://www.cs.utexas.edu/users/moore/acl2/v3-6/new/v3-6-1/index.html} * {Version 3.6 (August, 2009) | http://www.cs.utexas.edu/users/moore/acl2/v3-6/index.html} * {Version 3.5 (May, 2009) | http://www.cs.utexas.edu/users/moore/acl2/v3-5/index.html} * {Version 3.4 (August, 2008) | http://www.cs.utexas.edu/users/moore/acl2/v3-4/index.html} * {Version 3.3 (November, 2007) | http://www.cs.utexas.edu/users/moore/acl2/v3-3/index.html} * {Version 3.2.1 (June, 2007) | http://www.cs.utexas.edu/users/moore/acl2/v3-2/new/v3-2-1/index.html} * {Version 3.2 (April, 2007) | http://www.cs.utexas.edu/users/moore/acl2/v3-2/index.html} * {Version 3.1 (December, 2006) | http://www.cs.utexas.edu/users/moore/acl2/v3-1/index.html} * {Version 3.0.1 (August, 2006) | http://www.cs.utexas.edu/users/moore/acl2/v3-0/new/v3-0-1/index.html} * {Version 3.0 (June, 2006) | http://www.cs.utexas.edu/users/moore/acl2/v3-0/index.html} * {Version 2.9.4 (January, 2006) | http://www.cs.utexas.edu/users/moore/acl2/v2-9/new/v2-9-4/index.html} * {Version 2.9.3 (August, 2005) | http://www.cs.utexas.edu/users/moore/acl2/v2-9/new/v2-9-3/index.html} * {Version 2.9.2 (April, 2005) | http://www.cs.utexas.edu/users/moore/acl2/v2-9/new/v2-9-2/index.html} * {Version 2.9.1 (December, 2004) | http://www.cs.utexas.edu/users/moore/acl2/v2-9/new/v2-9-1/index.html} * {Version 2.9 (October, 2004) | http://www.cs.utexas.edu/users/moore/acl2/v2-9/index.html} * {Version 2.8 (March, 2004) | http://www.cs.utexas.edu/users/moore/acl2/v2-8/index.html} * {Version 2.7 (November, 2002) | http://www.cs.utexas.edu/users/moore/acl2/v2-7/index.html} * {Version 2.6 (November, 2001) | http://www.cs.utexas.edu/users/moore/acl2/v2-6/index.html} * {Version 2.5 (June, 2000) | http://www.cs.utexas.edu/users/moore/acl2/v2-5/index.html} * {Version 2.4 (August, 1999) | http://www.cs.utexas.edu/users/moore/acl2/v2-4/index.html} * {Version 2.3 (October, 1998) | http://www.cs.utexas.edu/users/moore/acl2/v2-3/index.html} * {Version 2.2 (August, 1998) | http://www.cs.utexas.edu/users/moore/acl2/v2-2/index.html} * {Version 2.1 (December, 1997) | http://www.cs.utexas.edu/users/moore/acl2/v2-1/index.html} * {Version 2.0 (July, 1997) | http://www.cs.utexas.edu/users/moore/acl2/v2-0/index.html} * {Version 1.9 (Fall, 1996) | http://www.cs.utexas.edu/users/moore/acl2/v1-9/acl2-doc.html} [31;1mNote[0m: The ACL2 Home Pages for versions between 5.0 and 7.0, listed above, did not directly include the Community Books, which were distributed separately. You may find the books for those versions at [47m{http://acl2.org/books-pre-7.0/ | http://acl2.org/books-pre-7.0/}[0m.") (rem (numbers acl2-built-ins) "Remainder using [47m[truncate][0m ACL2 !>(rem 14 3) 2 ACL2 !>(rem -14 3) -2 ACL2 !>(rem 14 -3) 2 ACL2 !>(rem -14 -3) -2 ACL2 !>(rem -15 -3) 0 ACL2 !> [47m(Rem i j)[0m is that number [47mk[0m for which [47m(* j (truncate i j))[0m added to [47mk[0m equals [47mi[0m. The [guard] for [47m(rem i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real], in ACL2(r)) numbers and [47mj[0m is non-zero. [47mRem[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<rem> (defun rem (x y) (declare (xargs :guard (and (real/rationalp x) (real/rationalp y) (not (eql y 0))))) (- x (* (truncate x y) y)))") (remove (lists acl2-built-ins) "Remove all occurrences General Forms: (remove x lst) (remove x lst :test 'eql) ; same as above (eql as equality test) (remove x lst :test 'eq) ; same, but eq is equality test (remove x lst :test 'equal) ; same, but equal is equality test [47m(Remove x lst)[0m is equal to [47mlst[0m if [47mx[0m is not a member of [47mlst[0m, else is the result of removing all occurrences of [47mx[0m from [47mlst[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements of [47mlst[0m. Also see [remove1]. The [guard] for a call of [47mremove[0m depends on the test. In all cases, the second argument must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mremove[0m and its variants: [47m(remove-eq x lst)[0m is equivalent to [47m(remove x lst :test 'eq)[0m; [47m(remove-equal x lst)[0m is equivalent to [47m(remove x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mremove-equal[0m. [31;1mFunction: [0m<remove-equal> (defun remove-equal (x l) (declare (xargs :guard (true-listp l))) (cond ((endp l) nil) ((equal x (car l)) (remove-equal x (cdr l))) (t (cons (car l) (remove-equal x (cdr l)))))) [47mRemove[0m is defined by Common Lisp. See any Common Lisp documentation for more information.") (remove-assoc (alists acl2-built-ins) "Remove all pairs with a given key from an association list General Forms: (remove-assoc key alist) (remove-assoc key alist :test 'eql) ; same as above (eql as equality test) (remove-assoc key alist :test 'eq) ; same, but eq is equality test (remove-assoc key alist :test 'equal) ; same, but equal is equality test [47m(Remove-assoc key alist)[0m returns an alist that is the same as the list [47malist[0m, except that all pairs in [47malist[0m with a [47m[car][0m of [47mkey[0m are deleted (if any; otherwise [47malist[0m is returned). Note that the order of the elements of [47malist[0m is unchanged (though some may be deleted). Also see [remove1-assoc] for a similar utility that deletes only the first pair in an alist with a given key, rather than all such pairs. The [guard] for a call of [47mremove-assoc[0m depends on the test. In all cases, the second argument must satisfy [47m[alistp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-alistp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-alistp][0m. See [equality-variants] for a discussion of the relation between [47mremove-assoc[0m and its variants: [47m(remove-assoc-eq key alist)[0m is equivalent to [47m(remove-assoc key alist :test 'eq)[0m; [47m(remove-assoc-equal key alist)[0m is equivalent to [47m(remove-assoc key alist :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mremove-assoc-equal[0m. [31;1mFunction: [0m<remove-assoc-equal> (defun remove-assoc-equal (x alist) (declare (xargs :guard (alistp alist))) (cond ((endp alist) nil) ((equal x (car (car alist))) (remove-assoc-equal x (cdr alist))) (t (cons (car alist) (remove-assoc-equal x (cdr alist))))))") (remove-assoc-eq (pointers) "See [remove-assoc].") (remove-assoc-equal (pointers) "See [remove-assoc].") (remove-binop (macros) "Remove the association of a function name with a macro name The form [47m(remove-binop macro-fn)[0m is an abbreviation for the form [47m(remove-macro-fn macro-fn)[0m. See [remove-macro-fn].") (remove-custom-keyword-hint (events) "Remove a custom keyword hint Example Forms: (remove-custom-keyword-hint :my-hint) General Form: (remove-custom-keyword-hint keyword) where [47mkeyword[0m is a [47m[keywordp][0m. For an explanation of how custom keyword hints are processed, see [custom-keyword-hints]; also see [add-custom-keyword-hint]. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded.") (remove-default-hints (default-hints) "Remove from the default hints Examples: (remove-default-hints '((computed-hint-1 clause) (computed-hint-2 clause stable-under-simplificationp))) Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs (see [remove-default-hints!] for a corresponding non-[47m[local][0m event). General Form: (remove-default-hints lst) where [47mlst[0m is a list. Generally speaking, the elements of [47mlst[0m should be suitable for use as [47m[computed-hints][0m. Also see [add-default-hints]. If some elements of the given list do not belong to the existing default hints, they will simply be ignored by this event. Also See [set-default-hints], see [add-default-hints], and see [default-hints]. Finally, note that the effects of [47mset-default-hints[0m, [47m[add-default-hints][0m, and [47m[remove-default-hints][0m are [47m[local][0m to the book in which they appear. Thus, users who include a book with such forms will not have their default hints affected by such forms. In order to export the effect of setting the default hints, use [47m[set-default-hints!][0m, [47m[add-default-hints!][0m, or [47m[remove-default-hints!][0m.") (remove-default-hints! (default-hints) "Remove from the default hints non-[47m[local][0mly Please see [remove-default-hints], which is the same as [47mremove-default-hints![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [remove-default-hints] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (remove-dive-into-macro (dive-into-macros-table) "Removes association of [proof-builder] diving function with macro name Example: (remove-dive-into-macro logand) This feature undoes the effect of [47m[add-dive-into-macro][0m, which is used so that the interactive [proof-builder]'s [47mDV[0m command and numeric diving commands (e.g., [47m3[0m) will dive properly into subterms. Please see [add-dive-into-macro] and especially see [dive-into-macros-table].") (remove-duplicates (lists strings acl2-built-ins) "Remove duplicates from a string or a list General Forms: (remove-duplicates x) (remove-duplicates x :test 'eql) ; same as above (eql as equality test) (remove-duplicates x :test 'eq) ; same, but eq is equality test (remove-duplicates x :test 'equal) ; same, but equal is equality test [47m(Remove-duplicates x)[0m returns the result of deleting duplicate elements from the beginning of the list or string [47mx[0m. For example, [47m(remove-duplicates '(1 2 3 2 4))[0m is equal to [47m'(1 3 2 4)[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements of [47mlst[0m. The [guard] for a call of [47mremove-duplicates[0m depends on the test. In all cases, the argument must satisfy [47m[stringp][0m or [47m[true-listp][0m. If the test is [47m[eql][0m, then the argument must satisfy either [47m[stringp][0m or [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then the argument must satisfy [47m[symbol-listp][0m. The relation between [47mremove-duplicates[0m and its variants is related to the usual pattern for equality variants; see [equality-variants]. However, the possibility of a string argument changes the usual pattern a bit. As one might expect: [47m(remove-duplicates-eq lst)[0m is equivalent to [47m(remove-duplicates lst :test 'eq)[0m. However, [47mremove-duplicates-equal[0m is defined without consideration of strings, for backward compatibility with versions of ACL2 through Version_4.2. The macro [47mremove-duplicates-logic[0m has been introduced to model the behavior of [47mremove-duplicates[0m even on strings; use [47m:[0m[47m[pe][0m if you wish to see its definition. So we can say the following. [47m(remove-duplicates-logic lst)[0m is equivalent to [47m(remove-duplicates lst :test 'equal)[0m; and [47m(remove-duplicates-logic lst)[0m is equal to [47m(remove-duplicates-equal lst)[0m when [47mlst[0m is not a string. In particular, when the argument is not a string, reasoning about any of these primitives reduces to reasoning about the function [47mremove-duplicates-equal[0m. [31;1mFunction: [0m<remove-duplicates-equal> (defun remove-duplicates-equal (l) (declare (xargs :guard (true-listp l))) (cond ((endp l) nil) ((member-equal (car l) (cdr l)) (remove-duplicates-equal (cdr l))) (t (cons-with-hint (car l) (remove-duplicates-equal (cdr l)) l)))) [47mRemove-duplicates[0m is defined by Common Lisp. See any Common Lisp documentation for more information.") (remove-duplicates-eq (pointers) "See [remove-duplicates].") (remove-duplicates-equal (pointers) "See [remove-duplicates].") (remove-eq (pointers) "See [remove].") (remove-equal (pointers) "See [remove].") (remove-global-stobj (events stobj) "Remove a global [stobj] with a given name See [47m[add-global-stobj][0m for relevant background and terminology together with an explanation of [47mremove-global-stobj[0m. Here we give only a brief summary. General Form: (remove-global-stobj x state) where [47mx[0m evaluates to the name of a stobj that has a global value. Example Form: (remove-global-stobj 'st state)") (remove-guard-holders (pointers) "See [guard-holders].") (remove-invisible-fns (loop-stopper) "Make some unary functions no longer invisible Examples: (remove-invisible-fns binary-+ unary-- foo) (remove-invisible-fns + unary-- foo) The setting above has makes unary functions [47m[unary--][0m and [47mfoo[0m no longer ``invisible'' for the purposes of applying permutative [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees. General Form: (remove-invisible-fns top-fn unary-fn1 ... unary-fnk) where [47mtop-fn[0m is a function symbol and the [47munary-fni[0m are unary function symbols, or more generally, these are all macro aliases for such function symbols (see [macro-aliases-table]). See [add-invisible-fns] and also see [invisible-fns-table] and see [set-invisible-fns-table].") (remove-macro-alias (macros) "Remove the association of a function name with a macro name Example: (remove-macro-alias append) General Form: (remove-macro-alias macro-name) See [macro-aliases-table] for a discussion of macro aliases; also see [add-macro-alias]. This form sets [47m[macro-aliases-table][0m to the result of deleting the key [47mmacro-name[0m from that [table]. If the name does not occur in the [table], then this form still generates an event, but the event has no real effect.") (remove-macro-fn (macros) "Remove the association of a function name with a macro name Example: (remove-macro-fn binary-append) General Form: (remove-macro-fn macro-fn) See [add-macro-fn] for a discussion of how to associate a macro name with a function name. This form sets [47m[untrans-table][0m to the result of deleting the association of a macro name with the given binary function name. If the function name has no such association, then this form still generates an event, but the event has no real effect.") (remove-nth-alias (nth-aliases-table) "Remove a symbol alias for printing of [47m[nth][0m/[47m[update-nth][0m terms Example: (remove-nth-alias append) General Form: (remove-nth-alias alias-name) See [nth-aliases-table] for further discussion; also see [add-nth-alias]. This form sets [47m[nth-aliases-table][0m to the result of deleting the key [47malias-name[0m from that [table]. If the name does not occur in the [table], then this form still generates an event, but the event has no real effect.") (remove-override-hints (override-hints) "Delete from the list of [override-hints] See [override-hints] for a discussion of override-hints. Here we describe how to delete from the list of override-hints. Note that the effects of [47mremove-override-hints[0m [events] are [local] to the [books] or [47mencapsulate[0m [events] in which they reside; see [remove-override-hints!] to avoid that restriction. Also see [add-override-hints] and see [set-override-hints]. General Form: (remove-override-hints form) where [47mform[0m should evaluate to a list of computed hint forms. The effect of this event is to set the list of [override-hints] to the result of deleting each element of the evaluation result from the [override-hints], if that element indeed belongs to the override-hints; no check is made that these elements are actually elements of the existing override-hints.") (remove-override-hints! (override-hints) "Delete non-[local]ly from the list of [override-hints] [47mRemove-override-hints![0m is the same as [47m[remove-override-hints][0m, except that the former is not [local] to [books] or [47m[encapsulate][0m [events] in which it occurs. See [remove-override-hints]; also see [add-override-hints] and see [set-override-hints].") (remove-trivial-equivalences-enabled-p (rewrite system-attachments) "Avoid removal of trivial equivalences during rewriting This topic concerns an advanced control for the ACL2 prover. This zero-ary attachable system function controls the ``remove-trivial-equivalences'' heuristic, which uses an equality hypothesis (and, when appropriate, an [equivalence] hypothesis) to replace a variable by a term in the rest of the goal. (However, perhaps similar heuristics will still be used, for example as part of the [tau-system].) Attach the function [47mconstant-nil-function-arity-0[0m to avoid this heuristic, and attach the function [47mconstant-t-function-arity-0[0m to restore it.") (remove-untouchable (defttag) "Remove names from lists of untouchable symbols Untouchables are functions that cannot be called or as [state] global variables (see [programming-with-state]) that cannot be modified or unbound. Example Forms: (remove-untouchable my-var nil) ; then state global my-var is not untouchable (remove-untouchable set-mem t) ; then function set-mem is not untouchable Also see [push-untouchable]. This documentation topic is directed at those who build systems on top of ACL2. We first describe a means for modifying [state] to remove some untouchables. Then we describe the [47mremove-untouchable[0m event. Both require an active trust tag (see [defttag]). We begin by discussing untouchable state global variables [47mtemp-touchable-vars[0m and [47mtemp-touchable-fns[0m, which initially have value [47mnil[0m. These can often be used in place of [47mremove-untouchable[0m. When the value is [47mt[0m, no variable (respectively, no function or macro) is treated as untouchable, regardless of the set of initial untouchables or the [47mremove-untouchable[0m or [47m[push-untouchable][0m [events] that have been admitted. Otherwise the value of each of these two variables is a [47m[symbol-listp][0m, and no member of this list is treated as an untouchable variable (in the case of [47mtemp-touchable-vars[0m) or as an untouchable function or macro (in the case of [47mtemp-touchable-fns[0m). These two state global variables can be set by [47mset-temp-touchable-vars[0m and [47mset-temp-touchable-fns[0m, respectively, provided there is an active trust tag (see [defttag]). Here is an illustrative example. This macro executes the indicated forms in a context where there are no untouchable variables, but requires an active trust tag when invoked. (defmacro with-all-touchable (&rest forms) `(progn! :state-global-bindings ((temp-touchable-vars t set-temp-touchable-vars)) (progn! ,@forms))) An equivalent version, which however is not recommended since [47m[state-global-let*][0m may have surprising behavior in raw Lisp, is as follows. (defmacro with-all-touchable (&rest forms) `(progn! (state-global-let* ((temp-touchable-vars t set-temp-touchable-vars)) (progn! ,@forms)))) Finally, the value [47mt[0m for [47mtemp-touchable-vars[0m removes the requirement that built-in state globals cannot be made unbound (with [47mmakunbound-global[0m). We now turn to the [47mremove-untouchable[0m event, in case the approach above is for some reason not adequate. This event is illegal by default, since it can be used to provide access to ACL2 internal functions and data structures that are intentionally made untouchable for the user. If you want to call it, you must first create an active trust tag; see [defttag]. General Form: (remove-untouchable name{s} fn-p) where [47mname{s}[0m is a non-[47mnil[0m symbol or a non-[47mnil[0m true list of symbols, and [47mfn-p[0m is any value (but generally [47mnil[0m or [47mt[0m). If [47mname{s}[0m is a symbol it is treated as the singleton list containing that symbol. The effect of this event is to remove the given symbols from the list of ``untouchable variables'' in the current world if [47mfn-p[0m is [47mnil[0m, else to remove the symbols into the list of ``untouchable functions''. This event is redundant if no symbol listed is a member of the appropriate untouchables list (variables or functions).") (remove1 (lists acl2-built-ins) "Remove first occurrences, testing using [47m[eql][0m General Forms: (remove1 x lst) (remove1 x lst :test 'eql) ; same as above (eql as equality test) (remove1 x lst :test 'eq) ; same, but eq is equality test (remove1 x lst :test 'equal) ; same, but equal is equality test [47m(Remove1 x lst)[0m is equal to [47mlst[0m if [47mx[0m is not a member of [47mlst[0m, else is the result of removing the first occurrences of [47mx[0m from [47mlst[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements of [47mlst[0m. Also see [remove]. The [guard] for a call of [47mremove1[0m depends on the test. In all cases, the second argument must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mremove1[0m and its variants: [47m(remove1-eq x lst)[0m is equivalent to [47m(remove1 x lst :test 'eq)[0m; [47m(remove1-equal x lst)[0m is equivalent to [47m(remove1 x lst :test 'equal)[0m. [31;1mFunction: [0m<remove1-equal> (defun remove1-equal (x l) (declare (xargs :guard (true-listp l))) (cond ((endp l) nil) ((equal x (car l)) (cdr l)) (t (cons-with-hint (car l) (remove1-equal x (cdr l)) l)))) In particular, reasoning about any of these primitives reduces to reasoning about the function [47mremove1-equal[0m.") (remove1-assoc (alists acl2-built-ins) "Remove the first pair with a given key from an association list General Forms: (remove1-assoc key alist) (remove1-assoc key alist :test 'eql) ; same as above (eql as equality test) (remove1-assoc key alist :test 'eq) ; same, but eq is equality test (remove1-assoc key alist :test 'equal) ; same, but equal is equality test [47m(Remove1-assoc key alist)[0m returns an alist that is the same as the list [47malist[0m, except that the first pair in [47malist[0m with a [47m[car][0m of [47mkey[0m is deleted, if there is one; otherwise [47malist[0m is returned. Note that the order of the elements of [47malist[0m is unchanged (though one may be deleted). Also see [remove-assoc] for a similar utility that deletes all pairs in an alist with a given key, rather than only the first such pair. The [guard] for a call of [47mremove1-assoc[0m depends on the test. In all cases, the second argument must satisfy [47m[alistp][0m. If the test is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m (see [eqlablep]) or the second argument must satisfy [47m[eqlable-alistp][0m. If the test is [47m[eq][0m, then either the first argument must be a symbol or the second argument must satisfy [47m[symbol-alistp][0m. See [equality-variants] for a discussion of the relation between [47mremove1-assoc[0m and its variants: [47m(remove1-assoc-eq key alist)[0m is equivalent to [47m(remove1-assoc key alist :test 'eq)[0m; [47m(remove1-assoc-equal key alist)[0m is equivalent to [47m(remove1-assoc key alist :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mremove1-assoc-equal[0m. [31;1mFunction: [0m<remove1-assoc-equal> (defun remove1-assoc-equal (key alist) (declare (xargs :guard (alistp alist))) (cond ((endp alist) nil) ((equal key (caar alist)) (cdr alist)) (t (cons (car alist) (remove1-assoc-equal key (cdr alist))))))") (remove1-assoc-eq (pointers) "See [remove1-assoc].") (remove1-assoc-equal (pointers) "See [remove1-assoc].") (remove1-eq (pointers) "See [remove1].") (remove1-equal (pointers) "See [remove1].") (reorder (pointers) "See [hints] for information about the keyword [47m:reorder[0m.") (reset-fc-reporting (forward-chaining-reports) "Reset the forward-chaining tracking state to its initial configuration Example: (reset-fc-reporting) This function erases all forward chaining tracking criteria and sets the on-the-fly reporting flag to [47mnil.[0m The next time you set the criteria (see [set-fc-criteria]) the short form of reports, in which only the caller and the fc-report number is printed, will appear in your proof logs. See [forward-chaining-reports] for details.") (reset-kill-ring (history) "Save memory by resetting and perhaps resizing the kill ring used by [47m[oops][0m By default, ACL2 holds on to old logical [world]s when you undo [command]s (see [ubt]), as documented elsewhere; see [oops]. You can free up memory by deleting those old worlds using [47mreset-kill-ring[0m. Examples: (reset-kill-ring t state) ; replace each element of the kill ring by nil (reset-kill-ring 2 state) ; create a new kill ring of '(nil nil) (reset-kill-ring 0 state) ; create a new kill ring that is empty (reset-kill-ring nil state) ; just return the length of the kill ring General form: (reset-kill-ring n state) where [47mn[0m evaluates either to [47mt[0m, to [47mnil[0m, or to a nonnegative integer (a [47m[natp][0m). If [47mn[0m evaluates to [47mt[0m, it is treated as the length of the current kill ring. If [47mn[0m is [47mnil[0m, then the length [47mk[0m of the current kill ring is returned as a value triple [47m(mv nil k state)[0m. If [47mn[0m is a [47m[natp][0m, then the kill ring is replaced with a list of [47mn[0m [47mnil[0ms. In particular, use [47m(reset-kill-ring 0 state)[0m to avoid saving any old logical [world]s, at the cost of disabling the effect of the [47m[oops][0m [command].") (reset-ld-specials (ld) "Restores initial settings of the [47m[ld][0m specials Examples: (reset-ld-specials t) (reset-ld-specials nil) Roughly speaking, the [47m[ld][0m specials are certain [state] global variables, such as [47m[ld-prompt][0m and [47m[ld-pre-eval-filter][0m, which are managed by [47m[ld][0m as though they were local variables. These variables determine the channels on which [47m[ld][0m reads and prints and control many options of [47m[ld][0m. See [ld] for the details on what the [47m[ld][0m specials are. This function, [47mreset-ld-specials[0m, takes one Boolean argument, [47mflg[0m. The function resets all of the [47m[ld][0m specials to their initial, top-level values, except for the three channel variables, [47m[standard-oi][0m, [47m[standard-co][0m, and [47m[proofs-co][0m, which are reset to their initial values only if [47mflg[0m is non-[47mnil[0m. Of course, if you are in a recursive call of [47m[ld][0m, then when you exit that call, the [47m[ld][0m specials will be restored to the values they had at the time [47m[ld][0m was called recursively. To see what the initial values are, inspect the value of the constant [47m*initial-ld-special-bindings*[0m.") (reset-prehistory (history) "Reset the prehistory Examples: (reset-prehistory) ; restart command numbering at 0 (reset-prehistory nil) ; same as above (reset-prehistory t) ; as above except also disable ubt-prehistory General Forms: (reset-prehistory) (reset-prehistory permanent-p) where [47mpermanent-p[0m is [47mt[0m or [47mnil[0m. After execution of this command, ACL2 will change the numbering provided by its [history] utilities so that this [47mreset-prehistory[0m command (or the top-level compound [command] containing it, which for example might be an [47m[include-book][0m) is assigned the number 0. The only way to undo this command is with command [47m[ubt-prehistory][0m. However, even that is disallowed if [47mpermanent-p[0m is [47mt[0m. Note that the second argument of [47m[certify-book][0m, which specifies the number of commands in the certification world (i.e., since ground-zero), is not sensitive to [47mreset-prehistory[0m; rather, it expects the number of commands since ground-zero. To see such commands, [47m:[0m[47m[pbt][0m[47m :start[0m. A [47mreset-prehistory[0m event for which parameter [47mpermanent-p[0m has the default value of [47mnil[0m is always skipped when any of the following conditions holds: during [47m[certify-book][0m; during [47m[include-book][0m or the second pass of [47m[encapsulate][0m (indeed, whenever [ld] special [47m'[0m[47m[ld-skip-proofsp][0m has value [47m'include-book[0m); or when [47mstate[0m global [47m'skip-reset-prehistory[0m has a non-[47mnil[0m value. Thus, we avoid resetting the history numbering to 0 when including or certifying a book, since that would probably not be what was intended. See [ubt-prehistory] for how to undo a [47mreset-prehistory[0m command that does not have a [47mpermanent-p[0m of [47mt[0m. See [disable-ubt] for a variant of [47m(reset-prehistory t)[0m that does not change command numbering and is used by the [break-rewrite] utility. Like [47mdisable-ubt[0m, [47mreset-prehistory[0m is never [redundant].") (reset-print-control (pointers) "See [print-control].") (resize-list (stobj acl2-built-ins) "List resizer in support of [stobj]s [47m(Resize-list lst n default-value)[0m takes a list, [47mlst[0m, and a desired length, [47mn[0m, for the result list, as well as a [47mdefault-value[0m to use for the extra elements if [47mn[0m is greater than the length of [47mlst[0m. [47mResize-list[0m has a guard of [47mt[0m. This function is called in the body of function, [47mresize-<a>[0m where [47m<a>[0m is an array field of a [stobj]. See [defstobj]. [31;1mFunction: [0m<resize-list-exec> (defun resize-list-exec (lst n default-value acc) (declare (xargs :guard (true-listp acc))) (if (and (integerp n) (> n 0)) (resize-list-exec (if (atom lst) lst (cdr lst)) (1- n) default-value (cons (if (atom lst) default-value (car lst)) acc)) (reverse acc))) [31;1mFunction: [0m<resize-list> (defun resize-list (lst n default-value) (declare (xargs :guard t)) (mbe :logic (if (and (integerp n) (> n 0)) (cons (if (atom lst) default-value (car lst)) (resize-list (if (atom lst) lst (cdr lst)) (1- n) default-value)) nil) :exec (resize-list-exec lst n default-value nil)))") (rest (nth acl2-built-ins) "Rest ([47m[cdr][0m) of the list In the logic, [47mrest[0m is just a macro for [47m[cdr][0m. [47mRest[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mMacro: [0m<rest> (defmacro rest (x) (list 'cdr x))") (restore-memoization-settings (memoize) "Restore the saved memoization settings For background on memoization, see [memoize]. General Form: (restore-memoization-settings) Calls of this macro restore the memoization settings saved by [47m[save-and-clear-memoization-settings][0m.") (restrict (pointers) "See [hints] for information about the keyword [47m:restrict[0m.") (retract-world (world) "Install an initial segment (retraction) of a given ACL2 [world] See [world] for relevant background on ACL2 property list worlds. Here we discuss how to install an initial segment (retraction) of a user-defined world, that is, a world other than the one named [47m'current-acl2-world[0m, which is maintained by the ACL2 system. Also see [extend-world] for a similar utility that instead extends a named world. General Form: (retract-world name wrld) where [47mname[0m is a symbol intended to name the given ACL2 property list world, [47mworld[0m. Consider the following example. ACL2 !>(let* ((wrld0 nil) (wrld1 (putprop 'my-sym1 'my-key1 'my-val1-old wrld0)) (wrld2 (putprop 'my-sym2 'my-key2 'my-val2 wrld1)) (wrld3 (putprop 'my-sym1 'my-key1 'my-val1 wrld2))) (pprogn (f-put-global 'my-w1 wrld1 state) (f-put-global 'my-w3 (extend-world 'my-world wrld3) state))) <state> ACL2 !>(retract-world 'my-world (@ my-w1)) ((MY-SYM1 MY-KEY1 . MY-VAL1-OLD)) ACL2 !>(getprop 'my-sym1 'my-key1 nil 'my-world (@ my-w1)) MY-VAL1-OLD ACL2 !> The first top-level form sets the values of [47m[state][0m globals [47mmy-w1[0m and [47mmy-w3[0m to the worlds obtained by extending the empty world one or three times, respectively, as shown. The second top-level form [3minstalls[0m the value of [47mmy-w1[0m as the world that is current for the name [47m'my-world[0m. The third top-level form returns the [47m'my-key1[0m property for the symbol [47m'my-sym1[0m in the installed world [47m(@ my-w1)[0m, and it does so efficiently because that world is installed. See [world].") (retrieve (proof-builder) "Re-enter a (specified) [proof-builder] state Examples: (retrieve associativity-of-permutationp) retrieve General Form: (retrieve &optional name) See [ACL2-pc::retrieve], or use [47m(help retrieve)[0m inside the interactive [proof-builder] loop. Also see [unsave].") (return-last (basics acl2-built-ins) "Return the last argument, perhaps with side effects [47mReturn-last[0m is an ACL2 function that returns its last argument. It is used to implement common utilities such as [47m[prog2$][0m and [47m[time$][0m. For most users, this may already be more than one needs to know about [47mreturn-last[0m; for example, ACL2 tends to avoid printing calls of [47mreturn-last[0m in its output, printing calls of [47m[prog2$][0m or [47m[time$][0m (or other such utilities) instead. If you encounter a call of [47mreturn-last[0m during a proof, then you may find it most useful to consider [47mreturn-last[0m simply as a function defined by the following equation. (equal (return-last x y z) z) It may also be useful to know that unlike other ACL2 functions, [47mreturn-last[0m can take a multiple value as its last argument, in which case this multiple value is returned. The following contrived definition illustrates this point. ACL2 !>(defun foo (fn x y z) (return-last fn x (mv y z))) Since FOO is non-recursive, its admission is trivial. We observe that the type of FOO is described by the theorem (AND (CONSP (FOO FN X Y Z)) (TRUE-LISTP (FOO FN X Y Z))). We used primitive type reasoning. (FOO * * * *) => (MV * *). Summary Form: ( DEFUN FOO ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) FOO ACL2 !>(foo 'bar 3 4 5) (4 5) ACL2 !>(mv-let (a b) (foo 'bar 3 4 5) (cons b a)) (5 . 4) ACL2 !> Most readers would be well served to avoid reading the rest of this documentation of [47mreturn-last[0m. For reference, however, below we document it in some detail. We include some discussion of its evaluation, in particular its behavior in raw Lisp, because we expect that most who read further are working with raw Lisp code (and trust tags). [47mReturn-last[0m is an ACL2 function that can arise from macroexpansion of certain utilities that return their last argument, which may be a multiple value. Consider for example the simplest of these, [47m[prog2$][0m: ACL2 !>:trans1 (prog2$ (cw "Some CW printing...~%") (+ 3 4)) (RETURN-LAST 'PROGN (CW "Some CW printing...~%") (+ 3 4)) ACL2 !> Notice that a call of [47mprog2$[0m macroexpands to a call of [47mreturn-last[0m in which the first argument is [47m(quote progn)[0m. Although [47mreturn-last[0m is a function in the ACL2 world, it is implemented ``under the hood'' as a macro in raw Lisp, as the following log (continuing the example above) illustrates. ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (macroexpand-1 '(RETURN-LAST 'PROGN (CW "Some CW printing...~%") (+ 3 4))) (PROGN (LET ((*AOKP* T)) (CW "Some CW printing...~%")) (+ 3 4)) T ? Thus, the original [47mprog2$[0m call generates a corresponding call of [47mprogn[0m in raw Lisp, which in turn causes evaluation of each argument and returns whatever is returned by evaluation of the last (second) argument. Remark for those who use [47m[defattach][0m. The binding of [47m*aokp*[0m to [47mt[0m is included for the second argument as shown in most cases. That binding is avoided only when the first argument is of the form [47m(QUOTE S)[0m for [47mS[0m a macro name and the second argument is a symbol or of the form [47m(QUOTE X)[0m for any [47mX[0m. By binding [47m*aokp*[0m to [47mt[0m, ACL2 is permitted to use attachments when evaluating the second argument of [47mreturn-last[0m (hence, in the first argument of [47m[prog2$][0m), even in contexts such as proofs in which attachments are normally not allowed. In general, a form [47m(return-last (quote F) X Y)[0m macroexpands to [47m(F X Y)[0m, where [47mF[0m is a symbol defined in raw Lisp to return its last argument. The case that [47mF[0m is [47mprogn[0m is a bit misleading, because it is so simple. More commonly, macroexpansion produces a call of a macro defined in raw Lisp that may produce side effects. Consider for example the ACL2 utility [47m[with-guard-checking][0m, which is intended to change the [guard]-checking mode to the indicated value (see [with-guard-checking]). ACL2 !>(with-guard-checking :none (car 3)) ; no guard violation NIL ACL2 !>:trans1 (with-guard-checking :none (car 3)) (WITH-GUARD-CHECKING1 (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3)) ACL2 !>:trans1 (WITH-GUARD-CHECKING1 (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3)) (RETURN-LAST 'WITH-GUARD-CHECKING1-RAW (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3)) ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (macroexpand-1 '(RETURN-LAST 'WITH-GUARD-CHECKING1-RAW (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3))) (WITH-GUARD-CHECKING1-RAW (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3)) T ? (pprint (macroexpand-1 '(WITH-GUARD-CHECKING1-RAW (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3)))) (LET ((ACL2_GLOBAL_ACL2::GUARD-CHECKING-ON (CHK-WITH-GUARD-CHECKING-ARG :NONE))) (DECLARE (SPECIAL ACL2_GLOBAL_ACL2::GUARD-CHECKING-ON)) (CAR 3)) ? The above raw Lisp code binds the state global variable [47mguard-checking-on[0m to [47m:none[0m, as [47mchk-with-guard-checking-arg[0m is just the identity function except for causing a hard error for an illegal input. The intended use of [47mreturn-last[0m is that the second argument is evaluated first in a normal manner, and then the third argument is evaluated in an environment that may depend on the value of the second argument. (For example, the macro [47m[with-prover-time-limit][0m macroexpands to a call of [47mreturn-last[0m with a first argument of [47m'WITH-PROVER-TIME-LIMIT1-RAW[0m, a second argument that evaluates to a numeric time limit, and a third argument that is evaluated in an environment where the theorem prover is restricted to avoid running longer than that time limit.) Although this intended usage model is not strictly enforced, it is useful to keep in mind in the following description of how calls of [47mreturn-last[0m are handled by the ACL2 evaluator. When a form is submitted in the top-level loop, it is handled by ACL2's custom evaluator. That evaluator is specified to respect the semantics of the expression supplied to it: briefly put, if an expression [47mE[0m evaluates to a value [47mV[0m, then the equality [47m(equal E (quote V))[0m should be a theorem. Notice that this specification does not discuss the side-effects that may occur when evaluating a call of [47mreturn-last[0m, so we discuss that now. Suppose that the ACL2 evaluator encounters the call [47m(return-last 'fn expr1 expr2)[0m. First it evaluates [47mexpr1[0m. If this evaluation succeeds without error, then it constructs an expression of the form [47m(fn *x* ev-form)[0m, where *x* is a Lisp variable bound to the result of evaluating [47mexpr1[0m and [47mev-form[0m is a call of the evaluator for [47mexpr2[0m. (Those who want implementation details are invited to look at function [47mev-rec-return-last[0m in ACL2 source file [47mtranslate.lisp[0m.) There are exceptions if [47mfn[0m is [47mprogn[0m, [47mec-call1-raw[0m, [47mwith-guard-checking1-raw[0m, or [47mmbe1-raw[0m, but the main idea is the same: do a reasonable job emulating the behavior of a raw-Lisp call of [47mreturn-last[0m. The following log shows how a [47m[time$][0m call can generate a call of the evaluator for the last argument of [47mreturn-last[0m (argument [47mexpr2[0m, above). We use [47m:[0m[47m[trans1][0m to show single-step macroexpansions, which indicate how a call of [47m[time$][0m expands to a call of [47mreturn-last[0m. The implementation actually binds the Lisp variable [47m*RETURN-LAST-ARG3*[0m to [47mexpr2[0m before calling the ACL2 evaluator, [47mev-rec[0m. ACL2 !>:trans1 (time$ (+ 3 4)) (TIME$1 (LIST 0 NIL NIL NIL NIL) (+ 3 4)) ACL2 !>:trans1 (TIME$1 (LIST 0 NIL NIL NIL NIL) (+ 3 4)) (RETURN-LAST 'TIME$1-RAW (LIST 0 NIL NIL NIL NIL) (+ 3 4)) ACL2 !>(time$ (+ 3 4)) ; (EV-REC *RETURN-LAST-ARG3* ...) took ; 0.00 seconds realtime, 0.00 seconds runtime ; (1,120 bytes allocated). 7 ACL2 !> We now show how things can go wrong in other than the ``intended use'' case described above. In the example below, the macro [47mmac-raw[0m is operating directly on the syntactic representation of its first argument, which it obtains of course as the second argument of a [47mreturn-last[0m call. Again this ``intended use'' of [47mreturn-last[0m requires that argument to be evaluated and then only its result is relevant; its syntax is not supposed to matter. We emphasize that only top-level evaluation depends on this ``intended use''; once evaluation is passed to Lisp, the issue disappears. We illustrate below how to use the [47m[top-level][0m utility to avoid this issue; see [top-level]. The example uses the utility [47mdefmacro-last[0m to ``install'' special handling of the raw-Lisp macro [47mmac-raw[0m by [47mreturn-last[0m; later below we discuss [47mdefmacro-last[0m. ACL2 !>(defttag t) TTAG NOTE: Adding ttag :T from the top level loop. T ACL2 !>(progn! (set-raw-mode t) (defmacro mac-raw (x y) `(progn (print (quote ,(cadr x))) (terpri) ; newline ,y))) Summary Form: ( PROGN! (SET-RAW-MODE T) ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) NIL ACL2 !>(defmacro-last mac) [[ ... output omitted ... ]] RETURN-LAST-TABLE ACL2 !>(return-last 'mac-raw '3 nil) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Fault during read of memory address #x120000300006 *********************************************** If you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !>(top-level (return-last 'mac-raw '3 nil)) 3 NIL ACL2 !> We next describe how to extend the behavior of [47mreturn-last[0m. This requires an active trust tag (see [defttag]), and is accomplished by extending a [table] provided by ACL2, see [return-last-table]. Rather than using [47m[table][0m [events] directly for this purpose, it is probably more convenient to use a macro, [47mdefmacro-last[0m. We describe the community book [47mbooks/misc/profiling.lisp[0m in order to illustrate how this works. The events in that book include the following, which are described below. (defttag :profiling) (progn! (set-raw-mode t) (load (concatenate 'string (cbd) "profiling-raw.lsp"))) (defmacro-last with-profiling) The first event introduces a trust tag. The second loads a file into raw Lisp that defines a macro, [47mwith-profiling-raw[0m, which can do profiling for the form to be evaluated. The third introduces an ACL2 macro [47mwith-profiling[0m, whose calls expand into calls of the form [47m(return-last (quote with-profiling-raw) & &)[0m. The third event also extends [47m[return-last-table][0m so that these calls will expand in raw Lisp to calls of [47mwith-profiling-raw[0m. The example above illustrates the following methodology for introducing a macro that returns its last argument but produces useful side-effects with raw Lisp code. (1) Introduce a trust tag (see [defttag]). (2) Using [47m[progn!][0m, load into raw Lisp a file defining a macro, [47mRAW-NAME[0m, that takes two arguments, returning its last (second) argument but using the first argument to produce desired side effects during evaluation of that last argument. (3) Evaluate the form [47m(defmacro-last NAME :raw RAW-NAME)[0m. This will introduce [47mNAME[0m as an ACL2 macro that expands to a corresponding call of [47mRAW-NAME[0m (see (2) above) in raw Lisp. The specification of keyword value of [47m:raw[0m as [47mRAW-NAME[0m may be omitted if [47mRAW-NAME[0m is the result of modifying the symbol [47mNAME[0m by suffixing the string [47m"-RAW"[0m to the [47m[symbol-name][0m of [47mNAME[0m. WARNING: Not every use of [47mreturn-last[0m can be soundly evaluated outside a function body. The reason is that ACL2's evaluator, [47mev-rec[0m, recurs through terms that are presented in the top-level loop, and handles [47mreturn-last[0m calls in a special manner: basically, the call of [47mev-rec[0m on the form [47m(return-last 'mac-raw x y)[0m leads to evaluation of a macro call of the form [47m(mac-raw *return-last-arg2* (ev-rec ...))[0m, where *return-last-arg2* is a global variable bound to the result of evaluating [47mx[0m with [47mev-rec[0m. Consider the following example. (defttag t) (set-raw-mode-on state) (defmacro mac-raw (str y) ; print message is an atom `(let ((result (consp ,y)) (str ,str)) (or result (prog2$ (fmx ,str ',y) nil)))) (set-raw-mode-off state) (defmacro-last mac) ; Horrible error: (mac "Not a cons: ~x0~%" 17) ; Works, but probably many would consider it awkward to use top-level: (top-level (mac "Not a cons: ~x0~%" 17)) In such cases we suggest supplying keyword [47m:top-level-ok nil[0m to the call of [47mdefmacro-last[0m, for example: (defmacro-last mac :top-level-ok nil) Then any attempt to call [47mmac[0m at the top level, as opposed to inside a function body, will cause a clean error before evaluation begins. It is useful to explore what is done by [47mdefmacro-last[0m. ACL2 !>:trans1 (defmacro-last with-profiling) (PROGN (DEFMACRO WITH-PROFILING (X Y) (LIST 'RETURN-LAST (LIST 'QUOTE 'WITH-PROFILING-RAW) X Y)) (TABLE RETURN-LAST-TABLE 'WITH-PROFILING-RAW 'WITH-PROFILING)) ACL2 !>:trans1 (with-profiling '(assoc-eq fgetprop rewrite) (mini-proveall)) (RETURN-LAST 'WITH-PROFILING-RAW '(ASSOC-EQ FGETPROP REWRITE) (MINI-PROVEALL)) ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ? (macroexpand-1 '(RETURN-LAST 'WITH-PROFILING-RAW '(ASSOC-EQ FGETPROP REWRITE) (MINI-PROVEALL))) (WITH-PROFILING-RAW '(ASSOC-EQ FGETPROP REWRITE) (MINI-PROVEALL)) T ? To understand the macro [47mwith-profiling-raw[0m you could look at the community book loaded above: [47mbooks/misc/profiling-raw.lsp[0m. We mentioned above that ACL2 tends to print calls of [47m[prog2$][0m or [47m[time$][0m (or other such utilities) instead of calls of [47mreturn-last[0m. Here we elaborate that point. ACL2's `[47muntranslate[0m' utility treats [47m(return-last (quote F) X Y)[0m as [47m(G X Y)[0m if [47mF[0m corresponds to the symbol [47mG[0m in [47mreturn-last-table[0m. However, it is generally rare to encounter such a term during a proof, since calls of [47mreturn-last[0m are generally expanded away early during a proof. Calls of [47mreturn-last[0m that occur in code --- forms submitted in the top-level ACL2 loop, and definition bodies other than those marked as [47m[non-executable][0m (see [defun-nx]) --- have the following restriction: if the first argument is of the form [47m(quote F)[0m where [47mF[0m is a non-[47mnil[0m symbol, then [47mF[0m must be an entry in [47mreturn-last-table[0m. There are however four exceptions: the following symbols are considered to be keys of [47mreturn-last-table[0m even if they are no longer associated with non-[47mnil[0m values, say because of a [47m[table][0m event with keyword [47m:clear[0m. * [47mprogn[0m, associated with [47m[prog2$][0m * [47mmbe1-raw[0m, associated with [47mmbe1[0m, a version of [47mmbe[0m * [47mec-call1-raw[0m, associated with [47mec-call1[0m (a variant of [47m[ec-call][0m) * [47mwith-guard-checking1-raw[0m, associated with [47mwith-guard-checking1[0m (a variant of [47m[with-guard-checking][0m) Note that because of its special status, it is illegal to trace [47mreturn-last[0m. For any object [47mx[0m that is not of the form [47m(quote S)[0m where [47mS[0m is a symbol, the call [47m(return-last x y z)[0m is legal, even in code, if [47my[0m and [47mz[0m are legal. Such terms are evaluated as though [47mx[0m is [47m(QUOTE PROGN)[0m, that is, as though they arose from a call of [47m[prog2$][0m. In particular, you are welcome to write terms of the form [47m(return-last '(<some-annotation>) y z)[0m. We conclude by warning that as a user, you take responsibility for not compromising the soundness or error handling of ACL2 when you define a macro in raw Lisp and especially when you install it as a key of [47m[return-last-table][0m, either directly or (more likely) using [47mdefmacro-last[0m. In particular, be sure that you are defining a macro of two arguments that always returns the value of its last argument, returning the complete multiple value if that last argument evaluates to a multiple value. The following is correct, and illustrates care taken to return multiple values. (defttag t) (set-raw-mode t) (defmacro my-time1-raw (val form) (declare (ignore val)) `(let ((start-time (get-internal-run-time)) (result (multiple-value-list ,form)) (end-time (get-internal-run-time))) (format t "Total time: ~s~%" (float (/ (- end-time start-time) internal-time-units-per-second))) (values-list result))) (set-raw-mode nil) (defmacro-last my-time1) (defmacro my-time (form) `(my-time1 nil ,form)) Then for example: ACL2 !>(my-time (equal (make-list 1000000) (make-list 1000000))) Total time: 0.12 T ACL2 !> But if instead we provide the following more naive implementation, of the above raw Lisp macro, the above evaluation can produce an error, for example if the host Lisp is CCL. (defmacro my-time1-raw (val form) (declare (ignore val)) `(let ((start-time (get-internal-run-time)) (result ,form) (end-time (get-internal-run-time))) (format t "Total time: ~s~%" (float (/ (- end-time start-time) internal-time-units-per-second))) result)) ; WRONG -- need multiple values returned! Here is a second, similar example. This time we'll start with the error; can you spot it? (defttag t) (progn! (set-raw-mode t) (defmacro foo-raw (x y) `(prog1 ,y (cw "Message showing argument 1: ~x0~%" ,x)))) (defmacro-last foo) We then can wind up with a hard Lisp error: ACL2 !>(foo 3 (mv 4 5)) Message showing argument 1: 3 *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: value NIL is not of the expected type REAL. *********************************************** If you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !> Here is a corrected version of the above macro. The point here is that [47mprog1[0m returns a single value, while [47mour-multiple-value-prog1[0m returns all the values that are returned by its first argument. (progn! (set-raw-mode t) (defmacro foo-raw (x y) `(our-multiple-value-prog1 ;; better ,y (cw "Message showing argument 1: ~x0~%" ,x)))) [31;1mFunction: [0m<return-last> (defun return-last (fn eager-arg last-arg) (declare (ignore fn eager-arg) (xargs :guard (if (equal fn 'mbe1-raw) (equal last-arg eager-arg) t))) last-arg) Subtopics [Return-last-table] Install special raw Lisp behavior") (return-last-table (return-last) "Install special raw Lisp behavior Please first see [return-last] for relevant background. This [table] is for advanced users only, and requires an active trust tag (see [defttag]). We recommend that you do not modify this table directly, but instead use the macro [47mdefmacro-last[0m. Here we augment that discussion with some highly technical observations that can probably be ignored if you use [47mdefmacro-last[0m. This [table] has a [47m:guard[0m requiring that each key be a symbol defined in raw Lisp, generally as a macro, and requiring that each non-[47mnil[0m value be associated either with a symbol that names a macro defined in ACL2, or else with a list of one element containing such a symbol. The table can only be modified when there is an active trust tag; see [defttag]. If a key is associated with the value [47mnil[0m, then that key is treated as though it were not in the table. Note that keys of this table are not eligible to be bound by [47m[flet][0m or [47m[macrolet][0m. The current value of this table may be obtained by evaluating the form [47m(table-alist 'return-last-table (w state))[0m. The built-in constant [47m*initial-return-last-table*[0m holds the initial value of this table.") (revappend (lists acl2-built-ins) "Concatenate the [reverse] of one list to another [47m(Revappend x y)[0m [concatenate]s the [reverse] of the list [47mx[0m to [47my[0m, which is also typically a list. The following theorem characterizes this English description. (equal (revappend x y) (append (reverse x) y)) Hint: This lemma follows immediately from the definition of [47m[reverse][0m and the following lemma. (defthm revappend-append (equal (append (revappend x y) z) (revappend x (append y z)))) The [guard] for [47m(revappend x y)[0m requires that [47mx[0m is a true list. [47mRevappend[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<revappend> (defun revappend (x y) (declare (xargs :guard (true-listp x))) (if (endp x) y (revappend (cdr x) (cons (car x) y))))") (reverse (lists strings acl2-built-ins) "Reverse a list or string [47m(Reverse x)[0m is the result of reversing the order of the elements of the list or string [47mx[0m. The [guard] for [47mreverse[0m requires that its argument is a true list or a string. [47mReverse[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<reverse> (defun reverse (x) (declare (xargs :guard (or (true-listp x) (stringp x)))) (cond ((stringp x) (coerce (revappend (coerce x 'list) nil) 'string)) (t (revappend x nil))))") (revert-world (programming) "Evaluate without (ultimately) changing the [world] General Form: (revert-world form) where [47mform[0m evaluates to an [error-triple]. Evaluation of [47m(revert-world form)[0m returns the same result, [47m(mv erp val state)[0m, as the given [47mform[0m, except that the [world] of the returned [47m[state][0m is the same as the world of the input state even if the evaluation of [47mform[0m modifies the world of the input state. To see [47mrevert-world[0m in action, consider the following definition. (defun test-revert-world (state) (declare (xargs :mode :program :stobjs state)) (er-progn (value (cw "Length of (w state) before defun: ~x0~%" (length (w state)))) (revert-world (er-progn (trans-eval '(with-output :off :all ; avoid output ; (defun foo (x) x)) 'my-ctx state nil) (value (cw "Length of (w state) after defun: ~x0~%" (length (w state)))))) (value (cw "Length of (w state) after revert-world: ~x0~%" (length (w state)))))) Here is a log produced after admitting the definition above in a fresh session (for an ACL2 build circa November 2017). It shows that the definition lengthens the world, but that the world's length is back to its initial value after we return from [47mrevert-world[0m. ACL2 !>(test-revert-world state) Length of (w state) before defun: 107133 Length of (w state) after defun: 107153 Length of (w state) after revert-world: 107133 NIL ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) P 1:x(DEFUN TEST-REVERT-WORLD (STATE) ...) ACL2 !> The macroexpansion of [47m(revert-world form)[0m contains a call of a [program]-mode function. It is thus illegal to call [47mrevert-world[0m in the body of a [logic]-mode function. Contact the ACL2 implementors if you want them to consider working to lift this restriction.") (revisiting_the_admission_of_app (pages_written_especially_for_the_tours) "Revisiting the Admission of App {IMAGE} (see [Evaluating_App_on_Sample_Input]) Here is the definition of [47mapp[0m again with certain parts highlighted. If you are taking the Walking Tour, please read the text carefully and click on each of the links below, [31;1mexcept those marked[0m {ICON} (see [A_Tiny_Warning_Sign]). Then come [31;1mback[0m here. {IMAGE} ACL2 !> (see [About_the_Prompt])[31;1m(defun app (x y)[0m [31;1m(cond ((endp x) y)[0m [31;1m(t (cons (car x) [0m [31;1m(app (cdr x) y)))))[0m The admission (see [About_the_Admission_of_Recursive_Definitions]) of APP is trivial, using the relation [o<] {ICON} (see [A_Tiny_Warning_Sign]) (which is known to be well-founded on the domain recognized by [o-p] {ICON} (see [A_Tiny_Warning_Sign])) and the measure ([ACL2-count] {ICON} (see [A_Tiny_Warning_Sign]) X). We observe (see [Guessing_the_Type_of_a_Newly_Admitted_Function]) that the type (see [About_Types]) of APP is described by the theorem (OR (CONSP (APP X Y)) (EQUAL (APP X Y) Y)). We used primitive type reasoning. Summary (see [The_Event_Summary]) Form: ( DEFUN APP ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: None Time: 0.03 seconds (prove: 0.00, print: 0.00, other: 0.03) APP {IMAGE} {IMAGE} (see [Evaluating_App_on_Sample_Input])") (rewrite (rule-classes) "Make some [47m:rewrite[0m rules (possibly conditional ones) See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. This doc topic discusses the rule-class [47m:rewrite[0m. If you want a general discussion of how rewriting works in ACL2 and some guidance on how to construct effective rewrite rules, see [introduction-to-rewrite-rules-part-1] and then see [introduction-to-rewrite-rules-part-2]. If you want a flexible, convenient interface to the ACL2 rewriter that can be called programmatically, see [rewrite$]. Examples: (defthm plus-commutes ; Replace (+ a b) by (+ b a) provided (equal (+ x y) (+ y x))) ; certain heuristics approve the ; permutation. (defthm plus-commutes ; equivalent to the above (equal (+ x y) (+ y x)) :rule-classes ((:rewrite :corollary (equal (+ x y) (+ y x)) :loop-stopper ((x y binary-+)) :match-free :all))) (defthm append-nil ; Replace (append a nil) by a, if (implies (true-listp x) ; (true-listp a) rewrites to t. (equal (append x nil) x))) (defthm append-nil ; as above, but with defaults and (implies (true-listp x) ; a backchain limit (equal (append x nil) x)) :rule-classes ((:rewrite :corollary (implies (true-listp x) (equal (append x nil) x)) :backchain-limit-lst (3) ; or equivalently, 3 :match-free :all))) (defthm member-append ; Replace (member e (append b c)) by (implies ; (or (member e b) (member e c) in (and ; contexts in which propositional (true-listp x) ; equivalence is sufficient, provided (true-listp y)) ; b and c are true-lists. (iff (member e (append x y)) (or (member e x) (member e y))))) General Form: (and ... (implies (and ...hi...) (implies (and ...hk...) (and ... (equiv lhs rhs) ...))) ...) Note: One [47m:rewrite[0m rule class object might create many rewrite rules from the [47m:[0m[47m[corollary][0m formula. To create the rules, we first translate the formula, expanding all macros (see [trans]) and also removing [guard-holders]. Next, we then flatten the [47m[and][0m and [47m[implies][0m structure of the formula; for example, if the hypothesis or conclusion is of the form [47m(and (and term1 term2) term3)[0m, then we replace that by the ``flat'' term [47m(and term1 term2 term3)[0m. (The latter is actually an abbreviation for the right-associated term [47m(and term1 (and term2 term3))[0m.) During this flattening process, we eliminate [47m[lambda][0ms as necessary in order to continue flattening; one may think of this step as simply substituting to eliminate [47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m in order to expose more calls of [47mimplies[0m and [47mand[0m. The result is a conjunction of formulas, each of the form (implies (and h1 ... hn) concl) where no hypothesis is a conjunction and [47mconcl[0m is neither a conjunction nor an implication. If necessary, the hypothesis of such a conjunct may be vacuous. We then further coerce each [47mconcl[0m into the form [47m(equiv lhs rhs)[0m, where we continue to eliminate [47mlambdas[0m until we reach this form, and then we eliminate [47mlambdas[0m from the first argument of [47mequiv[0m but not the second argument. Here [47mequiv[0m is a known [equivalence] relation. If we do not reach an equivalence relation, even after eliminating [47mlambdas[0m, then we replace the resulting term, [47mterm[0m by [47m(iff term t)[0m, except that we replace [47m(not term)[0m by [47m(iff term nil)[0m. By these steps we reduce the given [47m:[0m[47m[corollary][0m to a sequence of conjuncts, each of which is of the form (implies (and h1 ... hn) (equiv lhs rhs)) where [47mequiv[0m is a known [equivalence] relation and [47mlhs[0m has no [47mlambda[0ms. See [equivalence] for a general discussion of the introduction of new [equivalence] relations. At this point, we check whether [47mlhs[0m and [47mrhs[0m are the same term; if so, we cause an error, since this rule will loop. (But this is just a basic check; the rule could loop in other cases, for example if [47mrhs[0m is an instance of [47mlhs[0m; see [loop-stopper].) You can experiment by creating some rewrite rules using [47m[defthm][0m and then using [47m:[0m[47m[pr][0m to see how the rule was stored. We create a [47m:rewrite[0m rule for each such conjunct, if possible, and otherwise cause an error. It is possible to create a rewrite rule from such a conjunct provided [47mlhs[0m is not a variable, a quoted constant, a [47m[let][0m-expression, or a [47mlambda[0m application. Although it is legal to create a rewrite rule from an [47m[if][0m-expression [47m(if tst tbr fbr)[0m, note that the rewriter uses the truth or falsity of the test, [47mtst[0m, when rewriting the true and false branches [47mtbr[0m and [47mfbr[0m, respectively; so rewrite rules are most often unnecessary for [47mif[0m-expressions. A [47m:rewrite[0m rule is used when any instance of the [47mlhs[0m occurs in a context in which the [equivalence] relation is an admissible [congruence] relation. First, we find a substitution that makes [47mlhs[0m equal to the target term. Then we attempt to relieve the instantiated hypotheses of the rule. Hypotheses that are fully instantiated are relieved by recursive rewriting. Hypotheses that contain ``free variables'' (variables not assigned by the unifying substitution) are relieved by attempting to guess a suitable instance so as to make the hypothesis equal to some known assumption in the context of the target. If the hypotheses are relieved, and certain restrictions that prevent some forms of infinite regress are met (see [loop-stopper]), the target is replaced by the instantiated [47mrhs[0m, which is then recursively rewritten. ACL2's rewriting process has some optimizations, including the following. * The suggestion, above, that the rewriter looks through the goal [clause] for ``any instance of the [47mlhs[0m'' is not quite true. [47m:Rewrite[0m rules are never applied to quoted constants or any term inside a call of [47m[hide][0m. If you want to rewrite a quoted constant use a [47m:[0m[47m[rewrite-quoted-constant][0m rule. * The notion of ``a substitution that makes [47mlhs[0m equal to the target term'' is a bit more generous than the most straightforward such notion. Suppose for example that [47mlhs[0m is [47m(f (+ 3 x))[0m and the target term is [47m(f (+ 3 (g y))[0m. (Aside: ACL2 deals in so-called translated terms, so since [47m+[0m is a macro, [47mlhs[0m and term would actually be [47m(f (binary-+ '3 x))[0m and [47m(f (binary-+ '3 (g y)))[0m; we will ignore this distinction, but if you want more information, see [term].) Then of course, that substitution binds [47mx[0m to [47m(g y)[0m. But now suppose that instead the target term is [47m(f 10)[0m. You may be surprised to learn that the substitution binding [47mx[0m to [47m7[0m makes [47m(f (+ 3 x))[0m equal to [47m(f 10)[0m; for example, the rewrite rule [47m(equal (f (+ x 3)) (h x)))[0m would rewrite [47m(f 10)[0m to [47m(h 7)[0m. This would also be the case if [47mlhs[0m were instead [47m(f (+ x 3))[0m. This sort of optimization occurs when the new constant has [47m[ACL2-count][0m no greater than the old constant. There are similar optimizations for [47m*[0m, [47m/[0m, [47m-[0m, strings, symbols, and conses (for details see ACL2 source function [47mone-way-unify1-quotep-subproblems[0m). * When a term [47mt1[0m is rewritten to a new term [47mt2[0m, the rewriter is then immediately applied to [47mt2[0m. On rare occasions you may find that you do not want this behavior, in which case you may wish to use a trick involving [47m[hide][0m; see [meta], near the end of that documentation. * When the hypotheses and right-hand side are rewritten, ACL2 does not really first apply the substitution and then rewrite; instead, as it rewrites those terms it looks up the [3malready rewritten[0m values of the bound variables. Sometimes you may want those bindings rewritten again, e.g., because the variables occur in slots that admit additional equivalence relations. See [double-rewrite]. See [introduction-to-rewrite-rules-part-1] and see [introduction-to-rewrite-rules-part-2] for an extended discussion of how to create effective rewrite rules. Subtopics [Assume-true-false-aggressive-p] Control rewriter's use of the [type-alist] with [47mIF[0m calls [Backchain-limit] Limiting the effort expended on relieving hypotheses [Bind-free] To bind free variables of a rewrite, definition, or linear rule [Case-split] Like force but immediately splits the top-level goal on the hypothesis [Double-rewrite] Cause a term to be rewritten twice [Force] Identity function used to force a hypothesis [Free-variables] Free variables in rules [Hands-off-lambda-objects-theory] how to specify no modification of lambda objects [Hide] Hide a term from the rewriter [Loop-stopper] Limit application of permutative rewrite rules [Random-remarks-on-rewriting] Some basic facts about the ACL2 rewriter [Remove-trivial-equivalences-enabled-p] Avoid removal of trivial equivalences during rewriting [Rewrite-equiv] Force ACL2 to perform substitution using a stylized [equivalence] hypothesis [Rewrite-if-avoid-swap] Control rewriter's swapping of branches of [47mIF[0m calls [Rewrite-lambda-modep] switch controlling rewriting of lambda objects [Rewrite-lambda-object] rewriting lambda objects in :FN slots [Rewrite-lambda-object-actions] actions available when rewriting lambda objects [Rewrite-lambda-objects-theory] how to specify rewriting of lambda objects [Rewrite-stack-limit] Limiting the stack depth of the ACL2 rewriter [Rewriting-versus-cleaning-up-lambda-objects] why change the default action on rewriting [47mlambda[0m objects [Rw-cache-state] The current rw-cache-state [Set-rw-cache-state] Set the default rw-cache-state [Set-rw-cache-state!] Set the default rw-cache-state non-[47m[local][0mly [Simple] [47m:[0m[47m[definition][0m and [47m:[0m[47m[rewrite][0m rules used in preprocessing [Syntactically-clean-lambda-objects-theory] how to specify syntactic cleaning of lambda objects [Syntaxp] Attach a heuristic filter on a rule") (rewrite-cache (pointers) "See [set-rw-cache-state].") (rewrite-equiv (rewrite) "Force ACL2 to perform substitution using a stylized [equivalence] hypothesis [47mRewrite-equiv[0m is actually the [identity] function: [47m(rewrite-equiv x) = x[0m for all [47mx[0m. However, a term of the form [47m(hide (rewrite-equiv (equiv x y)))[0m appearing in the hypothesis induces ACL2 to aggressively substitute [47my[0m for [47mx[0m when [47mequiv[0m is an [equivalence] relation (including [47mequal[0m) and [47mx[0m appears in a context in which [47mequiv[0m is being maintained. Equivalence relations appearing in the hypothesis are not generally used by ACL2 to perform substitutions except under special circumstances, such as when one argument is a symbol or a constant or during the fertilization stage of the [waterfall] process. A stylized [47mrewrite-equiv[0m expression of the form [47m(hide (rewrite-equiv (equiv x y)))[0m can be used to override this default behavior. Care should be taken in using [47mrewrite-equiv[0m, however, because it can easily result in rewrite loops. For an example of a [clause-processor] that leverages [47mRewrite-equiv[0m to induce substitution using equivalence relations appearing in the hypothesis, see [rewrite-equiv-hint].") (rewrite-if-avoid-swap (rewrite system-attachments) "Control rewriter's swapping of branches of [47mIF[0m calls This topic concerns an advanced control for the ACL2 prover. By default, the ACL2 rewriter may swap true and false branches of a call of [47mIF[0m, in particular when the test is a call of [47mNOT[0m. Attach the function [47mconstant-t-function-arity-0[0m to defeat this behavior. Attach the function [47mconstant-nil-function-arity-0[0m to restore the default behavior.") (rewrite-lambda-modep (rewrite) "switch controlling rewriting of lambda objects [47mRewrite-lambda-modep[0m is an identity function with no purpose other than to serve as a switch controlling whether and how the ACL2 prover rewrites quoted [47mlambda[0m objects in argument positions of [ilk] [47m:FN[0m. Behavior is determined by the enabled status of two runes associated with [47mrewrite-lambda-modep[0m, the executable-counterpart rune and the definition rune. See [rewrite-lambda-object].") (rewrite-lambda-object (rewrite) "rewriting lambda objects in :FN slots [47m[Lambda][0m objects are quoted constants passed to [scion]s and applied as functions by [47m[apply$][0m. The ACL2 rewriter can be made to replace the bodies of quoted [47mlambda[0m objects with (supposedly) simpler bodies that are [47m[ev$][0m equivalent, when the lambda objects occur in slots of [ilk] [47m:FN[0m. However, there are restrictions on which lambda objects can be so simplified, restrictions on the techniques available to the rewriter during the simplification of [47mlambda[0m bodies, and restrictions controlling whether the simplified body replaces the original or is ignored. We explain below. When an Occurrence of a [47mlambda[0m Objects Is Eligible An occurrence of a quoted [47mlambda[0m object is eligible to be simplified provided * (a) it occurs in a [47m:FN[0m position of a call of a [scion], * (b) the [47mlambda[0m object is well-formed (see [47m[well-formed-lambda-objectp][0m), * (c) every function symbol mentioned in the body has been warranted However, eligible quoted [47mlambda[0m objects are not modified at all if the [rune] [47m(:executable-counterpart rewrite-lambda-modep)[0m is [disable]d. That rune is enabled by default. Condition (b) implies the body of the [47mlambda[0m is in fact a well-formed ACL2 term (so the rewriter can explore it), every function symbol in it is [badge]d (so that function objects mentioned are used properly), that every variable symbol occurring freely in the body is among the formals of the [47mlambda[0m object, and together with (c) implies that the term ``behaves'' as expected if the appropriate warrant hypotheses govern this occurrence of the object. This last implication means that [47m[ev$][0m of the body is equal to unquoted body (under a suitable assignment), which means we can replace the unquoted body. If (a) holds but either (b) or (c) fails, then a [47m"rewrite-lambda-object"[0m warning message is printed during the proof. However, this message is only printed once per [47mlambda[0m object per proof attempt because otherwise the presence of ill-formed [47mlambda[0m-like objects in a conjecture will litter the output with repeated warnings. You may turn these warnings off with [47m([0m[47m[toggle-inhibit-warning][0m [47m"Rewrite-lambda-object")[0m. Restrictions During Rewriting of a [47mLambda[0m Body The rewriter is restricted in three ways when rewriting the bodies of eligible occurrences of [47mlambda[0m objects. First, the user can specify one of two actions the rewriter can take on an eligible [47mlambda[0m object occurrence (in addition to taking no action as controlled by the [47mrewrite-lambda-modep[0m rune mentioned above). The available actions are to recursively call the rewriter and normalize the result, or to do syntactic cleaning only. The default is recursive rewriting, with the restrictions explained in below. Syntactic cleaning just eliminates declarations, guards, and various tags irrelevant to the logical value of the body. We describe how the user specifies the action to be used in [rewrite-lambda-object-actions]. We give more details about these two kinds of [47mlambda[0m body simplification in [rewriting-versus-cleaning-up-lambda-objects]. Second, warrant hypotheses in the goal [clause] are the only contextual information ``imported'' from the goal clause and made available while rewriting a [47mlambda[0m body. That means type information about variables and other terms is forgotten, as are any linear arithmetic relationships. The reason is simple: the variables in the body are in a different scope than the variables outside the [47mlambda[0m object. Put another way, we do not know, in general, to what the [47mlambda[0m object will eventually be applied and so, in ACL2's untyped logic, we know nothing about its formal variables. (Actually, we not only ``import'' the warrants from the goal clause, we import every ground hypothesis governing the [47mlambda[0m object's occurrence. But practically speaking that means we only import warrant hypotheses. A more sophisticated handling of contextual information can be imagined. For example, if the [47mlambda[0m object occurs as the first argument of a [47m[loop$][0m scion, like [47mcollect$[0m or [47msum$[0m, then the rewriter could perhaps extract type information from the target and import that information. For example, perhaps every element of the target is a number. In that case, since we know the [47mlambda[0m object in a [47mloop$[0m scion call is only applied to elements of that list, we would then be allowed to assume the corresponding formal of the [47mlambda[0m object is a number. But that more sophisticated handling of contextual information has not been implemented.) Third, recursive functions are never opened when rewriting [47mlambda[0m bodies. For example, if [47m(len (cons e x))[0m occurs in a [47mlambda[0m body, you might expect it to be simplified to [47m(+ 1 (len x))[0m, because that is what generally happens to that term when occurrences outside [47mlambda[0m objects are rewritten. ACL2 normally controls the expansion of recursive functions by reference to terms that already occur within the current goal. But the [47mlambda[0m object effectively shares no variables with the surrounding goal and those heuristics are inapplicable. Preliminary experiments with allowing expansions of recursive functions inside [47mlambda[0m objects have produced unsatisfactory results such as runaway expansions. So at the moment we allow no recursive expansions. The ACL2 implementors hope to address both of the above problems in eventual future releases. Syntactic cleaning, in contrast to the restricted rewriting just described, eliminates declarations, guards, and other compiler-related tags introduced by translation of [47mlambda$[0m and [47mloop$[0m. It does beta reduction, which eliminates local variable names (other than the formals of the [47mlambda[0m object). And it replaces the last argument of calls of [47m[do$][0m by [47mnil[0m if that argument is a quoted constant other than [47mnil[0m. (This argument is irrelevant to the value of the [47mdo$[0m term and only used in error reporting.) What Happens After Rewriting a [47mLambda[0m Body After the specified action on the body, [3mb[0m, of [47m(lambda([0m[3mv1...vn[0m[47m)[0m[3mb[0m[47m)[0m to produce [3mb'[0m the decision must be made as to whether to return the [47mlambda[0m with the rewritten body, [47m(lambda([0m[3mv1...vn[0m[47m)[0m[3mb'[0m[47m)[0m, or to ignore the rewrite and return the original (unrewritten) object. ACL2 ignores the rewrite and returns the original [47mlambda[0m object if any of the following three cases obtains: * (a) [3mb'[0m contains variables other than the [47mlambda[0m formals [3mv1,...,vn[0m, * (b) [3mb'[0m is not tame, or * (c) some function symbol appearing in [3mb'[0m has no warrant hypothesis in the goal clause but forcing is disabled (see [47m[force][0m). In all cases, the rewriter prints a [47m"rewrite-lambda-object"[0m warning when the rewritten body is different from the original one but the rewrite is rejected. The warning message displays the before and after [47mlambda[0m objects, lists the rewrite rules used, and explains which of the three conditions above was violated. However, this message is only printed once per [47mlambda[0m object per proof attempt because otherwise the presence of a [47mlambda[0m object that rewrites inappropriately will litter the output with repeated warnings. Condition (a) can arise if a rewrite rule introduces a free variable; disabling that rewrite rule is recommended. Condition (b) can arise if some rewrite rule introduces a function symbol that has not been warranted; disabling that rule can often solve that problem but perhaps a better response is to use [47m[defwarrant][0m to issue a warrant for the offending function symbol and then supply that warrant as a hypothesis to the goal; the latter response is perhaps better because it means all the ``usual'' rewriting is done, normalizing terms as expected. Condition (c) can be addressed by using [47mdefwarrant[0m to issue a warrant for the offending function symbol and enabling forcing (see [47m[force][0m). The warning message noted above can become annoying. You may turn these warnings off with [47m([0m[47m[toggle-inhibit-warning][0m [47m"Rewrite-lambda-object")[0m. Be advised that if the [47m"rewrite-lambda-object"[0m warning has been inhibited (by you or some book included in your session) and then, when looking at, say, the checkpoints in a failed proof, you see a [47mlambda[0m object that you expected to be simplified but was not, you may think rewriting was not attempted for it, for some reason, when in fact it was attempted but rejected. You can [47m(toggle-inhibit-warning "Rewrite-lambda-object")[0m and replay the proof attempt to see (all) the rejected [47mlambda[0m object rewrites. A Possible Confusion A metafunction that is included in the book [47mprojects/apply/top[0m can also cause quoted [47mlambda[0m objects to be rewritten. This metafunction, called [47mrelink-fancy-scion[0m, is called on certain calls of the fancy [47mloop$[0m scions, e.g., calls of [47m[always$+][0m, [47m[collect$+][0m, [47m[sum$+][0m, etc. The goal of that metafunction is to keep the list of ``global variables'' in some normal form. For example,consider the term (collect$+ (quote (lambda (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (cons (car (cdr loop$-gvars)) (cons (car loop$-ivars) 'nil))))) (list a b) target) which is (essentially) the translation of [47m(loop$ for e in target collect (list a b e))[0m. Suppose that in some case of a proof about this term the hypothesis [47m(equal a b)[0m governs this term. The term would thus become (collect$+ (quote (lambda (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (cons (car (cdr loop$-gvars)) (cons (car loop$-ivars) 'nil))))) (list a a) target) [47mRelink-fancy-scion[0m will rewrite that term to (collect$+ (quote (lambda (loop$-gvars loop$-ivars) (cons (car loop$-gvars) (cons (car loop$-gvars) (cons (car loop$-ivars) 'nil))))) (list a) target) which eliminates the duplicate entry in the list of globals and, as a necessary side effect, also replaces the body of the lambda object to eliminate the term [47m(car (cdr loop$-gvars))[0m. The application of the metafunction [47mrelink-fancy-scion[0m can easily but mistakenly be attributed to the rewriting of [47mlambda[0m objects but it is not! The metafunction is applied to the whole [47mcollect$+[0m term (and calls of every other fancy scion), not just the [47mlambda[0m object. If you want to avoid this normalization of the globals, disable the [rune] [47m(:meta relink-fancy-scion-correct)[0m.") (rewrite-lambda-object-actions (rewrite) "actions available when rewriting lambda objects As explained in [rewrite-lambda-object] the rewriter can be applied to eligible occurrences of quoted [47mlambda[0m objects. That documentation also describes eligibility, what happens during, and what happens after the specified action, with a focus on recursively rewriting the [47mlambda[0m body. This topic discusses how to specify the desired action. The user can specify one of three actions by manipulating the enabled status of the [rune] [47m(:executable-counterpart rewrite-lambda-modep)[0m and the enabled status of [47m(:definition rewrite-lambda-modep)[0m. Recall that such runes can be abbreviated [47m(:e rewrite-lambda-modep)[0m and [47m(:d rewrite-lambda-modep)[0m. But in this discussion, we'll abbreviate them still further by [3me[0m and [3md[0m, respectively. The actions available on the body of an eligible [47mlambda[0m object occurrence are * rewrite: [3me[0m and [3md[0m enabled * syntactically clean: [3me[0m enabled and [3md[0m disabled * hands-off (no action): [3me[0m disabled Since the action is determined by the enabled status of runes, it can be specified by the user by appropriate global [47m[in-theory][0m events or by goal-specific, local [47m:in-theory[0m [47m:[0m[47m[hints][0m. There are three 0-ary macros that expand into appropriate theories [3mprovided[0m the only runes you wish to affect are our so-called [3me[0m and [3md[0m. The three macros are [47m[rewrite-lambda-objects-theory][0m, [47m[syntactically-clean-lambda-objects-theory][0m, and [47m[hands-off-lambda-objects-theory][0m, with the obvious meanings. For example, [47m(syntactically-clean-lambda-objects-theory)[0m macroexpands to (e/d ((:executable-counterpart rewrite-lambda-modep)) ; enable ``e'' ((:definition rewrite-lambda-modep))) ; disable ``d'' Since [3me[0m and [3md[0m are both initially enabled in ACL2, eligible [47mlambda[0m objects are rewritten by default unless you change the status of [3me[0m and/or [3md[0m. For example, to make the prover just syntactically clean eligible [47mlambda[0m objects in [47mSubgoal 3[0m of some proof attempt you could provide the [47m:hint[0m ("Subgoal 3" :in-theory (syntactically-clean-lambda-objects-theory)) Note however that if you also need to adjust the status of some other rune in that same hint you must create a theory expression that includes the appropriate use of [3me[0m and [3md[0m. For example, to also enable [47mLEMMA1[0m but disable [47mLEMMA2[0m while specifying use of syntactic cleaning you could write: ("Subgoal 3" :in-theory (e/d ((:executable-counterpart rewrite-lambda-modep) LEMMA1) ((:definition rewrite-lambda-modep) LEMMA2))) For details on what syntactic cleaning is and why it is sometimes useful, see [rewriting-versus-cleaning-up-lambda-objects].") (rewrite-lambda-objects-theory (theories theory-functions rewrite) "how to specify rewriting of lambda objects The enabled status of two [47mrewrite-lambda-modep[0m runes are used as flags to determine the action taken when eligible [47mlambda[0m objects are encountered by the ACL2 rewriter. See [rewrite-lambda-object] and [47m[rewrite-lambda-object-actions][0m. To make the rewriter dive into the body of an eligible [47mlambda[0m object, both [47m(:executable-counterpart rewrite-lambda-modep)[0m and [47m(:definition rewrite-lambda-modep)[0m must be enabled in the then-current theory. The 0-ary function [47mrewrite-lambda-objects-theory[0m returns such a theory. In fact, diving into eligible quoted [47mlambda[0m object constants to rewrite the body is the default action when ACL2 starts up. See [rewriting-versus-cleaning-up-lambda-objects] for why you might want to change the default action when eligible [47mlambda[0m objects are encountered by the rewriter. The expression [47m(rewrite-lambda-objects-theory)[0m macroexpands to the theory expression (e/d ((:executable-counterpart rewrite-lambda-modep) (:definition rewrite-lambda-modep)) nil) which is a theory equal to the current theory except that the executable-counterpart rune and the definition rune of [47mrewrite-lambda-modep[0m are enabled. This expansion is suitable for use in an [47m[in-theory][0m event or [47m:in-theory[0m hint (see [47m:[0m[47m[hints][0m). Both these two runes are initially enabled, so eligible [47mlambda[0m object bodies are rewritten by default until and unless some event (e.g., an [47m[in-theory][0m or [47m[include-book][0m) or a superior local subgoal hint changes the status of those runes. For example, if [47mlambda[0m object rewriting has been disabled globally and you wish to enable it for [47mSubgoal 3[0m of some proof, you could use the [47m:[0m[47m[hints][0m ("Subgoal 3" :in-theory (rewrite-lambda-objects-theory)) Note that if you also wish to enable or disable other runes in the same subgoal you must construct an appropriate theory. For example, if in [47mSubgoal 3[0m of some proof you wanted to enable [47mLEMMA1[0m and disable [47mLEMMA2[0m in a theory that will also allow rewriting of [47mlambda[0m objects, you might write ("Subgoal 3" :in-theory (set-difference-theories (union-theories (rewrite-lambda-objects-theory) '(LEMMA1)) '(LEMMA2))) Some users might prefer ("Subgoal 3" :in-theory (e/d ((:executable-counterpart rewrite-lambda-modep) (:definition rewrite-lambda-modep) LEMMA1) (LEMMA2))) See [theories] for general information about theories and how to create and use them.") (rewrite-quoted-constant (rule-classes) "Make a rule to rewrite a quoted constant See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Note: It is helpful to know some basic facts about the ACL2 rewriter; see [random-remarks-on-rewriting]. Example Forms: (defthm lambda-id (fn-equal '(lambda (x) x) 'identity) :rule-classes :rewrite-quoted-constant) (defthm set-normalizer (set-equalp (drop-duplicates-and-sort x) x) :rule-classes :rewrite-quoted-constant) (defthm lambda-id-generalized (implies (symbolp v) (fn-equal (list 'lambda (list v) v) 'identity)) :rule-classes :rewrite-quoted-constant) To be accepted with rule-class [47m:rewrite-quoted-constant[0m a conjecture must have one of the following three General Forms: (IMPLIES hyps (equiv 'const1 'const2)) ; [1] (IMPLIES hyps (equiv (fn var) var)) ; [2] (IMPLIES hyps (equiv (constructor ...) rhs)) ; [3] where * [47mhyps[0m is a term (typically a conjunction) and may include [47m[force][0m and [47m[syntaxp][0m hypotheses with the usual semantics, * [47mequiv[0m is a known [equivalence] relation and, in the case of [47m[1][0m and [47m[2][0m, [47mequiv[0m is not [47mEQUAL[0m, * [47mvar[0m, in form [47m[2][0m, is a variable symbol, and * [47mconstructor[0m, in form [47m[3][0m, is an explicit value ``constructor'' function symbol listed in [47m*one-way-unify1-implicit-fns*[0m. The list just mentioned includes [47mcons[0m, which can be used to match non-empty list constants, [47mcoerce[0m, which can match string constants, [47mintern-in-package-of-symbol[0m, which can match symbol constants, and [47mbinary-+[0m and certain other arithmetic primitives which can match numeric constants. See [random-remarks-on-rewriting] for some examples. If a rule meets the criteria for both a form [47m[2][0m rule and a form [47m[3][0m rule, then it is considered to be a form [47m[2][0m rule. The function, [47mfn[0m, in a form [47m[2][0m rule is called the ``normalizer.'' We explain this terminology as we discuss how such rules are used. The [47m:rewrite-quoted-constant[0m rule-class is permitted to specify a [47m:corollary[0m and/or a [47m:loop-stopper[0m, with the usual syntax and meaning. See [47m:[0m[47m[rule-classes][0m. Note that for forms [47m[1][0m and [47m[2][0m above a [47m:[0m[47mloop-stopper[0m is probably irrelevant as the forms do not usually contain multiple variable symbols. Once a [47m:rewrite-quoted-constant[0m rule is proved and stored, the rewriter behaves as follows. When a quoted constant is encountered as the target term to be rewritten, the rewriter considers each enabled [47m:rewrite-quoted-constant[0m rule (most-recent first), looking for those whose [47mequiv[0m refines (see [47m:[0m[47m[refinement][0m) the equivalence relation being maintained by the rewriter for the given occurrence of the target. The rewriter tries to apply each such rule in turn (as described below) and replaces the target by the rewritten result of the first applicable rule. A rule applies if the ``pattern'' (see below) in the conclusion ``matches'' the quoted constant and the [47mhyps[0m can be relieved in the usual sense, including the treatment of free variables, pragmatic directives like [47m[force][0m and [47m[syntaxp][0m, and heuristics such as those controlled by any [47m:[0m[47m[loop-stopper][0m options in the rule-class or [47m:[0m[47mrestrict[0m [hints]. If these conditions are met, the quoted constant is replaced by the ``result.'' But the exact meanings of ``pattern,'' ``match'' and ``result'', here, are a little different from their meanings for ordinary [47m:rewrite[0m rules and depend on which of the three forms is being applied. * A form [47m[1][0m rule, whose conclusion is [47m(equiv 'const1 'const2)[0m, has [47m'const1[0m as its pattern and that pattern matches the target constant [47m'const[0m only when [47mconst1[0m is exactly [47mconst[0m. The result is [47m'const2[0m. Note that it is impossible to prove a form [47m[1][0m rule whose equivalence is [47mequal[0m unless the two constants are identical, so we disallow that case. * A form [47m[2][0m rule, whose conclusion is [47m(equiv (fn var) var)[0m, is most easily understood by swapping the roles of left- and right-hand sides of its conclusion. Its pattern is the right-hand side, [47mvar[0m, and its result is derived from the left-hand side, [47m(fn var)[0m. The reason we use the form shown here is so that the same conjecture might also be used as an ordinary [47m:rewrite[0m rule without forcing the user to type a [47m:corollary[0m with the sides swapped. Since form [47m[2][0m rules have a variable as the pattern they will match any quoted constant, [47m'const[0m, by binding [47mvar[0m to [47m'const[0m. The result is the quoted constant, if any, obtained by rewriting [47m(fn var)[0m under that binding of [47mvar[0m. If that rewrite does not result in a constant, no replacement is made, i.e., it is as though the rule did not match. Note that it is pointless to prove a form [47m[2][0m rule whose equivalence is [47mequal[0m because it would replace a quoted constant by itself, so we disallow that equivalence. Intuitively, [47mfn[0m is a function that normalizes every member of the [47mequiv[0m equivalence class: given a constant that is a member of the class it returns its ``normal'' form. That is why we call [47mfn[0m the ``normalizer'' for [47mequiv[0m. However, you do not have to prove anything like normality or canonicality; you just have to prove that [47mfn[0m returns a member of the class. Having several different normalizers is possible but it is best if only one is enabled at a time. When [47mvar[0m is bound to a constant, the rewriter will first try to reduce [47m(fn var)[0m to a constant by simple evaluation. If that fails, it tries using lemmas. If the normalizer or one of its subfunctions is disabled or is non-executable or has a disabled executable counterpart the attempt to simply evaluate [47m(fn var)[0m (under the assignment of [47m'const[0m to [47mvar[0m) may fail. That is why full-blown rewriting of [47m(fn var)[0m is tried instead. It might happen that evaluation fails but lemmas produce a constant. [31;1mThe fact that form [47m[2][0m[31;1m rules are used ``backwards,'' with the roles of the left- and right-hand sides swapped, has some ramifications worth noting.[0m First, you can also classify the same formula as a [47m:rewrite[0m rule (but of course as such it won't rewrite quoted constants); as a [47m:rewrite[0m rule it rewrites instances of [47m(fn var)[0m to the corresponding instance of [47mvar[0m. Second, when a [47m:rewrite-quoted-constant[0m rule is added, the new rule is compared to old rules for subsumption and warning messages are generated; however form [47m[2][0m rules are omitted from this subsumption check because their patterns match every constant (in the equivalence class). Third, if you inspect a form [47m[2][0m rule with [47m[pr][0m, it reports the actual syntax typed, e.g., the ``[47mLhs[0m'' is [47m(fn var)[0m and the ``[47mRhs[0m'' is [47mvar[0m. But, if you [47m:[0m[47m[monitor][0m a form [47m[2][0m rule and then interact with the resulting [break-rewrite] you will see that the [47m[brr-commands][0m [47m:lhs[0m and [47m:rhs[0m report the swapped results. That is, in the break, [47m:lhs[0m will be [47mvar[0m and [47m:rhs[0m will be [47m(fn var)[0m. This is different from the display by [47mpr[0m because [47mpr[0m reports the actual syntax but interactive breaks report how the rule is being used. We think the interactive user, out of long habit, will type [47m:lhs[0m to see the pattern being matched and we did not think it wise to add a special command just to see the pattern in a form [47m[2][0m rule. Fourth, if a form [47m[2][0m rule is mentioned in the report by [47m[pl][0m the ``New term'' is reported to be [47m(fn 'const)[0m, however replacement of [47m'const[0m occurs only if [47m(fn 'const)[0m reduces to a quoted constant by rewriting. * A form [47m[3][0m rule, whose conclusion is [47m(equiv (constructor ...) rhs)[0m, matches the constant [47m'const[0m provided [47m'const[0m is an instance of [47m(constructor ...)[0m under some variable substitution [47ms[0m. We illustrate cases where quoted constants are instances of ``constructor'' terms below and in [random-remarks-on-rewriting]. Note that form [47m[3][0m rules allow the equivalence relation to be [47mequal[0m. Use of [47mequal[0m here could cause looping rewrites if the [47mrhs[0m reduces to a constant. But we allow it because, as noted below, such a rule will also permit you to rewrite a quoted constant into an equivalent term that is not a quoted constant. It is important to realize that form [47m[1][0m and form [47m[3][0m rules only apply to the top-level of a quoted constant. We discuss this at length because it can cause some confusion. The examples below are drawn from the community book [47mbooks/demos/rewrite-quoted-constant-examples[0m. That book introduces [47mset-equalp[0m as an equivalence relation and proves various [47m:rewrite-quoted-constant[0m rules to rearrange the quoted constants occurring in [47mset-equalp[0m contexts. Assume all the quoted constants mentioned below occur in [47mset-equalp[0m contexts. The form [47m[1][0m rule [47m(set-equalp 77 nil)[0m will not cause [47m'(1 2 3 . 77)[0m to rewrite to [47m'(1 2 3)[0m. Because ACL2 applications frequently involve huge quoted list constants, we believe that making the rewriter explore them down to the tips would be prohibitively expensive. However, form [47m[2][0m rules, of the general form [47m(implies hyps (equiv (fn var) var))[0m, allow the normalizer to be applied to every quoted constant occurring in a suitable [47mequiv[0m context. The normalizer can then do a root-and-branch exploration of the constant to compute its replacement. For example, the [47mrewrite-quoted-constants-examples[0m book cited above defines the normalizer [47m(drop-dups-and-sort var)[0m to coerce its argument to a [47m[true-listp][0m, eliminate duplicate elements, and sort the remaining elements. It then proves the form [47m[2][0m rule [47m(set-equalp (drop-dups-and-sort var) var)[0m. Now consider how this rule is used when the rewriter encounters [47m'(3 1 1 2 . 77)[0m in a [47mset-equalp[0m context. First, [47mvar[0m is bound to [47m'const[0m. Then, the rewriter tries to relieve the instantiated hypotheses of the rule, if any. The example rule here has no hypotheses. But you can provide some and perhaps use them to prevent calling the normalizer on this particular constant. Since [47mvar[0m is bound to the constant [47m'const[0m such hypotheses can usually just be computed. Supposing the hypotheses are relieved, the rewriter then rewrites [47m(drop-dups-and-sort 'const)[0m. Under the most common circumstance, this just causes your normalizer function, here [47mdrop-dups-and-sort[0m, to execute on the given constant. (If you have verified the guard of the normalizer and [47m'const[0m satisfies the guard, then the execution is in the underlying raw Common Lisp.) In the most common circumstance, the function will return an explicit constant. If that returned value is indeed a constant (and different from [47m'const[0m), the rewriter replaces this occurrence of [47m'const[0m by the returned value. Otherwise the rule does not apply. As noted earlier, form [47m[3][0m rules are only applied at the top-level of a quoted constant. For example, the rule [47m(set-equalp (cons x y) (my-cons x y))[0m will not cause [47m'(1 2 3)[0m to rewrite to [47m(my-cons 1 (my-cons 2 (my-cons 3 nil)))[0m in [47mset-equalp[0m contexts. Instead, it would produce [47m(my-cons 1 '(2 3))[0m. But since the rewriter will eventually be called on that term, and since that term contains another top-level quoted constant, namely [47m'(2 3)[0m, you might expect the rule to eventually be used to replace [47m'(2 3)[0m by [47m(my-cons 2 '(3))[0m. Indeed, that is what happens -- if you have proved that [47mset-equalp[0m is a [congruence] for the second argument of [47mmy-cons[0m, maintaining [47mset-equalp[0m. However, for technical reasons explained in comments in the book [47mrewrite-quoted-constant-examples[0m, each rewrite occurs in a separate simplification step. So turning [47m'(1 2 3)[0m into [47m(my-cons 1 (my-cons 2 (my-cons 3 nil)))[0m requires three simplification steps. If the rule in question were [47m(set-equalp (cons x y) (cons x (double-rewrite y)))[0m it would happen in one simplification step. See [47mdouble-rewrite[0m and the examples in the book [47mrewrite-quoted-constant-examples[0m. Subtopics [Random-remarks-on-rewriting] Some basic facts about the ACL2 rewriter") (rewrite-stack-limit (rewrite) "Limiting the stack depth of the ACL2 rewriter ACL2 users can create rules of class [47m:[0m[47m[rewrite][0m (see [rule-classes]) that have the potential of causing an infinite loop in the ACL2 rewriter. This could lead to Lisp stack overflows and even segmentation faults. For this reason, the depth of certain calls of functions in the ACL2 rewriter is limited by default using the value of the form [47m(rewrite-stack-limit (w state))[0m. To see the limit in action, execute the following forms. (defthm app-assoc-1 (equal (append (append x y) z) (append x y z))) (defthm app-assoc-2 (equal (append x y z) (append (append x y) z))) (thm (equal (append a b c) xxx) ; try without these hints to see a slightly different error message :hints (("Goal" :do-not '(preprocess)))) The ensuing error message shows a stack of one greater than the value of [47m(rewrite-stack-limit (w state))[0m, which by default is the value of the constant [47m*default-rewrite-stack-limit*[0m. The error message also explains how to use [47m:[0m[47m[brr][0m[47m t[0m and [47m([0m[47m[cw-gstack][0m[47m)[0m to find looping rewrite rules. This limit can be changed; see [set-rewrite-stack-limit]. For a related limit, see [backchain-limit]. Subtopics [Set-rewrite-stack-limit] Sets the rewrite stack depth used by the rewriter") (rewrite_rules_are_generated_from_defthm_events (pages_written_especially_for_the_tours) "Rewrite Rules are Generated from DEFTHM Events {IMAGE} (see [You_Must_Think_about_the_Use_of_a_Formula_as_a_Rule]) By reading the documentation of [47m[defthm][0m {ICON} (see [A_Tiny_Warning_Sign]) (and especially of its [47m:[0m[rule-classes] {ICON} (see [A_Tiny_Warning_Sign]) argument) you would learn that when we submitted the command [31;1m(defthm associativity-of-app[0m [31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c))))[0m we not only command the system to prove that [47mapp[0m is an associative function but * [31;1mwe commanded it to use that fact as a rewrite rule[0m. That means that every time the system encounters a term of the form (app (app [31;1mx[0m [31;1my[0m) [31;1mz[0m) it will replace it with (app [31;1mx[0m (app [31;1my[0m [31;1mz[0m))! {IMAGE} (see [You_Must_Think_about_the_Use_of_a_Formula_as_a_Rule])") (rewriting-calls-of-apply$-ev$-and-loop$-scions (apply$) "How the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m terms This section focuses on how ACL2 rewrites calls of [47mapply$[0m, [47mev$[0m, and [47mloop$[0m scions. Our purpose is to explain the various ways the user can control that rewriting. We do so by taking you through a particularly simple example, starting with a [47mloop$[0m expression. We assume that the standard [47mapply$[0m book has been included, (include-book "projects/apply/top" :dir :system). and we suppose the function [47msq[0m, of one argument, has been defined and warranted (see [47m[defwarrant][0m. Recall that each [47m[loop$][0m statement is translated into a call of some [47mloop$[0m [scion] involving [47mlambda[0m objects formed from the iterated expressions in the [47mloop$[0m statement. Thus, for example, (loop$ for x in (cons a (cdr (cons x b))) collect (* (sq x) 3)) is essentially translated into (COLLECT$ '(LAMBDA (LOOP$-IVAR) (BINARY-* (SQ LOOP$-IVAR) '3)) (CONS A (CDR (CONS X B)))). Recall that you can view the cleaned up translation with [47m:[0m[47m[tc][0m, and the discussion at [47m[tc][0m explains what we mean by ``cleaned up'' here. So [47mloop$[0m statements just introduce [47mlambda[0m objects and scions into any conjecture using [47mloop$[0m. These are rewritten like any other term in ACL2: the arguments are rewritten recursively and then enabled [47m:[0m[47m[rewrite][0m rules (including the definition of the scion) are tried. Recall that ACL2 can rewrite [47mlambda[0m constants. (See [rewrite-lambda-object] for when that can occur and how to control it.) So now consider what happens when the rewriter encounters the translation of the [47mloop$[0m above. (collect$ '(lambda (x) (binary-* (sq x) '3)) ; note where 3 occurs (cons a (cdr (cons x b))) it will rewrite the [47mlambda[0m object and the [47mcons[0m term, effectively turning the [47mcollect$[0m term into (collect$ '(lambda (x) (binary-* '3 (sq x))) ; note where 3 occurs now (cons a b)) Then, if other rewrite rules about [47mcollect$[0m don't rewrite that, the the definition of [47mcollect$[0m will be tentatively tried. By that we mean the body of the definition of [47mcollect$[0m is rewritten (in an environment binding locals to actuals) and then the rewriter decides heuristically whether to use the original call (with its rewritten arguments) or the rewritten body. We do not discuss those heuristics here because they're the same for [47mloop$[0m scions as for all other recursive functions in ACL2. The logical definition of [47mcollect$[0m is (defun collect$ (fn lst) (if (endp lst) nil (cons (apply$ fn (list (car lst))) (collect$ fn (cdr lst))))). And in this case, the body will be tentatively rewritten in the environment where the locals [47mfn[0m and [47mlst[0m are bound as follows. fn: '(lambda (x) (binary-* '3 (sq x))) lst: (cons a b). As the rewriter descends through the body of [47mcollect$[0m it eventually encounters the [47mapply$[0m term. After rewriting its arguments, the [47mapply$[0m term effectively becomes (apply$ '(lambda (x) (binary-* 3 '(sq x))) (cons a 'nil)) and then rules about [47mapply$[0m are tried. Unless you disable it, the rule [47mbeta-reduction[0m, from the standard [47mapply$[0m book above, will fire, transforming the above [47mapply$[0m term to (ev$ '(binary-* '3 (sq x)) (cons (cons 'x a) 'nil)). ([47mBeta-reduction[0m is enabled by default. If you disable it, the [47mapply$[0m term will not change unless you enable [47m(:definition apply$)[0m, which is disabled by default.) But we recommend leaving [47mbeta-reduction[0m enabled and thus converting every [47mapply$[0m of a [47mlambda[0m object into an [47mev$[0m term. There is a special feature of the rewriter for simplifying certain [47mev$[0m terms. It is based on the fact that that (roughly speaking) the [47mev$[0m of a quoted tame term under an alist is the unquoted term with the alist applied as a substitution. That is, the [47mev$[0m term above is equal to [47m(binary-* '3 (sq a))[0m. More precisely, if a [3mx[0m is a [tame] term and every non-primitive function symbol in [3mx[0m has been warranted (see [47m[defwarrant][0m) and [3ma[0m is a [47mcons[0m nest term representing a substitution [3msigma[0m pairing the variable symbols occurring freely in [3mx[0m with terms, then [47m(ev$ '[0m[3mx a[0m[47m)[0m is equal to [3mx[0m/[3msigma[0m, provided the warrants of all the non-primitive function symbols in [3mx[0m are assumed. This is implemented in the rewriter so that when an [47m(ev$ 'x a)[0m is encountered and the following conditions hold * the standard [47mapply$[0m book has been included, * the rune [47m(:rewrite ev$-opener)[0m is enabled * [47mx[0m is a tame term * all non-primitive function symbols in [47mx[0m have been warranted (whether the warrants are assumed or not), and * [47ma[0m is a [47mcons[0m term representing an alist on variables, then the following three actions are taken, * The [47mcons[0m term [47ma[0m is converted to a substitution, [47msigma[0m, and that substitution is extended to a substitution, [47msigma'[0m, by pairing with [47mnil[0m each variable of [47mx[0m that is unbound in [47msigma[0m. It should be observed that an unbound variable is assigned the value [47mnil[0m by the definitions of [47mev$[0m (actually, of [47massoc[0m). * The warrant for each non-primitive function in [47mx[0m is [force]d if possible unless the warrant is already assumed in the current context. * The [47m(ev$ x a)[0m term is rewritten to the result of recursively rewriting [47mx[0m under the substitution [47msigma'[0m. Note that this eliminates [47mev$[0m. If you see an [47mev$[0m of a quoted term in a checkpoint produced by the prover, you will know that one of the conditions above is not satisfied or that a necessary warrant could not be forced because forcing was disallowed or the warrant was assumed false in the context. If you would rather [47mev$[0m did not just disappear like this, disable [47m(:rewrite ev$-opener)[0m. This might be desirable if the expansion produces a lot of cases and you can prove the theorem without exposing them. Sometimes you may wish for [47mev$[0m to expand, but to do so step-by-step, gradually working its way down through [47mx[0m. Such behavior can be achieved by disabling [47mev$-opener[0m but enabling [47m(:definition ev$)[0m, which is disabled by default. However, the tentative application of the mutually recursive definitions of [47mev$[0m and [47mapply$[0m can be quite slow when dealing with moderately large [47mlambda[0m objects. Step-by-step expansion of [47mev$[0m can be accomplished by the alternative but generally faster method of disabling [47m(:rewrite ev$-opener)[0m, leaving [47m(:definition ev$)[0m disabled, but proving your own version of [47mev$-opener[0m under a different name. (defthm my-version-of-ev$-opener (and (implies (symbolp x) (equal (ev$ x a) (cdr (assoc x a)))) (equal (ev$ (list 'quote obj) a) obj) (implies (suitably-tamep-listp 3 nil args) (equal (ev$ (cons 'if args) a) (if (ev$ (car args) a) (ev$ (cadr args) a) (ev$ (caddr args) a)))) (implies (and (not (eq fn 'quote)) (not (eq fn 'if)) (tamep (cons fn args))) (equal (ev$ (cons fn args) a) (apply$ fn (ev$-list args a))))) :hints (("Goal" :use ev$-opener))). By having the [47mapply$[0m book's [47mev$-opener[0m disabled you shut off the special feature described above, and by having your own version of [47mev$-opener[0m enabled you push the [47mev$[0m through the quoted term with rewrite rules. This can sometimes help narrow down which of the conditions above is unsatisfied, especially if you modify your version of the rule so that the [47mtamep[0m and [47msuitably-tamep-listp[0m hypotheses are [47m[force][0md.") (rewriting-versus-cleaning-up-lambda-objects (rewrite) "why change the default action on rewriting [47mlambda[0m objects See [rewrite-lambda-object] and [47m[rewrite-lambda-object-actions][0m for background information on how the ACL2 rewriter behaves on certain quoted [47mlambda[0m objects. In this topic we discuss why you might want to change that behavior. There are three basic actions the rewriter might take when it encounters a suitable [47mlambda[0m object. * recursively rewrite the body to get a new body, by rewriting in the theory described in [47m[rewrite-lambda-objects-theory][0m * just clean it up syntactically, by rewriting in the theory described by [47m[syntactically-clean-lambda-objects-theory][0m, or * do nothing --- leave [47mlambda[0m object constants untouched. by rewriting in the theory described by [47m[hands-off-lambda-objects-theory][0m. The reason we have several options has to do with the representation of [47mlambda[0m objects as quoted constants in ACL2's first order logic. Distinct [47mlambda[0m objects are unequal and yet sometimes by rewriting their bodies to functionally equivalent terms under [47m[ev$][0m they can become identical. For example, [47m'(lambda (x) (+ 1 x))[0m and [47m'(lambda (x) (+ x 1))[0m are unequal list constants. But they are functionally equal and by rewriting their bodies we can make them identical. The problem is greatly magnified by the way [47mlambda$[0m and [47mloop$[0m expressions macroexpand into formal terms. Their expansions are complicated with guards and tags that play key roles in their Common Lisp compilation and execution efficiency within the ACL2 top-level read-eval-print loop. But those guards and tags are irrelevant to their logical meanings. By eliminating the guards and tags from quoted [47mlambda[0m objects in slots of [47m[ilk][0m [47m:FN[0m we increase the chances that different objects become identical. Consider the translation of a [47mthereis[0m [47mloop$[0m statement. The [47mthereis[0m [47mloop$[0m operand looks for an element of the range that satisfies a given predicate and returns the first non-[47mnil[0m value of that predicate. The predicate is formally a [47mlambda[0m object. Below we translate a [47mthereis[0m [47mloop$[0m and show the result. ACL2 !>:trans (loop$ for x on a thereis (if (equal (car x) b) x nil)) (RETURN-LAST 'PROGN '(LOOP$ FOR X ON A THEREIS (IF (EQUAL (CAR X) B) X NIL)) (THEREIS$+ '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (IF (TRUE-LISTP LOOP$-GVARS) (IF (EQUAL (LEN LOOP$-GVARS) '1) (IF (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) '1) 'NIL) 'NIL) 'NIL) :SPLIT-TYPES T) (IGNORABLE LOOP$-GVARS LOOP$-IVARS)) (RETURN-LAST 'PROGN '(LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 1) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 1)))) (LET ((B (CAR LOOP$-GVARS)) (X (CAR LOOP$-IVARS))) (DECLARE (IGNORABLE E X)) (IF (EQUAL (CAR X) B) X NIL))) ((LAMBDA (B X) (IF (EQUAL (CAR X) B) X 'NIL)) (CAR LOOP$-GVARS) (CAR LOOP$-IVARS)))) (CONS B 'NIL) (LOOP$-AS (CONS (TAILS A) 'NIL)))) => * The predicate being mapped is the quoted [47mlambda[0m object in the first argument of the [47mthereis$+[0m. When shorn of the logically irrelevant [47mDECLARE[0m and [47mRETURN-LAST[0m forms this particular quoted [47mlambda[0m object becomes '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) ((LAMBDA (B X) (IF (EQUAL (CAR X) B) X 'NIL)) (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) But now consider the closely related [47mthereis[0m [47mloop$[0m which is like the one translated above but uses different names for the variables. (loop$ for y on aaa thereis (if (equal (car y) bbb) y nil)) The [47mlambda[0m object representing the predicate in this [47mloop$[0m, when shorn of logically irrelevant material, is '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) ((LAMBDA (BBB Y) (IF (EQUAL (CAR Y) BBB) Y 'NIL)) (CAR LOOP$-GVARS) (CAR LOOP$-IVARS))) But note that this [47mlambda[0m object contains the ``variables'' [47mBBB[0m and [47mY[0m where the earlier one contained [47mB[0m and [47mX[0m. However, they are not really variables! They are symbol constants because they occur in quoted list constants. Thus, the [47mlambda[0m object generated for the first [47mthereis[0m [47mloop$[0m is different from the [47mlambda[0m object generated from the ``closely related'' one. They are just two different list constants. Thus, the translations of those two [47mthereis[0m [47mloop$[0ms are not instances of one another. So if you proved a rewrite rule about the [47m(loop$ for x on ...B...)[0m and then the rewriter encountered [47m(loop$ for y on ...BBB...)[0m the rule would not match. (By the way, this problem has nothing special to do with [47mthereis[0m [47mloop$[0ms. It happens on every kind of [47mloop$[0m because the problem has everything to do with representing [47mlambda[0m expressions as list constants.) Fortunately, it is sound to replace the body of a [47mlambda[0m object with one that is equivalent under [47m[ev$][0m. That can be done either by rewriting the body or by syntactically cleaning the body. It turns out that both rewriting and syntactic cleaning produce the same result in this case and reduce these two distinct [47mlambda[0m objects to this one. '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) (IF (EQUAL (CAR (CAR LOOP$-IVARS)) (CAR LOOP$-GVARS)) (CAR LOOP$-IVARS) 'NIL)) Actually, all that is needed in this case is the beta reduction of the two bodies. Syntactic cleaning eliminates declarations, guards, and other compiler-related tags introduced by translation of [47mlambda$[0m and [47mloop$[0m. It does beta reduction, which eliminates local variable names (other than the formals of the [47mlambda[0m object). And it replaces the last argument of calls of [47m[do$][0m by [47mnil[0m if that argument is a quoted constant other than [47mnil[0m. (That argument is irrelevant to the value of the [47mdo$[0m term and only used in error reporting.) The logical semantics of [47mloop$[0m is best understood not by looking at its translation as we did above but by looking at the result of syntactically cleaning its translation. That is done by the command [47m:[0m[47m[tc][0m. [47mTc[0m translates its argument, in this case the [47mloop$[0m statement we've been studying, obtaining the large form shown above, and then syntactically cleans it, returning the internal representation of the logical semantics. ACL2 !>:tc (loop$ for x on a thereis (if (equal (car x) b) x nil)) (THEREIS$+ '(LAMBDA (LOOP$-GVARS LOOP$-IVARS) (IF (EQUAL (CAR (CAR LOOP$-IVARS)) (CAR LOOP$-GVARS)) (CAR LOOP$-IVARS) 'NIL)) (CONS B 'NIL) (LOOP$-AS (CONS (TAILS A) 'NIL))) Note that the free variables of the term are [47mA[0m and [47mB[0m. The iteration variable, [47mx[0m of the [47mloop$[0m does not appear. Instances of this term are formed by choosing instantiations of [47mA[0m and [47mB[0m. (Note: The related command [47m:[0m[47m[tcp][0m translates, cleans, and then converts the internal form of the term into the ``pretty'' user-level syntax. E.g., it converts the quoted [47mLAMBDA[0m constant above to a [47mlambda$[0m expression, converts the [47mIF[0m expression to an [47mAND[0m, and converts the [47mCONS[0m terms into [47mLIST[0m terms. But for this discussion it is really better to see the internal form. That [47mLAMBDA[0m object above is really a list constant!) [31;1mBefore a newly proved [47m:[0m[31;1m[47m[rewrite][0m[31;1m or [47m:[0m[31;1m[47m[linear][0m[31;1m rule is stored, the conclusion is syntactically cleaned.[0m Like syntactic cleaning, rewriting eliminates declarations, guards, and other compiler-related tags and does beta reduction --- but these transformations are generally carried out by rules whose enabled status can be altered. Furthermore, rewriting applies [47m:rewrite[0m and other rules which might commute terms, open function definitions, etc. We don't rewrite the conclusions of newly proved rules simply because the enabled rules may change from one event (or subgoal) to another. As noted earlier, there are three basic actions the rewriter might take when it encounters a suitable [47mlambda[0m object. * recursively rewrite the body to get a new body, * just clean it up syntactically, or * do nothing --- leave [47mlambda[0m object constants untouched. Since rules are cleaned before storage, it is almost always the case that you will want the prover either to rewrite [47mlambda[0m objects or syntactically clean them. In simple cases, like a rule about the first [47mthereis[0m [47mloop$[0m above and a conjecture about the [47msecond[0m, either action by the prover reduces ``closely related'' [47mlambda[0m objects to identical objects, making it more likely that rules will fire. So which of the three actions do you want the rewriter to take when it encounters an eligible [47mlambda[0m object? * rewrite the body --- best if there are multiple [47mlambda[0m objects in the conjecture that need to be written to be identified, and in simple cases rewriting is equivalent to syntactic cleaning * syntactic cleaning --- best if you want the [47mlambda[0m objects in the conjecture to match [47m:rewrite[0m or [47m:linear[0m rules containing closely related [47mlambda[0m objects, but you find that otherwise necessary [47m:rewrite[0m rules cause the rewriter to ``overshoot'' the syntactically cleaned term as illustrated further below * hands off --- fairly unuseful since rules are cleaned up before storage. However, one use of this is if you prove a lemma containing a [47mlambda[0m object but store it with [47m:rule-classes nil[0m and then [47m:use[0m an instance of it in the [47m:hints[0m for some conjecture that involves the very same [47mlambda[0m objects. We now illustrate some typical problems that arise when proving theorems about [47mloop$[0ms. These examples are documented in the book [47mbooks/projects/apply/rewriting-versus-cleaning-examples[0m. [31;1mWhy you might want to use syntactic cleaning:[0m Suppose you prove the [47m:rewrite[0m rule below. It says that a certain [47mthereis[0m [47mloop$[0m computes the same answer as the function [47m[last][0m. (defthm loop$-can-be-last (implies (listp a) (equal (loop$ for x on a thereis (if (atom (cdr x)) x nil)) (last a)))) What term does this rule target? We can answer that by using the [47m:[0m[47m[tc][0m command. ACL2 !>:tc (loop$ for x on a thereis (if (atom (cdr x)) x nil)) (THEREIS$ '(LAMBDA (LOOP$-IVAR) (IF (ATOM (CDR LOOP$-IVAR)) LOOP$-IVAR 'NIL)) (TAILS A)) By the way, a more common way to see the rules created by an event is to use the [47m:[0m[47m[pr][0m command. But that command displays the terms of the rule in user-level syntax and we want to see the internal form here. The ``[47mlambda[0m expression'' is really a quoted constant. Now imagine you are proving a conjecture that involves that identical (!) [47mloop$[0m. Of course, translation will replace the [47mloop$[0m by a rather large tagged term containing compiler directives, etc. Shorn of that material the term would become the [47mthereis$[0m term above, but the translation is what is in the initial [47mGoal[0m. Imagine further that you're doing this proof in a theory that allows the rewriter to recursively rewrite the bodies of quoted [47mlambda[0m objects, i.e., you are in a theory as described by [47m[rewrite-lambda-objects-theory][0m. ACL2 starts up in such a theory and unless you've changed the enabled status of the [47mrewrite-lambda-modep[0m runes rewriting [47mlambda[0m objects is the default behavior. You might expect the [47mloop$-can-be-last[0m rule to fire and replace the [47mthereis$[0m term in the [47mGoal[0m by [47m(last a)[0m. But that will not happen! The rule won't fire! The reason is that before the rewriter rewrites the [47mthereis$[0m term it rewrites its arguments. The quoted [47mlambda[0m object in the Goal is rewritten first. That is necessary because the translated [47mloop$[0m contains tags, etc. But the rewriter does more than just clean up the body. It ``overshoots'' and opens the nonrecursive function [47matom[0m and swaps the branches of the [47mif[0m to eliminate the [47mnot[0m thus introduced. The quoted [47mlambda[0m object becomes '(LAMBDA (LOOP$-IVAR) (IF (CONSP (CDR LOOP$-IVAR)) 'NIL LOOP$-IVAR)) So when the rewriter then tries to rewrite the [47mthereis$[0m terms the quoted [47mlambda[0m object in the rule does not match the one in the rewritten [47mGoal[0m. If the rewritten goal is printed, as it is likely to be a checkpoint, you will see the rewritten body with the [47mconsp[0m instead of [47matom[0m in it. As usual, pay attention to the checkpoints. One way to respond to this problem would be to ``hobble'' the rewriter by shifting over to syntactic cleaning of quoted [47mlambda[0m objects. This could be done by providing a local subgoal hint in which you specify :in-theory (syntactically-clean-lambda-objects-theory) which would prevent the rewriter from diving into the bodies of [47mlambda[0m objects and just clean them instead. [31;1mWhy you should probably use rewriting:[0m There is a deeper lesson here than just that you might want to hobble the rewriter to prevent it from diving into quoted [47mlambda[0m bodies. In our view the actual problem is with the [47mloop$-can-be-last[0m rule itself. ACL2 users are taught to express rules in maximally rewritten terms. No experienced user would pose a rule with a non-recursive function like [47matom[0m in its lefthand side. The best response to this situation, which may or may not be practical depending on how [47mloop$-can-be-last[0m came to be a rule in the session, is to change that rule to (defthm loop$-can-be-last (implies (listp a) (equal (loop$ for x on a thereis (if (consp (cdr x)) nil x)) (last a)))) This version of the rule would not only rewrite the [47mthereis[0m [47mloop$[0m above but rewrites (loop$ for x on a thereis (if (atom (cdr x)) x nil)) because, as illustrated above, the rewriter by default dives into the translated [47mloop$[0m and ``normalizes'' the resulting [47mthereis$[0m. Furthermore, because [47mand[0m macroexpands to an [47mif[0m-term and beta reduction eliminates local variable names it would rewrite (loop$ for rest on (aaa aa) thereis (let ((z (cdr rest))) (and (atom z) rest)) [31;1mBut not all such problems can be solved by switching between rewriting quoted [47mlambda[0m[31;1m objects and just cleaning them up![0m Consider this rewrite rule. The [47mthereis[0m [47mloop$[0m in the lefthand side of the rule below is exactly the [47mloop$[0m whose translation we showed at the beginning of this topic. The cleaned up internal form of the lefthand side is the [47mthereis$+[0m term shown by the first [47m:tc[0m display in this topic. The rule below says that the [47mthereis[0m [47mloop$[0m in question computes [47mmember[0m. (defthm loop$-can-be-member (equal (loop$ for x on a thereis (if (equal (car x) b) x nil)) (member b a))) You might expect that when the rewriter encounters (an instance of) such a [47mloop$[0m it will replace it by a [47mmember[0m term. That is actually true! For example, if we then tried to prove a conjecture mentioning (loop$ for x on aaa thereis (if (equal (car x) bbb) x nil)) the [47mloop$-can-be-member[0m rule would fire and replace that [47mloop$[0m by [47m(member bbb aaa)[0m. But it is easy to misjudge whether a given [47mloop$[0m is an instance of another. Suppose our goal conjecture contained (loop$ for x on (aaa aa) thereis (if (equal (car x) (bbb bb)) x nil)) This [47mloop$[0m looks like the [47mloop$[0m in [47mloop$-can-be-member[0m except we've used [47m(aaa aa)[0m instead of [47ma[0m, and [47m(bbb bb)[0m instead of [47mb[0m. Will that [47mloop$[0m be rewritten to [47m(member (bbb v) (aaa u))[0m? No! To understand why not, we first have to compare the internal forms of the two [47mloop$[0ms. Recall that the lefthand side of rewrite rules are cleaned up before storage, so the internal form of the lefthand side of [47mloop$-can-be-member[0m is in fact the [47mthereis$+[0m term produced by [47m:tc[0m above. If we are either rewriting [47mlambda[0m objects or just syntactically cleaning [47mlambda[0m objects in the proof we're looking at, the the internal forms of the [47mloop$[0m in the conjecture will be just the [47m:tc[0m of that [47mloop$[0m (because there's nothing interesting to rewrite here). So here is the lefthand side of the rule side-by-side with the rewritten target in the conjecture. We have highlighted the differences in uppercase and numbered the lines that contain differences. lhs of rule target (thereis$+ (thereis$+ '(lambda '(lambda (loop$-gvars loop$-ivars) (loop$-gvars loop$-ivars) (if (equal (if (equal (car (car loop$-ivars)) (car (car loop$-ivars)) (CAR LOOP$-GVARS)) (BBB (CAR LOOP$-GVARS))) ; [1] (car loop$-ivars) (car loop$-ivars) 'nil)) 'nil)) (cons B 'nil) (cons BB 'nil) ; [2] (loop$-as (loop$-as (cons (tails A) 'nil))) (cons (tails (AAA AA)) 'nil))) ; [3] Note that the target is not an instance of the lefthand side of the rule --- but only because of the difference on line [1]. Lines [2] and [3] of the lefthand side can be instantiated to become those lines in the target. But because of [1] our [47mloop$-can-be-member[0m rule will not rewrite the target shown here. This kind of problem cannot be fixed by fiddling with how the prover treats [47mlambda[0m objects. Instead, we need to transform the target [47mlambda[0m object into the functionally different [47mlambda[0m object in the rule while simultaneously changing how [47mthereis$+[0m applies it. In particular we need to transform [47mtarget[0m to [47mtarget'[0m below by moving the [47mBBB[0m out of [1] and into [2] as shown below. target target' (thereis$+ (thereis$+ '(lambda '(lambda (loop$-gvars loop$-ivars) (loop$-gvars loop$-ivars) (if (equal (if (equal (car (car loop$-ivars)) (car (car loop$-ivars)) (BBB (CAR LOOP$-GVARS))) (CAR LOOP$-GVARS)) ; [1] (car loop$-ivars) (car loop$-ivars) 'nil)) 'nil)) (cons BB 'nil) (cons (BBB BB) 'nil) ; [2] (loop$-as (loop$-as (cons (tails (aaa aa)) 'nil))) (cons (tails (aaa aa)) 'nil))) Note that [47mtarget'[0m is in fact an instance of the lefthand side of the rule. But we've changed the semantics of the [47mlambda[0m object and changed the way [47mthereis$+[0m uses it by moving the [47mBBB[0m from the inside to the outside of the [47mlambda[0m. No [47mlambda[0m rewriting can do this. Instead, we need a rule that rewrites [47mthereis$+[0m. (In fact, a great project would be to implement a metafunction that does this kind of optimization for all [47mloop$[0m scions. We just haven't done that yet. Let us know if you do!) Here is a suitable rewrite rule for this particular instance of this phenomenon. We write it as a [47mthereis[0m [47mloop$[0m rule rather than a [47mthereis$+[0m, but they're the same. (defthm example-of-constant-subterm-abstraction (implies (warrant bbb) (equal (loop$ for xxx on a thereis (if (equal (car xxx) (bbb bb)) xxx nil)) (let ((zzz (bbb bb))) (loop$ for xxx on a thereis (if (equal (car xxx) zzz) xxx nil)))))) This illustrates another lesson. Remember that we're imagining a proof of some conjecture that involves a [47mthereis[0m [47mloop$[0m mentioning [47mBBB[0m and wondering whether our rewrite rule [47mloop$-can-be-member[0m will hit it. Had the [47mthereis[0m [47mloop$[0m in the conjecture been written in the style of the [47mlet[0m expression above, where a variable is bound to [47m(bbb bb)[0m and then that variable used in the [47mloop$[0m body, we wouldn't need to move the [47m(bbb bb)[0m out. Instead, the [47mlambda[0m generated by translating the [47mloop$[0m would contain a variable instead of [47m(bbb bb)[0m. The name of the [47mlet[0m-bound variable outside the [47mlambda[0m is irrelevant since it won't appear in the cleaned up [47mlambda[0m object where it is replaced by a component of the global variables [47mLOOP$-GVARS[0m. In the containing [47mthereis$+[0m the value of that global variable will be [47m(bbb bb)[0m, which means the free variable [47mb[0m in our [47mloop$-can-be-member[0m rule can be instantiated with [47m(bbb bb)[0m to allow the rule to match. Put another way, by writing the [47mloop$[0m in the inefficient way (requiring [47m(bbb bb)[0m to be recomputed on every iteration) we implicitly produce [47mlambda[0m object that is less general than one with the [47m(bbb bb)[0m on the outside. [31;1mKeep unchanging subterms of [47mloop$[0m[31;1m bodies as variables and compute their values outside of the [47mlambda[0m[31;1m.[0m Basically, try to write the most general [47mlambda[0m objects you can. Finally, these difficulties are exacerbated by the ease with which [47mloop$[0m statements can be written and the difference between their appearance and the formal terms they denote. You might be more successful at learning to use [47mloop$[0ms in lemmas and theorems if you simply [31;1mdon't use [47mloop$[0m[31;1m![0m Instead, learn to write the corresponding terms, e.g., try writing a [47mthereis$[0m or a [47mthereis$+[0m term instead of a [47mthereis[0m [47mloop$[0m statement in your lemmas and theorems. Since the prover's output contains such terms (rather than [47mloop$[0m statements), it will be easier to see where lemmas differ from the targets they were intended to hit. After enough practice you can write [47mloop$[0m statements with a better appreciation of what they actually denote.") (rfix (numbers acl2-built-ins) "Coerce to a rational number [47mRfix[0m simply returns any rational number argument unchanged, returning [47m0[0m on a non-rational argument. Also see [nfix], see [ifix], see [realfix], and see [fix] for analogous functions that coerce to a natural number, an integer, a real, and a number, respectively. [47mRfix[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<rfix> (defun rfix (x) (declare (xargs :guard t)) (if (rationalp x) x 0))") (rize (pointers) "See [df].") (round (numbers acl2-built-ins) "Division returning an integer by rounding off Example Forms: ACL2 !>(round 14 3) 5 ACL2 !>(round -14 3) -5 ACL2 !>(round 14 -3) -5 ACL2 !>(round -14 -3) 5 ACL2 !>(round 13 3) 4 ACL2 !>(round -13 3) -4 ACL2 !>(round 13 -3) -4 ACL2 !>(round -13 -3) 4 ACL2 !>(round -15 -3) 5 ACL2 !>(round 15 -2) -8 [47m(Round i j)[0m is the result of taking the quotient of [47mi[0m and [47mj[0m and rounding off to the nearest integer. When the quotient is exactly halfway between consecutive integers, it rounds to the even one. The [guard] for [47m(round i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real], in ACL2(r)) numbers and [47mj[0m is non-zero. [47mRound[0m is a Common Lisp function. See any Common Lisp documentation for more information. However, note that unlike Common Lisp, the ACL2 [47mround[0m function returns only a single value, [31;1mFunction: [0m<round> (defun round (i j) (declare (xargs :guard (and (real/rationalp i) (real/rationalp j) (not (eql j 0))))) (let ((q (* i (/ j)))) (cond ((integerp q) q) ((>= q 0) (let* ((fl (floor q 1)) (remainder (- q fl))) (cond ((> remainder 1/2) (+ fl 1)) ((< remainder 1/2) fl) (t (cond ((integerp (* fl (/ 2))) fl) (t (+ fl 1))))))) (t (let* ((cl (ceiling q 1)) (remainder (- q cl))) (cond ((< (- 1/2) remainder) cl) ((> (- 1/2) remainder) (+ cl -1)) (t (cond ((integerp (* cl (/ 2))) cl) (t (+ cl -1))))))))))") (rule-classes (acl2) "Adding rules to the database For an introduction to rule-classes, see [rule-classes-introduction]. Example Form (from community book finite-set-theory/total-ordering.lisp): (defthm <<-trichotomy (implies (and (ordinaryp x) (ordinaryp y)) (or (<< x y) (equal x y) (<< y x))) :rule-classes ((:rewrite :corollary (implies (and (ordinaryp x) (ordinaryp y) (not (<< x y)) (not (equal x y))) (<< y x))))) General Form: a true list of rule class objects as defined below Special Cases: a symbol abbreviating a single rule class object When [47m[defthm][0m is used to prove a named theorem, rules may be derived from the proved formula and stored in the database. The user specifies which kinds of rules are to be built, by providing a list of rule class [3mnames[0m or, more generally, rule class [3mobjects[0m, which name the kind of rule to build and optionally specify various attributes of the desired rule. The rule class names are [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[built-in-clause][0m, [47m:[0m[47m[clause-processor][0m, [47m:[0m[47m[compound-recognizer][0m, [47m:[0m[47m[congruence][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[elim][0m, [47m:[0m[47m[equivalence][0m, [47m:[0m[47m[forward-chaining][0m, [47m:[0m[47m[generalize][0m, [47m:[0m[47m[induction][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[meta][0m, [47m:[0m[47m[refinement][0m, [47m:[0m[47m[tau-system][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[type-set-inverter][0m, and [47m:well-founded-relation[0m (see [well-founded-relation-rule]). Some classes [3mrequire[0m the user-specification of certain class-specific attributes. Each class of rule affects the theorem prover's behavior in a different way, as discussed in the corresponding documentation topic. In this topic we discuss the various attributes that may be attached to rule classes. Note that not all [events] generate rules. For example, a [47m[defthm][0m event that specifies [47m:rule-classes nil[0m does not generate a rule. Similarly, a [47m[defchoose][0m event generates an axiom that can be referenced by name in [47m:use[0m [hints], but it does not generate a rule. A rule class object is either one of the [47m:class[0m keywords or else is a list of the form shown below. Those fields marked with ``(!)'' are required when the [47m:class[0m is as indicated. (:class :COROLLARY term :TRIGGER-FNS (fn1 ... fnk) ; provided :class = :META (!) :WELL-FORMEDNESS-GUARANTEE x ; provided :class = :META or :class = :CLAUSE-PROCESSOR :TRIGGER-TERMS (t1 ... tk) ; provided :class = :FORWARD-CHAINING ; or :class = :LINEAR :TYPE-SET n ; provided :class = :TYPE-SET-INVERTER :TYPED-TERM term ; provided :class = :TYPE-PRESCRIPTION :CLIQUE (fn1 ... fnk) ; provided :class = :DEFINITION :CONTROLLER-ALIST alist ; provided :class = :DEFINITION :INSTALL-BODY directive ; provided :class = :DEFINITION :LOOP-STOPPER alist ; provided :class = :REWRITE or :class = :REWRITE-QUOTED-CONSTANT :PATTERN term ; provided :class = :INDUCTION (!) :CONDITION term ; provided :class = :INDUCTION :SCHEME term ; provided :class = :INDUCTION (!) :MATCH-FREE all-or-once ; provided :class = :REWRITE ; or :class = :LINEAR ; or :class = :FORWARD-CHAINING :BACKCHAIN-LIMIT-LST limit ; provided :class = :REWRITE ; or :class = :META ; or :class = :LINEAR ; or :class = :TYPE-PRESCRIPTION :HINTS hints ; provided instrs = nil :INSTRUCTIONS instrs ; provided hints = nil :OTF-FLG flg) When rule class objects are provided by the user, most of the fields are optional and their values are computed in a context sensitive way. When a [47m:class[0m keyword is used as a rule class object, all relevant fields are determined contextually. Each rule class object in [47m:rule-classes[0m causes one or more rules to be added to the database. The [47m:class[0m keywords are documented individually under the following names. Note that when one of these names is used as a [47m:class[0m, it is expected to be in the keyword package (i.e., the names below should be preceded by a colon but the ACL2 [documentation] facilities do not permit us to use keywords below). See also [47m[force][0m, [case-split], [47m[syntaxp][0m, and [47m[bind-free][0m for ``pragmas'' one can wrap around individual hypotheses of certain classes of rules to affect how the hypothesis is relieved. Before we get into the discussion of rule classes, let us return to an important point. In spite of the large variety of rule classes available, at present we recommend that new ACL2 users rely almost exclusively on (conditional) rewrite rules. A reasonable but slightly bolder approach is to use [47m:[0m[47m[type-prescription][0m and [47m:[0m[47m[forward-chaining][0m rules for ``type-theoretic'' rules, especially ones whose top-level function symbol is a common one like [47m[true-listp][0m or [47m[consp][0m; see [type-prescription] and see [forward-chaining]. However, the rest of the rule classes are really not intended for widespread use, but rather are mainly for experts. When in doubt, create a [47m:[0m[47m[rewrite][0m rule, which is the default. See [rule-classes-introduction]. [47m:Rule-classes[0m is an optional keyword argument of the [47m[defthm][0m (and [47m[defaxiom][0m) event. In the following, let [47mname[0m be the name of the event and let [47mthm[0m be the formula to be proved or added as an axiom. If [47m:rule-classes[0m is not specified in a [47m[defthm][0m (or [47m[defaxiom][0m) event, it is as though what was specified was to make one or more [47m:[0m[47m[rewrite][0m rules, i.e., as though [47m:rule-classes[0m [47m((:rewrite))[0m had been used. Use [47m:rule-classes[0m [47mnil[0m to specify that no rules are to be generated. If [47m:rule-classes[0m class is specified, where class is a non-[47mnil[0m symbol, it is as though [47m:rule-classes[0m [47m((class))[0m had been used. Thus, [47m:rule-classes[0m [47m:[0m[47m[forward-chaining][0m is equivalent to [47m:rule-classes[0m [47m((:forward-chaining))[0m. We therefore now consider [47m:rule-classes[0m as a true list. If any element of that list is a keyword, replace it by the singleton list containing that keyword. Thus, [47m:rule-classes[0m [47m(:rewrite :elim)[0m is the same as [47m:rule-classes[0m [47m((:rewrite) (:elim))[0m. Each element of the expanded value of [47m:rule-classes[0m must be a true list whose [47m[car][0m is one of the rule class keyword tokens listed above, e.g., [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[elim][0m, etc., and whose [47m[cdr][0m is a ``keyword alist'' alternately listing keywords and values. The keywords in this alist must be taken from those shown below. They may be listed in any order and most may be omitted, as specified below. [47m:[0m[47m[Corollary][0m --- its value, [47mterm[0m, must be a term. If omitted, this field defaults to [47mthm[0m. The [47m:[0m[47m[corollary][0m of a rule class object is the formula actually used to justify the rule created and thus determines the form of the rule. Nqthm provided no similar capability: each rule was determined by [47mthm[0m, the theorem or axiom added. ACL2 permits [47mthm[0m to be stated ``elegantly'' and then allows the [47m:[0m[47m[corollary][0m of a rule class object to specify how that elegant statement is to be interpreted as a rule. For the rule class object to be well-formed, its (defaulted) [47m:[0m[47m[corollary][0m, [47mterm[0m, must follow from [47mthm[0m. Unless [47mterm[0m follows trivially from [47mthm[0m using little more than propositional logic, the formula [47m(implies thm term)[0m is submitted to the theorem prover and the proof attempt must be successful. During that proof attempt the values of [47m:[0m[47m[hints][0m, [47m:[0m[47m[instructions][0m, and [47m:[0m[47m[otf-flg][0m, as provided in the rule class object, are provided as arguments to the prover. Such auxiliary proofs give the sort of output that one expects from the prover. However, as noted above, corollaries that follow trivially are not submitted to the prover; thus, such corollaries cause no prover output. Note that no rule is stored for the theorem until all corollaries have been proved. Note that before [47mterm[0m is stored, all calls of macros in it are expanded away. See [trans]. [47m:[0m[47m[Hints][0m, [47m:[0m[47m[instructions][0m, [47m:[0m[47m[otf-flg][0m --- the values of these fields must satisfy the same restrictions placed on the fields of the same names in [47m[defthm][0m. These values are passed to the recursive call of the prover used to establish that the [47m:[0m[47m[corollary][0m of the rule class object follows from the theorem or axiom [47mthm[0m. [47m:[0m[47m[Type-set][0m --- this field may be supplied only if the [47m:class[0m is [47m:[0m[47m[type-set-inverter][0m. When provided, the value must be a type-set, an integer in a certain range. If not provided, an attempt is made to compute it from the corollary. See [type-set-inverter]. [47m:Typed-term[0m --- this field may be supplied only if the [47m:class[0m is [47m:[0m[47m[type-prescription][0m. When provided, the value is the term for which the [47m:[0m[47m[corollary][0m is a type-prescription lemma. If no [47m:typed-term[0m is provided in a [47m:[0m[47m[type-prescription][0m rule class object, we try to compute heuristically an acceptable term. See [type-prescription]. [47m:Trigger-terms[0m --- this field may be supplied only if the [47m:class[0m is [47m:[0m[47m[forward-chaining][0m or [47m:[0m[47m[linear][0m. When provided, the value is a list of terms, each of which is to trigger the attempted application of the rule. If no [47m:trigger-terms[0m is provided, we attempt to compute heuristically an appropriate set of triggers. See [forward-chaining] or see [linear]. [47m:Trigger-fns[0m --- this field must (and may only) be supplied if the [47m:class[0m is [47m:[0m[47m[meta][0m. Its value must be a list of function symbols (except that a macro alias can stand in for a function symbol; see [add-macro-alias]). Terms with these symbols trigger the application of the rule. See [meta]. [47m:Well-formedness-guarantee[0m --- this field may be supplied only if the [47m:class[0m is [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m. Its value must be of one of the following forms: [1] thm-name1 ; :META or :CLAUSE-PROCESSOR rules [2] (thm-name1) ; :META rules [3] (thm-name1 thm-name2) ; :META rules where [47mthm-name1[0m and [47mthm-name2[0m are the names of previously proved theorems establishing that the results of applying the metafunction(s) or clause-processor will be syntactically well-formed. See [47m:[0m[meta] and [47m:[0m[clause-processor] for details of the required forms of these well-formedness theorems. Forms [1] and [2] may be used for [47m:meta[0m rules where no hypothesis metafunction is involved. Form [3] must be used for [47m:meta[0m rules with hypothesis metafunctions; that is, if you provide a well-formedness guarantee for a metatheorem with a hypothesis metafunction you must guarantee the well-formedness of both the metafunction (with [47mthm-name1[0m) and the hypothesis metafunction (with [47mthm-name2[0m). Form [1] must be used for [47m:clause-processor[0m rules. In the absence of a proper [47m:well-formedness-guarantee[0m the well-formedness of the output of a both kinds of rules is checked every time the rule is fired. These checks are skipped when a proper [47m:well-formedness-guarantee[0m is provided or when overridden as described in [47m[set-skip-meta-termp-checks][0m. [47m:Clique[0m and [47m:controller-alist[0m --- these two fields may only be supplied if the [47m:class[0m is [47m:[0m[47m[definition][0m. If they are omitted, then ACL2 will attempt to guess them. Suppose the [47m:[0m[47m[corollary][0m of the rule is [47m(implies hyp (equiv (fn a1 ... an) body))[0m. The value of the [47m:clique[0m field should be a true list of function symbols, and if non-[47mnil[0m must include [47mfn[0m. These symbols are all the members of the mutually recursive clique containing this definition of [47mfn[0m. That is, a call of any function in [47m:clique[0m is considered a ``recursive call'' for purposes of the expansion heuristics. The value of the [47m:controller-alist[0m field should be an alist that maps each function symbol in the [47m:clique[0m to a list of [47mt[0m's and [47mnil[0m's of length equal to the arity of the function. For example, if [47m:clique[0m consists of just two symbols, [47mfn1[0m and [47mfn2[0m, of arities [47m2[0m and [47m3[0m respectively, then [47m((fn1 t nil) (fn2 nil t t))[0m is a legal value of [47m:controller-alist[0m. The value associated with a function symbol in this alist is a ``mask'' specifying which argument slots of the function ``control'' the recursion for heuristic purposes. Sloppy choice of [47m:clique[0m or [47m:controller-alist[0m can result in infinite expansion and stack overflow. [47m:Install-body[0m --- this field may only be supplied if the [47m:class[0m is [47m:[0m[47m[definition][0m. Its value must be [47mt[0m, [47mnil[0m, or the default, [47m:normalize[0m. A value of [47mt[0m or [47m:normalize[0m will cause ACL2 to install this rule as the new body of the function being ``defined'' ([47mfn[0m in the paragraph just above); hence this definition will be installed for future [47m:expand[0m [hints]. Furthermore, if this field is omitted or the value is [47m:normalize[0m, then this definition will be simplified with the [normalization] procedure that is used by default when processing definitions made with [47m[defun][0m. You must explicitly specify [47m:install-body nil[0m in the following cases: the arguments are not a list of distinct variables, [47mequiv[0m (as above) is not [47m[equal][0m, or there are free variables in the hypotheses or right-hand side (see [free-variables]). However, supplying [47m:install-body nil[0m will not affect the rewriter's application of the [47m:definition[0m rule, other than to avoid using the rule to apply [47m:expand[0m hints. If a definition rule equates [47m(f a1 ... ak)[0m with [47mbody[0m but there are hypotheses, [47mhyps[0m, then [47m:expand[0m [hints] will replace terms [47m(f term1 ... termk)[0m by corresponding terms [47m(if hyps body (hide (f term1 ... termk)))[0m. [47m:[0m[47m[Loop-stopper][0m --- this field may only be supplied if the class is [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[rewrite-quoted-constant][0m. Its value must be a list of entries each consisting of two variables followed by a (possibly empty) list of function symbols, for example [47m((x y binary-+) (u v foo bar))[0m. It will be used to restrict application of rewrite rules by requiring that the list of instances of the second variables must be ``smaller'' than the list of instances of the first variables in a sense related to the corresponding functions listed; see [loop-stopper]. The list as a whole is allowed to be [47mnil[0m, indicating that no such restriction shall be made. Note that any such entry that contains a variable not being instantiated, i.e., not occurring on the left side of the rewrite rule, will be ignored. However, for simplicity we merely require that every variable mentioned should appear somewhere in the corresponding [47m:[0m[47m[corollary][0m formula. [47m:Pattern[0m, [47m:Condition[0m, [47m:Scheme[0m --- the first and last of these fields must (and may only) be supplied if the class is [47m:[0m[47m[induction][0m. [47m:Condition[0m is optional but may only be supplied if the class is [47m:[0m[47m[induction][0m. The values must all be terms and indicate, respectively, the pattern to which a new induction scheme is to be attached, the condition under which the suggestion is to be made, and a term which suggests the new scheme. See [induction]. [47m:Match-free[0m --- this field must be [47m:all[0m or [47m:once[0m and may be supplied only if the [47m:class[0m is either [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, or [47m:[0m[47m[forward-chaining][0m. (This field is not implemented for other rule classes, including the [47m:[0m[47m[type-prescription][0m rule class.) See [free-variables] for a description of this field. Note: Although this field is intended to be used for controlling retries of matching free variables in hypotheses, it is legal to supply it even if there are no such free variables. This can simplify the automated generation of rules, but note that when [47m:match-free[0m is supplied, the warning otherwise provided for the presence of free variables in hypotheses will be suppressed. [47m:Backchain-limit-lst[0m --- this field may be supplied only if the [47m:class[0m is either [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[meta][0m, [47m:[0m[47m[linear][0m, or [47m:[0m[47m[type-prescription][0m. It is further required that either only one rule is generated from the formula or, at least, every such rule has the same list of hypotheses. The value for [47m:backchain-limit-lst[0m must be [47mnil[0m; a non-negative integer; or, except in the case of [47m:[0m[47m[meta][0m rules, a true list each element of which is either [47mnil[0m or a non-negative integer. If it is a list, its length must be equal to the number of hypotheses of the rule and each item in the list is the ``backchain limit'' associated with the corresponding hypothesis. If [47mbackchain-limit-lst[0m is a non-negative integer, it is defaulted to a list of the appropriate number of repetitions of that integer. The backchain limit of a hypothesis is used to limit the effort that ACL2 will expend when relieving the hypothesis. If it is [47mNIL[0m, no new limits are imposed; if it is an integer, the hypothesis will be limited to backchaining at most that many times. Note that backchaining may be further limited by a global [47mbackchain-limit[0m; see [backchain-limit] for details. For different ways to reign in the rewriter, see [rewrite-stack-limit] and see [set-prover-step-limit]. Jared Davis has pointed out that you can set the [47m:backchain-limit-lst[0m to 0 to avoid any attempt to relieve [47m[force][0md hypotheses, which can lead to a significant speed-up in some cases. Once [47mthm[0m has been proved (in the case of [47m[defthm][0m) and each rule class object has been checked for well-formedness (which might require additional proofs), we consider each rule class object in turn to generate and add rules. Let [47m:class[0m be the class keyword token of the [47mi[0mth class object (counting from left to right). Generate the [rune] [47m(:class name . x)[0m, where [47mx[0m is [47mnil[0m if there is only one class and otherwise [47mx[0m is [47mi[0m. Then, from the [47m:[0m[47m[corollary][0m of that object, generate one or more rules, each of which has the name [47m(:class name . x)[0m. See the [47m:[0m[47m[doc][0m entry for each rule class to see how formulas determine rules. Note that it is in principle possible for several rules to share the same name; it happens whenever a [47m:[0m[47m[corollary][0m determines more than one rule. This in fact only occurs for [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, and [47m:[0m[47m[forward-chaining][0m class rules and only then if the [47m:[0m[47m[corollary][0m is essentially a conjunction. (See the documentation for [rewrite], [linear], or [forward-chaining] for details.) Subtopics [Backchaining] Attempting to relieve the hypotheses of a rule [Built-in-clause] To build a [clause] into the simplifier [Clause-processor] Make or apply a [47m:clause-processor[0m rule (goal-level simplifier) [Compound-recognizer] Make a rule used by the typing mechanism [Congruence] The relations to maintain while simplifying arguments [Corollary] The corollary formula of a [rune] [Default-backchain-limit] Specifying the backchain limit for a rule [Definition] Make a rule that acts like a function definition [Elim] Make a destructor elimination rule [Equivalence] Mark a relation as an equivalence relation [Executable-counterpart] A rule for computing the value of a function [Forward-chaining] Make a rule to forward chain when a certain trigger arises [Free-variables] Free variables in rules [Generalize] Make a rule to restrict generalizations [Guard-holders] Remove trivial calls from a [term] [Induction] Make a rule that suggests a certain induction [Induction-heuristics] How ACL2 selects induction schemes [Linear] Make some arithmetic inequality rules [Meta] Make a [47m:meta[0m rule (a hand-written simplifier) [Patterned-congruence] Removing restrictions on classic [congruence] rules [Refinement] Record that one equivalence relation refines another [Rewrite] Make some [47m:rewrite[0m rules (possibly conditional ones) [Rewrite-quoted-constant] Make a rule to rewrite a quoted constant [Rule-classes-introduction] Selecting which kind of rule to create [Tau-system] Make a rule for the ACL2 ``type checker'' [Type-prescription] Make a rule that specifies the type of a term [Type-reasoning] ACL2 reasoning with ``types'' [Type-set-inverter] Exhibit a new decoding for an ACL2 type-set [Well-formedness-guarantee] Guarantee that a metafunction or clause-processor returns a well-formed answer [Well-founded-relation] Show that a relation is well-founded on a set [Well-founded-relation-rule] Show that a relation is well-founded on a set") (rule-classes-introduction (rule-classes) "Selecting which kind of rule to create Successful ACL2 users generally direct many of their proved theorems to be stored as rules, which can be applied automatically in subsequent proof attempts. See [rule-classes] for a detailed discussion of the kinds of rules that can be created. Here, we give a brief introduction to rule-classes that may suffice for most ACL2 users. The workhorse for ACL2 proof attempts is generally the application of [rewrite] rules. When you prove a theorem stated with [47m[defthm][0m, ACL2 stores it as a rewrite rule unless either the [47m:rule-classes[0m keyword is supplied explicitly or an error occurs because the theorem is not in a form that ACL2 knows how to store as a rewrite rule. See [rewrite] for an introduction to rewrite rules in ACL2. That topic also has links to useful introductory material as well as a notion of [congruence], which allows the rewriting of one term to another when the two are merely equivalent in some suitable sense, but not necessarily equal. Most successful ACL2 users make only sparing use of other kinds of rules besides rewrite rules. When in doubt, the default is probably best: the absence of any [47m:rule-classes[0m keyword in a [47m[defthm][0m event, which is equivalent to [47m:rule-classes :rewrite[0m. Below are some suggestions for when other kinds of rules might be appropriate. Of course, you are welcome to scan the [community-books] for examples. One can for example find many examples (apparently more than 15,000) of [47m:type-prescription[0m rules by standing in the [47mbooks/[0m directory and issuing the following shell command (Linux or MacOS): time egrep -e ':rule-classes .*type-prescription' --include='*.l*sp' -ri . Below, we sometimes speak of the ``conclusion'' of a formula. For many rule classes, this is simply the formula itself unless the formula is of the form [47m(implies hyp concl)[0m, in which case it is recursively the conclusion of [47mconcl[0m. See the subtopics of [rule-classes] for detailed documentation. * If the conclusion is a call of a primitive recognizer or a compound recognizer, or the negation of such --- for example, [47m(true-listp (f x y))[0m --- consider making a [type-prescription] rule. (For relevant background on recognizers, see [compound-recognizer], which also describes how to make a rule that designates a function as a compound-recognizer.) But note that hypotheses of such a rule are proved (``relieved'') by ACL2 only using type reasoning (see [TYPE-REASONING]). If you want rewriting to be used for relieving the hypotheses, you can wrap them in [47m[force][0m or [47m[case-split][0m. * If the conclusion is an inequality or negated inequality, consider making a [linear] rule, but generally only if you can identify a reasonable maximal term, which very roughly is a syntactically largest term that binds all the variables. For example, the formula [47m(< (f x y) (g y z))[0m might not make a good linear rule. For a more careful discussion of maximal terms, see [linear]. * If the formula is a term in normal form (not simplifiable by your rewrite rules) that tends to be an explicit hypothesis in some of your theorems, consider making it a [forward-chaining] rule. For example, if you are reasoning about a finite state machine (such as an interpreter) and your theorems tend to have the hypothesis [47m(good-state-p st)[0m, and your formula is [47m(good-state-p (foo st))[0m, then that formula is a good candidate for a [forward-chaining] rule. * If the rule looks like a recursive definition [47m(equal (f x1 x2 ..) (... (f ...) ...))[0m, consider making a [definition] rule. * When you want to control the simplifier rather than just turning rules (especially rewrite rules) loose on your terms, consider using [meta] rules or [clause-processor] rules. There are other rule classes that can be useful. See [rule-classes] for a complete list.") (rule-names (theories) "How rules are named. Examples: (:rewrite assoc-of-app) (:linear delta-aref . 2) (:definition length) (:executable-counterpart length) See [rune].") (ruler (pointers) "See [rulers].") (ruler-extenders (pointers) "See [rulers].") (rulers (defun) "Control for ACL2's termination and induction analyses [31;1mIntroduction[0m Consider the following recursive definition, which returns a list of threes of length one more than the length of [47mx[0m. (defun f (x) (cons 3 (if (consp x) (f (cdr x)) nil))) One might expect ACL2's termination analysis to admit this function, since we know that [47m(cdr x)[0m is ``smaller'' than [47mx[0m if [47m(consp x)[0m is true. (ACL2's notion of ``smaller'' here is essentially ordinary natural-number [47m<[0m, and the argument [47mx[0m is measured by applying function [47m[ACL2-count][0m to [47mx[0m; see [defun].) However, by default that termination analysis does not consider [47m[if][0m tests, like [47m(consp x)[0m above, when they occur under calls of functions other than [47mIF[0m, such as [47mCONS[0m in the case above; it considers only rulers, as we now discuss. In the example above, we say that the term [47m(consp x)[0m [3mgoverns[0m the recursive call [47m(f (cdr x))[0m shown above, but does not [3mrule[0m that call. Roughly speaking, the set of [3mgovernors[0m of a subterm occurrence in a given term consists of all superior [47mIF[0m tests and their negations that must be true in order for evaluation to reach that subterm; however, the set of [3mrulers[0m of the occurrence only includes, at least by default, those tests and their negations from the top-level [47mIF[0m structure of the term --- that is, tests and their negations that are collected by walking through the true and false branches of [47mIF[0m calls, starting at the top. Consider for example the following term, where [47mfoo[0m is assumed to be a function symbol. (if a (if (if b c d) e f) (if g (foo (if h i j)) k)) For the occurrence of [47mc[0m in that term, the only ruler is [47ma[0m; but both [47ma[0m and [47mb[0m are governors. For the occurrence of [47mi[0m, [47m(not a)[0m and [47mg[0m are the only rulers; but its governors are [47m(not a)[0m, [47mg[0m, and [47mh[0m. We have seen that for a subterm occurrence in a term, every ruler is a governor but not necessarily vice-versa. It is the rulers of a recursive call that affect its role in the termination and induction analysis for a function. One way to overcome the discrepancy between rulers and governors is to ``lift'' the [47mIF[0m test to the top level. We can apply that technique to the [47mdefun[0m of [47mf[0m above, so that now [47m(consp x)[0m is a ruler of the recursive call, and not merely a governor (though it remains a governor as well, of course). (defun f (x) (if (consp x) (cons 3 (f (cdr x))) (cons 3 nil))) But another way to overcome the problem is to tell ACL2 to extend its termination (and induction) analysis through calls of [47mcons[0m, as follows, by designating that calls of [47mcons[0m should not block the accumulation of rulers. (defun f (x) (declare (xargs :ruler-extenders (cons))) (cons 3 (if (consp x) (f (cdr x)) nil))) Let's look at one more (contrived) example: (defun g (x) (if (atom x) x (len (if (symbolp (car x)) (g (cddr x)) (g (cdr x)))))) There are two recursive calls, and the set of rulers is [47m{(not (atom x))}[0m for each of those. The set of governors for the first recursive call is [47m{(not (atom x)), (symbolp (car x))}[0m, and for the second, [47m{(not (atom x)), (not (symbolp (car x)))}[0m. The rulers is extended to be the governors in each case if we specify: [47m(declare (xargs :ruler-extenders (len)))[0m. You may even wish to provide value [47m:all[0m instead of an explicit list of ruler-extenders, so that no function call blocks the termination analysis: (defun f (x) (declare (xargs :ruler-extenders :all)) (cons 3 (if (consp x) (f (cdr x)) nil))) Alternatively, you can omit the [47mXARGS[0m [47m:RULER-EXTENDERS[0m form, instead modifying the global default set of ruler-extenders: (set-ruler-extenders :all) ; or, for example: (set-ruler-extenders '(cons return-last)) You can call the function [47m[default-ruler-extenders][0m as follows to see the current global default set of ruler-extenders: (default-ruler-extenders (w state)) We conclude this introduction by considering the handling of [47mLET[0m expressions by termination analysis. Consider the following example. (defun fact (n) (the (integer 1 *) (if (posp n) (* n (fact (1- n))) 1))) ACL2 treats the call of [47m[the][0m in the body of this definition as follows. (let ((var (if (posp n) (* n (fact (1- n))) 1))) (if (and (integerp var) (<= 1 var)) var <some_error>)) A [47m[let][0m expression, in turn, is treated as a [47m[lambda][0m application: ((lambda (var) (if (if (integerp var) (not (< var 1)) nil) var <some_error>)) (if (posp n) (* n (fact (1- n))) 1)) Notice that the [47m[posp][0m test, which governs the recursive call of [47mfact[0m, is inside an argument of a function application, namely the application of the [47mLAMBDA[0m expression. So by default, ACL2 will not consider this [47m[posp][0m test in its termination analysis. The keyword [47m:LAMBDAS[0m in the list of ruler-extenders denotes all calls of lambda expressions, much as the inclusion of [47mCONS[0m in the ruler-extenders denotes all calls of [47mCONS[0m. The following definition is thus accepted by ACL2. (defun fact (n) (declare (xargs :ruler-extenders (:lambdas))) (the (integer 1 *) (if (posp n) (* n (fact (1- n))) 1))) As a convenience, ACL2 allows the symbol [47m:lambdas[0m in place of [47m(:lambdas)[0m, and in fact the former will also include the three basic ruler-extenders: [47m[return-last][0m, which comes from macroexpansion of calls of [47m[prog2$][0m, [47m[ec-call][0m, and others; [47m[mv-list][0m; and [47m[if][0m, which affects termination analysis through the first argument of calls of [47mIF[0m (it continues through the true and false branches of these calls even without [47mIF[0m being among the ruler-extenders). IMPORTANT REMARKS. 1. Notice that the argument to [47mset-ruler-extenders[0m is evaluated, but the argument to [47m:RULER-EXTENDERS[0m in [47mXARGS[0m is not evaluated. 2. Do not put macro names in your list of ruler-extenders. For example, if you intend that [47m+[0m should not block the termination analysis, in analogy to [47mcons[0m in the example above, then the list of ruler-extenders should include [47mbinary-+[0m, not [47m+[0m. Of course, if you use [47m:all[0m then this is not an issue, but see the next remark. 3. Also please note that by taking advantage of the ruler-extenders, you may change the induction scheme computed for the function. This is especially worth remembering for functions containing [47m[let][0m or [47m[let*][0m expressions (which translate to [47m[lambda][0m applications; see [term]). If the induction scheme suggested by such a function seems to provide more induction hypotheses than appear necessary, it might help to admit the function with [47m:lambdas[0m included among the ruler extenders even if that is not necessary for the termination proof. This can cause the induction scheme to have a richer case analysis with fewer induction hypotheses on any given induction step. While this can make it more difficult for the system to merge induction schemes to get an appropriate induction, it can also make the proof of each induction step easier. Unfortunately, we have no more precise advice as to exactly when adding [47m:lambdas[0m will help. See [induction-coarse-v-fine-grained]. To see the ruler-extenders of an existing function symbol, [47mfn[0m, in a logical [world], [47mwrld[0m, evaluate [47m(get-ruler-extenders 'fn wrld)[0m after [47m(include-book "std/system/get-ruler-extenders" :dir :system)[0m. For example, evaluation of [47m(get-ruler-extenders 'fn (w state))[0m provides the ruler-extenders of [47mfn[0m in the current logical world. Below we describe the notion of ruler-extenders in detail, as well as how to set its default using [47mset-ruler-extenders[0m. [31;1mDetails[0m We begin by discussing how to set the ruler-extenders by using the macro [47mset-ruler-extenders[0m; below we will discuss the use of keyword [47m:ruler-extenders[0m in [47m[xargs][0m [47m[declare][0m forms. NOTE: The legal values discussed below for [47mset-ruler-extenders[0m are the same as the legal values for the [47m:ruler-extenders[0m [47m[xargs][0m keyword. Examples: (set-ruler-extenders :basic) ; return to default (set-ruler-extenders *basic-ruler-extenders*) ; same as immediately above (set-ruler-extenders :all) ; every governing IF test rules a recursive call (set-ruler-extenders :lambdas) ; LET does not block termination analysis (set-ruler-extenders (cons :lambdas *basic-ruler-extenders*)) ; same as immediately above (set-ruler-extenders '(f g)) ; termination analysis goes past calls of f, g General Form: (set-ruler-extenders val) where [47mval[0m evaluates to one of [47m:basic[0m, [47m:all[0m, [47m:lambdas[0m, or a true list of symbols containing no keyword other than, optionally, [47m:lambdas[0m. When a recursive definition is submitted to ACL2 (in [47m:[0m[47m[logic][0m mode), the recursion must be proved to terminate; see [defun]. More precisely, ACL2 explores the [47m[if][0m structure of the body of the definition to accumulate the tests that ``rule'' any given recursive call. The following example reviews how this works. Suppose that [47mf[0m has already been defined. (defun g (x y) (declare (xargs :measure (+ (acl2-count x) (acl2-count y)))) (if (consp x) (g (cdr x) y) (if (consp y) (f (g x (cdr y))) (f (list x y))))) ACL2 makes the following response to this proposed definition. Notice that the [47m:measure[0m proposed above must be proved to be an ACL2 ordinal --- that is, to satisfy [47mO-P[0m --- and that the arguments to each recursive call must be smaller (in the sense of that measure and [47mO<[0m, which here reduces to the ordinary [47m<[0m relation) than the formals under the assumption of the ruling [47mIF[0m tests. The first [47mIMPLIES[0m term below thus corresponds to the recursive call [47m(g (cdr x) y)[0m, while the second corresponds to the recursive call [47m(g x (cdr y))[0m. For the admission of G we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (+ (ACL2-COUNT X) (ACL2-COUNT Y)). The non-trivial part of the measure conjecture is Goal (AND (O-P (+ (ACL2-COUNT X) (ACL2-COUNT Y))) (IMPLIES (CONSP X) (O< (+ (ACL2-COUNT (CDR X)) (ACL2-COUNT Y)) (+ (ACL2-COUNT X) (ACL2-COUNT Y)))) (IMPLIES (AND (NOT (CONSP X)) (CONSP Y)) (O< (+ (ACL2-COUNT X) (ACL2-COUNT (CDR Y))) (+ (ACL2-COUNT X) (ACL2-COUNT Y))))). Now consider the following alternate version of the above definition. (defun g (x y) (declare (xargs :measure (+ (acl2-count x) (acl2-count y)))) (if (consp x) (g (cdr x) y) (f (if (consp y) (g x (cdr y)) (list x y))))) The first test, [47m(consp x)[0m, still rules the first recursive call, [47m(g (cdr x) y)[0m. And the negation of that test, namely [47m(not (consp x))[0m, still rules the second recursive call [47m(g x (cdr y))[0m. But the call of [47mf[0m blocks the top-down exploration of the [47mIF[0m structure of the body of [47mg[0m, so [47m(consp y)[0m does not rule that second recursive call, which (again) is [47m(g x (cdr y))[0m. As a result, ACL2 fails to admit the above definition. [47mSet-ruler-extenders[0m is provided to overcome the sort of blocking described above. Suppose for example that the following event is submitted: (set-ruler-extenders '(f)) Then the alternate definition of [47mg[0m above is admissible, because the call of [47mf[0m no longer blocks the top-down exploration of the [47mIF[0m structure of the body of [47mg[0m: that is, [47m(consp y)[0m becomes a ruler of the recursive call [47m(g x (cdr y))[0m. In this case, we say that [47mf[0m is a ``ruler-extender''. The same result obtains if we first submit (set-ruler-extenders :all) as this removes all function calls as blockers of the top-down analysis. In other words, with [47m:all[0m it is the case that for every recursive call, every test argument of a superior call of [47mIF[0m contributes a ruler of that recursive call. ACL2 handles [47m[let][0m (and [47m[let*][0m) expressions by translating them to [47mLAMBDA[0m expressions (see [term]). The next examples illustrates termination analysis involving such expressions. First consider the following (admittedly inefficient) definition. (defun fact (n) (let ((k (if (natp n) n 0))) (if (equal k 0) 1 (* k (fact (+ -1 k)))))) ACL2 translates the body of this definition to a [47mLAMBDA[0m application, essentially: ((lambda (k) (if (equal k 0) 1 (* k (fact (+ -1 k))))) (if (natp n) n 0)) As with the application of any function other than [47mIF[0m, the top-down termination analysis does not dive into arguments: the [47mLAMBDA[0m blocks the continuation of the analysis into its argument. But here, the argument of the [47mLAMBDA[0m is [47m(if (natp n) n 0)[0m, which has no recursive calls to consider anyhow. What is more interesting: ACL2 does continue its termination analysis into the body of the [47mLAMBDA[0m, in an environment binding the [47mLAMBDA[0m formals to its actuals. In this case, the termination analysis thus continues into the term (if (equal k 0) 1 (* k (fact (+ -1 k)))) in the environment that binds [47mk[0m to the term [47m(if (natp n) n 0)[0m. Thus, the proof obligation is successfully discharged, as reported by ACL2: For the admission of FACT we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT N). The non-trivial part of the measure conjecture is Goal (IMPLIES (NOT (EQUAL (IF (NATP N) N 0) 0)) (O< (ACL2-COUNT (+ -1 (IF (NATP N) N 0))) (ACL2-COUNT N))). ..... Q.E.D. That completes the proof of the measure theorem for FACT. But now consider the following definition, in which the recursion takes place inside the argument of the [47mLAMBDA[0m rather than inside the [47mLAMBDA[0m body. (defun app (x y) (let ((result (if (endp x) y (cons (car x) (app (cdr x) y))))) (if (our-test result) result 0))) Writing the body in [47mLAMBDA[0m notation: ((lambda (result) (if (our-test result) result 0)) (if (endp x) y (cons (car x) (app (cdr x) y)))) By default, the [47mLAMBDA[0m call blocks the top-down termination analysis from proceeding into the term [47m(if (endp x) ...)[0m. To solve this, one can submit the event: (set-ruler-extenders :lambdas) The above definition of [47mapp[0m is then admitted by ACL2, because the termination analysis is no longer blocked by the [47mLAMBDA[0m call. The example just above illustrates that the heuristically-chosen measure is suitably sensitive to the ruler-extenders. Specifically: that measure is the application of [47macl2-count[0m to the first formal parameter of the function that is tested along every branch of the relevant [47mIF[0m structure (as determined by the rulers) and occurs as a proper subterm at the same argument position in every recursive call. The heuristics for choosing the controller-alist for a [47m[definition][0m rule are similarly sensitive to the ruler-extenders (see [definition]). The remarks above for [47m[defun][0m [events] are equally applicable when a definition sits inside a [47m[mutual-recursion][0m event, except of course that in this case, a ``recursive call'' is a call of any function being defined by that [47m[mutual-recursion][0m event. Rules of class [47m:[0m[47m[definition][0m are sensitive to [47mset-ruler-extenders[0m in analogy to the case of [47mdefun[0m [events]. This macro generates a call [47m(table acl2-defaults-table :ruler-extenders val)[0m and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs. See [ACL2-defaults-table]. The current list of ruler-extenders may be obtained as (cdr (assoc-eq :ruler-extenders (table-alist 'acl2-defaults-table (w state)))) or more conveniently, as: (default-ruler-extenders (w state)) Note that evaluation of [47m(set-ruler-extenders lst)[0m, where [47mlst[0m evaluates to a list, does not necessarily include the default ruler-extenders --- i.e., those included for the argument, [47m:basic[0m --- which are the elements of the list constant [47m*basic-ruler-extenders*[0m, namely [47m[return-last][0m [47m[mv-list][0m, and [47m[if][0m. You may, of course, include these explicitly in your list argument. We conclude our discussion by noting that the set of ruler-extenders can affect the induction scheme that is stored with a recursive definition. The community book [47mbooks/misc/misc2/ruler-extenders-tests.lisp[0m explains how induction schemes are derived in this case. Consider the following example. (defun tree-of-nils-p (x) (if (consp x) (and (tree-of-nils-p (car x)) (tree-of-nils-p (cdr x))) (null x))) The above definition generates the following induction scheme. Note that [47m(and u v)[0m expands to [47m(if u v nil)[0m, which explains why the term [47m(tree-of-nils-p (car x))[0m rules the recursive call [47m(tree-of-nils-p (cdr x))[0m, resulting in the hypothesis [47m(tree-of-nils-p (car x))[0m in the final conjunct below. (AND (IMPLIES (NOT (CONSP X)) (:P X)) (IMPLIES (AND (CONSP X) (NOT (TREE-OF-NILS-P (CAR X))) (:P (CAR X))) (:P X)) (IMPLIES (AND (CONSP X) (TREE-OF-NILS-P (CAR X)) (:P (CAR X)) (:P (CDR X))) (:P X))) Now consider the following variant of the above definition, in which a call of the function [47midentity[0m blocks the termination analysis. (defun tree-of-nils-p (x) (if (consp x) (identity (and (tree-of-nils-p (car x)) (tree-of-nils-p (cdr x)))) (null x))) This time the induction scheme is as follows, since only the top-level [47mIF[0m test contributes rulers to the termination analysis. (AND (IMPLIES (NOT (CONSP X)) (:P X)) (IMPLIES (AND (CONSP X) (:P (CAR X)) (:P (CDR X))) (:P X))) But now suppose we first designate [47midentity[0m as a ruler-extender. (set-ruler-extenders '(identity)) Then the induction scheme generated for the both of the above variants of [47mtree-of-nils-p[0m is the one shown for the first variant, which is reasonable because both definitions now produce essentially the same termination analysis. Subtopics [Default-ruler-extenders] The default [ruler-extenders] for [47m[defun][0m'd functions [Induction-coarse-v-fine-grained] advice on case explosion in complex inductions") (rune (theories) "A rule name Examples: (:rewrite assoc-of-app) (:linear delta-aref . 2) (:definition length) (:executable-counterpart length) Note: This topic discusses a basic notion of ``rule name'', or ``rune'' for short. Users often use abbreviations for runes; for example, a [theory] expression [47m(DISABLE APPEND)[0m abbreviates the following set of runes: [47m{(:DEFINITION BINARY-APPEND), (:INDUCTION BINARY-APPEND)}[0m. See [theories] for a discussion of so-called ``runic designators'', which include expressions like [47mAPPEND[0m (as above) as well as [47m(APPEND)[0m (for the [executable-counterpart] of [47mBINARY-APPEND[0m). Runic designators can also be ``runic abbreviations'' such as [47m(:d APPEND)[0m, [47m(:e APPEND)[0m, [47m(:i APPEND)[0m, and [47m(:t APPEND)[0m, which designate the definition, executable-counterpart, induction, and type-prescription rules for [47mBINARY-APPEND[0m. For a complete description of runic designators, see [theories]; we return now to the more basic notion of a rune. Background: The theorem prover is driven from a database of rules. The most common rules are [47m:[0m[47m[rewrite][0m rules, which cause the simplifier to replace one term with another. [Events] introduce rules into the database. For example, a [47m[defun][0m event may introduce runes for symbolically replacing a function call by its instantiated body, for evaluating the function on constants, for determining the type of a call of the function, and for the induction scheme introduced upon defining the function. [47m[Defthm][0m may introduce several rules, one for each of the [47m:[0m[47m[rule-classes][0m specified (where one rule class is specified if [47m:[0m[47m[rule-classes][0m is omitted, namely, [47m:rewrite[0m). Every rule in the system has a name. Each name is a structured object called a ``rune,'' which is short for ``rule name''. Runes are always of the form [47m(:token symbol . x)[0m, where [47m:token[0m is some keyword symbol indicating what kind of rule is named, [47msymbol[0m is the event name that created the rule (and is called the ``base symbol'' of the rune), and [47mx[0m is either [47mnil[0m or a natural number that makes the rule name distinct from that of rules generated by other [events] or by other [47m:[0m[47m[rule-classes][0m within the same event. For example, an event of the form (defthm name thm :rule-classes ((:REWRITE :COROLLARY term1) (:REWRITE :COROLLARY term2) (:ELIM :COROLLARY term3))) typically creates three rules, each with a unique rune. The runes are (:REWRITE name . 1), (:REWRITE name . 2), and (:ELIM name). However, a given formula may create more than one rule, and all rules generated by the same [47m:corollary[0m formula will share the same rune. Consider the following example. (defthm my-thm (and (equal (foo (bar x)) x) (equal (bar (foo x)) x))) This is treated identically to the following. (defthm my-thm (and (equal (foo (bar x)) x) (equal (bar (foo x)) x)) :rule-classes ((:rewrite :corollary (and (equal (foo (bar x)) x) (equal (bar (foo x)) x))))) In either case, two rules are created: one rewriting [47m(foo (bar x))[0m to [47mx[0m, and one rewriting [47m(bar (foo x))[0m to [47mx[0m. However, only a single rune is created, [47m(:REWRITE MY-THM)[0m, because there is only one rule class. But now consider the following example. (defthm my-thm2 (and (equal (foo (bar x)) x) (equal (bar (foo x)) x)) :rule-classes ((:rewrite :corollary (and (equal (foo (bar x)) x) (equal (bar (foo x)) x))) (:rewrite :corollary (and (equal (foo (bar (foo x))) (foo x)) (equal (bar (foo (bar x))) (bar x)))))) This time there are four rules created. The first two rules are as before, and are assigned the rune [47m(:REWRITE MY-THM . 1)[0m. The other two rules are similarly generated for the second [47m:corollary[0m, and are assigned the rune [47m(:REWRITE MY-THM . 2)[0m. The function [47m[corollary][0m will return the [corollary] term associated with a given rune in a given [world]. Example: (corollary '(:TYPE-PRESCRIPTION DIGIT-TO-CHAR) (w state)) However, the preferred way to see the corollary term associated with a rune or a name is to use [47m:pf[0m; see [pf]. The [47m[defun][0m event creates as many as four rules. [47m(:definition fn)[0m is the rune given to the equality axiom defining the function, [47mfn[0m. [47m(:executable-counterpart fn)[0m is the rune given to the rule for computing [47mfn[0m on known arguments. A type prescription rule may be created under the name [47m(:type-prescription fn)[0m, and an [induction] rule may be created under the name [47m(:induction fn)[0m. Runes may be individually [enable]d and [disable]d, according to whether they are included in the current theory. See [theories]. Thus, it is permitted to [disable] [47m(:elim name)[0m, say, while enabling the other rules derived from name. Similarly, [47m(:definition fn)[0m may be [disable]d while [47m(:executable-counterpart fn)[0m and the type prescriptions for [47mfn[0m are [enable]d. Associated with most runes is the formula justifying the rule named. This is called the ``[corollary] formula'' of the rune and may be obtained via the function [47m[corollary][0m, which takes as its argument a rune and a property list [world]. Also see [pf]. The [corollary] formula for [47m(:rewrite name . 1)[0m after the [47m[defthm][0m event above is [47mterm1[0m. The corollary formulas for [47m(:definition fn)[0m and [47m(:executable-counterpart fn)[0m are always identical: the defining axiom. Some runes, e.g., [47m(:definition car)[0m, do not have corollary formulas. [47m[Corollary][0m returns [47mnil[0m on such runes. In any case, the corollary formula of a rune, when it is non-[47mnil[0m, is a theorem and may be used in the [47m:use[0m and [47m:by[0m [hints]. Note: The system has built-in rules that, for regularity, ought to have names but don't because they can never be [disable]d. One such rule is that implemented by the [linear] arithmetic package. Because many of our subroutines are required by their calling conventions to return the justifying rune, we have invented the notion of ``fake runes.'' Fake runes always have the base symbol [47mnil[0m, use a keyword token that includes the phrase ``fake-rune'', and are always [enable]d. Here is the list of fake runes. ((:fake-rune-for-linear nil) (:fake-rune-for-linear-equalities nil) (:fake-rune-for-type-set nil) (:fake-rune-for-cert-data nil)) Occasionally the system will print a fake rune where a rune is expected. For example, when [47m(:FAKE-RUNE-FOR-LINEAR NIL)[0m is reported among the rules used in a proof, it is an indication that the linear arithmetic package was used. However, fake runes are not allowed in [theories], they cannot be [enable]d or [disable]d, and they do not have associated [corollary] formulas. In short, despite the fact that the user may sometimes see fake runes printed, they should never be typed. Subtopics [Find-rules-of-rune] Find the rules named rune") (runes-diff (pointers) "See [saving-event-data].") (running-acl2-without-executable (installation-support) "Running ACL2 without building an executable image The most convenient way to use ACL2 is first to install an executable image; see [creating-executable]. However, in some cases this is not possible, for example, perhaps if you are using a trial version of a Common Lisp implementation. In that case you should follow the steps below each time you want to start up ACL2. We assume you have obtained ACL2 and placed it in your current directory. Start up your Common Lisp in that directory, and compile by executing the following forms. [3mThis sequence of steps needs to be performed only once.[0m (load "init.lisp") (in-package "ACL2") (compile-acl2) Now each time you want to use ACL2, execute the following forms after starting up Common Lisp in that same directory. This may take a minute or two. (load "init.lisp") (in-package "ACL2") (load-acl2) (initialize-acl2) (lp) ; enter the ACL2 read-eval-print loop Now see [using-ACL2].") (running_models (pages_written_especially_for_the_tours) "Running Models {IMAGE} (see [Symbolic_Execution_of_Models]) Suppose the machine being modeled is some kind of arithmetic unit. Suppose the model can be initialized so as to [31;1mmultiply[0m [31;1mx[0m times [31;1my[0m and leave the answer in [31;1mz[0m. Then if we initialize [31;1ms[0m to [31;1mmultiply[0m with [31;1mx=5[0m and [31;1my=7[0m and run the machine long enough, we can read the answer [31;1m35[0m in the final state. {IMAGE} Because ACL2 is a programming language, our model can be [31;1mrun[0m or [31;1mexecuted[0m. If you defined the model in ACL2 and then typed (lookup 'z (mc (s 'mult 5 7) 29)) then ACL2 would compute 35. (Here we assume that the function [47ms[0m creates a state ready to run a given application on given inputs [47mx[0m and [47my[0m.) You can [31;1memulate[0m or [31;1mtest[0m the model of your machine. This is [31;1mobvious[0m because ACL2 is Common Lisp; and Common Lisp is a [31;1mprogramming language[0m. {IMAGE} (see [Symbolic_Execution_of_Models])") (rw-cache (pointers) "See [set-rw-cache-state].") (rw-cache-state (rewrite) "The current rw-cache-state See [47m[set-rw-cache-state][0m for background on the [3mrw-cache[0m, which saves failed attempts to apply conditional [rewrite] rules. To get the current rw-cache-state, evaluate the following form. (rw-cache-state (w state))") (safe-mode (guard macros) "A mode that avoids [guard] violations on [primitive]s ACL2 has a special mode, called ``safe mode'', that guarantees that built-in ACL2 [primitive]s check their [guard]s even even when [47m[set-guard-checking][0m has turned off guard-checking. This mode is used for macroexpansion as well as in processing a few other kinds of forms, notably [47m[defconst][0m, [47m[defpkg][0m, and [47m[value-triple][0m events. Use of this mode avoids the possibility of certain errors when loading a compiled file for a book. Consider the following definitions. (defun foo (x) (declare (xargs :guard (consp x))) (car x)) (defmacro bar () (foo 3)) Then we can see [47msafe-mode[0m in action as follows. ACL2 !>(set-guard-checking nil) Masking guard violations but still checking guards except for self- recursive calls. To avoid guard checking entirely, :SET-GUARD-CHECKING :NONE. See :DOC set-guard-checking. ACL2 >(bar) ACL2 Error in TOP-LEVEL: In the attempt to macroexpand the form (BAR), evaluation of the macro body caused the following error: The guard for the function call (CAR X), which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CAR 3). The guard is being checked because this function is a primitive and a "safe" mode is being used for defconst, defpkg, macroexpansion, or another operation where safe mode is required. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 > Notice that because of the [47mset-guard-checking[0m call above, no guard violation was reported for [47mfoo[0m. However, [47msafe-mode[0m caused the call of the [primitive], [47m[car][0m, to be guard-checked, and a violation was reported. To understand how safe-mode works we refer to the notion of ``executable-counterpart''; see [evaluation] for relevant background. ACL2 arranges for that for the executable-counterpart of any program mode function, [47mF[0m, then for every called subroutine [47mG[0m of [47mF[0m that is in program mode, the executable-counterpart of [47mG[0m is called rather than the raw Lisp function for [47mG[0m. This may result in an attempt to evaluate a so-called ``[program-only]'' function in safe-mode, which is illegal. See [safe-mode-cheat-sheet] for possible workarounds. Subtopics [Safe-mode-cheat-sheet] Working around ``[program-only]'' issues") (safe-mode-cheat-sheet (safe-mode) "Working around ``[program-only]'' issues This cheat sheet gives workarounds for errors caused by attempts to evaluate executable-counterparts (see [evaluation]) of so-called [program-only] functions. This most often occurs when [safe-mode] is active. Recall that safe-mode can be set by [47m(assign safe-mode t)[0m, and also is used during macroexpansion and other logical acts that might involve [47m:[0m[47m[program][0m mode functions. The problems manifest with a hard error like this: HARD ACL2 ERROR in PROGRAM-ONLY: The call <term> is an illegal call of a function that has been marked as ``program- only,'' presumably because it has special raw Lisp code and safe-mode is active. See :DOC program-only for further explanation and a link to possible workarounds. (See :DOC set-iprint to be able to see elided values in this message.) When the term is a call of [47mev-w[0m, an unsafe hack allowing such calls is as follows. Warning: This may result in unsoundness! (On a related note: For discussion about unsoundness when converting such [program]-mode functions to [logic] mode, see [program-only].) (value :q) (setf (symbol-function (*1*-symbol 'ev-w)) (symbol-function 'ev-w)) (lp) Typically that just leads to other similar errors and so you discover the call tree, each of whose functions can be handled similarly (also in raw Lisp): (setf (symbol-function (*1*-symbol 'ev-rec)) (symbol-function 'ev-rec)) (setf (symbol-function (*1*-symbol 'ev-fncall-rec)) (symbol-function 'ev-fncall-rec)) (setf (symbol-function (*1*-symbol 'push-warning)) (symbol-function 'push-warning)) Other times you may avoid the problem by defining your own utilities. For example, in safe-mode you can't use the utility [47m[without-evisc][0m (which is useful when [iprint]ing is active). But the following works, provided [47mform[0m evaluates to an [error-triple]. (defmacro without-evisc-error-triple (form) `(state-global-let* ((abbrev-evisc-tuple nil set-abbrev-evisc-tuple-state) (gag-mode-evisc-tuple nil set-gag-mode-evisc-tuple-state) (term-evisc-tuple nil set-term-evisc-tuple-state) (ld-evisc-tuple nil set-ld-evisc-tuple-state)) ,form)) The following log illustrates how to use this utility to avoid an error caused by [47mwithout-evisc[0m in safe-mode. ACL2 !>(set-iprint t) ACL2 Observation in SET-IPRINT: Iprinting has been enabled. ACL2 !>(assign safe-mode t) T ACL2 !>(cw "Something printed with evisceration: ~X01~|" '((((DEEP)))) (evisc-tuple 3 4 nil nil)) Something printed with evisceration: (((#@1#))) NIL ACL2 !>(without-evisc-error-triple (value '(((#@1#))))) ((((DEEP)))) ACL2 !>") (save-and-clear-memoization-settings (memoize) "Save and remove the current memoization settings For background on memoization, see [memoize]. General Form: (save-and-clear-memoization-settings) Calls of this macro achieve two changes. The first copies the current memoization settings into an ACL2 [table], and the second unmemoizes all functions that were memoized by calls of [47m[memoize][0m. But note that this skips memoization settings that are either derived from calls of [47m[memoize-partial][0m or have a non-[47mnil[0m value of [47m[memoize][0m argument [47m:invoke[0m Also see [restore-memoization-settings].") (save-exec (interfacing-tools command-line) "Save an executable image and a wrapper script [47mSave-exec[0m saves your ACL2 state so that you can immediately re-start later in that same state. This utility can be useful for a project with [books] to be included every time ACL2 is started (see [build::using-extended-ACL2-images]), to avoid time taken to run [47m[include-book][0m. Another use of [47msave-exec[0m is to save an executable that takes command-line arguments beyond those normally passed to the host Lisp executable. All arguments of a call of [47msave-exec[0m are evaluated. At the end of this topic we discuss how to use the `[47mmake[0m' utility to invoke [47msave-exec[0m. Examples: ; Save an executable script named my-saved_acl2, with the indicated message ; added below the words "MODIFICATION NOTICE" under the start-up banner: (save-exec "my-saved_acl2" "This saved image includes Version 7 of Project Foo.") ; Same as above, but instead with a generic comment under the modification ; notice: (save-exec "my-saved_acl2" nil) ; Arrange that the generated script passes the indicated arguments to be ; processed by the Lisp (ACL2) executable (where this example is specific to ; the case that CCL is the host Lisp): (save-exec "my-saved_acl2" nil :host-lisp-args "--no-init -Z 256M") ; Arrange that the generated script passes along the indicated arguments ; to Lisp (ACL2), but that they are not processed by Lisp other than to ; record the additional arguments (see (6) below). (save-exec "my-saved_acl2" nil :inert-args "abc xyz -i foo") ; Combining the preceding two examples: (save-exec "my-saved_acl2" nil :host-lisp-args "--no-init -Z 256M" :inert-args "abc xyz -i foo") ; Arrange that ACL2 evaluates (with LD) the three forms shown. ; In this example, the THM form fails, but that does not stop the definition ; of BAR from being evaluated: LD continues on, just as the top-level loop ; lets you continue after a failure. (save-exec "my-acl2" "test" :init-forms '((defun foo (x) (reverse x)) (thm (equal (foo x) x)) (defun bar (x) x))) ; Essentially as just above, except that the call of LD returns after the THM ; failure, so BAR does not get defined. (save-exec "my-acl2" "test" :init-forms '((ld '((defun foo (x) (reverse x)) (thm (equal (foo x) x)) (defun bar (x) x)) :ld-pre-eval-print t :ld-verbose nil))) ; Immediately exit the ACL2 read-eval-print loop after starting up. (save-exec "my-acl2" nil :return-from-lp t) ; Immediately exit the ACL2 read-eval-print loop after starting up and ; defining function FOO in the logic. (save-exec "my-acl2" "Start with foo defined." :return-from-lp '(with-output :off :all (defun foo (x) x))) ; Immediately exit the ACL2 read-eval-print loop after starting up and ; defining variable xxx in raw Lisp. (save-exec "my-acl2" "Start with xxx defined." :return-from-lp '(with-output :off :all (ld '((set-raw-mode-on!) (defvar xxx (make-list 10)) (set-raw-mode nil) (u))))) Each example above generates a file named "my-saved_acl2". That file is quite similar in form to the script generated when building ACL2 directly from source code; details are below. For example, here are the contents of that generated file if the host Lisp is CCL (but where dates and pathnames are specific to one's environment). Here, we break lines using `\', but the [47mexec[0m command is actually on a single line. #!/bin/sh # Saved August 16, 2013 23:06:49 # then August 17, 2013 11:01:56 export CCL_DEFAULT_DIRECTORY="/projects/acl2/lisps/ccl/15542/ccl" exec "/projects/ccl/lx86cl64" -I "/u/smith/my-saved_acl2.lx86cl64" \ -Z 64M -K ISO-8859-1 -e "(acl2::acl2-default-restart)" \ --no-init -Z 256M \ -- \ abc xyz -i foo \ "$@" General Form: (save-exec exec-filename extra-startup-string :host-lisp-args host-lisp-args :inert-args inert-args :return-from-lp return-from-lp :init-forms init-forms) where the keyword arguments are optional, and arguments are as follows. [47mExec-filename[0m is the filename of the proposed executable. [47mExtra-startup-string[0m is a non-empty string to be printed after the normal ACL2 startup message when you start up the saved image. However, [47mextra-startup-string[0m is allowed to be [47mnil[0m, in which case a generic string will be printed instead. [47mHost-lisp-args[0m can be [47mnil[0m (the default), but if it is a non-[47mnil[0m value, then it is a string to be inserted into the command line in the saved script, specifying additional arguments that are to be processed by the host Lisp executable. (Note for SBCL only: these are runtime options; for toplevel options, see (8) below.) [47mInert-args[0m can be [47mnil[0m (the default), but if it is a non-[47mnil[0m value, then it is a string to be inserted into the command line in the saved script, specifying additional arguments that are not to be processed by the host Lisp executable. [47mReturn-from-lp[0m and [47minit-forms[0m are [47mnil[0m by default. Regardless of their value, ACL2 starts up and enters its read-eval-print loop in the usual way; see [lp]. Normally you'll stay inside that loop, but if [47mreturn-from-lp[0m or [47minit-forms[0m is not [47mnil[0m, then the indicated forms are evaluated in the ACL2 read-eval-print loop: a single form in the case of [47mreturn-from-lp[0m, and a list of forms in the case of [47minit-forms[0m. (Essentially, the [47m[ld][0m special [47m[standard-oi][0m is provided to a call of [47m[ld][0m as a list with the indicated forms on the front.) Moreover, if the case of [47mreturn-from-lp[0m, the loop is exited after evaluation of the form, leaving you in raw Lisp. Evaluation of [47mreturn-from-lp[0m is done with [47m[ld][0m options that minimize output (also see [with-output] to minimize output). Suggestion: let [47mreturn-from-lp[0m be [47mt[0m if you simply want to exit the read-eval-print loop at startup, without evaluating any (nontrivial) form. NOTE: It is illegal to supply non-[47mnil[0m values for both [47m:return-from-lp[0m and [47m:init-forms[0m. But if you add [47m(value :q)[0m to the end of your list of [47m:init-forms[0m, and your other forms do not result in an error, then you will be left in raw Lisp (as was presumably intended if you were planning to use [47m:return-from-lp[0m). The remainder of this documentation focuses on the options other than [47mreturn-from-lp[0m and [47minit-forms[0m. [31;1mDetails[0m: (1) You must first exit the ACL2 read-eval-print loop, typically by executing [47m:[0m[47m[q][0m, before evaluating a [47msave-exec[0m call; otherwise an error occurs. (2) The image will be saved so that in the new image, the raw Lisp package and the package in the ACL2 read-eval-print loop (see [lp]) will be the same as their respective values at the time [47msave-exec[0m is called. (3) [47mSave-exec[0m generates a small script file (e.g., [47m"my-saved_acl2"[0m in the examples above), similar in form (see (4) below) to the script generated when building ACL2 directly from source code, but with a comment line indicating the time at which the new script is written. [47mSave-exec[0m also saves an associated binary file. The binary file's name is obtained by putting a suffix on the script filename; for example, if the host Lisp is GCL running on a Linux or Darwin (MacOS) system, then that binary file has the name [47mmy-saved_acl2.gcl[0m in the examples above. (4) If [47minert-args[0m is [47mnil[0m (for example if keyword [47m:inert-args[0m is omitted), then when the generated ACL2 script is invoked with command line arguments, those arguments will be passed to the host Lisp. If [47minert-args[0m is supplied a string, then although those arguments will be appended to the supplied arguments (see (5) below), they will be ignored by the host Lisp (except for being recorded; see (6) below). [47mInert-args[0m is [47mnil[0m by default (that is, when omitted). The other legal value of [47minert-args[0m, [47mt[0m, is discussed in (5) below. Thus for the example above, suppose we invoke the generated script as follows. my-saved_acl2 -a bcd -e fgh If [47mmy-saved_acl2[0m was generated using a [47msave-exec[0m command with a non-[47mnil[0m value specified for keyword [47m:inert-args[0m, then the arguments ``[47m-a bcd -e fgh[0m'' will not be passed to the host Lisp; otherwise, they will be. Note that for ACL2 executable scripts generated by an ordinary ACL2 build from sources, the latter case (i.e., without [47minert-args[0m) takes place. (5) The generated script, which specifies execution with [47m/bin/sh[0m, will generally contain a line of one of the following forms. (But for SBCL, see (8) below.) In the examples that follow, [47mACL2_options[0m is a suitable list of command-line arguments given to the ACL2 executable. The quoted string [47m"$@"[0m is intended to allow the user to pass additional command-line arguments to that executable. If [47mhost-lisp-args[0m and [47minert-args[0m are omitted (or [47mnil[0m): exec <lisp_executable> <ACL2_options> "$@" More generally, [47mhost-lisp-args[0m is inserted immediately after [47m<ACL2_options>[0m, but only if it is non-[47mnil[0m (hence a string). If [47minert-args[0m is [47mnil[0m, we thus get: exec <lisp_executable> <ACL2_options> host-lisp-args "$@" If [47mhost-lisp-args[0m redefines a value from [47m<ACL2_options>[0m, then it is up to the host lisp which value to use. For example, experiments show that in CCL, if [47m-Z[0m appears twice, each with a legal value, then the second value is the one that is used (i.e. it does indeed override the original value written out by ACL2 in [47m<ACL2_options>[0m. But experiments also show that in LispWorks, where ``[47m-init -[0m'' is included in [47m<ACL2_options>[0m, then inclusion of ``[47m-init foo.lisp[0m'' in [47mhost-lisp-args[0m is ignored. The remaining cases below are for a non-[47mnil[0m value of [47minert-args[0m. In each case, if [47mhost-lisp-args[0m is [47mnil[0m then it should be omitted from the displayed command. If [47minert-args[0m is [47mt[0m then an additional argument, `[47m--[0m', indicates that when ACL2 is given command line arguments, these should not be processed by the host Lisp (other than recording them; see (6) below): exec <lisp_executable> <ACL2_options> host-lisp-args -- "$@" If [47minert-args[0m is a string then the result is similar to the above, except that [47minert-args[0m is added immediately after `[47m--[0m': exec <lisp_executable> <ACL2_options> host-lisp-args -- inert-args "$@" (6) See [oslib::argv] for a utility that returns a list of all [47minert-args[0m from an invocation of ACL2. See also [getopt] for a convenient way to parse these arguments. (7) Suppose that you invoke an ACL2 script, say [47m"my-saved_acl2"[0m, that was generated by [47msave-exec[0m, and then optionally evaluate some forms. Then you may save a new ACL2 script with [47msave-exec[0m. The new script will contain comment lines that extend comment lines in [47m"my-saved_acl2"[0m with a new write date, but otherwise will be identical to the script that would have been generated by executing the new [47msave-exec[0m call after invoking the original ACL2 executable (built directly from ACL2 sources) instead of [47m"my-saved_acl2"[0m. In other words, the options added by the earlier [47msave-exec[0m call that created [47m"my-saved_acl2"[0m are discarded by the new [47msave-exec[0m call. However, the [47m.core[0m file will built on top of the [47m.core[0m file that was consulted when [47m"my-saved_acl2"[0m was invoked. (8) The following note pertains only to the case that the host Lisp is SBCL. For SBCL, the scripts written are analogous to, but slightly different from, those shown above. Please note that for SBCL, the [47mhost-lisp-args[0m are what the SBCL manual calls ``runtime options''. For SBCL only, an extra keyword argument, [47m:toplevel-args[0m, may be used for specifying what the SBCL manual calls ``toplevel options. As with [47m:host-lisp-args[0m, this value, [47mtoplevel-args[0m, should be [47mnil[0m (the default) or a string. Here is an example. (save-exec "my-saved_acl2" nil :host-lisp-args "--dynamic-space-size 50000" :toplevel-args "--eval '(print \"HELLO\")'" :inert-args "--my-option my-value") The script generated by this example call of [47msave-exec[0m contains a line such as the following (with the same convention for `\' as before). Notice that [47m:host-lisp-args[0m can be modified at startup (without [47msave-exec[0m) by setting environment variable [47mSBCL_USER_ARGS[0m. exec "/projects/sbcl-1.1.7-x86-64-linux/src/runtime/sbcl" \ --dynamic-space-size 24000 --control-stack-size 64 \ --core "/u/smith/my-saved_acl2.core" --dynamic-space-size 50000 \ ${SBCL_USER_ARGS} \ --end-runtime-options \ --no-userinit --eval '(acl2::sbcl-restart)' \ --eval '(print "HELLO")' \ --end-toplevel-options \ --my-option my-value \ "$@" In general, the generated script is of one of the following forms (with the same convention for `\' as before). For the case that [47minert-args[0m is [47mnil[0m: exec <lisp_executable> \ <ACL2_runtime_options> host-lisp-args --end-runtime-options \ <ACL2_toplevel_options> host-lisp-args \ "$@" For the case that [47minert-args[0m is non-[47mnil[0m: exec <lisp_executable> \ <ACL2_runtime_options> host-lisp-args --end-runtime-options \ <ACL2_toplevel_options> host-lisp-args --end-toplevel-options \ inert-args "$@" Notice that as before, when the generated script is invoked (for example, at the shell), additional command-line arguments provided at that time are passed to Lisp if and only if [47minert-args[0m is [47mnil[0m. For SBCL, when they are passed to Lisp they are passed as toplevel options, not as runtime options. Finally, note that [47msave-exec[0m can be invoked using the `[47mmake[0m' utility in the main ACL2 directory by using the [47msave-exec[0m target. That target will first build an ACL2 executable in the normal way if it is out of date. Then it will start that executable, using the value of [47mACL2_CUSTOMIZATION[0m (as a `[47mmake[0m' or environment variable) --- which must be specified --- as the [ACL2-customization] file, before making a [47msave-exec[0m call. By default, that call is [47m(save-exec "custom-saved_acl2" "Saved with additions from <file>")[0m, where [47m<file>[0m is the value of [47mACL2_CUSTOMIZATION[0m. (Except, in ACL2(p) and ACL2(r), [47m"custom-saved_acl2"[0m is replaced by [47m"custom-saved_acl2p"[0m and [47m"custom-saved_acl2r"[0m, respectively.) However, you can specify the first argument as the value of [47mACL2_SAVED[0m (as a `[47mmake[0m' or environment variable), and you can specify the remaining arguments as the value of [47mACL2_SAVED_ARGS[0m (also as a `[47mmake[0m' or environment variable). Here is an example one could run at the shell prompt; notice the careful quoting. make save-exec \ ACL2_CUSTOMIZATION=~/temp/foo.lsp \ ACL2_SAVED=my-acl2 \ ACL2_SAVED_ARGS='"My custom image" \ :init-forms (quote ((defun foo (x) (reverse x))))' WARNING: It is a good idea to look at the log file noted in the `[47mmake[0m' output, to check that your customization file loaded as intended (presumably, without errors).") (saving-and-restoring (pointers) "See [save-exec].") (saving-event-data (system-utilities output-controls) "Save data stored for subsidiary [events] Warning: This is a low-level system utility that may change somewhat over time. For more details, see the ACL2 source code. General Forms: (saving-event-data form) ; See Further information below for keyword options for these two: (runes-diff book-name) (old-and-new-event-data book-name) where [47mform[0m is any form that evaluates to an [error-triple] and [47mbook-name[0m is a file ending with [47m".lisp"[0m. See below for typical usage. A common problem is that a book whose certification formerly succeeded now has a certification failure. In that case, the failure is often caused by a proof failure; then one may wish for information on what has changed from the previous, successful proof attempt and the new, failing proof attempt. Here is a procedure for obtaining such information. After that we discuss some variations on that procedure. Finding [rune]s that were used only previously, or only now Here we discuss a procedure for discovering, given a book [47mBOOK.lisp[0m, which [rune]s were used in a previous successful proof but not in the new failed proof attempt, or vice-versa. The procedure described here requires certain ``event-data'' information to have been written by a previous certification of [47mBOOK.lisp[0m. Such writing of event-data can be accomplished by providing [47m[certify-book][0m the keyword argument [47m:write-event-data t[0m. Writing of event-data by [47mcertify-book[0m can also be accomplished by setting environment variable [47mACL2_WRITE_EVENT_DATA[0m to a non-empty value, though that is overridden if [47m[certify-book][0m keyword argument [47m:write-event-data[0m is explicitly supplied the value, [47mnil[0m. See [build::custom-certify-book-commands] for discussion about how a [47mcert-flags[0m comment can set [47mcertify-book[0m keyword values when using the [47mcert.pl[0m utility. When [47mcertify-book[0m writes event-data under either condition above (keyword argument or environment variable), it writes it to [47mBOOK@event-data.lsp[0m. That file includes entries of the form [47m(name . alist)[0m, where [47malist[0m is an [3mevent-data alist[0m --- see [47m[get-event-data][0m --- where each entry corresponds to one of the following event types, possibly generated by a macro or [47m[make-event][0m call. * defthm * defun * verify-guards * thm One [47m(name . alist)[0m entry is written for each such event, in the order in which the events were encountered during the proof pass of certification. Normally [47mname[0m is the name of the event, but it is [47mnil[0m in the case of a [47m[thm][0m event. Suppose that you have file [47mBOOK@event-data.lsp[0m as discussed above, that is, from having previously certified [47mBOOK.lisp[0m when writing event-data. Also suppose that you now have a copy of [47mBOOK.lisp[0m (maybe the same one, maybe not) for which certification has failed, possibly using a different ACL2 version than the first, and let [47mEV[0m be the event that caused the failure; assume that's because of a proof failure. Below are steps that allow you to see which rules (actually, [rune]s) were used in the proof attempt for the first event but not the second, or vice-versa. That information might help you to repair the proof, for example by enabling or disabling a rule whose [enable]d status has changed after the successful certification, or by proving a rule that was in an included book during the successful certification but has since been deleted. [31;1mStep 1[0m. Load the [portcullis] commands: (ld "BOOK.port") [31;1mStep 2[0m. Execute the following command, which will presumably end with a failed proof for the event, [47mEV[0m. (saving-event-data (ld "BOOK.lisp")) [31;1mStep 3[0m. See which runes were used in the old proof and not the new, and vice-versa, respectively: (runes-diff "BOOK.lisp") An example is in [community-books] file [47mbooks/demos/event-data/test1.lisp[0m, which has comments that lead through a variant of the steps above. File [47mtest1-input.lsp[0m in that directory actually carries out that process, resulting in output displayed in log file [47mtest1-log.txt[0m in that directory. Here is the output of a [47mrunes-diff[0m call shown both in that log file and in a comment in file [47mtest1-input.lsp[0m. It shows that a [type-prescription] rule, named [47mtrue-listp-append[0m, was used in the original proof but not the failed proof (which made the [47m[ld][0m call of Step 2 above without first performing Step 1, which would have introduced that type-prescription rule). This output also shows that the new (failed) proof attempt used many runes not used in the previous proof --- not surprisingly, since without the rule [47mtrue-listp-reverse[0m the prover made a desperate attempt involving destructor elimination and induction. ((:OLD ((:TYPE-PRESCRIPTION TRUE-LISTP-REVERSE))) (:NEW ((:DEFINITION ALISTP) (:DEFINITION ATOM) (:DEFINITION NOT) (:DEFINITION TRUE-LISTP) (:ELIM CAR-CDR-ELIM) (:EXECUTABLE-COUNTERPART CONSP) (:EXECUTABLE-COUNTERPART NOT) (:EXECUTABLE-COUNTERPART REVERSE) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:INDUCTION ALISTP)))) A second, analogous set of three files is in that same directory; just replace [47m"test1"[0m by [47m"test2"[0m in the filenames. Further information The [47mrunes-diff[0m utility is intended to serve as an example of a class of such query utilities. It is a macro that expands to a corresponding function call. ACL2 !>:trans1 (runes-diff "BOOK.lisp") (RUNES-DIFF-FN "BOOK.lisp" NIL NIL NIL 'RUNES-DIFF STATE) ACL2 !> [47mRunes-diff-fn[0m is actually quite simple. [31;1mFunction: [0m<runes-diff-fn> (defun runes-diff-fn (book-string name namep dir ctx state) (er-let* ((old/new (old-and-new-event-data-fn book-string name namep dir ctx state))) (let* ((old (car old/new)) (new (cdr old/new)) (old-runes (get-event-data-1 'rules old)) (new-runes (get-event-data-1 'rules new)) (old-diff (set-difference-equal old-runes new-runes)) (new-diff (set-difference-equal new-runes old-runes))) (value (list (list :old old-diff) (list :new new-diff)))))) It is simple because the real work is carried out using a more complex function, [47mold-and-new-event-data-fn[0m. That function returns a pair [47m(old . new)[0m, where [47mold[0m and [47mnew[0m are event-data alists for the failed event (called [47mEV[0m above). Then [47mrunes-diff-fn[0m only needs to pick out the [47mRULES[0m fields and form the set-differences. The macro [47mold-and-new-event-data[0m provides a convenient interface to [47mold-and-new-event-data-fn[0m. ACL2 !>:trans1 (old-and-new-event-data "BOOK.lisp") (OLD-AND-NEW-EVENT-DATA-FN "BOOK.lisp" NIL NIL NIL 'OLD-AND-NEW-EVENT-DATA STATE) ACL2 !> Both [47mrunes-diff[0m and [47mold-and-new-event-data[0m have keyword arguments that allow one to choose a specific name for a failed event --- the most recent event with that name, rather than [47mEV[0m --- and a directory for the given filename, which may be a string or a keyword representing a project directory (see [project-dir-alist]). The [47m"test2"[0m files mentioned above have an example in which the name [47mnil[0m is supplied to specify the [47m[thm][0m event most recently preceding the failed event (actually it's the only one preceding the failed event). General Forms: (runes-diff book-string &key name dir) (old-and-new-event-data book-string &key name dir) If you want to use these programmatically, call the corresponding [47m"-FN"[0m versions, where [47mnamep[0m is [47mt[0m to represent the case that a name is provided, else [47mnil[0m. General Forms: (runes-diff-fn book-string name namep dir ctx state) (old-and-new-event-data book-string name namep dir ctx state)") (sbcl-installation (obtaining-common-lisp) "Installing Steel Bank Common Lisp (SBCL) SBCL is available from [47m{https://www.sbcl.org | https://www.sbcl.org}[0m. You can of course go to that website to find download and installation instructions for SBCL, but below is a concise summary that includes build options appropriate for ACL2. [31;1mNOTE:[0m If you already have a previous version of SBCL installed and you have experience with Lisp, you might want to see [sbcl-installation-brief] for abbreviated instructions to use instead of those below. 1. Download an SBCL binary from [47m{https://www.sbcl.org/platform-table.html | https://www.sbcl.org/platform-table.html}[0m. That page contains a table with combinations of operating systems and hardware architectures, from which you have to pick the one that applies to you. Note that you need an SBCL binary in order to compile from source (see below). The file downloaded from the table will have a name like [47msbcl-2.1.2-arm64-darwin-binary.tar.bz2[0m, where the [47marm64-darwin[0m part depends on the chosen combination of operating system and hardware architecture. 2. Untar the file in a directory of your choice, which will create a subdirectory with a name like [47msbcl-2.1.2-arm64-darwin[0m, consistently with the name of the downloaded file. 3. Change to that subdirectory and run sh run-sbcl.sh to make sure that the binary works. On macOS, you may get a pop-up saying that Apple cannot check it for malware and that it needs to be updated. In that case, open the macOS settings, go under `Privacy and Security' (or `Security and Privacy', depending on macOS version), and you should see something about the (SBCL) executable whose execution was stopped: click the button to allow it, and retry running it. Eventually it should work. 4. In the same directory where you just ran SBCL, run the SBCL installer. This is done via INSTALL_ROOT=... sh install.sh where [47m...[0m is optional: if omitted, it defaults to [47m/usr/local[0m. If you pick something different from this default, note that the installer will create three directories there, namely [47mbin[0m, [47mlib[0m, and [47mshare[0m. Thus, for examples, if you want to install SBCL in your home, you may want to create a directory in your home (e.g. [47msbcl[0m, or [47mapps[0m), and pass that as [47mINSTALL_ROOT[0m, instead of passing your home directory. 5. Add that [47mbin[0m directory to your path, so that SBCL can be found. Try running sbcl to make sure that the installed binary works. This time macOS should not block its execution. 6. Download the SBCL source from [47m{https://www.sbcl.org/platform-table.html | https://www.sbcl.org/platform-table.html}[0m, the same page with the table of binaries. There should be one link to the sources, above the table of binaries. The downloaded file will have a name like [47msbcl-2.3.9-source.tar.bz2[0m. 7. Untar the file in a directory of your choice, which will create a subdirectory with a name like [47msbcl-2.3.9[0m. 8. Change to that subdirectory, and compile SBCL via: sh make.sh --without-immobile-space --without-immobile-code --without-compact-instance-header You might also need option [47m--with-sb-thread[0m; this has been necessary on a machine running FreeBSD. These options prevent certain possible errors. The compilation process prints a lot of stuff on the screen, and should succeed. 9. The final part of the screen output will suggest to run the tests, via: cd ./tests && sh ./run-tests.sh They will take a while, but should eventually succeed. 10. The final part of the screen output will also suggest to build the documentation, via cd ./doc/manual && make --- this may fail, but that does not seem to matter. 11. Finally, install the just compiled SBCL in the same way as the downloaded binary above, via: INSTALL_ROOT=... sh install.sh If you use the same [47m...[0m as above (or use the default if you did before), the new installation will replace the old one, and invoking SBCL (which will still be on the path) will run the newly compiled version. 12. If a new version of the SBCL sources becomes available, you can repeat the procedure above to compile and install it, using the previously installed binary. 13. As an alternative to installing the binary compiled from the sources, you could create a script, in your executable path, containing #!/bin/sh <dir>/run-sbcl.sh --dynamic-space-size 2000 "$@" where [47m<dir>[0m is the untarred directory described above, and where the dynamic space size option is just an example of how one can pass options to the running SBCL, but it is not necessarily needed. If you need to pass options like this, you can also do that if you follow the installation instructions: in that case, the script should contain just [47msbcl[0m instead of [47m<dir>/run-sbcl.sh[0m.") (sbcl-installation-brief (obtaining-common-lisp) "Installing Steel Bank Common Lisp (SBCL) The topic [sbcl-installation] contains full installation instructions for SBCL. The present topic contains abbreviated instructions that have been used successfully over time; these may be suitable for those who already have a previous version of SBCL installed and have experience with Lisp. If the instructions below are not sufficient for you, please see [sbcl-installation] instead. SBCL is available from [47m{https://www.sbcl.org | https://www.sbcl.org}[0m. You can of course go to that website to find download and installation instructions for SBCL, but here is a concise summary that includes build options appropriate for ACL2. 1. Download SBCL from [47m{https://www.sbcl.org | https://www.sbcl.org}[0m. A shortcut may be to follow the ``[31;1mSource[0m'' link near the top of the page, [47m{https://www.sbcl.org/platform-table.html | https://www.sbcl.org/platform-table.html}[0m. 2. The downloaded file will have a name like ``[47msbcl-2.2.10-source.tar.bz2[0m'', where ``[47m2.2.10[0m'' is replaced by the current SBCL version. Change to a directory just above where you want SBCL to reside and move the downloaded file there. 3. Extract the downloaded file (where it now resides), for example as follows (again, where ``[47m2.2.10[0m'' is replaced by the current SBCL version number). tar jxf sbcl-2.2.10-source.tar.bz2 4. Change to the new directory and build SBCL with options appropriate for ACL2, as follows (again, replacing ``[47m2.2.10[0m'' as appropriate). cd sbcl-2.2.10 sh make.sh --without-immobile-space --without-immobile-code --without-compact-instance-header You might also need option [47m--with-sb-thread[0m; this has been necessary on a machine running FreeBSD. 5. Create a script file in a directory that is on your path (or, if you are updating your sbcl, just replace your current sbcl script; you can find its location by executing the command, ``[47mwhich sbcl[0m''). If you are in directory [47m<DIR>[0m from the preceding step (e.g., a path ending in ``[47msbcl-2.2.10[0m''), then that script file should contain the following lines. #!/bin/sh <DIR>/run-sbcl.sh --dynamic-space-size 2000 "$@"") (scion (apply$) "A function ancestrally dependent on [47mapply$[0m The function [47mfn[0m is a [3mscion of[0m [47mapply$[0m or simply a [3mscion[0m if the function is ancestrally dependent on [47mapply$[0m. That is, [47mfn[0m is [47mapply$[0m, or [47mfn[0m calls [47mapply$[0m, or calls a function that calls [47mapply$[0m, or calls a function that calls a function that calls [47mapply$[0m, etc. Meriam-Webster defines [3mscion[0m as ``a descendant of a wealthy, aristocratic, or influential family.'' Examples of scions include [47mapply$[0m, [47mcollect$[0m and [47mfoldr[0m, where the last two are defined as shown below. (defun$ collect$ (fn lst) (if (endp lst) nil (cons (apply$ fn (list (car lst))) (collect$ fn (cdr lst))))) (defun$ foldr (lst fn init) (if (endp lst) init (apply$ fn (list (car lst) (foldr (cdr lst) fn init))))) Note: [47mCollect$[0m, which is part of the support for the [47m[loop$][0m statement, is pre-defined in ACL2 but [47mfoldr[0m is not. Most often, scions treat one or more of their arguments as ``functions,'' i.e., have at least one formal of ilk [47m:FN[0m. But that is not necessarily the case. [47mCollect$-squares[0m, as defined below, (defun$ collect$-squares (lst) (collect$ (lambda$ (x) (* x x)) lst)) is a scion even though it does not have a formal of ilk [47m:FN[0m. However, it calls the scion [47mcollect$[0m. The function defined by (defun$ collect$-expr (x lst alist) (if (endp lst) nil (cons (ev$ x (cons (cons 'v (car lst)) alist)) (collect$-expr x (cdr lst) alist)))) is a scion because it calls [47mev$[0m which calls [47mapply$[0m in the mutually recursive clique that defines them both. Note that the ilks of the formals of [47mcollect$-expr[0m are [47m:EXPR[0m, [47mNIL[0m and [47mNIL[0m, respectively. The function collects the successive values of the expression [47mx[0m under extensions of [47malist[0m binding the variable symbol [47mv[0m to successive elements of [47mlst[0m. In the early days of [47mapply$[0m we used the term ``mapping function'' to refer to scions. But that nomenclature was misleading because in the Lisp culture ``mapping'' tends to be understood as a kind of linear iteration. Fans of higher order logic have suggested we use the term ``functional'' for our scions, or at least for those scions having at least one formal of ilk [47m:FN[0m. However, we have resisted that suggestion because a functional takes a function as an argument and is thus a higher-order entity, but ACL2 is first-order, functions are never objects in ACL2, and the values of our [47m:FN[0m formals are ordinary objects like symbols and lists that are interpreted as functions.") (search (lists strings acl2-built-ins) "Search for a string or list in another string or list Example Forms: (search "cd" "Cdabcdefcde") ; = 4, index of first match (search "cd" "Cdabcdefcde" :test 'equal) ; same as above (search "cd" "Cdabcdefcde" :from-end t) ; = 8, index of last match (search "cd" "Cdabcdefcde" :start1 1) ; = 1 (search "cd" "Cdabcdefcde" :start2 5) ; = 8 (search "cd" "Cdabcdefcde" :test 'char-equal) ; = 0 (case-insensitive) (search "ac" "Cdabcdefcde") ; = nil (search '(a b) '(9 8 a b 7 6)) ; = 2 General Form: (search seq1 seq2 &key from-end test start1 start2 end1 end2) [47mSearch[0m indicates whether one string or list occurs as a (contiguous) subsequence of another string or list, respectively. It returns [47mnil[0m if no such match is found; otherwise it returns the (zero-based) index of the first match by default, but a non-[47mnil[0m value of keyword argument [47m:from-end[0m causes it to return the last match. The [47m:test[0m is [47mequal[0m by default. The other legal value for [47m:test[0m is [47mchar-equal[0m, which can be given only for two strings, in which case the match is case-insensitive. Finally, values of [47m:start1[0m and [47m:end1[0m for the first sequence, and of [47m:start2[0m and [47m:end2[0m for the second sequence, bound the portion of the respective sequence used for deciding on a match, though the index returned is always an index into the second sequence as a whole. The [guard] for calls of [47msearch[0m is given by a function, [47msearch-fn-guard[0m, which has the following requirements. * The two arguments much both satisfy [47m[true-listp][0m or else must both be strings. * The [47m:test[0m must evaluate to one of the symbols [47m[equal][0m or [47m[char-equal][0m, where the latter is only allowed if the (first) two arguments are strings. * The values of [47m:start1[0m, [47m:start2[0m, [47m:end1[0m, and [47m:end2[0m must all be natural numbers, where if omitted they default to 0, 0, the length [47mlen1[0m of the first argument, and the length [47mlen2[0m of the second argument, respectively. * If [47mstart1[0m is the value of [47m:start1[0m, defaulting as described just above, and similarly for the other start and end keywords and for lengths [47mlen1[0m and [47mlen2[0m as described just above, then: [47mstart1 <= end1 <= len1[0m and [47mstart2 <= end2 <= len2[0m. [47mSearch[0m is a Common Lisp function (actually, a macro in ACL2). See any Common Lisp documentation for more information. Definition [31;1mMacro: [0m<search> (defmacro search (seq1 seq2 &key from-end (test ''equal) (start1 '0) (start2 '0) (end1 'nil end1p) (end2 'nil end2p)) (cons 'search-fn (cons seq1 (cons seq2 (cons from-end (cons test (cons start1 (cons start2 (cons end1 (cons end2 (cons end1p (cons end2p 'nil)))))))))))) [31;1mFunction: [0m<search-fn> (defun search-fn (seq1 seq2 from-end test start1 start2 end1 end2 end1p end2p) (declare (xargs :guard (search-fn-guard seq1 seq2 from-end test start1 start2 end1 end2 end1p end2p))) (let* ((end1 (if end1p end1 (length seq1))) (end2 (if end2p end2 (length seq2))) (seq1 (subseq seq1 start1 end1))) (mv-let (seq1 seq2) (cond ((eq test 'char-equal) (mv (string-downcase seq1) (string-downcase seq2))) (t (mv seq1 seq2))) (and (<= (- end1 start1) (- end2 start2)) (cond (from-end (search-from-end seq1 seq2 start2 end2 nil)) (t (search-from-start seq1 seq2 start2 end2))))))) [31;1mFunction: [0m<search-from-end> (defun search-from-end (seq1 seq2 start2 end2 acc) (declare (xargs :guard (and (or (true-listp seq1) (stringp seq1)) (or (true-listp seq2) (stringp seq2)) (integerp start2) (<= 0 start2) (integerp end2) (<= end2 (length seq2)) (<= (+ start2 (length seq1)) end2)))) (cond ((or (not (integerp end2)) (not (integerp start2))) nil) (t (let* ((bound2 (+ start2 (length seq1))) (matchp (equal seq1 (subseq seq2 start2 bound2))) (new-acc (if matchp start2 acc))) (cond ((>= bound2 end2) new-acc) (t (search-from-end seq1 seq2 (1+ start2) end2 new-acc))))))) [31;1mFunction: [0m<search-from-start> (defun search-from-start (seq1 seq2 start2 end2) (declare (xargs :guard (and (or (true-listp seq1) (stringp seq1)) (or (true-listp seq2) (stringp seq2)) (integerp start2) (<= 0 start2) (integerp end2) (<= end2 (length seq2)) (<= (+ start2 (length seq1)) end2)))) (let ((bound2 (+ start2 (length seq1)))) (cond ((or (not (integerp end2)) (not (integerp start2))) nil) ((equal seq1 (subseq seq2 start2 bound2)) start2) ((>= bound2 end2) nil) (t (search-from-start seq1 seq2 (1+ start2) end2)))))") (second (nth acl2-built-ins) "Second member of the list See any Common Lisp documentation for details.") (serialize (io) "Routines for saving ACL2 objects to files, and later restoring them We thank Jared Davis for contributing the ``serialization'' routines for saving ACL2 objects in files for later loading. We implement some routines for writing arbitrary ACL2 objects to files, and for loading those files later. We usually call these ".sao" files, which stands for (S)erialized (A)CL2 (O)bject. Our serialization scheme uses a compact, binary format that preserves structure sharing in the original object. We optimize for read performance. Subtopics [Serialize-alternatives] Historic alternatives to the [serialize] routines. [Serialize-in-books] Using serialization efficiently in books [Serialize-read] Read a serialized ACL2 object from a file [Serialize-write] Write an ACL2 object into a file [Set-serialize-character-system] Avoid some special [serialize] writing, including for [47m.cert[0m files [With-serialize-character] Control output mode for [47mprint-object$[0m") (serialize-alternatives (serialize) "Historic alternatives to the [serialize] routines. Routines [47mcompact-print-file[0m and [47mcompact-read-file[0m were previously built into ACL2. Another option was to use the [47mhons-archive[0m library. These tools were deprecated and ultimately removed from ACL2. If for some reason you need to use them, see [community-books] SVN revisions prior to 1314.") (serialize-in-books (serialize) "Using serialization efficiently in books Our serialize scheme was developed in order to allow very large ACL2 objects to be loaded into books. Ordinarily this is carried out using [47m[serialize-read][0m within a [47m[make-event][0m, e.g., (make-event (mv-let (obj state) (serialize-read "my-file") (value `(defconst *my-file* ',obj)))) But this scheme is not particularly efficient. During [47m[certify-book][0m, the actual call of [47mserialize-read[0m is carried out, and this is typically pretty fast. But then a number of possibly inefficient things occur. * The ACL2 function [47mbad-lisp-object[0m is run on the resulting object. This is memoized for efficiency, but may still take considerable time when the file is very large. * The [checksum] of the resulting object is computed (though this is not the default; see [book-hash]. This is also memoized, but as before may still take some time. * The object that was just read is then written into book.cert, essentially with [47m[serialize-write][0m. This can take some time, and results in large certificate files. Then, during [include-book], the [47mmake-event[0m expansion is loaded. This is now basically just a [47mserialize-read[0m. The moral of the story is that using serialize will only help your [47mcertify-book[0m time, and it only impacts a portion of the overall time. To avoid this overhead, we have developed an UNSOUND alternative to [47mserialize-read[0m, which is available only by loading an additional book. So, if the above scheme is not performing well for you, you may wish to see [unsound-read].") (serialize-read (serialize acl2-built-ins) "Read a serialized ACL2 object from a file General form: (serialize-read filename [:hons-mode {:always, :never, :smart}] ; :smart by default [:verbosep {t, nil}]) ; nil by default --> (mv obj state) In the logic this is an oracle read. Under the hood, we try to read and return a serialized object from a file that was presumably created by [47m[serialize-write][0m. On success we return the contents of the file. Any failures (e.g., file not found, bad file contents, etc.) will result in a hard Lisp error. The [47mfilename[0m should be a string that gives the path to the file. The [47mhons-mode[0m controls how whether to use [47m[hons][0m or [47m[cons][0m to restore the object. The default mode is [47m:smart[0m, which means that conses that were [normed] at the time of the file's creation should be restored with [47mhons[0m. But you can override this and insist that [47mhons[0m is to [47m:always[0m or [47m:never[0m be used, instead. Why would you use [47m:never[0m? If your object previously had a lot of honses, but you no longer have any need for them to be normed, then using [47m:never[0m may sometimes be a lot faster since it can avoid [47mhons[0m calls. On the other hand, if you are going to [47m[hons-copy][0m some part of the file's contents, then it is likely faster to use [47m:smart[0m or [47m:always[0m instead of first creating normal conses and then copying them to build honses. The [47m:verbosep[0m flag just controls whether to print some low-level details related to timing and memory usage as the file is being read.") (serialize-write (serialize acl2-built-ins) "Write an ACL2 object into a file General form: (serialize-write filename obj [:verbosep {t, nil}]) ; nil by default --> state In the logic this carries out an oracle read. Under the hood, we try to save [47mobj[0m into the file indicated by [47mfilename[0m, which must be a string. The object can later be recovered with [47m[serialize-read][0m. We just return [47mstate[0m, and any failures (e.g., file not openable) will result in a hard Lisp error. Writing objects to disk is generally slower than reading them back in since some analysis is required to convert an object into our [serialize]d object format. The [47mverbosep[0m flag just says whether to print some low-level details related to timing and memory usage as the file is being written.") (set-absstobj-debug (defabsstobj) "Get more information when atomic update fails for an abstract stobj This [documentation] topic assumes familiarity with abstract stobjs. See [defabsstobj]. Below we explain what is meant by the following error message, and how to add information to the end of it. ACL2 Error in CHK-ABSSTOBJ-INVARIANTS: Possible invariance violation for an abstract stobj! **PROCEED AT YOUR OWN RISK.** To proceed, evaluate the following form. :CONTINUE-FROM-ILLEGAL-STATE See :DOC set-absstobj-debug. Advanced users who are willing to risk unsound invariance violations to get a bit more speed may submit the following when there is an active trust tag (see [defttag]). (set-absstobj-debug :ignore) The rest of the session will then avoid the error message above because it avoids the abstract stobj invariance checking discussed below. BUT WITHOUT THIS CHECKING, YOUR SESSION COULD BE CORRUPTED! The discussion below assumes that you are not using the special argument [47m:ignore[0m for [47mset-absstobj-debug[0m. The use of [47m(set-absstobj-debug t)[0m will make the error message above more informative, for example as follows, at the cost of slower execution --- but in practice, the slowdown may be negligible (more on that below). Below, only the last two lines are new. ACL2 Error in CHK-ABSSTOBJ-INVARIANTS: Possible invariance violation for an abstract stobj! **PROCEED AT YOUR OWN RISK.** To proceed, evaluate the following form. :CONTINUE-FROM-ILLEGAL-STATE See :DOC set-absstobj-debug. Evaluation was aborted under a call of abstract stobj export UPDATE-FLD-NIL-BAD. You may be best off starting a new ACL2 session if you see one of the errors above. But you can continue at your own risk. With a trust tag (see [defttag]), you can even fool ACL2 into thinking nothing is wrong, and perhaps you can fix up the abstract stobj so that indeed, nothing really is wrong. See the [community-books] file [47mbooks/demos/defabsstobj-example-4-input.lsp[0m for how to do that. (The corresponding output file [47mbooks/demos/defabsstobj-example-4-log.txt[0m may also be informative.) Examples: (set-absstobj-debug t) ; obtain extra debug info, as above (set-absstobj-debug nil) ; avoid extra debug info (default) (set-absstobj-debug :ignore) ; possibly unsound! -- see above General Form: (set-absstobj-debug val) where [47mval[0m is evaluated. Recall (see [defabsstobj]) that for any exported function whose [47m:EXEC[0m function might (according to ACL2's heuristics) modify the foundational stobj non-atomically, one must specify [47m:PROTECT t[0m. This results in extra code generated for the exported function, which provides a check that atomicity was not actually violated by a call of the exported function. The extra code might slow down execution, but perhaps only negligibly in typical cases. If you can tolerate a bit extra slow-down, then evaluate the form [47m(set-absstobj-debug t)[0m. Subsequent such errors will provide additional information, as in the example displayed earlier in this documentation topic. Calls of [47mset-absstobj-debug[0m are legal event forms (e.g., for [books]).") (set-accumulated-persistence (pointers) "See [accumulated-persistence].") (set-backchain-limit (backchain-limit) "Sets the backchain-limit used by the type-set and rewriting mechanisms Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. This event sets the global [47m[backchain-limit][0m used by the ACL2 type-set and rewriting mechanisms. Its value may be a cons whose car and cdr are each either [47mnil[0m or a non-negative integer. Its value [47mx[0m may also be [47mnil[0m or a non-negative integer, which is treated as a cons whose car and cdr are both [47mx[0m. The car is used to limit backchaining used by the ACL2 type-set mechanism, while the cdr is used to limit backchaining used by the rewriting mechanism. See [backchain-limit] for details about how backchain-limits are used. Rewrite backchain limits may also be installed at the level of hints; see [hints] for a discussion of [47m:backchain-limit-rw[0m. :set-backchain-limit nil ; do not impose any additional limits :set-backchain-limit 0 ; allow only type reasoning for rewriting ; hypotheses :set-backchain-limit 500 ; allow backchaining to a depth of no more ; than 500 for rewriting hypotheses (set-backchain-limit 500) ; same as above :set-backchain-limit (500 500) ; same as above (set-backchain-limit '(500 500)) ; same as above (set-backchain-limit '(3 500)) ; allow type-set backchaining to a depth of no more ; than 3 and rewriter backchaining to a depth of no ; more than 500 The default limit is [47m(nil nil)[0m.") (set-bad-lisp-consp-memoize (memoize) "Turn off or on memoization of raw Lisp function [47mbad-lisp-consp[0m WARNING: This is an advanced utility, recommended only for users who understand ACL2 at a deep level. Calling this function can permanently alter the performance of low-level raw Lisp function [47mbad-lisp-consp[0m. Invoke [47m(set-bad-lisp-consp-memoize t)[0m to memoize raw Lisp function [47mbad-lisp-consp[0m, which is memoized by default in ACL2 but not ACL2(p). This call has no effect if [47mbad-lisp-consp[0m is already memoized. Similarly, invoke [47m(set-bad-lisp-consp-memoize nil)[0m to unmemoize [47mbad-lisp-consp[0m; this call has no effect if [47mbad-lisp-consp[0m is already unmemoized.") (set-body (definition events) "Set the definition body Examples: (set-body foo (:definition foo)) ; restore original definition of foo (set-body foo foo) ; same as just above (set-body foo my-foo-def) ; use my-foo-def for the body of foo (set-body foo (:definition my-foo-def)) ; same as just above Rules of class [47m:[0m[47m[definition][0m can install a new definition body, used for example by [47m:expand[0m [hints]. See [definition] and also see [hints] for a detailed discussion of the [47m:install-body[0m fields of [47m:[0m[47m[definition][0m rules and their role in [47m:expand[0m hints. There may be several such definitions, but by default, the latest one is used by [47m:expand[0m hints. Although the [47m:with[0m keyword may be used in [47m:expand[0m hints to override this behavior locally (see [hints]), it may be convenient to install a definition for expansion other than the latest one --- for example, the original definition. [47mSet-body[0m may be used for this purpose. General Form: (set-body function-symbol rule-name) where [47mrule-name[0m is either a [47m:definition[0m [rune] or is a function symbol, [47msym[0m, which represents the rune [47m(:definition sym)[0m. You can view all definitions available for expansion; see [show-bodies].") (set-bogus-defun-hints-ok (defun) "Allow unnecessary [47m(xargs :hints ...)[0m and [measure]s. General Forms: (set-bogus-defun-hints-ok t) (set-bogus-defun-hints-ok nil) (set-bogus-defun-hints-ok :warn) By default, ACL2 causes an error when either of the keywords [47m:[0m[47m[hints][0m or [47m:measure[0m is supplied in an [47m[xargs][0m [declare] form for a [47m:[0m[47m[logic][0m mode non-recursive definition. That restriction also applies to [47m:[0m[47m[program][0m mode definitions in the case of [47m:measure[0m. This behavior can be defeated with [47m(set-bogus-defun-hints-ok t)[0m, or if you still want to see a warning in such cases, [47m(set-bogus-defun-hints-ok :warn)[0m. This utility should perhaps be called [47mset-bogus-defun-hints-and-measures-ok[0m, but we retain its original name (from when it did not deal with bogus measures).") (set-bogus-measure-ok (defun) "Allow unnecessary [measure]s and [47m(xargs :hints ...)[0m. A call [47m(set-bogus-measure-ok X)[0m is just an abbreviation for [47m(set-bogus-defun-hints-ok X)[0m. See [set-bogus-defun-hints-ok].") (set-bogus-mutual-recursion-ok (mutual-recursion) "Allow unnecessary ``mutual recursion'' Examples: (set-bogus-mutual-recursion-ok t) (set-bogus-mutual-recursion-ok nil) (set-bogus-mutual-recursion-ok :warn) By default, ACL2 checks that when a ``clique'' of more than one function is defined simultaneously (using [47m[mutual-recursion][0m or [47m[defuns][0m), then every body calls at least one of the functions in the ``clique.'' Below, we refer to definitional events that fail this check as ``bogus'' mutual recursions. The check is important because ACL2 does not store induction schemes for functions defined with other functions in a [47m[mutual-recursion][0m or [47m[defuns][0m event. Thus, ACL2 may have difficulty proving theorems by induction that involve such functions. Moreover, the check can call attention to bugs, since users generally intend that their mutual recursions are not bogus. Nevertheless, there are times when it is advantageous to allow bogus mutual recursions, for example when they are generated mechanically, even at the expense of losing stored induction schemes. The first example above allows bogus mutual recursion. The second example disallows bogus mutual recursion; this is the default. The third example allows bogus mutual recursion, but prints an appropriate warning. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. General Form: (set-bogus-mutual-recursion-ok flg) where [47mflg[0m is either [47mt[0m, [47mnil[0m, or [47m:warn[0m.") (set-brr-evisc-tuple (brr brr-evisc-tuple set-evisc-tuple) "Set the [47m[brr-evisc-tuple][0m General Form: (set-brr-evisc-tuple ev state) where [47mev[0m is either the keyword [47m:default[0m or a legal [47m[evisc-tuple][0m. This function sets the evisceration tuple used by [brr-commands]. The current value can be retrieved with [47m[brr-evisc-tuple][0m. The initial value is [47m:default[0m which means the [47m:term[0m evisceration tuple is used. To see how the [47mbrr-evisc-tuple[0m is used see [47m[brr-evisc-tuple][0m. Think of [47mbrr-evisc-tuple[0m as a true global variable, not a locally bound variable of break-rewrite. In particular, if you set the [47mbrr-evisc-tuple[0m inside a break-rewrite interactive break and eventually exit that break --- either to enter a deeper break or return to a shallower break or to the ACL2 top-level --- the [47mbrr-evisc-tuple[0m will retain its chronologically most recent setting. The general command for setting any of the system evisc-tuples is [47m[set-evisc-tuple][0m.") (set-case-split-limitations (miscellaneous) "Set the [case-split-limitations] Also see [case-split-limitations] for an example of how this utility inhibits case splitting. Examples: (set-case-split-limitations '(500 100)) (set-case-split-limitations 'nil) (set-case-split-limitations '(500 nil)) The first of these prevents [47mclausify[0m from trying the subsumption/replacement (see below) loop if more than 500 [clause]s are involved. It also discourages the clause simplifier from splitting into more than 100 cases at once. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. See [hints] for discussion of a related hint, [47m:case-split-limitations[0m. Also see [splitter] for information about reports on rules that may be responsible for case splits. General Form: (set-case-split-limitations lst) where [47mlst[0m is either [47mnil[0m (denoting a list of two [47mnil[0ms), or a list of length two, each element of which is either [47mnil[0m or a natural number. When [47mnil[0m is used as an element, it is treated as positive infinity. The default setting is [47m(500 100)[0m. The first number specifies the maximum number of clauses that may participate in the ``subsumption/replacement'' loop. Because of the expensive nature of that loop (which compares every clause to every other in a way that is quadratic in the number of literals in the clauses), when the number of clauses exceeds about 1000, the system tends to ``go into a black hole,'' printing nothing and not even doing many garbage collections (because the subsumption/replacement loop does not create new clauses so much as it just tries to delete old ones). The initial setting is lower than the threshold at which we see noticeably bad performance, so you probably will not see this behavior unless you have raised or disabled the limit. Why raise the subsumption/replacement limit? The subsumption/replacement loop cleans up the set of subgoals produced by the simplifier. For example, if one subgoal is (implies (and p q r) s) [1] and another is (implies (and p (not q) r) s) [2] then the subsumption/replacement loop would produce the single subgoal (implies (and p r) s) [3] instead. This cleanup process is simply skipped when the number of subgoals exceeds the subsumption/replacement limit. But each subgoal must nonetheless be proved. The proofs of [1] and [2] are likely to duplicate much work, which is only done once in proving [3]. So with a low limit, you may find the system quickly produces a set of subgoals but then takes a long time to prove that set. With a higher limit, you may find the set of subgoals to be ``cleaner'' and faster to prove. Why lower the subsumption/replacement limit? If you see the system go into a ``black hole'' of the sort described above (no output, and few garbage collections), it could due to the subsumption/replacement loop working on a large set of large subgoals. You might temporarily lower the limit so that it begins to print the uncleaned set of subgoals. Perhaps by looking at the output you will realize that some function can be disabled so as to prevent the case explosion. Then raise or disable the limit again! The second number in the case-split-limitations specifies how many case splits the simplifier will allow before it begins to shut down case splitting. In normal operation, when a literal rewrites to a nest of [47mIF[0ms, the system simplifies all subsequent literals in all the contexts generated by walking through the nest in all possible ways. This can also cause the system to ``go into a black hole'' printing nothing except garbage collection messages. This ``black hole'' behavior is different from than mentioned above because space is typically being consumed at a prodigious rate, since the system is rewriting the literals over and over in many different contexts. As the simplifier sweeps across the clause, it keeps track of the number of cases that have been generated. When that number exceeds the second number in case-split-limitations, the simplifier stops rewriting literals. The remaining, unrewritten, literals are copied over into the output clauses. [47mIF[0ms in those literals are split out, but the literals themselves are not rewritten. Each output clause is then attacked again, by subsequent simplification, and eventually the unrewritten literals in the tail of the clause will be rewritten because the earlier literals will stabilize and stop producing case splits. The default setting of 100 is fairly low. We have seen successful proofs in which thousands of subgoals were created by a simplification. By setting the second number to small values, you can force the system to case split slowly. For example, a setting of 5 will cause it to generate ``about 5'' subgoals per simplification. You can read about how the simplifier works in the book Computer-Aided Reasoning: An Approach (Kaufmann, Manolios, Moore); also see [introduction-to-the-theorem-prover] for a detailed tutorial on using the ACL2 prover. If you think about it, you will see that with a low case limit, the initial literals of a goal are repeatedly simplified, because each time a subgoal is simplified we start at the left-most subterm. So when case splitting prevents the later subterms from being fully split out, we revisit the earlier terms before getting to the later ones. This can be good. Perhaps it takes several rounds of rewriting before the earlier terms are in normal form and then the later terms rewrite quickly. But it could happen that the earlier terms are expensive to rewrite and do not change, making the strategy of delayed case splits less efficient. It is up to you. Sometimes the simplifier produces more clauses than you might expect, even with case-split-limitations in effect. As noted above, once the limit has been exceeded, the simplifier does not rewrite subsequent literals. But [47mIF[0ms in those literals are split out nonetheless. Furthermore, the enforcement of the limit is --- as described above --- all or nothing: if the limit allows us to rewrite a literal then we rewrite the literal fully, without regard for limitations, and get as many cases as ``naturally'' are produced. It quite often happens that a single literal, when expanded, may grossly exceed the specified limits. If the second ``number'' is [47mnil[0m and the simplifier is going to produce more than 1000 clauses, a ``helpful little message'' to this effect is printed out. This output is printed to the system's ``comment window'' not the standard proofs output.") (set-cbd (books-reference) "To set the connected book directory Example Forms: ACL2 !>:set-cbd "/usr/home/smith/" ACL2 !>:set-cbd "my-acl2/books" See [cbd] for a description of the connected book directory. General Form: (set-cbd str) where [47mstr[0m evaluates to a nonempty string that represents the desired directory (see [pathname]). This command sets the connected book directory according to that string; see [cbd]. Thus, this command may determine which files are processed by [47m[include-book][0m, [47m[certify-book][0m, and [47m[ld][0m [command]s, as well as by file operations such as [47m[open-input-channel][0m. IMPORTANT: Pathnames in ACL2 are in the Unix (trademark of AT&T) style. That is, the character ``[47m/[0m'' separates directory components of a pathname, and pathnames are absolute when they start with this character, and relative otherwise. See [pathname].") (set-check-invariant-risk (programming advanced-features guard debugging invariant-risk) "Affect certain [program]-mode updates to [stobj]s or [arrays] See [invariant-risk] for an introduction to the notion of invariant-risk. Also see [set-register-invariant-risk] for a way to avoid marking a specific set of functions as having invariant-risk, which can be much safer than avoiding invariant-risk checking for all functions at runtime as described below. Briefly put, if a syntactic analysis suggests that the call of a [47m:[0m[47m[program][0m-mode function can lead to an ill-guarded call of a [stobj] updater or of [47m[aset1][0m or [47m[aset2][0m, then ACL2 considers such a call to be an ``invariant-risk call''. There are four different ways that ACL2 can handle such a call, corresponding to four different values of the ``invariant-risk mode'', which is the value obtained by evaluating [47m(get-check-invariant-risk state)[0m. The default invariant-risk mode is [47m:WARNING[0m: in that mode, ACL2 prints a warning when encountering a topmost invariant-risk call and uses a slower mode of execution in order to avoid ill-guarded calls as discussed above. Mode [47mT[0m has the same behavior, but without the warning. Mode [47m:ERROR[0m causes a break when encountering a topmost invariant-risk call; the Lisp should give you the option of continuing (as though the mode were [47mT[0m) or aborting, as you choose. Finally, mode [47mNIL[0m --- which is unsafe and hence involves a trust tag (see [defttag]), as discussed below --- avoids any special treatment for invariant-risk calls. The utility, [47mset-check-invariant-risk[0m, is provided for changing invariant-risk mode. The simplest case is when that utility is only called with one argument, in which case, that argument becomes the new invariant-risk mode, as follows. (set-check-invariant-risk :ERROR) ; new mode is :ERROR (set-check-invariant-risk :WARNING) ; new mode is :WARNING (the default) (set-check-invariant-risk T) ; new mode is T (set-check-invariant-risk NIL) ; new mode is NIL The argument is evaluated (to itself when given one of the four constants shown above). There must be an active trust tag in order to set the invariant-risk mode to [47mNIL[0m. However, ACL2 arranges automatically to create a temporary trust tag when invoking [47mset-check-invariant-risk[0m on an expression that is other than one of the symbols [47m:ERROR[0m, [47m:WARNING[0m, or [47mT[0m. An environment variable, [47mACL2_CHECK_INVARIANT_RISK[0m, provides a convenient way to evaluate one of these forms automatically when ACL2 is invoked. When that environment variable has a value other than the empty string, the value is converted to a symbol after converting to upper-case with the function [47m[string-upcase][0m, and then corresponding call is make automatically (after loading the [ACL2-customization] file, if any). "error", ":error" ==> (set-check-invariant-risk :ERROR) "warning", ":warning" ==> (set-check-invariant-risk :WARNING) "t" ==> (set-check-invariant-risk T) "nil" ==> (set-check-invariant-risk NIL) Whether by direct user evaluation or environment variable, these calls simply set a certain global parameter, [47m'check-invariant-risk[0m (technically, a [state] global variable). However, they are not embedded event forms (see [embedded-event-form]: they cannot appear at the top level of books, [47m[encapsulate][0m [events], or [47m[progn][0m events. A non-nil second (optional) argument causes an [47m[ACL2-defaults-table][0m entry to be made, associating the key [47m:check-invariant-risk[0m with the invariant-risk mode. Thus, the following forms are embedded event forms. Notice the new ``mode'', [47m:CLEAR[0m, which behaves as though removing the key [47m:check-invariant-risk[0m from the [47m[ACL2-defaults-table][0m. (set-check-invariant-risk :ERROR t) (set-check-invariant-risk :WARNING t) (set-check-invariant-risk t t) (set-check-invariant-risk NIL t) (set-check-invariant-risk :CLEAR t) ; avoid using table to determine mode As before, the value [47mNIL[0m requires an active trust tag; but unlike before, ACL2 does not create a temporary trust tag, but instead expect the user to have created one already. Note also that changes to the [47macl2-defaults-table[0m are automatically local to a book or [47m[encapsulate][0m event in which they occur; [47m[ACL2-defaults-table][0m. Therefore, do not surround the forms just above with [47m[local][0m. When the [47m[ACL2-defaults-table][0m associates the key [47m:check-invariant-risk[0m with any value (as in the calls above) other than [47m:CLEAR[0m, then the invariant-risk mode is actually the ``minimum'' of that value and the value of the global parameter, [47m'check-invariant-risk[0m, where the modes are ordered from greatest to least as shown in the displays above. An [observation] is printed when the new mode does not change: for example, if you start your ACL2 session by evaluating [47m(set-check-invariant-risk :ERROR t)[0m, then the invariant-risk mode will be the minimum of the existing (default) value of [47m:WARNING[0m and the proposed value (newly stored in the [47macl2-defaults-table[0m of [47m:ERROR[0m; that minimum is [47m:WARNING[0m, so the mode will remain [47m:WARNING[0m and an [observation] will be printed to that effect. You can see all the relevant mode values as follows. ; current invariant-risk mode (:WARNING by default): (get-check-invariant-risk state) ; invariant-risk mode stored in global parameter 'check-invariant-risk: (@ check-invariant-risk) ; invariant-risk mode stored in the acl2-defaults-table: (table acl2-defaults-table :check-invariant-risk) The following log illustrates the interaction of the two ways of setting the invariant-risk mode (state global and table). ACL2 !>(set-check-invariant-risk :error t) ACL2 Observation in SET-CHECK-INVARIANT-RISK: No change is being made in the value computed by (GET-CHECK-INVARIANT-RISK STATE). This happens when the value of state global 'check-invariant-risk is less than the new table value; see :DOC set-check-invariant-risk. :ERROR ACL2 !>(get-check-invariant-risk state) :WARNING ACL2 !>(@ check-invariant-risk) :WARNING ACL2 !>(set-check-invariant-risk :error) :ERROR ACL2 !>(@ check-invariant-risk) :ERROR ACL2 !>(get-check-invariant-risk state) :ERROR ACL2 !>(set-check-invariant-risk t t) T ACL2 !>(get-check-invariant-risk state) T ACL2 !>(set-check-invariant-risk :warning) ACL2 Observation in SET-CHECK-INVARIANT-RISK: No change is being made in the value computed by (GET-CHECK-INVARIANT-RISK STATE), because the new value of state global 'check-invariant-risk is greater than the table value; see :DOC set-check-invariant-risk. :WARNING ACL2 !>(get-check-invariant-risk state) T ACL2 !>(set-check-invariant-risk :clear t) :CLEAR ACL2 !>(get-check-invariant-risk state) :WARNING ACL2 !> Note that the handling of an invariant-risk call of a function, [47mf[0m, depends on the current invariant-risk mode, not on the mode in place when [47mf[0m was defined. It might not be obvious how a given function call could lead to an ill-guarded call of a [stobj] updater or of a primitive with invariant-risk such as [aref1]. It should be reasonably straightforward to write a utility that provides this information; contact the ACL2 implementors if you want assistance in writing such a utility.") (set-checkpoint-summary-limit (set-gag-mode) "Control printing of key checkpoints upon a proof's failure See [set-gag-mode] for a discussion of key checkpoints. Examples: ; (Default) When a proof fails, print all key checkpoints before ; induction but at most 3 key checkpoints after induction: (set-checkpoint-summary-limit (nil . 3)) ; When a proof fails, print at most 3 key checkpoints before ; induction but all 3 key checkpoints after induction: (set-checkpoint-summary-limit (3 . nil)) ; When a proof fails, print at most 3 key checkpoints before ; induction and at most 5 key checkpoints after induction: (set-checkpoint-summary-limit (3 . 5)) ; When a proof fails, print at most 3 key checkpoints before ; induction and at most 3 key checkpoints after induction: (set-checkpoint-summary-limit (3 . 3)) ; or equivalently, (set-checkpoint-summary-limit 3) ; When a proof fails, print all key checkpoints: (set-checkpoint-summary-limit (nil . nil)) ; or equivalently, (set-checkpoint-summary-limit nil) ; When a proof fails, print no information at all about key checkpoints: (set-checkpoint-summary-limit t) General Forms: (set-checkpoint-summary-limit (n1 . n2)) (set-checkpoint-summary-limit n) (set-checkpoint-summary-limit t) where each of [47mn1[0m and [47mn2[0m is a natural number or [47mnil[0m. For the second form, [47mn[0m can be a natural number or [47mnil[0m and is treated as [47m(n . n)[0m. The value [47mt[0m inhibits all printing of checkpoint [summary] information. The values [47mn1[0m and [47mn2[0m determine printing of key checkpoints generated before the first induction and generated after the first induction, respectively, where at most [47mn1[0m or [47mn2[0m (respectively) such key checkpoints are printed unless the value is [47mnil[0m, in which case there is no limitation. The argument [47mx[0m for [47mset-checkpoint-summary-limit[0m, as described above, may be quoted, i.e. supplied as [47m'x[0m or [47m(quote x)[0m. Thus, you may use the keyword form (see [keyword-commands]) if you prefer, for example: :set-checkpoint-summary-limit (nil . 3) To see the current limit, invoke [47m(checkpoint-summary-limit)[0m. Note that if some subgoal in a set of key checkpoints is [47mNIL[0m, then such a subgoal will be printed first in the corresponding list, provided of course that the list isn't entirely ignored because of a limit of 0. See [nil-goal].") (set-compile-fns (compilation) "Have each function compiled as you go along. Example Forms: (set-compile-fns t) ; new functions compiled after DEFUN (set-compile-fns nil) ; new functions not compiled after DEFUN Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Also see [comp], because it may be more efficient in some Common Lisps to compile many functions at once rather than to compile each one as you go along. General Form: (set-compile-fns term) where [47mterm[0m is a variable-free term that evaluates to [47mt[0m or [47mnil[0m. This macro is equivalent to (table acl2-defaults-table :compile-fns term) and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. However, unlike the above simple call of the [47m[table][0m event function (see [table]), no output results from a [47mset-compile-fns[0m event. [47mSet-compile-fns[0m may be thought of as an event that merely sets a flag to [47mt[0m or [47mnil[0m. The flag's effect is felt when functions are defined, as with [47m[defun][0m. If the flag is [47mt[0m, functions are automatically compiled after they are defined, as are their executable-counterparts (see [evaluation]). Otherwise, functions are not automatically compiled. Exception: The flag has no effect when explicit compilation is suppressed; see [compilation]. Because [47mset-compile-fns[0m is an event, the old value of the flag is restored when a [47mset-compile-fns[0m event is undone. Even when [47m:set-compile-fns t[0m has been executed, functions are not individually compiled when processing an [47m[include-book][0m event. If you wish to include a book of compiled functions, we suggest that you first certify it with the [compilation] flag set (see [certify-book]) or else compile the book by supplying the appropriate [47mload-compiled-file[0m argument to [47m[include-book][0m. More generally, [compilation] via [47mset-compile-fns[0m is suppressed when the [state] global variable [47m[ld-skip-proofsp][0m has value [47m'[0m[47m[include-book][0m.") (set-compiler-enabled (compilation) "Disable [compilation]. For a thorough discussion of this utility, see [compilation]. Probably its most common use is the following, in order to prohibit [47m[include-book][0m from attempting to include compiled files: (set-compiler-enabled nil state)") (set-constraint-tracking (encapsulate) "Generate markers to indicate origins of constraints General Form: (set-constraint-tracking flg) where [47mflg[0m is Boolean. When [47mflg[0m is [47mt[0m the constraint subgoals generated by the [47m:functional-instance[0m hint (see [hints] and [lemma-instance]) have an additional hypothesis of the form [47m(extra-info :constraint ...)[0m where the second argument to [47mextra-info[0m is a quoted expression that indicates where the constraint came from. Since [47mextra-info[0m is a disabled defined function that always returns [47mt[0m, the addition of this hypothesis does not change the meaning of the formula. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It uses the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs. We expect this facility to be used only when a proof involving functional instantiation is failing and inspection of the subgoals or checkpoints leaves you asking the question ``why is it trying to prove this?'' But turning on this facility can cause a failing proof to fail even earlier because the [47mextra-info[0m hypotheses may change the course of the proof. We discuss some ways of handling this below. But first we give an example of the output that might be seen when the [47mconstraint-tracking[0m flag is set. This example is intended to give you an idea of how to read the [47mextra-info[0m --- which of course is only visible if [47m[gag-mode][0m is [47mnil[0m or a checkpoint is printed. Because the ``quoted expression that indicates where the constraint came from'' is entirely informal, we do not give you a formal syntax and semantics for it. Just study the examples. Furthermore, as this facility matures we may well change the quoted expressions to be more informative. Recall the example use of [47m:functional-instance[0m in [functional-instantiation-example]. (To understand what follows you really ought to read the example just cited.) In particular, after we use [47m[encapsulate][0m to constrain some functions and then prove a few useful lemmas, we prove the following by functional instantiation. We include the entire un-gagged proof output below from a session in which the [47mconstraint-tracking[0m flag has been set. ACL2 !>(DEFTHM TIMES-LIST-REV (IMPLIES (NUMBER-LISTP X) (EQUAL (TIMES-LIST (REV X)) (TIMES-LIST X))) :HINTS (("Goal" :USE ((:FUNCTIONAL-INSTANCE AC-FN-LIST-REV (AC-FN *) (AC-FN-ROOT (LAMBDA NIL 1)) (AC-FN-DOMAIN ACL2-NUMBERP) (AC-FN-LIST TIMES-LIST) (AC-FN-DOMAIN-LIST NUMBER-LISTP)))))) [Note: A hint was supplied for the goal above. Thanks!] We augment the goal with the hypothesis provided by the :USE hint. The hypothesis can be derived from AC-FN-LIST-REV via functional in- stantiation, provided we can establish the seven constraints generated; the constraints can be simplified using the :executable-counterparts of IF and TAU-SYSTEM and the simple :rewrite rules ASSOCIATIVITY-OF-* and UNICITY-OF-1. We are left with the following four subgoals. Subgoal 4 (IMPLIES (EXTRA-INFO :CONSTRAINT '((DEFUN AC-FN-LIST) ((AC-FN BINARY-*) (AC-FN-LIST TIMES-LIST) (AC-FN-ROOT (LAMBDA NIL '1))))) (EQUAL (TIMES-LIST X) (IF (ATOM X) 1 (* (CAR X) (TIMES-LIST (CDR X)))))). But simplification reduces this to T, using the :definitions ATOM and TIMES-LIST and primitive type reasoning. Subgoal 3 (IMPLIES (AND (EXTRA-INFO :CONSTRAINT '((THEOREM AC-FN-ID) ((AC-FN BINARY-*) (AC-FN-DOMAIN ACL2-NUMBERP) (AC-FN-ROOT (LAMBDA NIL '1))))) (ACL2-NUMBERP X)) (EQUAL (FIX X) X)). But simplification reduces this to T, using the :definition FIX and primitive type reasoning. Subgoal 2 (IMPLIES (EXTRA-INFO :CONSTRAINT '((THEOREM AC-FN-COMM) ((AC-FN BINARY-*) (AC-FN-DOMAIN ACL2-NUMBERP) (AC-FN-ROOT (LAMBDA NIL '1))))) (EQUAL (* X Y) (* Y X))). But simplification reduces this to T, using primitive type reasoning and the :rewrite rule COMMUTATIVITY-OF-*. Subgoal 1 (IMPLIES (EXTRA-INFO :CONSTRAINT '((DEFUN AC-FN-DOMAIN-LIST) ((AC-FN-DOMAIN ACL2-NUMBERP) (AC-FN-DOMAIN-LIST NUMBER-LISTP)))) (EQUAL (NUMBER-LISTP X) (COND ((ATOM X) T) ((ACL2-NUMBERP (CAR X)) (NUMBER-LISTP (CDR X))) (T NIL)))). But simplification reduces this to T, using the :definitions ATOM and NUMBER-LISTP and primitive type reasoning. Q.E.D. Note the [47mEXTRA-INFO[0m hypotheses. For example, in [47mSubgoal 1[0m, just above, the hypothesis is (EXTRA-INFO :CONSTRAINT '((DEFUN AC-FN-DOMAIN-LIST) ((AC-FN-DOMAIN ACL2-NUMBERP) (AC-FN-DOMAIN-LIST NUMBER-LISTP)))) which indicates that [47mSubgoal 1[0m is the functional instantiation of the defining equation for constrained function [47mAC-FN-DOMAIN-LIST[0m under the functional substitution shown. [47mSubgoal 1[0m establishes that [47mNUMBER-LISTP[0m satisfies the constraint on [47mAC-FN-DOMAIN-LIST[0m. You can view the definition of [47mAC-FN-DOMAIN-LIST[0m with the [47m:[0m[47mpe[0m command. By inspecting the [47mextra-info[0m in [47mSubgoal 2[0m, above, (EXTRA-INFO :CONSTRAINT '((THEOREM AC-FN-COMM) ((AC-FN BINARY-*) (AC-FN-DOMAIN ACL2-NUMBERP) (AC-FN-ROOT (LAMBDA NIL '1))))) you should be able to recognize that it establishes that multiplication is commutative, which is required by the constraining [47mTHEOREM[0m named [47mAC-FN-COMM[0m, since we are replacing [47mAC-FN[0m by multiplication. You can view the named theorem with the [47m:[0m[47mpe[0m command. You might occasionally see something like this (EXTRA-INFO :CONSTRAINT '((:THEOREM <term>) <fn-substitution>)) Note that this occurrence of the word ``THEOREM'' is as a keyword and what follows it is a term rather than a name. This stems from the use of the [47m:THEOREM[0m [lemma-instance] in the [47m:functional-instance[0m hint. In this case, the constraint is the term shown. The presence of these additional hypotheses may break some proofs that formerly worked! For example, if [47mconstraint-tracking[0m is off, the events in the ACL2 Community Book [47m/books/centaur/misc/tailrec.lisp[0m can be processed successfully. But if the flag is on the proofs fails because the book is employing a very restrictive proof strategy designed to deal exactly with proving certain mechanically generated formulas and the [47mextra-info[0m hypothesis makes the subgoals unrecognizable to that strategy. One way of dealing with this is to issue ``bye'' [hints], e.g., [47m:by nil[0m, to subgoals that are failing before the one you want to see. Alternatively, you might use the [47m:[0m[47m[otf-flg][0m option to allow failing subgoals to be pushed so the prover can carry on to later subgoals. A third way to deal with this is to prove the rewrite rule (defthm drop-extra-info-constraints (implies (equal x :constraint) (equal (extra-info x y) t)) :hints (("Goal" :in-theory (enable extra-info)))) which will cause the [47mextra-info[0m hypotheses to rewrite to [47mt[0m by the first simplification. (Aside: The corresponding unconditional [rewrite] rule, [47m(equal (extra-info :constraint y) t)[0m, is undesirable because it causes the [47mextra-info[0m hypotheses to be simplified to [47mt[0m before the goals are displayed to the user.) So for example, if a [47m:functional-instance[0m hint produced several immediate goals, one of which is [47mSubgoal 3[0m, and the constraint tracking flag is set, then [47mSubgoal 3[0m will have an [47mextra-info[0m hypothesis indicating the origin of that subgoal. If the rewrite rule above is available, the [47mextra-info[0m will have disappeared in the descendants of [47mSubgoal 3[0m. So if you find yourself asking ``Where did this goal come from?'' you might refer back to the parent, [47mSubgoal 3[0m, produced by the functional instance hint. (Remember, descendant subgoals, e.g., [47mSubgoal 3.17''[0m, have [clause-identifier]s that indicate their parentage, [47mSubgoal 3[0m.) That said, some proof strategies employed in the regression (including the one in the [47mtailrec.lisp[0m book cited above) are so automatic and thus so tightly restricted that you may not find a way to get over the obstacles created by the [47mextra-info[0m hypotheses! However, of the thousands of books in the regression, as of Version 8.6, only three books fail to recertify when the constraint tracking flag is turned on, and one of those three succeeds if the rewrite rule above is included. So we await further experience with this utility before investing more time in it.") (set-debugger-enable (debugging) "Control whether Lisp errors and breaks invoke the Lisp debugger Forms (see below for explanations and GCL exceptions): (set-debugger-enable t) ; enable breaks into the raw Lisp debugger (set-debugger-enable :break) ; same as above :set-debugger-enable t ; same as above (set-debugger-enable :break-bt) ; as above, but print a backtrace first (set-debugger-enable :bt-break) ; as above, but print a backtrace first (set-debugger-enable :bt) ; print a backtrace but do not enter debugger (set-debugger-enable :never) ; disable all breaks into the debugger (set-debugger-enable nil) ; disable debugger except when calling break$ [3mIntroduction.[0m Suppose we define [47mfoo[0m in [47m:[0m[47m[program][0m mode to take the [47m[car][0m of its argument. This can cause a raw Lisp error. ACL2 will then return control to its top-level loop unless you enable the Lisp debugger, as shown below (except: the error message can take quite a different form in non-ANSI GCL). ACL2 !>(defun foo (x) (declare (xargs :mode :program)) (car x)) Summary Form: ( DEFUN FOO ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FOO ACL2 !>(foo 3) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Attempt to take the car of 3 which is not listp. *********************************************** If you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !>(SET-DEBUGGER-ENABLE T) <state> ACL2 !>(foo 3) Error: Attempt to take the car of 3 which is not listp. [condition type: TYPE-ERROR] Restart actions (select using :continue): 0: Abort entirely from this (lisp) process. [Current process: Initial Lisp Listener] [1] ACL2(1): [RAW LISP] [3mDetails.[0m ACL2 usage is intended to take place inside the ACL2 read-eval-print loop (see [lp]). Indeed, in most Lisp implementations ACL2 comes up inside that loop, as evidenced by the prompt: ACL2 !> However, one can occasionally hit a raw Lisp error. Here is the above example again, this time for a GCL implementation, which unfortunately gives a slightly less aesthetic report. ACL2 !>(foo 3) Error: 3 is not of type LIST. Fast links are on: do (si::use-fast-links nil) for debugging Error signalled by CAR. Backtrace: funcall > system:top-level > lisp:lambda-closure > lp > acl2_*1*_acl2::foo > foo > car > system:universal-error-handler > system::break-level-for-acl2 > let* > UNLESS ACL2 !> Here, the user has defined [47mfoo[0m in [47m:[0m[47m[program][0m mode, with an implicit [guard] of [47mt[0m. The ACL2 evaluator therefore called the Lisp evaluator, which expected [47mnil[0m or a [47m[consp][0m argument to [47m[car][0m. By default, ACL2 will return to its top-level loop (at the same level of [47m[ld][0m) when there is a raw Lisp error, as though a call of [47m[er][0m with flag [47mHARD[0m has been evaluated. If instead you want to enter the raw Lisp debugger in such cases, evaluate the following form. (set-debugger-enable t) You can subsequently return to the default behavior with: (set-debugger-enable nil) Either way, you can enter the Lisp debugger from within the ACL2 loop by evaluating [47m([0m[47m[break$][0m[47m)[0m. If you want [47mbreak$[0m disabled, then evaluate the following, which disables entry to the Lisp debugger not only for Lisp errors but also when executing [47m(break$)[0m. (set-debugger-enable :never) The discussion above also applies to interrupts (from [47mControl-C[0m) in some, but not all, host Common Lisps --- perhaps all except for non-ANSI GCL, where interrupts will likely always put you into the debugger. It remains to discuss options [47m:break[0m, [47m:bt[0m, [47m:break-bt[0m, and [47m:bt-break[0m. Option [47m:break[0m is synonymous with option [47mt[0m, while option [47m:bt[0m prints a backtrace. Options [47m:break-bt[0m and [47m:bt-break[0m are equivalent, and each has the combined effect of [47m:bt[0m and [47m:break[0m: a backtrace is printed and then the debugger is entered. Note that [47mset-debugger-enable[0m applies not only to raw Lisp errors, but also to ACL2 errors: those affected by [47m[break-on-error][0m. However, for ACL2 errors, entering the debugger is controlled only by [47mbreak-on-error[0m, not by [47mset-debugger-enable[0m. For ACL2 errors encountered after evaluating [47m(break-on-error t)[0m, the [47mset-debugger-enable[0m values of [47m:bt[0m, [47m:break-bt[0m, and [47m:bt-break[0m will result in the same effect: in many host Lisps, this effect will be to cause a backtrace to be printed. Remark for Common Lisp hackers (except for the case that the host Lisp is non-ANSI GCL). You can customize the form of the backtrace printed by entering raw Lisp (with [47m:q[0m) and then redefining function [47mprint-call-history[0m, whose definition immediately precedes that of [47mbreak-on-error[0m in ACL2 source file [47mld.lisp[0m. Of course, all bets are off when defining any function in raw Lisp, but as a practical matter you are probably fine as long as your books are ultimately certified with an unmodified copy of ACL2. If you come up with improvements to [47mprint-call-history[0m, please pass them along to the ACL2 implementors.") (set-default-backchain-limit (backchain-limit) "Sets the default backchain-limit used when admitting a rule Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. This event sets the default [47m[backchain-limit][0m used when a new [47m[rewrite][0m, [47m[linear][0m, [47m[meta][0m, or [47m[type-prescription][0m rule is admitted. Its value may be a two-element list whose elements are each either [47mnil[0m or a non-negative integer. Its value [47mx[0m may also be [47mnil[0m or a non-negative integer, which is treated as the two element list [47m(x x)[0m. The first element of the list is used to limit backchaining for a rule of class [47m[type-prescription][0m while the second element is used to limit backchaining for the other three classes of rules mentioned above. See [backchain-limit] for details about how backchain-limits are used. The examples below assume that a new rule doesn't itself specify a value for [47m:backchain-limit-lst[0m. :set-default-backchain-limit nil ; do not impose backchain limits for the ; rule :set-default-backchain-limit 0 ; allow only type reasoning for ; relieving a new rule's hypotheses :set-default-backchain-limit 500 ; allow backchaining through a new rewrite, ; linear, or meta rule's hypotheses to a ; depth of no more than 500 (set-default-backchain-limit 500) ; same as above :set-default-backchain-limit (nil 500) ; same as above (set-default-backchain-limit '(nil 500)) ; same as above (set-default-backchain-limit '(3 500)) ; for a new :type-prescription rule, allow ; type-set backchaining to a depth ; of no more than 3; for a new ; rule of class :rewrite, :linear, ; or :meta, allow backchaining to ; a depth of no more than 50 (set-default-backchain-limit '(nil 500)) ; do not limit backchaining for a ; new :type-prescription rule; for ; a new rule of class :rewrite, ; :linear, or :meta, allow ; backchaining to a depth of no ; more than 50 The initial default backchain-limit is [47mnil[0m.") (set-default-hints (default-hints) "Set the default hints Examples: (set-default-hints '((computed-hint-1 clause) (computed-hint-2 clause stable-under-simplificationp))) (set-default-hints nil) Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [set-default-hints!] for a corresponding non-[47m[local][0m event. General Form: (set-default-hints lst) where [47mlst[0m is a list. Generally speaking, the elements of [47mlst[0m should be suitable for use as [47m[computed-hints][0m. Whenever a [47m[defthm][0m or [47m[thm][0m command is executed, the default hints are appended to the right of any explicitly provided [47m:[0m[47m[hints][0m in the command. The same applies to [47m[defun][0ms as well ([47m:hints[0m, [47m:guard-hints[0m, and (for ACL2(r)) [47m:std-hints[0m). The hints are then translated and processed just as though they had been explicitly included. Technically, we do not put restrictions on [47mlst[0m, beyond that it is a true list. It would be legal to execute (set-default-hints '(("Goal" :use lemma23))) with the effect that the given hint is added to subsequent hints supplied explicitly. An explicit "Goal" hint would, however, take priority, as suggested by the mention above of ``appended to the right.'' Note that [47mset-default-hints[0m sets the default hints as specified. To add to or remove from the current default, see [add-default-hints] and see [remove-default-hints]. To see the current default hints, see [default-hints]. Finally, note that the effects of [47mset-default-hints[0m, [47m[add-default-hints][0m, and [47m[remove-default-hints][0m are [47m[local][0m to the book in which they appear. Thus, users who include a book with such forms will not have their default hints affected by such forms. In order to export the effect of setting the default hints, use [47m[set-default-hints!][0m, [47m[add-default-hints!][0m, or [47m[remove-default-hints!][0m. For a related feature, which however is only for advanced system builders, see [override-hints].") (set-default-hints! (default-hints) "Set the default hints non-[47m[local][0mly Please see [set-default-hints], which is the same as [47mset-default-hints![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [set-default-hints] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (set-deferred-ttag-notes (defttag) "Modify the verbosity of [47mTTAG NOTE[0m printing General Form: (set-deferred-ttag-notes val state) where [47mval[0m is [47mt[0m or [47mnil[0m. See [defttag] for a discussion of trust tags (ttags). By default, a ``[47mTTAG NOTE[0m'' is printed in order to indicate reliance on a ttag. When many such notes are printed, it may be desirable to avoid seeing them all. Upon evaluation of the form (set-deferred-ttag-notes t state) ACL2 will enter a deferred mode for the printing of ttag notes. In this mode, only the first ttag note is printed for each top-level command, and the remainder are summarized before the next top-level prompt (if any) is printed, hence before the next command is evaluated. That summary is merely a list of ttags, but the summary explains that the full ttag notes may be printed with the command [47m(show-ttag-notes)[0m. Note that [47m(show-ttag-notes)[0m spares you duplicate ttag notes. If you want to see every ttag note as it would normally appear, for maximum security, do not evaluate the command [47m(set-deferred-ttag-notes t state)[0m. You can undo the effect of this command, returning to an immediate mode for printing ttag notes, by evaluating: (set-deferred-ttag-notes nil state)") (set-difference$ (lists acl2-built-ins) "Elements of one list that are not elements of another General Forms: (set-difference$ l1 l2) (set-difference$ l1 l2 :test 'eql) ; same as above (eql as equality test) (set-difference$ l1 l2 :test 'eq) ; same, but eq is equality test (set-difference$ l1 l2 :test 'equal) ; same, but equal is equality test [47m(Set-difference$ l1 l2)[0m equals a list that contains the [47m[member][0ms of [47ml1[0m that are not [47m[member][0ms of [47ml2[0m. More precisely, the resulting list is the same as one gets by deleting the members of [47ml2[0m from [47ml1[0m, leaving the remaining elements in the same order as in [47ml1[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing members of the two lists. The [guard] for a call of [47mset-difference$[0m depends on the test. In all cases, both arguments must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then one of the arguments must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47mset-difference$[0m and its variants: [47m(set-difference-eq l1 l2)[0m is equivalent to [47m(set-difference$ l1 l2 :test 'eq)[0m; [47m(set-difference-equal l1 l2)[0m is equivalent to [47m(set-difference$ l1 l2 :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47mset-difference-equal[0m. [31;1mFunction: [0m<set-difference-equal> (defun set-difference-equal (l1 l2) (declare (xargs :guard (and (true-listp l1) (true-listp l2)))) (cond ((endp l1) nil) ((member-equal (car l1) l2) (set-difference-equal (cdr l1) l2)) (t (cons (car l1) (set-difference-equal (cdr l1) l2))))) [47mSet-difference$[0m is similar to the Common Lisp primitive [47mset-difference[0m. However, Common Lisp does not specify the order of elements in the result of a call of [47mset-difference[0m.") (set-difference-eq (pointers) "See [set-difference$].") (set-difference-equal (pointers) "See [set-difference$].") (set-difference-theories (theories theory-functions) "Difference of two [theories] Example: (set-difference-theories (current-theory :here) '(fact (fact))) General Form: (set-difference-theories th1 th2) where [47mth1[0m and [47mth2[0m are [theories] (see [theories]). To each of the arguments there corresponds a runic theory. This function returns the set-difference of those two runic [theories], represented as a list and ordered chronologically. That is, a [rune] is in the result iff it is in the first runic theory but not in the second. The standard way to ``disable'' a theory, [47mlst[0m, is: [47m(in-theory (set-difference-theories (current-theory :here) lst))[0m. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (set-duplicate-keys-action (macro-args macros programming advanced-features) "Control action for macro calls with duplicate keyword arguments Example Forms: (set-duplicate-keys-action thm :warning) (set-duplicate-keys-action my-macro-1 nil) General Forms: (set-duplicate-keys-action name :error) (set-duplicate-keys-action name :warning) (set-duplicate-keys-action name nil) where [47mname[0m is a symbol, one that is generally expected to be the name of a macro. By default, an error occurs when ACL2 encounters a macro call with duplicate keys, for example [47m(foo 3 :y 4 :y 5)[0m where [47m:y[0m is a keyword argument of the macro, [47mfoo[0m. However, the event [47m(set-duplicate-keys-action name val)[0m can be used to determine whether such duplicate keys cause an error, a warning, or neither, according to whether [47mval[0m is the keyword [47m:error[0m, [47m:warning[0m, or [47mnil[0m, respectively. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [set-duplicate-keys-action!] for a corresponding non-[47m[local][0m event. Indeed, [47m(set-duplicate-keys-action ...)[0m is equivalent to [47m(local (set-duplicate-keys-action! ...))[0m.") (set-duplicate-keys-action! (output-controls) "Non-[47m[local][0m version of [47m[set-duplicate-keys-action][0m Please see [set-duplicate-keys-action], which is the same as [47mset-duplicate-keys-action![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Perhaps [set-duplicate-keys-action] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (set-dwp (type-reasoning) "Affect the effort made in [type-reasoning] This is a relatively advanced event that affects the [type-reasoning] heuristics. (The name ``dwp'' stands for ``double-whammy property'' because the effect pertains to making a second attempt.) The default behavior is obtained with [47m(set-dwp nil)[0m, but type reasoning makes an extra effort after evaluation of [47m(set-dwp t)[0m. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [set-dwp!] for a corresponding non-[47m[local][0m event. General Form: (set-dwp val) where [47mval[0m is arbitrary but is typically [47mt[0m or [47mnil[0m, since every non-[47mnil[0m value is treated the same as [47mt[0m. The following example, from Eric Smith, proves after evaluating [47m(set-dwp t)[0m but otherwise fails. (thm (implies (and (<= 0 (* 2 k)) ; extra hyp ; (unsigned-byte-p 4 k) (integerp x) (< x (+ 4 (* 2 k)))) (<= x (+ 3 (* 2 k)))) :hints (("Goal" :in-theory (disable unsigned-byte-p)))) So why not always evaluate [47m(set-dwp t)[0m at the beginning of an ACL2 session? Such a change added 3.9% to the certification of the ACL2 community books, and at least one book took almost twice as long to certify. That isn't a huge penalty, but on the other hand it seems likely that [47m(set-dwp t)[0m is helpful only in rare instances. To get the current value of [47mdwp[0m, evaluate [47m(get-dwp nil (w state))[0m.") (set-dwp! (type-reasoning) "Affect the effort made in [type-reasoning], non-[47m[local][0mly Please see [set-dwp], which is the same as [47mset-dwp![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [set-dwp] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (set-enforce-redundancy (redundant-events) "Require most events to be redundant General Forms: (set-enforce-redundancy nil) ; do not require redundancy (default) (set-enforce-redundancy t) ; most events (see below) must be redundant (set-enforce-redundancy :warn) ; warn for most non-redundant events Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. General Form: (set-enforce-redundancy flag) where [47mflag[0m is [47mnil[0m, [47mt[0m, or [47m:warn[0m, as indicated above. This macro is essentially equivalent to (table acl2-defaults-table :enforce-redundancy flag) and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. However, unlike the above simple call of the [47m[table][0m event function (see [table]), no output results from a [47mset-enforce-redundancy[0m event. [47mSet-enforce-redundancy[0m may be thought of as an event that merely sets a flag as indicated above, which determines whether most [events], including [47m[defun][0m and [47m[defthm][0m events, are allowed to be redundant; see [redundant-events]. The exceptions are [47m[deflabel][0m, [47m[defpkg][0m, [47m[encapsulate][0m, [47m[include-book][0m, [47m[push-untouchable][0m, [47m[remove-untouchable][0m, [47m[set-body][0m, and [47m[table][0m [events]. Any other type of non-redundant event will cause an error if [47mflag[0m is [47mt[0m and a warning if [47mflag[0m is [47mnil[0m, [3mexcept[0m in the course of carrying out an [47m[include-book][0m form or the second pass of an [47m[encapsulate][0m form. Note that because [47m[table][0m [events] that set the [47m[ACL2-defaults-table][0m are implicitly [47m[local][0m, [47mset-enforce-redundancy[0m events are ignored when including books. However, the presence of the event [47m(set-enforce-redundancy t)[0m in a book guarantees that its subsequent definitions and theorems are redundant. This can be a useful property to maintain in library development, as we now describe. An example of the use of this form can be found in the community [books] under directory [47mbooks/rtl/rel4/[0m. The intention in that directory has been to put all the gory details in subdirectories [47msupport/[0m and [47marithmetic/[0m, so that the books in subdirectory [47mlib/[0m contain only the ``exported'' definitions and theorems. This approach is useful for human readability. Moreover, suppose we want to prove new theorems in [47mlib/[0m. Typically we wish to prove the new theorems using the existing books in [47mlib/[0m; however, our methodology demands that the proofs go into books in [47msupport/[0m. If every theorem in [47mlib/[0m is redundant, then we can [3mdevelop[0m the proofs in [47mlib/[0m but then when we are done, [3mmove[0m each book with such proofs into [47msupport/[0m as follows. In any such book, we first replace [47m[include-book][0m forms referring to books in [47mlib/[0m by [47m[include-book][0m forms referring to corresponding books in [47msupport/[0m and/or [47marithmetic/[0m. Then, we add suitable [47m[in-theory][0m events to get us back into the original [47mlib/[0m proof environment. The default behavior of the system is as though the [47m:enforce-redundancy[0m value is [47mnil[0m. The current behavior can be ascertained by evaluating the following form. (cdr (assoc-eq :enforce-redundancy (table-alist 'acl2-defaults-table wrld)))") (set-evisc-tuple (io) "Control suppression of details when printing ACL2 output is generally printed in full. However, ACL2 can be directed to abbreviate, or ``eviscerate'', objects before printing them, through the use of a so-called ``evisc-tuple''. See [evisc-tuple] for a discussion of evisc-tuples. The utility [47mset-evisc-tuple[0m modifies certain global evisc-tuples, as explained below, to affect the extent to which ACL2 eviscerates objects during printing, for example during proof output or when printing top-level evaluation results. General Form: (set-evisc-tuple evisc-tuple ; a legal evisc-tuple, or :DEFAULT :iprint val ; one of *iprint-actions* :sites sites) ; either :ALL, or an element or a subset of ; the list of legal sites (see below) where the value of [47m:iprint[0m is passed to [47m[set-iprint][0m, [47m:sites :all[0m abbreviates [47m:sites[0m '[47m(:term :ld :trace :abbrev :gag-mode :brr)[0m, and other documentation is provided below. Note that all arguments are evaluated. See [without-evisc] for how to avoid evisceration for ACL2 output. The following example illustrates an invocation of [47mset-evisc-tuple[0m that limits the print-level to 3 --- only three descents into list structures are permitted before eviscerating a subterm --- and limits the print-length to 4 --- only the first four elements of any list structure will be printed. ACL2 !>(set-evisc-tuple (evisc-tuple 3 ; print-level 4 ; print-length nil ; alist nil ; hiding-cars ) :iprint :same ; better yet, T :sites :all) (:TERM :LD :TRACE :ABBREV ...) ACL2 !>'((a b ((c d)) e f g) u v w x y) ((A B (#) E ...) U V W ...) ACL2 !> We recommend however using [47m:iprint t[0m so that eviscerated terms may be read back in (see [set-iprint]), as shown here: ACL2 !>(set-evisc-tuple (evisc-tuple 3 ; print-level 4 ; print-length nil ; alist nil ; hiding-cars ) :iprint t :sites :all) ACL2 Observation in SET-EVISC-TUPLE: Iprinting has been enabled. (:TERM :LD :TRACE :ABBREV . #@1#) ACL2 !>(without-evisc '(:TERM :LD :TRACE :ABBREV . #@1#)) (:TERM :LD :TRACE :ABBREV :GAG-MODE :BRR) ACL2 !> Indeed, the [47m:iprint[0m argument is required as a reminder to the user to consider that issue, unless iprinting has been enabled at least once. If [47m:sites[0m or a required [47m:iprint[0m argument is omitted, however, ACL2 will query the user for the missing arguments rather than causing an error. ACL2 eviscerates by default only in a few cases, primarily in informational messages for errors, warnings, and queries (i.e., in the [47m:EVISC[0m case below), and in response to [break-rewrite] commands. Users can modify the default behavior by supplying a suitable argument to [47mset-evisc-tuple[0m. The argument may be [47m:default[0m, which denotes the evisceration provided when ACL2 starts up. Otherwise that argument is an evisc-tuple, which is either [47mnil[0m (no evisceration) or as described above. Moreover, there are six evisc-tuple ``evisceration contexts'', each with its own evisceration control. The value returned by [47mset-evisc-tuple[0m indicates the evisceration contexts whose evisc-tuple has been set. The evisceration contexts are as follows, all of which use a default value of [47mnil[0m for the hiding-cars. Accessors are also shown for retrieving the corresponding evisc-tuple. * [47m:TERM[0m --- used for printing terms. The accessor is [47m(term-evisc-tuple flg state)[0m, where [47mflg[0m is ignored if [47mset-evisc-tuple[0m has been called for [47m:term[0m with value other than [47m:default[0m, and otherwise (hence initially): a [47mflg[0m of [47mnil[0m indicates an evisc-tuple of [47mnil[0m, and otherwise the term-evisc-tuple has a print-level of 3 and print-length of 4. * [47m:ABBREV[0m --- used for printing informational messages for errors, warnings, and queries. Initially, the alist abbreviates the ACL2 [47mworld[0m, print-level is 5, and print-level is 7. The accessor is [47m(abbrev-evisc-tuple state)[0m. * [47m:BRR[0m --- used for output from [brr-commands] issued in the [break-rewrite] loop. When the value is [47m:DEFAULT[0m then the [3meffective value[0m of this evisc-tuple is the [47m:TERM[0m evisc-tuple with [47mflg = t[0m (see above). Also see [brr-evisc-tuple]. * [47m:GAG-MODE[0m --- used for printing induction schemes (and perhaps, in the future, for other printing) when [gag-mode] is on. If gag-mode is off, the value used for this [evisc-tuple] is [47m(term-evisc-tuple nil state)[0m. But if gag-mode is on (i.e., [47m(gag-mode)[0m evaluates to a non-[47mnil[0m value), then with one exception, the value is an evisc-tuple or [47mnil[0m, to be used in gag-mode for printing of induction schemes and, during proofs, the ``The non-trivial part of the guard conjecture''. The exceptional value is [47mt[0m, which indicates that in gag-mode, no printing of induction schemes should be and the guard conjecture should be printed using [47m(term-evisc-tuple t state)[0m. The accessor is [47m(gag-mode-evisc-tuple state)[0m. * [47m:LD[0m --- used by the ACL2 read-eval-print loop. The accessor is [47m([0m[47m[ld-evisc-tuple][0m[47m state)[0m. * [47m:TRACE[0m --- used for printing [trace] output. No accessor is available (though in raw Lisp, [47m(trace-evisc-tuple)[0m returns the trace-evisc-tuple). Each context [47mectx[0m also has an updater, [47m(set-ectx-evisc-tuple val state)[0m, where [47mval[0m is a legal value for [47mset-evisc-tuple[0m as described above: [47m:default[0m or an [evisc-tuple] (possibly [47mnil[0m). Subtopics [Set-brr-evisc-tuple] Set the [47m[brr-evisc-tuple][0m") (set-fast-cert (pointers) "See [fast-cert].") (set-fc-criteria (forward-chaining-reports) "To set the tracking criteria for forward chaining reports Examples: (set-fc-criteria) ; shut off all tracking (set-fc-criteria nil) (set-fc-criteria t) ; to track all forward chaining (set-fc-criteria (t t t)) (set-fc-criteria ((:FORWARD-CHAINING LEMMA1) ; track all uses of LEMMA1, t t) ((:FORWARD-CHAINING LEMMA2) ; uses of LEMMA2 triggered (ALISTP (BASIC-MAPPER A B)) ; by this specific ALISTP term t) (t t (TRUE-LISTP (DLT D)))) ; and every rule deriving ; this TRUE-LISTP term. General Forms: (set-fc-criteria nil) (set-fc-criteria t) (set-fc-criteria triple1 triple2 ...) where each triple is of the form [47m(rune inst-trigger inst-concl)[0m. If rune is non-[47mt[0m is must be a forward chaining [rune]. The other two components, [47minst-trigger[0m and [47minst-concl[0m, if non-[47mt[0m, must be terms. The list of all the triples supplied is called the ``criteria.'' In the form [47m(set-fc-criteria nil)[0m, the criteria used is the empty list of triples. (Technically, supplying [47mnil[0m as a triple ``ought'' to be an error, but it is a more ``natural'' way to say the list of criteria is empty than to use the correct form [47m(set-fc-criteria)[0m.) In the form [47m(set-fc-criteria t)[0m the criteria used is the list containing the single triple [47m(t t t)[0m. This function sets the tracking criteria for forward chaining reporting. See [forward-chaining-reports] for a general discussion of tracking and reporting forward chaining activity. Think of the forward chaining criteria as a list of triples, representing a disjunction of conjunctions. The activation of a [47m:[0m[47m[forward-chaining][0m rune by some triggering term in the current context [3msatisfies[0m the criteria if it satisfies one of the triples. To satisfy the triple [47m(rune inst-trigger inst-concl)[0m, the activation must satisfy each component of the triple. Any [47mt[0m component is always satisfied. If [47mrune[0m is non-[47mt[0m it is satisfied if the activation is for the given rune. If [47minst-trigger[0m is non-[47mt[0m, it is satisfied if the activation is triggered by the given term. (``[47mInst-trigger''[0m stands for ``instantiated trigger.'' It is not the trigger term of the rule but is supposed to be an instance of that term that you believe will arise in some proof attempt you are debugging --- an instance you want to ``watch'' as it fires the rule.) If [47minst-concl[0m is non-[47mt[0m, it is satisfied if the activation could possibly derive the conclusion given. (Again, ``[47minst-concl''[0m stands for ``instantiated conclusion'' and shows the term in your problem that you expect to be derived by forward chaining.) Note that if the criteria is empty, it is never satisfied, so tracking is turned off. If the criteria is the singleton list containing just the triple [47m(t t t)[0m, then every activation satisfies it and so all [47m:forward chaining[0m rules are tracked. See [forward-chaining-reports] for details.") (set-fc-report-on-the-fly (forward-chaining-reports) "To determine when forward-chaining reports are printed Examples: (set-fc-report-on-the-fly t) (set-fc-report-on-the-fly nil) If the flag is set to [47mt[0m, forward chaining tracking reports are printed when forward chaining occurs. If the flag is set to [47mnil[0m, very short reports (giving just the caller and the report number) are printed during forward chaining but you can use [47m[fc-report][0m to see the full report afterwards. Since nothing is tracked when the criteria is [47mnil[0m, this function also prints out the current criteria to remind you of what it is. The flag manipulated by this function does not shut off tracking. It only determines whether reports are printed on-the-fly or not. To shut off tracking [47m[set-fc-criteria][0m. See [forward-chaining-reports] for details.") (set-fmt-hard-right-margin (io acl2-built-ins) "Set the right margin for formatted output In this documentation topic we discuss setting of both a ``soft'' and a ``hard'' right margin. Example Forms: (set-fmt-soft-right-margin 55 state) ; set soft right margin to 55 (set-fmt-hard-right-margin 68 state) ; set hard right margin to 68 [47m[Fmt][0m and related functions can insert linebreaks when lines get too long. A linebreak is inserted at an aesthetically appropriate point once the column exceeds the value of [47m(@ fmt-soft-right-margin)[0m. ACL2 may also insert a linebreak (sometimes in an unaesthetic place) to prevent printing in a column that equals or exceeds the value of [47m(@ fmt-hard-right-margin)[0m. Such a ``hard'' linebreak follows the insertion of a backslash ([47m\[0m) character unless [47m[fmt!][0m, [47m[fms!][0m, or [47m[fmt1!][0m is used, or state global [47mwrite-for-read[0m is true. Note that a right margin of 40 is used for pretty printing with [47m[fmt][0m directives [47m~y[0m, [47m~Y[0m, [47m~q[0m, and [47m~Q[0m and can be changed to a positive integer [47mN[0m with [47m(set-ppr-flat-right-margin N state)[0m.") (set-fmt-soft-right-margin (io acl2-built-ins) "Set the soft right margin for formatted output See [set-fmt-hard-right-margin] for a discussion of the soft and hard right margin for formatted output.") (set-gag-mode (output-controls) "Modify the nature of proof output Examples: :set-gag-mode t ; enable gag-mode, suppressing most proof commentary (set-gag-mode t) ; same as above :set-gag-mode :goals ; same as above, but print names of goals when produced :set-gag-mode nil ; disable gag-mode General Forms: (set-gag-mode val) :set-gag-mode val where [47mval[0m is one of [47mt[0m, [47mnil[0m, or [47m:goals[0m. By default, gag-mode is enabled, set to [47m:goals[0m. To see the current value of gag-mode, evaluate the form, [47m(gag-mode)[0m. (gag-mode) ; evaluates to t, nil, or :goals The basic idea of gag-mode is to avoid much of the verbose output from the theorem prover, leaving only output that is expected to be helpful. The first two forms below set gag-mode on, while the other turns it off; these may be placed in your ACL2 customization file; see [ACL2-customization]. (set-gag-mode :goals) ; (default) avoid most prover output; show goal names (set-gag-mode t) ; avoid most prover output; also, hide goal names (set-gag-mode nil) ; allow prover output Gag-mode focuses attention on so-called ``key checkpoints''. By default, a checkpoint is a goal that cannot be simplified. (Below we discuss how to change this default.) A key checkpoint is a checkpoint that is not descended from another checkpoint. (Technical point: ``descended'' signifies that both goals are at the top level in the same forcing round, or are in the same proof by induction.) Successful ACL2 users generally focus their attention on key checkpoints, or less often, induction schemes. (To suppress or abbreviate induction schemes in gag-mode, see [set-evisc-tuple], specifically, the discussion of [47m:GAG-MODE[0m.) For a discussion of how to use ACL2 prover output in an effective manner, see [the-method], and see [introduction-to-the-theorem-prover] for a more detailed tutorial. In gag-mode, a key checkpoint is only displayed when ACL2 is unable to make any further progress on that goal or some descendant of it, other than with a proof by induction. Evaluation of [47m(set-gag-mode t)[0m enters gag-mode, so that only key checkpoints are printed. Evaluation of [47m(set-gag-mode :goals)[0m also enters gag-mode, but will additionally cause the name of a goal to be printed as soon as it is generated (by invoking [set-print-clause-ids]). The [47m:goals[0m setting is the default, and is useful for cases in which the prover spends very little of its time generating goals to be proved by induction, yet you want to see that it is making progress. For finer-grained feedback about the simplifier's activity, see [dmr]. An alternative to gag-mode is to use proof-trees; see [proof-tree]. With proof-trees it is not so important to avoid excessive prover output, since the proof-tree display provides structure that makes it easy to monitor proof attempts and navigate output for a proof that has failed or seems to be failing. Still, output can take time to print, so you may get better performance with gag-mode. The intention of gag-mode is to show you only the parts of a proof attempt that are relevant for debugging a failure; additional output is generally more likely to be distracting than truly helpful. But on occasion you may want to see the full proof output after an attempt made with gag-mode. This can be done provided proof output is not inhibited (see [set-inhibit-output-lst]) during the proof attempt; see [pso] and see [pso!]. You may notice that gag-mode tends to print relatively little information about goals pushed for proof by sub-induction --- i.e., a proof of *i.j, *i.j.k, etc. That feature emphasizes that unsuccessful sub-inductions should generally be avoided, not analyzed for ways to make them succeed. Instead, the key checkpoint that generated the goal pushed for this induction is more appropriate to analyze. In general, the ``higher level'' the checkpoint, the more worthy it is of attention. Thus, it might be helpful to look at the top-level checkpoints before looking at those labeled ``Key checkpoints under a top-level induction''. We conclude with remarks for advanced users. The notion of ``checkpoint'' can be modified by the user. The default, as discussed above, is for a checkpoint to be a goal that cannot be simplified. Put differently, a checkpoint is acted on by one of the processes in the value of the form [47m(@ checkpoint-processors)[0m; see [@]. Any or all of the symbols [47meliminate-destructors-clause[0m, [47mfertilize-clause[0m, [47mgeneralize-clause[0m, or [47meliminate-irrelevance-clause[0m can be removed from this value in order that invocation of the corresponding proof process does not cause its input goal to be labeled a checkpoint. For example, if you do not want destructor elimination to be treated differently from simplification for purposes of labeling checkpoints, you can evaluate the following form (see [assign]): (assign checkpoint-processors (remove 'eliminate-destructors-clause (@ checkpoint-processors))) Note that the value of [47m(@ checkpoint-processors)[0m also affects the proof tree display; see [proof-tree-details]. End of Remark.) See [set-evisc-tuple], in particular the discussion there of [47m:GAG-MODE[0m, for how to influence slightly just what is printed in gag-mode. Subtopics [Checkpoint-summary-limit] Control printing of key checkpoints upon a proof's failure [Set-checkpoint-summary-limit] Control printing of key checkpoints upon a proof's failure") (set-gc-strategy (miscellaneous acl2-built-ins) "Set the garbage collection strategy (CCL only) [3mNote[0m: This macro has no effect unless the host Lisp is CCL. General Forms: (set-gc-strategy :egc) ; the default: EGC is on, full GC is not delayed (set-gc-strategy :delay) ; EGC is off, full GC is delayed (set-gc-strategy :current) ; same as replacing :current by the latest ; strategy set (:egc or :delay) (set-gc-strategy strategy threshold) ; Same as (set-gc-strategy strategy), but sets ; threshold to the indicated number of bytes ; (see below) Logically, [47m(set-gc-strategy op)[0m returns [47mop[0m. But in some host Lisps (currently CCL only), it changes how garbage collection is invoked. Exactly how that is done is best understood by reading the ACL2 source code, starting with [47mset-gc-strategy[0m. Here we document what most users might want to know about this utility, assuming they are using CCL. We defer discussion of the optional second argument, [47mthreshold[0m, to the end. Normally the default garbage collection strategy will probably be fine. That default has the ephemeral garbage collector (EGC) enabled. But in jobs that stress [47m[hons][0m, or perhaps memoization (see [memoize]) or [fast-alists], it might be useful to switch to a strategy that disables EGC but also significantly delays garbage collection. To switch to that delaying strategy: (set-gc-strategy :delay) Then, you can return to the default strategy, re-enabling EGC and no longer causing delays in garbage collection, as follows. (set-gc-strategy :egc) It is also legal to invoke [47m(set-gc-strategy :current)[0m, which is equivalent to replacing [47m:current[0m by the current strategy; see [gc-strategy]. If you want to change the gc-strategy during certification of a book, but not when including that book, you can place your call of [47mset-gc-strategy[0m inside [47m[value-triple][0m, for example as follows. (value-triple (set-gc-strategy :delay)) The following variant causes the [gc-strategy] to be modified when including the book as well. (value-triple (set-gc-strategy :delay) :on-skip-proofs t) This capability might be extended to other host Lisps in the future, especially if ACL2 users provide suggestions for how to do so. Note that the default behavior can be changed to [47m:delay[0m at ACL2 build time, by setting [47mMake[0m variable [47mACL2_EGC_ON=nil[0m when building an ACL2 executable. The [47mthreshold[0m argument When a second argument is supplied in a call of [47mset-gc-strategy[0m, it must be either [47mnil[0m, which is equivalent to supplying no second argument, or else a positive integer. This positive integer will be the ``GC threshold'' number of bytes CCL will try to ensure are available before the next full garbage collection. The default (i.e., the value used when the second argument is [47mnil[0m or is omitted) is the minimum of the following two values: 1/2 GB, and 1/32 of physical memory (or 1/32 of 4 GB, if the physical memory cannot be determined). (Technical note: The GC threshold is stored in raw Lisp variable [47m*gc-min-threshold*[0m.)") (set-guard-checking (guard) "Control checking [guard]s during execution of top-level forms Detailed comments about the arguments of this function may be found elsewhere: see [guard-evaluation-table]. Here we provide an introduction to the use of [47mset-guard-checking[0m. New users are encouraged to execute one of the following forms in order to avoid evaluation errors due to [guard]s: (set-guard-checking :none) (set-guard-checking nil) The former avoids all guard-checking on user-defined functions and should generally work fine for new users, the only drawback being efficiency loss on compute-intensive problems. All settings other than [47m:none[0m check guards, but a value of [47mnil[0m allows evaluation to continue in the logic when guards fail (avoiding the raw Lisp definition in that case). You may put one of the above forms in the [47m"acl2-customization.lsp"[0m file in your current directory (see [cbd]) or your home directory; see [ACL2-customization]. Note that [guard]s are not part of the ACL2 logic, and hence new users can completely ignore the notion of [guard] (and the rest of this documentation section after this paragraph!). For example, [47m(car 3)[0m and [47mnil[0m can be proved equal in the ACL2 logic, as follows, even though the [guard] on [47m[car][0m requires its first argument to be a [47m[cons][0m pair or [47mnil[0m. (thm (equal (car 3) nil)) Moreover, unless your functions or top-level forms call built-in ACL2 functions that are defined in [47m:[0m[47m[program][0m mode, the following property will hold. Evaluation of [47m(set-guard-checking :none)[0m will allow evaluation of forms such as [47m(car 3)[0m to take place without error in the top level loop, not only when proving theorems. If you feel bold, then you may wish to read the rest of this documentation topic; also see [guard]. See [guard-evaluation-table] for a succinct table, with associated discussion, that covers in detail the material presented in the rest of the present topic. The top-level ACL2 loop has a variable which controls which sense of execution is provided. To turn ``[guard] checking on,'' by which we mean that [guard]s are checked at runtime, execute the top-level form [47m:set-guard-checking t[0m. To allow guard violations, do [47m:set-guard-checking nil[0m, or do [47m:set-guard-checking :none[0m to turn off all guard-checking, so that raw Lisp definitions of user-defined functions are avoided unless their [guard] is [47mt[0m. The status of guard-checking is reflected in the [prompt]. ACL2 !> means [guard] checking is on and ACL2 > means [guard] checking is off. The exclamation mark can be thought of as ``barring'' certain computations. The absence of the mark suggests the absence of error messages or unbarred access to the logical axioms. Thus, for example ACL2 !>(car 'abc) will signal an error, while ACL2 >(car 'abc) will return [47mnil[0m. We will return at the end of this documentation topic to discuss two other values, [47m:all[0m and [47m:nowarn[0m, for [47m:set-guard-checking[0m. We also note that evaluation of built-in [47m:program[0m mode functions always takes place in raw Lisp. Whether [guard]s are checked during evaluation is independent of the [47m[default-defun-mode][0m. We note this simply because it is easy to confuse ``[47m:[0m[47m[program][0m mode'' with ``evaluation in Common Lisp'' and thus with ``[guard] checking on;'' and it is easy to confuse ``[47m:[0m[47m[logic][0m mode'' with ``evaluation in the logic'' and with ``[guard] checking off.'' But the [47m[default-defun-mode][0m determines whether newly submitted definitions introduce programs or add logical axioms. That mode is independent of whether evaluation checks [guard]s or not. You can operate in [47m:[0m[47m[logic][0m mode with runtime [guard] checking on or off. Analogously, you can operate in [47m:[0m[47m[program][0m mode with runtime [guard] checking on or off. For further discussion on evaluation and guards see [guards-and-evaluation], in particular the exception for safe-mode in the ``Aside'' there. See [guard] for a general discussion of [guard]s. Now we fulfill our promise above to discuss two other values for [47m:set-guard-checking[0m: :set-guard-checking :nowarn :set-guard-checking :all The meaning of these values is perhaps best described by the following example provided by David Rager. ACL2 !>(defun my-test (expr) (declare (xargs :guard (true-listp expr) :verify-guards nil)) (if (atom expr) expr (cons (my-test (car expr)) (my-test (cdr expr))))) The admission of MY-TEST is trivial, using the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT EXPR). We could deduce no constraints on the type of MY- TEST. However, in normalizing the definition we used primitive type reasoning. Summary Form: ( DEFUN MY-TEST ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: None Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) MY-TEST ACL2 !>(my-test '(a b c)) ACL2 Warning [Guards] in TOP-LEVEL: Guard-checking will be inhibited on recursive calls of the executable-counterpart (i.e., in the ACL2 logic) of MY-TEST. To check guards on all recursive calls: (set-guard-checking :all) To leave behavior unchanged except for inhibiting this message: (set-guard-checking :nowarn) (A B C) ACL2 !> If you think about evaluation of [47m(my-test '(a b c))[0m, you will see that it leads to the recursive call [47m(my-test 'a)[0m, which one might expect to cause a guard violation since the symbol [47ma[0m is not a [47m[true-listp][0m. However, as the warning above explains, we do not by default check guards on recursive calls. The reason is efficiency --- imagine a simple definition with a guard that is slow to evaluate. The values [47m:nowarn[0m and [47m:all[0m for [47m:set-guard-checking[0m have been introduced as ways of dealing with the above warning. The value [47m:nowarn[0m simply turns off the warning above. The value [47m:all[0m causes all guards to be checked, even on recursive calls and even on all calls of non-built-in [47m:[0m[47m[program][0m mode functions --- unless, of course, a call is made of a function whose guard has been verified (see [verify-guards]), where the arguments satisfy the guard, in which case the corresponding call is made in raw Lisp without subsidiary guard-checking. We still say that ``guard-checking is on'' after [47m:set-guard-checking[0m is invoked with values [47mt[0m, [47m:nowarn[0m, and [47m:all[0m, otherwise (after value [47mnil[0m) we say ``guard-checking is off. For technical reasons, [47m:all[0m does not have its advertised effect in the case of built-in [47m:[0m[47m[program][0m-mode functions. If you are interested in this technical detail, see the comment ``In the boot-strap world...'' in source function [47moneify-cltl-code[0m. We conclude with a remark about the use of [47m:set-guard-checking[0m for experimenting with ACL2 as a logic or as a programming language. If one views ACL2 as a logic, one may wish to use [47m:set-guard-checking :none[0m, while if instead one views ACL2 as a functional programming language, one may wish to use [47m:set-guard-checking :all[0m. The following transcript illustrates this distinction by way of example. Specifically, [47m(car 3)[0m is equal to [47mnil[0m in the ACL2 logic, but may be viewed as a programming error. The default of [47m:set-guard-checking t[0m is problematic for learning ACL2 using [47m:[0m[47m[program][0m mode functions, since one can get raw Lisp errors. In the example below, the raw Lisp error occurs because [47mfoo[0m implicitly has a [guard] of [47mt[0m, hence [47m(foo 3)[0m is evaluated in raw Lisp, which leads to a raw Lisp call of c[(car 3)]. ACL2 !>(defun foo (x) (declare (xargs :mode :program)) (car x)) Summary Form: ( DEFUN FOO ...) Rules: NIL Warnings: None Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) FOO ACL2 !>(foo 3) Error: Attempt to take the car of 3 which is not listp. [condition type: TYPE-ERROR] Restart actions (select using :continue): 0: Abort entirely from this (lisp) process. [Current process: Initial Lisp Listener] [1] ACL2(1): [RAW LISP] :pop ACL2 !>:set-guard-checking :none Turning off guard checking entirely. To allow execution in raw Lisp for functions with guards other than T, while continuing to mask guard violations, :SET-GUARD-CHECKING NIL. See :DOC set-guard-checking. ACL2 >(foo 3) NIL ACL2 >:set-guard-checking :all Turning guard checking on, value :ALL. ACL2 !>(foo 3) ACL2 Error in TOP-LEVEL: The guard for the function symbol CAR, which is (OR (CONSP X) (EQUAL X NIL)), is violated by the arguments in the call (CAR 3). See :DOC trace for a useful debugging utility. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !>") (set-guard-msg (guard debugging) "Specify what is printed when a [guard] is violated This is an advanced feature that may require considerable understanding of ACL2 programming. ACL2 provides default error messages for guard violations. However, ACL2 also provides a [table], [47mguard-msg-table[0m, that allows custom error messages for guard-checking failures. The macro [47mset-guard-msg[0m provides a convenient way to update this table. The keys of the table are symbols, which can be expected to be function symbols or names of macros. Each value is a (translated) [term] whose only free variables are [47mworld[0m, [47margs[0m, and [47mcoda[0m. When guard-checking fails, the term is evaluated to create a [3mmessage[0m suitable for "[47m~@[0m" formatted printing directives; see [fmt]. That evaluation is done with [47mworld[0m bound to the current ACL2 logical [world], with [47margs[0m bound to the actual parameters of the call, and with [47mcoda[0m bound to the message that would typically be printed by default at the end of a guard violation. (See ACL2 source function [47mguard-er-message-coda[0m for details, or simply experiment.) Example Consider the following example. (defun foo (x) (declare (xargs :mode :program :guard (consp x))) (car x)) (set-guard-msg foo (msg "An error for call ~x0." (cons 'foo args))) Corresponding output for a guard violation is as follows. ACL2 !>(foo 3) ACL2 Error in TOP-LEVEL: An error for call (FOO 3). ACL2 !> Continuing in the same session, suppose we provide this fancier error message specification. (set-guard-msg foo (msg "An error for call ~x0 in a world of length ~x1.~@2" (cons 'foo args) (length world) ; length of the current ACL2 world coda)) The corresponding error is shown below. Notice that the coda starts on a new line, with the same "See :DOC ..." message that one would see if the default error message were supplied for the same guard violation. ACL2 !>(foo 3) ACL2 Error in TOP-LEVEL: An error for call (FOO 3) in a world of length 98582. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !> The capability shown above for function symbols is also available for macro names. However, the variable, [47mcoda[0m, should not be used for macro names.") (set-ignore-ok (declare defun) "Allow unused formals and locals without an [47mignore[0m or [47mignorable[0m declaration Examples: (set-ignore-ok t) (set-ignore-ok nil) (set-ignore-ok :warn) The first example above allows unused formals and locals, i.e., variables that would normally have to be [declare]d [47mignore[0md or [47mignorable[0m. The second example disallows unused formals and locals; this is the default. The third example allows them, but prints an appropriate warning. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. General Form: (set-ignore-ok flg) where [47mflg[0m is either [47mt[0m, [47mnil[0m, or [47m:warn[0m. One might find this event useful when one is generating function definitions by an automated procedure, when that procedure does not take care to make sure that all formals are actually used in the definitions that it generates. Note: Defun will continue to report irrelevant formals even if [47m:set-ignore-ok[0m has been set to [47mt[0m, unless you also use [47m[set-irrelevant-formals-ok][0m to instruct it otherwise.") (set-in-theory-redundant-okp (redundant-events) "Allow [47m[in-theory][0m events to be redundant See [redundant-events] for discussion of the notion of redundant events. General Forms: (set-in-theory-redundant-okp nil) ; default (set-in-theory-redundant-okp t) ; allow in-theory events to be redundant By default, [47m[in-theory][0m events are never redundant. This behavior avoids a redundancy check that could be a bit expensive, as it would require computing the current theory and checking its equality to the new theory. Evaluation of the event [47m(set-in-theory-redundant-okp t)[0m enables that redundancy check, so that when an [47min-theory[0m event computes a theory that is equal to the current theory, then that event is redundant. To see the current setting (i.e., the default of [47mnil[0m or else [47mt[0m after evaluation of [47m(set-in-theory-redundant-okp t)[0m), evaluate [47m(get-in-theory-redundant-okp state)[0m. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].") (set-induction-depth-limit (induction-depth-limit) "Set the [induction-depth-limit] Examples: (set-induction-depth-limit 3) ;; Set the induction depth limit to 3. (set-induction-depth-limit nil) ;; Remove the induction depth limit. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [set-induction-depth-limit!] for a corresponding non-[47m[local][0m event. General Form: (set-induction-depth-limit x) where [47mx[0m evaluates to a value that is a natural number or [47mnil[0m. The induction-depth-limit is set to that value; see [induction-depth-limit].") (set-induction-depth-limit! (induction) "Set the induction-depth-limit non-[47m[local][0mly Please see [set-induction-depth-limit], which is the same as [47mset-induction-depth-limit![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [47m[set-induction-depth-limit][0m is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (set-inhibit-er (output-controls errors) "Control the error output Examples: (set-inhibit-er "translate" "failure") Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [set-inhibit-er!] for a corresponding non-[47m[local][0m event. Indeed, [47m(set-inhibit-er ...)[0m is equivalent to [47m(local (set-inhibit-er! ...))[0m. General Form: (set-inhibit-er string1 string2 ...) where each string is considered without regard to case. This macro is is essentially [47m(local (table inhibit-er-table nil 'alist :clear))[0m, where [47malist[0m pairs each supplied string with [47mnil[0m: that is, [47malist[0m is [47m(pairlis$ lst nil)[0m where [47mlst[0m is the list of strings supplied. This macro is an event (see [table]), but no output results from a [47mset-inhibit-er[0m event. ACL2 prints errors that are generally important to see. This utility is appropriate for situations where one prefers not to see all error messages. Individual ``labeled'' error output can be silenced. Consider for example ACL2 Error [Failure] in ( DEFUN FOO ...): See :DOC failure. Here, the label is "Failure". The argument list for [47mset-inhibit-er[0m is a list of such labels, each of which is a string. Any error message is suppressed if its label is a member of this list, where case is ignored. Thus, for example, the error output above will be avoided after a call of [47mset-inhibit-er[0m that contains the string, [47m"Failure"[0m (or any string that is [47m[string-equal][0m to [47m"Failure"[0m, such as [47m"failure"[0m or [47m"FAILURE"[0m). In summary: the effect of this event is to suppress any error output whose label is a member of the given argument list, where case is ignored. At this time, many error messages are printed without a label, for example (as of this writing) the following. ACL2 !>(+ x 3) ACL2 Error in TOP-LEVEL: Global variables, such as X, are not allowed. See :DOC ASSIGN and :DOC @. ACL2 !> These can only be suppressed by turning off all error output; see [set-inhibit-output-lst]. Feel free to ask the ACL2 implementors to add labels; for example, you might ask for a label in the example above (which could be [47m"Globals"[0m or [47m"Global-variables"[0m). Note that [47mset-inhibit-er[0m has no effect on the value(s) returned by an expression (excepting the ACL2 [state] since it formally includes output). The list of currently inhibited error types is the list of keys in the [table] named [47minhibit-er-table[0m. (The values in the table are irrelevant.) One way to get that value is to get the result from evaluating the following form: [47m(table-alist 'inhibit-er-table (w state))[0m. Of course, if error output is inhibited overall --- see [set-inhibit-output-lst] --- then this value is entirely irrelevant. See [47m[toggle-inhibit-er][0m for a way to add or remove a single string.") (set-inhibit-er! (output-controls errors) "Control error output non-[47m[local][0mly Please see [set-inhibit-er], which is the same as [47mset-inhibit-er![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [set-inhibit-er] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (set-inhibit-output-lst (output-controls) "Control output Examples: (set-inhibit-output-lst '(warning)) (set-inhibit-output-lst '(proof-tree prove proof-builder)) (set-inhibit-output-lst *valid-output-names*) ; inhibit all prover output :set-inhibit-output-lst (proof-tree prove) General Form: (set-inhibit-output-lst x) where [47mx[0m is a form (which may mention [47m[state][0m) that evaluates to a list of names, each of which is the name of one of the following ``kinds'' of output produced by ACL2. error error messages (but for hard errors, see below) warning warnings other than those related to soundness warning! warnings (of all degrees of importance) observation observations prove commentary produced by the theorem prover proof-builder commentary produced by the interactive proof-builder event non-proof commentary produced by events such as defun and encapsulate history output from history commands such as :ubt and :pbt summary the summary at the successful conclusion of an event proof-tree proof-tree output comment output from cw, cw!, and utilities like time$ that use them It is possible to inhibit each kind of output by putting the corresponding name into [47mx[0m. For example, if [47m'warning[0m is included in (the value of) [47mx[0m, then no warnings are printed except those related to soundness, e.g., the inclusion of an uncertified book. Note that [proof-tree] output is affected by [47mset-inhibit-output-lst[0m; see [proof-tree]. Note that proof output can be controlled without inhibiting it using this utility, and indeed is already quite limited by default. See [47m[set-gag-mode][0m. See [with-output] for a variant of this utility that can be used in [books]. Also see [set-inhibit-warnings] and [set-inhibit-er] for how to inhibit individual warning and error output types, respectively, and see [set-inhibited-summary-types] for how to inhibit individual parts of the [summary]. Printing of events on behalf of [47m[certify-book][0m and [47m[encapsulate][0m is inhibited when both [47m'event[0m and [47m'prove[0m belong to the value of the input. Otherwise, printing of events is controlled by the [47m[ld][0m special [47m[ld-pre-eval-print][0m. Normally, hard error messages (see [er]) are not inhibited. To inhibit those as well when [47mERROR[0m output is inhibited: [47m(assign inhibit-er-hard t)[0m. To restore the original behavior: [47m(assign inhibit-er-hard nil)[0m. To get the current of names representing kinds of inhibit output, evaluate [47m(@ inhibit-output-lst)[0m. [3mNote for advanced users.[0m By including [47mwarning![0m in the value of the input, you are automatically including [47mwarning[0m as well: all warnings will be inhibited. This is not the case if you modify value of state global variable [47m'inhibit-output-lst[0m directly (with [47m[assign][0m or [47mf-put-global[0m); then, if you include [47mwarning![0m but not [47mwarning[0m, then warnings not related to soundness will still be printed (which is probably not what was intended).") (set-inhibit-warnings (output-controls) "Control warnings Examples: (set-inhibit-warnings "theory" "use") Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [set-inhibit-warnings!] for a corresponding non-[47m[local][0m event. Indeed, [47m(set-inhibit-warnings ...)[0m is equivalent to [47m(local (set-inhibit-warnings! ...))[0m. General Form: (set-inhibit-warnings string1 string2 ...) where each string is considered without regard to case. This macro is is essentially [47m(local (table inhibit-warnings-table nil 'alist :clear))[0m, where [47malist[0m pairs each supplied string with [47mnil[0m: that is, [47malist[0m is [47m(pairlis$ lst nil)[0m where [47mlst[0m is the list of strings supplied. This macro is an event (see [table]), but no output results from a [47mset-inhibit-warnings[0m event. ACL2 prints warnings that may, from time to time, seem excessive to experienced users. Each warning is ``labeled'' with a string identifying the type of warning. Consider for example ACL2 Warning [Use] in ( THM ...): It is unusual to :USE .... Here, the label is "Use". The argument list for [47mset-inhibit-warnings[0m is a list of such labels, each of which is a string. Any warning is suppressed if its label is a member of this list, where case is ignored. Thus, for example, the warning above will not be printed after a call of [47mset-inhibit-warnings[0m that contains the string, [47m"Use"[0m (or any string that is [47m[string-equal][0m to [47m"Use"[0m, such as [47m"use"[0m or [47m"USE"[0m). In summary: the effect of this event is to suppress any warning whose label is a member of the given argument list, where case is ignored. The list of currently inhibited warnings is the list of keys in the [table] named [47minhibit-warnings-table[0m. (The values in the table are irrelevant.) One way to get that value is to get the result from evaluating the following form: [47m(table-alist 'inhibit-warnings-table (w state))[0m. Of course, if warnings are inhibited overall --- see [set-inhibit-output-lst] --- then this value is entirely irrelevant. See [47m[toggle-inhibit-warning][0m for a way to add or remove a single warning string.") (set-inhibit-warnings! (output-controls) "Control warnings non-[47m[local][0mly Please see [set-inhibit-warnings], which is the same as [47mset-inhibit-warnings![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [set-inhibit-warnings] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (set-inhibited-summary-types (output-controls) "Control which parts of the [summary] are printed Example: (set-inhibited-summary-types '(rules time)) Note: This is not an event. Rather, it changes the [state], in analogy to [47m[set-inhibit-output-lst][0m. General Form: (set-inhibited-summary-types form) where form evaluates to a true-list of symbols, each of which is among the values of the constant [47m*summary-types*[0m, which is [47m(errors form header hint-events redundant rules splitter-rules steps system-attachments time value warnings)[0m. Each specified type inhibits printing of the corresponding portion of the summaries printed at the conclusions of [events], where [47mheader[0m refers to an initial newline followed by the line containing just the word [47mSummary[0m. Note the distinction between [47mrules[0m and [47mhint-events[0m. [47mRules[0m provides a record of automatic rule usage by the prover, while [47mhint-events[0m shows the names of events given to [47m:USE[0m or [47m:BY[0m [hints], as well as [clause-processor] functions given to [47m:CLAUSE-PROCESSOR[0m hints that have an effect on the proof. Also see [set-inhibit-output-lst]. Note that [47mset-inhibited-summary-types[0m has no effect when [47msummary[0m is one of the types inhibited by [set-inhibit-output-lst], because in that case none of the [summary] will be printed. To control summary types for a single event, see [with-output].") (set-invisible-fns-table (loop-stopper) "Set the invisible functions table Examples: (set-invisible-fns-table ((binary-+ unary--) (binary-* unary-/) (unary-- unary--) (unary-/ unary-/))) (set-invisible-fns-table t) ; restore original invisible-fns-table Among other things, the setting above has the effect of making [47m[unary--][0m ``invisible'' for the purposes of applying permutative [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees. Thus, [47marg[0m and [47m(unary-- arg)[0m will be given the same weight and will be permuted so as to be adjacent. The form [47m(invisible-fns-table (w state))[0m returns the current value of the invisible functions table. Also see [add-invisible-fns] and see [remove-invisible-fns] for events that add to and remove from the invisible functions table, while accounting for macro aliases (see [macro-aliases-table]). General Form: (set-invisible-fns-table alist) where [47malist[0m is either [47mt[0m or a true list of pairs, each element of which is of the form [47m(fn ufn1 ... ufnk)[0m, where [47mfn[0m is a function symbol and each [47mufni[0m is a unary function symbol. When alist is [47mt[0m, the initial value of this table is used in its place. Modulo the replacement of [47malist[0m by the default setting when [47malist[0m is [47mt[0m, this macro is equivalent to (table invisible-fns-table nil 'alist :clear) which is also an event (see [table]). Note that [47mset-invisible-fns-table[0m does not evaluate its argument. However, you can call [47m[table][0m directly for that purpose. For example, (set-invisible-fns-table ((binary-+ unary--) (binary-* unary-/) (unary-- unary--) (unary-/ unary-/))) ie equivalent to the following; see [table]. (table invisible-fns-table nil (quote ((binary-+ unary--) (binary-* unary-/) (unary-- unary--) (unary-/ unary-/))) :clear) See [invisible-fns-table] for a description of the invisible functions table.") (set-iprint (io) "Control whether abbreviated output can be read back in The following log may be sufficient for you to see how to use [47mset-iprint[0m; more explanation is below. The example is taken from a session that used the [break-rewrite] utility, but familiarity with that utility is not necessary in order to understand this example. What it shows is that the form [47m(set-iprint t)[0m allows you to recover, using [without-evisc], output that had been hidden. (See [break-rewrite] for more about the interaction of [47mbreak-rewrite[0m with iprinting.) ACL2 !>(thm (p y)) (1 Breaking (:REWRITE AX) on (P Y): 1 ACL2 >:eval 1x (:REWRITE AX) failed because :HYP 1 rewrote to (EQUAL Y '(NIL NIL NIL NIL ...)). 1 ACL2 >:a! Abort to ACL2 top-level Here is the current pstack [see :DOC pstack]: (REWRITE-ATM SIMPLIFY-CLAUSE WATERFALL) *** Note: No checkpoints to print. *** ACL2 Version 6.4. Level 1. Cbd "u/smith/". System books directory "/u/smith/acl2/v6-4/books/". Type :help for help. Type (good-bye) to quit completely out of ACL2. ACL2 !>(set-iprint t) ACL2 Observation in SET-IPRINT: Iprinting has been enabled. ACL2 !>(thm (p y)) (1 Breaking (:REWRITE AX) on (P Y): 1 ACL2 >:eval 1x (:REWRITE AX) failed because :HYP 1 rewrote to (EQUAL Y '(NIL NIL NIL NIL . #@2#)). 1 ACL2 >(without-evisc '(EQUAL Y '(NIL NIL NIL NIL . #@2#))) (EQUAL Y '(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)) 1 ACL2 > This concludes the introductory example. When ACL2 pretty-prints large expressions using formatted printing (see [fmt]), it may save time and space by printing tokens `[47m#[0m' or `[47m...[0m' in place of certain subexpressions. By default this only happens for a few settings such as error and warning messages; see [set-evisc-tuple] for controlling such elision in general. The full expression is unavailable to the user when `[47m#[0m' or `[47m...[0m' is printed, but that is easily solved by evaluating the form (set-iprint t) to enable a mode called ``iprinting''. Then, instead of printing `[47m#[0m' or `[47m...[0m', ACL2 prints `[47m#@i#[0m' for [47mi[0m = 1,2,3,... --- all in base 10. ACL2 can read back in such `[47m#@i#[0m' because under the hood, [47mi[0m is associated with its corresponding elided form. Thus the term ``iprint'' can be viewed as suggesting ``interactive print'' or ``index print''. We also think of ``iprint'' as suggesting ``[47mi[0m printing'', to suggest the printing of token `[47m#@i#[0m'. We call [47mi[0m the ``iprint index'' of that token. The following example should suffice to illustrate how to recover elided subexpressions. (Below this example we provide details that may be of interest only to advanced users.) Here we cause an error by defining a macro of one argument and then calling it with two arguments. By default, error messages abbreviate subexpressions deeper than level 5 with `[47m#[0m' and past the 7th element of a list with `[47m...[0m'. We see this behavior below. ACL2 !>(defmacro foo (x) x) Summary Form: ( DEFMACRO FOO ...) Rules: NIL Warnings: None Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) FOO ACL2 !>(foo arg1 (a (b (c (d (e (f (g)))))) h i j k l m n)) ACL2 Error in macro expansion: Wrong number of args in macro expansion of (FOO ARG1 (A (B (C (D #))) H I J K L ...)). (See :DOC set-iprint to be able to see elided values in this message.) ACL2 !>(set-iprint t) ACL2 Observation in SET-IPRINT: Iprinting has been enabled. ACL2 !>(foo arg1 (a (b (c (d (e (f (g)))))) h i j k l m n)) ACL2 Error in macro expansion: Wrong number of args in macro expansion of (FOO ARG1 (A (B (C (D #@1#))) H I J K L . #@2#)). ACL2 !>(acl2-count '(FOO ARG1 (A (B (C (D #@1#))) H I J K L . #@2#))) 23 ACL2 !> Sometimes you may want to supply the abbreviated form not to compute with it, as in the [47m[ACL2-count][0m example just above, but so that you can see it. The macro [47m[without-evisc][0m eliminates elision during printing. Below we show two ways to use this utility: first, we use it to print the elided form, and then, we use it instead on the original input form to print the entire error message. ACL2 !>(without-evisc '(FOO ARG1 (A (B (C (D #@1#))) H I J K L . #@2#))) (FOO ARG1 (A (B (C (D (E (F (G)))))) H I J K L M N)) ACL2 !>(without-evisc (foo arg1 (a (b (c (d (e (f (g)))))) h i j k l m n))) ACL2 Error in macro expansion: Wrong number of args in macro expansion of (FOO ARG1 (A (B (C (D (E (F (G)))))) H I J K L M N)). ACL2 !> If you wish to know which elided expressions are equal, you may call [47mset-iprint[0m with non-[47mnil[0m value for keyword argument [47m:share[0m. That will turn on [3miprint sharing[0m, which causes behavior as shown below: the value printed shows the iprint index 2 being used twice for the list [47m(C D E F)[0m. ACL2 !>'((a b c d e f) (a b c d e f) (a b c d e f)) ((A B . #@2#) (A B . #@2#) . #@3#) ACL2 !> We use the log displayed below to explain iprint sharing a bit more. The Warning below is pointing out that previous iprint indices are no longer valid; we are starting over. The first Observation points out that iprint sharing is on, and gives the name [47m:IPRINT-FAL[0m to look for in [47m(fast-alist-summary)[0m in case you want information on the [fast-alist] that associates values with corresponding iprint indices. To see the relevance of a fast-alist, note that the two elided occurrences of the list [47m(C D E F)[0m were originally not the identical list in memory; to make them identical, [47m[hons-copy][0m is applied to each to get the same list in memory, which is the one associated with iprint index 2 in a fast-alist named [47m:IPRINT-FAL[0m. ACL2 !>(set-iprint t :share t) ACL2 Warning [Iprint] in SET-IPRINT: Converting SET-IPRINT action from T to :RESET-ENABLE, as required by use of keyword :SHARE or :HARD- BOUND. See :DOC set-iprint. ACL2 Observation in SET-IPRINT: Iprinting is enabled with sharing, with a fast-alist whose name is :IPRINT-FAL. ACL2 Observation in SET-IPRINT: Iprinting has been reset and enabled. ACL2 !>(set-evisc-tuple (evisc-tuple 2 2 nil nil) :sites :all) (:TERM :LD . #@1#) ACL2 !>'((a b c d e f) (a b c d e f) (a b c d e f)) ((A B . #@2#) (A B . #@2#) . #@3#) ACL2 !>'(b c d e f) (B C . #@4#) ACL2 !> One might have expected the last form printed above to take advantage of the fact that the tail [47m(C D E F)[0m of the input's value is already associated with iprint index 2. If you want that sort of behavior --- that is, where we use an existing iprint index even when we have not yet reached the print-level or print-depth specified by our most recent call of [47m[set-evisc-tuple][0m --- then we can use the special value [47m:eager[0m for keyword [47m:share[0m, which gives us [3meager iprinting[0m: (set-iprint t :share :eager) If we use that call of [47mset-iprint[0m instead of our earlier one above (that is, with [47m:share t[0m), then the first of the two last results from the log above is unchanged, but in the second result, the tail [47m(C D E F)[0m is indeed abbreviated using iprint index 2. ACL2 !>'((a b c d e f) (a b c d e f) (a b c d e f)) ((A B . #@2#) (A B . #@2#) . #@3#) ACL2 !>'(b c d e f) (B . #@2#) ACL2 !> The documentation above probably suffices for most users. For those who want more details, below we detail all the ways to use the [47mset-iprint[0m utility. Example Forms: (set-iprint t) ; enable iprinting (elision with #@i@) (set-iprint nil) ; disable iprinting General Form: (set-iprint action ; t, nil, :reset, :reset-enable, or :same :share sym ; initially nil :soft-bound s ; initially 1000 :hard-bound h ; initially 10000) where all arguments are optional, but ACL2 queries for [47maction[0m if it is omitted. All arguments are evaluated. When a keyword argument is omitted, there is no change in the behavior that it controls. For now we defer further explanations of the keyword arguments. The values for [47maction[0m are as follows. [47mt[0m --- Enable iprinting. If either keyword [47m:share[0m or [47m:hard-bound[0m is supplied, then [47mt[0m is converted to [47m:reset-enable[0m. [47mnil[0m --- Disable iprinting. If either keyword [47m:share[0m or [47m:hard-bound[0m is supplied, then [47mnil[0m is converted to [47m:reset[0m. Otherwise, if the next call of [47mset-iprint[0m is with a first argument of [47mt[0m, then iprint indices will start at the next available value rather than going back to 1. [47m:reset[0m --- Reset iprinting to its initial disabled state, so that when enabled, the first index [47mi[0m for which `[47m#@i#[0m is printed will be 1. Note that all stored information for existing iprint indices will be erased. [47m:reset-enable[0m --- Reset iprinting as with [47m:reset[0m, and then enable iprinting. [47m:same[0m --- If either keyword [47m:share[0m or [47m:hard-bound[0m is supplied, then [47m:same[0m is converted to [47m:reset[0m or [47m:reset-enable[0m according to whether iprinting is currently disabled or enabled, respectively. Otherwise, make no change to the iprinting state other than setting the [47msoft-bound[0m if specified, as explained below. The value of [47m:share[0m must be a symbol, with default [47mnil[0m. If the value is [47mnil[0m, then an elided value will be printed using the next available iprint index. The value [47m:same[0m is treated as though [47m:share[0m had not been supplied. Otherwise, iprint sharing is on, which provides the following behavior. Suppose that a value [47mV[0m is to be elided that would be assigned the next available iprint index, [47mN[0m. If an iprint index [47mI < N[0m is already associated with a value equal to [47mV[0m, then ACL2 will print [47m#@I[0m for [47mV[0m instead of [47m#@N[0m. Thus, [47mN[0m will remain the next available iprint index. This behavior is implemented using a [fast-alist] that associates values with indices; in our example, the [47m[hons-copy][0m of [47mV[0m is associated with [47mI[0m. If the value of [47m:share[0m is [47mt[0m then the name of this fast-alist --- that is, its initial value --- is [47m:iprint-fal[0m; otherwise, the value of [47m:share[0m (other than [47mnil[0m or [47m:same[0m) is its name. This name is useful when viewing the output of [47m[fast-alist-summary][0m. Finally, a special case, called ``eager sharing'', is installed if the value of [47m:share[0m is [47m:eager[0m. In that case, the behavior described above --- where [47m#@I[0m is printed for [47mV[0m --- will occur even if the value [47mV[0m would otherwise not be elided, provided the most recent call of [47m[set-evisc-tuple][0m specified a non-[47mnil[0m print-level or print-length. Immediately after a top-level form is read, hence before it is evaluated, a check is made for whether the latest iprint index exceeds a certain bound, [47m(iprint-soft-bound state)[0m --- 1000, by default. If so, then the [47m(iprint-last-index state)[0m is set back to 0 so that the next iprint index that is generated will be 1. This soft bound can be changed to any positive integer [47mk[0m by calling [47mset-iprint[0m with [47m:soft-bound k[0m, for example: [47m(set-iprint :same :soft-bound k[0m)]. The above ``soft bound'' is applied once for each top-level form, but you may want finer control by applying a bound after the pretty-printing of each individual form (since many forms may be pretty-printed between successive evaluations of top-level forms). That bound is [47m(iprint-hard-bound state)[0m, and can be set with the [47m:hard-bound[0m argument in analogy to how [47m:soft-bound[0m is set, as described above, but with the effect of resetting iprinting, with [47m(iprint-last-index state)[0m set back to 0. A ``rollover'' is the detection that the soft or hard bound has been exceeded, along with a state update setting [47m(iprint-last-index state)[0m to 0 so that the next iprint index will be 1. Immediately before a rollover, any index beyond the last iprint index used (which must be from before an earlier rollover) is no longer available for reading. At the top level of the ACL2 read-eval-print loop, this works as follows: ACL2 reads the next top-level form according to the current iprint state, then handles a rollover if the latest iprint index exceeded the current soft bound. The following log illustrates a rollover, which follows the description above. ACL2 !>(set-iprint t :soft-bound 3) ACL2 Observation in SET-IPRINT: The soft-bound for iprinting has been set to 3. ACL2 Observation in SET-IPRINT: Iprinting has been enabled. ACL2 !>(set-evisc-tuple (evisc-tuple 2 3 nil nil) :sites :ld) (:LD) ACL2 !>'((a b c d e f g) (a b c d e f g) (a b c d e f g)) ((A B C . #@1#) (A B C . #@2#) (A B C . #@3#)) ACL2 !>'((a b c d e f g) (a b c d e f g) (a b c d e f g)) ((A B C . #@4#) (A B C . #@5#) (A B C . #@6#)) ACL2 !>(without-evisc '((A B C . #@4#) (A B C . #@5#) (A B C . #@6#))) ((A B C D E F G) (A B C D E F G) (A B C D E F G)) ACL2 !>'(1 2 3 4 5) (1 2 3 . #@1#) ACL2 !>'((a b c d e f g) (a b c d e f g) (a b c d e f g)) ((A B C . #@2#) (A B C . #@3#) (A B C . #@4#)) ACL2 !>(without-evisc '((A B C . #@4#) (A B C . #@5#) (A B C . #@6#))) ((A B C D E F G) (A B C D E F G) (A B C D E F G)) ACL2 !>(without-evisc '((A B C . #@4#) (A B C . #@5#) (A B C . #@6#))) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Out-of-bounds index in #@5#. See :DOC set-iprint. *********************************************** The message above might explain the error. If not, and if you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !> Rollover has the following additional effect when iprint sharing is on: it is illegal to read a form that has both an index from before the rollover and an index from after the rollover. The following log illustrates this requirement. Note that if the last input form below were read without error, the result would likely be highly confusing, since iprint index 1 no longer refers to the value it was originally given at the time the other iprint indices in the input (2, 3, and 4) were given their values. ACL2 !>(set-iprint t :soft-bound 3 :share t) ACL2 Warning [Iprint] in SET-IPRINT: Converting SET-IPRINT action from T to :RESET-ENABLE, as required by use of keyword :SHARE or :HARD- BOUND. See :DOC set-iprint. ACL2 Observation in SET-IPRINT: The soft-bound for iprinting has been set to 3. ACL2 Observation in SET-IPRINT: Iprinting is enabled with sharing, with a fast-alist whose name is :IPRINT-FAL. ACL2 Observation in SET-IPRINT: Iprinting has been reset and enabled. ACL2 !>(set-evisc-tuple (evisc-tuple 2 3 nil nil) :sites :ld) (:LD) ACL2 !>'((a b c d) (x y z w)) ((A B C . #@1#) (X Y Z . #@2#)) ACL2 !>'((e f g h) (k l m n)) ((E F G . #@3#) (K L M . #@4#)) ACL2 !>'(#@1# #@2# #@3# #@4#) ; OK, since rollover occurs after the read ((D) (W) (H) . #@1#) ACL2 !>'(#@1# #@2# #@3# #@4#) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Attempt to read a form containing both an index created before the most recent rollover (#@2#) and an index created after that rollover (#@1#). See :DOC set-iprint. *********************************************** The message above might explain the error. If not, and if you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 !> We conclude by mentioning two cases where iprinting and evisc-tuples are ignored. (1) This is typically the case when printing results in raw Lisp outside the ACL2 loop. To use iprinting and evisc-tuples in raw Lisp, use raw-mode; see [set-raw-mode]. In raw-mode, results that are ACL2 objects will be printed in the same way that ACL2 would print those results if not in raw-mode. (2) Iprinting and evisc-tuples are ignored by [47m[print-object$][0m, which however is sensitive to many settings that do not affect formatted ([47m[fmt][0m etc.) printing; see [print-control]. The reader interested in design and implementation issues considered during the addition of iprinting to ACL2 is invited to read the paper ``Abbreviated Output for Input in ACL2: An Implementation Case Study''; see the {proceedings of ACL2 Workshop 2009 | http://www.cs.utexas.edu/users/moore/acl2/workshop-2009/}.") (set-irrelevant-formals-ok (declare defun) "Allow irrelevant formals in definitions Examples: (set-irrelevant-formals-ok t) (set-irrelevant-formals-ok nil) (set-irrelevant-formals-ok :warn) The first example above allows irrelevant formals in definitions; see [irrelevant-formals]. The second example disallows irrelevant formals; this is the default. The third example allows irrelevant formals, but prints an appropriate warning. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. General Form: (set-irrelevant-formals-ok flg) where [47mflg[0m is either [47mt[0m, [47mnil[0m, or [47m:warn[0m. For a way to permit irrelevant formals in a specific definition, see [declare].") (set-ld-always-skip-top-level-locals (pointers) "See [ld-always-skip-top-level-locals].") (set-ld-error-action (pointers) "See [ld-error-action].") (set-ld-error-triples (pointers) "See [ld-error-triples].") (set-ld-evisc-tuple (pointers) "See [ld-evisc-tuple].") (set-ld-keyword-aliases (pointers) "See [ld-keyword-aliases].") (set-ld-keyword-aliases! (pointers) "See [ld-keyword-aliases].") (set-ld-missing-input-ok (pointers) "See [ld-missing-input-ok].") (set-ld-post-eval-print (pointers) "See [ld-post-eval-print].") (set-ld-pre-eval-filter (pointers) "See [ld-pre-eval-filter].") (set-ld-pre-eval-print (pointers) "See [ld-pre-eval-print].") (set-ld-prompt (pointers) "See [ld-prompt].") (set-ld-query-control-alist (pointers) "See [ld-query-control-alist].") (set-ld-redefinition-action (pointers) "See [ld-redefinition-action].") (set-ld-skip-proofs (pointers) "See [ld-skip-proofsp].") (set-ld-skip-proofsp (pointers) "See [ld-skip-proofsp].") (set-ld-user-stobjs-modified-warning (pointers) "See [user-stobjs-modified-warnings].") (set-ld-verbose (pointers) "See [ld-verbose].") (set-let*-abstraction (pointers) "See [set-let*-abstractionp].") (set-let*-abstractionp (output-controls) "To shorten many prettyprinted [clause]s Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. When this flag is set to [47mt[0m, subterms that occur more than once in a [clause] are abstracted away with [47m[let*][0m, generally shortening the displayed size of the clauses. This flag only affects how clauses are printed. It does not change what terms the theorem prover manipulates. :set-let*-abstractionp t ;;; or, (set-let*-abstractionp t) will cause the prettyprinter to do ``let* abstraction'' on clauses before they are printed. The algorithm finds the maximal multiply-occurring subterm and extracts it, binding it to some new variable and replacing its occurrences by that variable. This produces a [47mlet*[0m form. This process is iterated until no subterm occurs more than once. This process generally takes a little time, but less time than to print large clauses. The process can greatly reduce the amount of text produced by the prover. THIS ONLY AFFECTS HOW THE CLAUSES ARE PRINTED! The unabstracted clauses are manipulated by the theorem prover. :set-let*-abstractionp nil restores normal clause printing. The mode is stored in the defaults table, See [ACL2-defaults-table]. Thus, the mode may be set locally in books.") (set-match-free-default (free-variables) "Provide default for [47m:match-free[0m in future rules General Forms: (set-match-free-default :once) (set-match-free-default :all) (set-match-free-default nil) Note: This utility does not apply to [type-prescription] rules; for a related topic pertinent to such rules, see [free-variables-type-prescription]. As described elsewhere (see [free-variables]), a [rewrite], [linear], or [forward-chaining] rule may have free variables in its hypotheses, and ACL2 can be directed either to try all bindings (``[47m:all[0m'') or just the first (``[47m:once[0m'') when relieving that hypothesis, as a basis for relieving subsequent hypotheses. This directing of [47m:all[0m or [47m:once[0m is generally provided by specifying either [47m:match-free :once[0m or [47m:match-free :all[0m in the [47m:[0m[47m[rule-classes][0m of the rule. If neither of these is specified, then the most recent [47mset-match-free-default[0m is used by ACL2 to fill in this missing [47m:match-free[0m field. See [rule-classes]. Except: If the last [47mset-match-free-default[0m specifies [47mnil[0m, then ACL2 reverts to the behavior it had at start-up, as described in Remarks (2) and (3) below. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It uses the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs. Remarks. (1) The use of [47mset-match-free-default[0m has no effect on existing rules. In order to change the behavior of existing rules with respect to free-variable matching, see [add-match-free-override]. (2) If you submit a [rewrite], [linear], or [forward-chaining] rule with a free variable in a hypothesis, and no default setting was previously specified with [47mset-match-free-default[0m or the default setting is [47mnil[0m, and the rule is not within a book being processed with [47m[include-book][0m, [47m[certify-book][0m, or [47m[rebuild][0m, then a warning or error is caused. In order to make this an error instead of a warning, see [set-match-free-error]. (3) If you submit a [rewrite], [linear], or [forward-chaining] rule with a free variable in a hypothesis, and no default setting has been previously specified with [47mset-match-free-default[0m or the default setting is [47mnil[0m, and no error is caused (see (2) above), then the default [47m:all[0m is used.") (set-match-free-error (free-variables) "Control error vs. warning when [47m:match-free[0m is missing Legal Forms: (set-match-free-error nil) :set-match-free-error nil (set-match-free-error t) :set-match-free-error t As described elsewhere (see [free-variables]), when a [rewrite], [linear], or [forward-chaining] rule has free variables in its hypotheses, the user can specify whether to try all bindings (``[47m:all[0m'') or just the first (``[47m:once[0m'') when relieving its hypotheses, as a basis for relieving subsequent hypotheses. This direction of [47m:all[0m or [47m:once[0m is generally provided by specifying either [3m:match-free :once[0m or [3m:match-free :all[0m in the [47m:[0m[47m[rule-classes][0m of the rule. But suppose that neither of these is specified for such a rule. (Note: [47mset-match-free-error[0m is not relevant for [type-prescription] rules.) Also suppose that [47mset-match-free-default[0m has not specified a default of [47m:once[0m or [47m:all[0m (see [set-match-free-default]). In this case a warning will occur except when in the context of [47m[include-book][0m. If you prefer to see an error in such cases, except in the context of [47m[certify-book][0m, execute [47m(set-match-free-error t)[0m. If there is no error, then a default of [47m:all[0m is used. Note: This is NOT an event! Instead, [47mset-match-free-error[0m sets the state global [47m'match-free-error[0m (see [state] and see [assign]). Thus, this form cannot be put into a book. If you are tempted to put it into a book, consider the fact that it really isn't needed there, since the absence of [47m:match-free[0m does not cause an error in the context of [47m[certify-book][0m or [47m[include-book][0m. If you still feel the need for such a form, consider using [47mset-match-free-default[0m to provide a default, at least within the scope of the current book (if any); see [set-match-free-default].") (set-measure-function (defun) "Set the default measure function symbol Examples: (set-measure-function nqthm::count) Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. General Form: (set-measure-function name) where [47mname[0m is a function symbol of one argument. This macro is equivalent to [47m(table acl2-defaults-table :measure-function 'name)[0m, and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. Although this is thus an event (see [table]), nevertheless no output results from a [47mset-measure-function[0m event. This event sets the default measure function to [47mname[0m. Subsequently, if a recursively defined function is submitted to [47m[defun][0m with no explicitly given [47m:measure[0m argument, [47m[defun][0m ``guesses'' the measure [47m(name var)[0m, where [47mname[0m is the then current default measure function and [47mvar[0m is the first formal found to be tested along every branch and changed in every recursive call. Note that if [47m(table acl2-defaults-table :measure-function 'name)[0m has its default value of [47mnil[0m, then the default measure function is [47m[ACL2-count][0m.") (set-non-linear (pointers) "See [set-non-linearp].") (set-non-linearp (non-linear-arithmetic) "To turn on or off non-linear arithmetic reasoning Examples: (set-non-linearp t) (set-non-linearp nil) See [non-linear-arithmetic]. This event is equivalent to [47m(table acl2-defaults-table :non-linearp <t-or-nil>)[0m, and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. The initial value is [47mnil[0m.") (set-override-hints (override-hints) "Set the [override-hints] See [override-hints] for a discussion of override-hints. Here we describe how to set them. Note that the effects of [47mset-override-hints[0m [events] are [local] to the [books] or [47mencapsulate[0m [events] in which they reside; see [set-override-hints!] to avoid that restriction. Also see [add-override-hints] to add to the list of override-hints, rather than setting a new list and ignoring the present list. General Form: (set-override-hints form) where [47mform[0m evaluates to a list of computed hint forms. The effect of this event is to set the list of [override-hints] to the result of that evaluation.") (set-override-hints! (override-hints) "Set the [override-hints] non-[local]ly [47mSet-override-hints![0m is the same as [47m[set-override-hints][0m, except that the former is not [local] to [books] or [47m[encapsulate][0m [events] in which it occurs. See [set-override-hints]; also see [add-override-hints].") (set-parallel-execution (parallelism) "For ACL2(p): enabling parallel execution for four parallelism primitives This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. See [parallelism-tutorial] for an introduction to parallel execution in ACL2. General Forms: (set-parallel-execution nil) ; default for images not built for parallelism (set-parallel-execution t) ; default for images built for parallelism (set-parallel-execution :bogus-parallelism-ok) [47mSet-parallel-execution[0m takes an argument that specifies the enabling or disabling of [parallel] execution for the primitives [47m[pand][0m, [47m[por][0m, [47m[plet][0m, and [47m[pargs][0m (but not [47m[spec-mv-let][0m, whose parallel execution remains enabled). However, without using [47m[top-level][0m, calls of parallelism primitives made explicitly in the ACL2 top-level loop, as opposed to inside function bodies, will never cause parallel execution; see [parallelism-at-the-top-level]. Parallel execution is determined by the value of the argument to [47mset-parallel-execution[0m, as follows. Value [47mt[0m: All parallelism primitives used in bodies of function definitions are given the opportunity to execute in parallel. However, the use of parallelism primitives directly in the ACL2 top-level loop causes an error. Value [47m:bogus-parallelism-ok[0m: Parallel execution is enabled, as for value [47mt[0m. However, the use of parallelism primitives directly in the ACL2 top-level loop does not cause an error, but rather, simply results in serial execution for these primitives. Value [47mnil[0m: All parallelism primitives degrade to their serial equivalents, including their calls made directly in the ACL2 top-level loop. Thus, uses of parallelism primitives do not in themselves cause errors.") (set-persistent-whs-and-ephemeral-whs (wormhole) "maintaining wormhole coherence General Form: (set-persistent-whs-and-ephemeral-whs name new-status state) where [47mname[0m is the name of a [47m[wormhole][0m other than one of the built-in ACL2 system wormholes, and [47mnew-status[0m is the desired status of the wormhole. ACL2 insists that [47mname[0m be supplied as a [quote]d constant. The constant [47m*protected-system-wormhole-names*[0m lists the names of the built-in wormholes and includes [47mbrr[0m (the [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and [47mfc-wormhole[0m (the name of the wormhole managing [forward-chaining-reports]), among others. [47mSet-persistent-whs-and-ephemeral-whs[0m moves [47mnew-status[0m into the wormhole's persistent-whs (the status stored outside of the ACL2 state) and then executes [47m[sync-ephemeral-whs-with-persistent-whs][0m to re-establish coherence. It returns a modified [47mstate[0m. See [wormhole-programming-tips] for some tips for using this function.") (set-print-base (io acl2-built-ins) "Control radix in which numbers are printed Also see [47m[set-print-base-radix][0m for a nice combined use of [47mset-print-base[0m and [47m[set-print-radix][0m. By default, integers and ratios are printed in base 10. ACL2 also supports printing in radix 2, 8, or 16 by calling set-print-base with the desired radix (base). (set-print-base 10 state) ; Default printing (set-print-base 16 state) ; Print integers and ratios in hex Here is a sample log. ACL2 !>(list 25 25/3) (25 25/3) ACL2 !>(set-print-base 16 state) <state> ACL2 !>(list 25 25/3) (19 19/3) ACL2 !> See [set-print-radix] for how to print the radix, for example, printing the decimal number 25 in print-base 16 as ``[47m#x25[0m'' rather than ``[47m25[0m''. Also see [print-control] for other user-settable print controls. Note: ACL2 [events] and some other top-level commands (for example, [47m[thm][0m, [47m[verify][0m, and history commands such as [47m:[0m[47mpe[0m and [47m:[0m[47mpbt[0m) set the print base to 10 during their evaluation. So [47m[set-print-base][0m has no effect while these forms are being processed.") (set-print-base-radix (io acl2-built-ins) "Control radix in which numbers are printed and printing of the radix See [47m[set-print-base][0m and [47m[set-print-radix][0m for detailed discussions of those functions. [47mSet-print-base-radix[0m combines their functionality by setting the base (as is done by [47m[set-print-base][0m), and then causing the radix to be printed (as is done by [47m[set-print-radix][0m) exactly when the specified radix is not 10. Here is a sample log. ACL2 !>(list 25 25/3) (25 25/3) ACL2 !>(set-print-base-radix 16 state) <state> ACL2 !>(list 25 25/3) (#x19 #x19/3) ACL2 !>(set-print-base-radix 10 state) <state> ACL2 !>(list 25 25/3) (25 25/3) ACL2 !>") (set-print-case (io acl2-built-ins symbols) "Control whether [symbols] are printed in upper case or in lower case By default, [symbols] are printed in upper case when vertical bars are not required, as specified by Common Lisp. As with Common Lisp, ACL2 supports printing in a "downcase" mode, where symbols are printed in lower case. Many printing functions (some details below) print characters in lower case for a symbol when the ACL2 [state] global variable [47mprint-case[0m has value [47m:downcase[0m and vertical bars are not necessary for printing that symbol. (Thus, this state global functions in complete analogy to the Common Lisp global [47m*print-case*[0m.) The value [47mprint-case[0m is returned by [47m(print-case)[0m, and may be set using the function [47mset-print-case[0m as follows. (set-print-case :upcase state) ; Default printing (set-print-case :downcase state) ; Print symbols in lower case when ; vertical bars are not required The ACL2 user can expect that the [47m:downcase[0m setting will have an effect for formatted output (see [fmt] and see [fms]) when the directives are [47m~x[0m, [47m~X[0m, [47m~y[0m, or [47m~Y[0m, for built-in functions [47mprinc$[0m and [47mprin1$[0m, and the [47mppr[0m family of functions, and [3mnot[0m for built-in function [47mprint-object$[0m. For other printing functions, the effect of [47m:downcase[0m is unspecified. Also see [print-control] for other user-settable print controls.") (set-print-circle (pointers) "See [print-control].") (set-print-clause-ids (output-controls) "Cause subgoal numbers to be printed when [47m'prove[0m output is inhibited General Forms: (set-print-clause-ids t) :set-print-clause-ids t (set-print-clause-ids nil) :set-print-clause-ids nil This command affects output from the theorem prover only when [47m'prove[0m output is inhibited (see [set-inhibit-output-lst]) or gag-mode is on (but in that case the [47m:goals[0m setting issues this command automatically; see [set-gag-mode]). Calling this macro with value [47mt[0m as shown above will cause subsequent proof attempts with [47m'prove[0m output inhibited to print the subgoal number, so that you can see the progress of the proof; value [47mnil[0m reverts to the default behavior, where this is not the case. On a related note, we point out that you can cause output to be saved for later display; see [pso] and see [pso!]. If [47m'prove[0m output is inhibited or gag-mode is on, and if you issue [47m(set-print-clause-ids t)[0m (either explicitly or with [47m(set-gag-mode :goals)[0m), then you can restrict when subgoal numbers are printed. In the following example we restrict to subgoals that are no more than four inductions deep, no more than four casesplits deep, and no more than four single-subgoals deep. For additional relevant explanation, see [clause-identifier] and see [defattach]. (defun print-clause-id-okp-level-4 (cl-id) (declare (xargs :mode :logic :guard (clause-id-p cl-id))) (and (<= (length (access clause-id cl-id :pool-lst)) 4) (<= (length (access clause-id cl-id :case-lst)) 4) (<= (access clause-id cl-id :primes) 4))) (defattach-system print-clause-id-okp print-clause-id-okp-level-4)") (set-print-escape (pointers) "See [print-control].") (set-print-gv-defaults (print-gv guard debugging) "Set default keyword values for [47m[print-gv][0m Example Forms: (set-print-gv-defaults :conjunct t) (set-print-gv-defaults :conjunct t :substitute t) (set-print-gv-defaults :conjunct t :substitute 20) (set-print-gv-defaults :evisc-tuple (evisc-tuple 4 ; print-level 5 ; print-length (world-evisceration-alist state nil) nil ; hiding-cars )) (set-print-gv-defaults :conjunct :restore :substitute :restore :evisc-tuple :restore) (set-print-gv-defaults) General Form: (set-print-gv-defaults :conjunct c :substitute s :evisc-tuple e) where any or all of [47mc[0m, [47ms[0m, and [47me[0m may be the keyword, [47m:restore[0m, and otherwise these are as for [47m[print-gv][0m. These forms set the defaults for the corresponding keyword arguments of the [47mprint-gv[0m utility, where the value [47m:restore[0m restores the system defaults; see [print-gv]. Evaluation returns an [error-triple] whose value is an alist associating keywords with their current defaults. In particular, the call [47m(set-print-gv-defaults)[0m simply returns an error-triple with that alist as the value, without changing any defaults. Thus, for example, if you submit the form (set-print-gv-defaults :substitute t :conjunct t :evisc-tuple (evisc-tuple 3 4 nil nil)) then subsequently, if you submit the form [47m:print-gv[0m or [47m(print-gv[0m) it would be interpreted as follows. (print-gv :substitute t :conjunct t :evisc-tuple (evisc-tuple 3 4 nil nil)) Of course, you can override your defaults, so that for example if you subsequently submit the form [47m(print-gv :substitute nil)[0m or the form [47m(print-gv :substitute nil :evisc-tuple (print-gv-evisc-tuple))[0m, these would be equivalent to submitting the following forms, respectively. (print-gv :substitute nil :conjunct t :evisc-tuple (evisc-tuple 3 4 nil nil)) (print-gv :substitute nil :conjunct t :evisc-tuple (print-gv-evisc-tuple))") (set-print-length (pointers) "See [print-control].") (set-print-level (pointers) "See [print-control].") (set-print-lines (pointers) "See [print-control].") (set-print-radix (io acl2-built-ins) "Control printing of the radix for numbers Also see [47m[set-print-base-radix][0m for a nice combined use of [47m[set-print-base][0m and [47mset-print-radix[0m. See [set-print-base] for background on how the print base affects the printing of numbers. [47mset-print-radix[0m affects whether a radix indicated when a number is printed. The radix is not indicated by default, or after evaluating [47m(set-print-radix nil state)[0m. But if [47mset-print-radix[0m is called with a first argument that evaluates to a non[47mnil[0m value --- for example, [47m(set-print-radix t state)[0m --- then the radix is shown when printing. (This behavior is consistent with the handling of Common Lisp global [47m*print-radix*[0m.) The following log illustrates how this works. ACL2 !>(list 25 25/3) (25 25/3) ACL2 !>(set-print-base 16 state) <state> ACL2 !>(list 25 25/3) (19 19/3) ACL2 !>(set-print-radix t state) <state> ACL2 !>(list 25 25/3) (#x19 #x19/3) ACL2 !>(set-print-base 10 state) <state> ACL2 !>(list 25 25/3) (25. #10r25/3) ACL2 !>(set-print-radix nil state) <state> ACL2 !>(list 25 25/3) (25 25/3) ACL2 !>") (set-print-readably (pointers) "See [print-control].") (set-print-right-margin (pointers) "See [print-control].") (set-proofs-co (pointers) "See [proofs-co].") (set-prover-step-limit (miscellaneous) "Sets the step-limit used by the ACL2 prover This event provides a way to limit the number of so-called ``prover steps'' permitted for an event. See [with-prover-step-limit] for a way to specify the limit on prover steps for a single event, rather than globally. For a related utility based on time instead of prover steps, see [with-prover-time-limit]. For examples of how step limits work, see the community book [47mbooks/misc/misc2/step-limits.lisp[0m. For a utility that returns an indicator of the number of prover steps most recently taken, see [last-prover-steps]. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. Example Forms: (set-prover-step-limit *default-step-limit*) ; no limit on prover steps (set-prover-step-limit nil) ; abbreviation for the form just above (set-prover-step-limit 10000) ; allow at most 10,000 prover steps per event General Form: (set-prover-step-limit expr) where [47mexpr[0m evaluates either to [47mnil[0m or else to a natural number not exceeding the value of [47m*default-step-limit*[0m. If that value is [47mnil[0m or the value of [47m*default-step-limit*[0m, then no default limit is placed on the number of prover ``steps'' (see below) during processing of an event. Otherwise, that value is the maximum number of prover steps permitted before an error occurs. This event specifies the limit on the number of ``steps'' counted by the ACL2 prover during processing of an event. Currently, a step is counted for each call of the system functions [47mrewrite[0m and [47mexpand-abbreviations[0m. However, the steps counted may change in future releases of ACL2, so users would probably be well served by avoiding the assumption that only the above two calls are counted as prover steps. Depending on the computer you are using, you may have less than a half-hour of time before the number of prover steps exceeds the maximum step-limit, which is one less than the value of [47m*default-step-limit*[0m. Note however the exception stated above: if the ``limit'' is [47mnil[0m or is the value of [47m*default-step-limit*[0m, then no limit is imposed. There is at best a loose connection between the counting of steps and [47m[with-prover-time-limit][0m. In particular, for a call of [47mmfc-rw[0m or any [47mmfc-[0m function (see [extended-metafunctions]), the steps taken during that call are forgotten when returning from that call. The limit is relevant for every event, as well as for calls of [47m[thm][0m and [47m[certify-book][0m --- and more generally, to any form that creates a ``summary context'' to print the usual event [summary]. The limit is also put in force when entering the interactive [proof-builder]. A call of [47mset-prover-step-limit[0m applies to each subsequent form unless the call of [47mset-prover-step-limit[0m is within a summary context, in which case its effect disappears when exiting that summary context. The limit applies to each event, not just ``atomic'' events. Consider the following example. (set-prover-step-limit 500) (encapsulate () (defthm lemma-1 ; takes 380 steps (equal (append (append x y) z) (append x y z)) :rule-classes nil) (defthm lemma-2 ; would take 319 steps (equal (len (append x y)) (+ (len x) (len y))) :rule-classes nil)) The first [47m[defthm][0m event, [47mlemma-1[0m takes 380 steps (as of this writing), as shown in the [summary]: Prover steps counted: 380 LEMMA-1 The second [47m[defthm][0m event, [47mlemma-2[0m, takes 319 steps (as of this writing) when evaluated at the top level. However, in the context above, 380 steps of the available 500 steps (from the [47mset-prover-step-limit[0m event above) have already been taken under the above [47m[encapsulate][0m event. Thus, when the number of steps would exceed 120, the proof of [47mlemma-2[0m is aborted: ACL2 Error in STEP-LIMIT: The prover step-limit, which is 120 in the current context, has been exceeded. See :DOC set-prover-step-limit. The summary for [47mlemma-2[0m reflects that situation: Prover steps counted: More than 120 The summary for the [47m[encapsulate][0m event then indicates that the available steps for that event have also been exceeded: Prover steps counted: More than 500 The discussion above applies to any event that contains other events, hence applies similarly to [47m[progn][0m events. For those who use [47m[make-event][0m, we note that prover steps in the expansion phase similarly contribute to the total number of steps counted. For example, suppose that the limit is 500 prover steps as above, and you submit [47m(make-event EXPR)[0m, where 300 prover steps take place during evaluation of [47mEXPR[0m, producing event [47mEV[0m. Then evaluation of [47mEV[0m will cause an error if it takes more than 200 prover steps. This observation actually can be used to count prover steps for sequences of forms that are not all legal [47m[events][0m (see [embedded-event-form]), such as calls of [47m[thm][0m. For example, a small built-in ACL2 test suite that includes [47m[thm][0m forms can be run by evaluating the form [47m(mini-proveall)[0m, and the steps can be counted as shown below. (Here we assume a fresh ACL2 session; an error would occur if first, we evaluate the event [47m(set-prover-step-limit 500)[0m displayed above.) ACL2 !>(make-event (er-progn (mini-proveall) (value '(value-triple nil)))) [[... output omitted here ...]] Summary Form: ( MAKE-EVENT (ER-PROGN ...)) Rules: NIL Warnings: Double-rewrite, Equiv, Subsume and Non-rec Time: 0.38 seconds (prove: 0.04, print: 0.29, other: 0.05) Prover steps counted: 41090 NIL ACL2 !> Subtopics [Last-prover-steps] The number of prover steps most recently taken") (set-raw-mode (defttag) "Enter or exit ``raw mode,'' a raw Lisp environment Below we discuss raw-mode. In brief: The simplest way to turn raw-mode on is [47m:SET-RAW-MODE-ON![0m, and to turn it off, [47m:SET-RAW-MODE NIL[0m. Also see [set-raw-mode-on!]. ACL2 users often find its careful syntax checking to be helpful during code development. Sometimes it is even useful to do code development in [47m:[0m[47m[logic][0m mode, where ACL2 can be used to check termination of (mutually) recursive functions, verify guards, or even prove properties of the functions. However, loading code using [47m[include-book][0m is much slower than using Common Lisp [47mload[0m in raw Lisp, and in this sense ACL2 can get in the way of efficient execution. Unfortunately, it is error-prone to use ACL2 sources (or their compilations) in raw Lisp, primarily because a number of ACL2 primitives will not let you do so. Perhaps you have seen this error message when trying to do so: HARD ACL2 ERROR in ACL2-UNWIND-PROTECT: Apparently you have tried to execute a form in raw Lisp that is only intended to be executed inside the ACL2 loop. Even without this problem it is important to enter the ACL2 loop (see [lp]), for example in order to set the [47m[cbd][0m and (to get more technical) the readtable. See [q]. ACL2 provides a ``raw mode'' for execution of raw Lisp forms. In this mode, [47m[include-book][0m reduces essentially to a Common Lisp [47mload[0m. More generally, the ACL2 logical [47m[world][0m is not routinely extended in raw mode (some sneaky tricks are probably required to make that happen). To turn raw mode off or on: :set-raw-mode t ; turn raw mode on :set-raw-mode-on! ; same as above, but no trust tag required :set-raw-mode nil ; turn raw mode off The way you can tell that you are in raw mode is by looking at the prompt (see [default-print-prompt]), which uses a capital ``[47mP[0m'' (suggesting something like [program] mode, but even further from [logic] mode). ACL2 P> Typical benefits of raw mode are fast loading of source and compiled files and the capability to hack arbitrary Common Lisp code in an environment with the ACL2 sources loaded (and hence with ACL2 primitives available). However, it probably is generally best to avoid raw mode unless these advantages seem important. We expect the main benefit of raw mode to be in deployment of applications, where raw Lisp code may be useful, and where load time is much faster than the time required for a full-blown [47m[include-book][0m --- but not that the fast loading of books and treatment of hard errors discussed above may be useful during development. Raw mode is also useful for those who want to build extensions of ACL2. For example, the following form can be put into a certifiable book to load an arbitrary Common Lisp source or compiled file. (progn (defttag my-application) (progn! (set-raw-mode t) (load "some-file"))) Also see [include-raw] [with-raw-mode], [defttag], and [progn!]. Below are several disadvantages to using raw mode. These should discourage users from using it for general code development, as [47m:[0m[47m[program][0m mode is generally preferable. * Forms are in essence executed in raw Lisp. Hence: * Syntax checking is turned off; and * Guard checking is completely disabled. * Table events, including [47m[logic][0m, are ignored, as are many other [47m[events][0m, including [47m[defthm][0m and [47m[comp][0m. * Soundness claims are weakened for any ACL2 session in which raw mode was ever entered; see [defttag]. * The normal undoing mechanism (see [ubt]) is not supported. * Unexpected behavior may occur when you return from raw-mode. For example, if you redefine a :logic mode function whose guards have not been verified, you will not see the change inside the ACL2 loop because there, the raw Common Lisp definition is only executed after guards have been verified; see [guards-and-evaluation] and see [guard-evaluation-table]. We conclude with some details. [3mPrinting results[0m. The rules for printing results are mostly unchanged for raw mode, even to the point of attempting appropriate printing for state and stobjs (though this is merely heuristic when the top-level function is defined in raw mode), for example as follows. ACL2 !>(defstobj st fld) Summary Form: ( DEFSTOBJ ST ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) ST ACL2 !>(set-raw-mode-on!) TTAG NOTE: Adding ttag :RAW-MODE-HACK from the top level loop. ACL2 P>(defun f (st) st) F ACL2 P>(f st) <st> ACL2 P>(defun g (st state) (mv 3 st state)) G ACL2 P>(g st state) (3 <st> <state>) ACL2 P>(defun h (state) (mv nil 17 state)) H ACL2 P>(h state) ; notice the leading space; see below 17 ACL2 P> There is however one major exception. If the value to be printed contains any Lisp object that is not a legal ACL2 object, then the [47mprint[0m routine is used from the host Lisp, rather than the usual ACL2 printing routine. The following example illustrates the printing used when an illegal ACL2 object needs to be printed. Notice how that ``command conventions'' are observed, as indicated in the ``leading space'' comment above; see [ld-post-eval-print]. In particular, the ``[47m[Note[0m'' occurs one space over in the second example, and no result is printed in the third example. ACL2 P>(find-package "ACL2") [Note: Printing non-ACL2 result.] #<The ACL2 package> ACL2 P>(mv nil (find-package "ACL2") state) [Note: Printing non-ACL2 result.] #<The ACL2 package> ACL2 P>(mv t (find-package "ACL2") state) ACL2 P>(mv 3 (find-package "ACL2")) [Note: Printing non-ACL2 result.] (3 #<The ACL2 package>) ACL2 P> If you have trouble with large structures being printed out, you might want to execute appropriate Common Lisp forms in raw mode, for example, [47m(setq *print-length* 5)[0m and [47m(setq *print-level* 5)[0m. Evaluation in raw mode attempts to maintain global [stobjs], but may not accommodate arbitrary raw Lisp hacks that hide the stobj returned by ACL2. This can happen in two cases: when array resizing is used on the unique (array) field of a stobj, and when [47m[swap-stobjs][0m is used. Consider for example the following log. Evaluation behaves nicely for all forms except the last, where resizing seems not to have taken effect as explained after the log, below. ACL2 !>(defstobj st fld) Summary Form: ( DEFSTOBJ ST ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) ST ACL2 !>(defstobj st2 (ar :type (array t (8)) :resizable t)) Summary Form: ( DEFSTOBJ ST2 ...) Rules: NIL Time: 0.02 seconds (prove: 0.00, print: 0.00, other: 0.02) ST2 ACL2 !>(set-raw-mode-on!) TTAG NOTE: Adding ttag :RAW-MODE-HACK from the top level loop. ACL2 P>(progn (update-fld 3 st) 17) 17 ACL2 P>(resize-ar 20 st2) <st2> ACL2 P>(ar-length st2) 20 ACL2 P>(progn (resize-ar 30 st2) 17) 17 ACL2 P>(ar-length st2) ; Should be 30, but it's not! 20 ACL2 P> The reason for the last form's ``wrong'' result (and the other ``correct'' results) is technical. A stobj with a single array field is exactly that array in raw Lisp (except in some cases where that may be an array of characters), in which case resizing completely replaces the stobj in the global structure that stores the global stobj values. The use of raw-Lisp [47mprogn[0m hides the evidence of stobj modification, which is based on the stobjs returned by the form (but this [47mprogn[0m form returns 17). Such evidence is available in the earlier call of [47mresize-ar[0m above, since ACL2 knows that [47mresize-ar[0m returns a [47mst2[0m stobj. The [47mupdate-fld[0m call does not provide such evidence for [47mst1[0m, again because of the [47mprogn[0m around the call; but [47mupdate-fld[0m actually modifies the stobj in place, rather than replacing it in the aforementioned global structure. [3mInclude-book[0m. The [events] [47m[add-include-book-dir][0m, [47m[add-include-book-dir!][0m, [47m[delete-include-book-dir][0m, and [47m[delete-include-book-dir!][0m have been designed to work with raw mode. However, if you enter raw mode and then evaluate such forms, then the effects of these forms will disappear when you exit raw mode, in which case you can expect to see a suitable warning. Regarding [3minclude-book[0m itself: it should work in raw mode as you might expect, at least if a compiled file or expansion file was created when the book was certified; see [certify-book].") (set-raw-mode-on (defttag) "Enter ``raw mode,'' a raw Lisp environment (requires trust tag) [47m(Set-raw-mode-on state)[0m is equivalent to [47m([0m[47m[set-raw-mode][0m[47m t)[0m; see [set-raw-mode]. Both require an active trust tag; see [defttag]. Also see [set-raw-mode-on!], which first introduces a trust tag.") (set-raw-mode-on! (defttag) "Enter ``raw mode,'' a raw Lisp environment (adds trust tag) This is equivalent to [47m([0m[47m[set-raw-mode][0m[47m t)[0m except that it first introduces the required trust tag; see [defttag]. See [set-raw-mode] for a discussion of raw-mode.") (set-raw-proof-format (output-controls) "Proof output with [rune]s as lists and maybe clausal goals General Forms: (set-raw-proof-format t) :set-raw-proof-format t (set-raw-proof-format nil) :set-raw-proof-format nil (set-raw-proof-format :clause) :set-raw-proof-format :clause This command affects output from the theorem prover only when [47m'prove[0m output is not inhibited (see [set-inhibit-output-lst]) and gag-mode is off (see [set-gag-mode]). The default behavior is obtained with argument [47mnil[0m. Calling this macro with argument [47mt[0m will cause simplification steps from proof output, including steps from preprocess (see [simple]), to print the list of runes used in a list format, rather than in the English proof commentary. This ``raw'' format can be handy when you want to use that list as a basis for [47m[hints][0m that you construct for a subsequent proof attempt. Calling this macro with argument [47m:clause[0m provides not only the behavior described above for argument [47mt[0m, but also causes goals to be printed using their internal clausal format: each goal is a list, implicitly disjoined, of translated [term]s. See [clause]. To obtain the current raw proof format value of [47mt[0m, [47m:clause[0m or [47mnil[0m, corresponding to the descriptions above, evaluate [47m(@ raw-proof-format)[0m.") (set-raw-warning-format (output-controls) "Print some warnings in a ``raw'', s-expression format General Forms: (set-raw-warning-format t) :set-raw-warning-format t (set-raw-warning-format nil) :set-raw-warning-format nil This command affects [47m'warning[0m (and [47m'warning![0m) output from the theorem prover when not inhibited (see [set-inhibit-output-lst]). Calling this macro with value [47mt[0m as shown above will cause warnings to be printed in a ``raw'', s-expression format, of the form [47m(:WARNING warning-type alist)[0m. The following example shows a traditional warning message followed by its counterpart after evaluating [47m(set-raw-warning-format t)[0m. ; default format ACL2 Warning [Subsume] in ( DEFTHM APP-COMMUTES ...): A newly proposed :REWRITE rule generated from APP-COMMUTES probably subsumes the previously added :REWRITE rule APP-CONS, in the sense that the new rule will now probably be applied whenever the old rule would have been. ; raw format (:WARNING "Subsume" ((:CTX (DEFTHM . APP-COMMUTES)) (:NEW-RULE APP-COMMUTES) (:RULE-CLASS-NEW :REWRITE) (:RULE-CLASS-OLD :REWRITE) (:SUBSUMED-RULES (APP-CONS)))) As illustrated above, it is typical that in the raw format, the [47m:CTX[0m entry is first in the alist while the others are ordered alphabetically by key (e.g., [47m:NEW-RULE[0m precedes [47m:RULE-CLASS-NEW[0m alphabetically). To obtain the current raw-warning-format ([47mt[0m if that format is active, [47mnil[0m if not), evaluate [47m(@ raw-warning-format)[0m. NOTE: Only a few commonly-occurring classes of warnings are shown differently in raw-warning-format.") (set-register-invariant-risk (programming advanced-features guard debugging invariant-risk) "Avoid [invariant-risk] checking for specified functions See [invariant-risk] for an introduction to the notion of invariant-risk. Also see [set-check-invariant-risk] for a way to avoid invariant-risk checking at runtime. The present topic discusses a way to avoid marking specified functions as potentially having invariant-risk. General Forms: (set-register-invariant-risk t) ; default (set-register-invariant-risk nil) ; requires active trust tag See community book [47mbooks/demos/register-invariant-risk.lisp[0m for a demonstration of how to use this utility. Normally a function is marked by ACL2 as having ``invariant-risk'' if its execution may have the potential to corrupt the ACL2 state. This causes execution slowdown that is not necessary if there is actually no such potential. In such cases it may be advisable to instruct ACL2 to avoid marking that function as having invariant-risk. This can be done by including the form [47m(set-register-invariant-risk nil)[0m in the book (or its [portcullis] commands) or [47m[encapsulate][0m event that contains the definition of that function (or, it can be done in the top-level loop before defining that function). This action requires an active trust tag (see [defttag]) because you are asserting, without proof, that invariant-risk is impossible for that function. Its effect can be reversed (returning to the default behavior) by evaluating [47m(set-register-invariant-risk t)[0m, which does not require an active trust tag. To see the current setting (i.e., the default of [47mt[0m or else [47mnil[0m after evaluation of [47m(set-register-invariant-risk nil)[0m), evaluate [47m(get-register-invariant-risk state)[0m. Note this utility does not affect whether a [stobj] primitive is marked with invariant-risk (which seems too dangerous in general); it only applies to functions introduced by [47m[defun][0m. If you want a version of a stobj updater that has no invariant-risk and you have invoked [47m(set-register-invariant-risk nil)[0m, then define a function that calls the stobj updater. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].") (set-rewrite-stack-limit (rewrite-stack-limit) "Sets the rewrite stack depth used by the rewriter Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Example Forms: (set-rewrite-stack-limit 30) ; set to small limit :set-rewrite-stack-limit 30 ; same as above (set-rewrite-stack-limit *default-rewrite-stack-limit*) ; the default (set-rewrite-stack-limit (1- (expt 2 28))) ; maximum legal limit :set-rewrite-stack-limit nil ; same as above -- essentially, no limit This event sets the maximum stack depth for calls of certain functions that implement the ACL2 rewriter; see [rewrite-stack-limit]. It must be a non-negative integer less than 2^28. A call [47m(set-rewrite-stack-limit limit)[0m is equivalent to: (table acl2-defaults-table :rewrite-stack-limit limit). The use of [47m[ACL2-defaults-table][0m ensures that this event's effect is implicitly [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs. For a different but somewhat related concept, see [backchain-limit].") (set-ruler-extenders (pointers) "See [rulers].") (set-rw-cache-state (rewrite) "Set the default rw-cache-state The ACL2 rewriter uses a data structure, called the rw-cache (rewriter cache), to save failed attempts to apply conditional [rewrite] rules. The regression suite has taken approximately 11% less time with this mechanism. The rw-cache is active by default but this event allows its behavior to be modified or even disabled by changing the so-called [3mrw-cache-state[0m. Note that this event is [local] to its context (from [47m[encapsulate][0m or [47m[include-book][0m). For a non-local version, use [set-rw-cache-state!]. Example forms: (set-rw-cache-state :atom) ; default: rw-cache cleared for each literal ; (i.e., hypothesis or conclusion of a goal) (set-rw-cache-state nil) ; rw-cache is inactive (set-rw-cache-state t) ; rw-cache persists beyond each literal (set-rw-cache-state :disabled) ; rw-cache is inactive, but the rw-cache-state ; transitions to state t after ; simplification takes place General Form: (set-rw-cache-state val) where [47mval[0m evaluates to one of the four values shown in ``Example forms'' above. The default is [47m:atom[0m, which enables the rw-cache but clears it before rewriting a hypothesis or conclusion of any goal. The value [47mt[0m is provides more aggressive use of the rw-cache, basically preserving the rw-cache when there is a single subgoal. The value [47m:disabled[0m is the same as [47mt[0m, except that the rw-cache is initially inactive and only becomes active when some simplification has taken place. We have seen a few cases where value [47mt[0m will make a proof fail but [47m:disabled[0m does not. To obtain the current rw-cache-state, evaluate the form [47m(rw-cache-state (w state))[0m. The following example illustrates the rw-cache in action. You will see a break during evaluation of the [47m[thm][0m form. Type [47m:eval[0m and you will see a failed rewriting attempt. Type [47m:go[0m to continue, and at the next break type [47m:eval[0m again. This time you will see the same failed rewriting attempt, but this time labeled with a notation saying that the failure was cached earlier, which indicates that this time the rewriter did not even attempt to prove the hypothesis of the [rewrite] rule [47mf1->f2[0m. (defstub f1 (x) t) (defstub f2 (x) t) (defaxiom f1->f2 (implies (f1 x) (equal (f2 x) t))) :brr t :monitor (:rewrite f1->f2) t (thm (equal (car (f2 a)) (cdr (f2 a)))) Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs (see [set-rw-cache-state!] for a corresponding non-[47m[local][0m event). We also note that rw-cache-state changes may also be caused at the subgoal level; see [hints]. We welcome you to experiment with different rw-cache states. If the more aggressive values of [47mt[0m and [47m:disabled[0m cause proofs to fail, then you can revert to the default of [47m:atom[0m or even turn off the rw-cache using [47m(set-rw-cache-state nil)[0m. We don't expect users to need a deep knowledge of the rw-cache in order to do such experiments, but readers interested in details of the rw-cache implementation are invited to read the ``Essay on Rw-cache'' in the ACL2 source code.") (set-rw-cache-state! (rewrite) "Set the default rw-cache-state non-[47m[local][0mly Please see [set-rw-cache-state], which is the same as [47mset-rw-cache-state![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs.") (set-serialize-character (pointers) "See [with-serialize-character].") (set-serialize-character-system (serialize) "Avoid some special [serialize] writing, including for [47m.cert[0m files This function can be used to turn off (or on) the [serialize-write] capability, which is on by default, for writing certain files during book certification, including [certificate] files. To use this function during a session: ; Disable the use of serialize-write by book certification: (set-serialize-character-system nil state) ; Re-enable the use of serialize-write by book certification: (set-serialize-character-system #\Z state) To use this capability when certifying community-books, you can use a suitable [ACL2-customization] file, for example: cd books ; \ make basic \ ACL2_CUSTOMIZATION=`pwd`/../acl2-customization-files/no-serialize.lisp Alternatively, you can put the following form directly into the book: (make-event (pprogn (set-serialize-character-system nil state) (value '(value-triple nil)))) To control the use of [serialize] for writes controlled by the user rather than by the system, see [with-serialize-character].") (set-skip-meta-termp-checks (meta clause-processor) "Skip output checks for [meta] functions and [clause-processor]s WARNING: Use of this macro may render ACL2 unsound, which is why it requires a trust tag. If you obtained an error during application of a [meta]function, a hypothesis metafunction, or a [clause-processor], it might well be best to rewrite that function to avoid generating terms with the ``forbidden'' function calls described in that error message. However, judicious use of this macro can be useful during development; the rest of this topic describes its usage. The result of applying a [meta]function (or a hypothesis metafunction) must be a term. Similarly, the result of applying a [clause-processor] must be a list of clauses, where a clause is a list of terms (see [clause]). If these conditions fail, then an error occurs; see [term-table] for how one obtains some assistance towards avoiding such errors. By default, ACL2 actually enforces a stronger requirement: the resulting term or clause-list cannot contain any calls of ``forbidden'' function symbols: ones that would be illegal when submitting a theorem. These include function symbols that are [3muntouchable[0m (see [remove-untouchable]) as well as those that are keys of the alist [47m*ttag-fns*[0m. These two checks --- that the results are terms and that they contain no calls of forbidden function symbols --- can be expensive for large terms. The macro [47mset-skip-meta-termp-checks[0m provides a way to avoid both checks. Since these checks can be critical for soundness, a trust tag (see [defttag]) must be active in order to invoke this macro unless the argument is [47mnil[0m. It might be best to avoid using this macro except to skip such checks that you have identified to be expensive, and to skip them only when using ACL2 interactively (as opposed to doing batch certification jobs) --- though this macro might also be useful in determining when such checks are indeed expensive. There are two legal ways to call this macro, as follows. Note that the arguments are not evaluated. ; Skip all such checks: (set-skip-meta-termp-checks t) ; Skip such checks for functions fn1, ..., fnk (each of which is presumably a ; metafunction, hypothesis metafunction, or clause-processor): (set-skip-meta-termp-checks (fn1 ... fnk)) A special case of the second form above is to perform all such checks: [47m(set-skip-meta-termp-checks nil)[0m. No trust tag is required in this case. This macro actually generates a [local] [table] event, for the table [47mskip-meta-termp-checks-table[0m and its unique key, [47mt[0m. The macro [47m[set-skip-meta-termp-checks][0m generates a corresponding non-[local] [table] event. ACL2 !>:trans1 (set-skip-meta-termp-checks (f g)) (LOCAL (SET-SKIP-META-TERMP-CHECKS! (F G))) ACL2 !>:trans1 (set-skip-meta-termp-checks! (f g)) (TABLE SKIP-META-TERMP-CHECKS-TABLE T '(F G)) ACL2 !> It is probably good practice to use [47mset-skip-meta-termp-checks[0m rather than [47mset-skip-meta-termp-checks![0m, except when there is a compelling reason to do otherwise.") (set-skip-meta-termp-checks! (meta clause-processor) "Skip output checks non-[local]ly for [meta] functions and [clause-processor]s See [set-skip-meta-termp-checks].") (set-slow-alist-action (pointers) "See [slow-alist-warning].") (set-splitter-output (splitter) "Turn on or off reporting of rules that may have caused case splits Examples: (set-splitter-output t) ; enable reports of ``splitter'' rules (default) (set-splitter-output nil) ; disable reports of ``splitter'' rules After evaluation of the form [47m(set-splitter-output t)[0m (the default), then whenever [47mprove[0m output is not inhibited (see [set-inhibit-output-lst]), ACL2 will report [rewrite] and [definition] rules that may have reduced a goal to more than one subgoal. See [splitter] for how to interpret such reports. We call such rules ``splitter rules'' for the goal that is being split. This information can be useful in deciding how to eliminate large splits, for example of Goal into Subgoal 1000 through Subgoal 1, by disabling some splitter rules. If you want to avoid the printing of such information, you can put the form [47m(set-splitter-output t)[0m in your customization file; see [ACL2-customization]. Note that this command does not change the ACL2 [world]; it only modifies the [state]. More precisely, it sets a state global to the indicated value. (See [state] for discussion of the ``global-table'' of the state.) When [47mprove[0m output is enabled (see [set-inhibit-output-lst]), the value of that state global is the value of the form [47m([0m[47m[splitter-output][0m[47m)[0m; otherwise the value of that form is [47mnil[0m. Again, see [splitter] for the effects of turning on the reporting of splitter rules.") (set-standard-co (pointers) "See [standard-co].") (set-standard-oi (pointers) "See [standard-oi].") (set-state-ok (state) "Allow the use of STATE as a formal parameter Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. In brief: The variable symbol [47m[state][0m has an unusual status in ACL2. In order to use it, you either need to issue [47m:set-state-ok t[0m, as we explain below, or you need to declare it to be a [stobj], as explained elsewhere (see [declare-stobjs]). Now we explain in more detail. Because the variable symbol [47m[state][0m denotes the ``current ACL2 state,'' ACL2 treats the symbol very restrictively when it occurs as a formal parameter of a defined function. The novice user, who is unlikely to be aware of the special status of that symbol, is likely to be confused when error messages about [47mSTATE[0m are printed in response to the innocent choice of that symbol as a formal variable. Therefore the top-level ACL2 loop can operate in a mode in which [47m[state][0m is simply disallowed as a formal parameter. For a discussion of [47mSTATE[0m, See [state] and see [stobj]. Roughly speaking, at the top-level, the ``current ACL2 state'' is denoted by the variable symbol [47mSTATE[0m. Only the current state may be passed into a function expecting a state as an argument. Furthermore, the name of the formal parameter into which the current state is passed must be [47mSTATE[0m and nothing but the current state may be passed into a formal of that name. Therefore, only certain access and change functions can use that formal --- namely those with a [47mSTATE[0m formal --- and if any such function produces a new state it becomes the ``current state'' and must be passed along in the [47mSTATE[0m position thereafter. Thus, ACL2 requires that the state be single-threaded. This, in turn, allows us to represent only one state at a time and to produce new states from it destructively in a von Neumannesque fashion. The syntactic restrictions on the variable [47mSTATE[0m are enforced by the translate mechanism (see [trans] and see [term]) when terms are read. To prevent the novice user from seeing messages prohibiting certain uses of the variable symbol [47mSTATE[0m ACL2 has a mode in which it simply disallows the use of that symbol as a formal parameter. Use of the symbol causes a simple error message. The system is initially in that mode. To get out of that mode, execute: :set-state-ok t ;;; or, (set-state-ok t) It is not recommended that you do this until you have read the documentation of [47m[state][0m. To enter the mode in which use of [47mstate[0m is prohibited as a formal parameter, do: :set-state-ok nil The mode is stored in the defaults table, See [ACL2-defaults-table]. Thus, the mode may be set [47m[local][0mly in books.") (set-subgoal-loop-limits (miscellaneous) "Set the maximum length and repetition count of the subgoal path The ACL2 ``waterfall'' (see [hints-and-the-waterfall]) produces a tree of Goals and Subgoals. Consider a path through this tree in which each formula is an immediate descendant of the previous formula. More precisely, each element of the path records a goal formula (represented as a [clause]), the name by which the user may refer to it, e.g., [47m"Goal''"[0m or [47m"Subgoal *1/2.3"[0m (represented as a [clause-identifier]), the clause processor that produced the formula, e.g., [47msimplify-clause[0m, [47meliminate-destructors-clause[0m, [47mfertilize-clause[0m, etc., and the [ttree] that records the [rune]s the processor used and other information about what the processor did. Finally, each path starts with the top-level Goal or one of the cases produced by induction or a forcing round, and ends with (i) the reduction of the current goal to true, (ii) the abandonment of the proof attempt, or (iii) the addition of the current goal to the ``pool'' for a subsequent attempt at an inductive proof. [47mSubgoal-loop-limits[0m is a user-settable parameter that can limit (a) the maximum length of a path and (b) the maximum number of repetitions in the path of a formula and the clause processor that produced it. In particular, [47msubgoal-loop-limits[0m is a pair, [47m(len . cnt)[0m. If [47mlen[0m is [47mnil[0m, there is no limit on the length of a path, otherwise proof attempts are aborted if the length of any subgoal path exceeds [47mlen[0m. If [47mcnt[0m is [47mnil[0m, no check for formula repetition is made, otherwise each new subgoal formula (and its processor) is compared with [47m[equal][0m to the ancestors along the path. A probable loop is signaled and the proof is aborted if the number of occurrences exceeds [47mcnt[0m. The initial setting of [47msubgoal-loop-limits[0m is [47m(1000 . 2)[0m. That is, no proof can produce a path longer than a 1000 successive descendants or with more than 2 repetitions of the same formula (and processor). One might assume that a repetition count greater than 1 indicates a loop, but that is not true. Various ACL2 clause processors may see the same formula at different points along a path and, guided by heuristics sensitive to what happened the last time the formula was seen, do something different. This function, [47mset-subgoal-loop-limits[0m, sets the [47msubgoal-loop-limits[0m. Example Forms: (set-subgoal-loop-limits nil) ; = (set-subgoal-loop-limits '(nil . nil)) (set-subgoal-loop-limits t) ; = (set-subgoal-loop-limits '(nil . 2)) (set-subgoal-loop-limits 100) ; = (set-subgoal-loop-limits '(100 . 2)) (set-subgoal-loop-limits :default) ; = (set-subgoal-loop-limits '(100 . 2)) (set-subgoal-loop-limits '(100 . 5)) General Form: (set-subgoal-loop-limits term) where [47mterm[0m should evaluate to a [47m[cons][0m whose [47m[car][0m is either [47mnil[0m or a natural number and whose [47m[cdr][0m is [47mnil[0m or a non-0 natural number. However, several abbreviations are allowed. * If [47mterm[0m evaluates to [47mnil[0m, then [47m(nil . nil)[0m is used, imposing no limit on the length of a path and disabling loop detection. * If [47mterm[0m evaluates to [47mt[0m, then [47m(nil . 3)[0m is used, imposing no length limit but defining a loop to be 3 or more repetitions of a formula and proof technique. * If [47mterm[0m evaluates to a natural number, [47mn[0m, then the pair constructed by [47m(cons n 3)[0m is used, imposing a length limit of [47mn[0m and defining a loop to be 3 or more repetitions of a formula and proof technique. * If [47mterm[0m evaluates to [47m:DEFAULT[0m, then the pair [47m(1000 . 2)[0m is used, which sets the [47msubgoal-loop-limits[0m to its initial value, imposing a maximum path length of 1000 and a maximum repetition count of 2. When these limits are violated, an error occurs and the proof attempt is abandoned. Of course, there are loops other than the simple ones this feature enables! For example, the available rules may cause the simplifier to transform a subgoal into a bigger one, e.g., [47mGoal[0m [47m(p x)[0m may be transformed to [47mGoal'[0m [47m(p (f x))[0m, which may then transform to [47mGoal''[0m [47m(p (f (f x)))[0m, etc. [3mThe prover does not check for such loops.[0m However, such loops are stopped by the path length limit. (Internal rewrite loops, in which control never exits the simplifier, are not stopped even by a short path length.) For other ways to restrict the prover, see [set-rewrite-stack-limit], [with-prover-time-limit], [with-prover-step-limit], [set-prover-step-limit], and [set-induction-depth-limit]. If a proof aborts because of a probable loop and you suspect the prover is not really in a loop, i.e., that further iteration will break the cycle and make progress, use [47mset-subgoal-loop-limits[0m to change the default 3 to a bigger number and try the proof again! Checking for simple loops will slow down the prover in proofs producing very long subgoal paths. Note: [47mSet-subgoal-loop-limits[0m is an [event]! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. Moreover, its effect is to set the [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table]. To see the current limit (subgoal-loop-limits (w state)) When a loop is detected an error is signaled naming the clause processor, the repeated identical subgoals, and the runes used in each passage through the loop. One such error message is shown below. ACL2 Error [Waterfall-loop] in ( THM ...): The clause processor SIMPLIFY-CLAUSE has been applied to the same formula more than 2 times, namely at Goal', Goal'10' and Goal'19'. That suggests a loop in the waterfall. Consequently, we are aborting! The following list shows the runes used in each passage through the loop between successive subgoals. (("Goal'" ((:EXECUTABLE-COUNTERPART BINARY-+) (:REWRITE RULE1) (:REWRITE RULE2) (:REWRITE RULE3) (:REWRITE RULE4)) "Goal'10'") ("Goal'10'" ((:EXECUTABLE-COUNTERPART BINARY-+) (:REWRITE RULE1) (:REWRITE RULE2) (:REWRITE RULE3) (:REWRITE RULE4)) "Goal'19'")). For more information see :DOC set-subgoal-loop-limits. In the above example, we see that [47m"Goal'"[0m was transformed by [47mSIMPLIFY-CLAUSE[0m, using the runes listed, into [47m"Goal'10'"[0m. Furthermore, the formulas of [47m"Goal'"[0m and [47m"Goal'10'"[0m are identical. We also see that [47mSIMPLIFY-CLAUSE[0m then transformed [47m"Goal'10'"[0m, using the same runes, to the same formula again at [47m"Goal'19'"[0m. After the error, and if you so choose, you can use the utility [47m[pso][0m to display the (possibly gagged, see [set-gag-mode]) prover output between the named subgoals.") (set-table-guard (table events) "Set the [47m:guard[0m for a [table] This macro is a convenient interface for setting a [47mtable[0m's guard to produce user-friendly error messages when the guard fails. See [table] for background on table guards. As noted there, the table guard may reference variables [47mKEY[0m, [47mVAL[0m, [47mWORLD[0m, [47mENS[0m, and [47mSTATE[0m; that is the case for the [47mguard[0m and [47mcoda[0m mentioned below. Also particularly relevant here is the fact that the table guard can return a single value, but it can also return [47m(mv flg msg)[0m; in the latter case, if [47mflg[0m is [47mnil[0m then [47mmsg[0m is an error message. [47mSet-table-guard[0m is supplied a guard term that returns a single value, but sets the table guard to a corresponding term that returns values [47m(mv flg msg[0m), where [47mmsg[0m is constructed to be user-friendly when it is non-[47mnil[0m. General Form: (set-table-guard name guard :topic topic :show show :coda coda) where [47mname[0m is the name of a table, [47mguard[0m is a term returning a single value that specifies the guard of that table, and the optional keyword arguments are as follows. * [47m:Topic[0m defaults to [47mname[0m. Otherwise it is the name of a [documentation] topic to which the user is directed when the table guard fails. * [47m:Show[0m is [47mnil[0m by default, in which case the guard term is not included in the error message; otherwise it is included. * [47m:Coda[0m is [47mnil[0m by default. Otherwise it should be a message (see [msgp]) to be printed, preceded by two spaces, after the message that would otherwise be printed. The error message when keywords are omitted is as shown in the example below, but (of course) where [47mFOO[0m, [47mMY-KEY[0m, and [47mMY-VAL[0m are replaced respectively by the table name, the key, and the value. We start our example by evaluating the following two events. (defun foo-check (key val world) (declare (ignore val)) (function-symbolp key world)) (set-table-guard foo (foo-check key val world)) Then evaluation of [47m(table foo 'my-key 'my-val)[0m produces the following error message. ACL2 Error in ( TABLE FOO ...): The TABLE :guard for FOO disallows the combination of key MY-KEY and value MY-VAL. See :DOC FOO. Here we show what happens to the error message if instead we set the table guard as follows. As before, it should be clear from this example what the message would look like in general. This time we evaluate: (set-table-guard foo (foo-check key val world) :topic set-foo :show t :coda (and (eq val 'my-val) (msg "~x0 is an odd name for a value!" val))) This time, evaluation of [47m(table foo 'my-key 'my-val)[0m produces an error message that references [47m:DOC[0m topic [47mSET-FOO[0m instead of [47mFOO[0m (because of the [47m:topic[0m argument), shows the table guard (because of the [47m:show[0m argument), and prints a final coda (because of the [47m:coda[0m argument). ACL2 Error in ( TABLE FOO ...): The TABLE :guard for FOO disallows the combination of key MY-KEY and value MY-VAL. The :guard requires (FOO-CHECK KEY VAL WORLD). See :DOC SET-FOO. MY-VAL is an odd name for a value! It can be helpful for the table guard to be well-guarded. For the examples above, the error message from [47m(table foo 3 'my-val)[0m is ugly because [47m3[0m fails to satisfy the guard of [47mfunction-symbolp[0m, which is called by [47mfoo-check[0m. Here is a version of that function that produces the desired error message. (defun foo-check (key val world) (declare (xargs :guard t) (ignore val)) (and (symbolp key) ; for guard of function-symbolp (plist-worldp world) ; for guard of function-symbolp (function-symbolp key world))) Finally, here are two examples from the ACL2 source code. They illustrate that [47m:show t[0m is reasonable when the table guard is concise, and that [47m:topic[0m is necessary when the table name is undocumented. (set-table-guard invisible-fns-table (invisible-fns-entryp key val world) :show t) (set-table-guard inhibit-warnings-table (stringp key) :topic set-inhibit-warnings)") (set-tau-auto-mode (tau-system) "Turn on or off automatic (``greedy'') generation of [47m:tau-system[0m rules Examples: (set-tau-auto-mode t) ; select automatic (``greedy'') mode (set-tau-auto-mode nil) ; select manual mode This event is equivalent to [47m(table acl2-defaults-table :tau-auto-modep <t-or-nil>)[0m, and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. See [introduction-to-the-tau-system] for background details. The tau system gathers rules for its database in one of two ways: greedily or only at the explicit command of the user. ``Greedy'' mode is officially called ``automatic mode'' and is the default. The other mode is called ``manual mode.'' In automatic mode, all rules processed by ACL2 are also considered for inclusion in the tau database: if the [47m:corollary[0m of some proved theorem happens to fit into one of the forms described in [47m:[0m[47m[tau-system][0m, that rule is quietly added to the tau database [3mregardless of what[0m [47m:[0m[47m[rule-classes][0m the user named for the [47m:corollary[0m. Of course, such rules are also stored in the ways named by the user. See the [3mDesign Philosophy[0m section of [introduction-to-the-tau-system] for a discussion of why the tau system is greedy by default. More details are given on automatic mode after we explain manual mode. To more tightly control the rules available to the tau system, the user may select manual mode by executing [47m(set-tau-auto-mode nil)[0m. In manual mode, the only events that create [47m:tau-system[0m rules are [47mdefthm[0m events explicitly specifying the [47m:[0m[47m[tau-system][0m rule class in the [47m:[0m[47m[rule-classes][0m argument. Of course, for a [47m:tau-system[0m rule to be created from a proved formula (or its specified [47m:corollary[0m), the formula must be of the appropriate shape (syntactic form). See [tau-system]. In manual mode, if the [47m:tau-system[0m rule class is specified but the formula is not of an appropriate form an error is signaled. (Note: even in manual mode, monadic functions that are recognized as Boolean are classified as tau predicates; but no rules are created for them.) Returning to our discussion of automatic mode, a [47m:[0m[47m[tau-system][0m rule may be created by any of the events below, provided the definition or formula proved is of an appropriate shape: (1) [47mdefun[0m events introducing ``big switch'' or ``[47mmv-nth[0m synonyms,'' (2) [47mdefun[0m events creating type-prescription rules that may be also represented as ``signature rules'' of form 1, and (3) any [47mdefthm[0m event with a non-[47mnil[0m [47m:rule-classes[0m argument if no [47m:tau-system[0m rule is among the rule classes and the formula proved is in the shape of any [47mtau-system[0m rule. Of course, events such as [47m[defstobj][0m and [47m[defevaluator][0m may also add rules to the tau database when they execute the [47m[defun][0m and [47m[defthm][0m events implicit in their descriptions. See [tau-system] for a description of the various shapes mentioned above. Note that any rule (of any rule class) created when the tau system is in manual mode is also created in automatic mode. For example, if an event would create a [47m:DEFINITION[0m, [47m:TYPE-PRESCRIPTION[0m, [47mFORWARD-CHAINING[0m, or [47m:REWRITE[0m rule when the tau system is in manual mode, then the event will create that same rule when the tau system is in automatic mode. Automatic mode just means that some additional [47m:tau-system[0m rules may be created. Of course, if a [47mdefthm[0m event explicitly specifies a [47m:tau-system[0m rule class, then even if the tau system is in automatic mode, that tau rule is created from the proved formula (or the specified [47m:corollary[0m) or else an error is caused. But if the tau system is in automatic mode and a [47mdefthm[0m event doesn't explicitly specify a [47m:tau-system[0m rule class, then the system quietly checks each specified [47m:corollary[0m --- or, in the absence of any [47m:corollary[0m, it checks the proved formula --- for whether it can be stored as a tau rule. If so, then the system stores a tau rule, in addition to storing the specified rule. Of course, no error is signaled if a proved formula of some non-[47m:tau-system[0m rule class fails to be of an appropriate shape for the tau system. In automatic mode, if the [47m:rule-classes[0m specified for [47mdefthm[0m included several corollaries and any one of them is of class [47m:tau-system[0m then the only tau system rules created are those explicitly classed as [47m:tau-system[0m rules. For example, suppose a [47mdefthm[0m has one [47m:corollary[0m stored as a [47m:rewrite[0m rule and another [47m:corollary[0m stored as a [47m:tau-system[0m rule. But suppose the [47m:rewrite[0m rule happens to also to fit the form of a [47m:tau-system[0m rule. Is it added to the tau database or not? The answer is no. If you have taken the trouble to specify [47m:tau-system[0m corollaries for an event, then those corollaries are the only ones stored as tau system rules from that event. Note that had both corollaries been classed as [47m:rewrite[0m rules (and been of acceptable [47m:tau-system[0m form) both would have also been made [47m:tau-system[0m rules. This also allows you be in automatic mode and state a [47m:rewrite[0m or other non-[47m:tau-system[0m rule and prevent it from being also made a tau system rule: just add a frivolous [47m:tau-system[0m [47m:corollary[0m like [47m(booleanp (integerp x))[0m. Recall that the use of tau rules is controlled by the rune [47m(:EXECUTABLE-COUNTERPART TAU-SYSTEM)[0m. When that rune is disabled, no tau rules are [3mused[0m in proofs. However, the tau system continues to collect tau rules if the system is in automatic mode. Thus, if and when the tau system is re-enabled, rules automatically generated while the tau system was disabled will be used as usual by the tau system. Finally, note that [47mdefthm[0m events with [47m:rule-classes[0m [47mnil[0m do not create [47m:tau-system[0m rules even if the formula proved is of an appropriate shape, regardless of whether the tau system is in automatic or manual mode. The macro [47m[tau-status][0m provides a convenient way to enable/disable the [47m:[0m[47m[executable-counterpart][0m of [47mtau-system[0m and/or to switch between manual and automatic modes. It may also be used to determine the current settings of those two flags.") (set-temp-touchable-fns (pointers) "See [remove-untouchable].") (set-temp-touchable-vars (pointers) "See [remove-untouchable].") (set-total-parallelism-work-limit (parallelism) "For ACL2(p): set thread limit for parallelism primitives This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. While the most common use of the limit described below is in parallel proof (see [parallel-proof]), it also applies to all parallelism primitives (see [parallel-programming]) except [47m[spec-mv-let][0m --- though we expect that rather few programming applications will encounter this limit. General Forms: (set-total-parallelism-work-limit :none) ; disable the limit (set-total-parallelism-work-limit <integer>) ; set limit to <integer> See [parallelism-tutorial], Section ``Another Granularity Issue Related to Thread Limitations'', for an explanation of how the host Lisp can run out of threads. Also see [set-total-parallelism-work-limit-error]. If the underlying runtime system (the Operating System, the host Lisp, etc.) is unable to provide enough threads to finish executing the parallelism work given to it, the runtime system can crash in a very unpleasant manner (ranging from a Lisp error to completely freezing the machine). To avoid this unpleasantness, ACL2(p) will attempt to avoid creating so much parallelism that the runtime system crashes. ACL2 initially uses a conservative estimate to limit the number of threads. To tell ACL2(p) to use a different limit, call [47mset-total-parallelism-work-limit[0m with the new limit. For example, if the current default limit is 10,000, then to allow 13,000 threads to exist, issue the following form at the top level. (set-total-parallelism-work-limit 13000) To disable this limit altogether, evaluate the following form: (set-total-parallelism-work-limit :none) The default value of total-parallelism-work-limit can be found by calling function [47mdefault-total-parallelism-work-limit[0m. If the default value is too high for your system please notify the ACL2 maintainers with a limit that does work for your system, as they might then lower the default limit.") (set-total-parallelism-work-limit-error (parallelism) "For ACL2(p): control the action taken when the thread limit is exceeded This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. General Forms: (set-total-parallelism-work-limit-error t) ; cause error (default) (set-total-parallelism-work-limit-error nil) ; disable error and ; continue serially See [parallelism-tutorial], Section ``Another Granularity Issue Related to Thread Limitations'', for an explanation of how the host Lisp can run out of threads. See [set-total-parallelism-work-limit] for further details, including an explanation of how to manage the limit that triggers this error. The value of state global [47mtotal-parallelism-work-limit-error[0m dictates what occurs when the underlying runtime system runs reaches a limit on the number of threads for parallel computation. By default, when this limit is reached, the ACL2(p) user will receive an error and computation will halt. At this point, the ACL2(p) user has the following options. (1) Remove the limit by evaluating the following form. (set-total-parallelism-work-limit :none) (2) Disable the error so that execution continues serially once the available thread resources have been exhausted. (set-total-parallelism-work-limit-error nil) (3) Increase the limit on number of threads that ACL2(p) is willing to create, in spite of potential risk (see [set-total-parallelism-work-limit]). In this case, the following query returns the current limit. (f-get-global 'total-parallelism-work-limit) Then to increase that limit, evaluate the following form: (set-total-parallelism-work-limit <new-integer-value>) For example, suppose that the value of [47mtotal-parallelism-work-limit[0m was originally 10,000. Then evaluation of the following form increases that limit to 13,000. (set-total-parallelism-work-limit 13000)") (set-trace-co (pointers) "See [trace-co].") (set-trace-evisc-tuple (trace) "Set the trace evisc tuple A trace evisc-tuple, which is set by this utility, provides a means to restrict printing during tracing. See [evisc-tuple] for an introduction to evisc-tuples; also see [set-evisc-tuple] and see [set-iprint]. By default the ACL2 [trace] mechanism, [47m[trace$][0m, automatically deals with stobjs, the logical world, and certain other large structures. See [trace$], in particular the documentation of [47mtrace$[0m option [47m:hide[0m. However, even with that default behavior you may want to restrict what is printed according to the print-level and print-length of an evisc-tuple; see [evisc-tuple]. Examples: ; Set trace evisc tuple to a standard value, using current Lisp *print-level* ; and *print-length* variables: (set-trace-evisc-tuple t state) ; Set trace evisc tuple back to its default: (set-trace-evisc-tuple nil state) ; Set trace evisc tuple to restrict print-level to 3 and print-length to 4, ; while hiding the logical world and suitably printing stobjs even if trace$ ; option ``:hide nil'' is used. (Note: calling [47mtrace-evisceration-alist[0m ; directly requires removing this function as `untouchable', which requires a ; trust tag; see [remove-untouchable].) (set-trace-evisc-tuple (evisc-tuple 3 4 (trace-evisceration-alist state) nil) state) General Forms: (set-trace-evisc-tuple nil state) ; trace evisc-tuple set to standard value (set-trace-evisc-tuple t state) ; trace evisc-tuple set to hide the logical ; world and deal with stobjs even when ; trace$ option ``:hide nil'' is supplied (set-trace-evisc-tuple evisc-tuple state) ; tracing set to use indicated evisc-tuple See [trace$] for a discussion of ACL2 tracing. The [evisc-tuple] used by that trace utility is the one last installed by [47mset-trace-evisc-tuple[0m (or by [47m[set-evisc-tuple][0m for the trace-evisc-tuple) --- initially to the default of [47mnil[0m --- unless overridden by trace option [47m:evisc-tuple[0m. [31;1mRemark[0m. If you use value [47mt[0m, then ACL2 will ensure that the logical world and stobjs are kept up-to-date in the trace evisc-tuple.") (set-verify-guards-eagerness (guard) "The eagerness with which [guard] verification is tried. Example Forms: try guard verification? (set-verify-guards-eagerness 0) ; no, unless :verify-guards t (set-verify-guards-eagerness 1) ; yes if :guard, type :stobjs, or :df present (set-verify-guards-eagerness 2) ; yes, unless :verify-guards nil (set-verify-guards-eagerness 3) ; yes Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. General Form: (set-verify-guards-eagerness n) where [47mn[0m is a variable-free term that evaluates to [47m0[0m, [47m1[0m, [47m2[0m, or [47m3[0m. This macro is essentially equivalent to (table acl2-defaults-table :verify-guards-eagerness n) and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. However, unlike the above simple call of the [47m[table][0m event function (see [table]), no output results from a [47mset-verify-guards-eagerness[0m event. [47mSet-verify-guards-eagerness[0m may be thought of as an event that merely sets a flag to [47m0[0m, [47m1[0m, [47m2[0m, or [47m3[0m. The flag is used by certain [47m[defun][0m [events] to determine whether [guard] verification is tried. The flag is irrelevant to those [47m[defun][0m [events] in [47m:[0m[47m[program][0m mode. It is also irrelevant to those [47m[defun][0m [events] in which an explicit [47m:[0m[47m[verify-guards][0m setting is provided among the [47m[xargs][0m, except when the flag is [47m3[0m. In the [47m:[0m[47m[program][0m mode case, [guard] verification is not done because it can only be done when logical functions are being defined. Otherwise, unless the flag is [47m3[0m, the explicit [47m:[0m[47m[verify-guards][0m setting determines whether [guard] verification is tried. So consider a [47m:[0m[47m[logic][0m mode [47m[defun][0m in which no [47m:[0m[47m[verify-guards][0m setting is provided. Is [guard] verification tried? The answer depends on the eagerness setting as follows. If the eagerness is [47m0[0m, [guard] verification is not tried. If the eagerness is [47m1[0m, it is tried if and only if a guard is explicitly specified in the [47m[defun][0m, in the following sense: there is an [47mxargs[0m keyword [47m:guard[0m, [47m:stobjs[0m, or [47m:dfs[0m, or there is a [47m[type][0m declaration. If the eagerness is [47m2[0m or [47m3[0m, [guard] verification is tried. The above remarks apply to [47m[verify-termination][0m [events], according to whether guards are explicitly specified in the existing, corresponding [47m:[0m[47m[program][0m mode definitions. The default behavior of the system is as though the [47m:verify-guards-eagerness[0m is [47m1[0m. The current behavior can be ascertained by evaluating the form [47m(default-verify-guards-eagerness (w state))[0m.") (set-warnings-as-errors (warnings errors output-controls) "Changing [warnings] to hard [errors] (and vice-versa) It is common for ACL2 users not to notice warnings. That problem can be avoided by using the utility [47mset-warnings-as-errors[0m to convert warnings to errors. We start below with a general specification, followed by example forms, a detailed specification, and finally an extended example. General Form The general form is (set-warnings-as-errors flg types state) where [47mflg[0m is [47mt[0m, [47m:always[0m, or [47mnil[0m and [47mtypes[0m is either [47m:all[0m or a list of strings. The effect is to turn certain [warnings] into hard [errors], aborting the computation in progress. Note that [47mset-warnings-as-errors[0m is a function, so all arguments are evaluated. Details are described in the section below entitled ``Detailed Specification''. Example Forms ; When a [Subsume] or [Use] warning is to be printed, cause a hard error ; instead with a similar message. (set-warnings-as-errors t '("Subsume" "Use") state) ; As above, but cause a hard error even if the warning is not to be printed, ; i.e., even if by default it would be suppressed as a warning because of ; prior use of set-inhibit-output-lst or set-inhibit-warnings. (set-warnings-as-errors :always '("Subsume" "Use") state) ; Restore the treatment of [Use] warnings as warnings. (set-warnings-as-errors nil '("Use") state) ; Treat a warning as a hard error, but only if the warning is to be printed ; (hence not suppressed by set-inhibit-output-lst or set-inhibit-warnings). (set-warnings-as-errors t :all state) ; Treat a warning as a hard error, whether the warning is printed or not. (set-warnings-as-errors :always :all state) ; Restore the default behavior, treating warnings as warnings, not errors. (set-warnings-as-errors nil :all state) Detailed Specification * No warning whose type specified by constant [47m*uninhibited-warning-summaries*[0m is converted to an error. Those types are the ones that belong, with a case-insensitive check, to the list [47m("Uncertified" "Provisionally certified" "Skip-proofs" "Defaxioms" "Ttags" "Compiled file" "User-stobjs-modified")[0m. This exception overrides all discussion below. * The behavior of [warnings] is affected for every warning type specified by the [47mtypes[0m argument. When its value is [47m:all[0m, then all warnings are affected. Otherwise the value of [47mtypes[0m is a list of warning types (see [set-inhibit-warnings]): a true list of strings, each treated as case-insensitive. Note that when the value is not [47m:all[0m, the existing behavior for warning types is only changed for those in the value of [47mtypes[0m. * When [47mflg[0m is [47m:always[0m, then every warning specified by [47mtypes[0m is converted to a hard error, which aborts the evaluation in progress. This happens even if the warning is suppressed (by [47m[set-inhibit-output-lst][0m or [47m[set-inhibit-warnings][0m). * When [47mflg[0m is [47mt[0m, then when a warning specified by [47mtypes[0m is to be printed, it is converted to a hard error, which aborts the evaluation in progress. There is no error, however, if the warning is suppressed. * When [47mflg[0m is [47mnil[0m, then every warning specified by [47mtypes[0m is treated as a warning even if it had previously been treated as an error. * When a warning of a given type (possibly [47mnil[0m type) is converted to a hard error as specified above, then whether that error is printed is controlled by the usual mechanism for suppressing error messages; see [set-inhibit-er]. Note that the error will still be signaled regardless of whether the error message is thus suppressed. * Previous evaluations of calls of [47mset-warnings-as-errors[0m are ignored during [47m[certify-book][0m and [47m[include-book][0m. The handling of warnings as errors is restored at the end of these operations to what it was at the beginning. Extended Example ACL2 often prints [warnings], often with a message that includes a warning type. Here is a contrived example. (defthm foo t :hints (("Goal" :use car-cons)) :rule-classes nil) ACL2 Warning [Use] in ( DEFTHM FOO ...): It is unusual to :USE the formula of an enabled :REWRITE or :DEFINITION rule, so you may want to consider disabling (:REWRITE CAR-CONS) in the hint provided for Goal. See :DOC using-enabled-rules. In the example above, the warning type is the string, [47m"Use'[0m which is treated as case-insensitive; see [set-inhibit-warnings]. But maybe we prefer that every such warning be converted to an error; after all, as the warning suggests, we might want to disable the used rule first. It's easy to miss a warning but not an error, so we might do the following. (set-warnings-as-errors t '("use") state) That modifies ACL2 behavior such that instead of the warning above, we get the following error (after using [47m:u[0m to undo the effects of the [47mdefthm[0m event above). HARD ACL2 ERROR [Use] in ( DEFTHM FOO ...): It is unusual to :USE the formula of an enabled :REWRITE or :DEFINITION rule, so you may want to consider disabling (:REWRITE CAR-CONS) in the hint provided for Goal. See :DOC using-enabled-rules. Note that this is a ``hard'' error: it aborts the computation in progress. Suppose however that we turn off the warning by evaluating either of the following two forms. (set-inhibit-output-lst '(warning proof-tree)) ; OR (set-inhibit-warnings "use") After evaluating either (or both) of these forms, the [47mdefthm[0m form above completes with no warnings or errors. That's because there was no warning to print, and the [47mflg[0m value of [47mt[0m only has an effect for warnings that are printed. If we want errors to occur even for warnings whose printing is suppressed, we should use the [47mflg[0m value, [47m:always[0m. (set-warnings-as-errors :always '("use") state) ; OR (set-warnings-as-errors :always :all state)") (set-waterfall-parallelism (parallelism) "For ACL2(p): configuring the parallel execution of the waterfall This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. General Forms: (set-waterfall-parallelism nil) ; never parallelize (serial execution) (set-waterfall-parallelism :full) ; always parallelize (set-waterfall-parallelism :top-level) ; parallelize top-level subgoals (set-waterfall-parallelism ; parallelize if sufficient resources :resource-based) ; (recommended setting) (set-waterfall-parallelism t) ; alias for :resource-based (set-waterfall-parallelism ; parallelize if sufficient resources :resource-and-timing-based ; and suggested by prior attempts (set-waterfall-parallelism ; never parallelize but use parallel :pseudo-parallel) ; code base (a debug mode) [47mSet-waterfall-parallelism[0m evaluates its argument, which specifies the enabling or disabling of the [parallel] execution of ACL2's main proof process, the waterfall. It also sets [state] global [47mwaterfall-printing[0m to an appropriate value. See [set-waterfall-printing]. Note that not all ACL2 features are supported when waterfall-parallelism is set to non-[47mnil[0m (see [unsupported-waterfall-parallelism-features]). A value of [47mt[0m is treated the same as a value of [47m:resource-based[0m and is provided for user convenience. [47m:Resource-based[0m waterfall parallelism typically achieves the best performance in ACL2(p), while maintaining system stability, so [47m:resource-based[0m (or equivalently, [47mt[0m) is the recommended value. A value of [47mnil[0m indicates that ACL2(p) should never prove subgoals in parallel. A value of [47m:full[0m indicates that ACL2(p) should always prove independent subgoals in parallel. A value of [47m:top-level[0m indicates that ACL2(p) should prove each of the top-level subgoals in parallel but otherwise prove subgoals in a serial manner. This mode is useful when the user knows that there are enough top-level subgoals, many of which take a non-trivial amount of time to be proved, such that proving them in parallel will result in a useful reduction in overall proof time. A value of [47m:resource-based[0m (or equivalently, [47mt[0m) indicates that ACL2(p) should use its built-in heuristics to determine whether CPU core resources are available for parallel execution. Note that ACL2(p) does not hook into the operating system to determine the workload on the machine. ACL2(p) works off the assumption that it is the only process using significant CPU resources, and it optimizes the amount of parallelism based on the number of CPU cores in the system. (Note that ACL2(p) knows how to obtain the number of CPU cores from the operating system in CCL, but that, in SBCL and in Lispworks, a constant is used instead). During the first proof attempt of a given conjecture, a value of [47m:resource-and-timing-based[0m results in the same behavior as with [47m:resource-based[0m. However, on subsequent proof attempts, the time it took to prove each subgoal will be considered when deciding whether to parallelize execution. If a particular theorem's proof is already achieving satisfactory speedup via [47m:resource-based[0m parallelism, there is no reason to try this setting. However, if the user wishes to experiment, the [47m:resource-and-timing-based[0m setting may improve performance. Note that since the initial run does not have the subgoal proof times available, this mode will never be better than the [47m:resource-based[0m setting for non-interactive theorem proving. A value of [47m:pseudo-parallel[0m results in using the parallel waterfall code, but with serial execution. This setting is useful for debugging the code base that supports parallel execution of the waterfall. For example, you may wish to use this mode if you are an ``ACL2 Hacker'' who would like to see comprehensible output from tracing (see [trace$]) the [47m@par[0m versions of the waterfall functions. Since [memoization] is not supported when waterfall parallelism is enabled (see [unsupported-waterfall-parallelism-features]), then when [47mset-waterfall-parallelism[0m is called with a non-[47mnil[0m value, all memoized functions are unmemoized. When [47mset-waterfall-parallelism[0m is again called with a [47mnil[0m value, those memoization settings are restored. [47mSet-waterfall-parallelism[0m is an embedded event form. However, a call of this macro will not affect waterfall-parallelism when including a certified book that contains that call. For such an effect, you may use the following [47m[make-event][0m form; also see [non-parallel-book]. (make-event (er-progn (set-waterfall-parallelism :full) (value '(value-triple nil))) :check-expansion t) To enable waterfall parallelism for book certification using ACL2(p), see [waterfall-parallelism-for-book-certification].") (set-waterfall-parallelism-hacks-enabled (parallelism) "For ACL2(p): enable waterfall-parallelism hacks This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. General Forms: (set-waterfall-parallelism-hacks-enabled t) (set-waterfall-parallelism-hacks-enabled nil) Some features (e.g., [override-hints] and [clause-processor]s) of serial ACL2 are by default not available in ACL2(p) with waterfall parallelism enabled, because they offer a mechanism to modify [state] that is unsound. To allow or (once again) disallow the use the these features in ACL2(p), call [47mset-waterfall-parallelism-hacks-enabled[0m with argument [47mt[0m or [47mnil[0m, respectively. [47mSet-waterfall-parallelism-hacks-enabled[0m requires the use of a trust tag (see [defttag]). One can call [47m[set-waterfall-parallelism-hacks-enabled!][0m instead, which will automatically install a trust tag named [47m:waterfall-parallelism-hacks[0m. See [error-triples-and-parallelism] for further related discussion.") (set-waterfall-parallelism-hacks-enabled! (parallelism) "For ACL2(p): enabling waterfall parallelism hacks See [set-waterfall-parallelism-hacks-enabled].") (set-waterfall-printing (parallelism) "For ACL2(p): configuring the printing that occurs within the parallelized waterfall This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. General Forms: (set-waterfall-printing :full) ; print everything (set-waterfall-printing :limited) ; print a subset that's thought to be useful (set-waterfall-printing :very-limited) ; print an even smaller subset [47mSet-waterfall-printing[0m evaluates its argument, which indicates how much printing should occur when executing ACL2 with the parallelized version of the waterfall. It only affects the printing that occurs when parallelism mode is enabled for the waterfall (see [set-waterfall-parallelism]). A value of [47m:full[0m is intended to print the same output as in serial mode. This output will be interleaved unless the waterfall-parallelism mode is one of [47mnil[0m or [47m:pseudo-parallel[0m. A value of [47m:limited[0m omits most of the output that occurs in the serial version of the waterfall. Instead, the proof attempt prints key checkpoints (see [ACL2p-key-checkpoints]). The value of [47m:limited[0m also prints messages that indicate which subgoal is currently being proved, along with the wall-clock time elapsed since the theorem began its proof; and if state global [47m'waterfall-printing-when-finished[0m has a non-[47mnil[0m value, then such a message will also be printed at the completion of each subgoal. The function [47mprint-clause-id-okp[0m may receive an attachment to limit such printing; see [set-print-clause-ids]. Naturally, these subgoal numbers can appear out of order, because the subgoals can be proved in parallel. A value of [47m:very-limited[0m is treated the same as [47m:limited[0m, except that instead of printing subgoal numbers, the proof attempt prints a period (`[47m.[0m') each time it starts a new subgoal. Note that this form cannot be used at the top level of a book, or of a [47m[progn][0m or [47m[encapsulate][0m event. Here is a workaround for use in such contexts; of course, you may replace [47m:very-limited[0m with any other legal argument for [47mset-waterfall-printing[0m. (make-event (er-progn (set-waterfall-printing :very-limited) (value '(value-triple nil)))) (For more about event contexts and the use of [47mmake-event[0m, see [make-event], in particular the section ``Restriction to Event Contexts.'') The following form has the effect described above, except that it will affect waterfall-printing even when including a certified book that contains it. (make-event (er-progn (set-waterfall-printing :very-limited) (value '(value-triple nil))) :check-expansion t) Note that [47mset-waterfall-printing[0m is automatically called by [47m[set-waterfall-parallelism][0m. To enable the printing of information when a subgoal is finished, assign a non-[47mnil[0m value to global [47mwaterfall-printing-when-finished[0m. This can be accomplished by entering the following at the top level: (f-put-global 'waterfall-printing-when-finished t state)") (set-well-founded-relation (defun) "Set the default well-founded relation Examples: (set-well-founded-relation lex2) provided [47mlex2[0m has been proved to be a well-founded relation (see [well-founded-relation-rule]). Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. General Form: (set-well-founded-relation rel) where [47mrel[0m has been proved to be a well-founded relation on objects satisfying some predicate, [47mmp[0m; see [well-founded-relation-rule]. This macro is equivalent to [47m(table acl2-defaults-table :well-founded-relation 'rel)[0m, and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in which it occurs; see [ACL2-defaults-table]. This event sets the default well-founded relation to be that imposed on [47mmp[0m-measures by the relation [47mrel[0m. Subsequently, if a recursively defined function is submitted to [47m[defun][0m with no explicitly given [47m:well-founded-relation[0m argument, [47m[defun][0m uses the default relation, [47mrel[0m, and the associated domain predicate [47mmp[0m used in its well-foundedness theorem. That is, the termination conditions generated will require proving that the measure used by the [47m[defun][0m is an [47mmp[0m-measure and that in every recursive call the measure of the arguments decreases according to [47mrel[0m.") (set-wormhole-data (wormhole) "Sets the wormhole data object in a wormhole status object General Form: (set-wormhole-data whs data) See [wormhole]. [47mWhs[0m should be a well-formed wormhole status; [47mdata[0m is arbitrary. This function returns a new status with the same entry code as [47mwhs[0m but with the new [47mdata[0m. This function does not affect state or a wormhole's persistent-whs or ephemeral-whs. It just returns a (possibly) new status object suitable as the value of the [47mlambda[0m expressions in [47m[wormhole-eval][0m and [47m[wormhole][0m.") (set-wormhole-entry-code (wormhole) "Sets the wormhole entry code in a wormhole status object General Form: (set-wormhole-entry-code whs code) See [wormhole]. [47mWhs[0m should be a well-formed wormhole status and [47mcode[0m should be [47m:ENTER[0m or [47m:SKIP[0m. This function returns a new status with the specified entry code but the same data as [47mwhs[0m. This function does not affect state or a wormhole's persistent-whs or ephemeral-whs. It just returns a (possibly) new status object suitable as the value of the [47mlambda[0m expressions in [47m[wormhole-eval][0m and [47m[wormhole][0m.") (set-write-acl2x (books-reference) "Cause [47m[certify-book][0m to write out a [47m.acl2x[0m file Example Forms: (set-write-acl2x nil state) (set-write-acl2x t state) (set-write-acl2x '(nil) state) ; same as just above, but allow inclusion of ; uncertified books during certify-book (set-write-acl2x '(t) state) (set-write-acl2x '(include-book-with-locals) state) General Form: (set-write-acl2x val state) where [47mval[0m evaluates to [47mt[0m, [47mnil[0m, or a one-element list whose element is a legal value for the global [47m'ld-skip-proofsp[0m; see [ld-skip-proofsp]. The value returned is an error triple, which in the non-error case is [47m(mv nil v state)[0m, where [47mv[0m is the value of [47mval[0m and [47mstate[0m is the result of updating the input [state] by assigning state global [47m'write-acl2x[0m the value [47mv[0m. The command [47m(set-write-acl2x val state)[0m assigns the value of [47mval[0m to the [state] global variable [47m'write-acl2x[0m, affecting whether or not [47m[certify-book][0m writes out a file with extension [47macl2x[0m, called a ``[47m.acl2x[0m file'' and pronounced ``dot-acl2x file''. Such a file is read or written by [47m[certify-book][0m when it is supplied with keyword argument [47m:acl2x t[0m. By default, such a call of [47mcertify-book[0m reads a [47m.acl2x[0m file; but if the value of state global variable [47m'write-acl2x[0m is not [47mnil[0m, then [47mcertify-book[0m writes a [47m.acl2x[0m file (in which case it is illegal to specify a non-[47mnil[0m value for [47m[certify-book][0m keyword argument [47m:pcert[0m). Consider for example [47m(certify-book "foo" 0 nil :acl2x t)[0m. By default, this command reads file [47mfoo.acl2x[0m, which supplies replacements for some forms in [47mfoo.lisp[0m, as described later below. But if the value of state global [47m'write-acl2x[0m is not [47mnil[0m, then instead, this [47mcertify-book[0m command writes such a file [47mfoo.acl2x[0m. Before we discuss the function of [47m.acl2x[0m files, we first explain more about how a non-[47mnil[0m value of [state] global [47m'write-acl2x[0m affects the behavior of a command [47m(certify-book ... :acl2x t ...)[0m. A significant effect on the behavior is that after processing events in the given book, ACL2 writes out a [47m.acl2x[0m file and then returns, skipping the other subsequent actions typically performed by [47m[certify-book][0m: a [local-incompatibility] check, writing of a [certificate] file, and possibly [compilation]. Another effect is that proofs may be skipped when processing [events] assuming that the [47mcertify-book[0m command does not explicitly specify [47m:skip-proofs-okp nil[0m, as we now explain. A non-[47mnil[0m value of [47m'write-acl2x[0m should either be [47mt[0m or a one-element list [47m(x)[0m, where [47mx[0m is a legal value for the [state] global [47m'ld-skip-proofsp[0m (see [ld-skip-proofsp]). In both cases, [47mcertify-book[0m will process [events] to write out a [47m.acl2x[0m file as described above. But in the latter (list) case, event processing will take place according to the value of [47mx[0m: in particular, proofs will be skipped when [47mx[0m is not [47mnil[0m, and if moreover [47mx[0m is the symbol [47minclude-book-with-locals[0m, then only one pass will be made through each [47m[encapsulate][0m form. A third effect of a non-[47mnil[0m value of [47m'write-acl2x[0m, which is restricted to the list case, is that [include-book] events encountered during event processing are allowed to succeed on uncertified books, something that is prohibited during most calls of [47m[certify-book][0m. When [47m[certify-book][0m is used to write out a [47m.acl2x[0m file, there is typically a subsequent run of [47m[certify-book][0m that reads that file. Consider how this can work with a book [47mfoo.lisp[0m. In the first call of [47mcertify-book[0m, a file [47mfoo.acl2x[0m is written that contains all [47m[make-event][0m expansions, but [47mfoo.cert[0m is not written. In the second call of [47mcertify-book[0m, no [47m[make-event][0m expansion typically takes place, because [47mfoo.acl2x[0m supplies the expansions. The command [47m(set-write-acl2x t state)[0m should be evaluated before the first certification (though another legal non-[47mnil[0m value may be used in place of [47mt[0m), setting the value of [47m[state][0m global [47m'write-acl2x[0m to [47mt[0m, to enable writing of [47mfoo.acl2x[0m; and the command [47m(set-write-acl2x nil state)[0m may be evaluated before the second run (though this is not necessary in a fresh ACL2 session) in order to complete the certification (writing out [47mfoo.cert[0m) using [47mfoo.acl2x[0m to supply the [47m[make-event][0m expansions. When [47m[Certify-book][0m is supplied with keyword argument [47m:acl2x t[0m it will read or write the book's [47m.acl2x[0m file; when supplied with [47m:acl2x nil[0m, it will not read or write that [47m.acl2x[0m file. The value of [47m:acl2x[0m is [47mnil[0m by default. The interaction of [47m[certify-book][0m with the corresponding [47m.acl2x[0m file is as follows. o If [47m:acl2x[0m is [47mt[0m, then: - If [47mset-write-acl2x[0m has been (most recently) called with a value of [47mt[0m for its first argument,then ACL2 writes the corresponding [47m.acl2x[0m file. - If [47mset-write-acl2x[0m has been (most recently) called with a value of [47mnil[0m for its first argument, or not called at all, then ACL2 insists on a corresponding [47m.acl2x[0m file that is at least as recent as the corresponding [47m.lisp[0m file, causing an error otherwise. o If [47m:acl2x[0m is [47mnil[0m,then: - If [47mset-write-acl2x[0m has been (most recently) called with a value [47mt[0m for its first argument, or if argument [47m:ttagsx[0m is supplied, then an error occurs. - If the [47m.acl2x[0m file exists, then regardless of whether or how [47mset-write-acl2x[0m has been called, ACL2 ignores the [47m.acl2x[0m file but issues a warning about it. Suppose you use the two-runs approach: first write a [47m.acl2x[0m file, then certify using (reading) that [47m.acl2x[0m file. Then with scripts such as makefiles, then you may wish to provide a single [47m[certify-book][0m command to use for both runs. For that purpose, [47m[certify-book][0m supports the keyword argument [47m:ttagsx[0m. If this argument is supplied and [47mwrite-acl2x[0m is true, then this argument is treated as the [47m:ttags[0m argument, overriding a [47m:ttags[0m argument if present. That is, for the two runs, [47m:ttagsx[0m may be used to specify the trust tags used in the first certification while [47m:ttags[0m specifies the trust tags, if any (else [47m:ttags[0m may be omitted), used in the second certification. Note: If the argument [47m:ttagsx[0m is not supplied, then its value defaults to the (explicit or default) value of the [47m:ttags[0m argument. The built-in ACL2 Makefile support automatically generates suitable dependencies if you create a [47m.acl2[0m file with a [47m[certify-book][0m call matching the following regular expression, case-independent: (certify-book[^;]*:acl2x t For an example [47m.acl2[0m file with a [47mcertify-book[0m call matching the above pattern, see community books file [47mbooks/make-event/double-cert-test-1.acl2[0m. Note that [47m[include-book][0m is generally not affected by [47mset-write-acl2x[0m, other than through the indirect effect on [47m[certify-book][0m. More precisely: All expansions are stored in the [certificate] file, so when [47m[include-book][0m is applied to a certified book, the [47m.acl2x[0m file is not consulted. An example of how to put this all together may be found in community book [47mbooks/make-event/double-cert-test-1.lisp[0m. There, we see the following form. (make-event (progn (defttag :my-ttag) (progn! (let ((val (sys-call "pwd" nil))) (value (list 'defun 'foo () val)))))) Imagine that in place of the binding computed using [47m[sys-call][0m, which by the way requires a trust tag, is some computation of your choice (such as reading forms from a file) that is used to construct your own event, in place of the [47m[defun][0m event constructed above. The [47mMakefile[0m in that directory contains the following added dependency, so that file [47mdouble-cert-test-1.acl2x[0m will be created: double-cert-test-1.cert: double-cert-test-1.acl2x There is also the file [47mdouble-cert-test-1.acl2[0m in that directory, which contains a single form as follows. (certify-book "double-cert-test-1" ? t :ttagsx :all :ttags nil) Thus, a call of `make' first creates file [47mdouble-cert-test-1.acl2x[0m, which uses the above [47m:ttagsx[0m argument in order to support the use of [47m[defttag][0m during [47m[make-event][0m expansion. Then, `make' goes on to cause a second certification in which no trust tags are involved. As a result, the parent book [47mdouble-cert-test.lisp[0m is ultimately certified without requiring any trust tags. The discussion above is probably sufficient for most users of the two-run approach it describes. We conclude with further details for those who want more information. Those who wish to see a yet lower-level explanation of how all this works are invited to read the comment in the ACL2 source code entitled ``Essay on .acl2x Files (Double Certification). Consider the [47m.acl2x[0m file produced by the first run as described above. It contains a single expression, which is an association list whose keys are all positive integers, which occur in increasing order. When the [47m.acl2x[0m file is present and at least as recent as the corresponding [47m.lisp[0m file, then for a subsequent [47m[certify-book][0m with argument [47m:acl2x t[0m and the (default) value of [47mnil[0m for [state] global [47m'write-acl2x[0m, that association list will be applied to the top-level events in the book, as follows. Suppose the entry [47m(n . ev)[0m belongs to the association list in the [47m.acl2x[0m file. Then [47mn[0m is a positive integer, and the [47mn[0mth top-level event in the book --- where the [47m0[0mth event is the initial [47m[in-package][0m form --- will be replaced by [47mev[0m. In practice, [47mev[0m is the [47m[make-event][0m expansion created during certification for the [47mnth[0m top-level event in the book; and this will always be the case if the [47m.acl2x[0m file is created by [47m[certify-book][0m after execution of the form [47m(set-write-acl2x t state)[0m. However, you are welcome to associate indices manually with any [events] you wish into the alist stored in the [47m.acl2x[0m file. Note: Also see the community book [47mmake-event/acl2x-help.lisp[0m for a useful utility that can be used to skip proofs during the writing of [47m.acl2x[0m files.") (setenv$ (programming-with-state acl2-built-ins) "Set an environment variable [47m(Setenv$ str val)[0m, where [47mstr[0m and [47mval[0m are strings, sets the environment variable [47mstr[0m to have value [47mval[0m, for subsequent read by [47mgetenv$[0m (see [getenv$]), and returns [47mnil[0m. Or, if this operation is not implemented for the host Common Lisp, an error will occur. Example: (setenv$ "FOO" "BAR") It may be surprising that [47msetenv$[0m returns [47mnil[0m; indeed, it neither takes nor returns the ACL2 [state]. The reason is that [47m[getenv$][0m takes responsibility for trafficking in [state]; it is defined in the logic using the function [47m[read-ACL2-oracle][0m, which (again, in the logic) does modify state, by popping an entry from its acl2-oracle field. See [getenv$]. As suggested above, a call of [47m[getenv$][0m takes into account the most recent call of [47msetenv$[0m on the same environment variable. It may also be the case that [47msetenv$[0m modifies the environment of the underlying process; for example, we think this is probably the case for most invocations of ACL2 built on a host Lisp that is CCL, SBCL, or CMUCL, as well as others perhaps. If you want to rely on such behavior, however, we advise you to look at source code. [31;1mFunction: [0m<setenv$> (defun setenv$ (str val) (declare (xargs :guard (and (stringp str) (stringp val)))) (declare (ignore str val)) nil)") (seventh (nth acl2-built-ins) "Seventh member of the list See any Common Lisp documentation for details.") (sharp-bang-reader (reader packages) "Package prefix that is not restricted to symbols Examples: ACL2 !>(defpkg "FOO" nil) Summary Form: ( DEFPKG "FOO" ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) "FOO" ACL2 !>'#!foo(a b) (FOO::A FOO::B) ACL2 !>'#!foo(a #!acl2 b) (FOO::A B) ACL2 !>'#!foo(#!acl2 a b) (A FOO::B) ACL2 !>'#!foo(#!"ACL2" a b) (A FOO::B) ACL2 !> The ACL2 reader supports the syntax [47m#!pkg-name expr[0m where [47mpkg-name[0m is a string or symbol that names a package known to ACL2. As illustrated above, this syntax nests as one might expect. In the special case that [47mexpr[0m is a symbol, [47m#!pkg-name expr[0m is equivalent to [47mpkg-name::expr[0m.") (sharp-d-reader (reader numbers) "Read a rational number as a representable rational (see [df]) When the ACL2 reader encounters the two-character sequence [47m#d[0m, it invokes the Lisp reader to obtain the next token, which should designate a Lisp double-precision floating-point number. (Technically, the Lisp value of variable [47m*read-default-float-format*[0m is the symbol [47mDOUBLE-FLOAT[0m when the floating-point token is read.) The reader then returns the rational number represented by that floating-point token. The discussion above is complete, but it may make more sense to those familiar with so-called [3mdf[0m values in ACL2. See [df]. See also [sharp-f-reader], which reads input starting with [47m#f[0m. As with [47m#d[0m, one reads floating-point notation and returns the corresponding rational number. However, while [47m#d[0m reads the next token as a Lisp floating-point number, [47m#f[0m is specific to ACL2 and follows precise documented rules that, unlike [47m#d[0m, allow use of underscores ([47m_[0m) and hexadecimal notation.") (sharp-dot-reader (reader defconst) "Read-time evaluation of constants Example: ACL2 !>(defconst *a* '(a b c)) Summary Form: ( DEFCONST *A* ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) *A* ACL2 !>(quote (1 2 #.*a* 3 4)) (1 2 (A B C) 3 4) ACL2 !> The ACL2 reader supports the syntax [47m#.*a*[0m where [47m*a*[0m was defined by [47m[defconst][0m. In this case, the reader treats [47m#.*a*[0m as though it were reading the value of [47m*a*[0m. This feature can be useful in conjunction with the use of [47m[evisc-table][0m to abbreviate large constants, so that the abbreviation can be read back in; see [evisc-table]. Remarks. (1) The ACL2 reader only supports `[47m#.[0m' as described above, unlike Common Lisp. Older versions (preceding 3.5) used `[47m#.[0m' to abort, but that functionality is now carried out by [47m(a!)[0m; see [a!]. For a related feature that only pops up one level, see [p!]. (2) If you call [47m[certify-book][0m on a book that contains a form `[47m#.*foo*[0m', the [47m*foo*[0m must already be defined in the [world] in which you issue the [47mcertify-book[0m command. The reason is that [47mcertify-book[0m reads the entire book before evaluating its forms.") (sharp-f-reader (reader numbers) "Read a rational number in floating-point syntax This topic is about reading expressions starting with [47m#f[0m. See also [sharp-d-reader], which reads input starting with [47m#d[0m. Both read a form of floating-point notation as a rational number. However, while [47m#d[0m reads the next token as a Lisp floating-point number, [47m#f[0m is specific to ACL2 and follows rules documented explicitly below, including the use of underscores ([47m_[0m) and hexadecimal notation. Examples: ACL2 !>#f567 567 ACL2 !>#f_5_6__7_ ; underscores are allowed, and discarded 567 ACL2 !> ACL2 !>#f-567 -567 ACL2 !>#f+567 567 ACL2 !>#f5.67 567/100 ACL2 !>#f-5.67 -567/100 ACL2 !>#f5.67e3 5670 ACL2 !>#f-5.67e3 -5670 ACL2 !>#f-5.67e-3 -567/100000 ACL2 !>#f.67e2 67 ACL2 !>#f-.67e2 -67 ACL2 !>#f-.67e+4 -6700 ACL2 !>#f-0.67e+4 -6700 ACL2 !>#fx101 257 ACL2 !>#fx10.1 257/16 ACL2 !>#fx10.1p3 257/2 ACL2 !>#fx10.1p-4 257/256 ACL2 !>#fx-10.1p-4 -257/256 ACL2 !>#fx.1p4 1 ACL2 !>#fx.1p+8 16 ACL2 !>#fx.1p-2 1/64 ACL2 !>#fx-0_4p1_0 -4096 ACL2 !> As illustrated above, we support two forms of this reader: [47m#f[0m, indicating base 10 digits, and [47m#fx[0m, indicating base 16 digits. Let {i} be notation representing a sequence of digits and (optionally) underscore ([47m_[0m) characters, optionally preceded by a sign ([47m-[0m or [47m+[0m), that the ACL2 reader reads as the integer i after discarding underscore characters; similarly for {j} and {n}, except that an initial sign is illegal for {j}, and for {n} the digits are always base 10 (even in the case of [47m#fx[0m). Note that each such string is terminated at the first character from the input channel that is not a digit. For the [47m#f[0m case we have the following semantics. #f{i} => i #f{i}e{n} => i * 10^n #f{i}.{j} => i + (/ j 10^k) where k is the length of {j} #f{i}.{j}e{n} => (i + (/ j 10^k)) * 10^n where k is the length of {j} We have the following similar semantics for the [47m#fx[0m case, except that {i} and {j} are now read in base 16. Note that {n} is still read in base 10. #fx{i} => i #fx{i}p{n} => i * 2^n #fx{i}.{j} => i + (/ j 16^k) where k is the length of {j} #fx{i}.{j}p{n} => (i + (/ j 16^k)) * 2^n where k is the length of {j} We thank Dmitry Nadezhin for pointing us to the following page, which explains an analogous ``floating point literal'' syntax for C++: http://en.cppreference.com/w/cpp/language/floating_literal Note, however, that in ACL2 we do not support the use of single quote ([47m'[0m) as a separator, using underscore ([47m_[0m) instead, which is consistent with another reader macro, [47m#u[0m (see [sharp-u-reader]). Moreover, unlike the syntax described on the page above, the ACL2 [47m#f[0m reader allows an initial sign ([47m-[0m or [47m+[0m). To see why, note that in Lisp, the string [47m"-#"[0m starts a symbol, for example: ? '-#f23 |-#F23| ? Since the ACL2 reader is based on the Lisp reader, it would be awkward to provide support to read the string [47m"-#f23"[0m as a number, -23. Instead, ACL2 accepts a sign immediately after the initial [47m"#f"[0m or [47m"#fx"[0m: ACL2 !>#f-23 -23 ACL2 !>") (sharp-u-reader (reader numbers) "Allow underscore characters in numbers Example: ACL2 !>#ub1000_1000_1000_ 2184 ACL2 !>#b100010001000 2184 ACL2 !>#uo1_1 9 ACL2 !>#o11 9 ACL2 !>#u34_5 345 ACL2 !>#u345 345 ACL2 !>345 345 ACL2 !>#ux12_a 298 ACL2 !>#ux12a 298 ACL2 !>#u x12a 298 ACL2 !>#x12a 298 ACL2 !>#u123_456/7_919 123456/7919 ACL2 !> The ACL2 reader supports the use of [47m#ub[0m, [47m#uo[0m, and [47m#ux[0m where one would otherwise write [47m#b[0m, [47m#o[0m, and [47m#x[0m, respectively (for binary, octal, and hexadecimal numerals), but where underscore characters (`[47m_[0m') are allowed but ignored. Also supported is the prefix [47m#u[0m in front of a an expression that is a decimal numeral except that underscore characters are allowed but ignored. The precise specification of [47m#u[0m is as follows. The ACL2 reader reads one expression after the [47m#u[0m. If the result is a number, then that number is returned by the reader. Otherwise the result must be a symbol. Let [47mN[0m be the [47m[symbol-name][0m of the symbol; thus [47mN[0m is a string. If [47mN[0m begins with one of the characters `[47mB[0m', `[47mO[0m', or `[47mX[0m', then first obtain a string [47mS1[0m by prefixing [47mN[0m with the character, `[47m#[0m'; otherwise let [47mS1[0m be [47mN[0m. Next, remove all underscore characters `[47m_[0m' from [47mS1[0m, obtaining [47mS2[0m. The result is obtained by applying the ACL2 reader to [47mS2[0m; that result must be a number, or else an error occurs.") (show-accumulated-persistence (pointers) "See [accumulated-persistence].") (show-bdd (bdd) "Inspect failed BDD proof attempts Attempts to use BDDs (see [bdd]), using [47m:[0m[47m[bdd][0m [hints], can fail for various reasons. Sometimes it is useful to explore such failures. To do so, one may simply execute the form (show-bdd) inside the ACL2 loop. The system's response is generally self-explanatory. Perhaps you have already seen [47mshow-bdd[0m used in some examples (see [bdd-introduction] and see [if*]). Here we give some details about [47mshow-bdd[0m. [47m(Show-bdd)[0m prints the goal to which the BDD procedure was applied and reports the number of nodes created during the [bdd] computation, followed by additional information depending on whether or not the computation ran to completion or aborted (for reasons explained elsewhere; see [bdd-algorithm]). If the computation did abort, a backtrace is printed that should be useful in understanding where the problem lies. Otherwise, [47m(show-bdd)[0m prints out ``falsifying constraints.'' This list of pairs associates [term]s with values and suggests how to construct a binding list for the variables in the conjecture that will falsify the conjecture. It also prints out the [term] that is the result of simplifying the input [term]. In each of these cases, parts of the object may be hidden during printing, in order to avoid creating reams of uninteresting output. If so, the user will be queried about whether he wishes to see the entire object (alist or [term]), which may be quite large. The following responses are legal: [47m w[0m --- Walk around the object with a structure editor [47m y[0m --- Print the object in full [47m n[0m --- Do not print any more of the object [47mShow-bdd[0m actually has four optional arguments, probably rarely used. The general form is (show-bdd goal-name goal-ans falsifying-ans term-ans) where [47mgoal-name[0m is the name of the goal on which the [47m:[0m[47m[bdd][0m hint was used (or, [47mnil[0m if the system should find such a goal), [47mgoal-ans[0m is [47mnil[0m if there is to be a query and otherwise is the answer to be used (without a query) for whether to print the input goal in full ([47mt[0m for '[47my[0m', [47mnil[0m for '[47mn[0m', and [47m:w[0m for '[47mw[0m'), [47mfalsifying-ans[0m is the answer to be used in place of the query for whether to print the falsifying constraints in full, and [47mterm-ans[0m is the answer to be used in place of the query for whether to print the resulting [term] in full.") (show-bodies (definition) "Show the potential definition bodies Examples: (show-bodies foo) :show-bodies foo A definition made using [47m[defun][0m installs a so-called ``body'' of a function symbol, as do certain [47m:[0m[47m[definition][0m rules. Such bodies are used in a number of ways, including the application of [47m:expand[0m [hints]; see [definition], in particular the discussion of ``body'' there, and see [hints] for a discussion of the [47m:expand[0m hint. Also see [set-body] for how to change which of the available definitions (among the original definition and appropriate [47m:[0m[47m[definition][0m rules) is the one that provides the body. The [47mshow-bodies[0m command displays the available such bodies in an appropriate format, starting with the one that is currently used as the body. General Forms: (show-bodies function-symbol) :show-bodies function-symbol") (show-custom-keyword-hint-expansion (custom-keyword-hints) "Print out custom keyword hints when they are expanded Examples: (show-custom-keyword-hint-expansion t) (show-custom-keyword-hint-expansion nil) General Form: (show-custom-keyword-hint-expansion flg) If the value of [47mflg[0m is non-[47mnil[0m, then when custom keyword hints are expanded, the system prints the results of each expansion. This is sometimes useful for debugging custom keyword hints and, from time to time, may be useful in understanding how a custom hint affects some proof attempt. The default setting is [47mnil[0m. For an explanation of how custom keyword hints are processed, see [custom-keyword-hints].") (show-fc-criteria (forward-chaining-reports) "Print the forward-chaining tracking criteria Example: (show-fc-criteria) This function prints the list of triples being used to determine what is tracked during forward chaining. See [forward-chaining-reports] for details.") (signature (encapsulate) "How to specify the arity of a constrained function We start with a gentle introduction to signatures, where we pretend that there are no single-threaded objects (more on that below --- for now, if you don't know anything about single-threaded objects, that's fine!). Here are some simple examples of signatures. ((hd *) => *) ((pair * *) => *) ((foo * *) => (mv * * *)) The first of these says that [47mhd[0m is a function of one argument, while the other two say that [47mpair[0m and [47mfoo[0m are functions that each take two arguments. The first two say that [47mhd[0m and [47mpair[0m return a single value. The third says that [47mfoo[0m returns three values, much as the following definition returns three values: (defun bar (x y) (mv y x (cons x y))) Corresponding ``old style'' signatures are as follows. In each case, a function symbol is followed by a list of formal parameters and then either [47mt[0m, to denote a single value return, or [47m(mv t t t)[0m, to denote a multiple value return (in this case, returning three values). (hd (x) t) (pair (x y) t) (foo (x y) (mv t t t)) That concludes our gentle introduction. The documentation below is more general, for example covering single-threaded objects (see [stobj]), dfs (see [df]), and keyword values such as [47m:guard[0m. When reading what follows below, all you need to know about single-threaded objects (or ``stobjs'') that each has a unique symbolic name and that [47m[state][0m is the name of the only built-in single-threaded object. All other stobjs are introduced by the user via [47m[defstobj][0m or [47m[defabsstobj][0m. We also mention ``dfs'', which are ACL2 expressions that denote Lisp floating-point values; see [df]. An expression that is neither a stobj name nor a df is said to be ``ordinary''. Examples: ((hd *) => *) ((hd *) => * :formals (x) :guard (consp x)) ((printer * state) => (mv * * state)) ((mach * mach-state * state) => (mv * mach-state)) ((df-mult3 :df :df :df) => :df) General Form: ((fn ...) => *) ((fn ...) => s) ; where s is a stobj name ((fn ...) => :df) or ((fn ...) => (mv x1 x2 ... xn)) ; where each xi is *, a stobj, or :df or for part1 and part2 as above, (part1 => part2 :kwd1 val1 ... :kwdn valn) where [47mfn[0m is the constrained function symbol and the optional [47m:kwdi[0m and [47mvali[0m are as described below. ACL2 also supports an older style of signature, described below after we describe the preferred style. Signatures specify three syntactic aspects of a function symbol: (1) the ``arity'' or how many arguments the function takes, (2) the ``multiplicity'' or how many results it returns via [47mMV[0m, and (3) the arguments and results that are stobjs or dfs. A signature typically has the form [47m((fn x1 ... xn) => val)[0m. Such a signature has two parts, separated by the symbol ``=>''. The first part, [47m(fn x1 ... xn)[0m, is suggestive of a call of the constrained function. The number of ``arguments,'' [47mn[0m, indicates the arity of [47mfn[0m. Each [47mxi[0m must be a symbol. If a given [47mxi[0m is the symbol ``*'' then the corresponding argument must be ordinary. If a given [47mxi[0m is any other symbol, that symbol must be the name of a single-threaded object and the corresponding argument must be that object, or else that symbol must be [47m:df[0m and the corresponding argument must be a df (see [df]). No stobj name may occur twice among the [47mxi[0m. The second part, [47mval[0m, of a signature is suggestive of a term and indicates the ``shape'' of the output of [47mfn[0m. If [47mval[0m is a symbol then it must be either the symbol ``*'', the keyword [47m:df[0m, or the name of a single-threaded object. In either case, the multiplicity of [47mfn[0m is 1 and [47mval[0m indicates whether the result is ordinary, a df, or a stobj. Otherwise, [47mval[0m is of the form [47m(mv y1 ... yk)[0m, where [47mk[0m > 1. Each [47myi[0m must be either the symbol ``*'', the keyword [47m:df[0m, or the name of a stobj. Such a [47mval[0m indicates that [47mfn[0m has multiplicity [47mk[0m and the [47myi[0m indicate which results are ordinary, which are dfs, and which are stobjs. No stobj name may occur twice among the [47myi[0m, and a stobj name may appear in [47mval[0m only if appears among the [47mxi[0m. A signature may have the form [47m((fn x1 ... xn) => val . k)[0m, where [47mk[0m is a [47m[keyword-value-listp][0m, i.e., an alternating list of keywords and values starting with a keyword. In this case [47m((fn x1 ... xn) => val)[0m must be a legal signature as described above. The legal keywords in [47mk[0m are generally [47m:GUARD[0m and [47m:FORMALS[0m, but see remarks at the end of this topic regarding [47m:GLOBAL-STOBJS[0m and [47m:TRANSPARENT[0m and, for ACL2(r), [47m:CLASSICALP[0m. The value following [47m:FORMALS[0m is to be the list of formal parameters of [47mfn[0m, which must be consistent with the parameters specified in [47m(fn x1 ... xn)[0m: they must both specify the same arity (number of formal parameters) and the same [stobj] inputs. The value following [47m:GUARD[0m is a term that is to be the [guard] of [47mfn[0m. Note that this guard is never actually evaluated, and is not subject to the guard verification performed on functions introduced by [47m[defun][0m (see [verify-guards]). Said differently: this guard need not itself have a guard of [47mt[0m. Indeed, the guard is only used for attachments; see [defattach]. Note that if [47m:GUARD[0m is supplied, then [47m:FORMALS[0m must also be supplied as a list of distinct variables that includes all variables occurring free in the specified guard. One final observation about guards: if the [47m:GUARD[0m keyword is omitted, then the guard defaults to [47mT[0m. Before ACL2 supported user-declared single-threaded objects there was only one single-threaded object: ACL2's built-in notion of [47m[state][0m. The notion of signature supported then gave a special role to the symbol [47mstate[0m and all other symbols were considered to denote ordinary objects. ACL2 still supports the old form of signature, but it is limited to functions that operate on ordinary objects or ordinary objects and [47mstate[0m. Old Style General Form: (fn formals result . k) where [47mfn[0m is the constrained function symbol, [47mformals[0m is a suitable list of formal parameters for it, [47mk[0m is an optional [47m[keyword-value-listp][0m (see below), and [47mresult[0m is either a symbol denoting that the function returns one result or else [47mresult[0m is an [47m[mv][0m expression, [47m(mv s1 ... sn)[0m, where [47mn>1[0m, each [47msi[0m is a symbol, indicating that the function returns [47mn[0m results. At most one of the formals may be the symbol [47mSTATE[0m, indicating that the corresponding argument must be ACL2's built-in [47m[state][0m. If [47mstate[0m appears in [47mformals[0m then [47mstate[0m may appear once in [47mresult[0m. All ``variable symbols'' other than [47mstate[0m in old style signatures denote ordinary objects, regardless of whether the symbol has been defined to be a single-threaded object name! The optional [47mk[0m is as described above for newer-style signatures, except that the user is also allowed to declare which symbols (besides [47mstate[0m) are to be considered stobjs names or dfs. Thus [47m:STOBJS[0m and @9':DFS') are also legal keywords. The form (fn formals result ... :stobjs stobj-names :dfs df-names ...) specifies that [47mstobj-names[0m is either the name of a stobj or else is a list of such names; also, both [47mstobj-names[0m and [47mdf-names[0m are lists that must be contained in the [47mformals[0m list. Every name in [47mstobj-names[0m must have been previously defined as a stobj via [47m[defstobj][0m or [47m[defabsstobj][0m. As promised above, we conclude with a remark about additional keywords. The keyword [47m:GLOBAL-STOBJS[0m specifies the use of the macro, [47mwith-global-stobj[0m, in attachments (see [defattach]); see [47m[with-global-stobj][0m for explanation of this keyword. The keyword [47m:TRANSPARENT[0m specifies transparent functions; see [transparent-functions]. Finally, the keyword [47m:CLASSICALP[0m is legal for ACL2(r) only (see [real]). The value of this keyword must be [47mt[0m (the default) or [47mnil[0m, indicating respectively whether [47mfn[0m is classical or not.") (signed-byte-p (numbers acl2-built-ins) "Recognizer for signed integers that fit in a specified bit width [47m(Signed-byte-p bits x)[0m is [47mT[0m when [47mbits[0m is a positive integer and [47mx[0m is a signed integer whose 2's complement representation fits in a bit-width of [47mbits[0m, i.e., [47m-2^(bits-1) <= x < 2^(bits-1)[0m. Note that a [type-spec] of [47m(signed-byte i)[0m for a variable [47mx[0m in a function's [47m[declare][0m form translates to a [guard] condition of [47m(signed-byte-p i x)[0m. The [guard] for [47msigned-byte-p[0m is [47mT[0m. [31;1mFunction: [0m<signed-byte-p> (defun signed-byte-p (bits x) (declare (xargs :guard t)) (and (integerp bits) (< 0 bits) (let ((y (expt 2 (1- bits)))) (integer-range-p (- y) y x))))") (signum (numbers acl2-built-ins) "Indicator for positive, negative, or zero [47m(Signum x)[0m is [47m0[0m if [47mx[0m is [47m0[0m, [47m-1[0m if [47mx[0m is negative, and is [47m1[0m otherwise. The [guard] for [47msignum[0m requires its argument to be rational ([real], in ACL2(r)) number. [47mSignum[0m is a Common Lisp function. See any Common Lisp documentation for more information. From ``Common Lisp the Language'' page 206, we see a definition of [47msignum[0m in terms of [47m[abs][0m. As explained elsewhere (see [abs]), the [guard] for [47m[abs][0m requires its argument to be a rational ([real], in ACL2(r)) number; hence, we make the same restriction for [47msignum[0m. [31;1mFunction: [0m<signum> (defun signum (x) (declare (xargs :guard (real/rationalp x))) (if (zerop x) 0 (if (minusp x) -1 1)))") (simple (rewrite definition) "[47m:[0m[47m[definition][0m and [47m:[0m[47m[rewrite][0m rules used in preprocessing Example of simple rewrite rule: (equal (car (cons x y)) x) Examples of simple definition: (defun file-clock-p (x) (integerp x)) (defun naturalp (x) (and (integerp x) (>= x 0))) The theorem prover output sometimes refers to ``simple'' definitions and rewrite rules. These rules can be used by the preprocessor, which is one of the theorem prover's ``processes'' understood by the [47m:do-not[0m hint; see [hints]. The preprocessor expands certain definitions and uses certain rewrite rules that it considers to be ``fast''. There are two ways to qualify as fast. One is to be an ``abbreviation'', where a rewrite rule with no hypotheses or loop stopper is an ``abbreviation'' if the right side contains no more variable occurrences than the left side, and the right side does not call the functions [47m[if][0m, [47m[not][0m or [47m[implies][0m. Definitions and rewrite rules can both be abbreviations; the criterion for definitions is similar, except that the definition must not be recursive. The other way to qualify applies only to a non-recursive definition, and applies when its body is a disjunction or conjunction, according to a perhaps subtle criterion that is intended to avoid case splits.") (single-threaded-objects (pointers) "See [stobj].") (sixth (nth acl2-built-ins) "Sixth member of the list See any Common Lisp documentation for details.") (skip-proofs (events) "Skip proofs for a given form --- a quick way to introduce unsoundness Example Form: (skip-proofs (defun foo (x) (if (atom x) nil (cons (car x) (foo (reverse (cdr x))))))) General Form: (skip-proofs form) where [47mform[0m is processed as usual except that the proof obligations usually generated are merely assumed. Normally [47mform[0m is an event; see [events]. If you want to put [47mskip-proofs[0m around more than one event, consider the following (see [progn]): [47m(skip-proofs (progn event1 event2 ... eventk))[0m. [31;1mWARNING[0m: The use of [47mskip-proofs[0m carries an implicit promise by the user that the ensuing proof obligations are indeed theorems of the current theory. When that is not the case, [47mskip-proofs[0m can even allow inconsistent [events] to be admitted to the logic. Use it at your own risk! If your intention is truly to extend the current logical theory, consider using [47m[defaxiom][0m instead. Sometimes in the development of a formal model or proof it is convenient to skip the proofs required by a given event. By embedding the event in a [47mskip-proofs[0m form, you can avoid the proof burdens generated by the event, at the risk of introducing unsoundness. Below we list four illustrative situations in which you might find [47mskip-proofs[0m useful. 1. The termination argument for a proposed function definition is complicated. You presume you could admit it, but are not sure that your definition has the desired properties. By embedding the [47m[defun][0m event in a [47mskip-proofs[0m you can ``admit'' the function and experiment with theorems about it before undoing (see [ubt]) and then paying the price of its admission. Note however that you might still have to supply a measure. The set of formals used in some valid measure, known as the ``measured subset'' of the set of formals, is used by ACL2's induction heuristics and therefore needs to be suitably specified. You may wish to specify the special measure of [47m(:? v1 ... vk)[0m, where [47m(v1 ... vk)[0m enumerates the measured subset. 2. You intend eventually to verify the [guard]s for a definition but do not want to take the time now to pursue that. By embedding the [47m[verify-guards][0m event in a [47mskip-proofs[0m you can get the system to behave as though the [guard]s were verified. 3. You are repeatedly recertifying a book while making many experimental changes. A certain [47m[defthm][0m in the book takes a very long time to prove and you believe the proof is not affected by the changes you are making. By embedding the [47m[defthm][0m event in a [47mskip-proofs[0m you allow the theorem to be assumed without proof during the experimental recertifications. 4. You are constructing a proof top-down and wish to defer the proof of a [47m[defthm][0m until you are convinced of its utility. You can embed the [47mdefthm[0m in a [47mskip-proofs[0m. Of course, you may find later (when you attempt prove the theorem) that the proposed [47mdefthm[0m is not a theorem. Unsoundness or Lisp errors may result if the presumptions underlying a use of [47mskip-proofs[0m are incorrect. Therefore, [47mskip-proofs[0m must be considered a dangerous (though useful) tool in system development. Roughly speaking, a [47m[defthm][0m embedded in a [47mskip-proofs[0m is essentially a [47m[defaxiom][0m, except that it is not noted as an axiom for the purposes of functional instantiation (see [lemma-instance]). But a skipped [47m[defun][0m is much more subtle since not only is the definitional equation being assumed but so are formulas relating to termination and type. The situation is also difficult to characterize if the [47mskip-proofs[0m [events] are within the scope of an [47m[encapsulate][0m in which constrained functions are being introduced. In such contexts no clear logical story is maintained; in particular, constraints aren't properly tracked for definitions. A proof script involving [47mskip-proofs[0m should be regarded as work-in-progress, not as a completed proof with some unproved assumptions. A [47mskip-proofs[0m event represents a promise by the author to admit the given event without further axioms. In other words, [47mskip-proofs[0m should only be used when the belief is that the proof obligations are indeed theorems in the existing ACL2 logical [world]. ACL2 allows the certification of [books] containing [47mskip-proofs[0m [events] by providing the keyword argument [47m:skip-proofs-okp t[0m to the [47m[certify-book][0m command. This is contrary to the spirit of certified [books], since one is supposedly assured by a valid [certificate] that a book has been ``blessed.'' But certification, too, takes the view of [47mskip-proofs[0m as ``work-in-progress'' and so allows the author of the book to promise to finish. When such [books] are certified, a warning to the author is printed, reminding him or her of the incurred obligation. When [books] containing [47mskip-proofs[0m are included into a session, a warning to the user is printed, reminding the user that the book is in fact incomplete and possibly inconsistent. This warning is in fact an error if [47m:skip-proofs-okp[0m is [47mnil[0m in the [47m[include-book][0m form; see [include-book]. We conclude with a technical note. [47mSkip-proofs[0m works by binding the [47m[ld][0m special [47m[ld-skip-proofsp][0m to [47mt[0m unless it is already bound to a non-[47mnil[0m value; see [ld-skip-proofsp].") (sleep (programming) "Sleep for some number of seconds The call [47m(sleep n)[0m returns [47mnil[0m. However, it takes approximately [47mn[0m seconds of real time for this call to return. The [guard] for [47msleep[0m requires its argument to be a non-negative rational number. [47mSleep[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<sleep> (defun sleep (n) (declare (xargs :guard (and (rationalp n) (<= 0 n)))) (declare (ignore n)) nil)") (slow-alist-warning (fast-alists) "Warnings/errors issued when [47m[fast-alists][0m are used inefficiently Obtaining hash-table performance from [47m[hons-get][0m requires one to follow a certain discipline. If this discipline is violated, you may see the following message, which by default is followed by a Lisp break. (The Lisp break may be ignored by continuing in the host Common Lisp, for example using [47m:go[0m if the host Lisp is CCL. Or, it may be aborted, often using [47m:q[0m, again depending on the host Lisp.) ***************************************************************** Fast alist discipline violated in HONS-ACONS. See :DOC slow-alist-warning to suppress or break on this warning. ***************************************************************** This warning means that the alist you are extending or accessing does not have a valid hash table associated with it, and hence any accesses must be carried out with [47m[hons-assoc-equal][0m instead of [47mgethash[0m. You can control whether or not you get a warning and, if so, whether or not a break (again: an error from which you can continue) ensues. For instance: (set-slow-alist-action :break) ; warn and also call break$ (default) (set-slow-alist-action :warning) ; warn on slow access (set-slow-alist-action nil) ; do not warn or break The above forms expand to [47m[table][0m [events], so they can be embedded in [47m[encapsulate][0ms and [books], wrapped in [47m[local][0m, and so on. We conclude by showing how slow alist warnings can occur naturally, together with a couple of possible solutions. First consider the rather trivial example; the labels A1, A2, etc. are explained later. ; (A1) Create a hash table HT1 and associate it with the resulting alist. (assign a (hons-acons 'fn1 1 nil)) ; (A2) Create a hash table HT2 and associate it with the resulting alist. ; (Minor observation: HT1 is no longer accessible.) (assign a (hons-acons 'fn1 1 nil)) ; (B1) Update HT2 and associate it with the resulting alist. Thus, H2 is ; no longer associated with (@ a). (assign b (hons-acons 'fn2 2 (@ a))) ; (B2) Fast alist warning (with a Lisp break, by default): discipline is ; violated because (@ a) no longer has a backing hash table. (assign b (hons-acons 'fn2 2 (@ a))) ; (C1) Fast alist warning/break: discipline is violated because (@ b) does not ; have a backing hash table. (assign c (hons-acons 'fn3 3 (@ b))) ; (C2) Fast alist warning/break: discipline is violated because (@ b) does not ; have a backing hash table. (assign c (hons-acons 'fn3 3 (@ b))) Now consider the following related example (in a fresh session), involving three [47m[encapsulate][0m events labeled A, B, and C. (encapsulate nil (defconst *a* (hons-acons 'fn1 1 nil))) ; (A) (encapsulate nil (defconst *b* (hons-acons 'fn2 2 *a*))) ; (B) (encapsulate nil (defconst *c* (hons-acons 'fn3 3 *b*))) ; (C) Each of these [47mencapsulate[0m events generates two calls of [47m[hons-acons][0m: one in the first pass of the [47mencapsulate[0m and one in the second pass. With a little reflection you can see the connection between the two sequences of events above: [47mencapsulate[0m A makes assignments analogous to A1 (in its first pass) and A2 (in its second pass); similarly for B, B1, B2 and for C, C1, C2. Thus, we get a slow alist warning/break on the second pass of B and on both passes of C. The simplest way to fix this problem is to call [47m[make-fast-alist][0m, which is essentially a no-op when its argument is already a fast alist. (encapsulate nil (defconst *a* (make-fast-alist (hons-acons 'fn1 1 nil)))) (encapsulate nil (defconst *b* (make-fast-alist (hons-acons 'fn2 2 *a*)))) (encapsulate nil (defconst *c* (make-fast-alist (hons-acons 'fn3 3 *b*)))) We still see the warning/break in pass 2 of the second and third encapsulates, created by calls of [47m[hons-acons][0m exactly as before. However, the results of those two calls are converted to fast alists by [47mmake-fast-alist[0m; so after each [47mencapsulate[0m, the value of the defined constant is indeed a fast alist. A problem still persists: the second and third [47m[defconst][0m event each steal the fast-alist value of the previous [47mdefconst[0m. That's a problem that we won't try to solve here; we will just focus on how to ensure that the value of [47m*c*[0m is a fast alist. The following alternate solution has the advantage of avoiding the expense of reconstituting the fast alist during pass 2 of each of the [47mdefconst[0m events. (We continue to use [47m[encapsulate][0m since otherwise the issue at hand dissolves.) (encapsulate nil (make-event `(defconst *a* ',(hons-acons 'fn1 1 nil)))) (encapsulate nil (make-event `(defconst *b* ',(hons-acons 'fn2 2 *a*)))) (encapsulate nil (make-event `(defconst *c* ',(hons-acons 'fn3 3 *b*)))) These uses of [47m[make-event][0m cause each fast alist from pass 1 to be saved and then reused in pass 2. There are no fast-alist warnings, and we avoid the expense of [47m[make-fast-alist][0m.") (slow-array-warning (arrays) "A warning or error issued when [arrays] are used inefficiently If you use ACL2 [arrays] you may sometimes see a [31;1mslow array[0m warning. We explain below what that warning means and some likely ``mistakes'' it may signify. First, we note that you can control whether or not you get a warning and, if so, whether or not a break (error from which you can continue; see [break$]) ensues: (assign slow-array-action :warning) ; warn on slow array access (default) (assign slow-array-action :break) ; warn as above, and then call break$ (assign slow-array-action nil) ; do not warn or break on slow array access If you are using ACL2 arrays, then you probably care about performance, in which case it is probably best to avoid the [47mnil[0m setting. Below we assume the default behavior: a warning, but no break. The discussion in the documentation for [arrays] defines what we mean by the semantic value of a name. As noted there, behind the scenes ACL2 maintains the invariant that with some names there is associated a pair consisting of an ACL2 array [47malist[0m, called the semantic value of the name, and an equivalent raw lisp array. Access to ACL2 array elements, as in [47m(aref1 name alist i)[0m, is executed in constant time when the array alist is the semantic value of the name, because we can just use the corresponding raw lisp array to obtain the answer. [47m[Aset1][0m and [47m[compress1][0m modify the raw lisp array appropriately to maintain the invariant. If [47m[aref1][0m is called on a name and alist, and the alist is not the then-current semantic value of the name, the correct result is computed but it requires linear time because the alist must be searched. When this happens, [47m[aref1][0m prints a [31;1mslow array[0m warning message to the comment window. [47m[Aset1][0m behaves similarly because the array it returns will cause the [31;1mslow array[0m warning every time it is used. From the purely logical perspective there is nothing ``wrong'' about such use of [arrays] and it may be spurious to print a warning message. But because [arrays] are generally used to achieve efficiency, the [31;1mslow array[0m warning often means the user's intentions are not being realized. Sometimes merely performance expectations are not met; but the message may mean that the functional behavior of the program is different than intended. Here are some ``mistakes'' that might cause this behavior. In the following we suppose the message was printed by [47m[aset1][0m about an array named [47mname[0m. Suppose the alist supplied [47m[aset1][0m is [47malist[0m. (1) [47m[Compress1][0m was never called on [47mname[0m and [47malist[0m. That is, perhaps you created an alist that is an [47m[array1p][0m and then proceeded to access it with [47m[aref1][0m but never gave ACL2 the chance to create a raw lisp array for it. After creating an alist that is intended for use as an array, you must do [47m(compress1 name alist)[0m and pass the resulting [47malist'[0m as the array. (2) [47mName[0m is misspelled. Perhaps the array was compressed under the name [47m'delta-1[0m but accessed under [47m'delta1[0m? (3) An [47m[aset1][0m was done to modify [47malist[0m, producing a new array, [47malist'[0m, but you subsequently used [47malist[0m as an array. Inspect all [47m(aset1 name ...)[0m occurrences and make sure that the alist modified is never used subsequently (either in that function or any other). It is good practice to adopt the following syntactic style. Suppose the alist you are manipulating is the value of the local variable [47malist[0m. Suppose at some point in a function definition you wish to modify [47malist[0m with [47m[aset1][0m. Then write (let ((alist (aset1 name alist i val))) ...) and make sure that the subsequent function body is entirely within the scope of the [47m[let][0m. Any uses of [47malist[0m subsequently will refer to the new alist and it is impossible to refer to the old alist. Note that if you write (foo (let ((alist (aset1 name alist i val))) ...) ; arg 1 (bar alist)) ; arg 2 you have broken the rules, because in [47marg 1[0m you have modified [47malist[0m but in [47marg 2[0m you refer to the old value. An appropriate rewriting is to lift the [47m[let][0m out: (let ((alist (aset1 name alist alist i val))) (foo ... ; arg 1 (bar alist))) ; arg 2 Of course, this may not mean the same thing. (4) A function which takes [47malist[0m as an argument and modifies it with [47m[aset1][0m fails to return the modified version. This is really the same as (3) above, but focuses on function interfaces. If a function takes an array [47malist[0m as an argument and the function uses [47m[aset1][0m (or a subfunction uses [47m[aset1][0m, etc.), then the function probably ``ought'' to return the result produced by [47m[aset1][0m. The reasoning is as follows. If the array is passed into the function, then the caller is holding the array. After the function modifies it, the caller's version of the array is obsolete. If the caller is going to make further use of the array, it must obtain the latest version, i.e., that produced by the function.") (solution-to-acl2-quantifier-exercise-2 (quantifier-tutorial) "A solution to [47m[quantifier-tutorial][0m Exercise 2 In [quantifier-tutorial] exercise 2, it asks if we can prove or disprove the conjecture below. [31;1mExercise 2[0m. If there is an ACL2 object [47mx[0m which satisfies [47mM[0m, then there exists a least ACL2 object [47my[0m that satisfies [47mM[0m. This hypothesis can be disproved. Here is one possible solution, provided by Yan Peng.. (in-package "ACL2") (include-book "misc/total-order" :dir :system) ;; This hypothesis can be disproved. ;; The intuition: find a function M that can be satisfied and does not have a ;; minimal object that satisfies it. ;; For example, if M is evenp, then for any ACL2 object that satisfies M, one ;; can always construct a smaller object by subtracting 2 from it, which also ;; satisfies M. ;; Instead of using defstub, we provide an implementation for M which calls ;; evenp. (defun M (x) (evenp x)) ;; We prove a helper lemma that says if x satisfies M, then (- x 2) also ;; satisfies M and it is a smaller object. (defthm -2-satisfies-M-and-<< (implies (M x) (and (M (- x 2)) (<< (- x 2) x))) :hints (("Goal" :in-theory (enable << lexorder alphorder)))) (in-theory (disable evenp M)) (defun-sk some-M () (exists x (M x))) (in-theory (disable some-M some-M-suff)) ;; We prove M can be satisfied by providing a witness 0. (defthm some-M-lemma (some-M) :hints (("Goal" :use ((:instance some-M-suff (x 0)))))) ;; We negate none-below-2 (defun-sk exists-below (y) (exists r (and (<< r y) (M r)))) (in-theory (disable exists-below exists-below-suff)) ;; We negate min-M2 (defun-sk not-min-M () (forall y (implies (M y) (exists-below y)))) (in-theory (disable not-min-M not-min-M-necc)) ;; We prove that forall y, if y satisfies M, then there exists another smaller ;; object that satisfies M. (defthm not-min-M-lemma (not-min-M) :hints (("Goal" :use (;; The definition of not-min-M provides a witness ;; (not-min-M-witness) that satisfies M but doesn't satisfy ;; exists-below. (:instance (:definition not-min-M)) ;; By instantiating exists-below-suff, we provide a smaller ;; object r:(- (not-min-M-witness) 2) than ;; y:(not-min-M-witness), and satisfies M. This makes ;; (not-min-M-witness) vacuous, allowing us to prove the ;; forall. (:instance exists-below-suff (r (- (not-min-M-witness) 2)) (y (not-min-M-witness))))))) ;; We prove both some-M and not-min-M (defthm |minimal does not exist| (and (some-M) (not-min-M)))") (solution-to-simple-example (annotated-acl2-scripts) "Solution to a simple example To see a statement of the problem solved below, see [annotated-ACL2-scripts] (in particular the end of that topic). Here is a sequence of ACL2 [events] that illustrates the use of ACL2 to make definitions and prove theorems. We will introduce the notion of the fringe of a tree, as well as the notion of a leaf of a tree, and then prove that the members of the fringe are exactly the leaves. We begin by defining the fringe of a tree, where we identify trees simply as [cons] structures, with [atom]s at the leaves. The definition is recursive, breaking into two cases. If [47mx[0m is a [cons], then the [47mfringe[0m of [47mx[0m is obtained by appending together the [47mfringe[0ms of the [47m[car][0m and [47m[cdr][0m (left and right child) of [47mx[0m. Otherwise, [47mx[0m is an [atom] and its [47mfringe[0m is the one-element list containing only [47mx[0m. (defun fringe (x) (if (consp x) (append (fringe (car x)) (fringe (cdr x))) (list x))) Now that [47mfringe[0m has been defined, let us proceed by defining the notion of an atom appearing as a ``leaf'', with the goal of proving that the leaves of a tree are exactly the members of its [47mfringe[0m. (defun leaf-p (atm x) (if (consp x) (or (leaf-p atm (car x)) (leaf-p atm (cdr x))) (equal atm x))) The main theorem is now as follows. Note that the rewrite rule below uses the equivalence relation [47m[iff][0m (see [equivalence]) rather than [47m[equal][0m, since [47m[member][0m returns the tail of the given list that begins with the indicated member, rather than returning a Boolean. (Use [47m:pe member[0m to see the definition of [47m[member][0m.) (defthm leaf-p-iff-member-fringe (iff (leaf-p atm x) (member-equal atm (fringe x))))") (soundness (about-acl2) "Correctness property claimed for ACL2 What can we conclude when we use ACL2 to prove a formula or to compute the value of an expression? This topic provides a high-level sketch of an answer. Overview of the ACL2 logic Any notion of correctness of ACL2 necessarily depends on the logic that it is intended to implement. At its core, the ACL2 logic is just classical first-order logic. The first-order theory for a given ACL2 session, which we may call the ``prover's theory'', is the result of extending its set of built-in axioms according to [events] that have been executed in the session. * The built-in axioms describe properties of the ACL2 data types, such as the following. ACL2 !>:pe car-cons -8139 (DEFAXIOM CAR-CONS (EQUAL (CAR (CONS X Y)) X)) ACL2 !> * A key extension principle is the Principle of Definition, which, for a definition [47m(defun <fn> <args> <body>)[0m, introduces an axiom equating [47m<body>[0m with application of [47m<fn>[0m to [47m<args>[0m. This principle permits recursion, and even [mutual-recursion], provided a suitable [3mmeasure conjecture[0m is provable. * Other [events] come with extension principles too, including [47m[encapsulate][0m, [47m[defchoose][0m, [47m[defpkg][0m, and [47m[include-book][0m. Note that from a logical perspective, [47m[defstobj][0m and [47m[defabsstobj][0m just provide definitional extensions. * Each ACL2 theory is [3mclosed under induction[0m: that is, every instance of induction (in the language of the theory) below the ordinal [47mepsilon-0[0m (see [ordinals]) is also in the theory. In practical terms, this is what allows ACL2 to prove theorems by induction. For more about the ACL2 logic see the following publications by Matt Kaufmann and J Moore. * {``A Precise Description of the ACL2 Logic'' | http://www.cs.utexas.edu/users/moore/publications/km97a.pdf} (April, 1998). * {``Structured Theory Development for a Mechanized Logic'' | https://www.cs.utexas.edu/users/moore/publications/encap-story.pdf}, [3mJournal of Automated Reasoning[0m 26, no. 2 (2001) 161-203. The soundness property for ACL2 sessions The following soundness property is key for a given ACL2 session. The theorem prover proves only formulas that are theorems in the corresponding prover's theory in that session. Note that the theorem prover uses evaluation during proofs. The soundness property thus encompasses the following: when such evaluation of a term [47mtm[0m produces a value [47mv[0m, then [47m(equal tm 'v)[0m is provable from the context of that evaluation. Evaluation in the top-level loop has such a property as well, but because of attachments (see [defattach]) and [47m[apply$][0m, provability is with respect to a larger ``evaluation theory''; see [guarantees-of-the-top-level-loop]. Constraints on the soundness guarantee Here is a list of constraints on the soundness guarantee. * The prover's theory of a session is construed to include all axioms introduced by hidden [defpkg] events. See [hidden-death-package]. * There is no soundness guarantee for a session in which there is raw Lisp evaluation with side effects. (ACL2 normally avoids putting the user into raw Lisp, but this can happen with an interrupt, the use of [47m[break$][0m, or explicitly leaving the top-level loop with [47m:[0m[47m[q][0m.) ``Side effects'' should be interpreted as generously as possible: this certainly includes redefining a function or assigning to a variable, but not merely evaluating an arithmetic expression, for example. * There is no soundness guarantee for a session in which any trust tag has been installed (see [defttag]). The absence of trust tags is guaranteed by the absence of ``[47mTTAG NOTE[0m'' being printed to standard output (that is, to [47m[*standard-co*][0m). * The soundness guarantee only applies when a set of books is certified from scratch, including [community-books], in a single environment --- in particular, with the same Lisp implementation and operating system. (In practice this is often not an issue.) Examples of divergence among Lisp implementations Next, we provide examples illustrating the last point above, restricting to the use of a single Lisp. [31;1mExample 1: Divergences involving character and string operations.[0m Consider the following log in raw Lisp using SBCL, which introduces versions of characters ``[47mA[0m'' and ``[47ma[0m'' that are augmented with an ``acute'' accent. * (code-char 193) #LATIN_CAPITAL_LETTER_A_WITH_ACUTE * (code-char 225) #LATIN_SMALL_LETTER_A_WITH_ACUTE * While most Lisps that host ACL2 consider these two characters to be alphabetic characters with case (upper and lower, respectively), GCL does not (at least, a version available as of this writing). (alpha-char-p (code-char 193)) ; T except NIL in GCL (alpha-char-p (code-char 225)) ; T except NIL in GCL (upper-case-p (code-char 193)) ; T except NIL in GCL (lower-case-p (code-char 225)) ; T except NIL in GCL (char-code (char-downcase (code-char 193))) ; 225 except 193 in GCL (char-code (char-upcase (code-char 225))) ; 193 except 225 in GCL (let ((s (string-downcase (string (code-char 193))))) (char-code (char s 0))) ; 225 except 193 in GCL (let ((s (string-upcase (string (code-char 225))))) (char-code (char s 0))) ; 193 except 225 in GCL [31;1mExample 2: Another divergence for [47m[alpha-char-p][0m[31;1m.[0m ; True in SBCL 2.4.2, about the character it calls #MICRO_SIGN, ; but false in LispWorks 8.0.1: (alpha-char-p (code-char 181)) ; False in SBCL 2.4.2, about the character it calls #CENT_SIGN, ; but true in Allegro CL 10.1: (alpha-char-p (code-char 162)) [31;1mExample 3: A divergence involving a floating-point computation.[0m Here is another example illustrating the requirement on a single Lisp. In ACL2 built on most host Lisp implementations, one can admit the following event. (See [df] for background on floating-point computations with ACL2.) (defthm usual-sin-2pi (equal (df-sin (df* 2 *df-pi*)) #d-2.4492935982947064E-16)) But in ACL2 built on LispWorks, one can instead admit the following. (defthm lispworks-sin-2pi (equal (df-sin (df* 2 *df-pi*)) #d-2.4492127076447545E-16)) Clearly one could prove [47mnil[0m by including two books, one containing each of these theorems. (Aside: This does not violate the IEEE-754 spec, since it does not make specific requirements for trigonometric functions.) Further reading for those interested in drilling down This topic has discussed the soundness guarantee from the user perspective. Those interested in exploring deeper theoretical and implementation issues are welcome to read the extensive relevant comments in the ACL2 source code, including the comments labeled as follows (listed in order of appearance as of this writing, not to indicate the order in which to read them). * Essay on Admitting a Model for Apply$ and the Functions that Use It * Essay on Hidden Packages * Essay on Soundness Threats * Essay on a Total Order of the ACL2 Universe * Essay on Illegal-states * Essay on Evaluation in ACL2 * Essay on the Logical Basis for Linear Arithmetic * Essay on the Correctness of Abstract Stobjs * Essay on Memoization with Partial Functions (Memoize-partial) * Essay on Correctness of Evaluation with Stobjs * Essay on Correctness of Meta Reasoning Subtopics [Guarantees-of-the-top-level-loop] Guarantees provided by top-level evaluation") (spec-mv-let (parallel-programming acl2-built-ins) "Modification of [47m[mv-let][0m supporting speculative and parallel execution This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism], and see [parallel-programming], which has a disclaimer. Example Form: (defun pfib-with-step-count (x) (declare (xargs :mode :program)) (if (or (zp x) (< x 33)) (fib-with-step-count x) (spec-mv-let (a cnt1) (pfib-with-step-count (- x 1)) (mv-let (b cnt2) (pfib-with-step-count (- x 2)) (if t (mv (+ a b) (+ 1 cnt1 cnt2)) (mv "speculative result is always needed" -1)))))) General Form: (spec-mv-let (v1 ... vn) ; bind distinct variables <spec> ; evaluate speculatively; return n values (mv-let ; or, use mv?-let if k=1 below (w1 ... wk) ; bind distinct variables <eager> ; evaluate eagerly (if <test> ; use results from <spec> if true <typical-case> ; may mention v1 ... vn <abort-case>))) ; does not mention v1 ... vn Our design of [47mspec-mv-let[0m is guided by its use in ACL2 source code to parallelize part of ACL2's proof process, in the experimental parallel extension of ACL2. The user can think of [47mspec-mv-let[0m as a speculative version of [47m[mv-let][0m. (In ordinary ACL2, the semantics agree with this description but without speculative or parallel execution.) Evaluation of the above general form proceeds as suggested by the comments. First, [47m<spec>[0m is executed speculatively. Control then passes immediately to the [47m[mv-let][0m call, without waiting for the result of evaluating [47m<spec>[0m. The variables [47m(w1 ... wk)[0m are bound to the result of evaluating [47m<eager>[0m, and then [47m<test>[0m is evaluated. If the value of [47m<test>[0m is true, then the values of [47m(v1 ... vn)[0m are needed, and [47m<typical-case>[0m blocks until they are available. If the value of [47m<test>[0m is false, then the values of [47m(v1 ... vn)[0m are not needed, and the evaluation of [47m<spec>[0m may be aborted. The calls to [47mmv-let[0m and to [47mif[0m displayed above in the General Form are an essential part of the design of [47mspec-mv-let[0m, and are thus required. The following definition of [47mfib-with-step-count[0m completes the example above: (defun fib-with-step-count (x) (declare (xargs :mode :program)) (cond ((<= x 0) (mv 0 1)) ((= x 1) (mv 1 1)) (t (mv-let (a cnt1) (fib-with-step-count (- x 1)) (mv-let (b cnt2) (fib-with-step-count (- x 2)) (mv (+ a b) (+ 1 cnt1 cnt2)))))))") (special-cases-for-rewrite-rules (introduction-to-the-theorem-prover) "Convenient short forms for rewrite rule formulas In principle, every rewrite rule is made from a formula of this shape: (IMPLIES (AND [3mhyp1[0m ... [3mhypk[0m) ([3meqv[0m [3mlhs[0m [3mrhs[0m)) where [3meqv[0m is either [47mEQUAL[0m or [47mIFF[0m and the result of expanding any abbreviations in [3mlhs[0m is the application of some function symbol other than [47mIF[0m. * In the special case where there is only one [3mhyp[0m term, i.e., [3mk[0m=1, the [47m(AND[0m [3mhyp1[0m[47m)[0m can be written [3mhyp1[0m. * In the special case where there are no [3mhyp[0m terms, [3mk[0m=0, the [47m(AND)[0m term is logically just [47mT[0m and the whole [47mIMPLIES[0m can be dropped; such a formula may be written as an unconditional [47mEQUAL[0m or [47mIFF[0m term. * If you build a rewrite rule from a formula that concludes with [47m(NOT[0m [3mx[0m[47m)[0m, it is treated as though it were [47m(EQUAL[0m [3mx[0m [47mNIL)[0m, which is logically equivalent to what you typed. * If you build a rewrite rule from a formula that concludes with an [47mAND[0m, ACL2 will build a rewrite rule for each conjunct of the [47mAND[0m. This is because (IMPLIES hyp (AND concl1 concl2)) is propositionally equivalent to (AND (IMPLIES hyp concl1) (IMPLIES hyp concl2)). However, if you use an [47mOR[0m-expression as a hypothesis, ACL2 does [3mnot[0m do the dual transformation. Thus, [47m(IMPLIES (OR hyp1 hyp2) concl)[0m generates one rewrite rule. * Finally, if you build a rewrite rule from a formula that does not conclude with an [47mEQUAL[0m, an [47mIFF[0m, a [47mNOT[0m, or an [47mAND,[0m but with some other term, say, [3mlhs[0m, then ACL2 acts like you typed [47m(IFF[0m [3mlhs[0m [47mT)[0m, which is logically equivalent to what you typed. Thus, regardless of what you type, every rule has [3mk[0m hypotheses. For unconditional rules, [3mk[0m is 0 and the hypotheses are vacuously true. Whether or not you write an [47mEQUAL[0m or an [47mIFF[0m in the conclusion, every rule is either an equality or a propositional equivalence, every rule has a left-hand side, and every rule has a right-hand side. Use your browser's [31;1mBack Button[0m now to return to [introduction-to-rewrite-rules-part-1].") (specific-kinds-of-formulas-as-rewrite-rules (introduction-to-the-theorem-prover) "Advice about how to handle commonly occurring formulas as rewrite rules Below we give you some guidelines for handling specific, commonly occurring situations. * [31;1mAssociativity[0m: If a function [47mf[0m is associative, prove (equal (f (f x y) z) (f x (f y z))) ACL2 will use this to flatten [47mf[0m-nests ``to the right.'' * [31;1mCommutativity[0m: If a function [47mf[0m is commutative, prove both (equal (f x y) (f y x)) and (equal (f x (f y z)) (f y (f x z))) ACL2's heuristics will use these rules to order the arguments alphabetically, so that [47m(f B (f D (f A C)))[0m becomes [47m(f A (f B (f C D)))[0m. * [31;1mDistributivity[0m: If you have a pair of functions [47mf[0m and [47mg[0m so that [47m(f x (g y z))[0m is [47m(g (f x y) (f x z))[0m or some other form of distributivity is provable, arrange your rules to move the lighter function symbol up and the heavier one toward the variable symbols. For example, our arithmetic libraries drive multiplication through addition, producing sums of products rather than products of sums. * [31;1mIdentity and Other Laws[0m: Prove the obvious identity and zero laws (or at least anticipate that you might need them down the road) so as to eliminate operators. * [31;1mGet Rid of Tail Recursive Functions[0m: A corollary to the above advice concerns tail recursive functions that use auxiliary variables. New users often define concepts using tail recursions, accumulating partial results in auxiliary variables, because creating such functions is similar to programming with [47mwhile[0m loops. Expert users will use tail recursion when necessary for execution efficiency. But tail recursive functions are messy to reason about: their auxiliary variables have to be properly initialized to make the functions compute the expected results, but to state inductively provable properties of tail recursive functions you must identify the invariants on those auxiliary variables. This problem tends not to happen with [3mprimitive recursive functions[0m. A primitive recursive function is one that recurs down one variable and holds all the other variables constant in recursion. Most tail-recursive functions can be written elegantly as primitive recursive functions, though one might have to ignore the programmer's desire to make things efficient and define auxiliary functions to appropriately transform the value returned by the recursive call. The classic example is reverse defined in terms of the auxiliary function [47mappend[0m versus reverse defined tail recursively with an accumulator. By introducing [47mappend[0m you introduce a concept about which you can state lemmas and decompose the proofs of properties of reverse. So if your problem involves tail recursive functions with auxiliary variables, define the primitive recursive version, prove that the tail recursive function is equivalent to the primitive recursive one, and arrange the rewrite rule to eliminate the tail recursive function. * [31;1mGet Rid of Mutually Recursive Functions[0m: Similarly, if you have used [47mmutual-recursion[0m to introduce a clique of mutually recursive functions, [47mf1[0m, [47mf2[0m, ..., you will find that to reason about any one function in the nest you have to reason about all of them. Any mutually recursive function can be defined in a singly recursive way. So do that and then prove a rewrite rule that gets rid of all the mutually recursive functions by proving (and (equal (f1 ...) (g1 ...)) (equal (f2 ...) (g2 ...)) ...) where the [47mgi[0m are singly recursive. You may need to appeal to a trick to define the [47mgi[0m: define a singly recursive function that takes a flag argument and mimics whichever mutually recursive function the flag specifies. See [mutual-recursion] {ICON} (see [A_Tiny_Warning_Sign]) and see [mutual-recursion-proof-example] {ICON} (see [A_Tiny_Warning_Sign]). If you got to this documentation page from the tutorial discussion of rewrite rules, use your browser's [31;1mBack Button[0m now to return to [introduction-to-rewrite-rules-part-2].") (specious-simplification (miscellaneous) "Nonproductive proof steps Occasionally the ACL2 theorem prover reports that the current goal simplifies to itself or to a set including itself. Such simplifications are said to be ``specious'' and are ignored in the sense that the theorem prover acts as though no simplification were possible and tries the next available proof technique. Specious simplifications are almost always caused by the use of [47m[force][0m or [47m[case-split][0m. The simplification of a formula proceeds primarily by the local application of [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[type-prescription][0m, and other rules to its various subterms. If no rewrite rules apply, the formula cannot be simplified and is passed to the next ACL2 proof technique, which is generally the elimination of destructors. The experienced ACL2 user pays special attention to such ``maximally simplified'' formulas; the presence of unexpected terms in them indicates the need for additional rules or the presence of some conflict that prevents existing rules from working harmoniously together. However, consider the following interesting possibility: local rewrite rules apply but, when applied, reproduce the goal as one of its own subgoals. How can rewrite rules apply and reproduce the goal? Of course, one way is for one rule application to undo the effect of another, as when commutativity is applied twice in succession to the same term. Another kind of example is when two rules conflict and undermine each other. For example, under suitable hypotheses, [47m(length x)[0m might be rewritten to [47m(+ 1 (length (cdr x)))[0m by the [47m:[0m[47m[definition][0m of [47m[length][0m and then a [47m:[0m[47m[rewrite][0m rule might be used to ``fold'' that back to [47m(length x)[0m. Generally speaking the presence of such ``looping'' rewrite rules causes ACL2's simplifier either to stop gracefully because of heuristics such as that described in the documentation for [47m[loop-stopper][0m or to cause a stack overflow because of indefinite recursion. A more insidious kind of loop can be imagined: two rewrites in different parts of the formula undo each other's effects ``at a distance,'' that is, without ever being applied to one another's output. For example, perhaps the first hypothesis of the formula is simplified to the second, but then the second is simplified to the first, so that the end result is a formula propositionally equivalent to the original one but with the two hypotheses commuted. This is thought to be impossible unless forcing or case-splitting occurs, but if those features are exploited (see [force] and see [case-split]) it can be made to happen relatively easily. Here is a simple example. Declare [47mfoo[0m to be a function of one argument returning one result: (defstub p1 (x) t) Prove the following silly rule: (defthm bad (implies (case-split (p1 x)) (p1 x))) Now suppose we try the following. (thm (p1 x)) The [rewrite] rule [47mbad[0m will rewrite [47m(p1 x)[0m to [47mt[0m, but it will be unable to prove the hypothesis [47m(case-split (p1 x))[0m. As a result, the prover will spawn a new goal, to prove [47m(p1 x)[0m. However, since this new goal is the same as the original goal, ACL2 will recognize the simplification as [3mspecious[0m and consider the attempted simplification to have failed. In other words, despite the rewriting, no progress was made! In more common cases, the original goal may simplify to a set of subgoals, one of which includes the original goal. If ACL2 were to adopt the new set of subgoals, it would loop indefinitely. Therefore, it checks whether the input goal is a member of the output subgoals. If so, it announces that the simplification is ``specious'' and pretends that no simplification occurred. ``Maximally simplified'' formulas that produce specious simplifications are maximally simplified in a very technical sense: were ACL2 to apply every applicable rule to them, no progress would be made. Since ACL2 can only apply every applicable rule, it cannot make further progress with the formula. But the informed user can perhaps identify some rule that should not be applied and make it inapplicable by disabling it, allowing the simplifier to apply all the others and thus make progress. When specious simplifications are a problem it might be helpful to [disable] rules involved in forcing (including case-splits; see [force] and see [case-split]). For the example above we see the following output; and in fact, a hint to disable [47mBAD[0m will avoid the specious simplification (although the proof will still fail). Splitter note (see :DOC splitter) for Goal (0 subgoals). case-split: ((:REWRITE BAD)) A more drastic possibility is to disable all forcing (including [case-split]s) and resubmit the formula to observe whether forcing is involved in the loop or not. The commands ACL2 !>:disable-forcing and ACL2 !>:enable-forcing [disable] and [enable] the pragmatic effects of both [47mforce[0m and [47mcase-split[0m. If the loop is broken when forcing is [disable]d, then it is very likely some [force]d hypothesis of some rule is ``undoing'' a prior simplification. The most common cause of this is when we [force] a hypothesis that is actually false but whose falsity is somehow temporarily hidden (more below). To find the offending rule, compare the specious simplification with its non-specious counterpart and look for rules that were speciously applied that are not applied in the non-specious case. Most likely you will find at least one such rule and it will have a [47m[force][0md hypothesis. By disabling that rule, at least for the subgoal in question, you may allow the simplifier to make progress on the subgoal.") (split-types (pointers) "See [xargs] for information about the keyword [47m:split-types[0m.") (splitter (debugging) "Reporting of rules whose application may have caused case splits When the ACL2 rewriter applies a rule to a term, a goal might simplify to more than one subgoal. A rule with such an application is called a ``splitter''. Here, we explain the output produced for splitters when proof output is enabled (see [set-inhibit-output-lst]) and such reporting is turned on (as it is by default) --- that is, when the value of [47m([0m[47m[splitter-output][0m[47m)[0m is true. See [set-splitter-output] for how to turn off, or on, the reporting of splitters. Also see [set-case-split-limitations] for information on how to control case splits. Note that since splitters are rule applications, splitter output is not generated for case splits that are caused by other than rules, such as the mere presence of calls of the function symbol, [47m[if][0m, in the goal. We begin by describing three types of splitters. [47mif-intro[0m: The rule application may have introduced a call of [47mIF[0m, in the sense discussed at the end below. [47mcase-split[0m: For the application of a rule with hypothesis of the form [47m(case-split <hyp>)[0m, [47m<hyp>[0m did not simplify to true or false. [47mimmed-forced[0m: For the application of a rule with hypothesis of the form [47m(force <hyp>)[0m, [47m<hyp>[0m did not simplify to true or false, where immediate-force-modep is enabled (see [immediate-force-modep]). These three annotations --- [47mif-intro[0m, [47mcase-split[0m, and [47mimmed-forced[0m --- may be used in proof output and summaries for describing rule applications, as discussed below. A fourth annotation, [47mforced[0m, may also be used in proof output to indicate the application of a rule with hypothesis of the form [47m(force <hyp>)[0m when [47m<hyp>[0m did not simplify to true or false, where immediate-force-modep is disabled (see [immediate-force-modep]). We don't consider such uses of [47m[force][0m to be splitters, because they do not cause case splits (though they do produce goals to prove after lower-case ``q.e.d.'' is printed); see [force]. There are three kinds of output affected by splitters, illustrated in turn below using examples. (a) During the proof, [gag-mode] and raw proof format (see [set-raw-proof-format]) off (b) During the proof, [gag-mode] or raw proof format on (c) [Summary] Of course, (a) and (b) are skipped if proof output is inhibited, and (c) is skipped if [summary] output is inhibited; see [set-inhibit-output-lst]. (a) During the proof, [gag-mode] and raw proof format (see [set-raw-proof-format]) off With [gag-mode] off (or when using [47m:[0m[47m[pso][0m, [47m:[0m[47m[psof][0m, or [47m:[0m[47m[psog][0m) one normally gets an English commentary. The following output indicates that at least one application of each rule [47mF[0m and [47mG[0m is of type [47mif-intro[0m, at least one application of rules [47mG[0m and [47mR1[0m are of type [47mcase-split[0m, and at least one application of rule [47mR3[0m is of type [47mimmed-forced[0m. If [immediate-force-modep] is off then ``[47mimmed-forced[0m'' would be replaced by ``[47mforced[0m''. This simplifies, using the :definitions F (if-intro), G (case-split and if-intro) and H and the :rewrite rules R1, R2 (case-split), and R3 (immed-forced), to the following two conjectures. Note that any such printing of ``[47mforced[0m'' is done even if [47m(splitter-output)[0m is false. (b) During the proof, [gag-mode] or raw proof format on With [gag-mode] or raw proof format (see [set-raw-proof-format]) on, the proof output is abbreviated. However, in these cases ``Splitter Notes'' are printed so that one can still get important information to help control large case splits (by disabling splitter rules as appropriate). These are printed at the point when a goal splits into subgoals. Here, for example, is the Splitter Note that corresponds to the output shown in (a) above. It shows the goal whose simplification has produced a split into more than one subgoal, and it shows how many subgoals have been created. Splitter note (see :DOC splitter) for Subgoal *1/2.2.1' (2 subgoals). case-split: ((:DEFINITION G) (:REWRITE R2)) immed-forced: ((:REWRITE R3)) if-intro: ((:DEFINITION G) (:DEFINITION F)) No such splitter notes are printed for the use of [47m[force][0m (when [immediate-force-modep] is off). (c) [Summary] Here is a possible summary corresponding to our running example. In the summary, ``Splitter rules'' is omitted if there are no splitter rules, and a splitter type is only mentioned if there is at least one corresponding splitter rule. Summary Form: ( THM ...) Rules: ((:DEFINITION F) (:DEFINITION G) (:DEFINITION H) (:REWRITE R1) (:REWRITE R2) (:REWRITE R3)) Splitter rules (see :DOC splitter): case-split: ((:DEFINITION G) (:REWRITE R2)) immed-forced: ((:REWRITE R3)) if-intro: ((:DEFINITION G) (:DEFINITION F)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.00) Prover steps counted: 145 No indication for ``[47mforced[0m'' is given for ``Splitter rules''. (As discussed earlier above, the [47m[force][0md hypotheses are not considered relevant for determining splitter rule applications unless [immediate-force-modep] is on.) We conclude by giving the criteria for a [rewrite] or [definition] rule application to be a splitter of type [47mif-intro[0m. * Reporting of splitter rules is on, i.e., the value of [47m([0m[47m[splitter-output][0m[47m)[0m is true. * At least two subgoals are created, even before considering subgoals generated by hypotheses that are calls of [47m[case-split][0m or [47m[force][0m. * The term to which the rule is applied is at the top level, rather than being encountered when trying to establish the hypothesis of a rule. * The rule is a [rewrite] rule, a [definition] rule, or a [meta] rule. * There is a call of the function symbol [47mIF[0m in the right-hand side of the [rewrite] rule; or, in the case of a [definition] rule, in the body of the definition; or, in the case of a [meta] rule, in the result of applying the metafunction. * There is a call of the function symbol [47mIF[0m in the result of rewriting: the right-hand side (for a [rewrite] rule), the definition body (for a [definition] rule), or the metafunction application (for a [meta] rule). Any rule application meeting the above criteria will be considered a splitter of type [47mif-intro[0m, even if the call does not actually cause a case split. For example, if you are proving [47m(implies (hyp x) (conc x))[0m and rule R rewrites [47m(hyp x)[0m to [47m(if (h1 x) (h2 x) nil)[0m, which is really the term [47m(and (h1 x) (h2 x))[0m, then R may be labeled as a splitter rule. If you want to find the causes of case-splitting, the list of [47mif-intro[0m splitters can help you narrow your search, but may include irrelevant rules as well. Finally, note that you may see splits not attributed to splitters. We believe that this will be uncommon during simplification, though it can occur for example when a call of [47mIF[0m is in the body of a [47m[let][0m expression, i.e., in a call of a [47m[lambda][0m expression. But splits caused by other processes, notably destructor elimination (see [elim]), will typically not be attributed to splitters. Subtopics [Set-splitter-output] Turn on or off reporting of rules that may have caused case splits [Splitter-output] Status for reporting of [splitter] rules") (splitter-output (splitter) "Status for reporting of [splitter] rules See [splitter] for a discussion of splitter rules. See [set-splitter-output] for how to turn off, or on, the reporting of splitter rules. When splitter-output is off, because either [47mprove[0m output is inhibited (see [set-inhibit-output-lst]) or [47m([0m[47m[set-splitter-output][0m[47m nil)[0m has been invoked, then the value of [47m(splitter-output)[0m is [47mnil[0m. Otherwise, such reporting is on and the value is non-[47mnil[0m.") (stable-under-simplificationp (pointers) "See [computed-hints].") (standard-char-listp (characters lists acl2-built-ins) "Recognizer for a true list of standard characters [47m(standard-char-listp x)[0m is true if and only if [47mx[0m is a [47mnil[0m-terminated list all of whose members are standard [characters]. See [standard-char-p]. [47mStandard-char-listp[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<standard-char-listp> (defun standard-char-listp (l) (declare (xargs :guard t)) (cond ((consp l) (and (characterp (car l)) (standard-char-p (car l)) (standard-char-listp (cdr l)))) (t (equal l nil))))") (standard-char-p (characters acl2-built-ins) "Recognizer for standard characters [47m(Standard-char-p x)[0m is true if and only if [47mx[0m is a ``standard'' character, i.e., a member of the list [47m*standard-chars*[0m. This list includes [47m#\Newline[0m and [47m#\Space[0m [characters], as well as the usual punctuation and alphanumeric [characters]. [47mStandard-char-p[0m has a [guard] requiring its argument to be a character. [47mStandard-char-p[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<standard-char-p> (defun standard-char-p (x) (declare (xargs :guard (characterp x))) (if (member x *standard-chars*) t nil)) Subtopics [Standard-char-p+] Recognizer for standard characters whose guard is [47mt[0m") (standard-char-p+ (standard-char-p characters acl2-built-ins) "Recognizer for standard characters whose guard is [47mt[0m Logically [47mstandard-char-p+[0m is the same as [47m[standard-char-p][0m. However, [47mstandard-char-p+[0m has a guard of [47mt[0m, while [47mstandard-char-p[0m is guarded by [47m[characterp][0m. [31;1mFunction: [0m<standard-char-p+> (defun standard-char-p+ (x) (declare (xargs :guard t)) (and (characterp x) (standard-char-p x)))") (standard-co (io acl2-built-ins) "The character output channel to which [47m[ld][0m prints [47mStandard-co[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(standard-co state)[0m and the updater is [47m(set-standard-co val state)[0m. [47mStandard-co[0m must be an open character output channel. It is to this channel that [47m[ld][0m prints the [prompt], the form to be evaluated, and the results. The event [command]s such as [47m[defun][0m, [47m[defthm][0m, etc., which print extensive commentary do not print to [47mstandard-co[0m but rather to a different channel, [47m[proofs-co][0m, so that you may redirect this commentary while still interacting via [47mstandard-co[0m. See [proofs-co]. ``Standard-co'' stands for ``standard character output.'' The initial value of [47mstandard-co[0m is the same as the value of [47m[*standard-co*][0m.") (standard-oi (io acl2-built-ins) "The standard object input ``channel'' [47mStandard-oi[0m is an [47m[ld][0m special (see [ld]). The accessor is [47m(standard-oi state)[0m and the updater is [47m(set-standard-oi val state)[0m. [47mStandard-oi[0m must be an open object input channel, a true list of objects, or a list of objects whose last [47m[cdr][0m is an open object input channel. It is from this source that [47m[ld][0m takes the input forms to process. When [47m[ld][0m is called, if the value specified for [47mstandard-oi[0m is a string or a list of objects whose last [47m[cdr][0m is a string, then [47m[ld][0m treats the string as a file name and opens an object input channel from that file, where the connected book directory (see [cbd]) is used to resolve relative pathnames. The channel opened by [47m[ld][0m is closed by [47m[ld][0m upon termination. ``Standard-oi'' stands for ``standard object input.'' The read-eval-print loop in [47m[ld][0m reads the objects in [47mstandard-oi[0m and treats them as forms to be evaluated. The initial value of [47mstandard-oi[0m is the same as the value of [47m[*standard-oi*][0m.") (standard-part (real) "ACL2(r) function mapping limited numbers to standard numbers [47m(Standard-part x)[0m is, for a given [47m[i-limited][0m number [47mx[0m, the unique real number infinitesimally close (see [i-close]) to [47mx[0m. This function is only defined in ACL2(r) (see [real]).") (standardp (real) "ACL2(r) recognizer for standard objects [47m(Standardp x)[0m is true if and only if [47mx[0m is a ``standard'' object. This notion of ``standard'' comes from non-standard analysis and is discussed in Ruben Gamboa's dissertation. In brief, all the familiar objects are standard: e.g., the familiar real numbers are standard, but non-zero infinitesimals are not standard, and the familiar integers are standard, but not those that exceed every integer that you can express in the usual way (1, 2, 3, and so on). Similarly, the familiar lists are standard, but not so a list that contains a large number of integers, where ``large'' means more than the standard integers. The set of standard numbers is closed under the usual arithmetic operations, hence the sum of a standard number and a non-zero infinitesimal is not standard, though it is what is called ``limited'' (see [i-limited]). This predicate is only defined in ACL2(r) (see [real]).") (start-here (acl2) "Introductory information about ACL2 This [documentation] topic provides a starting point for those who are new to ACL2 or want to learn more about it. It accommodates different goals (ranging from mild curiosity about ACL2 to the desire to become an expert user) and different learning styles. A quick scan should help you find a place to start that suits you. * The [31;1mACL2 home page[0m, at [47m{ http://www.cs.utexas.edu/users/moore/acl2/ | http://www.cs.utexas.edu/users/moore/acl2/}[0m, provides links that can take you to good places to start learning about ACL2. * See [about-ACL2] for [31;1mbasic ``administrative'' information[0m such as how to obtain and build ACL2, copyright and license material, mailing lists, connection with GitHub, and so on. * See [using-ACL2] for introductory material about [31;1musing[0m ACL2. * See [tours] for [31;1moverviews at a high level[0m. Also see the paper [3m{Industrial Proofs with ACL2 | https://www.cs.utexas.edu/users/moore/publications/how-to-prove-thms/intro-to-acl2.pdf}[0m, which was written in the 1990s but is still useful for providing a brief overview of what can be done with ACL2. * [31;1mTutorial Introductions[0m at various levels are available at the [ACL2-tutorial] documentation topic and especially its subtopics. (There is some overlap with the present topic.) * [31;1mBooks[0m include the following. * [3m{Computer-Aided Reasoning: An Approach | http://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html}[0m provides a detailed introduction to ACL2 and contains many exercises. * [3m{Computer-Aided Reasoning: ACL2 Case Studies | http://www.cs.utexas.edu/users/moore/publications/acl2-books/acs/index.html}[0m describes some relatively early applications of ACL2, including scripts as well as answers to the exercises. * There are many [31;1mprojects that use ACL2.[0m * See [interesting-applications] for an overview of some projects that have used ACL2. * See publications for links to many books and papers. You can also see workshops for programs, talks, and papers presented at the numerous ACL2 Workshops. * The {Community Books | https://github.com/acl2/acl2/tree/master/books} is a repository of many projects, processed virtually continuously by virtue of constituting the ACL2 regression suite. Many of those projects are descried in the {ACL2+books online manual | https://acl2.org/doc/index.html}. * [31;1mProgramming with ACL2[0m is introduced gently in the documentation topic, [gentle-introduction-to-ACL2-programming]. * [31;1mLogical basics[0m are presented in the [recursion-and-induction] documentation topic, for teaching yourself how to prove theorems about recursively defined functions using mathematical induction. There are lots of exercises. Some may find this a good way to get into ACL2, by understanding its proof system before attempting to use the tool. * [31;1mThe theorem prover[0m is something perhaps best learned after studying the logical basics above, or at least giving them a quick glance. Then you can just dive in or you can first study how to use it. * See [the-method] for concise guidance on the key technique for using the ACL2 prover effectively. * See [introduction-to-the-theorem-prover] for a detailed discussion of how to be an effective user of the ACL2 theorem prover, including a focus on its primary proof technique, rewriting. * The paper ``{How to Prove Theorems Formally | https://www.cs.utexas.edu/users/moore/publications/how-to-prove-thms/main.pdf} guides the reader towards effective use of ACL2, with exercises included. Quoting the abstract: ``The real purpose of this paper is to answer the question how does one construct and manage large mechanically checked proofs (in ACL2)?''. * Here are some resources for trying out ACL2 without directly installing it yourself. * The ACL2 Sedan (see [ACL2-SEDAN]) is an [31;1mEclipse-based plug-in that provides a modern development environment[0m and other capabilities that may be helpful for new ACL2 users. * A basic [31;1mweb-based interface to ACL2[0m is {Proof Pad | http://new.proofpad.org}. * There is an {ACL2 Docker container | https://hub.docker.com/r/atwalter/acl2} (maintained at {this repo | https://github.com/mister-walter/acl2-docker}). Subtopics [About-ACL2] General information About ACL2 [ACL2-tutorial] Tutorial introduction to ACL2 [Gentle-introduction-to-ACL2-programming] A Gentle Introduction to ACL2 Programming") (start-proof-tree (proof-tree) "Start displaying proof trees during proofs Also see [proof-tree] and see [stop-proof-tree]. Note that [47m:start-proof-tree[0m works by removing [47m'[0m[47m[proof-tree][0m from the [47minhibit-output-lst[0m; see [set-inhibit-output-lst]. Explanations of proof tree displays may be found elsewhere: see [proof-tree]. In a nutshell: [47m:start-proof-tree[0m causes proof tree display to be turned on, once it has been turned off by [47m:[0m[47m[stop-proof-tree][0m. Do not attempt to invoke [47mstart-proof-tree[0m during an interrupt in the middle of a proof.") (startup (acl2-tutorial) "How to start using ACL2; the ACL2 [command] loop When you start up ACL2, you'll probably find yourself inside the ACL2 [command] loop, as indicated by the following [prompt]. ACL2 !> If not, you should type [47m(LP)[0m. See [lp], which has a lot more information about the ACL2 [command] loop. You should now be in ACL2. The current ``[default-defun-mode]'' is [47m:[0m[47m[logic][0m; the other mode is [47m:[0m[47m[program][0m, which would cause the letter [47mp[0m to be printed in the [prompt]. [47m:[0m[47m[Logic][0m means that any function we define is not only executable but also is axiomatically defined in the ACL2 logic. See [defun-mode] and see [default-defun-mode]. For example we can define a function [47mmy-cons[0m as follows. (You may find it useful to start up ACL2 and submit this and other [command]s below to the ACL2 [command] loop, as we won't include output below.) ACL2 !>(defun my-cons (x y) (cons x y)) An easy theorem may then be proved: the [47m[car][0m of [47m(my-cons a b)[0m is A. ACL2 !>(defthm car-my-cons (equal (car (my-cons a b)) a)) You can place raw Lisp forms to evaluate at start-up into file [47macl2-init.lsp[0m in your home directory, except on Windows systems. For example, if you put the following into [47macl2-init.lsp[0m, then ACL2 will print "HI" when it starts up. (print "HI") But be careful; all bets are off when you submit forms to raw Lisp, so this capability should only be used when you are hacking or when you are setting some Lisp parameters (e.g., [47m(setq si::*notify-gbc* nil)[0m to turn off garbage collection notices in GCL). Notice that unlike Nqthm, the theorem [command] is [47m[defthm][0m rather than [47mprove-lemma[0m. See [defthm], which explains (among other things) that the default is to turn theorems into [rewrite] rules. Various keyword commands are available to query the ACL2 ``[world]'', or database. For example, we may view the definition of [47mmy-cons[0m by invoking a command to print [events], as follows. ACL2 !>:pe my-cons Also see [pe]. We may also view all the lemmas that [rewrite] [term]s whose top function symbol is [47m[car][0m by using the following command, whose output will refer to the lemma [47mcar-my-cons[0m proved above. ACL2 !>:pl car Also see [pl]. Finally, we may print all the [command]s back through the initial [world] as follows. ACL2 !>:pbt 0 See [history] for a list of commands, including these, for viewing the current ACL2 [world]. Continue with the [documentation] for [annotated-ACL2-scripts] to see a simple but illustrative example in the use of ACL2 for reasoning about functions.") (startup-banner (interfacing-tools) "Modifying the ACL2 startup banner When you start up an ACL2 executable built from sources obtained from GitHub between ACL2 releases, you'll typically see a startup banner like this: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + ACL2 Version 8.6+ (a development snapshot based on ACL2 Version 8.6) + + built January 14, 2026 10:09:28. + + (Git commit hash: 1234567890abcdefghijklmnopqrstuvwxyz!@#$) + + Copyright (C) 2026, Regents of the University of Texas. + + ACL2 comes with ABSOLUTELY NO WARRANTY. This is free software and + + you are welcome to redistribute it under certain conditions. For + + details, see the LICENSE file distributed with ACL2. + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The third line of that banner can be modified by setting environment variable [47mACL2_SNAPSHOT_INFO[0m to a non-empty string before saving the executable. The value of that variable will be placed into the banner, for example as follows if that value is [47m"This is my private executable."[0m. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + ACL2 Version 8.6+ (a development snapshot based on ACL2 Version 8.6) + + built January 14, 2026 09:56:49. + + (Note from the environment when this executable was saved: + + This is my private executable.) + + Copyright (C) 2026, Regents of the University of Texas. + + ACL2 comes with ABSOLUTELY NO WARRANTY. This is free software and + + you are welcome to redistribute it under certain conditions. For + + details, see the LICENSE file distributed with ACL2. + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ An exception is the special value, [47m"none"[0m, which is treated as case-insensitive (so it can similarly be [47m"None"[0m, [47m"NONE"[0m, etc.). In that case, the third line of the original banner is omitted entirely.") (state (programming) "The von Neumannesque ACL2 state object Note: If you are interested in programming with state, see [programming-with-state] after reading the information below. The ACL2 state object is used extensively in programming the ACL2 system, and has been used in other ACL2 programs as well. However, most users, especially those interested in specification and verification (as opposed to programming [3mper se[0m), need not be aware of the role of the state object in ACL2, and will not write functions that use it explicitly. We say more about this point at the end of this documentation topic. The ACL2 state object is an example of a single-threaded object or [stobj]. ACL2 allows the user to define new single-threaded objects. Generally, ACL2 may need to access the ACL2 state but should not (cannot) change it except via a certain set of approved functions such as [47m[defun][0m and [47m[defthm][0m. If you need a state-like object to which you have complete rights, you may want a [stobj]. Key to the idea of our [47mstate[0m is the notion of single-threadedness. For an explanation, see [stobj]. The upshot of it is that [47mstate[0m is a variable symbol with severe restrictions on its use, so that it can be passed into only certain functions in certain slots, and must be returned by those functions that ``modify'' it. Henceforth, we do not discuss single-threaded objects in general (which the user can introduce with [47m[defstobj][0m and [47m[defabsstobj][0m) but one in particular, namely ACL2's [47mstate[0m object. The [3mglobal table[0m is perhaps the most visible portion of the state object. Using the interface functions [47m@[0m and [47massign[0m, a user may bind global variables to the results of function evaluations (much as an Nqthm user exploits the Nqthm utility [47mr-loop[0m). See [@], and see [assign]. A particularly interesting global is [47m'current-acl2-world[0m, whose value is the ACL2 logical [world]. ACL2 supports several facilities of a truly von Neumannesque state machine character, including file [io] and global variables. Logically speaking, the state is a true list of the 14 components described below. There is a ``current'' state object at the top-level of the ACL2 [command] loop. This object is understood to be the value of what would otherwise be the free variable [47mstate[0m appearing in top-level input. When any [command] returns a state object as one of its values, that object becomes the new current state. But ACL2 provides von Neumann style speed for state operations by maintaining only one physical (as opposed to logical) state object. Operations on the state are in fact destructive. This implementation does not violate the applicative semantics because we enforce certain draconian syntactic rules regarding the use of state objects. For example, one cannot ``hold on'' to an old state, access the components of a state arbitrarily, or ``modify'' a state object without passing it on to subsequent state-sensitive functions. Every routine that uses the state facilities (e.g. does [io], or calls a routine that does [io]), must be passed a ``state object.'' And a routine must return a state object if the routine modifies the state in any way. Rigid syntactic rules governing the use of state objects are enforced by the function [47mtranslate[0m, through which all ACL2 user input first passes. State objects can only be ``held'' in the formal parameter [47mstate[0m, never in any other formal parameter and never in any structure (except as a state value in a [multiple-value] return). State objects can only be accessed with the primitives we specifically permit. Thus, for example, one cannot ask, in code to be executed, for the length of [47mstate[0m or the [47m[car][0m of [47mstate[0m. In the statement and proof of theorems, there are no syntactic rules prohibiting arbitrary treatment of state objects. Logically speaking, a state object is a true list whose members are as follows: [47mOpen-input-channels[0m, an alist with keys that are symbols in package [47m"ACL2-INPUT-CHANNEL"[0m. The value ([47m[cdr][0m) of each pair has the form [47m((:header type file-name open-time) . elements)[0m, where [47mtype[0m is one of [47m:character[0m, [47m:byte[0m, or [47m:object[0m and [47melements[0m is a list of things of the corresponding [47mtype[0m, i.e. characters, integers of type [47m(mod 255)[0m, or lisp objects in our theory. [47mFile-name[0m is a string. [47mOpen-time[0m is an integer. See [io]. [47mOpen-output-channels[0m, an alist with keys that are symbols in package [47m"ACL2-OUTPUT-CHANNEL"[0m. The value of a pair has the form [47m((:header type file-name open-time) . current-contents)[0m. See [io]. [47mGlobal-table[0m, an alist associating symbols (to be used as ``global variables'') with values. See [@], and see [assign]. [47mIdates[0m, a list of dates and times, used to implement the function [47mprint-current-idate[0m, which prints the date and time. [47mAcl2-oracle[0m, a list of objects, used for example to implement the functions that let ACL2 report how much time was used, but inaccessible to the user. See [47m[read-ACL2-oracle][0m and also see [47m[with-prover-time-limit][0m. [47mFile-clock[0m, an integer that is increased on every file opening and closing, and is used to maintain the consistency of the [47m[io][0m primitives. [47mReadable-files[0m, an alist whose keys have the form [47m(string type time)[0m, where [47m[string][0m is a file name and [47mtime[0m is an integer. The value associated with such a key is a list of characters, bytes, or objects, according to [47mtype[0m. The [47mtime[0m field is used in the following way: when it comes time to open a file for input, we will only look for a file of the specified name and [47mtype[0m whose time field is that of [47mfile-clock[0m. This permits us to have a ``probe-file'' aspect to [47mopen-file[0m: one can ask for a file, find it does not exist, but come back later and find that it does now exist. [47mWritten-files[0m, an alist whose keys have the form [47m(string type time1 time2)[0m, where [47m[string][0m is a file name, [47mtype[0m is one of [47m:character[0m, [47m:byte[0m or [47m:object[0m, and [47mtime1[0m and [47mtime2[0m are integers. [47mTime1[0m and [47mtime2[0m correspond to the [47mfile-clock[0m time at which the channel for the file was opened and closed. This field is write-only; the only operation that affects this field is [47mclose-output-channel[0m, which [47m[cons][0mes a new entry on the front. [47mRead-files[0m, a list of the form [47m(string type time1 time2)[0m, where [47m[string][0m is a file name and [47mtime1[0m and [47mtime2[0m were the times at which the file was opened for reading and closed. This field is write only. [47mWriteable-files[0m, an alist whose keys have the form [47m(string type time)[0m. To open a file for output, we require that the name, type, and time be on this list. [47mUser-stobj-alist[0m, an alist which associates user-defined single-threaded objects (see [stobj]) with their values. We recommend avoiding the use of the state object when writing ACL2 code intended to be used as a formal model of some system, for several reasons. First, the state object is complicated and contains many components that are oriented toward implementation and are likely to be irrelevant to the model in question. Second, there is currently not much support for reasoning about ACL2 functions that manipulate the state object, beyond their logical definitions. Third, the documentation about state is not as complete as one might wish. User-defined single-threaded objects offer the speed of [47mstate[0m while giving the user complete access to all the fields. See [stobj]. Again, if you are interested in programming with state see [programming-with-state]. Subtopics [Io] Input/output facilities in ACL2 [Programming-with-state] Programming using the von Neumannesque ACL2 [state] object [Random$] Obtain a random value [Set-state-ok] Allow the use of STATE as a formal parameter [W] The current ACL2 [world] [World] ACL2 property lists and the ACL2 logical database [Wormhole] [47m[ld][0m without [47m[state][0m --- a short-cut to a parallel universe") (state-global-let* (programming-with-state acl2-built-ins) "Bind [state] global variables See [programming-with-state] for requisite background on programming with the ACL2 [state]. Example Forms: (state-global-let* ((inhibit-output-lst *valid-output-names*)) (thm (equal x x))) (state-global-let* ((fmt-hard-right-margin 1000 set-fmt-hard-right-margin) (fmt-soft-right-margin 1000 set-fmt-soft-right-margin)) (mini-proveall)) General Form: (state-global-let* ((var1 form1) ; or (var1 form1 set-var1) ... (vark formk) ; or (vark formk set-vark) ) body) where: each [47mvari[0m is a variable; each [47mformi[0m is an expression whose value is a single ordinary object (i.e. not multiple values, and not [state] or any other [stobj]); [47mset-vari[0m, if supplied, is a function or macro such that [47m(set-vari _ state)[0m returns [47m[state][0m; and [47mbody[0m is an expression that evaluates to an [error-triple]. Each [47mformi[0m is evaluated in order, starting with [47mform1[0m, and with each such binding the state global variable [47mvari[0m is bound to the value of [47mformi[0m, sequentially in the style of [47m[let*][0m. More precisely, the meaning of this form is to perform the following actions, in order. 1. Set (in order) the global values of the indicated [state] global variables [47mvari[0m to the values of [47mformi[0m. Exception: This is skipped when [47mvari[0m is a built-in state global and [47mformi[0m is [47m(f-get-global 'vari state)[0m. 2. Execute [47mbody[0m. 3. Restore the [47mvari[0m to their previous values. 4. Return the [error-triple] produced by [47mbody[0m, where [47m[state][0m reflects the modifications of the preceding step. The restoration is guaranteed even in the face of aborts. The ``bound'' variables may initially be unbound in state and restoration means to make them unbound again. Still referring to the General Form above, we next discuss how the values are set and restored. Let [47mold-vali[0m be the value of state global variable [47mvari[0m at the time [47mvari[0m is about to be assigned the value of [47mformi[0m. We say that a ``setter is supplied'' for [47mvari[0m if [47mset-vari[0m is supplied, either explicitly as in the General Form above, or implicitly by being associated with [47mvari[0m in the value of the constant, [47m*state-global-let*-untouchable-alist*[0m (whose definition appears at the end of this topic). If no setter is supplied then [47mvari[0m is set or restored to a value [47m<val>[0m by evaluating [47m(f-put-global 'vari <val> state)[0m. However, if a setter [47mset-vari[0m is supplied, then the form evaluated will instead be [47m(set-vari <val> state)[0m. Having a setter supplied is particularly useful if [47mvari[0m is [untouchable], since the call above of [47m[f-put-global][0m is illegal. However, the use of [47m*state-global-let*-untouchable-alist*[0m (mentioned above) avoids the need for supplying [47mset-vari[0m explicitly for certain built-in [untouchable] state global variables, [47mvari[0m. Note that the scope of the bindings of a [47mstate-global-let*[0m form is the body of that form. This may seem obvious, but to drive the point home, let's consider the following example (see [set-print-base] and see [set-print-radix]). ACL2 !>(state-global-let* ((print-base 16 set-print-base) (print-radix t set-print-radix)) (mv nil 10 state)) 10 ACL2 !> Why wasn't the result printed as [47m#xA[0m? The reason is that the result was printed after evaluation of the entire form had completed. If you want to see [47m#xA[0m, do the printing in the scope of the bindings, for example as follows. ACL2 !>(state-global-let* ((print-base 16 set-print-base) (print-radix t set-print-radix)) (pprogn (fms "~x0~%" (list (cons #\0 10)) *standard-co* state nil) (mv nil 10 state))) #xA 10 ACL2 !> Finally, as promised above, here is the definition of the constant that maps certain built-in untouchable variables to setters. [31;1mDefinition: [0m<*state-global-let*-untouchable-alist*> (defconst *state-global-let*-untouchable-alist* '((abbrev-evisc-tuple . set-abbrev-evisc-tuple-state) (compiler-enabled . set-compiler-enabled) (current-package . set-current-package-state) (fmt-hard-right-margin . set-fmt-hard-right-margin) (fmt-soft-right-margin . set-fmt-soft-right-margin) (gag-mode-evisc-tuple . set-gag-mode-evisc-tuple-state) (inhibit-output-lst . set-inhibit-output-lst-state) (inhibited-summary-types . set-inhibited-summary-types-state) (ld-evisc-tuple . set-ld-evisc-tuple-state) (ppr-flat-right-margin . set-ppr-flat-right-margin) (print-base . set-print-base) (print-case . set-print-case) (print-length . set-print-length) (print-level . set-print-level) (print-lines . set-print-lines) (print-right-margin . set-print-right-margin) (proofs-co . set-proofs-co-state) (serialize-character . set-serialize-character) (serialize-character-system . set-serialize-character-system) (standard-co . set-standard-co-state) (temp-touchable-fns . set-temp-touchable-fns) (temp-touchable-vars . set-temp-touchable-vars) (term-evisc-tuple . set-term-evisc-tuple-state)))") (stating-and-proving-lemmas-about-loop$s (loop$) "Stating and proving theorems about [47mloop$[0ms In this topic we give some advice about how to state and prove theorems involving [47mloop$[0ms, especially stating lemmas that are intended to rewrite [47mloop$[0m statements and proving theorems about [47mloop$[0m statements inductively. Name [47mLoop$[0ms When Memorable Names Come to Mind Just because you can write iterative computations inline, don't get carried away! If you can think of a good name for the concept implemented by a [47mloop$[0m statement, use [47mdefun[0m to define that name. This is especially the case if you intend to reason about that [47mloop$[0m statement or to write more than one instance of it. For example, rather than write instances of (loop$ for a in x as b in y sum (* a b)) it is better to define [47m(dot-product x y)[0m with that [47mloop$[0m as its body and then write calls of [47mdot-product[0m and lemmas about [47mdot-product[0m rather than that [47mloop$[0m. Basically, names are good as long as you can remember them. They give you a place to hang lemmas and the lemmas match without you having to think about how lambda objects rewrite, local variables, etc. Not all [47mloop$[0ms compute concepts with obvious, memorable names, but just because you can write ``anonymous'' iterations doesn't mean you should! Generalizing the Initial Values Let's start with the most common issue raised by any inductive proof: the conjecture to be proved must be general enough to permit the provision of an appropriate inductive hypothesis. Consider how you would prove the conjecture below after defining [47mrev[0m and [47mrev1[0m. (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) (defun rev1 (x a) (if (endp x) a (rev1 (cdr x) (cons (car x) a)))) (defthm rev1-is-rev (equal (rev1 x nil) (rev x))) The experienced ACL2 user would not attempt to prove [47mrev1-is-rev[0m by induction because the [47mnil[0m prevents the provision of an appropriate induction hypothesis. Instead, the user would first prove a generalization obtained by replacing that [47mnil[0m by a variable and ``explaining'' the role of that variable on the right-hand side. (defthm rev1-is-rev-generalized (equal (rev1 x a) (append (rev x) a))) The proof of the generalized theorem succeeds (though the prover must ``discover'' and then prove that [47mappend[0m is associative). With that theorem available, the proof of [47mrev1-is-rev[0m is trivial, given that [47mnil[0m is the right-identity for [47mappend[0m on true-lists and that [47mrev[0m returns a true-list. Now consider defining reverse with a [47mdo[0m [47mloop$[0m. (defun rev-loop$ (x) (loop$ with tail = x with a = nil do (if (endp tail) (return a) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail)))))) The experienced ACL2 user would not attempt to prove that [47m(rev-loop$ x)[0m is [47m(rev x)[0m by induction! The problem is the same as before: the [47mnil[0m initialization of the iterative variable [47ma[0m in the [47mdo[0m [47mloop$[0m does not permit an appropriate inductive hypothesis. Instead, the user needs to prove a more general theorem that cannot be stated in terms of [47mrev-loop$[0m because that [47mnil[0m is built into the definition. We need to lift the [47mloop$[0m out of the definition, generalize it, and prove a theorem about the generalized [47mloop$[0m. Ideally we'd prove (defthm rev-loop$-is-rev-generalized (equal (loop$ with tail = x with a = a do (if (endp tail) (return a) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail))))) (append (rev x) a))). ACL2's prover can derive induction schemes suggested by some [47mloop$[0m statements, just as it can from some calls of recursive functions. Because both iterative variables, [47mtail[0m and [47ma[0m, are initialized to variables, the [47mDO[0m [47mloop$[0m above suggests an appropriate induction. But inductions for [47mloop$[0ms raise some new issues as well as some traditional ones. ACL2 will prove the lemma above, if the associativity of [47mappend[0m has first been proved explicitly as a rewrite rule. (The presence of the [47mloop$[0m confuses the heuristics that enable the prover to ``discover'' the associativity of [47mappend[0m.) [31;1mLesson 1[0m: If a [47mloop$[0m has iterative variables initialized to non-variables, generalize them before expecting an induction to work! If the [47mloop$[0m is buried in a definition you'll have to lift the [47mloop$[0m out of the definition to generalize it and prove a theorem about the generalized [47mloop$[0m. Normal Forms in [47mLoop$[0m Bodies The lemma above, [47mrev-loop$-is-rev-generalized[0m, is adequate to subsequently prove the main theorem, (defthm rev-loop$-is-rev (equal (rev-loop$ x) (rev x))). But as stated, [47mrev-loop$-is-rev-generalized[0m is fragile because it mentions the non-recursively defined function [47mendp[0m. To explain this remark we need to walk through the proof of the main theorem. Recall that the prover always expands enabled functions that are not explicitly recursive. And [47mrev-loop$[0m is not explicitly recursive. So the proof attempt of [47mrev-loop$-is-rev[0m will expand the call of [47mrev-loop$[0m and produce Goal' (equal (loop$ with tail = x with a = nil do (if (endp tail) (return a) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail))))) (rev x)) If the [47mloop$[0m term above is immediately rewritten, our generalized lemma would fire and reduce the goal to Goal'' (equal (append (rev x) nil) (rev x)) and the proof would be completed as before with the right-identity rule. Indeed, this is what happens in this particular case, but the reason it works is completely unrelated to [47mloop$[0ms! Our generalized lemma has no hypotheses --- it is an unconditional rewrite rule that is applied early in the ``preprocessing'' phase of simplification. Let's suppose the generalized lemma did have some hypotheses or otherwise failed to apply during preprocessing. You can cause this to happen by restating the generalized lemma and the main theorem to have the (unnecessary but easily dealt with) hypothesis [47m(true-listp x)[0m. The proof of the conditional generalized lemma still goes through, but the proof of the conditional main theorem fails because the generalized lemma never fires! The reason it never fires is that it is not tried during prepreprocessing (because preprocessing doesn't deal with conditional rules because preprocessing doesn't support backchaining) and [47mGoal'[0m above enters the rewriter, which [3mrewrites every subterm of the term before trying to apply rules to the term itself[0m. In particular, before the rewriter tries to apply our generalized rule it rewrites the subterms of the [47mloop$[0m statement, including the body. (Technically, it rewrites the [47mlambda[0m object in the translation of the [47mloop$[0m. See [rewrite-lambda-object].) This transforms (loop$ with tail = x with a = nil do (if (endp tail) (return a) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail))))) to (loop$ with tail = x with a = nil do (if (consp tail) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail))) (return a))) because [47m(endp x)[0m expands to [47m(not (consp x))[0m and the branches of the [47mif[0m are swapped to eliminate the [47mnot[0m. After this rewrite, our generalized lemma no longer matches. [31;1mLesson 2[0m: Do not prove rewrite rules that target [47mloop$[0m statements containing terms in non-normal form! That is, as with all other rewrite rules, make sure your target is normalized under your intended rewrite regime. So for example, in addition to watching out for non-recursive functions in the body, be alert for things like expressions that are rearranged by associativity and commutativity rules. You wouldn't write a rewrite rule containing a subterm like [47m(append (append a b) c)[0m if you're right-associating [47mappend[0m nests, nor would you include a subterm like [47m(+ x 1)[0m if you're normalizing arithmetic expressions (in this case to [47m(+ 1 x)[0m). So don't use such non-normal terms in lemmas about [47mloop$[0ms! The entire robust script for the [47mrev-loop$[0m proof is given below. (defun rev (x) (if (endp x) nil (append (rev (cdr x)) (list (car x))))) (defun rev-loop$ (x) (loop$ with tail = x with a = nil do (if (endp tail) (return a) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail)))))) (defthm assoc-of-append (equal (append (append a b) c) (append a (append b c)))) (defthm rev-loop$-is-rev-generalized (equal (loop$ with tail = x with a = a do (if (consp tail) (progn (setq a (cons (car tail) a)) (setq tail (cdr tail))) (return a))) (append (rev x) a))) (defthm rev-loop$-is-rev (equal (rev-loop$ x) (rev x))) The script is robust in the sense that even if you conditionalize the generalized lemma with a hypothesis that can be relieved in the main theorem the lemma will fire and rewrite the [47mloop$[0m exposed when [47mrev-loop$[0m is expanded. Note that the [47mloop$[0m was written with [47m(endp tail)[0m in the [47mdefun[0m of [47mrev-loop$[0m but lemma deals with the normalized form of that body. Here is another example, this one involving a [47mdo[0m loop without any [47mWITH[0m clauses. That in itself causes no special proof problems, but as noted in [do-loop$], it necessitates the use of a stobj in the body and that raises issues similar to those just mentioned. So below we introduce a stobj, [47mst[0m, with one field, [47mfld[0m. We define [47m[warrant][0ms for both [47mfld[0m and [47mupdate-fld[0m, and then we define a function, [47mstobj-mem[0m, that uses a [47mdo[0m loop to determine whether a given element occurs in the field, simultaneously shortening the list in the field so that its [47mcar[0m is the element in question. Here is the setup. (defstobj st fld) (defwarrant fld) (defwarrant update-fld) (defun stobj-mem (e st) (declare (xargs :stobjs (st) :guard (true-listp (fld st)))) (loop$ do :values (st) :guard (and (stp st) (true-listp (fld st))) :measure (acl2-count (fld st)) (if (endp (fld st)) (return st) (if (equal e (car (fld st))) (return st) (setq st (update-fld (cdr (fld st)) st)))))) Note that there is no [47mWITH[0m clause but the size of [47m(fld st)[0m is decreasing. Suppose we want to prove that after running [47m(stobj-mem e st)[0m on proper input, the final value of [47mfld[0m is equal to [47m(member e (fld st))[0m. The desired formal statement is (defthm stobj-mem-correct (implies (and (stp st) (true-listp (fld st)) (warrant fld update-fld)) (let ((st1 (stobj-mem e st))) (and (stp st1) (equal (fld st1) (member e (fld st)))))) :hints ...) Note that in the theorem we use [47mst1[0m to denote the final value of the stobj whose initial value is [47mst[0m. We have to provide the warrants for the accessor and updater used in the body of the [47mloop$[0m. This theorem is a little tricky to prove because we're proving a conjunction and after the [47m(stobj-mem e st)[0m and the [47m(stp st)[0m expand we get several conjectures, each of which requires induction. It is simply easier to prove that the [47mloop$[0m in [47mstobj-mem[0m has the desired property and then use that lemma. So we first prove: (defthm stobj-mem-correct-lemma (implies (and (stp st) (true-listp (fld st)) (warrant fld update-fld)) (let ((st1 (loop$ do :values (st) :guard (and (stp st) (true-listp (fld st))) :measure (acl2-count (fld st)) (if (consp (fld st)) (if (equal e (car (fld st))) (return st) (setq st (update-fld (cdr (fld st)) st))) (return st))))) (and (stp st1) (equal (fld st1) (member e (fld st))))))) But note that we expanded the [47mendp[0m in the statement of this lemma because [47mendp[0m is built-in in a way that causes it often to expand even when disabled (as is actually noted in a warning message if we'd left the [47mendp[0m in place). We also normalized the resulting [47m(if (not (consp (fld st))) ...)[0m as explained in Lesson 2 above. Now we'd like to prove the desired theorem about [47mstobj-mem[0m, expecting that function to expand and then the lemma to hit it and complete the proof. But that won't work without a little more help! The problem is that the lemma mentions [47mstp[0m, [47mfld[0m, and [47mupdate-fld[0m in its left-hand side and those are non-recursively defined functions that will expand. So to make the lemma match the rewritten main theorem we must disable those three functions. (defthm stobj-mem-correct (implies (and (stp st) (true-listp (fld st)) (warrant fld update-fld)) (let ((st1 (stobj-mem e st))) (and (stp st1) (equal (fld st1) (member e (fld st)))))) :hints (("Goal" :in-theory (disable stp fld update-fld)))) The Secret [47mSetq[0m Problem Another issue that comes up when posing lemmas about [47mloop$[0ms is called the [3msecret [47msetq[0m[3m problem[0m and is best illustrated by example. Define the following function. (defun secret-setq-problem (k x) (loop$ with x = x with j = 0 do (cond ((endp x) (return 'bad)) ((equal j k) (return 'good)) (t (progn (setq x (cdr x)) (setq j (+ 1 j))))))) The function counts [47mj[0m up from [47m0[0m until it is equal to [47mk[0m, while [47mcdr[0ming [47mx[0m. It returns [47mgood[0m if [47mj[0m reaches [47mk[0m before the list is exhausted, and returns [47mbad[0m otherwise. Thus, this is a theorem. (defthm secret-setq-problem-main (implies (and (natp k) (< k (len x))) (equal (secret-setq-problem k x) 'good))) While [47msecret-setq-problem-main[0m is provable by ACL2, it should be clear from Lessons 1 and 2 above that we first need to prove a lemma about the generalized, normalized loop$. Here is a candidate lemma, which is proved by ACL2. (defthm secret-setq-problem-lemma (implies (and (natp j) (natp k) (< k (+ j (len x))) (<= j k)) (equal (loop$ with x = x with j = j do (if (consp x) (if (equal j k) (return 'good) (progn (setq x (cdr x)) (setq j (+ 1 j)))) (return 'bad))) 'good))) Following Lesson 1, we generalized the initial value of [47mj[0m, which was [47m0[0m, to [47mj[0m, and we added the hypotheses that [47mj[0m is a natural less than or equal to [47mk[0m. We generalized the [47m(< k (len x))[0m which we see in the main theorem to [47m(< k (+ j (len x)))[0m. This accommodates the arbitrary initial [47mj[0m and simplifies to [47m(len x)[0m when [47mj[0m is [47m0[0m. Furthermore, as [47mj[0m goes up and [47mx[0m gets shorter, their sum stays fixed, which is necessary if the generalized hypothesis is going to survive induction. Following Lesson 2, we normalized the body. We replaced the [47m(endp x)[0m by [47m(not (consp x))[0m and normalized the resulting [47mIF[0m nest. The lemma is proved automatically by ACL2, using the induction suggested by the [47mloop$[0m. However, the attempt to prove the main theorem above will fail! The lemma doesn't fire because the [47mloop$[0m target still doesn't match. (Note: we could forget about the lemma firing automatically. Instead, we could give a [47m:hint[0m that disables the lemma and [47m:use[0ms the instance of it with [47mj[0m replaced by [47m0[0m. That succeeds. But it is valuable for us to explore why it didn't work as a rewrite rule.) Sometimes to debug a failed proof it helps to compare the term that a lemma targets with its intended target in the checkpoint of the failed proof. This is especially true for [47mloop$[0ms because their translations are so different from their outward appearance. (See the sections titled ``Semantics'' in [for-loop$] and [do-loop$].) The following use of the [47m:[0m[47m[pr][0m command shows our lemma's true form. It is the left-hand side, [47mLhs[0m, we are interested in because it is the target pattern of the rewrite rule. ACL2 !>:pr secret-setq-problem-lemma Rune: (:REWRITE SECRET-SETQ-PROBLEM-LEMMA) Enabled: T Hyps: (AND (NATP J) (NATP K) (< K (+ J (LEN X))) (<= J K)) Equiv: EQUAL Lhs: (DO$ (LAMBDA$ (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'X ALIST)))) (LIST (CONS 'X X) (CONS 'J J) (CONS 'K K)) (LAMBDA$ (ALIST) (IF (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST))) (IF (EQUAL (CDR (ASSOC-EQ-SAFE 'J ALIST)) (CDR (ASSOC-EQ-SAFE 'K ALIST))) (LIST :RETURN 'GOOD (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))) (LIST NIL NIL (LIST (CONS 'X (CDDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (+ 1 (CDR (ASSOC-EQ-SAFE 'J ALIST)))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))) (LIST :RETURN 'BAD (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))))) (LAMBDA$ (ALIST) (LIST NIL NIL (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))) '(NIL) NIL) Rhs: 'GOOD Backchain-limit-lst: NIL Subclass: BACKCHAIN Loop-stopper: NIL The actual [47mdo$[0m term term you'll see in the checkpoint of the failed proof attempt is: (DO$ (LAMBDA$ (ALIST) (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'X ALIST)))) (LIST (CONS 'X X) '(J . 0) (CONS 'K K)) (LAMBDA$ (ALIST) (IF (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST))) (IF (EQUAL (CDR (ASSOC-EQ-SAFE 'J ALIST)) (CDR (ASSOC-EQ-SAFE 'K ALIST))) (LIST :RETURN 'GOOD (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'J ALIST))))) (LIST NIL NIL (LIST (CONS 'X (CDDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (+ 1 (CDR (ASSOC-EQ-SAFE 'J ALIST)))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))) (LIST :RETURN 'BAD (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))))) (LAMBDA$ (ALIST) (LIST NIL NIL (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST))) (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST))) (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))) '(NIL) NIL) Note that the [47mLhs[0m matches the actual term, when [47mJ[0m is instantiated with [47m0[0m, [3mexcept[0m in one place: the alist constructed in the [47m(LIST :RETURN 'GOOD ...)[0m triple binds [47m'K[0m to the value of [47m'K[0m in [47mLhs[0m but binds [47m'K[0m to the value of [47m'J[0m in the actual term. This happens because the actual term was rewritten under the assumption that the [47mIF[0m test equating the value of [47m'J[0m to the value of [47m'K[0m, and the rewriter substituted the value of [47m'J[0m for that of [47m'K[0m because of term ordering. The ACL2 pattern matching routine does not take account of tests. We could possibly fix this problem by changing how ACL2 stores lemmas or how the pattern matcher works. But such changes could have far reaching consequences across the entire ACL2 regression suite, so we have made no such changes. Absent such changes, it's incumbent on the user to phrase the rewrite rule appropriately. The question is, ``How can you make that particular [47m'K[0m in [47mLhs[0m be [47m'J[0m?'' One way would be to rephrase the rewrite rule by using the [47mDO$[0m term from the checkpoint in place of the [47mloop$[0m statement we wrote in [47msecret-setq-problem-lemma[0m. Another way to accomplish the same effect is to rewrite the [47mloop$[0m statement as shown below. (defthm secret-setq-problem-lemma (implies (and (natp j) (natp k) (< k (+ j (len x))) (<= j k)) (equal (loop$ with x = x with j = j with k = k ; ``new'' var do (if (consp x) (if (equal j k) (progn (setq k j) ; new setq! (return 'good)) (progn (setq x (cdr x)) (setq j (+ 1 j)))) (return 'bad))) 'good))) You can use [47m:[0m[47m[tcp][0m to confirm that the translation of the above [47mloop$[0m matches the actual term in the checkpoint. Note that the inclusion of the new ``[47mwith k = k[0m'' does not add any new subterms to the translation, it merely allows assignment to a previously used but never assigned variable. The order of the [47mwith[0m clauses determines the order of the alists being constructed, so pay attention to where [47m'k[0m is bound in the alists. Also note that the new [47msetq[0m does not add any new subterms to the translation; it just affects the final value of [47m'k[0m on that branch of the [47mif[0m tree. Finally note that we phrase the [47mloop$[0m this way in the lemma [3mwithout changing how we write the [47mloop$[0m[3m in the [47mdefun[0m[3m.[0m Writing the [47mloop$[0m this way in the [47mdefun[0m would add an unnecessary [47msetq[0m in the Common Lisp execution. But there is no need to change how we write the [47mloop$[0m in the defun. This lemma matches what comes up when we prove things about the [47mloop$[0m in the [47mdefun[0m. Because this matching problem can repaired by adding an unnecessary [47msetq[0m in the lemma, we call this the ``secret [47msetq[0m problem.'' [31;1mLesson 3:[0m If the left-hand side of a rewrite rule contains an [47mloop$[0m with an [47mif[0m in the body, remember the secret [47msetq[0m problem. More practically, if a [47mloop$[0m lemma you've proved fails to rewrite its target, compare the output of [47m:[0m[47mpr[0m, specifically the [47mLhs[0m, to the intended target printed in the checkpoint, and remember the secret [47msetq[0m problem. The Hidden Hypothesis Problem Another issue you may occasionally confront when dealing with inductions suggested by [47mdo[0m [47mloop$[0ms is indicated when the prover fails to prove the measure conjecture even though you ``know'' it is provable. To explain, we have to explain a little about how induction suggested by [47mdo[0m [47mloop$[0ms are done. From every [47mdo[0m [47mloop$[0m we can derive a proposed recursive function definition. When the prover sees a [47mdo[0m [47mloop$[0m in a conjecture that it has decided requires inductions, it generates that derived function, does an induction analysis for it, and adds any suggestions it gets to the set of candidate inductions to consider. However, the derived function may not terminate ``normally.'' Recall that [47m[do$][0m checks that the measure goes down before each iteration and returns a default value if that check fails. Thus, to justify the induction suggested by the generated function the proof obligations include those that establish that the measure decreases [3munder the tests leading to further iterations in the [47mloop$[0m[3m body[0m. Those tests are not always sufficient to guarantee termination! If the [47mloop$[0m came from a guard verified function definition, termination was proved. But it was proved as part of guard verification. Remember the main purpose of guards in [47mloop$[0ms: to allow us to execute the [47mloop$[0m as a Common Lisp [47mloop[0m. But that execution only happens when we know guards hold. But [47mloop$[0ms seen by the prover may not come from guard verified statements and, besides, guards are stripped out of conjectures to be proved because they're irrelevant to the logical meaning. However, it is logically valid to condition the induction-time measure conjectures on hypotheses from the conjecture being proved --- and it is often ineffective to include all of those hypotheses. So ACL2's induction mechanism chooses some of the available hypotheses and may not choose enough. This is the ``hidden hypothesis problem.'' An example is below. The following function can be admitted and guard verified, meaning the termination obligation is proved as part of guard verification. (defun hidden-hyp-problem (lo j) (declare (xargs :guard (and (natp lo) (natp j) (<= lo j)))) (loop$ with j = j do :guard (and (natp lo) (natp j) (<= lo j)) (if (equal lo j) (return 'good) (setq j (- j 1))))) Since since [47mlo[0m and [47mj[0m are both natural numbers and [47mj[0m is (weakly) above [47mlo[0m and is decremented on iteration, [47mj[0m will eventually reach [47mlo[0m and the [47mloop$[0m will stop. The derived recursive function corresponding to this [47mloop$[0m, which we'll call [47mderived-fn[0m here, is (defun derived-fn (lo j) (if (equal lo j) 'good (derived-fn lo (- j 1)))). That derived function doesn't necessarily terminate. Now let's try to prove that the [47mloop$[0m always returns [47m'good[0m. Note that it doesn't matter if we include guards in the conjecture or not. They're logically irrelevant and will be eliminated. However, the following proof attempt fails. The prover chooses to induct as suggested by the [47mdo[0m [47mloop$[0m. The induction scheme selected is shown. ACL2 !>(defthm hidden-hyp-problem-main (implies (and (natp lo) (natp j) (<= lo j)) (equal (loop$ with j = j do :guard (and (natp lo) (natp j) (<= lo j)) (if (equal lo j) (return 'good) (setq j (- j 1)))) 'good))) ... This suggestion was produced using the :induction rule DO$. If we let (:P J LO) denote *1 above then the induction scheme we'll use is (AND (IMPLIES (AND (NOT (EQUAL LO J)) (:P (+ -1 J) LO) (INTEGERP J) (<= 0 J)) (:P J LO)) (IMPLIES (AND (NOT (EQUAL LO J)) (< (+ -1 J) 0) (INTEGERP J) (<= 0 J)) (:P J LO)) (IMPLIES (AND (NOT (EQUAL LO J)) (NOT (INTEGERP (+ -1 J))) (INTEGERP J) (<= 0 J)) (:P J LO)) (IMPLIES (AND (EQUAL LO J) (INTEGERP J) (<= 0 J)) (:P J LO)) (IMPLIES (AND (INTEGERP J) (<= 0 J) (NOT (EQUAL LO J))) (L< (LEX-FIX (ACL2-COUNT (+ -1 J))) (LEX-FIX (ACL2-COUNT J))))). Note that one or more measure conjectures included in the scheme above justify this induction if they are provable. When applied to the goal at hand the above induction scheme produces six nontautological subgoals. ... The first four proof obligations, which are all proved by the prover, implicitly include the hypotheses that [47mLO[0m is a natural below [47mJ[0m because they're hypotheses in the four conclusions, [47m(:P J LO)[0m. But the last proof obligation has no hypotheses about [47mLO[0m other than the test in the body of the [47mloop$[0m, [47m(NOT (EQUAL LO J))[0m. This proof obligation is not a theorem and the proof attempt will fail. If the prover had just generated the measure conjecture from the [47mderived-fn[0m the last proof obligation would be even more inadequate! (IMPLIES (NOT (EQUAL LO J)) (L< (LEX-FIX (ACL2-COUNT (+ -1 J))) (LEX-FIX (ACL2-COUNT J)))). But we see that the prover actually augmented the hypothesis from the body with two literals it assumed were relevant from the conjecture being proved, namely [47m(INTEGERP J)[0m and [47m(<= 0 J)[0m. (The legality of such augmentation is illustrated by the book [47mprojects/apply/justification-of-do-induction.lisp[0m.) However, it did not include any facts about [47mLO[0m other than the test in the [47mloop$[0m body. This is a manifestation of the hidden hypothesis problem. In this case, we wish it had included [47m(NATP LO)[0m and [47m(<= LO J)[0m. (One can regard this as a heuristic inadequacy, but enlarging the set of hypotheses can cause proofs to fail and we've been conservative in our heuristics for augmenting [47mdo[0m [47mloop$[0m inductions.) You can fix this by providing an [47m:induct[0m hint. The [47mloop$[0m statement in the hint below is exactly the [47mloop$[0m statement in the theorem except we've added the UPPERCASE text. This proof succeeds. (defthm hidden-hyp-problem-main (implies (and (natp lo) (natp j) (<= lo j)) (equal (loop$ with j = j do (if (equal lo j) (return 'good) (setq j (- j 1)))) 'good)) :hints (("Goal" :induct (loop$ with j = j do (IF (AND (NATP LO) (<= LO J)) (if (equal lo j) (return 'good) (setq j (- j 1))) (RETURN 'IRRELEVANT-BASE-CASE)))))) [31;1mLesson 4[0m: You can use [47mloop$[0m to provide induction hints and those [47mloop$[0ms don't have to be identical to ones in your goal theorem. In particular, your hint [47mloop$[0m might contain more case analysis than the [47mloop$[0ms in your conjecture. You can use this fact to overcome the hidden hypothesis problem. Note that the derived function from the [47mloop$[0m in the hint doesn't necessarily terminate either (because no mention is made that [47mJ[0m is a natural). But the induction-time proof obligation is provable because it is still augmented by [47m(INTEGERP J)[0m and [47m(<= 0 J)[0m as before. Avoiding Some Specially Defined Hint Functions Another lesson suggested by the example above is that you don't always have to define a recursive function to suggest certain inductions. Here is an example. Recall the function [47mrev1[0m from the beginning of this topic. Now define the functions that ``mark'' every element of a list and that check that every element is ``marked''. (defun mark-all (x) (if (consp x) (cons (list 'mark (car x)) (mark-all (cdr x))) nil)) (defun all-markedp (x) (if (consp x) (and (consp (car x)) (eq (car (car x)) 'mark) (all-markedp (cdr x))) t)). Now prove (thm (implies (all-markedp a) (all-markedp (rev1 (mark-all x) a)))) No induction suggested by the functions in this theorem is appropriate. The appropriate induction assumes the theorem for [47mx[0m replaced by [47m(cdr x)[0m and [47ma[0m replaced by [47m(cons (list 'mark (car x)) a)[0m. (This is an example of rippling as discussed by Bundy, Basin, Hutter and Ireland, in the book [3mRippling: Meta-Level Guidance for Mathematical Reasoning[0m, Cambridge University, UK, 2005. But ACL2's induction heuristics don't implement rippling.) We could, of course, define a recursive function that suggests the appropriate induction and provide it as a hint. But in this case we needn't define a new function. We can just use a [47mloop$[0m. (thm (implies (all-markedp a) (all-markedp (rev1 (mark-all x) a))) :hints (("Goal" :induct (loop$ with x = x with a = a do (if (consp x) (progn (setq a (cons (list 'mark (car x)) a)) (setq x (cdr x))) (return 'base-case)))))). Other Relevant :DOC Topics See [lp-section-11] of the [47mLoop$[0m Primer for a narrative of how we might solve a certain computational problem with a nest of two [47mFOR[0m [47mloop$[0m. We also show how we verify the guards and then prove that the [47mloop$[0m solution is equivalent to a recursive solution. In [lp-section-12] of the primer you'll find some exercises in proving theorems about [47mFOR[0m [47mLoop$[0ms (with answers in a Community Book). In [lp-section-16] you'll find a narrative of how we might go about proving a theorem about a [47mDO[0m [47mLoop$[0m. And in [lp-section-17] you'll find exercises in proving theorems about [47mDO[0m [47mLoop$[0ms (with answers in a Community Book).") (step-limit (pointers) "See [with-prover-step-limit].") (stobj (programming) "Single-threaded objects or ``von Neumann bottlenecks'' In ACL2, a ``single-threaded object'' is a data structure whose use is so syntactically restricted that only one instance of the object need ever exist and its fields can be updated by destructive assignments. Note: Novices are advised to avoid using single-threaded objects, perhaps instead using [std::defaggregate] or community book [47mbooks/data-structures/structures.lisp[0m. At the least, consider using [47m([0m[47m[set-verify-guards-eagerness][0m[47m 0)[0m to avoid [guard] verification. This topic introduces the notion of a ``stobj'', or single-threaded object. It concludes with a link to a tour that introduces the use of stobjs by way of examples. We recommend that you follow that link the first time you read about stobjs. Detailed reference documentation about stobjs may be found in the subtopics listed at the end below; in particular see [defstobj] and, for so-called abstract stobjs, see [defabsstobj]. As noted, a ``single-threaded object'' is a data structure whose use is so syntactically restricted that only one instance of the object need ever exist. Updates to the object must be sequentialized. This allows us to update its fields with destructive assignments without wrecking the axiomatic semantics of update-by-copy. For this reason, single-threaded objects are sometimes called ``von Neumann bottlenecks.'' From the logical perspective, a single-threaded object is an ordinary ACL2 object, e.g., composed of integers and conses. Logically speaking, ordinary ACL2 functions are defined to allow the user to ``access'' and ``update'' its fields. Logically speaking, when fields in the object, obj, are ``updated'' with new values, a new object, obj', is constructed. But suppose that by syntactic means we could ensure that there were no more references to the ``old'' object, obj. Then we could create obj' by destructively modifying the memory locations involved in the representation of obj. The syntactic means is pretty simple but draconian: the only reference to obj is in the variable named [47mOBJ[0m. The consequences of this simple rule are far-reaching and require some getting used to. For example, if [47mOBJ[0m has been declared as a single-threaded object name, then the following consequences ensue (but see the discussion at the end of this topic for some relaxations). * [47mOBJ[0m is a top-level global variable that contains the current object, obj. * If a function uses the formal parameter [47mOBJ[0m that is declared as a stobj, the only ``actual expression'' that can be passed into that slot is the variable [47mOBJ[0m, not merely a term that ``evaluates to an obj''; thus, such functions can only operate on the current object. So for example, instead of [47m(FOO (UPDATE-FIELD1 3 ST))[0m write [47m(LET ((ST (UPDATE-FIELD1 3 ST))) (FOO ST))[0m. And instead of [47m(MV X (LET ((ST (UPDATE-FIELD1 3 ST))) (FOO ST)))[0m write [47m(LET ((ST (UPDATE-FIELD1 3 ST))) (MV X ST))[0m. * The accessors and updaters have a formal parameter named [47mOBJ[0m, so by the rule just above, those functions can only be applied to the current object. The recognizer is the one exception to the rule: it may be applied either the [47mOBJ[0m or to an ordinary (non-stobj) object. * The ACL2 primitives, such as [47mCONS[0m, [47mCAR[0m and [47mCDR[0m, may not be applied to the variable [47mOBJ[0m. Thus, for example, obj may not be consed into a list (which would create another pointer to it) or accessed or copied via ``unapproved'' means. * The updaters return a ``new [47mOBJ[0m object'', i.e., obj'; thus, when an updater is called, the only variable which can hold its result is [47mOBJ[0m. * If a function calls an [47mOBJ[0m updater, it must return an [47mOBJ[0m object (either as the sole value returned, or in [47m(mv ... OBJ ...)[0m; see [mv]). * When a top-level expression involving [47mOBJ[0m returns an [47mOBJ[0m object, that object becomes the new current value of [47mOBJ[0m. There are other functional languages supporting single-threadedness, for example Haskell's ``monads'' and Clean's ``uniqueness type system''. Of course, ACL2 provides a theorem prover that can prove theorems that involve such constructs. Note that the syntactic restrictions noted above are enforced only when single-threaded objects are encountered directly in the top-level loop or are used in function definitions; the accessor and update functions for single-threaded objects may be used without restriction in formulas to be proved. Since function evaluation is sometimes necessary during proofs, ACL2 must be able to evaluate these functions on logical constants representing the object, even when the constant is not ``the current object.'' Thus, ACL2 supports both the efficient von Neumann semantics and the clean applicative semantics, and uses the first in contexts where execution speed is paramount and the second during proofs. [47m[Defstobj][0m and [47m[defabsstobj][0m [events] introduce stobjs. See [defstobj] for more details about stobjs. In particular, a relatively advanced notion of ``congruent stobjs'' is discussed there. The idea is to allow a stobj, [47mst2[0m, of the same ``shape'' as a given stobj, [47mst1[0m, to be used in place of [47mst1[0m. Other [47m[defstobj][0m keywords allow inlining and renaming of stobj accessors and updaters, and a [47m:non-executable[0m keyword can be used to defer or totally avoid creating a ``global'' stobj for the given stobj name. But we are getting ahead of ourselves. To start the stobj tour recommended earlier in this topic, see [stobj-example-1]. Subtopics [Add-global-stobj] Add a global [stobj] with a given name [Count-keys] Count the number of keys in association list [Declare-stobjs] Declaring a formal parameter name to be a single-threaded object [Defabsstobj] Define a new abstract single-threaded object [Defstobj] Define a new single-threaded object [Nested-stobjs] Using [stobj]s that contain stobjs [Nth-aliases-table] A [table] used to associate names for nth/update-nth printing [Remove-global-stobj] Remove a global [stobj] with a given name [Resize-list] List resizer in support of [stobj]s [Stobj-example-1] An example of the use of single-threaded objects [Stobj-example-1-defuns] The defuns created by the [47mcounters[0m stobj [Stobj-example-1-implementation] The implementation of the [47mcounters[0m stobj [Stobj-example-1-proofs] Some proofs involving the [47mcounters[0m stobj [Stobj-example-2] An example of the use of arrays in single-threaded objects [Stobj-example-3] Another example of a single-threaded object [Stobj-table] A [stobj] field mapping stobj names to stobjs [Swap-stobjs] Swap two congruent [stobj]s [Trans-eval-and-locally-bound-stobjs] [47m[Trans-eval][0m deals in global [stobj]s. [Trans-eval-and-stobjs] How user-defined [stobj]s are handled by [47m[trans-eval][0m [Update-nth-array] Update a stobj array [User-stobjs-modified-warnings] Interactions of [47m[trans-eval][0m with [stobj]s that violate applicative semantics [With-global-stobj] Operate on a global single-threaded object [With-local-state] Locally bind state [With-local-stobj] Locally bind a single-threaded object") (stobj-attachment-restrictions (ld) "Restrictions on attachments to supporters of [stobj] primitives This topic assumes that the reader is familiar with the basics of [47m[defattach][0m and [stobj]s (which are introduced by [47m[defstobj][0m and [47m[defabsstobj][0m). It concerns restrictions that disallow the use of [47m[defattach][0m on [3msupporters[0m of [stobj] recognizers and, for [47m[defabsstobj][0m, other stobj primitives that return the new stobj. Here, a [3msupporter[0m of a function symbol [47mf[0m is a function symbol used in the event that introduces [47mf[0m or, recursively, is a supporter of any of those function symbols. The [community-book] [47mbooks/system/tests/stobj-attach-unsoundness.lisp[0m, developed by Sol Swords, illustrates a soundness bug that existed through ACL2 Version_8.6. That book shows several ways that [47mnil[0m could be proved by using [47m[defattach][0m to falsify stobj invariants --- either the recognizer or, for abstract stobjs, the correspondence function. Those proofs of [47mnil[0m no longer succeed because of the following two restrictions now imposed by ACL2. 1. No supporter of a stobj recognizer is allowed to have an attachment. 2. For a [47m[defabsstobj][0m event, there must be a correspondence function whose supporters are not allowed to have attachments. The second of these criteria may be met by the [47mdefabsstobj[0m event in [3meither[0m of the following two ways. Keyword [47m:CORR-FN-EXISTS[0m has value [47mt[0m, and the value of [47m:CORR-FN[0m is a function symbol whose supporters are not allowed to have attachments. [31;1mOR[0m Keyword [47m:CORR-FN-EXISTS[0m has value [47mnil[0m (the default), and the supporters of any stobj primitive (the creator and exports, in addition to the recognizer) that returns the new stobj are not allowed to have attachments. Note that in the first sub-case, where keyword argument [47m:CORR-FN-EXISTS[0m has value [47mt[0m, the definition of the [47m:CORR-FN[0m symbol must be non-[local]. In the second sub-case, where keyword argument [47m:CORR-FN-EXISTS[0m has value [47mnil[0m, the notion of ``supporter'' of a stobj primitive is understood to include any function symbol that is a supporter of either the [47m:LOGIC[0m or the [47m:EXEC[0m function of that stobj primitive. We conclude with an optional remark (for those interested in theory) that discusses how the two sub-cases above are related. Namely, for an abstract stobj [47mst[0m, there is always an implicit correspondence function definable in terms of the primitives as follows. A concrete state [47mc_k[0m and abstract state [47ma_k[0m correspond if there are corresponding sequences of values [47mc_i[0m and [47ma_i[0m (i <= k) produced by corresponding applications of primitives, each of which returns the new stobj, as follows. * [47mc_0[0m and [47ma_0[0m are the initial concrete (foundational) and abstract copies of [47mst[0m, that is, produced by applying the [47m:EXEC[0m and [47m:LOGIC[0m creator of [47mst[0m, respectively. * For all i < k, there is a stobj export [47mfi[0m returning [47mst[0m with [47m:EXEC[0m function [47mfi_E[0m and [47m:LOGIC[0m function [47mfi_L[0m and well-guarded parameter lists [47mp_E[0m and [47mp_L[0m for [47mfi[0m, such that the following conditions hold. The lists [47mp_E[0m and [47mp_L[0m agree except in one position,which is where [47mst[0m is returned. The actual parameter at that positioni s[47mc_i[0m for [47mp_E[0m and [47ma_i[0m for [47mp_L[0m. Then [47mc_j[0m and [47ma_j[0m are returned by the respective calls of [47mfi_E[0m on [47mp_E[0m and [47mfi_L[0m on [47mp_L[0m. For theoretical details pertaining to this topic, see the long comment, ``Essay on the Correctness of Abstract Stobjs'', in the ACL2 source code.") (stobj-example-1 (stobj) "An example of the use of single-threaded objects Suppose we want to sweep a tree and (1) count the number of interior nodes, (2) count the number of tips and (3) keep a record of every tip we encounter that is an integer. We could use a single-threaded object as our ``accumulator''. Such an object would have three fields, one holding the number of nodes seen so far, one holding the number of tips, and one holding all the integer tips seen. The following event declares [47mcounters[0m to be a single-threaded object. (defstobj counters (NodeCnt :type integer :initially 0) (TipCnt :type integer :initially 0) (IntTipsSeen :type t :initially nil)) It has three fields, [47mNodeCnt[0m, [47mTipCnt[0m, and [47mIntTipsSeen[0m. (As always in ACL2, capitalization is irrelevant in simple symbol names, so the first name could be written [47mnodecnt[0m or [47mNODECNT[0m, etc.) Those are the name of the accessor functions for the object. The corresponding update functions are named [47mupdate-NodeCnt[0m, [47mupdate-TipCnt[0m and [47mupdate-IntTipsSeen[0m. If you do not like the default function names chosen above, there is a feature in the [47m[defstobj][0m event that allows you to specify other names. If you want to see the ACL2 definitions of all the functions defined by this event, look at [stobj-example-1-defuns]. If, after this event, we evaluate the top-level ``global variable'' [47mcounters[0m in the ACL2 read-eval-print loop we get: ACL2 !>counters <counters> Note that the value printed is ``[47m<counters>[0m''. Actually, the value of [47mcounters[0m in the logic is [47m(0 0 NIL)[0m. But ACL2 always prints single-threaded objects in this non-informative way because they are usually so big that to do otherwise would be unpleasant. Had you tried to evaluate the ``global variable'' [47mcounters[0m before declaring it a single-threaded object, ACL2 would have complained that it does not support global variables. So a lesson here is that once you have declared a new single-threaded object your top-level forms can reference it. In versions of ACL2 prior to Version 2.4 the only variable enjoying this status was [47mSTATE[0m. single-threaded objects are a straightforward generalization of the long-implemented von Neumann [47m[state][0m feature of ACL2. We can access the fields of [47mcounters[0m as with: ACL2 !>(NodeCnt counters) 0 ACL2 !>(IntTipsSeen counters) NIL and we can set the fields of [47mcounters[0m as with: ACL2 !>(update-NodeCnt 3 counters) <counters> ACL2 !>(NodeCnt counters) 3 Observe that when we evaluate an expression that returns a counter object, that object becomes the ``current value'' of [47mcounters[0m. Here is a function that ``converts'' the [47mcounters[0m object to its ``ordinary'' representation: (defun show-counters (counters) (declare (xargs :stobjs (counters))) (list (NodeCnt counters) (TipCnt counters) (IntTipsSeen counters))) Observe that we [3mmust[0m declare, at the top of the [47mdefun[0m, that we mean to use the formal parameter [47mcounters[0m as a single-threaded object! If we did not make this declaration, the body of [47mshow-counters[0m would be processed as though [47mcounters[0m were an ordinary object. An error would be caused because the accessors used above cannot be applied to anything but the single-threaded object [47mcounters[0m. If you want to know why we insist on this declaration, see [declare-stobjs]. When [47mshow-counters[0m is admitted, the following message is printed: Since SHOW-COUNTERS is non-recursive, its admission is trivial. We observe that the type of SHOW-COUNTERS is described by the theorem (AND (CONSP (SHOW-COUNTERS COUNTERS)) (TRUE-LISTP (SHOW-COUNTERS COUNTERS))). We used primitive type reasoning. (SHOW-COUNTERS COUNTERS) => *. The guard conjecture for SHOW-COUNTERS is trivial to prove. SHOW-COUNTERS is compliant with Common Lisp. The line above containing the ``=>'' is called the ``signature'' of [47mshow-counters[0m; it conveys the information that the first argument is the single-threaded object [47mcounters[0m and the only result is an ordinary object. Here is an example of another signature: (PROCESSOR * * COUNTERS) => (MV * COUNTERS) which indicates that the function [47mPROCESSOR[0m (which we haven't shown you) takes three arguments, the third of which is the [47mCOUNTERS[0m stobj, and returns two results, the second of which is the modified [47mCOUNTERS[0m. Returning to the admission of [47mshow-counters[0m above, the last sentence printed indicates that the [47m[guard][0m conjectures for the function were proved. When some argument of a function is declared to be a single-threaded object via the [47mxargs[0m, [47m:stobjs[0m, we automatically add (conjoin) to the guard the condition that the argument satisfy the recognizer for that single-threaded object. In the case of [47mshow-counters[0m the guard is [47m(countersp counters)[0m. Here is an example of [47mshow-counters[0m being called: ACL2 !>(show-counters counters) (3 0 NIL) This is what we would see had we set the [47mNodeCnt[0m field of the initial value of [47mcounters[0m to [47m3[0m, as we did earlier in this example. We next wish to define a function to reset the [47mcounters[0m object. We could define it this way: (defun reset-counters (counters) (declare (xargs :stobjs (counters))) (let ((counters (update-NodeCnt 0 counters))) (let ((counters (update-TipCnt 0 counters))) (update-IntTipsSeen nil counters)))) which ``successively'' sets the [47mNodeCnt[0m field to [47m0[0m, then the [47mTipCnt[0m field to [47m0[0m, and then the [47mIntTipsSeen[0m field to [47mnil[0m and returns the resulting object. However, the nest of [47mlet[0m expressions is tedious and we use this definition instead. This definition exploits a macro, here named ``[47mseq[0m'' (for ``sequentially'') which evaluates each of the forms given, binding their results successively to the stobj name given. (defun reset-counters (counters) (declare (xargs :stobjs (counters))) (seq counters (update-NodeCnt 0 counters) (update-TipCnt 0 counters) (update-IntTipsSeen nil counters))) This definition is syntactically identical to the one above, after macro expansion. Our definition of [47mseq[0m is shown below and is not part of native ACL2. (defmacro seq (stobj &rest rst) (cond ((endp rst) stobj) ((endp (cdr rst)) (car rst)) (t `(let ((,stobj ,(car rst))) (seq ,stobj ,@(cdr rst)))))) The signature printed for [47mreset-counters[0m is (RESET-COUNTERS COUNTERS) => COUNTERS. Here is an example. ACL2 !>(show-counters counters) (3 0 NIL) ACL2 !>(reset-counters counters) <counters> ACL2 !>(show-counters counters) (0 0 NIL) Here finally is a function that uses [47mcounters[0m as a single-threaded accumulator to collect the desired information about the tree [47mx[0m. (defun sweep-tree (x counters) (declare (xargs :stobjs (counters))) (cond ((atom x) (seq counters (update-TipCnt (+ 1 (TipCnt counters)) counters) (if (integerp x) (update-IntTipsSeen (cons x (IntTipsSeen counters)) counters) counters))) (t (seq counters (update-NodeCnt (+ 1 (NodeCnt counters)) counters) (sweep-tree (car x) counters) (sweep-tree (cdr x) counters))))) We can paraphrase this definition as follows. If [47mx[0m is an atom, then increment the [47mTipCnt[0m field of [47mcounters[0m and [3mthen[0m, if [47mx[0m is an integer, add [47mx[0m to the [47mIntTipsSeen[0m field, and return [47mcounters[0m. On the other hand, if [47mx[0m is not an atom, then increment the [47mNodeCnt[0m field of [47mcounters[0m, and [3mthen[0m sweep the [47mcar[0m of [47mx[0m and [3mthen[0m sweep the [47mcdr[0m of [47mx[0m and return the result. Here is an example of its execution. We have displayed the input tree in full dot notation so that the number of interior nodes is just the number of dots. ACL2 !>(sweep-tree '((((a . 1) . (2 . b)) . 3) . (4 . (5 . d))) counters) <counters> ACL2 !>(show-counters counters) (7 8 (5 4 3 2 1)) ACL2 !>(reset-counters counters) <counters> ACL2 !>(show-counters counters) (0 0 NIL) The [47mcounters[0m object has two integer fields and a field whose type is unrestricted. single-threaded objects support other types of fields, such as arrays. We deal with that in the [stobj-example-2]. But we recommend that you first consider the implementation issues for the [47mcounters[0m example (in [stobj-example-1-implementation]) and then consider the proof issues (in [stobj-example-1-proofs]). To continue the stobj tour, see [stobj-example-2].") (stobj-example-1-defuns (stobj) "The defuns created by the [47mcounters[0m stobj Consider the event shown in [stobj-example-1]: (defstobj counters (NodeCnt :type integer :initially 0) (TipCnt :type integer :initially 0) (IntTipsSeen :type t :initially nil)) Here is a complete list of the defuns added by the event. The careful reader will note that the [47mcounters[0m argument below is [3mnot[0m declared with the [47m:stobjs[0m [47mxarg[0m even though we insist that the argument be a stobj in calls of these functions. This ``mystery'' is explained below. (defun NodeCntp (x) ;;; Recognizer for 1st field (declare (xargs :guard t :verify-guards t)) (integerp x)) (defun TipCntp (x) ;;; Recognizer for 2nd field (declare (xargs :guard t :verify-guards t)) (integerp x)) (defun IntTipsSeenp (x) ;;; Recognizer for 3rd field (declare (xargs :guard t :verify-guards t) (ignore x)) t) (defun countersp (counters) ;;; Recognizer for object (declare (xargs :guard t :verify-guards t)) (and (true-listp counters) (= (length counters) 3) (NodeCntp (nth 0 counters)) (TipCntp (nth 1 counters)) (IntTipsSeenp (nth 2 counters)) t)) (defun create-counters () ;;; Creator for object (declare (xargs :guard t :verify-guards t)) (list '0 '0 'nil)) (defun NodeCnt (counters) ;;; Accessor for 1st field (declare (xargs :guard (countersp counters) :verify-guards t)) (nth 0 counters)) (defun update-NodeCnt (v counters) ;;; Updater for 1st field (declare (xargs :guard (and (integerp v) (countersp counters)) :verify-guards t)) (update-nth 0 v counters)) (defun TipCnt (counters) ;;; Accessor for 2nd field (declare (xargs :guard (countersp counters) :verify-guards t)) (nth 1 counters)) (defun update-TipCnt (v counters) ;;; Updater for 2nd field (declare (xargs :guard (and (integerp v) (countersp counters)) :verify-guards t)) (update-nth 1 v counters)) (defun IntTipsSeen (counters) ;;; Accessor for 3rd field (declare (xargs :guard (countersp counters) :verify-guards t)) (nth 2 counters)) (defun update-IntTipsSeen (v counters) ;;; Updater for 3rd field (declare (xargs :guard (countersp counters) :verify-guards t)) (update-nth 2 v counters)) Observe that there is a recognizer for each of the three fields and then a recognizer for the [47mcounters[0m object itself. Then, for each field, there is an accessor and an updater. Observe also that the functions are guarded so that they expect a [47mcountersp[0m for their [47mcounters[0m argument and an appropriate value for the new field values. You can see all of the [47mdefuns[0m added by a [47mdefstobj[0m event by executing the event and then using the [47m:pcb![0m command on the stobj name. E.g., ACL2 !>:pcb! counters will print the defuns above. We now clear up the ``mystery'' mentioned above. Note, for example in [47mTipCnt[0m, that the formal [47mcounters[0m is used. From the discussion in [stobj-example-1] it has been made clear that [47mTipCnt[0m can only be called on the [47mcounters[0m object. And yet, in that same discussion it was said that an argument is so treated only if it it declared among the [47m:stobjs[0m in the definition of the function. So why doesn't [47mTipCnt[0m include something like [47m(declare (xargs :stobjs (counters)))[0m? The explanation of this mystery is as follows. At the time [47mTipCnt[0m was defined, during the introduction of the [47mcounters[0m stobj, the name ``[47mcounters[0m'' was not yet a single-threaded object. The introduction of a new single-threaded object occurs in three steps: (1) The new primitive recognizers, accessors, and updaters are introduced as ``ordinary functions,'' producing their logical axiomatizations. (2) The executable-counterparts are defined in raw Lisp to support destructive updating. (3) The new name is declared a single-threaded object to ensure that all future use of these primitives respects the single-threadedness of the object. The functions defined as part of the introduction of a new single-threaded object are the only functions in the system that have undeclared stobj formals other than [47mstate[0m. You may return to [stobj-example-1] here.") (stobj-example-1-implementation (stobj) "The implementation of the [47mcounters[0m stobj The event (defstobj counters (NodeCnt :type integer :initially 0) (TipCnt :type integer :initially 0) (IntTipsSeen :type t :initially nil)) discussed in [stobj-example-1], creates a Common Lisp object to represent the current value of [47mcounters[0m. That object is created by evaluating either of the following ``raw'' (non-ACL2) Common Lisp forms: (create-counters) (vector (make-array 1 :element-type 'integer :initial-element '0) (make-array 1 :element-type 'integer :initial-element '0) 'nil) and the value is stored in the Common Lisp global variable named [47m*the-live-counters*[0m. Thus, the [47mcounters[0m object is an array of length three. The first two elements are arrays of size 1 and are used to hold the [47mNodeCnt[0m and [47mTipCnt[0m fields. The third element is the [47mIntTipsSeen[0m field. The first two fields are represented by arrays so that we can implement the [47minteger[0m type specification efficiently. Generally, integers are ``boxed'' in some Common Lisp implementations, for example, GCL. Creating a new integer requires creating a new box to put it in. But in some lisps, including GCL, the integers inside arrays of integers are not boxed. The function [47mNodeCnt[0m is defined in raw Lisp as: (defun NodeCnt (counters) (the integer (aref (the (simple-array integer (1)) (svref counters 0)) 0))) Observe that the form [47m(svref counters 0)[0m is evaluated to get an array of size 1, which is followed by a call of [47maref[0m to access the 0th element of that array. The function [47mupdate-NodeCnt[0m is defined in raw Lisp as: (defun update-NodeCnt (v counters) (declare (type integer v)) (progn (setf (aref (the (simple-array integer (1)) (svref counters 0)) 0) (the integer v)) counters)) Note that when this function is called, it does not create a new vector of length three, but ``smashes'' the existing one. One way to see all the raw Lisp functions defined by a given [47mdefstobj[0m is to evaluate the [47mdefstobj[0m event and then evaluate, in the ACL2 loop, the expression [47m(nth 4 (global-val 'cltl-command (w state)))[0m. Those functions that contain [47m(DECLARE (STOBJ-INLINE-FN T))[0m will generate [47m[defabbrev][0m forms because the [47m:inline[0m keyword of [47m[defstobj][0m was supplied the value [47mt[0m. The rest will generate [47m[defun][0ms. We now recommend that you look at [stobj-example-1-proofs].") (stobj-example-1-proofs (stobj) "Some proofs involving the [47mcounters[0m stobj Consider again the event (defstobj counters (NodeCnt :type integer :initially 0) (TipCnt :type integer :initially 0) (IntTipsSeen :type t :initially nil)) discussed in [stobj-example-1], followed by the definition (defun reset-counters (counters) (declare (xargs :stobjs (counters))) (seq counters (update-NodeCnt 0 counters) (update-TipCnt 0 counters) (update-IntTipsSeen nil counters))) which, because of the [47mseq[0m macro in [stobj-example-1], is just syntactic sugar for (defun reset-counters (counters) (declare (xargs :stobjs (counters))) (let ((counters (update-NodeCnt 0 counters))) (let ((counters (update-TipCnt 0 counters))) (update-IntTipsSeen nil counters)))). Here is a simple theorem about [47mreset-counters[0m. (defthm reset-counters-is-constant (implies (countersp x) (equal (reset-counters x) '(0 0 nil)))) Before we talk about how to prove this theorem, note that the theorem is unusual in two respects. First, it calls [47mreset-counters[0m on an argument other than the variable [47mcounters[0m! That is allowed in theorems; logically speaking, the stobj functions are indistinguishable from ordinary functions. Their use is syntactically restricted only in [47mdefun[0ms, which might be compiled and run in raw Lisp. Those restrictions allow us to implement stobj modification destructively. But logically speaking, [47mreset-counters[0m and other stobj ``modifying'' functions just create new objects, constructively. Second, the theorem above explicitly provides the hypothesis that [47mreset-counters[0m is being applied to an object satisfying [47mcountersp[0m. Such a hypothesis is not always required: [47mreset-counters[0m is total and will do something no matter what [47mx[0m is. But in this particular case, the result is not [47m'(0 0 nil)[0m unless [47mx[0m is, at least, a true-list of length three. To make a long story short, to prove theorems about stobj functions you behave in exactly the way you would to prove the same theorems about the same functions defined without the stobj features. How can we prove the above theorem? Unfolding the definition of [47mreset-counters[0m shows that [47m(reset-counters x)[0m is equal to (update-IntTipsSeen nil (update-TipCnt 0 (update-NodeCnt 0 x))) which in turn is (update-nth 2 nil (update-nth 1 0 (update-nth 0 0 x))). Opening up the definition of [47mupdate-nth[0m reduces this to (list* 0 0 nil (cdddr x)). This is clearly equal to [47m'(0 0 nil)[0m, provided we know that [47m(cdddr x)[0m is [47mnil[0m. Unfortunately, that last fact requires a lemma. The most specific lemma we could provide is (defthm special-lemma-for-counters (implies (countersp x) (equal (cdddr x) nil))) but if you try to prove that lemma you will find that it requires some reasoning about [47mlen[0m and [47mtrue-listp[0m. Furthermore, the special lemma above is of interest only for [47mcounters[0m. The following lemma about [47mlen[0m is the one we prefer. (defthm equal-len-n (implies (syntaxp (quotep n)) (equal (equal (len x) n) (if (integerp n) (if (< n 0) nil (if (equal n 0) (atom x) (and (consp x) (equal (len (cdr x)) (- n 1))))) nil)))) This lemma will simplify any equality in which a [47mlen[0m expression is equated to any explicitly given constant [3mn[0m, e.g., [47m3[0m, reducing the equation to a conjunction of [47mconsp[0m terms about the first [3mn[0m [47mcdr[0ms. If the above lemma is available then ACL2 immediately proves (defthm reset-counters-is-constant (implies (countersp x) (equal (reset-counters x) '(0 0 nil)))) The point is presumably well made: proving theorems about single-threaded object accessors and updaters is no different than proving theorems about other recursively defined functions on lists. As we have seen, operations on [stobj]s turn into definitions involving [47m[nth][0m and [47m[update-nth][0m in the logic. Here are two lemmas, both due to Matt Wilding, that are useful for simplifying terms involving [47mnth[0m and [47mupdate-nth[0m, which are therefore useful in reasoning about single-threaded objects. (defthm update-nth-update-nth-same (implies (equal (nfix i1) (nfix i2)) (equal (update-nth i1 v1 (update-nth i2 v2 l)) (update-nth i1 v1 l)))) (defthm update-nth-update-nth-diff (implies (not (equal (nfix i1) (nfix i2))) (equal (update-nth i1 v1 (update-nth i2 v2 l)) (update-nth i2 v2 (update-nth i1 v1 l)))) :rule-classes ((:rewrite :loop-stopper ((i1 i2))))) We now recommend that you see [stobj-example-2].") (stobj-example-2 (stobj) "An example of the use of arrays in single-threaded objects The following event (defstobj ms (pcn :type integer :initially 0) (mem :type (array integer (100000)) :initially -1) (code :type t :initially nil)) introduces a single-threaded object named [47mms[0m (which stands for ``machine state''). The object has three fields, a [47mpcn[0m or program counter, a [47mmem[0m or memory, and a [47mcode[0m field. The [47mmem[0m field is occupied by an object initially of type [47m(array integer (100000))[0m. Logically speaking, this is a list of length [47m100000[0m, each element of which is an integer. But in the underlying implementation of the [47mms[0m object, this field is occupied by a raw Lisp array, initially of size 100000. You might expect the above [47mdefstobj[0m to define the accessor function [47mmem[0m and the updater [47mupdate-mem[0m. [3mThat does not happen![0m. The above event defines the accessor function [47mmemi[0m and the updater [47mupdate-memi[0m. These functions do not access/update the [47mmem[0m field of the [47mms[0m object; they access/update the individual elements of the array in that field. In particular, the logical definitions of the two functions are: (defun memi (i ms) (declare (xargs :guard (and (msp ms) (integerp i) (<= 0 i) (< i (mem-length ms))))) (nth i (nth 1 ms))) (defun update-memi (i v ms) (declare (xargs :guard (and (msp ms) (integerp i) (<= 0 i) (< i (mem-length ms)) (integerp v)))) (update-nth-array 1 i v ms)) For example, to access the 511th (0-based) memory location of the current [47mms[0m you could evaluate: ACL2 !>(memi 511 ms) -1 The answer is [47m-1[0m initially, because that is the above-specified initial value of the elements of the [47mmem[0m array. To set that element you could do ACL2 !>(update-memi 511 777 ms) <ms> ACL2 !>(memi 511 ms) 777 The raw Lisp implementing these two functions is shown below. (defun memi (i ms) (declare (type (and fixnum (integer 0 *)) i)) (the integer (aref (the (simple-array integer (*)) (svref ms 1)) (the (and fixnum (integer 0 *)) i)))) (defun update-memi (i v ms) (declare (type (and fixnum (integer 0 *)) i) (type integer v)) (progn (setf (aref (the (simple-array integer (*)) (svref ms 1)) (the (and fixnum (integer 0 *)) i)) (the integer v)) ms)) If you want to see the raw Lisp supporting a [47mdefstobj[0m, execute the [47mdefstobj[0m and then evaluate the ACL2 form [47m(nth 4 (global-val 'cltl-command (w state)))[0m. To continue the stobj tour, see [stobj-example-3].") (stobj-example-3 (stobj) "Another example of a single-threaded object The event (defstobj $s (x :type integer :initially 0) (a :type (array (integer 0 9) (3)) :initially 9 :resizable t)) introduces a stobj named [47m$S[0m. The stobj has two fields, [47mX[0m and [47mA[0m. The [47mA[0m field is an array. The [47mX[0m field contains an integer and is initially 0. The [47mA[0m field contains a list of integers, each between 0 and 9, inclusively. (Under the hood, this ``list'' is actually implemented as an array.) Initially, the [47mA[0m field has three elements, each of which is 9. This event introduces the following sequence of function definitions: (DEFUN XP (X) ...) ; recognizer for X field (DEFUN AP (X) ...) ; recognizer of A field (DEFUN $SP ($S) ...) ; top-level recognizer for stobj $S (DEFUN CREATE-$S NIL ...) ; creator for stobj $S (DEFUN X ($S) ...) ; accessor for X field (DEFUN UPDATE-X (V $S) ...) ; updater for X field (DEFUN A-LENGTH ($S) ...) ; length of A field (DEFUN RESIZE-A (K $S) ...) ; resizer for A field (DEFUN AI (I $S) ...) ; accessor for A field at index I (DEFUN UPDATE-AI (I V $S) ...) ; updater for A field at index I Here is the definition of [47m$SP[0m: (DEFUN $SP ($S) (DECLARE (XARGS :GUARD T :VERIFY-GUARDS T)) (AND (TRUE-LISTP $S) (= (LENGTH $S) 2) (XP (NTH 0 $S)) (AP (NTH 1 $S)) T)) This reveals that in order to satisfy [47m$SP[0m an object must be a true list of length 2 whose first element satisfies [47mXP[0m and whose second satisfies [47mAP[0m. By printing the definition of [47mAP[0m one learns that it requires its argument to be a true list, each element of which is an integer between 0 and 9. The initial value of stobj [47m$S[0m is given by zero-ary ``creator'' function [47mCREATE-$S[0m. Creator functions may only be used in limited contexts. See [with-local-stobj]. Here is the definition of [47mUPDATE-AI[0m, the updater for the [47mA[0m field at index [47mI[0m: (DEFUN UPDATE-AI (I V $S) (DECLARE (XARGS :GUARD (AND ($SP $S) (INTEGERP I) (<= 0 I) (< I (A-LENGTH $S)) (AND (INTEGERP V) (<= 0 V) (<= V 9))) :VERIFY-GUARDS T)) (UPDATE-NTH-ARRAY 1 I V $S)) By definition [47m(UPDATE-NTH-ARRAY 1 I V $S)[0m is [47m(UPDATE-NTH 1 (UPDATE-NTH I V (NTH 1 $S)) $S)[0m. This may be a little surprising but should be perfectly clear. First, ignore the guard, since it is irrelevant in the logic. Reading from the inside out, [47m(UPDATE-AI I V $S)[0m extracts [47m(NTH 1 $S)[0m, which is array [47ma[0m of [47m$S[0m. (Recall that [47m[nth][0m is 0-based.) The next higher expression in the definition above, [47m(UPDATE-NTH I V a)[0m, ``modifies'' [47ma[0m by setting its [47mI[0mth element to [47mV[0m. Call this [47ma'[0m. The next higher expression, [47m(UPDATE-NTH 1 a' $S)[0m, ``modifies'' [47m$S[0m by setting its 1st component to [47ma'[0m. Call this result [47m$s'[0m. Then [47m$s'[0m is the result returned by [47mUPDATE-AI[0m. So the first useful observation is that from the perspective of the logic, the type ``restrictions'' on stobjs are irrelevant. They are ``enforced'' by ACL2's guard mechanism, not by the definitions of the updater functions. As one might also imagine, the accessor functions do not really ``care,'' logically, whether they are applied to well-formed stobjs or not. For example, [47m(AI I $S)[0m is defined to be [47m(NTH I (NTH 1 $S))[0m. Thus, you will not be able to prove that (AI 2 $S) is an integer. That is, (integerp (AI 2 $S)) is not a theorem, because [47m$S[0m may not be well-formed. Now [47m(integerp (AI 2 $S))[0m will always evaluate to [47mT[0m in the top-level ACL2 command loop, because we insist that the current value of the stobj [47m$S[0m always satisfies [47m$SP[0m by enforcing the guards on the updaters, independent of whether guard checking is on or off; see [set-guard-checking]. But in a theorem [47m$S[0m is just another variable, implicitly universally quantified. So [47m(integerp (AI 2 $S))[0m is not a theorem because it is not true when the variable [47m$S[0m is instantiated with, say, '(1 (0 1 TWO)) because, logically speaking, [47m(AI 2 '(1 (0 1 TWO)))[0m evaluates to the symbol [47mTWO[0m. That is, (equal (AI 2 '(1 (0 1 TWO))) 'TWO) is true. However, (implies (and ($SP $S) (< 2 (A-LENGTH $S))) (integerp (AI 2 $S))) is a theorem. To prove it, you will have to prove a lemma about [47mAP[0m. The following will do: (defthm ap-nth (implies (and (AP x) (integerp i) (<= 0 i) (< i (len x))) (integerp (nth i x)))). Similarly, (implies (and (integerp i) (<= 0 i) (< i (A-LENGTH $S)) (integerp v) (<= 0 v) (<= v 9)) ($SP (UPDATE-AI i v $S))) is not a theorem until you add the additional hypothesis [47m($SP $S)[0m. To prove the resulting theorem, you will need a lemma such as the following. (defthm ap-update-nth (implies (and (AP a) (integerp v) (<= 0 v) (<= v 9) (integerp i) (<= 0 i) (< i (len a))) (AP (update-nth i v a)))) The moral here is that from the logical perspective, you must provide the hypotheses that, as a programmer, you think are implicit on the structure of your stobjs, and you must prove their invariance. This is a good area for further support, perhaps in the form of a library of macros. [3mResizing Array Fields[0m Recall the specification of the array field, [47mA[0m for the stobj [47m$S[0m introduced above: (a :type (array (integer 0 9) (3)) :initially 9 :resizable t) Logically, this field is a list, initially of length 3. Under the hood, this field is implemented using a Common Lisp array with 3 elements. In some applications, one may wish to lengthen an array field, or even (to reclaim space) to shrink an array field. The [47m[defstobj][0m event provides functions to access the current length of an array field and to change the array field, with default names obtained by suffixing the field name with ``[47mLENGTH-[0m'' or prefixing it with ``[47mRESIZE-[0m,'' respectively. The following log shows the uses of these fields in the above example. ACL2 !>(A-LENGTH $S) 3 ACL2 !>(RESIZE-A 10 $S) ; change length of A to 10 <$s> ACL2 !>(A-LENGTH $S) 10 ACL2 !>(AI 7 $S) ; new elements get value from :initially 9 ACL2 !>(RESIZE-A 2 $S) ; truncate A down to first 2 elements <$s> ACL2 !>(A-LENGTH $S) 2 ACL2 !>(AI 7 $S) ; error: access past array bound ACL2 Error in TOP-LEVEL: The guard for the function symbol AI, which is (AND ($SP $S) (INTEGERP I) (<= 0 I) (< I (A-LENGTH $S))), is violated by the arguments in the call (AI 7 $S). ACL2 !> Here are the definitions of the relevant functions for the above example; also see [resize-list]. (DEFUN A-LENGTH ($S) (DECLARE (XARGS :GUARD ($SP $S) :VERIFY-GUARDS T)) (LEN (NTH 1 $S))) (DEFUN RESIZE-A (K $S) (DECLARE (XARGS :GUARD ($SP $S) :VERIFY-GUARDS T)) (UPDATE-NTH 1 (RESIZE-LIST (NTH 1 $S) K 9) $S)) It is important to note that the implementation of array resizing in ACL2 involves copying the entire array into a newly allocated space and thus can be quite costly if performed often. This approach was chosen in order to make array access and update as efficient as possible, with the suspicion that for most applications, array access and update are considerably more frequent than resizing (especially if the programmer is aware of the relative costs beforehand). It should also be noted that computations of lengths of stobj array fields should be fast (constant-time) in all or most Common Lisp implementations. Finally, if [47m:resizable t[0m is not supplied as shown above, then an attempt to resize the array will result in an error. If you do not intend to resize the array, it is better to omit the [47m:resizable[0m option (or to supply [47m:resizable nil[0m), since then the length function will be defined to return a constant, namely the initial length, which can simplify guard proofs (compare with the definition of [47mA-LENGTH[0m above). This completes the tour through the documentation of [stobj]s. However, you may now wish to read the documentation for the event that introduces a new single-threaded object; see [defstobj].") (stobj-let (pointers) "See [nested-stobjs].") (stobj-table (stobj nested-stobjs) "A [stobj] field mapping stobj names to stobjs See [stobj] for basic background on stobjs, and see [defstobj] for detailed documentation on the syntax and semantics of stobjs, including fields specified with [47m:type (stobj-table)[0m or [47m:type (stobj-table SIZE)[0m. In the latter case, [47mSIZE[0m must either be a natural number or a defined constant whose value is a natural number. We call such fields --- that is, stobj fields specified with [47m:type (stobj-table)[0m or [47m:type (stobj-table SIZE)[0m --- ``stobj-table fields''; this documentation topic explains them, and it assumes familiarity with stobj fields of stobjs as documented in [nested-stobjs] --- especially, the use of [47m[stobj-let][0m to read and write such fields. Note that the documentation for [defstobj] shows the default names for accessors and updaters; for a stobj-table field, [47mTBL[0m, these are [47mTBL-GET[0m and [47mTBL-PUT[0m, respectively. For examples of [47mstobj-let[0m usage for stobj-tables, see [community-book] [47mbooks/system/tests/stobj-table-tests-input.lsp[0m. A stobj-table field may be viewed as an association list mapping stobj names to corresponding stobjs, so that each stobj name maps to a stobj that satisfies the recognizer for that stobj name. This requirement is not enforced in the logic (i.e., in recognizer functions). But it is essentially maintained in raw Lisp as an invariant, except that for efficiency, a stobj-table field is implemented as a hash table (again, mapping stobj names to corresponding stobjs). Below we give more details and explain how [47mstobj-let[0m may be used to access and update stobjs that are in such a table. The general forms for stobj-table fields of stobjs are as shown below. (defstobj NAME (TBL1 :type (stobj-table)) ; stobj field of default size ... (TBL2 :type (stobj-table SIZE)) ; stobj field of desired size SIZE ...) That is, a stobj-table field is a field whose type is of the form [47m(stobj-table)[0m or [47m(stobj-table SIZE)[0m. The syntax is thus much like the syntax for hash-table fields of stobjs, except that there is no test specified for a stobj-table (it is actually [47m[eq][0m in raw Lisp). As noted above, a stobj-table is conceptually an alist that associates stobj names with corresponding stobjs. We say ``conceptually'' because in fact, the recognizer for any stobj-table field is [47mt[0m: there is no requirement that it is actually an alist. It is accessed logically with [47m[hons-assoc-equal][0m, which is a variant of [47m[assoc][0m that treats an arbitrary object as an alist: only pairs are considered when looking up a key, and the final cdr is ignored. A default value is returned when there is no pair with the given key. A stobj-table field is thus very much like a hash-table field. The key difference (pun somewhat intended) is that each key of a stobj-table is the name of a stobj (other than [47mstate[0m, i.e., it is a user-defined stobj name), and the corresponding value is a stobj satisfying the recognizer for that name. A common case is that a stobj-table field is the unique field of its parent stobj. In that case we may think of the entire stobj as a stobj-table, and that is actually consistent with the implementation: in raw Lisp, if a stobj-table field is the sole field of its parent stobj, then that stobj-table field is actually the entire stobj; there is not the usual indirection in raw Lisp, where a stobj is a vector of fields and the field is accessed as an entry in that vector. (Logically, however, a stobj is always a list of its fields, even if there is only one field.) Reads and writes of a stobj-table field are much like reads and writes when the field is an array of stobjs. In both cases, one uses [47m[stobj-let][0m to access and possibly update the desired individual stobj or stobjs. The syntax thus looks as follows, where [47mST[0m is a stobj name and [47mPARENT[0m is the name of a stobj that has a stobj-table accessor with name [47mTBL-GET[0m. Note that the first argument of the accessor must be the quotation of the name of the bound stobj (thus below, [47m'ST[0m is the quotation of [47mST[0m) and the third argument must be a call of that stobj's creator function. (stobj-let (... ; bindings (ST (TBL-GET 'ST PARENT (CREATE-ST))) ... ) (...) ; producer variables (...) ; producer ... ; consumer ) The [47mTBL-GET[0m call above always returns an object that satisfies the recognizer for the stobj, [47mST[0m. However, that is a fact about evaluation; it is not provable in the logic. Fortunately, [guard] verification typically adds hypotheses to this effect when necessary. [31;1mRemark[0m. This remark on the implementation may be skipped, but it may provide some intuition. When a stobj name is not bound in the underlying hash table, then the default value (in the example above, [47m(CREATE-ST)[0m) provides a suitable stobj nonetheless. And if that stobj name is among the producer variables of a [47mstobj-let[0m form, it will be bound in the underlying hash table when the [47mstobj-let[0m form completes. End of remark. The remainder of this topic explains the use of stobj-tables by following the example in [community-book] [47mstd/stobjs/stobj-table.lisp[0m. The first form in that book (after the initial [47m[in-package][0m form) is as follows. (defstobj stobj-table (tbl :type (stobj-table))) This specifies a stobj named [47mstobj-table[0m with a unique field, [47mtbl[0m. As noted above, this stobj is the same as its field in raw Lisp, so even though it is the field that is truly a stobj-table, it is not conceptually problematic to call the entire stobj ``stobj-table''. This may be the most common case for a stobj-table (i.e., being a unique field of a stobj). The remaining forms in the book are [local] to the book, intended to illustrate with simple examples how stobj-tables may be used. The first one just introduces a rather trivial stobj. (defstobj st1 fld1) The next form puts this stobj into the stobj-table after updating its field with a specified value. (defun update-st1-in-tbl (val stobj-table) (declare (xargs :stobjs stobj-table)) (stobj-let ((st1 (tbl-get 'st1 stobj-table (create-st1)))) ; bindings (st1) ; producer variable (update-fld1 val st1) ; producer stobj-table ; consumer )) The form after that accesses the value of [47m'st1[0m in the stobj-table and returns its field's value. (defun read-st1-in-tbl1 (stobj-table) (declare (xargs :stobjs stobj-table)) (stobj-let ((st1 (tbl-get 'st1 stobj-table (create-st1)))) ; bindings (val) ; producer variable (fld1 st1) ; producer val ; consumer )) Next is a check that when a specific value is written for the key [47m'st1[0m with the update function defined above, the value subsequently read for key [47m'st1[0m is that written value. The reason for the [47mmv[0m call is that the updater returns an updated stobj-table, which therefore must be returned. However, [47m[assert-event][0m is sufficiently clever to check that the first (i.e., ordinary) value returned is non-[47mnil[0m. (assert-event (let ((stobj-table (update-st1-in-tbl 3 stobj-table))) (mv (equal (read-st1-in-tbl1 stobj-table) 3) stobj-table)) :stobjs-out '(nil stobj-table)) The computation above is a special case of a standard ``read-over-write'' property, that after a write, we read the value that was just written. This is proved automatically. (defthm read-over-write-st1-in-tbl (implies (stobj-tablep stobj-table) (let ((stobj-table (update-st1-in-tbl val stobj-table))) (equal (read-st1-in-tbl1 stobj-table) val)))) The other standard ``read-over-write'' property is that the write for a given key doesn't affect the value read for a different key. The following events, admitted automatically, illustrate that property: here, writing a value for the key [47m'st1[0m doesn't affect the value read for the key [47m'st2[0m. (defstobj st2 fld2) (defun read-st2-in-tbl (stobj-table) (declare (xargs :stobjs stobj-table)) (stobj-let ((st2 (tbl-get 'st2 stobj-table (create-st2)))) ; bindings (val) ; producer variable (fld2 st2) ; producer val ; consumer )) (defthm read-over-write-st2-in-tbl (implies (stobj-tablep stobj-table) (let ((stobj-table-2 (update-st1-in-tbl val stobj-table))) (equal (read-st2-in-tbl stobj-table-2) (read-st2-in-tbl stobj-table))))) Note that all keys in a stobj-table are names of stobjs. Consider what happens when we evaluate the events in the book above, including the local events, and then undo the [47m[defstobj][0m event admitting [47mst1[0m. It is clear that undoing has removed the symbol [47mst1[0m as a key in the stobj-table. ACL2 !>(ld "std/stobjs/stobj-table.lisp" :dir :system) [[.. output omitted ..]] ACL2 !>(tbl-count stobj-table) 1 ACL2 !>:ubt st1 d 1:x(DEFSTOBJ STOBJ-TABLE (TBL :TYPE #)) ACL2 !>(tbl-count stobj-table) 0 ACL2 !> Finally, we remark that there is nothing special about stobj-table fields with respect to stobj fields of abstract stobjs.") (stobjp (pointers) "See [system-utilities].") (stobjs (pointers) "See [xargs] for information about the keyword [47m:stobjs[0m.") (stobjs-in (pointers) "See [system-utilities].") (stobjs-out (pointers) "See [system-utilities].") (stop-proof-tree (proof-tree) "Stop displaying proof trees during proofs Also see [proof-tree] and see [start-proof-tree]. Note that [47m:stop-proof-tree[0m works by adding [47m'[0m[47m[proof-tree][0m to the [47minhibit-output-lst[0m; see [set-inhibit-output-lst]. Proof tree displays are explained in the documentation for [proof-tree]. [47m:Stop-proof-tree[0m causes proof tree display to be turned off. It is permissible to submit the form [47m(stop-proof-tree)[0m during a break. Thus, you can actually turn off proof tree display in the middle of a proof by interrupting ACL2 and submitting the form [47m(stop-proof-tree)[0m in raw Lisp.") (string (strings acl2-built-ins) "[coerce] to a string [47m(String x)[0m [coerce]s [47mx[0m to a string. The [guard] for [47mstring[0m requires its argument to be a string, a symbol, or a character. * If [47mx[0m is already a string, then it is returned unchanged. * If [47mx[0m is a symbol, then its [47m[symbol-name][0m is returned. * If [47mx[0m is a character, the corresponding one-character string is returned. Note: this is a rather low-level operation that doesn't support coercing numbers or conses into strings. If you want to turn numbers into strings, see functions such as [str::nat-to-dec-string], or more generally the [str::numbers] functions. For conses, see the [str::pretty-printing] routines such as [str::pretty]. [47mString[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<string> (defun string (x) (declare (xargs :guard (or (stringp x) (symbolp x) (characterp x)))) (cond ((stringp x) x) ((symbolp x) (symbol-name x)) (t (coerce (list x) 'string))))") (string-alistp (alists acl2-built-ins) "Recognizer for association lists with strings as keys [47m(String-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of the form [47m(cons key val)[0m where [47mkey[0m is a string. [47mString-alistp[0m has a [guard] of [47mt[0m. [31;1mFunction: [0m<string-alistp> (defun string-alistp (x) (declare (xargs :guard t)) (cond ((atom x) (eq x nil)) (t (and (consp (car x)) (stringp (car (car x))) (string-alistp (cdr x))))))") (string-append (strings acl2-built-ins) "[concatenate] two strings [47mString-append[0m takes two arguments, which are both strings (if the [guard] is to be met), and returns a string obtained by concatenating together the [characters] in the first string followed by those in the second. For a related macro that can take an arbitrary number of string arguments, see [concatenate], noting that the macro call (concatenate 'string str1 str2). expands to the call (string-append str1 str2). [31;1mFunction: [0m<string-append> (defun string-append (str1 str2) (declare (xargs :guard (and (stringp str1) (stringp str2)))) (mbe :logic (coerce (append (coerce str1 'list) (coerce str2 'list)) 'string) :exec (concatenate 'string str1 str2)))") (string-downcase (strings acl2-built-ins) "In a given string, turn upper-case [characters] into lower-case For a string [47mx[0m, [47m(string-downcase x)[0m is the result of applying [47m[char-downcase][0m to each character in [47mx[0m. The [guard] for [47mstring-downcase[0m states that its argument is a string. [47mString-downcase[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<string-downcase> (defun string-downcase (x) (declare (xargs :guard (stringp x))) (coerce (string-downcase1 (coerce x 'list)) 'string))") (string-equal (strings acl2-built-ins) "String equality without regard to case For strings [47mstr1[0m and [47mstr2[0m, [47m(string-equal str1 str2)[0m is true if and only [47mstr1[0m and [47mstr2[0m are the same except perhaps for the cases of their [characters]. The [guard] on [47mstring-equal[0m requires that its arguments are strings. [47mString-equal[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<string-equal> (defun string-equal (str1 str2) (declare (xargs :guard (and (stringp str1) (stringp str2)))) (let ((len1 (length str1))) (and (= len1 (length str2)) (string-equal1 str1 str2 0 len1))))") (string-listp (strings lists acl2-built-ins) "Recognizer for a true list of strings The predicate [47mstring-listp[0m tests whether its argument is a [47m[true-listp][0m of strings. [31;1mFunction: [0m<string-listp> (defun string-listp (x) (declare (xargs :guard t)) (cond ((atom x) (eq x nil)) (t (and (stringp (car x)) (string-listp (cdr x))))))") (string-upcase (strings acl2-built-ins) "In a given string, turn lower-case [characters] into upper-case For a string [47mx[0m, [47m(string-upcase x)[0m is the result of applying [47m[char-upcase][0m to each character in [47mx[0m. The [guard] for [47mstring-upcase[0m states that its argument is a string. [47mString-upcase[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<string-upcase> (defun string-upcase (x) (declare (xargs :guard (stringp x))) (coerce (string-upcase1 (coerce x 'list)) 'string))") (string< (strings acl2-built-ins) "Less-than test for strings [47m(String< str1 str2)[0m is non-[47mnil[0m if and only if the string [47mstr1[0m precedes the string [47mstr2[0m lexicographically, where character inequalities are tested using [47m[char<][0m. When non-[47mnil[0m, [47m(string< str1 str2)[0m is the first position (zero-based) at which the strings differ. Here are some examples. ACL2 !>(string< "abcd" "abu") 2 ACL2 !>(string< "abcd" "Abu") NIL ACL2 !>(string< "abc" "abcde") 3 ACL2 !>(string< "abcde" "abc") NIL The [guard] for [47mstring<[0m specifies that its arguments are strings. [47mString<[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<string<> (defun string< (str1 str2) (declare (xargs :guard (and (stringp str1) (stringp str2)))) (string<-l (coerce str1 'list) (coerce str2 'list) 0))") (string<= (strings acl2-built-ins) "Less-than-or-equal test for strings [47m(String<= str1 str2)[0m is non-[47mnil[0m if and only if the string [47mstr1[0m precedes the string [47mstr2[0m lexicographically or the strings are equal. When non-[47mnil[0m, [47m(string<= str1 str2)[0m is the first position (zero-based) at which the strings differ, if they differ, and otherwise is their common length. See [string<]. The [guard] for [47mstring<=[0m specifies that its arguments are strings. [47mString<=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<string<=> (defun string<= (str1 str2) (declare (xargs :guard (and (stringp str1) (stringp str2)))) (if (equal str1 str2) (length str1) (string< str1 str2)))") (string> (strings acl2-built-ins) "Greater-than test for strings [47m(String> str1 str2)[0m is non-[47mnil[0m if and only if [47mstr2[0m precedes [47mstr1[0m lexicographically. When non-[47mnil[0m, [47m(string> str1 str2)[0m is the first position (zero-based) at which the strings differ. See [string<]. [47mString>[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<string>> (defun string> (str1 str2) (declare (xargs :guard (and (stringp str1) (stringp str2)))) (string< str2 str1))") (string>= (strings acl2-built-ins) "Less-than-or-equal test for strings [47m(String>= str1 str2)[0m is non-[47mnil[0m if and only if the string [47mstr2[0m precedes the string [47mstr1[0m lexicographically or the strings are equal. When non-[47mnil[0m, [47m(string>= str1 str2)[0m is the first position (zero-based) at which the strings differ, if they differ, and otherwise is their common length. See [string>]. The [guard] for [47mstring>=[0m specifies that its arguments are strings. [47mString>=[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<string>=> (defun string>= (str1 str2) (declare (xargs :guard (and (stringp str1) (stringp str2)))) (if (equal str1 str2) (length str1) (string> str1 str2)))") (stringp (strings acl2-built-ins) "Recognizer for strings [47m(stringp x)[0m is true if and only if [47mx[0m is a string.") (strings (programming) "Strings are atomic objects that contain character sequences, like [47m"Hello World"[0m. See the [std/strings] library for many additional string functions and lemmas about the built-in string functions. Subtopics [Char] The [nth] element (zero-based) of a string [Coerce] Coerce a character list to a string and a string to a list [Concatenate] Concatenate lists or strings together [Count] Count the number of occurrences of an item in a string or true-list [Length] Length of a string or proper list [Position] Position of an item in a string or a list [Remove-duplicates] Remove duplicates from a string or a list [Reverse] Reverse a list or string [Search] Search for a string or list in another string or list [String] [coerce] to a string [String-append] [concatenate] two strings [String-downcase] In a given string, turn upper-case [characters] into lower-case [String-equal] String equality without regard to case [String-listp] Recognizer for a true list of strings [String-upcase] In a given string, turn lower-case [characters] into upper-case [String<] Less-than test for strings [String<=] Less-than-or-equal test for strings [String>] Greater-than test for strings [String>=] Less-than-or-equal test for strings [Stringp] Recognizer for strings [Subseq] Subsequence of a string or list [Substitute] Substitute into a string or a list, using [47m[eql][0m as test") (strip-cars (alists acl2-built-ins) "Collect up all first components of pairs in a list [47m(strip-cars x)[0m is the list obtained by walking through the list [47mx[0m and collecting up all first components ([47m[car][0ms). This function is implemented in a tail-recursive way, despite its logical definition. [47m(strip-cars x)[0m has a [guard] of [47m(alistp x)[0m. [31;1mFunction: [0m<strip-cars> (defun strip-cars (x) (declare (xargs :guard (alistp x))) (cond ((endp x) nil) (t (cons (car (car x)) (strip-cars (cdr x))))))") (strip-cdrs (alists acl2-built-ins) "Collect up all second components of pairs in a list [47m(strip-cdrs x)[0m has a [guard] of [47m(alistp x)[0m, and returns the list obtained by walking through the list [47mx[0m and collecting up all second components ([47m[cdr][0ms). This function is implemented in a tail-recursive way, despite its logical definition. [31;1mFunction: [0m<strip-cdrs> (defun strip-cdrs (x) (declare (xargs :guard (alistp x))) (cond ((endp x) nil) (t (cons (cdr (car x)) (strip-cdrs (cdr x))))))") (strong-rewrite-rules (introduction-to-the-theorem-prover) "Formulating good rewrite rules Suppose you notice the following term in a Key Checkpoint: (MEMBER (CAR A) (REV B)). You might think of two theorems for handling this term, which we'll call the ``weak'' and ``strong'' version of [47mmember-rev[0m. (defthm member-rev-weak (implies (member e b) (member e (rev b)))). (defthm member-rev-strong (iff (member e (rev b)) (member e b))). The ``strong'' version logically implies the ``weak'' version and so deserves the adjective. (Recall that ``[3mp[0m <---> [3mq[0m'' is just ``[3mp[0m ---> [3mq[0m'' and ``[3mq[0m ---> [3mp[0m.'' So the strong version quite literally says everything the weak version does and then some.) But the ``strong'' version also produces a [3mbetter[0m rewrite rule. Here are the rules generated from these two formulas, phrased as directives to ACL2's simplifier: [47mmember-rev-weak[0m: If you ever see an instance of [47m(MEMBER e (REV b))[0m, backchain to [47m(MEMBER e b)[0m (i.e., turn your attention to that term) and if you can show that it is true, replace [47m(MEMBER e (REV b))[0m by [47mT[0m. [47mmember-rev-strong[0m: If you ever see an instance of [47m(MEMBER e (REV b))[0m, replace it by [47m(MEMBER e b)[0m. Technical Note: Actually, both rules concern [3mpropositional[0m occurrences of the ``target'' expression, [47m(MEMBER e (REV b))[0m, i.e., occurrences of the target in which its truth value is the only thing of relevance. (Recall that [47m(MEMBER x y)[0m returns the tail of [47my[0m starting with [47mx[0m! Evaluate some simple [47mMEMBER[0m expressions, like [47m(MEMBER 3 '(1 2 3 4 5))[0m to see what we mean.) Both theorems tell us about circumstances in which the target is non-[47mNIL[0m (i.e., ``true'') without telling us its identity. But ACL2 keeps track of when the target is in a propositional occurrence and can use such rules to rewrite the target to propositionally equivalent terms. So the strong version is better because it will always eliminate [47m(MEMBER e (REV b))[0m in favor of [47m(MEMBER e b)[0m. That simpler expression may be further reduced if the context allows it. But in any case, the strong version eliminates [47mREV[0m from the problem. The weak version only eliminates [47mREV[0m when a side-condition can be proved. While either version may permit us to prove the Key Checkpoint that ``suggested'' the rule, the strong version is a better rule to have in the database going forward. For example, suppose [47mNATS-BELOW[0m returns the list of natural numbers below its argument. Imagine two alternative scenarios in which a key checkpoint is about to arise involving this term: (MEMBER K (REV (NATS-BELOW J))) [31;1mScenario 1[0m is when you've got the strong version in your database: it will rewrite the key checkpoint term to (MEMBER K (NATS-BELOW J)) and that's what you'll see in the printed checkpoint unless other rules reduce it further. [31;1mScenario 2[0m is when you have only the weak version in your database: the weak rule will attempt to reduce the term above to [47mT[0m and will, if there are sufficient rules and hypotheses about [47mK[0m's membership in [47m(NATS-BELOW J)[0m. But if no such rules or hypotheses are available, you'll be confronted with a key checkpoint involving (MEMBER K (REV (NATS-BELOW J))) and [3mit will not be obvious[0m that the problem would go away if you could establish that [47mK[0m is in [47m(NATS-BELOW J)[0m. Clearly, Scenario 1 is better. We recommend that you now practice formulating strong versions of rules suggested by terms you might see. See [practice-formulating-strong-rules]. When you are finished with that, use your browser's [31;1mBack Button[0m to return to [introduction-to-key-checkpoints].") (subcor-var (pointers) "See [system-utilities].") (subgoal-loop-limits (miscellaneous) "maximum length of the subgoal stack General Form: (subgoal-loop-limits (w state)) See [47m[set-subgoal-loop-limits][0m for a discussion of how you can set this parameter, which can be used to detect simple looping by the prover and to cut off some forms of infinite looping.") (sublis (alists acl2-built-ins) "Substitute an alist into a tree [47m(Sublis alist tree)[0m is obtained by replacing every leaf of [47mtree[0m with the result of looking that leaf up in the association list [47malist[0m. However, a leaf is left unchanged if it is not found as a key in [47malist[0m. Leaves are looked up using the function [47m[assoc][0m. The [guard] for [47m(sublis alist tree)[0m requires [47m(eqlable-alistp alist)[0m. This [guard] ensures that the [guard] for [47m[assoc][0m will be met for each lookup generated by [47msublis[0m. [47mSublis[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<sublis> (defun sublis (alist tree) (declare (xargs :guard (eqlable-alistp alist))) (cond ((atom tree) (let ((pair (assoc tree alist))) (cond (pair (cdr pair)) (t tree)))) (t (cons (sublis alist (car tree)) (sublis alist (cdr tree))))))") (sublis-fn (pointers) "See [system-utilities].") (sublis-fn-lst-simple (pointers) "See [system-utilities].") (sublis-fn-simple (pointers) "See [system-utilities].") (sublis-var (pointers) "See [system-utilities].") (subseq (lists strings acl2-built-ins) "Subsequence of a string or list For any natural numbers [47mstart[0m and [47mend[0m, where [47mstart[0m [47m<=[0m [47mend[0m [47m<=[0m [47m(length seq)[0m, [47m(subseq seq start end)[0m is the subsequence of [47mseq[0m from index [47mstart[0m up to, but not including, index [47mend[0m. [47mEnd[0m may be [47mnil[0m, in which case it is treated as though it is [47m(length seq)[0m, i.e., we obtain the subsequence of [47mseq[0m from index [47mstart[0m all the way to the end. The [guard] for [47m(subseq seq start end)[0m is that [47mseq[0m is a true list or a string, [47mstart[0m and [47mend[0m are integers (except, [47mend[0m may be [47mnil[0m, in which case it is treated as [47m(length seq)[0m for the rest of this discussion), and [47m0[0m [47m<=[0m [47mstart[0m [47m<=[0m [47mend[0m [47m<=[0m [47m(length seq)[0m. [47mSubseq[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note: In Common Lisp the third argument of [47msubseq[0m is optional, but in ACL2 it is required, though it may be [47mnil[0m as explained above. [31;1mFunction: [0m<subseq> (defun subseq (seq start end) (declare (xargs :guard (and (or (true-listp seq) (stringp seq)) (integerp start) (<= 0 start) (or (null end) (and (integerp end) (<= end (length seq)))) (<= start (or end (length seq)))))) (if (stringp seq) (coerce (subseq-list (coerce seq 'list) start (or end (length seq))) 'string) (subseq-list seq start (or end (length seq)))))") (subsequencep (pointers) "See [system-utilities].") (subsetp (lists acl2-built-ins) "Test if every [47m[member][0m of one list is a [47m[member][0m of the other General Forms: (subsetp x y) (subsetp x y :test 'eql) ; same as above (eql as equality test) (subsetp x y :test 'eq) ; same, but eq is equality test (subsetp x y :test 'equal) ; same, but equal is equality test [47m(Subsetp x y)[0m is true if and only if every [47m[member][0m of the list [47mx[0m is a [47mmember[0m of the list [47my[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing members of the two lists. The [guard] for a call of [47msubsetp[0m depends on the test. In all cases, both arguments must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then one of the arguments must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47msubsetp[0m and its variants: [47m(subsetp-eq x lst)[0m is equivalent to [47m(subsetp x lst :test 'eq)[0m; [47m(subsetp-equal x lst)[0m is equivalent to [47m(subsetp x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47msubsetp-equal[0m. [31;1mFunction: [0m<subsetp-equal> (defun subsetp-equal (x y) (declare (xargs :guard (and (true-listp y) (true-listp x)))) (cond ((endp x) t) ((member-equal (car x) y) (subsetp-equal (cdr x) y)) (t nil))) [47mSubsetp[0m is defined by Common Lisp. See any Common Lisp documentation for more information.") (subsetp-eq (pointers) "See [subsetp].") (subsetp-equal (pointers) "See [subsetp].") (subst (conses acl2-built-ins) "A single substitution into a tree [47m(Subst new old tree)[0m is obtained by substituting [47mnew[0m for every occurrence of [47mold[0m in the given tree. Equality to [47mold[0m is determined using the function [47m[eql][0m. The [guard] for [47m(subst new old tree)[0m requires [47m(eqlablep old)[0m, which ensures that the [guard] for [47m[eql][0m will be met for each comparison generated by [47msubst[0m. [47mSubst[0m is defined in Common Lisp. See any Common Lisp documentation for more information. [31;1mFunction: [0m<subst> (defun subst (new old tree) (declare (xargs :guard (eqlablep old))) (cond ((eql old tree) new) ((atom tree) tree) (t (cons (subst new old (car tree)) (subst new old (cdr tree))))))") (subst-expr (pointers) "See [system-utilities].") (subst-var (pointers) "See [system-utilities].") (substitute (lists strings acl2-built-ins) "Substitute into a string or a list, using [47m[eql][0m as test [47m(Substitute new old seq)[0m is the result of replacing each occurrence of [47mold[0m in [47mseq[0m, which is a list or a string, with [47mnew[0m. The guard for [47msubstitute[0m requires that either [47mseq[0m is a string and [47mnew[0m is a character, or else: [47mseq[0m is a [47m[true-listp][0m such that either all of its members are [47m[eqlablep][0m or [47mold[0m is [47meqlablep[0m. [47mSubstitute[0m is a Common Lisp function. See any Common Lisp documentation for more information. Since ACL2 functions cannot take keyword arguments (though macros can), the test used in [47msubstitute[0m is [47meql[0m. [31;1mFunction: [0m<substitute> (defun substitute (new old seq) (declare (xargs :guard (or (and (stringp seq) (characterp new)) (and (true-listp seq) (or (eqlablep old) (eqlable-listp seq)))))) (if (stringp seq) (coerce (substitute-ac new old (coerce seq 'list) nil) 'string) (substitute-ac new old seq nil)))") (subsumption_of_induction_candidates_in_app_example (pages_written_especially_for_the_tours) "Subsumption of Induction Candidates in App Example After collecting induction suggestions from these three terms (app [31;1ma[0m b) (app [31;1mb[0m c) (app [31;1ma[0m (app b c)) the system notices that the first and last suggest the same decomposition of [47ma[0m: case split on whether [47ma[0m is empty (i.e., [47m(endp a)[0m), and in the case where it is not empty, recursively process [47m(cdr a)[0m. So we are left with two ideas about how to induct: Decompose [31;1ma[0m as we would to unwind (app [31;1ma[0m b). Decompose [31;1mb[0m as we would to unwind (app [31;1mb[0m c).") (subversive-inductions (miscellaneous) "Why we restrict [encapsulate]d recursive functions See [subversive-recursions].") (subversive-recursions (miscellaneous) "Why we restrict [encapsulate]d recursive functions Subtleties arise when one of the ``constrained'' functions, [47mf[0m, introduced in the [signature] of an [47m[encapsulate][0m event, is involved in the termination argument for a non-local recursively defined function, [47mg[0m, in that [47mencapsulate[0m. During the processing of the encapsulated events, [47mf[0m is locally defined to be some witness function, [47mf'[0m. Properties of [47mf'[0m are explicitly proved and exported from the encapsulate as the constraints on the undefined function [47mf[0m. But if [47mf[0m is used in a recursive [47mg[0m defined within the encapsulate, then the termination proof for [47mg[0m may use properties of [47mf'[0m --- the witness --- that are not explicitly set forth in the constraints stated for [47mf[0m. Such recursive [47mg[0m are said be ``subversive'' because if naively treated they give rise to unsound induction schemes or (via functional instantiation) recurrence equations that are impossible to satisfy. We illustrate what could go wrong below. Subversive recursions are not banned outright. Instead, they are treated as part of the constraint. That is, in the case above, the definitional equation for [47mg[0m becomes one of the constraints on [47mf[0m. This is generally a severe restriction on future functional instantiations of [47mf[0m. In addition, ACL2 removes from its knowledge of [47mg[0m any suggestions about legal inductions to ``unwind'' its recursion. What should you do? Often, the simplest response is to move the offending recursive definition, e.g., [47mg[0m, out of the encapsulate. That is, introduce [47mf[0m by constraint and then define [47mg[0m as an ``independent'' event. You may need to constrain ``additional'' properties of [47mf[0m in order to admit [47mg[0m, e.g., constrain it to reduce some ordinal measure. However, by separating the introduction of [47mf[0m from the admission of [47mg[0m you will clearly identify the necessary constraints on [47mf[0m, functional instantiations of [47mf[0m will be simpler, and [47mg[0m will be a useful function which suggests inductions to the theorem prover. Note that the functions introduced in the [signature] should not even occur ancestrally in the termination proofs for non-local recursive functions in the encapsulate. That is, the constrained functions of an encapsulate should not be reachable in the dependency graph of the functions used in the termination arguments of recursive functions in encapsulate. If they are reachable, their definitions become part of the constraints. The following event illustrates the problem posed by subversive recursions. (encapsulate (((f *) => *)) (local (defun f (x) (cdr x))) (defun g (x) (if (consp x) (not (g (f x))) t))) Suppose, contrary to how ACL2 works, that the encapsulate above were to introduce no constraints on [47mf[0m on the bogus grounds that the only use of [47mf[0m in the encapsulate is in an admissible function. We discuss the plausibility of this bogus argument in a moment. Then it would be possible to prove the theorem: (defthm f-not-identity (not (equal (f '(a . b)) '(a . b))) :rule-classes nil :hints (("Goal" :use (:instance g (x '(a . b)))))) simply by observing that if [47m(f '(a . b))[0m were [47m'(a . b)[0m, then [47m(g '(a . b))[0m would be [47m(not (g '(a . b)))[0m, which is impossible. But then we could functionally instantiate [47mf-not-identity[0m, replacing [47mf[0m by the identity function, to prove [47mnil[0m! This is bad. (defthm bad nil :rule-classes nil :hints (("Goal" :use (:functional-instance f-not-identity (f identity))))) This sequence of events was legal in versions of ACL2 prior to Version 1.5. When we realized the problem we took steps to make it illegal. However, our steps were insufficient and it was possible to sneak in a subversive function (via mutual recursion) as late as Version 2.3. We now turn to the plausibility of the bogus argument above. Why might one even be tempted to think that the definition of [47mg[0m above poses no constraint on [47mf[0m? Here is a very similar encapsulate. (encapsulate (((f *) => *)) (local (defun f (x) (cdr x))) (defun map (x) (if (consp x) (cons (f x) (map (cdr x))) nil))) Here [47mmap[0m plays the role of [47mg[0m above. Like [47mg[0m, [47mmap[0m calls the constrained function [47mf[0m. But [47mmap[0m truly does not constrain [47mf[0m. In particular, the definition of [47mmap[0m could be moved ``out'' of the encapsulate so that [47mmap[0m is introduced afterwards. The difference between [47mmap[0m and [47mg[0m is that the constrained function plays no role in the termination argument for the one but does for the other. As a ``user-friendly'' gesture, ACL2 implicitly moves [47mmap[0m-like functions out of encapsulations; logically speaking, they are introduced after the encapsulation. This simplifies the constraint. When the constraint cannot be thus simplified the user is advised, via the ``infected'' warning, to phrase the encapsulation in the simplest way possible. See [infected-constraints]. The lingering bug between Versions 1.5 and 2.3 mentioned above was due to our failure to detect the [47mg[0m-like nature of some functions when they were defined in mutually recursively cliques with other functions. The singly recursive case was recognized. The bug arose because our detection ``algorithm'' was based on the ``suggested inductions'' left behind by successful definitions. We failed to recall that mutually-recursive definitions do not, as of this writing, make any suggestions about inductions and so did not leave any traces of their subversive natures. We conclude by elaborating on the criterion ``involved in the termination argument'' mentioned at the outset. Suppose that function [47mf[0m is recursively defined in an [47m[encapsulate][0m, where the body of [47mf[0m has no ``ancestor'' among the functions introduced in the signature of that [47m[encapsulate][0m, i.e.: the body contains no call of a signature function, no call of a function whose body calls a signature function, and so on. Then ACL2 treats [47mf[0m as though it is defined in front of that [47mencapsulate[0m form; so [47mf[0m is not [47mconstrained[0m by the encapsulate, and its definition is hence certainly not subversive in the sense discussed above. But suppose to the contrary that some function introduced in the signature is an ancestor of the body of [47mf[0m. Then the definition of [47mf[0m is subversive if moreover, its termination proof obligation has an ancestor among the signature functions. Now, that proof obligation involves terms from the first argument of selected calls of [47mIF[0m, as well as recursive calls; for a detailed discussion, see [rulers]. The important point here is that for the recursive calls, only the arguments in ``measured'' positions are relevant to the termination proof obligation. Consider the following example. (encapsulate (((h *) => *)) (local (defun h (n) n)) (defun f (i n) (if (zp i) n (f (1- i) (h n))))) ACL2 heuristically picks the measure [47m(acl2-count i)[0m for the definition of [47mf[0m; thus, [47mi[0m is the only ``measured formal'' of [47mf[0m. Since [47mi[0m is the first formal of [47mf[0m, then for the recursive call of [47mf[0m, only the first argument contributes to the termination proof obligation: in this case, [47m(1- i)[0m but not [47m(h n)[0m. Thus, even though [47mh[0m is a signature function, the definition of [47mf[0m is not considered to be subversive; an induction scheme is thus stored for [47mf[0m. (This restriction to measured formal positions of recursive calls, for determining subversive definitions, is new in Version_3.5 of ACL2.)") (suggested_inductions_in_the_associativity_of_app_example (pages_written_especially_for_the_tours) "Suggested Inductions in the Associativity of App Example To find a plausible induction argument, the system studies the recursions exhibited by the terms in the conjecture. Roughly speaking, a call of a recursive function ``suggests'' an induction if the argument position decomposed in recursion is occupied by a variable. In this conjecture, three terms suggest inductions: (app [31;1ma[0m b) (app [31;1mb[0m c) (app [31;1ma[0m (app b c)) The variable recursively decomposed is indicated in [31;1mbold[0m.") (suitably-tamep-listp (pointers) "See [tame].") (sum$ (pointers) "See [loop$].") (sum$+ (pointers) "See [loop$].") (summary (output-controls) "The summary printed at the conclusion of an event At the conclusion of an [event] form, ACL2 prints (by default) information summarizing the event. The entire summary may be avoided --- see [set-inhibit-output-lst] --- or if you prefer, you may inhibit just specified components of the summary --- see [set-inhibited-summary-types]. The components are listed in the constant [47m*summary-types*[0m and most are available programmatically: see [get-event-data]. Some are omitted, however, if they would otherwise be empty. Here is a brief summary of the components, listed alphabetically. Most are printed with an initial field indicator, e.g., ``[47mRules: [0m''; a few, as indicated below, are not. * [47mErrors[0m (no field indicator): The final error message * [47mForm[0m (no field indicator): The ``context'' for the event ([ctx]) * [47mHeader[0m (no field indicator): The initial word ``Summary'' * [47mHint-events[0m: Certain hints (e.g., [47m:use[0m hints) supplied * [47mRedundant[0m: There is field indicator, but a message is printed that notes a redundant event (see [redundant-events]) above the rest of the summary. That message is printed even when [47mSUMMARY[0m output or the [47mREDUNDANT[0m summary-type is inhibited, if [47mEVENT[0m output is not inhibited. * [47mRules[0m: [Rune]s contributing to the proof or storage of the event * [47mSplitter-rules[0m: Potential causes of case splits (see [splitter]) * [47mSteps[0m (field indicator is [47m"Prover steps counted"[0m): Prover steps (see [set-prover-step-limit]) * [47mSystem-attachments[0m: List of doublets [47m(f g)[0m for which [47mf[0m is a system function with attachment [47mg[0m (see [defattach]), when [47mg[0m differs from the initial attachment to [47mf[0m * [47mTime[0m: Runtime (or real time; see [get-internal-time]) * [47mValue[0m: When an event form under [47m[progn][0m or [47m[encapsulate][0m evaluates to [47m(mv nil val state)[0m, [47mval[0m is printed immediately under the summary fields. (No field indicator) * [47mWarnings[0m: All warning string summaries printed during processing of the event Subtopics [Checkpoint-summary-limit] Control printing of key checkpoints upon a proof's failure") (summary-of-acl2-system-distribution (installation-support) "Summary of ACL2 system distribution This topic discusses a distribution that includes only the ACL2 system, without the [community-books]. See [installation-instructions] for how to obtain a gzipped tarfile that contains both the ACL2 sources and community books. Below we describe the ACL2 distribution only (without the community books). Its files are available by obtaining a gzipped tarfile, {acl2.tar.gz | https://www.cs.utexas.edu/users/moore/acl2/v8-6/distrib/acl2.tar.gz}. If you download this file and extract it with tar xfz acl2.tar.gz then you will create a subdirectory, [47macl2-sources[0m, which is approximately the usual ACL2 distribution (see [installation-instructions]) without the [47mbooks[0m subdirectory. Among its contents, in addition to the ACL2 source files, are the following. LICENSE ; ACL2 license file GNUmakefile ; For use with GNU make TAGS ; Handy for looking at source files with emacs TAGS-acl2-doc ; Handy for finding code in books, e.g., with the acl2-doc browser acl2-customization-files/ ; Useful for certifying books, e.g., with ACL2(p) bin/ ; Contains an executable script, bin/acl2, which invokes ACL2 doc/ ; ACL2 documentation emacs/ ; Some helpful emacs utilities Also available are {images/ | https://www.cs.utexas.edu/users/moore/acl2/v8-6/distrib/images/}, which may contain executables; see {images/Readme.html | https://www.cs.utexas.edu/users/moore/acl2/v8-6/distrib/images/Readme.html} GitHub Distributions We strongly recommend that ACL2 users update their local copies of the system and [community-books] every time there is an ACL2 release. While that should suffice for many ACL2 users, nevertheless for those who prefer to obtain the latest developments, the ACL2 source code and community books are available between ACL2 releases, by way of revision control using git. See the {GitHub ACL2 project website | https://github.com/acl2/acl2} for more information.") (swap-stobjs (stobj acl2-built-ins) "Swap two congruent [stobj]s See [stobj] for relevant background on single-threaded objects. The macro call [47m(swap-stobjs st1 st2)[0m is allowed when [47mst1[0m and [47mst2[0m are congruent [stobj]s. The logical meaning is simply to return the two stobjs in reverse order, [47m(list st2 st1)[0m: [31;1mMacro: [0m<swap-stobjs> (defmacro swap-stobjs (x y) (cons 'progn$ (cons (cons 'mv (cons y (cons x 'nil))) 'nil))) However, for purposes of tracking single-threadedness, the result [47m(mv st2 st1)[0m of [47m(swap-stobjs st1 st2)[0m is treated as a list of new values for the stobjs [47mst1[0m and [47mst2[0m, respectively. That is, after this call of [47mswap-stobjs[0m, the new value of stobj [47mst1[0m is considered to be the old value of [47mst2[0m, and the new value of stobj [47mst2[0m is considered to be the old value of [47mst1[0m. This is illustrated by the following example. (defstobj st1 fld1) (defstobj st2 fld2 :congruent-to st1) (defstobj st3 fld3 :congruent-to st1) (defun foo (st1 st2) (declare (xargs :stobjs (st1 st2))) (swap-stobjs st1 st2)) ; Initialize: (update-fld1 3 st1) (update-fld2 4 st2) ; Swap: (foo st1 st2) ; Check that the swap took place: (assert-event (equal (fld2 st2) 3)) (assert-event (equal (fld1 st1) 4)) The example above is essentially the first of several that may be found in the [community-book], [47mbooks/system/tests/swap-stobjs.lisp[0m. Those examples illustrate that [47mswap-stobjs[0m has the expected effect even when stobjs are involved that are bound by [47m[with-local-stobj][0m or [47m[stobj-let][0m. It also explains subtle interaction with [47m[trans-eval][0m. For another example, see [47mbooks/demos/swap-stobj-fields.lisp[0m. In the example above, we call [47mfoo[0m rather than calling [47mswap-stobjs[0m directly. That is because [47mswap-stobjs[0m calls must not be made directly in the top-level loop. Instead, put those calls in function bodies or in theorems. Both inputs to [47mswap-stobjs[0m are required to be [stobj]s. However, the usual tracking of stobjs is relaxed during proofs. See [live-stobj-in-proof] for an error caused by [47m[swap-stobjs][0m during a proof when exactly one of the arguments is truly a stobj (i.e., a so-called ``live'' stobj).") (symbol-alistp (alists acl2-built-ins) "Recognizer for association lists with symbols as keys [47m(Symbol-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of the form [47m(cons key val)[0m where [47mkey[0m is a [47m[symbolp][0m. [31;1mFunction: [0m<symbol-alistp> (defun symbol-alistp (x) (declare (xargs :guard t)) (cond ((atom x) (eq x nil)) (t (and (consp (car x)) (symbolp (car (car x))) (symbol-alistp (cdr x))))))") (symbol-class (pointers) "See [system-utilities].") (symbol-doublet-listp (pointers) "See [system-utilities].") (symbol-listp (symbols lists acl2-built-ins) "Recognizer for a true list of symbols The predicate [47msymbol-listp[0m tests whether its argument is a true list of symbols. [31;1mFunction: [0m<symbol-listp> (defun symbol-listp (lst) (declare (xargs :guard t)) (cond ((atom lst) (eq lst nil)) (t (and (symbolp (car lst)) (symbol-listp (cdr lst))))))") (symbol-name (symbols acl2-built-ins) "The name of a symbol (a string) Completion Axiom ([47mcompletion-of-symbol-name[0m): (equal (symbol-name x) (if (symbolp x) (symbol-name x) "")) [Guard] for [47m(symbol-name x)[0m: (symbolp x)") (symbol-name-lst (symbols acl2-built-ins) "Lift [47m[symbol-name][0m to lists This function returns the list of [47m[symbol-name][0ms of a given list of symbols. [31;1mFunction: [0m<symbol-name-lst> (defun symbol-name-lst (lst) (declare (xargs :guard (symbol-listp lst))) (cond ((endp lst) nil) (t (cons (symbol-name (car lst)) (symbol-name-lst (cdr lst))))))") (symbol-package-name (symbols packages acl2-built-ins) "The name of the package of a symbol (a string) WARNING: While [47msymbol-package-name[0m behaves properly on all ACL2 objects, it may give surprising results when called in raw Lisp. For more details see [pkg-imports], in particular the discussion there of the [47m"COMMON-LISP"[0m package. Completion Axiom ([47mcompletion-of-symbol-package-name[0m): (equal (symbol-package-name x) (if (symbolp x) (symbol-package-name x) "")) [Guard] for [47m(symbol-package-name x)[0m: (symbolp x) Note: [47mSymbol-package-name[0m may diverge from the name of the symbol's package in raw Lisp, in the case that this package is the main Lisp package. For example, in GCL [47m(symbol-package-name 'car)[0m evaluates to "COMMON-LISP" even though the actual package name for the symbol, [47mcar[0m, is "LISP".") (symbol< (symbols acl2-built-ins) "Less-than test for symbols [47m(symbol< x y)[0m is non-[47mnil[0m if and only if either the [47m[symbol-name][0m of the symbol [47mx[0m lexicographically precedes the [47m[symbol-name][0m of the symbol [47my[0m (in the sense of [47m[string<][0m) or else the [47m[symbol-name][0ms are equal and the [47m[symbol-package-name][0m of [47mx[0m lexicographically precedes that of [47my[0m (in the same sense). So for example, [47m(symbol< 'abcd 'abce)[0m and [47m(symbol< 'acl2::abcd 'foo::abce)[0m are true. The [guard] for [47msymbol[0m specifies that its arguments are symbols. [31;1mFunction: [0m<symbol<> (defun symbol< (x y) (declare (xargs :guard (and (symbolp x) (symbolp y)))) (let ((x1 (symbol-name x)) (y1 (symbol-name y))) (or (string< x1 y1) (and (equal x1 y1) (string< (symbol-package-name x) (symbol-package-name y))))))") (symbolic_execution_of_models (pages_written_especially_for_the_tours) "Symbolic Execution of Models {IMAGE} (see [Proving_Theorems_about_Models]) But ACL2 is more than a programming language. Initialize [31;1mx[0m to 5 and let [31;1my[0m be [31;1many legal value[0m. {IMAGE} Because ACL2 is a mathematical language, we can simplify the expression (lookup 'z (mc (s 'mult 5 y) 29)) and get (+ y y y y y). This is [31;1msymbolic execution[0m because not all of the parameters are known. {IMAGE} (see [Proving_Theorems_about_Models])") (symbolp (symbols acl2-built-ins) "Recognizer for symbols [47m(symbolp x)[0m is true if and only if [47mx[0m is a symbol. Subtopics [Intern] Create a new symbol in a given package [Intern$] Create a new symbol in a given package [Intern-in-package-of-symbol] Create a symbol with a given name") (symbols (programming) "Symbols in ACL2 and operations on them Symbols are a basic datatype in ACL2 and Common Lisp. Every symbol has two components: its name (see [symbol-name]) and its package name (see [symbol-package-name]). When symbols are read by Common Lisp or ACL2, they are converted to upper case. Note carefully that this remark applies to the characters in [3msymbols[0m. The characters in strings are not converted to upper case. To type a symbol containing lower case characters you can enclose the symbol in vertical bars, as in [47m|AbC|[0m, or you can put a ``backslash'' before each lower case character you wish to preserve, as in [47mA\bC[0m. [47m|AbC|[0m and [47mA\bC[0m are two different ways of writing the same symbol (just like 2/4 and 1/2 are two different ways of writing the same rational and 123 and 0123 are two different ways to write the same natural number). The symbol has three characters in its name, the middle one of which is a lower case b. Subtopics [Add-to-set] Add a symbol to a list [Keywordp] Recognizer for keywords [Packn] Build a symbol from a list [Packn-pos] Build a symbol in a specified package from a list [Set-print-case] Control whether [symbols] are printed in upper case or in lower case [Symbol-listp] Recognizer for a true list of symbols [Symbol-name] The name of a symbol (a string) [Symbol-name-lst] Lift [47m[symbol-name][0m to lists [Symbol-package-name] The name of the package of a symbol (a string) [Symbol<] Less-than test for symbols [Symbolp] Recognizer for symbols") (sync-ephemeral-whs-with-persistent-whs (wormhole) "establishing wormhole coherence General Form: (sync-ephemeral-whs-with-persistent-whs name state) where [47mname[0m is the quoted name of a [47m[wormhole][0m other than one of the built-in ACL2 system wormholes. It is forbidden to invoke [47msync-ephemeral-whs-with-persistent-whs[0m on the names listed in the constant [47m*protected-system-wormhole-names*[0m which includes [47mbrr[0m (the [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and [47mfc-wormhole[0m (the name of the wormhole managing [forward-chaining-reports]), among others. If executed on the live state and while in the named wormhole, this function moves the wormhole's status from the persistent-whs (located in that part of the memory outside of ACL2's state) to the ephemeral-whs (the value of the state global variable [47mwormhole-status[0m). Subsequently, [47mname[0m's persistent-whs is equal to its ephemeral-whs: the [47mname[0m wormhole is coherent. If executed on a state other than the live one or while outside of the named wormhole, this function is a no-op. Of course, the next time the [47mname[0m wormhole is entered it will be in a coherent state since entry to a wormhole initializes the [47mwormhole-status[0m to the persistent-whs. [47msync-ephemeral-whs-with-persistent-whs[0m returns the new state. Logically speaking, this function uses [47m[read-ACL2-oracle][0m to obtain the wormhole's hidden status. So the output state is almost certainly different than the input state. See [wormhole-programming-tips] for some tips for using this function.") (syntactically-clean-lambda-objects-theory (theories theory-functions rewrite) "how to specify syntactic cleaning of lambda objects The enabled status of two [47mrewrite-lambda-modep[0m runes are used as flags to determine the action taken when eligible [47mlambda[0m objects are encountered by the ACL2 rewriter. See [rewrite-lambda-object] and [47m[rewrite-lambda-object-actions][0m. To prevent the rewriter from diving recursively into the body of an eligible [47mlambda[0m object but use a simpler syntactic cleaning process instead, the rune [47m(:executable-counterpart rewrite-lambda-modep)[0m must be enabled and the rune [47m(:definition rewrite-lambda-modep)[0m must be disabled in the then-current theory. The 0-ary function [47msyntactically-clean-lambda-objects-theory[0m returns such a theory. In fact, diving into eligible quoted [47mlambda[0m object constants to rewrite the body is the default action when ACL2 starts up. See [rewriting-versus-cleaning-up-lambda-objects] for why you might want to change the default action when eligible [47mlambda[0m objects are encountered by the rewriter. The expression [47m(syntactically-clean-lambda-objects-theory)[0m macroexpands to the theory expression (e/d ((:executable-counterpart rewrite-lambda-modep)) ((:definition rewrite-lambda-modep))) which is a theory equal to then current theory except that the executable-counterpart rune of [47mrewrite-lambda-modep[0m but the definition rune is disabled. This expansion is suitable for use in an [47m[in-theory][0m event or [47m:in-theory[0m hint (see [47m:[0m[47m[hints][0m). Both these two runes are initially enabled, so eligible [47mlambda[0m object bodies are rewritten by default until and unless some event (e.g., an [47m[in-theory][0m or [47m[include-book][0m) or a superior local subgoal hint changes the status of those runes. For example, if [47mlambda[0m object rewriting is active you wish to just syntactically clean the [47mlambda[0m objects in [47mSubgoal 3[0m of some proof, you could use the [47m:[0m[47m[hints][0m ("Subgoal 3" :in-theory (syntactically-clean-lambda-objects-theory)) Note that if you also wish to enable or disable other runes in the same subgoal you must construct an appropriate theory. For example, if in [47mSubgoal 3[0m of some proof you wanted to enable [47mLEMMA1[0m and disable [47mLEMMA2[0m in a theory that will also specify syntactic cleaning of [47mlambda[0m objects, you might write ("Subgoal 3" :in-theory (set-difference-theories (union-theories (syntactically-clean-lambda-objects-theory) '(LEMMA1)) '(LEMMA2))) Some users might prefer ("Subgoal 3" :in-theory (e/d ((:executable-counterpart rewrite-lambda-modep) LEMMA1) ((:definition rewrite-lambda-modep) LEMMA2))) See [theories] for general information about theories and how to create and use them.") (syntax (miscellaneous) "The syntax of ACL2 is that of Common Lisp For the details of ACL2 syntax, see CLTL. For examples of ACL2 syntax, use [47m:[0m[47m[pe][0m to print some of the ACL2 system code. For example: :pe assoc-equal :pe dumb-occur :pe var-fn-count :pe add-linear-variable-to-alist There is no comprehensive description of the ACL2 syntax yet, except that found in CLTL. Also see [term].") (syntaxp (rewrite definition linear meta) "Attach a heuristic filter on a rule A call of [47msyntaxp[0m in the hypothesis of a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule is treated specially, as described below. Similar treatment is given to the evaluation of a [47m:[0m[47m[meta][0m rule's hypothesis function call. For example, consider the [47m:[0m[47m[rewrite][0m rule created from the following formula. Example: (IMPLIES (SYNTAXP (NOT (AND (CONSP X) (EQ (CAR X) 'NORM)))) (EQUAL (LXD X) (LXD (NORM X)))). The [47msyntaxp[0m hypothesis in this rule will allow the rule to be applied to [47m(lxd (trn a b))[0m but will not allow it to be applied to [47m(lxd (norm a))[0m. General Form: (SYNTAXP test) [47mSyntaxp[0m always returns [47mt[0m and so may be added as a vacuous hypothesis. However, when relieving the hypothesis, the test ``inside'' the [47msyntaxp[0m form is actually treated as a meta-level proposition about the proposed instantiation of the rule's variables and that proposition must evaluate to true (non-[47mnil[0m) to ``establish'' the [47msyntaxp[0m hypothesis. Note that the test of a [47msyntaxp[0m hypothesis does not, in general, deal with the meaning or semantics or values of the terms, but rather with their syntactic forms. In the example above, the [47msyntaxp[0m hypothesis allows the rule to be applied to every target of the form [47m(lxd u)[0m, provided [47mu[0m is not of the form [47m(norm v)[0m. Observe that without this syntactic restriction the rule above could loop, producing a sequence of increasingly complex targets [47m(lxd a)[0m, [47m(lxd (norm a))[0m, [47m(lxd (norm (norm a)))[0m, etc. An intuitive reading of the rule might be ``[47mnorm[0m the argument of [47mlxd[0m unless it has already been [47mnorm[0med.'' Note also that a [47msyntaxp[0m hypothesis deals with the syntactic form used internally by ACL2, rather than that seen by the user. In some cases these are the same, but there can be subtle differences with which the writer of a [47msyntaxp[0m hypothesis must be aware. You can use [47m:[0m[47m[trans][0m to display this internal representation. There are two types of [47msyntaxp[0m hypotheses. The simpler type may be a hypothesis of a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule provided [47mtest[0m contains at least one variable but no free variables (see [free-variables]). In particular, [47mtest[0m may not use [stobj]s; any stobj name will be treated as an ordinary variable. The case of [47m:[0m[47m[meta][0m rules is similar to the above, except that it applies to the result of applying the hypothesis metafunction. (Later below we will describe the second type, an [3mextended[0m [47msyntaxp[0m hypothesis, which may use [47m[state][0m.) We illustrate the use of simple [47msyntaxp[0m hypotheses by slightly elaborating the example given above. Consider a [47m:[0m[47m[rewrite][0m rule: (IMPLIES (AND (RATIONALP X) (SYNTAXP (NOT (AND (CONSP X) (EQ (CAR X) 'NORM))))) (EQUAL (LXD X) (LXD (NORM X)))) How is this rule applied to [47m(lxd (trn a b))[0m? First, we form a substitution that instantiates the left-hand side of the conclusion of the rule so that it is identical to the target term. In the present case, the substitution replaces [47mx[0m with [47m(trn a b)[0m. (LXD X) ==> (LXD (trn a b)). Then we backchain to establish the hypotheses, in order. Ordinarily this means that we instantiate each hypothesis with our substitution and then attempt to rewrite the resulting instance to true. Thus, in order to relieve the first hypothesis above, we rewrite (RATIONALP (trn a b)). If this rewrites to true, we continue. Of course, many users are aware of some exceptions to this general description of the way we relieve hypotheses. For example, if a hypothesis contains a ``free-variable'' --- one not bound by the current substitution --- we attempt to extend the substitution by searching for an instance of the hypothesis among known truths. See [free-variables]. [47m[Force][0md hypotheses are another exception to the general rule of how hypotheses are relieved. Hypotheses marked with [47msyntaxp[0m, as in [47m(syntaxp test)[0m, are also exceptions. We instantiate such a hypothesis; but instead of rewriting the instantiated instance, we evaluate the instantiated [47mtest[0m. More precisely, we evaluate [47mtest[0m in an environment in which its variable symbols are bound to the quotations of the terms to which those variables are bound in the instantiating substitution. So in the case in point, we (in essence) evaluate (NOT (AND (CONSP '(trn a b)) (EQ (CAR '(trn a b)) 'NORM))). This clearly evaluates to [47mt[0m. When a [47msyntaxp[0m test evaluates to true, we consider the [47msyntaxp[0m hypothesis to have been established; this is sound because logically [47m(syntaxp test)[0m is [47mt[0m regardless of [47mtest[0m. If the test evaluates to [47mnil[0m, we act as though we cannot establish the hypothesis and abandon the attempt to apply the rule; it is always sound to give up. The acute reader will have noticed something odd about the form (NOT (AND (CONSP '(trn a b)) (EQ (CAR '(trn a b)) 'NORM))). When relieving the first hypothesis, [47m(RATIONALP X)[0m, we substituted [47m(trn a b)[0m for [47mX[0m; but when relieving the second hypothesis, [47m(SYNTAXP (NOT (AND (CONSP X) (EQ (CAR X) 'NORM))))[0m, we substituted the quotation of [47m(trn a b)[0m for [47mX[0m. Why the difference? Remember that in the first hypothesis we are talking about the value of [47m(trn a b)[0m --- is it rational --- while in the second one we are talking about its syntactic form. Remember also that Lisp, and hence ACL2, evaluates the arguments to a function before applying the function to the resulting values. Thus, we are asking ``Is the list [47m(trn a b)[0m a [47m[consp][0m and if so, is its [47m[car][0m the symbol [47mNORM[0m?'' The [47mquote[0ms on both [47m(trn a b)[0m and [47mNORM[0m are therefore necessary. One can verify this by defining [47mtrn[0m to be, say [47m[cons][0m, and then evaluating forms such as (AND (CONSP '(trn a b)) (EQ (CAR '(trn a b)) 'NORM)) (AND (CONSP (trn a b)) (EQ (CAR (trn a b)) NORM)) (AND (CONSP (trn 'a 'b)) (EQ (CAR (trn 'a 'b)) NORM)) (AND (CONSP '(trn a b)) (EQ '(CAR (trn a b)) ''NORM)) at the top-level ACL2 prompt. See [syntaxp-examples] for more examples of the use of [47msyntaxp[0m. An extended [47msyntaxp[0m hypothesis is similar to the simple type described above, but it uses two additional variables, [47mmfc[0m and [47mstate[0m, which must not be bound by the left hand side or an earlier hypothesis of the rule. They must be the last two variables mentioned by [47mform[0m; first [47mmfc[0m, then [47mstate[0m. These two variables give access to the functions [47mmfc-[0mxxx; see [extended-metafunctions]. As described there, [47mmfc[0m is bound to the so-called metafunction-context and [47mstate[0m to ACL2's [47m[state][0m. See [syntaxp-examples] for an example of the use of these extended [47msyntaxp[0m hypotheses. We conclude with an example illustrating an error that may occur if you forget that a [47msyntaxp[0m hypothesis will be evaluated in an environment where variables are bound to syntactic terms, not to values. Consider the following [stobj] introduction (see [defstobj]). (defstobj st (fld1 :type (signed-byte 3) :initially 0) fld2) The following [47msyntaxp[0m hypothesis is ill-formed for evaluation. Indeed, ACL2 causes an error because it anticipates that when trying to relieve the [47msyntaxp[0m hypothesis of this rule, ACL2 would be evaluating [47m(fld1 st)[0m where [47mst[0m is bound to a term, not to an actual [47mstobj[0m as required by the function [47mfld1[0m. The error message is intended to explain this problem. ACL2 !>(defthm bad (implies (syntaxp (quotep (fld1 st))) (equal (stp st) (and (true-listp st) (equal (len st) 2) (fld1p (car st)))))) ACL2 Error in ( DEFTHM BAD ...): The form (QUOTEP (FLD1 ST)), from a SYNTAXP hypothesis, is not suitable for evaluation in an environment where its variables are bound to terms. See :DOC SYNTAXP. Here is further explanation: The form ST is being used, as an argument to a call of FLD1, where the single-threaded object of that name is required. But in the current context, the only declared stobj name is STATE. Note: this error occurred in the context (FLD1 ST). Summary Form: ( DEFTHM BAD ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Error in ( DEFTHM BAD ...): See :DOC failure. ******** FAILED ******** ACL2 !> Presumably the intention was to rewrite the term [47m(stp st)[0m when the [47mfld1[0m component of [47mst[0m is seen to be an explicit constant. As explained elsewhere (see [free-variables]), we can obtain the result of rewriting [47m(fld1 st)[0m by binding a fresh variable to that term using [47mEQUAL[0m, as follows. (defthm good (implies (and (equal f (fld1 st)) (syntaxp (quotep f))) (equal (stp st) (and (true-listp st) (equal (len st) 2) (fld1p (car st)))))) The event above is admitted by ACL2. We can see it in action by disabling the definition of [47mstp[0m so that only the rule above, [47mgood[0m, is available for reasoning about [47mstp[0m. (in-theory (disable stp)) Then the proof fails for the following, because the [47msyntaxp[0m hypothesis of the rule, [47mgood[0m, fails: [47m(quotep f)[0m evaluates to [47mnil[0m when [47mf[0m is bound to the term [47m(fld1 st)[0m. (thm (stp st)) However, the proof succeeds for the next form, as we explain below. (thm (stp (list 3 rest))) Consider what happens in that case when rule [47mgood[0m is applied to the term [47m(stp (list 3 rest))[0m. (See [free-variables] for relevant background.) The first hypothesis of [47mgood[0m binds the variable [47mf[0m to the result of rewriting [47m(fld1 st)[0m, where [47mst[0m is bound to the (internal form of) the term [47m(list 3 rest)[0m --- and that result is clearly the term, [47m'3[0m. Then the [47msyntaxp[0m hypothesis is successfully relieved, because the evaluation of [47m(quotep f)[0m returns [47mt[0m in the environment that binds [47mf[0m to [47m'3[0m. Subtopics [Syntaxp-examples] Examples pertaining to syntaxp hypotheses") (syntaxp-examples (syntaxp) "Examples pertaining to syntaxp hypotheses See [syntaxp] for a basic discussion of the use of [47msyntaxp[0m to control rewriting. A common syntactic restriction is (SYNTAXP (AND (CONSP X) (EQ (CAR X) 'QUOTE))) or, equivalently, (SYNTAXP (QUOTEP X)). A rule with such a hypothesis can be applied only if [47mx[0m is bound to a specific constant. Thus, if [47mx[0m is [47m23[0m (which is actually represented internally as [47m(quote 23)[0m), the test evaluates to [47mt[0m; but if [47mx[0m prints as [47m(+ 11 12)[0m then the test evaluates to [47mnil[0m (because [47m(car x)[0m is the symbol [47m[binary-+][0m). We see the use of this restriction in the rule (implies (and (syntaxp (quotep c)) (syntaxp (quotep d))) (equal (+ c d x) (+ (+ c d) x))). If [47mc[0m and [47md[0m are constants, then the [47m[executable-counterpart][0m of [47m[binary-+][0m will evaluate the sum of [47mc[0m and [47md[0m. For instance, under the influence of this rule (+ 11 12 foo) rewrites to (+ (+ 11 12) foo) which in turn rewrites to [47m(+ 23 foo)[0m. Without the syntactic restriction, this rule would loop with the built-in rules [47mASSOCIATIVITY-OF-+[0m or [47mCOMMUTATIVITY-OF-+[0m. We here recommend that the reader try the affects of entering expressions such as the following at the top level ACL2 prompt. (+ 11 23) (+ '11 23) (+ '11 '23) (+ ''11 ''23) :trans (+ 11 23) :trans (+ '11 23) :trans (+ ''11 23) :trans (+ c d x) :trans (+ (+ c d) x) We also recommend that the reader verify our claim above about looping by trying the affect of each of the following rules individually. (defthm good (implies (and (syntaxp (quotep c)) (syntaxp (quotep d))) (equal (+ c d x) (+ (+ c d) x)))) (defthm bad (implies (and (acl2-numberp c) (acl2-numberp d)) (equal (+ c d x) (+ (+ c d) x)))) on (the false) theorems: (thm (equal (+ 11 12 x) y)) (thm (implies (and (acl2-numberp c) (acl2-numberp d) (acl2-numberp x)) (equal (+ c d x) y))). One can use [47m:[0m[47m[brr][0m, perhaps in conjunction with [47m[cw-gstack][0m, to investigate any looping. Here is a simple example showing the value of rule [47mgood[0m above. Without [47mgood[0m, the [47mthm[0m form below fails. (defstub foo (x) t) (thm (equal (foo (+ 3 4 x)) (foo (+ 7 x)))) The next three examples further explore the use of [47mquote[0m in [47m[syntaxp][0m hypotheses. We continue the examples of [47m[syntaxp][0m hypotheses with a rule from community book [47mbooks/finite-set-theory/set-theory.lisp[0m. We will not discuss here the meaning of this rule, but it is necessary to point out that [47m(ur-elementp nil)[0m is true in this book. (defthm scons-nil (implies (and (syntaxp (not (equal a ''nil))) (ur-elementp a)) (= (scons e a) (scons e nil)))). Here also, [47m[syntaxp][0m is used to prevent looping. Without the restriction, [47m(scons e nil)[0m would be rewritten to itself since [47m(ur-elementp nil)[0m is true. Question: Why the use of two quotes in [47m''nil[0m? Hints: [47mNil[0m is a constant just as 23 is. Try [47m:trans (cons a nil)[0m, [47m:trans (cons 'a 'nil)[0m, and [47m:trans (cons ''a ''nil)[0m. Also, don't forget that the arguments to a function are evaluated before the function is applied. The next two rules move negative constants to the other side of an inequality. (defthm |(< (+ (- c) x) y)| (implies (and (syntaxp (quotep c)) (syntaxp (< (cadr c) 0)) (acl2-numberp y)) (equal (< (+ c x) y) (< (fix x) (+ (- c) y))))) (defthm |(< y (+ (- c) x))| (implies (and (syntaxp (quotep c)) (syntaxp (< (cadr c) 0)) (acl2-numberp y)) (equal (< y (+ c x)) (< (+ (- c) y) (fix x))))) Questions: What would happen if [47m(< (cadr c) '0)[0m were used? What about [47m(< (cadr c) ''0)[0m? One can also use [47msyntaxp[0m to restrict the application of a rule to a particular set of variable bindings as in the following taken from the [ihs] library. (encapsulate () (local (defthm floor-+-crock (implies (and (real/rationalp x) (real/rationalp y) (real/rationalp z) (syntaxp (and (eq x 'x) (eq y 'y) (eq z 'z)))) (equal (floor (+ x y) z) (floor (+ (+ (mod x z) (mod y z)) (* (+ (floor x z) (floor y z)) z)) z))))) (defthm floor-+ (implies (and (force (real/rationalp x)) (force (real/rationalp y)) (force (real/rationalp z)) (force (not (equal z 0)))) (equal (floor (+ x y) z) (+ (floor (+ (mod x z) (mod y z)) z) (+ (floor x z) (floor y z)))))) ) We recommend the use of [47m:[0m[47mbrr[0m to investigate the use of [47mfloor-+-crock[0m. Another useful restriction is defined by (defun rewriting-goal-literal (x mfc state) ;; Are we rewriting a top-level goal literal, rather than rewriting ;; to establish a hypothesis from a rewrite (or other) rule? (declare (ignore x state)) (null (access metafunction-context mfc :ancestors))). We use this restriction in the rule (defthm |(< (* x y) 0)| (implies (and (syntaxp (rewriting-goal-literal x mfc state)) (rationalp x) (rationalp y)) (equal (< (* x y) 0) (cond ((equal x 0) nil) ((equal y 0) nil) ((< x 0) (< 0 y)) ((< 0 x) (< y 0)))))) which has been found to be useful, but which also leads to excessive thrashing in the linear arithmetic package if used indiscriminately. See [extended-metafunctions] for information on the use of [47mmfc[0m and [47mmetafunction-context[0m.") (sys-call (interfacing-tools acl2-built-ins) "Make a system call to the host operating system Example Forms: (sys-call "cp" '("foo.lisp" "foo-copied.lisp")) (prog2$ (sys-call "cp" '("foo.lisp" "foo-copied.lisp")) (sys-call-status state)) The first argument of [47msys-call[0m is a command for the host operating system, and the second argument is a list of strings that are the arguments for that command. The use of [47m[prog2$][0m in the second example form above is optional, but illustrates how to get the return status. See [sys-call-status]. [47mSys-call[0m itself always returns [47mnil[0m. [31;1mWARNING[0m: The details of how [47msys-call[0m works can vary among different host Lisp implementations! Consider for example wildcard expansion, such as when executing the form [47m(sys-call "ls" '("*.lisp"))[0m. For ACL2 built on Allegro CL, CCL, CMUCL, GCL, or SBCL, we have seen this result in an error message such as [47m"No such file or directory"[0m, even though files with names of the form [47m*.lisp[0m are present in the current directory; but for ACL2 built on LispWorks, a list of such filenames is printed. More generally, we note that [47msys-call[0m does not provide some features that one may expect of a shell. We mentioned wildcard expansion above; other sorts of shell expansion may also not be supported, such as [47m~/[0m. [47mSys-call[0m also does not directly support output redirection. If you want to run a program, [47mP[0m, and redirect its output, one option is to create a wrapper script, [47mW[0m to call instead. Thus [47mW[0m might be a shell script containing the line: P $* >& foo.out Another approach is suggested by {a passage in the CCL manual | https://ccl.clozure.com/manual/chapter9.2.html}: call the shell program. For example, here is how one might list the [47m.lisp[0m files in a directory. (sys-call "sh" '("-c" "ls *.lisp")) For related utilities, see [sys-call*] and [sys-call+]. Both of those utilities return a suitable status (rather than requiring a separate call of a separate function, [47m[sys-call-status][0m, as described later below). Also, [47msys-call+[0m returns the command's output, but (like [47msys-call[0m) [47msys-call*[0m does not. An important distinction is that both [47msys-call+[0m and [47msys-call*[0m can make their calls to the operating system during proofs, unlike [47msys-call[0m as we now explain. [47mSys-call[0m does not invoke the operating system when it is invoked inside the theorem prover or [proof-builder]. The following example, from Eric Smith, illustrates this point: presumably we only want to reason about the return value, not write a file during a proof! (defttag foo) (thm (equal (sys-call "touch" (list "/tmp/XXX")) nil) :hints (("Goal" :in-theory (disable (:type-prescription sys-call))))) Through Version 7.4, running this example did indeed create file [47m/tmp/XXX[0m if that file did not already exist. Now, the [executable-counterpart] of [47msys-call[0m is disabled, which avoids that specific behavior. Moreover: even with that executable-counterpart enabled, no file is created; [47msys-call[0m returns [47mnil[0m without invoking the operating system. If such an evaluation attempt occurs during invocation of a [clause-processor] or [meta]function, then an error will be signaled. General Form: (sys-call cmd args) This function logically returns [47mnil[0m. However, it makes the indicated call to the host operating system, as described above (not during a proof), using a function supplied ``under the hood'' by the underlying Lisp system. This is an advanced feature that requires a trust tag (see below). As noted above, host lisps differ on their handling of [47msys-call[0m; see the raw Lisp definition of ACL2 source function [47msystem-call[0m for details, including exactly the underlying Lisp code that is invoked. You can then look at that host lisp's manual for details about that underlying function. On occasions where one wishes to obtain the numeric status returned by the host operating system (or more precisely, by the Lisp function under the hood that passes the system call to the host operating system), one may do so; see [sys-call-status]. The status value is the value returned by that Lisp function, which may well be the same numeric value returned by the host operating system for the underlying system call. Note that [47msys-call[0m does not touch the ACL2 [47m[state][0m; however, [47m[sys-call-status][0m updates the [47macl2-oracle[0m field of the [47mstate[0m. Be careful if you use [47msys-call[0m! It can be used for example to overwrite files, or worse! We view a use of [47msys-call[0m as a call to the operating system that is made outside ACL2. The following example from Bob Boyer shows how to use [47msys-call[0m to execute, in effect, arbitrary Lisp forms. ACL2 provides a ``trust tag'' mechanism that requires execution of a [47m[defttag][0m form before you can use [47msys-call[0m; see [defttag]. (Note: The setting of the raw Lisp variable [47m*features*[0m below is just to illustrate that any such mischief is possible. Normally [47m*features*[0m is a list with more than a few elements. Also, note that this log is from many years ago; the feature shown, [47m:AKCL-SET-MV[0m, is no longer present.) % cat foo print *0x85d2064=0x838E920 detach q % acl2 ... boilerplate deleted ACL2 !>(sys-call "gdb -p $PPID -w < foo >& /dev/null " nil) NIL ACL2 !>:q Exiting the ACL2 read-eval-print loop. To re-enter, execute (LP). ACL2>*features* (:AKCL-SET-MV) ACL2> Subtopics [Sys-call*] Make a system call to the host OS, returning a status [Sys-call+] Make a system call to the host OS, returning status and output [Sys-call-status] Exit status from the preceding system call") (sys-call* (sys-call acl2-built-ins) "Make a system call to the host OS, returning a status See [sys-call+] for a closely related utility. There are only the following two differences between [47msys-call*[0m and [47msys-call+[0m. * Both return an [error-triple] [47m(mv erp val state)[0m, but for [47msys-call*[0m, [47mval[0m is always [47mnil[0m after printing as a side effect like [47m[sys-call][0m. (For [47msys-call+[0m, [47mval[0m is the string produced as output by the command.) * Logically, [47msys-call*[0m pops the oracle once, not twice.") (sys-call+ (sys-call acl2-built-ins) "Make a system call to the host OS, returning status and output Example Form: ; The following returns (mv nil s state), where s is the standard output ; from the command: ls -l ./ (sys-call+ "ls" '("-l" "./") state) General Form: (sys-call+ cmd args state) where [47mcmd[0m is a command to the host operating system and [47margs[0m is a list of strings. Also see related utilities [sys-call] and [sys-call*]. There are three major differences between [47m[sys-call][0m and both [47msys-call+[0m and [47msys-call*[0m. First, the latter two take an extra argument, [47mstate[0m. Second, while [47msys-call[0m returns [47mnil[0m, [47msys-call+[0m and [47msys-call*[0m both return an [error-triple], [47m(mv erp val state)[0m. Finally, [47msys-call+[0m and [47msys-call*[0m provide a command to the host operating system even during a proof, which could be useful in computed hints and clause processors. While execution returns values as listed below, further below we explain the logical return values. In the following, please keep in mind that the exact behavior depends on the platform; the description is only a guide. For example, on some platforms [47merp[0m might always be [47mnil[0m, even if in the error case, and [47mval[0m might or might not include error output. (For details, look at the ACL2 source code for function [47msystem-call+[0m, whose output is converted by replacing an [47merp[0m of [47mnil[0m by 0.) [47mErp[0m can be [47mnil[0m, indicating that after the command executes the process status returned is 0, indicating a normal exit. Otherwise [47merp[0m is a non-zero integer, which is the status returned by the process when it completes. [47mVal[0m is a string, typically the output generated by the call of [47mcmd[0m. [47mState[0m is an ACL2 [state]. While the description above pertains to the values returned by executing [47msys-call+[0m, the logical values are as follows. For a discussion of the [47macl2-oracle[0m field of an ACL2 state, see [47m[read-ACL2-oracle][0m and [state]. [47mErp[0m is the first element of the [47macl2-oracle[0m of the input state if that element is a nonzero integer, and otherwise is [47mnil[0m. [47mVal[0m is the second element of the [47macl2-oracle[0m of the input state if it is a string, else the empty string, [47m""[0m. [47mState[0m is the result of popping the [47macl2-oracle[0m field twice from the input state. Note that unlike [47m[sys-call][0m, a call of [47m[sys-call+][0m has no effect on subsequent calls of [47m[sys-call-status][0m. As is the case for [47msys-call[0m, a trust tag is required to call [47msys-call+[0m. For discussion of this and more, see [sys-call].") (sys-call-status (sys-call acl2-built-ins) "Exit status from the preceding system call This function returns two values, [47m(mv status state)[0m. The first is the status resulting from the most recent call to the operating system by invoking function [47m[sys-call][0m. The second is the ACL2 [47m[state][0m object, which is also the input to this function. The function [47m[sys-call][0m provides a command to be executed by the host operating system (except when invoked during a proof; see [sys-call]) using a function supplied ``under the hood'' by the underlying Lisp system. The status value is an integer, which is the status returned by the process when it completes.") (sysfile (books project-dir-alist) "File representation using ACL2 project directories ACL2 supports relocation of book directories so that those books are still treated as certified. See [project-dir-alist]. A key data structure to support this feature is the [3msysfile[0m, which is a pair of the form [47m(:kwd . "relpath")[0m. Here, [47m:kwd[0m is a key of the [47mproject-dir-alist[0m, bound to some absolute pathname [47m"D/"[0m of a directory, and [47m"relpath"[0m is a string that denotes a pathname relative to directory [47m"D/"[0m. Thus, the sysfile [47m(:kwd . "relpath")[0m represents the same pathname as [47m"D/relpath"[0m. (Remark. The name ``sysfile'' was originally coined to suggest ``system file'', suggesting the use of keyword [47m:SYSTEM[0m to indicate a file residing in the [community-books]. It now extends to [47m(:kwd . "relpath")[0m even for [47m:kwd[0m values other than [47m:SYSTEM[0m. But ``sysfile'' is a convenient name, and it still seems reasonable since ``system file'' can suggest a file of the filesystem.) ACL2 rarely generates output that includes sysfiles; they are mostly used in the implementation, for example to denote included books in [certificate] files. But they are occasionally relevant at the user level; for example see [add-include-book-dir]. Finally we discuss the use of sysfiles in [certificate] files. When the [community-books] directory is a prefix of a [full-book-name] string, ACL2 may choose to represent that full-book-name as [47m(:system . "relpath")[0m, where [47m"relpath"[0m is the result of removing the community-books directory from the front of the full-book-name. Here is an example. ; full-book-name: "/Users/smith/acl2/acl2/books/std/portcullis.lisp" ; sysfile representation ; (where "/Users/smith/acl2/acl2/books/" is the community-books directory): (:SYSTEM . "std/portcullis.lisp") This behavior applies to more than the community-books: it applies to the entire [47m[project-dir-alist][0m. If that alist associates keyword [47m:K[0m with absolute directory name [47m"<dir>"[0m, then a full-book-name with prefix [47m"<dir>"[0m, say, [47m"<dir>/relpath"[0m, is written to a [certificate] file as [47m(:K . "relpath")[0m. This capability supports relocating book directories; see [project-dir-alist] for a more complete discussion.") (system-attachments (programming defattach) "System-level algorithms that users can modify with attachments This topic concerns advanced methods for modifying the behavior of ACL2. See [defattach] for some relevant background. If you evaluate the form [47m(global-val 'attachments-at-ground-zero (w state))[0m, you will see a list of pairs of the form [47m(f . g)[0m, where [47mf[0m is a built-in constrained utility and [47mg[0m is its attachment. At the end of this topic is a list that associates each such [47mf[0m with brief documentation (often, just a link). Users are permitted to modify these attachments using [47m[defattach-system][0m, even without a trust tag (see [defttag]), because they do not affect soundness. Here are two functions that are useful for attaching to many attachable 0-ary system functions. [31;1mFunction: [0m<constant-t-function-arity-0> (defun constant-t-function-arity-0 nil (declare (xargs :guard t)) t) [31;1mFunction: [0m<constant-nil-function-arity-0> (defun constant-nil-function-arity-0 nil (declare (xargs :guard t)) nil) To see how to use one of these functions, consider the following example of a pair [47m(f . g)[0m as described above, i.e., a system function [47mf[0m that comes with attachment [47mg[0m. (ASSUME-TRUE-FALSE-AGGRESSIVE-P . CONSTANT-NIL-FUNCTION-ARITY-0) Here is how we can make the so-called ``assume-true-false'' algorithm more aggressive; see [assume-true-false-aggressive-p]. (defattach-system assume-true-false-aggressive-p constant-t-function-arity-0) The following brief explanations are intentionally brief. We expect that those who want to use such system attachments are comfortable as ``system programmers'', so that the brief documentation below is sufficient for getting started. Perusal of the ACL2 source code and its comments can fill in details as needed. Also see [efficiency] for further discussion on making system attachments that modify ACL2's default behavior. Summary of attachable system functions [47mACL2X-EXPANSION-ALIST[0m Built-in attachment: [47mIDENTITY-WITH-STATE[0m [Undocumented: low-level system utility] [47mALWAYS-DO-PROOFS-DURING-MAKE-EVENT-EXPANSION[0m Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m Documentation: See [make-event]. [47mANCESTORS-CHECK[0m Built-in attachment: [47mANCESTORS-CHECK-BUILTIN[0m Documentation: Backchaining control; see [use-trivial-ancestors-check]. Source function [47mstrip-ancestor-literals[0m might also be useful. [47mAPPLY$-USERFN[0m Built-in attachment: [47mDOPPELGANGER-APPLY$-USERFN[0m [Undocumented: low-level system utility] [47mASSUME-TRUE-FALSE-AGGRESSIVE-P[0m Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m Documentation: See [assume-true-false-aggressive-p]. [47mBADGE-USERFN[0m Built-in attachment: [47mDOPPELGANGER-BADGE-USERFN[0m [Undocumented: low-level system utility] [47mBEING-OPENEDP-LIMITED-FOR-NONREC[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: Attach to [47mconstant-nil-function-arity-0[0m to extend to non-recursively defined functions the stack-based limitation on opening recursively-defined functions. [47mBRKPT1-BRR-DATA-ENTRY[0m Built-in attachment: [47mBRKPT1-BRR-DATA-ENTRY-BUILTIN[0m Documentation: See [with-brr-data]. [47mBRKPT2-BRR-DATA-ENTRY[0m Built-in attachment: [47mBRKPT2-BRR-DATA-ENTRY-BUILTIN[0m Documentation: See [with-brr-data]. [47mCONJOIN-CLAUSE-SETS-BOUND[0m Built-in attachment: [47mCONJOIN-CLAUSE-SETS-BOUND-BUILTIN[0m Documentation: Attach to a constant function that returns a natural number (default [47m50[0m) bounding how large a clause-set can be to do smart merging into another clause-set; see comments in the definition of conjoin-clause-sets in the ACL2 sources for more explanation. [47mHEAVY-LINEAR-P[0m Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m Documentation: See [heavy-linear-p]. [47mHIDE-WITH-COMMENT-P[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: See [hide]. [47mONCEP-TP[0m Built-in attachment: [47mONCEP-TP-BUILTIN[0m Documentation: See [free-variables-type-prescription]. [47mPRINT-CLAUSE-ID-OKP[0m Built-in attachment: [47mPRINT-CLAUSE-ID-OKP-BUILTIN[0m Documentation: See [set-print-clause-ids]. [47mQUICK-AND-DIRTY-SRS[0m Built-in attachment: [47mQUICK-AND-DIRTY-SRS-BUILTIN[0m Documentation: See [quick-and-dirty-subsumption-replacement-step]. [47mRELIEVE-HYP-FAILURE-ENTRY-SKIP-P[0m Built-in attachment: [47mRELIEVE-HYP-FAILURE-ENTRY-SKIP-P-BUILTIN[0m [Undocumented: low-level system utility] [47mREMOVE-GUARD-HOLDERS-BLOCKED-BY-HIDE-P[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: See [guard-holders]. [47mREMOVE-GUARD-HOLDERS-LAMP[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: See [guard-holders]. [47mREMOVE-TRIVIAL-EQUIVALENCES-ENABLED-P[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: See [remove-trivial-equivalences-enabled-p]. [47mREWRITE-IF-AVOID-SWAP[0m Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m Documentation: See [rewrite-if-avoid-swap]. [47mRW-CACHE-DEBUG[0m Built-in attachment: [47mRW-CACHE-DEBUG-BUILTIN[0m [Undocumented: low-level system utility] [47mRW-CACHE-DEBUG-ACTION[0m Built-in attachment: [47mRW-CACHE-DEBUG-ACTION-BUILTIN[0m [Undocumented: low-level system utility] [47mRW-CACHEABLE-FAILURE-REASON[0m Built-in attachment: [47mRW-CACHEABLE-FAILURE-REASON-BUILTIN[0m [Undocumented: low-level system utility] [47mSET-LD-HISTORY-ENTRY-USER-DATA[0m Built-in attachment: [47mSET-LD-HISTORY-ENTRY-USER-DATA-DEFAULT[0m Documentation: See [ld-history]. [47mSIMPLIFIABLE-MV-NTH-P[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: See [theories-and-primitives]. [47mTOO-MANY-IFS-POST-REWRITE[0m Built-in attachment: [47mTOO-MANY-IFS-POST-REWRITE-BUILTIN[0m Documentation: Heuristic for discarding rewriter result with ``too many IFs''. Defeat by attaching [47mconstant-nil-function-arity-2[0m. [47mTOO-MANY-IFS-PRE-REWRITE[0m Built-in attachment: [47mTOO-MANY-IFS-PRE-REWRITE-BUILTIN[0m Documentation: Heuristic for skipping rewrite when unrewritten result has ``too many IFs''. Defeat by attaching [47mconstant-nil-function-arity-2[0m. [47mUNTRANSLATE-LAMBDA-OBJECT-P[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: See [lambda$]. [47mUPDATE-BRR-DATA-1[0m Built-in attachment: [47mUPDATE-BRR-DATA-1-BUILTIN[0m Documentation: See [with-brr-data]. [47mUPDATE-BRR-DATA-2[0m Built-in attachment: [47mUPDATE-BRR-DATA-2-BUILTIN[0m Documentation: See [with-brr-data]. [47mUSE-ENHANCED-RECOGNIZER[0m Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m Documentation: Heuristic for treating [47m(equal TERM nil)[0m and [47m(equal nil TERM)[0m as providing a type for [47mTERM[0m during forward-chaining and other operations that assume such a term to be true. [47mWORSE-THAN[0m Built-in attachment: [47mWORSE-THAN-BUILTIN[0m [Undocumented: low-level system utility] [47mWORSE-THAN-OR-EQUAL[0m Built-in attachment: [47mWORSE-THAN-OR-EQUAL-BUILTIN[0m [Undocumented: low-level system utility] Subtopics [Assume-true-false-aggressive-p] Control rewriter's use of the [type-alist] with [47mIF[0m calls [Heavy-linear-p] Extend the use of [linear-arithmetic] during rewriting [Remove-trivial-equivalences-enabled-p] Avoid removal of trivial equivalences during rewriting [Rewrite-if-avoid-swap] Control rewriter's swapping of branches of [47mIF[0m calls") (system-utilities (programming) "Some built-in programming utilities pertaining to the ACL2 system Since the ACL2 system is written in itself, the source code defines many utilities that support the ACL2 implementation. Some of these have been found to be useful not only to the ACL2 developers, but to those who use ACL2 to perform tasks other than the traditional ones: writing and submitting definitions, and proving theorems about the functions defined. This topic provides a summary of some of those utilities that are built into the ACL2 system. It is intended to be a growing document, with contributions from those in the community who find such utilities that benefit them. It has already grown substantially from an initial version created by the ACL2 implementors, and others will likely continue to add to it over time. [31;1mWARNING 1[0m. Some system utilities are in [47m:[0m[47m[program][0m mode, and for many of those, [guard]s are incomplete or missing entirely. Incorrect use of such utilities can thus lead to scary (though often harmless) raw Lisp errors! Although this situation may improve over time, for now users of these utilities must cope with that danger just as the ACL2 implementors cope with it, which is by understanding the requirements on each utility that is invoked. For example, if you incorrectly invoke [47m(untranslate (cons 3 4) nil (w state))[0m, where perhaps [47m(untranslate '(cons '3 '4) nil (w state))[0m was intended, then the resulting raw Lisp error is your responsibility for invoking [47muntranslate[0m on the object [47m(3 . 4)[0m instead of the term [47m(cons '3 '4)[0m. [31;1mWARNING 2[0m. These utilities are subject to change. They were developed to support the ACL2 system, and as ACL2 evolves, its developers claim the right to modify these functions --- even their input-output [signature]s. That said, changes to these functions are likely to be quite rare. The ACL2 system comes with substantial comments. As of Version_7.1 (May, 2015), out of slightly under 10 MB of source code (not including 4.8 MB of [documentation] topics), nearly 400 KB (just over 40%) were comment lines. This topic is not intended to supplant or duplicate those comments, but rather, only to note system utilities of interest to the community. If you find the source comments inadequate, please feel free to ask the system implementors to make corresponding additions to the source code comments. Note that if you execute the command egrep -e '^; Essay on' *.lisp in your ACL2 sources directory, you will see the names of more than 90 long source comments, or ``Essays'', that can provide additional background. Also see [programming] and its subtopics, in particular [programming-with-state], which describes [3mmany[0m built-in system utilities. For example, a subsection of [programming-with-state], entitled ``SEQUENTIAL PROGRAMMING'', introduces handy utilities [47m[pprogn][0m and [47m[er-progn][0m along with links to their documentation. You may also wish to see [system-attachments] for how to make a few changes to the behavior of ACL2. Here is another option for finding a built-in system utility: As ACL2 developers sometimes do, use [47mmeta-.[0m or [47mmeta-x tags-apropos[0m in Emacs to find utilities with given substrings in their names. For example, if in Emacs you submit the command [47mmeta-x tags-apropos[0m and reply [47mpwd[0m at the prompt, you'll find a raw Lisp function [47mour-pwd[0m that ACL2 defines as an analogue to the Linux [47mpwd[0m command; and, with [47mmeta-x tags-search[0m applied to [47m(our-pwd[0m, you can see how ACL2 source code uses this utility. List of a few built-in system utilities Every function mentioned below belongs in the constant [47m[*ACL2-system-exports*][0m. Also see [ACL2-built-ins] for built-in utilities that are less relevant to the ACL2 system, and see [programming] for utilities in general. * [47m(acl2-unwind-protect expl body cleanup1 cleanup2)[0m: This particularly sophisticated utility (warning: for advanced system hackers) is logically just the following (where the formals shown above are capitalized). (mv-let (erp val state) BODY (cond (erp (pprogn CLEANUP1 (mv erp val state))) (t (pprogn CLEANUP2 (mv erp val state))))) However, aborts are typically handled by causing the ``cleanup'' forms to be executed, in the spirit of Common Lisp's [47munwind-protect[0m. In typical use the cleanup forms restore the values of [state] global variables that were ``temporarily'' set by [47mbody[0m. Note that [47mexpl[0m is essentially ignored. For more information see the Essay on Unwind-Protect in the ACL2 source code. * [47m(add-suffix sym str)[0m: Extend a symbol [47msym[0m with a suffix expressed as a string [47mstr[0m. The resulting symbol is in the same package as the original symbol. For instance, [47m(add-suffix 'abc "DEF")[0m results in the symbol [47m'abcdef[0m, in the same package as [47m'abc[0m. See [47m[add-suffix-to-fn][0m for a variant that may be more appropriate for generating new function names. * [47m(add-suffix-to-fn sym suffix)[0m: Variant of [47m[add-suffix][0m that puts the new symbol in the [47m"ACL2"[0m package when [47msym[0m is in the [47m"COMMON-LISP"[0m package. New function symbols cannot be in the [47m"COMMON-LISP"[0m package; thus, this utility may be appropriate when generating new function names from old ones. * [47m(all-attachments wrld)[0m: Return a list of all attachment pairs [47m(f . g)[0m where [47mg[0m is attached to [47mf[0m (see [defattach]) in the [world], [47mwrld[0m, except for two cases that are ignored for this purpose: [warrant]s, and attachments introduced with a non-[47mnil[0m value of [47m:skip-checks[0m. To obtain the attachment to a function symbol [47mf[0m, without the restrictions above and with value [47mnil[0m if there is no attachment to [47mf[0m, evaluate [47m(cdr (attachment-pair 'f wrld))[0m. To obtain the list of all built-in attachments, evaluate [47m(global-val 'attachments-at-ground-zero (w state))[0m. * [47m(all-calls names term alist ans)[0m: Accumulate into [47mans[0m (which typically is [47mnil[0m at the top level) all pseudo-terms [47mu/alist[0m such that for some [47mf[0m in the list, [47mnames[0m, [47mu[0m is a subterm of the pseudo-term, [47mterm[0m, that is a call of the symbol, [47mf[0m. Note that [47m(all-calls-lst names lst alist ans)[0m is similar, except for a list, [47mlst[0m, of terms in place of a single term, [47mterm[0m. * [47m(all-ffn-symbs term ans)[0m: Accumulate into [47mans[0m (which typically is [47mnil[0m at the top level) all function symbols called in the given term. This may become deprecated, and is just a macro expanding to a corresponding call of [47mall-fnnames1[0m; see [47mall-fnnames[0m, [47mall-fnnames-lst[0m, and [47mall-fnnames1[0m, below. * [47m(all-ffn-symbs-lst lst ans)[0m: Accumulate into [47mans[0m (which typically is [47mnil[0m at the top level) all function symbols called in the given list of terms. This may become deprecated, and is just a macro expanding to a corresponding call of [47mall-fnnames1[0m; see [47mall-fnnames[0m, [47mall-fnnames-lst[0m, and [47mall-fnnames1[0m, below. * [47m(all-fnnames term)[0m: Return a list of all function symbols called in the given term. This is a macro call expanding to [47m(all-fnnames1 nil term nil)[0m. * [47m(all-fnnames-lst lst)[0m: Return a list of all function symbols called in the given list of terms. This is a macro call expanding to [47m(all-fnnames1 t lst nil)[0m. * [47m(all-fnnames1 flg x acc)[0m: Accumulate into [47macc[0m the function symbols called in the given term or list of terms, [47mx[0m, according to whether [47mflg[0m is [47mnil[0m (for a term) or not [47mnil[0m (for a list of terms), respectively. * [47m(all-vars x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return a duplicate-free list of all variables in [47mx[0m, in reverse print order of first occurrence. For example, [47mall-vars[0m of [47m'(f (g a b) c)[0m is [47m'(c b a)[0m. * [47m(arglistp lst)[0m: Return true iff [47mlst[0m is a [47mnil[0m-terminated list of distinct, legal variable names, usable as the formal argument list (hence the name of this utility) of a function. * [47m(arity fn w)[0m: For a function symbol or [47mlambda[0m expression [47mfn[0m of [world] [47mw[0m, return the number of its formal parameters. * [47m(body fn normalp w)[0m: [47mFn[0m should either be a [47m:[0m[47m[logic][0m-mode function symbol of [world] [47mw[0m or a [47mlambda[0m expression. If [47mfn[0m is a symbol and [47mnormalp[0m is [47mnil[0m, then return the body (translated but unnormalized) of its original definition. If [47mfn[0m is a [47mlambda[0m expression, return its body. We now discuss the remaining case, where [47mfn[0m is a [47m:[0m[47m[logic][0m-mode function symbol and [47mnormalp[0m is true. In the usual case that no [definition] rule has been introduced for [47mfn[0m with a non-[47mnil[0m value of [47m:install-body[0m (which is the default), return the [normalize]d body from the [47mdefun[0m form that introduced [47mfn[0m, or [47mnil[0m if [47mfn[0m was not introduced with [47mdefun[0m (as with [47m[encapsulate][0m, [47m[defstub][0m, or [47m[defchoose][0m) --- except that in the case that [47m:normalize nil[0m was specified in that [47mdefun[0m form (see [xargs]), return the unnormalized body. The remaining case is that at least one [definition] rule for [47mfn[0m has been installed. In that case, the latest such rule provides the body (see source function [47mlatest-body[0m for how hypotheses are handled), with one exception: if the equivalence relation for that rule is other than [47mequal[0m, then the unnormalized body is returned. * [47m(conjoin lst)[0m: The conjunction of the given list of terms. * [47m(conjoin2 term1 term2)[0m: The conjunction of the given two terms. * [47m(cons-term fn args)[0m: Returns a [term] with function symbol (or [lambda] expression) [47mfn[0m and arguments [47margs[0m. Evaluation may be performed for calls of primitives --- that is, built-in functions without definitions --- on arguments that are quoted constants, for example as follows. ACL2 !>(cons-term 'coerce (list ''"abc" ''list)) '(#\a #\b #\c) ACL2 !> To avoid such evaluation, use [47mfcons-term[0m (``fast cons-term''), described below. Also see [47mcons-term*[0m and [47mfcons-term*[0m below. * [47m(cons-term* fn arg1 arg2 ...)[0m: This variant of [47mcons-term[0m (described above) returns a term with the indicated function and arguments, where the arguments are ``spread'' into individual actual parameters rather than provided as a list. Some simplification may be done; to avoid that, use [47mfcons-term*[0m. Also see [47mcons-term[0m above and [47mfcons-term[0m below. * [47m(default-state-vars state-p &key ...)[0m: Returns a record suitable as an argument for some utilities that take the [world] as an argument but not the [state], such as [47mtranslate-cmp[0m. That record provides values for certain state global variables (which are not stored in the world), such as [47mguard-checking-on[0m (which holds the [guard]-checking mode). As described below, [47mdefault-state-vars[0m provides suitable defaults, which however can be modified by supplying keyword arguments corresponding to certain state globals, such as [47m:guard-checking-on[0m. When the required argument is [47mt[0m, those defaults are the values of those state globals; thus, [47mt[0m is probably the right value to use for that argument when the state is available in the calling context. Otherwise, those defaults are the values commonly found in those state globals. * [47m(defined-constant name w)[0m: If [47mname[0m is [47mt[0m, [47mnil[0m, or defined using [47m[defconst][0m, return [47m(quote val)[0m where [47mval[0m is the value of [47mname[0m; otherwise return [47mnil[0m. * [47m(defun-mode fn w)[0m: If [47mfn[0m is a function symbol, return the [defun-mode] of [47mfn[0m: [47m:program[0m if [47mfn[0m is in [47m:[0m[47m[program][0m mode, [47m:logic[0m if [47mfn[0m is in [47m:[0m[47m[logic][0m mode. If [47mfn[0m is not a function symbol, return [47mnil[0m. * [47m(disabledp name)[0m: The list of [rune]s introduced with [47mname[0m that are currently [disable]d. See [disabledp]. Also see [47menabled-runep[0m, below, for a more direct test of whether a given rune is [enable]d. * [47m(disjoin lst)[0m: The disjunction of the given list of terms. * [47m(disjoin2 term1 term2)[0m: The disjunction of the given two terms. * [47m(doublet-listp x)[0m: Returns [47mt[0m if [47mlst[0m is a list of two-element lists [47m(x1 x2)[0m, else [47mnil[0m. * [47m(dumb-negate-lit t1)[0m: For the given [term] [47mt1[0m, return a term that is propositionally equivalent to [47m(not t1)[0m. * [47m(dumb-occur x y)[0m: Return [47mt[0m if the term [47mx[0m occurs free in the term [47my[0m, but without looking for [47mx[0m inside of quoted constants; else, returns [47mnil[0m. * [47m(dumb-occur-var x y)[0m: Return [47mt[0m if the variable [47mx[0m occurs free in the term [47my[0m, else [47mnil[0m. This is the same as [47mdumb-occur[0m, but optimized for the case that [47mx[0m is a variable. * [47m(enabled-numep nume ens wrld)[0m: Return true iff the given nume (numeric representation of a [rune]) in the [world], [47mwrld[0m, is [enable]d with respect to the given enabled structure, [47mens[0m. (For example, [47m(ens state)[0m returns the global enabled structure; during a proof, the enabled structure comes from the so-called rewrite-constant.) [47mNil[0m is also a valid first argument, in which case the return value is [47mt[0m. See also [47menabled-runep[0m. * [47m(enabled-runep rune ens wrld)[0m: Return true iff the given [rune] in the [world], [47mwrld[0m, is [enable]d with respect to the given enabled structure (as discussed for [47menabled-numep[0m, just above). See also [47menabled-numep[0m, which may be more efficient since [47menabled-runep[0m is defined in terms of [47menabled-numep[0m. * [47m(fargn x n)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is a function call and for a positive integer [47mn[0m, return the [47mn[0m-th argument of [47mx[0m, where the numbering of arguments starts at 1. * [47m(fargs x)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is a function call, return its arguments. * [47m(fcons-term fn args)[0m: This variant of [47mcons-term[0m (described above) returns a term with the indicated function and arguments, without any simplification. Also see [47mcons-term[0m and [47mcons-term*[0m above, and [47mfcons-term*[0m below. * [47m(fcons-term* fn arg1 arg2 ...)[0m: This variant of [47mfcons-term[0m (described above) returns a term with the indicated function and arguments, without any simplification, and where the arguments are ``spread'' into individual actual parameters rather than provided as a list. Also see [47mcons-term[0m, [47mcons-term*[0m, and [47mfcons-term[0m above. * [47m(fdefun-mode fn)[0m: For a function symbol [47mfn[0m, return the [defun-mode] of [47mfn[0m: [47m:program[0m if [47mfn[0m is in [47m:[0m[47m[program][0m mode, [47m:logic[0m if [47mfn[0m is in [47m:[0m[47m[logic][0m mode. * [47m(ffn-symb x)[0m: This version of [47mfn-symb[0m (described below) assumes that [47mx[0m is a [47m[pseudo-termp][0m that is a function call, without checking that [47mx[0m is a function call (the leading ``f'' is for ``fast''), and returns its called function or [47mlambda[0m expression. * [47m(ffn-symb-p x sym)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return [47mt[0m if it is a function call whose function symbol is [47msym[0m, else return [47mnil[0m. * [47m(ffnnamep fn term)[0m: Returns [47mt[0m when the function [47mfn[0m (possibly a [lambda] expression) is used as a function in [47mterm[0m, which is assumed to be a [47m[pseudo-termp][0m; else returns [47mnil[0m. * [47m(ffnnamep-lst fn lst)[0m: Returns [47mt[0m when the function [47mfn[0m (possibly a [lambda] expression) is used as a function in a member of the list [47mlst[0m of [47m[pseudo-termp][0ms; else returns [47mnil[0m. * [47m(fix-pkg pkg)[0m: Returns [47mpkg[0m, which should be [47mnil[0m or a non-empty string, with one exception: if [47mpkg[0m is [47m"COMMON-LISP"[0m then [47m"ACL2"[0m is returned. * [47m(flambda-applicationp x)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is not a variable, return [47mt[0m if it is a function call whose function symbol is a [47mlambda[0m expression, else return [47mnil[0m. * [47m(flambdap fn)[0m: For a [47m[pseudo-termp][0m [47m(fn arg1 ... argk)[0m, true when [47mfn[0m is a [47m[lambda][0m expression * [47m(flatten-ands-in-lit term)[0m: Returns a list of terms whose conjunction is equivalent to the given term (which satisfies [47m[pseudo-termp][0m), obtained by flattening its conjunctive structure. For example, [47m(flatten-ands-in-lit '(if (if x y 'nil) z 'nil))[0m is the list [47m(x y z)[0m. * [47m(fn-rune-nume fn nflg xflg wrld)[0m: For a function symbol [47mfn[0m, return either the [rune] (case [47mnflg[0m = [47mnil[0m) or nume (numeric representation of a rune) (case [47mnflg[0m = [47mt[0m) associated with either [47m(:DEFINITION fn)[0m (case [47mxflg[0m = [47mnil[0m) or [47m(:EXECUTABLE-COUNTERPART fn)[0m (case [47mxflg[0m = [47mt[0m). If [47mfn[0m is a constrained function, return [47mnil[0m for all combinations of the flags. * [47m(fn-symb x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return its called function or [47mlambda[0m expression if [47mx[0m is a function call, otherwise return [47mnil[0m. Also see [47mffn-symb[0m, above. * [47m(formals fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return its list of formal parameters. * [47m(formula name normalp w)[0m: For an event name or [rune], [47mname[0m, of [world] [47mw[0m, return the corresponding formula if any ([normalize]d iff [47mnormalp[0m is true), else [47mnil[0m. See [formula]. * [47m(fquotep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is not a variable, return true iff [47mx[0m is a quoted constant. * [47m(fsubcor-var vars terms form)[0m: This variant of [47msubcor-var[0m (described below) also substitutes, in the [47m[pseudo-termp][0m [47mform[0m, the variables in the list of [47m[symbolp][0ms [47mvars[0m with the corresponding elements in the list of [47m[pseudo-termp][0ms [47mterms[0m, but without performing any simplification. * [47m(function-symbolp sym w)[0m: True when the symbol [47msym[0m is a function symbol in the [world] [47mw[0m. * [47m(genvar pkg-witness prefix n avoid-lst)[0m: Generate a new variable name. * [47m(get-brr-local var state)[0m: The value of brr-local variable [47mvar[0m; this is the utility used by [brr@]. * [47m(get-defun-event name w)[0m: For the given name of a defined function in the current ACL2 [world] [47mw[0m, return its [47m[defun][0m form. Note that this applies to both [47m:[0m[47m[logic][0m-mode and [47m:[0m[47m[program][0m-mode functions, in spite of the name, ``logical'' (which is actually intended to distinguish from ``raw Lisp''). * [47m(get-event name w)[0m: For the given name of an event in the current ACL2 [world] [47mw[0m, return that event. Typically there is only one such event, but for built-in functions the most recent event might be a variant of a [47m[verify-termination][0m event, so consider using [47mget-defun-event[0m for names of functions (see above). * [47m(get-skipped-proofs-p name w)[0m: For the given name of an event in the current ACL2 [world] [47mw[0m, return [47mt[0m if proofs were skipped when introducing that event, as with [47m[skip-proofs][0m or using [47m[set-ld-skip-proofsp][0m --- that is, with proofs skipped other than by the system (as with [47m[include-book][0m); else return [47mnil[0m. Exception: if [47mname[0m is a function symbol that is either built in or in [47m:[0m[47m[program][0m mode, return [47mnil[0m. * [47m(guard fn stobj-optp w)[0m: For a function symbol or [47mlambda[0m expression [47mfn[0m of [world] [47mw[0m, return its [guard]. Optimize the [stobj] recognizers away iff [47mstobj-optp[0m is true. * [47m(implicate t1 t2)[0m: For terms [47mt1[0m and [47mt2[0m, return a term that is propositionally equivalent to [47m(implies t1 t2)[0m. * [47m(io? token commentp shape vars body &key ...)[0m: This is a complex macro that may be most fully understood by reading the source code, including comments in its definition and examples of its use. But the following example from the definition of source function [47mprint-failure1[0m may get the idea across. (io? summary nil state (channel) (fms *proof-failure-string* nil channel state nil)) This is essentially just the [47mbody[0m argument, which here is the indicated [47m[fms][0m call, but where, going through the other arguments: * [47msummary[0m --- evaluation only takes place when [47msummary[0m output is enabled (see [set-inhibit-output-lst]); * [47mnil[0m --- don't enter a wormhole; * [47mstate[0m --- the body (which here is the [47mfms[0m call) returns a single [47mstate[0m value; and finally * [47mchannel[0m --- this is the list of free variables in the body (which here is the [47mfms[0m call). * [47m(known-package-alist state)[0m: Returns a list of package entries, as explained in the definition of [47mmake-package-entry[0m in ACL2 sources, which is followed by simple accessor definitions (all in file [47maxioms.lisp[0m as of this writing). This list includes entries for hidden packages (see [hidden-death-package]). As a package is introduced, its package entry is pushed on the front of the existing known-package-alist. Note that this list can be accessed directly from a [world], [47mw[0m, with: [47m(global-val 'known-package-alist w)[0m. * [47m(lambda-applicationp x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return [47mt[0m if it is a function call whose function symbol is a [47mlambda[0m expression, else return [47mnil[0m. * [47m(lambda-body x)[0m: For a [47mlambda[0m expression [47mx[0m, return its body. * [47m(lambda-formals x)[0m: For a [47mlambda[0m expression [47mx[0m, return its formal parameters. * [47m(legal-constantp name)[0m: Returns [47mt[0m if [47mname[0m is a legal constant name, else [47mnil[0m. * [47m(legal-variablep name)[0m: Returns [47mt[0m if [47mname[0m is a legal variable name, else [47mnil[0m. For example, [47mx[0m is a legal variable name but the following are not: [47m:abc[0m, [47mt[0m, [47mnil[0m, [47m&a[0m (a lambda keyword), [47m*c*[0m (syntax of a constant), and [47mpi[0m (a Common Lisp constant). * [47m(logicp fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return [47mt[0m when the [47msymbol-class[0m of [47mfn[0m in [47mw[0m is not [47m:program[0m, else [47mnil[0m. (See [47msymbol-class[0m, below.) * [47m(make-lambda args body)[0m: Return the [47mlambda[0m expression with formal parameters [47margs[0m and body [47mbody[0m. * [47m(make-lambda-application formals body actuals)[0m: Return the [47mlambda[0m application that is essentially [47m((lambda formals body) . actuals)[0m. However, extra formals and corresponding actuals are added when [47mbody[0m has free variables that do not belong to [47mformals[0m, because lambdas must be closed in ACL2. A similar function is [47mmake-lambda-term[0m, but that one does not drop unused formals, while [47mmake-lambda-application[0m does drop them. * [47m(make-lambda-term formals actuals body)[0m: Return the [47mlambda[0m application that is essentially [47m((lambda formals body) . actuals)[0m. However, extra formals and corresponding actuals are added when [47mbody[0m has free variables that do not belong to [47mformals[0m, because lambdas must be closed in ACL2. A similar function is [47mmake-lambda-application[0m, but that one drops unused formals, while [47mmake-lambda-term[0m does not. * [47m(maybe-convert-to-mv uterm)[0m: Given the untranslated [term] [47muterm[0m, replace each of its top-level calls of [47m[list][0m by a call of [47m[mv][0m on the same arguments. * [47m(nvariablep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return true iff [47mx[0m is not a variable (i.e. it is a quoted constant or a function call). * [47m(partition-rest-and-keyword-args x keys)[0m: [47mx[0m should be a list of the form [47m(a1 ... an :key1 v1 ... :keyk vk)[0m, where no [47mai[0m is a keyword. The result is [47m(mv erp rest alist)[0m, where [47merp[0m is non-[47mnil[0m if and only if the keyword section of [47mx[0m (that is, starting with [47m:key1[0m) is ill-formed, that is: some [47m:keyi[0m is not a keyword, [47m:keyi[0m and [47m:keyj[0m are the same for some distinct i and j, or some [47m:keyi[0m is not a member of [47mkeys[0m. When [47merp[0m is [47mnil[0m, then [47mrest[0m is [47m(a1 ... an)[0m and alist is equivalent (as a mapping) to [47m((:key1 . v1) ... (:keyk . vk))[0m. * [47m(plist-worldp alist)[0m: Recognizer for when [47malist[0m is syntactically well-formed as an ACL2 logical [world], sometimes suitable for use in [guard]s. Note: for a somewhat deeper check, see community book [47mbooks/system/pseudo-good-worldp.lisp[0m. * [47m(prettyify-clause cl let*-abstractionp wrld)[0m: Returns an untranslated (user-level) term that is equivalent to the [clause], [47mcl[0m. * [47m(programp fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return [47mt[0m when the [47msymbol-class[0m of [47mfn[0m in [47mw[0m is [47m:program[0m, else [47mnil[0m. (See [47msymbol-class[0m, below.) * [47m(quotep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return true iff [47mx[0m is a quoted constant. * [47m(recursivep fn flg w)[0m: [47mFn[0m should be a [47m:[0m[47m[logic][0m-mode function symbol [47mfn[0m of the [world], [47mw[0m. The result is the list of mutually recursive functions of which [47mfn[0m is a member. The list is empty iff [47mfn[0m is not recursive. The list contains just [47mfn[0m iff [47mfn[0m is singly recursive. NOTE: [47mflg[0m should be [47mt[0m or [47mnil[0m. If [47mflg[0m is [47mnil[0m, the result is based solely on the [47m[defun][0m form that introduced [47mfn[0m and is equal to [47m(getpropc fn 'recursivep nil w)[0m. If [47mflg[0m is [47mt[0m, then the most recent [definition] rule for [47mfn[0m with a non-[47mnil[0m value of [47m:install-body[0m --- which could be the original definition --- will cause [47mrecursivep[0m to return the [47m:clique[0m specified by that rule; see [rule-classes]. * [47m(stobjp x known-stobjs w)[0m: Returns a non-[47mnil[0m value when [47mx[0m is to be treated as a [stobj] name, else [47mnil[0m. Argument [47mknown-stobjs[0m is a list of all such names, or else [47mt[0m, standing for all stobj names in the [world], [47mw[0m. If you want to know whether [47mx[0m has been defined as a stobj in [47mw[0m, use [47mknown-stobjs[0m = [47mt[0m. Technicality: if [47mknown-stobjs[0m is a list then it is allowed to contain any number of [47mnil[0m elements (as may be the case for the [47mstobjs-in[0m or [47mstobjs-out[0m of a symbol), which are ignored. * [47m(stobjs-in fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return the stobjs-in of [47mfn[0m, which is the result of modifying the list of formal parameters of [47mfn[0m by replacing with [47mnil[0m or [47m:df[0m each symbol that is not a [stobj] input --- generally [47mnil[0m, but [47m:df[0m if the formal parameter is declared to be a df (see [df]). Note that [47mfn[0m must be a symbol, not a [lambda] expression. * [47m(stobjs-out fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return the stobjs-out of [47mfn[0m, which is the list described below whose length [47mL[0m is the number of return values of [47mfn[0m --- that is, [47mL[0m is 1 unless [47mfn[0m returns multiple values. First suppose that [47mL[0m is 1; say the stobjs-out list is [47m(s)[0m. If [47mfn[0m returns a stobj then [47ms[0m is that stobj; if [47mfn[0m returns a [df] then [47ms[0m is [47m:df[0m; and otherwise [47ms[0m is [47mnil[0m. Otherwise, [47mL[0m is greater than 1. Then for each [47mi[0m less than [47mL[0m, if the [47mi[0mth return value is a stobj, then that is the [47mi[0mth element of the stobjs-out; otherwise the [47mi[0mth element of the stobjs-out is [47m:df[0m if calls of [47mfn[0m are df{i} expressions (see [df], else [47mnil[0m. Note that [47mfn[0m must be a symbol, not a [lambda] expression. Moreover [47mfn[0m must not be a member of the list value of the constant [47m*stobjs-out-invalid*[0m, i.e., the list [47m(if return-last do$ read-user-stobj-alist)[0m, since for these functions arbitrary multiple values may be returned. * [47m(subcor-var vars terms form)[0m: For a list [47mvars[0m of symbols, a list [47mterms[0m of [47m[pseudo-termp][0ms, and a [47m[pseudo-termp][0m [47mform[0m, substitute, in [47mform[0m, the [3mi[0m-th variable from [47mvars[0m with the [3mi[0m-th term from [47mterms[0m. Note that [47mvars[0m and [47mterms[0m should have the same length. ("[47msubcor[0m" stands for "substitute corresponding elements".) Some simplification may be done; to avoid that, use [47mfsubcor-var[0m (``fast substitute corresponding elements''), described above. * [47m(sublis-fn-simple alist term)[0m, [47m(sublis-fn alist term bound-vars)[0m: Both of these apply the functional substitution, [47malist[0m, to the given term. Thus in both cases, all keys of [47malist[0m are function symbols. In the case of [47msublis-fn-simple[0m, each key of [47malist[0m is mapped to a function symbol; but for [47msublis-fn[0m, a key may instead be mapped to a legal [lambda] expression. The other difference between the two functions is that for [47msublis-fn[0m, the formal [47mbound-vars[0m is a list of variables, generally [47mnil[0m at the top level. For details see the Lisp comments in the ACL2 sources for function [47msublis-fn-rec[0m (which is more general than either [47msublis-fn-simple[0m and [47msublis-fn[0m, and is called by both of them to do the real work). * [47m(sublis-fn-lst-simple alist termlist)[0m: Apply the given functional substitution, [47malist[0m, to each term in [47mtermlist[0m, essentially by applying [47msublis-fn-simple[0m to alist and each such term. See the description of [47msublis-fn-simple[0m, above. * [47m(sublis-var alist form)[0m: Substitute [47malist[0m into the [term], [47mform[0m. [47mAlist[0m should be an alist that associates symbols with [47m[pseudo-termp][0ms, and [47mterm[0m should also satisfy [47mpseudo-termp[0m. Note that the substitution process evaluates calls of primitives on quoted constants, essentially using [47m[cons-term][0m. * [47m(subsequencep lst1 lst2)[0m: Determine whether the list lst1 is a subsequence of the list lst2, although not necessarily a proper subsequence. * [47m(subst-expr new old term)[0m: Substitute [47mnew[0m for [47mold[0m in [47mterm[0m; all are assumed to be [term]s. This function provides a slightly optimized version of equivalent function [47m(subst-expr1 new old term)[0m. Also, the former causes an explicit error if [47mold[0m is a quoted constant, and neither will search strictly inside a quoted subterm of [47mold[0m. A more complex function (perhaps a bit less likely to stay forever unchanged), [47msubst-equiv-expr[0m, may be found in the source code; it can substitute one expression for another when the two are equivalent, but not necessarily equal. * [47m(subst-var new old term)[0m: Substitute [47mnew[0m for [47mold[0m in [47mterm[0m; all are assumed to be [term]s, but moreover, [47mold[0m is assumed to be a variable. * [47m(symbol-class name w)[0m: For a function symbol, [47mname[0m, of the ACL2 [world] [47mw[0m, return [47m:program[0m if [47mname[0m is in [47m:[0m[47m[program][0m mode, [47m:common-lisp-compliant[0m if [47mname[0m is [guard]-verified, and otherwise, [47m:ideal[0m. If [47mname[0m is the name of a theorem (more specifically, has a [47m'theorem[0m property; see [getprop]), return [47m:ideal[0m unless the theorem is guard-verified, in which case return [47m:common-lisp-compliant[0m. Otherwise return [47m:program[0m. * [47m(symbol-doublet-listp lst)[0m: Returns [47mt[0m if [47mlst[0m is a list of two-element lists [47m(x1 x2)[0m where [47mx1[0m is a symbol, else [47mnil[0m. * [47m(termp x w)[0m: Is [47mx[0m a [term] in logical [world] [47mw[0m? * [47m(trans-eval form ctx state aok)[0m: Translate and then evaluate [47mform[0m. See [trans-eval] for discussion and related utilities. * [47mtranslate[0m, [47mtranslate1[0m, [47mtranslate11[0m, [47mtranslate-cmp[0m, [47mtranslate1-cmp[0m, and [47mtranslate1-cmp+[0m: Functions that translate user-level input to translated [term]s, as recognized by [47mtermp[0m. Note that these functions perform macroexpansion, which checks [guard]s on [primitive]s; see [safe-mode]. * [47m(translate-hints name-tree lst ctx wrld state)[0m: Translate a given list of user-level hints, [47mlst[0m, to internal form. NOTE: this function returns an [error-triple], and it checks the syntax of [47mlst[0m. Its documentation essentially resides in a comment in source function [47mtranslate-hints1[0m. * [47m(untranslate term iff-flg w)[0m: see [untranslate]. * [47m(value x)[0m: This macro call expands to [47m(mv nil x state)[0m. For related discussion, see [error-triple]. * [47m(variablep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return true iff [47mx[0m is a variable, i.e., a symbol. Subtopics [Constraint-info] Obtaining the [constraint] on a function symbol [Get-event-data] Obtain data stored after at the conclusion of an event [Saving-event-data] Save data stored for subsidiary [events] [Trans-eval] Evaluate a form [Untranslate] Show a user-level representation of a term") (table (events) "User-managed tables Examples: (table tests 1 '(...)) ; set contents of tests[1] to '(...) (table tests 25) ; get contents of tests[25] (table tests) ; return table tests as an alist (table tests nil nil :clear) ; clear table tests (table tests nil '((foo . 7)) :clear) ; set table tests to ((foo . 7)) (table tests nil nil :guard) ; fetch the table guard (table tests nil nil :guard term) ; set the table guard General Form: (table table-name key-term value-term op term) where [47mtable-name[0m is a symbol that is the name of a (possibly new) table; [47mkey-term[0m and [47mvalue-term[0m, if present, are arbitrary terms involving (at most) the variables [47mWORLD[0m and [47mENS[0m with exceptions noted below; [47mop[0m, if present, is one of the table operations below; and [47mterm[0m, if present, is a term. [47mTable[0m returns an ACL2 [error-triple]. The effect of [47mtable[0m on [47m[state][0m depends on [47mop[0m and how many arguments are presented. Some invocations actually have no effect on the ACL2 [world] and hence an invocation of [47mtable[0m is not always an ``event''. We explain below, after giving some background information. [31;1mImportant Note:[0m The [47mtable[0m forms above are calls of a macro that expands to involve the special variable [47m[state][0m. This will prevent you from accessing a table from within a hint or theory where you do not have the [47m[state][0m variable. However, the form (table-alist 'tests world) returns the alist representation of the table named [47mtests[0m in the given [47m[world][0m. Often you can provide a suitable expression for [47mworld[0m, for example, [47m(w state)[0m. The ACL2 system provides ``tables'' by which the user can associate one object with another. Tables are in essence just conventional association lists --- lists of pairs --- but the ACL2 environment provides a means of storing these lists in the ``ACL2 world'' of the current [47m[state][0m. The ACL2 user could accomplish the same ends by using ACL2 ``global variables''; however, limitations on global variable names are imposed to ensure ACL2's soundness. Some features of the system use tables, and the user is invited to make free use of tables. By convention, no user-defined table is important to ACL2's soundness. Because tables are stored in the ACL2 [world] they are restored by [47m[include-book][0m and undone by [47m:[0m[47m[ubt][0m. Many users of Nqthm requested a facility by which user data could be saved in Nqthm ``lib files'' and tables are ACL2's answer to that request. Abstractly, each table is an association list mapping ``keys'' to ``values.'' In addition, each table has a ``[47m:guard[0m,'' which is a term that must be true of any key and value used. By setting the [47m:guard[0m on a table you may enforce an invariant on the objects in the table, e.g., that all keys are positive integers and all values are symbols. Note that attachments are allowed when evaluating a table guard (see [defattach]). Each table has a ``name,'' which must be a symbol. Given a table name, the following operations can be performed on the table. [47m:put[0m --- associate a value with a key (possibly changing the value currently associated with that key). [47m:get[0m --- retrieve the value associated with a key (or nil if no value has been associated with that key). [47m:alist[0m --- return an alist showing all keys and non-nil values in the table. [47m:clear[0m --- clear the table (so that every value is nil), or if val is supplied then set table to that value (which must be an alist). [47m:guard[0m --- fetch or set the [47m:guard[0m of the table. See [set-table-guard] for a convenient way to set a table's [47m:guard[0m to produce user-friendly error messages. When the operations above suggest that the table or its [47m:guard[0m are modified, what is actually meant is that the current [state] is redefined so that in it, the affected table name has the appropriate properties. In such cases, the [47mtable[0m form is an event (see [events]). In the [47m:put[0m case, if the key is already in the table and associated with the proposed value, then the [47mtable[0m event is redundant (see [redundant-events]). [47mTable[0m forms are commonly typed by the user while interacting with the system. [47m:Put[0m and [47m:get[0m forms are especially common. Therefore, we have adopted a positional syntax that is intended to be convenient for most applications. Essentially, some operations admit a ``short form'' of invocation. (table name key-term value-term :put) ; long form (table name key-term value-term) ; short form evaluates the key- and value-terms, obtaining two objects that we call [47mkey[0m and [47mvalue[0m, checks that the [47mkey[0m and [47mvalue[0m satisfy the [47m:guard[0m on the named table and then ``modifies'' the named table so that the value associated with [47mkey[0m is [47mvalue[0m. When used like this, [47mtable[0m is actually an event in the sense that it changes the ACL2 [world]. In general, the forms that are evaluated to obtain the [47mkey[0m and [47mvalue[0m may involve two variables: [47mWORLD[0m, which is bound to the then-current [world]; and [47mENS[0m, which is bound to the enabled structure representing the current theory. (The enabled structure is passed as a formal parameter to many built-in functions; for example, see [system-utilities] for a description of built-in utilities [47menabled-numep[0m and [47menabled-runep[0m.) However, in the following two special cases, the [47mkey[0m and [47mvalue[0m terms may not contain any variables: when the table is named [47m[ACL2-defaults-table][0m; or when the table's [47m:guard[0m is a call of the unary function [47mstrict-table-guard[0m, which returns its argument unchanged but indicates this restriction on variables for specifying keys and values. Essentially, the keys and values used in [events] setting such tables must be explicitly given constants. See [ACL2-defaults-table]. (table name key-term nil :get) ; long form (table name key-term) ; short form evaluates the key-term (see note below), obtaining an object, [47mkey[0m, and returns the value associated with [47mkey[0m in the named table (or, [47mnil[0m if there is no value associated with [47mkey[0m). When used like this, [47mtable[0m is not an event; the value is simply returned. (table name nil nil :alist) ; long form (table name) ; short form returns an alist representing the named table; for every key in the table with a non-[47mnil[0m associated value, the alist pairs the key and its value. The order in which the keys are presented is unspecified. When used like this, [47mtable[0m is not an event; the alist is simply returned. (table name nil val :clear) sets the named table to the alist [47mval[0m, making the checks that [47m:put[0m makes for each key and value of [47mval[0m. When used like this, [47mtable[0m is an event because it changes the ACL2 [world]. (table name nil nil :guard) returns the translated form of the guard of the named table. (table name nil nil :guard term) This event sets the [47m:guard[0m of the named table to [47mterm[0m, provided the following requirements are met. The named table must be empty and it must not have been assigned a [47m:guard[0m yet. [47mTerm[0m (which is not evaluated) should be a term that mentions at most the variables [47mKEY[0m, [47mVAL[0m, [47mWORLD[0m, [47mENS[0m, and [47mSTATE[0m. In the common case [47mterm[0m will evaluate to a single value, but it can return two values as discussed later below; either way, it must not return [47mSTATE[0m. Whenever a subsequent [47m:put[0m occurs, [47mterm[0m will be evaluated with [47mKEY[0m bound to the key argument of the [47m:put[0m, [47mVAL[0m bound to the [47mval[0m argument of the [47m:put[0m, [47mWORLD[0m bound to the then current [world], [47mENS[0m bound to the enabled structure representing the current theory, and [47mSTATE[0m bound to the ACL2 [state]. The term is evaluated. An error will be caused by the [47m:put[0m if the result of the evaluation is [47mnil[0m when a single value is returned; what if two values are returned? If the term returns multiple values [47m(mv okp msg)[0m, then an error will be caused if [47mokp[0m is [47mnil[0m. In that case, if [47mmsg[0m is also [47mnil[0m then a generic error message is printed about the illegal key/value pair, just as in the single-value return case. Otherwise [47mmsg[0m should be a [47m[msgp][0m --- a string or a cons suitable for printing with the [47m[fmt][0m directive, [47m~@[0m. In that case, [47mmsg[0m is printed (using [47m[fmt][0m [47m~@[0m) instead of the generic error message. Here is a simple example adapted from former code in the ACL2 sources. (defun my-table-guard (fn val wrld) (let ((msg0 ; nil if fn/val is OK as a key/value pair, else a msg (my-table-guard-msg fn val wrld))) (cond (msg0 (mv nil (msg "Illegal my-table key and value (see :DOC ~ memoize-partial):~|key = ~y0value = ~y1Reason:~%~@2~|~%" fn val msg0))) (t (mv t nil))))) (table my-table nil nil :guard (my-table-guard key val world)) Note that it is not allowed to change the [47m:guard[0m on a table once it has been explicitly set. Before the [47m:guard[0m is explicitly set, it is effectively just [47mt[0m. After it is set it can be changed only by undoing the event that set it. The purpose of this restriction is to prevent the user from changing the [47m:guards[0m on tables provided by other people or the system. The intuition behind the [47m:guard[0m mechanism on tables is to enforce invariants on the keys and values in a table, so that the values, say, can be used without run-time checking. But if the [47m:guard[0m of a table is sensitive to the ACL2 [world], it may be possible to cause some value in the table to cease satisfying the [47m:guard[0m without doing any operations on the table. Consider for example the [47m:guard[0m ``no value in this table is the name of an event.'' As described, that is enforced each time a value is stored. Thus, [47m'bang[0m can be [47m:put[0m in the table provided there is no event named [47mbang[0m. But once it is in the table, there is nothing to prevent the user from defining [47mbang[0m as a function, causing the table to contain a value that could not be [47m:put[0m there anymore. Observe that not all state-sensitive [47m:guard[0ms suffer this problem. The [47m:guard[0m ``every value is an event name'' remains invariant, courtesy of the fact that undoing back through an event name in the table would necessarily undo the [47m:put[0m of the name into the table. [47mTable[0m was designed primarily for convenient top-level use. Tables are not especially efficient. Each table is represented by an alist stored on the property list of the table name. [47m:Get[0m is just a [47mgetprop[0m and [47m[assoc-equal][0m. [47m:Put[0m does a [47mgetprop[0m to the get the table alist, a [47mput-assoc-equal[0m to record the new association, and a [47mputprop[0m to store the new table alist --- plus the overhead associated with [47m:guard[0ms and undoable [events], and checking (for redundancy) if the key is already bound to its proposed value. Note that there are never duplicate keys in the resulting [47malist[0m; in particular, when the operation [47m:clear[0m is used to install new [47malist[0m, duplicate keys are removed from that alist. A table name may be any symbol whatsoever. Symbols already in use as function or theorem names, for example, may be used as table names. Symbols in use only as table names may be defined with [47m[defun][0m, etc. Because there are no restrictions on the user's choice of table names, table names are not included among the logical names. Thus, [47m:pe name[0m will never display a table event (for a logical name other than [47m:here[0m). Either [47m:pe name[0m will display a ``normal'' event such as [47m(defun name ...)[0m or [47m(defthm name ...)[0m or else [47m:pe name[0m will cause an error indicating that [47mname[0m is not a logical name. This happens even if [47mname[0m is in use as a table name. Subtopics [ACL2-defaults-table] A [table] specifying certain defaults, e.g., the default [defun-mode] [Set-table-guard] Set the [47m:guard[0m for a [table] [Using-tables-efficiently] Notes on how to use tables efficiently") (table-alist (pointers) "See [table].") (tag-tree (pointers) "See [ttree].") (tail-biting (debugging) "Rewriting a true term to [47mNIL[0m On rare occasions, a true term can [rewrite] to [47mNIL[0m. Such ``tail-biting'' behavior can make the prover fail to prove a theorem but will not make it ``prove'' a non-theorem. This topic explains this behavior, first with one paragraph explaining it in high-level terms and then, for those interested in details, with a specific example. That example includes discussion that exposes more of the ACL2 implementation than is usually exposed in documentation topics, so we expect that most readers will skip it. When backchaining to rewrite a hypothesis [47mH[0m of a [rewrite] or [linear] rule, ACL2 uses the following heuristic: assume that [47mH[0m is false when trying to prove it. That is sound: proposition [47mP[0m is equivalent to proposition [47m(implies (not P) P)[0m. We do not discuss why ACL2 does this or why it rarely results in so-called ``tail-biting'': rewriting the hypothesis to [47mNIL[0m by using the fact that it has been assumed false. But that can happen on rare occasions. So if you see a term rewrite to [47mNIL[0m when you know it to be true, consider whether this is because it was encountered earlier during the backchaining process, when it was assumed false. ===== Maybe stop here (lower-level explanation follows)! ===== The example below shows how tail-biting can happen. As noted above, beware: this explanation is closer to the implementation than is found in most of the ACL2 documentation. We give the example in full first, and then we conclude with a more concise summary. Key to this explanation is the notion of the [3mancestors-stack[0m, which is a data structure kept by the rewriter as it backchains through hypotheses, to record the negation of each hypothesis encountered during backchaining. We begin with a very simple definition and theorem. Note that we treat [47m[member][0m below as [47m[member-equal][0m, to simplify the exposition. (defun copylist (x) (if (endp x) nil (cons (car x) (copylist (cdr x))))) (defthm key-rule (implies (not (member a lst)) ; hypothesis later denoted as ``H'' (not (member a (copylist lst))))) The following ``weird'' rule backchains from [47m(member a (cdr lst))[0m to [47m(member a lst)[0m, sort of un-opening [47mmember[0m. (defthm weird (implies (and (consp lst) (member a lst) (not (equal a (car lst)))) (member a (cdr lst)))) Now here is our main theorem. It ought to follow by simplification from [47mkey-rule[0m above, if we can just establish the hypothesis [47mH[0m of [47mkey-rule[0m from the hypotheses of [47mmain[0m. The instance of [47mH[0m is [47m(not (member aaa (cdr xxx)))[0m. The rewriter cannot establish this because it requires a proof by induction. So the proof is bound to fail here. (defthm main (implies (and (consp (cdr xxx)) (nat-listp xxx) (symbolp aaa)) (not (member aaa (copylist (cdr xxx))))) :hints (("Goal" :do-not-induct t :do-not '(eliminate-destructors)))) So we decide to monitor key-rule and see why it failed: (monitor! '(:rewrite key-rule) t) (defthm main ...) ; exactly as above :eval :a! And we see that [47m[brr][0m reports that ``[47m:HYP 1 rewrote to 'NIL[0m'', i.e., that the relevant instance of [47mH[0m, [47m(not (member aaa (cdr xxx)))[0m, rewrote to [47mNIL[0m. This seems to suggest [47maaa[0m is in [47m(cdr xxx)[0m. But we know it can't be! The hypotheses of main say [47maaa[0m is a symbol and [47mxxx[0m is a list of natural numbers. So [47maaa[0m can't be in [47m(cdr xxx)[0m. We can prove it: (defthm hyps-of-main-imply-hyp-1 (implies (and (consp (cdr xxx)) (nat-listp xxx) (symbolp aaa)) (not (member aaa (cdr xxx))))) And using that rule we can now prove [47mmain[0m: (defthm main (implies (and (consp (cdr xxx)) (nat-listp xxx) (symbolp aaa)) (not (member aaa (copylist (cdr xxx))))) :hints (("Goal" :do-not-induct t :do-not '(eliminate-destructors)))) So the question is: why did the hypothesis of [47mkey-rule[0m rewrite to [47mNIL[0m? Let's undo back through [47mhyps-of-main-imply-hyp-1[0m and monitor [47mkey-rule[0m, [47mweird[0m, and the definition of [47m[member-equal][0m, and also [trace] system function [47mancestors-check-builtin[0m, which queries the ancestor-stack, and then repeat the doomed proof attempt for [47mmain[0m. (ubt! 'hyps-of-main-imply-hyp-1) (monitor '(:rewrite key-rule) ''(:go)) (monitor '(:rewrite weird) ''(:go)) (monitor '(:definition member-equal) ''(:go)) (trace$ ancestors-check-builtin) (defthm main (implies (and (consp (cdr xxx)) (nat-listp xxx) (symbolp aaa)) (not (member aaa (copylist (cdr xxx))))) :hints (("Goal" :do-not-induct t :do-not '(eliminate-destructors)))) Here is the series of breaks on (:REWRITE WEIRD), except that the second break is elided because you will see at the subsequent ``2x (:REWRITE WEIRD) failed...'' that everything that goes on there is irrelevant. Also deleted are some irrelevant calls of [47mancestors-check-builtin[0m, but the important one remains. (1 Breaking (:REWRITE KEY-RULE) on (MEMBER-EQUAL AAA (COPYLIST (CDR XXX))): 1 ACL2 >:GO (2 Breaking (:REWRITE WEIRD) on (MEMBER-EQUAL AAA (CDR XXX)): ... 2x (:REWRITE WEIRD) failed because :HYP 2 rewrote to (MEMBER-EQUAL AAA (CDR XXX)). 2) (2 Breaking (:DEFINITION MEMBER-EQUAL) on (MEMBER-EQUAL AAA (CDR XXX)): 2 ACL2 >:GO (3 Breaking (:REWRITE WEIRD) on (MEMBER-EQUAL AAA (CDR (CDR XXX))): 3 ACL2 >:GO 1> (ANCESTORS-CHECK-BUILTIN (MEMBER-EQUAL AAA (CDR XXX)) (((MEMBER-EQUAL AAA (CDR XXX)) (MEMBER-EQUAL AAA (CDR XXX)) 2 2 0 ((:REWRITE KEY-RULE)) . 1)) ((:REWRITE WEIRD))) <1 (ANCESTORS-CHECK-BUILTIN T T) 3 (:REWRITE WEIRD) produced 'T. 3) 2 (:DEFINITION MEMBER-EQUAL) produced 'T. 2) 1x (:REWRITE KEY-RULE) failed because :HYP 1 rewrote to 'NIL. (See :DOC tail-biting if this surprises you.) 1) So we've entered the break on [47mkey-rule[0m and backchained to prove its hypothesis, [47m(not (member aaa (cdr xxx)))[0m. We thus assume the negation, [47m(member aaa (cdr xxx))[0m, on the ancestors stack and then open [47m(member aaa (cdr xxx))[0m with the definition. That results in a call of [47m(member aaa (cdr (cdr xxx)))[0m and we backchain through [47mweird[0m to [47m(member aaa (cdr xxx))[0m and find it assumed true (on the ancestors-stack). So [47mweird[0m rewrites [47m(member-aaa (cdr (cdr xxx)))[0m to [47mT[0m (propositionally) and so [47mmember-equal[0m returns [47mT[0m, so [47mH[0m rewrites to [47mNIL[0m. This is not unsound; it is just tail biting. Here is a summary of what has happened. 1. Attempt to rewrite [47m(not (member aaa (copylist (cdr xxx))))[0m to [47mT[0m. 2. Attempt to rewrite [47m(member aaa (copylist (cdr xxx)))[0m to [47mNIL[0m. 3. Backchain with [47mkey-rule[0m to [47m(not (member aaa (cdr xxx)))[0m. 4. Assume [47m(member aaa (cdr xxx))[0m by putting it on the ancestors-stack. This is sound because we are trying to prove [47m(not (member aaa (cdr xxx)))[0m, and it is sound to assume [47m(not P)[0m when proving [47mP[0m. 5. Expand [47m(member aaa (cdr xxx))[0m, given [47m(consp (cdr xxx))[0m, to [47m(or (equal aaa (cadr xxx)) (member aaa (cddr xxx)))[0m 6. Rewrite [47m(member aaa (cddr xxx))[0m) using [47mweird[0m. 7. Backchain with weird on (member aaa (cddr xxx)) and relieve its hypotheses under the substitution [47ma := aaa[0m, [47mlst := (cdr xxx)[0m. * a. [47m(consp (cdr xxx))[0m is true (hypothesis of [47mmain[0m). * b. [47m(member aaa (cdr xxx))[0m is true (TAIL BITING!). * c. [47m(not (equal aaa (car (cdr xxx))))[0m is true, presumably from expansion of hypotheses of [47mmain[0m. 8. So [47mweird[0m applies, hence the following are true: * From 6. [47m(member aaa (cddr xxx))[0m * From 5. [47m(member aaa (cdr xxx))[0m So 3 fails because [47m(not (member aaa (cdr xxx)))[0m rewrites to [47mNIL[0m.") (take (lists acl2-built-ins) "Initial segment (first n elements) of a list For any natural number [47mn[0m not exceeding the length of [47ml[0m, [47m(take n l)[0m collects the first [47mn[0m elements of the list [47ml[0m. The following is a theorem: (equal (length (take n l)) (nfix n)) If [47mn[0m is an integer greater than the length of [47ml[0m, then [47mtake[0m pads the list with the appropriate number of [47mnil[0m elements. Thus, the following is also a theorem (though it takes some effort, including lemmas, to get ACL2 to prove it). (implies (and (integerp n) (true-listp l) (<= (length l) n)) (equal (take n l) (append l (make-list (- n (length l)))))) For related functions, see [nthcdr] and see [butlast]. The [guard] for [47m(take n l)[0m is that [47mn[0m is a nonnegative integer and [47ml[0m is a true list. [31;1mFunction: [0m<first-n-ac> (defun first-n-ac (i l ac) (declare (type (integer 0 *) i) (xargs :guard (and (true-listp l) (true-listp ac)))) (cond ((zp i) (revappend ac nil)) (t (first-n-ac (1- i) (cdr l) (cons (car l) ac))))) [31;1mFunction: [0m<take> (defun take (n l) (declare (xargs :guard (and (integerp n) (not (< n 0)) (true-listp l)))) (mbe :logic (if (zp n) nil (cons (car l) (take (1- n) (cdr l)))) :exec (first-n-ac n l nil)))") (talks (acl2-tutorial) "Some talks about ACL2 The list below contains links to talks about ACL2. This list may grow over time. Please email the [ACL2-help] mailing list if you find a broken link or if you care to contribute another link to a talk (or simply make the changes yourself if you have permission to do so on GitHub). * Links to several introductory/overview talks on ACL2 may be found on the {page of talks by Matt Kaufmann | http://www.cs.utexas.edu/users/kaufmann/selected-presentations.html}, including {a general introductory talk on ACL2 by Matt Kaufmann and J Moore | http://www.cs.utexas.edu/users/kaufmann/visions-moore-kaufmann.pdf} from 2006. * Several introductory/overview talks on ACL2 by J Moore: * {Two talks given July 6 and 7, 2017 | http://www.cs.utexas.edu/users/moore/acl2/talks/big-proof-talks/}, at the {Big Proof workshop | https://www.newton.ac.uk/event/bpr} at the Isaac Newton Institute for Mathematical Sciences in Cambridge, England. The first talk focuses on the role of mechanized proof,specifically ACL2, to verify hardware and software of interest to industry. The second talk touches upon how the ACL2 prover works, how the user directs it, and some of the features of particular importance to its industrial applications. * {Industrial Hardware and Software Verification with ACL2 | http://www.cs.utexas.edu/users/moore/acl2/talks/royal-society/talk.pdf}, presented at the Royal Society, London, in April, 2016 (co-authored with Warren A. Hunt, Jr., Matt Kaufmann, and Anna Slobodova). * This page for {Mechanized Operational Semantics | http://www.cs.utexas.edu/users/moore/publications/talks/marktoberdorf-08/index.html} contains links not only to talks given at the Marktoberdorf Summer School (Germany, August, 2008) but also to supplemental materials. * The ``Talks'' section of {Warren Hunt's home page | http://www.cs.utexas.edu/users/hunt/index.html} has an annotated list of links to several talks about the use of ACL2 for hardware specification and verification. Note that many talks are also available from the ACL2 Workshops pages and on the {University of Texas ACL2 Seminar page | http://www.cs.utexas.edu/users/moore/acl2/seminar/}.") (tame (apply$) "Definitions of the various notions of tameness The adjective ``tame'' can be applied to four different kinds of objects, [47mLAMBDA[0m objects, function symbols, expressions, and lists of expressions. Formally, these notions are defined mutually recursively as the macro [47mtamep-lambdap[0m and the [47m:logic[0m mode functions named [47mtamep-functionp[0m, [47mtamep[0m, and [47msuitably-tamep-listp[0m, respectively. We exhibit the formal definitions at the end of this documentation. Definitions * [31;1mtame [47mLAMBDA[0m[31;1m object[0m aka [47mtamep-lambdap[0m: An object is a tame [47mLAMBDA[0m object if is of the form [47m(LAMBDA vars body)[0m or [47m(LAMBDA vars dcl body)[0m where [47mvars[0m is a list of symbols and [47mbody[0m is a tame expression. Formally, an object [47mx[0m is a tame [47mLAMBDA[0m object iff [47m(tamep-lambdap x)[0m. [47mTamep-lambdap[0m is actually a macro. * [31;1mtame function[0m aka [47mtamep-functionp[0m: An object is a [3mtame function[0m iff it is either (a) a badged symbol and ilks is [47mT[0m, or (b) a tame [47mLAMBDA[0m object (see above). Formally, an object [47mx[0m is a tame function iff [47m(tamep-functionp x)[0m. * [31;1mtame expression[0m aka [47mtamep[0m: An object is a [3mtame expression[0m iff it is a symbol, a quoted constant, the call of an badged function symbol on the correct number of suitably tame expressions with respect to the ilks of the function symbol, or the call of a tame [47mLAMBDA[0m expression on the correct number of tame expressions. Formally, an object [47mx[0m is a tame expression iff [47m(tamep x)[0m. Note that tameness implies every function symbol in the expression is badged but [3mnot necessarily warranted[0m. * [31;1msuitably tame with (respect to arity and ilks)[0m aka [47msuitably-tamep-listp[0m: A list of objects [47mx[0m is [3msuitably tame[0m with respect to an arity [47mn[0m and a list of [47milks[0m iff [47mx[0m is a true list of length [47mn[0m, and when an ilk is [47m:FN[0m the corresponding object is a [3mquoted[0m tame function, when an ilk is [47m:EXPR[0m the object is a [3mquoted[0m tame expression, and when an ilk is [47mNIL[0m the object is a tame expression. Formally, an object [47mx[0m is suitably tame with respect to [47mn[0m and [47milks[0m iff [47m(suitably-tamep-listp n ilks x)[0m. Note in particular our use of the word ``quoted'' above. We illustrate this in the example below. Note that the various notions of tameness make no mention of whether the function symbols involved are in [47m:program[0m or [47m:logic[0m mode. The function symbols must have badges but need not have warrants. Intuitively, a tame expression can be built out of functions that are not themselves tame, e.g., scions, by making sure that every [47m:FN[0m slot is occupied by a quoted tame function. Put another way, if we were to trace the calls of [47mapply$[0m while evaluating a tame expression every branch eventually bottoms out on a call of a primitive. This is illustrated below. Examples We assume the following events have been processed. (include-book "projects/apply/top" :dir :system) (defun$ sq (x) (* x x)) (defun$ foldr (lst fn init) (if (endp lst) init (apply$ fn (list (car lst) (foldr (cdr lst) fn init))))) [47mSq[0m and [47mfoldr[0m above are defined as [47m:logic[0m mode functions and are badged and warranted (note the use of [47mdefun$[0m). But for our purposes they could have been introduced by [47mdefun[0m in [47m:program[0m mode and then badged with two calls of [47mdefbadge[0m. As a result, we see the following badges: symbol badge CONS (APPLY$-BADGE 2 1 . T) ; . T means all args ordinary SQ (APPLY$-BADGE 1 1 . T) ; . T means all args ordinary FOLDR (APPLY$-BADGE 1 1 NIL :FN NIL) Consider the following expression. (foldr lst (lambda$ (x y) (foldr y 'cons (list (sq x)))) nil) Forgetting about tameness for a moment, what does this term compute? Study the definition of [47mfoldr[0m if you're not familiar with it and work it out! Answer: It collects, in reverse order, the squares of the elements of [47mlst[0m. E.g., if [47mlst[0m is [47m(1 2 3 4)[0m the value of the [47mfoldr[0m expression above is [47m(16 9 4 1)[0m. But we are interested in whether it is tame. Tameness is a concept applied to objects representing formal (fully translated) terms (or components of terms in the case of ``tame functions,'' ``tame lambdas,'' etc.). Saying ``[3mx[0m is a tame expression'' is just a colloquial way of saying ``[47m(tamep [0m[3mx[0m[47m)[0m = [47mt[0m. So we can evaluate this term in the top-level ACL2 loop, (tamep '(foldr lst (lambda$ (x y) (foldr y 'cons (list (sq x)))) nil)) and the result is [47mnil[0m because [47mlambda$[0m is not a ``badged function symbol.'' In fact, [47mlambda$[0m is not a function symbol. It is a macro. We're really interested in the formal translation of the [47mfoldr[0m expression. One way to understand the situation is that [47mtamep[0m does not expand macros. The translation of the above term is (FOLDR LST '(LAMBDA (X Y) (DECLARE (IGNORABLE X Y)) (RETURN-LAST 'PROGN '(LAMBDA$ (X Y) (FOLDR Y 'CONS (LIST (SQ X)))) (FOLDR Y 'CONS (CONS (SQ X) 'NIL)))) 'NIL) The [47mRETURN-LAST[0m subterm is a marker that records the original user-supplied [47mlambda$[0m expression, which is needed during compilation and execution in raw Lisp. But the value of that [47mRETURN-LAST[0m is the expected [47mFOLDR[0m expression in its last argument. To simplify our discussion of tameness let's determine whether the following equivalent term is tame. (FOLDR LST '(LAMBDA (X Y) (FOLDR Y 'CONS (CONS (SQ X) 'NIL))) 'NIL) The answer is yes, it is a tame expression. In particular (tamep '(FOLDR LST '(LAMBDA (X Y) (FOLDR Y 'CONS (CONS (SQ X) 'NIL))) 'NIL)) = T By the way, [47mtamep[0m answers the same way on the quotation of the actual translation of the [47mfoldr[0m term. We explain below how [47mtamep[0m computes this result. But before we dive into details consider what this example illustrates. [47mFOLDR[0m is [3mnot a tame function[0m according to the definitions above. But it can be used in the construction of tame expressions provided, mainly, that its second argument is a quoted tame function. Indeed, the example illustrates that we can even call [47mFOLDR[0m within the [47mLAMBDA[0m expression passed to another [47mFOLDR[0m and still have a tame expression. If we were to [47m[trace$][0m the functions [47mtamep[0m, [47mtamep-functionp[0m, and [47msuitably-tamep-listp[0m, and then call [47mtamep[0m on the [47mFOLDR[0m term above we would see a tree of calls of the various tameness notions. Here are selected calls from that tree. All of the calls return [47mT[0m. We discuss each of these calls below. (tamep '(CONS (SQ X) 'NIL)) ; [1] (suitably-tamep-listp 3 ; [2] '(NIL :FN NIL) '(Y 'CONS (CONS (SQ X) 'NIL))) (tamep '(FOLDR Y 'CONS (CONS (SQ X) 'NIL))) ; [3] (tamep-functionp '(LAMBDA (X Y) ; [4] (FOLDR Y 'CONS (CONS (SQ X) 'NIL)))) (tamep '(FOLDR LST ; [5] '(LAMBDA (X Y) (FOLDR Y 'CONS (CONS (SQ X) 'NIL))) 'NIL)) [47m[1][0m: The object here, [47m(CONS (SQ X) 'NIL)[0m, is tame because both [47mCONS[0m and [47mSQ[0m are tame functions and they are applied to the correct number of tame expressions. [47m[2][0m: The list of objects here, [47m(Y 'CONS (CONS (SQ X) 'NIL))[0m is a suitably tame list of length [47m3[0m with ilks [47mNIL[0m, [47m:FN[0m, and [47mNIL[0m because [47mY[0m and [47m'NIL[0m are both tame and [47m'CONS[0m is a [3mquoted[0m tame function, [47mCONS[0m. [47m[3][0m: The object here is tame because [47mFOLDR[0m is a badged function of arity 3 and its actuals are suitably tame with respect to its arity and ilks as shown by example [47m[2][0m. [47m[4][0m: The [47mLAMBDA[0m object here is a tame function because it is of the form [47m(LAMBDA vars body)[0m, where [47mvars[0m is the list of symbols [47m(X Y)[0m and body is the tame object shown in example [47m[4][0m. [47m[5][0m: The object here, a call of [47mFOLDR[0m, is tame because there are 3 actuals, the first and third are tame expressions and the second is a [3mquoted[0m tame function as shown in Example [47m[4][0m. Logical Definitions The various notions of tameness, [47mtamep-functionp[0m, [47mtamep[0m, and [47msuitably-tamep-listp[0m, are defined mutually recursively as [47m:logic[0m mode functions. The definition employs the macro [47mtamep-lambdap[0m, which is used by [47mtamep-functionp[0m to handle the [47mLAMBDA[0m case. [31;1mFunction: [0m<tamep-functionp> (defun tamep-functionp (fn) (declare (xargs :guard t)) (if (symbolp fn) (let ((bdg (badge fn))) (and bdg (eq (access apply$-badge bdg :ilks) t))) (and (consp fn) (tamep-lambdap fn)))) [31;1mFunction: [0m<tamep> (defun tamep (x) (declare (xargs :guard t)) (cond ((atom x) (symbolp x)) ((eq (car x) 'quote) (and (consp (cdr x)) (null (cddr x)))) ((symbolp (car x)) (let ((bdg (badge (car x)))) (cond ((null bdg) nil) ((eq (access apply$-badge bdg :ilks) t) (suitably-tamep-listp (access apply$-badge bdg :arity) nil (cdr x))) (t (suitably-tamep-listp (access apply$-badge bdg :arity) (access apply$-badge bdg :ilks) (cdr x)))))) ((consp (car x)) (let ((fn (car x))) (and (tamep-lambdap fn) (suitably-tamep-listp (length (cadr fn)) nil (cdr x))))) (t nil))) [31;1mFunction: [0m<suitably-tamep-listp> (defun suitably-tamep-listp (n flags args) (declare (xargs :guard (and (natp n) (true-listp flags)))) (cond ((zp n) (null args)) ((atom args) nil) (t (and (let ((arg (car args))) (case (car flags) (:fn (and (consp arg) (eq (car arg) 'quote) (consp (cdr arg)) (null (cddr arg)) (tamep-functionp (cadr arg)))) (:expr (and (consp arg) (eq (car arg) 'quote) (consp (cdr arg)) (null (cddr arg)) (tamep (cadr arg)))) (otherwise (tamep arg)))) (suitably-tamep-listp (- n 1) (cdr flags) (cdr args)))))) [31;1mMacro: [0m<tamep-lambdap> (defmacro tamep-lambdap (fn) (list 'let (list (list 'fn fn)) '(and (lambda-object-shapep fn) (symbol-listp (lambda-object-formals fn)) (tamep (lambda-object-body fn))))) At the top-level of the ACL2 loop you can determine whether an object satisfies one of these predicates by calling the appropriate formal notion on the object. But because these functions are defined in terms of [47m[badge][0m these notions of tameness are evaluable only in the evaluation theory (where [47m[warrant][0ms are implicitly assumed). If you want to prove that an object is tame, you may need warrant hypotheses. See [guarantees-of-the-top-level-loop].") (tamep (pointers) "See [tame].") (tamep-functionp (pointers) "See [tame].") (tamep-lambdap (pointers) "See [tame].") (tau-data (tau-system) "To see what tau knows about a function symbol Examples: (tau-data binary-+) General Form: (tau-data fn) This macro returns a list structure that indicates what facts about the symbol [47mfn[0m are known to the tau system. [47mFn[0m should either be a function symbol or else a macro associated with [47mfn[0m; see [macro-aliases-table]. See [introduction-to-the-tau-system] for background details. The list structure should be self-explanatory given the following brief comments. The ``index'' of a function, when non-[47mnil[0m, means the function is a monadic Boolean function treated by the tau system as a tau predicate. The ``positive'' and ``negative implicants'' are conjunctions that indicate the tau implied by the given one or its negation. The ``signatures'' entry is a formula indicating all the known signatures. If the signatures formula is [47mT[0m it means there are no known signatures. (Signatures is the conjunction of all signature rules and the empty conjunction is [47mT[0m.) If you wish to see a long list of all the runes from which some tau information has been gleaned, evaluate [47m(get-tau-runes (w state))[0m.") (tau-database (tau-system history) "To see the tau database as a (very large) object Example: (tau-database (w state)) This function returns a large list object that shows in a human-readable way what the tau system knows about every function symbol. It is supposed to be self-explanatory. See [introduction-to-the-tau-system] for background details. If the output is not self-explanatory, please contact the implementors and we will improve the output or the documentation.") (tau-interval-dom (tau-system) "Access the domain of a tau interval It is the case that (tau-interval-dom (make-tau-interval dom lo-rel lo hi-rel hi)) = dom For a well-formed interval, [47mdom[0m is one of the symbols [47mINTEGERP[0m, [47mRATIONALP[0m, [47mACL2-NUMBERP[0m, or [47mNIL[0m. When the domain is [47mNIL[0m there is no domain restriction. When the domain is [47mINTEGERP[0m, there are additional constraints on the other components. See [make-tau-interval].") (tau-interval-hi (tau-system) "Access the upper bound of a tau interval It is the case that (tau-interval-hi (make-tau-interval dom lo-rel lo hi-rel hi)) = hi For a well-formed interval, [47mhi[0m is either [47mnil[0m, denoting positive infinity, or a rational number giving the upper bound of the interval. It must be the case that the upper bound is weakly above the lower bound of a well-formed interval. When the domain of an interval is [47mINTEGERP[0m, there are additional constraints on the other components. See [make-tau-interval].") (tau-interval-hi-rel (tau-system) "Access the upper bound relation of a tau interval It is the case that (tau-interval-hi-rel (make-tau-interval dom lo-rel lo hi-rel hi)) = hi-rel For a well-formed interval, [47mhi-rel[0m is a Boolean, where [47mt[0m denotes the [47m[<][0m (strong inequality or ``less-than'') relation and [47mnil[0m denotes [47m[<=][0m (weak inequality or ``less-than-or-equal'') relation between the elements of the interval and the upper bound. When the domain of an interval is [47mINTEGERP[0m, there are additional constraints on the other components. See [make-tau-interval].") (tau-interval-lo (tau-system) "Access the lower bound of a tau interval It is the case that (tau-interval-lo (make-tau-interval dom lo-rel lo hi-rel hi)) = lo For a well-formed interval, [47mlo[0m is either [47mnil[0m, denoting negative infinity, or a rational number giving the lower bound of the interval. It must be the case that the lower bound is weakly below the upper bound of a well-formed interval. When the domain of an interval is [47mINTEGERP[0m, there are additional constraints on the other components. See [make-tau-interval].") (tau-interval-lo-rel (tau-system) "Access the lower bound relation of a tau interval It is the case that (tau-interval-lo-rel (make-tau-interval dom lo-rel lo hi-rel hi)) = lo-rel For a well-formed interval, [47mlo-rel[0m is a Boolean, where [47mt[0m denotes the [47m[<][0m (strong inequality or ``less-than'') relation and [47mnil[0m denotes [47m[<=][0m (weak inequality or ``less-than-or-equal'') relation between the lower bound and the elements of the interval. When the domain of an interval is [47mINTEGERP[0m, there are additional constraints on the other components. See [make-tau-interval].") (tau-intervalp (tau-system) "Boolean recognizer for tau intervals General Form: (tau-intervalp x) An interval is a structure of the form: [47m([0m[3mdom[0m [47m([0m[3mlo-rel[0m [47m.[0m [3mlo[0m[47m)[0m [47m.[0m [47m([0m[3mhi-rel[0m [47m.[0m [3mhi[0m[47m))[0m. Every tau contains an interval used to represent the domain and the upper and lower bounds of the objects recognized by the tau. Restrictions on the components of an interval are as follows. For an interpretation of the meaning of the components, see [47m[in-tau-intervalp][0m or [47m[make-tau-interval][0m. [3mDom[0m (``domain'') must be one of four symbols: [47mINTEGERP[0m, [47mRATIONALP[0m, [47mACL2-NUMBERP[0m, or [47mNIL[0m. The two ``relations,'' [3mlo-rel[0m and [3mhi-rel[0m, must be Booleans. [3mLo[0m and [3mhi[0m must be either [47mnil[0m or explicit rational numbers. [3mLo[0m must be no greater than [3mhi[0m (where [47mnil[0ms represent negative or positive infinity for [3mlo[0m and [3mhi[0m respectively. Finally, if the [3mdom[0m is [47mINTEGERP[0m, then both relations must [47mnil[0m and [3mlo[0m and [3mhi[0m must be integers when they are non-[47mnil[0m. Recall that [47m[make-tau-interval][0m constructs intervals. The intervals it constructs are well-formed only if the arguments to [47mmake-tau-interval[0m satisfy the rules above; [47mmake-tau-interval[0m does not coerce or adjust its arguments in any way. Thus, it can be (mis-)used to create non-intervals. Here are examples of [47mtau-intervalp[0m using [47mmake-tau-interval[0m. ; integers: 0 <= x <= 10: (tau-intervalp (make-tau-interval 'INTEGERP nil 0 nil 10)) = t ; integers: 0 <= x (i.e., the natural numbers): (tau-intervalp (make-tau-interval 'INTEGERP nil 0 nil nil)) = t ; violations of domain rules: (tau-intervalp (make-tau-interval 'INTEGERP t 0 t 10)) = nil (tau-intervalp (make-tau-interval 'INTEGERP nil 0 nil 10/11)) = nil ; violation of rule that bounds must be rational if non-nil: (tau-intervalp (make-tau-interval 'ACL2-NUMBERP t 0 t #c(3 5))) = nil ; violation of rule that lo <= hi: (tau-intervalp (make-tau-interval 'ACL2-NUMBERP t 0 t -10)) = nil ; rationals: 0 < x <= 22/7: (tau-intervalp (make-tau-interval 'RATIONALP t 0 nil 22/7)) = t ; numbers: -10 < x < 10: (tau-intervalp (make-tau-interval 'ACL2-NUMBERP t -10 t 10)) = t ; any: -10 < x < 10: (tau-intervalp (make-tau-interval nil t -10 t 10)) = t : any: (tau-intervalp (make-tau-interval nil nil nil nil nil)) = t Note that the second-to-last interval, with domain [47mnil[0m contains all non-numbers as well as numbers strictly between -10 and 10. The reason is that the interval contains [47m0[0m and all non-numbers are coerced to [47m0[0m by the inequality functions. Note that the last interval contains all ACL2 objects. It is called the ``universal interval.''") (tau-status (tau-system) "Query or set tau system status Examples: (tau-status) (tau-status :system t) (tau-status :auto-mode nil) (tau-status :system t :auto-mode nil) General Form: (tau-status :system a :auto-mode b) where [47ma[0m and [47mb[0m are Booleans. Both keyword arguments are optional and they may be presented in either order. Value [47ma[0m controls whether the [47m[tau-system][0m is used during subsequent proofs. Value [47mb[0m controls whether tau system rules are added automatically (``greedily'') when rules of other [47m[rule-classes][0m are added. If no arguments are supplied, this is not an event and just returns an [error-triple] indicating the current settings. See [introduction-to-the-tau-system] for background details. The two flags are independent. For example, the tau system may be disabled in proof attempts even though it is automatically (and silently) extending its database as rules of other classes are added. Flag (a) is actually toggled by enabling or disabling the [47m:[0m[47m[executable-counterpart][0m of [47m[tau-system][0m. Flag (b) is toggled with the function [47m[set-tau-auto-mode][0m, which manipulates the [47m[ACL2-defaults-table][0m. This macro expands into zero, one, or two [events], as required by the supplied values of flags [47ma[0m and [47mb[0m. If no arguments are supplied the form is not an event and simply returns (as an [error-triple], [47m(mv nil ans state)[0m) the current settings of the two flags. For example: ACL2 !>(tau-system) ((:SYSTEM NIL) (:AUTO-MODE T)) intended to be self-explanatory.") (tau-system (rule-classes) "Make a rule for the ACL2 ``type checker'' This documentation topic describes the syntactic form of ``tau-system'' rules; these rules extend ACL2's ``type checker.'' For an introduction to the tau system, see [introduction-to-the-tau-system]. There happens to be a [3mfunction[0m named [47mtau-system[0m, defined as the identity function. Its only role is to provide the rune [47m(:EXECUTABLE-COUNTERPART TAU-SYSTEM)[0m, which is used to enable and disable the tau system. Otherwise the function [47mtau-system[0m has no purpose and we recommend that you avoid using it so you are free to enable and disable the tau system. When in the default (``greedy'') mode (see [47m[set-tau-auto-mode][0m), every [47m[defun][0m and every [47m:corollary[0m (see [47m:[0m[47m[rule-classes][0m) of every [47m[defthm][0m stored as a rule [3mof any[0m [47m:rule-class[0m is inspected to determine if it is of one of the forms below. Rules of these forms are added to the tau database, even if they are not labeled as [47m:tau-system[0m rules, e.g., a [47m:[0m[47m[rewrite][0m rule might contribute to the tau database! To add a rule to the tau database without adding any other kind of rule, tag it with [47m:[0m[47m[rule-classes][0m [47m:tau-system[0m. If a theorem has [47m:[0m[47m[rule-classes][0m [47mnil[0m, it is not considered for the tau database. General Forms: [3mBoolean[0m: (booleanp (p v)) [3mEval[0m: (p 'const) or (p *const*) [3mSimple[0m: (implies (p v) (q v)) [3mConjunctive[0m: (implies (and (p1 v) ... (pk v)) (q v)), ; Here k must exceed 1. [3mSignature Form 1[0m: (implies (and (p1 x1) (p2 x2) ...) (q (fn x1 x2 ...))) [3mSignature Form 2[0m: (implies (and (p1 x1) (p2 x2) ...) (q (mv-nth 'n (fn x1 x2 ...)))) [3mBounder Form 1 (or Form 2)[0m: (implies (and (tau-intervalp i1) ... (or (equal (tau-interval-dom i1) 'dom1-1) ...) ... (in-tau-intervalp x1 i1) ...) (and (tau-intervalp (bounder-fn i1 ...)) (in-tau-intervalp [3mtarget[0m (bounder-fn i1 ...)))) where [3mtarget[0m is (fn x1 ... y1 ...) in [3mForm 1[0m, and (mv-nth 'n (fn x1 ... y1 ...)) in [3mForm 2[0m [3mBig Switch[0m: (equal (fn . formals) body) [3mMV-NTH Synonym[0m: (equal (nth-alt x y) (mv-nth x y)) or (equal (mv-nth x y) (nth-alt x y)) The symbols [47mp[0m, [47mq[0m, [47mp1[0m, etc., denote monadic (one-argument) Boolean-valued function symbols, or equalities in which one argument is constant, arithmetic comparisons in which one argument is a rational or integer constant, or the logical negations of such terms. By ``equalities'' we allow [47m[equal][0m, [47m[eq][0m, [47m[eql][0m, and [47m[=][0m. By ``arithmetic comparison'' we mean [47m[<][0m, [47m[<=][0m, [47m[>=][0m, or [47m[>][0m. Any of these tau predicates may appear negated. The notation [47m(p v)[0m above might stand for any one of: (INTEGERP X) (EQUAL V 'MONDAY) (<= I 16) (NOT (EQUAL X 'SUNDAY)) The different rule forms above affect different aspects of the tau system. We discuss each form in more detail below. The documentation below is written as though the tau system is in auto mode! To ensure that the only rules added to the tau system are those explicitly assigned to [47m:rule-class[0m [47m:tau-system[0m, you should use [47m[set-tau-auto-mode][0m to select manual mode. General Form: [3mBoolean[0m: (booleanp (p v)) Here [47mp[0m must be a function symbol and [47mv[0m must be a variable. Such a [47m:tau-system[0m rule adds [47mp[0m to the list of tau predicates. If [47mp[0m was recognized as Boolean when it was defined, there is no need to state this rule. This form is needed if you define a monadic Boolean function in such a way that the system does not recognize that it is Boolean. General Form: [3mEval[0m: (p 'const) or (p *const*) Here [47mp[0m must be a function symbol. In addition, recall that these general tau predicate forms may appear negated. So the form above includes such theorems as [47m(NOT (GOOD-STATEP *INITIAL-STATE*))[0m. A theorem of this form thus records whether a named predicate is true or false on the given constant. Generally, when the tau system must determine whether an enabled tau predicate is true or false on a constant, it simply evaluates the predicate on the constant. This can be impossible or very inefficient if [47mp[0m is not defined but constrained, or if [47mp[0m is defined in a hard-to-compute way (e.g., [47m(defun p (x) (evenp (ack x x)))[0m where [47mack[0m is the Ackermann function), or perhaps if the constant is very large. By proving a [47m:tau-system[0m rule of Eval form, you cause the tau system to note the value of the predicate on the constant and henceforth to look it up instead of evaluating the definition. A difficulty, however, is determining that a slow down is due to the evaluation of tau predicates and not some other reason. The first step is determining that tau is slowing the proof down. See [47m[time-tracker-tau][0m for an explanation of [47mTIME-TRACKER-NOTE[0ms output during some proofs involving tau reasoning. These notes can alert you to the fact that significant amounts of time are being spent in the tau system. [47m[Time-tracker-tau][0m gives some ways of determining whether tau predicate evaluation is involved. (If worse comes to worst, consider the following hack: In the ACL2 source file [47mtau.lisp[0m, immediately after the definition of the system function [47mev-fncall-w-tau-recog[0m, there is a comment which contains some raw Lisp code that can be used to investigate whether tau's use of evaluation on constants is causing a problem.) However, once a recognizer and the constants on which it is being evaluated are identified, the tau system can be sped up by proving Eval rules to pre-compute and store the values of the recognizer on those constants. Alternatively, at the possible loss of some completeness in the tau system, the executable-counterpart of the recognizer can be disabled. General Form: [3mSimple[0m: (implies (p v) (q v)) Here [47mv[0m must be a variable symbol. This rule builds-in the information that anything satisfying [47mp[0m must also satisfy [47mq[0m, i.e., the ``type'' [47mq[0m includes the ``type'' [47mp[0m. Recall that the forms may be negated. Most of the time, [47mp[0m and [47mq[0m will be predicate symbols but it is possible they will be equalities- or inequalities-with-constants. Examples of Simple rules include the following, which are in fact built-in: (implies (natp x) (integerp x)) (implies (integerp x) (rationalp x)) (implies (integerp x) (not (true-listp x))) (implies (natp x) (not (< x 0))) (implies (symbol-alistp x) (alistp x)) Because the tau system records the transitive closure of the Simple rules, any time a term is known to satisfy [47mnatp[0m it is also known to satisfy [47mintegerp[0m and [47mrationalp[0m, and known not to satisfy [47mtrue-listp[0m, and known to be non-negative. General Form: [3mConjunctive[0m: (implies (and (p1 v) ... (pk v)) (q v)), ; Here k must exceed 1. The [47mpi[0m and [47mq[0m may be any tau predicates or their negations, [47mv[0m must be a variable symbol, and [47mi[0m must exceed 1 or else this is a Simple rule. An obvious operational interpretation of this rule is that if an object is known to satisfy all of the [47mpi[0m, then it is known to satisfy [47mq[0m. However, the actual interpretation is more general. For example, if an object is known to satisfy all but one of the [47mpi[0m and is known not to satisfy [47mq[0m, then the object is known not to satisfy the ``missing'' [47mpi[0m. For example, the following Conjunctive rule allows tau to conclude that if weekday [47mD[0m is not [47mMON[0m, [47mTUE[0m, [47mTHU[0m or [47mFRI[0m, then it is [47mWED[0m: (implies (and (weekdayp d) (not (eq d 'MON)) (not (eq d 'TUE)) (not (eq d 'WED)) (not (eq d 'THU))) (eq d 'FRI)) The tau database is not closed under conjunctive rules; they are applied dynamically. General Form: [3mSignature Form 1[0m: (implies (and (p1 x1) (p2 x2) ... (pn xn) dep-hyp) (q (fn x1 x2 ... xn))) The [47mpi[0m and [47mq[0m may be any tau predicates or their negations, [47mfn[0m must be a function symbol of arity [47mn[0m, the [47mxi[0m must be distinct variable symbols and [47mdep-hyp[0m may be any term, provided it is not of the [47m(pi xi)[0m shape and the only variables in it are the [47mxi[0m. The Signature form actually allows multiple tau predicates to be applied to each variable, e.g., x1 might be required to be both an [47mINTEGERP[0m and [47mEVENP[0m. The Signature form allows there to be multiple hypotheses classified as [47mdep-hyp[0ms, i.e., not fitting any of the previous shapes, and they are implicitly just conjoined. The name ``dep-hyp'' is an abbreviation of ``dependent hypothesis'' and stems from the fact they often express relations between several of the function's inputs rather than type-like constraints on individual inputs. A Signature rule informs tau that the function [47mfn[0m returns an object satisfying [47mq[0m provided that the arguments satisfy the respective [47mpi[0m and provided that [47mdep-hyp[0m occurs in the current context. Note: to be precise, dependent hypotheses are relieved only by applying ACL2's most primitive form of reasoning, type reasoning (see [TYPE-REASONING]) (using [type-set]). In particular, tau reasoning is not used to establish dependent hypotheses. The presence of a [47mdep-hyp[0m in a signature rule may severely restrict its applicability. We discuss this after showing a few mundane examples. An example Signature rule is (implies (and (integer-listp x) (integer-listp y)) (integer-listp (append x y))) Of course, a function may have multiple signatures: (implies (and (symbol-listp x) (symbol-listp y)) (symbol-listp (append x y))) Here is a Signature rule for the function [47mpairlis$[0m: (implies (and (symbol-listp x) (integer-listp y)) (symbol-alistp (pairlis$ x y))) The tau system can consequently check this theorem by composing the last two rules shown and exploiting Simple rule stating that symbol-alists are also alists: (thm (implies (and (symbol-listp a) (symbol-listp b) (integer-listp y)) (alistp (pairlis$ (append a b) y)))) Since [47ma[0m and [47mb[0m are known to be lists of symbols and a signature for [47mappend[0m is that it preserves that predicate, the first argument to the [47mpairlis$[0m expression is known to be a list of symbols. This means the Signature rule for [47mpairlis$[0m tells us the result is a [47msymbol-alistp[0m, but the previously mentioned Simple rule, [47m(implies (symbol-alistp x) (alistp x))[0m, tells us the result is also an [47malistp[0m. When a Signature rule has an [47mdep-hyp[0m, that hypothesis is not an expression in the tau system. Tau is not used to check that hypothesis. Instead, tau uses the more primitive [type-set] mechanism of ACL2. Here is an example of a Signature rule with a [47mdep-hyp[0m: (implies (and (natp n) (integer-listp a) (< n (len a))) (integerp (nth n a))) Note that the last hypothesis is a dependent hypothesis: it is not a tau predicate but a relationship between [47mn[0m and [47ma[0m. It is relieved by [type-set]. If one is trying to compute the signature of an [47m(nth n a)[0m expression in a context in which [47m(< n (len a))[0m is explicitly assumed, then this mechanism would establish the dependent hypothesis. But one can easily imagine an almost identical context where, say [47m(< n (len (rev a)))[0m is explicitly assumed. In that context, the Signature rule would not be fired because [47m[type-set][0m cannot establish [47m(< n (len a))[0m from [47m(< n (len (rev a)))[0m, even though it would be easily proved by rewriting using the theorem [47m(equal (len (rev a)) (len a))[0m. Note also that if this signature could be phrased in a way that eliminates the dependency between [47mn[0m and [47ma[0m it would be more effective. For example, here is a related Signature rule without a dependent hypothesis: (implies (and (natp n) (register-filep a) (< n 16)) (integerp (nth n a))) In this theorem we require only that [47mn[0m be less than 16, which is a tau predicate and hence just an additional tau constraint on [47mn[0m. General Form: [3mSignature Form 2[0m: (implies (and (p1 x1) (p2 x2) ... (pn xn) dep-hyp) (q (mv-nth 'n (fn x1 x2 ... xn)))) This form of signature rule is just like form 1 except that it is useful for functions that return [multiple-value]s and allows us to ``type-check'' their individual outputs. General Form: [3mBounder Forms 1 and 2[0m: (implies (and (tau-intervalp i1) ... (or (equal (tau-interval-dom i1) 'dom1-1) ...) ... (in-tau-intervalp x1 i1) ...) (and (tau-intervalp (bounder-fn i1 ...)) (in-tau-intervalp [3mtarget[0m (bounder-fn i1 ...)))) where [3mtarget[0m is either [47m(fn x1 ... y1 ...)[0m in [3mForm 1[0m or [47m(mv-nth 'n (fn x1 ... y1 ...))[0m in [3mForm 2[0m. This form is for advanced users only and the schema given above is just a reminder of the general shape. A ``bounder'' for a given function symbol, [47mfn[0m, is a function symbol [47mbounder-fn[0m that computes an interval containing [47m(fn x1 ... y1 ...)[0m (or its [47mn[0mth component in the case of Form 2 rules) from the intervals containing certain of the arguments of [47mfn[0m. The correctness theorem for a bounder function informs the tau system that bounds for [47mfn[0m are computed by [47mbounder-fn[0m and sets up the correspondence between the relevant arguments, [47mxi[0m, of [47mfn[0m and the intervals containing those arguments, [47mii[0m to which [47mbounder-fn[0m is applied. When the tau system computes the tau for a call of [47mfn[0m, it computes the tau of the relevant arguments and applies the bounder to the intervals of those tau. This provides a domain and upper and/or lower bounds for the value of the term. The tau system then further augments that with signature rules. See [bounders] for details on intervals, bounders, and bounder correctness theorems. General Form: [3mBig Switch[0m: (equal (fn . formals) body) In the Big Switch form, [47mfn[0m must be a function symbol, [47mformals[0m must be a list of distinct variable symbols, and [47mbody[0m must be a ``big switch'' term, i.e., one that case splits on tau predicates about a single variable and produces a term not involving that variable. An example of a Big Switch rule is (equal (conditional-type x y) (if (consp x) (consp y) (integerp y))) The idea is that the tau system can treat calls of [47mconditional-type[0m as a tau-predicate after determining the tau of an argument. Since equality-to-constants are tau predicates, a more common example of a Big Switch rule is (equal (dtypep x expr) (case x (STMT (stmt-typep expr)) (EXPR (expr-typep expr)) (MODULE (module-typep expr)) (otherwise nil))) This is because [47m(case x (STMT ...) ...)[0m macroexpands in ACL2 to [47m(if (eql x 'STMT) ... ...)[0m and [47m(eql x 'STMT)[0m is a tau predicate about [47mx[0m. Big Switch rules are recognized when a function is defined (if tau is in automatic mode). They generally do not have to be proved explicitly, though they might be when mutual recursion is involved. Only the first detected Big Switch rule about a function [47mfn[0m is recognized. General Form: [3mMV-NTH Synonym[0m: (equal (nth-alt x y) (mv-nth x y)) or (equal (mv-nth x y) (nth-alt x y)) Rules of this form just tell the tau system that the user-defined function [47mnth-alt[0m is synonymous with the ACL2 primitive function [47m[mv-nth][0m. Because ACL2's rewriter gives special handling to [47mmv-nth[0m by default, users sometimes define their own versions of that function so they can disable them and control rewriting better. By revealing to the tau system that such a synonym has been introduced you allow Signature rules of Form 2 to be used. Subtopics [Bounders] Intervals, bounder functions, and bounder correctness [In-tau-intervalp] Boolean membership in a tau interval [Introduction-to-the-tau-system] A decision procedure for runtime types [Make-tau-interval] Make a tau interval [Set-tau-auto-mode] Turn on or off automatic (``greedy'') generation of [47m:tau-system[0m rules [Tau-data] To see what tau knows about a function symbol [Tau-database] To see the tau database as a (very large) object [Tau-interval-dom] Access the domain of a tau interval [Tau-interval-hi] Access the upper bound of a tau interval [Tau-interval-hi-rel] Access the upper bound relation of a tau interval [Tau-interval-lo] Access the lower bound of a tau interval [Tau-interval-lo-rel] Access the lower bound relation of a tau interval [Tau-intervalp] Boolean recognizer for tau intervals [Tau-status] Query or set tau system status [Time-tracker-tau] Messages about expensive use of the [tau-system]") (tc (macros) "translate form and clean it up Examples: :tc (member e a) :tc (list (cadr x) (loop$ for e in lst collect (+ 1 e))) :tcp (list (cadr x) (loop$ for e in lst collect (+ 1 e))) :tca (list (cadr x) (loop$ for e in lst collect (+ 1 e))) General Form: :tc form :tca form :tcp form (tc 'form) (tca 'form) (tcp 'form) The [47m:[0m[47m[trans][0m command prints the translation of a form into a formal term. However, sometimes the translation can be hard to understand because various tags and declarations are included, usually for execution efficiency. For example, consider [47m:trans[0m versus [47m:tcp[0m of [47m(member e a)[0m. ACL2 !>:trans (member e a) ((LAMBDA (X L) (RETURN-LAST 'MBE1-RAW (MEMBER-EQL-EXEC X L) (RETURN-LAST 'PROGN (MEMBER-EQL-EXEC$GUARD-CHECK X L) (MEMBER-EQUAL X L)))) E A) => * ACL2 !>:tcp (member e a) (MEMBER-EQUAL E A) The [47m:tc[0m command and its variants, [47m:tca[0m and [47m:tcp[0m, translate the given form and then ``clean'' it up, returning the result in an [error-triple]. These commands are especially useful when [47m[loop$][0m, [scion]s or [47m[lambda$][0m forms are involved in the form to be translated. But they are also useful when [47m[mbe][0m, [47m[return-last][0m, [47m[progn$][0m and other special forms are used or show up in the translation. The [47mtc[0m commands are macros that expand into terms involving [47m[state][0m, since errors are signaled when ill-formed forms are submitted. * [47m:tc[0m [3mform[0m --- translate [3mform[0m and remove everything not relevant to the logical value. This is the logical semantics [3mform[0m and is returned in the ``internal format'' of ACL2 terms, i.e., macros have been expanded and all constants are quoted. The prover will reduce [3mform[0m to this term almost immediately. Typically, this is the term that the rewriter will encounter during a proof involving this [3mform[0m. Of course, rewrite rules can further change the form. However, see the note below concerning warrants. * [47m:tcp[0m [3mform[0m --- translate [3mform[0m and remove everything not relevant to the logical value as above, and then [47m[untranslate][0m, restoring the use of such system macros as [47m[lambda$][0m, [47m[let][0m, [47m[and][0m, [47m[list][0m, [47m[cadr][0m, and [47m[+][0m and [47m[*][0m. This is the semantics of [3mform[0m in a ``user friendly'' syntax. The suffix ``p'' in [47m:tcp[0m stands for ``pretty.'' * [47m:tca[0m [3mform[0m --- translate [3mform[0m and then [47muntranslate[0m as noted above. This effectively leaves ``annotations'' in place such as a [47mprog2$[0m joining each [47mloop$[0m in [3mform[0m to its semantics, [47mdeclare[0m forms in [47mlambda[0m objects, and [47m[let][0m forms associating user variable names to values. This term is mainly meant as a pedagogical device to help you understand how [47mloop$[0ms are translated. The suffix ``a'' in [47m:tca[0m stands for ``annotated.'' The terms returned by the three flavors of [47mtc[0m are all provably equivalent to each other and to the original [3mform[0m provided the necessary warrants are assumed. For example, if [47msq[0m is a user-defined function of arity 1 and [47m(defwarrant sq)[0m has issued a warrant for [47msq[0m, then ACL2 !>:tc (loop$ for e in lst collect (sq e)) ; sq is warranted (COLLECT$ '(LAMBDA (LOOP$-IVAR) (SQ LOOP$-IVAR)) LST) Nevertheless, the equivalence of the input and output of [47m:tc[0m above cannot be proved unless the warrants are assumed. That is, (thm (equal (loop$ for e in lst collect (sq e)) (COLLECT$ '(LAMBDA (LOOP$-IVAR) (SQ LOOP$-IVAR)) LST))) will fail with a checkpoint indicating that the warrant for [47msq[0m must be provided. However, (thm (implies (warrant sq) (equal (loop$ for e in lst collect (sq e)) (COLLECT$ '(LAMBDA (LOOP$-IVAR) (SQ LOOP$-IVAR)) LST)))) succeeds. If there is no warrant for [47msq[0m but there is a badge, then [47m:tc[0m cannot clean up the translation because without a warrant the [47mlambda[0m object calling [47msq[0m is not [tame]. Thus, ACL2 !>:tc (loop$ for e in lst collect (sq e)) ; sq is badged not warranted (COLLECT$ '(LAMBDA (LOOP$-IVAR) (RETURN-LAST 'PROGN '(LAMBDA$ (LOOP$-IVAR) (LET ((E LOOP$-IVAR)) (DECLARE (IGNORABLE E)) (SQ E))) ((LAMBDA (E) (SQ E)) LOOP$-IVAR))) LST) By the way, if you see a quoted [47mlambda[0m objects like that above in output from the prover, it probably means the [47mlambda[0m object contains unwarranted user-defined symbols! The differences between [47m:trans[0m and the three commands ([47m:tc[0m, [47m:tcp[0m, and [47m:tca[0m) are perhaps best illustrated by considering their respective outputs on a single [47m[loop$][0m statement. ACL2 !>:trans (list (cadr x) (loop$ for e in lst collect (+ 1 e))) (CONS (CAR (CDR X)) (CONS (RETURN-LAST 'PROGN '(LOOP$ FOR E IN LST COLLECT (+ 1 E)) (COLLECT$ '(LAMBDA (LOOP$-IVAR) (DECLARE (IGNORABLE LOOP$-IVAR)) (RETURN-LAST 'PROGN '(LAMBDA$ (LOOP$-IVAR) (LET ((E LOOP$-IVAR)) (DECLARE (IGNORABLE E)) (+ 1 E))) ((LAMBDA (E) (BINARY-+ '1 E)) LOOP$-IVAR))) LST)) 'NIL)) => * ACL2 !>:tc (list (cadr x) (loop$ for e in lst collect (+ 1 e))) (CONS (CAR (CDR X)) (CONS (COLLECT$ '(LAMBDA (LOOP$-IVAR) (BINARY-+ '1 LOOP$-IVAR)) LST) 'NIL)) ACL2 !>:tcp (list (cadr x) (loop$ for e in lst collect (+ 1 e))) (LIST (CADR X) (COLLECT$ (LAMBDA$ (LOOP$-IVAR) (+ 1 LOOP$-IVAR)) LST)) ACL2 !>:tca (list (cadr x) (loop$ for e in lst collect (+ 1 e))) (LIST (CADR X) (PROG2$ '(LOOP$ FOR E IN LST COLLECT (+ 1 E)) (COLLECT$ (LAMBDA$ (LOOP$-IVAR) (LET ((E LOOP$-IVAR)) (DECLARE (IGNORABLE E)) (+ 1 E))) LST))) First, notice that [47m:trans[0m also reports the output signature of the term but the [47m:tc[0m commands do not. They all return the cleaned up translation in an error triple. Second, [47m:tc[0m returns a term in the internal format: the [47mlambda[0m objects are quoted list constants and their bodies are in internal format, e.g., note the [47mbinary-+[0m and quoted constant [47m1[0m in the output of [47m:tc[0m above. If you use the [47m:tc[0m command on the left-hand side of the conclusion of a [47m:rewrite[0m rule the term you see is the term under which the rule is stored, i.e., the rule will be tried to rewrite instances of that term. The other two commands have ``prettied up'' the output into a more user-friendly format. Third, the [47m:tca[0m command uses a [47mprog2$[0m to show the untranslated [47mloop$[0m as a list constant and then show its pretty semantics, with a [47mlet[0m form in the body of the [47mlambda$[0m reminding you that [47mloop$-ivar[0m is what was called [47me[0m. It is often helpful to look at the semantics of fancy [47mloop$[0ms. ACL2 !>:tca (loop$ for x in xlst as y in ylst collect (+ (* a x) (* b y))) (PROG2$ '(LOOP$ FOR X IN XLST AS Y IN YLST COLLECT (+ (* A X) (* B Y))) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 2) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 2)))) (LET ((A (CAR LOOP$-GVARS)) (B (CAR (CDR LOOP$-GVARS))) (X (CAR LOOP$-IVARS)) (Y (CAR (CDR LOOP$-IVARS)))) (DECLARE (IGNORABLE A B X Y)) (+ (* A X) (* B Y)))) (LIST A B) (LOOP$-AS (LIST XLST YLST)))) Notice what happens to the [47m:guard[0m of the [47mlambda$[0m if we insert type specifications with [47mof-type[0m. ACL2 !>:tca (loop$ for x of-type (satisfies natp) in xlst as y of-type integer in ylst collect (+ (* a x) (* b y))) (PROG2$ '(LOOP$ FOR X OF-TYPE (SATISFIES NATP) IN XLST AS Y OF-TYPE INTEGER IN YLST COLLECT (+ (* A X) (* B Y))) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 2) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 2) (NATP (CAR LOOP$-IVARS)) (INTEGERP (CAR (CDR LOOP$-IVARS)))))) (LET ((A (CAR LOOP$-GVARS)) (B (CAR (CDR LOOP$-GVARS))) (X (CAR LOOP$-IVARS)) (Y (CAR (CDR LOOP$-IVARS)))) (DECLARE (TYPE (SATISFIES NATP) X) (TYPE INTEGER Y) (IGNORABLE A B X Y)) (+ (* A X) (* B Y)))) (LIST A B) (LOOP$-AS (LIST XLST YLST)))) And notice how the [47m:guard[0m keyword after the [47mcollect[0m in the [47mloop$[0m statement is added to the [47m:guard[0m of the generated [47mlambda$[0m. ACL2 !>:tca (loop$ for x of-type (satisfies natp) in xlst as y of-type integer in ylst collect :guard (and (rationalp a) (complex-rationalp b)) (+ (* a x) (* b y))) (PROG2$ '(LOOP$ FOR X OF-TYPE (SATISFIES NATP) IN XLST AS Y OF-TYPE INTEGER IN YLST COLLECT :GUARD (AND (RATIONALP A) (COMPLEX-RATIONALP B)) (+ (* A X) (* B Y))) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS) (EQUAL (LEN LOOP$-GVARS) 2) (TRUE-LISTP LOOP$-IVARS) (EQUAL (LEN LOOP$-IVARS) 2) (NATP (CAR LOOP$-IVARS)) (INTEGERP (CAR (CDR LOOP$-IVARS))) (AND (RATIONALP (CAR LOOP$-GVARS)) (COMPLEX-RATIONALP (CAR (CDR LOOP$-GVARS))))))) (LET ((A (CAR LOOP$-GVARS)) (B (CAR (CDR LOOP$-GVARS))) (X (CAR LOOP$-IVARS)) (Y (CAR (CDR LOOP$-IVARS)))) (DECLARE (TYPE (SATISFIES NATP) X) (TYPE INTEGER Y) (IGNORABLE A B X Y)) (+ (* A X) (* B Y)))) (LIST A B) (LOOP$-AS (LIST XLST YLST)))) Of course, while these declarations play a role in [47m:guard[0m verification and execution in raw Lisp, they are irrelevant to the formal semantics, as made clear by [47m:tcp[0m. ACL2 !>:tcp (loop$ for x of-type (satisfies natp) in xlst as y of-type integer in ylst collect :guard (and (rationalp a) (complex-rationalp b)) (+ (* a x) (* b y))) (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS) (+ (* (CAR LOOP$-GVARS) (CAR LOOP$-IVARS)) (* (CADR LOOP$-GVARS) (CADR LOOP$-IVARS)))) (LIST A B) (LOOP$-AS (LIST XLST YLST)))") (tca (macros) "translate a form and clean it up into an annotated pretty term See [47m[tc][0m.") (tcp (macros) "translate a form and clean it up into a pretty term See [47m[tc][0m.") (tenth (nth acl2-built-ins) "Tenth member of the list See any Common Lisp documentation for details.") (term (miscellaneous) "The three senses of well-formed ACL2 expressions or formulas Also see [untranslate] for a relevant utility (and a more abbreviated explanation of terms). Examples of Terms: (cond ((caar x) (cons t x)) (t 0)) ; an untranslated term (if (car (car x)) (cons 't x) '0) ; a translated term (car (cons x y) 'nil v) ; a pseudo-term In traditional first-order predicate calculus a ``term'' is a syntactic entity denoting some object in the universe of individuals. Often, for example, the syntactic characterization of a term is that it is either a variable symbol or the application of a function symbol to the appropriate number of argument terms. (Note that ACL2 is case-insensitive when dealing with symbols; see [symbols].) Traditionally, ``atomic formulas'' are built from terms with predicate symbols such as ``equal'' and ``member;'' ``formulas'' are then built from atomic formulas with propositional ``operators'' like ``not,'' ``and,'' and ``implies.'' Theorems are formulas. Theorems are ``valid'' in the sense that the value of a theorem is true, in any model of the axioms and under all possible assignments of individuals to variables. However, in ACL2, terms are used in place of both atomic formulas and formulas. ACL2 does not have predicate symbols or propositional operators as distinguished syntactic entities. The ACL2 universe of individuals includes a ``true'' object (denoted by [47mt[0m) and a ``false'' object (denoted by [47mnil[0m), predicates and propositional operators are functions that return these objects. Theorems in ACL2 are terms and the ``validity'' of a term means that, under no assignment to the variables does the term evaluate to [47mnil[0m. We use the word ``term'' in ACL2 in three distinct senses. We will speak of ``translated'' terms, ``untranslated'' terms, and ``pseudo-'' terms. [3mTranslated Terms: The Strict Sense and Internal Form[0m In its most strict sense, a ``term'' is either a legal variable symbol, a quoted constant, or the application of an n-ary function symbol or closed [47mlambda[0m expression to a true list of n terms. The legal variable symbols are symbols other than [47mt[0m or [47mnil[0m which are not in the keyword package, do not start with ampersand, do not start and end with asterisks, and if in the main Lisp package, do not violate an appropriate restriction (see [name]). Quoted constants are expressions of the form [47m(quote x)[0m, where [47mx[0m is any ACL2 object. Such expressions may also be written [47m'x[0m. Closed [47mlambda[0m expressions are expressions of the form [47m(lambda (v1 ... vn) body)[0m where the [47mvi[0m are distinct legal variable symbols, [47mbody[0m is a term, and the only free variables in [47mbody[0m are among the [47mvi[0m. The function [47mtermp[0m, which takes two arguments, an alleged term [47mx[0m and a logical world [47mw[0m (see [world]), recognizes terms of a given extension of the logic. Its definition may be inspected with [47m:[0m[47m[pe][0m [47mtermp[0m for a complete specification of what we mean by ``term'' in the most strict sense. Most ACL2 term-processing functions deal with terms in this strict sense and use [47mtermp[0m as a [guard]. That is, the ``internal form'' of a term satisfies [47mtermp[0m, the strict sense of the word ``term.'' [3mUntranslated Terms: What the User Types[0m While terms in the strict sense are easy to explore (because their structure is so regular and simple) they can be cumbersome to type. Thus, ACL2 supports a more sugary syntax that includes uses of macros and constant symbols. Very roughly speaking, macros are functions that produce terms as their results. Constants are symbols that are associated with quoted objects. Terms in this sugary syntax are ``translated'' to terms in the strict sense; the sugary syntax is more often called ``untranslated.'' Translation includes the process of macroexpansion as well as the replacement of constant symbols by their quoted values, while checking all the rules governing the strict sense of ``term.'' More precisely, macro symbols are as described in the documentation for [47m[defmacro][0m. A macro, [47mmac[0m, can be thought of as a function, [47mmac-fn[0m, from ACL2 objects to an ACL2 object to be treated as an untranslated term. For example, [47m[caar][0m is defined as a macro symbol; the associated macro function maps the object [47mx[0m into the object [47m(car (car x))[0m. A macro form is a ``call'' of a macro symbol, i.e., a list whose [47m[car][0m is the macro symbol and whose [47m[cdr][0m is an arbitrary true list of objects, used as a term. Macroexpansion is the process of replacing in an untranslated term every occurrence of a macro form by the result of applying the macro function to the appropriate arguments. The ``appropriate'' arguments are determined by the exact form of the definition of the macro; macros support positional, keyword, optional and other kinds of arguments. See [defmacro]. In addition to macroexpansion and constant symbol dereferencing, translation implements the mapping of [47m[let][0m and [47m[let*][0m forms into applications of [47mlambda[0m expressions and closes [47mlambda[0m expressions containing free variables. Thus, the translation of (let ((x (1+ i))) (cons x k)) can be seen as a two-step process that first produces ((lambda (x) (cons x k)) (1+ i)) and then ((lambda (x k) (cons x k)) (1+ i) k) . Observe that the body of the [47m[let][0m and of the first [47mlambda[0m expression contains a free [47mk[0m which is finally bound and passed into the second [47mlambda[0m expression. Translation also maps [47m[flet][0m forms into applications of [47mlambda[0m expressions. See [flet]. When we say, of an event-level function such as [47m[defun][0m or [47m[defthm][0m, that some argument ``must be a term'' we mean an untranslated term. The event functions translate their term-like arguments. To better understand the mapping between untranslated terms and translated terms it is convenient to use the keyword command [47m:[0m[47m[trans][0m to see examples of translations. See [trans] and also see [trans1]. Note that translation produces a translated term that need not obey code restrictions: a translated term can be used in theorems but might not be allowed in definitions (except in [non-executable] contexts; see [defun-nx] and see [non-exec]). Suppose for example that we make the following definition, so that [47mfoo[0m returns two values (see [mv]). (defun foo (x) (mv x x)) Now consider the following translation of a use of [47m[mv-let][0m. ACL2 !>:trans (mv-let (a b) (foo x) (+ a b)) ((LAMBDA (MV) ((LAMBDA (A B) (BINARY-+ A B)) (MV-NTH '0 MV) (MV-NTH '1 MV))) (FOO X)) => * ACL2 !> The first definition below is legal. But the second definition --- which uses the translation of the body of the first definition --- is not legal. That's because a [lambda] application, as with any function application, expects each of its arguments to represent a single value, but the argument [47m(foo x)[0m returns two values. (defun legal-def (x) (mv-let (a b) (foo x) (+ a b))) (defun illegal-def (x) ((LAMBDA (MV) ((LAMBDA (A B) (BINARY-+ A B)) (MV-NTH '0 MV) (MV-NTH '1 MV))) (FOO X))) Finally, we note that the theorem prover prints terms in untranslated form. But there can be more than one correct untranslated term corresponding to a given translated term. For example, the translated term [47m(if x y 'nil)[0m can be untranslated as [47m(if x y nil)[0m and can also be untranslated as [47m(and x y)[0m. The theorem prover attempts to print an untranslated term that is as helpful to the user as possible. In particular, consider a term of the form [47m(nth k st)[0m where [47mst[0m is a single-threaded object (see [stobj]) and the [47mkth[0m accessor of [47mst[0m is, say, [47mkn[0m. The theorem prover typically would expand [47m(kn st)[0m to [47m(nth k st)[0m. If [47mk[0m is large then it could be difficult for the user to make sense out of a proof transcript that mentions the expanded term. Fortunately, the untranslation of [47m(nth k st)[0m would be [47m(nth *kn* st)[0m; here [47m*kn*[0m would be a constant (see [defconst]) added by the [47m[defstobj][0m event introducing [47mst[0m, defined to have value [47mk[0m. The user can extend this user-friendly style of printing applications of [47m[nth][0m to stobjs; see [add-nth-alias]. These remarks about printing applications of function [47m[nth][0m extend naturally to function [47m[update-nth][0m. Moreover, the prover will attempt to treat terms as [stobj]s for the above purpose when appropriate. For example, if function [47mfoo[0m has [signature] [47m((foo * st) => (mv * * * st))[0m, where [47mst[0m is introduced with [47m(defstobj st f0 f1)[0m, then the [term] [47m(nth '1 (mv-nth '3 (foo x st0)))[0m will be printed as [47m(nth *f1* (mv-nth 3 (foo x st0)))[0m. [3mPseudo-Terms: A Common Guard for Metafunctions[0m Because [47mtermp[0m is defined in [47m:[0m[47m[program][0m mode, it cannot be used effectively in conjectures to be proved. Furthermore, from the perspective of merely guarding a term processing function, [47mtermp[0m often checks more than is required. Finally, because [47mtermp[0m requires the logical [world] as one of its arguments it is impossible to use [47mtermp[0m as a [guard] in places where the logical [world] is not itself one of the arguments. For these reasons we support the idea of ``pseudo-terms.'' A pseudo-term is either a symbol (but not necessarily one having the syntax of a legal variable symbol), a true list of length 2 beginning with [47mquote[0m, or the ``application of'' a symbol or pseudo [47mlambda[0m expression to a true list of pseudo-terms. A pseudo [47mlambda[0m expression is an expression of the form [47m(lambda (v1 ... vn) body)[0m where the [47mvi[0m are all symbols and [47mbody[0m is a pseudo-term. Pseudo-terms are recognized by the unary function [47m[pseudo-termp][0m. If [47m(termp x w)[0m is true, then [47m(pseudo-termp x)[0m is true. However, if [47mx[0m fails to be a (strict) term it may nevertheless still be a pseudo-term. For example, [47m(car a b)[0m is not a term, because [47m[car][0m is applied to the wrong number of arguments, but it is a pseudo-term. The structures recognized by [47m[pseudo-termp][0m can be recursively explored with the same simplicity that terms can be. In particular, if [47mx[0m is not a [47mvariablep[0m or an [47mfquotep[0m, then [47m(ffn-symb x)[0m is the function ([47msymbol[0m or [47mlambda[0m expression) and [47m(fargs x)[0m is the list of argument pseudo-terms. A metafunction (see [meta]) or clause-processor (see [clause-processor]) may use [47m[pseudo-termp][0m as the [guard]. Subtopics [Guard-holders] Remove trivial calls from a [term] [Kwote] Quote an arbitrary object [Kwote-lst] Quote an arbitrary true list of objects [L<] Ordering on naturals or lists of naturals [Lambda] Lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions [Pseudo-term-listp] A predicate for recognizing lists of term-like s-expressions [Pseudo-termp] A predicate for recognizing term-like s-expressions [Term-order] The ordering relation on terms used by ACL2 [Termify] the process of converting a clause to a term [Termp] recognizer for the quotation of a [term]") (term-list-listp (acl2-built-ins) "recognizer for a list of [clause]s Example: (term-list-listp '(((NOT (ENDP X)) (NATP (LEN X))) ((ENDP X) (NOT (NATP (LEN (CDR X)))) (NATP (LEN X)))) (w state)) General Form: (term-list-listp x w) where [47mx[0m is any ACL2 object and [47mw[0m is an ACL2 logical [world]. The result is [47mt[0m or [47mnil[0m according to whether [47mx[0m is a true list of true lists of quotations of well-formed terms in [47mw[0m. This function is the standard ACL2 idiom for recognizing a ``set of clauses.'' See [clause] and see [47m[clause-processor][0m. Each clause processor is supposed to take a clause (i.e., [47mterm-listp[0m) as input and yield a list of clauses (i.e., [47mterm-list-listp[0m) as output. When a clause processor is run by the theorem prover its input is guaranteed to be a well-formed clause by invariants maintained by ACL2. But its output is checked by an explicit call to this function unless the user has proved that the clause processor always returns a list of clauses (see [well-formedness-guarantee]) or has taken the risk of disabling the runtime test with [47m[set-skip-meta-termp-checks][0m. [31;1mFunction: [0m<term-list-listp> (defun term-list-listp (l w) (declare (xargs :guard (plist-worldp-with-formals w))) (if (atom l) (equal l nil) (and (term-listp (car l) w) (term-list-listp (cdr l) w))))") (term-listp (acl2-built-ins) "recognizer for a list of quotations of terms and of [clause]s Example: (term-listp '((ZP X) 'NIL (CONS X Y)) (w state)) General Form: (term-listp x w) where [47mx[0m is any ACL2 object and [47mw[0m is an ACL2 logical [world]. The result is [47mt[0m or [47mnil[0m according to whether [47mx[0m is a true list of quotations of well-formed terms in [47mw[0m. This function is used in the definition of [47m[termp][0m. In addition, [47mterm-listp[0m is the standard ACL2 idiom for recognizing a clause (``set of literals''). See [clause] and see [47m[clause-processor][0m. Each clause processor is supposed to take a clause (i.e., [47mterm-listp[0m) as input and yield a list of clauses (i.e., [47m[term-list-listp][0m) as output. When a clause processor is run by the theorem prover its input is guaranteed to be a well-formed clause by invariants maintained by ACL2. But its output is checked by an explicit call of [47m[term-list-listp][0m unless the user has proved that the clause processor always returns a list of clauses (see [well-formedness-guarantee]) or has taken the risk of disabling the runtime test with [47m[set-skip-meta-termp-checks][0m. [47m[Term-listp][0m is mutually recursive with [47m[termp][0m. [31;1mFunction: [0m<term-listp> (defun term-listp (x w) (declare (xargs :guard (plist-worldp-with-formals w))) (cond ((atom x) (equal x nil)) ((termp (car x) w) (term-listp (cdr x) w)) (t nil)))") (term-order (term acl2-built-ins) "The ordering relation on terms used by ACL2 ACL2 must occasionally choose which of two terms is syntactically smaller. The need for such a choice arises, for example, when using equality hypotheses in conjectures (the smaller term is substituted for the larger elsewhere in the formula), in stopping loops in permutative rewrite rules (see [loop-stopper]), and in choosing the order in which to try to cancel the addends in linear arithmetic inequalities. When this notion of syntactic size is needed, ACL2 uses ``term order.'' Popularly speaking, term order is just a lexicographic ordering on terms. But the situation is actually more complicated. We define term order only with respect to terms in translated form. See [trans]. Constants are viewed as built up by [3mpseudo-function[0m applications, as described at the end of this documentation. [47mTerm1[0m comes before [47mterm2[0m in the term order iff (a) the number of variable occurrences in [47mterm1[0m is less than that in [47mterm2[0m, or (b) the numbers of variable occurrences in the two terms are equal but the number of function applications in [47mterm1[0m is less than that in [47mterm2[0m, or (c) the numbers of variable occurrences in the two terms are equal, the numbers of functions applications in the two terms are equal, but pseudo-function application count for [47mterm1[0m is less than that for [47mterm2[0m, or (d) the numbers of variable occurrences in the two terms are equal, the numbers of functions applications in the two terms are equal, the pseudo-function application counts for the two terms are equal, and [47mterm1[0m comes before [47mterm2[0m in a lexicographic ordering, [47m[lexorder][0m, based their structure as Lisp objects: see [lexorder]. The function [47mterm-order[0m, when applied to the translations of two ACL2 terms, returns [47mt[0m iff the first is ``less than or equal'' to the second in the term order. By ``number of variable occurrences'' we do not mean ``number of distinct variables'' but ``number of times a variable symbol is mentioned.'' [47m(Cons x x)[0m has two variable occurrences, not one. Thus, perhaps counterintuitively, a large term that contains only one variable occurrence, e.g., [47m(standard-char-p (car (reverse x)))[0m comes before [47m(cons x x)[0m in the term order. Since constants contain no variable occurrences and non-constant expressions must contain at least one variable occurrence, constants come before non-constants in the term order, no matter how large the constants. For example, the list constant '(monday tuesday wednesday thursday friday) comes before [47mx[0m in the term order. Because term order is involved in the control of permutative rewrite rules and used to shift smaller terms to the left, a set of permutative rules designed to allow the permutation of any two tips in a tree representing the nested application of some function will always move the constants into the left-most tips. Thus, (+ x 3 (dx i j) (car (reverse klst))) , which in translated form is (binary-+ x (binary-+ '3 (binary-+ (dx i j) (car (reverse klst))))), will be permuted under the built-in commutativity rules to (binary-+ '3 (binary-+ x (binary-+ (car (reverse klst)) (dx i j)))) or (+ 3 x (car (reverse klst)) (dx i j)). Two terms with the same numbers of variable occurrences and function applications and the same pseudo-function application count are ordered by lexicographic means, based on their structures. See [lexorder]. Thus, if two terms [47m(member ...)[0m and [47m(reverse ...)[0m contain the same numbers of variable occurrences and function applications, and no quoted constants, then the [47m[member][0m term is first in the term order because [47m[member][0m comes before [47m[reverse][0m in the term order (which is here reduced to alphabetic ordering). It remains to discuss the notion of [3mpseudo-function application count[0m. Clearly, two constants are ordered using cases (c) and (d) of term order, since they each contain 0 variable occurrences and no function calls. This raises the question ``How many function applications are in a constant?'' Because we regard the number of function applications as a more fundamental measure of the size of a constant than lexicographic considerations, we decided that for the purposes of term order, constants would be seen as being built by primitive constructor functions. These constructor functions are not actually defined in ACL2 but merely imagined for the purposes of term order. We here use suggestive names for these imagined functions, ignoring entirely the prior use of these names within ACL2. The imagined applications of these functions are what we refer to as [3mpseudo-function[0m applications. The constant function [47mz[0m constructs [47m0[0m. Positive integers are constructed from [47m(z)[0m by the successor function, [47ms[0m. Thus [47m2[0m is [47m(s (s (z)))[0m and contains three function applications. [47m100[0m contains one hundred and one applications. Negative integers are constructed from their positive counterparts by [47m[-][0m. Thus, [47m-2[0m is [47m(- (s (s (z))))[0m and has four applications. Ratios are constructed by the dyadic function [47m[/][0m. Thus, [47m-1/2[0m is (/ (- (s (z))) (s (s (z)))) and contains seven applications. Complex rationals are similarly constructed from rationals. All character objects are considered primitive and are constructed by constant functions of the same name. Thus [47m#\a[0m and [47m#\b[0m both contain one application. Strings are built from the empty string, [47m(o)[0m by the ``string-cons'' function written [47mcs[0m. Thus [47m"AB"[0m is [47m(cs (#\a) (cs (#\b) (o)))[0m and contains five applications. Symbols are obtained from strings by ``packing'' the [47m[symbol-name][0m with the unary function [47mp[0m. Thus [47m'ab[0m is (p (cs (#\a) (cs (#\b) (o)))) and has six applications. Note that packages are here ignored and thus [47m'acl2::ab[0m and [47m'my-package::ab[0m each contain just six applications. Finally, [cons]es are built with [47m[cons][0m, as usual. So [47m'(1 . 2)[0m is [47m(cons '1 '2)[0m and contains six applications, since [47m'1[0m contains two and [47m'2[0m contains three. This, for better or worse, answers the question ``How many function applications are in a constant?'' Finally, when we refer to the ``pseudo-function application count'', we mean the number of pseudo-function applications as described above, except that we bound this number by the constant [47m(fn-count-evg-max-val)[0m. (This bound is important for efficiency, so that constants that are very large [47mcons[0m structures do not cause significant slowdown as ACL2 attempts to walk through them while computing their pseudo-function application count.)") (term-table (meta) "A table used to validate meta rules Example: (table term-table t '((binary-+ x y) '3 'nil (car x))) See [table] for a general discussion of tables and the [47mtable[0m event used to manipulate tables. The ``[47mterm-table[0m'' is used at the time a meta rule is checked for syntactic correctness. Each proposed metafunction is run on each term in this table, and the result in each case is checked to make sure that it is a [47mtermp[0m in the current world. In each case where this test fails, a warning is printed. By default, when a metafunction is run in support of the application of a meta rule, the result must be a term (see [47m[termp][0m) in the current world. When the result is not a term, a hard error arises. (However, see the last paragraph below.) The [47mterm-table[0m is simply a means for providing feedback to the user at the time a meta rule is submitted, warning of the definite possibility that such a hard error will occur at some point in the future. The key used in [47mterm-table[0m is arbitrary. The top-most value is always the one that is used; it is the entire list of terms to be considered. Each must be a [47mtermp[0m in the current ACL2 world. The runtime check on the output of metafunctions can be avoided by proving that it will always succeed (see [well-formedness-guarantee]) or by telling ACL2 to skip the test at the risk of soundness (see [47m[set-skip-meta-termp-checks][0m).") (termify (term) "the process of converting a clause to a term The ACL2 prover represents its goals and subgoals as [clause]s, e.g., lists of [term]s treated as disjunctions. The individual elements of a clause are called [3mliterals[0m. For example a goal printed as [47m(IMPLIES (AND p q) r)[0m is internally represented as the 3-literal clause [47m((NOT p) (NOT q) r)[0m. A clause containing just one literal is called a [3munit clause[0m. To [3mtermify[0m a clause containing multiple literals, we convert the clause to a unit clause using [47mIF[0m to express the disjunction. For example, the 3-literal clause [47m((NOT p) (NOT q) r)[0m is propositionally equivalent to the term [47m(IF (NOT P) 'T (IF (NOT Q) 'T R))[0m. By embedding that [47mIF[0m-term in a singleton list we obtain a unit clause equivalent to the original 3-literal clause. Applying an induction scheme to a clause containing multiple literals can produce an exponential number of cases. This does not happen if the clause is a unit clause. So the ACL2 induction mechanism sometimes termifies its goal clause before applying the induction scheme to shift the case-analysis burden to the rest of the prover.") (termination-theorem (lemma-instance measure hints) "Use a (functional instance of a) previously-proved measure theorem See [lemma-instance] for a discussion of [47m:termination-theorem[0m and [47m:termination-theorem![0m lemma instances, and see [tthm] for a related user-level query utility. Also see [termination-theorem-example] for simple examples of the use of measure (termination) theorems in [hints]. For a related utility, see [make-termination-theorem].") (termination-theorem-example (lemma-instance measure hints) "How to use a previously-proved measure theorem See [lemma-instance] for a discussion of [47m:termination-theorem[0m and [47m:termination-theorem![0m lemma instances, and see [tthm] for a related user-level query utility. In this topic, we illustrate the use of such lemma instances to take advantage of a measure theorem already proved for an existing definition, when attempting to admit a new definition. We present two examples: a basic one, and then another that shows how an existing termination theorem can be automatically functionally instantiated. For a related utility, see [make-termination-theorem]. The following very simple example is contrived but should get the main idea across. Suppose that the following event was previously executed, for example when including a book, in order to define the log base 10 of [47mx[0m. (encapsulate () (local (include-book "arithmetic-5/top" :dir :system)) (defun log10 (x) ; log base 10 of x (if (or (zp x) (< x 10)) 0 (1+ (log10 (floor x 10)))))) Now suppose we want to admit the following definition, whose recursion pattern is similar to that above. The simplest way might be to include the same book as above, but perhaps that is impossible because the [formula] for some name in that book conflicts with the formula for that name in the current session. Without that book, it could be challenging to develop lemmas that allow the termination proof to succeed for this proposed definition. So we provide a hint, specifying the use of the termination theorem already proved for [47mlog10[0m, as follows. (defun base10-digits (x) (declare (xargs :hints (("Goal" :use ((:termination-theorem log10)))))) (if (or (zp x) (< x 10)) (list x) (append (base10-digits (floor x 10)) (list (mod x 10))))) With this hint, the termination proof succeeds, printing the following line in the event [summary]. Hint-events: ((:USE LOG10)) This line says that the only [47m:use[0m hint was based on the event [47mlog10[0m. This may surprise you; perhaps you would expect to see something instead such as [47m(:USE (:TERMINATION-THEOREM LOG10))[0m. However, the [47mHint-events[0m field of the summary is intended only to show the names of [events] that support the hints. For example, if you replace the [47m:use[0m hint in the example above with :use ((:rewrite car-cons) (:termination-theorem log10)) then the [47mHint-events[0m [summary] line will be as follows. Hint-events: ((:USE CAR-CONS) (:USE LOG10)) Similarly, proof output for a [47m:use[0m hint (provided when not in [gag-mode]) is also given at the level of events. For the definition above, we get the following output. We augment the goal with the hypothesis provided by the :USE hint. The hypothesis can be obtained from LOG10. We are left with the following subgoal. Again, perhaps one would expect to see ``[47mobtained from the termination theorem for LOG10[0m''. But for the modified hint shown above, using [47m(:rewrite car-cons)[0m, we similarly see only event names, not a [rune]. These hypotheses can be obtained from CAR-CONS and LOG10. Next, we consider an example where a function symbol being defined occurs in the measure theorem. (defun left (x) (car x)) (defun right (x) (car x)) (defun first-natp (x) (if (atom x) (if (natp x) x nil) (or (first-natp (left x)) (first-natp (right x))))) The measure (termination) theorem for [47mfirst-natp[0m is as follows. (AND (IMPLIES (NOT (ATOM X)) (O< (ACL2-COUNT (LEFT X)) (ACL2-COUNT X))) (IMPLIES (AND (NOT (ATOM X)) (NOT (FIRST-NATP (LEFT X)))) (O< (ACL2-COUNT (RIGHT X)) (ACL2-COUNT X)))) Now suppose the functions [47mleft[0m and [47mright[0m are [disable]d and we then try to admit the analogous definition below. This sort of situation may be common; imagine a library of books in which [47mfirst-natp[0m is defined followed by disabling of [47mleft[0m and [47mright[0m, and we have included that book in hopes of re-using the termination theorem. (in-theory (disable left right)) (defun first-symbolp (x) (if (atom x) (if (symbolp x) x nil) (or (first-symbolp (left x)) (first-symbolp (right x))))) This time the termination theorem is as follows. (AND (IMPLIES (NOT (ATOM X)) (O< (ACL2-COUNT (LEFT X)) (ACL2-COUNT X))) (IMPLIES (AND (NOT (ATOM X)) (NOT (FIRST-SYMBOLP (LEFT X)))) (O< (ACL2-COUNT (RIGHT X)) (ACL2-COUNT X)))) Notice that this theorem is not an immediate consequence of the termination theorem for [47mfirst-natp[0m, because of the call [47mfirst-symbolp[0m in the latter that replaces the call [47mfirst-natp[0m in the former. ACL2 provides support to work around this difficulty, however. When you give a [47m:termination-theorem[0m [lemma-instance] in your :hints for the termination proof, then ACL2 automatically replaces the old function symbol (here, [47mfirst-natp[0m) in the old termination theorem by the new function symbol (here, [47mfirst-symbolp[0m), before applying the hint. So the following definition is admitted, because the old termination theorem, thus modified, is exactly the new termination theorem. (defun first-symbolp (x) (declare (xargs :hints (("Goal" :by (:termination-theorem first-natp))))) (if (atom x) (if (symbolp x) x nil) (or (first-symbolp (left x)) (first-symbolp (right x))))) Such a substitution is made provided the old and new function symbols each have the same number of formal parameters. In general a [47m:termination-theorem[0m may be used for admitting either a singly-recursive function or a nest of mutually-recursive functions; the general criterion is that the number of formals must match for corresponding functions. The functional substitution can be provided explicitly. The following example has identical behavior to that above. (defun first-symbolp (x) (declare (xargs :hints (("Goal" :by (:termination-theorem first-natp ((first-natp first-symbolp))))))) (if (atom x) (if (symbolp x) x nil) (or (first-symbolp (left x)) (first-symbolp (right x))))) Finally, note that a [47m:by[0m hint is not guaranteed to work; a [47m:use[0m hint may be a bit slower, and may require the use of [47m:instance[0m (see [lemma-instance], but it can be more reliable. We conclude with a remark about what happens when the termination theorem does not exist, even though (as required) the indicated function symbol is in [logic] mode. (For example, imagine that you are generating such hints programmatically, without analyzing whether the indicated function symbol was defined using recursion.) In that case, using [47m:termination-theorem[0m will fail. Here, for example, is what happens if [47mf[0m was defined non-recursively. ACL2 !>(defun g (x) (declare (xargs :hints (("Goal" :use ((:termination-theorem f)))))) (if (consp x) (g (cddr x)) x)) ACL2 Error in ( DEFUN G ...): The object (:TERMINATION-THEOREM F) is an ill-formed lemma instance because there is no termination theorem for F. The function F is not recursive. See :DOC lemma-instance. Summary Form: ( DEFUN G ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Error in ( DEFUN G ...): See :DOC failure. ******** FAILED ******** ACL2 !> The alternative, [47m:termination-theorem![0m, is provided in order to avoid this sort of error. Here is the corresponding (edited) log, with [gag-mode] off. Notice that since there is no termination theorem stored for [47mf[0m, the [47m:use[0m hint specifies the use of [47mT[0m for the termination theorem. ACL2 !>(defun g (x) (declare (xargs :hints (("Goal" :use ((:termination-theorem! f)))))) (if (consp x) (g (cddr x)) x)) For the admission of G we will use the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). The non-trivial part of the measure conjecture is Goal (IMPLIES (CONSP X) (O< (ACL2-COUNT (CDDR X)) (ACL2-COUNT X))). [Note: A hint was supplied for the goal above. Thanks!] We augment the goal with the hypothesis provided by the :USE hint. The hypothesis can be obtained from F. We are left with the following subgoal. Goal' (IMPLIES T (OR (NOT (CONSP X)) (O< (ACL2-COUNT (CDDR X)) (ACL2-COUNT X)))). By case analysis we reduce the conjecture to [[.. output elided ..]] Hint-events: ((:USE F)) Time: 0.02 seconds (prove: 0.01, print: 0.01, other: 0.00) Prover steps counted: 1121 G ACL2 !>") (termp (term acl2-built-ins) "recognizer for the quotation of a [term] Example: (termp '(CAR (CONS X Y)) (w state)) General Form: (termp x w) where [47mx[0m is any ACL2 object and [47mw[0m is an ACL2 logical [world]. The result is [47mt[0m or [47mnil[0m according to whether [47mx[0m is the quotation of a translated (well-formed) term in the [world], [47mw[0m. See [term] for a discussion of translated terms. Each metafunction (see [47m[meta][0m) is supposed to take (the quotation of) a translated term as input and yield (the quotation of) a translated term as output. When a metafunction is run by the simplifier its input is guaranteed to be well-formed by invariants maintained by ACL2. But its output is checked by an explicit call of [47mtermp[0m unless the user has proved that the metafunction always returns a term (see [well-formedness-guarantee]) or has taken the risk of disabling the runtime test with [47m[set-skip-meta-termp-checks][0m. [47m[Termp][0m is mutually recursive with [47m[term-listp][0m. [31;1mFunction: [0m<termp> (defun termp (x w) (declare (xargs :guard (plist-worldp-with-formals w))) (cond ((atom x) (legal-variablep x)) ((eq (car x) 'quote) (and (consp (cdr x)) (null (cddr x)))) ((symbolp (car x)) (let ((arity (arity (car x) w))) (and arity (term-listp (cdr x) w) (eql (length (cdr x)) arity)))) ((and (consp (car x)) (true-listp (car x)) (eq (car (car x)) 'lambda) (eql 3 (length (car x))) (arglistp (cadr (car x))) (termp (caddr (car x)) w) (null (set-difference-eq (all-vars (caddr (car x))) (cadr (car x)))) (term-listp (cdr x) w) (eql (length (cadr (car x))) (length (cdr x)))) t) (t nil))) [31;1mFunction: [0m<term-listp> (defun term-listp (x w) (declare (xargs :guard (plist-worldp-with-formals w))) (cond ((atom x) (equal x nil)) ((termp (car x) w) (term-listp (cdr x) w)) (t nil))) Subtopics [Logic-fns-list-listp] Recognizer for when a given list of lists of [term]s calls only [47m:[0m[47m[logic][0m-mode function symbols [Logic-fns-listp] Recognizer for when a given list of [term]s calls only [47m:[0m[47m[logic][0m-mode function symbols [Logic-fnsp] Recognizer for when a given [term] calls only [47m:[0m[47m[logic][0m-mode function symbols [Logic-term-list-listp] Recognizer for lists of lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols [Logic-term-listp] Recognizer for lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols [Logic-termp] Recognizer for [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols") (the (guard compilation acl2-built-ins) "Special form for execution efficiency or run-time type checks [47mTHE[0m is a Common Lisp special form. It is usually used as a way to boost performance by telling the Common Lisp compiler that a certain expression will always produce a result of a certain type. This information may allow the Common Lisp compiler to avoid certain run-time checks. When evaluating code directly in the top-level loop or in [47m:[0m[47m[logic][0m-mode functions that have not been [guard]-verified, [47mTHE[0m can perform run-time type checks. See [declare] and [type-spec] for general, related background. General form: (the <typ> <val>) ;; returns <val>, or causes a run-time error * [47m<typ>[0m is a [type-spec] * [47m<val>[0m is some expression that should produce a value of that type. Typical example: (defun merge-bytes (b1 b2) ;; Combine two 8-bit bytes into a 16-bit result. (declare (type (unsigned-byte-p 8) b1 b2)) (the (unsigned-byte 16) (logior (the (unsigned-byte 16) (ash b1 8)) b2))) On most Lisp implementations 16-bit numbers are fixnums. The [47mTHE[0m forms above are promises to the Lisp compiler that these [47mash[0m and [47mlogior[0m operations will always produce 16-bit numbers. Ideally, the compiler could use this information to generate more efficient code, i.e., by omitting whatever code is normally required to handle bignum results. (Of course, a sufficiently smart compiler could have figured this out on its own; in practice Lisp compilers vary in their reasoning abilities.) Relation to Guards To justify that type declarations are correct, [47mTHE[0m is integrated into ACL2's [guard] mechanism. A call of [47m(the TYPE EXPR)[0m in the body of a function definition generates a guard proof obligation that the type, [47mTYPE[0m, holds for the value of the expression, [47mEXPR[0m. Consider the following example. (defun f (x) (declare (xargs :guard (p1 x))) (if (p2 x) (the integer (h x)) 17)) The [guard] proof obligation generated for the [47mTHE[0m expression above is as follows. (implies (and (p1 x) (p2 x)) (let ((var (h x))) (integerp var))) For [47mTHE[0m to provide any execution speed benefit, [guard]s must be verified (see [VERIFY-GUARDS]). In contexts where guards have [3mnot[0m been verified, [47mTHE[0m acts as a low-level, run-time type check that [47mval[0m satisfies the type specification [47mtyp[0m (see [type-spec]). An error is caused if the check fails; otherwise, [47mval[0m is returned. Here are some examples: (the integer 3) ; returns 3 (the (integer 0 6) 3) ; returns 3 (the (integer 0 6) 7) ; causes an error (see below for exception) There is an exception to the rule that failure of the type-check causes an error: there is no error when [guard]-checking has been turned off, that is, in any of the following ways; also [set-guard-checking] and see [with-guard-checking]. * [47m:set-guard-checking nil[0m * [47m(with-guard-checking nil ...)[0m * [47m:set-guard-checking :none[0m * [47m(with-guard-checking :none ...)[0m Further resources The [b*] macro provides a special syntax that may make using [47mTHE[0m forms more pleasant; see [patbind-the] for more information. When optimizing functions with type declarations, you may wish to manually inspect the compiler's output with [disassemble$] or conduct experiments to measure the impact of your optimizations. A term of the form [47m(the double-float <term>)[0m will assist ACL2's syntax checking by telling ACL2 that [47m<term>[0m returns a df. See [df] for relevant background. [47mTHE[0m is defined in Common Lisp. See any Common Lisp documentation for more information. Subtopics [Type-spec] Type specifiers can be used in Common Lisp type declarations and [the] forms, and may result in improved efficiency of execution.") (the-method (acl2-tutorial) "How to find proofs Also see [introduction-to-the-theorem-prover] for a more detailed tutorial on how to prove theorems with ACL2. Many users develop proof scripts in an Emacs buffer and submit one event at a time to the theorem prover running in a [47m*shell*[0m buffer. The script buffer is logically divided into two regions: the events that have been accepted by the theorem prover and those that have not yet been accepted. An imaginary ``barrier'' divides these two regions. The region above the barrier describes the state of the [47m*shell*[0m buffer (and ACL2's logical world). The region below the barrier is the ``to do'' list. We usually start a proof project by typing the key lemmas, and main goal into the to do list. Definitions are here just regarded as theorems to prove (i.e., the measure conjectures). Then we follow ``The Method.'' (1) Think about the proof of the first theorem in the to do list. Structure the proof either as an induction followed by simplification or just simplification. Have the necessary lemmas been proved? That is, are the necessary lemmas in the done list already? If so, proceed to Step 2. Otherwise, add the necessary lemmas at the front of the to do list and repeat Step 1. (2) Call the theorem prover on the first theorem in the to do list and let the output stream into the *shell* buffer. Abort the proof if it runs more than a few seconds. (3) If the theorem prover succeeded, advance the barrier past the successful command and go to Step 1. (4) Otherwise, inspect the failed proof attempt, starting from the beginning, not the end. Basically you should look for the first place the proof attempt deviates from your imagined proof. If your imagined proof was inductive, inspect the induction scheme used by ACL2. If that is ok, then find the first subsequent subgoal that is stable under simplification and think about why it was not proved by the simplifier. If your imagined proof was not inductive, then think about the first subgoal stable under simplification, as above. Modify the script appropriately. It usually means adding lemmas to the to do list, just in front of the theorem just tried. It could mean adding hints to the current theorem. In any case, after the modifications go to Step 1. We do not seriously suggest that this or any rotely applied algorithm will let you drive ACL2 to difficult proofs. Indeed, to remind you of this we call this ``The Method'' rather than ``the method.'' That is, we are aware of the somewhat pretentious nature of any such advice. But these remarks have helped many users approach ACL2 in a constructive and disciplined way. We say much more about The Method in the ACL2 book. See the home page. Also see [set-gag-mode] for a discussion of a way for ACL2 to help you to use The Method. And again, see [introduction-to-the-theorem-prover] for a more detailed tutorial. Learning to read failed proofs is a useful skill. There are several kinds of ``checkpoints'' in a proof: (1) a formula to which induction is being (or would be) applied, (2) the first formula stable under simplification, (3) a formula that is possibly generalized, either by cross-fertilizing with and throwing away an equivalence hypothesis or by explicit generalization of a term with a new variable. At the induction checkpoint, confirm that you believe the formula being proved is a theorem and that it is appropriately strong for an inductive proof. Read the selected induction scheme and make sure it agrees with your idea of how the proof should go. At the post-simplification checkpoint, which is probably the most commonly seen, consider whether there are additional rewrite rules you could prove to make the formula simplify still further. Look for compositions of function symbols you could rewrite. Look for contradictions among hypotheses and prove the appropriate implications: for example, the checkpoint might contain the two hypotheses [47m(P (F A))[0m and [47m(NOT (Q (G (F A))))[0m and you might realize that [47m(implies (p x) (q (g x)))[0m is a theorem. Look for signs that your existing rules did not apply, e.g., for terms that should have been rewritten, and figure out why they were not. Possible causes include that they do not exactly match your old rules, that your old rules have hypotheses that cannot be relieved here --- perhaps because some other rules are missing, or perhaps your old rules are disabled. If you cannot find any further simplifications to make in the formula, ask yourself whether it is valid. If so, sketch a proof. Perhaps the proof is by appeal to a combination of lemmas you should now prove? At the two generalization checkpoints --- where hypotheses are discarded or terms are replaced by variables --- ask yourself whether the result is a theorem. It often is not. Think about rewrite rules that would prove the formula. These are often restricted versions of the overly-general formulas created by the system's heuristics. See [proof-tree] for a discussion of a tool to help you navigate through ACL2 proofs.") (the-number (numbers acl2-built-ins) "Coerce an expected number to a number Like [47m[fix][0m, [47mthe-number[0m logically returns its argument unchanged if that argument is numeric and [47m0[0m otherwise. Unlike [47mfix[0m, the [guard] for [47m(the-number x)[0m is [47m(acl2-numberp x)[0m, and [47m(the-number x)[0m evaluates to [47mx[0m in raw Lisp (see [guards-and-evaluation] for relevant discussion). [31;1mFunction: [0m<the-number> (defun the-number (x) (declare (xargs :guard (acl2-numberp x))) (mbe :logic (fix x) :exec x))") (the-true-list (true-listp acl2-built-ins) "Coerce an expected true list to a true list Like [47m[true-list-fix][0m, [47mthe-true-list[0m logically returns its argument unchanged if that argument satisfies [47m[true-listp][0m and otherwise returns a corresponding ``fixed'' true list. Unlike [47mtrue-list-fix[0m, the [guard] for [47m(the-true-list x)[0m is [47m(true-listp x)[0m, and [47m(the-true-list x)[0m evaluates immediately to [47mx[0m in raw Lisp (see [guards-and-evaluation] for relevant discussion). [31;1mFunction: [0m<the-true-list> (defun the-true-list (x) (declare (xargs :guard (true-listp x))) (mbe :logic (true-list-fix x) :exec x))") (theories (acl2) "Sets of [rune]s to [enable]/[disable] in concert Example: '((:definition app) ; or (:d app) (:executable-counterpart app) (:i app) rv (rv) (:r assoc-of-app)) See: A theory is a list of ``runic designators'' as described below. Each runic designator denotes a set of ``runes'' (see [rune]) and by unioning together the runes denoted by each member of a theory we define the set of runes corresponding to a theory. Theories are used to control which rules are ``[enable]d,'' i.e., available for automatic application by the theorem prover. There is always a ``current'' theory. A rule is [enable]d precisely if its [rune] is an element of the set of [rune]s corresponding to the current theory. At the top-level, the current theory is the theory selected by the most recent [47m[in-theory][0m event, extended with the rule names introduced since then. Inside the theorem prover, the [47m:[0m[47m[in-theory][0m hint (see [hints]) can be used to select a particular theory as current during the proof attempt for a particular goal. Theories are generally constructed by ``theory expressions.'' Formally, a theory expression is any term, containing at most the single free variable [47m[world][0m, that when evaluated with [47m[world][0m bound to the current ACL2 world (see [world]) produces a theory. ACL2 provides various functions for the convenient construction and manipulation of theories. These are called ``theory functions'' (see [theory-functions]). For example, the theory function [47m[union-theories][0m takes two theories and produces their union. The theory function [47m[universal-theory][0m returns the theory containing all known rule names as of the introduction of a given logical name. But a theory expression can contain constants, e.g., '(len (len) (:rewrite car-cons) car-cdr-elim) and user-defined functions. The only important criterion is that a theory expression mention no variable freely except [47m[world][0m and evaluate to a theory. More often than not, theory expressions typed by the user do not mention the variable [47m[world][0m. This is because user-typed theory expressions are generally composed of applications of ACL2's theory functions. These ``functions'' are actually macros that expand into terms in which [47m[world][0m is used freely and appropriately. Thus, the technical definition of ``theory expression'' should not mislead you into thinking that interesting theory expressions must mention [47m[world][0m; they probably do and you just didn't know it! One aspect of this arrangement is that theory expressions cannot generally be evaluated at the top-level of ACL2, because [47m[world][0m is not bound. To see the value of a theory expression, [47mexpr[0m, at the top-level, type ACL2 !>(LET ((WORLD (W STATE))) expr). However, because the built-in theories are quite long, you may be sorry you printed the value of a theory expression! A theory is a true list of runic designators and to each theory there corresponds a set of [rune]s, obtained by unioning together the sets of [rune]s denoted by each runic designator. For example, the theory constant '(len (len) (:e nth) (:rewrite car-cons) car-cdr-elim) corresponds to the set of [rune]s {(:definition len) (:induction len) (:executable-counterpart len) (:executable-counterpart nth) (:rewrite car-cons) (:elim car-cdr-elim)} . Observe that the theory contains five elements but its runic correspondent contains six. That is because runic designators can denote sets of several [rune]s, as is the case for the first designator, [47mlen[0m. If the above theory were selected as current then the six rules named in its runic counterpart would be [enable]d and all other rules would be [disable]d. We now precisely define the runic designators and the set of [rune]s denoted by each. When we refer below to the ``macro-aliases dereference of'' a symbol, [47msymb[0m, we mean the (function) symbol corresponding to [47msymb[0m in the macro-aliases-table if there is such a symbol, else [47msymb[0m itself; see [macro-aliases-table]. For example, the macro-aliases dereference of [47m[append][0m is [47m[binary-append][0m, and the macro-aliases dereference of [47m[nth][0m is [47mnth[0m. * A [rune] is a runic designator and denotes the singleton set containing that rune. * Suppose that [47msymb[0m is a symbol and [47msymb'[0m is the macro-aliases dereference of [47msymb[0m, where [47msymb'[0m is a function symbol introduced with a [47m[defun][0m (or [47m[defuns][0m) event. Then [47msymb[0m is a runic designator and denotes the set containing the runes [47m(:definition symb')[0m and [47m(:induction symb')[0m, omitting the latter if no such [induction] rune exists (presumably because the definition of [47msymb'[0m is not singly recursive). * Suppose that [47msymb[0m is a symbol and [47msymb'[0m is the macro-aliases dereference of [47msymb[0m, where [47msymb'[0m is a function symbol introduced with a [47m[defun][0m (or [47m[defuns][0m) event. Then [47m(symb)[0m is a runic designator and denotes the singleton set containing the rune [47m(:executable-counterpart symb')[0m. * If [47msymb[0m is the name of a [47m[defthm][0m (or [47m[defaxiom][0m) event that introduced at least one rule, then [47msymb[0m is a runic designator and denotes the set of the names of all rules introduced by the named event. * If [47mstr[0m is the string naming some [47m[defpkg][0m event and [47msymb[0m is the symbol returned by [47m(intern (concatenate 'string str "-PACKAGE") "ACL2")[0m, then [47msymb[0m is a runic designator and denotes the singleton set containing [47m(:rewrite symb)[0m, which is the name of the rule stating the conditions under which the [47m[symbol-package-name][0m of [47m(intern x str)[0m is [47mstr[0m. * If [47msymb[0m is the name of a [47m[deftheory][0m event, then [47msymb[0m is a runic designator and denotes the runic theory (as defined below) corresponding to [47msymb[0m. * Finally, suppose that [47msymb[0m is a symbol and [47msymb'[0m is the macro-aliases dereference of [47msymb[0m. Then [47m(:KWD symb . rest)[0m is a runic designator, known as a ``runic abbreviation'', if [47m(:KWD' symb' . rest)[0m is a [rune], where: [47m:KWD[0m is one of [47m:d[0m, [47m:e[0m, [47m:i[0m, [47m:r[0m, or [47m:t[0m; and [47m:KWD'[0m is [47m:definition[0m, [47m:executable-counterpart[0m, [47m:induction[0m, [47m:rewrite[0m, or [47m:type-prescription[0m, respectively. In this case, [47m(:KWD symb . rest)[0m denotes the runic theory (as defined below) corresponding to the rune [47m(:KWD' symb' . rest)[0m. Note that including a function name, e.g., [47m[len][0m, in the current theory [enable]s that function but does not [enable] the [executable-counterpart]. Similarly, including [47m(len)[0m or [47m(:e len)[0m [enable]s the executable-counterpart but not the symbolic definition. And including the name of a proved lemma [enable]s all of the rules added by the event. Of course, one can include explicitly the [rune]s naming the rules in question and so can avoid entirely the use of non-runic elements in theories. Because a [rune] is a runic designator denoting the set containing that [rune], a list of [rune]s is a theory and denotes itself. There is a natural ``canonical'' ordering of runes by order of their creation. We call a canonically ordered true list of runes a ``runic theory.'' To every theory there corresponds a runic theory, sometimes called its runic correspondent, obtained by unioning together the sets denoted by each designator in the theory. When a theory is selected as ``current'' it is actually its runic correspondent that is effectively used. That is, a [rune] is [enable]d iff it is a member of the runic correspondent of the current theory. The value of a theory defined with [47m[deftheory][0m is the runic correspondent of the theory computed by the defining theory expression. The theory manipulation functions, e.g., [47m[union-theories][0m, actually convert their theory arguments to their runic correspondents before performing the required set operation. The manipulation functions always return runic theories. Thus, it is sometimes convenient to think of (non-runic) theories as merely abbreviations for their runic correspondents, abbreviations which are ``expanded'' at the first opportunity by theory manipulation functions and the ``theory consumer'' functions such as [47m[in-theory][0m and [47m[deftheory][0m. Subtopics [Active-or-non-runep] Require a [rune] to exist, and check that it is [enable]d [Active-runep] Check that a [rune] exists and is [enable]d [Current-theory] Currently [enable]d rules as of logical name [Deftheory] Define a theory (to [enable] or [disable] a set of rules) [Deftheory-static] Define a `static' theory (to [enable] or [disable] a set of rules) [Defthy] Define a theory (to [enable] or [disable] a set of rules) [Disable] Deletes names from current theory [Disabledp] Determine whether a given name or rune is disabled [E/d] Enable/disable rules [Enable] Adds names to current theory [Executable-counterpart-theory] [Executable-counterpart] rules as of logical name [Function-theory] Function symbol rules as of logical name [Ground-zero] [enable]d rules in the [startup] theory [Hands-off-lambda-objects-theory] how to specify no modification of lambda objects [In-theory] Designate ``current'' theory (enabling its rules) [Incompatible] Declaring that two rules should not both be [enable]d [Incompatible!] Declaring that two rules must exist and should not both be [enable]d [Intersection-theories] Intersect two [theories] [Minimal-theory] A minimal theory to enable [Rewrite-lambda-objects-theory] how to specify rewriting of lambda objects [Rule-names] How rules are named. [Rune] A rule name [Set-difference-theories] Difference of two [theories] [Syntactically-clean-lambda-objects-theory] how to specify syntactic cleaning of lambda objects [Theories-and-primitives] Warnings from disabling or enabling certain built-in functions [Theory] Retrieve named theory [Theory-functions] Functions for obtaining or producing [theories] [Union-theories] Union two [theories] [Universal-theory] All rules as of logical name [Using-enabled-rules] Avoiding [47m:use[0m [hints] for [enable]d [47m:[0m[47m[rewrite][0m rules") (theories-and-primitives (theories) "Warnings from disabling or enabling certain built-in functions When you [disable] the [definition] or [executable-counterpart] of a built-in function, you may see a warning, for example as follows. ACL2 !>(in-theory (disable mv-nth iff length)) ACL2 Warning [Theory] in ( IN-THEORY (DISABLE ...)): The :DEFINITION rules for the built-in functions MV-NTH and IFF are disabled by the theory expression (DISABLE MV-NTH IFF LENGTH), but some expansions of their calls may still occur. See :DOC theories-and-primitives. This warning is telling us that the built-in functions [47m[mv-nth][0m and [47m[iff][0m are given certain special handling, hence their calls may be expanded even when their definitions are disabled. This behavior applies to the functions in the list obtained by evaluating the constant, [47m*definition-minimal-theory*[0m. These warnings can be eliminated by turning off all theory warnings (see [set-inhibit-warnings]) or even turning off all warnings (see [set-inhibit-output-lst]), or simply by evaluating the following form. (assign verbose-theory-warning nil) But before you eliminate such theory warnings, you may wish to read the following to gain more understanding of their significance. First consider the following example, evaluated after the [47m[in-theory][0m event displayed above. ACL2 !>(thm (equal (mv-nth 2 (list a b c d e)) c)) Q.E.D. Summary Form: ( THM ...) Rules: ((:DEFINITION MV-NTH) (:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Prover steps counted: 18 Proof succeeded. ACL2 !> Note that even though the [definition] of [47m[mv-nth][0m had been [disable]d, nevertheless its definition rule was used in proving this theorem. It is as though [47m[mv-nth][0m had not been disabled after all! The warning is intended to indicate that expansion of [47mmv-nth[0m calls may be made by the theorem prover even when [47mmv-nth[0m is disabled. Indeed, the prover has special-purpose code for simplifying certain [47mmv-nth[0m calls. A similar issue can arise for [47mexecutable-counterpart[0m rules, as the following log illustrates. ACL2 !>(in-theory (disable (:e symbolp))) ACL2 Warning [Theory] in ( IN-THEORY (DISABLE ...)): The :EXECUTABLE- COUNTERPART rule for the built-in function SYMBOLP is disabled by the theory expression (DISABLE (:E SYMBOLP)), but some evaluations of its calls may still occur. See :DOC theories-and-primitives. Summary Form: ( IN-THEORY (DISABLE ...)) Rules: NIL Warnings: Theory Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) (:NUMBER-OF-ENABLED-RUNES 4268) ACL2 !>(thm (symbolp 'a)) Q.E.D. Summary Form: ( THM ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Proof succeeded. ACL2 !> In general, ACL2 warns when [47m[in-theory][0m [events] or [hints] leave you in a theory where rules for certain built-in functions have just been disabled, yet these rules may be applied in some cases nonetheless, because of special-purpose prover code for handling calls of that function. The built-in function symbols with such [definition] rules or [executable-counterpart] rules are those in the following two lists, which are the respective values of built-in constants [47m*definition-minimal-theory*[0m and [47m*built-in-executable-counterparts*[0m. [31;1mDefinition: [0m<*definition-minimal-theory*> (defconst *definition-minimal-theory* (list* 'mv-nth 'iff *expandable-boot-strap-non-rec-fns*)) [31;1mDefinition: [0m<*built-in-executable-counterparts*> (defconst *built-in-executable-counterparts* '(acl2-numberp binary-* binary-+ unary-- unary-/ < car cdr char-code characterp code-char complex complex-rationalp coerce cons consp denominator equal if imagpart integerp intern-in-package-of-symbol numerator pkg-witness pkg-imports rationalp realpart stringp symbol-name symbol-package-name symbolp not)) A third class of warnings pertains to [primitive]s that do not have definitions, such as [47mcons[0m. Here is an example of such a warning, for the event [47m(in-theory (disable cons))[0m. ACL2 Warning [Theory] in ( IN-THEORY (DISABLE ...)): There is no effect from disabling or enabling :DEFINITION rules for primitive functions (see :DOC primitive). For the expression (DISABLE CONS), the attempt to disable CONS will therefore have no effect for its definition. See :DOC theories-and-primitives. Unlike the warnings discussed above, warnings about primitives can occur not only when disabling definitions but also when enabling them. Here is what happens when we submit [47m(in-theory (enable cons))[0m immediately after the event just above. ACL2 Warning [Theory] in ( IN-THEORY (ENABLE ...)): There is no effect from disabling or enabling :DEFINITION rules for primitive functions (see :DOC primitive). For the expression (ENABLE CONS), the attempt to enable CONS will therefore have no effect for its definition. See :DOC theories-and-primitives. If however we submit [47m(in-theory (enable cons))[0m again, or in a fresh session, there is no warning. To see why, understand that all of these warnings are based on a comparison of the preceding current [theory] with the new one. If [47mcons[0m is already enabled, then [47m(in-theory (enable cons))[0m is a no-op; hence, there is no warning. There is another case in which there is no warning: if all definitions of primitives transition from disabled to enabled, or vice-versa. For example, such a transition occurs for consecutive events [47m(in-theory (current-theory 'ground-zero))[0m and [47m(in-theory (theory 'minimal-theory))[0m. We conclude with a note for advanced users only. You can eliminate all special treatment discussed above for expanding the definition of [47m[mv-nth][0m (but not for any of the other primitives listed above) by evaluating the following form (also see [defattach-system]). (defattach-system simplifiable-mv-nth-p constant-nil-function-arity-0) That said, this is probably only useful for very specific cases of ``system-level'' programming. You can restore the default behavior as follows. (defattach-system simplifiable-mv-nth-p constant-t-function-arity-0)") (theory (theories theory-functions) "Retrieve named theory Examples: [3mFor use in [47m[in-theory][0m[3m [events] or [47m:in-theory[0m[3m [hints]:[0m [47m(theory 'ground-zero)[0m [3mFor direct evaluation at the top-level loop:[0m [47m(let ((world (w state))) (theory 'ground-zero))[0m In the examples above, the theory returned is the one in force when ACL2 is started up (see [ground-zero]). General Form: (theory name) where [47mname[0m is the name of a previously executed [47m[deftheory][0m event (otherwise a hard error occurs). Returns the named theory. See [theories]. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (theory-functions (theories) "Functions for obtaining or producing [theories] Example Calls of Theory Functions: (universal-theory :here) (union-theories th1 th2) (set-difference-theories th1 th2) The theory functions are documented individually: The functions (actually, macros) mentioned above are convenient ways to produce [theories]. (See [theories].) Some, like [47m[universal-theory][0m, take a logical name (see [logical-name]) as an argument and return the relevant theory as of the time that name was introduced. Others, like [47m[union-theories][0m, take two [theories] and produce a new one. See [redundant-events] for a caution about the use of logical names in theory expressions. Theory expressions are generally composed of applications of theory functions. Formally, theory expressions are expressions that involve, at most, the free variable [47m[world][0m and that when evaluated with [47m[world][0m bound to the current ACL2 world (see [world]) return [theories]. The ``theory functions'' are actually macros that expand into forms that involve the free variable [47m[world][0m. Thus, for example [47m(universal-theory :here)[0m actually expands to [47m(universal-theory-fn :here world)[0m and when that form is evaluated with [47m[world][0m bound to the current ACL2 [world], [47muniversal-theory-fn[0m scans the ACL2 property lists and computes the current universal theory. Because the theory functions all implicitly use [47m[world][0m, the variable does not generally appear in anything the user types. Subtopics [Current-theory] Currently [enable]d rules as of logical name [Disable] Deletes names from current theory [E/d] Enable/disable rules [Enable] Adds names to current theory [Executable-counterpart-theory] [Executable-counterpart] rules as of logical name [Function-theory] Function symbol rules as of logical name [Ground-zero] [enable]d rules in the [startup] theory [Hands-off-lambda-objects-theory] how to specify no modification of lambda objects [Intersection-theories] Intersect two [theories] [Minimal-theory] A minimal theory to enable [Rewrite-lambda-objects-theory] how to specify rewriting of lambda objects [Set-difference-theories] Difference of two [theories] [Syntactically-clean-lambda-objects-theory] how to specify syntactic cleaning of lambda objects [Theory] Retrieve named theory [Union-theories] Union two [theories] [Universal-theory] All rules as of logical name") (theory-invariant (events) "User-specified invariants on [theories] Examples: (theory-invariant (not (and (active-runep '(:rewrite left-to-right)) (active-runep '(:rewrite right-to-left)))) :key my-invariant :error nil) ; Equivalent to the above: (theory-invariant (incompatible (:rewrite left-to-right) (:rewrite right-to-left)) :key my-invariant :error nil) ; As above, but cause an error for non-runes: (theory-invariant (incompatible! (:rewrite left-to-right) (:rewrite right-to-left)) :key my-invariant :error nil) General Form: (theory-invariant term &key key error) where: * [47mterm[0m is a term that uses no variables other than [47mens[0m and [47m[state][0m; * [47mkey[0m is an arbitrary ``name'' for this invariant (if omitted, an integer is generated and used); and * [47m:error[0m specifies the action to be taken when an invariant is violated --- either [47mnil[0m if a warning is to be printed, else [47mt[0m (the default) if an error is to be caused. [47mTheory-invariant[0m is an event that adds to or modifies the [table] of user-supplied theory invariants that are checked each time a theory expression is evaluated. The theory invariant mechanism is provided via a table (see [table]) named [47mtheory-invariant-table[0m. In fact, the [47mtheory-invariant[0m ``event'' is just a macro that expands into a use of the [47m[table][0m event. More general access to the [47mtheory-invariant[0m [table] is provided by [47m[table][0m itself. For example, the [table] can be inspected or cleared with [47m[table][0m; you can clear an individual theory invariant by setting the invariant to [47mt[0m, or eliminate all theory invariants with the command [47m(table theory-invariant-table nil nil :clear)[0m. [47mTheory-invariant-table[0m maps arbitrary keys to records containing terms that mention, at most, the variables [47mens[0m and [47m[state][0m. Every time an alleged theory expression is evaluated, e.g., in the [47m[in-theory][0m event or [47m:[0m[47m[in-theory][0m hint, each of the terms in [47mtheory-invariant-table[0m is evaluated with [47mens[0m bound to a so-called ``enabled structure'' obtained from the theory expression and [47m[state][0m bound to the current ACL2 state (see [state]). Users generally need not know about the enabled structure, other than that it can be accessed using the macros [47mactive-runep[0m and [47mincompatible[0m; see [active-runep] and see [incompatible]. (Also see variants [active-or-non-runep] and [incompatible!], whose use by the theory-invariant mechanism will cause an error any time either ``rune'' is not truly a rune.) If the result is [47mnil[0m, a message is printed and an error occurs (except, only a warning occurs if [47m:error nil[0m is specified). Thus, the [table] can be thought of as a list of conjuncts. Each [47mterm[0m in the [table] has a ``name,'' which is just the key under which the term is stored. When a theory violates the restrictions specified by some term, both the name and the term are printed. By calling [47mtheory-invariant[0m with a new term but the same name, you can overwrite that conjunct of the theory invariant; but see the Local Redefinition Caveat at the end of this note. You may want to avoid using explicit names, since otherwise the subsequent inclusion of another book that defines a theory invariant with the same name will override your theory invariant. Theory invariants are particularly useful in the context of large rule sets intended for re-use. Such sets often contain conflicting rules, e.g., rules that are to be [enable]d when certain function symbols are [disable]d, rules that rewrite in opposite directions and thus loop if simultaneously [enable]d, groups of rules which should be [enable]d in concert, etc. The developer of such rule sets understands these restrictions and probably documents them. The theory invariant mechanism allows the developer to codify his restrictions so that the user is alerted when they are violated. Since theory invariants are arbitrary terms, macros may be used to express commonly used restrictions. For example, executing the event (theory-invariant (incompatible (:rewrite left-to-right) (:rewrite right-to-left))) would subsequently cause an error any time the current theory contained both of the two [rune]s shown. Of course, [incompatible] is just defined as a macro. Its definition may be inspected with [47m:pe incompatible[0m. In order for a [47mtheory-invariant[0m event to be accepted, the proposed theory invariant must be satisfied by the current theory (see [current-theory]). The value returned upon successful execution of the event is the key (whether user-supplied or generated). Local Redefinition Caveat. Care needs to be taken when redefining a theory invariant in a [local] context. Consider the following example. (theory-invariant (active-runep '(:definition binary-append)) :key app-inv) (encapsulate () (local (theory-invariant t :key app-inv)) (in-theory (disable binary-append)) (defthm ...)) The second pass of the [47m[encapsulate][0m will fail, because the [47m[in-theory][0m event violates the original [47mtheory-invariant[0m and the [47m[local][0m [47mtheory-invariant[0m is skipped in the second pass of the [47m[encapsulate][0m. Of course, [47m[local][0m [47m[theory-invariant][0ms in [books] can cause the analogous problem in the second ([47m[include-book][0m) pass of a [47m[certify-book][0m. In both cases, though, the theory invariants are only checked at the conclusion of the ([47minclude-book[0m or [47mencapsulate[0m) event. Indeed, theory invariants are checked at the end of every event related to [theories], including [47m[defun][0m, [47m[defthm][0m, [47m[in-theory][0m, [47m[encapsulate][0m, and [47m[include-book][0m, except for events executed on behalf of an [47m[include-book][0m or the second pass of an [47m[encapsulate][0m.") (thereis$ (pointers) "See [loop$].") (thereis$+ (pointers) "See [loop$].") (the_admission_of_app (pages_written_especially_for_the_tours) "The Admission of App {IMAGE} (see [Revisiting_the_Admission_of_App]) Here is what it looks like to submit the definition of [47mapp[0m to ACL2: {IMAGE} ACL2 !>[31;1m(defun app (x y)[0m [31;1m(cond ((endp x) y)[0m [31;1m(t (cons (car x) [0m [31;1m(app (cdr x) y)))))[0m The admission of APP is trivial, using the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT X). We observe that the type of APP is described by the theorem (OR (CONSP (APP X Y)) (EQUAL (APP X Y) Y)). We used primitive type reasoning. Summary Form: ( DEFUN APP ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) APP {IMAGE} The text between the lines above is one interaction with the ACL2 command loop. Interacting with the latest version of ACL2 may not produce the very same output, but we trust you'll recognize the basics. Above you see the user's [31;1minput[0m and how the system responds. This little example shows you what the syntax looks like and is a very typical [31;1msuccessful[0m interaction with the definitional principle. Let's look at it a little more closely. {IMAGE} (see [Revisiting_the_Admission_of_App])") (the_associativity_of_app (pages_written_especially_for_the_tours) "The Associativity of App {IMAGE} (see [The_Theorem_that_App_is_Associative]) {IMAGE} ACL2!>[31;1m(let ((a '(1 2))[0m [31;1m(b '(3 4))[0m [31;1m(c '(5 6)))[0m [31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c))))[0m T {IMAGE} Observe that, for the particular [47ma[0m, [47mb[0m, and [47mc[0m above, [47m(app (app a b) c)[0m returns the same thing as [47m(app a (app b c))[0m. Perhaps [47mapp[0m is [31;1massociative[0m. Of course, to be associative means that the above property must hold for all values of [47ma[0m, [47mb[0m, and [47mc[0m, not just the ones [31;1mtested[0m above. Wouldn't it be cool if you could type ACL2!>[31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c)))[0m and have ACL2 compute the value [47mT[0m? Well, [31;1myou can't![0m If you try it, you'll get an error message! The message says we can't evaluate that form because it contains [31;1mfree[0m variables, i.e., variables not given values. Click here (see [Free_Variables_in_Top-Level_Input]) to see the message. We cannot evaluate a form on an infinite number of cases. But we can prove that a form is a theorem and hence know that it will always evaluate to true. {IMAGE} (see [The_Theorem_that_App_is_Associative])") (the_base_case_in_the_app_example (pages_written_especially_for_the_tours) "The Base Case in the App Example This formula is the [31;1mBase Case[0m. It consists of two parts, a test identifying the non-inductive case and the conjecture to prove. (IMPLIES (ENDP A) [31;1m; Test[0m (:P A B C)) [31;1m; Conjecture[0m When we prove this we can assume * [47mA[0m is empty and we have to prove the conjecture for [47mA[0m.") (the_end_of_the_flying_tour (pages_written_especially_for_the_tours) "The End of the Flying Tour {IMAGE} This completes the Flying Tour. We recommend that you now take A Walking Tour of ACL2 (see [A_Walking_Tour_of_ACL2]). Thanks. Matt Kaufmann and J Moore {IMAGE} (see [A_Walking_Tour_of_ACL2])") (the_end_of_the_proof_of_the_associativity_of_app (pages_written_especially_for_the_tours) "The End of the Proof of the Associativity of App {IMAGE} (see [Guiding_the_ACL2_Theorem_Prover]) That completes (see [Popping_out_of_an_Inductive_Proof]) the proof of *1. Q.E.D. (see [The_Q.E.D._Message]) Summary Form: ( DEFTHM ASSOCIATIVITY-OF-APP ...) Rules (see [The_Rules_used_in_the_Associativity_of_App_Proof]): ((:REWRITE CDR-CONS) (:REWRITE CAR-CONS) (:DEFINITION NOT) (:DEFINITION ENDP) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:DEFINITION APP)) Warnings: None Time: 0.27 seconds (prove: 0.10 (see [The_Time_Taken_to_do_the_Associativity_of_App_Proof]), print: 0.05, other: 0.12) ASSOCIATIVITY-OF-APP {IMAGE} {IMAGE} (see [Guiding_the_ACL2_Theorem_Prover])") (the_end_of_the_walking_tour (pages_written_especially_for_the_tours) "The End of the Walking Tour {IMAGE} This completes the Walking Tour. We intend to document many other parts of the system this way, but we just haven't gotten around to it. To start the two tours over again from the beginning, click on the icons below. If you are really interested in learning how to use ACL2, we recommend that you repeat each tour at least once more to explore branches of the tour that you might have missed. If you want to learn how to use the theorem prover, we now recommend that you devote the time necessary to work your way through the extended introduction to how to use the prover. See [introduction-to-the-theorem-prover]. This will explain how to interact with ACL2 and has some sample problems for you to solve including some challenge proofs to make ACL2 find. We hope you enjoy ACL2. We do. Matt Kaufmann and J Strother Moore {IMAGE} (see [A_Flying_Tour_of_ACL2]) {IMAGE} (see [A_Walking_Tour_of_ACL2])") (the_event_summary (pages_written_especially_for_the_tours) "The Event Summary At the conclusion of most events (click here (see [About_the_Prompt]) for a brief discussion of events or see [events] {ICON} (see [A_Tiny_Warning_Sign])), ACL2 prints a summary. The summary for [47mapp[0m is: Summary Form: ( DEFUN APP ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: None Time: 0.03 seconds (prove: 0.00, print: 0.00, other: 0.03) APP The ``rules'' listed are those used in function admission or proof summarized. What is actually listed are ``runes'' (see [rune]) {ICON} (see [A_Tiny_Warning_Sign])) which are list-structured names for rules in the ACL2 database or ``[world]'' {ICON} (see [A_Tiny_Warning_Sign]). Using [theories] {ICON} (see [A_Tiny_Warning_Sign]) you can ``enable'' and ``disable'' rules so as to make them available (or not) to the ACL2 theorem prover. The ``warnings'' mentioned (none are listed for [47mapp[0m) remind the reader whether the event provoked any warnings. The warnings themselves would have been printed earlier in the processing and this part of the summary just names the earlier warnings printed. The ``time'' indicates how much processing time was used and is divided into three parts: the time devoted to proof, to printing, and to syntactic checks, pre-processing and database updates. Despite the fact that ACL2 is an applicative language it is possible to measure time with ACL2 programs. The [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign]) contains a clock. The times are printed in decimal notation but are actually counted in integral units. Note that by default, each time is a runtime, also known as a cpu time, as opposed to being a real time, also known as a wall clock time. The final [47mAPP[0m is the value of the [47mdefun[0m command and was printed by the read-eval-print loop. The fact that it is indented one space is a subtle reminder that the command actually returned an ``error triple'', consisting of a flag indicating (in this case) that no error occurred, a value (in this case the symbol [47mAPP[0m), and the final [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign])). See [ld-post-eval-print] {ICON} (see [A_Tiny_Warning_Sign]) for some details. If you really want to follow that link, however, you might see [ld] {ICON} (see [A_Tiny_Warning_Sign]) first. You should now return to the Walking Tour (see [Revisiting_the_Admission_of_App]).") (|THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP_{STEP_0}| (pages_written_especially_for_the_tours) "The Expansion of ENDP in the Induction Step (Step 0) Subgoal *1/2 (IMPLIES (AND (NOT ( (see [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_1}])ENDP A)) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). {IMAGE} Click on the link above (the open parenthesis before [47mENDP[0m) to replace [47m(ENDP A)[0m by its definition.") (|THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP_{STEP_1}| (pages_written_especially_for_the_tours) "The Expansion of ENDP in the Induction Step (Step 1) Subgoal *1/2 (IMPLIES (AND ( (see [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_2}])NOT [31;1m(NOT (CONSP A))[0m) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). {IMAGE} The [31;1mbold[0m text is the instantiated definition of [47mENDP[0m. Now click on the link above to simplify (NOT (NOT (CONSP A)))") (|THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP_{STEP_2}| (pages_written_especially_for_the_tours) "The Expansion of ENDP in the Induction Step (Step 2) Subgoal *1/2' (IMPLIES (AND [31;1m(CONSP A)[0m (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP (APP A B) C) (APP A (APP B C)))). {IMAGE} Note that this is [47mSubgoal *1/2'.[0m You may click here (see [Overview_of_the_Simplification_of_the_Induction_Step_to_T]) to return to the main proof.") (the_falling_body_model (pages_written_especially_for_the_tours) "The Falling Body Model {IMAGE} One particularly famous and very simple model is the equation of a falling body: the distance d an object falls is proportional to the square of the time t. If the time is measured in seconds and the distance in feet, the equation relating these two is 2 d = 16t This equation is a [31;1mmodel[0m of falling objects. It can be used to predict how long it takes a cannonball to fall from the top of a 200 foot tower (3.5 seconds). This might be important if your product is designed to drop cannonballs on moving targets.") (|THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_0}| (pages_written_especially_for_the_tours) "The Final Simplification in the Base Case (Step 0) Subgoal *1/1' (IMPLIES (NOT (CONSP A)) (EQUAL (APP ( (see [The_Final_Simplification_in_the_Base_Case_{Step_1}])APP A B) C) (APP A (APP B C)))). {IMAGE} Click on the link above to replace [47m(APP A B)[0m by its definition. Note that the hypothesis [47m(NOT (CONSP A))[0m allows us to simplify the [47mIF[0m in [47mAPP[0m to its [31;1mfalse branch[0m this time.") (|THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_1}| (pages_written_especially_for_the_tours) "The Final Simplification in the Base Case (Step 1) Subgoal *1/1' (IMPLIES (NOT (CONSP A)) (EQUAL (APP [31;1mB[0m C) ( (see [The_Final_Simplification_in_the_Base_Case_{Step_2}])APP A (APP B C)))). {IMAGE} Click on the link above to expand the definition of [47mAPP[0m. Again, we come out through the false branch because of the hypothesis.") (|THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_2}| (pages_written_especially_for_the_tours) "The Final Simplification in the Base Case (Step 2) Subgoal *1/1' (IMPLIES (NOT (CONSP A)) ( (see [The_Final_Simplification_in_the_Base_Case_{Step_3}])EQUAL (APP B C) [31;1m(APP B C)[0m)). {IMAGE} Click on the link above to use the Axiom [47m(EQUAL x x) = t[0m") (|THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_3}| (pages_written_especially_for_the_tours) "The Final Simplification in the Base Case (Step 3) Subgoal *1/1' (IMPLIES (NOT (CONSP A)) [31;1mT[0m) {IMAGE} Now that its conclusion is identically [47mT[0m the [47mIMPLIES[0m will simplify to [47mT[0m (not shown) and we are done with [47mSubgoal *1/1'[0m. You may click here (see [Overview_of_the_Simplification_of_the_Base_Case_to_T]) to return to the main proof.") (the_first_application_of_the_associativity_rule (pages_written_especially_for_the_tours) "The First Application of the Associativity Rule So here we see our associativity rule being used! The rewriter sweeps the conjecture in a [31;1mleftmost innermost[0m fashion, applying rewrite rules as it goes. The associativity rule is used many times in this sweep. The first ``target'' is highlighted below. Click on it to see what happens: [31;1mCurrent Conjecture[0m: (equal (app (app (app (app x1 x2) (app x3 x4)) (see [A_Sketch_of_How_the_Rewriter_Works]) (app x5 x6)) x7) (app x1 (app (app x2 x3) (app (app x4 x5) (app x6 x7)))))") (the_induction_scheme_selected_for_the_app_example (pages_written_especially_for_the_tours) "The Induction Scheme Selected for the App Example (AND (IMPLIES (AND (NOT (ENDP A)) ; Induction Step: test (:P (CDR A) B C)) ; and induction hypothesis (:P A B C)) ; implies induction conclusion. (IMPLIES (ENDP A) (:P A B C))) ; Base Case The formula beginning with this parenthesis is the induction scheme suggested by [47m(APP A B)[0m applied to [47m(P A B C)[0m. It is a [31;1mconjunction[0m ([47m[and][0m {ICON} (see [A_Tiny_Warning_Sign])) of two formulas. The first is the [31;1minduction step[0m and the second is the [31;1mbase case[0m.") (the_induction_step_in_the_app_example (pages_written_especially_for_the_tours) "The Induction Step in the App Example This formula is the [31;1mInduction Step[0m. It basically consists of three parts, a test identifying the inductive case, an induction hypothesis and an induction conclusion. (IMPLIES (AND (NOT (ENDP A)) [31;1m; Test[0m (:P (CDR A) B C)) [31;1m; Induction Hypothesis[0m (:P A B C)) [31;1m; Induction Conclusion[0m When we prove this we can assume * [47mA[0m is not empty, and that * the associativity conjecture holds for a ``smaller'' version of [47mA[0m, namely, [47m(CDR A)[0m. Under those hypotheses we have to prove the associativity conjecture for [47mA[0m itself.") (the_instantiation_of_the_induction_scheme (pages_written_especially_for_the_tours) "The Instantiation of the Induction Scheme The induction scheme just shown is just an abbreviation for our real goal. To obtain our actual goals we have to replace the schema [47m:P[0m by the associativity conjecture (instantiated as shown in the scheme). This produces two actual goals, the induction step and the base case.") (the_justification_of_the_induction_scheme (pages_written_especially_for_the_tours) "The Justification of the Induction Scheme This paragraph explains why the induction selected is legal. The explanation is basically the same as the explanation for why the recursion in [47m(APP A B)[0m terminates.") (the_proof_of_the_associativity_of_app (pages_written_especially_for_the_tours) "The Proof of the Associativity of App {IMAGE} (see [Overview_of_the_Simplification_of_the_Induction_Step_to_T]) Here is the theorem prover's output when it processes the [31;1mdefthm[0m command for the associativity of [47mapp[0m. We have highlighted text for which we offer some explanation, and broken the presentation into several pages. (The most recent version of ACL2 may print slightly different output but the basics are the same.) Just follow the Walking Tour after exploring the explanations. However, before exploring this output you should understand that ACL2 users rarely read successful proofs! Instead, they look at certain subgoals printed in failed proofs, figure whether and how those subgoals can be proved, and give ACL2 directions for proving them, usually by simply proving other lemmas. Furthermore, to be a good user of ACL2 you do not have to understand how the theorem prover works. You just have to understand how to interact with it. We explain this in great detail later. But basically all new users are curious to know how ACL2 works and this little tour attempts to give some answers, just to satisfy your curiosity. The first command below, [47m:set-gag-mode nil[0m, instructs ACL2 to supply its full prover output; normally that output is restricted considerably (``gagged''), but we include it all below in support of the associated explanations. {IMAGE} ACL2!>[31;1m:set-gag-mode nil[0m <state> ACL2!>[31;1m(defthm associativity-of-app[0m [31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c))))[0m Name the formula above *1 (see [Name_the_Formula_Above]). [Perhaps] we can prove *1 by induction. Three induction schemes are suggested (see [Suggested_Inductions_in_the_Associativity_of_App_Example]) by this conjecture. Subsumption (see [Subsumption_of_Induction_Candidates_in_App_Example]) reduces that number to two. However, one of these is flawed (see [Flawed_Induction_Candidates_in_App_Example]) and so we are left with one viable candidate. We will induct according to a scheme suggested by (APP A B). If we let (:P A B C) denote *1 above then the induction scheme we'll use is ( (see [The_Induction_Scheme_Selected_for_the_App_Example])AND ( (see [The_Induction_Step_in_the_App_Example])IMPLIES (AND (NOT (ENDP A)) (:P (CDR A) B C)) (:P A B C)) ( (see [The_Base_Case_in_the_App_Example])IMPLIES (ENDP A) (:P A B C))). This induction is justified (see [The_Justification_of_the_Induction_Scheme]) by the same argument used to admit APP, namely, the measure (ACL2-COUNT A) is decreasing according to the relation O< (which is known to be well-founded on the domain recognized by O-P). When applied (see [The_Instantiation_of_the_Induction_Scheme]) to the goal at hand the above induction scheme produces the following two nontautological subgoals (see [Nontautological_Subgoals]). {IMAGE} (see [Overview_of_the_Simplification_of_the_Induction_Step_to_T])") (the_q.e.d._message (pages_written_especially_for_the_tours) "The Q.E.D. Message [31;1mQ.E.D.[0m stands for ``quod erat demonstrandum'' which is Latin for ``which was to be demonstrated'' and is the signal that a proof is completely done.") (the_rules_used_in_the_associativity_of_app_proof (pages_written_especially_for_the_tours) "The Rules used in the Associativity of App Proof Note that under [31;1mRules[0m we list the runes (see [RUNE]) {ICON} (see [A_Tiny_Warning_Sign]) of all the rules used in the proof. This list says that we used the rewrite rules [47mCAR-CONS[0m and [47mCDR-CONS[0m, the definitions of the functions [47mNOT[0m, [47mENDP[0m and [47mAPP[0m, and primitive type reasoning (which is how we simplified the [47mIF[0m and [47mEQUAL[0m terms). For what it is worth, [47mIMPLIES[0m and [47mAND[0m are actually macros (see [DEFMACRO]) {ICON} (see [A_Tiny_Warning_Sign]) that are expanded into [47mIF[0m expressions before the proof ever begins. The use of macros is not reported among the rules.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_0}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 0) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_1}])APP A B) C) (APP A (APP B C)))). {IMAGE} Click on the link above to replace [47m(APP A B)[0m by its definition.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_10}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 10) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_11}])[31;1mEQUAL (APP (APP (CDR A) B) C)[0m [31;1m(APP (CDR A) (APP B C)))[0m). {IMAGE} Click on the link above to use the Induction Hypothesis (which is the second of the two hypotheses above and which is identical to the rewritten conclusion).") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_11}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 11) Subgoal *1/2' ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_12}])IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) [31;1mT[0m) {IMAGE} Click on the link above to use the definition of [47mIMPLIES[0m. Since the conclusion of the implication is now identically [47mT[0m, the implication simplifies to [47mT[0m.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_12}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 12) Subgoal *1/2' [31;1mT[0m {IMAGE} So, indeed, [47mSubgoal *1/2'[0m [31;1mdoes[0m simplify to T! You can see that even in an example as simple as this one, quite a lot happens in simplification. You may click here (see [Overview_of_the_Simplification_of_the_Induction_Step_to_T]) to return to the main proof.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_1}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 1) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP [31;1m(IF [0m( (see [The_Simplification_of_the_Induction_Conclusion_{Step_2}])[31;1mCONSP A)[0m [31;1m(CONS (CAR A) (APP (CDR A) B))[0m [31;1mB)[0m C) (APP A (APP B C)))). {IMAGE} Note that the [47mIF[0m expression above is the simplified body of [47mAPP[0m. But we know the test [47m(CONSP A)[0m is true, by the first hypothesis. Click on the link above to replace the test by [47mT[0m. Actually this step and several subsequent ones are done during the simplification of the body of [47mAPP[0m but we want to illustrate the basic principles of simplification without bothering with every detail.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_2}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 2) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (APP ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_3}])IF [31;1mT[0m (CONS (CAR A) (APP (CDR A) B)) B) C) (APP A (APP B C)))). {IMAGE} Click on the link above to apply the Axiom [47m(IF T x y) = x[0m.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_3}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 3) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_4}])APP [31;1m(CONS (CAR A) (APP (CDR A) B))[0m C) (APP A (APP B C)))). {IMAGE} Click on the link above to expand the definition of [47mAPP[0m here.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_4}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 4) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (IF ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_5}])[31;1mCONSP (CONS (CAR A) (APP (CDR A) B)))[0m [31;1m(CONS (CAR (CONS (CAR A) (APP (CDR A) B)))[0m [31;1m(APP (CDR (CONS (CAR A) (APP (CDR A) B)))[0m [31;1mC))[0m [31;1mC)[0m (APP A (APP B C)))). {IMAGE} Click on the link above to apply the Axiom [47m(CONSP (CONS x y)) = T[0m.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_5}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 5) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (IF [31;1mT[0m (CONS ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_6}])CAR (CONS (CAR A) (APP (CDR A) B))) (APP (CDR (CONS (CAR A) (APP (CDR A) B))) C)) C) (APP A (APP B C)))). {IMAGE} Click on the link above to apply the Axiom [47m(CAR (CONS x y)) = x[0m.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_6}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 6) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL (IF T (CONS [31;1m(CAR A)[0m (APP ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_7}])CDR (CONS (CAR A) (APP (CDR A) B))) C)) C) (APP A (APP B C)))). {IMAGE} Click on the link above to apply the Axiom [47m(CDR (CONS x y)) = y[0m.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_7}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 7) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_8}])IF T (CONS (CAR A) (APP [31;1m(APP (CDR A) B)[0m C)) C) (APP A (APP B C)))). {IMAGE} Click on the link above to apply the Axiom [47m(IF T x y) = x[0m.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_8}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 8) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) (EQUAL [31;1m(CONS (CAR A)[0m [31;1m(APP (APP (CDR A) B)[0m [31;1mC))[0m ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_9}])APP A (APP B C)))). {IMAGE} Click on the link above to expand the definition of [47mAPP[0m here. This time, we'll do the whole expansion at once, including the simplification of the resulting [47mIF[0m. This is how ACL2 actually does it.") (|THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_9}| (pages_written_especially_for_the_tours) "The Simplification of the Induction Conclusion (Step 9) Subgoal *1/2' (IMPLIES (AND (CONSP A) (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C)))) ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_10}])EQUAL (CONS (CAR A) (APP (APP (CDR A) B) C)) [31;1m(CONS (CAR A)[0m [31;1m(APP (CDR A) (APP B C))[0m))). {IMAGE} Click on the link above to apply the Axiom that [47m(EQUAL (CONS x y) (CONS u v))[0m is equal to the conjunction of [47m(EQUAL x u)[0m and [47m(EQUAL y v)[0m. In this case, [47m(EQUAL x u)[0m is trivial, [47m(EQUAL (CAR A) (CAR A))[0m.") (the_summary_of_the_proof_of_the_trivial_consequence (pages_written_especially_for_the_tours) "The Summary of the Proof of the Trivial Consequence Note that at the conclusion of the proof, the system reminds you of the earlier [31;1mWarning[0m. It is a good idea, when the [31;1mQ.E.D.[0m flies by, to see if there were any Warnings.") (the_theorem_that_app_is_associative (pages_written_especially_for_the_tours) "The Theorem that App is Associative {IMAGE} (see [The_Proof_of_the_Associativity_of_App]) ACL2!>[31;1m(defthm associativity-of-app[0m [31;1m(equal (app (app a b) c)[0m [31;1m(app a (app b c))))[0m The formula above says [47mapp[0m is associative. The [47m[defthm][0m {ICON} (see [A_Tiny_Warning_Sign]) command instructs ACL2 to prove the formula and to name it [47massociativity-of-app[0m. Actually, the [47mdefthm[0m command also builds the formula into the database as a [47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule, but we won't go into that just yet. What we will consider is how the ACL2 theorem prover proves this formula. If you proceed you will find the actual output of ACL2 in response to the command above. Some of the text is highlighted for the purposes of the tour. ACL2 does not highlight its output. You will note that we sometimes highlight a single open parenthesis. This is our way of drawing your attention to the subformula that begins with that parenthesis. By clicking on the parenthesis you will get an explanation of the subformula or its processing. {IMAGE} (see [The_Proof_of_the_Associativity_of_App])") (the_time_taken_to_do_the_associativity_of_app_proof (pages_written_especially_for_the_tours) "The Time Taken to do the Associativity of App Proof The time it took us to explain this proof may leave the impression that the proof is complicated. In a way, it is. But it happens quickly. The time taken to do this proof is about 1/10 second. The rest of the time (about 2/10 seconds) is spent in pre- and post-processing. Basically, this proof flashes across your screen before you can read it; you see the [31;1mQ.E.D.[0m and don't bother to scroll back to read it. You have more important things to do than read successful proofs.") (the_tours (pointers) "See [tours].") (the_warning_about_the_trivial_consequence (pages_written_especially_for_the_tours) "The WARNING about the Trivial Consequence This [31;1mWarning[0m alerts us to the fact that when treated as a [31;1mrewrite[0m rule, the new rule [47mTRIVIAL-CONSEQUENCE[0m, rewrites terms of the same form as a rule we have already proved, namely [47mASSOCIATIVITY-OF-APP[0m. When you see this warning you should [31;1mthink about your rules[0m! In the current case, it would be a good idea [31;1mnot[0m to make [47mTRIVIAL-CONSEQUENCE[0m a rule at all. We could do this with [47m:[0m[47m[rule-classes][0m {ICON} (see [A_Tiny_Warning_Sign]) nil. ACL2 proceeds to try to prove the theorem, even though it printed some warnings. The basic assumption in ACL2 is that the [31;1muser[0m [31;1munderstands what he or she is doing[0m but may need a little reminding just to manage a complicated set of facts.") (third (nth acl2-built-ins) "Third member of the list See any Common Lisp documentation for details.") (thm (miscellaneous) "Prove a theorem Example: (thm (equal (app (app a b) c) (app a (app b c)))) Also see [defthm]. Unlike [47m[defthm][0m, [47mthm[0m does not store an event; it merely causes the theorem prover to attempt a proof. But like [47mdefthm[0m, calls of [47mthm[0m are legal in event contexts (see [embedded-event-form]). General Form: (thm term :instructions instructions :hints hints :otf-flg otf-flg) where [47mterm[0m is a term alleged to be a theorem, and [47m[instructions][0m, [47m[hints][0m, and [47m[otf-flg][0m are as described in the corresponding [documentation] topics. The keyword arguments are optional. For information on how [47mthm[0m is implemented using [47m[make-event][0m, see [make-event-example-3]. Subtopics [Otf-flg] Allow more than one initial subgoal to be pushed for induction") (tidbits (acl2-tutorial) "Some basic hints for using ACL2 See [books] for a discussion of books. Briefly, a book is a file whose name ends in ``.lisp'' that contains ACL2 [events]; see [events]. See [history] for a list of useful commands. Some examples: :pbt :here ; print the current event :pbt (:here -3) ; print the last four events :u ; undo the last event :pe append ; print the definition of append See [documentation] to learn how to print documentation to the terminal. There are also versions of the [documentation] for web browsers and for Emacs (see [ACL2-Doc]). There are quite a few kinds of rules allowed in ACL2 besides [47m:[0m[47m[rewrite][0m rules, though we hope that beginners won't usually need to be aware of them. See [rule-classes] for details. In particular, there is support for [congruence] rewriting. See [rune] (``RUle NamE'') for a description of the various kinds of rules in the system. Also see [theories] for a description of how to build [theories] of [rune]s, which are often used in hints; see [hints]. A ``[programming] mode'' is supported; see [program], see [defun-mode], and see [default-defun-mode]. It can be useful to prototype functions after executing the command [47m:[0m[47m[program][0m, which will cause definitions to be syntax-checked only. ACL2 supports mutual recursion, though this feature is not tied into the automatic discovery of [induction] schemas and is often not the best way to proceed when you expect to be reasoning about the functions. See [defuns]; also see [mutual-recursion]. See [ld] for discussion of how to load files of [events]. There are many options to [47m[ld][0m, including ones to suppress proofs and to control output. The [47m:[0m[47m[otf-flg][0m (Onward Thru the Fog FLaG) is a useful feature that Nqthm users have often wished for. It prevents the prover from aborting a proof attempt and inducting on the original conjecture. See [otf-flg]. ACL2 supports redefinition and redundancy in [events]; see [ld-redefinition-action] and see [redundant-events]. A [proof-tree] display feature is available for use with Emacs. This feature provides a view of ACL2 proofs that can be much more useful than reading the stream of [characters] output by the theorem prover as its ``proof.'' See [proof-tree]. An interactive feature similar to Pc-Nqthm is supported in ACL2. See [verify] and see [proof-builder]. ACL2 allows you to [monitor] the use of [rewrite] rules. See [break-rewrite]. See [arrays] to read about applicative, fast [arrays] in ACL2. To quit the ACL2 [command] loop, or (in gcl) to return to the ACL2 [command] loop after an interrupt, type [47m:[0m[47m[q][0m. To continue (resume) after an interrupt (in gcl), type [47m:r[0m. To cause an interrupt hit control-C (twice, if inside Emacs). To exit ACL2 altogether, type [47m:[0m[47m[quit][0m. See [state] to read about the von Neumannesque ACL2 [state] object that records the ``current state'' of the ACL2 session. Also see [@], and see [assign], to learn about reading and setting global [state] variables. If you want your own von Neumannesque object, e.g., a structure that can be ``destructively modified'' but which must be used with some syntactic restrictions, see [stobj].") (time$ (programming acl2-built-ins) "Time the evaluation of a given form Semantically, [47m(time$ x ...)[0m equals [47mx[0m. However, its evaluation writes timing output to the trace output (which is usually the terminal), as explained further below. Note: Some of the functionality below is available only for certain host Common Lisp implementations. Examples: ; Basic examples: (time$ (foo 3 4)) (time$ (mini-proveall)) (defun bar (x) (time$ (f x))) ; Custom examples, which use a custom timing message rather than a built-in ; message from Lisp: ; Report only if real time is at least 1/2 second (two equivalent forms). (time$ (foo) :mintime 1/2) (time$ (foo) :real-mintime 1/2) ; Report only if allocation is at least 1000 bytes (and if the Lisp supports ; :minalloc). (time$ (foo) :minalloc 1000) ; Report only if real time is at least 1/2 second and (if the Lisp supports ; :minalloc) allocation is at least 931 bytes. (time$ (foo) :real-mintime 1/2 :minalloc 931) ; Print "Hello Moon, Goodbye World" instead of any timing data. (time$ (foo) :msg "Hello ~s0, ~s1 World." :args (list "Moon" "Goodbye")) ; Print default custom timing message (same as omitting :mintime 0): (time$ (foo) :mintime 0) ; Print supplied custom timing message. (let ((bar ...)) (time$ (foo) :msg "The execution of ~xf took ~st seconds of real ~ time and ~sc seconds of run time (cpu time), and ~ allocated ~sa bytes. In an unrelated note, bar ~ currently has the value ~x0.~%" :args (list bar))) General Forms: (time$ form) (time$ form ; arguments below are optional :real-mintime <rational number of seconds> :run-mintime <rational number of seconds> :minalloc <number of bytes> :msg <fmt string> :args <list of arguments for msg> ) ; Note: :real-mintime can be replaced by :mintime where [47mform[0m is processed as usual except that the host Common Lisp times its evaluation. The simplest form is [47m(time$ x)[0m, which will call the [47mtime[0m utility in the underlying Lisp, and will print a small default message. If you want to see a message printed by the host Lisp, use [47m(time$ x :mintime nil)[0m instead, which may provide detailed, implementation-specific data such as the amounts of time spent in user and system mode, the gc time, the number of page faults encountered, and so on. Of you can create a custom message, configured using the [47m:msg[0m and [47m:args[0m parameters. [47mTime$[0m can also be made to report timing information only conditionally: the [47m:real-mintime[0m (or equivalently, [47m:mintime[0m), [47m:run-mintime[0m, and [47m:minalloc[0m arguments can be used to avoid reporting timing information for computations that take a small amount of time (perhaps as might be expected in ordinary cases), but to draw the user's attention to computations that take longer or allocate more memory than expected. We next document the keyword arguments in some detail. Keyword arguments [47m:real-mintime[0m (or [47m:mintime[0m) and [47m:run-mintime[0m can be used to specify a minimum time threshold for time reporting. That is, no timing information will be printed if the execution of [47mform[0m takes less than the specified number of seconds of real (total) time or run (cpu) time, respectively. Note that rational numbers like 1/2 may be used to specify a fractional amount of seconds. It is an error to specify both [47m:real-mintime[0m and its synonym, [47m:mintime[0m. Keyword argument [47m:minalloc[0m is not supported on all Lisps. When it is not supported, it is ignored. But on supported Lisps, [47m:minalloc[0m can be used to specify a minimum memory allocation threshold. If [47mform[0m results in fewer than this many bytes being allocated, then no timing information will be reported. Keyword argument [47m:msg[0m, when provided, should be a string accepted by the [47mfmt[0m family of functions (see [fmt]), and it may refer to the elements of [47m:args[0m by their positions, just as for [47mcw[0m (see [cw]). The following directives allow you to report timing information using the [47m:msg[0m string. The examples at the top of this documentation topic illustrate the use of these directives. [47m~xf[0m --- the form that was executed [47m~sa[0m --- the amount of memory allocated, in bytes (in supported Lisps) [47m~st[0m --- the real time taken, in seconds [47m~sc[0m --- the run time (cpu time) taken, in seconds The following apply only when the host Lisp is GCL. The two system times will likely be [47mnil[0m unless the GCL version is 2.6.10 or later. Note the upper-case characters for child times. [47m~sC[0m --- the child run time (cpu time) taken, in seconds [47m~ss[0m --- the system time taken, in seconds [47m~sS[0m --- the child system time taken, in seconds We turn now to an example that illustrates how [47mtime$[0m can be called in function bodies. Consider the following definition of the Fibonacci function, followed by the definition of a function that times [47mk[0m calls of this function. (defun fib (n) (if (zp n) 1 (if (= n 1) 1 (+ (fib (- n 1)) (fib (- n 2)))))) (defun time-fib (k) (if (zp k) nil (prog2$ (time$ (fib k) :mintime 1/2 :msg "(fib ~x0) took ~st seconds, ~sa bytes allocated.~%" :args (list k)) (time-fib (1- k))))) The following log shows a sample execution of the function defined just above. ACL2 !>(time-fib 36) (fib 36) took 3.19 seconds, 1280 bytes allocated. (fib 35) took 1.97 seconds, 1280 bytes allocated. (fib 34) took 1.21 seconds, 1280 bytes allocated. (fib 33) took 0.75 seconds, 1280 bytes allocated. NIL ACL2 !> Notes: (1) Common Lisp specifies that the [47mtime[0m utility prints to ``trace output'', and [47mtime$[0m follows this convention. Thus, if you have opened a [trace] file (see [open-trace-file]), then you can expect to find the [47mtime$[0m output there. (2) Unless the [47m:msg[0m argument is supplied, an explicit call of [47mtime$[0m in the top-level loop will show that the form being timed is a call of the ACL2 evaluator function [47mev-rec[0m. This is normal; the curious are invited, at their own risk, to see [return-last] for an explanation. Subtopics [Time-tracker] Display time spent during specified evaluation") (time-limit (pointers) "See [with-prover-time-limit].") (time-tracker (debugging time$ acl2-built-ins) "Display time spent during specified evaluation The [47mtime-tracker[0m macro is a utility for displaying time spent during specified evaluation. In general, the user provides this specification. However, ACL2 itself uses this utility for tracking uses of its [tau-system] reasoning utility (see [time-tracker-tau]). We discuss that use as an example before discussing the general form for calls of [47mtime-tracker[0m. Note that by default, the time being tracked is runtime (cpu time); to switch to realtime (elapsed time), see [get-internal-time]. Remark for ACL2(p) users (see [parallelism]): [47mtime-tracker[0m is merely a no-op in ACL2(p). During the development of the [tau-system], we were concerned about the possibility that it would slow down proofs without any indication of how one might avoid the problem. We wanted a utility that would alert the user in such situations. However, the tau-system code does not return [state], so we could not track time spent in the state. We developed the [47mtime-tracker[0m utility to track time and print messages, and we did it in a general way so that others can use it in their own code. Here is an example of such a message that could be printed during a proof. TIME-TRACKER-NOTE [:TAU]: Elapsed runtime in tau is 2.58 secs; see :DOC time-tracker-tau. And here is an example of such a message that could be printed at the end of the proof. TIME-TRACKER-NOTE [:TAU]: For the proof above, the total time spent in the tau system was 20.29 seconds. See :DOC time-tracker-tau. The [47mtime-tracker[0m utility tracks computation time spent on behalf of a user-specified ``tag''. In the case of the tau-system, we chose the tag, [47m:tau[0m. The first argument of [47mtime-tracker[0m is the tag, which in our running example is always [47m:tau[0m. Note that although all arguments of [47mtime-tracker[0m are evaluated, the first argument is typically a keyword and the second is always a keyword, and such arguments evaluate to themselves. An ACL2 function invoked at the start of a proof includes approximately the following code. (progn$ (time-tracker :tau :end) (time-tracker :tau :init :times '(1 2 3 4 5) :interval 5 :msg "Elapsed runtime in tau is ~st secs; see :DOC ~ time-tracker-tau.~|~%") ...) The first [47mtime-tracker[0m call (above) ends any existing time-tracking for tag [47m:tau[0m. One might have expected it to be put into code managing the proof [summary], but we decided not to rely on that code being executed, say, in case of an interrupt. When a given tag is not already being time-tracked, then [47m:end[0m is a no-op (rather than an error). The second [47mtime-tracker[0m call (above) initiates time-tracking for the tag, [47m:tau[0m. Moreover, it specifies the effect of the [47m:print?[0m keyword. Consider the following abbreviated definition from the ACL2 source code. (defun tau-clausep-lst-rec (clauses ens wrld ans ttree state calist) (cond ((endp clauses) (mv (revappend ans nil) ttree calist)) (t (mv-let (flg1 ttree1 calist) (tau-clausep (car clauses) ens wrld state calist) (prog2$ (time-tracker :tau :print?) (tau-clausep-lst-rec (cdr clauses) ...)))))) Notice that [47m(time-tracker :tau :print?)[0m is executed immediately after [47mtau-clausep[0m is called. The idea is to check whether the total time elapsed inside the tau-system justifies printing a message to the user. The specification of [47m:times '(1 2 3 4 5)[0m in the [47m:init[0m form above says that a message should be printed after 1 second, after 2 seconds, ..., and after 5 seconds. Thereafter, the specification of [47m:interval 5[0m in the [47m:init[0m form above says that each time we print, at least 5 additional seconds should have been tracked before [47m(time-tracker :tau :print?)[0m prints again. Finally, the [47m:msg[0m keyword above specifies just what should be printed. If it is omitted, then a reasonable default message is printed (as discussed below), but in this case we wanted to print a custom message. The [47m:msg[0m string above is what is printed using formatted printing (see [fmt]), where the character [47m#\t[0m is bound to a string giving a decimal representation with two decimal points of the time tracked so far for tag [47m:tau[0m. (As our general description below points out, [47m:msg[0m can also be a ``message'' list rather than a string.) But when is time actually tracked for [47m:tau[0m? Consider the following definition from the ACL2 source code. (defun tau-clausep-lst (clauses ens wrld ans ttree state calist) (prog2$ (time-tracker :tau :start!) (mv-let (clauses ttree calist) (tau-clausep-lst-rec clauses ens wrld ans ttree state calist) (prog2$ (time-tracker :tau :stop) (mv clauses ttree calist))))) The two calls of [47mtime-tracker[0m above first start, and then stop, time-tracking for the tag, [47m:tau[0m. Thus, time is tracked during evaluation of the call of [47mtau-clausep-lst-rec[0m, which is the function (discussed above) that does the [tau-system]'s work. Finally, as noted earlier above, ACL2 may print a time-tracking message for tag [47m:tau[0m at the end of a proof. The ACL2 function [47mprint-summary[0m contains essentially the following code. (time-tracker :tau :print? :min-time 1 :msg "For the proof above, the total runtime ~ spent in the tau system was ~st seconds. ~ See :DOC time-tracker-tau.~|~%") The use of [47m:min-time[0m says that we are to ignore the [47m:times[0m and [47m:interval[0m established by the [47m:init[0m call described above, and instead, print a message if and only if at least 1 second (since 1 is the value of keyword [47m:min-time[0m) has been tracked for tag [47m:tau[0m. Formatted printing (see [fmt]) is used for the value of [47m:msg[0m, where the character [47m#\t[0m is bound to a decimal string representation of the time in seconds, as described above. The example above covers all legal values for the second argument of [47mtime-tracker[0m and discusses all the additional legal keyword arguments. We conclude with a precise discussion of all arguments. Note that all arguments are evaluated; thus when we refer to an argument, we are discussing the value of that argument. All times discussed are runtimes, i.e., cpu times, unless that default is changed; see [get-internal-time]. General forms: (time-tracker t) ; enable time-tracking (default) (time-tracker nil) ; disable time-tracking (time-tracker tag ; a symbol other than t or nil option ; :init, :end, :start, :start!, :stop, or :print? ;; keyword arguments: :times ; non-nil if and only if option is :init :interval ; may only be non-nil with :init option :min-time ; may only be non-nil with :print? option :msg ; may only be non-nil with :init and :print? options Time-tracking is enabled by default. If the first argument is [47mt[0m or [47mnil[0m, then no other arguments are permitted and time-tracking is enabled or disabled, respectively. When time-tracking is disabled, nothing below takes place. Thus we assume time-tracking is enabled for the remainder of this discussion. We also assume below that the first argument is neither [47mt[0m nor [47mnil[0m. We introduce some basic notions about time-tracking. A given tag, such as [47m:tau[0m in the example above, might or might not currently be ``tracked'': [47m:init[0m causes the specified tag to be tracked, while [47m:end[0m causes the specified tag not to be tracked. If the tag is being tracked, the tag might or might not be ``active'': [47m:start[0m and [47m:start![0m cause the tag to be in an active state, while [47m:stop[0m causes the tag not to be active. Note that only tracked tags can be in an active or inactive state. For a tag that is being tracked, the ``accumulated time'' is the total time spent in an active state since the time that the tag most recently started being tracked, and the ``checkpoint list'' is a non-empty list of rational numbers specifying when printing may take place, as described below. We now consider each legal value for the second argument, or ``option'', for a call of [47mtime-tracker[0m on a given tag. [47m:Init[0m specifies that the tag is to be tracked. It also establishes defaults for the operation of [47m:print?[0m, as described below, using the [47m:times[0m, [47m:interval[0m, and [47m:msg[0m keywords. Of these three, only [47m:times[0m is required, and its value must be a non-empty list of rational numbers specifying the initial checkpoint list for the tag. It is an error to specify [47m:init[0m if the tag is already being tracked. (So if you don't care whether or not the tag is already being tracked and you want to initiate tracking for that tag, use [47m:end[0m first.) [47m:End[0m specifies that if the tag is being tracked, then it should stop being tracked. If the tag is not being tracked, then [47m:end[0m has no effect. [47m:Start[0m specifies that the tag is to be active. It is an error to specify [47m:start[0m if the tag is not being tracked or is already active. [47m:Start![0m has the same effect as [47m:start[0m, except that it does not cause an error when the tag is already active. In effect, [47m:start![0m first invokes [47m:stop[0m if the tag is already active, and then invokes [47mstart[0m. [47m:Stop[0m specifies that the tag is to stop being active. It is an error to specify [47m:stop[0m if the tag is not being tracked or is not active. [47m:Print?[0m specifies that if the tag is being tracked (not necessarily active), then a message should be printed if a suitable condition is met. The nature of that message and that condition depend on the keyword options supplied with [47m:print?[0m as well as those supplied with the [47m:init[0m option that most recently initiated tracking. [47m:Print?[0m has no effect if the tag is not being tracked, except that if certain keyword values are checked if supplied with [47m:print?[0m: [47m:min-time[0m must be a rational number or [47mnil[0m, and [47m:msg[0m must be either a string, a true-list whose [47mcar[0m is a string, or [47mnil[0m. The remainder of this documentation describes the [47m:print?[0m option in detail under the assumption that the tag is being tracked: first, giving the conditions under which it causes a message to be printed, and second, explaining what is printed. When [47m:print?[0m is supplied a non-[47mnil[0m value of [47m:min-time[0m, that value must be a rational number, in which case a message is printed if the accumulated time for the tag is at least that value. Otherwise a message is printed if the accumulated time is greater than or equal to the [47mcar[0m of the checkpoint list for the tag. In that case, the tracking state for the tag is updated in the following two ways. First, the checkpoint list is scanned from the front and as long as the accumulated time is greater than or equal to the [47mcar[0m of the remaining checkpoint list, that [47mcar[0m is popped off the checkpoint list. Second, if the checkpoint list has been completely emptied and a non-[47mnil[0m [47m:interval[0m was supplied when tracking was most recently initiated with the [47m:init[0m option, then the checkpoint list is set to contain a single element, namely the sum of the accumulated time with that value of [47m:interval[0m. Finally, suppose the above criteria are met, so that [47m:print?[0m results in printing of a message. We describe below the message, [47mmsg[0m, that is printed. Here is how it is printed (see [fmt]), where [47mseconds-as-decimal-string[0m is a string denoting the number of seconds of accumulated time for the tag, with two digits after the decimal point. (fms "TIME-TRACKER-NOTE [~x0]: ~@1~|" (list (cons #0 tag) (cons #1 msg) (cons #t seconds-as-decimal-string)) (proofs-co state) state nil) The value of [47mmsg[0m is the value of the [47m:msg[0m keyword supplied with [47m:print?[0m, if non-[47mnil[0m; else, the value of [47m:msg[0m supplied when most recently initialization with the [47m:init[0m option, if non-[47mnil[0m; and otherwise, the string [47m"~st s"[0m (the final ``s'' abbreviating the word ``seconds''). It is convenient to supply [47m:msg[0m as a call [47m(msg str arg-0 arg-1 ... arg-k)[0m, where [47mstr[0m is a string and each [47marg-i[0m is the value to be associated with [47m#\i[0m upon formatted printing (as with [47m[fmt][0m) of the string [47mstr[0m.") (time-tracker-tau (tau-system) "Messages about expensive use of the [tau-system] This [documentation] topic explains messages printing by the theorem prover about the [tau-system], as follows. During a proof you may see a message such as the following. TIME-TRACKER-NOTE [:TAU]: Elapsed runtime in tau is 4.95 secs; see :DOC time-tracker-tau. Just below a proof [summary] you may see a message such as the following. TIME-TRACKER-NOTE [:TAU]: For the proof above, the total runtime spent in the tau system was 30.01 seconds. See :DOC time-tracker-tau. Both of these messages are intended to let you know that certain prover heuristics (see [tau-system]) may be slowing proofs down more than they are helping. If you are satisfied with the prover's performance, you may ignore these messages or even turn them off by disabling time-tracking entirely (see [time-tracker]). Otherwise, here are some actions that you can take to solve such a performance problem. The simplest solution is to disable the tau-system, in either of the following equivalent ways. (in-theory (disable (:executable-counterpart tau-system))) (in-theory (disable (tau-system))) But if you want to leave the tau-system enabled, you could investigate the possibility that the tau-system is causing an expensive [47m:[0m[47m[logic][0m-mode function to be executed. You can diagnose that problem by observing the rewriter --- see [dmr] --- or by interrupting the system and getting a backtrace (see [set-debugger-enable]). A solution in that case is to disable the [executable-counterpart] of that function, for example in any of these equivalent ways. (in-theory (disable (:executable-counterpart foo))) (in-theory (disable (:e foo))) (in-theory (disable (foo))) As a result, the tau-system will be weakened, but perhaps only negligibly. In either case above, you may prefer to provide [47m:[0m[47m[in-theory][0m hints rather than [47m:in-theory[0m [events]; see [hints]. A more sophisticated solution is to record values of the [47m:[0m[47m[logic][0m-mode function in question, so that the tau-system will look up the necessary values rather than calling the function, whether or not the executable-counterpart of that function is enabled. Here is an example of a lemma that can provide such a solution. See [tau-system]. (defthm lemma (and (foo 0) (foo 17) (foo t) (not (foo '(a b c)))) :rule-classes :tau-system)") (tips (acl2-tutorial) "Some hints for using the ACL2 prover We present here some tips for using ACL2 effectively. Though this collection is somewhat [3mad hoc[0m, we try to provide some organization, albeit somewhat artificial: for example, the sections overlap, and no particular order is intended. This material has been adapted by Bill Young from a very similar list for Nqthm that appeared in the conclusion of: ``Interaction with the Boyer-Moore Theorem Prover: A Tutorial Study Using the Arithmetic-Geometric Mean Theorem,'' by Matt Kaufmann and Paolo Pecchiari, CLI Technical Report 100, June, 1995. We also draw from a similar list in Chapter 13 of ``A Computational Logic Handbook'' by R.S. Boyer and J S. Moore (Academic Press, 1988). We'll refer to this as ``ACLH'' below. These tips are organized roughly as follows. A. ACL2 Basics B. Strategies for creating events C. Dealing with failed proofs D. Performance tips E. Miscellaneous tips and knowledge F. Some things you DON'T need to know [3mACL2 BASICS[0m [31;1mA1. The ACL2 logic.[0m This is a logic of total functions. For example, if [47mA[0m and [47mB[0m are less than or equal to each other, then we need to know something more in order to conclude that they are equal (e.g., that they are numbers). This kind of twist is important in writing definitions; for example, if you expect a function to return a number, you may want to apply the function [47m[fix][0m or some variant (e.g., [47m[nfix][0m or [47m[ifix][0m) in case one of the formals is to be returned as the value. ACL2's notion of ordinals is important on occasion in supplying ``measure [hints]'' for the acceptance of recursive definitions. Be sure that your measure is really an ordinal. Consider the following example, which ACL2 fails to admit (as explained below). (defun cnt (name a i x) (declare (xargs :measure (+ 1 i))) (cond ((zp (+ 1 i)) 0) ((equal x (aref1 name a i)) (1+ (cnt name a (1- i) x))) (t (cnt name a (1- i) x)))) One might think that [47m(+ 1 i)[0m is a reasonable measure, since we know that [47m(+ 1 i)[0m is a positive integer in any recursive call of [47mcnt[0m, and positive integers are ACL2 ordinals (see [o-p]). However, the ACL2 logic requires that the measure be an ordinal unconditionally, not just under the governing assumptions that lead to recursive calls. An appropriate fix is to apply [47m[nfix][0m to [47m(+ 1 i)[0m, i.e., to use (declare (xargs :measure (nfix (+ 1 i)))) in order to guarantee that the measure will always be an ordinal (in fact, a positive integer). For more about admissibility of recursive definitions, see [defun], in particular the discussion of termination. [31;1mA2. Simplification.[0m The ACL2 simplifier is basically a rewriter, with some ``[linear] arithmetic'' thrown in. One needs to understand the notion of conditional rewriting. See [rewrite]. [31;1mA3. Parsing of rewrite rules.[0m ACL2 parses [rewrite] rules roughly as explained in ACLH, [3mexcept[0m that it never creates ``unusual'' rule classes. In ACL2, if you want a [47m:[0m[47m[linear][0m rule, for example, you must specify [47m:[0m[47m[linear][0m in the [47m:[0m[47m[rule-classes][0m. See [rule-classes], and also see [rewrite] and see [linear]. [31;1mA4. Linear arithmetic.[0m On this subject, it should suffice to know that the prover can handle truths about [47m[+][0m and [47m[-][0m, and that [linear] rules (see above) are somehow ``thrown in the pot'' when the prover is doing such reasoning. Perhaps it's also useful to know that [linear] rules can have hypotheses, and that conditional rewriting is used to relieve those hypotheses. [31;1mA5. Events.[0m Over time, the expert ACL2 user will know some subtleties of its [events]. For example, [47m[in-theory][0m [events] and [hints] are important, and they distinguish between a function's definition and its [executable-counterpart]. [3mB. STRATEGIES FOR CREATING EVENTS[0m In this section, we concentrate on the use of definitions and [rewrite] rules. There are quite a few kinds of rules allowed in ACL2 besides [rewrite] rules, though most beginning users probably won't usually need to be aware of them. See [rule-classes] for details. In particular, there is support for [congruence] rewriting. Also see [rune] (``RUle NamE'') for a description of the various kinds of rules in the system. [31;1mB1. Use high-level strategy.[0m Decompose theorems into ``manageable'' lemmas (admittedly, experience helps here) that yield the main result ``easily.'' It's important to be able to outline non-trivial proofs by hand (or in your head). In particular, avoid submitting goals to the prover when there's no reason to believe that the goal will be proved and there's no ``sense'' of how an induction argument would apply. It is often a good idea to avoid induction in complicated theorems unless you have a reason to believe that it is appropriate. [31;1mB2. Write elegant definitions.[0m Try to write definitions in a reasonably modular style, especially recursive ones. Think of ACL2 as a [programming] language whose procedures are definitions and lemmas, hence we are really suggesting that one follow good [programming] style (in order to avoid duplication of ``code,'' for example). When possible, complex functions are best written as compositions of simpler functions. The theorem prover generally performs better on primitive recursive functions than on more complicated recursions (such as those using accumulating parameters). Avoid large non-recursive definitions which tend to lead to large case explosions. If such definitions are necessary, try to prove all relevant facts about the definitions and then [disable] them. Whenever possible, avoid mutual recursion if you care to prove anything about your functions. The induction heuristics provide essentially no help with reasoning about mutually defined functions. Mutually recursive functions can usually be combined into a single function with a ``flag'' argument. (However, see [mutual-recursion-proof-example] for a small example of proof involving mutually recursive functions.) [31;1mB3. Look for analogies.[0m Sometimes you can easily edit sequences of lemmas into sequences of lemmas about analogous functions. [31;1mB4. Write useful rewrite rules.[0m As explained in A3 above, every [rewrite] rule is a directive to the theorem prover, usually to replace one [term] by another. The directive generated is determined by the syntax of the [47m[defthm][0m submitted. Never submit a [rewrite] rule unless you have considered its interpretation as a proof directive. [31;1mB4a. Rewrite rules should simplify.[0m Try to write [rewrite] rules whose right-hand sides are in some sense ``simpler than'' (or at worst, are variants of) the left-hand sides. This will help to avoid infinite loops in the rewriter. [31;1mB4b. Avoid needlessly expensive rules.[0m Consider a rule whose conclusion's left-hand side (or, the entire conclusion) is a [term] such as [47m(consp x)[0m that matches many [term]s encountered by the prover. If in addition the rule has complicated hypotheses, this rule could slow down the prover greatly. Consider switching the conclusion and a complicated hypothesis (negating each) in that case. [31;1mB4c. The ``Knuth-Bendix problem''.[0m Be aware that left sides of [rewrite] rules should match the ``normalized forms'', where ``normalization'' (rewriting) is inside out. Be sure to avoid the use of nonrecursive function symbols on left sides of [rewrite] rules, except when those function symbols are [disable]d, because they tend to be expanded away before the rewriter would encounter an instance of the left side of the rule. Also assure that subexpressions on the left hand side of a rewrite rule are in simplified form; see [community-books] example [47mbooks/demos/knuth-bendix-problem-1.lisp[0m. [31;1mB4d. Avoid proving useless rules.[0m Sometimes it's tempting to prove a [rewrite] rule even before you see how it might find application. If the rule seems clean and important, and not unduly expensive, that's probably fine, especially if it's not too hard to prove. But unless it's either part of the high-level strategy or, on the other hand, intended to get the prover past a particular unproved goal, it may simply waste your time to prove the rule, and then clutter the database of rules if you are successful. [31;1mB4e. State rules as strongly as possible, usually.[0m It's usually a good idea to state a rule in the strongest way possible, both by eliminating unnecessary hypotheses and by generalizing subexpressions to variables. Advanced users may choose to violate this policy on occasion, for example in order to avoid slowing down the prover by excessive attempted application of the rule. However, it's a good rule of thumb to make the strongest rule possible, not only because it will then apply more often, but also because the rule will often be easier to prove (see also B6 below). New users are sometimes tempted to put in extra hypotheses that have a ``type restriction'' appearance, without realizing that the way ACL2 handles (total) functions generally lets it handle trivial cases easily. [31;1mB4f. Avoid circularity.[0m A stack overflow in a proof attempt almost always results from circular rewriting. Use [47m[brr][0m to investigate the stack; see [break-lemma]. Because of the complex heuristics, it is not always easy to define just when a [rewrite] will cause circularity. See the very good discussion of this topic in ACLH. See [break-lemma] for a trick involving use of the forms [47mbrr t[0m and [47m(cw-gstack)[0m for inspecting loops in the rewriter. [31;1mB4g. Remember restrictions on permutative rules.[0m Any rule that permutes the variables in its left hand side could cause circularity. For example, the following axiom is automatically supplied by the system: (defaxiom commutativity-of-+ (equal (+ x y) (+ y x))). This would obviously lead to dangerous circular rewriting if such ``permutative'' rules were not governed by a further restriction. The restriction is that such rules will not produce a [term] that is ``lexicographically larger than'' the original [term] (see [loop-stopper]). However, this sometimes prevents intended rewrites. See Chapter 13 of ACLH for a discussion of this problem. [31;1mB5. Conditional vs. unconditional rewrite rules.[0m It's generally preferable to form unconditional [rewrite] rules unless there is a danger of case explosion. That is, rather than pairs of rules such as (implies p (equal term1 term2)) and (implies (not p) (equal term1 term3)) consider: (equal term1 (if p term2 term3)) However, sometimes this strategy can lead to case explosions: [47m[if][0m [term]s introduce cases in ACL2. Use your judgment. (On the subject of [47m[if][0m: [47m[cond][0m, [47m[case][0m, [47m[and][0m, and [47m[or][0m are macros that abbreviate [47m[if][0m forms, and propositional functions such as [47m[implies][0m quickly expand into [47m[if][0m [term]s.) [31;1mB6. Create elegant theorems.[0m Try to formulate lemmas that are as simple and general as possible. For example, sometimes properties about several functions can be ``factored'' into lemmas about one function at a time. Sometimes the elimination of unnecessary hypotheses makes the theorem easier to prove, as does generalizing first by hand. [31;1mB7. Use[0m [47m[defaxiom][0ms [31;1mtemporarily to explore possibilities.[0m When there is a difficult goal that seems to follow immediately (by a [47m:use[0m hint or by rewriting) from some other lemmas, you can create those lemmas as [47m[defaxiom][0m [events] (or, the application of [47m[skip-proofs][0m to [47m[defthm][0m [events]) and then double-check that the difficult goal really does follow from them. Then you can go back and try to turn each [47m[defaxiom][0m into a [47m[defthm][0m. When you do that, it's often useful to [disable] any additional [rewrite] rules that you prove in the process, so that the ``difficult goal'' will still be proved from its lemmas when the process is complete. Better yet, rather than disabling [rewrite] rules, use the [47m[local][0m mechanism offered by [47m[encapsulate][0m to make temporary rules completely [47m[local][0m to the problem at hand. See [encapsulate] and see [local]. [31;1mB9. Use books.[0m Consider using previously certified [books], especially for [arithmetic] reasoning. This cuts down the duplication of effort and starts your specification and proof effort from a richer foundation. See [community-books]. [3mC. DEALING WITH FAILED PROOFS[0m [31;1mC1. Look in proof output for goals that can't be further simplified.[0m Use the ``[proof-tree]'' utility to explore the proof space. However, you don't need to use that tool to use the ``checkpoint'' strategy. The idea is to think of ACL2 as a ``simplifier'' that either proves the theorem or generates some goal to consider. That goal is the first ``checkpoint,'' i.e., the first goal that does not further simplify. Exception: it's also important to look at the induction scheme in a proof by induction, and if induction seems appropriate, then look at the first checkpoint [3mafter[0m the induction has begun. Consider whether the goal on which you focus is even a theorem. Sometimes you can execute it for particular values to find a counterexample. When looking at checkpoints, remember that you are looking for any reason at all to believe the goal is a theorem. So for example, sometimes there may be a contradiction in the hypotheses. Don't be afraid to skip the first checkpoint if it doesn't seem very helpful. Also, be willing to look a few lines up or down from the checkpoint if you are stuck, bearing in mind however that this practice can be more distracting than helpful. [31;1mC2. Use the ``break rewrite'' facility.[0m [47m[Brr][0m and related utilities let you inspect the ``rewrite stack.'' These can be valuable tools in large proof efforts. See [break-lemma] for an introduction to these tools, and see [break-rewrite] for more complete information. The break facility is especially helpful in showing you why a particular rewrite rule is not being applied. [31;1mC3. Use induction hints when necessary.[0m Of course, if you can define your functions so that they suggest the correct inductions to ACL2, so much the better! But for complicated inductions, induction [hints] are crucial. See [hints] for a description of [47m:induct[0m [hints]. [31;1mC4. Use the interactive ``Proof-Builder'' to explore.[0m The [47m[verify][0m command supplied by ACL2 allows one to explore problem areas ``by hand.'' However, even if you succeed in proving a conjecture with [47m[verify][0m, it is useful to prove it without using it, an activity that will often require the discovery of [rewrite] rules that will be useful in later proofs as well. [31;1mC5. Don't have too much patience.[0m Interrupt the prover fairly quickly when simplification isn't succeeding. [31;1mC6. Simplify rewrite rules.[0m When it looks difficult to relieve the hypotheses of an existing [rewrite] rule that ``should'' apply in a given setting, ask yourself if you can eliminate a hypothesis from the existing [rewrite] rule. If so, it may be easier to prove the new version from the old version (and some additional lemmas), rather than to start from scratch. [31;1mC7. Deal with base cases first.[0m Try getting past the base case(s) first in a difficult proof by induction. Usually they're easier than the inductive step(s), and rules developed in proving them can be useful in the inductive step(s) too. Moreover, it's pretty common that mistakes in the statement of a theorem show up in the base case(s) of its proof by induction. [31;1mC8. Use[0m [47m:expand[0m [31;1mhints.[0m Consider giving [47m:expand[0m [hints]. These are especially useful when a proof by induction is failing. It's almost always helpful to open up a recursively defined function that is supplying the induction scheme, but sometimes ACL2 is too timid to do so; or perhaps the function in question is [disable]d. [3mD. PERFORMANCE TIPS[0m [31;1mD1. Disable rules.[0m There are a number of instances when it is crucial to [disable] rules, including (often) those named explicitly in [47m:use[0m [hints]. Also, [disable] recursively defined functions for which you can prove what seem to be all the relevant properties. The prover can spend significant time ``behind the scenes'' trying to open up recursively defined functions, where the only visible effect is slowness. [31;1mD2. Turn off the ``break rewrite'' facility.[0m Remember to execute [47m:brr nil[0m after you've finished with the ``break rewrite'' utility (see [break-rewrite]), in order to bring the prover back up to full speed. [3mE. MISCELLANEOUS TIPS AND KNOWLEDGE[0m [31;1mE1. Order of application of rewrite rules.[0m Keep in mind that the most recent [rewrite] rules in the [history] are tried first. [31;1mE2. Relieving hypotheses is not full-blown theorem proving.[0m Relieving hypotheses on [rewrite] rules is done by rewriting and [linear] arithmetic alone, not by case splitting or by other prover processes ``below'' simplification. [31;1mE3. ``Free variables'' in rewrite rules.[0m The set of ``free variables'' of a [rewrite] rule is defined to contain those variables occurring in the rule that do not occur in the left-hand side of the rule. It's often a good idea to avoid rules containing free variables because they are ``weak,'' in the sense that hypotheses containing such variables can generally only be proved when they are ``obviously'' present in the current context. This weakness suggests that it's important to put the most ``interesting'' (specific) hypotheses about free variables first, so that the right instances are considered. For example, suppose you put a very general hypothesis such as [47m(consp x)[0m first. If the context has several [term]s around that are known to be [47m[consp][0ms, then [47mx[0m may be bound to the wrong one of them. For much more information on free variables, see [free-variables]. [31;1mE4. Obtaining information[0m Use [47m:[0m[47m[pl][0m [47mfoo[0m to inspect [rewrite] rules whose left hand sides are applications of the function [47mfoo[0m. Another approach to seeing which [rewrite] rules apply is to enter the interactive [proof-builder] with [47m[verify][0m, and use the [47mshow-rewrites[0m or [47msr[0m command. [31;1mE5. Consider esoteric rules with care.[0m If you care to see [rule-classes] and peruse the list of subtopics (which will be listed right there in most versions of this [documentation]), you'll see that ACL2 supports a wide variety of rules in addition to [47m:[0m[rewrite] rules. Should you use them? This is a complex question that we are not ready to answer with any generality. Our general advice is to avoid relying on such rules as long as you doubt their utility. More specifically: be careful not to use conditional type prescription rules, as these have been known to bring ACL2 to its knees, unless you are conscious that you are doing so and have reason to believe that they are working well. [3mF. SOME THINGS YOU DON'T NEED TO KNOW[0m Most generally: you shouldn't usually need to be able to predict too much about ACL2's behavior. You should mainly just need to be able to react to it. [31;1mF1. Induction heuristics.[0m Although it is often important to read the part of the prover's output that gives the induction scheme chosen by the prover, it is not necessary to understand how the prover made that choice. (Granted, advanced users may occasionally gain minor insight from such knowledge. But it's truly minor in many cases.) What [3mis[0m important is to be able to tell it an appropriate induction when it doesn't pick the right one (after noticing that it doesn't). See C3 above. [31;1mF2. Heuristics for expanding calls of recursively defined functions.[0m As with the previous topic, the important thing isn't to understand these heuristics but, rather, to deal with cases where they don't seem to be working. That amounts to supplying [47m:expand[0m [hints] for those calls that you want opened up, which aren't. See also C8 above. [31;1mF3. The ``waterfall''.[0m As discussed many times already, a good strategy for using ACL2 is to look for checkpoints (goals stable under simplification) when a proof fails, perhaps using the [proof-tree] facility. Thus, it is reasonable to ignore almost all the prover output, and to avoid pondering the meaning of the other ``processes'' that ACL2 uses besides simplification (such as elimination, cross-fertilization, generalization, and elimination of irrelevance).") (to-df (pointers) "See [df].") (to-dfp (pointers) "See [df].") (toggle-inhibit-er (output-controls errors) "Add or delete an error output string from the [47minhibit-er-table[0m See [set-inhibit-er] for relevant background. General Form: (toggle-inhibit-er string) where [47mstring[0m is the name of some error output like [47m"Translate"[0m or [47m"Failure"[0m. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [toggle-inhibit-er!] for a corresponding non-[47m[local][0m event. Indeed, [47m(toggle-inhibit-er str)[0m is equivalent to [47m(local (toggle-inhibit-er! str))[0m. The given string is added to the list of strings used for inhibiting error output if it is not there already and is deleted from the list if it is there. Case is unimportant in [47mstring[0m. See [47m[set-inhibit-er][0m.") (toggle-inhibit-er! (output-controls errors) "Toggle an [47minhibit-er-table[0m entry non-[47m[local][0mly Please see [toggle-inhibit-er], which is the same as [47mtoggle-inhibit-er![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [toggle-inhibit-er] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (toggle-inhibit-warning (output-controls) "Add or delete a warning string from the [47minhibit-warnings-table[0m General Form: (toggle-inhibit-warning string) where [47mstring[0m is the name of some warning like [47m"Subsume"[0m, [47m"Non-rec"[0m or [47m"Rewrite-lambda-object"[0m. Note: This is an event! It does not print the usual event [summary] but nevertheless changes the ACL2 logical [world] and is so recorded. It is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs; see [toggle-inhibit-warning!] for a corresponding non-[47m[local][0m event. Indeed, [47m(toggle-inhibit-warning str)[0m is equivalent to [47m(local (toggle-inhibit-warning! str))[0m. The given string is added to the list of inhibited warnings if it is not there already and is deleted from the list if it is there. Case is unimportant in [47mstring[0m. See [47m[set-inhibit-warnings][0m.") (toggle-inhibit-warning! (output-controls) "Toggle an [47minhibit-warnings-table[0m entry non-[47m[local][0mly Please see [toggle-inhibit-warning], which is the same as [47mtoggle-inhibit-warning![0m except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it occurs. Probably [toggle-inhibit-warning] is to be preferred unless you have a good reason for wanting to export the effect of this event outside the enclosing [47m[encapsulate][0m or book.") (toggle-pc-macro (proof-builder) "Change an ordinary macro command to an atomic macro, or vice-versa Example: (toggle-pc-macro pro) Change [47mpro[0m from an atomic macro command to an ordinary one (or vice-versa, if [47mpro[0m happens to be an ordinary macro command) General Form: (toggle-pc-macro name &optional new-tp) If name is an atomic macro command then this turns it into an ordinary one, and vice-versa. However, if [47mnew-tp[0m is supplied and not [47mnil[0m, then it should be the new type (the symbol [47mmacro[0m or [47matomic-macro[0m, in any package), or else there is no change.") (too-many-ifs (pointers) "See [efficiency].") (top nil "ACL2 documentation (system only, not including the community books) This is the documentation for the ACL2 system. For the ACL2+Books Manual, which documents both the ACL2 system and the ACL2 [community-books], see the {ACL2+Books Manual | https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}. Subtopics [ACL2] ACL2 system documentation [Books] [3mBooks[0m are files of ACL2 [events]---they are the main way to split up large ACL2 developments into separate modules. [Debugging] Tools for debugging failed or slow proofs, or misbehaving functions. [Documentation] Information about options for downloading and viewing the ACL2 documentation, contributing documentation, and the available tools for documenting your own books. [Interfacing-tools] Libraries and tools for doing basic file i/o (see [STD/IO]), using raw Common Lisp libraries (see [QUICKLISP]), working with the operating system (see [OSLIB]), and interfacing with other programs (see [BRIDGE]).") (top-level (miscellaneous) "Evaluate a top-level form as a function body Some forms, such as calls of [47m[with-local-stobj][0m, are illegal when supplied directly to the ACL2 top-level loop. The macro [47mtop-level[0m provides a workaround in such cases, by defining a temporary [47m:[0m[47m[program][0m-mode function named [47mtop-level-fn[0m whose only argument is [47mstate[0m and whose body is the form to be evaluated. When the call of [47mtop-level[0m returns there is no change to the existing ACL2 logical [world]. The following edited log illustrates all of the above points. ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) ACL2 !>(defstobj st fld) Summary Form: ( DEFSTOBJ ST ...) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) ST ACL2 !>(top-level (with-local-stobj st (mv-let (result st) (let ((st (update-fld 17 st))) (mv (fld st) st)) result))) 17 ACL2 !>(top-level (with-local-stobj st (mv-let (result st) (let ((st (update-fld 17 st))) (mv (fld st) st)) (mv nil result state)))) 17 ACL2 !>(top-level (with-local-stobj st (mv-let (result st) (let ((st (update-fld 17 st))) (mv (fld st) st)) (mv result state)))) (17 <state>) ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) d 1:x(DEFSTOBJ ST FLD) ACL2 !> Each argument of [47mtop-level[0m after the first should be a [47m[declare][0m form or [documentation] string, as the list of these extra arguments will be placed before the first argument when forming the definition of [47mtop-level-fn[0m. [47m[Top-level][0m generates a call of [47m[ld][0m, so that the value returned is printed in the normal way. The call of [47m[top-level][0m itself actually evaluates to [47m(mv erp :invisible state)[0m, where [47merp[0m is [47mt[0m if and only evaluation of the call of [47mtop-level-fn[0m caused an error, which normally results in no additional output. (For details about ``caused an error'', see the definition of [47mtop-level[0m in the ACL2 source code, and see [ld-error-action].) Since the defined function [47mtop-level[0m takes only [47mstate[0m as a parameter, the given form should not include any user-defined [stobj]s that occur free in the form. Finally, note that since [47mtop-level[0m runs a function that is defined in [47m:[0m[47m[program][0m mode, it is possible for a raw lisp error to occur. Here is an example. ACL2 !>(top-level (car 3)) *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: The value 3 is not of the expected type LIST. While executing: CAR ***********************************************") (top-level-loop (pointers) "See [guarantees-of-the-top-level-loop].") (tours (pages_written_especially_for_the_tours acl2-tutorial) "The Tours ACL2 is a very large, multipurpose system. You can use it as a programming language, a specification language, a modeling language, a formal mathematical logic, or a semi-automatic theorem prover, just to name its most common uses. It has been used on a number of industrial applications (see [INTERESTING-APPLICATIONS]). If you're uncertain as to whether your project is appropriate for ACL2 we urge you to look over this list or contact the ACL2 developers. This home page includes all of ACL2's online documentation, which is quite extensive (over 4 megabytes). To help ease your introduction to ACL2, we have built two tours through this documentation. If you are familiar with at least some of the industrial applications (see [INTERESTING-APPLICATIONS]) of ACL2, then you will understand the distance between the simple examples we talk about in these tours and the kinds of things ACL2 users do with the system. Newcomers to ACL2 should first take the ``Flying Tour.'' Then, if you want to know more, take the ``Walking Tour.'' On your first reading, follow the two Tours linearly, clicking only on the icon of the Tour you're on. Beware of other links, which might jump you from one tour to the other or into the ACL2 User's Manual! Once you've had a coherent overview of the system, you might quickly repeat both Tours to see if there are unvisited links you're interested in, using your browser's Back Button to return to your starting points. If after all this you want to learn how to use the theorem prover (!), see [introduction-to-the-theorem-prover]. To start a tour, click on the appropriate icon below. {IMAGE} (see [A_Flying_Tour_of_ACL2]) {IMAGE} (see [A_Walking_Tour_of_ACL2]) If you take the tours in a text-based format (such as using the :DOC command in Emacs), they will probably be unsatisfying because we use gif files and assume you can navigate ``back.''") (trace (debugging) "Tracing functions in ACL2 ACL2 provides a trace utility, [47m[trace$][0m, with corresponding reverse operation [47m[untrace$][0m. These can be used without any dependence on the underlying Lisp utility, and are the tracing utilities of choice in ACL2; see [trace$] and see [untrace$]. However, for advanced users we note that the underlying host Lisp may also provide a trace utility, [47mtrace[0m, and corresponding [47muntrace[0m. Moreover, these have been modified in the case that the host Lisp is GCL, Allegro CL, or CCL (OpenMCL), to provide limited support for [47m:entry[0m, [47m:exit[0m, and perhaps [47m:cond[0m keywords, to hide certain large data structures (world, enabled structure, rewrite constant), and to trace executable-counterparts (see [evaluation]). See source files [47m*-trace.lisp[0m. For the above Lisps, you can invoke the original [47mtrace[0m and [47muntrace[0m by invoking [47mold-trace[0m and [47mold-untrace[0m, respectively, in raw Lisp rather than in the normal ACL2 loop. Subtopics [Break-on-error] Break when encountering a hard or soft error caused by ACL2 [Close-trace-file] Stop redirecting trace output to a file [Open-trace-file] Redirect trace output to a file [Set-trace-evisc-tuple] Set the trace evisc tuple [Trace!] Trace the indicated functions after creating an active trust tag [Trace$] Trace function evaluations [Untrace$] Untrace functions [Wet] Evaluate a form and print subsequent error trace") (trace! (trace) "Trace the indicated functions after creating an active trust tag Example: (trace! (fact :native t :entry *foo*)) General Form: (trace! spec1 ... specn) where the [47mspeci[0m are suitable arguments to [47m[trace$][0m. See [trace$] for a way to trace function calls. Some calls of [47mtrace$[0m are potentially dangerous and thus require a trust tag (see [defttag]). But it can be a nuisance to call [47mdefttag[0m explicitly, so the [47mtrace![0m macro is provided in order to avoid the need to do that: [47mtrace![0m automatically defines a (temporary) trust tag. See [untrace$] for how to undo the effect of [47m[trace!][0m. The evaluation of a [47mtrace![0m form causes temporary creation of an active trust tag, [47m:trace![0m, followed by the corresponding [47mtrace$[0m form. The trust tag will disappear when the call to [47mtrace![0m completes. Even though [47mtrace![0m will remove its temporary ttag, it will still print a ``[47mTTAG NOTE[0m'', which indicates that the session is suspect. See [defttag] and see [ttags-seen] for further remarks on this issue. Because of the active trust tag, it is possible to do things with [47mtrace![0m that are useful but without logical justification. Below is an example of how to use [47mtrace![0m to cause a function call to change [state], even though the function does not take [47m[state][0m as a parameter. Note: It may be helpful to see [evaluation] in order to understand the package prefix [47m"ACL2_*1*_ACL2"[0m displayed below. ACL2 !>(defun fact (n) (declare (xargs :guard (natp n) :verify-guards nil)) (if (zp n) 1 (* n (fact (1- n))))) The admission of FACT is trivial, using the relation O< (which is known to be well-founded on the domain recognized by O-P) and the measure (ACL2-COUNT N). We observe that the type of FACT is described by the theorem (AND (INTEGERP (FACT N)) (< 0 (FACT N))). We used the :compound- recognizer rule ZP-COMPOUND-RECOGNIZER and primitive type reasoning. Summary Form: ( DEFUN FACT ...) Rules: ((:COMPOUND-RECOGNIZER ZP-COMPOUND-RECOGNIZER) (:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 !>(defun update-foo (n value state) (declare (xargs :stobjs state :verify-guards nil)) (assign foo (cons (cons n value) (@ foo)))) Since UPDATE-FOO is non-recursive, its admission is trivial. We observe that the type of UPDATE-FOO is described by the theorem (AND (CONSP (UPDATE-FOO N VALUE STATE)) (TRUE-LISTP (UPDATE-FOO N VALUE STATE))). We used primitive type reasoning. (UPDATE-FOO * * STATE) => (MV * * STATE). Summary Form: ( DEFUN UPDATE-FOO ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) UPDATE-FOO ACL2 !>(trace! (fact :exit (update-foo n value state))) TTAG NOTE: Adding ttag :TRACE! from the top level loop. ((FACT :EXIT (UPDATE-FOO N VALUE STATE))) ACL2 !>(assign foo nil) NIL ACL2 !>(fact 7) 1> (ACL2_*1*_ACL2::FACT 7) 2> (ACL2_*1*_ACL2::FACT 6) 3> (ACL2_*1*_ACL2::FACT 5) 4> (ACL2_*1*_ACL2::FACT 4) 5> (ACL2_*1*_ACL2::FACT 3) 6> (ACL2_*1*_ACL2::FACT 2) 7> (ACL2_*1*_ACL2::FACT 1) 8> (ACL2_*1*_ACL2::FACT 0) <8 NIL <7 NIL <6 NIL <5 NIL <4 NIL <3 NIL <2 NIL <1 NIL 5040 ACL2 !>(@ foo) ((7 . 5040) (6 . 720) (5 . 120) (4 . 24) (3 . 6) (2 . 2) (1 . 1) (0 . 1)) ACL2 !>(verify-guards fact) Computing the guard conjecture for FACT.... The guard conjecture for FACT is trivial to prove, given the :compound- recognizer rules NATP-COMPOUND-RECOGNIZER and ZP-COMPOUND-RECOGNIZER, primitive type reasoning and the :type-prescription rule FACT. FACT is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS FACT) Rules: ((:COMPOUND-RECOGNIZER NATP-COMPOUND-RECOGNIZER) (:COMPOUND-RECOGNIZER ZP-COMPOUND-RECOGNIZER) (:FAKE-RUNE-FOR-TYPE-SET NIL) (:TYPE-PRESCRIPTION FACT)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) FACT ACL2 !>(assign foo nil) NIL ACL2 !>(fact 7) 1> (ACL2_*1*_ACL2::FACT 7) 2> (FACT 7) 3> (FACT 6) 4> (FACT 5) 5> (FACT 4) 6> (FACT 3) 7> (FACT 2) 8> (FACT 1) 9> (FACT 0) <9 NIL <8 NIL <7 NIL <6 NIL <5 NIL <4 NIL <3 NIL <2 NIL <1 NIL 5040 ACL2 !>(@ foo) ((7 . 5040) (7 . 5040) (6 . 720) (5 . 120) (4 . 24) (3 . 6) (2 . 2) (1 . 1) (0 . 1)) ACL2 !>(trace! (fact :exit (progn (update-foo n value state) (cons traced-fn values)))) TTAG NOTE: Adding ttag :TRACE! from the top level loop. ((FACT :EXIT (PROGN (UPDATE-FOO N VALUE STATE) (CONS TRACED-FN VALUES)))) ACL2 !>(assign foo nil) NIL ACL2 !>(fact 7) 1> (ACL2_*1*_ACL2::FACT 7) 2> (FACT 7) 3> (FACT 6) 4> (FACT 5) 5> (FACT 4) 6> (FACT 3) 7> (FACT 2) 8> (FACT 1) 9> (FACT 0) <9 (FACT 1) <8 (FACT 1) <7 (FACT 2) <6 (FACT 6) <5 (FACT 24) <4 (FACT 120) <3 (FACT 720) <2 (FACT 5040) <1 (ACL2_*1*_ACL2::FACT 5040) 5040 ACL2 !>(@ foo) ((7 . 5040) (7 . 5040) (6 . 720) (5 . 120) (4 . 24) (3 . 6) (2 . 2) (1 . 1) (0 . 1)) ACL2 !>") (trace$ (trace) "Trace function evaluations Examples: (trace$ foo bar) ; trace foo and bar (trace$) ; return current trace info (no new tracing specified) (trace$ (foo :entry ; trace foo, printing first actual parameter upon entry (car arglist))) (trace$ (foo :exit ; trace foo, using fmt to print upon exit (:fmt (msg "Exiting FOO with ~x0" value)))) (trace$ (foo :native t)) General Forms: (trace$ spec1 spec2 ... specn) ; n >= 1 (trace$) where the [47mspeci[0m are trace specs, as described below. [47mTrace$[0m installs alternate code for the indicated functions that prints information upon entry to, and exit from, calls of the functions. For an alternate tracing utility used for educational purposes in ACL2s (see [ACL2-SEDAN]), see community book [47mbooks/misc/trace-star.lisp[0m. From a logical perspective all trace printing is a fiction. (But see [trace!] for a way to get around this and modify [state].) For a related fiction, see [cw]. [47m(Trace$)[0m returns the list of currently-active trace specs, while the application of [47mtrace$[0m to at least one argument returns the list of its arguments that are successfully acted on. Output from [47m[trace$][0m normally goes to the screen, i.e., to [47m[standard-co][0m. But it can be redirected to a file; see [trace-co]. See [untrace$] for how to undo the effect of [47m[trace$][0m. Also see [trace] for mention of modifications made to raw Lisp trace, which is accessible (as described below) using the [47m:native[0m keyword. Note that when [47mtrace$[0m is applied to a function without option [47m:native[0m, that function's declarations and documentation are discarded. Next, we introduce tracing with some examples. After that, we provide reference documentation for individual trace options allowed in a trace spec. Note that although our example focuses on user-defined functions, [47mtrace$[0m can also be applied to built-in functions, though perhaps only system hackers should take advantage of this observation. We begin by illustrating the simplest sort of trace spec: a function symbol. For example, the form [47m(trace$ foo bar)[0m directs the tracing of functions [47mfoo[0m and [47mbar[0m by virtue of the two trace specs [47mfoo[0m and [47mbar[0m. We can see tracing in action by first defining: (defun f (x) (cons x x)) (defun g (x) (list (f x) 3)) The following log then illustrates tracing of these two functions. Notice that before [guard]s have been verified, the ``executable-counterpart functions'' are called but the corresponding submitted functions are not (see [evaluation] for relevant background); but after guard verification of [47mf[0m, the submitted function for [47mf[0m is indeed called. (See [guard] and see [guard-evaluation-examples-log].) ACL2 !>(trace$ f g) ((F) (G)) ACL2 !>(g 7) 1> (ACL2_*1*_ACL2::G 7) 2> (ACL2_*1*_ACL2::F 7) <2 (ACL2_*1*_ACL2::F (7 . 7)) <1 (ACL2_*1*_ACL2::G ((7 . 7) 3)) ((7 . 7) 3) ACL2 !>(verify-guards f) Computing the guard conjecture for F.... The guard conjecture for F is trivial to prove. F is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS F) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) F ACL2 !>(g 7) 1> (ACL2_*1*_ACL2::G 7) 2> (ACL2_*1*_ACL2::F 7) 3> (F 7) <3 (F (7 . 7)) <2 (ACL2_*1*_ACL2::F (7 . 7)) <1 (ACL2_*1*_ACL2::G ((7 . 7) 3)) ((7 . 7) 3) ACL2 !> The following example introduces trace specs other than function symbols. Consider the following definition. (defun fact (n) (declare (xargs :guard (natp n))) (if (zp n) 1 (* n (fact (1- n))))) The following log illustrates the use of trace options [47m:cond[0m (condition for entering trace), [47m:entry[0m (what to print on entry), and [47m:exit[0m (what to print on exit). The reason for two calls on argument 4 is that we are seeing such calls for the executable-counterpart of [47mfact[0m and also its raw Lisp function. ACL2 !>(trace$ (fact :cond (evenp (car arglist)) :entry (cons 'factorial-call arglist) :exit (car values))) ((FACT :COND (EVENP (CAR ARGLIST)) :ENTRY (CONS 'FACTORIAL-CALL ARGLIST) :EXIT (CAR VALUES))) ACL2 !>(fact 4) 1> (FACTORIAL-CALL 4) 2> (FACTORIAL-CALL 4) 3> (FACTORIAL-CALL 2) 4> (FACTORIAL-CALL 0) <4 1 <3 2 <2 24 <1 24 24 ACL2 !> Notice that [47mVALUES[0m above is the list of all values returned, which is a one-element list unless [47m[mv][0m return is used, as illustrated in the following example, after defining: [47m(defun two-vals (x) (mv x 7))[0m. ACL2 !>(trace$ two-vals) ((TWO-VALS)) ACL2 !>(two-vals 3) 1> (ACL2_*1*_ACL2::TWO-VALS 3) <1 (ACL2_*1*_ACL2::TWO-VALS 3 7) (3 7) ACL2 !>(verify-guards two-vals) Computing the guard conjecture for TWO-VALS.... The guard conjecture for TWO-VALS is trivial to prove, given the :executable- counterpart of CONS. TWO-VALS is compliant with Common Lisp. Summary Form: ( VERIFY-GUARDS TWO-VALS) Rules: ((:EXECUTABLE-COUNTERPART CONS)) Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) TWO-VALS ACL2 !>(two-vals 3) 1> (ACL2_*1*_ACL2::TWO-VALS 3) 2> (TWO-VALS 3) <2 (TWO-VALS 3 7) <1 (ACL2_*1*_ACL2::TWO-VALS 3 7) (3 7) ACL2 !> We now document all of the options that may appear in a trace spec. A trace spec with options is of the form (fn :kwd1 val1 :kwd2 val2 ... :kwdn valn) and here we document each legal keyword [47m:kwdi[0m and corresponding expected value [47mvali[0m. Note that [47mtrace$[0m is intended primarily for functions defined in the ACL2 command loop (see [lp]). If you want to trace a function that is defined in raw Lisp, then you can use option [47m:native[0m (see below), but then many other [47mtrace$[0m options will not be available to you: all of them except [47m:multiplicity[0m and [47m:native[0m itself will be passed, as described below, to the [47mtrace[0m utility of the underlying Common Lisp. [47m:COND[0m, [47m:ENTRY[0m, and [47m:EXIT[0m Introduction For each of these three options, the value is a (user-level) term, except that for [47m:entry[0m and [47m:exit[0m the value can be of the form [47m(:fmt u)[0m or [47m(:fmt! u)[0m, where [47mu[0m is a user-level term. We skip these two latter cases for now and return to them later. Then the indicated term is evaluated as indicated in the next paragraph, and if the [47m:cond[0m term is omitted or evaluates to non-[47mnil[0m, then the value of the [47m:entry[0m term is printed on entry and the value of the [47m:exit[0m term is printed on exit. By default, where [47m:entry[0m is omitted or is specified as [47mnil[0m, the value printed for [47m:entry[0m is the list obtained by consing the calling function symbol onto the list of actual parameters: in the notation described below, this is [47m(cons TRACED-FN ARGLIST)[0m. Similarly, the default for printing at the exit of the function call, i.e. where [47m:exit[0m is omitted or is specified as [47mnil[0m, is [47m(cons TRACED-FN VALUES)[0m where [47mVALUES[0m is the list of values returned as described below. Available Variables NOTE. The symbols mentioned below, for example [47mARGLIST[0m, are all in the [47m"ACL2"[0m package. If you are in another package you may need an [47m"ACL2::"[0m package prefix, e.g., [47mACL2::ARGLIST[0m. In the evaluations of the term described below upon a call of [47mfn[0m, each formal parameter of the definition of [47mfn[0m will be bound to the corresponding actual of the call, the variable [47mARGLIST[0m will be bound to the list of actuals, and the variable [47mTRACED-FN[0m will be bound to the function being called (either [47mfn[0m or its executable-counterpart function; see above). Additionally in the case of [47m:exit[0m, the variable [47mVALUES[0m will be bound to the multiple values returned (thus, a one-element list if [47m[mv][0m is not used in the return). Also for [47m:exit[0m, we bind [47mVALUE[0m to the logical value returned, i.e., to the suitable list of values returned in the [47m[mv][0m case and otherwise to the single value returned. So in the [47mmv[0m case, [47mVALUE[0m is the same as [47mVALUES[0m, and otherwise [47mVALUE[0m is [47m(car VALUES)[0m. Finally, the variable [47mTRACE-LEVEL[0m will be bound to the level, or depth, of tracing; that is, the number printed at entry and exit (e.g., 3 in [47m`3>'[0m and [47m`<3'[0m). Other than these variables and [47m[state][0m, no other variable may occur in the term, whose value must be a single non-[47m[stobj][0m value, unless there is an active trust tag (see [defttag]). Basic Options Now suppose [47mfn[0m is called. First: If [47m:cond[0m is supplied and the result of evaluating the [47m:cond[0m term is [47mnil[0m, then no tracing is done. Otherwise tracing proceeds as follows. First the [47m:entry[0m form is evaluated, and the result is printed. Then the call of [47mfn[0m is evaluated. Finally the [47m:exit[0m term is evaluated and the result is printed. As indicated above, the default for the [47m:entry[0m term if omitted or explicitly [47mnil[0m is [47m(cons TRACED-FN ARGLIST)[0m, and the default for the [47m:exit[0m term if omitted or explicitly [47mnil[0m is [47m(cons TRACED-FN VALUES)[0m. Note that if the function has a formal named [47mARGLIST[0m, then [47mARGLIST[0m will nevertheless refer to the entire list of formals, not the single formal named [47mARGLIST[0m; similarly for [47mTRACED-FN[0m, and additionally for [47mVALUE[0m and [47mVALUES[0m in the case of [47m:exit[0m. As mentioned above, for each of [47m:entry[0m and [47m:exit[0m, a value of [47mnil[0m specifies the default behavior. If you really want a value of [47mnil[0m, use a non-[47mnil[0m form that evaluates to [47mnil[0m, for example [47m(car nil)[0m or [47m'nil[0m. However, for [47m:cond[0m a value of [47mnil[0m means what it says: do not evaluate the [47m:entry[0m or [47m:exit[0m forms. Finally we discuss the case that the [47m:entry[0m or [47m:exit[0m term is of the form [47m(:fmt u)[0m or [47m(:fmt! u)[0m. In these cases, the term [47mu[0m is evaluated as described above to produce a value, say [47mmsg[0m, but instead of printing [47mmsg[0m directly, ACL2 calls [47mfmt1[0m using the string [47m"~@0"[0m and the alist that binds just character [47m#\0[0m to [47mmsg[0m. The following example illustrates this point, where [47mfact[0m is defined as above. Also see [fmt]. Note that [47m(msg string . vals)[0m produces a value suitable for a [47m"~@"[0m directive to the [47mfmt[0m family of print functions. ACL2 !>(trace$ (fact :entry (:fmt (msg "Tracing ~x0 on ~x1" traced-fn arglist)) :exit (car values))) ((FACT :ENTRY (:FMT (MSG "Tracing ~x0 on ~x1" TRACED-FN ARGLIST)) :EXIT (CAR VALUES))) ACL2 !>(fact 3) 1> Tracing ACL2_*1*_ACL2::FACT on (3) 2> Tracing FACT on (3) 3> Tracing FACT on (2) 4> Tracing FACT on (1) 5> Tracing FACT on (0) <5 1 <4 1 <3 2 <2 6 <1 6 6 ACL2 !> If [47m:fmt![0m is used instead of [47m:fmt[0m, then indentation as is the prefix string, [47m"n> "[0m or [47m"<n "[0m. The following example illustrates the use of [47m:fmt![0m. ACL2 !>(trace$ (fact :entry (:fmt! (msg "Tracing ~x0 on ~x1" traced-fn arglist)) :exit (:fmt! (msg "From input ~x0: ~x1" (car arglist) (car values))))) ((FACT :ENTRY (:FMT! (MSG "Tracing ~x0 on ~x1" TRACED-FN ARGLIST)) :EXIT (:FMT! (MSG "From input ~x0: ~x1" (CAR ARGLIST) (CAR VALUES))))) ACL2 !>(fact 3) Tracing ACL2_*1*_ACL2::FACT on (3) Tracing FACT on (3) Tracing FACT on (2) Tracing FACT on (1) Tracing FACT on (0) From input 0: 1 From input 1: 1 From input 2: 2 From input 3: 6 From input 3: 6 6 ACL2 !> Here is the same example, with user-managed indentation. ACL2 !>(trace$ (fact :entry (:fmt! (msg "~t0Tracing ~x1 on ~x2" (+ 3 (* 2 trace-level)) traced-fn arglist)) :exit (:fmt! (msg "~t0From input ~x1: ~x2" (1+ (* 2 trace-level)) (car arglist) (car values))))) ((FACT :ENTRY (:FMT! (MSG "~t0Tracing ~x1 on ~x2" (+ 3 (* 2 TRACE-LEVEL)) TRACED-FN ARGLIST)) :EXIT (:FMT! (MSG "~t0From input ~x1: ~x2" (1+ (* 2 TRACE-LEVEL)) (CAR ARGLIST) (CAR VALUES))))) ACL2 !>(fact 3) Tracing ACL2_*1*_ACL2::FACT on (3) Tracing FACT on (3) Tracing FACT on (2) Tracing FACT on (1) Tracing FACT on (0) From input 0: 1 From input 1: 1 From input 2: 2 From input 3: 6 From input 3: 6 6 ACL2 !> Advanced Options (alphabetical list) [47m:COMPILE[0m The tracing of [47mfn[0m installs a substitute definition of [47mfn[0m that prints trace information. If the [47m:compile[0m option is omitted or has value [47m:same[0m, then the new definition will be compiled if and only if the existing definition is already compiled. Otherwise, the new definition will be compiled exactly when the value of [47m:compile[0m is not [47mnil[0m. [47m:DEF[0m, [47m:MULTIPLICITY[0m ACL2's [47mtrace$[0m mechanism often needs to know the number of outputs of a traced function, in the sense of [47m[mv][0m. If you provide an alternative definition using option [47m:def[0m (see below) and the new definition changes the number of values returned, then a natural number value for [47m:multiplicity[0m informs the trace utility of the number of expected outputs of the function being traced. In the case that [47m:native[0m is supplied, the [47m:multiplicity[0m option is ignored. For GCL and Allegro CL, [47m:multiplicity[0m is used to generate a suitable [47m:exit[0m form if the [47m:exit[0m keyword was not already supplied. For the other Lisps, the [47m:multiplicity[0m value is treated essentially as 1 whether it is supplied or not, because we do not know how to pass suitable information based on this value to the host Lisp's built-in tracing mechanism. Note that even supplying a [47m:multiplicity[0m option does not change the meaning of the variable [47mvalues[0m. See the discussion of [47m:native[0m below. A useful option can be to supply a definition as the value of [47m:def[0m. (Again, note that if [47m:native[0m is used, then all options other than [47m:multiplicity[0m are passed to the trace utility of the underlying Lisp; in particular, [47m:def[0m will have no effect with [47m:native[0m except in the unlikely case that the raw Lisp provides some sort of support for [47m:def[0m.) Note that this definition should be like a [47m[defun][0m form, but without the leading [47mdefun[0m symbol; and it should define the function symbol being traced, with the same formal parameter list. However, tracing of the ``executable-counterpart'' of a function (see [evaluation] is not sensitive to the [47m:def[0m option; rather, if a function has an executable-counterpart then that executable-counterpart is traced. [47m:EVISC-TUPLE[0m The printing described above is, by default, done using the current default trace evisc-tuple, which can be set using [47m[set-trace-evisc-tuple][0m (for the shape of this tuple, see [evisc-tuple]); see [set-trace-evisc-tuple]. This tuple is based by default on the raw Lisp variables [47m*print-level*[0m and [47m*print-length*[0m, and will hide the ACL2 [world] and handle [stobj]s appropriately. You may override this default by supplying an evisc tuple with the [47m:evisc-tuple[0m argument in your trace spec. Be careful to supply a valid evisc-tuple, or you may get a raw Lisp error! A special value, [47m:print[0m, is useful if you are doing system hacking that can produce objects that are not valid ACL2 objects, such as raw Lisp arrays or objects in supporting packages not visible in the ACL2 read-eval-print loop. If you supply [47m:evisc-tuple :print[0m, then the printing described above will be done with raw Lisp printing rather than ACL2 printing. Note that [stobj]s will be printed as vectors (rather than their usual hiding with symbols such as [47m<st>[0m) when using [47m:evisc-tuple :print[0m, but other structures will still be hidden unless [47m:hide nil[0m is supplied. A second special value for [47m:evisc-tuple[0m, [47m:no-print[0m, avoids printing the values of the [47m:entry[0m and [47m:exit[0m forms (or their defaults, if not specified). This option is of use for side effects; for an example see community book [47mbooks/misc/wet.lisp[0m. Note that if [47m:evisc-tuple X[0m is supplied, then the form [47mX[0m will be evaluated before the function body is entered. You can thus pull some tricks to print extra information before the [47m:entry[0m form is evaluated, for example as follows for a factorial function, [47mfact[0m. ACL2 !>(trace$ (fact :evisc-tuple (prog2$ (cw "~|**** HERE IS CW ****~|") nil))) ((FACT :EVISC-TUPLE (PROG2$ (CW "~|**** HERE IS CW ****~|") NIL))) ACL2 !>(fact 3) **** HERE IS CW **** 1> (ACL2_*1*_ACL2::FACT 3) **** HERE IS CW **** 2> (ACL2_*1*_ACL2::FACT 2) **** HERE IS CW **** 3> (ACL2_*1*_ACL2::FACT 1) **** HERE IS CW **** 4> (ACL2_*1*_ACL2::FACT 0) <4 (ACL2_*1*_ACL2::FACT 1) <3 (ACL2_*1*_ACL2::FACT 1) <2 (ACL2_*1*_ACL2::FACT 2) <1 (ACL2_*1*_ACL2::FACT 6) 6 ACL2 !> [47m:FORMALS[0m Normally ACL2 can figure out the formals for a given function. This is always the case for functions defined in the ACL2 command loop and when option [47m:def[0m is supplied. If neither of these cases applies then you can still trace a function (even without using the [47m:native[0m option) by supplying option [47m:notinline :fncall[0m, but you will still need to supply the list of formal parameters. The value of the [47m:formals[0m option should be the list of formals in this case. [47m:HIDE[0m The default value for this advanced option is [47mt[0m, which causes [stobj]s and the logical [world] to be printed as single symbols, along with certain large structures of interest to developers (rewrite constants, enabled structures, and event and command index structures). (For an exception regarding stobjs, see the discussion of [47m:evisc-tuple :print[0m above.) If however the value [47mnil[0m is supplied, then this default behavior is defeated. In that case, you can still arrange to print the logical world as a symbol and to print [stobj]s without breaking the trace printing: see [set-trace-evisc-tuple] for how to do this globally, or similarly use the [47m:evisc-tuple[0m option to [47mtrace$[0m to do this with a single trace spec. Note however that with value [47mnil[0m specified for [47m:hide[0m, such use of an evisc-tuple will not deal properly with local stobjs (see [with-local-stobj]) or stobjs bound by [47m[stobj-let][0m, or with the aforementioned large structures other than the logical [world]. [47m:NATIVE[0m If [47m:native[0m is supplied with a non-[47mnil[0m value, then the trace spec is passed to the native Lisp trace (after removing the [47m:native[0m and [47m:multiplicity[0m options). Each trace spec generates its own call of Lisp [47mtrace[0m: directly in most cases, but if SBCL is the host Lisp then the SBCL [47mtrace[0m syntax is accommodated by placing the the function symbol last, after any keyword options. A trust tag (see [defttag]) is required in order to use the [47m:native[0m option, because arbitrary raw Lisp may be executed by the options! Note that by ``native Lisp trace'' we mean the currently installed [47mtrace[0m. As discussed briefly elsewhere (see [trace]), ACL2 has modified that trace to be more useful if the underlying host Lisp is GCL, Allegro CL, or CCL. If you need the original trace utility supplied for those Lisps, quit the ACL2 loop with [47m:q[0m and call [47mold-trace[0m and [47mold-untrace[0m in raw Lisp where you would otherwise call [47mtrace[0m and [47muntrace[0m. Note that the original trace utility supplied with a given Lisp will not hide the ACL2 logical [world] or give special treatment to [stobj]s. It is important to understand that if [47m:native t[0m is specified, then all other options are interpreted by the native Lisp trace. For example, that trace probably has no understanding of the use of [47m:fmt[0m described above for [47m:entry[0m or [47m:exit[0m. Indeed, the native trace may not even accept any of [47m:cond[0m, [47m:entry[0m or [47m:exit[0m, let alone any of the advanced options! (But it may accept many options that are not available with the non-native ACL2 [47mtrace$[0m.) [47m:NOTINLINE[0m By default, a new definition installed by [47mtrace$[0m will include a [47mnotinline[0m declaration so that recursive calls will always be traced. (But see Remark (0) below for an exception involving [invariant-risk].) To avoid this declaration, supply value [47mnil[0m. A special value for [47m:notinline[0m, [47m:fncall[0m, will cause the traced function to call its original definition. Without this special value, the new installed definition for the traced function will include the body of the original definition. This [47m:fncall[0m behavior is the default only in the following cases: * for functions whose definitions are built into ACL2; * for functions that have been added (using a trust tag, an advanced feature, so most users can probably ignore this case) to either of the [47m[state][0m global variables [47mprogram-fns-with-raw-code[0m or [47mlogic-fns-with-raw-code[0m; * for [47m[memoize][0md functions. The legal values for [47m:notinline[0m are [47mt[0m (the default for other than the cases displayed above), [47mnil[0m, and [47m:fncall[0m. Remarks (0) For a [47m:[0m[47m[program][0m mode function with [invariant-risk], recursive calls are never traced. To see these recursive calls, use one of the two methods to defeat invariant-risk checking; see [invariant-risk]. (Implementation note: This behavior on recursive calls is a consequence of how ACL2 defines the executable-counterpart --- also known as the ``*1* function'' (see [evaluation]) --- to call a local function to do the computation.) (1) If some of the given trace specs have errors, then [47mtrace$[0m will generally print error messages for those but will still process those that do not have errors. The value returned will indicate the trace specs that were processed successfully. (2) If you certify or include a book that redundantly defines a function that is currently traced, then tracing behavior may disappear if a compiled definition is installed for the submitted function or its executable-counterpart (see [evaluation] for relevant background). (3) Some predefined functions are called during tracing. In order to avoid infinite loops, such calls of traced predefined functions will be made using the original predefined functions, not using their code installed by [47mtrace$[0m. (4) For a [wormhole] such as the [break-rewrite] loop, all calls of [47mtrace$[0m and [47m[untrace$][0m inside that wormhole are undone upon exit from the wormhole. In particular, if you trace or untrace a function during a [47m[brr][0m break, then effects of that trace or untrace will disappear when you proceed using a keyword such as [47m:eval[0m or [47m:go[0m.") (trace-co (io acl2-built-ins) "The [trace] character output channel See [io] for relevant background. [47m(Trace-co state)[0m is an open character output channel. [Trace] output is printed to this channel. Evaluate [47m(set-trace-co CHAN state)[0m to set [47m(Trace-co state)[0m to the channel, [47mCHAN[0m. ``Trace-co'' stands for ``trace character output.'' The initial value of [47mtrace-co[0m is the same as the value of [47m[*standard-co*][0m.") (trans (macros) "Print the translation of a form Examples: :trans (list a b c) :trans (caddr x) :trans (cond (p q) (r)) ACL2 accepts user-level syntax as input, and it prints the result of [3mtranslating[0m it to an internal syntax. This translation includes macroexpansion, replacing [47m[let][0m forms by [47m[lambda][0m expressions, quoting constants, and so on. See [term] for relevant background. The printing can be abbreviated, as it uses the [47m:term[0m [evisc-tuple] (with a [47mflg[0m of [47mnil[0m, hence without any abbreviation by default; see [set-evisc-tuple]). Note that the [47mtrans[0m command prints a [47m[term][0m that need not obey code restrictions: that term can be used in theorems but might not be allowed in definitions (except in [non-executable] contexts; see [defun-nx] and see [non-exec]). [47mTrans[0m takes one argument, an alleged term in user syntax, and translates it, expanding the macros in it completely. Either an error is caused or the internal syntax for the term (representing its formal meaning) is printed. It also prints the ``output signature'' which indicates how many results are returned and which are single-threaded objects. For example, a term that returns one ordinary object (e.g., an object other than [47m[state][0m or a user-defined single-threaded object (see [defstobj])) has the output signature => * A term that returns the single-threaded object [47mSTATE[0m has the output signature => STATE and a term that returns four results might have the output signature => (MV $MEM * * STATE) This signature indicates that the first result is the (user defined) single-threaded object [47m$MEM[0m, that the next two results are ordinary, and that the last result is [47mSTATE[0m. See [trans!] for a corresponding command that does not enforce restrictions of single-threaded objects. See [trans*] for a command that can show intermediate expansion results. The argument supplied to [47m:trans[0m may contain variables, including [stobj] names. However, variables that are not stobj names are assumed not to be dfs (see [df]). For example, [47m:trans (df+ x y)[0m causes an error; to see the desired translation use [47m:trans! (df+ x y)[0m. It is sometimes more convenient to use [47m:[0m[47m[trans1][0m, which, unlike [47m:trans[0m, only does top-level macroexpansion. For more, see [term].") (trans! (macros) "Print the translation without code restrictions on the input Examples: :trans! (list a b c) :trans! (append x state) :trans! (cons (mv 3 4) x) [47m:Trans![0m is identical to [47m:[0m[47m[trans][0m, except that [47m:trans![0m is more permissive: it allows expressions that may occur in theorems but are illegal in code. In particular, [47m:trans![0m allows violations of single-threadedness and multiple-value restrictions. Thus, the second and third forms above are legal for [47m:trans![0m even though they are illegal for [47m:trans[0m. Also see [trans], see [trans1], and see [trans*].") (trans* (macros) "Show intermediate expansion results for the translation of a form See [term] for background on translated and untranslated terms. See [trans], [trans!], and [47m[trans1][0m for other utilities that expand and translate their input. Unlike [47mtrans[0m, the [47mtrans*[0m command can print not only the translation of a given expression but also the intermediate expansions leading to that translation, and [47mtrans*[0m can also print [47m[make-event][0m expansions. Another difference between [47mtrans*[0m and [47mtrans[0m is that [47mtrans*[0m does not enforce code restrictions; thus, multiple-value mismatches and violations of single-threadedness are permitted by [47mtrans*[0m. That is: when [47mtrans*[0m takes steps to convert an untranslated term to a translated term, it does so as though one is translating a theorem statement, not a definition body. But like [47mtrans[0m, the [47mtrans*[0m command prints [47m[term][0ms that need not obey code restrictions: they can be used in theorems but might not be allowed in definitions (except in [non-executable] contexts; see [defun-nx] and see [non-exec]). Also like [47mtrans[0m, the printing uses the [47m:term[0m [evisc-tuple] (with a [47mflg[0m of [47mnil[0m, hence without any abbreviation by default; see [set-evisc-tuple]). For discussion of how one may use a keyword command like [47m:trans*[0m in place of calling the corresponding utility, in this case [47mtrans*[0m, see [keyword-commands]. Below we focus on the use of the keyword command, [47m:trans*[0m. We begin with some simple examples that may suffice to explain how to use [47mtrans*[0m. We then document this utility before concluding with further details. Introductory Examples The examples below assume that the following definition has been submitted. (defmacro mac (x y) `(append ,y (rest ,x))) Here is a log showing a typical use of [47m:trans*[0m; comments are below. ACL2 !>:trans* t (mac u v) Iteration 1 produces (by expansion): (APPEND V (REST U)) ---------- Iteration 2 produces (by expansion): (BINARY-APPEND V (REST U)) ---------- Iteration 3 produces (by translation): (BINARY-APPEND V (CDR U)) ---------- ACL2 !> We see that Iteration 1 expands away the call of the macro, [47mmac[0m. The next iteration expands away the resulting call of the macro, [47mappend[0m. Those two steps are labeled with ``(by expansion)'' because they are removing top-level macro calls. The result of the second iteration is not a macro call, so [47m:trans*[0m finishes up by translating that result to obtain the final result; notice translation of the second argument of the [47mbinary-append[0m call by expanding [47m[rest][0m to [47m[cdr][0m. The example above illustrates a couple of aspects of [47m:trans*[0m. * An expansion step occurs only with a top-level macro call. * A translation step is always last. The result is the same for input [47m:trans* 3 (mac u v)[0m, i.e., if first argument [47mt[0m is replaced by [47m3[0m or, in fact, any integer that is at least the total number of iterations produced with argument [47mt[0m. But we can specify that we want to stop before the final step. One way is to specify a number less than the number of iterations. Here is what we get when we specify that we should stop after 1 iteration. ACL2 !>:trans* 1 (mac u v) Iteration 1 produces (by expansion): (APPEND V (REST U)) ---------- ACL2 !> Another way to stop early is to rule out the final translation step. Here is an example by using [47mnil[0m or a negative integer as the first argument. ACL2 !>:trans* -5 (mac u v) ; same for nil, -2, -3, -4, etc. instead of -5 Iteration 1 produces (by expansion): (APPEND V (REST U)) ---------- Iteration 2 produces (by expansion): (BINARY-APPEND V (REST U)) ---------- ACL2 !> If you are only interested in obtaining the final result, with no intermediate printing, put parentheses around the first argument. Here is what happens when we make that modification to the example immediately above. ACL2 !>:trans* (-5) (mac u v) ; same answer for nil, -2, -3, etc instead of -5 (BINARY-APPEND V (REST U)) ACL2 !> Note the single space of indentation in the result above. That indicates that what is actually returned is multiple values, [47m(mv nil (BINARY-APPEND V (REST U)) state)[0m. Without the parentheses, [47m(mv nil :invisible state)[0m is returned. See [error-triple]. Documentation General Forms: :trans t form :trans nil form :trans n form :trans -n form :trans (x) form ; for x = t, nil, n, or -n where [47mn[0m is a positive integer and [47mform[0m is any ACL2 expression (i.e., any untranslated term; see [term]). These commands repeat translation steps as described later below, according to the value of the first argument, as follows. * [47mt[0m: iterate to completion, printing intermediate results * [47mnil[0m: iterate to completion except for skipping the final translation step, printing intermediate results * [47mn[0m: iterate at most [47mn[0m steps, printing intermediate results * [47m-n[0m: iterate at most [47mn[0m steps except for skipping a final translation step, printing intermediate results * [47m(x)[0m: same as [47mx[0m but without printing intermediate results, and returning an [error-triple] [47m(mv nil val state)[0m where [47mval[0m is the final result, It is reasonable to think of a first argument of [47mt[0m as ``infinity'' and of [47mnil[0m as ``minus infinity''. Although a first argument of [47m(t)[0m is much like using [47m[trans][0m, key differences besides enforcement of code restrictions (as discussed above) are that [47mtrans*[0m performs [47m[make-event][0m expansion and discards certain ``wrappers'' like [47m[with-output][0m, as described below. The related utility [47m[trans*-][0m differs from [47mtrans*[0m in only one way: [47mtrans*-[0m does not perform [47mmake-event[0m expansion. Here is a specification of the iteration step performed on a given form, which is initially the second argument of [47mtrans*[0m and is updated by each iteration. If the form is not a true-list then iteration halts without any further result. Otherwise the form may be written as a call [47m(caller arg1 ... argk)[0m, and the next step's result, if any, depends on [47mcaller[0m as follows. * If [47mcaller[0m is in the list of ``event wrappers'', [47m(local skip-proofs with-cbd with-current-package with-guard-checking-event with-output with-prover-step-limit with-prover-time-limit)[0m, then the next step's result is the last argument of the call, denoted [47margk[0m above. * Else if [47mcaller[0m is [47m[make-event][0m, the result is the form's [47mmake-event[0m expansion. (This step is skipped when [47m[trans*-][0m is used rather than [47mtrans*[0m.) * Else if [47mcaller[0m is a built-in event constructor such as [47m[defun][0m or [47m[defthm][0m, or one of [47m[certify-book][0m, [47m[defpkg][0m, or [47m[in-package][0m, then iteration is halted. (Technical note: The actual test used here is whether [47mcaller[0m is a key of the alist value of the constant, [47m*syms-not-callable-in-code-fal*[0m.) * Else if [47mcaller[0m is a macro, expand the macro call. * Otherwise translate the form, except that as noted above, if the first argument of [47mtrans*[0m is [47mnil[0m or a negative integer, then this step is skipped and instead iteration is halted. Further Details While [47mtrans*[0m will almost always determine accurately how the given input expands and is ultimately translated, it is not quite 100% reliable for that purpose. In particular, [47mmake-event[0m expansion isn't guaranteed to check that the expansion is an embedded event form, as is required for [47m[make-event][0m. Another limitation for [47mmake-event[0m expansion is that when an iteration reaches the form [47m(:OR ev1 ... evk)[0m, the iteration concludes rather than evaluating the events [47mevi[0m (see [make-event]). A similar utility, [47m[trans*-][0m, stops iteration at a call of [47mmake-event[0m without continuing with its [47mmake-event[0m expansion. That is, in fact, the only difference between [47mtrans*[0m and [47mtrans*-[0m. We conclude by adding emphasis to an aspect of [47mtrans*[0m that is already noted above: expansion (whether macroexpansion or [47mmake-event[0m expansion) and elimination of event wrappers only take place for the top-level call, not calls occurring in subterms. Of course, one can call [47mtrans*[0m on subterms. Consider the following example. ACL2 !>:trans* t (defund-nx f (x) x) Iteration 1 produces (by expansion): (WITH-OUTPUT :STACK :PUSH :OFF :ALL (PROGN (ENCAPSULATE NIL (LOGIC) (SET-STATE-OK T) (WITH-OUTPUT :STACK :POP (DEFUND F (X) (DECLARE (XARGS :NON-EXECUTABLE T :MODE :LOGIC)) (PROG2$ (THROW-NONEXEC-ERROR 'F (LIST X)) X))) (WITH-OUTPUT :STACK :POP :OFF SUMMARY (IN-THEORY (DISABLE (:E F))))) (WITH-OUTPUT :STACK :POP :OFF SUMMARY (VALUE-TRIPLE '(:DEFUND-NX F))))) ---------- Iteration 2 is dropping the WITH-OUTPUT wrapper: (PROGN (ENCAPSULATE NIL (LOGIC) (SET-STATE-OK T) (WITH-OUTPUT :STACK :POP (DEFUND F (X) (DECLARE (XARGS :NON-EXECUTABLE T :MODE :LOGIC)) (PROG2$ (THROW-NONEXEC-ERROR 'F (LIST X)) X))) (WITH-OUTPUT :STACK :POP :OFF SUMMARY (IN-THEORY (DISABLE (:E F))))) (WITH-OUTPUT :STACK :POP :OFF SUMMARY (VALUE-TRIPLE '(:DEFUND-NX F)))) ---------- ACL2 !> One can then call [47mtrans*[0m on the [47m[defund][0m subterm to see its expansion.") (trans*- (macros) "Variant of [47m[trans*][0m the skips [47m[make-event][0m expansion See [trans*]. The only difference between [47mtrans*[0m and [47mtrans*-[0m is that the latter does not do [47m[make-event][0m expansion, but rather, stops the iterations when reaching a form that is a call of [47mmake-event[0m.") (trans-eval (system-utilities) "Evaluate a form This relatively advanced system utility translates and evaluates a form. The following examples illustrate that an [error-triple] is returned whose value component is [47m(stobjs-out . values)[0m. ACL2 !>(trans-eval '(+ 3 4) 'my-ctx state nil) ((NIL) . 7) ACL2 !>(trans-eval '(mv (+ 3 4) (car '(5))) 'my-ctx state nil) ((NIL NIL) 7 5) ACL2 !> General Form: (trans-eval form ; an untranslated form ctx ; a context state aokp) ; allow attachments The result is an [error-triple], [47m(mv erp val state)[0m. The value of [47merp[0m is non-[47mnil[0m if there is an error when translating [47mform[0m. Otherwise [47merp[0m is typically [47mnil[0m, in which case [47mval[0m is a [47mcons[0m pair whose [47mcar[0m is the [47m[stobjs-out][0m --- a list whose length is the number of values returned, with [47mnil[0m in each position except when occupied by a returned [stobj] for that position --- and whose [47mcdr[0m is the returned value or list of values in the [multiple-value] case. Also see [47msimple-translate-and-eval-cmp[0m in the ACL2 sources, and see [trans-eval-error-triple] (and, which is perhaps less useful, [trans-eval-state]). If you use [47mtrans-eval[0m then you may see a warning, for example as follows. ACL2 !>(foo st state) ACL2 Warning [User-stobjs-modified] in FOO: A call of the ACL2 evaluator on the term (UPDATE-FLD '4 ST) may have modified the user stobj ST. See :DOC user-stobjs-modified-warning. (4 <state> <st>) ACL2 !> These warnings indicate a potentially serious violation of applicative semantics when one is also updating user-defined stobjs outside calls of [47mtrans-eval[0m! To understand and perhaps avoid such warnings, see [user-stobjs-modified-warnings]. Also see [trans-eval-and-locally-bound-stobjs] for discussion of how [47mtrans-eval[0m modifies global stobj values, not locally-bound stobjs. Subtopics [Trans-eval-and-locally-bound-stobjs] [47m[Trans-eval][0m deals in global [stobj]s. [Trans-eval-and-stobjs] How user-defined [stobj]s are handled by [47m[trans-eval][0m [User-stobjs-modified-warnings] Interactions of [47m[trans-eval][0m with [stobj]s that violate applicative semantics") (trans-eval-and-locally-bound-stobjs (trans-eval stobj) "[47m[Trans-eval][0m deals in global [stobj]s. This topic assumes familiarity with the relatively advanced utility, [47m[trans-eval][0m. In particular, see [trans-eval-and-stobjs] for relevant background. It may also be helpful to see [user-stobjs-modified-warnings]. A stobj may be locally bound by [47m[stobj-let][0m or [47m[with-local-stobj][0m. But [47m[trans-eval][0m ignores such local bindings! The following example illustrates this point. (defstobj st fld) (defun f (x state) (declare (xargs :stobjs state :mode :program)) (with-local-stobj st (mv-let (state local-fld st) (mv-let (erp val state) (trans-eval `(update-fld ',x st) 'f state nil) (declare (ignore erp val)) (mv state (fld st) st)) (mv state local-fld)))) ; The following returns (<state> NIL). Thus, the return value of local-fld ; indicated above, which is the value of the fld of the locally-bound st, is ; nil: trans-eval did not update the locally-bound stobj! (f 3 state) ; On the other hand the global stobj, st, was indeed updated by the call of f ; just above. (assert-event (equal (fld st) 3)) Here is another such example, this time using [nested-stobjs] instead of [47m[with-local-stobj][0m. (defstobj sub1 sub1-fld1) (defstobj top1 (top1-fld :type sub1)) (defun g (x top1 state) (declare (xargs :stobjs (top1 state) :mode :program)) (stobj-let ((sub1 (top1-fld top1))) ; bindings (sub1 state) ; producer variables (mv-let (erp val state) ; producer ; NOTE: The reference to sub1 inside the following trans-eval call is actually ; a reference to the global sub1 from the user-stobj-alist, not to the sub1 ; bound by stobj-let above. Thus, this trans-eval call updates the global ; stobj, sub1, not the locally bound sub1 that is a field of top1. (trans-eval `(update-sub1-fld1 ',x sub1) 'g state t) (declare (ignore erp val)) (mv sub1 state)) (mv top1 state) ; consumer )) (g 7 top1 state) ; The global stobj, sub1, has been updated by the call of g just above. (assert-event (equal (sub1-fld1 sub1) 7)) (g 8 top1 state) ; The global stobj, sub1, has been updated by the call of g just above. (assert-event (equal (sub1-fld1 sub1) 8)) ; Obtain the sub1 field of top1. (defun get-sub1-of-top1 (top1) (declare (xargs :stobjs top1 :mode :program)) (stobj-let ((sub1 (top1-fld top1))) ; bindings (val) ; producer variable (sub1-fld1 sub1) ; producer val ; consumer )) ; The calls of g above did not update the locally bound sub1. ; That is, they did not update the sub1 field of top1. (assert-event (equal (get-sub1-of-top1 top1) nil))") (trans-eval-and-stobjs (trans-eval stobj) "How user-defined [stobj]s are handled by [47m[trans-eval][0m See [trans-eval] for basic background on the relatively advanced system utility, [47mtrans-eval[0m. In this topic we discuss how [47mtrans-eval[0m handles user-defined [stobj]s. A field of the ACL2 [state], the [47muser-stobj-alist[0m, is an association list (alist) that maps each user-defined [stobj] name to its current value. [47mTrans-eval[0m evaluates with respect to this alist, so that any time a variable (which must be a stobj name) is to be evaluated, its value is looked up in that alist. For example, suppose that you evaluate the following forms in the top-level ACL2 loop. (defstobj st fld) (fld st) To evaluate the expression, [47m(fld st)[0m, ACL2 calls [47m[trans-eval][0m --- or more accurately its variant, [47m[trans-eval-default-warning][0m --- on that expression. (We generally consider all such variants to be the same as [47mtrans-eval[0m for purposes of this documentation topic.) Although [47mst[0m has the syntax of a global variable, it is bound in the [47muser-stobj-alist[0m. Here we see [47mtrans-eval[0m in action. ACL2 !>(trace$ trans-eval-default-warning) ((TRANS-EVAL-DEFAULT-WARNING)) ACL2 !>(fld st) 1> (TRANS-EVAL-DEFAULT-WARNING (FLD ST) TOP-LEVEL |*the-live-state*| T) <1 (TRANS-EVAL-DEFAULT-WARNING NIL ((NIL)) |*the-live-state*|) NIL ACL2 !> This call of [47mtrans-eval[0m (or more accurately, [47mtrans-eval-default-warning[0m) invokes an ACL2 evaluator [47m(ev form alist state ...)[0m, by calling it on the form [47m(fld st)[0m and an alist that binds the variable [47mst[0m to its value in the [47muser-stobj-alist[0m component of the ACL2 [state]. We may refer to this value as the ``global value of'' [47mst[0m. We can of course update this stobj. ACL2 !>(update-fld 3 st) 1> (TRANS-EVAL-DEFAULT-WARNING (UPDATE-FLD 3 ST) TOP-LEVEL |*the-live-state*| T) <1 (TRANS-EVAL-DEFAULT-WARNING NIL ((ST) . REPLACED-ST) |*the-live-state*|) <st> ACL2 !>(fld st) ; check that the update occurred 1> (TRANS-EVAL-DEFAULT-WARNING (FLD ST) TOP-LEVEL |*the-live-state*| T) <1 (TRANS-EVAL-DEFAULT-WARNING NIL ((NIL) . 3) |*the-live-state*|) 3 ACL2 !> We see above that the global value of [47mst[0m was indeed updated by evaluating the [47mupdate-fld[0m call. That is: the value of [47mst[0m in the [47muser-stobj-alist[0m of the ACL2 [47m[state][0m was updated by calling [47m[trans-eval][0m on the expression, [47m(update-fld 3 st)[0m. More generally: as [47mtrans-eval[0m returns, it updates the [47muser-stobj-alist[0m of the ACL2 [state] according to all stobj values that have been returned.") (trans-eval-default-warning (pointers) "See [user-stobjs-modified-warnings].") (trans-eval-no-warning (pointers) "See [user-stobjs-modified-warnings].") (trans1 (macros) "Print the one-step macroexpansion of a form See [term] for background on translated and untranslated terms, including some discussion of macros. Examples: :trans1 (list a b c) :trans1 (caddr x) :trans1 (cond (p q) (r)) This utility takes one argument, an alleged untranslated term, and expands the top-level macro in it for one step only. Either an error is caused, which happens when the form is not a call of a macro, or the result is printed. Also see [trans], which translates the given form completely. On very rare occasions, complete translation is not quite the same as translating the output of [47m:trans1[0m, though the two should still be logically equivalent. This can happen for a call of [47m[stobj-let][0m in the body of a function: its translation may include a check for duplicate indices that is omitted in the single-step macroexpansion.") (translam (apply$) "Print the translation of a lambda$ expression :translam (lambda$ (x) (+ 1 x)) :translam (lambda (x) (+ 1 x)) This function takes a [47mlambda$[0m term or an unquoted [47mLAMBDA[0m constant. In the former case, it translates the [47mlambda$[0m and prints the result. In the latter case it puts the [47mLAMBDA[0m in a [47mQUOTE[0m and translates it as though it occurred in a [47m:FN[0m slot. Unless an error is signaled it prints the same [47mLAMBDA[0m object as the result. This utility exists because you cannot write, say, :trans (lambda$ (x) (+ 1 x)) because the [47mtrans[0m utility assumes its argument in an ordinary (ilk [47mNIL[0m) slot. In such slots, [47mlambda$[0m terms are disallowed and no restrictions are enforced on quoted [47mLAMBDA[0m objects. This utility is useful for seeing what the formal translation of a [47mlambda$[0m term is. For example, ACL2 !>:translam (lambda$ (x) (declare (type (satisfies natp) x)) (* x x)) produces the quoted well-formed [47mLAMBDA[0m expression: '(LAMBDA (X) (DECLARE (TYPE (SATISFIES NATP) X) (XARGS :GUARD (NATP X) :SPLIT-TYPES T) (IGNORABLE X)) (RETURN-LAST 'PROGN '(LAMBDA$ (X) (DECLARE (TYPE (SATISFIES NATP) X)) (* X X)) (BINARY-* X X))) You might now have an inkling about why we discourage you from trying to enter quoted well-formed [47mLAMBDA[0m objects by hand! The normal form of a quoted well-formed [47mLAMBDA[0m object is complicated so that [47mapply$[0m can rapidly identify the parts, generate guard conditions, compile the object, recognize objects coming from [47mlambda$[0m terms, etc.") (translate (pointers) "See [system-utilities].") (translate-cmp (pointers) "See [system-utilities].") (translate-hints (pointers) "See [system-utilities].") (translate1 (pointers) "See [system-utilities].") (translate1-cmp (pointers) "See [system-utilities].") (translate11 (pointers) "See [system-utilities].") (transparent-functions (meta) "Working around restrictions on the use of evaluators in meta-level rules See [evaluator-restrictions] for relevant background. For examples of the use of transparent functions, see [community-book] file [47mbooks/system/tests/transparent-functions-input.lsp[0m, with corresponding output in file [47mtransparent-functions-log.txt[0m in the same directory. A function is called a ``transparent function symbol'' when it is declared with [47m:transparent t[0m in a [signature] of an [47m[encapsulate][0m event. By thus declaring a function to be transparent, you are modifying the notion of ``ancestor'' of a meta-level function as follows, for purposes of the ancestor restriction described in [evaluator-restrictions]: when a transparent function [47mf[0m has an attachment [47mg[0m (see [defattach]), then [47mg[0m is the sole ancestor (supporter) of [47mf[0m. We illustrate with a (contrived) example, which shows how declaring a function to be transparent can avoid an error. Consider what happens when we submit the following events in a fresh ACL2 session. (defstub f0 (x) t) (encapsulate (((f1 *) => *) ((f2 *) => *)) (local (defun f1 (x) (f0 x))) (local (defun f2 (x) (f0 x))) (defthm f2-is-f1 (implies (f0 x) (equal (f2 x) (f1 x))) :rule-classes nil)) (defn g0 (x) x) (defattach f0 g0) (with-output :off :all ; avoid noisy output (defevaluator evl evl-list ((f0 x)))) (defn meta-fn1 (x) (if (f1 x) x x)) (defattach (f1 consp) (f2 consp)) (defthm thm1 (equal (evl x a) (evl (meta-fn1 x) a)) :rule-classes ((:meta :trigger-fns (nth)))) The final ([47m[defthm][0m) event results in the following error. ACL2 Error in ( DEFTHM THM1 ...): The proposed :META rule, THM1, is illegal because the attached function F0 is ancestral in both the evaluator and meta functions. See :DOC evaluator-restrictions and see :DOC transparent- functions. The following is an ancestor path from F0 to the meta function META-FN1, i.e., each function symbol is a supporter of the next: (F0 F1 META-FN1) The following is an ancestor path from F0 to the evaluator function EVL, i.e., each function symbol is a supporter of the next: (F0 EVL) The events above make it clear that the alleged ancestor paths are indeed ancestor paths, in the sense that each function symbol in the path occurs in the definition or [constraint] for the function symbol immediately after it. To avoid this error, we need to arrange that [47mf0[0m is no longer a common ancestor of [47mmeta-fn1[0m and [47mevl[0m. The notion of ancestor doesn't change for the path leading to the evaluator function; but for the path leading to the meta function, a transparent function symbol has its attachment as its ancestor instead of the function symbols in its [constraint]. In particular, [47mf1[0m normally has [47mf0[0m as an ancestor, since [47mf0[0m occurs in the constraint on [47mf1[0m; but if [47mf1[0m is transparent and has an attachment, then its attachment is the sole ancestor of [47mf0[0m, as though [47mf1[0m had been defined to be [47mf0[0m. Thus, if we replace the [47m[encapsulate][0m event in our example simply by declaring its [signature] functions to be transparent, as follows, then the error disappears. (encapsulate (((f1 *) => * :transparent t) ((f2 *) => * :transparent t)) (local (defun f1 (x) (f0 x))) (local (defun f2 (x) (f0 x))) (defthm f2-is-f1 (implies (f0 x) (equal (f2 x) (f1 x))) :rule-classes nil)) We close with some restrictions pertaining to transparent function symbols. * If any function is declared with [47m:transparent t[0m in the signatures of an [47mencapsulate[0m event, then all must be. * If any function is declared with [47m:transparent t[0m in the signatures of an [47mencapsulate[0m event, then every signature in a superior or inferior [47mencapsulate[0m event must also specify [47m:transparent t[0m. * The value of the [47m:transparent[0m keyword in a signature must be [47mt[0m or the default, [47mnil[0m. * The signatures of a [47m[partial-encapsulate][0m (or of any encapsulate with a call of [47mset-unknown-constraints-supporters[0m) must not specify [47m:transparent t[0m in its signatures. * When a [47m[defattach][0m event attaches to a transparent function symbol [47mf[0m, that event must attach to every function symbol constrained in an encapsulate with [47mf[0m, and only to such function symbols. The same holds for unattaching in place of attaching.") (true-list-fix (true-listp acl2-built-ins) "Coerce to a true list Many functions that process lists follows the [31;1mtrue-list-fix convention[0m: whenever [47mf[0m is given some non-[47m[true-listp][0m [47mx[0m where it expected a list, that is, some [47mx[0m with a non-[47mnil[0m [47m[final-cdr][0m, it will act as though it had been given [47m(true-list-fix x)[0m instead. As a few examples, logically, * [47m(endp x)[0m ignores the final [47mcdr[0m of [47mx[0m * [47m(len x)[0m ignores the final [47mcdr[0m of [47mx[0m * [47m(append x y)[0m ignores the final [47mcdr[0m of [47mx[0m (but not [47my[0m) * [47m(member a x)[0m ignores the final [47mcdr[0m of [47mx[0m [47mTrue-list-fix[0m is often useful when writing theorems about how list-processing functions behave. For example, it allows us to write strong, hypothesis-free theorems such as: (equal (character-listp (append x y)) (and (character-listp (true-list-fix x)) (character-listp y))) Indeed, [47mtrue-list-fix[0m is the basis for [list-equiv], an extremely common [equivalence] relation. Efficiency note. In practice, most lists are [47mnil[0m-terminated. As an optimization, [47mtrue-list-fix[0m tries to avoid any consing by first checking whether its argument is a [true-listp], and, in that case, it simply returns its argument unchanged. For a logically equivalent utility that returns its argument unchanged (with no checking) during normal evaluation, see [the-true-list]. [31;1mFunction: [0m<true-list-fix-exec> (defun true-list-fix-exec (x) (declare (xargs :guard t)) (if (consp x) (cons (car x) (true-list-fix-exec (cdr x))) nil)) [31;1mFunction: [0m<true-list-fix> (defun true-list-fix (x) (declare (xargs :guard t)) (mbe :logic (if (consp x) (cons (car x) (true-list-fix (cdr x))) nil) :exec (if (true-listp x) x (true-list-fix-exec x))))") (true-list-listp (lists true-listp acl2-built-ins) "Recognizer for true (proper) lists of true lists [47mTrue-list-listp[0m is the function that checks whether its argument is a list that ends in, or equals, [47mnil[0m, and furthermore, all of its elements have that property. Also see [true-listp]. [31;1mFunction: [0m<true-list-listp> (defun true-list-listp (x) (declare (xargs :guard t)) (cond ((atom x) (eq x nil)) (t (and (true-listp (car x)) (true-list-listp (cdr x))))))") (true-listp (lists acl2-built-ins) "Recognizer for proper ([47mnil[0m-terminated) lists [47mTrue-listp[0m is the function that checks whether its argument is a list that ends in, or equals, [47mnil[0m. For a discussion of whether requiring lists to be [47mnil[0m-terminated is right for you, see [std::strict-list-recognizers]. [31;1mFunction: [0m<true-listp> (defun true-listp (x) (declare (xargs :guard t)) (if (consp x) (true-listp (cdr x)) (eq x nil))) Subtopics [The-true-list] Coerce an expected true list to a true list [True-list-fix] Coerce to a true list [True-list-listp] Recognizer for true (proper) lists of true lists") (truncate (numbers acl2-built-ins) "Division returning an integer by truncating toward 0 Example Forms: ACL2 !>(truncate 14 3) 4 ACL2 !>(truncate -14 3) -4 ACL2 !>(truncate 14 -3) -4 ACL2 !>(truncate -14 -3) 4 ACL2 !>(truncate -15 -3) 5 ACL2 !>(truncate 10/4 3/4) 3 [47m(Truncate i j)[0m is the result of taking the quotient of [47mi[0m and [47mj[0m and dropping the fraction. For example, the quotient of [47m-14[0m by [47m3[0m is [47m-4 2/3[0m, so dropping the fraction [47m2/3[0m, we obtain a result for [47m(truncate -14 3)[0m of [47m-4[0m. The [guard] for [47m(truncate i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real], in ACL2(r)) numbers and [47mj[0m is non-zero. [47mTruncate[0m is a Common Lisp function. However, note that unlike Common Lisp, the ACL2 [47mtruncate[0m function returns only a single value, Also see [nonnegative-integer-quotient], which is appropriate for integers and may simplify reasoning, unless a suitable arithmetic library is loaded, but be less efficient for evaluation on concrete objects. [31;1mFunction: [0m<truncate> (defun truncate (i j) (declare (xargs :guard (and (real/rationalp i) (real/rationalp j) (not (eql j 0))))) (let* ((q (* i (/ j))) (n (numerator q)) (d (denominator q))) (cond ((= d 1) n) ((>= n 0) (nonnegative-integer-quotient n d)) (t (- (nonnegative-integer-quotient (- n) d))))))") (trust-mfc (extended-metafunctions) "A macro that supports testing of extended metafunctions) Example Form: (trust-mfc (mfc-ts term mfc state)) General Form: (trust-mfc form) where [47mform[0m is any form, but is typically a call of an extended metafunction such as [47mmfc-ts[0m or [47mmfc-rw[0m. Extended metafunctions (see [extended-metafunctions]) may normally only be invoked during proofs. [47mTrust-mfc[0m is an advanced utility that relaxes that requirement, thus supporting the testing of extended-metafunctions outside calls of the ACL2 prover. When you use [47mtrust-mfc[0m, you are taking on the responsibility to pass only well-formed [47m[mfc][0m arguments to your calls of extended-metafunctions, since otherwise raw Lisp errors may be signaled. Because of this danger, the logical definition of [47mtrust-mfc[0m causes an error, thus making it useless at the top level and in [47m:[0m[47m[logic][0m-mode code: [31;1mMacro: [0m<trust-mfc> (defmacro trust-mfc (&whole whole form) (cons 'prog2$ (cons (cons 'er (cons 'hard (cons ''trust-mfc (cons '"It is illegal to run ~x0 except in raw Lisp, ~ typically by way of a :program-mode function ~ body. ~ See :DOC trust-mfc. Evaluation of ~ the form ~x1 has led to this error." (cons ''trust-mfc (cons (cons 'quote (cons whole 'nil)) 'nil)))))) (cons form 'nil)))) However, [47mtrust-mfc[0m can be very useful when used in [47m:[0m[47m[program][0m-mode code that calls extended metafunctions, which makes it useful for [47m:logic[0m-mode code as well; see [program-wrapper]. The log below illustrates typical usage. ACL2 !>(defun my-mfc (state) ;; Define a simple metafunction-contextx. (declare (xargs :mode :program :guard t :stobjs state)) (make metafunction-context :rdepth 10000 :type-alist nil :obj '? :geneqv nil :wrld (w state) :fnstack nil :ancestors nil :backchain-limit nil :simplify-clause-pot-lst nil :rcnst (initial-rcnst-from-ens (ens state) (w state) state nil) :gstack nil :ttree nil :unify-subst nil)) Summary Form: ( DEFUN MY-MFC ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) MY-MFC ACL2 !>(mfc-ts '(cons x y) (my-mfc state) state) ; error: not in prover Meta-level function Problem: This error can quite possibly be avoided; see :DOC trust-mfc. You or some meta-level function applied MFC-TS but not from within the theorem prover's meta-level function handler. This suggests you are trying to test a meta-level function and have evidently manufactured an allegedly suitable context. Perhaps so. But that is so difficult to check that we don't bother. Instead we cause this error and urge you to test your meta-level function by having the meta-level function handler invoke it as part of a test proof- attempt. To do this, assume the metatheorem that you intend eventually to prove. You may do this by executing the appropriate DEFTHM event embedded in a SKIP-PROOFS form. Then use THM to submit conjectures for proof and observe the behavior of your metafunction. Remember to undo the assumed metatheorem before you attempt genuine proofs! If this suggestion isn't applicable to your situation, contact the authors. ACL2 Error in TOP-LEVEL: ACL2 cannot ev the call of non-executable function MFC-TS on argument list: ((CONS X Y) MFC STATE) To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. ACL2 !>(trust-mfc (mfc-ts '(cons x y) (my-mfc state) state)) ; top-level (bad) HARD ACL2 ERROR in TRUST-MFC: It is illegal to run TRUST-MFC except in raw Lisp, typically by way of a :program-mode function body. See :DOC trust-mfc. Evaluation of the form (TRUST-MFC (MFC-TS '(CONS X Y) (MY-MFC STATE) STATE)) has led to this error. ACL2 Error in TOP-LEVEL: Evaluation aborted. To debug see :DOC print- gv, see :DOC trace, and see :DOC wet. ACL2 !>(defun my-mfc-ts (term mfc state) (declare (xargs :mode :program :stobjs state)) (trust-mfc (mfc-ts term mfc state))) Summary Form: ( DEFUN MY-MFC-TS ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) MY-MFC-TS ACL2 !>(my-mfc-ts '(cons x y) (my-mfc state) state) 3072 ACL2 !>(decode-type-set 3072) ; let's see that the result above is reasonable *TS-CONS* ACL2 !>") (trust-tag (pointers) "See [defttag].") (ttag (pointers) "See [defttag].") (ttags-seen (miscellaneous) "List some declared trust tags (ttags) General Forms: :ttags-seen (ttags-seen) Suppose the output is as follows. (T NIL) (FOO "/home/bob/bar.lisp" "/home/cindy/bar.lisp") Warning: This output is minimally trustworthy (see :DOC TTAGS-SEEN). This output indicates that the current logical [world] has seen the declaration of trust tag [47mT[0m at the top-level (see [defttag]) and the declaration of trust tag [47mFOO[0m in the two books included from the listed locations. The warning emphasizes that this command cannot be used to validate the ``purity'' of an ACL2 session, because using a ttag renders enough power to hide from this or any other command the fact that the ttag was ever declared. As discussed elsewhere (see [defttag]), the only reliable way to validate the ``purity'' of a session is to watch for ``[47mTTAG NOTE[0m'' output. Another shortcoming of this command is that it only checks the current logical [world] for ttag declarations. For example, one could execute a [47m[defttag][0m event; then use [47m[progn!][0m and [47m[set-raw-mode][0m to replace system functions with corrupt definitions or to introduce inconsistent axioms in the [47m[ground-zero][0m [world]; and finally, execute [47m:[0m[47m[ubt!][0m[47m 1[0m to remove all evidence of the ttag in the [world] while leaving in place the corrupt definitions or axioms. The base world is now tainted, meaning we could prove [47mnil[0m or certify a book that proves [47mnil[0m, but the resulting session or book would contain no trace of the ttag that tainted it! Despite shortcomings, this command might be useful to system hackers. It also serves to illustrate the inherent flaw in asking a session whether or how it is ``tainted'', justifying the ``[47mTTAG NOTE[0m'' approach (see [defttag]).") (tthm (history measure) "The [measure] (termination) theorem for a given function symbol Example Forms: :tthm FN (tthm 'FN) ; equivalent to the above where [47mFN[0m is a function symbol. This shows the [measure] (termination) theorem for [47mFN[0m. More precisely, evaluation of a call of this macro --- pronounced ``tee-thumb'' --- either results in an error or returns an [error-triple] whose value component is the user-level (untranslated) version of that termination theorem. Also see [lemma-instance] for discussion of a related [47m:termination-theorem[0m prover hint. Technical note: a corresponding evaluation that provides a (translated) [termp] is: [47m(termination-theorem 'FN (w state))[0m.") (ttree (miscellaneous) "Tag-trees Many low-level ACL2 functions take and return ``tag trees'' or ``ttrees'' (pronounced ``tee-trees'') which contain useful information such as the lemmas used, the linearize assumptions made, etc. Here we present only minimal user-level information, for example in support of the use of the [break-rewrite] utility or writing metafunctions. Implementation-level information about tag trees may be found in the Developer's Guide; users should probably not visit that topic (see [DEVELOPERS-GUIDE-UTILITIES]) unless they plan to become ACL2 developers. Abstractly a tag-tree represents a list of sets, each member set having a name given by one of the ``tags'' (which are symbols) of the ttree. The elements of the set named [47mtag[0m are all of the objects tagged [47mtag[0m in the tree. The rewriter, for example, takes a term and a ttree (among other things), and returns a new term, term', and new ttree, ttree'. Term' is equivalent to term (under the current assumptions) and the ttree' is an extension of ttree. If we focus just on the set associated with the tag [47mLEMMA[0m in the ttrees, then the set for ttree' is the extension of that for ttree obtained by unioning into it all the [rune]s used by the rewrite. The set associated with [47mLEMMA[0m can be obtained by [47m(tagged-objects 'LEMMA ttree)[0m.") (tutorial1-towers-of-hanoi (annotated-acl2-scripts) "The Towers of Hanoi Example This example was written almost entirely by Bill Young of Computational Logic, Inc. We will formalize and prove a small theorem about the famous ``Towers of Hanoi'' problem. This problem is illustrated by the following picture. | | | | | | --- | | ----- | | ------- | | A B C We have three pegs --- [47ma[0m, [47mb[0m, and [47mc[0m --- and [47mn[0m disks of different sizes. The disks are all initially on peg [47ma[0m. The goal is to move all disks to peg [47mc[0m while observing the following two rules. 1. Only one disk may be moved at a time, and it must start and finish the move as the topmost disk on some peg; 2. A disk can never be placed on top of a smaller disk. Let's consider some simple instances of this problem. If [47mn[0m = 1, i.e., only one disk is to be moved, simply move it from [47ma[0m to [47mc[0m. If [47mn[0m = 2, i.e., two disks are to be moved, the following sequence of moves suffices: move from [47ma[0m to [47mb[0m, move from [47ma[0m to [47mc[0m, move from [47mb[0m to [47mc[0m. In this doc topic we will show an ACL2 function that generates a suitable list of moves for a tower of [47mn[0m disks. Then we will use ACL2 to prove that the number of moves is [47m(- (expt 2 n) 1)[0m. For an ACL2 script that proves the correctness of (a version of) this function, see the community book [47m"misc/hanoi.lisp"[0m in the [47mbooks[0m directory of your ACL2 sources. In general, this problem has a straightforward recursive solution. Suppose that we desire to move [47mn[0m disks from [47ma[0m to [47mc[0m, using [47mb[0m as the intermediate peg. For the basis, we saw above that we can always move a single disk from [47ma[0m to [47mc[0m. Now if we have [47mn[0m disks and assume that we can solve the problem for [47mn-1[0m disks, we can move [47mn[0m disks as follows. First, move [47mn-1[0m disks from [47ma[0m to [47mb[0m using [47mc[0m as the intermediate peg; move the single disk from [47ma[0m to [47mc[0m; then move [47mn-1[0m disks from [47mb[0m to [47mc[0m using [47ma[0m as the intermediate peg. In ACL2, we can write a function that will return the sequence of moves. One such function is as follows. Notice that we have two base cases. If [47m(zp n)[0m then [47mn[0m is not a positive integer; we treat that case as if [47mn[0m were 0 and return an empty list of moves. If [47mn[0m is 1, then we return a list containing the single appropriate move. Otherwise, we return the list containing exactly the moves dictated by our recursive analysis above. (defun move (a b) (list 'move a 'to b)) (defun hanoi (a b c n) (if (zp n) nil (if (equal n 1) (list (move a c)) (append (hanoi a c b (1- n)) (cons (move a c) (hanoi b a c (1- n))))))) Notice that we give [47mhanoi[0m four arguments: the three pegs, and the number of disks to move. It is necessary to supply the pegs because, in recursive calls, the roles of the pegs differ. In any execution of the algorithm, a given peg will sometimes be the source of a move, sometimes the destination, and sometimes the intermediate peg. After submitting these functions to ACL2, we can execute the [47mhanoi[0m function on various specific arguments. For example: ACL2 !>(hanoi 'a 'b 'c 1) ((MOVE A TO C)) ACL2 !>(hanoi 'a 'b 'c 2) ((MOVE A TO B) (MOVE A TO C) (MOVE B TO C)) ACL2 !>(hanoi 'a 'b 'c 3) ((MOVE A TO C) (MOVE A TO B) (MOVE C TO B) (MOVE A TO C) (MOVE B TO A) (MOVE B TO C) (MOVE A TO C)) From the algorithm it is clear that if it takes [47mm[0m moves to transfer [47mn[0m disks, it will take [47m(m + 1 + m) = 2m + 1[0m moves for [47mn+1[0m disks. From some simple calculations, we see that we need the following number of moves in specific cases: Disks 0 1 2 3 4 5 6 7 ... Moves 0 1 3 7 15 31 63 127 ... The pattern is fairly clear. To move [47mn[0m disks requires [47m(2^n - 1)[0m moves. Let's attempt to use ACL2 to prove that fact. First of all, how do we state our conjecture? Recall that [47mhanoi[0m returns a list of moves. The length of the list (given by the function [47mlen[0m) is the number of moves required. Thus, we can state the following conjecture. (defthm hanoi-moves-required-first-try (equal (len (hanoi a b c n)) (1- (expt 2 n)))) When we submit this to ACL2, the proof attempt fails. Along the way we notice subgoals such as: Subgoal *1/1' (IMPLIES (NOT (< 0 N)) (EQUAL 0 (+ -1 (EXPT 2 N)))). This tells us that the prover is considering cases that are uninteresting to us, namely, cases in which [47mn[0m might be negative. The only cases that are really of interest are those in which [47mn[0m is a non-negative natural number. Therefore, we revise our theorem as follows: (defthm hanoi-moves-required (implies (and (integerp n) (<= 0 n)) ;; n is at least 0 (equal (len (hanoi a b c n)) (1- (expt 2 n))))) and submit it to ACL2 again. Again the proof fails. Examining the proof script we encounter the following text. (How did we decide to focus on this goal? Some information is provided in ACLH, and the ACL2 documentation on [tips] may be helpful. But the simplest answer is: this was the first goal suggested by the ``[proof-tree]'' tool below the start of the proof by induction. See [proof-tree].) Subgoal *1/5'' (IMPLIES (AND (INTEGERP N) (< 0 N) (NOT (EQUAL N 1)) (EQUAL (LEN (HANOI A C B (+ -1 N))) (+ -1 (EXPT 2 (+ -1 N)))) (EQUAL (LEN (HANOI B A C (+ -1 N))) (+ -1 (EXPT 2 (+ -1 N))))) (EQUAL (LEN (APPEND (HANOI A C B (+ -1 N)) (CONS (LIST 'MOVE A 'TO C) (HANOI B A C (+ -1 N))))) (+ -1 (* 2 (EXPT 2 (+ -1 N)))))) It is difficult to make much sense of such a complicated goal. However, we do notice something interesting. In the conclusion is a [term] of the following shape. (LEN (APPEND ... ...)) We conjecture that the length of the [47m[append][0m of two lists should be the sum of the lengths of the lists. If the prover knew that, it could possibly have simplified this [term] earlier and made more progress in the proof. Therefore, we need a [rewrite] rule that will suggest such a simplification to the prover. The appropriate rule is: (defthm len-append (equal (len (append x y)) (+ (len x) (len y)))) We submit this to the prover, which proves it by a straightforward induction. The prover stores this lemma as a [rewrite] rule and will subsequently (unless we [disable] the rule) replace [term]s matching the left hand side of the rule with the appropriate instance of the [term] on the right hand side. We now resubmit our lemma [47mhanoi-moves-required[0m to ACL2. On this attempt, the proof succeeds and we are done. One bit of cleaning up is useful. We needed the hypotheses that: (and (integerp n) (<= 0 n)). This is an awkward way of saying that [47mn[0m is a natural number; natural is not a primitive data type in ACL2. We could define a function [47mnaturalp[0m, but it is somewhat more convenient to define a macro as follows: (defmacro naturalp (x) (list 'and (list 'integerp x) (list '<= 0 x))) Subsequently, we can use [47m(naturalp n)[0m wherever we need to note that a quantity is a natural number. See [defmacro] for more information about ACL2 macros. With this macro, we can reformulate our theorem as follows: (defthm hanoi-moves-required (implies (naturalp n) (equal (len (hanoi a b c n)) (1- (expt 2 n))))). Another interesting (but much harder) theorem asserts that the list of moves generated by our [47mhanoi[0m function actually accomplishes the desired goal while following the rules. When you can state and prove that theorem, you'll be a very competent ACL2 user. By the way, the name ``Towers of Hanoi'' derives from a legend that a group of Vietnamese monks works day and night to move a stack of 64 gold disks from one diamond peg to another, following the rules set out above. We're told that the world will end when they complete this task. From the theorem above, we know that this requires 18,446,744,073,709,551,615 moves: ACL2 !>(1- (expt 2 64)) 18446744073709551615 ACL2 !> We're guessing they won't finish any time soon.") (tutorial2-eights-problem (annotated-acl2-scripts) "The Eights Problem Example This example was written almost entirely by Bill Young of Computational Logic, Inc. This simple example was brought to our attention as one that Paul Jackson has solved using the NuPrl system. The challenge is to prove the theorem: for all n > 7, there exist naturals i and j such that: n = 3i + 5j. In ACL2, we could phrase this theorem using quantification. However we will start with a constructive approach, i.e., we will show that values of [47mi[0m and [47mj[0m exist by writing a function that will construct such values for given [47mn[0m. Suppose we had a function [47m(split n)[0m that returns an appropriate pair [47m(i . j)[0m. Our theorem would be as follows: (defthm split-splits (let ((i (car (split n))) (j (cdr (split n)))) (implies (and (integerp n) (< 7 n)) (and (integerp i) (<= 0 i) (integerp j) (<= 0 j) (equal (+ (* 3 i) (* 5 j)) n))))) That is, assuming that [47mn[0m is a natural number greater than 7, [47m(split n)[0m returns values [47mi[0m and [47mj[0m that are in the appropriate relation to [47mn[0m. Let's look at a few cases: 8 = 3x1 + 5x1; 11 = 3x2 + 5x1; 14 = 3x3 + 5x1; ... 9 = 3x3 + 5x0; 12 = 3x4 + 5x0; 15 = 3x5 + 5x0; ... 10 = 3x0 + 5x2; 13 = 3x1 + 5x2; 16 = 3x2 + 5x2; ... Maybe you will have observed a pattern here; any natural number larger than 10 can be obtained by adding some multiple of 3 to 8, 9, or 10. This gives us the clue to constructing a proof. It is clear that we can write split as follows: (defun bump-i (x) ;; Bump the i component of the pair ;; (i . j) by 1. (cons (1+ (car x)) (cdr x))) (defun split (n) ;; Find a pair (i . j) such that ;; n = 3i + 5j. (if (or (zp n) (< n 8)) nil ;; any value is really reasonable here (if (equal n 8) (cons 1 1) (if (equal n 9) (cons 3 0) (if (equal n 10) (cons 0 2) (bump-i (split (- n 3)))))))) Notice that we explicitly compute the values of [47mi[0m and [47mj[0m for the cases of 8, 9, and 10, and for the degenerate case when [47mn[0m is not a natural or is less than 8. For all naturals greater than [47mn[0m, we decrement [47mn[0m by 3 and bump the number of 3's (the value of i) by 1. We know that the recursion must terminate because any integer value greater than 10 can eventually be reduced to 8, 9, or 10 by successively subtracting 3. Let's try it on some examples: ACL2 !>(split 28) (6 . 2) ACL2 !>(split 45) (15 . 0) ACL2 !>(split 335) (110 . 1) Finally, we submit our theorem [47msplit-splits[0m, and the proof succeeds. In this case, the prover is ``smart'' enough to induct according to the pattern indicated by the function split. For completeness, we'll note that we can state and prove a quantified version of this theorem. We introduce the notion [47msplit-able[0m to mean that appropriate [47mi[0m and [47mj[0m exist for [47mn[0m. (defun-sk split-able (n) (exists (i j) (equal n (+ (* 3 i) (* 5 j))))) Then our theorem is given below. Notice that we prove it by observing that our previous function [47msplit[0m delivers just such an [47mi[0m and [47mj[0m (as we proved above). (defthm split-splits2 (implies (and (integerp n) (< 7 n)) (split-able n)) :hints (("Goal" :use (:instance split-able-suff (i (car (split n))) (j (cdr (split n))))))) Unfortunately, understanding the mechanics of the proof requires knowing something about the way [47m[defun-sk][0m works. See [defun-sk] or see [Tutorial4-Defun-Sk-Example] for more on that subject.") (tutorial3-phonebook-example (annotated-acl2-scripts) "A Phonebook Specification The other tutorial examples are rather small and entirely self contained. The present example is rather more elaborate, and makes use of a feature that really adds great power and versatility to ACL2, namely: the use of previously defined collections of lemmas, in the form of ``[books].'' This example was written almost entirely by Bill Young of Computational Logic, Inc. It was updated in December, 2024 (from the original version of about two decades ago) thanks to Andrei Koltsov, to work with recent ACL2 versions. This example is based on one developed by Ricky Butler and Sally Johnson of NASA Langley for the PVS system, and subsequently revised by Judy Crow, [3met al[0m, at SRI. It is a simple phone book specification. We will not bother to follow their versions closely, but will instead present a style of specification natural for ACL2. The idea is to model an electronic phone book with the following properties. Our phone book will store the phone numbers of a city. It must be possible to retrieve a phone number, given a name. It must be possible to add and delete entries. Of course, there are numerous ways to construct such a model. A natural approach within the Lisp/ACL2 context is to use ``association lists'' or ``alists.'' Briefly, an alist is a list of pairs [47m(key . value)[0m associating a value with a key. A phone book could be an alist of pairs [47m(name . pnum)[0m. To find the phone number associated with a given name, we merely search the alist until we find the appropriate pair. For a large city, such a linear list would not be efficient, but at this point we are interested only in [31;1mmodeling[0m the problem, not in deriving an efficient implementation. We could address that question later by proving our alist model equivalent, in some desired sense, to a more efficient data structure. We could build a theory of alists from scratch, or we can use a previously constructed theory (book) of alist definitions and facts. By using an existing book, we build upon the work of others, start our specification and proof effort from a much richer foundation, and hopefully devote more of our time to the problem at hand. Unfortunately, it is not completely simple for the new user to know what [books] are available and what they contain. Documentation is available for the growing collection of [community-books] that are typically downloaded with ACL2, and a mailing list, [47macl2-help[0m, is available (see the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/}. For present purposes, the beginning user can simply take our word that a book exists containing useful alist definitions and facts. These definitions and lemmas can be introduced into the current theory using the [command]: (include-book "data-structures/alist-defthms" :dir :system) This book has been ``certified,'' which means that the definitions and lemmas have been mechanically checked and stored in a safe manner. (See [books] and see [include-book] for details.) Including this book makes available a collection of functions including the following: (ALISTP A) ; is A an alist (actually a primitive ACL2 function) (BIND X V A) ; associate the key X with value V in alist A (BINDING X A) ; return the value associated with key X in alist A (BOUND? X A) ; is key X associated with any value in alist A (DOMAIN A) ; return the list of keys bound in alist A (RANGE A) ; return the list of values bound to keys in alist A (REMBIND X A) ; remove the binding of key X in alist A Along with these function definitions, the book also provides a number of proved lemmas that aid in simplifying expressions involving these functions. (See [rule-classes] for the way in which lemmas are used in simplification and rewriting.) For example, (defthm bound?-bind (equal (bound? x (bind y v a)) (or (equal x y) (bound? x a)))) asserts that [47mx[0m will be bound in [47m(bind y v a)[0m if and only if: either [47mx = y[0m or [47mx[0m was already bound in [47ma[0m. Also, (defthm binding-bind (equal (binding x (bind y v a)) (if (equal x y) v (binding x a)))) asserts that the resulting binding will be [47mv[0m, if [47mx = y[0m, or the binding that [47mx[0m had in [47ma[0m already, if not. Thus, the inclusion of this book essentially extends our specification and reasoning capabilities by the addition of new operations and facts about these operations that allow us to build further specifications on a richer and possibly more intuitive foundation. However, it must be admitted that the use of a book such as this has two potential limitations: the definitions available in a book may not be ideal for your particular problem; it is (extremely) likely that some useful facts (especially, [rewrite] rules) are not available in the book and will have to be proved. For example, what is the value of [47mbinding[0m when given a key that is not bound in the alist? We can find out by examining the function definition. Look at the definition of the [47mbinding[0m function (or any other defined function), using the [47m:[0m[47m[pe][0m command: ACL2 !>:pe binding d 1 (INCLUDE-BOOK "data-structures/alist-defthms" :DIR ...) [Included books, outermost to innermost: ".../acl2/books/data-structures/alist-defthms.lisp" ".../acl2/books/data-structures/alist-defuns.lisp" ] >V d (DEFUN BINDING (X A) "The value bound to X in alist A." (DECLARE (XARGS :GUARD (AND (ALISTP A) (OR (EQLABLEP X) (EQLABLE-ALISTP A))))) (CDR (ASSOC X A))) This tells us that [47mbinding[0m was introduced by the given [47m[include-book][0m form, is currently [disable]d in the current theory, and has the definition given by the displayed [47m[defun][0m form. We see that [47mbinding[0m is actually defined in terms of the primitive [47m[assoc][0m. If we submit [47m:pe assoc[0m then we can see that [47massoc[0m is a macro that essentially serves as an abbreviation for the primitive function [47m[assoc-equal][0m. We say no more about [47massoc[0m here but instead focus on [47massoc-equal[0m. If we use [47m:pe[0m to look at the definition of [47m[assoc-equal][0m: PV -8489 (DEFUN ASSOC-EQUAL (X ALIST) (DECLARE (XARGS :GUARD (ALISTP ALIST))) (COND ((ENDP ALIST) NIL) ((EQUAL X (CAR (CAR ALIST))) (CAR ALIST)) (T (ASSOC-EQUAL X (CDR ALIST))))) we can see that [47m[assoc-equal][0m returns [47mnil[0m upon reaching the end of an unsuccessful search down the alist. So [47mbinding[0m returns [47m(cdr nil)[0m in that case, which is [47mnil[0m. Notice that we could also have investigated this question by trying some simple examples. ACL2 !>(binding 'a nil) NIL ACL2 !>(binding 'a (list (cons 'b 2))) NIL These definitions aren't ideal for all purposes. For one thing, there's nothing that keeps us from having [47mnil[0m as a value bound to some key in the alist. Thus, if [47mbinding[0m returns [47mnil[0m we don't always know if that is the value associated with the key in the alist, or if that key is not bound. We'll have to keep that ambiguity in mind whenever we use [47mbinding[0m in our specification. Suppose instead that we wanted [47mbinding[0m to return some error string on unbound keys. Well, then we'd just have to write our own version of [47mbinding[0m. But then we'd lose much of the value of using a previously defined book. As with any specification technique, certain tradeoffs are necessary. Why not take a look at the definitions of other alist functions and see how they work together to provide the ability to construct and search alists? We'll be using them rather heavily in what follows so it will be good if you understand basically how they work. Simply start up ACL2 and execute the form shown earlier, but substituting our directory name for the top-level ACL2 directory with yours. Alternatively, just (include-book "data-structures/alist-defthms" :dir :system) Then, you can use [47m:[0m[pe] to look at function definitions. You'll soon discover that almost all of the definitions are built on definitions of other, more primitive functions, as [47mbinding[0m is built on [47m[assoc-equal][0m. You can look at those as well, of course, or in many cases visit their documentation. The other problem with using a predefined book is that it will seldom be ``sufficiently complete,'' in the sense that the collection of [rewrite] rules supplied won't be adequate to prove everything we'd like to know about the interactions of the various functions. If it were, there'd be no real reason to know that [47mbinding[0m is built on top of [47m[assoc-equal][0m, because everything we'd need to know about [47mbinding[0m would be nicely expressed in the collection of theorems supplied with the book. However, that's very seldom the case. Developing such a collection of rules is currently more art than science and requires considerable experience. We'll encounter examples later of ``missing'' facts about [47mbinding[0m and our other alist functions. So, let's get on with the example. Notice that alists are mappings of keys to values; but, there is no notion of a ``type'' associated with the keys or with the values. Our phone book example, however, does have such a notion of types; we map names to phone numbers. We can introduce these ``types'' by explicitly defining them, e.g., names are strings and phone numbers are integers. Alternatively, we can [31;1mpartially define[0m or axiomatize a recognizer for names without giving a full definition. A way to safely introduce such ``constrained'' function symbols in ACL2 is with the [47m[encapsulate][0m form. For example, consider the following form. (encapsulate ;; Introduce a recognizer for names and give a ``type'' lemma. (((namep *) => *)) ;; (local (defun namep (x) ;; This declare is needed to tell ;; ACL2 that we're aware that the ;; argument x is not used in the body ;; of the function. (declare (ignore x)) t)) ;; (defthm namep-booleanp (booleanp (namep x)))) This [47m[encapsulate][0m form introduces the new function [47mnamep[0m of one argument and one result and constrains [47m(namep x)[0m to be Boolean, for all inputs [47mx[0m. More generally, an encapsulation establishes an environment in which functions can be defined and theorems and rules added without necessarily introducing those functions, theorems, and rules into the environment outside the encapsulation. To be admissible, all the events in the body of an encapsulate must be admissible. But the effect of an encapsulate is to assume only the non-local events. The first ``argument'' to [47mencapsulate[0m, [47m(((namep *) => *))[0m above, declares the intended [signature]s of new function symbols that will be ``exported'' from the encapsulation without definition. The [47m[local][0m [47m[defun][0m of [47mname[0m defines name within the encapsulation always to return [47mt[0m. The [47mdefthm[0m event establishes that [47mnamep[0m is Boolean. By making the [47mdefun[0m local but the [47mdefthm[0m non-[47mlocal[0m this encapsulate constrains the undefined function [47mnamep[0m to be Boolean; the admissibility of the encapsulation establishes that there exists a Boolean function (namely the constant function returning [47mt[0m). We can subsequently use [47mnamep[0m as we use any other Boolean function, with the proviso that we know nothing about it except that it always returns either [47mt[0m or [47mnil[0m. We use [47mnamep[0m to ``recognize'' legal keys for our phonebook alist. We wish to do something similar to define what it means to be a legal phone number. We submit the following form to ACL2. (encapsulate ;; Introduce a recognizer for phone numbers. (((pnump *) => *)) ;; (local (defun pnump (x) (not (equal x nil)))) ;; (defthm pnump-booleanp (booleanp (pnump x))) ;; (defthm nil-not-pnump (not (pnump nil)))) This introduces a Boolean-valued recognizer [47mpnump[0m, with the additional proviso that the constant [47mnil[0m is not a [47mpnump[0m. We impose this restriction to guarantee that we'll never bind a name to [47mnil[0m in our phone book and thereby introduce the kind of ambiguity described above regarding the use of [47mbinding[0m. Now a legal phone book is an alist mapping from [47mnamep[0ms to [47mpnump[0ms. We can define this as follows: (defun name-phonenum-pairp (x) ;; Recognizes a pair of (name . pnum). (and (consp x) (namep (car x)) (pnump (cdr x)))) (defun phonebookp (l) ;; Recognizes a list of such pairs. (if (not (consp l)) (null l) (and (name-phonenum-pairp (car l)) (phonebookp (cdr l))))) Thus, a phone book is really a list of pairs [47m(name . pnum)[0m. Notice that we have not assumed that the keys of the phone book are distinct. We'll worry about that question later. (It is not always desirable to insist that the keys of an alist be distinct. But it may be a useful requirement for our specific example.) Now we are ready to define some of the functions necessary for our phonebook example. The functions we need are: (IN-BOOK? NM BK) ; does NM have a phone number in BK (FIND-PHONE NM BK) ; find NM's phone number in phonebook BK (ADD-PHONE NM PNUM BK) ; give NM the phone number PNUM in BK (CHANGE-PHONE NM PNUM BK) ; change NM's phone number to PNUM in BK (DEL-PHONE NM PNUM) ; remove NM's phone number from BK Given our underlying theory of alists, it is easy to write these functions. But we must take care to specify appropriate ``boundary'' behavior. Thus, what behavior do we want when, say, we try to change the phone number of a client who is not currently in the book? As usual, there are numerous possibilities; here we'll assume that we return the phone book unchanged if we try anything ``illegal.'' Possible definitions of our phone book functions are as follows. (Remember, an [47minclude-book[0m form such as the ones shown earlier must be executed in order to provide definitions for functions such as [47mbound?[0m.) (defun in-book? (nm bk) (bound? nm bk)) (defun find-phone (nm bk) (binding nm bk)) (defun add-phone (nm pnum bk) ;; If nm already in-book?, make no change. (if (in-book? nm bk) bk (bind nm pnum bk))) (defun change-phone (nm pnum bk) ;; Make a change only if nm already has a phone number. (if (in-book? nm bk) (bind nm pnum bk) bk)) (defun del-phone (nm bk) ;; Remove the binding from bk, if there is one. (rembind nm bk)) Notice that we don't have to check whether a name is in the book before deleting, because [47mrembind[0m is essentially a no-op if [47mnm[0m is not bound in [47mbk[0m. In some sense, this completes our specification. But we can't have any real confidence in its correctness without validating our specification in some way. One way to do so is by proving some properties of our specification. Some candidate properties are: 1. A name will be in the book after we add it. 2. We will find the most recently added phone number for a client. 3. If we change a number, we'll find the change. 4. Changing and then deleting a number is the same as just deleting. 5. A name will not be in the book after we delete it. Let's formulate some of these properties. The first one, for example, is: (defthm add-in-book (in-book? nm (add-phone nm pnum bk))). You may wonder why we didn't need any hypotheses about the ``types'' of the arguments. In fact, [47madd-in-book[0m is really expressing a property that is true of alists in general, not just of the particular variety of alists we are dealing with. Of course, we could have added some extraneous hypotheses and proved (defthm add-in-book (implies (and (namep nm) (pnump pnum) (phonebookp bk)) (in-book? nm (add-phone nm pnum bk)))) but that would have yielded a weaker and less useful lemma because it would apply to fewer situations. In general, it is best to state lemmas in the most general form possible and to eliminate unnecessary hypotheses whenever possible. The reason for that is simple: lemmas are usually stored as rules and used in later proofs. For a lemma to be used, its hypotheses must be relieved (proved to hold in that instance); extra hypotheses require extra work. So we avoid them whenever possible. There is another, more important observation to make about our lemma. Even in its simpler form (without the extraneous hypotheses), the lemma [47madd-in-book[0m may be useless as a [rewrite] rule. Notice that it is stated in terms of the non-recursive functions [47min-book?[0m and [47madd-phone[0m. If such functions appear in the left hand side of the conclusion of a lemma, the lemma may not ever be used. Suppose in a later proof, the theorem prover encountered a [term] of the form: (in-book? nm (add-phone nm pnum bk)). Since we've already proved [47madd-in-book[0m, you'd expect that this would be immediately reduced to true. However, the theorem prover will often ``expand'' the non-recursive definitions of [47min-book?[0m and [47madd-phone[0m using their definitions [31;1mbefore[0m it attempts rewriting with lemmas. After this expansion, lemma [47madd-in-book[0m won't ``match'' the [term] and so won't be applied. Look back at the proof script for [47madd-in-proof[0m and you'll notice that at the very end the prover warned you of this potential difficulty when it printed: Warnings: Non-rec Time: 0.18 seconds (prove: 0.05, print: 0.00, other: 0.13) ADD-IN-BOOK The ``Warnings'' line notifies you that there are non-recursive function calls in the left hand side of the conclusion and that this problem might arise. Of course, it may be that you don't ever plan to use the lemma for rewriting or that your intention is to [disable] these functions. [Disable]d functions are not expanded and the lemma should apply. However, you should always take note of such warnings and consider an appropriate response. By the way, we noted above that [47mbinding[0m is [disable]d. If it were not, none of the lemmas about [47mbinding[0m in the book we included would likely be of much use for exactly the reason we just gave. For our current example, let's assume that we're just investigating the properties of our specifications and not concerned about using our lemmas for rewriting. So let's go on. If we really want to avoid the warnings, we can add [47m:rule-classes nil[0m to each [47mdefthm[0m event; see [rule-classes]. Property 2 is: we always find the most recently added phone number for a client. Try the following formalization: (defthm find-add-first-cut (equal (find-phone nm (add-phone nm pnum bk)) pnum)) and you'll find that the proof attempt fails. Examining the proof attempt and our function definitions, we see that the lemma is false if [47mnm[0m is already in the book. We can remedy this situation by reformulating our lemma in at least two different ways: (defthm find-add1 (implies (not (in-book? nm bk)) (equal (find-phone nm (add-phone nm pnum bk)) pnum))) (defthm find-add2 (equal (find-phone nm (add-phone nm pnum bk)) (if (in-book? nm bk) (find-phone nm bk) pnum))) For technical reasons, lemmas such as [47mfind-add2[0m, i.e., which do not have hypotheses, are usually slightly preferable. This lemma is stored as an ``unconditional'' [rewrite] rule (i.e., has no hypotheses) and, therefore, will apply more often than [47mfind-add1[0m. However, for our current purposes either version is all right. Property 3 says: If we change a number, we'll find the change. This is very similar to the previous example. The formalization is as follows. (defthm find-change (equal (find-phone nm (change-phone nm pnum bk)) (if (in-book? nm bk) pnum (find-phone nm bk)))) Property 4 says: changing and then deleting a number is the same as just deleting. We can model this as follows. (defthm del-change (equal (del-phone nm (change-phone nm pnum bk)) (del-phone nm bk))) Unfortunately, our attempt to prove it failed with the following subgoal under a top-level induction. Subgoal *1/4'' (IMPLIES (AND (CONSP BK) (NOT (EQUAL NM (CAR (CAR BK)))) (NOT (BOUND?-EQUAL NM (CDR BK))) (BOUND?-EQUAL NM BK)) (EQUAL (REMBIND-EQUAL NM (BIND-EQUAL NM PNUM (CDR BK))) (REMBIND-EQUAL NM (CDR BK)))) We have defined [47mdel-phone[0m using [47mrembind[0m, and [47mchange-phone[0m using [47min-book[0m (which uses [47mbound?[0m) and [47mbind[0m; but we have ``equal'' suffixes in the subgoal. The cause is theorems of the form [47m***->***-equal[0m, which are given in the included book. We can use [history]'s [47m:[0m[47m[pl][0m command to print the rules for a given name or term. Here is the part of [47m:[0m[47m[pl][0m's output we are interested in now, for the [47mrembind[0m function: ACL2 !>:pl rembind ... Rune: (:REWRITE REMBIND->REMBIND-EQUAL) Enabled: T Hyps: T Equiv: EQUAL Lhs: (REMBIND X A) Rhs: (REMBIND-EQUAL X A) Backchain-limit-lst: NIL Subclass: ABBREVIATION ... We can see that [rewrite] rule [47mrembind->rembind-equal[0m is [enable]d and that it replaces [3mlhs[0m with [3mrhs[0m. For functions [47mbind[0m, [47mbinding[0m and [47mbound?[0m we have similar rules. Our intuition about [47mrembind[0m and [47mbind[0m tells us that this goal should be true even without the hypotheses. We attempt to prove the following lemma. (defthm rembind-equal-bind-equal (equal (rembind-equal nm (bind-equal nm pnum bk)) (rembind-equal nm bk))) The prover proves this by induction, and stores it as a rewrite rule. After that, the prover has no difficulty in proving [47mdel-change[0m. The need to prove lemma [47mrembind-equal-bind-equal[0m illustrates a point we made early in this example: the collection of [rewrite] rules supplied by a previously certified book will almost never be everything you'll need. It would be nice if we could operate purely in the realm of names, phone numbers, and phone books without ever having to prove any new facts about alists. Unfortunately, we needed a fact about the relation between [47mrembind-equal[0m and [47mbind-equal[0m that wasn't supplied with the alists theory. Hopefully, such omissions will be rare. Let's take two steps back now (just enter the [47m:u[0m command twice) to get acquainted with a method that will be very useful to us. What happens if we state the previous lemma another way? (defthm rembind-bind (equal (rembind name (bind name num book)) (rembind name book))) An attempt to prove [47mdel-change[0m would fail then with the same subgoal as above. In this case we can give to the prover the hint to use [47mrembind-bind[0m as an instance of [47mdel-change[0m (see [hints] and find keywords [47m:use[0m and [47m:instance[0m): (defthm del-change-lemma-instance-example (equal (del-phone nm (change-phone nm pnum bk)) (del-phone nm bk)) :hints (("Goal" :use (:instance rembind-bind (name nm) (num pnum) (book bk))))) As described in [hints], a [47m:use[0m hint causes the prover to replace a goal [47mG[0m with new goal ([47mIMPLIES[0m [47mP[0m [47mG[0m), where [47mP[0m is the specified theorem to use. The [47m:instance[0m form specifies instantiation of the free variables of a previously proved theorem. See [lemma-instance] for more information on this subject. Finally, let's consider our property 5 above: a name will not be in the book after we delete it. We formalize this as follows: (defthm in-book-del (not (in-book? nm (del-phone nm bk)))) This proves easily. But notice that it's only true because [47mdel-phone[0m (actually [47mrembind[0m) removes [31;1mall[0m occurrences of a name from the phone book. If it only removed, say, the first one it encountered, we'd need a hypothesis that said that [47mnm[0m occurs at most once in [47mbk[0m. Ah, maybe that's a property you hadn't considered. Maybe you want to ensure that [31;1many[0m name occurs at most once in any valid phonebook. To complete this example, let's consider adding an [31;1minvariant[0m to our specification. In particular, suppose we want to ensure that no client has more than one associated phone number. One way to ensure this is to require that the domain of the alist is a ``set'' (has no duplicates). (defun setp (l) (if (atom l) (null l) (and (not (member-equal (car l) (cdr l))) (setp (cdr l))))) (defun valid-phonebookp (bk) (and (phonebookp bk) (setp (domain bk)))) Now, we want to show under what conditions our operations preserve the property of being a [47mvalid-phonebookp[0m. The operations [47min-book?[0m and [47mfind-phone[0m don't return a phone book, so we don't really need to worry about them. Since we're really interested in the ``types'' of values preserved by our phonebook functions, let's look at the types of those operations as well. (defthm in-book-booleanp (booleanp (in-book? nm bk))) (defthm in-book-namep (implies (and (phonebookp bk) (in-book? nm bk)) (namep nm)) :hints (("Goal" :in-theory (enable bound?-equal)))) (defthm find-phone-pnump (implies (and (phonebookp bk) (in-book? nm bk)) (pnump (find-phone nm bk))) :hints (("Goal" :in-theory (enable bound?-equal binding-equal)))) Note the ``[47m:[0m[47m[hints][0m'' on the last two lemmas. Neither of these would prove without these [hints], because once again there are some facts about [47mbound?-equal[0m and [47mbinding-equal[0m not available in our current context. Now, we could figure out what those facts are and try to prove them. Alternatively, we can [enable] [47mbound?-equal[0m and [47mbinding-equal[0m and hope that by opening up these functions, the conjectures will reduce to versions that the prover does know enough about, perhaps using proof by induction. In this case, this strategy works. The hints tell the prover to [enable] the functions in question when considering the designated goal and any subgoals of it. It's important to understand that it's not enough to [enable] the [47mbound?[0m and [47mbinding[0m functions. That's because rewrite rules of the form [47m***->***-equal[0m (mentioned above) will replace [enable]d functions with [disable]d ones for which there are not sufficient rules to complete the proof. We can use [history]'s very informative command [47m:[0m[pl] to get a lot of information about rules for a given name. Below we develop the theorems showing that [47madd-phone[0m, [47mchange-phone[0m, and [47mdel-phone[0m preserve our proposed invariant. Notice that along the way we have to prove some subsidiary facts, some of which are pretty ugly. It would be a good idea for you to try, say, [47madd-phone-preserves-invariant[0m without introducing the following four lemmas first. Perhaps you will use the instantiation of lemmas method, described above. See if you can develop the proof and only add these lemmas as you need assistance. Then try [47mchange-phone-preserves-invariant[0m and [47mdel-phone-preserves-invariant[0m. They will be easier. It is illuminating to think about why [47mdel-phone-preserves-invariant[0m does not need any ``type'' hypotheses. (defthm bind-preserves-phonebookp (implies (and (phonebookp bk) (namep nm) (pnump num)) (phonebookp (bind nm num bk)))) (defthm member-equal-strip-cars-bind-equal (implies (and (not (equal x y)) (not (member-equal x (strip-cars a)))) (not (member-equal x (strip-cars (bind-equal y z a)))))) (defthm bind-equal-preserves-domain-setp (implies (and (alistp bk) (setp (domain bk))) (setp (domain (bind-equal nm num bk)))) :hints (("Goal" :in-theory (enable domain)))) Let's take two steps back (using [47m:u[0m twice) and prove the following instead of [47mmember-equal-strip-cars-bind-equal[0m: (defthm member-equal-strip-cars-bind (implies (and (not (equal x y)) (not (member-equal x (strip-cars a)))) (not (member-equal x (strip-cars (bind y z a)))))) Then [47mbind-equal-preserves-domain-setp[0m fails: Subgoal *1/5'' (IMPLIES (AND (CONSP BK) (NOT (EQUAL NM (CAR (CAR BK)))) (SETP (STRIP-CARS (BIND-EQUAL NM NUM (CDR BK)))) (CONSP (CAR BK)) (ALISTP (CDR BK)) (NOT (MEMBER-EQUAL (CAR (CAR BK)) (STRIP-CARS (CDR BK)))) (SETP (STRIP-CARS (CDR BK)))) (NOT (MEMBER-EQUAL (CAR (CAR BK)) (STRIP-CARS (BIND-EQUAL NM NUM (CDR BK)))))) We can use a [lemma-instance] to prove it: (defthm bind-equal-preserves-domain-setp (implies (and (alistp bk) (setp (domain bk))) (setp (domain (bind-equal nm num bk)))) :hints (("Goal" :in-theory (enable domain)) ("Subgoal *1/5''" :use (:instance member-equal-strip-cars-bind (x (car (car bk))) (y nm) (z num) (a (cdr bk)))))) The use of [lemma-instance] is somewhat artificial in this example, but this method gives great opportunities to lead ACL2 in proving theorems. That said, it is generally preferable to avoid [47m:use[0m hints in favor of developing a useful set of [rewrite] rules, since those rules can help to automate future proof attempts. We continue now with proofs that our operations preserve the [47mphonebook'[0m invariant. (defthm phonebookp-alistp (implies (phonebookp bk) (alistp bk))) (defthm bind-equal-preserves-phonebookp (implies (and (phonebookp bk) (namep nm) (pnump num)) (phonebookp (bind-equal nm num bk)))) (defthm add-phone-preserves-invariant (implies (and (valid-phonebookp bk) (namep nm) (pnump num)) (valid-phonebookp (add-phone nm num bk))) :hints (("Goal" :in-theory (disable domain-bind-equal)))) (defthm change-phone-preserves-invariant (implies (and (valid-phonebookp bk) (namep nm) (pnump num)) (valid-phonebookp (change-phone nm num bk))) :hints (("Goal" :in-theory (disable domain-bind-equal)))) (defthm member-remove-equal (implies (and (not (equal a b)) (not (member a x))) (not (member a (remove-equal b x))))) (defthm remove-equal-preserves-setp (implies (setp l) (setp (remove-equal x l)))) (defthm del-phone-preserves-invariant (implies (valid-phonebookp bk) (valid-phonebookp (del-phone nm bk)))) As a final test of your understanding, try to formulate and prove an invariant that says that no phone number is assigned to more than one name. The following hints may help. 1. Define the appropriate invariant. (Hint: remember the function [47mrange[0m.) 2. Do our current definitions of [47madd-phone[0m and [47mchange-phone[0m necessarily preserve this property? If not, consider what hypotheses are necessary in order to guarantee that they do preserve this property. 3. Study the definition of the function [47mrange[0m and notice that it is defined in terms of the function [47m[strip-cdrs][0m. Understand how this defines the range of an alist. 4. Formulate the correctness theorems and attempt to prove them. You'll probably benefit from studying the invariant proof above. In particular, you may need some fact about the function [47m[strip-cdrs][0m analogous to the lemma [47mmember-equal-strip-cars-bind[0m above. Below is one solution to this exercise. Don't look at the solution, however, until you've struggled a bit with it. Notice that we didn't actually change the definitions of [47madd-phone[0m and [47mchange-phone[0m, but added a hypothesis saying that the number is ``new.'' We could have changed the definitions to check this and return the phonebook unchanged if the number was already in use. (defun pnums-in-use (bk) (range bk)) (defun phonenums-unique (bk) (setp (pnums-in-use bk))) (defun new-pnump (pnum bk) (not (member-equal pnum (pnums-in-use bk)))) (defthm member-equal-strip-cdrs-rembind (implies (not (member-equal x (strip-cdrs y))) (not (member-equal x (strip-cdrs (rembind-equal z y)))))) (defthm del-phone-preserves-phonenums-unique (implies (phonenums-unique bk) (phonenums-unique (del-phone nm bk))) :hints (("Goal" :in-theory (enable range)))) (defthm strip-cdrs-bind-non-member (implies (and (not (bound?-equal x a)) (alistp a)) (equal (strip-cdrs (bind-equal x y a)) (append (strip-cdrs a) (list y)))) :hints (("Goal" :in-theory (enable bound?-equal)))) (defthm member-append (iff (member e (append x y)) (or (member e x) (member e y)))) (defthm setp-append-list (implies (setp l) (equal (setp (append l (list x))) (not (member-equal x l))))) (defthm add-phone-preserves-phonenums-unique (implies (and (phonenums-unique bk) (new-pnump pnum bk) (alistp bk)) (phonenums-unique (add-phone nm pnum bk))) :hints (("Goal" :in-theory (enable range)))) (defthm member-equal-strip-cdrs-bind-equal (implies (and (not (member-equal z (strip-cdrs a))) (not (equal z y))) (not (member-equal z (strip-cdrs (bind-equal x y a)))))) (defthm change-phone-preserves-phonenums-unique (implies (and (phonenums-unique bk) (new-pnump pnum bk) (alistp bk)) (phonenums-unique (change-phone nm pnum bk))) :hints (("Goal" :in-theory (enable range))))") (tutorial4-defun-sk-example (annotated-acl2-scripts) "Example of quantified notions This example illustrates the use of [47m[defun-sk][0m and [47m[defthm][0m [events] to reason about quantifiers. See [defun-sk]. For a more through, systematic beginner's introduction to quantification in ACL2, see [quantifier-tutorial]. Many users prefer to avoid the use of quantifiers, since ACL2 provides only very limited support for reasoning about quantifiers. Here is a list of [events] that proves that if there are arbitrarily large numbers satisfying the disjunction [47m(OR P R)[0m, then either there are arbitrarily large numbers satisfying [47mP[0m or there are arbitrarily large numbers satisfying [47mR[0m. ; Introduce undefined predicates p and r. (defstub p (x) t) (defstub r (x) t) ; Define the notion that something bigger than x satisfies p. (defun-sk some-bigger-p (x) (exists y (and (< x y) (p y)))) ; Define the notion that something bigger than x satisfies r. (defun-sk some-bigger-r (x) (exists y (and (< x y) (r y)))) ; Define the notion that arbitrarily large x satisfy p. (defun-sk arb-lg-p () (forall x (some-bigger-p x))) ; Define the notion that arbitrarily large x satisfy r. (defun-sk arb-lg-r () (forall x (some-bigger-r x))) ; Define the notion that something bigger than x satisfies p or r. (defun-sk some-bigger-p-or-r (x) (exists y (and (< x y) (or (p y) (r y))))) ; Define the notion that arbitrarily large x satisfy p or r. (defun-sk arb-lg-p-or-r () (forall x (some-bigger-p-or-r x))) ; Prove the theorem promised above. Notice that the functions open ; automatically, but that we have to provide help for some rewrite ; rules because they have free variables in the hypotheses. The ; ``witness functions'' mentioned below were introduced by DEFUN-SK. (thm (implies (arb-lg-p-or-r) (or (arb-lg-p) (arb-lg-r))) :hints (("Goal" :use ((:instance some-bigger-p-suff (x (arb-lg-p-witness)) (y (some-bigger-p-or-r-witness (max (arb-lg-p-witness) (arb-lg-r-witness))))) (:instance some-bigger-r-suff (x (arb-lg-r-witness)) (y (some-bigger-p-or-r-witness (max (arb-lg-p-witness) (arb-lg-r-witness))))) (:instance arb-lg-p-or-r-necc (x (max (arb-lg-p-witness) (arb-lg-r-witness)))))))) ; And finally, here's a cute little example. We have already ; defined above the notion (some-bigger-p x), which says that ; something bigger than x satisfies p. Let us introduce a notion ; that asserts that there exists both y and z bigger than x which ; satisfy p. On first glance this new notion may appear to be ; stronger than the old one, but careful inspection shows that y and ; z do not have to be distinct. In fact ACL2 realizes this, and ; proves the theorem below automatically. (defun-sk two-bigger-p (x) (exists (y z) (and (< x y) (p y) (< x z) (p z)))) (thm (implies (some-bigger-p x) (two-bigger-p x))) ; A technical point: ACL2 fails to prove the theorem above ; automatically if we take its contrapositive, unless we disable ; two-bigger-p as shown below. That is because ACL2 needs to expand ; some-bigger-p before applying the rewrite rule introduced for ; two-bigger-p, which contains free variables. The moral of the ; story is: Don't expect too much automatic support from ACL2 for ; reasoning about quantified notions. (thm (implies (not (two-bigger-p x)) (not (some-bigger-p x))) :hints (("Goal" :in-theory (disable two-bigger-p))))") (tutorial5-miscellaneous-examples (annotated-acl2-scripts) "Miscellaneous ACL2 examples The following examples are more advanced examples of usage of ACL2. They are included largely for reference, in case someone finds them useful. Subtopics [File-reading-example] Example of reading files in ACL2 [Functional-instantiation-example] A small proof demonstrating functional instantiation [Guard-example] A brief transcript illustrating [guard]s in ACL2 [Mutual-recursion-proof-example] A small proof about mutually recursive functions") (type (pointers) "Disambiguation page for [3mtype[0m-related concepts. The word [31;1mtype[0m might mean many things in ACL2. Built-in Types ACL2 can reason about and compute with certain different kinds of objects, such as [numbers], [strings], [characters], and [conses]. See [About_Types] for basic background on the different kinds of ACL2 objects; also see [type-reasoning] for additional relevant background. User-Defined Types When modeling systems with ACL2, you may often want to introduce certain concepts as new data types. For instance, if you are modeling a network, you might want [47mhost[0m and [47mconnection[0m objects. ACL2 does not directly support introducing new types. Instead, such types are usually ``emulated'' by introducing a new [3mrecognizer[0m function, say [47mhostp[0m, and perhaps some related [3mconstructor[0m and [3maccessor[0m functions, say [47mmake-host[0m and [47mhost->name[0m. Macro libraries can help to assist with introducing common types. See for instance [std/util], [defdata], or [fty]. Type Declarations For more efficient Common Lisp execution, ACL2 functions can be annotated with Common Lisp type specifiers (see [type-spec]) that may boost performance by reducing run-time type checking. This mechanism is integrated with ACL2's [guard] mechanism, so you can prove your type declarations are correct. See also [declare] and [the], and also [patbind-the]. Type Prescriptions ACL2 includes a limited but efficient ``type reasoning (see [TYPE-REASONING])'' engine for determining whether objects are of certain [31;1mbuilt-in[0m types. This engine can be extended with [type-prescription] rules. Such rules are often inferred automatically when new functions are introduced with [defun]. Type reasoning can assist other reasoning engines like [forward-chaining], [linear-arithmetic], and rewriting. Type-set information is stored in a [type-alist] data structure; see [type-reasoning] for relevant basic background... Tau ACL2 includes another reasoning engine, the [tau-system], for reasoning about type-like predicates. Unlike [type-set], Tau can also be used for reasoning about [31;1muser-defined types[0m, and can also carry out certain interval arithmetic reasoning. See the [introduction-to-the-tau-system] for more information about Tau.") (type-alist (type-set) "An ACL2 representation of contextual knowledge See [type-reasoning] for basic background on type reasoning in ACL2. The ACL2 prover maintains many structures that need not be understood by the user. One of these, the [3mtype-alist[0m structure, is usually in this category. But some utilities refer to the type-alist, so we summarize it here. A type-alist is an association list, each element of which is of the form [47m(u ts . ttree)[0m, where [47mu[0m is a [term] (in internal, ``translated'' form), [47mts[0m is a [type-set], and [47mttree[0m is a tag-tree (see [ttree]). Such an element means that the term [47mu[0m has the type-set [47mts[0m, which is a number. While you are welcome to see the [documentation] of [type-set] for details, this is not necessary, since user-level utilities generally display a type-alist without displaying numeric type-sets. Instead, they often use a symbol of the form [47m*TS-typ*[0m to denote the type described by [47mtyp[0m, and for complements they use [47m(TS-COMPLEMENT *TS-typ*)[0m. For example, a context in which the terms [47m(p x y)[0m, [47m(no-duplicatesp-equal y)[0m, and [47m(natp x)[0m are assumed to be true (i.e., non-[47mnil[0m) may be displayed using the following lines. ----- Terms with type *TS-T*: (NO-DUPLICATESP-EQUAL Y) ----- Terms with type (TS-COMPLEMENT *TS-NIL*): (P X Y) ----- Terms with type *TS-NON-NEGATIVE-INTEGER*: X ----- These lines says that [47m(no-duplicatesp-equal y)[0m is the symbol [47mt[0m, [47m(p x y)[0m is not the symbol [47mnil[0m, and [47mx[0m is a non-negative integer (i.e., a [47m[natp][0m). ACL2 computes a type-alist based on contextual information including the hypotheses of the current goal (technically: the negations of the literals in the goal that are not currently being rewritten), [forward-chaining] from those literals, and the surrounding tests in calls of [47mif[0m. The type-alist is of course not all that is known, since an entire logical [world] of facts is also known; and additional known information may be recorded in the current database of [linear] rules.") (type-prescription (rule-classes) "Make a rule that specifies the type of a term See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Also see [type-reasoning] for basic background on type reasoning in ACL2. In this topic we focus on user-defined type-prescription rules, but note that ACL2 also introduces type-prescription rules when introducing a function with [47m[defun][0m; see [type-prescription-debugging] for discussion of how to influence the generation of such rules. Examples: (defthm integerp-foo ; Assumes that foo has been (integerp (foo x y)) ; defined; then, states that :rule-classes :type-prescription) ; (foo x y) is of type integer. (defthm characterp-nth-type-prescription ; (Nth n lst) is of type character (implies ; provided the hypotheses can be (and (character-listp lst) ; established by type reasoning. (<= 0 n) (< n (len lst))) (characterp (nth n lst))) :rule-classes :type-prescription) (defthm characterp-nth-type-prescription-alt ; equivalent to the above (implies (and (character-listp lst) (<= 0 n) (< n (len lst))) (characterp (nth n lst))) :rule-classes ((:type-prescription :typed-term (nth n lst)))) (defthm demodulize-type-for-quote-value ; (Demodulize a lst 'value ans) is (implies ; either a nonnegative integer or (and (atom a) ; of the same type as ans, provided (true-listp lst) ; the hyps can be established by type (member-equal a lst)) ; reasoning ; (or (and (integerp (demodulize a lst 'value ans)) (>= (demodulize a lst 'value ans) 0)) (equal (demodulize a lst 'value ans) ans))) :rule-classes :type-prescription) To specify the term whose type (see [type-set]) is described by the rule, provide that term as the value of the [47m:typed-term[0m field of the rule class object. General Form (after preprocessing; see below): (implies hyps (or type-restriction1-on-pat ... type-restrictionk-on-pat (equal pat var1) ... (equal pat varj))) where [47mpat[0m is the application of some function symbol to some arguments, each [47mtype-restrictioni-on-pat[0m is a term involving [47mpat[0m and containing no variables outside of the occurrences of [47mpat[0m, and each [47mvari[0m is one of the variables of [47mpat[0m. Generally speaking, the [47mtype-restriction[0m terms ought to be terms that inform us as to the type of [47mpat[0m. Ideally, they should be ``primitive recognizing expressions'' about [47mpat[0m; see [compound-recognizer]. We describe preprocessing at the end of this topic. If the [47m:typed-term[0m is not provided in the rule class object, it is computed heuristically by looking for a term in the conclusion whose type is being restricted. An error is caused if no such term is found. Roughly speaking, the effect of adding such a rule is to inform the ACL2 typing mechanism that [47mpat[0m has the type described by the conclusion, when the hypotheses are true. In particular, the type of [47mpat[0m is within the union of the types described by the several disjuncts. The ``type described by'' [47m(equal pat vari)[0m is the type of [47mvari[0m. More operationally, when asked to determine the type of a term that is an instance of [47mpat[0m, ACL2 will first attempt to establish the hypotheses. [31;1mThis is done by type reasoning alone, not rewriting![0m However, if some hypothesis is a call of [47m[force][0m, then forcing may occur, which may ultimately invoke the rewriter; see [force] and see [case-split]. So-called free variables in hypotheses are treated specially; see [free-variables]. Provided the hypotheses are established by type reasoning, ACL2 then unions the types described by the [47mtype-restrictioni-on-pat[0m terms together with the types of those subexpressions of [47mpat[0m identified by the [47mvari[0m. The final type computed for a term is the intersection of the types implied by each applicable rule. Type prescription rules may be disabled. You can limit the recursive establishment of hypotheses of rules; see [set-backchain-limit]. Because only type reasoning is used to establish the hypotheses of [47m:type-prescription[0m rules, some care must be taken with the hypotheses. Suppose, for example, that the non-recursive function [47mmy-statep[0m is defined as (defun my-statep (x) (and (true-listp x) (equal (len x) 2))) and suppose [47m(my-statep s)[0m occurs as a hypothesis of a [47m:type-prescription[0m rule that is being considered for use in the proof attempt for a conjecture with the hypothesis [47m(my-statep s)[0m. Since the hypothesis in the conjecture is rewritten, it will become the conjunction of [47m(true-listp s)[0m and [47m(equal (len s) 2)[0m. Those two terms will be assumed to have type [47mt[0m in the context in which the [47m:type-prescription[0m rule is tried. But type reasoning will be unable to deduce that [47m(my-statep s)[0m has type [47mt[0m in this context. Thus, either [47mmy-statep[0m should be disabled (see [disable]) during the proof attempt or else the occurrence of [47m(my-statep s)[0m in the [47m:type-prescription[0m rule should be replaced by the conjunction into which it rewrites. While this example makes it clear how non-recursive predicates can cause problems, non-recursive functions in general can cause problems. For example, if [47m(mitigate x)[0m is defined to be [47m(if (rationalp x) (1- x) x)[0m then the hypothesis [47m(pred (mitigate s))[0m in the conjecture will rewrite, opening [47mmitigate[0m and splitting the conjecture into two subgoals, one in which [47m(rationalp s)[0m and [47m(pred (1- x))[0m are assumed and the other in which [47m(not (rationalp s))[0m and [47m(pred x)[0m are assumed. But [47m(pred (mitigate s))[0m will not be typed as [47mt[0m in either of these contexts. The moral is: beware of non-recursive functions occurring in the hypotheses of [47m:type-prescription[0m rules. Because of the freedom one has in forming the conclusion of a type-prescription, we have to use heuristics to recover the pattern, [47mpat[0m, whose type is being specified. In some cases our heuristics may not identify the intended term and the [47m:type-prescription[0m rule will be rejected as illegal because the conclusion is not of the correct form. When this happens you may wish to specify the [47mpat[0m directly. This may be done by using a suitable rule class token. In particular, when the token [47m:type-prescription[0m is used it means ACL2 is to compute pat with its heuristics; otherwise the token should be of the form [47m(:type-prescription :typed-term pat)[0m, where [47mpat[0m is the term whose type is being specified. The defun event may generate a [47m:type-prescription[0m rule. Suppose [47mfn[0m is the name of the function concerned. Then [47m(:type-prescription fn)[0m is the rune given to the type-prescription, if any, generated for [47mfn[0m by [47m[defun][0m. (The trivial rule, saying [47mfn[0m has unknown type, is not stored, but [47m[defun][0m still allocates the rune and the corollary of this rune is known to be [47mt[0m.) We close with a discussion of how, before a term is parsed into a [47m:type-prescription[0m rule, it is preprocessed. We describe this preprocessing in some detail below, but first consider the following (contrived) example. (defthm append-tp-example (let ((result (append x y))) (implies (nat-listp x) (implies (let ((second-hyp (integer-listp y))) second-hyp) (true-listp result)))) :rule-classes :type-prescription) This theorem is parsed into a type-prescription rule with the following hypotheses and conclusion. (nat-listp x) ; first hypothesis ((lambda (second-hyp) second-hyp) (integer-listp y)) ; second hypothesis (true-listp (binary-append x y)) ; conclusion Notice that the top-level [47m[let][0m was expanded, i.e., [47m(append x y)[0m was substituted for [47mresult[0m --- more accurately, [47m(binary-append x y)[0m was substituted for [47mresult[0m, since [47m[append][0m is a macro that abbreviates [47m[binary-append][0m. Also notice that the two hypotheses were ``flattened'' in the sense that they were gathered up into a list. Finally, notice that the [47m[let][0m in the second hypothesis was not expanded (it was merely translated to internal form, using [47mLAMBDA[0m). If you actually submit the theorem above, you will get warnings, which you may choose to ignore; the application of [47mtype-prescription[0m rules is somewhat subtle, so if you use them then you may wish to experiment to see which forms work best for you. Here is the detail promised above, for parsing a term into a [47m:type-prescription[0m rule. There are two steps. (1) ACL2 first translates the term, expanding all macros (see [trans]) and also removing [guard-holders]. (2) Then the translated term is traversed top-down, expanding away [47mlambda[0ms ([47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m expressions) and flattening the [47m[implies][0m structure, until the conclusion is exposed; then the conclusion's [47mlambda[0ms are also expanded away. The simplest way to understand (2) may be to look at the definition of ACL2 source function [47munprettyify-tp[0m, which implements Step (2), say by evaluating [47m:[0m[47m[pe][0m[47m unprettyify-tp[0m. Subtopics [Backchain-limit] Limiting the effort expended on relieving hypotheses [Case-split] Like force but immediately splits the top-level goal on the hypothesis [Force] Identity function used to force a hypothesis [Type-prescription-debugging] Improve a built-in [type-prescription] rule") (type-prescription-debugging (debugging type-prescription) "Improve a built-in [type-prescription] rule A [type-prescription] rule is introduced automatically when a function is defined (see [defun]). However, that rule might not be what you expect. In this topic we explore how you might be able to improve that rule, by way of an example. First consider the following definition. ACL2 !>(defun f (x) (alistp x)) Since F is non-recursive, its admission is trivial. We observe that the type of F is described by the theorem (OR (EQUAL (F X) T) (EQUAL (F X) NIL)). We used the :type-prescription rule ALISTP. Summary Form: ( DEFUN F ...) Rules: ((:TYPE-PRESCRIPTION ALISTP)) Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.00) F ACL2 !> Notice in particular the phrase, ``We used the :type-prescription rule ALISTP,'' and the corresponding [rune] [47m(:TYPE-PRESCRIPTION ALISTP)[0m in the list of rules printed in the [summary]. These are telling us that ACL2 used the indicated rule during the process of computing a [type-prescription] rule for [47mf[0m. Now suppose that in a different session we instead proceed as follows. ACL2 !>(in-theory (disable (:type-prescription alistp))) Summary Form: ( IN-THEORY (DISABLE ...)) Rules: NIL Time: 0.01 seconds (prove: 0.00, print: 0.00, other: 0.01) (:NUMBER-OF-ENABLED-RUNES 3298) ACL2 !>(defun f (x) (alistp x)) Since F is non-recursive, its admission is trivial. We could deduce no constraints on the type of F. Summary Form: ( DEFUN F ...) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) F ACL2 !> Notice that this time ``We could deduce no constraints on the type of F,'' because in this context, [type-set] reasoning does not see that the body of [47mf[0m is a Boolean, because [47m(:type-prescription alistp)[0m has been [disable]d. Thus, the ``Rules'' field of the summary is empty this time. Consider the following story. On Monday, you run the first session, and a subsequent proof uses [type-set] reasoning to conclude that [47m(f x)[0m is Boolean, even after you [disable] the [definition] of [47mf[0m. Then on Tuesday, you run the second session, and are surprised to find that ACL2 no longer reasons (during that same subsequent proof attempt) that [47m(f x)[0m is Boolean. You want to debug this problem, so you look back in the log where you defined [47mf[0m, and you see the ``deduce no constraints'' message --- but then you look further back, at Monday's log, where you find the definition of [47mf[0m ``used the :type-prescription rule ALISTP'' to conclude that ``the type of F is described by the theorem (OR (EQUAL (F X) T) (EQUAL (F X) NIL))''. The mention of ALISTP in that definition's output from Monday, together with the corresponding mention of [47m(:TYPE-PRESCRIPTION ALISTP)[0m in the ``Rules'' field of the summary, leads you to resolve the issue as follows. On Monday, when [47m(:TYPE-PRESCRIPTION ALISTP)[0m was [enable]d, ACL2 used type-set reasoning to conclude that the body of [47mf[0m is Boolean, but on Tuesday, [47m(:TYPE-PRESCRIPTION ALISTP)[0m was disabled at that point and hence the body of [47mf[0m was not known to be Boolean by type-set reasoning. Hence on Tuesday, no Boolean type-prescription rule was stored for [47mf[0m at definition time, which is why the subsequent proof attempt failed to use such a rule. So you avoid disabling [47m(:TYPE-PRESCRIPTION ALISTP)[0m until after submitting the [47m[defun][0m for [47mf[0m, and now ACL2's type reasoning (see [TYPE-REASONING]) knows that [47mf[0m returns a Boolean.") (type-reasoning (rule-classes) "ACL2 reasoning with ``types'' ACL2 has a ``type reasoning'' system, which may be viewed as a relatively basic rule-based theorem prover for questions about Common Lisp types, e.g., ``does this expression produce a [47m[consp][0m?'', ``does this expression produce some kind of ACL2 number, e.g., an [47m[integerp][0m, a [47m[rationalp][0m, or a [47m[complex-rationalp][0m?'', ``does this expression produce a non-[47mnil[0m value (i.e., is it true)?'', etc. This system uses built-in reasoning about types, for example that a rational number is not a cons; when the ACL2 prover reports that a goal is simplified using ``primitive type reasoning'', it is referring to such built-in type reasoning. However, type reasoning is also driven by [type-prescription] rules, as we'll discuss shortly. ACL2 reasoning, including type reasoning, takes place with respect to a context that associates terms with values that represent their ``types''. These contexts are called [type-alist]s, and those values are called [type-set]s; however, unless you write certain sophisticated tools, perhaps such as [clause-processor]s, you probably do not need to know more than that about these two notions. (If you're curious about them, you can see [type-set] and see [type-alist].) For example, when ACL2 attempts to prove a conjecture [47m(implies (and (p x) (integerp (f x))) (p2 x))[0m, it builds a type-alist recording that [47m(p x)[0m and [47m(integerp (f x))[0m are true when attempting to reason about [47m(p2 x)[0m. That type-alist associates [47m(p x)[0m with a value representing the complement of the set, [47m{nil}[0m, meaning that [47m(p x)[0m is non-[47mnil[0m, i.e., true. But for [47m(integerp (f x))[0m something a bit more clever takes place: since [47mintegerp[0m recognizes a Boolean combination of built-in types --- see [compound-recognizer] --- the context associates [47m(f x)[0m with a value representing the set of integers. So for example, type reasoning can conclude from that type-alist that [47m(not (consp (f x)))[0m is true, since the built-in types for integer and cons are disjoint. As noted above, type reasoning can take advantage of [type-prescription] rules. In short, such a rule tells ACL2 that any instance of the ``typed-term'' of the rule must have a specified type. To relieve the hypotheses of type-prescription rules, the type-reasoning system recursively invokes itself. This can be done for any hypothesis, whether it is ``type-like'' or not, since any proposition, [47mp[0m, can be phrased as the type-like question ``does [47mp[0m produce an object of type [47mnil[0m?'' However, as you might expect, the type system is not very good at establishing hypotheses that are not type-like, unless they are represented rather explicitly in the context in which the question is posed. Consider the following example from the [type-prescription] documentation. (defthm characterp-nth-type-prescription ; (Nth n lst) is of type character (implies ; provided the hypotheses can be (and (character-listp lst) ; established by type reasoning. (<= 0 n) (< n (len lst))) (characterp (nth n lst))) :rule-classes :type-prescription) It may seem impossible to relieve the hypothesis [47m(character-listp lst)[0m by type reasoning, since there is no suitable ``type'' for [47mlst[0m, i.e., [47mcharacter-listp[0m does not recognize a Boolean combination of ACL2 types (see [compound-recognizer]). However, suppose we are attempting to prove a theorem of the form [47m(implies (and (character-listp x) p) q)[0m and ACL2 is in the process of simplifying either [47mp[0m or [47mq[0m. In that case, the context --- that is, the type-alist --- will associate the term [47m(character-listp x)[0m with a value indicating that this term is true, i.e., non-[47mnil[0m. Then if ACL2 encounters the term [47m(nth k x)[0m, it will try to apply the type-prescription rule above, matching [47mk[0m to [47mn[0m and matching [47mlst[0m to [47mx[0m. The instantiated first hypothesis of that rule will then be [47m(character-listp x)[0m. Since the type-alist designates [47m(character-listp x)[0m as true, that hypothesis is successfully relieved. Again, there was no [47mcharacter-listp[0m ``type'' involved; what was typed was the entire term, [47m(character-listp x)[0m. The instantiated hypothesis above was relieved because it was in the context, so no rewriting was necessary to establish it. See [force] for how to involve the ACL2 rewriter to establish hypotheses of type-prescription rules. Subtopics [Set-dwp] Affect the effort made in [type-reasoning] [Set-dwp!] Affect the effort made in [type-reasoning], non-[47m[local][0mly") (type-set (miscellaneous) "How type information is encoded in ACL2 See [type-reasoning] for basic background on type reasoning in ACL2. To help you experiment with type-sets we briefly note the following utility functions. [47m(type-set-quote x)[0m will return the type-set of the object [47mx[0m. For example, [47m(type-set-quote "test")[0m is [47m2048[0m and [47m(type-set-quote '(a b c))[0m is [47m512[0m. [47m(type-set 'term nil nil nil (ens state) (w state) nil nil nil)[0m will return the type-set of [47mterm[0m with respect to the current world and the top-level enabled structure. For example, (type-set '(integerp x) nil nil nil (ens state) (w state) nil nil nil) will return (mv 192 nil). 192, otherwise known as [47m*ts-boolean*[0m, is the type-set containing [47mt[0m and [47mnil[0m. The second result may be ignored in these experiments. [47mTerm[0m must be in the [47mtranslated[0m, internal form shown by [47m:[0m[47m[trans][0m. See [trans] and see [term]. [47m(type-set-implied-by-term 'x nil 'term (ens state)(w state) nil)[0m will return the type-set deduced for the variable symbol [47mx[0m assuming the [47mtranslated[0m term, [47mterm[0m, true. The second result may be ignored in these experiments. For example, (type-set-implied-by-term 'v nil '(integerp v) (ens state) (w state) nil) returns [47m11[0m. [47m(convert-type-set-to-term 'x ts (ens state) (w state) nil)[0m will return a term whose truth is equivalent to the assertion that the term [47mx[0m has type-set [47mts[0m. The second result may be ignored in these experiments. For example (convert-type-set-to-term 'v 523 (ens state) (w state) nil) returns a term expressing the claim that [47mv[0m is either an integer or a non-[47mnil[0m true-list. [47m523[0m is the [47mlogical-or[0m of [47m11[0m (which denotes the integers) with [47m512[0m (which denotes the non-[47mnil[0m true-lists). The ``actual primitive types'' of ACL2 are listed in [47m*actual-primitive-types*[0m, whose elements are shown below. Each actual primitive type denotes a set --- sometimes finite and sometimes not --- of ACL2 objects and these sets are pairwise disjoint. For example, [47m*ts-zero*[0m denotes the set containing 0 while [47m*ts-negative-integer*[0m denotes the set containing all of the negative integers. *TS-ZERO* ;;; {0} *TS-ONE* ;;; {1} *TS-INTEGER>1* ;;; integers greater than 1 *TS-POSITIVE-RATIO* ;;; positive non-integer rationals *TS-NEGATIVE-INTEGER* ;;; negative integers *TS-NEGATIVE-RATIO* ;;; negative non-integer rationals *TS-COMPLEX-RATIONAL* ;;; complex rationals *TS-NIL* ;;; {nil} *TS-T* ;;; {t} *TS-NON-T-NON-NIL-SYMBOL* ;;; symbols other than nil, t *TS-PROPER-CONS* ;;; nil-terminated non-empty lists *TS-IMPROPER-CONS* ;;; conses that are not proper *TS-STRING* ;;; strings *TS-CHARACTER* ;;; characters The actual primitive types were chosen by us to make theorem proving convenient. Thus, for example, the actual primitive type [47m*ts-nil*[0m contains just [47mnil[0m so that we can encode the hypothesis ``[47mx[0m is [47mnil[0m'' by saying ``[47mx[0m has type [47m*ts-nil*[0m'' and the hypothesis ``[47mx[0m is non-[47mnil[0m'' by saying ``[47mx[0m has type complement of [47m*ts-nil*[0m.'' We similarly devote a primitive type to [47mt[0m, [47m*ts-t*[0m, and to a third type, [47m*ts-non-t-non-nil-symbol*[0m, to contain all the other ACL2 symbols. Let [47m*ts-other*[0m denote the set of all Common Lisp objects other than those in the actual primitive types. Thus, [47m*ts-other*[0m includes such things as floating point numbers and CLTL array objects. The actual primitive types together with [47m*ts-other*[0m constitute what we call [47m*universe*[0m. Note that [47m*universe*[0m is a finite set containing one more object than there are actual primitive types; that is, here we are using [47m*universe*[0m to mean the finite set of primitive types, not the infinite set of all objects in all of those primitive types. [47m*Universe*[0m is a partitioning of the set of all Common Lisp objects: every object belongs to exactly one of the sets in [47m*universe*[0m. Abstractly, a ``type-set'' is a subset of [47m*universe*[0m. To say that a term, [47mx[0m, ``has type-set [47mts[0m'' means that under all possible assignments to the variables in [47mx[0m, the value of [47mx[0m is a member of some member of [47mts[0m. Thus, [47m(cons x y)[0m has type-set [47m{*ts-proper-cons* *ts-improper-cons*}[0m. A term can have more than one type-set. For example, [47m(cons x y)[0m also has the type-set [47m{*ts-proper-cons* *ts-improper-cons* *ts-nil*}[0m. Extraneous types can be added to a type-set without invalidating the claim that a term ``has'' that type-set. Generally we are interested in the smallest type-set a term has, but because the entire theorem-proving problem for ACL2 can be encoded as a type-set question, namely, ``Does [47mp[0m have type-set complement of [47m*ts-nil*[0m?,'' finding the smallest type-set for a term is an undecidable problem. When we speak informally of ``the'' type-set we generally mean ``the type-set found by our heuristics'' or ``the type-set assumed in the current context.'' Note that if a type-set, [47mts[0m, does not contain [47m*ts-other*[0m as an element then it is just a subset of the actual primitive types. If it does contain [47m*ts-other*[0m it can be obtained by subtracting from [47m*universe*[0m the complement of [47mts[0m. Thus, every type-set can be written as a (possibly complemented) subset of the actual primitive types. By assigning a unique bit position to each actual primitive type we can encode every subset, [47ms[0m, of the actual primitive types by the nonnegative integer whose ith bit is on precisely if [47ms[0m contains the ith actual primitive type. The type-sets written as the complement of [47ms[0m are encoded as the two's-complement bitwise [47m`not'[0m of the encoding of [47ms[0m. Those type-sets are thus negative integers. The bit positions assigned to the actual primitive types are enumerated from [47m0[0m in the same order as the types are listed in [47m*actual-primitive-types*[0m. At the concrete level, a type-set is an integer between [47m*min-type-set*[0m and [47m*max-type-set*[0m, inclusive. For example, [47m*ts-nil*[0m has bit position [47m7[0m. The type-set containing just [47m*ts-nil*[0m is thus represented by [47m128[0m. If a term has type-set [47m128[0m then the term is always equal to [47mnil[0m. The type-set containing everything but [47m*ts-nil*[0m is the bitwise [47m`not'[0m of [47m128[0m, which is [47m-129[0m. If a term has type-set [47m-129[0m, it is never equal to [47mnil[0m. By ``always'' and ``never'' we mean under all, or under no, assignments to the variables, respectively. Here is a more complicated example. Let [47ms[0m be the type-set containing all of the symbols and the natural numbers. The relevant actual primitive types, their bit positions and their encodings are: actual primitive type bit value *ts-zero* 0 1 *ts-one* 1 2 *ts-integer>1* 2 4 *ts-nil* 7 128 *ts-t* 8 256 *ts-non-t-non-nil-symbol* 9 512 Thus, the type-set [47ms[0m is represented by [47m(+ 1 2 4 128 256 512)[0m = [47m903[0m. The complement of [47ms[0m, i.e., the set of all objects other than the natural numbers and the symbols, is [47m-904[0m. We can get ACL2 to provide such information as follows. ACL2 !>(decode-type-set 903) (TS-UNION *TS-SYMBOL* *TS-NON-NEGATIVE-INTEGER*) ACL2 !>(decode-type-set -904) (TS-COMPLEMENT (TS-UNION *TS-SYMBOL* *TS-NON-NEGATIVE-INTEGER*)) ACL2 !> Subtopics [Type-alist] An ACL2 representation of contextual knowledge") (type-set-inverter (rule-classes) "Exhibit a new decoding for an ACL2 type-set See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Also see [type-reasoning] for basic background on type reasoning in ACL2. Example Rule Class: (:type-set-inverter :corollary (equal (and (counting-number x) (not (equal x 0))) (and (integerp x) (< 0 x))) :type-set 2) General Forms of Rule Class: :type-set-inverter, or (:type-set-inverter :type-set n) General Form of Theorem or Corollary: (EQUAL new-expr old-expr) where [47mn[0m is a [47m[type-set][0m (see [type-set]) and [47mold-expr[0m is the term containing [47mx[0m as a free variable that ACL2 currently uses to recognize [47m[type-set][0m [47mn[0m. For a given [47mn[0m, the exact form of [47mold-expr[0m is generated by (convert-type-set-to-term 'x n (ens state) (w state) nil)]. If the [47m:[0m[47m[type-set][0m field of the rule-class is omitted, we attempt to compute it from the right-hand side, [47mold-expr[0m, of the corollary. That computation is done by [47mtype-set-implied-by-term[0m (see [type-set]). However, it is possible that the type-set we compute from [47mlhs[0m does not have the required property that when inverted with [47mconvert-type-set-to-term[0m the result is [47mlhs[0m. If you omit [47m:[0m[47m[type-set][0m and an error is caused because [47mlhs[0m has the incorrect form, you should manually specify both [47m:[0m[47m[type-set][0m and the [47mlhs[0m generated by [47mconvert-type-set-to-term[0m. The rule generated will henceforth make [47mnew-expr[0m be the term used by ACL2 to recognize type-set [47mn[0m. If this rule is created by a [47m[defthm][0m event named [47mname[0m then the rune of the rule is [47m(:type-set-inverter name)[0m and by disabling that rune you can prevent its being used to decode type-sets. Type-sets are inverted when forced assumptions are turned into formulas to be proved. In their internal form, assumptions are essentially pairs consisting of a context and a goal term, which was forced. Abstractly a context is just a list of hypotheses which may be assumed while proving the goal term. But actually contexts are alists which pair terms with type-sets, encoding the current hypotheses. For example, if the original conjecture contained the hypothesis [47m(integerp x)[0m then the context used while working on that conjecture will include the assignment to [47mx[0m of the type-set [47m*ts-integer*[0m.") (type-spec (declare the) "Type specifiers can be used in Common Lisp type declarations and [the] forms, and may result in improved efficiency of execution. ACL2 permits the use of type declarations in certain contexts; see [declare] for background. Here is an example of a type declaration; here the symbol, [47minteger[0m, is what we refer to as a ``type-spec'': (let ((x (+ a b))) (declare (type integer x)) ;; <-- type declaration (+ 1 x)) A Common Lisp compiler might be able to use the above declaration to improve the execution efficiency of the resulting code. In particular, the Common Lisp [+] operation is rather elaborate: it must be capable of adding together integers, rationals, floats, etc. When we tell the compiler that this [47mx[0m is surely an integer, it may be able to use a more efficient version of [47m(+ 1 x)[0m that only deals with the integer case. Type declarations can be added to functions, [47m[let][0m bindings, and other places as described in [declare], and interact with the ACL2's [guard] mechanism. For instance, during guard verification, the above type declaration will result in a guard obligation: we will need to prove that [47m(+ a b)[0m is always an integer. Type declarations about the formals of a function generally become part of the guard of the function, but see also [split-types] for a way to gain more control over this. Whether or not a particular type declaration will actually improve the efficiency of your functions depends on the Lisp compiler. For instance, many Lisp compilers will not benefit much from a plain [47minteger[0m declaration. If you are trying to optimize code by adding type declarations, it may be useful to use [disassemble$] to inspect the impact that your declarations have on the resulting code. While type specs may be used in [defstobj] events, the [47mHASH-TABLE[0m and [47mSTOBJ-TABLE[0m type specs may only be used in those events. We say nothing further about them in the present topic. Type Specs The syntax that Common Lisp compilers use for these type declarations---e.g., the symbol [47minteger[0m above---is different than the usual syntax of ACL2. We use the name [31;1mtype-spec[0m to refer to the supported types that can be mentioned in declarations. For instance: Declaration | Type-Spec | [47m(type string x y z)[0m | [47mstring[0m | [47m(type (integer 0 7) x)[0m | [47m(integer 0 7)[0m | [47m(type rational x)[0m | [47mrational[0m | [47m(type (rational 1 *) x)[0m | [47m(rational 1 *)[0m | The supported type-specs and their meanings (when applied to the variable [47mx[0m as in [47m(declare (type type-spec x))[0m are given below. type-spec meaning ---------------------------------------------------------------------- (AND type1 ... typek) (AND (p1 X) ... (pk X)) where (pj x) is the meaning for type-spec typej ATOM (ATOM X) BIT (OR (EQUAL X 1) (EQUAL X 0)) CHARACTER (CHARACTERP X) COMPLEX (AND (COMPLEX-RATIONALP X) (RATIONALP (REALPART X)) (RATIONALP (IMAGPART X))) (COMPLEX RATIONAL) same as COMPLEX, above (COMPLEX type) (AND (COMPLEX-RATIONALP X) (p (REALPART X)) (p (IMAGPART X))) where (p x) is the meaning for type-spec type CONS (CONSP X) DOUBLE-FLOAT (DFP X) ; See :DOC df. INTEGER (INTEGERP X) (INTEGER i j) (AND (INTEGERP X) ; See notes below. (<= i X) (<= X j)) LIST (LISTP X) (MEMBER x1 ... xn) (MEMBER X '(x1 ... xn)) (MOD i) same as (INTEGER 0 i-1) NIL NIL (NOT type) (NOT (p X)) where (p x) is the meaning for type-spec type NULL (EQ X NIL) NUMBER (ACL2-NUMBERP x) (OR type1 ... typek) (OR (p1 X) ... (pk X)) where (pj x) is the meaning for type-spec typej RATIO (AND (RATIONALP X) (NOT (INTEGERP X))) RATIONAL (RATIONALP X) (RATIONAL i j) (AND (RATIONALP X) ; See notes below. (<= i X) (<= X j)) REAL (RATIONALP X) ; (REALP X) in ACL2(r) (REAL i j) (AND (RATIONALP X) ; See notes below. (<= i X) (<= X j)) (SATISFIES pred) (pred X) ; Lisp requires a unary function, not a macro SIGNED-BYTE (INTEGERP X) (SIGNED-BYTE i) same as (INTEGER k m) where k=-2^(i-1), m=2^(i-1)-1 STANDARD-CHAR (STANDARD-CHAR-P X) STRING (STRINGP X) (STRING max) (AND (STRINGP X) (EQUAL (LENGTH X) max)) SYMBOL (SYMBOLP X) T T UNSIGNED-BYTE same as (INTEGER 0 *) (UNSIGNED-BYTE i) same as (INTEGER 0 (2^i)-1) ---------------------------------------------------------------------- Notes In general, [47m(integer i j)[0m means (AND (INTEGERP X) (<= i X) (<= X j)). But if [47mi[0m is the symbol [47m*[0m, the first inequality is omitted. If [47mj[0m is the symbol [47m*[0m, the second inequality is omitted. If instead of being an integer, the second element of the type specification is a list containing an integer, [47m(i)[0m, then the first inequality is made strict. An analogous remark holds for the [47m(j)[0m case. The [47mrational[0m and [47mreal[0m type specifiers are similarly generalized. Common Lisp supports a richer set of type specifiers than ACL2 supports.") (typespec-check (pointers) "See [meta-extract].") (u (history undo) "Undo last [command], without a query See [undo] for an introduction to undoing commands. Example: :u The keyword [command] [47m:u[0m is the same as [47m:[0m[47m[ubt!][0m [47m:x[0m. [47m:[0m[47m[Oops][0m will undo the last [47m:u[0m. See [ubt!].") (ubt (history undo) "Undo the [command]s back through a [command] descriptor See [undo] for an introduction to undoing commands. Examples: :ubt :max ; undo back through the most recent command ; (which just means undo the most recent command) :ubt :x ; same as :ubt :max :u ; same as :ubt :max with no questions asked :ubt fn ; undo back through the introduction of fn ; (including all the other events in fn's block) :ubt 5 ; undo back through the fifth command executed :ubt (:max -4) ; undo back through the most recent five commands :ubt (:x -4) ; undo back through the most recent five commands See [command-descriptor]. [47mUbt[0m takes one argument, a [command] descriptor, and undoes the [command]s from [47m:[0m[47m[max][0m (aka [47m:x[0m) through the one described. See [command-descriptor]. [47m[Pbt][0m will print the [command]s that [47mubt[0m will undo. [47m:[0m[47m[Oops][0m will undo the undo. See [oops]. [47mUbt[0m can cause errors but not queries. To get queries as well, see [ubt?]. To get neither errors nor queries, see [ubt!].. It is important to remember that a [command] may create several [events]. That is, the [command] that introduces [47mfn1[0m may also introduce [47mfn2[0m. Undoing the [command] that created either of these will undo them both. The [events] created by a [command] constitute the [command]'s ``block'' and we can only undo entire blocks. Use [47m[pcb][0m to print the [command] block of a [command] if you wish to see what will be lost by undoing the [command]. [47mUbt[0m will not undo into ``prehistory''. [47m:Ubt 1[0m will undo all of your [command]s. But [47m:ubt -5[0m will cause an error, warning you that [47m:ubt[0m cannot undo system initialization. See [u] for how to undo just the latest command. See [ubu], [ubu!], and [ubu?] for how to undo back up to, but not including, the current command.") (ubt! (history undo) "Undo [command]s, without a query or an error See [undo] for an introduction to undoing commands. Example: :ubt! :x-4 The keyword [command] [47m:ubt![0m is the same as [47m:[0m[47m[ubt][0m, but with a guarantee that it is ``error-free.'' More precisely, the value returned by [47m:ubt![0m will always be of the form [47m(mv nil val state)[0m. Note that [47m:ubt![0m will not print error messages. [47m:[0m[47m[Oops][0m will undo the last [47m:ubt![0m. See [ubt], [ubt?], [ubu!], [ubu], [ubu?], and [u].") (ubt-prehistory (history undo) "Undo the [command]s back through the last [47m[reset-prehistory][0m event See [undo] for an introduction to undoing commands. This command is only used to eliminate a [47m[reset-prehistory][0m event. If your most recent [47mreset-prehistory[0m event does not have a flag argument of [47mt[0m, then [47m:ubt-prehistory[0m undoes all command back through, and including, that [47mreset-prehistory[0m event.") (ubt? (history undo) "Undo [command]s, with queries as appropriate See [undo] for an introduction to undoing commands. Example: :ubt? :x-4 The keyword [command] [47m:ubt?[0m is the same as [47m:[0m[47m[ubt][0m, but with appropriate queries made. [47m:[0m[47m[Oops][0m will undo the last [47m:ubt?[0m. See [ubt!], [ubt], [ubu!], [ubu], [ubu?], and [u].") (ubu (history undo) "Undo the [command]s back up to (not including) a [command] descriptor See [undo] for an introduction to undoing commands. Examples: :ubu :x-3 ; undo the last three commands (same as :ubt :x-2) :ubu (:x -3) ; same as above :ubu fn ; undo back up to, but not including the introduction of fn ; (so fn will continue to be defined) :ubu 5 ; undo back up to, but not including, the fifth command ; executed (leaving the first five commands in place) See [command-descriptor]. [47mUbu[0m takes one argument, a [command] descriptor, and undoes the [command]s from [47m:[0m[47m[max][0m (aka [47m:x[0m) up to, but not including, the indicated command. See [command-descriptor]. [47mUbu[0m can cause errors. To avoid these, see [ubu!]. For appropriate queries to be made, see [ubu?]. Also see [ubt], which is similar but also undoes the indicated command. As for [47m:[0m[47m[ubt][0m, [47m:[0m[47m[oops][0m will undo the undo (see [oops]) and [47m[ubu][0m will not undo into ``prehistory''. See [u] for how to undo just the latest command, and see [ubt], [ubt!], and [ubt?] for how to undo back through (that is, including) the current command.") (ubu! (history undo) "Undo [command]s, without a query or an error See [undo] for an introduction to undoing commands. Example: :ubu! :x-4 The keyword [command] [47m:ubu![0m is the same as [47m:[0m[47m[ubu][0m, but with a guarantee that it is ``error-free.'' More precisely, the [error-triple] returned by [47m:ubu![0m will always be of the form [47m(mv nil val state)[0m. Note that [47m:ubu![0m will not print error messages. [47m:[0m[47m[Oops][0m will undo the last [47m:ubu![0m. Also see [ubu], [ubu?], [ubt], [ubt!], [ubt?], and [u].") (ubu? (history undo) "Undo [command]s, with queries as appropriate See [undo] for an introduction to undoing commands. Example: :ubu? :x-4 The keyword [command] [47m:ubu?[0m is the same as [47m:[0m[47m[ubu][0m, but with appropriate queries made. [47m:[0m[47m[Oops][0m will undo the last [47m:ubu?[0m. Also see [ubu!], [ubu], [ubt!], [ubt], [ubt?], and [u].") (unary-- (numbers acl2-built-ins) "Arithmetic negation function Completion Axiom ([47mcompletion-of-unary-minus[0m): (equal (unary-- x) (if (acl2-numberp x) (unary-- x) 0)) [Guard] for [47m(unary-- x)[0m: (acl2-numberp x) Notice that like all arithmetic functions, [47munary--[0m treats non-numeric inputs as [47m0[0m. Calls of the macro [47m[-][0m on one argument expand to calls of [47munary--[0m; see [-].") (unary-/ (numbers acl2-built-ins) "Reciprocal function Completion Axiom ([47mcompletion-of-unary-/[0m): (equal (unary-/ x) (if (and (acl2-numberp x) (not (equal x 0))) (unary-/ x) 0)) [Guard] for [47m(unary-/ x)[0m: (and (acl2-numberp x) (not (equal x 0))) Notice that like all arithmetic functions, [47munary-/[0m treats non-numeric inputs as [47m0[0m. Calls of the macro [47m[/][0m on one argument expand to calls of [47munary-/[0m; see [/].") (unary-df- (pointers) "See [df].") (unary-df-log (pointers) "See [df].") (unary-df/ (pointers) "See [df].") (uncertified-books (books) "Invalid [certificate]s and uncertified [books] For relevant background see [books], see [books-tour], see [certificate], and see [portcullis]. You may have been led to this topic by a warning or error message such as the following. There is no certificate on file for /u/smith/foo.lisp. See :DOC uncertified-books. The remedy is to [3mcertify[0m the indicated book; see [certify-book]. Such certification is typically a [3mvery[0m good idea, as discussed further below. After certification succeeds, the book will have a valid [certificate] and the message will no longer be printed. The rest of this topic explains issues pertaining to books that are [3muncertified[0m, that is, have not been certified. [47m[Include-book][0m has a special provision for dealing with an uncertified book, i.e., a file whose [certificate] is missing or invalid (e.g., one for a different ACL2 version or whose [book-hash] value describes a file other than the one actually read). In this case, a warning is printed (as above) and the book is usually processed much as though it were certified. If a book [47mB.lisp[0m was previously certified, it will probably have a corresponding file [47mB.port[0m representing the [portcullis] [command]s for that previous certification. (See keyword argument [47m:write-port[0m of [47m[certify-book][0m.) Then if [47mB.lisp[0m is currently uncertified and [47mB.port[0m exists, evaluation of [47m(include-book "B")[0m will cause the forms in [47mB.port[0m to be evaluated before the forms in [47mB.lisp[0m. To avoid such evaluation for [47m.port[0m files, see [compilation]. The ability to include uncertified [books] is handy but it can have disastrous consequences, ranging from hard lisp errors, to damaged memory, to quiet logical inconsistency. It is possible for the inclusion of an uncertified book to render the logic inconsistent. For example, one of its non-[47m[local][0m [events] might be [47m(defthm t-is-nil (equal t nil))[0m. It is also possible for the inclusion of an uncertified book to cause hard errors or [breaks] into raw Common Lisp. For example, if the file has been edited since it was certified, it may contain too many open parentheses, causing Lisp to read past ``end of file.'' Similarly, it might contain non-ACL2 objects such as [47m3.1415[0m or ill-formed event forms that cause ACL2 code to break. Even if a book is perfectly well formed and could be certified (in a suitable extension of ACL2's initial [world]), its uncertified inclusion might cause Lisp errors or inconsistencies! For example, it might mention packages that do not exist in the host [world], especially if the [47m.port[0m file (discussed above) does not exist from an earlier certification attempt. The [portcullis] of a certified book ensures that the correct [47m[defpkg][0ms have been admitted, but if a book is read without actually raising its [portcullis], symbols in the file, e.g., [47macl2-arithmetic::fn[0m, could cause ``unknown package'' errors in Common Lisp. Perhaps the most subtle disaster occurs if the host [world] does have a [47m[defpkg][0m for each package used in the book but the host [47m[defpkg][0m imports different symbols than those required by the [portcullis]. In this case, it is possible that formulas which were theorems in the certified book are non-theorems in the host [world], but those formulas can be read without error and will then be quietly assumed. In short, if you include an uncertified book, [31;1mall bets are off[0m regarding the validity of the future behavior of ACL2. That said, it should be noted that ACL2 is pretty tough and if errors don't occur, the chances are that deductions after the inclusion of an uncertified book are probably justified in the (possibly inconsistent) logical extension obtained by assuming the admissibility and validity of the definitions and conjectures in the book.") (undo (history) "Undoing and perhaps redefining This topic provides a high-level view of how one can undo a definition, perhaps replacing it with a new definition. We begin with some background. ACL2 maintains a stack of [command]s. For example, suppose we submit the following [events] in a new session. (defun f (x) x) (defun g (x) (* x x)) (defthm f^2-is-g (equal (expt (f x) 2) (g x)) :hints (("Goal" :expand ((expt x 2))))) Then we can see the stack of commands by using [47m:[0m[47m[pcb][0m (``Print Command Block'') back to command 0, that is back to the start. ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) L 1 (DEFUN F (X) ...) L 2 (DEFUN G (X) ...) 3:x(DEFTHM F^2-IS-G ...) ACL2 !> Now suppose that we want to redefine [47mg[0m. The cleanest, safest way is to unwind the stack with [47m:[0m[47m[ubt][0m (``Undo Back Through'') all the way back through (and including) [47mg[0m. ACL2 !>:ubt g L 1:x(DEFUN F (X) ...) ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) L 1:x(DEFUN F (X) ...) ACL2 !> Now we can define [47mg[0m again and proceed from there. ACL2 !>(defun g (x) (expt x 2)) [[.. output omitted here ..]] G ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) L 1 (DEFUN F (X) ...) L 2:x(DEFUN G (X) ...) ACL2 !>(defthm f^2-is-g (equal (expt (f x) 2) (g x))) [[.. output omitted here ..]] F^2-IS-G ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) L 1 (DEFUN F (X) ...) L 2 (DEFUN G (X) ...) 3:x(DEFTHM F^2-IS-G ...) ACL2 !> See [ubt] for more information, including variants such as [47m:u[0m, which undoes a single command (the most recent one). Also see [oops] for how to undo an undo. It can occasionally be inconvenient to undo a large number of commands when one's goal is only to redefine a single function. In such cases one might wish to enable redefinition, even though it can be unsafe. Here is an example (admittedly contrived) for how to continue the session above. Note that there are variants of [47m:redef[0m --- see [redef] --- for example to avoid the query shown below and answered with `[47my[0m'. ACL2 !>:redef (:QUERY . :OVERWRITE) ACL2 !>(defun f (x) (+ 10 x)) ACL2 Query (:REDEF): The name F is in use as a function. Its current defun-mode is :logic. Do you want to redefine it? (N, Y, E, O or ?): y Since F is non-recursive, its admission is trivial. We observe that the type of F is described by the theorem (ACL2-NUMBERP (F X)). We used primitive type reasoning. Summary Form: ( DEFUN F ...) Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)) Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) F ACL2 !>:pbt 0 0 (EXIT-BOOT-STRAP-MODE) L 1 (DEFUN F (X) ...) L 2 (DEFUN G (X) ...) 3 (DEFTHM F^2-IS-G ...) L 4:x(DEFUN F (X) ...) ACL2 !> Notice that the ``theorem'' [47mf^2-is-g[0m is still in our session, even though it is no longer valid now that [47mf[0m has been redefined. This shows one reason we say that redefinition can be unsafe; it can be unsound! Other possible dangers include execution errors and ignoring, in existing definitions, redefinitions of constants and macros. Thus, undoing (and then redoing) is generally preferable to redefinition. Indeed, redefinition is disallowed in [books]. You can inspect both commands that introduce a definition for [47mf[0m with [47m:pcb[0m (``Print Command Block'' in full; see [pcb]). ACL2 !>:pcb! 1 L 1 (DEFUN F (X) X) ACL2 !>:pcb! 3 L 3:x(DEFUN F (X) (CAR (CONS X X))) ACL2 !> Subtopics [U] Undo last [command], without a query [Ubt] Undo the [command]s back through a [command] descriptor [Ubt!] Undo [command]s, without a query or an error [Ubt-prehistory] Undo the [command]s back through the last [47m[reset-prehistory][0m event [Ubt?] Undo [command]s, with queries as appropriate [Ubu] Undo the [command]s back up to (not including) a [command] descriptor [Ubu!] Undo [command]s, without a query or an error [Ubu?] Undo [command]s, with queries as appropriate") (undoing (pointers) "See [undo].") (union$ (lists acl2-built-ins) "A list that contains exactly the elements of the given lists General Forms: (union$ l1 l2 ... lk) (union$ l1 l2 ... lk :test 'eql) ; same as above (union$ l1 l2 ... lk :test 'eq) ; same, but eq is equality test (union$ l1 l2 ... lk :test 'equal) ; same, but equal is equality test [47m(Union$ x y)[0m equals a list that contains both the members of [47mx[0m and the members of [47my[0m. More precisely, the resulting list is the same as one would get by first deleting the members of [47my[0m from [47mx[0m, and then concatenating the result to the front of [47my[0m. The optional keyword, [47m:TEST[0m, has no effect logically, but provides the test (default [47m[eql][0m) used for comparing members of the two lists. [47mUnion$[0m need not take exactly two arguments: [47m(union$)[0m is [47mnil[0m, [47m(union$ x)[0m is [47mx[0m, [47m(union$ x y z ... :test test)[0m is [47m(union$ x (union$ y z ... :test test) :test test)[0m, and if [47m:TEST[0m is not supplied, then [47m(union$ x y z ...)[0m is [47m(union$ x (union$ y z ...))[0m. For the discussion below we restrict ourselves, then, to the cases [47m(union$ x y)[0m and [47m(union$ x y :test test)[0m. The [guard] for a call of [47munion$[0m (in the two cases just above) depends on the test. In all cases, both arguments must satisfy [47m[true-listp][0m. If the test is [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m. If the test is [47m[eq][0m, then one of the arguments must satisfy [47m[symbol-listp][0m. See [equality-variants] for a discussion of the relation between [47munion$[0m and its variants: [47m(union-eq x lst)[0m is equivalent to [47m(union$ x lst :test 'eq)[0m; [47m(union-equal x lst)[0m is equivalent to [47m(union$ x lst :test 'equal)[0m. In particular, reasoning about any of these primitives reduces to reasoning about the function [47munion-equal[0m. [31;1mFunction: [0m<union-equal> (defun union-equal (l1 l2) (declare (xargs :guard (and (true-listp l1) (true-listp l2)))) (cond ((endp l1) l2) ((member-equal (car l1) l2) (union-equal (cdr l1) l2)) (t (cons (car l1) (union-equal (cdr l1) l2))))) Note that [47munion-eq[0m can take any number of arguments, in analogy to [47munion$[0m; indeed, [47m(union-eq ...)[0m expands to [47m(union$ ... :test 'eq)[0m. However, [47munion-equal[0m is a function, not a macro, and takes exactly two arguments. [47mUnion$[0m is similar to the Common Lisp primitive [47munion[0m. However, Common Lisp does not specify the order of elements in the result of a call of [47munion[0m.") (union-eq (pointers) "See [union$].") (union-equal (pointers) "See [union$].") (union-theories (theories theory-functions) "Union two [theories] Example: (union-theories (current-theory 'lemma3) (theory 'arith-patch)) General Form: (union-theories th1 th2) where [47mth1[0m and [47mth2[0m are theories (see [theories]). To each of the arguments there corresponds a runic theory. This function returns the union of those two runic [theories], represented as a list and ordered chronologically. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world].") (universal-theory (theories theory-functions) "All rules as of logical name Examples: (universal-theory :here) (universal-theory 'lemma3) See [logical-name]. General Form: (universal-theory logical-name) Returns the theory consisting of all the [rune]s that existed immediately after [47m[logical-name][0m was introduced. See [theories] and see [logical-name]. The theory includes [47m[logical-name][0m itself (if there is a rule by that name). (Note that since some [events] do not introduce rules (e.g., [47m[defmacro][0m, [47m[defconst][0m or [47m[defthm][0m with [47m:[0m[47m[rule-classes][0m [47mnil[0m), the universal-theory does not necessarily include a [rune] for every event name.) The universal-theory is very long and you will probably regret printing it. You may experience a fencepost problem in deciding which [logical-name] to use. [47m[Deflabel][0m can always be used to mark unambiguously for future reference a particular point in the development of your theory. This is convenient because [47m[deflabel][0m does not introduce any rules and hence it doesn't matter if you count it as being in the interval or not. The order of [events] in the vicinity of an [47m[encapsulate][0m is confusing. See [encapsulate]. This ``function'' is actually a macro that expands to a term mentioning the single free variable [47m[world][0m. When theory expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint, [47m[world][0m is bound to the current ACL2 [world]. Also see [current-theory]. [47mCurrent-theory[0m is much more commonly used than [47muniversal-theory[0m. The former includes only the [enable]d [rune]s as of the given [47m[logical-name][0m, which is probably what you want, while the latter includes [disable]d ones as well.") (unknown-constraints (pointers) "See [partial-encapsulate].") (unmemoize (memoize programming hons-and-memoization events) "Turn off memoization for the specified function Example: (unmemoize 'foo) ; turn off memoization of foo General Form: (unmemoize fn) where [47mfn[0m evaluates to a function symbol that is currently memoized; see [memoize]. An exception is that as with [47m[memoize][0m, [47mfn[0m may evaluate to the name of a macro that is associated with such a function symbol; see [macro-aliases-table]. Calls of this macro generate events of the form [47m(table memoize-table fn nil)[0m. When successful, the returned value is of the form [47m(mv nil function-symbol state)[0m. To remove the effects of all [47m[memoize][0m [events], evaluate: [47m(clear-memo-table)[0m. To save and restore memoization, see [save-and-clear-memoization-settings] and see [restore-memoization-settings]. These are both legal [event] forms. Note: These events do not affect memoization from [47m[memoize][0m events that either are derived from calls of [47m[memoize-partial][0m or have a non-[47mnil[0m value of [47m[memoize][0m argument [47m:invoke[0m") (unmonitor (break-rewrite) "To stop monitoring a rule name Examples: (unmonitor '(:rewrite assoc-of-app)) :unmonitor (:rewrite assoc-of-app) :unmonitor :all General Forms: (unmonitor rune) (unmonitor :all) Here, [47mrune[0m is a [rune] that is currently among those with break points installed. This function removes the break. See [monitor]. Subtle point: Because you may want to unmonitor a ``[rune]'' that is no longer a [rune] in the current ACL2 [world], we don't actually check this about [47mrune[0m. We simply check that [47mrune[0m is currently monitored and remove it. If [47mrune[0m corresponds to no entry on the list of monitored runes we cause an error since it may indicate a misspelling.") (unquote 'acl2-built-ins "Obtain the object being quoted [47mUnquote[0m is just an abbreviation for [47m[cadr][0m. Its intended use is to obtain an object being quoted. For example, if [47mx[0m is [47m(quote (3 4))[0m then [47m(unquote x)[0m is [47m(3 4)[0m: ACL2 !>(let ((x '(quote (3 4)))) (unquote x)) (3 4) ACL2 !>") (unsave (proof-builder) "Remove a [proof-builder] state Example: (unsave assoc-of-append) General Form: (unsave name) Eliminates the association of an interactive [proof-builder] state with [47mname[0m. See [unsave] or see [ACL2-pc::unsave]. Also see [ACL2-pc::save] and see [retrieve].") (unsigned-byte-p (numbers acl2-built-ins) "Recognizer for natural numbers that fit in a specified bit width [47m(Unsigned-byte-p bits x)[0m is [47mT[0m when [47mbits[0m is a positive integer and [47mx[0m is a nonnegative integer that fits into a bit-width of [47mbits[0m, i.e., [47m0 <= x < 2^bits[0m. Note that a [type-spec] of [47m(unsigned-byte i)[0m for a variable [47mx[0m in a function's [47m[declare][0m form translates to a [guard] condition of [47m(unsigned-byte-p i x)[0m. The [guard] for [47munsigned-byte-p[0m is [47mT[0m. [31;1mFunction: [0m<unsigned-byte-p> (defun unsigned-byte-p (bits x) (declare (xargs :guard t)) (and (integerp bits) (<= 0 bits) (integer-range-p 0 (expt 2 bits) x)))") (unsupported-parallelism-features (parallelism) "ACL2 features not supported in ACL2(p) This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. See [parallelism-tutorial] for an introduction to parallel programming in ACL2. For proof features of ACL2 that are not yet supported when parallel execution is enabled for the primary ACL2 proof process, generally known as ``the waterfall'', see [unsupported-waterfall-parallelism-features]. Please note that this topic discusses ACL2 features that are disabled when using ACL2(p) (see [compiling-ACL2p]). These features are disabled regardless of whether waterfall parallelism is enabled. Calls of [47m[observation-cw][0m simply convert to calls of [47m[cw][0m, so suppressing [47m[observation][0ms (see [set-inhibit-output-lst]) will not suppress these messages. Memoization is not supported when executing in parallel. See [Unsupported-waterfall-parallelism-features] for memoization details related to waterfall parallelism. Since, as of April 2012, garbage collection is inherently sequential, ACL2(p) minimizes the use of garbage collection by setting a high garbage collection threshold. As a result, ACL2(p) is not expected to perform well on machines with less memory than this threshold (1 gigabyte, as of April 2012). In CCL, the underlying parallel execution engine is tuned for the number of CPU cores (or hardware threads) actually available in the machine. SBCL and LispWorks are tuned for a machine with 16 CPU cores. CCL is considered to be the ``flagship Lisp'' for parallel execution in ACL2. The SBCL and LispWorks implementations are thought to be generally stable. However, due to their relatively less common use, the SBCL and LispWorks implementations are likely less robust than the CCL implementation. The [47m[time-tracker][0m utility is a no-op for ACL2(p). When executing calls of [47m[hons-get][0m in parallel, you may see messages about [47m"Fast alist discipline"[0m violations. This can happen because each thread uses its own underlying hash table for fast access by [47mhons-get[0m, but typical top-level calls of [47m[hons-acons][0m and [47m[make-fast-alist][0m only affect that main thread's hash table. You can use [47m(set-slow-alist-action nil)[0m to eliminate this warning entirely; see [slow-alist-warning].") (unsupported-waterfall-parallelism-features (parallel-proof) "Proof features not supported with waterfall-parallelism enabled For a general introduction to ACL2(p), an experimental extension of ACL2 that supports parallel execution and proof, see [parallelism]. Please note that although this extension is usable and, we hope, robust in its behavior, there are still known issues to address beyond those listed explicitly below. While we expect ACL2(p) to perform correctly, it may never have the same level of attention to correctness as is given to ACL2; see [parallelism], specifically the ``IMPORTANT NOTE'' there. Below we list proof features of ACL2 that are not yet supported when parallel execution is enabled for the primary ACL2 proof process, generally known as ``the waterfall'', typically by calling [47m[set-waterfall-parallelism][0m. Please note that this topic is limited to the case that such waterfall parallelism is enabled. We believe that all ACL2 proof procedures are supported when waterfall parallelism is disabled, even in executables that support parallelism (see [compiling-ACL2p]). Without a trust tag (see [defttag]): We support [clause-processor]s, [computed-hints], and [custom-keyword-hints] that do not modify [state], but we do not permit [override-hints], regardless of whether they modify state. With a trust tag, the user can use [clause-processor]s that modify state and can also use [override-hints] (see [set-waterfall-parallelism-hacks-enabled] for a convenient mechanism for adding a trust tag). See [error-triples-and-parallelism] for a discussion of how to avoid modifying state in such situations. Regardless of whether a trust tag is active: We do not support checkers of [custom-keyword-hints] to be anything but the default checker. GNU Make versions 3.81 and 3.82 formerly caused a lot of problems (version 3.80 somewhat less so), at least on Linux, when certifying books with ACL2 built on a host Lisp of CCL using `make'. CCL was updated around March 23, 2011 to fix this problem, so if you get segfaults (for example) with CCL, try updating your CCL installation. Book certification should generally work but may present some issues, including the following. * The standard `make'-based process for book certification will not use [waterfall-parallelism], which is disabled by default (even when [compiling-ACL2p] by using the [47mACL2_PAR[0m flag). See [books-certification] and see [books-certification-classic], which explain that [ACL2-customization] files are ignored during that process unless specified explicitly on the command line or in the environment. * A book certified with ACL2(p) might subsequently cause an error when included with ACL2. As of this writing, however, we have only seen this for a book in which [47m[deftheory-static][0m is used. * In general, ACL2(p) is primarily intended to support more rapid interactive development. While we are unaware of an unsoundness likely to affect an ACL2(p) user, we suggest using ACL2 for final book certification, rather than ACL2(p), to lower the risk of unsound book certification. Proof output can contain repeated printing of the same subgoal name. [Gag-mode] isn't officially supported, although it has proved helpful to use ACL2(p) in conjunction with [47m(set-gag-mode t)[0m (because this setting suppresses the output that occurs outside the waterfall). This being said, ACL2(p) also prints key checkpoints (for example see [introduction-to-key-checkpoints]), but with a notion of ``key checkpoint'' that does not take into account whether the goal is later proved by induction. See [ACL2p-key-checkpoints] for further explanation of these key checkpoints. Note that [47m[pso][0m is also not supported. The [47m:[0m[47m[brr][0m and [47m[with-brr-data][0m utilities are not supported. The [47m[accumulated-persistence][0m utility is not supported. Tracking for [forward-chaining-reports] is not supported (see [set-fc-criteria]). Time limits (see [with-prover-time-limit]) aren't supported. The timing information printed at the end of a proof attempt, which is intended to represent cpu time (not wall-clock time), may be somewhat inaccurate when [waterfall-parallelism] is non-[47mnil[0m. Consider using [47m[time$][0m to obtain timing information. Use [47m[wormhole][0ms at your own risk. Although they use locks, there has been some concern that they may cause race conditions. They are used in ACL2(p) source code (macro [47m[observation-cw][0m), however, thus we have hope that they perform acceptably. Output specific to [47m:OR[0m [hints] is disabled. Proof trees are likely not to work as originally designed. The use of [47m[set-inhibit-output-lst][0m may not fully inhibit proof output. Reporting of [splitter] rules is currently unsupported when waterfall-parallelism is on. Interrupting a proof attempt is not yet properly supported. At a minimum, interrupts are trickier with waterfall parallelism enabled. For one, the user typically needs to issue the interrupt twice before the proof attempt is actually interrupted. Additionally, on rare occasions the theorem is registered as proved, even though the prover did not finish the proof. If this occurs, issue a [47m:u[0m (see [ubt]) and you will likely be at a stable state. Also with regards to interrupting a proof attempt, sometimes the user may need to issue a [47m:q[0m and [47mlp[0m to reset properly the parallelism implementation to a stable state. The primary symptom that the user is experiencing this issue is that threads will continue to compute in the background, even though there should be no proof attempt in progress. The user can observe this symptom by examining the CPU utilization of their ACL2 process, for example on Linux/Unix with the shell process [47mtop[0m. Lisp usage greater than a few percent is indicative of this problem. Because of how ACL2 [arrays] are designed, the user may find that, in practice, ACL2 arrays work (but perhaps with some [slow-array-warning] messages). However, we are aware of race conditions that can cause problems. Instead of dynamically monitoring rewrites, [dmr] instead dynamically outputs information helpful for debugging the performance of proof parallelism. The instructions concerning how to see this debugging information are the same as the instructions for enabling [dmr] mode. If you are working with LispWorks 6.0 or 6.0.1, then you may see messages about misaligned conses. The state of the system may be corrupted after such a message has been printed. This LispWorks bug is fixed in LispWorks 6.1. The waterfall parallelism mode [47m:resource-and-timing-based[0m is not fully supported when the host Lisp is other than CCL. It may work, but we have not attempted to address a potential race condition. Proof output for splitter rules (see [splitter]) is currently unsupported when waterfall-parallelism is enabled. Profiling may cause proofs to hang when waterfall-parallelism is enabled (GitHub Issue #638). During proofs with [waterfall-parallelism] enabled, you may see messages about [47m"Fast alist discipline"[0m violations, even when using [47m[hons-get][0m appropriately. This can happen because each thread uses its own underlying hash table for fast access by [47mhons-get[0m, but typical top-level calls of [47m[hons-acons][0m and [47m[make-fast-alist][0m only affect that main thread's hash table. You can use [47m(set-slow-alist-action nil)[0m to eliminate this warning entirely; see [slow-alist-warning].") (until$ (pointers) "See [loop$].") (until$+ (pointers) "See [loop$].") (untouchable (defttag) "Function symbols and state globals that cannot be referenced Untouchables are functions that cannot be called, as well as [state] global variables (see [programming-with-state]) that cannot be modified or unbound. To add or remove untouchables, see [push-untouchable] and see [remove-untouchable]. Macros can be made effectively untouchable as well; see [defmacro-untouchable].") (untouchable-marker (pointers) "See [defmacro-untouchable].") (untrace$ (trace) "Untrace functions Examples: (untrace$) ; untrace all functions previously ; traced (e.g. with trace$ or trace!) (untrace$ foo bar) ; as above, except only untrace foo and bar General Forms: (untrace$) ; untrace all (as noted above) (untrace$ fn1 fn2 ... fnk) ; untrace the indicated functions where the [47mfni[0m were previously traced (e.g. with [47m[trace$][0m or [47m[trace!][0m). [47mUntrace$[0m undoes the effect of [47m[trace$][0m. See [trace$]. The value returned by [47muntrace$[0m gives the list of functions for which tracing is being removed.") (untrans-table (macros) "Associates a function symbol with a macro for printing user-level terms Examples: ACL2 !>(untrans-table (w state)) ((BINARY-+ + . T) (BINARY-* * . T) (BINARY-APPEND APPEND . T) (BINARY-LOGAND LOGAND . T) (BINARY-LOGIOR LOGIOR . T) (BINARY-LOGXOR LOGXOR . T) (BINARY-LOGEQV LOGEQV . T) (BINARY-POR POR . T) (BINARY-PAND PAND . T)) See [table] for a general discussion of tables. See [add-macro-fn] for a more general discussion of this [table] and for a way to associate a macro name with a function name in theory events.") (untranslate (system-utilities) "Show a user-level representation of a term ACL2 uses a strict notion of ``[term]'' for its internal computations; see [pseudo-termp]. Such expressions are sometimes called ``translated terms''. However, ACL2 provides user-level output --- for example, in output from the theorem prover --- in the form of so-called ``untranslated terms''. For example, the untranslated term [47m(<= 3 x)[0m corresponds to the translated term [47m(not (< x '3))[0m, as is illustrated by applying [47m:[0m[47m[trans][0m to the untranslated term: ACL2 !>:trans (<= 3 x) (NOT (< X '3)) => * ACL2 !> Notice for example that the macro [47m<=[0m has been eliminated in favors of the functions [47mnot[0m and [47m<[0m, and that the constant [47m3[0m has been quoted. The call [47m(untranslate term iff-flg wrld)[0m returns an untranslated term corresponding to the given translated term, [47mterm[0m, with respect to the given logical [world], [47mwrld[0m. If [47miff-flg[0m is not [47mnil[0m, then that untranslated term is merely propositionally equivalent to the input term, as the following example illustrates. ACL2 !>:trans (and x t) (IF X 'T 'NIL) => * ACL2 !>(untranslate '(IF X 'T 'NIL) nil (w state)) (AND X T) ACL2 !>(untranslate '(IF X 'T 'NIL) t (w state)) X ACL2 !> The latter result, [47mx[0m, is what one might want to see if the term is being used as the first argument of a call of the function, [47mif[0m. Indeed, [47muntranslate[0m is defined so that the [47miff[0m flag is automatically set in the test position of an [47mif[0m call. ACL2 !>:trans (if (and x t) y z) (IF (IF X 'T 'NIL) Y Z) => * ACL2 !>(untranslate '(IF (IF X 'T 'NIL) Y Z) nil (w state)) (IF X Y Z) ACL2 !> Also see [user-defined-functions-table] and [add-macro-fn].") (untranslate-preprocess (pointers) "See [user-defined-functions-table].") (update-nth (lists acl2-built-ins) "Modify a list by putting the given value at the given position [47m(Update-nth key val l)[0m returns a list that is the same as the list [47ml[0m, except that the value at the [47m0[0m-based position [47mkey[0m (a natural number) is [47mval[0m. If [47mkey[0m is an integer at least as large as the length of [47ml[0m, then [47ml[0m will be padded with the appropriate number of [47mnil[0m elements, as illustrated by the following example. ACL2 !>(update-nth 8 'z '(a b c d e)) (A B C D E NIL NIL NIL Z) We have the following theorem. (implies (and (true-listp l) (integerp key) (<= 0 key)) (equal (length (update-nth key val l)) (if (< key (length l)) (length l) (+ 1 key)))) The [guard] of [47mupdate-nth[0m requires that its first (position) argument is a natural number and its last (list) argument is a true list. [31;1mFunction: [0m<update-nth> (defun update-nth (key val l) (declare (xargs :guard (true-listp l)) (type (integer 0 *) key)) (cond ((zp key) (cons val (cdr l))) (t (cons (car l) (update-nth (1- key) val (cdr l)))))) Subtopics [Nth-aliases-table] A [table] used to associate names for nth/update-nth printing") (update-nth-array (stobj acl2-built-ins) "Update a stobj array [47mUpdate-nth-array[0m is called by [stobj] updaters to modify stobj array fields. See [stobj-example-3] for a discussion of this function and how it plays that role. [31;1mFunction: [0m<update-nth-array> (defun update-nth-array (j key val l) (declare (xargs :guard (and (integerp j) (integerp key) (<= 0 j) (<= 0 key) (true-listp l) (true-listp (nth j l))))) (update-nth j (update-nth key val (nth j l)) l))") (upper-case-p (characters acl2-built-ins) "Recognizer for upper case characters [47m(Upper-case-p x)[0m is true if and only if [47mx[0m is an upper case character, i.e., a member of the list [47m#\A[0m, [47m#\B[0m, ..., [47m#\Z[0m. The [guard] for [47mupper-case-p[0m states that its argument is a character. [47mUpper-case-p[0m is a Common Lisp function. See any Common Lisp documentation for more information. Note that the value returned may depend on the host Lisp; see [soundness], specifically Example 1 in the Section, ``Examples of divergence among Lisp implementations''. [31;1mFunction: [0m<upper-case-p> (defun upper-case-p (x) (declare (xargs :guard (characterp x))) (cond ((standard-char-p x) (and (member x '(#\A #\B #\C #\D #\E #\F #\G #\H #\I #\J #\K #\L #\M #\N #\O #\P #\Q #\R #\S #\T #\U #\V #\W #\X #\Y #\Z)) t)) (t (upper-case-p-non-standard x))))") (use (pointers) "See [hints] for information about the keyword [47m:use[0m.") (useless-runes (certify-book accumulated-persistence) "Speed up proofs by disabling useless [rune]s This topic documents the [47m:useless-runes[0m keyword argument of [47m[certify-book][0m and [47m[ld][0m, which makes it possible to speed up repeated running of a book's [events]. This option is ignored in ACL2(r) (see [real]) and, when [waterfall-parallelism] is active, in ACL2(p) (see [parallelism]). Introduction For a given [event], the so-called ``useless'' rules are those that do not contribute to the progress of any proof supporting that event. For more background see [accumulated-persistence], which is typically used for finding rules (or more precisely, [rune]s) to [disable] during proofs. The feature described in the present topic provides automation for the discovery and effective disabling of useless rules. Below, we focus first on the use of [47m:useless-runes[0m for [47m[certify-book][0m rather than for [47m[ld][0m. The main time to use this option with [47m[ld][0m may be when developing a book that is to be certified eventually with a [47m:useless-runes[0m option. We return to discuss [47mld[0m later in this topic (in Section ``Modifications for [47m[ld][0m''). To use the [47m:useless-runes[0m option of [47m[certify-book][0m, first certify your book --- say, [47mfoo.lisp[0m --- by supplying option [47m:useless-runes :write[0m. This creates a file in the subdirectory [47m.sys[0m of the book's directory, creating that directory if it does not already exist. This new file, [47m.sys/foo@useless-runes.lsp[0m, associates names of [47m[defthm][0m, [47m[defun][0m, and [47m[verify-guards][0m [events] with sets of ``useless'' [rune]s'': rule names (``[rune]s'') not contributing to the progress of the proof. Then, future certifications can use option [47m:useless-runes :read[0m --- or some limited variations of [47m:read[0m using numeric values, as discussed below) --- which, during evaluation of an event, will effectively [disable] rules associated with that event in file [47mfoo@useless-runes.lsp[0m. Environment variable [47mACL2_USELESS_RUNES[0m can take the value [47m"write"[0m or [47m"read"[0m to be used in place of the [47m:useless-runes[0m option [47m:read[0m or [47m:write[0m (respectively) of [47mcertify-book[0m. [47mACL2_USELESS_RUNES[0m can also have value [47m"nil"[0m (case-insensitive) or a string representing a legal numeric value for the [47m:useless-runes[0m option of [47m[certify-book][0m. This is all discussed below. By default, certification of the [community-books], when using either [47mmake[0m (as described elsewhere; see [books-certification]) or [build::cert.pl], is performed with environment variable [47mACL2_USELESS_RUNES[0m set to [47m"-25"[0m. This setting, for each book [47mfoo.lisp[0m, causes part of the corresponding file [47m.sys/foo@useless-runes.lsp[0m, if it exists, to be consulted as described below. However, useless runes are entirely ignored (both their use and for writing to [47m.sys/foo@useless-runes.lsp[0m files) both in ACL2(r) (see [real]) and, when [waterfall-parallelism] is active, in ACL2(p) (see [parallelism]). Detailed Documentation Again, the [47m:useless-runes[0m option provides a way to automate discovery and, in subsequent uses, disabling of useless runes that can speed up proofs. Information about useless runes is communicated using a file, which we call the ``@useless-runes.lsp file'' (or, sometimes, ``useless-runes file''), whose name is obtained by adding the suffix [47m"@useless-runes.lsp"[0m to the book name, and which is placed in the [47m.sys[0m subdirectory of the book's directory, after creating that subdirectory if it does not already exist. For example, if the book's filename is [47m"foo.lisp"[0m then the corresponding @useless-runes.lsp has filename [47m".sys/foo@useless-runes.lsp"[0m. The following table summarizes the legal values for the option [47m:useless-runes[0m; further explanation follows. :write ; Write the @useless-runes.lsp file to speed up future proofs. :read or ; Read the @useless-runes.lsp file to speed up proofs; :read? ; file must exist for :read, but need not exist for :read?. N, -N ; N is a positive integer not exceeding 100. Then |N|% of the rules ; indicated by the @useless-runes.lsp file are to be kept disabled. ; The @useless-runes.lsp file needs to exist for N but not for -N. nil ; Do not read or write the @useless-runes.lsp file. Notice in particular that [47m:useless-runes 100[0m is equivalent to [47m:useless-runes :read[0m, while [47m:useless-runes -100[0m is equivalent to [47m:useless-runes :read?[0m. The option [47m:useless-runes :write[0m directs that a corresponding @useless-runes.lsp file is to be written. Each top-level entry of this file that is non-trivial (see below) has the form (name (frames-1 tries-1 rune-1) (frames-2 tries-2 rune-2) ... (frames-k tries-k rune-k) ) where [47mname[0m is the name of a [47m[defthm][0m, [47m[defun][0m, or [47m[verify-guards][0m event, and each tuple [47m(frames-i tries-i rune-i)[0m indicates the number of frames and tries for [47mrune-i[0m recorded for the proofs done on behalf of that event. ACL2 claims that none of the indicated rules contributed to the progress of the proof. See [accumulated-persistence], but also see [accumulated-persistence-subtleties] for some limitations. These top-level entries are listed in order of event in the book, from top to bottom. Because of [local] [events], the same name may appear more than once; we say more about this in the ``Subtleties'' section, below. Note that ``trivial'' entries are possible, where there are no tuples; in that case, just [47m(name)[0m is printed, on a single line. Otherwise printing uses the format shown above, where the first line contains a left parenthesis on the left margin followed by the name, and each tuple is on a single line starting in column 1 (i.e., after a single space), as is the final right parenthesis. The option [47m:useless-runes :read[0m or [47m:useless-runes :read?[0m directs use of the corresponding @useless-runes.lsp file, if it exists. If that file does not exist, an error is caused when the option value is [47m:read[0m but the option is simply ignored when the option value is [47m:read?[0m. The value of [47m:useless-runes[0m may also be a non-zero integer between -100 and 100, inclusive. The absolute value of this number is the percentage of the runes associated with the current event that are to be effectively kept [disable]d, starting with the useless rune with the highest number of frames built (see [accumulated-persistence]). For example, if the value is 20 then 1/5 of the runes associated with the current event in the @useless-runes.lsp file are to be kept disabled; so if the relevant top-level form in that file is (name (frames-1 tries-1 rune-1) (frames-2 tries-2 rune-2) (frames-3 tries-3 rune-3) (frames-4 tries-4 rune-4) (frames-5 tries-5 rune-5) (frames-6 tries-6 rune-6) (frames-7 tries-7 rune-7) ) then 1/5 of the 7 runes are to be disabled, so since the first integer greater than or equal to 7/5 is 2, the runes [47mrune-1[0m and [47mrune-2[0m will be kept disabled. Note again that the value [47m100[0m for [47m:useless-runes[0m gives the same behavior as the value [47m:read[0m, and the value [47m-100[0m gives the same behavior as the value [47m:read?[0m. The [47m:useless-runes[0m option need not be given explicitly to [47m[certify-book][0m. Suppose that the environment variable [47mACL2_USELESS_RUNES[0m has a non-empty value. Then that value implicitly invokes the [47m:useless-runes[0m option as indicated by the following table, which shows how that environment variable value corresponds to a value for the [47m:useless-runes[0m option. ACL2_USELESS_RUNES value :useless-runes value ------------------------ -------------------- WRITE (case insensitive) :write READ (case insensitive) :read READ? (case insensitive) :read? i, ij, -i, -ij, 100, -100 corresponding integer, which cannot be 0 (i and j are base-10 digits) [31;1mImportant[0m. An explicitly supplied [47m:useless-runes[0m value normally takes priority over the value of environment variable [47mACL2_USELESS_RUNES[0m. However, for [47mcertify-book[0m the environment variable takes priority if its (case insensitive) value is [47m"WRITE"[0m provided [47m:useless-runes nil[0m is not supplied explicitly. This feature supports the use of the environment variable when using [47mmake[0m to update @useless-runes.lsp files for the community books. If you want certification to avoid reading the book's @useless-runes.lsp file even when this environment variable has a non-empty value that specifies reading, use option [47m:useless-runes nil[0m. A reason for allowing integer values, rather than only [47m:read[0m and [47m:read?[0m, is that the disabling of useless runes can cause a proof to fail. Although this is probably uncommon, it can happen, for example because an otherwise useless rule rewrites the hypothesis of rule R to something that can not be proved by rewriting, thus blocking the use of rule R; but with the useless rule disabled, R is successfully applied, sending the proof in a direction that leads to failure. This problem may disappear when using only a portion of the useless rules. See also [accumulated-persistence-subtleties]. Note that when using the @useless-runes.lsp file for a given event's proofs, then the appropriate rules are effectively [disable]d not only at the top level, but also whenever [hints] are supplied. So if an [47m:[0m[47m[in-theory][0m hint specifies a [theory] that includes rule R, but rule R is specified for disabling for the current event by the @useless-runes.lsp file, then R will be removed from the theory before installing that hint. In particular, even the hint [47m:in-theory (enable [0mR[47m)[0m will not enable R in this case. Finally, we remark that the @useless-runes.lsp file is somewhat robust in the following sense. Suppose that rule R is specified in that file, but at the time the @useless-runes.lsp is read, rule R has been removed from one's books. Then the inclusion of R as a useless rule will simply be ignored, rather than causing an error. Subtleties The @useless-runes.lsp files do not contain any [47m:[0m[47m[executable-counterpart][0m runes, because there are many places that ACL2 does not track such runes for [47m[accumulated-persistence][0m. (Details are in a comment in the ACL2 source definition of function [47mprint-useless-runes[0m.) On rare occasions, when using the [47m:read[0m option or related values that specify reading from an appropriate @useless-runes.lsp file, the [package] of a rune's name might not be known to ACL2 at read time. In that case, that rune will be ignored. Because of [local] [events], more than one event may be associated with a name in a given @useless-runes.lsp file. When using the [47m:read[0m option or related values that specify reading from an appropriate @useless-runes.lsp file, ACL2 considers entries for a given name from top to bottom in the @useless-runes.lsp file, attempting to match them to [47m[defthm][0m, [47m[defun][0m, and [47m[verify-guards][0m events from top to bottom in the book. As suggested by discussions above, a @useless-runes.lsp file is intended not to cause proof failures, even if it is older than the corresponding book or even older than other books containing runes that are listed in that @useless-runes.lsp file. That said, an out-of-date @useless-runes.lsp might cause proofs to fail. In particular, imagine that there are several lemmas in the corresponding book all with the same name (and thus all [local] to an [47m[encapsulate][0m event except perhaps the last), and one of those lemmas other than the last is deleted from the book. Then references to the later such lemmas will be wrong in the @useless-runes.lsp file. If you run into this problem, then either regenerate the @useless-runes.lsp file (e.g., using [47mcertify-book[0m with environment variable [47mACL2_USELESS_RUNES[0m set to [47m"write"[0m), or give distinct names to your book's lemmas, or even consider adding a line like the following to a suitable [47m.acl2[0m file (see [build::custom-certify-book-commands]). ; cert-flags: ? t :useless-runes nil Adaptations for [47m[ld][0m The [47m:useless-runes[0m keyword argument was originally developed for [47m[certify-book][0m, and that is probably still where it is most useful. But when developing or updating a book [47m"BK"[0m, it may be convenient to evaluate the book's [events] using [47m(ld "BK.lisp" .. :useless-runes ..)[0m. In that case, it is probably a good idea to run that [47mld[0m command in the same certification [world] (i.e., the world with the same sequence of [portcullis] commands) as will be encountered when certifying the book, so that the accesses to the @useless-runes.lsp will match up between the [47mld[0m call and a corresponding [47mcertify-book[0m call. The following observations may help in that respect. * If [47m"BK.lisp"[0m has previously been certified, there should be a file [47m"BK.port"[0m. By executing [47m(ld "BK.port")[0m, you will put yourself in the appropriate certification world (unless the book's [portcullis] commands have changed since the time it was certified). * If your [47mld[0m of the book ends prematurely in an error, then before you call [47mld[0m again with a [47m:useless-runes[0m argument, it would very likely be best to back up (using [47m:[0m[47m[ubt][0m) so that you are once again in the intended certification world. Here are a few differences between [47mld[0m and [47mcertify-book[0m with respect to useless-runes. For purposes of this discussion, let's say a call of [47mld[0m is ``a book-like call'' if the first argument is a string ending with [47m".lisp"[0m. * Just as how [47mcertify-book[0m consults environment variable [47mACL2_USELESS_RUNES[0m for an implicit value of omitted keyword argument [47m:useless-runes[0m, a book-like call of [47mld[0m consults environment variable [47mACL2_USELESS_RUNES_LD[0m. For example, if environment variable [47mACL2_USELESS_RUNES_LD[0m has value [47m"50"[0m, then the call [47m(ld "foo.lisp")[0m will be treated as though it were the call [47m(ld "foo.lisp" :useless-runes 50)[0m. * If environment variable [47mACL2_USELESS_RUNES_LD[0m takes on the special value [47m"cert"[0m, case-insensitive, then [47mld[0m will consult environment variable [47mACL2_USELESS_RUNES[0m just as [47mcertify-book[0m does. * It is an error for a call of [47mld[0m that is not book-like to have a non-[47mnil[0m [47m:useless-runes[0m argument. For a call of [47mld[0m without a [47m:useless-runes[0m argument, environment variables supply a useless-runes value (as described above) only if it is a book-like call. * The value of keyword argument [47m:useless-runes[0m in a call of [47mcertify-book[0m or [47mld[0m does not persist to a subsidiary call of [47mcertify-book[0m or [47mld[0m. If you want a useless-runes value to persist, use environment variables. * Recall that for [47mcertify-book[0m, the environment variable takes priority if its (case insensitive) value is [47m"write"[0m provided the [47m:useless-runes nil[0m keyword argument is not supplied. But for [47mld[0m, an explicit value of the [47m:useless-runes[0m keyword argument always takes priority; environment variables, even with value [47m"write"[0m, do not override any such value. Performance In ``everything'' testing of all of the [community-books] during (not quite complete) development of this capability, we found that writing the @useless-runes.lsp files (by setting the environment variable [47mACL2_USELESS_RUNES[0m to [47m"write"[0m) caused an 11% slowdown from the normal time, but a fresh such test when reading the @useless-runes.lsp files by setting the environment variable [47mACL2_USELESS_RUNES[0m to [47m"25"[0m cut 24% from the normal time. Books varied considerably, however. For example, after finding a specific time reduction that was particularly significant, we re-certified on standalone runs (i.e., on an otherwise unloaded machine) and found that the time was reduced from 17 minutes and 1.9 seconds down to 34.93 seconds, thus eliminating 96.6% of the time. Subtopics [Useless-runes-failures] Failures caused by [useless-runes]") (useless-runes-failures (failure useless-runes) "Failures caused by [useless-runes] When an event fails you may see the following message: *NOTE*: Useless-runes were in use and can affect proof attempts. See :DOC useless-runes-failures. This message may be printed after the usual failure message when a [useless-runes] file has been consulted during proofs, as is usually the case when using build system tools (see [books-certification] and [build::cert.pl]). It is intended to suggest that you consider removing or regenerating the associated [useless-runes] file in the situation described below. Suppose that you have developed a book --- say, [47mfoo.lisp[0m --- and placed it into the [community-books]. Then [regression] runs may occasionally generate (or regenerate) the associated [useless-runes] file. Now suppose you modify [47mfoo.lisp[0m or some books that are included in it. You successfully run [47m(certify-book "foo")[0m; yet, certification of [47mfoo.lisp[0m subsequently fails as part of a [regression] run or when you use [47m[build::cert.pl][0m to certify [47mfoo.lisp[0m. This could be unsettling! In that case, what is probably happening is that the [useless-runes] file is no longer suitable. If you are a contributor to the ``ACL2 System and Community Books'' GitHub project (see [git-quick-start]), you can update repository as follows (followed by the usual actions when updating the repository). git rm .sys/foo@useless-runes.lsp Or, if you like, you could regenerate the useless-runes file, for example as follows. (certify-book "foo" ? t :useless-runes :write) Or if you prefer to avoid this useless-runes file from now on, you could add a line like the following to [47mfoo.acl2[0m (see [build::custom-certify-book-commands]) and also, ideally, delete the useless-runes file using the [47m"git rm"[0m command displayed above. ; cert-flags: ? t :useless-runes nil") (user-defined-functions-table (macros) "An advanced [table] used to replace certain system functions Examples: (table user-defined-functions-table 'untranslate-preprocess 'my-preprocess) (table user-defined-functions-table 'untranslate 'my-untranslate) This feature should perhaps only be used by advanced users who have a thorough understanding of the system functions being replaced. There are currently two ways a user can affect the way ACL2 prints terms. The first example associates the user-defined function symbol [47mmy-preprocess[0m with [47muntranslate-preprocess[0m. As a result, when ACL2 prints a term, say during a proof, using its so-called ``untranslate'' process the first thing it does is to call [47mmy-preprocess[0m on two arguments: that term and the current ACL2 logical [world]. If the call produces a non-[47mnil[0m result, then that result is passed to the untranslate process. The second example associates the user-defined function symbol [47mmy-untranslate[0m with the built-in function symbol [47muntranslate[0m. As a result, the code for [47mmy-untranslate[0m will be run whenever the untranslate process is run. The formals of the two functions must agree and must not contain any [stobj] names. Note that these overrides fail to occur upon guard violations and some other evaluation errors. The [47muntranslate-preprocess[0m approach may suffice for most cases in which a user wants to modify the way output is produced by the theorem prover. We present an example immediately below, but see [untranslate-patterns] for a more elaborate example. If the [47muntranslate-preprocess[0m approach does not seem sufficient for your purposes, you are invited to look at community book [47mbooks/misc/rtl-untranslate.lisp[0m or the source code for [define] for an example of user-defined [47muntranslate[0m (i.e., following the second example displayed above). Suppose you have a large constant that you would prefer not to see in proofs. For example, you may have submitted the following definition (but imagine a much larger constant, say, a list of length 1,000,000). (defconst *a* '(a b c d)) If you submit the following (silly) theorem (thm (equal (cons x *a*) (car (cons yyy zzz)))) then you will see the following output: (EQUAL (CONS X '(A B C D)) YYY). If [47m*a*[0m had represented a much larger structure, we would wish we could see the following instead. (EQUAL (CONS X *A*) YYY) That can be accomplished as follows. First we make the following definition. (defun my-preprocess (term wrld) (declare (ignore wrld)) (if (equal term (list 'quote *a*)) '*a* nil)) Now we submit the following [47m[table][0m event. (table user-defined-functions-table 'untranslate-preprocess 'my-preprocess) This will install [47mmy-preprocess[0m as a preprocessor before the normal untranslation routine is applied to printing a term. When the untranslation routine encounters the constant [47m(QUOTE (A B C D))[0m, it will replace it with [47m*a*[0m, and the usual untranslation routine will print this as [47m*A*[0m.") (user-stobjs-modified-warnings (trans-eval stobj) "Interactions of [47m[trans-eval][0m with [stobj]s that violate applicative semantics The utility, [47m[trans-eval][0m, may be called to evaluate arbitrary ACL2 forms. It can thus be useful for writers of tools. This topic discusses certain [warnings] that may be issued by [47mtrans-eval[0m for [stobj] updates that may violate applicative semantics. Also see [trans-eval-and-locally-bound-stobjs] for how [47mtrans-eval[0m relates to updates of locally bound stobjs. Please see [trans-eval] and [trans-eval-and-stobjs] for relevant background. Consider the following log. ACL2 !>(foo st state) ACL2 Warning [User-stobjs-modified] in FOO: A call of the ACL2 evaluator on the term (UPDATE-FLD '4 ST) may have modified the user stobj ST. See :DOC user-stobjs-modified-warnings. (4 <state> <st>) ACL2 !> The warning is intended to indicate that a [stobj] may have been modified even though that stobj was accessed indirectly, through the ACL2 [state]. If you see such a warning, it is probably caused by a utility that you are invoking. At this time there are no special tools for identifying which tool is issuing those warnings, but the ``context'' on the first line of the warning --- [47mFOO[0m, above --- may give a clue. Below we discuss the following events, which were evaluated before producing the log above. (defstobj st fld) (defun foo (st state) (declare (xargs :stobjs (st state) :mode :program)) (let ((st (update-fld 3 st))) (mv-let (erp val state) (trans-eval '(update-fld 4 st) 'foo state nil) (declare (ignore erp val)) (mv (fld st) state st)))) After submitting these two forms, we can submit to ACL2 the form [47m(foo st state)[0m to produce the log displayed near the top of this topic. That log is actually very surprising if you think about it, since the [47mtrans-eval[0m call in the definition of [47mfoo[0m modifies only the [47mstate[0m parameter, not the [47mst[0m parameter, and yet the value [47mst[0m has changed: [47m(fld st)[0m has changed from 3 to 4, while evaluating code in which [47mst[0m does not occur free! Let us discuss this point further. First consider the definition of [47mfoo[0m. Now [47mtrans-eval[0m returns an [error-triple], say [47m(mv erp val state)[0m, where [47merp[0m and [47mval[0m are ordinary (non-[stobj]) values. In particular, [47mtrans-eval[0m does not return the user-defined stobj, [47mst[0m. It ``should'' follow, then, that the only modification to [47mst[0m before returning is by the form [47m(update-fld 3 st)[0m. So the final value of [47m(fld st)[0m ``should'' be 3; yet, it is 4, not 3! So the first return value of 4, above, can very reasonably be considered to violate applicative semantics. ACL2 acknowledges this concern --- that is, the concern that an operation (i.e., [47mfld[0m) now gives a different result on an object (i.e., [47mst[0m) that ``should'' not have changed, thus violating normal applicative semantics --- by printing the warning displayed above. To see how this can happen, consider that in raw Lisp the stobj, [47mst[0m, is actually a one-element array whose unique value is [47m(fld st)[0m. The [47mtrans-eval[0m call in [47mfoo[0m replaces that element, in this case 3, with a new value, in this case 4. It does this [3mdestructively[0m: the memory location of [47mst[0m is not changed. Thus, evaluation of [47m(fld st)[0m after the [47mtrans-eval[0m call now returns the new array element, which is 4. Worse yet, there are similar cases where there is [3mno[0m such violation of applicative semantics! We return to this point later below. First we provide some additional discussion of such warnings, as well as observations for tool writers who want to eliminate the warnings. In general, such a warning is printed whenever the [47mstobjs-out[0m returned in the [47mcar[0m of the value, as discussed above, contains a user-defined stobj name, that is, a non-[47mnil[0m value other than [47mstate[0m. Fortunately, this behavior can only happen with [47m:[0m[47m[program][0m-mode functions; [47mtrans-eval[0m will never be in [47m:[0m[47m[logic][0m mode, and therefore, neither will its callers. Nevertheless, even without proving [47mnil[0m one might reasonably be frustrated by this sort of violation of applicative semantics. The warning is, at least, an acknowledgment of this situation. We next discuss how to write tools that avoid producing such warnings, and the advisability (or not) of doing so. There may be cases in which you want to write a tool that calls [47mtrans-eval[0m and modifies user-defined stobjs, but you don't want the users of your tool to see the warning, perhaps because you are convinced that no stobj parameter is modified indirectly using [47mtrans-eval[0m. Think carefully about whether you really don't want them to see the warning! After all, they may be relying on normal applicative semantics, even with [47m:program[0m-mode functions. If indeed you want to avoid warnings, you can call the function [47mtrans-eval-no-warning[0m exactly as you call [47mtrans-eval[0m. For example, if you replace [47mtrans-eval[0m by [47mtrans-eval-no-warning[0m in the definition above, and then you evaluate [47m(foo st state)[0m, you will not see the warning printed above. Again, consider whether you really want to suppress that warning. Remark pertaining to [47m(ld ...)[0m. There is another alternative to [47mtrans-eval[0m, [47mtrans-eval-default-warning[0m. This alternative behaves like [47mtrans-eval[0m when the [47mld[0m special, [47mld-user-stobjs-modified-warning[0m, is [47mt[0m; otherwise it behaves like [47mtrans-eval-no-warning[0m. See [ld]. There are several calls of [47mtrans-eval-default-warning[0m in the ACL2 source code: in function [47mld-read-eval-print[0m, which evaluates on behalf of the top-level loop, and in some functions that support [events], such as those supporting the proof-builder. But for user-level code it may be more appropriate to call [47mtrans-eval[0m so that violations of applicative semantics are reported. These warnings are unimportant for the top-level calls of [47mtrans-eval[0m that implement the ACL2 read-eval-print loop, because one expects stobjs to be updated by evaluation. End of Remark. For [trans-eval] and [47mtrans-eval-default-warning[0m, the normal way of inhibiting warnings is supported: [47m(set-inhibit-warnings "User-stobjs-modified")[0m. We now elaborate on a point made briefly above, that there are cases where the usual violation of applicative semantics does not take place. This happens when the underlying raw Lisp stobj is actually replaced, which happens when there is a single stobj field that is either an array being resized or a hash table being initialized (with the ``clear'' or ``init'' function); see [defstobj]. Consider the following example. (defstobj st2 (ar :type (array t (10)) :resizable t)) (defun foo2 (st2 state) (declare (xargs :stobjs (st2 state) :mode :program)) (let ((st2 (update-ari 3 'old st2))) (mv-let (erp val state) (trans-eval '(let ((st2 (resize-ar 20 st2))) (update-ari 3 'new st2)) 'foo state nil) (declare (ignore erp val)) (mv (ari 3 st2) state st2)))) After submitting these forms, evaluation of the form [47m(foo2 st2 state)[0m produces [47m(OLD <state> <st2>)[0m. But based on the first example, [47mfoo[0m, we might expect that destructive modification of [47mst2[0m would result instead in [47m(NEW <state> <st2>)[0m. Indeed, if the first argument of [47mtrans-eval[0m in the definition of [47mfoo2[0m is instead [47m(update-ari 3 'new st2))[0m, then the result is [47m(NEW <state> <st2>)[0m. So why do we get the OLD result using the definition of [47mfoo2[0m displayed above? The reason is that when a stobj has a single field, and that field is an array or hash table, then in raw Lisp the stobj [3mis[0m exactly that field. When we call [47mresize-ar[0m, the entire array is rebuilt, and thus the stobj is at a new memory location. To be precise: After the resizing, then the value of [47mst2[0m in the [47muser-stobj-alist[0m of the ACL2 state is a new stobj: the actual parameter [47mst2[0m of [47mfoo2[0m is not destructively modified. Thus, normal applicative semantics apply: the final value of [47m(fld st2)[0m is independent of the replacement of [47mst2[0m in the [47muser-stobj-alist[0m hence is still 3 (from the first update). We close with a more realistic example. (It is based on our experience modifying the definition of the macro, [47mlocal-test[0m, in [community-book] [47mbooks/system/tests/nested-stobj-tests.lisp[0m, when we changed ACL2 so that the stobj is the entire array field when there is only that one field.) The [47m[make-event][0m call below fails, because the resizing operation replaces the stobj in the global [47muser-stobj-alist[0m of the ACL2 [state], but the call of [47mEQUAL[0m still references the original stobj. This failure is thus exactly as expected for an applicative semantics. However, it fails only because the resize operation is not destructive: it replaces the entire stobj. (defstobj st3 (ar3 :type (array t (10)) :resizable t)) ; Fails (see discussion above): (make-event (er-progn (trans-eval '(let ((st3 (resize-ar3 30 st3))) (update-ar3i 24 'done st3)) 'top state t) (value (equal (ar3i 24 st3) 'done)) (value '(value-triple :success)))) ; Passes because by now, the user-stobj-alist has been updated by ; the top-level call of trans-eval to implement the ACL2 ; read-eval-print loop: (assert-event (equal (ar3i 24 st3) 'done)) ; The following version passes because the second trans-eval call ; below references the value of st3 in the user-stobj-alist that was ; produced by the first trans-eval call below. (make-event (er-progn (trans-eval '(let ((st3 (resize-ar3 40 st3))) (update-ar3i 34 'new st3)) 'top state t) (trans-eval '(if (equal (ar3i 34 st3) 'new) (value nil) (er soft 'top "Failed!")) 'top state t) (value '(value-triple :success))))") (using-acl2 (installation about-acl2) "Using ACL2 [31;1mTable of Contents[0m * Invoking ACL2 * Testing ACL2 * Certifying ACL2 Books * Documentation * Emacs Invoking ACL2 We assume that you have followed the [installation] instructions to install ACL2. The sources and, in general, an executable image are located in that directory. However, if you have not saved an executable image but instead use the directions for running ACL2 without building an executable image (see [running-ACL2-without-executable]), skip to ``When ACL2 Starts Up'' below. Invoke ACL2 by running the executable file, [47msaved_acl2[0m, for example as follows (but you can supply a suitable pathname if you are not standing in the directory that contains [47msaved_acl2[0m). mycomputer% ./saved_acl2 If you on a Unix-like system, then to make it easy to invoke ACL2 by typing a short command, e.g., mycomputer% acl2 you may want to install an executable file on your path, e.g., [47m~/bin/acl2[0m, containing the following two lines where [47m<path>[0m is the absolute pathname for the directory of [47msaved_acl2[0m. #!/bin/sh <path>/saved_acl2 "$@" Note: A carriage return in the file after the last line above may be important! [3mWhen ACL2 Starts Up[0m When you invoke ACL2, you should see the host Common Lisp print a header concerning the ACL2 version, license and copyright. Most or all hosts then automatically enter the ACL2 [3mcommand loop[0m, an ACL2 read-eval-print loop with the prompt: ACL2 !> In the very unlikely case that a host leaves you in Common Lisp's read-eval-print loop, then you'll need to evaluate the Common Lisp expression [47m(ACL2::LP)[0m or simply [47m(LP)[0m if the current package is [47m"ACL2"[0m. Once in the ACL2 command loop, you can type an ACL2 term, typically followed by ``return'' or ``enter,'' and ACL2 will evaluate the term, print its value, and prompt you for another one. Below are three simple interactions. ACL2 !>t T ACL2 !>'abc ABC ACL2 !>(+ 2 2) 4 To get out of the ACL2 command loop, type the [47m:q[0m command. This returns you to the host Common Lisp. We sometimes call this ``raw Lisp.'' You may re-enter the command loop with [47m(LP)[0m as above. To quit ACL2 (and Lisp) entirely, submit the command, [47m(quit)[0m. Note that when you are in raw Lisp you can overwrite or destroy ACL2 by executing inappropriate Common Lisp expressions. [31;1mAll bets are off once you've exited the ACL2 loop.[0m That said, this is typically safe and many users do it. For example, you might exit the ACL2 loop, activate some debugging or trace features in raw Lisp, and then reenter the ACL2 loop. While developing proofs or tracking down problems, this can occasionally be reasonable behavior. Now you are ready to test your copy of ACL2. Testing ACL2 An easy way to test the theorem prover is to type the following term to the ACL2 command loop. :mini-proveall This will cause a sequence of commands to be processed, each of which is first printed out as though you had typed it. Each will print some text, generally a proof of some conjecture. None should fail. A more elaborate test is to certify the community books; see [community-books] and [certify-book]. This certification is a good idea anyhow; this is our next topic. On a Unix-like system, you can also certify just a small but useful subset of the books in a few minutes by executing [47mmake basic[0m in either the main ACL2 directory or the [47mbooks/[0m subdirectory. Certifying ACL2 Books The [3mcommunity books[0m (see [COMMUNITY-BOOKS]), which reside in subdirectory [47mbooks/[0m, have been contributed by many ACL2 users. See [books] for a through discussion of the general topic of books. Books should be [3mcertified[0m before they are used. ACL2 is distributed without book [certificate]s, mainly because certification produces compiled code specific to the host. You should certify the books locally, both as a test of your ACL2 image and because books generally need to be certified before they can be used. See [installation], or more specifically [installation-instructions], for how to perform this certification. For additional explanation and further options, see [books-certification]. Documentation See [documentation] for a discussion of ACL2's documentation system. To query ACL2 about a built-in topic, [47m<topic>[0m, submit [47m:DOC <topic>[0m to ACL2. Emacs Emacs users may find it helpful to load into emacs the file [47memacs/emacs-acl2.el[0m for Emacs 24 or 25 or the file [47mbooks/emacs/emacs-acl2.el[0m for later Emacs versions. Utilities offered by this file are documented near the top of the file. In particular, this file automatically loads the [ACL2-doc] Emacs-based browser for ACL2 documentation.") (using-computed-hints (computed-hints hints) "How to use computed hints Computed hints (see [computed-hints]) are extraordinarily powerful. We show a few examples here to illustrate their use. We recommend that the [47musing-computed-hints-n[0m topics be read in the order [47musing-computed-hints-1[0m, [47musing-computed-hints-2[0m, and so on. Subtopics [Using-computed-hints-1] Driving Home the Basics [Using-computed-hints-2] One Hint to Every Top-Level Goal in a Forcing Round [Using-computed-hints-3] Hints as a Function of the Goal (not its Name) [Using-computed-hints-4] Computing the Hints [Using-computed-hints-5] Debugging Computed Hints [Using-computed-hints-6] Using the computed-hint-replacement feature [Using-computed-hints-7] Using the [47mstable-under-simplificationp[0m flag [Using-computed-hints-8] Some Final Comments") (using-computed-hints-1 (using-computed-hints) "Driving Home the Basics The common hint ("Subgoal 3.2.1''" :use lemma42) has the same effect as the computed hint (if (equal id '((0) (3 2 1) . 2)) '(:use lemma42) nil) which, of course, is equivalent to (and (equal id '((0) (3 2 1) . 2)) '(:use lemma42)) which is also equivalent to the computed hint my-special-hint provided the following [47mdefun[0m has first been executed (defun my-special-hint (id clause world) (declare (xargs :mode :program) (ignore clause world)) (if (equal id '((0) (3 2 1) . 2)) '(:use lemma42) nil)) It is permitted for the [47mdefun[0m to be in :LOGIC mode (see [defun-mode]) also. Just to be concrete, the following three events all behave the same way (if [47mmy-special-hint[0m is as above): (defthm main (big-thm a b c) :hints (("Subgoal 3.2.1''" :use lemma42))) (defthm main (big-thm a b c) :hints ((and (equal id '((0) (3 2 1) . 2)) '(:use lemma42)))) (defthm main (big-thm a b c) :hints (my-special-hint))") (using-computed-hints-2 (using-computed-hints) "One Hint to Every Top-Level Goal in a Forcing Round Suppose the main proof completes with a forcing round on three subgoals, "[1]Subgoal 3", "[1]Subgoal 2", and "[1]Subgoal 1". Suppose you wish to [47m:use lemma42[0m in all top-level goals of the first forcing round. This can be done supplying the hint (if test '(:use lemma42) nil), where [47mtest[0m is an expression that returns [47mt[0m when [47mID[0m is one of the clause ids in question. goal-spec (parse-clause-id goal-spec) "[1]Subgoal 3" ((1) (3) . 0) "[1]Subgoal 2" ((1) (2) . 0) "[1]Subgoal 1" ((1) (1) . 0) Recall (see [clause-identifier]) that [47mparse-clause-id[0m maps from a goal spec to a clause id, so you can use that function on the goal specs printed in the failed proof attempt to determine the clause ids in question. So one acceptable [47mtest[0m is (member-equal id '(((1) (3) . 0) ((1) (2) . 0) ((1) (1) . 0))) or you could use [47mparse-clause-id[0m in your computed hint if you don't want to see clause ids in your script: (or (equal id (parse-clause-id "[1]Subgoal 3")) (equal id (parse-clause-id "[1]Subgoal 2")) (equal id (parse-clause-id "[1]Subgoal 1"))) or you could use the inverse function (see [clause-identifier]): (member-equal (string-for-tilde-@-clause-id-phrase id) '("[1]Subgoal 3" "[1]Subgoal 2" "[1]Subgoal 1")) Recall that what we've shown above are the tests to use in the computed hint. The hint itself is [47m(if test '(:use lemma42) nil)[0m or something equivalent like [47m(and test '(:use lemma42))[0m. The three tests above are all equivalent. They suffer from the problem of requiring the explicit enumeration of all the goal specs in the first forcing round. A change in the script might cause more forced subgoals and the ones other than those enumerated would not be given the hint. You could write a test that recognizes all first round top-level subgoals no matter how many there are. Just think of the programming problem: how do I recognize all the clause id's of the form [47m((1) (n) . 0)[0m? Often you can come to this formulation of the problem by using [47mparse-clause-id[0m on a few of the candidate goal-specs to see the common structure. A suitable test in this case is: (and (equal (car id) '(1)) ; forcing round 1, top-level (pre-induction) (equal (len (cadr id)) 1) ; Subgoal n (not Subgoal n.i ...) (equal (cddr id) 0)) ; no primes The test above is ``overkill'' because it recognizes precisely the clause ids in question. But recall that once a computed hint is used, it is (by default) removed from the hints available to the children of the [clause]. Thus, we can widen the set of clause ids recognized to include all the children without worrying that the hint will be applied to those children. In particular, the following test supplies the hint to every top-level goal of the first forcing round: (equal (car id) '(1)) You might worry that it would also supply the hint to the subgoal produced by the hint --- the cases we ruled out by the ``overkill'' above. But that doesn't happen since the hint is unavailable to the children. You could even write: (equal (car (car id)) 1) which would supply the hint to every goal of the form "[1]Subgoal ..." and again, because we see and fire on the top-level goals first, we will not fire on, say, "[1]Subgoal *1.3/2", i.e., the id '((1 1 3) (2) . 0) even though the test recognizes that id. Finally, the following test supplies the hint to every top-level goal of every forcing round (except the 0th, which is the ``gist'' of the proof, not ``really'' a forcing round): (not (equal (car (car id)) 0)) Recall again that in all the examples above we have exhibited the [47mtest[0m in a computed hint of the form [47m(if test '(:key1 val1 ...) nil)[0m.") (using-computed-hints-3 (using-computed-hints) "Hints as a Function of the Goal (not its Name) Sometimes it is desirable to supply a hint whenever a certain term arises in a conjecture. For example, suppose we have proved (defthm all-swaps-have-the-property (the-property (swap x)) :rule-classes nil) and suppose that whenever [47m(SWAP A)[0m occurs in a goal, we wish to add the additional hypothesis that [47m(THE-PROPERTY (SWAP A))[0m. Note that this is equivalent supplying the hint (if test '(:use (:instance all-swaps-have-the-property (x A))) nil) where [47mtest[0m answers the question ``does the [clause] contain [47m(SWAP A)[0m?'' That question can be asked with [47m(occur-lst '(SWAP A) clause)[0m. Briefly, [47moccur-lst[0m takes the representation of a translated term, x, and a list of translated terms, y, and determines whether x occurs as a subterm of any term in y. (By ``subterm'' here we mean proper or improper, e.g., the subterms of [47m(CAR X)[0m are [47mX[0m and [47m(CAR X)[0m.) Thus, the computed hint: (if (occur-lst '(swap a) clause) '(:use (:instance all-swaps-have-the-property (x A))) nil) will add the hypothesis [47m(THE-PROPERTY (SWAP A))[0m to every goal containing [47m(SWAP A)[0m --- except the children of goals to which the hypothesis was added. [31;1mA COMMON MISTAKE[0m users are likely to make is to forget that they are dealing with translated terms. For example, suppose we wished to look for [47m(SWAP (LIST 1 A))[0m with [47moccur-lst[0m. We would never find it with (occur-lst '(SWAP (LIST 1 A)) clause) because that presentation of the term contains macros and other abbreviations. By using :trans (see [trans]) we can obtain the translation of the target term. Then we can look for it with: (occur-lst '(SWAP (CONS '1 (CONS A 'NIL))) clause) Note in particular that you must * eliminate all macros and * explicitly quote all constants. We recommend using [47m:trans[0m to obtain the translated form of the terms in which you are interested, before programming your hints. An alternative is to use the expression [47m(prettyify-clause clause nil nil)[0m in your hint to convert the current goal clause into the s-expression that is actually printed. For example, the clause ((NOT (CONSP X)) (SYMBOLP Y) (EQUAL (CONS '1 (CAR X)) Y)) ``prettyifies'' to (IMPLIES (AND (CONSP X) (NOT (SYMBOLP Y))) (EQUAL (CONS 1 (CAR X)) Y)) which is what you would see printed by ACL2 when the goal clause is that shown. However, if you choose to convert your clauses to prettyified form, you will have to write your own explorers (like our [47moccur-lst[0m), because all of the ACL2 term processing utilities work on translated and/or clausal forms. This should not be taken as a terrible burden. You will, at least, gain the benefit of knowing what you are really looking for, because your explorers will be looking at exactly the s-expressions you see at your terminal. And you won't have to wade through our still undocumented term/clause utilities. The approach will slow things down a little, since you will be paying the price of independently consing up the prettyified term. We make one more note on this example. We said above that the computed hint: (if (occur-lst '(swap a) clause) '(:use (:instance all-swaps-have-the-property (x A))) nil) will add the hypothesis [47m(THE-PROPERTY (SWAP A))[0m to every goal containing [47m(SWAP A)[0m --- except the children of goals to which the hypothesis was added. It bears noting that the subgoals produced by induction and top-level forcing round goals are not children. For example, suppose the hint above fires on "Subgoal 3" and produces, say, "Subgoal 3'". Then the hint will not fire on "Subgoal 3'" even though it (still) contains [47m(SWAP A)[0m because "Subgoal 3'" is a child of a goal on which the hint fired. But now suppose that "Subgoal 3'" is pushed for induction. Then the goals created by that induction, i.e., the base case and induction step, are not considered children of "Subgoal 3'". All of the original hints are available. Alternatively, suppose that "Subgoal 3' is proved but forces some other subgoal, "[1]Subgoal 1" which is attacked in Forcing Round 1. That top-level forced subgoal is not a child. All the original hints are available to it. Thus, if it contains [47m(SWAP A)[0m, the hint will fire and supply the hypothesis, producing "[1]Subgoal 1'". This may be unnecessary, as the hypothesis might already be present in "[1]Subgoal 1". In this case, no harm is done. The hint won't fire on "[1]Subgoal 1'" because it is a child of "[1]Subgoal 1" and the hint fired on that.") (using-computed-hints-4 (using-computed-hints) "Computing the Hints So far we have used computed hints only to compute when a fixed set of keys and values are to be used as a hint. But computed hints can, of course, compute the set of keys and values. You might, for example, write a hint that recognizes when a [clause] ``ought'' to be provable by a [47m:BDD[0m hint and generate the appropriate hint. You might build in a set of useful lemmas and check to see if the clause is provable [47m:BY[0m one of them. You can keep all function symbols disabled and use computed hints to compute which ones you want to [47m:EXPAND[0m. In general, you can write a theorem prover for use in your hints, provided you can get it to do its job by directing our theorem prover. Suppose for example we wish to find every occurrence of an instance of [47m(SWAP x)[0m and provide the corresponding instance of [47mALL-SWAPS-HAVE-THE-PROPERTY[0m. Obviously, we must explore the clause looking for instances of [47m(SWAP x)[0m and build the appropriate instances of the lemma. We could do this in many different ways, but below we show a general purpose set of utilities for doing it. The functions are not defined in ACL2 but could be defined as shown. Our plan is: (1) Find all instances of a given pattern (term) in a clause, obtaining a set of substitutions. (2) Build a set of [47m:instance[0m expressions for a given lemma name and set of substitutions. (3) Generate a [47m:use[0m hint for those instances when instances are found. The pair of functions below find all instances of a given pattern term in either a term or a list of terms. The functions each return a list of substitutions, each substitution accounting for one of the matches of pat to a subterm. At this level in ACL2 substitutions are lists of pairs of the form [47m(var . term)[0m. All terms mentioned here are presumed to be in translated form. The functions take as their third argument a list of substitutions accumulated to date and add to it the substitutions produced by matching pat to the subterms of the term. We intend this accumulator to be nil initially. If the returned value is nil, then no instances of pat occurred. (mutual-recursion (defun find-all-instances (pat term alists) (declare (xargs :mode :program)) (mv-let (instancep alist) (one-way-unify pat term) (let ((alists (if instancep (add-to-set-equal alist alists) alists))) (cond ((variablep term) alists) ((fquotep term) alists) (t (find-all-instances-list pat (fargs term) alists)))))) (defun find-all-instances-list (pat list-of-terms alists) (declare (xargs :mode :program)) (cond ((null list-of-terms) alists) (t (find-all-instances pat (car list-of-terms) (find-all-instances-list pat (cdr list-of-terms) alists)))))) Caveat: The following aside has nothing to do with computed hints. Does an instance of [47m(CAR (CDR x))[0m occur in [47m((LAMBDA (V) (CAR V)) (CDR A))[0m? It does if one beta-reduces the lambda-expression to [47m(CAR (CDR A))[0m; the appropriate substitution is to replace [47mx[0m by [47mA[0m. But the definition of [47mfind-all-instances[0m above does [3mnot[0m find this instance because it does not do beta-reduction. We now turn our attention to converting a list of substitutions into a list of lemma instances, each of the form (:INSTANCE name (var1 term1) ... (vark termk)) as written in [47m:use[0m hints. In the code shown above, substitutions are lists of pairs of the form [47m(var . term)[0m, but in lemma instances we must write ``doublets.'' So here we show how to convert from one to the other: (defun pairs-to-doublets (alist) (declare (xargs :mode :program)) (cond ((null alist) nil) (t (cons (list (caar alist) (cdar alist)) (pairs-to-doublets (cdr alist)))))) Now we can make a list of lemma instances: (defun make-lemma-instances (name alists) (declare (xargs :mode :program)) (cond ((null alists) nil) (t (cons (list* :instance name (pairs-to-doublets (car alists))) (make-lemma-instances name (cdr alists)))))) Finally, we can package it all together into a hint function. The function takes a pattern, [47mpat[0m, which must be a translated term, the name of a lemma, [47mname[0m, and a clause. If some instances of [47mpat[0m occur in [47mclause[0m, then the corresponding instances of [47mname[0m are [47m:USE[0md in the computed hint. Otherwise, the hint does not apply. (defun add-corresponding-instances (pat name clause) (declare (xargs :mode :program)) (let ((alists (find-all-instances-list pat clause nil))) (cond ((null alists) nil) (t (list :use (make-lemma-instances name alists)))))) The design of this particular hint function makes it important that the variables of the pattern be the variables of the named lemma and that all of the variables we wish to instantiate occur in the pattern. We could, of course, redesign it to allow ``free variables'' or some sort of renaming. We could now use this hint as shown below: (defthm ... ... :hints ((add-corresponding-instances '(SWAP x) 'ALL-SWAPS-HAVE-THE-PROPERTY clause))) The effect of the hint above is that any time a clause arises in which any instance of [47m(SWAP x)[0m appears, we add the corresponding instance of [47mALL-SWAPS-HAVE-THE-PROPERTY[0m. So for example, if Subgoal *1/3.5 contains the subterm [47m(SWAP (SWAP A))[0m then this hint fires and makes the system behave as though the hint: ("Subgoal *1/3.5" :USE ((:INSTANCE ALL-SWAPS-HAVE-THE-PROPERTY (X A)) (:INSTANCE ALL-SWAPS-HAVE-THE-PROPERTY (X (SWAP A))))) had been present.") (using-computed-hints-5 (using-computed-hints) "Debugging Computed Hints We have found that it is sometimes helpful to define hints so that they print out messages to the terminal when they fire, so you can see what hint was generated and which of your computed hints did it. To that end we have defined a macro we sometimes use. Suppose you have a [47m:hints[0m specification such as: :hints (computed-hint-fn (hint-expr id)) If you defmacro the macro below you could then write instead: :hints ((show-hint computed-hint-fn 1) (show-hint (hint-expr id) 2)) with the effect that whenever either hint is fired (i.e., returns non-[47mnil[0m), a message identifying the hint by the marker (1 or 2, above) and the non-[47mnil[0m value is printed. (defmacro show-hint (hint &optional marker) (cond ((and (consp hint) (stringp (car hint))) hint) (t `(let ((marker ,marker) (ans ,(if (symbolp hint) `(,hint id clause world stable-under-simplificationp) hint))) (if ans (prog2$ (cw "~%***** Computed Hint~#0~[~/ (from hint ~x1)~]~%~x2~%~%" (if (null marker) 0 1) marker (cons (string-for-tilde-@-clause-id-phrase id) ans)) ans) nil))))) Note that when [47mshow-hint[0m is applied to a hint that is a symbol, e.g., [47mcomputed-hint-fn[0m, it applies the symbol to the four computed-hint arguments: [47mid[0m, [47mclause[0m, [47mworld[0m, and [47mstable-under-simplificationp[0m. If [47mcomputed-hint-fn[0m is of arity 3 the code above would cause an error. One way to avoid it is to write :hints ((show-hints (computed-hint-fn id clause world) 1) (show-hint (hint-expr id) 2)). If you only use computed hints of arity 3, you might eliminate the occurrence of [47mstable-under-simplificationp[0m in the definition of [47mshow-hint[0m above. Putting a [47mshow-hint[0m around a common hint has no effect. If you find yourself using this utility let us know and we'll consider putting it into the system itself. But it does illustrate that you can use computed hints to do unusual things.") (using-computed-hints-6 (using-computed-hints) "Using the computed-hint-replacement feature So far none of our computed hints have used the [47m:COMPUTED-HINT-REPLACEMENT[0m feature. We now illustrate that. The [47m:computed-hint-replacement[0m feature can easily lead to loops. So as you experiment with the examples in this section and your own hints using this feature, be ready to interrupt the theorem prover and abort! A non-looping use of the [47m:computed-hint-replacement[0m feature would be a hint like this: (if (certain-terms-present clause) '(:computed-hint-replacement t :in-theory (enable lemma25)) '(:computed-hint-replacement t :in-theory (disable lemma25))) In this hint, if certain terms are present in [47mclause[0m, as determined by the function with the obvious name (here undefined), then this hint enables [47mlemma25[0m and otherwise disables it. [47mLemma25[0m might be a very expensive lemma, e.g., one that matches frequently and has an expensive and rarely established hypothesis. One might wish it enabled only under certain conditions. Recall that theories are inherited by children. So once [47mlemma25[0m is enabled it ``stays'' enabled for the children, until disabled; and vice versa. If the [47m:computed-hint-replacement[0m feature were not present and computed hints were always deleted after they had been used, then [47mlemma25[0m would be left enabled (or disabled) for all the children produced by the first firing of the hint. But with the arrangement here, every subgoal gets a theory deemed suitable by the hint, and the hint persists. Now we will set up a toy to allow us to play with computed hints to understand them more deeply. To follow the discussion it is best to execute the following events. (defstub wrapper (x) t) (defaxiom wrapper-axiom (wrapper x) :rule-classes nil) Now submit the following event and watch what happens. (thm (equal u v) :hints (`(:use (:instance wrapper-axiom (x a))))) The theorem prover adds [47m(wrapper a)[0m to the goal and then abandons the proof attempt because it cannot prove the subgoal. Since the computed hint is deleted upon use, the hint is not applied to the subgoal (i.e., the child of the goal). What happens if we do the following? (thm (equal u v) :hints (`(:computed-hint-replacement t :use (:instance wrapper-axiom (x a))))) As one might expect, this loops forever: The hint is applied to the child and adds the hypothesis again. When the hint fires, nothing is actually changed, since [47m(wrapper a)[0m is already in the subgoal. So let's change the experiment a little. Let's make the hint add the hypothesis [47m(wrapper p)[0m where [47mp[0m is the first literal of the [clause]. This is silly but it allows us to explore the behavior of computed hints a little more. (thm (equal u v) :hints (`(:use (:instance wrapper-axiom (x ,(car clause)))))) So in this case, the theorem prover changes the goal to (IMPLIES (WRAPPER (EQUAL U V)) (EQUAL U V)) which then simplifies to (IMPLIES (WRAPPER NIL) (EQUAL U V)) because the concluding equality can be assumed false in the hypothesis (e.g., think of the contrapositive version). Nothing else happens because the hint has been removed and so is not applicable to the child. Now consider the following --- and be ready to interrupt it and abort! (thm (equal u v) :hints (`(:computed-hint-replacement t :use (:instance wrapper-axiom (x ,(car clause)))))) This time the hint is not removed and so is applied to the child. So from [47mGoal[0m we get Goal' (IMPLIES (WRAPPER (EQUAL U V)) (EQUAL U V)) and then Goal'' (IMPLIES (AND (WRAPPER (NOT (WRAPPER (EQUAL U V)))) (WRAPPER (EQUAL U V))) (EQUAL U V)) etc. First, note that the hint is repeatedly applied to its children. That is because we wrote [47m:computed-hint-replacement t[0m. But second, note that [47mGoal'[0m is not even being simplified before [47mGoal''[0m is produced from it. If it were being simplified, the [47m(equal u v)[0m's in the hypotheses would be replaced by [47mnil[0m. This is a feature. It means after a computed hint has fired, other hints are given a chance at the result, even the hint itself unless it is removed from the list of hints. As an exercise, let's arrange for the hint to stay around and be applied indefinitely but with a simplification between each use of the hint. To do this we need to pass information from one application of the hint to the next, essentially to say ``stay around but don't fire.'' First, we will define a function to use in the hint. This is more than a mere convenience; it allows the hint to ``reproduce itself'' in the replacement. (defun wrapper-challenge (clause parity) (if parity `(:computed-hint-replacement ((wrapper-challenge clause nil)) :use (:instance wrapper-axiom (x ,(car clause)))) `(:computed-hint-replacement ((wrapper-challenge clause t))))) Note that this function is not recursive, even though it uses its own name. That is because the occurrence of its name is in a quoted constant. Now consider the following. What will it do? (thm (equal u v) :hints ((wrapper-challenge clause t))) First, observe that this is a legal hint because it is a term that mentions only the free variable [47mCLAUSE[0m. When defining hint functions you may sometimes think their only arguments are the four variables [47mid[0m, [47mclause[0m, [47mworld[0m, and [47mstable-under-simplificationp[0m. That is not so. But in your hints you must call those functions so that those are the only free variables. Note also that the occurrence of [47mclause[0m inside the [47m:computed-hint-replacement[0m is not an occurrence of the variable clause but just a constant. Just store this note away for a moment. We'll return to it momentarily. Second, the basic cleverness of this hint is that every time it fires it reproduces itself with the opposite parity. When the parity is [47mt[0m it actually changes the goal by adding a hypothesis. When the parity is [47mnil[0m it doesn't change the goal and so allows simplification to proceed --- but it swaps the parity back to [47mt[0m. What you can see with this simple toy is that we can use the computed hints to pass information from parent to child. Ok, so what happens when the event above is executed? Try it. You will see that ACL2 applied the hint the first time. It doesn't get around to printing the output because an error is caused before it can print. But here is a blow-by-blow description of what happens. The hint is evaluated on [47mGoal[0m with the [47mclause[0m [47m((equal u v))[0m. It produces a hint exactly as though we had typed: ("Goal" :use (:instance wrapper-axiom (x (equal u v)))) which is applied to this goal. In addition, it produces the new hints argument :hints ((wrapper-challenge clause nil)). By applying the [47m"Goal"[0m hint we get the new subgoal Goal' (implies (wrapper (equal u v)) (equal u v)) but this is not printed because, before printing it, the theorem prover looks for hints to apply to it and finds (wrapper-challenge clause nil) That is evaluated and produces a hint exactly as though we had typed: ("Goal'" ) and the new hints argument: :hints ((wrapper-challenge clause nil)). But if you supply the hint [47m("Goal'" )[0m, ACL2 will signal an error because it does not allow you to specify an empty hint! So the definition of [47mwrapper-challenge[0m above is almost correct but fatally flawed. We need a non-empty ``no-op'' hint. One such hint is to tell the system to expand a term that will always be expanded anyway. So undo [47mwrapper-challenge[0m, redefine it, and try the proof again. Now remember the observation about [47mclause[0m that we asked you to ``store'' above. The new definition of [47mwrapper-challenge[0m illustrates what we meant. Note that the first formal parameter of [47mwrapper-challenge[0m, below, is no longer named [47mclause[0m but is called [47mcl[0m instead. But the ``call'' of [47mwrapper-challenge[0m in the replacements is on [47mclause[0m. This may seem to violate the rule that a function definition cannot use variables other than the formals. But the occurrences of [47mclause[0m below are not variables but constants in an object that will eventually be treated as a hint term. :ubt wrapper-challenge (defun wrapper-challenge (cl parity) (if parity `(:computed-hint-replacement ((wrapper-challenge clause nil)) :use (:instance wrapper-axiom (x ,(car cl)))) `(:computed-hint-replacement ((wrapper-challenge clause t)) :expand ((atom zzz))))) (thm (equal u v) :hints ((wrapper-challenge clause t))) This time, things go as you might have expected! [47mGoal'[0m is produced and simplified, to Goal'' (implies (wrapper nil) (equal u v)). Simplification gets a chance because when the new hint [47m(wrapper-challenge clause nil)[0m is fired it does not change the goal. But it does change the parity in the hints argument so that before [47mGoal''[0m is simplified again, the hint fires and adds the hypothesis: Goal''' (IMPLIES (AND (WRAPPER (NOT (WRAPPER NIL))) (WRAPPER NIL)) (EQUAL U V)). This simplifies, replacing the first [47m(NOT (WRAPPER NIL))[0m by [47mNIL[0m, since [47m(WRAPPER NIL)[0m is known to be true here. Thus the goal simplifies to Goal'4' (IMPLIES (WRAPPER NIL) (EQUAL U V)). The process repeats indefinitely. So we succeeded in getting a hint to fire indefinitely but allow a full simplification between rounds.") (using-computed-hints-7 (using-computed-hints) "Using the [47mstable-under-simplificationp[0m flag A problem with the example in [using-computed-hints-6] is that exactly one simplification occurs between each (effective) firing of the hint. Much more commonly we wish to fire a hint once a subgoal has become stable under simplification. A classic example of this is when we are dealing with an interpreter for some state machine. We typically do not want the ``step'' function to open up on the symbolic representation of a state until that state has been maximally simplified. We will illustrate with a simple state machine. Let us start by defining the step function, [47mstp[0m, and the corresponding [47mrun[0m function that applies it a given number of times. (defun stp (s) (+ 1 s)) (defun run (s n) (if (zp n) s (run (stp s) (- n 1)))) The step function here is trivial: a state is just a number and the step function increments it. In this example we will not be interested in the theorems we prove but in how we prove them. The formula we will focus on is (thm (equal (run s 7) xxx)) This is not a theorem, of course. But we want to test our advice on non-theorems because we do not want the advice to work only for proofs that succeed. (In the past, we gave advice about using computed hints and that advice caused the theorem prover to run forever when given formulas that it couldn't prove --- but most of the time the system is presented with formulas it cannot prove!) Furthermore, without some kind of additional rules, the [47m(run s 7)[0m expression in the conjecture above will not expand at all, because ACL2's heuristics do not approve. In fact, we do not want to take chances that [47mrun[0m will be expanded --- we want to control its expansion completely. Therefore, disable [47mrun[0m. (in-theory (disable run)) Now, what do we want? (That is always a good question to ask!) We want [47m(run s 7)[0m to expand ``slowly.'' In particular, we want it to expand once, to [47m(run (stp s) 6)[0m. Then we want the [47mstp[0m to be expanded and fully simplified before the [47mrun[0m expression is expanded again. That is, we want to force the expansion of [47mrun[0m whenever the goal is stable under simplification. This is sometimes called ``staged simplification.'' We can achieve staged simplification for any given function symbol by defining the functions shown below and then using a simple computed hint: (thm (equal (run s 7) xxx) :hints ((stage run))) By inspecting how [47mstage[0m is defined you can see how to extend it, but we explain as we go. To experiment, you can just paste the definitions (and defmacro) below into your ACL2 shell and then try the [47mthm[0m command. First, define this pair of mutually recursive functions. [47mFind-first-call[0m finds the first call of the function symbol [47mfn[0m in a given term. (mutual-recursion (defun find-first-call (fn term) ; Find the first call of fn in term. (cond ((variablep term) nil) ((fquotep term) nil) ((equal (ffn-symb term) fn) term) (t (find-first-call-lst fn (fargs term))))) (defun find-first-call-lst (fn lst) ; Find the first call of fn in a list of terms. (cond ((endp lst) nil) (t (or (find-first-call fn (car lst)) (find-first-call-lst fn (cdr lst))))))) We will arrange for the computed hint to generate an [47m:EXPAND[0m hint for the first call of [47mfn[0m, whenever the goal becomes stable under simplification. If no call is found, the hint will do nothing. To make sure the hint will not loop indefinitely (for example, by forcing [47mfn[0m to expand only to have the rewriter ``fold'' it back up again), we will provide the hint with a bound that stops it after some number of iterations. Here is the basic function that creates the [47mexpand[0m hint and replaces itself to count down. (defun stage1 (fn max clause flg) ; If the clause is stable under simplification and there is a call of ; fn in it, expand it. But don't do it more than max times. (let ((temp (and flg (find-first-call-lst fn clause)))) (if temp (if (zp max) (cw "~%~%HINT PROBLEM: The maximum repetition count of ~ your STAGE hint has been reached without eliminating ~ all of the calls of ~x0. You could supply a larger ~ count with the optional second argument to STAGE ~ (which defaults to 100). But think about what is ~ happening! Is each stage permanently eliminating a ~ call of ~x0?~%~%" fn) `(:computed-hint-replacement ((stage1 ',fn ,(- max 1) clause stable-under-simplificationp)) :expand (,temp))) nil))) Suppose that when [47mstage1[0m is called, [47mfn[0m is the function we want to expand, [47mmax[0m is the maximum number of iterations of this expansion, [47mclause[0m is the current goal [clause], and [47mflg[0m is the value of the [47mstable-under-simplificationp[0m flag. Then if [47mclause[0m is stable and we can find a call of [47mfn[0m in it, we ask whether [47mmax[0m is exhausted. If so, we print an ``error message'' to the comment window with [47m[cw][0m and return [47mnil[0m (the value of [47mcw[0m). That [47mnil[0m means the hint does nothing. But if [47mmax[0m is not yet exhausted, we return a new hint. As you can see above, the hint replaces itself with another [47mstage1[0m hint with the same [47mfn[0m and a decremented [47mmax[0m to be applied to the new [47mclause[0m and the then-current value of [47mstable-under-simplificationp[0m. The hint also contains an [47m:expand[0m directive for the call of [47mfn[0m found. Thus, if the computed hint was: (stage1 'run 5 clause stable-under-simplificationp) and [47m(run s 7)[0m occurs in the clause, then it will generate (:computed-hint-replacement ((stage1 'run 4 clause stable-under-simplificationp)) :expand ((run s 7))) which will in turn replace the old [47mstage1[0m hint with the new one and will apply [47m:expand ((run s 7))[0m to the current goal. We can make this more convenient by defining the macro: (defmacro stage (fn &optional (max '100)) `(stage1 ',fn ,max clause stable-under-simplificationp)) Note that the macro allows us to either provide the maximum bound or let it default to 100. Henceforth, we can type (thm (equal (run s 7) xxx) :hints ((stage run))) to stage the opening of [47mrun[0m up to 100 times, or we can write (thm (equal (run s 7) xxx) :hints ((stage run 5))) to stage it only 5 times. In the latter example, the system will print an ``error message'' after the fifth expansion. Note that if we executed (set-default-hints '((stage run))) then we could attack all theorems (involving [47mrun[0m) with staged simplification (up to bound 100), without typing an explicit hint. (thm (equal (run s 7) xxx)) Using techniques similar to those above we have implemented ``priority phased simplification'' and provided it as a book. See community book [47mbooks/misc/priorities.lisp[0m. This is an idea suggested by Pete Manolios, by which priorities may be assigned to rules and then the simplifier simplifies each subgoal maximally under the rules of a given priority before enabling the rules of the next priority level. The book above documents both how we implement it with computed hints and how to use it. Here is another example of using the [47mstable-under-simplificationp[0m flag to delay certain actions. It defines a default hint, see [default-hints], which will enable [non-linear-arithmetic] on precisely those goals which are stable-under-simplificationp. It also uses the [47mHISTORY[0m and [47mPSPV[0m variables to determine when toggling [non-linear-arithmetic] is appropriate. These variables are documented only in the source code. If you start using these variables extensively, please contact the developers of ACL2 or Robert Krug ([47mrkrug@cs.utexas.edu[0m) and let us know how we can help. (defun nonlinearp-default-hint (stable-under-simplificationp hist pspv) (cond (stable-under-simplificationp (if (not (access rewrite-constant (access prove-spec-var pspv :rewrite-constant) :nonlinearp)) '(:computed-hint-replacement t :nonlinearp t) nil)) ((access rewrite-constant (access prove-spec-var pspv :rewrite-constant) :nonlinearp) (if (not (equal (caar hist) 'SETTLED-DOWN-CLAUSE)) '(:computed-hint-replacement t :nonlinearp nil) nil)) (t nil)))") (using-computed-hints-8 (using-computed-hints) "Some Final Comments None of the examples show the use of the variable [47mWORLD[0m, which is allowed in computed hints. There are some (undocumented) ACL2 utilities that might be useful in programming hints, but these utilities need access to the ACL2 logical world (see [world]). A very useful fact to know is that [47m(table-alist name world)[0m returns an alist representation of the current value of the [47m[table][0m named [47mname[0m. The ACL2 source code is littered with [47m:[0m[47m[program][0m mode functions for manipulating world. In our source code, the world is usually bound a variable named [47mwrld[0m; so searching our code for that name might be helpful. Using these utilities to look at the [47mWORLD[0m one can, for example, determine whether a symbol is defined recursively or not, get the body and formals of a defined function, or fetch the statement of a given lemma. Because these utilities are not yet documented, we do not expect users to employ [47mWORLD[0m in computed hints. But experts might and it might lead to the formulation of a more convenient language for computed hints. None of our examples illustrated the 7 argument form of a computed hint, [47m(fn ID CLAUSE WORLD STABLE-UNDER-SIMPLIFICATIONP HIST PSPV CTX)[0m. When used, the variables [47mHIST[0m, [47mPSPV[0m, and [47mCTX[0m, are bound to the [clause] history, the package of ``special variables'' governing the clause, and the ``error message context.'' These variables are commonly used throughout our source code but are, unfortunately, undocumented. Again, we expect a few experts will find them useful in developing computed hints. If you start using computed hints extensively, please contact the developers of ACL2 and let us know what you are doing with them and how we can help.") (using-enabled-rules (theories) "Avoiding [47m:use[0m [hints] for [enable]d [47m:[0m[47m[rewrite][0m rules Consider the following (admittedly silly) example. (thm (equal (append (append x y) z) (append x y z)) :hints (("Subgoal *1/1" :use cdr-cons))) ACL2's output includes the following warning. ACL2 Warning [Use] in ( THM ...): It is unusual to :USE the formula of an enabled :REWRITE or :DEFINITION rule, so you may want to consider disabling (:REWRITE CDR-CONS) in the hint provided for Subgoal *1/1. See :DOC using-enabled-rules. The warning is saying that if you leave the rewrite rule enabled, ACL2 may simplify away the hypothesis added by the [47m:use[0m hint. We now explain this danger in more detail and show how disabling the rule can solve this problem. Recall (see [hints]) how [47m:use[0m [hints] work. Such a hint specifies a formula, [47mF[0m, which is based on an existing lemma. Then the indicated goal, [47mG[0m, is replaced by the implication [47m(implies F G)[0m. The intention is that the truth of [47mF[0m will help in the simplification of [47mG[0m to [47mT[0m (true). The ``[Use]'' warning shown above is telling us of the danger that [47mF[0m may be rewritten to [47mT[0m, reducing the implication above to [47m(implies T G)[0m --- thus, sadly, [47mF[0m has disappeared and is not available to help with the simplification of [47mG[0m. Consider the following tiny example. (defun p (x) (cons x x)) (defthm car-p (equal (car (p x)) x)) (in-theory (disable p (:type-prescription p))) (thm (implies (equal (p x1) (p x2)) (equal x1 x2)) :hints (("Goal" :use ((:instance car-p (x x1)) (:instance car-p (x x2)))))) The proof of the final [47m[thm][0m form fails, because the new hypotheses are rewritten to [47mt[0m using the [47m:[0m[47m[rewrite][0m rule [47mCAR-P[0m, in the manner described above. The following proof log shows the new hypotheses and their disappearance via rewriting. We augment the goal with the hypotheses provided by the :USE hint. These hypotheses can be derived from CAR-P via instantiation. We are left with the following subgoal. Goal' (IMPLIES (AND (EQUAL (CAR (P X1)) X1) (EQUAL (CAR (P X2)) X2)) (IMPLIES (EQUAL (P X1) (P X2)) (EQUAL X1 X2))). By the simple :rewrite rule CAR-P we reduce the conjecture to Goal'' (IMPLIES (EQUAL (P X1) (P X2)) (EQUAL X1 X2)). When we disable the rule [47mCAR-P[0m as follows, the proof succeeds. (thm (implies (equal (p x1) (p x2)) (equal x1 x2)) :hints (("Goal" :use ((:instance car-p (x x1)) (:instance car-p (x x2))) :in-theory (disable car-p)))) In general, then, a solution is to disable the rewrite rule that you are supplying in a [47m:use[0m hint.") (using-tables-efficiently (table) "Notes on how to use tables efficiently (Thanks to Jared Davis for contributing this [documentation] topic, to which we have made only minor modifications.) Suppose your book contains [47m[table][0m [events], or macros that expand into [47mtable[0m events, of the following form: (table my-table 'my-field <computation>) Then [47m<computation>[0m will be evaluated [3mtwice[0m during [47m[certify-book][0m and [3magain[0m every time you include the book with [47m[include-book][0m. In some cases this overhead can be avoided using [47m[make-event][0m. See also [defconsts] for an analogous trick involving [47m[defconst][0m. As an example, suppose we want to store numbers in a table only if they satisfy some computationally expensive predicate. We'll introduce a new book, [47mnumber-table.lisp[0m, and create a table to store these numbers: (table number-table 'data nil) Instead of implementing a ``computationally expensive predicate,'' we'll write a function that just prints a message when it is called and accepts even numbers: (defun expensive-computation (n) (prog2$ (cw "Expensive computation on ~x0.~%" n) (evenp n))) Now we'll implement a macro, [47madd-number[0m, which will add its argument to the table only if it satisfies the expensive predicate: (defmacro add-number (n) `(table number-table 'data (let ((current-data (cdr (assoc-eq 'data (table-alist 'number-table world))))) (if (expensive-computation ,n) (cons ,n current-data) current-data)))) Finally, we'll call [47madd-number[0m a few times to finish the book. (add-number 1) (add-number 2) (add-number 3) When we now invoke [47m(certify-book "number-table")[0m, we see the expensive predicate being called twice for each number: once in Step 2, the main pass, then again in Step 3, the admissibility check. Worse, the computation is performed again for each number when we use [47m[include-book][0m to load [47mnumber-table[0m, e.g., ACL2 !>(include-book "number-table") Expensive computation on 1. Expensive computation on 2. Expensive computation on 3. To avoid these repeated executions, we can pull the test out of the [47mtable[0m event using [47m[make-event][0m. Here's an alternate implementation of [47madd-number[0m that won't repeat the computation: (defmacro add-number (n) `(make-event (if (expensive-computation ,n) '(table number-table 'data (cons ,n (cdr (assoc 'data (table-alist 'number-table world))))) '(value-triple :expensive-computation-failed)))) When we recertify [47mnumber-table.lisp[0m, we'll see the expensive computation is still called once for each number in Step 2, but is no longer called during Step 3. Similarly, the [47m[include-book][0m no longer shows any calls of the expensive computation.") (using_the_associativity_of_app_to_prove_a_trivial_consequence (pages_written_especially_for_the_tours) "Using the Associativity of App to Prove a Trivial Consequence {IMAGE} (see [Overview_of_the_Proof_of_a_Trivial_Consequence]) If we have proved the [47massociativity-of-app[0m rule, then the following theorem is trivial: (defthm trivial-consequence (equal (app (app (app (app x1 x2) (app x3 x4)) (app x5 x6)) x7) (app x1 (app (app x2 x3) (app (app x4 x5) (app x6 x7)))))) Below we show the proof {IMAGE} (see [Overview_of_the_Proof_of_a_Trivial_Consequence])") (value (pointers) "See [system-utilities].") (value-cmp (pointers) "See [context-message-pair].") (value-triple (events acl2-built-ins errors) "Compute a value, optionally checking that it is not [47mnil[0m Simple Example ; Return the value 7 as an error triple, i.e., (mv nil 7 state)). (value-triple (+ 3 4)) Examples Involving Keyword Arguments ; Print "hi" even when skipping proofs. (value-triple (cw "hi") :on-skip-proofs t) ; Return an error triple containing the value of a state global. ; (This shows that it's OK to reference state.) (value-triple (@ ld-pre-eval-print)) ; Check that the given form returns a non-nil value. (value-triple (equal (+ 3 4) 7) :check t) ; Check that the given defun is admissible, then revert the world. (value-triple (er-progn (defun foo (x) (cons x x)) (value :success)) :stobjs-out :auto) General Form (value-triple form :check chk ; default nil :ctx ; default 'value-triple :on-skip-proofs sp ; default nil :safe-mode safe-mode ; default :same :stobjs-out stobjs-out ; default nil ) where all keyword arguments are evaluated and optional, and the defaults shown above represent values after evaluation. The following example illustrates all of the keyword arguments, which are documented below. (value-triple (mv nil (equal (+ 3 4) 7) state) :check (msg "Oops, I forgot what ~x0+~x1 is!" 3 4) :ctx '(value-triple . <some-mv>) :on-skip-proofs t :safe-mode nil ; legacy behavior (rarely used) :stobjs-out '(nil nil state)) Description [47mValue-triple[0m provides a convenient way to evaluate a form in a context where an [event] is expected; thus, a call of [47mvalue-triple[0m may occur in [47m[progn][0m and [47m[encapsulate][0m forms and in [books]. By default, the form should evaluate to a single, non-[stobj] value (but see the discussion below about the [47m:STOBJS-OUT[0m keyword argument). Calls of [47mvalue-triple[0m are skipped by default when proofs are being skipped (but see the discussion below about the [47m:ON-SKIP-PROOFS[0m keyword argument). By default, a [47mvalue-triple[0m call has no effect other than to evaluate its form, but see the discussion of the [47m:CHECK[0m keyword below for how to check the result. A call of [47mvalue-triple[0m returns an [error-triple], [47m(mv erp val state)[0m. By default or when [47m:CHECK nil[0m is supplied: [47merp[0m is [47mnil[0m when evaluation completes without error and [47mval[0m is the value returned by evaluating the given form. However, when the keyword argument [47m:CHECK[0m has a non-[47mnil[0m value, there is a check that [47mval[0m is non-[47mnil[0m. Note that the value of keyword argument [47m:STOBJS-OUT[0m can affect this notion of ``the value returned'' (by evaluation), as discussed below. Keyword Arguments Here is documentation for the keyword arguments, arranged alphabetically and followed by relevant remarks. [47m:CHECK chk[0m (default: [47mnil[0m) When [47mchk[0m is supplied and non-[47mnil[0m, the value returned by evaluating the given form must be non-[47mnil[0m, or else an error occurs: The error message is generic if [47mchk[0m is [47mt[0m. (By default a single value is returned, so the notion of ``the value returned'' is clear; but see the discussion of [47m:STOBJS-OUT[0m below for the notion of ``the value returned'' in the general case.) If [47mchk[0m is supplied and is neither [47mt[0m nor [47mnil[0m, then it should be a ``message'' (see [msg]) that is used when printing the error message. [47m:CTX ctx[0m (default: [47m'value-triple[0m) Error messages from [47mvalue-triple[0m start, by default, with ``ACL2 Error in VALUE-TRIPLE''. To replace [47mVALUE-TRIPLE[0m with a different context (see [ctx]), [47mctx[0m, supply keyword argument [47m:CTX ctx[0m. [47m:ON-SKIP-PROOFS sp[0m (default: [47mnil[0m) By default or when [47m:ON-SKIP-PROOFS[0m has value [47mnil[0m, the form is not evaluated when proofs are being skipped. The form is, however, evaluated when [47m:ON-SKIP-PROOFS t[0m is supplied. The other legal value for [47m:ON-SKIP-PROOFS[0m is [47m:interactive[0m, which is more restrictive than [47mt[0m. [47m:Interactive[0m directs the [47mvalue-triple[0m call to be skipped when executing an [47m[include-book][0m or making a second pass through an [47m[encapsulate][0m, but not merely because [47m(set-ld-skip-proofsp t state)[0m has been executed. [47m:SAFE-MODE safe-mode[0m (default: [47m:same[0m) It is usually safe to ignore this option, which is available for backward compatibility: [47m:SAFE-MODE t[0m gives the behavior of [47massert-event[0m from before April, 2021. Normally ACL2 operates without so-called ``safe-mode''; see [safe-mode]. The value [47m:same[0m prevents any change in whether safe-mode is on or off; otherwise the value is [47mt[0m to evaluate the form with safe-mode on and [47mnil[0m for safe-mode off. [47m:STOBJS-OUT stobjs-out[0m (default: [47mnil[0m) When [47mstobjs-out[0m has its default value of [47mnil[0m, which abbreviates the value [47m(nil)[0m, the form supplied to [47mvalue-triple[0m is expected to evaluate to a single value that is neither a [stobj] nor a [df]. However, [multiple-value] return is also allowed, including stobjs (user-defined stobjs as well as [47mstate[0m). The return shape is specified by supplying [47mstobjs-out[0m as a true list corresponding to the values returned, with stobj names in stobj positions and, [47m:DF[0m in df positions, and [47mnil[0m elsewhere. (The list has length one if a single value is returned.) For example, if [47mstobjs-out[0m is [47m(nil st1 nil st2)[0m then the form should evaluate to a [multiple-value] return, with ordinary values in (zero-based) positions 0 and 2, stobj [47mst1[0m in position 1, and stobj [47mst2[0m in position 3. [47mStobjs-out[0m may also be [47m:auto[0m, which allows arbitrary returns. We speak of ``the value returned''. When the evaluation results in a single value, that is of course the value returned. When multiple values are returned, the first of those values is normally what we mean by ``the value returned'', with the following exception. When an [error-triple] is returned --- say [47m(mv erp val state)[0m where [47merp[0m is an ordinary value, [47mval[0m is a non-[stobj] value, and [47mstate[0m is the ACL2 [state] --- then [47mval[0m is considered to be the value returned if [47merp[0m is [47mnil[0m; but if [47merp[0m is not [47mnil[0m, then there is no value returned, and [47mvalue-triple[0m results in an error. If [47m:CHECK[0m has a non-[47mnil[0m value then the value returned must not be a stobj. Otherwise, when the value returned is a stobj it is replaced by the stobj's name, as discussed below. Remarks We conclude by remarking on some details. These remarks also apply to [assert-event], since it expands to make corresponding calls of [47mvalue-triple[0m. 1. Since [47mvalue-triple[0m is an [event] macro, it returns an [error-triple], that is, the multiple values [47m(mv erp val state)[0m, where [47merp[0m is [47mnil[0m exactly when the event completes without error. If the value of keyword argument [47m:CHECK[0m is non-[47mnil[0m and [47merp[0m is [47mnil[0m, then [47mval[0m is [47m:passed[0m. Otherwise [47mval[0m is the value returned as discussed above. To be precise: [47mval[0m is the result of evaluating the given form in the default case, when [47m:STOBJS-OUT[0m is not provided (or is [47mnil[0m or [47m(nil)[0m), but in general there several cases possible, as follows. * If the evaluation of the given form results in a single ordinary value, then [47mval[0m is that value. * If the evaluation of the given form results in a single stobj value, then [47mval[0m is that stobj's name (a symbol). In particular, if the value is state, then [47mval[0m is the symbol [47mSTATE[0m (in the [47m"ACL2"[0m package). * If the evaluation of the given form results in a single [df] value, then [47mval[0m is the corresponding rational number. * If the evaluation of the given form results in multiple values [47m(mv x1 ...)[0m, then [47mval[0m is [47mx1[0m if [47mx1[0m is not a stobj (but converted to a rational if [47mx1[0m is a [df]), else [47mval[0m is the name of that stobj. 2. When [47m:STOBJS-OUT[0m is [47m:auto[0m and at least one user-defined [stobj] is returned, you will see a [47m"User-stobjs-modified"[0m warning unless warnings have been suppressed. Although warnings are typically suppressed by general utilities such as [47m[set-inhibit-output-lst][0m, [47m[set-inhibit-warnings][0m, and [47m[with-output][0m, a more direct way to avoid this warning is to specify [47m:STOBJS-OUT[0m as a list (as discussed above). 3. As noted above, the ACL2 [state] may change when keyword option [47m:STOBJS-OUT[0m has a value other than [47mnil[0m or [47m(nil)[0m. Nevertheless, ACL2 ensures that certain parts of the state, including the logical [world], are the same after the [47mvalue-triple[0m call completes as they were before (as with [47mmake-event[0m expansion; see [make-event]). Also, trust tags (see [defttag]) must not be introduced during such evaluation. 4. (Ignore this remark unless you make many, many calls of [47mvalue-triple[0m.) Evaluation may be much faster when [47m:STOBJS-OUT[0m is omitted or is specified as [47mnil[0m (the default) or [47m(nil)[0m. That is because otherwise, since the return shape is checked only after evaluation completes, therefore a somewhat complex environment set-up is performed prior to evaluation, in which certain parts of the ACL2 [state] are protected as for [47m[make-event][0m (using [47m[revert-world][0m, and also as discussed in the documentation for [47m[make-event][0m about [47m*protected-system-state-globals*[0m). Moreover, evaluation is faster still if in addition, the given form is [47mt[0m, [47mnil[0m, a [keyword], or of the form [47m(QUOTE x)[0m.") (variablep (pointers) "See [system-utilities].") (verbose-pstack (pstack) "Seeing what the prover is up to (for system hackers) NOTE: This utility is a low-level debugging utility, which may not be useful except to those familiar with ACL2 source code. General Forms: (verbose-pstack t) ; get trace-like information on prover during proofs (verbose-pstack '(fn1 fn2 ...)) ; as above, but omit calls of the indicated functions (verbose-pstack nil) ; turn off trace-like information on prover For example, (verbose-pstack '(ev-fncall)) will provide a trace of various prover functions during proofs, except for the function [47mev-fncall[0m. By evaluating [47m(verbose-pstack t)[0m one can get trace-like information during subsequent proofs about prover functions, including time summaries, printed to the screen during a proof. To turn off this feature, evaluate [47m(verbose-pstack nil)[0m. Also see [pstack].") (verify (proof-builder) "Enter the interactive proof-builder For proof-builder command summaries, see [proof-builder]. Examples: (VERIFY (implies (and (true-listp x) (true-listp y)) (equal (append (append x y) z) (append x (append y z))))) -- Attempt to prove the given term interactively. (VERIFY (p x) :event-name p-always-holds :rule-classes (:rewrite :generalize) :instructions ((rewrite p-always-holds-lemma) change-goal)) -- Attempt to prove (p x), where the intention is to call the resulting DEFTHM event by the name p-always-holds, with rule-classes as indicated. The two indicated instructions will be run immediately to start the proof. (VERIFY) -- Re-enter the interactive proof-builder in the state at which it was most recently left. General Form: (VERIFY &OPTIONAL raw-term &KEY event-name rule-classes instructions) [47mVerify[0m is the function used for entering the interactive [proof-builder]'s read-eval-print loop. Note that you can use [47mverify[0m to create an event, by using the [47mexit[0m command (see [ACL2-pc::exit]). For example, after evaluating (verify (equal y y) :instructions (s (exit foo nil t))) we can see that the expected event was successfully created: ACL2 !>:pe foo 1:x(VERIFY (EQUAL Y Y) :INSTRUCTIONS ...) > (DEFTHM FOO (EQUAL Y Y) :RULE-CLASSES NIL :INSTRUCTIONS (:S)) ACL2 !> That said, it's probably not a good idea to save [events] with [47m:instructions[0m. There are at least two general reasons to avoid [47m:instructions[0m: (1) to encourage the development of [rewrite] rules and other ways to help with later proofs, and (2) to make the proofs less brittle, that is, more likely to survive when there are small changes to earlier events.") (verify-guard-implication (memoize guard-formula-utilities) "[Guard] implication for [47m[memoize][0m keyword [47m:invoke[0m Examples: (verify-guard-implication f g) (verify-guard-implication f g :hints (("Goal" :in-theory (enable nth)))) General Form: (verify-guard-implication fn1 fn2 &key hints otf-flg) where none of the arguments is evaluated. This macro creates a [47m[defthm][0m event with [47m:[0m[47m[rule-classes][0m [47mnil[0m, using [47m:hints[0m and [47m:otf-flg[0m if provided. The formula of that event is generally an implication formed from the guards of the two functions, but might be [47mT[0m, as we now describe. Let [47mguard-fn1[0m be the [guard] for [47mfn1[0m, and let [47mguard-fn2[0m be the result of substituting the formals of [47mfn1[0m for the formals of [47mfn2[0m in the guard for [47mfn2[0m. If [47mguard-fn1[0m tautologically implies [47mguard-fn2[0m (for example, the two are equal or [47mguard-fn2[0m is [47m'T[0m), then the formula of the generated event is [47mT[0m. Otherwise, the formula is [47m(IMPLIES guard-fn1 guard-fn2)[0m. Note that the formula might be unpleasant for a human to read, since [47mguard-fn1[0m and [47mguard-fn2[0m are translated terms (see [term]).") (verify-guards (events guard) "Verify the [guard]s of a function See [guard] for a general discussion of guards. Before discussing the [47mverify-guards[0m [event], we first discuss [guard] verification, which can take place at definition time or, later, using [47mverify-guards[0m. Typically, guard verification takes place at definition time if a guard (or type, or [stobjs]) has been supplied explicitly unless [47m:verify-guards nil[0m has been specified; see [defun] and see [xargs], and see [set-verify-guards-eagerness] for how to change this default. The point of guard verification is to ensure that during evaluation of an expression without free variables, no guard violation takes place. Technical Notes: (1) The first argument of [47mverify-guards[0m must be a function symbol, the name of a [47m[defthm][0m or [47m[defaxiom][0m event, a [47m[lambda$][0m expression, or an unquoted well-formed [47mLAMBDA[0m object; it must not be a macro-alias for a function symbol (see [macro-aliases-table]). See [verify-guards+] for a utility that does not have this restriction. (2) When the guards of a defined function, [47mfn[0m, are verified, [47mverify-guards[0m also includes the guards of all the functions that are mutually recursive with [47mfn[0m, if any, plus the guards of all the quoted well-formed [47mLAMBDA[0m objects used by [47mfn[0m or any function in its mutually-recursive clique. Guard obligations for [47mlambda$[0m and [47mLAMBDA[0m objects are [3mnot[0m included when the first argument is the name of a theorem or axiom. Details are discussed further below. Guard verification is intended to guarantee that for any call of a given function, if its [guard] holds for that call then the [guard] will hold for every function call in the body of that function. Moreover, in order to avoid guard violations during evaluation of the function's guard itself, guard verification also is intended to guarantee that the guards are satisfied for all calls in the guard itself. Consider the following simple example. (defun f (x) (declare (xargs :guard (and (consp x) (integerp (car x))))) (if (rationalp (cdr x)) (+ (car x) (cdr x)) 17)) If you evaluate [47m(f t)[0m, for example, in the top-level loop, you will (by default) get a guard error. The point of guard verification is to guarantee the absence of guard errors, and we start by using this example to illustrate the proof obligations that guarantee such absence. The body of the above definition has the following function calls, where the first is the entire body. (if (rationalp (cdr x)) (< (car x) (cdr x)) 17) (rationalp (cdr x)) ; the test of the top-level IF call (cdr x) ; from (rationalp (cdr x)) (< (car x) (cdr x)) ; the true branch of the top-level IF call (car x) ; from (< (car x) (cdr x)) (cdr x) ; from (< (car x) (cdr x)) We thus see potentially six conditions to prove, one for each call. The guards of the function symbols of those calls are [47mt[0m for [47m[if][0m and [47m[rationalp][0m, [47m(or (consp x) (equal x nil))[0m for both [47m(car x)[0m and [47m(cdr x)[0m, and finally that both arguments are rationals for [47m<[0m. Moreover, we can take advantage of ``contextual assumptions'': the [47mif[0m-test conditions and the top-level [47m:guard[0m. Thus, for [47mverify-guards[0m the proof obligation from the body of [47mf[0m is as follows. (implies (and (consp x) (integerp (car x))) ; from the :guard (and t ; from the top-level IF call t ; from (rationalp (cdr x)) (or (consp x) (equal x nil)) ; from the first (cdr x) (implies (rationalp (cdr x)) ; IF-test for calls in the true branch (and (or (consp x) (equal x nil)) ; from (car x) (or (consp x) (equal x nil)) ; from the second (cdr x) (and (rationalp (car x)) (rationalp (cdr x))) ; from the < call )))) But the [47m:guard[0m itself generates a similar sort of proof obligation. Note that the guard [47m(and (consp x) (integerp (car x)))[0m is really an abbreviation (i.e. via the macro [47m[and][0m) for the term [47m(if (consp x) (integerp (car x)) nil)[0m. The guard proof obligation for the guard itself is thus as follows. (and t ; from (consp x) (implies (consp x) (and t ; from (integerp (car x)) ; (consp x) ; from (car x) ; ))) All of the above proof obligations are indeed theorems, and guard verification succeeds for the above definition of [47mf[0m. The example above illustrates the general procedure for generating the guard proof obligation. Each function call is considered in the body or guard of the function, and it is required that the guard is met for that call, under certain ``contextual assumptions'', which are as follows. In the case of the body of the named function, it is assumed that the guard holds for that function on its formal parameters. And in both cases --- the body of the named function and also its guard --- the governing tests from superior calls of [47m[if][0m are also assumed. (However, additional conjectures are generated for [47mloop$[0m statements. See the section [31;1mSpecial Guard Conjectures for LOOP$[0m in the documentation for [47m[loop$][0m.) As mentioned above, if the guard on a function is not [47mt[0m, then guard verification requires not only consideration of the body under the assumption that the guard is true, but also consideration of the guard itself. Thus, for example, guard verification fails in the following example, even though there are no proof obligations arising from the body, because the guard itself can cause a guard violation when evaluated for an arbitrary value of [47mx[0m: (defun foo (x) (declare (xargs :guard (car x))) x) We turn now to the [47mverify-guards[0m event as a way of verifying the [guard]s for a function or theorem. Examples: (verify-guards flatten) (verify-guards flatten :hints (("Goal" :use (:instance assoc-of-app))) :guard-debug t ; default = nil :guard-simplify :limited ; default = t :otf-flg t) (verify-guards (lambda$ (x) (declare (xargs :guard (natp x))) (+ 1 x))) (verify-guards (LAMBDA (X) (DECLARE (XARGS :GUARD (NATP X) :SPLIT-TYPES T)) (RETURN-LAST 'PROGN '(LAMBDA$ (X) (DECLARE (XARGS :GUARD (NATP X))) (+ 1 X)) (BINARY-+ '1 X)))) General Form: (verify-guards name :hints hints :guard-debug gdbg ; default generally nil; any value is legal :guard-simplify gsmp ; default generally t; may be set to :limited :otf-flg otf-flg) In the General Form above, [47mname[0m may be the name of a [47m:[0m[47m[logic][0m mode function (see [defun-mode]). In that case, the first three keywords may default to values in an existing definition as discussed below. Otherwise, [47mname[0m is the name of a theorem or axiom, or it is a [47m[lambda$][0m expression or a well-formed [47mLAMBDA[0m object (not [3mquoted[0m). [Mixed-mode-functions] cannot be guard verified. In the most common case [47mname[0m is the name of a function that has not yet had its [guard]s verified, each subroutine of which has had its [guard]s verified. The values [47m[hints][0m, [47m[otf-flg][0m, and [47m[guard-debug][0m are as described in the corresponding [documentation] entries, but [47mhints[0m and [47mguard-debug[0m can be taken from the existing definition of [47mname[0m; we return to that point later. The keyword arguments above are all optional. To admit this event, the conjunction of the guard proof obligations must be proved. If all the guard obligations are proved, [47mname[0m is considered to have had its [guard]s verified. The [47m:guard-simplify[0m option controls certain simplifications that may be applied to the guard conjecture while generating the initial goal: its default is [47mt[0m, which doesn't restrict such simplification, and the other legal value is [47m:limited[0m, which skips all simplifications that depend on the set of currently [enable]d rules; but as with [47mhints[0m and [47mguard-debug[0m, the value can be taken from the existing definition of [47mname[0m, as described further below. See also [guard-simplification]. If [47mname[0m is a [47mlambda$[0m expression it is translated (to a quoted well-formed [47mLAMBDA[0m object), the formals, declaration, and body are extracted, and [47mverify-guards[0m behaves as though [47mname[0m were the name of some defined function with those formals, declaration, and body. If [47mname[0m is a [47mLAMBDA[0m object, it is checked for well-formedness (see [47m[well-formed-lambda-objectp][0m), the formals, declaration, and body are extracted [47mverify-guards[0m behaves as though [47mname[0m were the name of some defined function with those formals, declaration, and body. for [47mlambda$[0m. We henceforth limit our attention to [47mname[0m being the name of a function, theorem or axiom. Note: Since we encourage you to use [47mlambda$[0m instead of trying to type quoted well-formed [47mLAMBDA[0m objects, you might wonder why we allow [47mverify-guards[0m to operate on well-formed [47mLAMBDA[0m objects instead of [47mlambda$[0m expressions. The answer is that in proof output and in [47m[print-cl-cache][0m output you see quoted well-formed [47mLAMBDA[0m objects and we expect you might grab the text of such an object and submit it to [47mverify-guards[0m. See [guard-formula-utilities] for related utilities, including ones that let you view the formula to be proved by [47mverify-guards[0m, but without creating an event. If [47mname[0m is one of several functions in a mutually recursive clique, [47mverify-guards[0m will attempt to verify the [guard]s of all of the functions. As promised above, we now describe the case that [47mname[0m was defined function symbol whose definition supplies the value of [47m:hints[0m, [47m:guard-debug[0m, and/or [47m:guard-simplify[0m. This happens when those keywords are not supplied with the [47mverify-guards[0m event but the existing definition specifies [47m:guard-hints[0m, [47m:guard-debug[0m, and/or [47m:guard-simplify[0m, respectively, in its [47m[xargs][0m [declaration]. Note that when [47mname[0m is defined as part of a [47m[mutual-recursion][0m event, only declarations in the definition of [47mname[0m are relevant, but those in definitions of other functions in the clique. Consider the following example. (defun my-consp (x) (declare (xargs :guard t)) (consp x)) (defun my-cdr (x) (declare (xargs :guard (my-consp x))) (cdr x)) (mutual-recursion (defun evenlp (x) (declare (xargs :verify-guards nil)) (if (consp x) (oddlp (my-cdr x)) t)) (defun oddlp (x) (declare (xargs :guard-hints (("Goal" :in-theory (disable my-consp (tau-system)))))) (if (consp x) (evenlp (my-cdr x)) nil))) Each of the following succeeds or fails for the reason given. ; Succeeds: :guard-hints for oddlp are ignored. (verify-guards evenlp) ; Fails: :guard-hints for oddlp defeat the proof attempt. (verify-guards oddlp) ; Succeeds: guard-hints for oddlp are ignored because :hints was supplied ; explicitly (even though :hints is nil, which is the default). (verify-guards oddlp :hints nil) If the guard or body of [47mname[0m include any quoted well-formed [47mLAMBDA[0m objects, [47mverify-guards[0m include their proof obligations in those generated for [47mname[0m. Roughly speaking, the guard obligations for a well-formed [47mLAMBDA[0m object are exactly those that would be generated for a separately defined non-recursive function with the formals, guard, and body of the [47mLAMBDA[0m object. We discuss this further in the ``Remarks on [47mLAMBDA[0m objects in defined functions'' below. As a non-logical side-effect of the successful verification of all the proof obligations, all well-formed [47mLAMBDA[0m objects in the guard or body of [47mname[0m (including [47mname[0m itself if it is a [47mlambda$[0m expression or [47mLAMBDA[0m object) are added to the compiled lambda cache. This will speed up the execution of [47mname[0m in the evaluation theory when those well-formed [47mLAMBDA[0m objects are [47mapply$[0md. See [47m[print-cl-cache][0m. If [47mname[0m is a theorem or axiom name, [47mverify-guards[0m verifies the guards of the associated formula. When a theorem has had its guards verified then you know that the theorem will evaluate to non-[47mnil[0m in all Common Lisps, without causing a runtime error (other than possibly a resource error). In particular, you know that the theorem's validity does not depend upon ACL2's arbitrary completion of the domains of partial Common Lisp functions. For example, if [47mapp[0m is defined as (defun app (x y) (declare (xargs :guard (true-listp x))) (if (endp x) y (cons (car x) (app (cdr x) y)))) then we can verify the guards of [47mapp[0m and we can prove the theorem: (defthm assoc-of-app (equal (app (app a b) c) (app a (app b c)))) However, if you go into almost any Common Lisp in which [47mapp[0m is defined as shown and evaluate (equal (app (app 1 2) 3) (app 1 (app 2 3))) we get an error or, perhaps, something worse like [47mnil[0m! How can this happen since the formula is an instance of a theorem? It is supposed to be true! It happens because the theorem exploits the fact that ACL2 has completed the domains of the partially defined Common Lisp functions like [47m[car][0m and [47m[cdr][0m, defining them to be [47mnil[0m on all non-conses. The formula above violates the guards on [47mapp[0m. It is therefore ``unreasonable'' to expect it to be valid in Common Lisp. But the following formula is valid in Common Lisp: (if (and (true-listp a) (true-listp b)) (equal (app (app a b) c) (app a (app b c))) t) That is, no matter what the values of [47ma[0m, [47mb[0m and [47mc[0m the formula above evaluates to [47mt[0m in all Common Lisps (unless the Lisp engine runs out of memory or stack computing it). Furthermore the above formula is a theorem: (defthm guarded-assoc-of-app (if (and (true-listp a) (true-listp b)) (equal (app (app a b) c) (app a (app b c))) t)) This formula, [47mguarded-assoc-of-app[0m, is very easy to prove from [47massoc-of-app[0m. So why prove it? The interesting thing about [47mguarded-assoc-of-app[0m is that we can verify the guards of the formula. That is, [47m(verify-guards guarded-assoc-of-app)[0m succeeds. Note that it has to prove that if [47ma[0m and [47mb[0m are true lists then so is [47m(app a b)[0m to establish that the guard on the outermost [47mapp[0m on the left is satisfied. By verifying the guards of the theorem we know it will evaluate to true in all Common Lisps. Put another way, we know that the validity of the formula does not depend on ACL2's completion of the partial functions or that the formula is ``well-typed.'' One last complication: The careful reader might have thought we could state [47mguarded-assoc-of-app[0m as (implies (and (true-listp a) (true-listp b)) (equal (app (app a b) c) (app a (app b c)))) rather than using the [47mif[0m form of the theorem. We cannot! The reason is technical: [47m[implies][0m is defined as a function in ACL2. When it is called, both arguments are evaluated and then the obvious truth table is checked. That is, [47mimplies[0m is not ``lazy.'' Hence, when we write the guarded theorem in the [47mimplies[0m form we have to prove the guards on the conclusion without knowing that the hypothesis is true. It would have been better had we defined [47mimplies[0m as a macro that expanded to the [47mif[0m form, making it lazy. But we did not and after we introduced guards we did not want to make such a basic change. For a utility that deals with this sort of problem automatically, see [47m[defthmg][0m. Recall however that [47mverify-guards[0m is almost always used to verify the guards on a function definition rather than a theorem. We now return to that discussion. [47mVerify-guards[0m must often be used when the value of a recursive call of a defined function is given as an argument to a subroutine that is [guard]ed. An example of such a situation is given below. Suppose [47mapp[0m (read ``append'') has a [guard] requiring its first argument to be a [47m[true-listp][0m. Consider (defun rev (x) (declare (xargs :guard (true-listp x))) (cond ((endp x) nil) (t (app (rev (cdr x)) (list (car x)))))) Observe that the value of a recursive call of [47mrev[0m is being passed into a [guard]ed subroutine, [47mapp[0m. In order to verify the [guard]s of this definition we must show that [47m(rev (cdr x))[0m produces a [47m[true-listp][0m, since that is what the [guard] of [47mapp[0m requires. How do we know that [47m(rev (cdr x))[0m is a [47m[true-listp][0m? The most elegant argument is a two-step one, appealing to the following two lemmas: (1) When [47mx[0m is a [47m[true-listp][0m, [47m(cdr x)[0m is a [47m[true-listp][0m. (2) When [47mz[0m is a [47m[true-listp][0m, [47m(rev z)[0m is a [47m[true-listp][0m. But the second lemma is a generalized property of [47mrev[0m, the function we are defining. This property could not be stated before [47mrev[0m is defined and so is not known to the theorem prover when [47mrev[0m is defined. Therefore, we might break the admission of [47mrev[0m into three steps: define [47mrev[0m without addressing its [guard] verification, prove some general properties about [47mrev[0m, and then verify the [guard]s. This can be done as follows: (defun rev (x) (declare (xargs :guard (true-listp x) :verify-guards nil)) ; Note this additional xarg. (cond ((endp x) nil) (t (app (rev (cdr x)) (list (car x)))))) (defthm true-listp-rev (implies (true-listp x2) (true-listp (rev x2)))) (verify-guards rev) The ACL2 system can actually admit the original definition of [47mrev[0m, verifying the [guard]s as part of the [47m[defun][0m event. The reason is that, in this particular case, the system's heuristics just happen to hit upon the lemma [47mtrue-listp-rev[0m. But in many more complicated functions it is necessary for the user to formulate the inductively provable properties before [guard] verification is attempted. [31;1mRemarks on [47mLAMBDA[0m[31;1m objects in defined functions[0m. The guard obligations of a function, [47mname[0m, include the guard obligations of every quoted well-formed [47mLAMBDA[0m object occurring in either the guard or body of [47mname[0m. We point this out because quoted well-formed [47mLAMBDA[0m objects are, after all, just quoted constants and no other quoted constant generates guard obligations! Note also that we collect [3mall[0m quoted well-formed [47mLAMBDA[0m objects, not just the translations of [47m[lambda$][0m expressions and not just objects in slots of [ilk] [47m:FN[0m. (We do not actually expect the user to write quoted well-formed [47mLAMBDA[0m objects in non-[47m:FN[0m slots -- it can't be done with [47mlambda$[0m expressions -- but we collect them all anyway. If such a quoted constant is not guard verifiable, you could always use so-called Bypass 1 of [gratuitous-lambda-object-restrictions] and avoid quoting it.) We assume that when calls of [47mname[0m are executed some of those [47mLAMBDA[0m objects may reach [47mapply$[0m and be applied. Those applications will be faster if the guards for the [47mLAMBDA[0ms are verified too. The guard obligations of a quoted well-formed [47mLAMBDA[0m object are just those obligations that would be generated by a defined function with the same formals, guard, and body as the [47mLAMBDA[0m object. Those obligations are unioned with the rest of the obligations generated for [47mname[0m and all must be proved for [47m(verify-guards name)[0m to be successful. If the guards of some [47mLAMBDA[0m object requires hints to prove, the hints may be supplied to [47mverify-guards[0m as you would for any other failing guard obligation in [47mname[0m. When successful, the [47mLAMBDA[0m objects thus verified are added, behind the scenes, to the compiled lambda cache (see [47m[print-cl-cache][0m) to speed up [47mapply$[0m in the evaluation theory. Since, in general, [47mLAMBDA[0m objects can be passed around or re-used in different contexts, the guard obligations generated for a quoted well-formed [47mLAMBDA[0m object occurring in [47mname[0m are entirely independent of the guard on the [47mname[0m itself. This is best explained by example. In the [47mdefun[0m below, which contains a [47mlambda$[0m expression in its body, we assume each function has the guard shown below: function formals guard f (x) (fp x) g (x y) (gp x y) the lambda$ (x) (lp x) r (x) (rp x) s (x) (sp x) We also assume that the ilks of [47mg[0m are [47m:FN[0m and [47mNIL[0m. Then the guard obligations generated for (defun f (x) (declare (xargs :guard (fp x))) (g (lambda$ (x) (declare (xargs :guard (lp x))) (r x)) (s x))) is (and (implies (fp x) (sp x)) ; f can call s (implies (fp x) ; f can call g (gp (lambda$ (x) (declare (xargs :guard (hg x))) (r x)) (s x))) (implies (lp x) (rp x)) ; the lambda$ can call r ) Note: The actual obligation will have been generated from the fully translated body of [47mf[0m and the [47mlambda$[0m expression will have been converted to a quoted well-formed [47mLAMBDA[0m object. But we will refer to it as a [47mlambda$[0m here for clarity. In particular note that the last conjecture, establishing that the [47mlambda$[0m can call [47mr[0m, does not have [47mf[0m's guard as a hypothesis. The [47mlambda$[0m is being guard verified in a ``context free'' way because we cannot (or at least do not) trace the hypotheses governing every time it is called in [47mg[0m and the variable [47mx[0m in [47mf[0m and its guard is unrelated to the local variable [47mx[0m in the [47mlambda$[0m. Furthermore, if [47mapply$[0m ever encounters this [47mlambda$[0m it will know it has been guard verified (because it finds it marked as such in the cache) and it may well [3mnot[0m be under a call of [47mf[0m. Be that as it may, the guard obligations of the [47mlambda$[0m are included in the guard obligations for [47mf[0m. As of ACL2 Version 8.1, the guard obligation that [47mg[0m can call the [47mlambda$[0m is checked by computation every time the [47mlambda$[0m is [47mapply$[0md. That is, [47m(lp x)[0m is run on each object the [47mlambda$[0m is [47mapply$[0md to and the compiled code for the [47mlambda$[0m is run only if its guard approves. [31;1mRemark on computation of guard conjectures and evaluation[0m. When ACL2 computes the [guard] conjecture for the body of a function, it evaluates any ground subexpressions (those with no free variables), for calls of functions whose [47m:[0m[47m[executable-counterpart][0m [rune]s are [47m[enable][0md. Note that here, ``enabled'' refers to the current global [theory], not to any [47m:[0m[47m[hints][0m given to the guard verification process; after all, the guard conjecture is computed even before its initial goal is produced. Also note that this evaluation is done in an environment as though [47m:set-guard-checking :all[0m had been executed, so that we can trust that this evaluation takes place without guard violations; see [set-guard-checking]. If you want to verify the [guard]s on functions that are built into ACL2, you will first need to put them into [47m:[0m[47m[logic][0m mode. See [verify-termination], specifically the ``Remark on system functions'' in that [documentation]. Subtopics [Verify-guards-for-system-functions] Arranging that source functions come up as guard-verified") (verify-guards+ (events) "Verify the [guard]s of a function We assume familiarity with [guard] verification; see [verify-guards]. Unlike [47mverify-guards[0m, the macro call [47m(verify-guards+ mac ...)[0m will verify guards for a function, [47mfn[0m, such that the macro [47mmac[0m is associated with the function symbol [47mfn[0m in [47m[macro-aliases-table][0m (also see [add-macro-alias]). For example, if you define a macro [47mapp[0m and list append function [47mbinary-app[0m, and you associate macro [47mapp[0m with function symbol [47mbinary-app[0m in [47m[macro-aliases-table][0m, then evaluation of the form [47m(verify-guards+ app)[0m will have the effect of evaluating [47m(verify-guards fn)[0m. Note that in this setting, evaluation of [47m(verify-guards app)[0m would cause an error, because [47mapp[0m is a macro and [47mverify-guards[0m, unlike [47mverify-guards+[0m, cannot handle macros. The rest of this [documentation] topic discusses why we do not simply arrange that [47mverify-guards[0m be permitted to take a macro alias. The following example shows a soundness issue in doing so. (encapsulate () (defun f1 (x) (declare (xargs :guard (consp x) :verify-guards nil)) (car x)) (defun f2 (x) (declare (xargs :guard t :verify-guards nil)) (cdr x)) (defmacro mac (x) x) (add-macro-alias mac f2) ; silly macro alias ; (local (add-macro-alias mac f1)) ; alternate silly macro alias ; (verify-guards mac)) If we were to allow macro aliases in [47m[verify-guards][0m, this event would be admitted, because on the first pass we are verifying guards of [47mf1[0m. But after the [47m[encapsulate][0m form completes evaluation, it would appear that [47mf2[0m is guard-verified. That could of course cause a raw Lisp error. The enhanced functionality provided by [47mverify-guards+[0m does not have the above problem, because it takes advantage of [47m[make-event][0m to avoid taking advantage of the contradictory results produced by the two calls of [47madd-macro-alias[0m. See [make-event]. If the specific example above is modified by replacing [47mverify-guards[0m with [47mverify-guards+[0m, then the first pass through the [47m[encapsulate][0m form will expand the form [47m(verify-guards+ mac)[0m to [47m(verify-guards f1)[0m. That same expansion will be used for the [47mverify-guards+[0m call during the second pass through the [47mencapsulate[0m form, which is evaluated successfully and leaves us in a [world] where [47mf1[0m is guard-verified and [47mf2[0m is not.") (verify-guards-eagerness (pointers) "See [set-verify-guards-eagerness].") (verify-guards-for-system-functions (verify-termination verify-guards) "Arranging that source functions come up as guard-verified ACL2 is maintained solely by Matt Kaufmann and J Moore. However, we anticipate that a few others will eventually contribute as well. Here we discuss how to put built-in functions into [47m:[0m[47m[logic][0m mode. Since ACL2 insists that its built-in [47m:logic[0m mode functions are [guard]-verified, we actually explain how to arrange that built-in [47m:[0m[47m[program][0m mode functions become built-in guard-verified [47m:logic[0m mode functions. To put a system function into guard-verified [47m:logic[0m mode, you might first need or want to modify your local copy of the ACL2 sources, for example replacing [47m(null lst)[0m by [47m(endp lst)[0m in a function's definition in support of the termination proof and then specifying [47m(true-listp lst)[0m in its guard. You don't need to become a system developer to do this, but see [developers-guide] if you are an experienced ACL2 user and system development interests you. IMPORTANT: Eventually you will probably want to undo your changes; this will be explained further below. After making such changes, build an ACL2 executable image containing your modified code, to test that the modified code builds. The next step is typically to create a new file, perhaps named after the main function(s) whose guards you want to verify, in directory [47mbooks/system[0m. Community book [47mbooks/system/too-many-ifs.lisp[0m is a good example. Ultimately, this file should be a certifiable book that verifies the desired termination and guards. Include this book in [47mbooks/system/top.lisp[0m. Of course, you can instead add to some existing file in the same directory that is already included in [47mbooks/system/top.lisp[0m, rather than creating a new book and including it there. In general, in this new file or new file addition, it is necessary to use both [47m[verify-termination][0m and [47m[verify-guards][0m on the system functions in question, in order to both put them in logic mode and verify their guards. However, as explained in the documentation of [47m[verify-termination][0m, sometimes [47m[verify-termination][0m also verifies the guards (see also [47m[set-verify-guards-eagerness][0m). In this case, it is good practice to add a comment `[47m; and guards[0m' just after the [47m[verify-termination][0m form, on the same line, as can be seen in some of the files under [community-books] directory [47msystem/[0m. Now it is time to add entries to the value of constant [47m*system-verify-guards-alist*[0m in your local copy of the ACL2 sources, which specifies functions whose guard-verification is completed by including [community-book] [47mbooks/system/devel-check.lisp[0m (which includes [47mbooks/system/top.lisp[0m. Each entry is of the form [47m(function-symbol . measure)[0m. For example, the entry [47m(ARITY-ALISTP ACL2-COUNT ALIST)[0m signifies that the function symbol [47marity-alistp[0m is to have measure [47m(acl2-count alist)[0m, while the entry [47m(ARGLISTP)[0m signifies that function symbol [47marglistp[0m has no measure (i.e., we use [47mnil[0m for the measure), presumably because its definition is not recursive. After you make those additions, then follow the steps below. 1. Build a so-called ``devel'' copy in which the functions in [47m*system-verify-guards-alist*[0m remain in [47m:program[0m mode. For example, the following command will create ``devel'' executable [47msaved_acl2d[0m. (time nice make ACL2_DEVEL=d) >& make-devel.log 2. Check that the build seems to have worked, for example by finding the string [47m"Successfully built"[0m near the end of your log file. 3. Run a ``devel'' regression, for example as follows if starting in the ACL2 sources directory. Note that including ``[47mACL2_USELESS_RUNES= [0m'' as shown below may be necessary because of how proofs differ between normal and ``devel'' versions of ACL2. make clean-books ACL2=`pwd`/saved_acl2d cd books (time nice make -j 8 \ ACL2=`pwd`/../saved_acl2d \ ACL2_USELESS_RUNES= \ system/devel-check.cert) \ >& make-devel-regression.log& The last of these commands should run much more quickly than a normal regression. You can of course check on it as follows. tail make-devel-regression.log 4. Check that there are no errors, by checking that the following produces no output. fgrep -a '**' make-devel-regression.log 5. Run the following check from your ACL2 sources directory. make devel-check ACL2=`pwd`/saved_acl2d You should see output like the following. SUCCESS for chk-new-verified-guards SUCCESS for check-system-events SUCCESS for devel-check 6. Now clean the books (see [47mmake clean-books[0m above) and then do a normal build and regression. 7. Finally, send your changes to Matt Kaufmann, with a request that they be incorporated into the ACL2 sources and books. We now return to the remark labeled ``IMPORTANT'' above: undoing your changes. This isn't necessary if you will not be using that local copy of ACL2 in the future. But otherwise you may run into problems when you try to use git to merge changes into that local ACL2+books copy. One option is to throw your changes away by standing in your local ACL2 directory and using the shell command: [47mgit checkout -f[0m. But be careful --- this will throw away all your work! So you might want to wait until your changes make it into the main (master) git branch.") (verify-guards-formula (guard-formula-utilities) "View the guard proof obligation, without proving it See [verify-guards] and see [guard] for a discussion of guards. This utility, which does not evaluate its argument, provides output showing the guard proof obligation (also known as the guard theorem) as printed by [47mverify-guards[0m, but without then carrying out a proof attempt. See also [guard-formula-utilities] for related utilities. Example Forms: (verify-guards-formula foo) (verify-guards-formula foo :guard-debug t) (verify-guards-formula foo :guard-debug t :guard-simplify :limited) (verify-guards-formula foo :rrp t :otf-flg dont-care :xyz whatever) (verify-guards-formula (+ (foo x) (bar y)) :guard-debug t) [47mVerify-guards-formula[0m allows all keywords, but only pays attention to [47m:guard-debug[0m and [47m:guard-simplify[0m, which have the same effect as in [47m[verify-guards][0m (also see [guard-debug] and [guard-simplification]), and to [47m:rrp[0m, described below. Apply [47mverify-guards-formula[0m to a name just as you would use [47m[verify-guards][0m, but when you only want the output that shows the guard proof obligation, without attempting a proof or creating an event. If the first argument is not a symbol, then it is treated as the body of a [47m[defthm][0m event for which you want the guard proof obligation. The [47m:rrp[0m argument (``return redundant p'') is [47mnil[0m by default. If its value is not [47mnil[0m, then in the case that the first argument is a guard-verified function symbol, the keyword [47m:REDUNDANT[0m is returned without any output.") (verify-termination (events) "Convert a function from :program mode to :logic mode Example: (verify-termination fact) General Forms: (verify-termination fn dcl ... dcl) (verify-termination (fn1 dcl ... dcl) (fn2 dcl ... dcl) ...) where [47mfn[0m and the [47mfni[0m are function symbols having [47m:[0m[47m[program][0m mode (see [defun-mode]) and all of the [47mdcl[0ms are either [47m[declare][0m forms or [documentation] strings. The first form above is an abbreviation for (verify-termination (fn dcl ... dcl)) so we limit our discussion to the second form. Each of the [47mfni[0m must be in the same clique of mutually recursively defined functions, but not every function in the clique need be among the [47mfni[0m. [47mVerify-termination[0m attempts to establish the admissibility of the [47mfni[0m. [47mVerify-termination[0m retrieves their definitions, creates modified definitions using the [47mdcl[0ms supplied above, and resubmits these definitions. You could avoid using [47mverify-termination[0m by typing the new definitions yourself. So in that sense, [47mverify-termination[0m adds no new functionality. But if you have prototyped your system in [47m:[0m[47m[program][0m mode and tested it, you can use [47mverify-termination[0m to resubmit your definitions and change their [defun-mode]s to [47m:[0m[47m[logic][0m, adding [hints] without having to retype or recopy the code. The [47m[defun][0m [command] executed by [47mverify-termination[0m is obtained by retrieving the [47m[defun][0m (or [47m[mutual-recursion][0m) [command] that introduced the clique in question and then possibly modifying each definition as follows. Consider a function, [47mfn[0m, in the clique. If [47mfn[0m is not among the [47mfni[0m above, its definition is left unmodified other than to add [47m(declare (xargs :mode :logic))[0m. Otherwise, [47mfn[0m is some [47mfni[0m and we modify its definition by inserting into it the corresponding [47mdcl[0ms listed with [47mfni[0m in the arguments to [47mverify-termination[0m, as well as [47m(declare (xargs :mode :logic))[0m. In addition, we throw out from the old declarations in [47mfn[0m the [47m:mode[0m specification and anything that is specified in the new [47mdcl[0ms. For example, suppose that [47mfact[0m was introduced with: (defun fact (n) (declare (type integer n) (xargs :mode :program)) (if (zp n) 1 (* n (fact (1- n))))). Suppose later we do [47m(verify-termination fact)[0m. Then the following definition is submitted. (defun fact (n) (declare (type integer n)) (if (zp n) 1 (* n (fact (1- n))))). Observe that this is the same definition as the original one, except the old specification of the [47m:mode[0m has been deleted so that the [defun-mode] now defaults to [47m:[0m[47m[logic][0m. Although the termination proof succeeds, ACL2 also tries to verify the [guard], because we have (implicitly) provided a [guard], namely [47m(integerp n)[0m, for this function. (See [guard] for a general discussion of guards, and see [type-spec] for a discussion of how type declarations are used in guards.) Unfortunately, the [guard] verification fails, because the subterm [47m(zp n)[0m requires that [47mn[0m be nonnegative, as can be seen by invoking [47m:args zp[0m. (For a discussion of termination issues relating to recursion on the naturals, see [zero-test-idioms].) So we might be tempted to submit the following: (verify-termination fact (declare (xargs :guard (and (integerp n) (<= 0 n))))). However, this is considered a changing of the guard (from [47m(integerp n)[0m), which is illegal. If we instead change the guard in the earlier [47mdefun[0m after undoing that earlier definition with [47m:[0m[47m[ubt][0m[47m fact[0m, then [47m(verify-termination fact)[0m will succeed. It may be necessary to specify an appropriate [47m:ruler-extenders[0m in a [47mdcl[0m supplied to [47mverify-termination[0m. This determines the [rulers] used in the termination proofs and also the case analysis in the induction scheme suggested by the admitted function. See [induction-coarse-v-fine-grained]. [31;1mRemark on system functions.[0m There may be times when you want to apply [47mverify-termination[0m (and also, perhaps, [47m[verify-guards][0m) to functions that are predefined in ACL2. It may be necessary in such cases to modify the system code first. See [verify-guards-for-system-functions] for a discussion of the process for contributing updates to the system code and [books] with such [47mverify-termination[0m or [47m[verify-guards][0m [events], perhaps resulting in more system functions being built-in as [guard]-verified. To see which built-in functions have already received such treatment, see community books directory [47mbooks/system/[0m; or, evaluate the constant [47m*system-verify-guards-alist*[0m, which specifies a list of functions whose guard-verification is proved by including that book. See the above URL for more details. Note that if [47mfn1[0m is already in [47m:[0m[47m[logic][0m mode, then the [47mverify-termination[0m call has no effect. It is generally considered to be redundant, in the sense that it returns without error; but if the [47mfn1[0m is a constrained function (i.e., introduced in the signature of an [47m[encapsulate][0m, or by [47m[defchoose][0m), then an error occurs. This error is intended to highlight unintended uses of [47mverify-termination[0m; but if you do not want to see an error in this case, you can write and use your own macro in place of [47mverify-termination[0m. The following explanation of the implementation of [47mverify-termination[0m may help with such a task. We conclude with a discussion of the use of [47m[make-event][0m to implement [47mverify-termination[0m. This discussion can be skipped; we include it only for those who want to create variants of [47mverify-termination[0m, or who are interested in seeing an application of [47m[make-event][0m. Consider the following proof of [47mnil[0m, which succeeded up through Version_3.4 of ACL2. (encapsulate () (defun foo (x y) (declare (xargs :mode :program)) (if (or (zp x) (zp y)) (list x y) (foo (1+ x) (1- y)))) (local (defun foo (x y) (declare (xargs :measure (acl2-count y))) (if (or (zp x) (zp y)) (list x y) (foo (1+ x) (1- y))))) (verify-termination foo)) (defthm bad-lemma (zp x) :hints (("Goal" :induct (foo x 1))) :rule-classes nil) How did this work? In the first pass of the [47m[encapsulate][0m, the second [47m[defun][0m of [47mfoo[0m promoted [47mfoo[0m from [47m:program[0m to [47m:logic[0m mode, with [47my[0m as the unique measured variable. The following call to [47mverify-termination[0m was then redundant. However, on the second pass of the [47m[encapsulate][0m, the second ([47m[local][0m) definition of [47mfoo[0m was skipped, and the [47mverify-termination[0m event then used the first definition of [47mfoo[0m to guess the measure, based (as with all guesses of measures) on a purely syntactic criterion. ACL2 incorrectly chose [47m(acl2-count x)[0m as the measure, installing [47mx[0m as the unique measured variable, which in turn led to an unsound induction scheme subsequently used to prove [47mnil[0m (lemma [47mbad-lemma[0m, above) Now, [47mverify-termination[0m is a macro whose calls expand to [47m[make-event][0m calls. So in the first pass above, the [47mverify-termination[0m call generated a [47mdefun[0m event identical to the [47m[local][0m [47m[defun][0m of [47mfoo[0m, which was correctly identified as redundant. That expansion was recorded, and on the second pass of the [47m[encapsulate][0m, the expansion was recalled and used in place of the [47mverify-termination[0m call (that is how [47m[make-event][0m works). So instead of a measure being guessed for the [47mverify-termination[0m call on the second pass, the same measure was used as was used on the first pass, and a sound induction scheme was stored. The attempt to prove [47mnil[0m (lemma [47mbad-lemma[0m) then failed. Subtopics [Verify-guards-for-system-functions] Arranging that source functions come up as guard-verified [Verify-termination-on-raw-program-okp] Permit [47m[verify-termination][0m for functions with raw Lisp code.") (verify-termination-on-raw-program-okp (verify-termination) "Permit [47m[verify-termination][0m for functions with raw Lisp code. By default, it is not permitted to verify termination (see [VERIFY-TERMINATION]) for functions with raw Lisp code. This restriction is important in general for preserving soundness; see [program-only]. However, in some cases it may be harmless to remove this restriction. That can be done as follows. Note that an active trust tag is required: in principle you can render ACL2 unsound with this action! (defttag t) (remove-untouchable verify-termination-on-raw-program-okp nil) ; In the following, t can be replaced by an expression that evaluates to a ; list of symbols for which it is permitted to verify termination. (assign verify-termination-on-raw-program-okp t)") (version (about-acl2) "ACL2 Version Number To determine the version number of your copy of ACL2, evaluate the form [47m(@ acl2-version)[0m. The value will be a string. For example, ACL2 !>(@ acl2-version) "ACL2 Version 3.4" The part of the string after [47m"ACL2 Version "[0m is of the form [47mx.y[0m or [47mx.y.z[0m, optionally followed by a succession of values in parentheses, where [47mx[0m, [47my[0m, and [47mz[0m are natural numbers. If [47mz[0m is omitted then it is implicitly 0. We refer to [47mX[0m, [47my[0m, and [47mz[0m as the ``major'', ``minor'', and ``incrl'' fields, respectively. The incrl field is used for incremental releases. The discussion just below assumes that incremental releases are not employed at the user's site, i.e., the incrl fields are always 0. We remove this assumption when we discuss incremental releases at the end of this documentation topic. [Books] are considered certified only in the same version of ACL2 in which the certification was done. The [certificate] file records the version number of the certifying ACL2 and [include-book] considers the book uncertified if that does not match the current version number. Thus, each time we release a new version of ACL2, previously certified books should be recertified. Note that there are over 150 constants in the system, most having to do with the fact that ACL2 is coded in ACL2. Many of these, for example [47m*common-lisp-specials-and-constants*[0m and [47m*acl2-exports*[0m, may change from version to version, and this can cause unsoundness. For example, the symbol [47m'set-difference-eq[0m was added to [47m*acl2-exports*[0m in Version_2.9, so we can certify a book in Version_2.8 containing the following theorem, which is false in Version_2.9. (null (member 'set-difference-eq *acl2-exports*)) Therefore, we need to disallow inclusion of such a book in a Version_2.9 session, which otherwise would allow us to prove [47mnil[0m. Furthermore, it is possible that from one version of the system to another we might change, say, the default values on some system function or otherwise make ``intentional'' changes to the axioms. It is even possible one version of the system is discovered to be unsound and we release a new version to correct our error. Therefore we adopted the draconian policy that books are certified by a given version of ACL2 and ``must'' be recertified to be used in other versions. We put ``must'' in quotes because in fact, ACL2 allows a book that was certified in one ACL2 version to be included in a later version, using [47m[include-book][0m. But ACL2 does not allow [47m[certify-book][0m to succeed when such an [47m[include-book][0m is executed on its behalf. Also, you may experience undesirable behavior if you avoid recertification when moving to a different version. Hence we recommend that you stick to the draconion policy of recertifying books when updating to a new ACL2 version. Furthermore, all bets are off if you certify a book using ACL2 built on one host Lisp implementation and include the book using ACL2 built on a different host Lisp implementation. For example, for most host Lisp implementations, the Lisp reader will interpret the token [47m2f[0m as a symbol; however, Common Lisp allows for the possibility that [47m2f[0m is read as a number. In such a case, one could use the former ACL2 executable to certify a book containing the form (defthm my-thm (symbolp '2f) :rule-classes nil) but then use the latter ACL2 executable to include the book, even though for the latter ACL2 executable, [47m2f[0m is a number, not a symbol. Of course, one would expect an error because of a [book-hash] mismatch) in such case. But these do not provide guaranteed protection against including uncertified books. [3mIncremental releases.[0m From time to time, so-called ``incremental releases'' of ACL2 are made available. These releases are thoroughly tested on at least two platforms; ``normal'' releases, on the other hand, are thoroughly tested on many more platforms (perhaps a dozen or so) and are accompanied by updates to the ACL2 home page. We provide incremental releases in order to provide timely updates for ACL2 users who want them, without imposing unnecessary burdens on either on the ACL2 implementors or on ACL2 users who prefer to update less frequently. The implementors expect users to update their copies of ACL2 when normal releases are made available, but not necessarily when incremental releases are made available. Incremental releases are accompanied by a bump in the incrl field of the version field, while normal releases are accompanied by a bump in the minor or (much less frequently) major field and zeroing out of the incrl field. Note that incremental releases are full-fledged releases.") (w (state) "The current ACL2 [world] The value of the form [47m(w state)[0m is the current ACL2 world. See [world].") (walkabout (debugging) "Explore an ACL2 cons tree By typing [47m(walkabout x state)[0m for an ACL2 term [47mx[0m whose value is a [47m[cons][0m tree, you can walk around that tree. For example, ACL2 developers often use this utility to explore the ACL2 logical [world]. When you issue a [47mwalkabout[0m command, a summary of commands will be printed before you enter an interactive loop. Commands: 1, 2, ..., up, nx, bk, pp, (pp n), (pp lev len), =, (= symb), (cmds c1 c2 ... cn), and q. In the interactive [47mwalkabout[0m loop, a positive integer n takes you to the nth position, while [47mup[0m takes you up a level. The commands [47mnx[0m and [47mbk[0m take you to the next and previous position, respectively, at the same level. The command [47mpp[0m prints the current object in full, while [47m(pp level length)[0m hides sub-objects below the indicated level and past the indicated length, if non-[47mnil[0m; see [evisc-tuple]. The command [47m(pp n)[0m abbreviates [47m(pp n n)[0m, so in particular [47m(pp nil)[0m is equivalent to [47mpp[0m. The commands [47m=[0m and [47mcmds[0m are described below. Note that the commands above work in any package: [47mup[0m, [47mnx[0m, [47mbk[0m, [47mpp[0m, [47m=[0m, [47mcmds[0m, and [47mq[0m are converted to the [47m"ACL2"[0m package if the current package is not [47m"ACL2"[0m. Also, as a convenience, the single character [47m0[0m is accepted as equivalent to [47mup[0m. The following example illustrates the commands described above. ACL2 !>(walkabout (append '(a (b1 b2 b3)) '(c d e f)) state) Commands: 1, 2, ..., up, nx, bk, pp, (pp n), (pp lev len), =, (= symb), (cmds c1 c2 ... cn), and q. (A (B1 B2 B3) C ...) :2 (B1 B2 B3) :3 B3 :up (B1 B2 B3) :nx C :nx D :up (A (B1 B2 B3) C ...) :pp (A (B1 B2 B3) C D E F) :(pp 4) (A (B1 B2 B3) C D ...) :(pp 1 4) (A # C D ...) :(pp nil 2) (A (B1 B2 ...) ...) :q ACL2 !> The command [47m(cmds c1 c2 ... cn)[0m just executes each of the [47mci[0m, sequentially. The command [47mq[0m simply causes an exit from the [47mwalkabout[0m loop. The command [47m=[0m also exits, but returns the current object as the value in an ACL2 [error-triple]. The command [47m(= symb)[0m saves an association of [47msymb[0m with the current object, which can be retrieved outside the [47mwalkabout[0m loop using the macro [47mwalkabout=[0m, as illustrated below. ... :pp (B1 B2 B3) :(= my-list) (walkabout= MY-LIST) is (B1 B2 B3) :q ACL2 !>(walkabout= MY-LIST) (B1 B2 B3) ACL2 !> Finally, we remark that for trees that are not true-lists, [47mwalkabout[0m treats the dot as an object that can be ``walked about''. The following example illustrates this point. ACL2 !>(walkabout '(c d e . f) state) Commands: 1, 2, ..., up, nx, bk, pp, (pp n), (pp lev len), =, (= symb), (cmds c1 c2 ... cn), and q. (C D E . F) :3 E :nx . :nx F :up (C D E . F) :4 . :up (C D E . F) :5 F :") (warnings (output-controls) "Warnings emitted by the ACL2 proof process The prover can emit many warnings when processing [events]. See [set-inhibit-warnings] and see [set-inhibit-output-lst] for how to disable and enable them. See also [47m[toggle-inhibit-warning][0m and [47m[set-warnings-as-errors][0m. Subtopics [Set-warnings-as-errors] Changing [warnings] to hard [errors] (and vice-versa)") (warrant (apply$) "Giving [47m[apply$][0m permission to handle a user-defined function in proofs The word ``warrant'' is defined in the Merriam-Webster dictionary as ``a commission or document giving authority to do something....'' The discussion below mentions the concept of [47m[badge][0ms, which are easily confused with warrants. See the discussion of [31;1mBadges versus Warrants[0m at the top of [47m[defbadge][0m. But roughly put, badges extend the ACL2 syntax and warrants extend the proof theory. You'll need a badge for [47mfn[0m to allow the system to syntactically analyze [47m(apply$ 'fn ...)[0m. You'll need a both a badge and a warrant for [47mfn[0m if you wish to reason about that term with ACL2. Badges and warrants also have impact on evaluation of forms in the top-level loop. See [guarantees-of-the-top-level-loop]. In the ACL2 proof theory, the functions [47m[badge][0m and [47m[apply$][0m are undefined on user-defined function symbols. To be precise, when presented with a user-defined function symbol, [47mbadge[0m calls the weakly constrained function [47mbadge-userfn[0m and [47mapply$[0m calls the weakly constrained function [47mapply$-userfn[0m. Warrants are terms that, if available as hypotheses in a conjecture, further constrain those functions for specific function symbols. If there is a warrant for [47mfn[0m among the hypotheses of a conjecture, [47m(badge 'fn)[0m and [47m(apply$ 'fn ...)[0m can be simplified appropriately. In particular, [47m(badge 'fn)[0m is simplified to the actual badge of [47mfn[0m and [47m(apply$ 'fn ...)[0m is simplified to the appropriate application of [47mfn[0m provided the arguments are suitably [tame]. We think of the warrant for [47mfn[0m giving [47mbadge[0m and [47mapply$[0m authority to expand on [47m'fn[0m. For reasons of logical consistency not every [47mfn[0m can have a warrant. Warrants are issued, when possible, by [47m[defwarrant][0m. In the ACL2 evaluation theory --- a consistent extension of the proof theory --- all warrants issued by [47mdefwarrant[0m are implicitly assumed, meaning [47mbadge[0m and [47mapply$[0m can be executed on warranted user-defined function symbols at the top-level of the ACL2 loop without explicit mention of the warrants. In fact, just as the evaluation theory can --- ``magically'' --- execute [47m:program[0m mode functions despite the absence of any axioms about them, the evaluation theory can execute a well-formed [47mapply$[0m on any [47m:program[0m mode function that has a [47m[badge][0m. However, for a [47m:logic[0m mode function [47mfn[0m, the top-level loop cannot evaluate [47m(apply$ 'fn ...)[0m unless [47m(defwarrant fn)[0m has previously succeeded. See [guarantees-of-the-top-level-loop].) For a discussion of the restrictions on when a [47mfn[0m can be warranted, see [47m[defwarrant][0m. This topic discusses warrants [3mper se[0m, their names, their logical meaning, when they must be explicitly added as hypotheses to conjectures, and their consistency. Logical Definition of the Warrant of a Function If [3mfn[0m has a warrant, then the warrant is the term [47m(apply$-warrant-[0m[3mfn[0m[47m)[0m, i.e., a call of the 0-ary warrant function named, [47mapply$-warrant-[0m[3mfn[0m. That warrant function name is admitted to the logic when [47mdefwarrant[0m succeeds on [47mfn[0m. The warrant function for [47mfn[0m, introduced by [47m(defwarrant fn)[0m, is defined with [47m[defun-sk][0m because the warrant must specify the values returned by [47m(apply$ 'fn args)[0m [3mfor all possible[0m [47margs[0m. Recall that [47m[badge][0m and [47m[apply$][0m defer to two undefined functions, [47mbadge-userfn[0m and [47mapply$-userfn[0m, when they are applied to user-defined function symbols. The warrant for [47mfn[0m is actually phrased in terms of those two undefined functions. By stipulating their values on [47m'fn[0m the warrant determines the values of [47m(badge 'fn)[0m and [47m(apply$ 'fn ...)[0m. To create the warrant function for [47mfn[0m, [47mdefwarrant[0m must turn the ilks of [47mfn[0m into tameness requirements on the corresponding elements of the [47margs[0m to which [47mfn[0m will be applied by [47mapply$[0m. Each [47m:FN[0m argument must be a [tame] function and each [47m:EXPR[0m argument must be a [tame] expression. It is easiest to understand the above paragraph by looking at the generated warrant function for [47mfoldr[0m, whose definition is shown at the top of the documentation for [47m[apply$][0m and whose [badge] is [47m(APPLY$-BADGE 3 1 NIL :FN NIL)[0m, indicating that [47mfoldr[0m takes 3 arguments of ilks [47mNIL[0m, [47m:FN[0m, and [47mNIL[0m, and returns 1 result. The warrant function for [47mfoldr[0m is defined as follows. (defun-sk apply$-warrant-foldr () (forall (args) (implies (tamep-functionp (cadr args)) (and (equal (badge-userfn 'FOLDR) '(APPLY$-BADGE 3 1 NIL :FN NIL)) (equal (apply$-userfn 'FOLDR args) (foldr (car args) (cadr args) (caddr args)))))) :constrain t) Notice also that the tameness hypothesis involves the universally quantified variable [47margs[0m, but that the first conjunct of the conclusion does not mention that variable. So we can read [47m(apply$-warrant-foldr)[0m as equivalent to the conjunction of: (equal (badge-userfn 'FOLDR) '(APPLY$-BADGE 3 1 NIL :FN NIL)) and (forall (args) (implies (tamep-functionp (cadr args)) (equal (apply$-userfn 'FOLDR args) (foldr (car args) (cadr args) (caddr args))))) The first specifies the value of the undefined function used by [47mbadge[0m to find the badge of a user-defined function. The second specifies the behavior of the undefined function used by [47mapply$[0m to [47mapply$[0m [47m'FOLDR[0m and requires that the second element of [47margs[0m be a [tame] function. Finally, notice that the warrant function for [47mfoldr[0m, [47mapply$-warrant-foldr[0m, ancestrally depends on [47mfoldr[0m: [47mfoldr[0m is called in the [47mdefun-sk[0m. That is crucial to avoiding the [47mLOCAL[0m problem noted in [introduction-to-apply$]. If the warrant for [47mfoldr[0m is required for a theorem's proof (which it will be if the proof involves ``expanding'' [47m(apply$ 'FOLDR ...)[0m), then the theorem is ancestrally dependent on [47mfoldr[0m even though that function symbol may not be otherwise mentioned in the theorem. That, in turn, means that [47mfoldr[0m may not be a locally defined symbol in the environment from which the theorem is exported. Now consider a function symbol that returns more than one result. Suppose the badge of [47madd-and-subtract[0m is [47m(APPLY$-BADGE 2 2 . T)[0m, meaning it takes two ordinary objects and returns two results. The function is tame and so no tameness requirements are imposed on its application. Its warrant is defined (defun-sk apply$-warrant-add-and-subtract () (forall (args) (and (equal (badge-userfn 'add-and-subtract) '(APPLY$-BADGE 2 2 . T)) (equal (apply$ 'add-and-subtract args) (mv-list 2 (add-and-subtract (car args) (cadr args))))))) Rewrite Rules that Lift and Force the Warrant Once [47mdefwarrant[0m has introduced the warrant function for [3mfn[0m it proves two rewrite rules, conjoined under the name [47mapply$-[0m[3mfn[0m, that ``lifts'' the warrant from the level of the two undefined functions to the level of [47mbadge[0m and [47mapply$[0m. In the case of [47mfoldr[0m the rules are: (defthm apply$-foldr (and (implies (force (apply$-warrant-foldr)) (equal (badge 'FOLDR) '(APPLY$-BADGE 3 1 NIL :FN NIL))) (implies (and (force (apply$-warrant-foldr)) (tamep-functionp (car (cdr args)))) (equal (apply$ 'FOLDR args) (foldr (car args) (car (cdr args)) (car (cdr (cdr args)))))))) Observe that these rules say that if [47m(apply$-warrant-foldr)[0m is available as a hypothesis, then [47m(badge 'FOLDR)[0m is [47m(APPLY$-BADGE 3 1 NIL :FN NIL)[0m and [47m(apply$ 'FOLDR args)[0m has the naively expected behavior of calling [47mfoldr[0m, provided the second element of [47margs[0m is a [47mtamep-functionp[0m. Also note that the warrant hypothesis is [47m[force][0md in both rules. The effect of these rules is if either [47m(badge 'FOLDR)[0m or any instance of [47m(apply$ 'FOLDR args)[0m arises during a proof, the warrant for [47mfoldr[0m is raised and either relieved or forced. The [47mbadge[0m and [47mapply$[0m terms are simplified whether the warrant is present or not, but if the warrant is not among the hypotheses and the proof is otherwise successful, the warrant for [47mfoldr[0m will show up in a checkpoint. If no warrant has been issued for [47mfoldr[0m these terms will not simplify. Determining the Necessary Warrants [3mThere is no easy way to determine the warrants you'll need to make a formula a theorem.[0m At first this seems to be a problem that could be solved with a few rules of thumb and indeed, there are a few useful rules. But they don't guarantee success. [3mRule 1.[0m One way to determine sufficient warrants for a formula to be a theorem is to attempt to prove the formula without warrants and see the checkpoints. This may have to be repeated to collect sufficient warrants and can be frustrating. Furthermore, as illustrated further below, it can lead to unnecessary warrants. Most users attempt to anticipate what warrants are needed. [3mRule 2.[0m You will probably need a warrant hypothesis for every user-defined function symbol mentioned in the fully translated term occupying any slot of ilk [47m:FN[0m in the formula you're trying to prove. The two common situations are quoted user-defined function symbols in such slots and [47m[lambda$][0m expressions. In the latter case, you must consider every user-defined function symbol in the [3mfully translated[0m body of the [47m[lambda$][0m expression. (If you've ignored our recommendations to use [47mlambda$[0m instead of hand-typed quoted [47mLAMBDA[0m objects, you'll have to look at those too.) But Rule 2 says ``probably need a warrant'' because whether you do or not depends on what you're proving. In the examples below, suppose we have carried out these events. (include-book "projects/apply/top" :dir :system) (defun$ sq (x) (* x x)) and recall that [47mcollect$[0m is [47m[loop$][0m scion logically defined as (defun$ collect$ (fn lst) (if (endp lst) nil (cons (apply$ fn (list (car lst))) (collect$ fn (cdr lst))))) No warrant is [3mreally[0m needed to prove (thm (equal (collect$ 'sq (append a b)) (append (collect$ 'sq a) (collect$ 'sq b)))) because it [3mcould[0m be proved by appealing to the more general (thm (equal (collect$ fn (append a b)) (append (collect$ fn a) (collect$ fn b)))) which makes clear that the properties of [47msq[0m are totally irrelevant to the proof of this formula. But if you followed Rule 1 and just submitted (thm (equal (collect$ 'sq (append a b)) (append (collect$ 'sq a) (collect$ 'sq b)))) the proof would fail with a checkpoint indicating that you need the warrant for [47msq[0m. That happens because the :rewrite rules proved by [47mdefwarrant[0m, discussed in the previous section and named [47mapply$-sq[0m in the case of [47msq[0m, fire and force that warrant. However, you could disable that rule and get the proof without a warrant. To further dim our hopes for a simple way to identify warrants, consider (defun$ square (i) (apply$ 'sq (list i))) and then the proof of (thm (equal (square i) (* i i))) This theorem requires the warrant for [47msq[0m even though [47m'sq[0m is not mentioned in the top-level statement of the theorem. The problem, of course, is that the mention of [47m'sq[0m in a [47m:FN[0m slot is mentioned in the definition of [47msquare[0m. [3mRule 3.[0m You may need warrants for any symbols used in [47m:FN[0m slots in the definitions of any function appearing in the formula. And then of course there is the usual reason you need forgotten hypotheses: some lemma critical to your proof has that hypothesis. For example, one could imagine proving (defthm lemma (implies (apply$-warrant-sq) (equal (square x) (sq x)))) and then try to prove (thm (equal (square x) (* x x)) :hints (("Goal" :in-theory (disable square)))) hoping the lemma would reduce [47m(square x)[0m to [47m(sq x)[0m and then [47m(sq x)[0m would expand to [47m(* x x)[0m. But of course, the lemma isn't applicable because we can't establish its hypothesis. The point here is that another source of required warrants can be the warrant hypotheses of any lemmas needed for the proof. We could posit a ``Rule 4'' but what's the point? Returning to the first thing we said in this section, there is no easy sure-fire way to determine the warrants you'll need. It just depends on the functions you're manipulating, the cases explored in the proof, the hypotheses of crucial lemmas, etc. However, our experience is that it's not nearly so hard as we're suggesting here! Basically you'll need a warrant for [47mfn[0m if the proof requires [47mapply$[0m to behave as naively expected on [47m'fn[0m or the warrant is required for some lemma. Chances are you'll know when you're depending on the meaning of a quoted symbol and when you're not. And Rule 1 will eventually get you there though it may generate unnecessary warrant hypotheses. There is another piece of good news perhaps best explained by example. Imagine that you've defined and warranted your own versions of the familiar list concatenation and list reverse functions under the names [47map[0m and [47mrv[0m. (defun$ ap (x y) (if (endp x) y (cons (car x) (ap (cdr x) y)))) (defun$ rv (x) (if (endp x) nil (ap (rv (cdr x)) (list (car x))))) What warrant(s) do you need to prove (implies (true-listp x) (equal (apply$ 'rv (list (apply$ 'rv (list x)))) x))? You clearly need the warrant for [47mrv[0m. But do you need the warrant for its subfunction [47map[0m? Some users fall into the trap of thinking they do. They think they'll need warrants for all the subfunctions of any function requiring a warrant. We fall into this trap when we think [3mall evaluation[0m is carried out by [47mev$[0m and [47mapply$[0m. Put another way, if we defined (defun$ rv1 (x) (if (endp x) nil (apply$ 'ap (list (rv1 (cdr x)) (list (car x)))))) and then tried to prove (implies (true-listp x) (equal (apply$ 'rv1 (list (apply$ 'rv1 (list x)))) x)) we would indeed need warrants for both [47mrv1[0m and [47map[0m, as per Rule 3, because [47mrv1[0m [47mapply$[0ms [47m'ap[0m. But the warrant for the original [47mrv[0m says that [47m(apply$ 'rv args)[0m is (unconditionally) equal to [47m(rv (car args))[0m. There are no [47mapply$[0ms left in the problem once we get to a call of the ACL2 function [47mrv[0m. We don't need any warrants, even to evaluate a function we called via [47mapply$[0m unless the definition of the function itself involves further [47mapply$[0ms. A Convenient Macro for Conjoining Warrants Because ``[47mAPPLY$-WARRANT-[0m[3mfn[0m'' is hard to remember, we provide a macro for referring to the conjunction of warrant terms for a list of functions. General Form: (warrant fn1 fn2 ... fnk) where each [47mfni[0m is the name of a defined function on which [47mdefwarrant[0m has been previously called and succeeded. (Actually, we allow the [47mfni[0m to include certain primitive function symbols already built into [47mapply$[0m, but for the moment we ignore the possible presence of such symbols among the arguments to [47mwarrant[0m.) [47m(Warrant fn1 fn2 ... fnk)[0m expands to: (AND (FORCE (APPLY$-WARRANT-fn1)) (FORCE (APPLY$-WARRANT-fn2)) ... (FORCE (APPLY$-WARRANT-fnk))) Because there are over 800 ACL2 primitives built into [47mapply$[0m, it can be hard to look at a conjecture involving, say, a [47m[lambda$][0m term, and list all and only the function names that need warrants. For example, if the body of the [47mlambda$[0m term calls [47mlogeqv[0m it will expand into [47mbinary-logeqv[0m and the diligent user might anticipate, accurately, that the [47mev$[0m of that body will involve [47m(apply$ 'BINARY-LOGEQV ...)[0m and thus might suppose that [47mbinary-logeqv[0m be included among the [47mfni[0m listed in the [47mwarrant[0m hypothesis. But no warrant for [47mbinary-logeqv[0m exists, that is, [47mapply$-warrant-binary-logeqv[0m is not defined, because [47mbinary-logeqv[0m is built into [47mapply$[0m. For this reason, we do not insist that every [47mfni[0m in [47mwarrant[0m's argument be a function possessing a warrant. Instead, the [47mwarrant[0m macro ignores those [47mfni[0m built into [47mapply$[0m. It does cause an error if one of the [47mfni[0m has no warrant and is not built in. The [47m(warrant fn1 fn2 ... fnk)[0m macro [47m[force][0ms the warrants because (a) we assume the only use of the macro is to add warrant hypotheses to conjectures and (b) by forcing warrants aggressively the prover ``almost completes'' more proofs and enters a forcing round that highlights the need to assume those warrants. When a rewrite rule, for example, is conditioned on a warrant that is not forced (as would happen if you added the hyps [47m(apply$-warrant-fn1)[0m, [47m(apply$-warrant-fn2)[0m, etc.), then the rule will not fire if a subsequent conjecture omitted the warrants. Of course, this raises the question ``But are all the warrants really true?'' Why Warrants Don't Render Theorems Vacuous Adding warrants to formulas certainly restricts (weakens) the resulting theorem since it is only applicable when the warrant is assumed. But an important question to ponder is whether adding warrants can actually make a formula vacuously valid? That is, can a set of warrants simply be unsatisfiable so that any formula having that set of warrants among its hypotheses is a theorem? Put another way, is there a model for the set of all warrants introduced by [47m[defwarrant][0m? The answer is yes. This is discussed in {``Limited Second-Order Functionality in a First-Order Setting'' | http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by Matt Kaufmann and J Strother Moore. For any set of functions warranted by [47mdefwarrant[0m it is possible to [3mdefine[0m, under the standard ACL2 definitional principle, versions of those functions (together with [47mapply$[0m, [47mev$[0m, etc.) and then make attachments to the undefined [47mbadge-userfn[0m and [47mapply$-userfn[0m, and so that every warrant is provably equal to [47mT[0m. In fact, the resultant theory is the basis of ACL2's evaluation theory where all warranted functions can be [47mapply$[0md (under the appropriate tameness requirements) without explicit mention of warrants. The crux of the proof is admitting a big mutually recursive clique containing versions of [47mapply$[0m and all of its [scion]s, by inventing a measure that provably decreases as [47mapply$[0m and the scions call each other. The keys to that measure's existence are the restrictions imposed by [47m[defwarrant][0m and [tame]ness. See the paper for a sketch of the proof and see the comment titled [47mEssay on Admitting a Model for Apply$ and the Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m.") (waterfall (pointers) "See [hints-and-the-waterfall].") (waterfall-parallelism (parallel-proof) "For ACL2(p): configuring the parallel execution of the waterfall See [set-waterfall-parallelism].") (waterfall-parallelism-for-book-certification (parallelism) "For ACL2(p): using waterfall parallelism during book certification This [documentation] topic relates to the experimental extension of ACL2 supporting parallel execution and proof; see [parallelism]. There are books whose certification can be sped up significantly by using waterfall parallelism. (See [parallelism], including the caveat in its "IMPORTANT NOTE".) One such example in the ACL2 community books is [47mmodels/jvm/m5/apprentice.lisp[0m, which is typically excluded from regressions because of how long it takes to certify. In order to use waterfall parallelism during certification of a book [47m<book-name>.lisp[0m using `make' (see [books-certification] and see [books-certification-classic]), we recommend creating a file [47m<book-name>.acl2[0m that includes the following forms. #+acl2-par (set-waterfall-parallelism t) (certify-book <book-name> ? t) ; other arguments may be preferable Note that there are books that will not certify when waterfall-parallelism is enabled. See file [47macl2-customization-files/README[0m for more information, including how to certify essentially all books using waterfall parallelism.") (waterfall-printing (parallel-proof) "For ACL2(p): configuring the printing within the parallelized waterfall See [set-waterfall-printing].") (weak-ld-history-entry-p (pointers) "See [ld-history].") (well-formed-lambda-objectp (apply$) "Predicate for recognizing well-formed [47mLAMBDA[0m objects Example: value (well-formed-lambda-objectp T '(lambda (x) (binary-+ '1 x)) (w state)) (well-formed-lambda-objectp NIL '(lambda (x) (+ 1 x)) (w state)) (well-formed-lambda-objectp T '(lambda (x) (declare (type (satisfies natp) x) (xargs :guard (natp x) :split-types t)) (binary-+ '1 x)) (w state)) (well-formed-lambda-objectp NIL '(lambda (x) (declare (type (satisfies natp) x)) (binary-+ '1 x)) (w state)) General Form: (well-formed-lambda-objectp obj wrld) [47mWell-formed-lambda-objectp[0m is a [47m:program[0m mode function that checks the well-formedness of an arbitrary ACL2 object being used as a [47mLAMBDA[0m object by [47m[apply$][0m. Before we tell you what ``well-formedness'' means in this context we collect some random related facts that we consider more important than its precise meaning! [47mLambda$[0m terms always translate to quoted well-formed [47mLAMBDA[0m objects unless translate signals an explanatory error. Don't try to type well-formed [47mLAMBDA[0m objects as explicitly quoted constants. Use [47m[lambda$][0m! Only well-formed [47mLAMBDA[0m objects can be compiled. Use [47m[lambda$][0m. But the compiled code is not necessarily always run when a well-formed [47mLAMBDA[0m object is [47mapply$[0md! The object must additionally be guard verified and its guards must be satisfied by the arguments supplied by [47mapply$[0m. Well-formedness does not do guard verification. The definitional axiom for [47m[apply$][0m knows nothing about well-formedness. It checks that the purported [47mLAMBDA[0m object satisfies [47m[tamep-lambdap][0m, which is a simpler [47m:logic[0m mode concept. If you are writing a definition or theorem about an arbitrary object to be used as a [47mLAMBDA[0m object by [47mapply$[0m, and want to restrict it to the kind of objects handled as [47mLAMBDA[0m objects by [47mapply$[0m, use the predicate [47mtamep-lambdap[0m to characterize the object. (Since [47mwell-formed-lambda-objectp[0m is in [47m:[0m[47m[program][0m mode and requires access to the world, using it in a [47m:logic[0m mode context would involve a lot of work!) Well-formedness implies tameness. So if you write your [47mLAMBDA[0m objects with [47mlambda$[0m [47mapply$[0m will be able to handle them. But [47mapply$[0m can handle more objects than the Common Lisp compiler can. Some tame [47mLAMBDA[0m objects can be applied faster than others. The fast ones are recognized by [47mwell-formed-lambda-objectp[0m -- but also have to be guard verified and guard checked. Applications of ill-formed but tame [47mLAMBDA[0m objects are evaluable, but the evaluation is done more slowly. See the performance comparison in [47m[print-cl-cache][0m. We compare well-formedness to tameness at the end of this topic. You can't call this predicate on a [47mlambda$[0m term, as by (well-formed-lambda-objectp (lambda$ (x) x) (w state)) because [47mlambda$[0m can only be called in slots of ilk [47m:FN[0m. Furthermore, there's no point! [47mLambda$[0m terms always translate to well-formed [47mLAMBDA[0m objects unless an explanatory error is signaled by translation. If you want to [3msee[0m the translation of a [47mlambda$[0m term, e.g., to copy the text and modify it to produce some similar [47mLAMBDA[0m object, use [47m:[0m[47m[translam][0m. We sometimes do this to explore by example the restrictions on well-formedness. If you have a [47mLAMBDA[0m object, e.g., one printed by [47m[print-cl-cache][0m, that you suspect is ill-formed, this function won't tell you [3mwhy[0m it is ill-formed! It will just tell you whether it's ill-formed. If you want to know why, translate the quoted [47mLAMBDA[0m object with [47m:[0m[47m[translam][0m, which generates sometimes verbose error messages. The global setting of [47mset-ignore-ok[0m has no effect on well-formedness of [47mLAMBDA[0m objects. [47mIGNORE[0m and [47mIGNORABLE[0m declarations inside the [47mLAMBDA[0m are effective. ACL2 !>(set-ignore-ok t) T ACL2 !>(well-formed-lambda-objectp '(LAMBDA (X Y) (DECLARE (XARGS :GUARD (NATP X) :SPLIT-TYPES T)) (BINARY-+ '1 X)) (w state)) NIL ACL2 !>(well-formed-lambda-objectp '(LAMBDA (X Y) (DECLARE (XARGS :GUARD (NATP X) :SPLIT-TYPES T) (IGNORE Y)) (BINARY-+ '1 X)) (w state)) T There should be very few occasions on which you need to know what this predicate checks! That said, here are the rules enforced. An object is a well-formed [47mLAMBDA[0m object iff it has one of the following two forms: (LAMBDA vars tbody) ; ``simple'' LAMBDA object (LAMBDA vars tdcl tbody) ; ``declared'' LAMBDA object where * [47mvars[0m is a list of distinct legal variable names * [47mtdcl[0m, if present, is a [47mDECLARE[0m form containing, at most, [47mTYPE[0m, [47mIGNORE[0m, [47mIGNORABLE[0m, and [47mXARGS[0m keys. The user of [47m[lambda$][0m may provide multiple [47mDECLARE[0m forms but when translated they are combined into one as shown here. * If an [47mXARGS[0m key is present it has exactly this form [47m(XARGS :GUARD tguard :SPLIT-TYPES T)[0m, where [47mtguard[0m is a [3mfully translated[0m logic mode term involving only the formal variables, [47mvars[0m. Note that the user of [47m[lambda$][0m may supply [47m:SPLIT-TYPES[0m [47mNIL[0m and may do so before or after the [47m:GUARD[0m, and the guard term need not be in translated form, but the resulting [47mLAMBDA[0m object has the form described here. * The [47m:GUARD[0m specified in [47mXARGS[0m must include as a conjunct every [47mTYPE[0m expression generated by any [47mTYPE[0m specs. E.g., [47m(INTEGERP x)[0m must be a conjunct of [47mtguard[0m if [47m(TYPE INTEGER ... x ...)[0m is declared. That is consistent with the [47m:SPLIT-TYPES[0m [47mT[0m setting and means the guard does not need to be extended any further with the [47mTYPES[0m. The point of this restriction is to guarantee that the guard implies the types declared to the compiler. But this is a purely syntactic check and so may at times require entering silly-looking guards. For example, [47m(declare (type rational x) (xargs :guard (integerp x) :split-types t))[0m is ruled ill-formed because [47m(rationalp x)[0m is not a conjunct of the guard, even though it is logically implied by the guard. So you'd have to use [47m(declare (type rational x) (xargs :guard (if (integerp x) (rationalp x) 'nil) :split-types t))[0m. Note also that the guard is a fully translated conjunction, i.e., an [47mIF[0m, not an [47mAND[0m! Order of the conjuncts does not matter. Note: The guard need not be tame (or even fully badged) because guards are irrelevant to the axioms of [47mapply$[0m. But guards must be in [47m:logic[0m mode from the outset because we may have to prove guard obligations on-the-fly in evaluation (we do not want to try to convert functions used in the guard from from [47m:program[0m to [47m:logic[0m mode while doing an evaluation of an [47mapply$[0m). * [47mtbody[0m is a fully translated, [tame] term, involving no free variables and respecting the declared [47mIGNORE[0m and [47mIGNORABLE[0m declarations. Furthermore, in the case of a lambda object generated by [47mlambda$[0m, [47mtbody[0m is a ``tagged'' version of the translation of the body used in the [47mlambda$[0m expression. Tagging involves use of a special form generated by [47mtag-translated-lambda$-body[0m and recognized by [47mlambda$-bodyp[0m. This form contains the untranslated [47mlambda$[0m expression as well as the translation of its body. For example, [47m(lambda$ (x) (+ 1 x))[0m translates to the tagged lambda object [47m'(LAMBDA (X) (RETURN-LAST 'PROGN 'orig-form tbody))[0m, where [47morig-form[0m is [47m(LAMBDA$ (X) (+ 1 X))[0m and [47mtbody[0m is [47m(BINARY-+ '1 X)[0m. It may be helpful to use [47m:[0m[47m[translam][0m to inspect examples of the translations of [47mlambda$[0m expressions. The Differences Between Well-Formed and Merely Tame Lambda Objects Roughly put, tame [47mLAMBDA[0m objects have to have one of the two basic shapes described above (simple or declared), the listed formals merely have to be symbols -- not necessarily variable symbols and not necessarily distinct. The declaration, if present, is completely irrelevant and the body merely has to be a tame expression -- not necessarily closed with respect to the formals or respecting [47mIGNORE[0m or [47mIGNORABLE[0m declarations. The meaning assigned to such an object when applied to some arguments is just the result delivered by [47mev$[0m under an alist formed by pairing the formals -- including non-variables and any duplicates -- with the actuals. If a free variable is encountered, [47mev$[0m gives it the value [47mNIL[0m courtesy of [47massoc[0m. This behavior is implemented by compiled Common Lisp only when well-formedness, guard verification, and guard checking approve of the object and its application.") (well-formedness-guarantee (rule-classes) "Guarantee that a metafunction or clause-processor returns a well-formed answer A [47m:well-formedness-guarantee[0m is a keyword attribute available in the [47m:[0m[47m[meta][0m and [47m:[0m[47m[clause-processor][0m [47m:[0m[47m[rule-classes][0m. By default, when a metafunction or clause processor is applied, ACL2 checks that the output is well-formed (and does not contain certain ``forbidden'' functions; see [47m[set-skip-meta-termp-checks][0m). By providing a [47m:well-formedness-guarantee[0m when you store a [47m:meta[0m or [47m:clause-processor[0m rule, you can cause ACL2 to skip these runtime checks. This is considered an advanced feature that requires that you prove certain theorems; this is probably only worthwhile if your metafunctions or clause processors produce very large terms. Henceforth, we assume you are familiar with metafunctions and clause processors. This topic first exhibits a simple example of a well-formedness guarantee for a metafunction. This example is really an outline; a self-contained, runnable example may be found in the [community-books] in file [47mbooks/demos/meta-wf-guarantee-example.lisp[0m. Then we describe the acceptable values of the [47m:well-formedness-guarantee[0m keyword of both the [47m:meta[0m and [47m:clause-processor[0m rule-classes. Next we show the forms of the theorems you must prove to provide such guarantees. Finally, we discuss the runtime effects of providing such guarantees. Example Suppose that [47mfn[0m is a vanilla metafunction that rewrites terms with top function symbol [47mTARGET[0m, of [47m[arity][0m 1. The event storing [47mfn[0m as a metafunction would normally be something like this: (defthm fn-is-correct (implies (and (pseudo-termp x) (alistp a)) (equal (evl x a) (evl (fn x) a))) :rule-classes ((:meta :trigger-fns (TARGET)))) where [47mevl[0m is an evaluator for all the function symbols known to [47mfn[0m. Suppose that to prove this theorem, [47mevl[0m must be able to interpret the symbols [47mTARGET[0m, [47mCONS[0m, and [47mIF[0m. While the metatheorem for [47mfn[0m establishes that [47mfn[0m returns something with the same ``meaning'' (under [47mevl[0m) as its input, it does not answer the question: does [47mfn[0m return a well-formed term, all of whose function symbols are in [47m:[0m[47m[logic][0m mode? Given the above [47m:rule-class[0m, whenever the simplifier fires the [47m:meta[0m rule [47mfn-is-correct[0m by applying [47mfn[0m to a term, it checks that the value, [47mval[0m, is well-formed, by evaluating [47m(logic-termp val (w state))[0m. The function [47m[logic-termp][0m checks that its argument is a [term] all of whose function symbols are in [47m:logic[0m mode. [31;1mFunction: [0m<logic-termp> (defun logic-termp (x wrld) (declare (xargs :guard (plist-worldp-with-formals wrld))) (and (termp x wrld) (logic-fnsp x wrld))) The [47mlogic-termp[0m check can be avoided if, before you store the rule [47mfn-is-correct[0m, you prove: (defthm fn-is-well-formed (implies (and (logic-termp x w) (arities-okp '((TARGET . 1) (CONS . 2) (IF . 3)) w)) (logic-termp (fn x) w)) :rule-classes nil) and then you store [47mfn-is-correct[0m this way: (defthm fn-is-correct (implies (and (pseudo-termp x) (alistp a)) (equal (evl x a) (evl (fn x) a))) :rule-classes ((:meta :trigger-fns (TARGET) :well-formedness-guarantee fn-is-well-formed))) Acceptable Values Now we describe the values you may provide with the [47m:well-founded-guarantee[0m keyword of the [47m:meta[0m and the [47m:clause-processor[0m rule-classes. General Forms: :well-formedness-guarantee thm-name1 :well-formedness-guarantee (thm-name1) :well-formedness-guarantee (thm-name1 thm-name2) where both [47mthm-name1[0m and [47mthm-name2[0m are the names of previously proved ``well-formedness theorems'' (see the next section); furthermore, [47mthm-name1[0m must be about the metafunction or clause processor being introduced, and [47mthm-name2[0m must be about the hypothesis metafunction (if any) associated with the metafunction. For [47m:meta[0m rules, all three forms are accepted, but the last form is required if the [47m:meta[0m rule involves a hypothesis metafunction. That is, to provide a [47m:well-formedness-guarantee[0m for a metatheorem with a hypothesis metafunction, you must supply both [47mthm-name1[0m and [47mthm-name2[0m. For [47m:clause-processor[0m rules, you must use the first form. Each well-formedness theorem provides an ``arity alist'' that specifies the assumed arities of the function symbols known to the metafunction or clause processor. The arities shown for the function symbols listed in that alist must be the same as the arities of those functions in the actual ACL2 logical [world] current at the time the [47m:meta[0m or [47m:clause-processor[0m is stored. Moreover, the function symbols in that alist must all be in [47m:[0m[47m[logic][0m mode. Furthermore, none of the function symbols in the arity alists should be ``forbidden'' function symbols as explained in [47m[set-skip-meta-termp-checks][0m. When the [47m:meta[0m or [47m:clause-processor[0m rule is stored, notes are made that will prevent the function symbols on the arity alists from becoming untouchable (and thus forbidden). See [47m[push-untouchable][0m. The only way a function's arity or forbidden status can change, or that a function can transition out of [47m:logic[0m mode, is if the user has engaged in redefinition or activated a trust tag to add or remove untouchables. Thus, the restrictions above are unimportant to most users. Well-Formedness Theorems Theorems must be proved to establish that metafunctions and clause processors return well-formed results. These are called ``well-formedness theorems.'' Note: To say a theorem is a ``well-formedness theorem'' is a remark about the shape of the formula, not its rule-class. There is no [47m:well-formedness-theorem[0m rule-class and a well-formedness theorem may be stored with any [47m:[0m[47m[rule-classes][0m that accept the syntax of the formula or as [47m:rule-classes[0m [47mnil[0m. Indeed, if one of your metafunctions uses another function to produce a subterm of the metafunction's answer, you might need to prove a well-formedness theorem for the sub-function and make it a [47m:rewrite[0m rule. Well-formedness theorems for metafunctions and clause processors are similar but slightly different. We deal with metafunctions and their corresponding hypothesis metafunctions (if any) first. The shapes of the well-formedness theorems for a metafunction and hypothesis metafunction are identical, but remember that you must prove a well-formedness theorem for both the metafunction and the associated hypothesis metafunction. So suppose [47mfn[0m is a metafunction or a hypothesis metafunction and let [47m(fn x ...)[0m be a legal call on distinct variable symbols. (Recall that extended metafunctions and their hypothesis functions can take three arguments.) Then the general form a well-formedness theorem for [47mfn[0m states that [47mfn[0m returns a [47m[termp][0m when given one, provided the arities of certain function symbols are as expected: General Form of Well-Formedness Theorem for a Metafunction: (implies (and (logic-termp x w) (arities-okp '<alist> w)) (logic-termp (fn x ...) w)) where [47m<alist>[0m is an alist pairing function symbols with their assumed arities as illustrated in the opening example. Note that the first argument of [47marities-okp[0m in the theorem is a quoted constant. You may omit or reorder the hypotheses above and you may use different variable symbols in place of [47mx[0m and [47mw[0m, but they must be distinct and different from the variables in the ``[47m...[0m.'' An example of [47m<alist>[0m is [47m((TARGET . 1) (CONS . 2) (IF . 3))[0m. Generally, the [47m<alist>[0m you provide should assign arities to every symbol known to [47mfn[0m, i.e., every function symbol known to the evaluator used in your correctness theorem. If you inspect the definition of [47m[termp][0m you will see that it uses [47mw[0m to obtain arities of the function symbols in [47mx[0m. The [47m[arities-okp][0m hypothesis restricts [47mw[0m to worlds where the function symbols known to [47mfn[0m have the arities you expect and are in [47m:[0m[47m[logic][0m-mode. For example, given the [47m(arities-okp '<alist> w)[0m hypothesis for the [47m<alist>[0m above, the theorem prover will rewrite [47m(arity 'IF w)[0m to 3. By default [47m[arity][0m and [47m[arities-okp][0m are disabled; and the following rewrite rules, which are part of ACL2's initial [world], will take care of calls like [47m(arity 'IF w)[0m and [47m(logicp fn w)[0m. [31;1mTheorem: [0m<arities-okp-implies-arity> (defthm arities-okp-implies-arity (implies (and (arities-okp user-table w) (assoc fn user-table)) (equal (arity fn w) (cdr (assoc fn user-table))))) [31;1mTheorem: [0m<arities-okp-implies-logicp> (defthm arities-okp-implies-logicp (implies (and (arities-okp user-table w) (assoc fn user-table)) (logicp fn w))) Now we turn to the well-formedness theorem for a clause processor, [47mcl-proc[0m. Let [47m(cl-proc x ...)[0m be a legal call on distinct variable symbols. The theorem establishes that [47mcl-proc[0m returns a list of clauses when given a clause, provided certain functions have the expected arities. But the recognizer for a clause is the function [47m[logic-term-listp][0m and the recognizer for a list of clauses is [47m[logic-term-list-listp][0m: General Forms of Well-Formedness Theorem for a Clause Processor (implies (and (logic-term-listp x w) (arities-okp '<alist> w)) (logic-term-list-listp (cl-proc x ...) w)) (implies (and (logic-term-listp x w) (arities-okp '<alist> w)) (logic-term-list-listp (clauses-result (cl-proc x ...)) w)) The first form above is for a [47mcl-proc[0m that returns a single value and the second form is for a [47mcl-proc[0m that returns multiple values. The discussion about metafunctions, above, applies here as well. [47m<Alist>[0m is an alist pairing function symbols with their assumed arities. You may omit or reorder the hypotheses and you may use different variable symbols in place of [47mx[0m and [47mw[0m, but they must be distinct and different from the variables in the ``[47m...[0m.'' Runtime Effects In the absence of a [47m:well-formedness-guarantee[0m, if a metafunction or clause processor is applied during a proof and produces [47mval[0m, then certain checks are made on [47mval[0m before it is used in the proof attempt. In the case of a metafunction, [47m(logic-termp val (w state))[0m is checked and [47mval[0m is scanned to ensure that it contains no forbidden function symbols. In the case of a clause processor, [47m(logic-term-list-listp val (w state))[0m is checked and [47mval[0m is scanned to ensure that it contains no forbidden function symbols. If [47mval[0m is large (e.g., because the input is large), these checks can take more time than the metafunction or clause processor did to produce [47mval[0m! It is for this reason that we provide for [47m:well-formedness-guarantee[0ms. When a [47m:well-formedness-guarantee[0m is provided no checks are made on [47mval[0m. However, ACL2 will check that the arity alist(s) involved in the guarantee still correctly shows the arities of the function symbols listed. Because those function symbols were not forbidden when the guarantee was made and are prohibited from being forbidden thereafter, no check is necessary to ensure that no forbidden symbols are introduced into the proof.") (well-founded-relation (rule-classes) "Show that a relation is well-founded on a set See [well-founded-relation-rule] for discussion of well-founded relations in ACL2. A related utility, [47mget-well-founded-relation[0m, may be found in the [community-books], file [47mstd/system/get-well-founded-relation.lisp[0m.") (well-founded-relation-rule (rule-classes) "Show that a relation is well-founded on a set See [rule-classes] for a general discussion of rule classes, including how they are used to build rules from formulas and a discussion of the various keywords in a rule class description. Example: (defthm lex2p-is-well-founded-relation (and (implies (pairp x) (o-p (ordinate x))) (implies (and (pairp x) (pairp y) (lex2p x y)) (o< (ordinate x) (ordinate y)))) :rule-classes :well-founded-relation) The example above creates a [47m:well-founded-relation[0m rule, where of course the functions [47mpairp[0m, [47mlex2p[0m, and [47mordinate[0m would have to be defined first. It establishes that [47mlex2p[0m is a well-founded relation on [47mpairp[0ms. We explain and give details below. Exactly two general forms are recognized: General Forms (AND (IMPLIES (mp x) (O-P (fn x))) ; Property 1 (IMPLIES (AND (mp x) ; Property 2 (mp y) (rel x y)) (O< (fn x) (fn y)))), or (AND (O-P (fn x)) ; Property 1 (IMPLIES (rel x y) ; Property 2 (O< (fn x) (fn y)))) where [47mmp[0m, [47mfn[0m, and [47mrel[0m are function symbols, [47mx[0m and [47my[0m are distinct variable symbols, and no other [47m:well-founded-relation[0m theorem about [47mfn[0m has been proved. When the second general form is used, we act as though the first form were used with [47mmp[0m being the function that ignores its argument and returns [47mt[0m. The discussion below therefore considers only the first general form. Note: We are very rigid when checking that the submitted formula is of one of these forms. For example, in the first form, we insist that all the conjuncts appear in the order shown above. Thus, interchanging the two properties in the top-level conjunct or rearranging the hypotheses in the second conjunct both produce unrecognized forms. The requirement that each [47mfn[0m be proved well-founded at most once ensures that for each well-founded relation, [47mfn[0m, there is a unique [47mmp[0m that recognizes the domain on which [47mrel[0m is well-founded. We impose this requirement simply so that [47mrel[0m can be used as a short-hand when specifying the well-founded relations to be used in definitions; otherwise the specification would have to indicate which [47mmp[0m was to be used. We also insist that the new ordering be embedded into the ordinals as handled by [47m[o-p][0m and [47m[o<][0m and not some into previously admitted user-defined well-founded set and relation. This restriction should pose no hardship. If [47mmp[0m and [47mrel[0m were previously shown to be well-founded via the embedding [47mfn[0m, and you know how to embed some new set and relation into [47mmp[0m and [47mrel[0m, then by composing [47mfn[0m with your new embedding and using the previously proved well-founded relation lemma you can embed the new set and relation into the ordinals. [47mMp[0m is a predicate that recognizes the objects that are supposedly ordered in a well-founded way by [47mrel[0m. We call such an object an ``[47mmp[0m-measure'' or simply a ``measure'' when [47mmp[0m is understood. Property 1 tells us that every measure can be mapped into an ACL2 ordinal. (See [o-p].) This mapping is performed by [47mfn[0m. Property 2 tells us that if the measure [47mx[0m is smaller than the measure [47my[0m according to [47mrel[0m, then the image of [47mx[0m under [47mfn[0m is smaller than that of [47my[0m, according to the well-founded relation [47m[o<][0m. (See [o<].) Thus, the general form of a [47m:well-founded-relation[0m formula establishes that there exists a [47mrel[0m-order preserving embedding (namely via [47mfn[0m) of the [47mmp[0m-measures into the ordinals. We can thus conclude that [47mrel[0m is well-founded on [47mmp[0m-measures. Such well-founded relations are used in the admissibility test for recursive functions, in particular, to show that the recursion terminates. To illustrate how such information may be used, consider a generic function definition (defun g (x) (if (test x) (g (step x)) (base x))). If [47mrel[0m has been shown to be well-founded on [47mmp[0m-measures, then [47mg[0m's termination can be ensured by finding a measure, [47m(m x)[0m, with the property that [47mm[0m produces a measure: (mp (m x)), ; Defun-goal-1 and that the argument to [47mg[0m gets smaller (when measured by [47mm[0m and compared by [47mrel[0m) in the recursion, (implies (test x) (rel (m (step x)) (m x))). ; Defun-goal-2 If [47mrel[0m is selected as the [47m:well-founded-relation[0m to be used in the definition of [47mg[0m, the definitional principal will generate and attempt to prove [47mdefun-goal-1[0m and [47mdefun-goal-2[0m to justify [47mg[0m. We show later why these two goals are sufficient to establish the termination of [47mg[0m. Observe that neither the ordinals nor the embedding, [47mfn[0m, of the [47mmp[0m-measures into the ordinals is involved in the goals generated by the definitional principal. Suppose now that a [47m:well-founded-relation[0m theorem has been proved for [47mmp[0m and [47mrel[0m. How can [47mrel[0m be ``selected as the [47m:well-founded-relation[0m'' by [47m[defun][0m? There are two ways. First, an [47m[xargs][0m keyword to the [47m[defun][0m event allows the specification of a [47m:well-founded-relation[0m. Thus, the definition of [47mg[0m above might be written (defun g (x) (declare (xargs :well-founded-relation rel)) (if (test x) (g (step x)) (base x))) Alternatively, [47mrel[0m may be specified as the [47m:default-well-founded-relation[0m in [47m[ACL2-defaults-table][0m by executing the event (set-well-founded-relation rel). When a [47m[defun][0m event does not explicitly specify the relation in its [47m[xargs][0m the default relation is used. When ACL2 is initialized, the default relation is [47m[o<][0m. Finally, though it is probably obvious, we now show that [47mdefun-goal-1[0m and [47mdefun-goal-2[0m are sufficient to ensure the termination of [47mg[0m provided [47mproperty-1[0m and [47mproperty-2[0m of [47mmp[0m and [47mrel[0m have been proved. To this end, assume we have proved [47mdefun-goal-1[0m and [47mdefun-goal-2[0m as well as [47mproperty-1[0m and [47mproperty-2[0m and we show how to admit [47mg[0m under the primitive ACL2 definitional principal (i.e., using only the ordinals). In particular, consider the definition event (defun g (x) (declare (xargs :well-founded-relation o< :measure (fn (m x)))) (if (test x) (g (step x)) (base x))) Proof that [47mg[0m is admissible: To admit the definition of [47mg[0m above we must prove (o-p (fn (m x))) ; *1 and (implies (test x) ; *2 (o< (fn (m (step x))) (fn (m x)))). But *1 can be proved by instantiating [47mproperty-1[0m to get (implies (mp (m x)) (o-p (fn (m x)))), and then relieving the hypothesis with [47mdefun-goal-1[0m, [47m(mp (m x))[0m. Similarly, *2 can be proved by instantiating [47mproperty-2[0m to get (implies (and (mp (m (step x))) (mp (m x)) (rel (m (step x)) (m x))) (o< (fn (m (step x))) (fn (m x)))) and relieving the first two hypotheses by appealing to two instances of [47mdefun-goal-1[0m, thus obtaining (implies (rel (m (step x)) (m x)) (o< (fn (m (step x))) (fn (m x)))). By chaining this together with [47mdefun-goal-2[0m, (implies (test x) (rel (m (step x)) (m x))) we obtain *2. Q.E.D.") (wet (trace) "Evaluate a form and print subsequent error trace The acronym ``wet'' stands for ``with-error-trace''. [47mWet[0m provides a convenient way to obtain a backtrace when evaluation causes a guard violation or other error. Summary Documentation General Form: (wet form ; an arbitrary form :book bk-form ; optional, not evaluated; specify different wet book ;;; the rest are optional and evaluated: :compile c ; :same, t, or nil; default :same (nil if :fns supplied) :fullp h ; nil by default, else handle some raw Lisp errors :evisc-tuple e ; an evisc-tuple :fns fns ; :all, or a list of functions to show in a backtrace [47mForm[0m is evaluated. If there is an error, a backtrace stack is printed to the standard output ([47m[*standard-co*][0m), containing (by default) the user-defined function calls made before the error. Such printing is controlled by the [47m:evisc-tuple[0m if supplied; otherwise, hiding of large structures will occur. Discussion The basic idea is that [47m(wet form)[0m evaluates [47mform[0m and, if there is an error, shows a backtrace of calls that led to that error. Note however that by default only calls of user-defined (not built-in) functions ``supporting'' [47mform[0m in the following sense will show up in the backtrace: those that occur in the macroexpansion of [47mform[0m or (recursively) support any of those functions. So for example, since [47m(make-event form)[0m macroexpands to [47m(make-event-fn (quote form) ...)[0m, calls of functions occurring in [47mform[0m will likely not show up in the backtrace by default. The option [47m:fns all[0m overrides this default, with potential loss of speed; more on this below. The following example explains the use of [47mwet[0m. First, submit the following three definitions: (defun foo (x) (declare (xargs :guard (consp x))) (car x)) (defun bar (x) (foo (cdr x))) (defun g (x) (bar (cdr x))) Now imagine you have obtained the following guard violation: ACL2 !>(g '(3 4)) ACL2 Error in TOP-LEVEL: The guard for the function call (FOO X), which is (CONSP X), is violated by the arguments in the call (FOO NIL). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. ACL2 !> With [47mwet[0m, you can get a backtrace of user-defined functions. The package prefixes shown below, [47mACL2_*1*_[0m, indicate that the executable-counterparts of the corresponding submitted functions are being called; see [evaluation]. Don't forget to start with [47m(include-book "misc/wet" :dir :system)[0m. ACL2 !>(wet (g '(3 4))) ; Fast loading /projects/acl2/devel/books/misc/wet.fasl TTAG NOTE: Adding ttag :TRACE! from the top level loop. ACL2 Error in WET: The guard for the function call (FOO X), which is (CONSP X), is violated by the arguments in the call (FOO NIL). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. Backtrace stack: ---------------- 1. (ACL2_*1*_ACL2::FOO NIL) 2. (ACL2_*1*_ACL2::BAR (4)) 3. (ACL2_*1*_ACL2::G (3 4)) ACL2 !> By default, large structures are hidden during the printing of the backtrace stack. (Technical detail: by default the global abbrev-evisc-tuple is used, if bound; see [set-evisc-tuple]. But you can supply a value for keyword argument [47m:evisc-tuple[0m to modify the printing: [47mnil[0m to avoid hiding, else a suitable evisc-tuple, as shown below (see [evisc-tuple]). ACL2 !>(wet (g '(3 4)) :evisc-tuple (evisc-tuple 1 1 nil nil)) ; Fast loading /projects/acl2/devel/books/misc/wet.fasl TTAG NOTE: Adding ttag :TRACE! from the top level loop. ACL2 Error in WET: The guard for the function call (FOO X), which is (CONSP X), is violated by the arguments in the call (FOO NIL). To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. Backtrace stack: ---------------- 1. (ACL2_*1*_ACL2::FOO ...) 2. (ACL2_*1*_ACL2::BAR ...) 3. (ACL2_*1*_ACL2::G ...) ACL2 !> For a backtrace as a data object, evaluate the form [47m(@ wet-stack)[0m. But note that this object may not be a legal ACL2 value, for example because of the ``[47m*1*[0m'' symbols shown above. Keyword Arguments The [47m:fullp[0m option. Consider the following example. (program) (defun foo (x) (declare (xargs :guard (consp x))) (car x)) (defun bar (x) (foo (cdr x))) (defun g (x) (bar (cdr x))) ; Raw Lisp error: (g '(3 4 . 5)) We may be initially disappointed using [47mwet[0m on this example, as follows --- it didn't work! ACL2 p!>(wet (g '(3 4 . 5))) TTAG NOTE: Adding ttag :TRACE! from the top level loop. *********************************************** ************ ABORTING from raw Lisp *********** ********** (see :DOC raw-lisp-error) ********** Error: Fault during read of memory address #x2D While executing: FOO *********************************************** The message above might explain the error. If not, and if you didn't cause an explicit interrupt (Control-C), then it may help to see :DOC raw-lisp-error. To enable breaks into the debugger (also see :DOC acl2-customization): (SET-DEBUGGER-ENABLE T) ACL2 p!> The fix is to use [47m:fullp t[0m. ACL2 p!>(wet (g '(3 4 . 5)) :fullp t) TTAG NOTE: Adding ttag :TRACE! from the top level loop. ACL2 Error in WET: The guard for the :program function call (FOO X), which is (CONSP X), is violated by the arguments in the call (FOO 5). See :DOC set-guard-checking for information about suppressing this check with (set-guard-checking :none), as recommended for new users. To debug see :DOC print-gv, see :DOC trace, and see :DOC wet. Backtrace stack: ---------------- 1. (ACL2_*1*_ACL2::FOO 5) 2. (ACL2_*1*_ACL2::BAR (4 . 5)) 3. (ACL2_*1*_ACL2::G (3 4 . 5)) ACL2 p!> Why doesn't [47mwet[0m always do things this way? The answer pertains to performance. When [47m:fullp[0m is non-nil, [47mwet[0m sets guard-checking to [47m:all[0m before evaluating the given form; see [set-guard-checking]. This may slow down evaluation substantially, which is why it is not the default behavior. The [47m:fns[0m option. As mentioned above, by default the [47mwet[0m backtrace shows user-defined functions that syntactically ``support'' the form being evaluated. This default can be overridden by supplying an explicit list, [47mfns[0m, of functions, using option [47m:fns fns[0m; these will then be the functions whose calls are eligible for inclusion in the backtrace. The special value [47m:fns :all[0m will allow all user-defined function calls in the backtrace. This value can be useful when using [47m[magic-ev-fncall][0m, for example, since the function being applied isn't typically included as a syntactic supporter of the form being evaluated. The [47m:compile[0m option. [47mWet[0m uses the [47m[trace$][0m utility to modify the definitions of affected functions so that they can record information for the backtrace. As described above, these affected functions are those that syntactically ``support'' the form unless specified by the [47m:fns[0m option. As is the case for [47mtrace$[0m --- see [trace$] --- the new definitions of these affected functions may or may not be compiled. For [47mtrace$[0m and for [47mwet[0m, the default is to compile the new definition if and only if the original definition was compiled, except: For [47mwet[0m, if option [47m:fns :all[0m is provided, then the default is not to compile the affected definitions. And for [47mtrace$[0m and [47mwet[0m, the [47m:compile[0m option overrides the default, to specify what will be compiled: value [47m:same[0m to compile each affected function if and only if its original definition was compiled, value [47mt[0m to compile all affected functions, and value [47mnil[0m to skip compilation. The [47m:book[0m option. [47mWet[0m actually works by temporarily including a community book, (include-book "misc/wet" :dir :system) and then passing its arguments to macro [47mwet![0m, defined in that book. The keyword argument [47m:book[0m allows you to specify a different book that defines a macro [47mwet![0m to which to pass its arguments. If the value of [47m:book[0m is a string, then the book named by that string is temporarily included using [47m[include-book][0m: [47m(include-book "bk")[0m. Otherwise [47m:book[0m should be a list of arguments, to be provided (unevaluated) to [47m[include-book][0m, for example [47m("my-wet" :dir :my-utils)[0m. Thus you can experiment by copying community book [47mbooks/misc/wet.lisp[0m to your own directory and making modifications to the copy. If you make changes, we invite you to share them with the ACL2 community (see [books]). Note that you can also supply [47m:book nil[0m, in which case the definition of [47mwet![0m in your current session will be used without including a book. Concluding Remark Also see [trace$] for a general tracing utility. As mentioned above, [47mwet[0m is implemented using [47mtrace$[0m. [47mWet[0m actually first applies [47m[untrace$][0m; upon completion, [47mwet[0m then applies [47m[trace$][0m to re-trace any functions that it had untraced, using their original trace specs.") (|WHAT_IS_ACL2{Q}| (pages_written_especially_for_the_tours) "What Is ACL2? {IMAGE} (see [What_is_a_Mathematical_Logic{Q}]) ACL2 is a [31;1mmathematical logic[0m together with a [31;1mmechanical theorem prover[0m to help you reason in the logic. The logic is just a subset of applicative Common Lisp (see [Common_Lisp]). (This link takes you off the main route of the tour. You'll see some Common Lisp on the tour, so visit this later!) The theorem prover is an ``industrial strength'' version of the Boyer-Moore theorem prover, Nqthm. [31;1mModels[0m of all kinds of computing systems can be built in ACL2, just as in Nqthm, even though the formal logic is Lisp. Once you've built an ACL2 model of a system, you can run it. You can also use ACL2 to prove theorems about the model. {IMAGE} (see [What_is_a_Mathematical_Logic{Q}])") (|WHAT_IS_A_MATHEMATICAL_LOGIC{Q}| (pages_written_especially_for_the_tours) "What is a Mathematical Logic? {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}]) {IMAGE} A mathematical logic is a formal system of formulas ([31;1maxioms[0m) and [31;1mrules[0m for deriving other formulas, called [31;1mtheorems[0m. A [31;1mproof[0m is a derivation of a theorem. To see a concrete proof tree, click here (see [A_Trivial_Proof]). Why should you care? The neat thing about Theorems is that they are ``true.'' More precisely, if all the axioms are valid and the rules are validity preserving, then anything derived from the axioms via the rules is valid. So, if you want to determine if some formula is true, [31;1mprove it[0m. {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}])") (|WHAT_IS_A_MECHANICAL_THEOREM_PROVER{Q}| (pages_written_especially_for_the_tours) "What is a Mechanical Theorem Prover? {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}_{cont}]) A [31;1mmechanical theorem prover[0m is a computer program that finds proofs of theorems. {IMAGE} The ideal mechanical theorem prover is [31;1mautomatic[0m: you give it a formula and it gives you a proof of that formula or tells you there is no proof. Unfortunately, automatic theorem provers can be built only for very simple logics (e.g., [31;1mpropositional calculus[0m) and even then practical considerations (e.g., how many centuries you are willing to wait) limit the problems they can solve. {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}_{cont}])") (|WHAT_IS_A_MECHANICAL_THEOREM_PROVER{Q}_{CONT}| (pages_written_especially_for_the_tours) "What is a Mechanical Theorem Prover? (cont) {IMAGE} (see [About_Models]) To get around this, mechanical theorem provers often require help from the [31;1muser[0m. {IMAGE} Click here (see [ACL2_as_an_Interactive_Theorem_Prover]) to continue downward. {IMAGE} (see [About_Models])") (|WHAT_IS_REQUIRED_OF_THE_USER{Q}| (pages_written_especially_for_the_tours) "What is Required of the User? {IMAGE} (see [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}]) It is not easy to build ACL2 models of complex systems. To do so, the user must [31;1munderstand[0m * the system being modeled, and * ACL2, at least as a programming language. It is not easy to get ACL2 to prove hard theorems. To do so, the user must [31;1munderstand[0m * the model, * ACL2 as a mathematical logic, and * be able to construct a proof (in interaction with ACL2). ACL2 will help construct the proof but its primary role is to prevent logical mistakes. The creative burden --- the mathematical insight into [31;1mwhy the model has the desired property[0m --- is the user's responsibility. {IMAGE} (see [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}])") (when$ (pointers) "See [loop$].") (when$+ (pointers) "See [loop$].") (why-brr (break-rewrite) "An explanation of why ACL2 has an explicit [47m[brr][0m mode Why isn't [47m[brr][0m mode automatically disabled when there are no monitored runes? The reason is that the list of monitored runes is kept in a wormhole state. See [wormhole] for more information on wormholes in general. But the fundamental property of the wormhole function is that it is a logical [47mno-op[0m, a constant function that does not take state as an argument. When entering a wormhole, arbitrary information can be passed in (including the external state). That information is used to construct a near copy of the external state and that ``wormhole state'' is the one with respect to which interactions occur during breaks. But no information is carried by ACL2 out of a wormhole --- if that were allowed wormholes would not be logical no-ops. The only information carried out of a wormhole is in the user's head. [47m[Break-rewrite][0m interacts with the user in a wormhole state because the signature of the ACL2 rewrite function does not permit it to modify [47m[state][0m. Hence, only wormhole interaction is possible. (This has the additional desirable property that the correctness of the rewriter does not depend on what the user does during interactive breaks within it; indeed, it is logically impossible for the user to affect the course of [47m[rewrite][0m.) Now consider the list of monitored runes. Is that kept in the external state as a normal state global or is it kept in the wormhole state? If it is in the external state then it can be inspected within the wormhole but not changed. This is unacceptable; it is common to change the [monitor]ed rules as the proof attempt progresses, installing monitors when certain rules are about to be used in certain contexts. Thus, the list of monitored runes must be kept as a wormhole variable. Hence, its value cannot be determined outside the wormhole, where the proof attempt is ongoing. This raises another question: If the list of monitored runes is unknown to the rewriter operating on the external state, how does the rewriter know when to break? The answer is simple: it breaks every time, for every rune, if [47m[brr][0m mode is enabled. The wormhole is entered (silently), computations are done within the wormhole state to determine if the user wants to see the break, and if so, interactions begin. For unmonitored runes and runes with false break conditions, the silent wormhole entry is followed by a silent wormhole exit and the user perceives no break. Thus, the penalty for running with [47m[brr][0m mode enabled when there are no monitored runes is high: a wormhole is entered on every application of every rune and the user is simply unaware of it. The user who has finally unmonitored all runes is therefore strongly advised to carry this information out of the wormhole and to do [47m:[0m[47m[brr][0m [47mnil[0m in the external state when the next opportunity arises.") (windows-installation (installation-support) "Installing ACL2 on Windows Windows users will probably want to do one of the following to install and run ACL2 on their systems. Thanks to David Rager for his help with this topic. * Use a Virtual Machine platform, such as VMware Player (free for non-commercial use) or Oracle Virtualbox (free even for commercial use) to install Linux, and then follow the normal [installation-instructions] to install ACL2. As of 2014, at least a couple of our power users are very happy with this solution, as it provides first-class access to utilities relevant to maintaining the ACL2 system and books (like GNU Make and perl). * Set up {Windows Subsystem for Linux | https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux} (WSL) on a 64-bit version of Windows 10 (or later, once available). Within that subsystem, follow the normal [installation-instructions] for ACL2. See the below section regarding the ACL2 Sedan Windows installation instructions for more info, as that involves installing the ACL2 Sedan in WSL on Windows. * Use the ACL2 Sedan (ACL2s) Windows installation instructions --- see [ACL2s::ACL2s-installation] for more details. This will install ACL2 and the ACL2s system (including a copy of the Eclipse IDE with ACL2s support) in a Windows Subsystem for Linux distro. This distro is configured to automatically open Eclipse when the distro starts up, but one can start the distro without Eclipse by running [47mwsl -d acl2s -e /bin/bash --noprofile[0m. You are welcome to {obtain a Windows installer for a previous ACL2 release | http://www.cs.utexas.edu/users/moore/acl2/v3-6/distrib/windows/}, which mimics some of Linux and provides Emacs. Updated ACL2 binaries have been successfully installed in such an environment. When installing ACL2 on Windows without a Unix-like environment, consider at least downloading a utility such as [47mdjtarnt.exe[0m to use with the [47m-x[0m option on gzipped tarfiles. Gnu tar is preferred, as there have been some problems with long file names when using at least one other tar program. You may want to use the [47m-i[0m option, [47mtar xpvfi ...[0m, if you have problems with other than Gnu tar. You can see if you have Gnu tar by running [47mtar -v[0m. WARNING: At least one user experienced CR/LF issues when using WinZIP, but we have received the suggestion that people untarring with that utility should probably turn off smart cr/lf conversion. Here are links to some older documentation topics, possibly out of date, that provide additional information for installing ACL2 on Windows. * See [windows-installation-gcl] for building an executable image on a Windows system using GCL * Click {here | https://www.cs.utexas.edu/users/moore/acl2/contrib/windows7.html} for some older instructions for building ACL2 on Windows. * Click {here | https://www.cs.utexas.edu/users/moore/acl2/contrib/windows-gcl-jared.html} for yet older instructions for building ACL2 on Windows using mingw. Subtopics [Windows-installation-gcl] Building an executable image on a Windows system using GCL") (windows-installation-gcl (windows-installation) "Building an executable image on a Windows system using GCL This topic is based on very old documentation that is probably superseded by the topic, [windows-installation]. But here are steps that [3mmay[0m be helpful when installing ACL2 on Windows with GCL as the host Common Lisp. 1. [31;1mFIRST[0m get GCL running on your Windows system using [31;1mONE[0m of the following two options. Note that GCL can be unhappy with spaces in filenames, so you should probably save the GCL distribution to a directory whose path is free of spaces. * {Obtain GCL for Windows systems | https://www.gnu.org/software/gcl/} if such a distribution is available. * [31;1mOR[0m, perhaps you can build GCL on your Windows system from the sources. The mingw tools and the cygnus bash shell have been used to build distributed GCL executables. 2. [31;1mSECOND[0m, create an appropriate GCL batch file. When we tried running the script [47mgclm/bin/gclm.bat[0m, a separate window popped up, and with an error. Many ACL2 users prefer running in an emacs shell buffer. The following modification of [47mgclm.bat[0m seemed to solve the problem (your pathnames may vary). @ % do not delete this line % @ECHO off set cwd=%cd% path C:\gcl\gclm\mingw\bin;%PATH% C:\gcl\gclm\lib\gcl-2.6.2\unixport\saved_gcl.exe -dir C:/gcl/gclm/lib/gcl-2.6.2/unixport/ -libdir C:/gcl/gclm/lib/gcl-2.6.2/ -eval "(setq si::*allow-gzipped-file* t)" %1 %2 %3 %4 %5 %6 %7 %8 %9 3. [31;1mTHIRD[0m, see [creating-executable], and follow the instructions in the section, ``Building an executable image on other than a Unix-like system''. The resulting file may be called [47msaved_acl2.exe[0m rather than [47msaved_acl2[0m. 4. [31;1mFINALLY[0m, create a suitable file [47macl2.bat[0m. If you experience problems, the following hints may help. TROUBLESHOOTING * In an attempt to build ACL2 on Windows XP on top of GCL, the attempt broke at the end of the ``Initialization, first pass'' step (see [creating-executable]), while compiling [47mTMP1.lisp[0m. That was easily remedied by starting up a fresh GCL session and invoking [47m(compile-file "TMP1.lisp")[0m before proceeding to the next step. * When you want to quit ACL2, invoke [47m(good-bye)[0m. The point here is to avoid [47mcontrol-c control-d[0m, even though that often works fine in Emacs under Unix-like systems. * If the above batch file does not work for some reason, an alternate approach may be to set environment variables. You may be able to add to the [47mPATH[0m variable [3mgcl-dir[0m[47m\gcc\bin[0m, where [3mgcl-dir[0m is the directory where GCL is installed. To get to the place to set environment variables, you might be able to go to the control panel, under system, under advanced. Alternately, you might be able to get there by opening [47mMy Computer[0m and right-clicking to get to [47mProperties[0m, then selecting the [47mAdvanced[0m tab. At one time, when GCL/Windows was released as Maxima, Pete Manolios once suggested adding the system variable [47mLD_LIBRARY_PATH[0m with the value [47m"maxima-dir\gcc\i386-mingw32msvc\include"[0m; this may or may not be necessary for your GCL installation (and the path would of course likely be different).") (with-brr-data (debugging break-rewrite) "Finding the source of a term in prover output When a proof attempt fails, a good first step is typically to look at [3mcheckpoints[0m; see [the-method]. That step is often sufficient. But occasionally a checkpoint contains an undesirable term whose source is a mystery, and it may be useful to find the origin of that term. [47mWith-brr-data[0m is a utility that collects such data that can be queried by various utilities, for example as follows. Example: ; Collect brr-data when attempting the indicated proof: (with-brr-data (thm (equal (append x y) (append y x)))) ; Show a path leading to a rewrite result that contains ; (append y (cdr x)) as a subterm: (cw-gstack-for-subterm (append y (cdr x))) ; Same as above, except enter a loop to query for additional such results: (cw-gstack-for-subterm* (append y (cdr x))) The rest of this documentation topic is structured as follows. It may suffice to read only the first two sections. * Introduction * Connections with [break-rewrite] * General form of [47mwith-brr-data[0m calls * General forms of queries * Keyword arguments of [47mwith-brr-data[0m (optional) * Low-level details (optional) * Using attachments to modify functionality of [47mwith-brr-data[0m Introduction [47m(With-brr-data form)[0m evaluates [47mform[0m while collecting data on rule application --- often [rewrite] and [definition] rules, but also [linear] and [rewrite-quoted-constant] rules. Query utilities allow one to search the collected data for a specified result of a rule application and print a stack of operations leading to that result. The name ``brr'' is suggestive of the [break-rewrite] utility, which shares some aspects with the [47mwith-brr-data[0m utility: in particular, the [47m:path+[0m command of break-rewrite shows a stack of operations in the same way as the query utilities for [47mwith-brr-data[0m. The next section, ``Connection with [break-rewrite]'', further explores the relationship between break-rewrite and [47mwith-brr-data[0m. The collection of break-rewrite data can slow down the theorem prover, but the slowdown will probably be modest, perhaps adding an extra 15% or so to the time. We turn now to examples that illustrate how [47mwith-brr-data[0m works with associated query utilities. These examples are intended to make it clear how to use these utilities, but further information is provided in later sections for those who are interested. Note that each of these examples attempts to prove a non-theorem; they are chosen simply to illustrate tool usage. Example Set 1 Our first illustration of [47mwith-brr-data[0m and associated query utilities uses the following (non-theorem) example, mentioned earlier. (with-brr-data (thm (equal (append x y) (append y x)))) ACL2 produces the following checkpoints, exactly as though the [47m[thm][0m call were evaluated without the surrounding call of [47mwith-brr-data[0m. (The optional section on ``Low-level details'' discusses the ``ACL2 Observation:'' printed at the end by [47mwith-brr-data[0m.) *** Key checkpoint at the top level: *** Goal (EQUAL (APPEND X Y) (APPEND Y X)) *** Key checkpoints under a top-level induction before generating a goal of NIL (see :DOC nil-goal): *** Subgoal *1/2'' (IMPLIES (AND (CONSP X) (EQUAL (APPEND (CDR X) Y) (APPEND Y (CDR X)))) (EQUAL (CONS (CAR X) (APPEND Y (CDR X))) (APPEND Y X))) Subgoal *1/1'' (IMPLIES (NOT (CONSP X)) (EQUAL Y (APPEND Y X))) ACL2 Error [Failure] in ( THM ...): See :DOC failure. ******** FAILED ******** ACL2 Observation: (LENGTH (@ BRR-DATA-LST)) = 16 ACL2 !> Consider the term [47m(APPEND Y (CDR X))[0m occurring in one of these checkpoints. It might not be clear, at least at first glance, how this term came about during the proof. We can find at least one source of that term by issuing the [47mcw-gstack-for-subterm[0m query shown below, which searches ``top-level'' rewrites --- those not invoked when relieving hypotheses of rules --- for a result that contains the given term, in this case [47m(append y (cdr x))[0m, as a subterm. The output is similar to the output of the utility, [47m[cw-gstack][0m, followed by the result of the bottom-most rewriter call, which contains the given term as a subterm. (See [term] for discussion of ``translated'' and ``untranslated'' terms.) ACL2 !>(cw-gstack-for-subterm (append y (cdr x))) 1. Simplifying the clause ((NOT (CONSP X)) (NOT (EQUAL (BINARY-APPEND (CDR X) Y) (BINARY-APPEND Y (CDR X)))) (EQUAL (BINARY-APPEND X Y) (BINARY-APPEND Y X))) 2. Rewriting (to simplify) the atom of the third literal, (EQUAL (BINARY-APPEND X Y) (BINARY-APPEND Y X)), 3. Rewriting (to simplify) the first argument, (BINARY-APPEND X Y), 4. Attempting to apply (:DEFINITION BINARY-APPEND) to (BINARY-APPEND X Y) The resulting (translated) term is (CONS (CAR X) (BINARY-APPEND Y (CDR X))). ACL2 !> One might realize that [47m(BINARY-APPEND Y (CDR X))[0m comes about from expanding [47m(BINARY-APPEND X Y)[0m to expose the term [47m(BINARY-APPEND (CDR X) Y)[0m and then using the inductive hypothesis to swap the arguments. In that case, the mystery of the term's appearance is solved! But if that isn't clear, one at least has the clue from Frame 4 above that the term is produced by applying the definition of [47m[binary-append][0m. With that information one can issue a [47m[monitor!][0m command as follows. :monitor! (:definition binary-append) (equal (brr@ :target) '(binary-append x y)) We now issue the [47m[thm][0m call above, with or without the wrapper of [47mwith-brr-data[0m. After breaking twice (see [break-rewrite]) and proceeding with [47m:go[0m to find two failed attempts to use the definition of [47mbinary-append[0m, we explore at the third break as follows. 1 ACL2 >:type-alist Decoded type-alist: ----- Terms with type *TS-T*: (EQUAL (APPEND (CDR X) Y) (APPEND Y (CDR X))) ----- Terms with type *TS-CONS*: X ========== Use (GET-BRR-LOCAL 'TYPE-ALIST STATE) to see actual type-alist. 1 ACL2 >:target (BINARY-APPEND X Y) 1 ACL2 >:eval 1! (:DEFINITION BINARY-APPEND) produced (CONS (CAR X) (BINARY-APPEND Y (CDR X))). 1 ACL2 > The log above shows how the term [47m(BINARY-APPEND Y (CDR X))[0m was produced: the definition of [47mbinary-append[0m was expanded on the term [47m(BINARY-APPEND X Y)[0m, and the inductive hypothesis --- represented in the [47m:type-alist[0m command's output --- is applied to swap the resulting arguments. We can find more sources of the same term by using the ``[47m*[0m'' version of the [47mcw-gstack-for-subterm[0m command as follows. By repeatedly responding with ``[47my[0m'' to the query presented by the system, we find three additional paths leading to the desired subterm. (cw-gstack-for-subterm* (append y (cdr x))) While [47mcw-gstack-for-subterm[0m and [47mcw-gstack-for-subterm*[0m may be the most useful queries in general, one may wish to search for paths leading to [3mexactly[0m a given term rather than paths to a term [3mcontaining[0m that term (as above). The queries [47mcw-gstack-for-term[0m and [47mcw-gstack-for-term*[0m may be used for this purpose, for example as follows. (cw-gstack-for-term (append y (cdr x))) (cw-gstack-for-term* (append y (cdr x))) Finally, these queries support searching for [3minstances[0m of a term or subterm, by supplying a ``term'' of the form [47m(:free (v1 ... vn) u)[0m where [47mv1[0m through [47mvn[0m are distinct variables and [47mu[0m is a term. Each of the following produces the path shown above. (cw-gstack-for-term (:free (u v) (cons u v))) (cw-gstack-for-term* (:free (u v) (cons u v))) Notice that the use of this [47m:free[0m construct allows one to search for the source of a call of any function symbol [47mf[0m, as with [47mcons[0m above. If [47mf[0m has k formals, then one can supply the argument [47m(:free (x1 ... xk) (f x1 ... xk))[0m to find a rewriter call that produces a call of [47mf[0m. Example Set 2 Consider the following (admittedly contrived) example. (defstub f0 (x) t) (defun f1 (x) (cons x x)) (defun f2 (x) (f1 (f0 x))) (defun f3 (x) (if (atom x) (f2 x) (f2 (car x)))) (with-brr-data (thm (equal (f3 x) yyy))) The call of [47m[thm][0m produces the following checkpoint. (IMPLIES (CONSP X) (EQUAL (CONS (F0 (CAR X)) (F0 (CAR X))) YYY)) In this simple example it's easy to figure out how the term [47m(F0 (CAR X))[0m was produced. But suppose we were surprised to see that term. We might issue the following query but be disappointed in the result. ACL2 !>(cw-gstack-for-term (F0 (CAR X))) There are no results. ACL2 !> To see why there are no results, recall that [47mwith-brr-data[0m collects data from rule applications. However, no rule produced the term [47m(F0 (CAR X))[0m. This becomes clear if we issue a query that looks for that term as a subterm of a rule application's result. ACL2 !>(cw-gstack-for-subterm (F0 (CAR X))) 1. Simplifying the clause ((EQUAL (F3 X) YYY)) 2. Rewriting (to simplify) the atom of the first literal, (EQUAL (F3 X) YYY), 3. Rewriting (to simplify) the first argument, (F3 X), 4. Attempting to apply (:DEFINITION F3) to (F3 X) 5. Rewriting (to simplify) the body, (IF (CONSP X) (F2 (CAR X)) (F2 X)), under the substitution X : X 6. Rewriting (to simplify) the second argument, (F2 (CAR X)), under the substitution X : X 7. Attempting to apply (:DEFINITION F2) to (F2 (CAR X)) 8. Rewriting (to simplify) the rhs of the conclusion, (F1 (F0 X)), under the substitution X : (CAR X) 9. Attempting to apply (:DEFINITION F1) to (F1 (F0 (CAR X))) The resulting (translated) term is (CONS (F0 (CAR X)) (F0 (CAR X))). Note: The first lemma application above that provides a suitable result is at frame 4, and that result is (IF (CONSP X) (CONS (F0 (CAR X)) (F0 (CAR X))) (CONS (F0 X) (F0 X))). ACL2 !> We see that the term [47m(FO (CAR X))[0m is not itself the result of a rule application. This example illustrates that one may often get better results using [47mcw-gstack-for-subterm[0m rather than [47mcw-gstack-for-term[0m. It is also interesting to look at the ``Note'' printed at the end. The query utilities search for the first rule application that produced a suitable result, and then they search from that point for a maximally deeper rule application that produced a suitable result. In this case, the first rule that produced a term containing [47m(FO (CAR X))[0m is shown in the frame at position 4, as per the Note. The rule at frame 9 also produced such a term (though a different one than at frame 4), and there was no deeper such rule application --- that is, from the time the definition at frame 9 was applied till the time its body was fully rewritten, no rule produced a term containing [47m(FO (CAR X))[0m. (This notion of ``deeper'' is discussed at some length in the section below on ``General forms of queries''.) Next we'll explore a limitation of these tools and how to get around it. We start as follows (following the definitions above). (with-brr-data (thm (equal (append (f3 x) y) z) :hints (("Goal" :in-theory (disable append))))) This proof attempt results in the following checkpoint. (IMPLIES (CONSP X) (EQUAL (APPEND (CONS (F0 (CAR X)) (F0 (CAR X))) Y) Z)) The following log may be surprising, especially since the indicated term need only be a subterm of a rewriter result, and we see this exact term in the checkpoint above! ACL2 !>(cw-gstack-for-subterm (APPEND (CONS (F0 (CAR X)) (F0 (CAR X))) Y)) There are no results. ACL2 !> A solution is to choose a subterm of that input term, as shown in the log below. The resulting output shows why the query above yielded no results: frame 6 below shows that the first argument, [47m(F3 X)[0m, of [47mbinary-append[0m (see frame 3 below) generates a call of [47mIF[0m, so the rewrite at frame 3 will generate a term of the form [47m(BINARY-APPEND (IF ...) ...)[0m, not of the form [47m(BINARY-APPEND (CONS ...) ...)[0m. ACL2 !>(cw-gstack-for-subterm (cons (f0 (car x)) (f0 (car x)))) 1. Simplifying the clause ((EQUAL (BINARY-APPEND (F3 X) Y) Z)) 2. Rewriting (to simplify) the atom of the first literal, (EQUAL (BINARY-APPEND (F3 X) Y) Z), 3. Rewriting (to simplify) the first argument, (BINARY-APPEND (F3 X) Y), 4. Rewriting (to simplify) the first argument, (F3 X), 5. Attempting to apply (:DEFINITION F3) to (F3 X) 6. Rewriting (to simplify) the body, (IF (CONSP X) (F2 (CAR X)) (F2 X)), under the substitution X : X 7. Rewriting (to simplify) the second argument, (F2 (CAR X)), under the substitution X : X 8. Attempting to apply (:DEFINITION F2) to (F2 (CAR X)) 9. Rewriting (to simplify) the rhs of the conclusion, (F1 (F0 X)), under the substitution X : (CAR X) 10. Attempting to apply (:DEFINITION F1) to (F1 (F0 (CAR X))) The resulting (translated) term is (CONS (F0 (CAR X)) (F0 (CAR X))). Note: The first lemma application above that provides a suitable result is at frame 5, and that result is (IF (CONSP X) (CONS (F0 (CAR X)) (F0 (CAR X))) (CONS (F0 X) (F0 X))). ACL2 !> The careful reader may notice another reason that the [47mappend[0m call does not yield a match: no such call is the result of a rewriter call. The moral of this story is that if a term fails to give you a match, then use a subterm of it. You can also use the [47m:free[0m construct mentioned above, for example as follows --- this gives the same output as shown in the log just above. (cw-gstack-for-subterm (:free (v) (cons (f0 v) (f0 v)))) Connections with break-rewrite We noted above that after running [47mwith-brr-data[0m, the stacks (paths) displayed by query commands such as [47mcw-gstack-for-term[0m are the same as the stacks displayed by the [break-rewrite] command, [47m:path+[0m. But there are these additional connections between [47mwith-brr-data[0m and the break-rewrite utility. * The same rewriting processes are considered by [47mwith-brr-data[0m as by break-rewrite; in particular, abbreviation rules are not considered during preprocessing (see [monitor]). * When a query command ([47mcw-gstack-for-term[0m etc.) finds a match with a rewriting result, it discards the result if the input --- the [47m:target[0m, in the parlance of [break-rewrite] --- contains that match. * [Monitor]ed [rune]s are indeed monitored during evaluation of a call of [47mwith-brr-data[0m, even if break-rewrite has not been enabled globally (using [47m:[0m[47m[brr][0m or [47m[monitor!][0m). If this is not desired, then [unmonitor] runes before calling [47mwith-brr-data[0m. * There is the following low-level way to collect brr-data for queries such as [47mcw-gstack-for-term[0m without calling [47mwith-brr-data[0m: [47m(assign gstack :brr-data)[0m. But you may want to clear such data afterwards, which you can do by evaluating the form, [47m(clear-brr-data-lst)[0m. Otherwise the brr-data from later proof attempts will be combined, probably in unexpected ways, with brr-data from earlier proof attempts. * [47mWith-brr-data[0m and its queries pay no attention to ``near-miss'' breaks (see [break-rewrite] for discussion of these breaks). The first item above is worth emphasizing. Consider the following example. (include-book "std/lists/rev" :dir :system) (with-brr-data (thm (implies (and (natp n) (< n (len x))) (equal (nth n (revappend x y)) (nth n (reverse x)))) :hints (("Goal" :do-not '(preprocess))))) (cw-gstack-for-subterm (APPEND (REV X) Y)) The [47mcw-gstack-for-subterm[0m query yields a result in this example, but not if we change it to remove the [47m:[0m[47m[hints][0m. If we use [47m:[0m[47m[pso][0m on the proof attempt without the [47m:hints[0m, we notice that the requested subterm was introduced by ``the simple :rewrite rule REVAPPEND-REMOVAL''; here ``simple'' indicates the use of the [3mpreprocess[0m process for simplification, which avoids the usual rewriter. If we instead query the no-hints version with [47m(cw-gstack-for-subterm (REV X))[0m, the output below shows that a chain of rewrites generates [47m(APPEND (REV X) Y)[0m as an intermediate term but not as the result of a rewrite. ACL2 !>(cw-gstack-for-subterm (REV X)) 1. Simplifying the clause ((NOT (INTEGERP N)) (< N '0) (NOT (< N (LEN X))) (EQUAL (NTH N (BINARY-APPEND (REV X) Y)) (NTH N (REVERSE X)))) 2. Rewriting (to simplify) the atom of the fourth literal, (EQUAL (NTH N (BINARY-APPEND (REV X) Y)) (NTH N (REVERSE X))), 3. Rewriting (to simplify) the second argument, (NTH N (REVERSE X)), 4. Rewriting (to simplify) the second argument, (REVERSE X), 5. Attempting to apply (:DEFINITION REVERSE) to (REVERSE X) 6. Rewriting (to simplify) the body, (IF (STRINGP X) (COERCE (REVAPPEND (COERCE X 'LIST) 'NIL) 'STRING) (REVAPPEND X 'NIL)), under the substitution X : X 7. Rewriting (to simplify) the third argument, (REVAPPEND X 'NIL), under the substitution X : X 8. Attempting to apply (:REWRITE REVAPPEND-REMOVAL) to (REVAPPEND X 'NIL) 9. Rewriting (to simplify) the rhs of the conclusion, (BINARY-APPEND (REV X) Y), under the substitution Y : 'NIL X : X 10. Attempting to apply (:REWRITE APPEND-ATOM-UNDER-LIST-EQUIV) to (BINARY-APPEND (REV X) 'NIL) The resulting (translated) term is (REV X). Note: The first lemma application above that provides a suitable result is at frame 5, and that result is (IF (STRINGP X) (COERCE (REV (COERCE X 'LIST)) 'STRING) (REV X)). ACL2 !> The version of this example without [47m:hints[0m also illustrates the second item above, about discarding matches that occur in the [47m:target[0m of rewriting. Without that restriction we would see a result for the query [47m(cw-gstack-for-subterm (APPEND (REV X) Y))[0m from an attempt to rewrite the term [47m(NTH N (APPEND (REV X) Y))[0m. But that would not help us to find the source of the term [47m(APPEND (REV X) Y)[0m. General form of [47mwith-brr-data[0m calls The general form, including optional keyword arguments, is (with-brr-data form :global-var var :brr-data-returned bool) where [47mform[0m is typically an event but is only required to evaluate to an [error-triple]. By default (i.e., when the keyword arguments are omitted), that error triple is returned by the [47mwith-brr-data[0m call. There is probably little reason for most users to supply either keyword argument. They are documented in the section after next. [31;1mNotes[0m. * The data collected by a call of [47mwith-brr-data[0m will persist until the next call of [47mwith-brr-data[0m. * Behavior is undefined for nested calls of [47mwith-brr-data[0m. (If this presents a problem then you may ask the ACL2 implementors to consider specifying that behavior.) General forms of queries The four queries (all illustrated above) are as follows, where the keyword argument is optional. (cw-gstack-for-subterm u :global-var var) (cw-gstack-for-subterm* u :global-var var) (cw-gstack-for-term u :global-var var) (cw-gstack-for-term* u :global-var var) In each case, [47mu[0m is either a term (which can be a user-level term, i.e., not necessarily translated; see [term]) or of the form [47m(:free (v1 ... vk) u1)[0m where [47mu1[0m is a term. In the latter case, [47mv1[0m through [47mvk[0m must be distinct variables that all occur in (the translation of) [47mu1[0m. These queries are effective after data collection using [47mwith-brr-data[0m, which is typically wrapped around an event that calls the theorem prover. To understand how the queries work, it is useful to view a proof attempt as generating ``initial'' calls of the rewriter, such as when rewriting a hypothesis or the conclusion of a goal (technically, a literal of the goal clause; see [clause]): that is, initial rewriter calls are those that are not under another rewriter call. Then data collection under each initial call creates a tree of ``top-level'' calls --- those not made under an attempt to relieve a hypothesis --- for which that initial call is the root. Thus each node of that tree corresponds to a rewriter call, and each child of that node is a top-level call of the rewriter that is immediately under that call, where the order of calls is respected by the ordering of child nodes from left to right. For example, the top-level application a rewrite rule corresponds to a node, and the call to rewrite the right-hand side of the rule (with appropriate variable bindings) corresponds to a child of that node. Another example is when an attempt to rewrite a function call leads to an attempt to rewrite an argument of that call: the latter corresponds to a child node of the former. Each of the four query utilities looks for the first root node, and the left-most branch under that node, that results in a rewriter result that ``matches'' the input in the following sense. This notion of ``matches'' depends on the call, as follows. First assume that the input is a term. For [47mcw-gstack-for-subterm[0m and [47mcw-gstack-for-subterm*[0m, the result matches when it contains the given term as a subterm. For [47mcw-gstack-for-term[0m and [47mcw-gstack-for-term*[0m, the result matches when it is exactly the given term. Now suppose the input is [47m(:free (v1 ... vk) u)[0m. Then the notion of ``matches'' is modified to allow any instance [47mu/s[0m for a substitution [47ms[0m that instantiates only the variables [47mvi[0m. When a matching node [47mN1[0m is found for the input term, or in the case of [47m(:free (v1 ... vk) u)[0m, some instance of [47mu[0m, then a further search below [47mN[0m is made to find a maximal left-most branch below it that terminates in a node [47mN2[0m that also matches, using the same substitution in the case of [47m:free[0m. If no such branch is found, then [47mN2[0m is [47mN[0m. Either way, the term or instance that matched at [47mN[0m (as a subterm in the case of [47mcw-gstack-for-subterm[0m or [47mcw-gstack-for-subterm*[0m, else as an exact match) also matches at [47mN2[0m. The output then shows a path to [47mN2[0m, but if [47mN1[0m and [47mN2[0m differ then the output also notes that the first match was at [47mN1[0m, as we have seen in each ``Note'' at the end of logs displayed above. The discussion above characterizes the behavior of [47mcw-gstack-for-subterm[0m and [47mcw-gstack-for-term[0m; now let us consider [47mcw-gstack-for-subterm*[0m and [47mcw-gstack-for-term*[0m. These ``[47m*[0m'' versions query after each result to ask if another result is desired. If so, the search starts strictly after [47mN[0m; it does not look for a second successor [47mN2[0m of [47mN[0m. The search continues until either the user answers [47mn[0m (regardless of the package; the query cares only that the [47m[symbol-name][0m is [47m"Y"[0m or [47m"N"[0m) or there are no more results. Keyword arguments of [47mwith-brr-data[0m (optional) As noted above, the general form of a call of [47mwith-brr-data[0m is as follows. (with-brr-data form :global-var var :brr-data-returned bool) The keywords have aspects that are quite technical, so unless you are somewhat familiar with ACL2 implementation issues you will probably want to skip this section. Neither keyword argument is evaluated. The behavior of the keyword arguments depends on a list, [47mBDL[0m (``Brr-Data List''), that is typically made available by a call of [47mwith-brr-data[0m, as described below. The members of [47mBDL[0m represent successful initial calls of the rewriter, in order. Each of those members is a [47mbrr-data[0m record, as described in the next section. After the [47mwith-brr-data[0m call returns, then [47m(mv nil BDL state)[0m is returned by evaluation of [47m(brr-data-lst state)[0m, until the next time that either a call of [47mwith-brr-data[0m or the form [47m(clear-brr-data-lst)[0m is evaluated. Implementation notes: information is stored in the [47mbrr-data[0m [wormhole]; [47m(brr-data-lst state)[0m extracts that information and reorders appropriately before producing [47mBDL[0m; and [47m(clear-brr-data-lst)[0m removes that information from the [47mbrr-data[0m wormhole. We now explain the keyword arguments in terms of the list [47mBDL[0m. * [47m:global-var var[0m The symbol [47mvar[0m defaults to the symbol, [47mbrr-data-lst[0m. [47mVar[0m is either [47mnil[0m or a state global variable (see [programming-with-state]), which by default is [47mbrr-data-lst[0m. If [47mvar[0m is not [47mnil[0m, then the [47mwith-brr-data[0m call modifies [state] by setting the value of the state global, [47mvar[0m, to [47mBDL[0m. * [47m:brr-data-returned bool[0m Suppose that the [47mform[0m argument of the [47mwith-brr-data[0m call evaluates to [47m(mv erp val state)[0m. Then when [47mbool[0m is [47mnil[0m (which is the default), the [47mwith-brr-data[0m call returns that same [error-triple], [47m(mv erp val state)[0m. If however [47mbool[0m is not [47mnil[0m, then instead the [47mwith-brr-data[0m call returns [47m(mv erp BDL state)[0m. Low-level details (optional) This implementation-level section further describes the [47mbrr-data[0m structure mentioned above. It is probably of interest only to those who consider writing their own tools to query the data produced by [47mwith-brr-data[0m. A [47mbrr-data[0m record is a structure that has a field [47m:brr-data-1[0m representing information from entry into the rewriter, a field [47m:brr-data-2[0m representing information from the corresponding exit from the rewriter, and a field [47m:completed[0m that is the list of [47mbrr-data[0m records produced between that entry and exit, in order. (Implementation detail: these are produced inside the [47mbrr-data[0m [wormhole] by the same functions, [47mbrkpt1[0m and [47mbrkpt2[0m, that implement the [break-rewrite] utility.) (defrec brr-data (pre post . completed) nil) (defrec brr-data-1 (((lemma . target) . (unify-subst type-alist . geneqv)) . ((pot-list . ancestors) . (rcnst initial-ttree . gstack))) nil) (defrec brr-data-2 ((failure-reason unify-subst . brr-result) . (rcnst final-ttree . gstack)) nil) The [47mbrr-data[0m definition introduces a recursive data type (as per ACL2 source function [47mbrr-data-p[0m, since the [47m:completed[0m field is a list of [47mbrr-data[0m records. These correspond to immediate sub-calls of the rewriter, yielding ``child nodes'' as described in the section, ``General forms of queries''. We have seen above that the use of [47mwith-brr-data[0m activates the collection of break-rewrite data. Collection may also be activated by assigning the [state] global, [47mgstackp[0m, to the value [47m:brr-data[0m. (See [programming-with-state] for relevant programming background.) You can use [47m:[0m[47m[trans1][0m on a [47mwith-brr-data[0m call to see how [47mwith-brr-data[0m sets [47mgstackp[0m. Note that setting (or binding) [47mgstackp[0m to [47m:brr-data[0m has the effect of [47m:[0m[47m[brr][0m[47m t[0m but enhanced with collection of [47mbrr-data[0m records. When [47mgstackp[0m has value [47m:brr-data[0m, [47m:brr t[0m is treated as a no-op and [47m:brr nil[0m is an error, to avoid inadvertently turning off [47mbrr-data[0m record collection. Note that although [47mwith-brr-data[0m is disallowed in ACL2(p) (see [parallelism]) when [waterfall-parallelism] is enabled, this prohibition can be circumvented by assigning [47mgstackp[0m to [47m:brr-data[0m; however, in that case [47mwith-brr-data[0m might well not behave correctly. The programmer who manipulates [47mbrr-data[0m records may wish to look at the ACL2 source code and the [break-rewrite] documentation to understand the fields of the [47mbrr-data-1[0m and [47mbrr-data-2[0m records. The form [47m(brr-data-listp t lst)[0m recognizes a list of well-formed [47mbrr-data[0m records. The [47m:failure-reason[0m field of the [47mbrr-data-2[0m record may be of particular interest; see ACL2 source function [47mtilde-@-failure-reason-phrase1[0m for the forms that this field may take. It is easy to see the list of [47mbrr-data[0m records created by a call of [47mwith-brr-data[0m. A big hint is given in the output printed at the completion of a [47mwith-brr-data[0m call, as suggested in the first example in the introduction, with the following output. ACL2 Observation: (LENGTH (@ BRR-DATA-LST)) = 16 The form [47m(@ BRR-DATA-LST)[0m evaluates to the resulting list of [47mbrr-data[0m records, one for each so-called ``initial call'' of the rewriter, in the sense described in the section above on ``Keyword arguments''. The utility [47mshow-brr-data-lst[0m can be applied to such a list to show the most interesting parts of each record, for example, [47m(show-brr-data-lst (@ brr-data-lst))[0m. Also you can call the utility [47mshow-brr-data[0m on a single [47mbrr-data[0m record. Using attachments to modify functionality of [47mwith-brr-data[0m The behavior of [47mwith-brr-data[0m is customizable by using attachments (see [defattach]). The macro, [47mset-brr-data-attachments[0m, has been provided for this purpose. This section provides only minimal documentation on this customizability; those who want to implement new such attachments can look at the following examples in the [community-books] to get a sense of how that might be done. Note that the query utilities work the same regardless of the attachments, and the relevant data structures are also unchanged. books/kestrel/utilities/brr-data-all.lisp books/kestrel/utilities/brr-data-failures.lisp When the macro is called with no arguments, i.e., [47m(set-brr-data-attachments)[0m, behavior is restored to the built-in behavior as described above. But this macro can be given an argument that indicates a string: it is either a string or a symbol, where a symbol indicates its [47m[symbol-name][0m. The indicated string, which we write below as [47m"<S>"[0m, is added as a suffix after a hyphen to create four system attachments. These are [47m[defattach][0m calls rather than [47m[defattach-system][0m calls, so that their effect is not [local] to the enclosing book. (defattach (brkpt1-brr-data-entry brkpt1-brr-data-entry-<S> :system-ok t) (defattach (brkpt2-brr-data-entry brkpt2-brr-data-entry-<S> :system-ok t) (defattach (update-brr-data-1 update-brr-data-1-<S>) :system-ok t) (defattach (update-brr-data-2 update-brr-data-2-<S>) :system-ok t) The four [47m"-<S>"[0m functions must be defined to match the signatures of the functions to which they are attached. Those functions have the following arguments and results, where [47m*[0m indicates an ordinary (non-[stobj]) value. (brkpt1-brr-data-entry ancestors gstack rcnst state) => * (brkpt2-brr-data-entry ancestors gstack rcnst state) => * (update-brr-data-1 lemma target unify-subst type-alist ancestors initial-ttree gstack rcnst pot-lst whs-data) => * (update-brr-data-2 wonp failure-reason unify-subst gstack brr-result final-ttree rcnst ancestors whs-data) => * Note that [47m(set-brr-data-attachments)[0m is actually equivalent to [47m(set-brr-data-attachments builtin)[0m. That is, the initial (built-in) attachments to the functions above all have the suffix, [47m"-BUILTIN"[0m.") (with-cbd (books-reference) "To bind the connected book directory [47mWith-cbd[0m sets the connected book directory (see [cbd]) within its scope. Example Forms: ; Equivalent to (include-book "dir1/dir2/foo"): (with-cbd "dir1" (include-book "dir2/foo")) ; Equivalent to evaluation of the form, ; (include-book "arithmetic/top" :dir :system)'): (with-cbd (cdr (assoc-eq :system (project-dir-alist (w state)))) (include-book "arithmetic/top")) See [cbd] for a description of the connected book directory. The ``Technical Remark'' there, about Lisp using the [47mcbd[0m to elaborate relative pathnames, applied to [47mwith-cbd[0m as well. General Form: (with-cbd str form) where [47mstr[0m evaluates to a nonempty string that represents the desired directory (see [pathname]) and [47mform[0m evaluates to an [error-triple]. The effect of [47m(with-cbd str form)[0m is to evaluate first [47m(set-cbd str)[0m and then to evaluate [47mform[0m, after which the connected book directory is restored to the value it had before that evaluation of [47mset-cbd[0m. However, the implementation is designed so that the connected book directory is restored even when the evaluation of [47mform[0m causes an error. The form [47m(with-cbd str ev)[0m is an [event] form if [47mev[0m is an event form; thus, it may occur in [books] as well as [47m[encapsulate][0m and [47m[progn][0m events. See [embedded-event-form]. But in an [event] context, [47mstr[0m must be a string, not merely an expression that evaluates to a string. Finally, note that Lisp compilers may vary in how they handle functions defined within the scope of [47mwith-cbd[0m. If you find an example of slower execution caused by using [47mwith-cbd[0m, please feel free to send it to the ACL2 implementors.") (with-current-package (books-reference) "To bind the [current-package] Evaluation of a form [47m(with-current-package "pkg" form[0m) causes [47mform[0m to be evaluated with the [current-package] bound to [47m"pkg"[0m. Example and [31;1mWARNING[0m. The current-package is not modified until after the form is read! Consider the following log that was produced when the value of the current-package was the default, [47m"ACL2"[0m. ACL2 !>(with-current-package "ACL2-USER" (value (cw "~x0~%" 'abcd))) ACL2::ABCD NIL ACL2 !> We see that the call of [47m[cw][0m did its printing relative to the [47m"ACL2-USER"[0m package, producing output [47m"ACL2::ABCD"[0m. This illustrates that the form was [3mread[0m with respect to package [47m"ACL2"[0m but that its [3mevaluation[0m took place with respect to package [47m"ACL2-USER"[0m. General Form: (with-current-package str form) where [47mstr[0m evaluates to a nonempty string that represents the desired package (see [current-package]) and [47mform[0m evaluates to an [error-triple]. Evaluation of [47m(with-current-package str form)[0m first switches to the indicated package, as with [47m(in-package str)[0m, and evaluates [47mform[0m, after which the current-package is restored to the value it had before that evaluation of [47mwith-current-package[0m. The implementation is designed so that the current-package is restored even when the evaluation of [47mform[0m causes an error. The following example drives home the behavior of [47mwith-current-package[0m; explanation follows. ACL2 !>'common-lisp::defun DEFUN ACL2 !>'acl2-user::defun DEFUN ACL2 !>(with-current-package "ACL2-USER" (er-progn (set-current-package "ACL2-PC" state) (value (cw "~x0~%" 'defun)))) COMMON-LISP::DEFUN NIL ACL2 !> The symbol [47mcommon-lisp::defun[0m is imported from the [47m"COMMON-LISP"[0m package into both the [47m"ACL2"[0m package and, as shown in the first two evaluation results above, the [47m"ACL2-USER"[0m package. But it's not imported into the [47m"ACL2-PC"[0m package. The call above of [47mwith-current-package[0m reads [47m'defun[0m into the current package, [47m"ACL2"[0m. Then for evaluation the package changes to [47m"ACL2-USER"[0m; then the package is changed again to [47m"ACL2-PC"[0m before evaluating the [47m[cw][0m call in that package, necessitating the [47m"COMMON-LISP::"[0m prefix since the [47mdefun[0m symbol in that [47mcw[0m call is not in the [47m"ACL2-PC"[0m package. But notice that the prompt comes back as [47m"ACL2 !>"[0m, indicating that we are back in the [47m"ACL2"[0m package. The original package is restored after the [47mwith-current-package[0m call completes evaluation, even when the current-package is changed during evaluation. The form [47m(with-current-package str ev)[0m is an [event] form if [47mev[0m is an event form; thus, it may occur in [books] as well as [47m[encapsulate][0m and [47m[progn][0m events. See [embedded-event-form]. But in an [event] context, [47mstr[0m must be a string, not merely an expression that evaluates to a string. Finally, note that Lisp compilers may vary in how they handle functions defined within the scope of [47mwith-current-package[0m. If you find an example of slower execution caused by using [47mwith-current-package[0m, please feel free to send it to the ACL2 implementors.") (with-fast-alist (fast-alists acl2-built-ins) "[47m(with-fast-alist name form)[0m causes [47mname[0m to be a fast alist for the execution of [47mform[0m. Logically, [47mwith-fast-alist[0m just returns [47mform[0m. Under the hood, we cause [47malist[0m to become a fast alist before executing [47mform[0m. If doing so caused us to introduce a new hash table, the hash table is automatically freed after [47mform[0m completes. More accurately, under the hood [47m(with-fast-alist name form)[0m essentially expands to something like: (if (already-fast-alist-p name) form (let ((<temp> (make-fast-alist name))) (prog1 form (fast-alist-free <temp>)))) Practically speaking, [47mwith-fast-alist[0m is frequently a better choice then just using [47m[make-fast-alist][0m, and is particularly useful for writing functions that can take either fast or slow alists as arguments. That is, consider the difference between: (defun bad (alist ...) (let* ((fast-alist (make-fast-alist alist)) (answer (expensive-computation fast-alist ...))) (prog2$ (fast-alist-free fast-alist) answer))) (defun good (alist ...) (with-fast-alist alist (expensive-computation alist ...))) Either approach is fine if the caller provides a slow [47malist[0m. But if the input [47malist[0m is already fast, [47mbad[0m will (perhaps unexpectedly) free it! On the other hand, [47mgood[0m is able to take advantage of an already-fast argument and will not cause it to be inadvertently freed. See also the macro [47mwith-fast-alists[0m defined in the community book [47m"books/centaur/misc/hons-extra.lisp"[0m, which allows you to call [47m[with-fast-alist][0m on several alists simultaneously. The community book [47m"books/centaur/misc/hons-extra.lisp"[0m extends the [b*] macro with the [47mwith-fast[0m pattern binder. That is, after executing [47m(include-book "centaur/misc/hons-extra.lisp" :dir :system)[0m you may write something like this: (b* (... ((with-fast a b c ...)) ...) ...) which causes [47ma[0m, [47mb[0m, and [47mc[0m to become fast alists until the completion of the [47mb*[0m form. Note that [47mwith-fast-alist[0m will cause logically tail-recursive functions not to execute tail-recursively if its cleanup phase happens after the tail-recursive call returns.") (with-global-stobj (stobj acl2-built-ins) "Operate on a global single-threaded object See [stobj] for an introduction to single-threaded objects. Also see [defstobj] for additional background. The [47mwith-global-stobj[0m macro is a relatively advanced utility that allows stobjs to be accessed directly from the ACL2 [state]. Examples may be found in [community-book] file [47mbooks/system/tests/with-global-stobj-input.lsp[0m; we draw heavily from them below. Example Forms: ; Read-only form (length 3) (with-global-stobj st ;; body: (fld st)) ; Updating form (length 4; (returns state)) (with-global-stobj st ; bound stobj (st) ; output signature of body ;; body: (update-fld x st)) ; Updating form (length 4; returns (mv * * state st2)) (with-global-stobj st ; bound stobj (nil st nil state st2) ; output signature of body ;; body: (let* ((st (update-fld x st)) (st2 (update-fld2 x st2))) (mv (fld st) st (fld st2) state st2))) In the forms above, we call [47mst[0m the stobj that is ``bound by'' the [47mwith-global-stobj[0m call, and the ``body'' of the form is the last argument. The read-only form above, like all read-only forms, has a body that does not return the stobj bound by the form. Each updating form above specifies an output signature as a list, which must contain the stobj bound by the form, whose elements are all [47mnil[0m (designating a non-stobj value) or a stobj name. That output signature reflects the result of the body; the entire form does not return the bound stobj, but does return [47m[state][0m, as explained below. [47mWith-global-stobj[0m is a macro, and the example forms above expand as follows. ACL2 !>:trans1 (with-global-stobj st (fld st)) (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE))) (FLD ST)) ACL2 !>:trans1 (with-global-stobj st (st) (update-fld x st)) (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE))) (LET ((ST (UPDATE-FLD X ST))) (WRITE-USER-STOBJ-ALIST 'ST ST STATE))) ACL2 !>:trans1 (with-global-stobj st (nil st nil state st2) (let* ((st (update-fld x st)) (st2 (update-fld2 x st2))) (mv (fld st) st (fld st2) state st2))) (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE))) (MV-LET ({WGS}0 ST {WGS}1 STATE ST2) (LET* ((ST (UPDATE-FLD X ST)) (ST2 (UPDATE-FLD2 X ST2))) (MV (FLD ST) ST (FLD ST2) STATE ST2)) (LET ((STATE (WRITE-USER-STOBJ-ALIST 'ST ST STATE))) (MV? {WGS}0 {WGS}1 STATE ST2)))) ACL2 !> The first illustrates that in the read-only form, the bound stobj, which is [47mst[0m in that example, is bound to its value in the [47muser-stobj-alist[0m field of the ACL2 [state]. The second and third similarly bind the stobj, [47mst[0m, but then update that stobj according to the body of the [47mwith-global-stobj[0m call (its last argument) and then update the [47muser-stobj-alist[0m of the state with that stobj's resulting value. You can of course use [47m:[0m[47m[trans1][0m in this way to see expansions of other [47mwith-global-stobj[0m calls. Note that ACL2 expects you to use [47mwith-global-stobj[0m, not its expansions in terms of the [non-executable] functions [47mread-user-stobj-alist[0m, which accesses the bound stobj from the user-stobj-alist of [47mstate[0m, and [47mwrite-user-stobj-alist[0m, which completes the write for updating [47mwith-global-stobj[0m forms. These are defined as follows, in terms of the ACL2 state's user-stobj-alist field, which maps stobj names to their values. (defun-nx read-user-stobj-alist (st state) (declare (xargs :guard (symbolp st) :stobjs state)) (cdr (assoc-eq st (user-stobj-alist1 state)))) (defun-nx write-user-stobj-alist (st val state) (declare (xargs :guard (symbolp st) :stobjs state)) (update-user-stobj-alist1 (put-assoc-eq st val (user-stobj-alist1 state)) state)) [47mWith-global-stobj[0m can be useful when you want a function to read or write a stobj but you don't want to pass that stobj as a formal parameter. As long as you pass [47mstate[0m as a formal parameter, you can access the stobj using [47mwith-global-stobj[0m. This topic is intended to be sufficient preparation for the use of [47mwith-global-stobj[0m. Those who want to read more about design and underlying theory are welcome to peruse the (long) ACL2 source code comments, ``Essay on the Design of With-global-stobj'' and ``Essay on Correctness of Evaluation with Stobjs''. More Examples As noted above, examples may be found in [community-book] file [47mbooks/system/tests/with-global-stobj-input.lsp[0m. Here we discuss some of those examples. Let us start by introducing a couple of stobjs. (defstobj st fld) (defstobj st2 fld2 :congruent-to st) Calls of [47mwith-global-stobj[0m are illegal at the top level (as opposed to occurrences in the bodies of a definition or a theorem). (with-global-stobj st (fld st)) One solution may be to use [47m[top-level][0m. (top-level (with-global-stobj st (fld st))) Normally, however, [47mwith-global-stobj[0m is used inside definition bodies. Here we read and write the stobj, [47mst[0m, directly from the ACL2 [state]. (defun rd0 (state) (declare (xargs :stobjs state)) (with-global-stobj st (fld st))) (defun wr0 (x state) (declare (xargs :stobjs state)) (with-global-stobj st (st) (update-fld x st))) Let's see these in action, first writing and then reading. ACL2 !>(wr0 2 state) <state> ACL2 !>(rd0 state) 2 ACL2 !>(fld st) 2 ACL2 !> We can use various stobj operations, even the rather fancy [47m[swap-stobjs][0m, in the body of a [47mwith-global-stobj[0m call. The following events are admissible. (update-fld 1 st) (update-fld 2 st2) (defun f3 (st2 state) (declare (xargs :stobjs (st2 state))) (with-global-stobj st (st2 st) (swap-stobjs st2 st))) (f3 st2 state) (assert-event (and (equal (fld st) 2) (equal (fld st2) 1))) The following function writes to both [47mst[0m and [47mst2[0m without passing in either one (just [47mstate[0m). Notice that the inner [47mwith-global-stobj[0m call has a body that returns the indicated values [47mst[0m and [47mst2[0m, but since [47mst2[0m is bound by the call, it is dropped before returning from the call, and [47mstate[0m is added --- which explains the list [47m(st state)[0m supplied to the outer call. (defun write-global-st-st2 (fld fld2 state) (declare (xargs :stobjs state)) (with-global-stobj st (st state) (let ((st (update-fld fld st))) (with-global-stobj st2 (st st2) (let ((st2 (update-fld fld2 st2))) (mv st st2)))))) Let's check that this works as expected. ACL2 !>(write-global-st-st2 'a 'b state) <state> ACL2 !>(fld st) A ACL2 !>(fld st2) B ACL2 !> We can also read both fields. (defun read-global-st-st2 (state) (declare (xargs :stobjs state)) (with-global-stobj st (with-global-stobj st2 (list (fld st) (fld st2))))) Then, continuing with the session above: ACL2 !>(read-global-st-st2 state) (A B) ACL2 !> We can reason about [47mwith-global-stobj[0m by reasoning about its expansions. Consider the following theorem (continuing the session above). (defthm rd0-of-wr0 (equal (rd0 (wr0 val state)) val)) This fails to prove, but each of the two checkpoints has a term of the form [47m(ASSOC-EQUAL 'ST (PUT-ASSOC-EQUAL 'ST _ _))[0m. That suggests the following lemma. (defthm assoc-equal-put-assoc-equal (equal (assoc-equal key (put-assoc-equal key val alist)) (cons key val))) This lemma proves automatically, after which [47mrd0-of-wr0[0m proves automatically. Syntax and Semantics This section provides a reference for [47mwith-global-stobj[0m. The next section discusses restrictions that avoid aliasing problems. General Forms: ; Read-only form (length 3): (with-global-stobj st form) ; Updating form (length 4): (with-global-stobj st lst form) where [47mst[0m is the name of a [stobj] that is user-defined (i.e., not [47mstate[0m), [47mform[0m is subject to syntactic restrictions discussed below, and [47mlst[0m is a list, sometimes called an ``output signature''. That list indicates the list of [47mN[0m values returned by [47mform[0m, which must include the bound stobj, [47mst[0m: thus [47mlst[0m is [47m(st)[0m if [47mN[0m is 1, indicating that [47mform[0m returns an instance of that stobj; and otherwise [47mform[0m returns multiple values [47m(x0 x1 ... xk)[0m where [47mk[0m is [47mN-1[0m and for each [47mi[0m, [47mxi[0m is either [47mnil[0m if the [47mi[0mth value is an ordinary value or else is the name of a stobj returned in that position (and one such stobj name is the bound stobj). In each General Form above, [47mst[0m and [47mform[0m are called the ``bound stobj'' and ``body'' of the [47mwith-global-stobj[0m call (respectively). For the read-only form, the bound stobj (which is [47mst[0m above) must not be returned by the body of the form. For the updating form, the values actually returned are obtained by removing [47mst[0m from [47mlst[0m and then, if [47mstate[0m is not already in [47mlst[0m, adding [47mstate[0m at the end of [47mlst[0m. Consider the following example. (defun f0 (st2 state) (declare (xargs :stobjs (st2 state))) (with-global-stobj st (st st2 nil state) (mv st st2 nil state))) In this case, [47mlst[0m is [47m(st st2 nil state)[0m, and the following expansion shows that [47mst[0m has been dropped from the returned values. ACL2 !>:trans1 (with-global-stobj st (st st2 nil state) (mv st st2 nil state)) (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE))) (MV-LET (ST ST2 {WGS}0 STATE) (MV ST ST2 NIL STATE) (LET ((STATE (WRITE-USER-STOBJ-ALIST 'ST ST STATE))) (MV? ST2 {WGS}0 STATE)))) ACL2 !> Evaluation of an updating [47mwith-global-stobj[0m form always updates [47mstate[0m: specifically it updates its [47muser-stobj-alist[0m field (see [state]). The following example is similar to the one above, except that this time the body of the [47mwith-global-stobj[0m call does not return state; nevertheless, the entire call does return state. It illustrates that when [47mstate[0m is not in the list given as the second argument of an updating [47mwith-global-stobj[0m call, then the [47mwith-global-stobj[0m form not only drops the bound stobj from its return values but also adds [47mstate[0m as the last returned value (or, if the bound stobj was the sole symbol in the list, then the call returns [47mstate[0m as the sole value). ACL2 !>:trans1 (with-global-stobj st (st st2 nil) (mv st st2 nil)) (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE))) (MV-LET (ST ST2 {WGS}0) (MV ST ST2 NIL) (LET ((STATE (WRITE-USER-STOBJ-ALIST 'ST ST STATE))) (MV? ST2 {WGS}0 STATE)))) ACL2 !> Note that because [47mwith-global-stobj[0m updates [47mstate[0m, then [47mstate[0m must be a known stobj when [47mwith-global-stobj[0m is called. In particular, in order to call [47mwith-global-stobj[0m in the body of a function, [47mstate[0m should be a formal parameter of that function. Syntactic Restrictions to Avoid Aliasing For the examples in this section, we continue to assume that the following [47m[defstobj][0m [events] have been evaluated. (defstobj st fld) (defstobj st2 fld2 :congruent-to st) Consider the following definition. (defun foo (st state) (declare (xargs :stobjs (st state))) (let ((state (with-global-stobj st (st) (update-fld 3 st)))) (mv (fld st) state))) ACL2 admits that form, but causes an error with the following call of [47mfoo[0m. ACL2 !>(foo st state) ACL2 Error in TOP-LEVEL: Illegal top-level form, (FOO ST STATE). The stobj ST occurs free, yet may be bound by an updating WITH-GLOBAL- STOBJ form, as the top-level form calls FOO, which makes an updating WITH-GLOBAL-STOBJ call that binds ST. See :DOC with-global-stobj. ACL2 !> Let us see why this call must be illegal; then we'll study the error message. The [47mwith-global-stobj[0m form above will set the field, [47mfld[0m, of [47mst[0m to the value, 3. Moreover, ACL2 uses destructive update on stobjs: the actual Lisp object representing [47mst[0m has value 3 in its field, and this is the same object for which we return [47m(fld st)[0m from [47mfoo[0m. So if [47m(foo st state)[0m were allowed to execute, it would return the multiple values [47m(3 <state>)[0m. However, ACL2 can prove that ACL2 returns [47m(fld st)[0m unchanged: (thm (implies (stp st) (equal (mv-nth 0 (foo st state)) (fld st)))) What we are seeing is a violation of single-threadedness. Now let's look at the error message above. It explains that ``the stobj ST occurs free'' in [47m(foo st state)[0m: indeed, [47mst[0m is the first argument of that call. Therefore, [47mst[0m can be accessed in that top-level form; indeed, we have seen that it is returned as the first value. However, [47mst[0m can also be destructively modified because of the updating [47mwith-global-stobj[0m call in the body of [47mfoo[0m: ``the top-level form calls FOO, which makes an updating WITH-GLOBAL-STOBJ call that binds ST.'' As we have discussed, that updating call destroys single-threadedness, and hence must be avoided. We may call this an ``aliasing problem'', since the bound stobj shares structure with the formal parameter. By contrast, there is no such problem if we replace [47mst[0m by its congruent stobj, [47mst2[0m, in the top-level call. ACL2 !>(foo st2 state) (NIL <state>) ACL2 !>(fld st2) NIL ACL2 !>(fld st) 3 ACL2 !> In this case there is no aliasing problem. The formal parameter [47mst[0m of [47mfoo[0m is bound to the (global) value of [47mst2[0m, which does not share structure with the (global) value of stobj [47mst[0m that is updated by the [47mwith-global-stobj[0m form. Note that the aliasing problem can be buried through a chain of function calls, as we now illustrate. Function [47mfoo2[0m is like [47mfoo[0m above, with two changes: instead of updating the field with [47m3[0m we update it with the formal parameter, [47mval[0m; and that update is done inside the called function, [47mfoo2-sub[0m, rather than directly in the body of [47mfoo2[0m. (defun foo2-sub (val state) (declare (xargs :stobjs state)) (with-global-stobj st (st) (update-fld val st))) (defun foo2 (val st state) (declare (xargs :stobjs (st state))) (let ((state (foo2-sub val state))) (mv (fld st) state val))) The error message is essentially the same, except that the chain of calls is shown that leads to the problematic updating [47mwith-global-stobj[0m form. The behavior on [47mst2[0m instead of [47mst[0m is fine, as before. ACL2 !>(foo2 3 st state) ACL2 Error in TOP-LEVEL: Illegal top-level form, (FOO2 3 ST STATE). The stobj ST occurs free, yet may be bound by an updating WITH-GLOBAL- STOBJ form, as the top-level form calls FOO2, which calls FOO2-SUB, which makes an updating WITH-GLOBAL-STOBJ call that binds ST. See :DOC with-global-stobj. ACL2 !>(foo2 4 st2 state) (NIL <state> 4) ACL2 !>(fld st2) NIL ACL2 !>(fld st) 4 ACL2 !> So far we have seen just one aliasing problem, i.e., between a free stobj in a top-level form and a subsidiary updating [47mwith-global-stobj[0m form. Another case is where the free stobj in a top-level form is actually returned (we might say, updated) by that form; in that case, any subsidiary [47mwith-global-stobj[0m form is problematic, even if it is read-only. Here is an example. (defun g2 (val st state) (declare (xargs :stobjs (st state))) (let ((st (update-fld val st))) (let ((f (with-global-stobj st (fld st)))) (mv f (fld st) st state)))) (g2 nil st state) As before, the definition is fine, but the ensuing top-level call is not. And as before, if we replace the top-level stobj occurrence by one that is congruent to [47mst[0m, there is no error: [47m(g2 5 st2 state)[0m. Note that there is no aliasing problem when there is no update of the stobj, either in the top-level form or in the subsidiary [47mwith-global-stobj[0m form. The following are perfectly legal, for example. (defun g1 (st state) (declare (xargs :stobjs (st state))) (let ((f (with-global-stobj st (fld st)))) (mv f state (fld st)))) (g1 st state) So far we have seen two similar error cases due to aliasing: both are top-level calls involving a stobj occurrence that has an occurrence below bound by [47mwith-global-stobj[0m, where at least one of the two occurrences updates the stobj. Consider this: a top-level call like [47m(foo st state)[0m could be viewed as grabbing [47mst[0m from the ACL2 state, hence could be viewed as being [47m(with-global-stobj st (foo st state))[0m. So we can think of the restrictions as being about nested [47mwith-global-stobj[0m calls, and that leads us to the final two cases. Here is a summary of all the restrictions to prevent aliasing, starting with the two discussed above about top-level evaluation, and ending with the two new ones about nested [47mwith-global-stobj[0m calls. * In a form [47mu[0m that is legal at the top-level, where [47mu[0m has a free occurrence of stobj [47mst[0m, there is no updating [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked during evaluation of [47mu[0m. * In a form [47mu[0m that is legal at the top-level, where [47mu[0m returns stobj [47mst[0m, there is no [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked during evaluation of [47mu[0m. * In a form [47m(with-global-stobj st u)[0m, there is no updating [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked during evaluation of [47mu[0m. * In an updating form [47m(with-global-stobj st lst u)[0m, there is no [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked during evaluation of [47mu[0m. Our restrictions that prevent aliasing are syntactic ones, sufficient to prevent the invocations described above. They are implemented by searching for calls of [47mread-user-stobj-alist[0m to identify expansions of [47mwith-global-stobj[0m calls, and by searing for calls of [47mwrite-user-stobj-alist[0m to identify expansions of updating [47mwith-global-stobj[0m calls. Finally, we note that the syntactic restrictions extend to [guard]s. Consider again the function [47mrd0[0m as defined above, and let's use it in the guard of a function. (defun rd0 (state) (declare (xargs :stobjs state)) (with-global-stobj st (fld st))) (defun call-rd0-in-guard (state) (declare (xargs :stobjs state :guard (rd0 state)) (ignore state)) 17) Then as before, it is an error for a top-level form to update [47mst[0m and also call a function that may lead to a [47mwith-global-stobj[0m call that binds [47mst[0m. ACL2 !>(let ((st (update-fld 3 st))) (mv st (call-rd0-in-guard state))) ACL2 Error in TOP-LEVEL: Illegal top-level form, (LET ((ST (UPDATE-FLD 3 ST))) (LIST ST (CALL-RD0-IN-GUARD STATE))). The stobj ST is returned by evaluation of that form, yet is bound by a WITH-GLOBAL-STOBJ form, as the top-level form calls CALL-RD0-IN-GUARD, which calls RD0, which makes a WITH-GLOBAL-STOBJ call that binds ST. See :DOC with-global-stobj. ACL2 !> Constrained Functions and Defattach Consider the following constrained function introduction. (encapsulate (((crn0 state) => *)) (local (defun crn0 (state) (declare (xargs :stobjs state)) (state-p state)))) If we try to attach [47mrd0[0m (defined above) to [47mcrn0[0m we get an error, as shown just below. In short, this error says that since [47mrd0[0m may lead to a call of [47mwith-global-stobj[0m that binds [47mst[0m, then with this attachment, [47mcrn0[0m may lead to such a call; yet there is no record in the [world] that [47mcrn0[0m may lead to such a call. ACL2 !>(defattach crn0 rd0) ACL2 Error in ( DEFATTACH CRN0 RD0): The attachment of RD0 to CRN0 restricts stobjs bound by WITH-GLOBAL-STOBJ under calls of RD0, according to the :GLOBAL-STOBJS keyword (default nil) in the signature introducing CRN0. But this restriction is violated for stobj ST: the attempt is to attach RD0, which makes a WITH-GLOBAL-STOBJ call that binds ST, yet that stobj is not specified by the :GLOBAL-STOBJS keyword of CRN0. See :DOC with-global-stobj. Summary Form: ( DEFATTACH CRN0 RD0) Rules: NIL Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) ACL2 Error [Failure] in ( DEFATTACH CRN0 RD0): See :DOC failure. ******** FAILED ******** ACL2 !> The solution is to note, in the signature of the constrained function, that it may lead to a [47mwith-global-stobj[0m call. This is accomplished by using the keyword, [47m:GLOBAL-STOBJS[0m, in the signature of the function. The value of that keyword is [47mnil[0m by default, indicating that there is no such call. Otherwise the value is a cons of the form [47m(r . w)[0m, where [47mr[0m and [47mw[0m are disjoint lists of stobjs. Their interpretation is as follows: [47mw[0m includes all stobjs for which an attachment may have an updating [47mwith-global-stobj[0m call, and [47mr[0m includes all stobjs not in [47mw[0m for which an attachment may have a [47mwith-global-stobj[0m call. Consider the following modification of the [47m[encapsulate][0m form above. (encapsulate (((crn1 state) => * :global-stobjs ((st) . nil))) (local (defun crn1 (state) (declare (xargs :stobjs state)) (state-p state)))) Then the form [47m(defattach crn1 rd0)[0m is legal: unlike [47mcrn0[0m, [47mcrn1[0m has specified that [47mst[0m may be bound by [47mwith-global-stobj[0m in an attachment. The requirement is thus as follows. Consider attachment of [47mg[0m to a constrained function [47mf[0m, where [47mg[0m may lead to updating [47mwith-global-stobj[0m calls that bind stobjs [47mw1[0m, [47mw2[0m, ..., [47mwk[0m, and also [47mg[0m may lead to [47mwith-global-stobj[0m calls that bind, in addition to the [47mwi[0m, stobjs [47mr1[0m, [47mr2[0m, ..., [47mrn[0m. Then the signature of [47mf[0m must specify a value [47m(r . w)[0m for the keyword [47m:GLOBAL-STOBJS[0m, where [47mr[0m and [47mw[0m are lists of stobjs such that: [47mw[0m includes all [47mwi[0m, and the union of [47mr[0m and [47mw[0m includes all [47mri[0m.") (with-guard-checking (guard acl2-built-ins) "Suppress or enable guard-checking for a form Example: ; Turn off all guard-checking for the indicated calls of append and car: (with-guard-checking :none (append 3 4)) General Form: (with-guard-checking val form) where [47mval[0m evaluates to a legal [guard]-checking value (see [set-guard-checking], or evaluate [47m*guard-checking-values*[0m to see the list of such values), and [47mform[0m is a form that does not mention [47m[state][0m (unless there is an active trust tag, in which case mention of [47mstate[0m can be unsound; see below). See [with-guard-checking-error-triple] and [with-guard-checking-event] for analogous utilities to be used with forms that return [error-triple]s. [47mForm[0m is to be evaluated in a scope such that, in essence, [47m(set-guard-checking val)[0m is first executed locally in that scope. However, this guard-checking setting is ignored once evaluation passes into raw Lisp functions (see [guards-and-evaluation]). Note that the addition of [47mwith-guard-checking[0m does not change the proof obligations generated for guard verification. However, [47m[ec-call][0m can be used in order to eliminate those proof obligations. Consider the following example. (defun f1 (x) (declare (xargs :guard t)) (with-guard-checking nil (ec-call (nth t x)))) Then guard verification succeeds, and evaluation of the form [47m(f1 '(1 2 3))[0m will return [47m1[0m, without causing a guard violation. However, if [47mec-call[0m is instead removed from this definition, then guard verification will fail, and for good reason, as illustrated by the following example. (defun f2 (x) (declare (xargs :guard t)) (with-guard-checking nil (nth t x))) (defun f3 (x) (declare (xargs :guard t)) (f2 x)) Suppose guard verification were to succeed for [47mf2[0m. Then of course it would also succeed for [47mf3[0m. But the call [47m(f3 nil)[0m would then cause a raw Lisp error (at least in many host Lisps), because it would lead to a raw-Lisp call of [47mnth[0m whose first argument is not a number. The remainder of this topic provides a remark for advanced users. [47mWith-guard-checking[0m is implemented using [47m[return-last][0m, which you can in principle call directly; use [47m:[0m[47m[trans][0m or [47m:[0m[47m[trans1][0m to see how a call of [47mwith-guard-checking[0m expands to a corresponding call of [47mreturn-last[0m. However, ACL2 enforces a couple of checks that can only be circumvented if there is an active trust tag. The following example from Jared Davis shows why those checks are required (in particular, it shows how circumventing them with a trust tag can be unsound). We start by defining our own version of the utility, which omits the check that the form has no occurrences of [47mstate[0m. (defmacro my-with-guard-checking (val form) `(with-guard-checking1 (chk-with-guard-checking-arg ,val) ,form)) Submitting the following event results in the error shown just below it. (defun foo (state) (declare (xargs :stobjs state :guard (f-boundp-global 'guard-checking-on state))) (my-with-guard-checking :all (f-get-global 'guard-checking-on state))) ACL2 Error in ( DEFUN FOO ...): The form (RETURN-LAST 'WITH-GUARD-CHECKING1-RAW (CHK-WITH-GUARD-CHECKING-ARG :ALL) (F-GET-GLOBAL 'GUARD-CHECKING-ON STATE)) is essentially a call of WITH-GUARD-CHECKING, but without certain checks performed. This is illegal unless there is an active trust tag; see :DOC defttag. To avoid this error without use of a trust tag, call WITH-GUARD-CHECKING directly. Note: this error occurred in the context (WITH-GUARD-CHECKING1 (CHK-WITH-GUARD-CHECKING-ARG :ALL) (F-GET-GLOBAL 'GUARD-CHECKING-ON STATE)). But if we first evaluate [47m(defttag t)[0m, then the [47m[defun][0m event above is admitted, and we can subsequently prove something that is not true. (thm (equal (foo state) (f-get-global 'guard-checking-on state))) (assert-event (not (equal (foo state) (f-get-global 'guard-checking-on state))))") (with-guard-checking-error-triple (guard acl2-built-ins) "Suppress or enable guard-checking for a form See documentation on the closely related utility, [with-guard-checking], for relevant background. Example: ; Turn off all guard-checking for the indicated calls of append and car: (with-guard-checking-error-triple :none (value (append 3 4))) General Form: (with-guard-checking-error-triple val form) where [47mval[0m evaluates to a legal guard-checking value (see [set-guard-checking], or evaluate [47m*guard-checking-values*[0m to see the list of such values), and [47mform[0m is a form that returns an error triple, [47m(mv erp val state)[0m; see [error-triple]. Thus, [47mwith-guard-checking-error-triple[0m is much like [47m[with-guard-checking][0m, but the former is to be used if [47mform[0m mentions the ACL2 [state]; indeed, [47mwith-guard-checking-error-triple[0m requires [47mform[0m to evaluate to an error triple. As with [47mwith-guard-checking[0m, [47mform[0m is evaluated in a context where guard-checking has been set to the value of [47mval[0m, but this guard-checking setting is ignored once evaluation passes into raw Lisp functions (see [guards-and-evaluation]). Also see [with-guard-checking-event] for a similar utility to be used for creating [events], specifically, [embedded-event-form]s.") (with-guard-checking-event (guard acl2-built-ins) "Suppress or enable guard-checking for an event form See documentation on the closely related utility, [with-guard-checking], for relevant background. General Forms: (with-guard-checking-event val form) (with-guard-checking-event (quote val) form) where [47mval[0m is a legal guard-checking value (see [set-guard-checking], or evaluate [47m*guard-checking-values*[0m to see the list of such values), and [47mform[0m is a form that returns an [error-triple], [47m(mv erp val state)[0m. This macro is identical to [47m[with-guard-checking-error-triple][0m, except that the first argument of a call of [47mwith-guard-checking-event[0m must be a constant as described above, and it will generate a legal event form [embedded-event-form]. For example, the following (uninteresting) form may be placed in a book. (with-guard-checking-event :none (make-event (prog2$ (car 3) '(defun f (x) x)))) In raw Lisp, [47m(with-guard-checking-event x y)[0m macroexpands to [47my[0m; thus, wrapping an event with [47mwith-guard-checking-event[0m has effect only inside the ACL2 read-eval-print loop. Because of that behavior, calls of [47mwith-guard-checking-event[0m must not be used in function definitions; use [47m[with-guard-checking-error-triple][0m in such cases.") (with-live-state (programming-with-state acl2-built-ins) "Allow a reference to [47mstate[0m in raw Lisp The macro [47mwith-live-state[0m is an advanced feature that very few users will need (basically, only system hackers). Indeed, it is essentially [untouchable], defined with [47m[defmacro-untouchable][0m; [remove-untouchable] for how to enable calling [47mwith-live-state[0m in the ACL2 loop. Example Form: (with-live-state (assign y 3)) General form: (with-live-state form) where form is an arbitrary form with a free reference to the variable [47m[state][0m. Logically, [47m(with-live-state FORM)[0m macroexpands to [47mFORM[0m. However, in raw Lisp it expands to: (let ((state *the-live-state*)) FORM) If a form that mentions the variable [47m[state][0m might be executed in raw Lisp --- that is, either outside the ACL2 loop or in raw mode (see [set-raw-mode]) --- then the surrounding the form with [47mwith-live-state[0m as shown above can avoid potential warnings or (much less likely) errors. Note however that if [47mstate[0m is lexically bound to a state other than the usual ``live'' state, surprising behavior may occur when evaluating a call of [47mwith-live-state[0m in raw Lisp or raw mode (either directly by evaluation or at compile time), because [47mwith-live-state[0m will override that lexical binding of [47m[state][0m by a lexical binding of [47mstate[0m to the usual ``live'' state.") (with-local-state (stobj acl2-built-ins) "Locally bind state This is an advanced topic, probably of interest only to system developers. Consider the following example form: (with-local-state (mv-let (result state) (compute-with-state x state) result)) This is equivalent to the following form. (with-local-stobj state (mv-let (result state) (compute-with-state x state) result)) By default, this form is illegal, because ACL2 does not have a way to unwind all changes to the ACL2 [state]; we say more on this issue below. There may however be situations where you are willing to manage or overlook this issue. In that case you may execute the following form to enable the use of [47mwith-local-state[0m, by enabling the use of [47m[with-local-stobj][0m on [47mstate[0m; but note that it requires an active trust tag (see [defttag]). (remove-untouchable create-state t) Please be aware that no local [state] is actually created, however! In particular, users of [47mwith-local-state[0m need either to ensure that channels are closed and state global variables are returned to their original values, or else be willing to live with changes made to state that are not justified by the code that has been evaluated. You are welcome to look in the ACL2 source code at the definition of macro [47mchannel-to-string[0m, which employs [47mwith-local-state[0m to create a local [state] for the purpose of creating a string. Here is an example use of [47mwith-local-state[0m. Notice the use of [47m[defttag][0m --- and indeed, please understand that we are just hacking here, and in general it takes significant effort to be sure that one is using [47mwith-local-state[0m correctly! (defttag t) (remove-untouchable create-state t) (set-state-ok t) (defun foo (state) (declare (xargs :mode :program)) (mv-let (channel state) (open-input-channel "my-file" :object state) (mv-let (eofp obj state) (read-object channel state) (declare (ignore eofp)) (let ((state (close-input-channel channel state))) (mv obj state))))) (defun bar () (declare (xargs :mode :program)) (with-local-state (mv-let (result state) (foo state) result))) ; Multiple-value return version: (defun foo2 (state) (declare (xargs :mode :program)) (mv-let (channel state) (open-input-channel "my-file" :object state) (mv-let (eofp obj state) (read-object channel state) (let ((state (close-input-channel channel state))) (mv eofp obj state))))) (defun bar2 () (declare (xargs :mode :program)) (with-local-state (mv-let (eofp result state) (foo2 state) (mv eofp result)))) Note for ACL2(p) users: When [parallel-execution] is enabled, invocations of [47mwith-local-state[0m are surrounded by a lock.") (with-local-stobj (stobj acl2-built-ins) "Locally bind a single-threaded object See [stobj] for an introduction to single-threaded objects. Also see [defstobj] for additional background. Example Form: (with-local-stobj st (mv-let (result st) (compute-with-st x st) result)) [47mWith-local-stobj[0m can be thought of as a macro, where the example form above expands as follows. (mv-let (result st) (let ((st (create-st))) (compute-with-st x st)) (declare (ignore st)) result) However, ACL2 expects you to use [47mwith-local-stobj[0m, not its expansion. More precisely, stobj creator functions are only allowed via [47mwith-local-stobj[0m or in logic-only situations (like theorems and hints). Moreover, neither [47mwith-local-stobj[0m nor its expansions are legal when typed directly at the top-level loop. See [top-level] for a way to use [47mwith-local-stobj[0m in the top-level loop. General Forms: (with-local-stobj stobj-name mv-let-form) (with-local-stobj stobj-name mv-let-form creator-name) where [47mstobj-name[0m is the name of a [stobj], [47mmv-let-form[0m is a call of [47m[mv-let][0m that binds [47mstobj-name[0m but does not return [47mstobj-name[0m --- in fact, if [47mmv-let-form[0m is [47m(mv-let (...) ... body)[0m, then [47mbody[0m does not even reference [47mstobj-name[0m --- and if [47mcreator-name[0m is supplied then it should be the name of the creator function for [47mstobj-name[0m. For the example form above, its expansion would use [47mcreator-name[0m, if supplied, in place of [47mcreate-st[0m. Note that [47mstobj-name[0m must not be [47m[state][0m (the ACL2 state), except in special situations probably of interest only to system developers; see [with-local-state]. Note that if a stobj [47mST[0m is bound upon beginning evaluation of a form [47m(with-local-stobj ST ...)[0m, then the value of [47mST[0m is the same immediately before evaluating that form as it is immediately after that evaluation. In other words, only a local version of [47mST[0m is modified inside that [47mwith-local-stobj[0m form. [47mWith-local-stobj[0m can be useful when a stobj is used to memoize intermediate results during a computation, yet it is desired not to make the [47mstobj[0m a formal parameter for the function and its callers. ACL2 can reason about these ``local stobjs,'' and in particular about stobj creator functions. For technical reasons, ACL2 will not allow you to enable the [47m:EXECUTABLE-COUNTERPART[0m [rune] of a stobj creator function. Finally, here is a small example concocted in order to illustrate that [47mwith-local-stobj[0m calls can be nested. (defstobj st fld1) (defun foo () (with-local-stobj st ; Let us call this the ``outer binding of st''. (mv-let (val10 val20 st) (let ((st (update-fld1 10 st))) ;; At this point the outer binding of st has fld1 = 10. (let ((result (with-local-stobj st ; Let us call this the ``inner binding of st''. (mv-let (val st) (let ((st (update-fld1 20 st))) ;; Now fld1 = 20 for the inner binding of st. (mv (fld1 st) st)) val)))) ;; So result has been bound to 20 above, but here we are once again ;; looking at the outer binding of st, where fld1 is still 10. (mv (fld1 st) result st))) (mv val10 val20)))) (thm (equal (foo) (mv 10 20))) ; succeeds") (with-output (output-controls) "Suppressing or turning on specified output for an event The macro [47mwith-output[0m can be used to control ACL2 output. It can be wrapped around an event to create a new event; see [embedded-event-form]. The macro [47mwith-output![0m is identical except that it does not create an event and, unlike [47mwith-output[0m, it can be called in code. Examples ; Turn off all controllable output during evaluation of the indicated thm form. (with-output :off :all :gag-mode nil :inhibit-er-hard t (thm (equal (app (app x y) z) (app x (app y z))))) ; Equivalent to the example just above. (with-output :off :all! (thm (equal (app (app x y) z) (app x (app y z))))) ; Prove the indicated theorem with the event summary turned off and ; using the :goals setting for gag-mode. (with-output :off summary :gag-mode :goals (defthm app-assoc (equal (app (app x y) z) (app x (app y z))))) ; Same effect as just above: (with-output :on summary :summary-off :all :gag-mode :goals (defthm app-assoc (equal (app (app x y) z) (app x (app y z))))) ; Turn off all but the ``time'' and ``rules'' parts of the summary. (with-output :on summary :summary-off (:other-than time rules) :gag-mode :goals ; default: use gag-mode, with goal names printed (defthm app-assoc (equal (app (app x y) z) (app x (app y z))))) ; Same as specifying :off :all!, but with output types made explicit ; (that is, using the value of constant *valid-output-names*): (with-output :off (error warning warning! observation prove proof-builder event history summary proof-tree) :gag-mode nil (thm (equal (app (app x y) z) (app x (app y z))))) ; Same as above, but :stack :push says to save the current ; inhibit-output-lst, which can be restored in a subsidiary with-output call ; that specifies :stack :pop. (with-output :stack :push :off :all :gag-mode nil (thm (equal (app (app x y) z) (app x (app y z))))) ; Abbreviate printing in gag-mode for guard goals and induction schemes, but ; defeat abbreviated printing (if any) for terms. (with-output :evisc (:gag-mode (evisc-tuple 3 4 nil nil) :term nil) (defun h (x) (declare (xargs :guard t)) (append (cons (make-list 10) x) x))) ; The following use of :ctx causes the error message to start with ; ``ACL2 Error in MY-CUSTOM-CTX'' instead of ; ``ACL2 Error in ( DEFUN FOO ...)''. (with-output :ctx 'my-custom-ctx (defun foo (x) y)) General Form (with-output :key1 val1 ... :keyk valk form) where [47mform[0m should evaluate to an [error-triple]. That evaluation takes place with output that is according to the values [47mvali[0m of the keywords, [47m:keyi[0m, as described below. When the scope of [47mwith-output[0m is exited, then all modifications are undone, including the states of output and summary inhibition, [47m[gag-mode][0m, and [evisc-tuple]s. Each keyword may occur at most once. Use of the argument [47m:off :all![0m is treated exactly the same as using arguments [47m:off :all :gag-mode nil[0m. We assume below that any use of [47m:off :all![0m has been expanded away in that manner. On-off specs Before discussing the keywords we introduce the notion of ``on-off specs'', which are the legal values of the keywords [47m:on[0m, [47m:off[0m, [47m:summary-on[0m, and [47m:summary-off[0m. (As noted above, we ignore [47m:off :all![0m below, as it is just an abbreviation for [47m:off :all :gag-mode nil[0m.) An on-off spec has one of the following forms, where each [47msymi[0m is a symbol, and subject to restrictions discussed below * [47m:all[0m * [47msym[0m ; a symbol that is not [47m:all[0m * [47m(sym1 ... symk)[0m * [47m(:other-than sym1 ... symk)[0m The set of ``associated valid symbols'' is defined as follows. For [47m:off[0m or [47m:on[0m, these symbols are the [3moutput types[0m that can be inhibited --- that is, members of the list stored in the constant [47m*valid-output-names*[0m, which is the list [47m(proof-tree error warning! warning observation prove event summary proof-builder comment history)[0m --- and they are treated as in [47m[set-inhibit-output-lst][0m. Similarly, for [47m:summary-on[0m or [47m:summary-off[0m, these are the [3msummary types[0m: the parts of the [summary] that can be inhibited as in [47m[set-inhibited-summary-types][0m, that is, members of the list stored in the constant [47m*summary-types*[0m, which is the list [47m(errors form header hint-events redundant rules splitter-rules steps system-attachments time value warnings)[0m. An on-off spec consisting of associated valid symbols, [47m(sym1 ... symk)[0m, indicates the set of symbols, [47m{sym1,...,symk}[0m. The other legal forms of on-off spec and their meanings are as follows: [47m:all[0m represents the set of all associated valid symbols, any other symbol [47msym[0m abbreviates [47m(sym)[0m, and [47m(:other-than sym1 ... symk)[0m represents the set of associated valid symbols that are not in the list [47m(sym1 ... symk)[0m. Note that these two notions of ``associated valid symbols'' --- the [3moutput types[0m controlled by keywords [47m:on[0m and [47m:off[0m, and the [3msummary types[0m controlled by keywords [47m:summary-on[0m and [47m:summary-off[0m --- operate independently in the following sense. The keywords [47m:on[0m and [47m:off[0m control output types from the list [47m*valid-output-names*[0m displayed above, one of whose members is [47mSUMMARY[0m. The keywords [47m:summary-on[0m and [47m:summary-off[0m control summary types from the list [47m*summary-types*[0m displayed above, indicating which types of summary are to be printed in the case that [47mSUMMARY[0m is among the output types that are on. This summary control persists even as the [47mSUMMARY[0m type changes state between off and on. Consider the following example. (with-output :off (summary) (with-output :summary-off (time) (with-output :on (summary) (thm (equal (car (append x y)) (if (consp x) (car x) (car y))))))) The resulting output does not include [47mTIME[0m output in the summary. The reason is that the second [47mwith-output[0m form specifies that [47mTIME[0m summary output is off; then when the third (innermost) output turns [47mSUMMARY[0m output on, still, the [47mTIME[0m summary output is off, so the [47mTHM[0m call does not print the [47mTIME[0m part of the summary output. Note that the same reasoning applies if the third [47mwith-output[0m call above specifies [47m:on :all[0m instead of [47m:on (summary)[0m; that case also produces no time output in the summary. That is, the use of [47m:on :all[0m specifies which output types are on, but does not affect which summary types are on; again, output types and summary types are controlled independently by the respective pairs [47m:on/:off[0m and [47m:summary-on/:summary-off[0m. Keyword arguments We turn now to a discussion of the keyword arguments. [47m:on[0m, [47m:off[0m The values for these keywords, which are not evaluated, must be on-off specs for these keywords (as discussed above). If [47m:on :all[0m is specified, then then every output type is turned on except for those in the set specified by the value of [47m:off[0m. Otherwise, if [47m:off :all[0m is specified, then every output type is inhibited except as specified by the value of [47m:on[0m. Otherwise [47m:all[0m is not specified for either [47m:on[0m or [47m:off[0m, and the currently-inhibited output types are reduced as specified by the value of [47m:on[0m and then extended as specified by the value of [47m:off[0m. [47m:summary-on[0m, [47m:summary-off[0m The values for these keywords, which are not evaluated, must be on-off specs for these keywords. They are interpreted exactly as are the values for [47m:on[0m and [47m:off[0m as described above, except that instead of output types they are interpreted with respect to the summary types (i.e., in the terminology introduced above, with respect to the set of associated valid symbols for [47m:summary-on[0m and [47m:summary-off[0m). [47m:gag-mode[0m The value should evaluate to one of the legal values for [47m[set-gag-mode][0m. The effect is as though [47mset-gag-mode[0m has been called with this argument, before modifying how output is inhibited, at the start of evaluating the given form. [47m:evisc[0m The value should evaluate to a [47m[keyword-value-listp][0m, where each key is a legal keyword for the [47m:sites[0m keyword argument of [47m[set-evisc-tuple][0m other than [47m:trace[0m and [47m:brr[0m (that is, a member of the list [47m(:term :ld :abbrev :gag-mode)[0m), and each value evaluates to a legal [evisc-tuple] for that keyword. The effect is as though [47mset-evisc-tuple[0m has been called, before modifying how output is inhibited, with this argument at the start of evaluating the given form. [47m:ctx[0m The value should evaluate to a context --- see [ctx] --- that will generally be used throughout evaluation of the given form, in place of the usual event context (including the [47m"Form"[0m field of the [summary]). [47m:stack[0m The value, which is not evaluated, must be [47m:push[0m or [47m:pop[0m. The effect of [47m:push[0m is essentially to create a new environment for inferior calls of [47mwith-output[0m that can be reverted (popped) by inferior calls of [47mwith-output[0m, as discussed in the next section. Note that the handling of the [47m:stack[0m argument pays no attention to the [47m:summary-on[0m or [47m:summary-off[0m arguments. [47m:inhibit-er-hard[0m By default, ACL2 prints messages for hard errors --- errors whose message starts with ``HARD ACL2 ERROR'' --- even when [47merror[0m output is inhibited (whether by using the keyword, [47m:off[0m, or by calling [47m[set-inhibit-output-lst][0m). This behavior holds when [state] global [47minhibit-er-hard[0m has its default value of [47mnil[0m; see [set-inhibit-output-lst]. When keyword [47m:inhibit-er-hard[0m is supplied an expression, the value [47mv[0m of that expression overrides the global value of [47minhibit-er-hard[0m: thus when error output is inhibited, hard error messages are printed if [47mv[0m is [47mnil[0m and they are not printed if [47mv[0m is not [47mnil[0m. Note that this behavior automatically takes place when [47mwith-output[0m is supplied the arguments [47m:off :all![0m, but not [47m:off :all[0m. More about the [47mstack[0m argument The [47m:stack[0m keyword's effect is illustrated by the following example, where ``[47m(encapsulate nil)[0m'' may replaced by ``[47m(progn[0m'' without any change to the output that is printed. (with-output :stack :push :off :all (encapsulate () (defun f1 (x) x) (with-output :stack :pop (defun f2 (x) x)) (defun f3 (x) x) (with-output :stack :pop :off warning (in-theory nil)) (defun f4 (x) x))) The outer [47mwith-output[0m call saves the current output settings (as may have been modified by earlier calls of [47m[set-inhibit-output-lst][0m), by pushing them onto a stack, and then turns off all output. Each inner [47mwith-output[0m call temporarily pops that stack, restoring the starting output settings, until it completes and undoes the effects of that pop. Unless [47mevent[0m output was inhibited at the top level (see [set-inhibit-output-lst]), the following output is shown: Since F2 is non-recursive, its admission is trivial. We observe that the type of F2 is described by the theorem (EQUAL (F2 X) X). And then, if [47msummary[0m output was not inhibited at the top level, we get the rest of this output: Summary Form: ( DEFUN F2 ...) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Summary Form: ( IN-THEORY NIL) Rules: NIL Warnings: None Time: 0.00 seconds (prove: 0.00, print: 0.00, other: 0.00) Note that the use of [47m:off warning[0m suppresses a [47m"Theory"[0m warning for the [47m(in-theory nil)[0m event, and that in no case will output be printed for definitions of [47mf1[0m, [47mf3[0m, or [47mf4[0m, or for the [47m[encapsulate][0m event itself. The following more detailed explanation of [47m:stack[0m is intended only for advanced users. After [47m:gag-mode[0m and [47m:evisc[0m are handled (if present) but before [47m:on[0m or [47m:off[0m is handled, the value of [47m:stack[0m is handled as follows. If the value is [47m:push[0m, then [state] global [47minhibit-output-lst-stack[0m is modified by pushing the cons of the values of [state] globals [47minhibit-output-lst[0m and [47mgag-mode[0m onto the value of [state] global [47minhibit-output-lst-stack[0m, which is [47mnil[0m at the top level. If the value is [47m:pop[0m, then [state] global [47minhibit-output-lst-stack[0m is modified only if non-[47mnil[0m, in which case its top element is popped and provides the values of [state] globals [47minhibit-output-lst[0m and [47mgag-mode[0m. Concluding remarks [47mWith-output[0m has no effect in raw Lisp, in the sense that a call [47m(with-output ... form)[0m macroexpands to [47mform[0m in raw Lisp. Normally this produces desired behavior, but occasionally you may be a bit surprised. Consider for example the following book. (in-package "ACL2") (with-output :off :all (make-event (prog2$ (cw "@@@ NOISE @@@") '(defun f (x) x)) :check-expansion t)) (make-event (with-output! :off :all (value (prog2$ (cw "@@@ QUIET @@@") '(defun g (x) x)))) :check-expansion t) When certifying this book, we do not see either `[47mNOISE[0m' or `[47mQUIET[0m'. But then when we include this book, we see `[47mNOISE[0m' (but not `[47mQUIET[0m'). To see why, we first note that both events are evaluated in raw Lisp when including the book (as discussed briefly in the documentation topic, [book-compiled-file]). The first calls [47mwith-output[0m, which (as noted above) disappears during macroexpansion. The second calls [47mwith-output![0m, which has the desired effect of suppressing output.") (with-output! (pointers) "See [with-output].") (with-output-lock (parallel-programming acl2-built-ins) "Provides a mutual-exclusion mechanism for performing output in parallel This documentation topic relates to an experimental extension of ACL2, ACL2(p), created initially by David L. Rager. See [compiling-ACL2p] for how to build an executable image that supports parallel execution. Also see community books directory [47mbooks/parallel/[0m for examples. One may wish to perform output while executing code in parallel. If threads are allowed to print concurrently, the output will be interleaved and often unreadable. To avoid this, the user can surround forms that perform output with the [47mwith-output-lock[0m macro. Warning: [47mwith-output-lock[0m may not perform as expected when called directly in the loop; see [parallelism-at-the-top-level]. Take the following definition of [47mpfib[0m as an example. (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((mbe :logic (or (zp x) (<= x 0)) :exec (<= x 0)) 0) ((= x 1) 1) (t (plet (declare (granularity t)) ((a (prog2$ (cw "Computing pfib ~x0~%" (- x 1)) (pfib (- x 1)))) (b (prog2$ (cw "Computing pfib ~x0~%" (- x 2)) (pfib (- x 2))))) (+ a b))))) With [parallel-execution] enabled, a call of [47m(pfib 5)[0mresults in non-deterministically interleaved output, for example as follows. ACL2 !>(pfib 5) CComputing pfib 4 omputing pfib 3 ComCpuotmipnugt ipnfgi bp fib3 2 Computing pCfiobm put2i ng pfib 1 Computing pfib Co1mp uting pfib 0 CCoommppuuttiinngg ppffiibb 12 ComCpuotmipnugt ipnfgi bp fib1 0 CoCmopmuptuitnign gp fpifbi b 1 0 5 ACL2 !> If the user instead surrounds the calls to [47m[cw][0m with the macro [47mwith-output-lock[0m, as in the following session, the output will no longer be interleaved. ACL2 !> (defun pfib (x) (declare (xargs :guard (natp x))) (cond ((mbe :logic (or (zp x) (<= x 0)) :exec (<= x 0)) 0) ((= x 1) 1) (t (plet (declare (granularity t)) ((a (prog2$ (with-output-lock (cw "Computing pfib ~x0~%" (- x 1))) (pfib (- x 1)))) (b (prog2$ (with-output-lock (cw "Computing pfib ~x0~%" (- x 2))) (pfib (- x 2))))) (+ a b))))) <snip> ACL2 !>(pfib 5) Computing pfib 4 Computing pfib 3 Computing pfib 3 Computing pfib 2 Computing pfib 2 Computing pfib 1 Computing pfib 2 Computing pfib 1 Computing pfib 1 Computing pfib 0 Computing pfib 1 Computing pfib 0 Computing pfib 1 Computing pfib 0 5 ACL2 !>") (with-prover-step-limit (miscellaneous) "Limit the number of steps for proofs Logically, [47m(with-prover-step-limit expr form)[0m is equivalent to [47mform[0m, except that if the number of ``prover steps'' executed during evaluation of [47mform[0m exceeds a bound specified by the value of [47mexpr[0m, then that proof will abort. See [set-prover-step-limit] for a related utility that sets the limit on prover steps globally instead of setting it for just one form, and for a discussion of the notion of ``prover steps'', which could change in future ACL2 releases. For a related utility based on time instead of prover steps, see [with-prover-time-limit]; but as discussed in the [documentation] for [47m[set-prover-step-limit][0m, there is at best a loose connection between the counting of steps and [47m[with-prover-time-limit][0m. The arguments of [47m(with-prover-step-limit expr form)[0m are evaluated. However, the (optional) argument [47mflg[0m is not evaluated in [47m(with-prover-step-limit expr flg form)[0m. Depending on the machine you are using, you may have less than a half-hour of time before the number of prover steps exceeds the maximum limit on prover steps that may be imposed, which is one less than the value of [47m*default-step-limit*[0m. But there is no limit unless you explicitly call [47mwith-prover-step-limit[0m or [47m[set-prover-step-limit][0m. For examples of how step-limits work besides those presented below, see the community book [47mbooks/misc/misc2/step-limits.lisp[0m. For a utility that returns an indicator of the number of prover steps most recently taken, see [last-prover-steps]. Note that [47mwith-prover-step-limit[0m may not be called inside definitions, and that it is simply the identity macro in raw Lisp. However, [47mwith-prover-step-limit![0m may be called in place of [47mwith-prover-step-limit[0m, with the effect described here even in raw Lisp. Examples: ; Limit (mini-proveall) to 100,000 prover steps (which happens to suffice) (with-prover-step-limit 100000 (mini-proveall)) ; Same as above for the inner call of with-prover-step-limit; so the ; mini-proveall call completes, but then we get an error because the second ; argument of the outer with-prover-step-limit call took more than 200 ; steps. (with-prover-step-limit 200 (with-prover-step-limit 100000 (mini-proveall))) ; Same as preceding form just above, except that this time there is no error, ; because the inner call of with-prover-step-limit has an extra argument ; of t inserted into the second argument position, which specifies that this ; entire inner call is treated as though it uses no prover steps. (with-prover-step-limit 200 (with-prover-step-limit 100000 t (mini-proveall))) ; The inner call limits (mini-proveall) to 200 prover steps, which fails ; almost immediately. (with-prover-step-limit 100000 (with-prover-step-limit 200 (mini-proveall))) ; Do not limit the number of prover steps, regardless of such a limit imposed ; globally or by the surrounding context. (with-prover-step-limit nil (mini-proveall)) ; Same as just above (indeed, nil above is converted to ; *default-step-limit*): (with-prover-step-limit *default-step-limit* (mini-proveall)) ; Advanced example: Limit the indicated theorem to 100 steps, and when the ; proof does not complete, then put down a label instead. (mv-let (erp val state) (with-prover-step-limit 100 (thm (equal (append (append x x) x) (append x x x)))) (if erp (deflabel foo :doc "Attempt failed.") (value (list :succeeded-with val)))) ; Use extra argument of t to avoid ``charging'' steps for the indicated ; form. (with-prover-step-limit 500 (encapsulate () (with-prover-step-limit 500 t ; Don't charge prover steps for this first defthm. (defthm test1 (equal (append x (append y z)) (append (append x y) z)) :rule-classes nil)) (defthm test2 (equal (append x (append y z)) (append (append x y) z)) :rule-classes nil))) General Forms: (with-prover-step-limit expr form) (with-prover-step-limit expr flg form) where [47mform[0m is an arbitrary form to evaluate, and [47mexpr[0m evaluates to one of the following: [47mnil[0m; a natural number not exceeding the value of [47m*default-step-limit*[0m; or the special value, [47m:START[0m. The optional extra argument in the second position, [47mflg[0m, must be Boolean if supplied. If the value of [47mexpr[0m is a natural number less than the value of [47m*default-step-limit*[0m, then that value is the maximum number of prover steps permitted during evaluation of [47mform[0m before an error occurs. If however the value of [47mexpr[0m is [47mnil[0m or is the value of [47m*default-step-limit*[0m, then no limit is placed on the number of prover steps during processing of [47mform[0m. Otherwise, the value of [47mexpr[0m should be the keyword [47m:START[0m, which is intended for use by the ACL2 implementation and may have semantics that change with new ACL2 versions. Finally we describe the optional extra Boolean argument, [47mflg[0m. If [47mflg[0m is [47mnil[0m or omitted, then a running count of prover steps is maintained after [47mform[0m is evaluated; otherwise, that count is not affected by evaluation of [47mform[0m. To see how this works when [47mflg[0m is nil or omitted, consider an event of shape [47m(progn form1 form2)[0m, where we are tracking prover steps (say, because of a superior call of [47mwith-prover-step-limit[0m). If [47mn[0m is the number of prover steps available when the [47m[progn][0m form is entered, and if [47ms[0m prover steps are executed while evaluating [47mform1[0m, then [47mn-s[0m steps are available for evaluation of [47mform2[0m provided [47ms[0m does not exceed [47mn[0m; otherwise, an error occurs. In particular, this is the case if [47mform1[0m is an event [47m(with-prover-step-limit k form1')[0m. However, if [47mform1[0m is an event [47m(with-prover-step-limit k t form1')[0m, then because of the extra argument of [47mt[0m, no steps are ``charged'' to [47mform[0m; that is, all [47mn[0m steps, rather than [47mn-s[0m steps, are available for evaluation of [47mform2[0m. Subtopics [Last-prover-steps] The number of prover steps most recently taken") (with-prover-step-limit! (pointers) "See [with-prover-step-limit].") (with-prover-time-limit (miscellaneous) "Limit the time for proofs Examples: ; Limit (mini-proveall) to about 1/4 second: (with-prover-time-limit 1/4 (mini-proveall)) ; Limit (mini-proveall) to about 1/4 second, even if surrounding call of ; with-prover-time-limit provides for a more restrictive bound: (with-prover-time-limit '(1/4) (mini-proveall)) ; Limit the indicated theorem to about 1/50 second, and if the proof does not ; complete or it fails, then put down a label instead. (mv-let (erp val state) (with-prover-time-limit 1/50 (thm (equal (append (append x x) x) (append x x x)))) (if erp (deflabel foo :doc "Attempt failed.") (value (list :succeeded-with val)))) General Form: (with-prover-time-limit time form) where [47mtime[0m evaluates to a positive rational number or to a list containing such, and [47mform[0m is arbitrary. Logically, [47m(with-prover-time-limit time form)[0m is equivalent to [47mform[0m. However, if the time for evaluation of [47mform[0m exceeds the value specified by [47mtime[0m, and if ACL2 notices this fact during a proof, then that proof will abort, for example like this: ACL2 Error in ( DEFTHM PERM-REFLEXIVE ...): Out of time in the rewriter. If there is already a surrounding call of [47mwith-prover-time-limit[0m that has set up an expiration time, the inner [47mwith-prover-time-limit[0m call is not allowed to push that time further into the future unless the inner time is specified as a list containing a rational, rather than as a rational. Note that by default, the time used is runtime (cpu time); to switch to realtime (elapsed time), see [get-internal-time]. For a related utility based on prover steps instead of time, see [with-prover-step-limit]; also see [set-prover-step-limit]. Those utilities have the advantage of having platform-independent behavior, unlike time limits, which of course are generally less restrictive for faster processors. But note that the prover steps counted need not correspond closely to prover time. For other utilities that limit time, see [with-timeout] and [oracle-timelimit]. Although [47mwith-prover-time-limit[0m behaves like an ACL2 function in the sense that it evaluates both its arguments, it is however actually a macro that behaves as follows. (1) The value of its first (time limit) argument affects the evaluation of its second argument (by causing an error during that evaluation if the time for completion is insufficient). (2) The second argument can return multiple values (see [mv]), which are then returned by the call of [47mwith-prover-time-limit[0m. (3) Thus, there is not a fixed number of values returned by [47mwith-prover-time-limit[0m. If you find that the time limit appears to be implemented too loosely, it may be because the prover only checks the time elapsed at certain points during the proof process, for example at entry to the rewriter. For example, if you write your own [47m[clause-processor][0m that does an expensive computation, the time is unlikely to be checked during its execution. If however you find the time limit seems to be ignored even during ordinary prover operation, you are encouraged to email an example to the ACL2 implementors with instructions on how to observe the undesirable behavior. This information can perhaps be used to improve ACL2 by the insertion of more checks for expiration of the time limit. The rest of this documentation topic explains the rather subtle logical story, and is not necessary for understanding how to use [47mwith-prover-time-limit[0m. The ACL2 [47m[state][0m object logically contains a field called the [47macl2-oracle[0m, which is an arbitrary true list of objects; see [47m[read-ACL2-oracle][0m. Our claim is that every ACL2 session makes sense for [31;1msome[0m value of [47macl2-oracle[0m in the initial [47mstate[0m for that session. Logically, [47mwith-prover-time-limit[0m is a no-op, just returning its second value. But under the hood, it provides a ``hint'' for the [47macl2-oracle[0m, so that (logically speaking) when its first element ([47m[car][0m) is consulted by ACL2's prover to see if the time limit has expired, it gets the ``right'' answer (specifically, either nil if all is well or else a message to print if the time limit has expired). Logically, the [47macl2-oracle[0m is then [47m[cdr][0m'ed --- that is, its first element is popped off --- so that future results from [47mread-acl2-oracle[0m are independent of the one just obtained.") (with-serialize-character (serialize acl2-built-ins) "Control output mode for [47mprint-object$[0m See [serialize] for a discussion of ``serialization'' routines, contributed by Jared Davis for saving ACL2 objects in files for later loading. NOTE: To control the use of the serialize writer by the system, rather than by the user (as discussed below), see [set-serialize-character-system]. The expression [47m(with-serialize-character char form)[0m evaluates to the value of [47mform[0m, but with the serialize-character of the [47m[state][0m assigned to [47mchar[0m, which should be one of [47mnil[0m, [47m#\Y[0m, or [47m#\Z[0m. We describe the effect of that assignment below. But note that if you are doing this because of one or more specific calls of [47mprint-object$[0m, such as [47m(print-object$ x channel state)[0m, then you may wish instead to evaluate [47m(print-object$-fn x serialize-character channel state)[0m, in which case you will not need to use [47mwith-serialize-character[0m. General forms: (with-serialize-character nil form) (with-serialize-character #Y form) (with-serialize-character #Z form) where [47mform[0m should evaluate to an [error-triple]. You can get the current serialize-character as follows. (get-serialize-character state) Note that if you prefer to obtain the same behavior (as described below) globally, rather than only within the scope of [47mwith-serialize-character[0m, then use [47mset-serialize-character[0m in a corresponding manner: (set-serialize-character nil state) (set-serialize-character #\Y state) (set-serialize-character #\Z state) In each case above, calls of [47mprint-object$[0m (see [io]) in [47mform[0m will produce a readable object. In the first case, that object is printed as one might expect at the terminal, as an ordinary Lisp s-expression. But in the other cases, the object is printed by first laying down either [47m#Y[0m or [47m#Z[0m (respectively) and then calling [47m[serialize-write][0m (or more precisely, the underlying function called by [47mserialize-write[0m that prints to a stream). Consider what happens when the ACL2 reader encounters an object produced as described above (in the [47m#Y[0m or [47m#Z[0m case). When the object was written, information was recorded on whether that object was a [hons]. In the case of [47m#Z[0m, the object will be read as a hons if and only if it was originally written as a hons. But in the case of [47m#Y[0m, it will never be read as a hons. Thus, [47m#Y[0m and [47m#Z[0m will behave the same if the original written object was not a hons, creating an object that is not a hons. For an equivalent explanation and a bit more discussion, see [serialize-read], in particular the discussion of the hons-mode. The value [47m:smart[0m described there corresponds to [47m#Z[0m, while [47m:never[0m corresponds to [47m#Y[0m.") (with-stolen-alist (fast-alists acl2-built-ins) "[47m(with-stolen-alist name form)[0m ensures that [47mname[0m is a fast alist at the start of the execution of [47mform[0m. At the end of execution, it ensures that [47mname[0m is a fast alist if and only if it was originally. That is, if [47mname[0m was not a fast alist originally, its hash table link is freed, and if it was a fast alist originally but its table was modified during the execution of [47mform[0m, that table is restored. Note that any extended table created from the original fast alist during [47mform[0m must be manually freed. Logically, [47mwith-stolen-alist[0m just returns [47mform[0m. Under the hood, we cause [47malist[0m to become a fast alist before executing [47mform[0m, and we check the various conditions outlined above before returning the final value. Note that [47mwith-stolen-alist[0m will cause logically tail-recursive functions not to execute tail-recursively if its cleanup phase happens after the tail-recursive call returns.") (without-evisc (io acl2-built-ins) "Print output in full General Form: (without-evisc form) where [47mform[0m is any expression to evaluate. The effect is to evaluate [47mform[0m as though the [47mwithout-evisc[0m wrapper were absent, except that expressions are printed in full for the ensuing output, regardless of the current evisc-tuples (see [set-evisc-tuple]). See [set-iprint] for an example. More precisely, [47mwithout-evisc[0m binds each of the term-evisc-tuple, ld-evisc-tuple, abbrev-evisc-tuple and gag-mode-evisc-tuple to [47mnil[0m (see [set-evisc-tuple]). It does not modify the trace or brr evisc-tuples, so trace and brr output are not modified by [47mwithout-evisc[0m. Also note that calls of printing functions such as [47m[fmt][0m that include explicit evisc-tuples will not have those evisc-tuples overridden. The following example illustrates this point. ACL2 !>(without-evisc (fms "~x0~%" (list (cons #0 '((a b ((c d)) e f g) u v w x y))) *standard-co* state (evisc-tuple 2 3 nil nil))) ((A B # ...) U V ...) <state> ACL2 !> We conclude with two remarks. (1) A call of [47mwithout-evisc[0m on expression [47mexp[0m actually invokes a specialized call of [47m[ld][0m on a one-element list containing [47mexp[0m, which prints the value returned by evaluation of [47mexp[0m. It actually returns the useless value [47m(mv nil :invisible state)[0m, except that if an error is detected then it generally returns [47m(mv t nil state)[0m, indicating an error; see [error-triple]. So do not use [47mwithout-evisc[0m in programs if you want the value of the computation to be returned, rather than merely printed. (2) Even when using without-evisc, if the ACL2 logical [world] is part of the value returned, it will be printed in abbreviated form because the ACL2 read-eval-print loop always arranges for this to be the case, regardless of the ld-evisc-tuple. For example: ACL2 !>(without-evisc (w state)) <world> ACL2 !> An alternative to the use of [47mwithout-evisc[0m is to explore large objects using the ACL2 function [47m(walkabout object state)[0m; see [walkabout].") (wof (output-controls io) "Direct standard output and proofs output to a file Example Form: (wof "tmp" (pso)) ; same as (psof "tmp") General Form: (wof filename form) where [47mfilename[0m is a writable filename and [47mform[0m is any form that evaluates to an error triple (see [programming-with-state]), that is, a multiple value of the form [47m(mv erp val state)[0m. All output to channels [47m[standard-co][0m and [47m[proofs-co][0m will be directed to the indicated file. It is acceptable to replace [47mfilename[0m with [47m(quote filename)[0m. For a general discussion about redirection of output to a file, see [output-to-file]. Note that so-called comment-window output (see [cw] and see [observation-cw]) is not redirected by [47mwof[0m to a file, nor is printing from a [wormhole].") (world (state) "ACL2 property lists and the ACL2 logical database The ACL2 logical world is a data structure that includes all logical content resulting from the [command]s evaluated, back through and including initialization, but not including commands that have been undone (see [ubt]). Thus in particular, the world includes a representation of the current logical theory, as well as some extra-logical information such as the values of ACL2 [table]s. The rest of this topic focuses on the structure of the ACL2 world and, more generally, the ``world'' data structure. A ``world'' is a list of triples, each of the form [47m(sym prop . val)[0m, implementing the ACL2 notion of property lists. ACL2 permits the simultaneous existence of many property list worlds. ``The world'' is often used as a shorthand for ``the ACL2 logical world'' which is the particular property list world used within the ACL2 system to maintain a database that contains rules, [table]s, and so on. Common Lisp provides the notion of ``property lists'' by which one can attach ``properties'' and their corresponding ``values'' to symbols. For example, one can arrange for the [47m'color[0m property of the symbol [47m'box-14[0m to be [47m'purple[0m and the [47m'color[0m property of the symbol [47m'triangle-7[0m to be [47m'yellow[0m. Access to property lists is given via the Common Lisp function [47mget[0m. Thus, [47m(get 'box-14 'color)[0m might return [47m'purple[0m. Property lists can be changed via the special form [47msetf[0m. Thus, [47m(setf (get 'box-14 'color) 'blue)[0m changes the Common Lisp property list configuration so that [47m(get 'box-14 'color)[0m returns [47m'blue[0m. It should be obvious that ACL2 cannot provide this facility, because Common Lisp's [47mget[0m ``function'' is not a function of its argument, but instead a function of some implicit state object representing the property list settings for all symbols. ACL2 provides the functions [47mgetprop[0m and [47mputprop[0m which allow one to mimic the Common Lisp property list facility. However, ACL2's [47mgetprop[0m takes as one of its arguments a list that is a direct encoding of what was above called the ``state object representing the property list settings for all symbols.'' Because ACL2 already has a notion of ``[state]'' that is quite distinct from that used here, we call this property list object a ``world.'' A world is just a true list of triples. Each triple is of the form [47m(sym prop . val)[0m. This world can be thought of as a slightly elaborated form of association list and [47mgetprop[0m is a slightly elaborated form of [47m[assoc][0m that takes two keys. When [47mgetprop[0m is called on a symbol, [47ms[0m, property [47mp[0m, and world, [47mw[0m, it scans [47mw[0m for the first triple whose [47msym[0m is [47ms[0m and [47mprop[0m is [47mp[0m and returns the corresponding [47mval[0m. [47mGetprop[0m has two additional arguments: one controls what it returns if no such [47msym[0m and [47mprop[0m exist in [47mw[0m, and the other allows an extremely efficient implementation. To set some property's value for some symbol, ACL2 provides [47mputprop[0m. [47m(putprop sym prop val w)[0m merely returns a new world, [47mw'[0m, in which [47m(sym prop . val)[0m has been [47m[cons][0med onto the front of [47mw[0m, thus ``overwriting'' the [47mprop[0m value of [47msym[0m in [47mw[0m to [47mval[0m and leaving all other properties in [47mw[0m unchanged. One aspect of ACL2's property list arrangement is that it is possible to have many different property list worlds. For example, [47m'box-14[0m can have [47m'color[0m [47m'purple[0m in one world and can have [47m'color[0m [47m'yes[0m in another, and these two worlds can exist simultaneously because [47mgetprop[0m is explicitly provided the world from which the property value is to be extracted. The efficiency alluded to above stems from the fact that Common Lisp provides property lists. Using Common Lisp's provisions behind the scenes, ACL2 can ``install'' the properties of a given world into the Common Lisp property list state so as to make retrieval via [47mgetprop[0m very fast in the special case that the world provided to [47mgetprop[0m has been installed. To permit more than one installed world, each of which is permitted to be changed via [47mputprop[0m, ACL2 requires that worlds be named and these names are used to distinguish installed versions of the various worlds. See [extend-world] and [retract-world] for how to install a world. However, the ACL2 system uses a property list world, named [47m'current-acl2-world[0m, in which to store the succession of user [command]s and their effects on the logic. This world is often referred to in our [documentation] as ``the world'' though it should be stressed that the user is permitted to have worlds and ACL2's is in no way distinguished except that the user is not permitted to modify it except via event [command]s. The ACL2 world is part of the ACL2 [state] and may be obtained via [47m(w state)[0m. [31;1mWarning[0m: The ACL2 world is very large. Its length as of this writing (Version 2.5) is over [47m40,000[0m and it grows with each release. Furthermore, some of the values stored in it are pointers to old versions of itself. Printing [47m(w state)[0m is something you should avoid because you likely will not have the patience to await its completion. For these practical reasons, the only thing you should do with [47m(w state)[0m is provide it to [47mgetprop[0m, as in the form (getprop sym prop default 'current-acl2-world (w state)) or its convenient abbreviation (getpropc sym prop default) to inspect properties within it, or to pass it to ACL2 primitives, such as theory functions, where it is expected. Some ACL2 [command] forms, such as theory expressions (see [theories]) and the values to be stored in tables (see [table]), are permitted to use the variable symbol [47mworld[0m freely with the understanding that when these forms are evaluated that variable is bound to [47m(w state)[0m. Theoretically, this gives those forms complete knowledge of the current logical configuration of ACL2. However, at the moment, few world scanning functions have been documented for the ACL2 user. Instead, supposedly convenient macro forms have been created and documented. For example, [47m(current-theory :here)[0m, which is the theory expression which returns the currently [enable]d theory, actually macroexpands to [47m(current-theory-fn :here world)[0m. When evaluated with [47mworld[0m bound to [47m(w state)[0m, [47mcurrent-theory-fn[0m scans the current ACL2 world and computes the set of [rune]s currently [enable]d in it. Subtopics [Extend-world] Install an extension of a given ACL2 [world] [Formula] The formula of a name or [rune] [Getprop] Access fast property lists [Getpropc] Access fast property lists [Logical-name] A name created by a logical event [Props] Print the ACL2 properties on a symbol [Putprop] Update fast property lists [Redefined-names] To collect the names that have been redefined [Retract-world] Install an initial segment (retraction) of a given ACL2 [world]") (wormhole (state ld) "[47m[ld][0m without [47m[state][0m --- a short-cut to a parallel universe Example Form: ; The following form enters a recursive read-eval-print loop on a ; copy of the current state, allowing you to interact with that loop. ; Note that the form does not mention the ACL2 state variable! ; Evaluate the form below. Inside the resulting loop, define some function, ; e.g., with [47m(defun foo (x) x)[0m. Then exit with [47m:q[0m and observe, ; e.g., with [47m:pe foo[0m, that the external state did not change. (wormhole 'foo '(lambda (whs) (set-wormhole-entry-code whs :ENTER)) nil '(list 'hello 'there)) General Form: (wormhole name entry-lambda input form :current-package ... ; known package name :ld-skip-proofsp ... ; nil, t or 'include-book :ld-redefinition-action ; nil or '(:a . :b) :ld-prompt ... ; nil, t, or some prompt printer fn :ld-missing-input-ok ... ; nil, t, :warn, or warning message :ld-pre-eval-filter ... ; :all, :query, or some new name :ld-pre-eval-print ... ; nil, t, or :never :ld-post-eval-print ... ; nil, t, or :command-conventions :ld-evisc-tuple ... ; nil or '(alist level length hiding-cars) :ld-error-triples ... ; nil or t :ld-error-action ... ; :return!, :return, :continue, :error, ; or (:exit N) :ld-query-control-alist ; alist supplying default responses :ld-verbose ...) ; nil or t The keyword arguments above are exactly those of [47m[ld][0m (see [ld]) except that three of [47m[ld][0m's keyword arguments are missing: the three that specify the channels [47m[standard-oi][0m, [47m[standard-co][0m and [47m[proofs-co][0m, which default in [47mwormhole[0m to ACL2's comment window. There are two ways to create and enter a wormhole: [47mwormhole[0m as described here and the simpler [47m[wormhole-eval][0m. We recommend you read this full account of wormholes before using [47mwormhole-eval[0m. Ignoring the use of [47mentry-lambda[0m, [47mwormhole[0m manufactures a named ``wormhole [state]'' and calls the general-purpose ACL2 read-eval-print loop [47m[ld][0m on it. However, when [47mld[0m exits, the wormhole evaporates and the function [47mwormhole[0m returns [47mnil[0m. The manufactured state is like the ``current'' ACL2 [state] except for two things. First, some information from the last wormhole state of this name is transferred into the new state; this allows a wormhole to maintain some state from one call to the next. Second, some information from the wormhole call itself is transferred into the new state; this allows the wormhole to be sensitive to context. These two changes to the current state are reflected in the settings [47m(@ wormhole-status)[0m and [47m(@ wormhole-input)[0m when in the wormhole. This is discussed in detail below. Note that [47mwormhole[0m may be called from environments in which [47m[state][0m is not bound. It is still applicative because it always returns [47mnil[0m. There are some restrictions about what can be done inside a wormhole. As you may imagine, we really do not ``copy the current state'' but rather just keep track of how it is modified while in the wormhole and we undo those modifications upon exit. In particular, when exiting a wormhole, values of state globals (see [programming-with-state]) are restored to their values at the time the wormhole was entered. Note that information about traced functions is stored in state globals (see [trace$]); accordingly, all tracing and untracing done inside a wormhole is undone upon exit from the wormhole. An error is signaled if you try to modify state in an unsupported way. For this same reason, wormholes do not allow updating of any user-defined single-threaded objects. See [stobj]. One example wormhole is the implementation of the ACL2 [47m[accumulated-persistence][0m facility for tracking the frequency with which rules are tried. To implement this feature directly the theorem prover would have to take the tracking data as an argument and pass it around so that updates could be accumulated. This would greatly clutter the code. Instead, the tracking data is maintained in a wormhole. The theorem prover enters the wormhole to update the data as rules are tried. When you request a display of the data, [47m[show-accumulated-persistence][0m enters the wormhole and prints the data. But the data is never available outside that wormhole. The ACL2 system uses a second wormhole, named [47m[brr][0m, to implement the [break-rewrite] facility, allowing the user to interact with the rewriter as rules are applied. We now specify the arguments and behavior of [47mwormhole[0m. The [47mname[0m argument must be a quoted constant and is typically a symbol. It will be the ``name'' of the wormhole. A wormhole of that name will be created the first time [47mwormhole[0m, [47m[wormhole-eval][0m, or [47m[set-persistent-whs-and-ephemeral-whs][0m is called. However, it is forbidden to invoke these functions on any name listed in [47m*protected-system-wormhole-names*[0m, which includes [47mbrr[0m (the [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and [47mfc-wormhole[0m (the name of the wormhole managing [forward-chaining-reports]), among others. Every wormhole name has a ``status.'' The status of a wormhole is stored outside of ACL2 at a location known to hold the ``persistent wormhole status'' or ``persistent-whs'' of that wormhole. Before [47mwormhole[0m enters its read-eval-print loop the persistent-whs is assigned to the state global variable [47mwormhole-status[0m and so while inside the wormhole the status is available as [47m(@ wormhole-status)[0m. [47mWormhole-status[0m is untouchable: you cannot change it directly as with [47m(assign wormhole-status ...)[0m. But the persistent-whs can be changed, e.g., with [47mwormhole[0m, [47mwormhole-eval[0m, or [47mset-persistent-whs-and-ephemeral-whs[0m. See [47m[wormhole-status][0m for a discussion of the ramifications of there being two places a wormhole's status might be found and of the importance of the notion of ``wormhole coherence.'' Upon the first call on name of [47mwormhole[0m (or the other wormhole creator functions mentioned above) the status of that name is [47mnil[0m. But in general you should arrange for the status to be a cons. The status is set by the quoted [47mlambda[0m every time [47mwormhole[0m is called; but it may also be by set in the [47mform[0m argument of [47mwormhole[0m using [47mset-persistent-whs-and-ephemeral-whs[0m or [47m[sync-ephemeral-whs-with-persistent-whs][0m. The [47mcar[0m of the status should be either [47m:ENTER[0m or [47m:SKIP[0m and is called the wormhole's ``entry code.'' The entry code of [47mnil[0m or, indeed, of any value other than [47m:SKIP[0m is treated as thought it were [47m:ENTER[0m. The [47mcdr[0m of the status is arbitrary data maintained by the author of the wormhole. When the wormhole is exited --- typically because the form [47m:q[0m was read by [47mld[0m --- the then-current ephemeral-whs (i.e., (@ wormhole-status)) is moved to the persistent-whs so that it can be restored when this wormhole is entered again. (Note: The break-rewrite wormhole, [47mbrr[0m, is handled differently. When it is exited back to the top-level, the persistent-whs is set to what it was when ACL2 was last at the top-level.) The rest of the wormhole state is lost upon exit. This allows a sequence of entries and exits to a wormhole to maintain some history in the status and this information can be manipulated by ACL2 functions executing inside the wormhole. The second argument to [47mwormhole[0m must be a quoted lambda expression. We explain it later. The third argument, [47minput[0m, may be any term. The value of the term is passed into the manufactured wormhole state, allowing you to pass in information about the calling context. Inside the wormhole, the [47minput[0m is available via [47m(@ wormhole-input)[0m and may be assigned with [47m[assign][0m. The fourth argument, [47mform[0m, may be any term; when [47m[ld][0m is called on the manufactured wormhole state, the first form evaluated by [47mld[0m will be the value of [47mform[0m. Note that [47mform[0m will be translated by [47mld[0m. Errors, including guard violations, in the translation or execution of that first form will exit the wormhole. When used properly, the first form allows you to greet your user before reading the first interactive command or simply to do whatever computation you want to do inside the wormhole and exit silently. We give examples below. Manufacturing a wormhole state is relatively expensive; in addition, the forms executed by [47mld[0m must be read, translated, and interpreted as with any user type-in. The [47mentry-lambda[0m offers a way to avoid this or, at least, to decide whether to incur that expense. Before the wormhole state is manufactured and entered, the [47mentry-lambda[0m is applied to the persistent-whs with [47m[wormhole-eval][0m. That [47mlambda[0m application must produce a new wormhole status, which is stored as the wormhole's new persistent-whs. The entry code for the new status determines whether [47mwormhole[0m actually manufactures a wormhole state and calls [47mld[0m. If the entry code for that new status is [47m:SKIP[0m the wormhole state is not manufactured; the new persistent-whs is merely saved and [47mwormhole[0m returns nil. Otherwise, a new state is manufactured and entered. Note therefore that the [47mentry-lambda[0m may be used to perform two functions: (a) to determine if it is really necessary to manufacture a state and (b) to update the data in the wormhole status as a function of the old status without invoking [47mld[0m. The [47mentry-lambda[0m must be a quoted lambda expression of at most one argument. Thus, the argument must be either '(lambda (whs) <body>) or '(lambda () <body>) Note the quote. If a formal, e.g., [47mwhs[0m, is provided, it must be used as a variable in the [47mlambda[0m body. The [47mlambda[0m-expression may contain free variables, that is, the body may mention variables other than the [47mlambda[0m formal. These free variables are understood in the caller's environment. These conventions allow us to compile the [47mentry-lambda[0m application very efficiently when the guard has been verified. The guard on a call of [47mwormhole[0m is the conjunction of the guards on the arguments conjoined with the guard on the body of the [47mentry-lambda[0m. See [wormhole-eval] for a discussion of the guard on the [47mlambda[0m-expression. The functions [47m[wormhole-statusp][0m, [47m[wormhole-entry-code][0m, [47m[wormhole-data][0m, [47m[set-wormhole-entry-code][0m, [47m[set-wormhole-data][0m, and [47m[make-wormhole-status][0m may be useful in manipulating entry codes and data in the [47mentry-lambda[0m. See [47m[wormhole-programming-tips][0m for some advice about using wormholes, maintaining (or not maintaining) coherence, etc. Pragmatic Advice on Designing a Wormhole: Suppose you are using wormholes to implement some extra-logical utility. You must contemplate how you will use your wormhole's status to store hidden information. You might be tempted to exploit the entry code as part of the status. For example, you may think of [47m:ENTER[0m as indicating that your utility is ``turned on'' and [47m:SKIP[0m as indicating that your utility is ``turned off.'' We advise against such a design. We recommend you base your decisions on the wormhole data. We recommend that you set but not read the wormhole entry code to signal whether you wish to enter a full-fledged wormhole. To use the entry code as a flag overloads it and invites confusion when your facility is ``turned off'' but you have to enter the wormhole for some reason. For a behind-the-scenes description of how wormholes work, See [wormhole-implementation]. Here are some sample situations handled by [47mwormhole-eval[0m and [47mwormhole[0m. The wormhole in question will be named [47mdemo[0m and it is created in the answer to the first question below. The functions below all maintain the convention that the status is either [47mnil[0m or of the form [47m(:key . lst)[0m, where [47m:key[0m is either [47m:skip[0m or [47m:enter[0m and [47mlst[0m is a true-list of arbitrary objects. But since there is no way to prevent the user from entering the [47mdemo[0m wormhole interactively and doing something to the status, this convention cannot be enforced. Thus, the functions below do what we say they do, e.g., remember all the values of [47mx[0m ever seen, only if they're the only functions messing with the [47mDEMO[0m status. On the other hand, the guards of all the functions below can be verified. We have explicitly declared that the guards on the functions below are to be verified, to confirm that they can be. Guard verification is optional but wormholes (and [47mwormhole-eval[0m in particular) are more efficient when guards have been verified. All of the functions defined below return [47mnil[0m. The examples below build on each other. If you really want to understand wormholes we recommend that you evaluate each of the forms below, in the order they are discussed. [31;1mQ.[0m How do I initialize the status of the [47mdemo[0m wormhole? Actually, it is often unnecessary to explicitly initialize the status of a new wormhole because it is [47mnil[0m by default, the [47m[wormhole-entry-code][0m of [47mnil[0m is [47m:enter[0m and the [47m[wormhole-data][0m of [47mnil[0m is [47mnil[0m, which often is enough. But if the data field of your wormhole needs more structure for whatever you're planning to do with it to make sense, you can initialize it by executing a form like this, where the [47mnil[0m below is the contents of the initial data field. ACL2 !>(wormhole-eval 'demo '(lambda (whs) (make-wormhole-status whs :enter nil)) nil) NIL ACL2 !>(get-persistent-whs 'demo state) (:ENTER) [31;1mQ.[0m How do I define a function that prints the (persistent) status of the [47mdemo[0m wormhole to the comment window? (defun demo-status () (declare (xargs :verify-guards t)) (wormhole-eval 'demo '(lambda (whs) (prog2$ (cw "DEMO status:~%~x0~%" whs) whs)) nil)) Note the [47mprog2$[0m above. After printing the status to the comment window we return the unchanged status [47mwhs[0m. Had we just written the [47mcw[0m term, which returns [47mnil[0m, without then returning [47mwhs[0m, the function would print the status and then set it to [47mnil[0m! [31;1mQ.[0m How can I define a function, [47mdemo-collect[0m, that does not take or return [47m[state][0m but that can collect every symbol passed to it (but not collect non-symbols)? (defun demo-collect (x) (declare (xargs :verify-guards t)) (wormhole-eval 'demo '(lambda (whs) (make-wormhole-status whs (wormhole-entry-code whs) (if (symbolp x) (cons x (wormhole-data whs)) (wormhole-data whs)))) nil)) We could have also defined this function this way: (defun demo-collect (x) (declare (xargs :verify-guards t)) (if (symbolp x) (wormhole-eval 'demo '(lambda (whs) (set-wormhole-data whs (cons x (wormhole-data whs)))) nil) nil)) Both versions always return [47mnil[0m and both versions collect into the wormhole data field just the symbols [47mx[0m upon which [47mdemo-collect[0m is called. Note that the [47mlambda[0m expressions used in both definitions mention [47mx[0m as a free variable. [31;1mQ.[0m How do I use [47mdemo-collect[0m? Below we show an interactive session log with [47mdemo-collect[0m and [47mdemo-status[0m. Notice that [47mstate[0m is nowhere involved but that the functions always return [47mnil[0m. The computation, collection, and printing are done inside the wormhole. ACL2 !>(demo-status) DEMO status: (:ENTER) NIL ACL2 !>(demo-collect 'a) NIL ACL2 !>(demo-status) DEMO status: (:ENTER A) NIL ACL2 !>(demo-collect 'b) NIL ACL2 !>(demo-collect 'c) NIL ACL2 !>(demo-status) DEMO status: (:ENTER C B A) NIL [31;1mQ.[0m How do I reset the data to [47mnil[0m? The answer is the same as the answer to the first question, use [47mwormhole-eval[0m as we did there. But we'll repeat it as a session log because in the next question we want the data field to start off at [47mnil[0m again. ACL2 !>(wormhole-eval 'demo '(lambda (whs) (make-wormhole-status whs :enter nil)) nil) NIL ACL2 !>(demo-status) DEMO status: (:ENTER) NIL [31;1mQ.[0m How can I use [47mdemo-collect[0m in a function? Below is a function that maps over a list and computes its length. But it has been annotated with a call to [47mdemo-collect[0m on every element. We illustrate a call below. (defun my-len (lst) (if (endp lst) 0 (+ 1 (prog2$ (demo-collect (car lst)) (my-len (cdr lst)))))) Thus, for example, if we call [47mmy-len[0m on a list of length [47m5[0m it returns [47m5[0m but accumulates the symbols into the [47mdemo[0m wormhole, without [47mstate[0m. From a logical perspective [47mmy-len[0m is just [47mlen[0m and that can be proved trivially. ACL2 !>(my-len '(4 temp car "Hi" fix)) 5 ACL2 !>(demo-status) DEMO status: (:ENTER FIX CAR TEMP) NIL ACL2 !>(thm (equal (my-len x) (len x))) ... Proof succeeded. [31;1mQ.[0m How do I set the entry code to [47m:enter[0m or [47m:skip[0m according to whether [47mname[0m is a [47mmember-equal[0m of the list of things seen so far? Note that we cannot check this condition outside the wormhole, because it depends on the list of things collected so far. We make the decision inside the [47mlambda[0m-expression. Note that we explicitly check that the guard of [47mmember-equal[0m is satisfied by the current wormhole data, since we cannot rely on the invariant that no other function interferes with the status of the [47mdemo[0m wormhole. In the case that the data is not a true-list we act like the data is [47mnil[0m and set the status to [47m(:skip . nil)[0m. (defun demo-set-entry-code (name) (declare (xargs :verify-guards t)) (wormhole-eval 'demo '(lambda (whs) (if (true-listp (wormhole-data whs)) (set-wormhole-entry-code whs (if (member-equal name (wormhole-data whs)) :enter :skip)) '(:skip . nil))) nil)) Thus ACL2 !>(demo-set-entry-code 'monday) NIL ACL2 !>(demo-status) DEMO status: (:SKIP FIX CAR TEMP) NIL ACL2 !>(demo-set-entry-code 'fix) NIL ACL2 !>(demo-status) DEMO status: (:ENTER FIX CAR TEMP) NIL ACL2 !> We won't be using [47mdemo-set-entry-code[0m again in these questions and answers, so don't spend time learning more about it! [31;1mQ.[0m Suppose I want to collect every symbol and then, if the symbol has an [47mabsolute-event-number[0m property in the ACL2 logical world, print the defining event with [47m:pe[0m and then enter an interactive loop; but if the symbol does not have an [47mabsolute-event-number[0m, don't print anything and don't enter an interactive loop. Here it is not important to know what [47mabsolute-event-number[0m is; this example just shows that we can use a wormhole to access the ACL2 logical world, even in a function that does not take the state as an argument. In the code below, we use [47mwormhole[0m instead of [47mwormhole-eval[0m, because we might have to access the logical world and enter an interactive loop. But for efficiency we do as much as we can inside the entry [47mlambda[0m, where we can check whether [47mx[0m is symbol and collect it into the data field of the wormhole status. Note that if we collect [47mx[0m, we also set the entry code to [47m:enter[0m. If we don't collect [47mx[0m, we set the entry code to [47m:skip[0m. (defun demo-collect-symbols-and-print-events (x) (declare (xargs :guard t)) (wormhole 'demo '(lambda (whs) (if (symbolp x) (make-wormhole-status whs :enter (cons x (wormhole-data whs))) (set-wormhole-entry-code whs :skip))) ; The wormhole will not get past here is unless the entry code is ; :enter. If we get past here, wormhole will manufacture a state, put ; x into (@ wormhole-input) and call ld in such a way that the ; first form executed is the quoted if-expression below. x '(if (getpropc (@ wormhole-input) 'absolute-event-number) (er-progn (mv-let (col state) (fmt "~%Entering a wormhole on the event name ~x0~%~ Exit with :q~%~%" (list (cons #\0 (@ wormhole-input))) *standard-co* state nil) (declare (ignore col)) (value nil)) (pe (@ wormhole-input)) (set-ld-prompt 'wormhole-prompt state) (value :invisible)) (value :q)) :ld-verbose nil :ld-prompt nil)) The ``first form'' --- so called because it is the first form executed by the wormhole's read-eval-print loop --- is the quoted [47mif[0m-expression in the fourth argument of [47mwormhole[0m. It asks whether the [47mwormhole-input[0m (i.e., [47mx[0m) has an [47mabsolute-event-number[0m property. The true branch of that [47mif[0m is an [47m[er-progn][0m to perform a sequence of commands, each of which returns an ACL2 error triple (see [programming-with-state]). The first form uses [47m[fmt][0m to print a greeting. Since [47mfmt[0m returns [47m(mv col state)[0m and we must return an error triple, we embed the [47mfmt[0m term in an [47m(mv-let (col state) ... (value nil))[0m. The macro [47mvalue[0m takes an object and returns a ``normal return'' error triple. The second form in the [47mer-progn[0m uses the ACL2 history macro [47mpe[0m (see [pe]) to print the defining event for a name. The third form sets the prompt of this read-eval-print loop to the standard function for printing the wormhole prompt. We silenced the printing of the prompt when we called [47mld[0m, thanks to the [47m:ld-prompt nil[0m keyword option. More on this below. The fourth form returns the error triple value [47m:invisible[0m as the value of the first form. This prevents [47mld[0m from printing the value of the first form. Since we have not exited [47mld[0m, that function just continues by reading the next form from the comment window. The user perceives this as entering a read-eval-print loop and being prompted for input. We continue in the loop until the user types [47m:q[0m. The false branch of the [47mif[0m is taken when [47mx[0m has no [47mabsolute-event-number[0m property. We execute the form [47m(value :q)[0m, which is the programming equivalent of typing [47m:q[0m. That causes the [47mld[0m to exit. The [47mld[0m special variables set in the call to [47mwormhole[0m and further manipulated inside the first form to [47mld[0m may require explanation. By setting [47m:[0m[47m[ld-verbose][0m to [47mnil[0m, we prevent [47mld[0m from printing the familiar ACL2 banner when [47mld[0m is called. If [47m:ld-verbose nil[0m is deleted, then you would see something like ACL2 Version 4.0. Level 2. ... Type (good-bye) to quit completely out of ACL2. every time the first form is read and evaluated. By setting [47m:[0m[47m[ld-prompt][0m to [47mnil[0m we prevent [47mld[0m from printing the prompt before reading and evaluating the first form. As this example shows, to use full-blown wormholes you must understand the protocol for using wormhole status to control whether a wormhole state is manufactured for [47mld[0m and you must also understand programming with [47m[state][0m and the effects of the various [47m[ld][0m ``special variables.'' Had we defined [47mdemo-collect-symbols-and-print-events[0m before [47mmy-len[0m we could have called it instead of [47mdemo-collect[0m. Then ACL2 !>(my-len '(4 temp car "Hi" fix)) would have still collected all the symbols into the [47mdemo[0m wormhole, but on the symbols [47mcar[0m and [47mfix[0m it would have entered an interactive break. Here is the break that would be triggered when this version of [47mmy-len[0m encounters the [47mfix[0m. Entering a wormhole on the event name FIX Exit with :q V -8055 (DEFUN FIX (X) (DECLARE (XARGS :GUARD T :MODE :LOGIC)) (IF (ACL2-NUMBERP X) X 0)) Wormhole ACL2 !>(fix 123) 123 Wormhole ACL2 !>(fix t) 0 Wormhole ACL2 !>:q After printing the [47m(DEFUN FIX ...)[0m above the user in this session called [47mfix[0m twice to see how it behaves. Then the user issued the [47m:q[0m command to exit the interactive loop, allowing [47mmy-len[0m to continue. When [47mmy-len[0m finishes processing the list, it would return [47m5[0m. From the discussion above we see that wormholes can be used to create formatted output without passing in the ACL2 [47m[state][0m. For examples see [cw], in particular the discussion at the end of that documentation topic. Subtopics [Get-persistent-whs] Make a wormhole's status visible outside the wormhole [Make-wormhole-status] Creates a wormhole status object from given status, entry code, and data [Set-persistent-whs-and-ephemeral-whs] maintaining wormhole coherence [Set-wormhole-data] Sets the wormhole data object in a wormhole status object [Set-wormhole-entry-code] Sets the wormhole entry code in a wormhole status object [Sync-ephemeral-whs-with-persistent-whs] establishing wormhole coherence [Wormhole-data] Determines the wormhole data object from a wormhole status object [Wormhole-entry-code] Determines the wormhole entry code from a wormhole status object [Wormhole-eval] State-saving without [state] --- a short-cut to a parallel universe [Wormhole-implementation] Notes on how wormholes are implemented [Wormhole-p] Predicate to determine if you are inside a [47m[wormhole][0m [Wormhole-programming-tips] some tips for how to use wormholes [Wormhole-status] the two senses of a wormhole's status [Wormhole-statusp] Predicate recognizing well-formed wormhole status object") (wormhole-coherence (pointers) "See [wormhole-status].") (wormhole-data (wormhole) "Determines the wormhole data object from a wormhole status object General Form: (wormhole-data whs) See [wormhole]. Returns the wormhole data from a well-formed wormhole status [47mwhs[0m. If [47mwhs[0m is [47mnil[0m or not well-formed, the data is [47mnil[0m.") (wormhole-entry-code (wormhole) "Determines the wormhole entry code from a wormhole status object General Form: (wormhole-entry-code whs) See [wormhole]. Returns [47m:ENTER[0m or [47m:SKIP[0m given a well-formed wormhole status [47mwhs[0m. If [47mwhs[0m is [47mnil[0m or not well-formed, the entry code is [47m:ENTER[0m.") (wormhole-eval (wormhole) "State-saving without [state] --- a short-cut to a parallel universe Example Form: (wormhole-eval 'demo '(lambda (whs) (set-wormhole-data whs (cons (cons name info) (wormhole-data whs)))) (prog2$ info name)) General Form: (wormhole-eval name lambda varterm) where [47mname[0m must be a quoted wormhole name and [47mlambda[0m must be a quoted [47mlambda[0m-expression as described below. It is forbidden to invoke [47mwormhole-eval[0m on the names listed in [47m*protected-system-wormhole-names*[0m, which includes [47mbrr[0m (the [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and [47mfc-wormhole[0m (the name of the wormhole managing [forward-chaining-reports]), among others. The [47mlambda[0m-expression must have at most one formal parameter but the body of the [47mlambda[0m-expression may contain other variables. Note that in the example form given above, the [47mlambda[0m has one formal, [47mwhs[0m, and uses [47mname[0m and [47minfo[0m freely. Note that the [47mlambda[0m is quoted. The third argument of [47mwormhole-eval[0m, [47mvarterm[0m, is an arbitrary term that should mention all of the free variables in the [47mlambda[0m-expression. That term establishes your ``right'' to refer to those free variables in the environment in which the [47mwormhole-eval[0m expression occurs. The value of [47mvarterm[0m is irrelevant and if you provide [47mnil[0m ACL2 will automatically provide a suitable term, namely a [47mprog2$[0m form like the one shown in the example above. Aside: Exception for ACL2(p) (see [parallelism]) to the irrelevance of [47mvarterm[0m. By default, calls of [47mwormhole-eval[0m employ a lock, [47m*wormhole-lock*[0m. To avoid such a lock, include the symbol [47m:NO-WORMHOLE-LOCK[0m in [47mvarterm[0m; for example, you might replace a last argument of [47mnil[0m in [47mwormhole-eval[0m by [47m:NO-WORMHOLE-LOCK[0m. End of Aside. See [wormhole] for a full explanation of wormholes. Most relevant here is that every wormhole has a name and a status. The status is generally a cons pair whose [47mcar[0m is the keyword [47m:ENTER[0m or the keyword [47m:SKIP[0m and whose [47mcdr[0m is an arbitrary object used to store information from one wormhole call to the next. Here is a succinct summary of [47mwormhole-eval[0m. If the [47mlambda[0m-expression has a local variable, [47mwormhole-eval[0m applies the [47mlambda[0m-expression to the persistent-whs (see [47m[wormhole-status][0m) of the named wormhole and remembers the value as the new persistent-whs. If the [47mlambda[0m has no formal parameter, the [47mlambda[0m is applied to no arguments and the value is the new persistent-whs. [47mWormhole-eval[0m returns [47mnil[0m. Thus, the formal parameter of the [47mlambda[0m-expression, if provided, denotes the wormhole's hidden status information; the value of the [47mlambda[0m is the new status and is hidden away. The guard of a [47mwormhole-eval[0m call is the guard of the body of the [47mlambda[0m-expression, with a fresh variable symbol used in place of the formal so that no assumptions are possible about the hidden wormhole status. If the guard of a [47mwormhole-eval[0m is verified, the call is macroexpanded inline to the evaluation of the body in a suitable environment. Thus, it can be a very fast way to access and change the persistent-whs, but the results remain hidden. To interact with the wormhole's state you must use [47m[wormhole][0m. Functions that are probably useful in the body of the [47m[lambda][0m or the guard of a function using [47mwormhole-eval[0m include the following: [47m[wormhole-statusp][0m, [47m[wormhole-entry-code][0m, [47m[wormhole-data][0m, [47m[set-wormhole-entry-code][0m, [47m[set-wormhole-data][0m, and [47m[make-wormhole-status][0m. [47mWormhole-eval[0m is intended to be fast, but it is further optimized when the given [47mlambda[0m is of the following form. In this case [47mwormhole-eval[0m returns immediately when the [47m[wormhole-data][0m is [47mnil[0m, which is reasonable since the old and new status are equal in this case. (lambda (whs) (let ((info (wormhole-data whs))) (cond ((null info) whs) ...))) See [wormhole] for a series of example uses of [47mwormhole-eval[0m and [47mwormhole[0m. For a behind-the-scenes description of how wormholes work, See [wormhole-implementation]. Subtopics [Wormhole-programming-tips] some tips for how to use wormholes") (wormhole-implementation (wormhole) "Notes on how wormholes are implemented What happens when you call [47m[wormhole][0m? Recall that a typical call of the function looks like this: (wormhole 'name '(lambda (whs) ...) input form :ld-verbose ... ...) A brief recap of the advertised semantics for [47mwormhole[0m establishes our terminology: When the above [47mwormhole[0m is evaluated, the [47mlambda[0m-expression is applied to the persistent-whs and the result is stored as the new persistent-whs. Then, if the entry-code of the new status is [47m:ENTER[0m (actually, if it is not [47m:SKIP[0m), [47m[ld][0m is invoked on a copy of the ``current state'' with the specified [47mld-[0m ``special variables;'' output is directed to the comment window. In that copy of the state, the state global variables [47mwormhole-name[0m, [47mwormhole-input[0m and [47mwormhole-status[0m are assigned [47mname[0m, the value of [47minput[0m and the persistent-whs, respectively. Thus, inside the wormhole, [47m(@ wormhole-name)[0m returns the name of the current wormhole, [47m(@ wormhole-input)[0m returns the list of inputs, [47m(@ wormhole-status)[0m returns the ephemeral-whs. The first form executed by the [47mld[0m is the value of [47mform[0m and unless that form returns [47m(value :q)[0m, causing the [47mld[0m to quit, the [47mld[0m proceeds to take subsequent input from the comment window. Upon exiting from [47mld[0m, the ephemeral-whs is written to the persistent-whs and the wormhole state ``evaporates.'' The next time the wormhole is entered its ephemeral-whs will be what it was when it last exited. Here is what really happens. Each wormhole's persistent-whs is recorded in an alist stored in a Common Lisp global variable named [47m*wormhole-status-alist*[0m. This variable is not part of the ACL2 state. If you exit the ACL2 loop with [47m:q[0m you can inspect the value of [47m*wormhole-status-alist*[0m. However, be cautious about printing it because the persistent-whs of some wormholes can be quite large. When the [47mlambda[0m-expression is evaluated it is applied to the value associated with [47mname[0m in the alist and the result is stored back into that alist. This step is performed by [47m[wormhole-eval][0m. To make things more efficient, [47mwormhole-eval[0m is just a macro that expands into a [47mlet[0m that binds the [47mlambda[0m formal to the current status and whose body is the [47mlambda[0m body. [Guard] [clause]s are generated from the body, with one exception: the [47mlambda[0m formal is replaced by a new variable so that no prior assumptions are available about the value of the wormhole status. If the newly computed status has an entry code other than [47m:SKIP[0m [47m[ld][0m will be invoked. But we don't really copy state, of course. Instead we will invoke [47mld[0m on the live state, which is always available in the von Neumann world in which ACL2 is implemented. To give the illusion of copying state, we will undo changes to the state upon exiting. To support this, we do two things just before invoking [47mld[0m: we bind a Common Lisp special variable, [47m*wormholep*[0m, to [47mt[0m to record that ACL2 is in a wormhole, and we initialize an accumulator that will be used to record state changes made while in the wormhole. Then we assign the three state globals [47mwormhole-name[0m, [47mwormhole-input[0m, and [47mwormhole-status[0m. Those assignments are made undoably since [47m*wormholep*[0m is set. Then [47mld[0m is invoked, with first argument, [47mstandard-oi[0m, being set to [47m(cons form *standard-oi*)[0m. According to the standard semantics of [47mld[0m, the first read from this [47mstandard-oi[0m returns [47mform[0m and subsequent reads, if any, come from [47m*standard-oi*[0m. The standard channels are directed to and from the terminal, which is the physical realization of the comment window. All state modifying functions of ACL2 are sensitive to the special variable [47m*wormholep*[0m that indicates that evaluation is in a wormhole. Some ACL2 state-modifying functions (e.g., those that modify the file system like [47m[write-byte$][0m) are made to cause an error if invoked inside a wormhole on a file other than the terminal. Others, like [47mf-put-global[0m (the function behind such features as [47massign[0m and maintenance of the ACL2 logical world by such events as [47m[defun][0m and [47m[defthm][0m) are made to record the old value of the state component being changed; these records are kept in the accumulator initialized above. Upon exit from [47mld[0m for any reason, the ephemeral-whs is transferred to the persistent-whs, i.e., the final value of [47m(@ wormhole-status)[0m is stored under the current [47mwormhole-name[0m in [47m*wormhole-status-alist*[0m and then the accumulator is used to ``undo'' all the state changes. [47mWormhole[0m always returns [47mnil[0m. The system wormhole named [47mbrr[0m, which implements [break-rewrite], is treated a little differently. When [47mld[0m exits due to an abort the ephemeral-whs is not transferred to the persistent-whs. Instead, the persistent-whs is set to what it was at the time break-rewrite was first entered from the top-level. See the Essay on Break-Rewrite in the source code file [47mrewrite.lisp[0m for details about the implementation of break-rewrite, which is intimately connected to wormholes.") (wormhole-p (wormhole) "Predicate to determine if you are inside a [47m[wormhole][0m See [wormhole] for a discussion of wormholes. [47m(Wormhole-p state)[0m returns [47m(mv nil t state)[0m when evaluated inside a wormhole, else [47m(mv nil nil state)[0m.") (wormhole-programming-tips (wormhole wormhole-eval) "some tips for how to use wormholes Wormholes allow one to collect data and print without having access to ACL2's [47m[state][0m. Many ACL2 utilities are implemented in terms of wormholes. Examples include [break-rewrite], [47m[accumulated-persistence][0m, and [47m[forward-chaining-reports][0m. So an ACL2 developer wishing to add features or fixing misbehaviors in these system utilities must be familiar with programming wormholes. But users might also employ wormholes to implement utilities in their own models. Thus, this documentation topic is as much for future ACL2 developers and maintainers as for ACL2 users (but items meant primarily for developers often include references to functions in the ACL2 source code which other users may just ignore). This is simply a list of tips for a person programming with wormholes. This list doesn't replace the topics [47m[wormhole][0m and [47m[wormhole-eval][0m, and their subtopics including the particularly relevant [wormhole-status]. But this list of tips might serve as a useful reminder when you're programming with wormholes. * The ``function'' [47m[wormhole][0m is really a macro that expands in raw Lisp into a call of [47m[wormhole-eval][0m to set the entry code and then a call of [47mwormhole1[0m to do the interactive work. But in addition, the source code functions [47mev-rec[0m, [47mtranslate11-wormhole-eval[0m, [47mtranslate11-call-1[0m, and [47mtranslate11-call[0m all contain special provisions for wormholes. Do not think you can add features to wormholes by just changing the definition of [47mwormhole[0m or [47mwormhole1[0m! These functions are in what we call the wormhole implementation nexus and there is entitled ``[47m; Essay on the Wormhole Implementation Nexus[0m'' in the source file [47maxioms.lisp[0m. * The built-in ACL2 system wormholes are protected by mechanisms in [47mtranslate11-call-1[0m and [47mtranslate11-call[0m so that code executed during ACL2's boot-strapping process is allowed to manipulate system wormholes but code executed after boot-strap cannot. Search the source code for occurrences of [47m*protected-system-wormhole-names*[0m. * System implementors and maintainers may be hampered by being unable to invoke wormhole functions on system wormholes like [47mbrr[0m or [47maccumulated-persistence[0m. One way around that, e.g., to test changes to existing code, is to execute [47m(defconst *protected-system-wormhole-names* nil)[0m after doing [47m(redef+)[0m. * Users may wish to employ wormholes so they can build tools allowing the [47m[state][0m-less exploration of their models. But we confess that to make wormholes as useful to other tool developers as they are to the ACL2 developers we will need to add some protection features (similar to those in the item above) to user-defined wormholes. Ideas we have toyed with but not implemented include pairing a wormhole's name with various attributes such as a flag to prevent its use except through named interfaces, a wrapper form or filter that applies to every form read, translated, and evaluated by the [47mld[0m inside that wormhole, and what should happen when the wormhole is exited. But these ideas are not implemented. If you really need them, let us know. * Each wormhole has a name, which is typically but not necessarily a symbol. * Each wormhole has a current status. The status is a cons whose [47mcar[0m is either [47m:ENTER[0m or [47m:SKIP[0m, and whose [47mcdr[0m is an arbitrary ACL2 object managed by the creator of the wormhole. The [47mcar[0m of the status is called the ``entry code''. The [47mcdr[0m is called the ``data''. See [47m[wormhole-entry-code][0m, [47m[wormhole-data][0m, and [47m[make-wormhole-status][0m. * The status object of a wormhole named [47mnm[0m is stored in raw Lisp in a part of memory inaccessible to ACL2 terms other than the ACL2 oracle (see [47m[read-ACL2-oracle][0m). We call this the [3mpersistent wormhole status[0m or [3mpersistent-whs[0m. If you're in raw Lisp --- which you can reach by exiting the ACL2 loop with [47m:q[0m or by invoking [47m[break$][0m --- you can recover the persistent-whs of the [47mnm[0m wormhole with [47m(cdr (assoc nm *wormhole-status-alist*))[0m. However, the logic-mode function [47m[get-persistent-whs][0m takes a name and [47mstate[0m returns an error triple containing the persistent status. [47mGet-persistent-whs[0m reads the ACL2 oracle (see [read-ACL2-oracle]) to get the otherwise hidden status of the wormhole. In doing so it changes the state. So if you're not in a context in which you have [47mstate[0m and can return a modified state, you can't use [47mget-persistent-whs[0m. * [47m[Wormhole-eval][0m gives you a way, without access to state, to set the persistent-whs of a named wormhole as a function of its current persistent-whs. [47mWormhole-eval[0m takes a wormhole name, a lambda expression, and a term (which is functionally irrelevant), applies the lambda expression to the persistent-whs, stores as the new persistent-whs, and returns [47mnil[0m. * [47m[Wormhole][0m is a function that allows you to set and test the status of a named wormhole and if the resulting status has an entry code of [47m:enter[0m you will enter a read-eval-print loop. Wormhole has two other arguments, the so-called ``input'' object and the ``first form'' to execute if and when the loop is entered. * The read-eval-print loop is managed by [47m[ld][0m, the same function that manages ACL2's top-level read-eval-print loop. The [47mwormhole[0m function allows you to specify the standard [47mld[0m variables (e.g., [47m[ld-error-action][0m, etc.). One of those variables is [47m[ld-keyword-aliases][0m which specifies the behaviors of keyword commands issued in the wormhole's loop. * Before [47mwormhole[0m (actually [47mwormhole1[0m) calls [47mld[0m it sets the three important state global variables mentioned below. Then while in the interactive loop: (@ wormhole-name) = nm (@ wormhole-input) = the ``input'' object supplied to wormhole (@ wormhole-status) = the wormhole's persistent-whs at the time of entry * When inside the interactive loop of the wormhole we call the value of [47mwormhole-status[0m the [3mephemeral wormhole status[0m or [3mephemeral-whs[0m. It ``disappears'' when the wormhole is exited but it is easy to read without changing state while inside the wormhole. * The ``first form'' is very often the only form executed! We typically use that form to grab the input and the status and print stuff. Then the first form returns [47m(value :q)[0m. Recall that typing [47m(value :q)[0m to the ACL2 loop (i.e., to [47m[ld][0m) exits the loop, which exits the wormhole. See the example in the documentation topic [47m[wormhole][0m, starting with "[47m(wormhole 'demo[0m". If the first form returns any other non-erroneous value triple, user input is read and evaluated. So if your first form always returns [47m(value :q)[0m you're in complete control of your wormhole --- and if it doesn't, you're not because the next thing that happens is the wormhole reads and evaluates whatever the user types! * The use of [47mld[0m to manage the read-eval-print loop means that the user can execute virtually any ACL2 term. If you use [47mwormhole[0m and allow input from the user, you have no control over the operations performed. * If, while in the [47mnm[0m wormhole, you execute [47m(wormhole-eval nm ...)[0m it will set the persistent-whs but not set the ephemeral-whs. (Recall, [47mwormhole-eval[0m does not have access to [47mstate[0m.) This means that you can't trust [47m(@ wormhole-status)[0m after a call of [47mwormhole-eval[0m --- or of any function that calls [47mwormhole-eval[0m --- from within the wormhole. * This brings us to the [3mWormhole Coherence Convention[0m. The problem described in the bullet above is akin to the cache coherence problem. Think of the persistent-whs stored in [47m*wormhole-status-alist*[0m as being stored in a distant memory location and the ephemeral-whs stored in [47m(@ wormhole-status)[0m as a nearby, easily accessible cache when you're in the wormhole. [47mWormhole-eval[0m reads and writes the persistent-whs and does not update the cache. The Wormhole Coherence Convention is to keep persistent-whs and the ephemeral-whs equal. Of course, the convention is meant to hold except in the region of code between updating the two locations. * The wormhole programmer is responsible for maintaining the wormhole coherence --- or not. It's up to you. But remember: if your wormhole permits user interaction, you can't prevent the execution of certain forms. * The state global variable [47mwormhole-status[0m is untouchable, so the user cannot just execute [47m(assign wormhole-status new-status)[0m to change it. But [47mwormhole-status[0m can be changed by certain special functions available to the user, namely [47m[sync-ephemeral-whs-with-persistent-whs][0m and [47m[set-persistent-whs-and-ephemeral-whs][0m, though these will only have effect after executing [47m[wormhole-eval][0m or [47m[wormhole][0m. * We have already mentioned [47mwormhole-eval[0m, which writes to the persistent-whs not to the ephemeral-whs. But the other two utilities mentioned above are helpful in establishing and maintaining coherence. * [47m(sync-ephemeral-whs-with-persistent-whs nm state)[0m moves the ``distant'' memory status into the cached status. It returns the modified state. * [47m(set-persistent-whs-and-ephemeral-whs nm new-status state)[0m writes [47mnew-status[0m to the persistent-whs of [47mnm[0m and, if you're in the wormhole [47mnm[0m, it also updates the ephemeral-whs status. It returns a new state. * Using [47msync-ephemeral-whs-with-persistent-whs[0m and [47mset-persistent-whs-and-ephemeral-whs[0m you can program your wormhole operations to establish and maintain coherence. But you can't prevent the user from breaking it if you allow user interaction. * While it may seem that [47mset-persistent-whs-and-ephemeral-whs[0m is the preferred way to update the status of a wormhole, that function suffers from the requirement that you have to have the new status in hand when you call [47mset-persistent-whs-and-ephemeral-whs[0m. So from a practical perspective [47mset-persistent-whs-and-ephemeral-whs[0m is either used outside the wormhole to initialize the status to some standard value or is used inside the wormhole after having obtained the current status from the cache and modifying it to create the new status. * Both [47msync-ephemeral-whs-with-persistent-whs[0m and [47mset-persistent-whs-and-ephemeral-whs[0m take and return [47mstate[0m and so can only be used in contexts allowing that. * In contrast, [47mwormhole-eval[0m allows you to compute the new status as a function of the old status, [3mWITHOUT HAVING PRIOR ACCESS[0m to the old status and without access to [47mstate[0m. But then remember to call [47msync-ephemeral-whs-with-persistent-whs[0m, which will restore coherence. * The most direct way to establish and maintain the wormhole coherence is to avoid use of fully interactive calls of [47mwormhole[0m (i.e., make sure the first form executed always returns [47m(value :q)[0m), and do all modifications to the wormhole status with [47mwormhole-eval[0m, which reads and writes the persistent-whs. For example, search the ACL2 sources for occurrences of [47m'accumulated-persistence[0m. You'll see [47mwormhole-eval[0m is used to collect all the data. Then in [47mshow-accumulated-persistence-fn[0m, [47mwormhole[0m is used to display the data and exit with [47m(value :q)[0m. * But the [47m[break-rewrite][0m wormhole, named [47mbrr[0m, is necessarily different because the whole intention is to allow interaction with the user! So there is special code here and there throughout ACL2 to maintain coherence. We're sorry we don't provide suitable provisions for other users! * If you're in a wormhole, all modifications to state globals during the execution of the commands in the read-eval-print loop will be undone when the loop is exited. This cleanup is done in the raw Lisp code for [47mwormhole1[0m, by evaluating the raw Lisp form held in [47m*wormhole-cleanup-form*[0m. That form is destructively modified every time an [47mf-put-global[0m is executed from within some wormhole. The modification introduces code to undo each [47mf-put-global[0m and restore the previous values. * The cleanup form just mentioned contains special code for the [47mbreak-rewrite[0m wormhole! Look for [47m'brr[0m in [47mwormhole1[0m and read the comments.") (wormhole-status (wormhole) "the two senses of a wormhole's status As noted in the discussion of [47mwormhole[0ms, every wormhole has a current status, which is some ACL2 object whose shape is largely determined by the author of the wormhole. That object is not stored in the ACL2 state. When the wormhole is entered, its status is assigned to the state global variable [47mwormhole-status[0m, making it visible. When the wormhole is exited, the value of [47mwormhole-status[0m is transferred back to its ``hidden'' location outside of the state. Thus, the next time it is entered the [47mwormhole-status[0m is the same as it was when it was last exited. We call the ``hidden'' version of a wormhole's status the [3mpersistent wormhole status[0m or [3mpersistent-whs[0m and the version occasionally found in the state global [47mwormhole-status[0m as the [3mephemeral wormhole status[0m or [3mephemeral-whs[0m. It is helpful to think of the persistent-whs as the wormhole's status as stored in some distant location and its ephemeral-whs as an easily accessible, nearby cache. When the two locations hold the same value we say the wormhole is [3mcoherent[0m. The state global variable [47mwormhole-status[0m is untouchable: you can read it but not directly write to it via [47m[assign][0m or [47m[f-put-global][0m. But you can write to the persistent-whs. That is what [47m[wormhole-eval][0m does. So while a wormhole is coherent when you first enter it it can become incoherent if you use [47mwormhole-eval[0m to change its persistent-whs while inside the wormhole. And remember, the use of [47mwormhole-eval[0m can be disguised via a function definition. The following script illustrates this. First, create a wormhole named [47mdemo[0m whose data field is empty. We'll use it to accumulate items without modifying state. We define [47m(save x)[0m to cons [47mx[0m onto the data field of the [47mdemo[0m wormhole. So execute these five commands at the top-level of ACL2. (wormhole-eval 'demo '(lambda nil '(:enter . nil)) nil) (defun save (x) (wormhole-eval 'demo '(lambda (whs)(set-wormhole-data whs (cons x (wormhole-data whs)))) nil)) (save 'a) (save 'b) (save 'c) Then inspect the persistent-whs of [47mdemo[0m: ACL2 !>(get-persistent-whs 'demo state) (:ENTER C B A) So [47msave[0m works as we planned. But now let's enter the [47mdemo[0m wormhole. Inside the wormhole we first inspect the ephemeral-whs (i.e., [47m(@ wormhole-status)[0m, and the persistent-whs to confirm the wormhole is coherent. Then we execute [47m(save 'd)[0m to add [47mD[0m to the accumulator. Inspecting the persistent-whs shows that it worked. But the ephemeral-whs did not change! The wormhole is now incoherent, thanks to the ``disguised'' use of [47mwormhole-eval[0m while in the wormhole. ACL2 !>(wormhole 'demo '(lambda (whs) whs) nil '(quote (welcome!))) Project-dir-alist: ((:SYSTEM . "/Users/moore/Desktop/v85k1/books/")). Type :help for help. Type (quit) to quit completely out of ACL2. Wormhole ACL2 !>(WELCOME!) Wormhole ACL2 !>(@ wormhole-status) (:ENTER C B A) Wormhole ACL2 !>(get-persistent-whs 'demo state) (:ENTER C B A) Wormhole ACL2 !>(save 'd) NIL Wormhole ACL2 !>(get-persistent-whs 'demo state) (:ENTER D C B A) Wormhole ACL2 !>(@ wormhole-status) (:ENTER C B A) Wormhole ACL2 !>:q NIL The [47m:q[0m above exits the wormhole. Now re-enter the wormhole and inspect the ephemeral-whs and persistent-whs. ACL2 !>(wormhole 'demo '(lambda (whs) whs) nil '(quote (welcome back!))) Project-dir-alist: ((:SYSTEM . "/Users/moore/Desktop/v85k1/books/")). Type :help for help. Type (quit) to quit completely out of ACL2. Wormhole ACL2 !>(WELCOME BACK!) Wormhole ACL2 !>(@ wormhole-status) (:ENTER C B A) Wormhole ACL2 !>(get-persistent-whs 'demo state) (:ENTER C B A) Wormhole ACL2 !>(value :q) NIL The wormhole is coherent of course; wormholes are always coherent upon entry. But notice the value of the data field! It doesn't list [47mD[0m! That happened because when we exited the wormhole, the ephemeral-whs was written back to the persistent-whs, and the ephemeral-whs of the incoherent status did not contain [47mD[0m. There are ways ensure that your wormholes remain coherent and they all involve using the function [47m[sync-ephemeral-whs-with-persistent-whs][0m, which does what its name says. For example, we could have defined [47msave[0m this way instead. (defun save (x state) (prog2$ (wormhole-eval 'demo '(lambda (whs)(set-wormhole-data whs (cons x (wormhole-data whs)))) nil) (sync-ephemeral-whs-with-persistent-whs 'demo state))) But note that we must now provide [47mstate[0m as an argument to all calls of [47msave[0m and [47msave[0m must return [47mstate[0m because [47m[read-ACL2-oracle][0m was used to reach out to the [47mpersistent-whs[0m to refresh the ephemeral-whs. This means we can only call this version of [47msave[0m in environments in which we have [47mstate[0m and can return [47mstate[0m. Perhaps a better way preserve coherence is to keep [47msave[0m defined in the earlier, [47mstate[0m-less way but to call [47msync-ephemeral-whs-with-persistent-whs[0m from within the wormhole after we call [47m(save 'd)[0m. That is easy enough to do if you are in complete control of the [47mdemo[0m wormhole. Recall the specification of [47m[wormhole][0m. If the entry [47mlambda[0m sets the [47m[wormhole-entry-code][0m to [47m:enter[0m, then [47m[ld][0m is invoked but the first form executed by the resulting read-eval-print loop is the [47mform[0m argument of [47mwormhole[0m. We used the [47mform[0m argument in the script above to just print a greeting but it can be an arbitrary form. If [47mform[0m returns [47m(value nil)[0m the [47mld[0m is exited without ever giving the user the opportunity to type and evaluate an arbitrary form. But if the [47mdemo[0m wormhole allows a user to type and evaluate arbitrary forms (including forms like [47mwormhole-eval[0m or the [47mstate[0m-less [47msave[0m), there is no way to ensure coherency. We admit this is an unfortunate aspect of the current design. The simplest way to avoid such problems is to use [47mwormhole-eval[0m exclusively and avoid use of the interactive read-eval-print loop provided by [47m[wormhole][0m, except loops intended for experts. This is the approach taken by such system utilities as [47m[accumulated-persistence][0m and [47m[fc-report][0m: [47mwormhole-eval[0m is used to collect data and either [47mwormhole-eval[0m or a non-interactive [47mwormhole[0m is used to display it.") (wormhole-statusp (wormhole) "Predicate recognizing well-formed wormhole status object General Form: (wormhole-statusp whs) See [wormhole]. This predicate is useful in guards for wormholes. It checks whether [47mwhs[0m is either [47mnil[0m or a cons whose car is [47m:ENTER[0m or [47m:SKIP[0m.") (write-byte$ (pointers) "See [io].") (xargs (defun declare) "Extra arguments, for example to give [hints] to [47m[defun][0m Common Lisp's [47m[defun][0m function does not easily allow one to pass extra arguments such as ``[hints]''. ACL2 therefore supports a peculiar new declaration (see [declare]) designed explicitly for passing additional arguments to [47m[defun][0m via a keyword-like syntax. This declaration can also be used with [47m[defmacro][0m, but only for [47mxargs[0m keyword [47m:guard[0m; so we restrict attention below to use of [47mxargs[0m in [47m[defun][0m [events]. The following declaration is nonsensical but does illustrate all of the [47mxargs[0m keywords for [47m[defun][0m (which are the members of the list [47m*xargs-keywords*[0m). (declare (xargs :guard (symbolp x) :guard-debug t :guard-simplify :limited :guard-hints (("Goal" :in-theory (theory batch1))) :hints (("Goal" :in-theory (theory batch1))) :loop$-recursion t :measure (- i j) :measure-debug t :mode :logic :non-executable t :normalize nil :otf-flg t ; the default for defun :ruler-extenders :basic :split-types t :stobjs ($s) :dfs (v1 v2) :type-prescription (natp (foo x y)) :verify-guards t :well-founded-relation my-wfr)) General Form: (xargs :key1 val1 ... :keyn valn) where the keywords and their respective values are as shown below. Note that once ``inside'' the xargs form, the ``extra arguments'' to [47m[defun][0m are passed exactly as though they were keyword arguments. [47m:guard[0m [47mValue[0m is a term involving only the formals of the function being defined. The actual [guard] used for the definition is the conjunction of all the [guard]s and types declared, in the order lexically given, preceded by conjuncts corresponding to the [47m:[0m[47m[stobj][0m declarations (if any, and including [47m(state-p state)[0m if [47mstate[0m is a formal). Also see [declare]. Note that if no [47m:guard[0m is specified explicitly, then a guard of [47mt[0m is assumed, as though one had declared [47m(xargs :guard t)[0m. (Note that [47mt[0m is indeed a term involving only the formals; it specifies that the guard requirement is always met.) However, by default, a [47m:[0m[47m[logic][0m mode function definition will not attempt to verify guards unless an explicit [47mxargs[0m [47m:guard[0m declaration is provided. For details on this point, as well as how to change that default behavior, see [set-verify-guards-eagerness]. [47m:guard-debug[0m [47mValue[0m: [47mnil[0m by default, else directs ACL2 to decorate each guard proof obligation with hypotheses indicating its sources. See [guard-debug]. [47m:guard-hints[0m [47mValue[0m: hints (see [hints]), to be used during the [guard] verification proofs as opposed to the termination proofs of the [47m[defun][0m. Note that these hints apply only to guard proofs, not to the generation of guard proof obligations; for that, see [guard-simplification]. [47m:guard-simplify[0m [47mValue[0m: [47mt[0m by default, which supports simplification performed while generating the guard proof obligation. The value can also be [47m:limited[0m, which directs ACL2 to skip such simplification that depends on which rules are currently [enable]d. This has the same effect as the corresponding keyword argument to [47m[verify-guards][0m. Also see [guard-simplification] and [guard-formula-utilities]. [47m:[0m[47m[hints][0m Value: hints (see [hints]), to be used during the termination proofs as opposed to the [guard] verification proofs of the [47m[defun][0m. [47m:[0m[47m[loop$-recursion][0m Value: this flag must be set to [47mt[0m or [47mnil[0m; [47mnil[0m is the default. The flag must be [47mt[0m if and only if the function being defined calls itself recursively from within a [47m[loop$][0m body or within a [47mwhen[0m or [47muntil[0m clause. See [loop$-recursion]. [47m:measure[0m [47mValue[0m is a term involving only the formals of the function being defined. This term indicates what is getting smaller in the recursion. The well-founded relation with which successive measures are compared is [47m[o<][0m by default, but can be changed using the [47m:well-founded-relation[0m keyword or with the [set-well-founded-relation] event. Also allowed is a special case, [47m(:? v1 ... vk)[0m, where [47m(v1 ... vk)[0m enumerates a subset of the formal parameters such that some valid measure involves only those formal parameters. However, this special case is only allowed for definitions that are redundant (see [redundant-events]) or are executed when skipping proofs (see [skip-proofs]). Another special case is [47m:measure nil[0m, which is treated the same as if [47m:measure[0m is omitted. Note that a [47m:measure[0m is not allowed for a non-recursive definition (other than the ``measure'' [47mnil[0m) unless the definition is part of a [mutual-recursion]; moreover, if a [47m:measure[0m is supplied, then it must be a legal term. Apart from these restrictions, the [47m:measure[0m is ignored in [47m:[0m[47m[program][0m mode; see [defun-mode]. [47m:measure-debug[0m [47mValue[0m: [47mnil[0m by default, else directs ACL2 to decorate each termination proof obligation with hypotheses indicating its sources. See [measure-debug]. [47m:mode[0m [47mValue[0m is [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m, indicating the [47m[defun][0m mode of the function introduced. See [defun-mode]. If unspecified, the [47m[defun][0m mode defaults to the default [47m[defun][0m mode of the current [world]. To convert a function from [47m:[0m[47m[program][0m mode to [47m:[0m[47m[logic][0m mode, see [verify-termination]. [47m:non-executable[0m [47mValue[0m is normally [47mt[0m or [47mnil[0m (the default). Rather than stating [47m:non-executable t[0m directly, which requires [47m:[0m[47m[logic][0m mode and that the definitional body has a certain form, we suggest using the macro [47mdefun-nx[0m or [47mdefund-nx[0m; see [defun-nx]. A third value of [47m:non-executable[0m for advanced users is [47m:program[0m, which is generated by expansion of [47mdefproxy[0m forms; see [defproxy]. For another way to deal with non-executability, see [non-exec]. [47m:normalize[0m Value is a flag telling [47m[defun][0m whether to perform certain simplification before storing the body of the function; see [normalize]. Since the default is to do such [normalization], the value supplied is only of interest when it is [47mnil[0m. (See [defun]). [47m:[0m[47m[otf-flg][0m Value is a flag indicating ``Onward Through the Fog'', to keep the prover from starting over when it encounters a second subgoal to be pushed for later proof by induction. See [otf-flg]). The default is [47mt[0m when processing a [47m[defun][0m or [47m[verify-termination][0m event and [47mnil[0m otherwise. [47m:ruler-extenders[0m For recursive definitions (possibly mutually recursive), [47mvalue[0m controls termination analysis and the resulting stored induction scheme. See [rulers] for a discussion of legal values and their effects. See [induction-coarse-v-fine-grained] for a discussion of how a well-chosen [47m:ruler-extenders[0m setting may improve the induction scheme suggested by a function. [47m:[0m[47msplit-types[0m [47mValue[0m is [47mt[0m or [47mnil[0m, indicating whether or not [type]s are to be proved from the [guard]s. The default is [47mnil[0m, indicating that type declarations (see [declare]) contribute to the [guard]s. If the value is [47mt[0m, then instead, the expressions corresponding to the type declarations (see [type-spec]) are conjoined into a ``split-type expression,'' and guard verification insists that this term is implied by the specified [47m:guard[0m. Suppose for example that a definition has the following [47m[declare][0m form. (declare (xargs :guard (p x y) :split-types t) (type integer x) (type (satisfies good-bar-p) y)) Then for guard verification, [47m(p x y)[0m is assumed, and in addition to the usual proof obligations derived from the body of the definition, guard verification requires a proof that [47m(p x y)[0m implies both [47m(integerp x)[0m and [47m(good-bar-p y)[0m. See community book [47mdemos/split-types-examples.lisp[0m for small examples. [47m:stobjs[0m [47mValue[0m is either a single [47m[stobj][0m name or a true list of stobj names (see [stobj] and see [defstobj], and perhaps see [defabsstobj]). Every stobj name among the formals of the function must be listed, if the corresponding actual is to be treated as a stobj. That is, if a function uses a stobj name as a formal parameter but the name is not declared among the [47m:stobjs[0m then the corresponding argument is treated as ordinary. The only exception to this rule is [47m[state][0m: whether you include it or not, [47mstate[0m is always treated as a single-threaded object. This declaration has two effects. One is to enforce the syntactic restrictions on single-threaded objects. The other is to strengthen the [47m[guard][0m of the function being defined so that it includes conjuncts specifying that each declared single-threaded object argument satisfies the recognizer for the corresponding single-threaded object. [47m:dfs[0m [47mValue[0m is either a single variable or a true list of variables. See [df]. [47m:type-prescription[0m [47mValue[0m is either [47mnil[0m (the default) or a formula that is suitable for a hypothesis-free [47m:[0m[47m[type-prescription][0m rule. That rule must be appropriate for the [47m:typed-term[0m that is the application of the defined function symbol to its formal parameters. For example, a legal value for [47m:type-prescription[0m in [47m(defun f (x y) ...)[0m could be [47m(or (consp (f x y)) (equal (f x y) y))[0m, but not [47m(or (consp (f u v)) (equal (f u v) v))[0m. The specified formula must provide a type that is implied by the built-in type that is computed for the defined function. Normally these will be equal, but if the value of [47m:type-prescription[0m specifies a strictly weaker type than the computed built-in type then a warning will be printed (unless of course such warnings have been suppressed; see [set-inhibit-output-lst] and [set-inhibit-warnings]). It is an error to supply a non-[47mnil[0m value for [47m:type-prescription[0m if there is no built-in type computed for the function. See also [type-prescription]. [47m:[0m[47m[verify-guards][0m [47mValue[0m is [47mt[0m or [47mnil[0m, indicating whether or not [guard]s are to be verified upon completion of the termination proof. This flag should only be [47mt[0m if the [47m:mode[0m is unspecified but the default [47m[defun][0m mode is [47m:[0m[47m[logic][0m, or else the [47m:mode[0m is [47m:[0m[47m[logic][0m. [47m:[0m[47m[well-founded-relation][0m [47mValue[0m is a function symbol that is known to be a well-founded relation in the sense that a rule of class [47m:well-founded-relation[0m has been proved about it. The effect is to replace the default well-founded relation, which is typically [47m[o<][0m, by the specified value. See [well-founded-relation-rule] and see [set-well-founded-relation] for further discussion, including how to change the default well-founded-relation. Subtopics [Guard] Restricting the domain of a function [Measure] Declare a measure for a [47m[defun][0m [Normalize] Storing simplified [definition] bodies and [guard]s [Otf-flg] Allow more than one initial subgoal to be pushed for induction") (xor (basics acl2-built-ins) "Logical ``exclusive or'' [47mXor[0m is the ACL2 exclusive-or function. [47m(xor P Q)[0m means that either [47mP[0m or [47mQ[0m, but not both, is false (i.e., [47mnil[0m). [31;1mFunction: [0m<xor> (defun xor (p q) (declare (xargs :guard t)) (if p (if q nil t) (if q t nil)))") (you_must_think_about_the_use_of_a_formula_as_a_rule (pages_written_especially_for_the_tours) "You Must Think about the Use of a Formula as a Rule {IMAGE} (see [Using_the_Associativity_of_App_to_Prove_a_Trivial_Consequence]) This is [31;1mgood[0m and [31;1mbad[0m. The good news is that you can [31;1mprogram[0m ACL2's simplifier. The bad news is that when you command ACL2 to prove a theorem you must give some thought to [31;1mhow that theorem is to be used as a rule[0m! For example, if after proving [47massociativity-of-app[0m as previously shown, you engaged in the mathematically trivial act of proving it again but with the equality reversed, you would have programmed ACL2's rewriter to loop forever. You can avoid adding any rule by using the command: (defthm associativity-of-app (equal (app (app a b) c) (app a (app b c))) [31;1m:rule-classes nil[0m) {IMAGE} (see [Using_the_Associativity_of_App_to_Prove_a_Trivial_Consequence])") (zero-test-idioms (numbers) "How to test for 0 Below are six commonly used idioms for testing whether [47mx[0m is [47m0[0m. [47m[Zip][0m and [47m[zp][0m are the preferred termination tests for recursions down the integers and naturals, respectively. idiom logical guard primary meaning compiled code* (equal x 0) (equal x 0) t (equal x 0) (eql x 0) (equal x 0) t (eql x 0) (zerop x) (equal x 0) x is a number (= x 0) (= x 0) (equal x 0) x is a number (= x 0) (zip x) (equal (ifix x) 0) x is an integer (= x 0) (zp x) (equal (nfix x) 0) x is a natural (int= x 0) (zpf x) (equal (nfix x) 0) x is a fixnum >= 0 (eql (the-fixnum x) 0) *See [guards-and-evaluation], especially the subsection titled ``Guards and evaluation V: efficiency issues''. Primary code is relevant only if [guard]s are verified. The ``compiled code'' shown is only suggestive. The first four idioms all have the same logical meaning and differ only with respect to their executability and efficiency. In the absence of compiler optimizing, [47m(= x 0)[0m is probably the most efficient, [47m(equal x 0)[0m is probably the least efficient, and [47m(eql x 0)[0m is in between. However, an optimizing compiler could always choose to compile [47m(equal x 0)[0m as [47m(eql x 0)[0m and, in situations where [47mx[0m is known at compile-time to be numeric, [47m(eql x 0)[0m as [47m(= x 0)[0m. So efficiency considerations must, of course, be made in the context of the host compiler. Note also that [47m(zerop x)[0m and [47m(= x 0)[0m are indistinguishable. They have the same meaning and the same [guard], and can reasonably be expected to generate equally efficient code. Note that [47m(zip x)[0m and [47m(zp x)[0m do not have the same logical meanings as the others or each other. They are not simple tests for equality to [47m0[0m. They each coerce [47mx[0m into a restricted domain, [47m[zip][0m to the integers and [47m[zp][0m to the natural numbers, choosing [47m0[0m for [47mx[0m when [47mx[0m is outside the domain. Thus, [47m1/2[0m, [47m#c(1 3)[0m, and [47m'abc[0m, for example, are all ``recognized'' as zero by both [47m[zip][0m and [47m[zp][0m. But [47m[zip][0m reports that [47m-1[0m is different from [47m0[0m while [47m[zp][0m reports that [47m-1[0m ``is'' [47m0[0m. More precisely, [47m(zip -1)[0m is [47mnil[0m while [47m(zp -1)[0m is [47mt[0m. Note that the last five idioms all have [guard]s that restrict their Common Lisp executability. If these last five are used in situations in which [guard]s are to be verified, then proof obligations are incurred as the price of using them. If guard verification is not involved in your project, then the first five can be thought of as synonymous. [47m[Zip][0m and [47m[zp][0m are not provided by Common Lisp but are ACL2-specific functions. Why does ACL2 provide these functions? The answer has to do with the admission of recursively defined functions and efficiency. [47m[Zp][0m is provided as the zero-test in situations where the controlling formal parameter is understood to be a natural number. [47m[Zip][0m is analogously provided for the integer case. We illustrate below. Here is an admissible definition of factorial (defun fact (n) (if (zp n) 1 (* n (fact (1- n))))) Observe the classic recursion scheme: a test against [47m0[0m and recursion by [47m[1-][0m. Note however that the test against [47m0[0m is expressed with the [47m[zp][0m idiom. Note also the absence of a [guard] making explicit our intention that [47mn[0m is a natural number. This definition of factorial is readily admitted because when [47m(zp n)[0m is false (i.e., [47mnil[0m) then [47mn[0m is a natural number other than [47m0[0m and so [47m(1- n)[0m is less than [47mn[0m. The base case, where [47m(zp n)[0m is true, handles all the ``unexpected'' inputs, such as arise with [47m(fact -1)[0m and [47m(fact 'abc)[0m. When calls of [47mfact[0m are evaluated, [47m(zp n)[0m checks [47m(integerp n)[0m and [47m(> n 0)[0m. [Guard] verification is unsuccessful for this definition of [47mfact[0m because [47m[zp][0m requires its argument to be a natural number and there is no [guard] on [47mfact[0m, above. Thus the primary raw lisp for [47mfact[0m is inaccessible and only the [47m:[0m[47m[logic][0m definition (which does runtime ``type'' checking) is used in computation. In summary, this definition of factorial is easily admitted and easily manipulated by the prover but is not executed as efficiently as it could be. Runtime efficiency can be improved by adding a [guard] to the definition. (defun fact (n) (declare (xargs :guard (and (integerp n) (>= n 0)))) (if (zp n) 1 (* n (fact (1- n))))) This [guard]ed definition has the same termination conditions as before --- termination is not sensitive to the [guard]. But the [guard]s can be verified. This makes the primary raw lisp definition accessible during execution. In that definition, the [47m(zp n)[0m above is compiled as [47m(= n 0)[0m, because [47mn[0m will always be a natural number when the primary code is executed. Thus, by adding a [guard] and verifying it, the elegant and easily used definition of factorial is also efficiently executed on natural numbers. Now let us consider an alternative definition of factorial in which [47m(= n 0)[0m is used in place of [47m(zp n)[0m. (defun fact (n) (if (= n 0) 1 (* n (fact (1- n))))) This definition does not terminate. For example [47m(fact -1)[0m gives rise to a call of [47m(fact -2)[0m, etc. Hence, this alternative is inadmissible. A plausible response is the addition of a [guard] restricting [47mn[0m to the naturals: (defun fact (n) (declare (xargs :guard (and (integerp n) (>= n 0)))) (if (= n 0) 1 (* n (fact (1- n))))) But because the termination argument is not sensitive to the [guard], it is still impossible to admit this definition. To influence the termination argument one must change the conditions tested. Adding a runtime test that [47mn[0m is a natural number would suffice and allow both admission and [guard] verification. But such a test would slow down the execution of the compiled function. The use of [47m(zp n)[0m as the test avoids this dilemma. [47m[Zp][0m provides the logical equivalent of a runtime test that [47mn[0m is a natural number but the execution efficiency of a direct [47m[=][0m comparison with [47m0[0m, at the expense of a [guard] conjecture to prove. In addition, if [guard] verification and most-efficient execution are not needed, then the use of [47m(zp n)[0m allows the admission of the function without a [guard] or other extraneous verbiage. While general rules are made to be broken, it is probably a good idea to get into the habit of using [47m(zp n)[0m as your terminating ``[47m0[0m test'' idiom when recursing down the natural numbers. It provides the logical power of testing that [47mn[0m is a non-[47m0[0m natural number and allows efficient execution. We now turn to the analogous function, [47m[zip][0m. [47m[Zip][0m is the preferred [47m0[0m-test idiom when recursing through the integers toward [47m0[0m. [47m[Zip][0m considers any non-integer to be [47m0[0m and otherwise just recognizes [47m0[0m. A typical use of [47m[zip][0m is in the definition of [47m[integer-length][0m, shown below. (ACL2 can actually accept this definition, but only after appropriate lemmas have been proved.) (defun integer-length (i) (declare (xargs :guard (integerp i))) (if (zip i) 0 (if (= i -1) 0 (+ 1 (integer-length (floor i 2)))))) Observe that the function recurs by [47m(floor i 2)[0m. Hence, calling the function on [47m25[0m causes calls on [47m12[0m, [47m6[0m, [47m3[0m, [47m1[0m, and [47m0[0m, while calling it on [47m-25[0m generates calls on [47m-13[0m, [47m-7[0m, [47m-4[0m, [47m-2[0m, and [47m-1[0m. By making [47m(zip i)[0m the first test, we terminate the recursion immediately on non-integers. The [guard], if present, can be verified and allows the primary raw lisp definition to check [47m(= i 0)[0m as the first terminating condition (because the primary code is executed only on integers).") (zerop (numbers acl2-built-ins) "Test an acl2-number against 0 [47m(zerop x)[0m is [47mt[0m if [47mx[0m is [47m0[0m and is [47mnil[0m otherwise. Thus, it is logically equivalent to [47m(equal x 0)[0m. [47m(Zerop x)[0m has a [guard] requiring [47mx[0m to be numeric and can be expected to execute more efficiently than [47m(equal x 0)[0m in properly [guard]ed compiled code. In recursions down the natural numbers, [47m(zp x)[0m is preferred over [47m(zerop x)[0m because the former coerces [47mx[0m to a natural and allows the termination proof. In recursions through the integers, [47m(zip x)[0m is preferred. See [zero-test-idioms]. [47mZerop[0m is a Common Lisp function. See any Common Lisp documentation for more information. [31;1mFunction: [0m<zerop> (defun zerop (x) (declare (xargs :guard (acl2-numberp x))) (eql x 0))") (zip (numbers acl2-built-ins) "Testing an ``integer'' against 0 [47m(Zip i)[0m is logically equivalent to [47m(equal (ifix i) 0)[0m and is the preferred termination test for recursion through the integers. [47m(Zip i)[0m returns [47mt[0m if [47mi[0m is [47m0[0m or not an integer; it returns [47mnil[0m otherwise. Thus, i (zip i) 3 nil 0 t -2 nil 5/2 t #c(1 3) t 'abc t [47m(Zip i)[0m has a [guard] requiring [47mi[0m to be an integer. For a discussion of the various idioms for testing against [47m0[0m, see [zero-test-idioms]. [47mZip[0m is typically used as the termination test in recursions through the integers. It has the advantage of ``coercing'' its argument to an integer and hence allows the definition to be admitted without an explicit type check in the body. [Guard] verification allows [47mzip[0m to be compiled as a direct [47m[=][0m-comparison with [47m0[0m. [31;1mFunction: [0m<zip> (defun zip (x) (declare (xargs :guard (integerp x))) (if (integerp x) (= x 0) t))") (zp (numbers acl2-built-ins) "Testing a ``natural'' against 0 [47m(Zp n)[0m is logically equivalent to [47m(equal (nfix n) 0)[0m and is the preferred termination test for recursion down the natural numbers. [47m(Zp n)[0m returns [47mt[0m if [47mn[0m is [47m0[0m or not a natural number; it returns [47mnil[0m otherwise. Thus, in the ACL2 logic (ignoring the issue of [guard]s): n (zp n) 3 nil 0 t -1 t 5/2 t #c(1 3) t 'abc t [47m(Zp n)[0m has a [guard] requiring [47mn[0m to be a natural number. For a discussion of the various idioms for testing against [47m0[0m, see [zero-test-idioms]. [47mZp[0m is typically used as the termination test in recursions down the natural numbers. It has the advantage of ``coercing'' its argument to a natural and hence allows the definition to be admitted without an explicit type check in the body. [Guard] verification allows [47mzp[0m to be compiled as a direct [47m[=][0m-comparison with [47m0[0m. [31;1mFunction: [0m<zp> (defun zp (x) (declare (xargs :guard (and (integerp x) (<= 0 x)))) (if (integerp x) (<= x 0) t))") (zpf (numbers acl2-built-ins) "Testing a nonnegative fixnum against 0 [47mZpf[0m is exactly the same as [47m[zp][0m, except that [47mzpf[0m is intended for, and faster for, fixnum arguments. Its guard is specified with a type declaration, [47m(type (unsigned-byte 29) x)[0m. (See [declare] and see [type-spec].) Also see [zp]. [31;1mFunction: [0m<zpf> (defun zpf (x) (declare (type (unsigned-byte 60) x)) (if (integerp x) (<= x 0) t))") (= (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) attempt an equality (or equivalence) substitution Examples: = -- replace the current subterm by a term equated to it in one of the hypotheses (if such a term exists) (= x) -- replace the current subterm by x, assuming that the prover can show that they are equal (= (+ x y) z) -- replace all occurrences of the term (+ x y) by the term z inside the current subterm, assuming that the prover can prove (equal (+ x y) z) from the current top-level hypotheses or that this term or (equal z (+ x y)) is among the current top-level hypotheses or the current governors (= & z) -- exactly the same as above, if (+ x y) is the current subterm (= (+ x y) z :hints :none) -- same as (= (+ x y) z), except that a new subgoal is created with the current goal's hypotheses and governors as its top-level hypotheses and (equal (+ x y) z) as its conclusion (= (+ x y) z 0) -- exactly the same as immediately above (= (p x) (p y) :equiv iff :otf-flg t :hints (("Subgoal 2" :BY FOO) ("Subgoal 1" :use bar))) -- same as (= (+ x y) z), except that the prover uses the indicated values for otf-flg and hints, and only propositional (iff) equivalence is used (however, it must be that only propositional equivalence matters at the current subterm) General Forms: (= x) (= x y) (= x y :kwd1 val1 ... :kwdn valn) (= x y atom :kwd1 val1 ... :kwdn valn) where each [47m:kwdi[0m is one of [47m:hints[0m, [47m:otf-flg[0m, or [47m:equiv[0m, without repetition. In the last form, [47matom[0m is a non-keyword atom and no [47mkwdi[0m may be [47m:hints[0m; that atom, if supplied, is equivalent to [47m:hints atom[0m, which indicates that instead of performing a proof that the two indicated terms (as described below) are suitably equivalent, a new such goal is created. If terms [47mx[0m and [47my[0m are supplied, then replace [47mx[0m by [47my[0m everywhere inside the current subterm if they are ``known'' to be equal, or more generally, equivalent in the sense described below. Here ``known'' means the following: except in the cases that no arguments are provided or else [47m:hints atom[0m is provided as described above, the prover is called as in the [47mprove[0m command (using keyword arguments [47m:otf[0m and [47m:hints[0m, if supplied, where the value of [47m:hints[0m is not an atom) to prove equivalence of [47mx[0m and [47my[0m under the current governors and top-level hypotheses. By default, this equivalence is equality; however the keyword argument [47m:equiv[0m can specify a known equivalence relation. In cases other than equality, substitution only takes place where justified by the equivalence maintained at the current subterm. For the keyword arguments, [47m:equiv[0m defaults to [47mequal[0m if not supplied or [47mnil[0m; if it is not [47mequal[0m (either explicitly or by default), then it should be the name of a known ACL2 [equivalence] relation, and substitution will only take place at subterm occurrences for which the [47m:equiv[0m is among the [equivalence] relations being maintained without the use of [patterned-congruence]s. Remarks on defaults * If there are at least two arguments, then [47mx[0m may be the symbol [47m&[0m, in any package except the keyword package, which represents the current subterm. * The one-argument command [47m(= a)[0m is equivalent to [47m(= & a)[0m. * If there are no arguments, then we look for a top-level hypothesis or a governor of the form [47m(equal c u)[0m or [47m(equal u c)[0m, where [47mc[0m is the current subterm. In that case we replace the current subterm by [47mu[0m. * As with the [47mprove[0m command, we allow goals to be given ``bye''s in the proof, which may be generated by a [47m:hints[0m keyword argument in [47mkeyword-args[0m. These result in the creation of new subgoals. * It is allowed to use abbreviations (see [ACL2-pc::add-abbreviation]) in the hints.") (acl2-wrap (proof-builder-commands) "(macro) same as [47m(lisp x)[0m Example: (acl2-wrap (pe :here)) General Form: (acl2-wrap form) Same as [47m(lisp form)[0m. This is provided for interface tools that want to be able to execute the same form in raw Lisp, in the proof-builder, or in the ACL2 top-level loop [47m(lp)[0m.") (add-abbreviation (proof-builder-commands) "(primitive) add an abbreviation Example: [47m(add-abbreviation v (* x y))[0m causes future occurrences of [47m(* x y)[0m to be printed as [47m(? v)[0m, until (unless) a corresponding invocation of [47mremove-abbreviations[0m occurs. In this case we say that [47mv[0m ``abbreviates'' [47m(* x y)[0m. General Form: (add-abbreviation var &optional raw-term) Let [47mvar[0m be an abbreviation for [47mraw-term[0m, if [47mraw-term[0m is supplied, else for the current subterm. Note that [47mvar[0m must be a variable that does not already abbreviate some term. A way to think of abbreviations is as follows. Imagine that whenever an abbreviation is added, say [47mv[0m abbreviates [47mexpr[0m, an entry associating [47mv[0m to [47mexpr[0m is made in an association list, which we will call ``[47m*abbreviations-alist*[0m''. Then simply imagine that [47m?[0m is a function defined by something like: (defun ? (v) (let ((pair (assoc v *abbreviations-alist*))) (if pair (cdr pair) (error ...)))) Of course the implementation isn't exactly like that, since the ``constant'' [47m*abbreviations-alist*[0m actually changes each time an [47madd-abbreviation[0m instruction is successfully invoked. Nevertheless, if one imagines an appropriate redefinition of the ``constant'' [47m*abbreviations-alist*[0m each time an [47madd-abbreviation[0m is invoked, then one will have a clear model of the meaning of such an instruction. The effect of abbreviations on output is that before printing a term, each subterm that is abbreviated by a variable [47mv[0m is first replaced by [47m(? v)[0m. The effect of abbreviations on input is that every built-in proof-builder command accepts abbreviations wherever a term is expected as an argument, i.e., accepts the syntax [47m(? v)[0m whenever [47mv[0m abbreviates a term. For example, the second argument of [47madd-abbreviation[0m may itself use abbreviations that have been defined by previous [47madd-abbreviation[0m instructions. See also [ACL2-pc::remove-abbreviations] and see [ACL2-pc::show-abbreviations].") (al (proof-builder-commands) "(macro) same as apply-linear Example: (al 3) See [ACL2-pc::apply-linear], as [47mal[0m and [47mapply-linear[0m are identical.") (apply-linear (proof-builder-commands) "(primitive) apply a linear rule Examples: (apply-linear foo) -- apply the linear rule `foo' (apply-linear (:linear foo)) -- same as above (apply-linear 2) -- apply the second linear rule, as displayed by show-linears rewrite -- apply the first rewrite rule, as displayed by show-rewrites (apply-linear foo ((y 7))) -- apply the linear rule foo with the substitution that associates 7 to the ``free variable'' y (apply-linear foo ((x 2) (y 3)) t) -- apply the linear rule foo by substituting 2 and 3 for free variables x and y, respectively, and also binding all other free variables possible by using the current context (hypotheses and governors) General Form: (apply-linear &optional rule-id substitution instantiate-free) Add a new top-level hypothesis by applying a [linear] rule to the current subterm. The new hypothesis will be created according to the information provided by the [47mshow-linears[0m ([47msls[0m) command. A short name for this command is [47mal[0m. We assume familiarity with the interactive [proof-builder]'s [47mrewrite[0m ([47mr[0m) command (see [ACL2-pc::rewrite]). In brief, the [47mapply-linear[0m command is an analogue of the [47mrewrite[0m command, but for [linear] rules in place of [rewrite] rules. There is a significant difference: for the [47mapply-linear[0m command, instead of rewriting the current subterm as is done by the [47mrewrite[0m command, the conclusion of the applicable linear rule, suitably instantiated, is added as a new (and last) top-level hypothesis of the goal. There is another significant difference: the automatic application of [linear] rules in the theorem prover is somewhat more complex than the automatic application of [rewrite] rules, so the [47mapply-linear[0m command may not correspond as closely to the prover's automatic use of a linear rule as the [47mrewrite[0m command corresponds to the prover's automatic use of a rewrite rule. Below, we refer freely to the [documentation] for the interactive proof-builder's [47mrewrite[0m command (see [ACL2-pc::rewrite]). The [47mrule-id[0m is treated just as it is by the [47mrewrite[0m command. If [47mrule-id[0m is a positive integer [47mn[0m, then the [47mn[0mth rule as displayed by [47mshow-linears[0m is the one that is applied. If [47mrule-id[0m is [47mnil[0m or is not supplied, then it is treated as the number 1. Otherwise, [47mrule-id[0m should be either a symbol or else a [47m:linear[0m [rune]. If a symbol is supplied, then any [linear] rule of that name may be used. Consider the following example. Suppose that the current subterm is [47m(< (g (h y)) y)[0m and that [47mfoo[0m is the name of the following linear rule. (implies (true-listp x) (< (g x) 15)) Then the instruction [47m(apply-linear foo)[0m applies [47mfoo[0m by adding a new hypothesis [47m(< (g (h y)) 15)[0m. In addition, a new goal with conclusion [47m(true-listp y)[0m is created unless the current context (top-level hypotheses and governors) implies [47m(true-listp y)[0m using only ``trivial reasoning'', just as for the [47mrewrite[0m command. If the [47mrule-id[0m argument is a number or is not supplied, then the system will store an instruction of the form [47m(apply-linear name ...)[0m, where [47mname[0m is the name of a [linear] rule; this is in order to make it easier to replay instructions when there have been changes to the history. Except: instead of the name (whether the name is supplied or calculated), the system stores the [rune] if there is any chance of ambiguity. (Formally, ``ambiguity'' here means that the rune being applied is of the form [47m(:rewrite name . index)[0m, where index is not [47mnil[0m.) Speaking in general, then, an [47mapply-linear[0m instruction works as follows. First, a [linear] rule is selected according to the arguments of the instruction. The selection is made as explained under ``General Form'' above. Next, a trigger term of the rule (see [linear]) is matched with the current subterm, i.e., a substitution [47munify-subst[0m is found such that if one instantiates that trigger term of the rule with [47munify-subst[0m, then one obtains the current subterm. If this match fails, then the instruction fails. Next, an attempt is made to relieve (discharge) the hypotheses, possibly handling free variables (see [free-variables]), exactly as is done with hypotheses when applying the interactive [proof-builder] command, [47mrewrite[0m ([47mr[0m). Finally, the instruction is applied exactly as the [47mrewrite[0m instruction is applied, except instead of replacing the current subterm, the rule's instantiated conclusion is added to the end of the list of top-level hypotheses of the goal. Note that as for the [47mrewrite[0m command, the substitution argument should be a list whose elements have the form [47m(variable term)[0m, where [47mterm[0m may contain abbreviations.") (bash (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) call the ACL2 theorem prover's simplifier Examples: bash -- attempt to prove the current goal by simplification alone (bash ("Subgoal 2" :by foo) ("Subgoal 1" :use bar)) -- attempt to prove the current goal by simplification alone, with the indicated hints General Form: (bash &rest hints) Call the theorem prover's simplifier, creating a subgoal for each resulting goal. Notice that unlike [47mprove[0m, the arguments to [47mbash[0m are spread out, and are all hints. [47mBash[0m is similar to [47mreduce[0m in that neither of these allows induction. But [47mbash[0m only allows simplification, while [47mreduce[0m allows processes [47meliminate-destructors[0m, [47mfertilize[0m, [47mgeneralize[0m, and [47meliminate-irrelevance[0m. [31;1mRemark:[0m All forcing rounds will be skipped (unless there are more than 15 subgoals generated in the first forcing round, an injustice that should be rectified, but might remain unless there is pressure to fix it).") (bdd (proof-builder-commands) "(atomic macro) prove the current goal using bdds Examples: bdd (bdd :vars nil :bdd-constructors (cons) :prove t :literal :all) The general form is as shown in the latter example above, but with any keyword-value pairs omitted and with values as described for the [47m:[0m[47m[bdd][0m hint; see [hints]. This command simply calls the theorem prover with the indicated bdd hint for the top-level goal. Note that if [47m:prove[0m is [47mt[0m (the default), then the proof will succeed entirely using bdds or else it will fail immediately. See [bdd].") (bk (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) move backward one argument in the enclosing term Example and General Form: bk For example, if the conclusion is [47m(= x (* (- y) z))[0m and the current subterm is [47m(* (- y) z)[0m, then after executing [47mbk[0m, the current subterm will be [47mx[0m. Move to the previous argument of the enclosing term. This is the same as [47mup[0m followed by [47m(dive n-1)[0m, where [47mn[0m is the position of the current subterm in its parent term in the conclusion. Thus in particular, the [47mnx[0m command fails if one is already at the top of the conclusion. Also see [ACL2-pc::up], [ACL2-pc::dive], [ACL2-pc::top], and [ACL2-pc::nx].") (bookmark (proof-builder-commands) "(macro) insert matching ``bookends'' comments Example: (bookmark final-goal) General Form: (bookmark name &rest instruction-list) Run the instructions in [47minstruction-list[0m (as though this were a call of [47mdo-all[0m; see [ACL2-pc::do-all]), but first insert a begin bookend with the given name and then, when the instructions have been completed, insert an end bookend with that same name. See [ACL2-pc::comm] for an explanation of bookends and how they can affect the display of instructions.") (casesplit (proof-builder-commands) "(primitive) split into two cases Example: (casesplit (< x y)) -- assuming that we are at the top of the conclusion, add (< x y) as a new top-level hypothesis in the current goal, and create a subgoal identical to the current goal except that it has (not (< x y)) as a new top-level hypothesis General Form: (casesplit expr &optional use-hyps-flag do-not-flatten-flag) When the current subterm is the entire conclusion, this instruction adds [47mexpr[0m as a new top-level hypothesis, and create a subgoal identical to the existing current goal except that it has the negation of [47mexpr[0m as a new top-level hypothesis. Also see [ACL2-pc::claim]. The optional arguments control the use of governors and the ``flattening'' of new hypotheses, as we now explain. The argument [47muse-hyps-flag[0m is only of interest when there are governors. (To read about governors, see [ACL2-pc::hyps]). In that case, if [47muse-hyps-flag[0m is not supplied or is [47mnil[0m, then the description above is correct; but otherwise, it is not [47mexpr[0m but rather it is [47m(implies govs expr)[0m that is added as a new top-level hypothesis (and whose negation is added as a top-level hypothesis for the new goal), where [47mgovs[0m is the conjunction of the governors. If [47mdo-not-flatten-flag[0m is supplied and not [47mnil[0m, then that is all there is to this command. Otherwise (thus this is the default), when the claimed term (first argument) is a conjunction ([47mand[0m) of terms and the [47mclaim[0m instruction succeeds, then each (nested) conjunct of the claimed term is added as a separate new top-level hypothesis. Consider the following example, assuming there are no governors. (casesplit (and (and (< x y) (integerp a)) (equal r s)) t) Three new top-level hypotheses are added to the current goal, namely [47m(< x y)[0m, [47m(integerp a)[0m, and [47m(equal r s)[0m. In that case, only one hypothesis is added to create the new goal, namely the negation of [47m(and (< x y) (integerp a) (equal r s))[0m. If the negation of this term had been [47mclaim[0med, then it would be the other way around: the current goal would get a single new hypothesis while the new goal would be created by adding three hypotheses. [31;1mRemark:[0m It is allowed to use abbreviations in the hints.") (cg (proof-builder-commands proof-builder-commands-short-list) "(macro) change to another goal. Examples: (cg (main . 1)) -- change to the goal (main . 1) cg -- change to the next-to-top goal General Form: (CG &OPTIONAL goal-name) Same as [47m(change-goal goal-name t)[0m, i.e. change to the indicated and move the current goal to the end of the goal stack.") (change-goal (proof-builder-commands) "(primitive) change to another goal. Examples: (change-goal (main . 1)) -- change to the goal (main . 1) change-goal -- change to the next-to-top goal General Form: (change-goal &optional goal-name end-flg) Change to the goal with the name [47mgoal-name[0m, i.e. make it the current goal. However, if [47mgoal-name[0m is [47mnil[0m or is not supplied, then it defaults to the next-to-top goal, i.e., the second goal in the stack of goals. If [47mend-flg[0m is supplied and not [47mnil[0m, then move the current goal to the end of the goal stack; else merely swap it with the next-to-top goal. Also see [ACL2-pc::cg].") (cl-proc (proof-builder-commands) "(macro) same as [47mclause-processor[0m This is simply an abbreviation for [ACL2-pc::clause-processor].") (claim (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) add a new hypothesis Examples: (claim (< x y)) -- attempt to prove (< x y) from the current top-level hypotheses and if successful, then add (< x y) as a new top-level hypothesis in the current goal (claim (< x y) :otf-flg t :hints (("Goal" :induct t))) -- as above, but call the prover using the indicated values for the otf-flg and hints (claim (< x y) 0) -- as above, except instead of attempting to prove (< x y), create a new subgoal with the same top-level hypotheses as the current goal that has (< x y) as its conclusion (claim (< x y) :hints :none) -- same as immediately above General Form: (claim expr &rest rest-args) This command creates a new subgoal with the same top-level hypotheses as the current goal but with a conclusion of [47mexpr[0m. If [47mrest-args[0m is a non-empty list headed by a non-keyword, then there will be no proof attempted for the new subgoal. With that possible exception, [47mrest-args[0m should consist of keyword arguments. The keyword argument [47m:do-not-flatten[0m controls the ``flattening'' of new hypotheses, just as with the [47mcasesplit[0m command (see [ACL2-pc::casesplit]). The remaining [47mrest-args[0m are used with a call the [47mprove[0m command on the new subgoal, except that if [47m:hints[0m is a non-[47mnil[0m atom, then the prover is not called --- rather, this is the same as the situation described above, where [47mrest-args[0m is a non-empty list headed by a non-keyword. [31;1mRemarks:[0m (1) Unlike the [47mcasesplit[0m command, the [47mclaim[0m command is completely insensitive to governors. (2) It is allowed to use abbreviations in the hints. (3) The keyword [47m:[0m[47mnone[0m has the special role as a value of [47m:[0m[47mhints[0m that is shown clearly in an example above.") (clause-processor (proof-builder-commands) "(atomic macro) use a clause-processor Example: (cl-proc :function note-fact-clause-processor :hint '(equal a a)) -- Invoke the indicated clause processor function with the indicated hint argument (see the beginning of community book [47mbooks/clause-processors/basic-examples.lisp[0m. General Form: (cl-proc &rest cl-proc-args) Invoke a clause-processor as indicated by cl-proc-args, which is a list of arguments that can serve as the value of a [47m:[0m[47m[clause-processor][0m hint; see [hints]. This command calls the [47mprove[0m command, and hence should only be used at the top of the conclusion.") (comm (proof-builder-commands proof-builder-commands-short-list) "(macro) display instructions from the current interactive session Examples: comm (comm 10) General Form: (comm &optional n) Prints out instructions in reverse order. This is actually the same as [47m(commands n t)[0m --- or, [47m(commands nil t)[0m if [47mn[0m is not supplied. As for [47mcommands[0m (see [ACL2-pc::commands]), the final argument of [47mt[0m causes suppression of instructions occurring between so-called ``matching bookends,'' which we now explain. A ``begin bookend'' is an instruction of the form (COMMENT :BEGIN x . y). Similarly, an ``end bookend'' is an instruction of the form (COMMENT :END x' . y'). The ``name'' of the first bookend is [47mx[0m and the ``name'' of the second bookend is [47mx'[0m. When such a pair of instructions occurs in the current state-stack, we call them ``matching bookends'' provided that they have the same name (i.e. [47mx[0m equals [47mx'[0m) and if no other begin or end bookend with name [47mx[0m occurs between them. The idea now is that [47mcomm[0m hides matching bookends together with the instructions they enclose. Here is a more precise explanation of this ``hiding''; probably there is no value in reading on! A [47mcomm[0m instruction hides bookends in the following manner. (So does a [47mcomment[0m instruction when its second optional argument is supplied and non-[47mnil[0m.) First, if the first argument [47mn[0m is supplied and not [47mnil[0m, then we consider only the last [47mn[0m instructions from the state-stack; otherwise, we consider them all. Now the resulting list of instructions is replaced by the result of applying the following process to each pair of matching bookends: the pair is removed, together with everything in between the begin and end bookend of the pair, and all this is replaced by the ``instruction'' ("***HIDING***" :COMMENT :BEGIN name ...) where [47m(comment begin name ...)[0m is the begin bookend of the pair. Finally, after applying this process to each pair of matching bookends, each begin bookend of the form [47m(comment begin name ...)[0m that remains is replaced by ("***UNFINISHED***" :COMMENT :BEGIN name ...) .") (commands (proof-builder-commands) "(macro) display instructions from the current interactive session Examples: commands (commands 10 t) General Forms: commands or (commands nil) Print out all the instructions (in the current state-stack) in reverse order, i.e. from the most recent instruction to the starting instruction. (commands n) [n a positive integer] Print out the most recent n instructions (in the current state-stack), in reverse order. (commands x abbreviate-flag) Same as above, but if abbreviate-flag is non-NIL, then do not display commands between ``matching bookends''. See documentation for comm for an explanation of matching bookends. [31;1mRemark[0m: If there are more than [47mn[0m instructions in the state-stack, then [47m(commands n)[0m is the same as [47mcommands[0m (and also, [47m(commands n abb)[0m is the same as [47m(commands nil abb)[0m).") (comment (proof-builder-commands) "(primitive) insert a comment Example: (comment now begin difficult final goal) General Form: (comment &rest x) This instruction makes no change in the state except to insert the [47mcomment[0m instruction. Some comments can be used to improve the display of commands; see [ACL2-pc::comm].") (contradict (proof-builder-commands) "(macro) same as [47mcontrapose[0m See [ACL2-pc::contrapose].") (contrapose (proof-builder-commands proof-builder-commands-short-list) "(primitive) switch a hypothesis with the conclusion, negating both Example: (contrapose 3) General Form: (contrapose &optional n) The (optional) argument [47mn[0m should be a positive integer that does not exceed the number of hypotheses. Negate the current conclusion and make it the [47mn[0mth hypothesis, while negating the current [47mn[0mth hypothesis and making it the current conclusion. If no argument is supplied then the effect is the same as for [47m(contrapose 1)[0m. [31;1mRemark:[0m By ``negate'' we mean an operation that replaces [47mnil[0m by [47mt[0m, [47mx[0m by [47mnil[0m for any other explicit value [47mx[0m, [47m(not x)[0m by [47mx[0m, and any other [47mx[0m by [47m(not x)[0m.") (demote (proof-builder-commands proof-builder-commands-short-list) "(primitive) move top-level hypotheses to the conclusion Examples: demote -- demote all top-level hypotheses (demote 3 5) -- demote hypotheses 3 and 5 For example, if the top-level hypotheses are [47mx[0m and [47my[0m and the conclusion is [47mz[0m, then after execution of [47mdemote[0m, the conclusion will be [47m(implies (and x y) z)[0m and there will be no (top-level) hypotheses. General Form: (demote &rest hyps-indices) Eliminate the indicated (top-level) hypotheses, but replace the conclusion [47mconc[0m with [47m(implies hyps conc)[0m where [47mhyps[0m is the conjunction of the hypotheses that were eliminated. If no arguments are supplied, then all hypotheses are demoted, i.e. [47mdemote[0m is the same as [47m(demote 1 2 ... n)[0m where [47mn[0m is the number of top-level hypotheses. [31;1mRemark[0m: You must be at the top of the conclusion in order to use this command. Otherwise, first invoke [47mtop[0m. Also, [47mdemote[0m fails if there are no top-level hypotheses or if indices are supplied that are out of range.") (dive (proof-builder-commands) "(primitive) move to the indicated subterm Examples: (DIVE 1) -- assign the new current subterm to be the first argument of the existing current subterm (DIVE 1 2) -- assign the new current subterm to be the result of first taking the 1st argument of the existing current subterm, and then the 2nd argument of that For example, if the current subterm is (* (+ a b) c), then after [47m(dive 1)[0m it is (+ a b). If after that, then [47m(dive 2)[0m is invoked, the new current subterm will be b. Instead of [47m(dive 1)[0m followed by [47m(dive 2)[0m, the same current subterm could be obtained by instead submitting the single instruction [47m(dive 1 2)[0m. General Form: (dive &rest naturals-list) If [47mnaturals-list[0m is a non-empty list [47m(n_1 ... n_k)[0m of natural numbers, let the new current subterm be the result of selecting the [47mn_1[0m-st argument of the current subterm, and then the [47mn_2[0m-th subterm of that, ..., finally the [47mn_k[0m-th subterm. [31;1mRemark:[0m [47mDive[0m is related to the command [47mpp[0m, in that the diving is done according to raw (translated, internal form) syntax. Use the command [47mdv[0m if you want to dive according to the syntax displayed by the command [47mp[0m. Note that [47m(dv n)[0m can be abbreviated by simply [47mn[0m. [31;1mRemark:[0m Emacs users who load (into Emacs) the file [47memacs-acl2.el[0m (from a suitable directory; see [emacs]) will have defined a command, [47mControl-t Control-d[0m, that avoids the need to type [47mdive[0m commands. After you print the current term using the [47mpp[0m command, you may position the cursor on a subterm and type [47mControl-t Control-d[0m. Emacs will respond by pasting the appropriate [47mdive[0m command immediately after the interactive proof-builder's prompt. You can then simply type [47m<RETURN>[0m in order to dive to the desired subterm.") (do-all (proof-builder-commands) "(macro) run the given instructions Example: (do-all induct p prove) General Form: (do-all &rest instruction-list) Run the indicated instructions until there is a hard ``failure''. The instruction ``succeeds'' if and only if each instruction in [47minstruction-list[0m does. (See [ACL2-pc::sequence] for an explanation of ``success'' and ``failure.'') As each instruction is executed, the system will print the usual prompt followed by that instruction, unless the value of [47m(access pc-info (@ pc-info) :print-prompt-and-instr-flg)[0m is [47mnil[0m. [31;1mRemark:[0m If [47mdo-all[0m ``fails'', then the failure is hard if and only if the last instruction it runs has a hard ``failure''. Obscure point: For the record, [47m(do-all ins_1 ins_2 ... ins_k)[0m is the same as [47m(sequence (ins_1 ins_2 ... ins_k))[0m.") (do-all-no-prompt (proof-builder-commands) "(macro) run the given instructions, halting once there is a ``failure'' Example: (do-all-no-prompt induct p prove) General Form: (do-all-no-prompt &rest instruction-list) [47mDo-all-no-prompt[0m is the same as [47mdo-all[0m, except that the prompt and instruction are not printed each time, regardless of the value of [47mpc-print-prompt-and-instr-flg[0m. Also, restoring is disabled. See [ACL2-pc::do-all].") (do-strict (proof-builder-commands) "(macro) run the given instructions, halting once there is a ``failure'' Example: (do-strict induct p prove) General Form: (do-strict &rest instruction-list) Run the indicated instructions until there is a (hard or soft) ``failure''. In fact [47mdo-strict[0m is identical in effect to [47mdo-all[0m, except that [47mdo-all[0m only halts once there is a hard ``failure''. See [ACL2-pc::do-all].") (doc (proof-builder-commands) "(macro) access documentation inside the interactive proof-builder Examples: (doc rewrite) -- documentation on rewriting in ACL2 (doc acl2-pc::rewrite) -- documentation on the proof-builder rewrite command (doc) -- same as (help doc) or (doc acl2-pc::doc) doc -- same as above General Forms: (doc) ; or, just: help (doc topic-name) For any [documentation] topic, [47mA[0m, [47m(doc A)[0m prints documentation on [47mA[0m to the terminal. You can read that documentation online or in the Emacs [ACL2-Doc] browser; see [documentation]. This [proof-builder] command provides a direct interface to the ACL2 [47m:[0m[47m[doc][0m command at the terminal. Also see [ACL2-pc::help], which provides help for proof-builder commands. For example, submitting [47m(help rewrite)[0m to the proof-builder is equivalent to submitting [47m(doc acl2-pc::rewrite)[0m to the proof-builder, which corresponds to submitting [47m:doc acl2-pc::rewrite[0m directly to the ACL2 loop.") (drop (proof-builder-commands proof-builder-commands-short-list) "(primitive) drop top-level hypotheses Examples: (drop 2 3) -- drop the second and third hypotheses drop -- drop all top-level hypotheses General Forms: (drop n1 n2 ...) -- Drop the hypotheses with the indicated indices. drop -- Drop all the top-level hypotheses. [31;1mRemark:[0m If there are no top-level hypotheses, then the instruction [47mdrop[0m will fail. If any of the indices is out of range, i.e. is not an integer between one and the number of top-level hypotheses [47m(inclusive)[0m, then [47m(drop n1 n2 ...)[0m will fail.") (dv (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) move to the indicated subterm Examples: (dv 1) -- assign the new current subterm to be the first argument of the existing current subterm (dv 1 2) -- assign the new current subterm to be the result of first taking the 1st argument of the existing current subterm, and then the 2nd argument of that For example, if the current subterm is (* (+ a b) c), then after [47m(dv 1)[0m it is (+ a b). If after that, then [47m(dv 2)[0m is invoked, the new current subterm will be b. Instead of [47m(dv 1)[0m followed by [47m(dv 2)[0m, the same current subterm could be obtained by instead submitting the single instruction [47m(dv 1 2)[0m. General Form: (dv &rest naturals-list) If [47mnaturals-list[0m is a non-empty list [47m(n_1 ... n_k)[0m of natural numbers, let the new current subterm be the result of selecting the [47mn_1[0m-st argument of the current subterm, and then the [47mn_2[0m-th subterm of that, ..., finally the [47mn_k[0m-th subterm. [31;1mRemark:[0m [47m(dv n)[0m may be abbreviated by simply [47mn[0m, so we could have typed [47m1[0m instead of [47m(dv 1)[0m in the first example above. [31;1mRemark:[0m Emacs users who load (into Emacs) the file [47memacs-acl2.el[0m (from a suitable directory; see [emacs]) will have defined a command, [47mControl-t d[0m, that avoids the need to type [47mdv[0m commands. After you print the current term using the [47mp[0m or [47mth[0m command, you may position the cursor on a subterm and type [47mControl-t d[0m. Emacs will respond by pasting the appropriate [47mdv[0m command immediately after the interactive proof-builder's prompt. You can then simply type [47m<RETURN>[0m in order to dive to the desired subterm. [31;1mRemark:[0m A similar command is [47mdive[0m, which is related to the command [47mpp[0m, in that the diving is done according to raw (translated, internal form) syntax. (See [ACL2-pc::dive].) Use the command [47mdv[0m if you want to dive according to the syntax displayed by the command [47mp[0m. Thus, the command ``[47mup[0m'' is the inverse of [47mdive[0m, not of [47mdv[0m. The following example illustrates this point. ACL2 !>(verify (equal (* a b c) x)) ->: p ; print user-level term (EQUAL (* A B C) X) ->: pp ; print internal-form (translated) term (EQUAL (BINARY-* A (BINARY-* B C)) X) ->: exit Exiting.... NIL ACL2 !>(verify (equal (* a b c) x)) ->: p (EQUAL (* A B C) X) ->: 1 ; same as (dv 1) ->: p ; print user-level term (* A B C) ->: pp ; print internal-form (translated) term (BINARY-* A (BINARY-* B C)) ->: 3 ; dive to third argument of (* A B C) ->: p C ->: up ; go up one level in (BINARY-* A (BINARY-* B C)) ->: p (* B C) ->: pp (BINARY-* B C) ->: Subtopics [Dive-into-macros-table] Right-associated function information for the [proof-builder]") (elim (proof-builder-commands) "(atomic macro) call the ACL2 theorem prover's elimination process Example and General Form: elim Upon running the [47melim[0m command, the system will create a subgoal will be created for each goal that would have been pushed for proof by induction in an ordinary proof, where [31;1monly[0m elimination is used; not even simplification is used!") (equiv (proof-builder-commands) "(primitive) attempt an equality (or congruence-based) substitution Examples: (equiv (* x y) 3) -- replace (* x y) by 3 everywhere inside the current subterm, if their equality is among the top-level hypotheses or the governors (equiv x t iff) -- replace x by t everywhere inside the current subterm, where only propositional equivalence needs to be maintained at each occurrence of x General form: (equiv old new &optional relation) Substitute [47mnew[0m for [47mold[0m everywhere inside the current subterm, provided that either [47m(relation old new)[0m or [47m(relation new old)[0m is among the top-level hypotheses or the governors (possibly by way of backchaining and/or refinement; see below). If [47mrelation[0m is [47mnil[0m or is not supplied, then it defaults to [47mequal[0m. If [47mrelation[0m is not [47mequal[0m (either explicitly or by default), then substitution of [47mnew[0m for [47mold[0m will only take place at occurrences for which [47mrelation[0m is among the [equivalence] relations being maintained without the use of [patterned-congruence]s. Also see [47macl2-pc::=[0m for a much more flexible command. Note that the [47mequiv[0m command fails if no substitution is actually made. [31;1mRemark:[0m No substitution takes place inside explicit values. So for example, the instruction [47m(equiv 3 x)[0m will cause [47m3[0m to be replaced by [47mx[0m if the current subterm is, say, [47m(* 3 y)[0m, but not if the current subterm is [47m(* 4 y)[0m even though [47m4 = (1+ 3)[0m. The following remarks are quite technical and mostly describe a certain weak form of ``backchaining'' that has been implemented for [47mequiv[0m in order to support the [47m=[0m command. In fact neither the term [47m(relation old new)[0m nor the term [47m(relation new old)[0m needs to be [31;1mexplicitly[0m among the current ``assumptions'', i.e., the top-level hypothesis or the governors. Rather, there need only be such an assumption that ``tells us'' [47m(r old new)[0m or [47m(r new old)[0m, for [31;1msome[0m equivalence relation [47mr[0m that [31;1mrefines[0m [47mrelation[0m. Here, ``tells us'' means that either one of the indicated terms is among those assumptions, or else there is an assumption that is an implication whose conclusion is one of the indicated terms and whose hypotheses (gathered up by appropriately flattening the first argument of the [47mimplies[0m term) are all among the current assumptions.") (ex (proof-builder-commands) "(macro) exit after possibly saving the state Example and General Form: ex Same as [47mexit[0m, except that first the instruction [47msave[0m is executed. If [47msave[0m queries the user and is answered negatively, then the exit is aborted.") (exit (proof-builder-commands proof-builder-commands-short-list) "(meta) exit the interactive proof-builder Examples: exit -- exit the interactive proof-builder (exit t) -- exit after printing a bogus defthm event (exit append-associativity) -- exit and create a defthm event named append-associativity General Forms: exit -- Exit without storing an event. (exit t) -- Exit after printing a bogus defthm event, showing :INSTRUCTIONS. (exit event-name &optional rule-classes do-it-flg) -- Exit, and perhaps store an event The command [47mexit[0m returns you to the ACL2 loop. At a later time, [47m(acl2::verify)[0m may be executed to get back into the same interactive proof-builder state, as long as there hasn't been an intervening use of the proof-builder (otherwise see [ACL2-pc::save]). When given one or more arguments as shown above, [47mexit[0m still returns you to the ACL2 loop, but first, if the interactive proof is complete, then it attempts create a [47mdefthm[0m event with the specified [47mevent-name[0m and [47mrule-classes[0m (which defaults to [47m(:rewrite)[0m if not supplied). The event will be printed to the terminal, and then normally the user will be queried whether an event should really be created. However, if the final optional argument [47mdo-it-flg[0m is supplied and not [47mnil[0m, then an event will be made without a query. For example, the form (exit top-pop-elim (:elim :rewrite) t) causes a [47mdefthm[0m event named [47mtop-pop-elim[0m to be created with rule-classes [47m(:elim :rewrite)[0m, without a query to the user (because of the argument [47mt[0m). [31;1mRemark:[0m it is permitted for [47mevent-name[0m to be [47mnil[0m. In that case, the name of the event will be the name supplied during the original call of [47mverify[0m. (See [verify] and [ACL2-pc::commands].) Also in that case, if [47mrule-classes[0m is not supplied then it defaults to the rule-classes supplied in the original call of [47mverify[0m. [47mComments[0m on ``success'' and ``failure''. An [47mexit[0m instruction will always ``fail'', so for example, if it appears as an argument of a [47mdo-strict[0m instruction then none of the later (instruction) arguments will be executed. Moreover, the ``failure'' will be ``hard'' if an event is successfully created or if the instruction is simply [47mexit[0m; otherwise it will be ``soft''. See [ACL2-pc::sequence] for an explanation of hard and soft ``failures''. An obscure but potentially important fact is that if the ``failure'' is hard, then the error signal is a special signal that the top-level interactive loop can interpret as a request to exit. Thus for example, a sequencing command that turns an error triple [47m(mv erp val state)[0m into [47m(mv t val state)[0m would never cause an exit from the interactive loop. If the proof is not complete, then neither [47m(exit event-name ...)[0m nor [47m(exit t)[0m will cause an exit from the interactive loop. However, in that case either one will print out the original user-supplied goal (the one that was supplied with the call to [47mverify[0m) and the current list of instructions.") (expand (proof-builder-commands proof-builder-commands-short-list) "(primitive) expand the current function call without simplification Examples: expand -- expand and do not simplify. Also see [ACL2-pc::x], which performs simplification, and see [ACL2-pc::x-dumb], which provides a simple interface to [47macl2-pc::expand[0m. For example, if the current subterm is [47m(append a b)[0m, then after [47mexpand[0m the current subterm will be the term: (if (consp a) (cons (car a) (append (cdr a) b)) b) regardless of the top-level hypotheses and the governors. General Form: (expand &optional do-not-expand-lambda-flg) Expand the function call at the current subterm, and do not simplify. The options have the following meanings: do-not-expand-lambda-flg: default is nil; otherwise, the result should be a lambda expression") (fail (proof-builder-commands) "(macro) cause a failure Examples: fail (fail t) General Form: (fail &optional hard) This is probably only of interest to writers of macro commands. The only function of [47mfail[0m is to fail to ``succeed''. The full story is that [47mfail[0m and [47m(fail nil)[0m simply return [47m(mv nil nil state)[0m, while [47m(fail hard)[0m returns [47m(mv hard nil state)[0m if [47mhard[0m is not [47mnil[0m. Also see [ACL2-pc::do-strict], [ACL2-pc::do-all], and [ACL2-pc::sequence].") (finish (proof-builder-commands) "(macro) require completion of instructions; save error if inside [47m:[0m[47m[hints][0m Example: (finish induct prove bash) General Form: (finish &rest instructions) Run the indicated instructions, stopping at the first failure. If there is any failure, or if any new goals are created and remain at the end of the indicated instructions, then consider the call of [47mfinish[0m to be a failure. See [proof-builder-commands] and see [ACL2-pc::sequence] for a discussion of the notion of ``failure'' for interactive [proof-builder] commands.") (forwardchain (proof-builder-commands) "(atomic macro) forward chain from an implication in the hyps Example: (forwardchain 2) ; Second hypothesis should be of the form ; (IMPLIES hyp concl), and the result is to replace ; that hypothesis with concl. General Forms: (forwardchain hypothesis-number) (forwardchain hypothesis-number hints) (forwardchain hypothesis-number hints quiet-flg) This command replaces the hypothesis corresponding to the given index. That hypothesis --- call it [47mH[0m --- must be of the form [47m(IMPLIES hyp concl)[0m. The effect of this command is to replace [47mH[0m by [47mconcl[0m, which becomes the final hypothesis. The prover must be able to prove [47mconcl[0m from the hypotheses other than [47mH[0m (more precisely, to prove [47mconcl[0m after removing the hypothesis at the given index), or else the command will fail. The [47m:hints[0m argument is used in this prover call, and should have the usual syntax of hints to the prover. Output is suppressed if [47mquiet-flg[0m is supplied and not [47mnil[0m.") (free (proof-builder-commands) "(atomic macro) create a ``free variable'' Example: (free x) General Form: (free var) Mark [47mvar[0m as a ``free variable''. Free variables are only of interest for the [47mput[0m command; see [ACL2-pc::put].") (geneqv (proof-builder-commands) "(macro) show the generated equivalence relation maintained at the current subterm General Forms: geneqv ; show list of equivalence relations being maintained (geneqv t) ; as above, but pair each relation with a justifying rune This is an advanced command, whose effect is to print the so-called ``generated equivalence relation'' (or ``geneqv'') that is maintained at the current subterm of the conclusion. That structure is a list of equivalence relations, representing the transitive closure [47mE[0m of the union of those relations, such that it suffices to maintain [47mE[0m at the current subterm: if that subterm, [47mu[0m, is replaced in the goal's conclusion, [47mG[0m, by another term equivalent to [47mu[0m with respect to [47mE[0m, then the resulting conclusion is Boolean equivalent to [47mG[0m. Also see [defcong]. The command `[47mgeneqv[0m' prints the above list of equivalence relations, or more precisely, the list of function symbols for those relations. If however [47mgeneqv[0m is given a non-[47mnil[0m argument, then a list is printed whose elements are each of the form [47m(s r)[0m, where [47ms[0m is the symbol for an equivalence relation and [47mr[0m is a [47m:[0m[47m[congruence][0m [rune] justifying the inclusion of [47ms[0m in the list of equivalence relations being maintained at the current subterm.") (generalize (proof-builder-commands) "(primitive) perform a generalization Example: (generalize ((and (true-listp x) (true-listp y)) 0) ((append x y) w)) General Form: (generalize &rest substitution) Generalize using the indicated substitution, which should be a non-empty list. Each element of that list should be a two-element list of the form [47m(term variable)[0m, where [47mterm[0m may use abbreviations. The effect of the instruction is to replace each such term in the current goal by the corresponding variable. This replacement is carried out by a parallel substitution, outside-in in each hypothesis and in the conclusion. More generally, actually, the ``variable'' (second) component of each pair may be [47mnil[0m or a number, which causes the system to generate a new name of the form [47m_[0m or [47m_n[0m, with [47mn[0m a natural number; more on this below. However, when a variable is supplied, it must not occur in any goal of the current state of the interactive proof-builder. When the ``variable'' above is [47mnil[0m, the system will treat it as the variable [47m|_|[0m if that variable does not occur in any goal of the current proof-builder state. Otherwise it treats it as [47m|_0|[0m, or [47m|_1|[0m, or [47m|_2|[0m, and so on, until one of these is not among the variables of the current proof-builder state. If the ``variable'' is a non-negative integer [47mn[0m, then the system treats it as [47m|_n|[0m unless that variable already occurs among the current goals, in which case it increments n just as above until it obtains a new variable. [31;1mRemark:[0m The same variable may not occur as the variable component of two different arguments (though [47mnil[0m may occur arbitrarily many times, as may a positive integer).") (goals (proof-builder-commands proof-builder-commands-short-list) "(macro) list the names of goals on the stack Example and General Form: goals [47mGoals[0m lists the names of all goals that remain to be proved. They are listed in the order in which they appear on the stack of remaining goals, which is relevant for example to the effect of a [47mchange-goal[0m instruction.") (help (proof-builder-commands) "(macro) proof-builder help facility Examples: (help rewrite) -- documentation on the proof-builder rewrite command (help) -- this help (help help) -- same as (help) or simply, help (help all) -- same as (doc proof-builder-commands) General Forms: (help) ; or, just: help (help command) (help all) For any interactive proof-builder command, [47mC[0m, [47m(help C)[0m prints documentation on [47mC[0m to the terminal. You can read that documentation online or in the Emacs [ACL2-Doc] browser by viewing topic [47macl2-pc::C[0m; see [documentation]. To see a list of all interactive proof-builder commands, you can submit [47m(help all)[0m. This is actually equivalent to [47m(doc proof-builder-commands)[0m, which prints the documentation for topic [proof-builder-commands] (which, as discussed above, you can view online or with [ACL2-Doc]). Also see [ACL2-pc::doc], which provides a direct interface to the ACL2 [47m:[0m[47m[doc][0m command. For example, submitting [47m(help rewrite)[0m to the interactive proof-builder is equivalent to submitting [47m(doc acl2-pc::rewrite)[0m to the proof-builder or submitting [47m:doc acl2-pc::rewrite[0m directly to the ACL2 loop.") (hyps (proof-builder-commands) "(macro) print the hypotheses Examples: hyps -- print all (top-level) hypotheses (hyps (1 3) (2 4)) -- print hypotheses 1 and 3 and governors 2 and 4 (hyps (1 3) t) -- print hypotheses 1 and 3 and all governors General Form: (hyps &optional hyps-indices govs-indices) Print the indicated top-level hypotheses and governors. (The notion of ``governors'' is defined below.) Here, [47mhyps-indices[0m and [47mgovs-indices[0m should be lists of indices of hypotheses and governors (respectively), except that the atom [47mt[0m may be used to indicate that one wants all hypotheses or governors (respectively). The list of ``governors'' is defined as follows. Actually, we define here the notion of the governors for a pair of the form [47m<term[0m, address>]; we're interested in the special case where the term is the conclusion and the address is the current address. If the address is [47mnil[0m, then there are no governors, i.e., the list of governors is [47mnil[0m. If the term is of the form [47m(if x y z)[0m and the address is of the form [47m(2 . rest)[0m or [47m(3 . rest)[0m, then the list of governors is the result of [47mcons[0ming [47mx[0m or its negation (respectively) onto the list of governors for the pair [47m<y, rest>[0m or the pair [47m<z, rest>[0m (respectively). If the term is of the form [47m(implies x y)[0m and the address is of the form [47m(2 . rest)[0m, then the list of governors is the result of [47mcons[0ming [47mx[0m onto the list of governors for the pair [47m<y, rest>[0m. Otherwise, the list of governors for the pair [47m<term, (n . rest)>[0m is exactly the list of governors for the pair [47m<argn, rest>[0m where [47margn[0m is the [47mn[0mth argument of [47mterm[0m. If all goals have been proved, a message saying so will be printed. (as there will be no current hypotheses or governors!). The [47mhyps[0m command never causes an error. It ``succeeds'' (in fact its value is [47mt[0m) if the arguments (when supplied) are appropriate, i.e. either [47mt[0m or lists of indices of hypotheses or governors, respectively. Otherwise it ``fails'' (its value is [47mnil[0m).") (illegal (proof-builder-commands) "(macro) illegal instruction Example: (illegal -3) General Form: (illegal instruction) Probably not of interest to most users; always ``fails'' since it expands to the [47mfail[0m command. The [47millegal[0m command is used mainly in the implementation. For example, the instruction [47m0[0m is ``read'' as [47m(illegal 0)[0m, since [47mdive[0m expects positive integers.") (in-theory (proof-builder-commands proof-builder-commands-short-list) "(primitive) set the current proof-builder theory Example: (in-theory (union-theories (theory 'minimal-theory) '(true-listp binary-append))) General Form: (in-theory &optional atom-or-theory-expression) If the argument is not supplied, then this command sets the current interactive proof-builder theory (see below for explanation) to agree with the current ACL2 theory. Otherwise, the argument should be a theory expression, and in that case the proof-builder theory is set to the value of that theory expression. The current interactive proof-builder theory is used in all calls to the ACL2 theorem prover and rewriter from inside the proof-builder. Thus, the most recent [47min-theory[0m instruction in the current [47mstate-stack[0m has an effect in the proof-builder totally analogous to the effect caused by an [47min-theory[0m hint or event in ACL2. All [47min-theory[0m instructions before the last are ignored, because they refer to the current theory in the ACL2 [47m[state][0m, not to the existing proof-builder theory. For example: ACL2 !>:trans1 (enable bar) (UNION-THEORIES (CURRENT-THEORY :HERE) '(BAR)) ACL2 !>:trans1 (CURRENT-THEORY :HERE) (CURRENT-THEORY-FN :HERE WORLD) ACL2 !> Thus [47m(in-theory (enable bar))[0m modifies the current theory of the current ACL2 world. So for example, suppose that [47mfoo[0m is disabled outside the proof-builder and you execute the following instructions, in this order. (in-theory (enable foo)) (in-theory (enable bar)) Then after the second of these, [47mbar[0m will be enabled in the proof-builder, but [47mfoo[0m will be disabled. The reason is that [47m(in-theory (enable bar))[0m instructs the proof-builder to modify the current theory (from outside the proof-builder, not from inside the proof-builder) by enabling [47mbar[0m. Note that [47min-theory[0m instructions in the proof-builder have no effect outside the proof-builder's interactive loop. If the most recent [47min-theory[0m instruction in the current state of the proof-builder has no arguments, or if there is no [47min-theory[0m instruction in the current state of the proof-builder, then the proof-builder will use the current ACL2 theory. This is true even if the user has interrupted the interactive loop by exiting and changing the global ACL2 theory. However, if the most recent [47min-theory[0m instruction in the current state of the proof-builder had an argument, then global changes to the current theory will have no effect on the proof-builder state.") (induct (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) generate subgoals using induction Examples: induct, (induct t) -- induct according to a heuristically-chosen scheme, creating a new subgoal for each base and induction step (induct (append (reverse x) y)) -- as above, but choose an induction scheme based on the term (append (reverse x) y) rather than on the current goal General Form: (induct &optional term) Induct as in the corresponding [47m:induct[0m hint given to the theorem prover, creating new subgoals for the base and induction steps. If term is [47mt[0m or is not supplied, then use the current goal to determine the induction scheme; otherwise, use that term. [31;1mRemark:[0m As usual, abbreviations are allowed in the term. [31;1mRemark:[0m [47mInduct[0m actually calls the [47mprove[0m command with all processes turned off. Thus, you must be at top of the goal for an [47minduct[0m instruction.") (lemmas-used (proof-builder-commands) "(macro) print the runes (definitions, lemmas, ...) used This is just an alias for [47mrunes[0m.") (lisp (proof-builder-commands) "(meta) evaluate the given form in Lisp Example: (lisp (assign xxx 3)) General Form: (lisp form) Evaluate [47mform[0m. The [47mlisp[0m command is mainly of interest for side effects. Also see [ACL2-pc::print], [ACL2-pc::skip], and [ACL2-pc::fail]. The rest of the documentation for [47mlisp[0m is of interest only to those who use it in macro commands. If the Lisp evaluation (by [47mtrans-eval[0m) of form returns an [error-triple] of the form [47m(mv erp ((NIL NIL STATE) . (erp-1 val-1 &)) state)[0m, then the [47mlisp[0m command returns the appropriate error triple (mv (or erp erp-1) val-1 state) . Otherwise, the [47mtrans-eval[0m of form must return an error triple of the form [47m(mv erp (cons stobjs-out val) &)[0m, and the [47mlisp[0m command returns the appropriate error triple (mv erp val state). Note that the output signature of the form has been lost. The user must know the signature in order to use the output of the [47mlisp[0m command. Trans-eval, which is undocumented except by comments in the ACL2 source code, has replaced, in [47mval[0m, any occurrence of the current state or the current values of stobjs by simple symbols such as [47mREPLACED-STATE[0m. The actual values of these objects may be recovered, in principle, from the [47mstate[0m returned and the [47muser-stobj-alist[0m within that state. However, in practice, the stobjs cannot be recovered because the user is denied access to [47muser-stobj-alist[0m. The moral is: do not try to write macro commands that manipulate stobjs. Should the returned [47mval[0m contain [47mREPLACED-STATE[0m the value may simply be ignored and [47mstate[0m used, since that is what [47mREPLACED-STATE[0m denotes.") (negate (proof-builder-commands) "(macro) run the given instructions, and ``succeed'' if and only if they ``fail'' Example: (negate prove) General form: (negate &rest instruction-list) Run the indicated instructions exactly in the sense of [47mdo-all[0m, and ``succeed'' if and only if they ``fail''. [31;1mRemark:[0m [47mNegate[0m instructions will never produce hard ``failures''.") (nil (proof-builder-commands) "(macro) used for interpreting [47mcontrol-d[0m Example and General form: nil (or, [47mcontrol-d[0m). The whole point of this command is that there have been Lisps where if you type [47mcontrol-d[0m then it seems, on occasion, to get interpreted as [47mnil[0m. Without this command, one seems to get into an infinite loop.") (noise (proof-builder-commands) "(meta) run instructions with prover output Example: (noise induct prove) General Form: (noise &rest instruction-list) Run the [47minstruction-list[0m through the top-level loop with prover output. In fact, having prover output is the default. [47mNoise[0m is useful inside a surrounding call of [47mquiet[0m, when one temporarily wants output. For example, if one wants to see output for a [47mprove[0m command immediately following an [47minduct[0m command but before an [47ms[0m command, one may want to submit an instruction like [47m(quiet induct (noise prove) s)[0m. Also see [ACL2-pc::quiet] and [ACL2-pc::noise!].") (noise! (proof-builder-commands) "(meta) run instructions with prover and proof-tree output Example: (noise! induct prove) General Form: (noise! &rest instruction-list) Run the [47minstruction-list[0m through the top-level loop with prover output and [proof-tree] output. See [ACL2-pc::noise]; the [47mnoise![0m command is the same, except for adding proof-tree output.") (nx (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) move forward one argument in the enclosing term Example and General Form: nx For example, if the conclusion is [47m(= x (* (- y) z))[0m and the current subterm is [47mx[0m, then after executing [47mnx[0m, the current subterm will be [47m(* (- y) z)[0m. This is the same as [47mup[0m followed by [47m(dive n+1)[0m, where [47mn[0m is the position of the current subterm in its parent term in the conclusion. Thus in particular, the [47mnx[0m command fails if one is already at the top of the conclusion. Also see [ACL2-pc::up], [ACL2-pc::dive], [ACL2-pc::top], and [ACL2-pc::bk].") (orelse (proof-builder-commands) "(macro) run the first instruction; if (and only if) it ``fails'', run the second Example: (orelse top (print "Couldn't move to the top")) General form: (orelse instr1 instr2) Run the first instruction. Then if it ``fails'', run the second instruction also; otherwise, stop after the first. This instruction ``succeeds'' if and only if either [47minstr1[0m ``succeeds'', or else [47minstr2[0m ``succeeds''. If it ``fails'', then the failure is soft.") (p (proof-builder-commands proof-builder-commands-short-list) "(macro) prettyprint the current term in the usual user-level (untranslated) syntax Example and General Form: p Prettyprint the current term. The usual user (untranslated) syntax is used, so that for example one would see [47m(and x y)[0m rather than [47m(if x y 'nil)[0m. (See also [47mpp[0m.) Also, abbreviations are inserted where appropriate; see [ACL2-pc::add-abbreviation]. The ``current term'' is the entire conclusion unless [47mdive[0m commands have been given, in which case it may be a subterm of the conclusion. If all goals have been proved, a message saying so will be printed (as there will be no current [47mterm[0m!).") (p-top (proof-builder-commands proof-builder-commands-short-list) "(macro) prettyprint the conclusion, highlighting the current term Example and General Form: p-top For example, if the conclusion is [47m(equal (and x (p y)) (foo z))[0m and the current subterm is [47m(p y)[0m, then [47mp-top[0m will print [47m(equal (and x (*** (p y) ***)) (foo z))[0m. Prettyprint the conclusion, highlighting the current term. The usual user syntax is used, as with the command [47mp[0m (as opposed to [47mpp[0m). This is illustrated in the example above, where one would [3m*not*[0m see [47m(equal (if x (*** (p y) ***) 'nil) (foo z))[0m. [31;1mRemark[0m (obscure): In some situations, a term of the form [47m(if x t y)[0m occurring inside the current subterm will not print as [47m(or x y)[0m, when [47mx[0m isn't a call of a boolean primitive. There's nothing incorrect about this, however.") (pl (proof-builder-commands) "(macro) print the rules for a given name Examples: pl (pl foo) General Form: (pl &optional x) This command simply invokes the corresponding command of the top-level ACL2 loop; see [pl]. If no argument is given, or if the argument is [47mnil[0m, then the current subterm should be a call of a function symbol, and the argument is taken to be that symbol. If you want information about applying rewrite rules to the current subterm, consider the [47mshow-rewrites[0m (or equivalently, [47msr[0m) command.") (pot-lst (proof-builder-commands) "(macro) display the linear arithmetic database based on the current context This is a relatively advanced command. For discussion of a related but more elementary command, including remarks about the utility of such a command, see [ACL2-pc::type-alist]. See [linear-arithmetic] for a description of the ACL2 linear arithmetic decision procedure Examples: (pot-lst nil t) ; display linear pot-lst based on governors only (default) pot-lst ; same as (pot-lst nil t) -- governors only (default) (pot-lst nil) ; same as (pot-lst nil t) -- governors only (default) (pot-lst nil t nil nil) ; same as above (pot-lst nil t nil t) ; same as above, except: raw format (pot-lst t t) ; display pot-lst based on conclusion and governors (pot-lst t) ; same as (pot-lst t nil) -- conclusion only (pot-lst nil nil) ; based on neither conclusion nor governors General Form: (pot-lst &optional concl-flg govs-flg rawp) where if [47mgovs-flg[0m is omitted then it defaults to [47m(not concl-flg)[0m, and each of the other optional arguments defaults to [47mnil[0m. This command displays the linear database, also known as the linear [3mpot-lst[0m, that is computed from a suitable set of assumptions. That set of assumptions always includes all top-level hypotheses. By default, and when [47mgovs-flg[0m is supplied a non-[47mnil[0m value, the set of assumptions includes all governors (which are based on surrounding if-expressions that must be true or false). The negation of the current goal's top-level conclusion is also included in the assumptions when [47mconcl-flg[0m is supplied a non-[47mnil[0m value. The computed pot-lst is based on the result of forward chaining from the set of assumptions as described above. By default, that pot-lst is displayed in a self-explanatory way. Here is an (admittedly contrived) example. ACL2 !>(verify (implies (and (>= (- (nth 3 x) a) 7) (< (nth 3 x) b) (< c b)) (< (nth 3 x) d))) ->: promote ->: th *** Top-level hypotheses: 1. (<= 7 (+ (NTH 3 X) (- A))) 2. (< (NTH 3 X) B) 3. (< C B) The current subterm is: (< (NTH 3 X) D) ->: pot-lst Current pot-lst: ----- For maximal term B the list of polynomials is: ((A + 7 < B)) ----- For maximal term C the list of polynomials is: ((C < B)) ----- For maximal term (NTH '3 X) the list of polynomials is: (((NTH '3 X) < B) (A + 7 <= (NTH '3 X))) NIL ->: (pot-lst t t) Current pot-lst: ----- For maximal term B the list of polynomials is: ((A + 7 < B)) ----- For maximal term C the list of polynomials is: ((C < B)) ----- For maximal term D the list of polynomials is: ((D < B)) ----- For maximal term (NTH '3 X) the list of polynomials is: (((NTH '3 X) < B) (A + 7 <= (NTH '3 X)) (D <= (NTH '3 X))) NIL ->: You can get the internal form of the pot-lst by supplying all optional arguments including a non-[47mnil[0m value for [47mrawp[0m.") (pp (proof-builder-commands) "(macro) prettyprint the current term in internal (translated) form Example and General Form: pp This is the same as [47mp[0m (see its documentation), except that raw syntax (internal form) is used. So for example, one would see [47m(if x y 'nil)[0m rather than [47m(and x y)[0m. Abbreviations are however still inserted, as with [47mp[0m.") (pr (proof-builder-commands) "(macro) print the rules for a given name Examples: pr (pr foo) General Form: (pr &optional x) This command simply invokes the corresponding command of the top-level ACL2 loop; see [pr]. If no argument is given, or if the argument is [47mnil[0m, then the current subterm should be a call of a function symbol, and the argument is taken to be that symbol. If you want information about applying rewrite rules to the current subterm, consider the [47mshow-rewrites[0m (or equivalently, [47msr[0m) command.") (print (proof-builder-commands) "(macro) print the result of evaluating the given form Example: (print (append '(a b) '(c d))) Print the list (a b c d) to the terminal General Forms: (print form) (print form t) Prettyprints the result of evaluating form. The evaluation of [47mform[0m should return a single value that is not [47m[state][0m or a single-threaded object (see [stobj]). The optional second argument causes printing to be done without elision (so-called ``evisceration''; see [evisc-tuple]). If the form you want to evaluate does not satisfy the criterion above, you should create an appropriate call of the [47mlisp[0m command instead. Notice that this command always returns [47m(mv nil nil state)[0m where the second result will always be [47mREPLACED-STATE[0m.") (print-all-concs (proof-builder-commands) "(macro) print all the conclusions of (as yet unproved) goals Example and General Form: print-all-concs Prints all the conclusions of goals that remain to be proved, in a pleasant format, ordered as by the command, [47m[ACL2-pc::goals][0m. Also see [ACL2-pc::print-all-goals].") (print-all-goals (proof-builder-commands) "(macro) print all the (as yet unproved) goals Example and General Form: print-all-goals Prints all the goals that remain to be proved, in a pleasant format, ordered as by the command, [47m[ACL2-pc::goals][0m. Also see [ACL2-pc::print-all-concs].") (print-main (proof-builder-commands) "(macro) print the original goal Example and General Form: print-main Print the goal as originally entered.") (pro (proof-builder-commands) "(atomic macro) repeatedly apply promote Example and General Form: pro Apply the [47mpromote[0m command until there is no change. This command ``succeeds'' exactly when at least one call of [47mpromote[0m ``succeeds''. In that case, only a single new proof-builder state will be created. Note: The [47msplit[0m command is probably more helpful in many cases than [47mpro[0m.") (promote (proof-builder-commands) "(primitive) move antecedents of conclusion's [47mimplies[0m term to top-level hypotheses Examples: promote (promote t) For example, if the conclusion is [47m(implies (and x y) z)[0m, then after execution of [47mpromote[0m, the conclusion will be [47mz[0m and the terms [47mx[0m and [47my[0m will be new top-level hypotheses. General Form: (promote &optional do-not-flatten-flag) Replace conclusion of [47m(implies hyps exp)[0m or [47m(if hyps exp t)[0m with simply [47mexp[0m, adding [47mhyps[0m to the list of top-level hypotheses. Moreover, if [47mhyps[0m is viewed as a conjunction then each conjunct will be added as a separate top-level hypothesis. An exception is that if [47mdo-not-flatten-flag[0m is supplied and not [47mnil[0m, then only one top-level hypothesis will be added, namely [47mhyps[0m. [31;1mRemark[0m: You must be at the top of the conclusion in order to use this command. Otherwise, first invoke [47mtop[0m.") (protect (proof-builder-commands) "(macro) run the given instructions, reverting to existing state upon failure Example: (protect induct p prove) General Form: (protect &rest instruction-list) [47mProtect[0m is the same as [47mdo-strict[0m, except that as soon as an instruction ``fails'', the state-stack reverts to what it was before the [47mprotect[0m instruction began, and [47mrestore[0m is given the same meaning that it had before the [47mprotect[0m instruction began. See [ACL2-pc::do-strict].") (prove (proof-builder-commands proof-builder-commands-short-list) "(primitive) call the ACL2 theorem prover to prove the current goal Examples: prove -- attempt to prove the current goal (prove :otf-flg t :hints (("Subgoal 2" :by foo) ("Subgoal 1" :use bar))) -- attempt to prove the current goal, with the indicated hints and with OTF-FLG set General Form: (prove &rest rest-args) Attempt to prove the current goal, where [47mrest-args[0m is as in the keyword arguments to [47mdefthm[0m except that only [47m:hints[0m and [47m:otf-flg[0m are allowed. The command succeeds exactly when the corresponding [47mdefthm[0m would succeed, except that it is all right for some goals to be given ``bye''s. Each goal given a ``bye'' will be turned into a new subgoal. (See [hints] for an explanation of [47m:by[0m hints.) [31;1mRemark:[0m Use [47m(= t)[0m instead if you are not at the top of the conclusion. Also note that if there are any hypotheses in the current goal, then what is actually attempted is a proof of [47m(implies hyps conc)[0m, where [47mhyps[0m is the conjunction of the top-level hypotheses and [47mconc[0m is the goal's conclusion. [31;1mRemark:[0m It is allowed to use abbreviations in the hints.") (pso (proof-builder-commands) "(macro) print the most recent proof attempt from inside the proof-builder Example and General Form: pso Print the most recent proof attempt from inside the interactive proof-builder. This includes prover calls, including for example [proof-builder] commands [47minduct[0m, [47msplit[0m, and [47mbash[0m, in addition to [47mprove[0m. So for example, you can follow [47m(quiet prove)[0m with [47mpso[0m to see the proof, including [proof-tree] output, if it failed. Related [proof-builder] commands are [47mpsog[0m and [47mpso![0m; see [ACL2-pc::psog] and [ACL2-pc::pso!].") (pso! (proof-builder-commands) "(macro) print the most recent proof attempt from inside the proof-builder Example and General Form: pso! Print the most recent proof attempt from inside the interactive proof-builder. This includes prover calls, including for example [proof-builder] commands [47minduct[0m, [47msplit[0m, and [47mbash[0m, in addition to [47mprove[0m. So for example, you can follow [47m(quiet prove)[0m with [47mpso![0m to see the proof, including [proof-tree] output, if it failed. Related [proof-builder] commands are [47mpso[0m and [47mpsog[0m; see [ACL2-pc::pso] and [ACL2-pc::psog].") (psog (proof-builder-commands) "(macro) print the most recent proof attempt from inside the proof-builder Example and General Form: psog Print the most recent proof attempt from inside the interactive proof-builder, including goal names. This includes prover calls, including for example [proof-builder] commands [47minduct[0m, [47msplit[0m, and [47mbash[0m, in addition to [47mprove[0m. So for example, you can follow [47m(quiet prove)[0m with [47mpsog[0m to see the proof, including [proof-tree] output, if it failed. Related [proof-builder] commands are [47mpso[0m and [47mpso![0m; see [ACL2-pc::pso] and [ACL2-pc::pso!].") (put (proof-builder-commands) "(macro) substitute for a ``free variable'' Example: (put x 17) General Form: (put var expr) Substitute [47mexpr[0m for the ``free variable'' [47mvar[0m, as explained below. A ``free variable'' is, for our purposes, a variable [47mvar[0m such that the instruction [47m(free var)[0m has been executed earlier in the state-stack. What [47m(free var)[0m really does is to let [47mvar[0m be an abbreviation for the term [47m(hide var)[0m (see [ACL2-pc::add-abbreviation]). What [47m(put var expr)[0m really does is to unwind the state-stack, replacing that [47mfree[0m instruction with the instruction [47m(add-abbreviation var expr)[0m, so that future references to [47m(? var)[0m become reference to [47mexpr[0m rather than to [47m(hide var)[0m, and then to replay all the other instructions that were unwound. Because [47mhide[0m was used, the expectation is that in most cases, the instructions will replay successfully and [47mput[0m will ``succeed''. However, if any replayed instruction ``fails'', then the entire replay will abort and ``fail'', and the state-stack will revert to its value before the [47mput[0m instruction was executed. If [47m(put var expr)[0m ``succeeds'', then [47m(remove-abbreviation var)[0m will be executed at the end. [31;1mRemark[0m: The [47mrestore[0m command will revert the state-stack to its value present before the [47mput[0m instruction was executed.") (quiet (proof-builder-commands) "(meta) run instructions without prover output Example: (quiet induct prove) General Form: (quiet &rest instruction-list) Run the [47minstruction-list[0m through the top-level loop with no output. Also see [ACL2-pc::noise] and [ACL2-pc::quiet!].") (quiet! (proof-builder-commands) "(meta) run instructions without prover output Example: (quiet! induct prove) General Form: (quiet! &rest instruction-list) Run the [47minstruction-list[0m through the top-level loop with no output. See [ACL2-pc::quiet]; the two commands are equivalent, except that the [47mquiet![0m command additionally suppresses the printing of goal identifiers (as with [47m[set-print-clause-ids][0m).") (r (proof-builder-commands proof-builder-commands-short-list) "(macro) same as rewrite Example: (r 3) See [ACL2-pc::rewrite].") (reduce (proof-builder-commands) "(atomic macro) call the ACL2 theorem prover's simplifier Examples: reduce -- attempt to prove the current goal without using induction (reduce ("Subgoal 2" :by foo) ("Subgoal 1" :use bar)) -- attempt to prove the current goal without using induction, with the indicated hints General Form: (reduce &rest hints) Attempt to prove the current goal without using induction, using the indicated hints (if any). A subgoal will be created for each goal that would have been pushed for proof by induction in an ordinary proof. Notice that unlike [47mprove[0m, the arguments to [47mreduce[0m are spread out, and are all hints. [47mReduce[0m is similar to [47mbash[0m in that neither of these allows induction. But [47mbash[0m only allows simplification, while [47mreduce[0m allows processes [47meliminate-destructors[0m, [47mfertilize[0m, [47mgeneralize[0m, and [47meliminate-irrelevance[0m. [31;1mRemark:[0m Induction will be used to the extent that it is ordered explicitly in the hints.") (reduce-by-induction (proof-builder-commands) "(macro) call the ACL2 prover without induction, after going into induction Examples: reduce-by-induction -- attempt to prove the current goal after going into induction, with no further inductions (reduce-by-induction ("Subgoal 2" :by foo) ("Subgoal 1" :use bar)) -- attempt to prove the current goal after going into induction, with no further inductions, using the indicated hints General Form: (reduce-by-induction &rest hints) A subgoal will be created for each goal that would have been pushed for proof by induction in an ordinary proof, except that the proof begins with a top-level induction. Notice that unlike [47mprove[0m, the arguments to [47mreduce-by-induction[0m are spread out, and are all hints. Also see [ACL2-pc::prove], [ACL2-pc::reduce], and [ACL2-pc::bash]. [31;1mRemark[0m: Induction and the various processes will be used to the extent that they are specified explicitly in the [47m:induct[0m and [47m:do-not[0m [hints].") (remove-abbreviations (proof-builder-commands) "(primitive) remove one or more abbreviations Examples: remove-abbreviations -- remove all abbreviations (remove-abbreviations v w) -- assuming that V and W currently abbreviate terms, then they are ``removed'' in the sense that they are no longer considered to abbreviate those terms General Forms: (remove-abbreviations &rest vars) If vars is not empty (i.e., not [47mnil[0m), remove the variables in [47mvars[0m from the current list of abbreviations, in the sense that each variable in [47mvars[0m will no longer abbreviate a term. [31;1mRemark:[0m The instruction fails if at least one of the arguments fails to be a variable that abbreviates a term. Also see [ACL2-pc::add-abbreviation] for a discussion of abbreviations in general, and see [ACL2-pc::show-abbreviations].") (repeat (proof-builder-commands) "(macro) repeat the given instruction until it ``fails'' Example: (repeat promote) General Form: (repeat instruction) The given [47minstruction[0m is run repeatedly until it ``fails''. A call of [47m:repeat[0m always ``succeeds''. [31;1mRemark:[0m There is nothing here in general to prevent the instruction from being run after all goals have been proved, though it may then fail, thus causing [47m:repeat[0m to return.") (repeat-rec (proof-builder-commands) "(macro) auxiliary to [47mrepeat[0m See [ACL2-pc::repeat].") (replay (proof-builder-commands proof-builder-commands-short-list) "(macro) replay one or more instructions Examples: REPLAY -- replay all instructions in the current session (i.e., state-stack) (REPLAY 5) -- replay the most recent 5 instructions (REPLAY 5 (COMMENT deleted dive command here)) -- replace the 5th most recent instruction with the indicated comment instruction, and then replay it followed by the remaining 4 instructions General Form: (REPLAY &OPTIONAL n replacement-instruction) Replay the last [47mn[0m instructions if [47mn[0m is a positive integer; else [47mn[0m should be [47mnil[0m or not supplied, and replay all instructions. However, if [47mreplacement-instruction[0m is supplied and not [47mnil[0m, then before the replay, replace the [47mnth[0m instruction (from the most recent, as shown by [47mcommands[0m) with [47mreplacement-instruction[0m. If this command ``fails'', then the [47mrestore[0m command will revert the state-stack to its value present before the [47mreplay[0m instruction was executed.") (restore (proof-builder-commands proof-builder-commands-short-list) "(meta) remove the effect of an UNDO command Example and General Form: restore [47mRestore[0m removes the effect of an [47mundo[0m command. This always works as expected if [47mrestore[0m is invoked immediately after [47mundo[0m, without intervening instructions. However, other commands may also interact with [47mrestore[0m, notably ``sequencing'' commands such as [47mdo-all[0m, [47mdo-strict[0m, [47mprotect[0m, and more generally, [47msequence[0m. [31;1mRemark:[0m Another way to control the saving of proof-builder state is with the [47msave[0m command; see [ACL2-pc::save]. The [47mrestore[0m command always ``succeeds''; it returns [47m(mv nil t state)[0m.") (retain (proof-builder-commands) "(atomic macro) drop all [31;1mbut[0m the indicated top-level hypotheses Example: (RETAIN 2 3) -- keep the second and third hypotheses, and drop the rest General Form: (retain &rest args) Drop all top-level hypotheses [31;1mexcept[0m those with the indicated indices. There must be at least one argument, and all must be in range (i.e. integers between one and the number of top-level hypotheses, inclusive).") (retrieve (proof-builder-commands proof-builder-commands-short-list) "(macro) re-enter the proof-builder Examples: (retrieve associativity-of-permutationp) retrieve General Form: (retrieve &optional name) Must be used from [47moutside[0m the interactive proof-builder loop. If name (which must be a symbol) is supplied and not [47mnil[0m, this causes re-entry to the interactive proof-builder loop in the state at which [47msave[0m was last executed for the indicated name. (See [ACL2-pc::save].) If [47mname[0m is [47mnil[0m or is not supplied, then the user is queried regarding which proof-builder state to re-enter. The query is omitted, however, if there only one proof-builder state is present that was saved with [47msave[0m, in which case that is the one that is used. Also see [ACL2-pc::unsave].") (rewrite (proof-builder-commands) "(primitive) apply a rewrite rule Examples: (rewrite reverse-reverse) -- apply the rewrite rule `reverse-reverse' (rewrite (:rewrite reverse-reverse)) -- same as above (rewrite 2) -- apply the second rewrite rule, as displayed by show-rewrites rewrite -- apply the first rewrite rule, as displayed by show-rewrites (rewrite transitivity-of-< ((y 7))) -- apply the rewrite rule transitivity-of-< with the substitution that associates 7 to the ``free variable'' y (rewrite foo ((x 2) (y 3)) t) -- apply the rewrite rule foo by substituting 2 and 3 for free variables x and y, respectively, and also binding all other free variables possible by using the current context (hypotheses and governors) General Form: (rewrite &optional rule-id substitution instantiate-free) Replace the current subterm with a new term by applying a [rewrite] or [definition] rule. The replacement will be done according to the information provided by the [47mshow-rewrites[0m ([47msr[0m) command. If [47mrule-id[0m is a positive integer [47mn[0m, then the [47mn[0mth rule as displayed by [47mshow-rewrites[0m is the one that is applied. If [47mrule-id[0m is [47mnil[0m or is not supplied, then it is treated as the number 1. Otherwise, [47mrule-id[0m should be either a symbol or else a [47m:rewrite[0m or [47m:definition[0m [rune]. If a symbol is supplied, then any ([47m:rewrite[0m or [47m:definition[0m) rule of that name may be used. We say more about this, and describe the other optional arguments, below. Consider first the following example. Suppose that the current subterm is [47m(reverse (reverse y))[0m and that there is a [rewrite] rule called [47mreverse-reverse[0m of the form (implies (true-listp x) (equal (reverse (reverse x)) x)) . Then the instruction [47m(rewrite reverse-reverse)[0m causes the current subterm to be replaced by [47my[0m and creates a new goal with conclusion [47m(true-listp y)[0m. An exception is that if the top-level hypotheses imply [47m(true-listp y)[0m using only ``trivial reasoning'' (more on this below), then no new goal is created. If the [47mrule-id[0m argument is a number or is not supplied, then the system will store an instruction of the form [47m(rewrite name ...)[0m, where [47mname[0m is the name of a rewrite rule; this is in order to make it easier to replay instructions when there have been changes to the history. Except: instead of the name (whether the name is supplied or calculated), the system stores the [rune] if there is any chance of ambiguity. (Formally, ``ambiguity'' here means that the rune being applied is of the form [47m(:rewrite name . index)[0m, where index is not [47mnil[0m.) Speaking in general, then, a [47mrewrite[0m instruction works as follows: First, a [rewrite] or [definition] rule is selected according to the arguments of the [47mrewrite[0m instruction. The selection is made as explained under ``General Form'' above. Next, the left-hand side of the rule is matched with the current subterm, i.e., a substitution [47munify-subst[0m is found such that if one instantiates the left-hand side of the rule with [47munify-subst[0m, then one obtains the current subterm. If this match fails, then the instruction fails. Next, an attempt is made to relieve (discharge) the hypotheses, much as the theorem prover relieves hypotheses except that there is no call to the rewriter. First, the substitution [47munify-subst[0m is extended with the [47msubstitution[0m argument, which may bind free variables (see [free-variables]). Each hypothesis of the rule is then considered in turn, from first to last. For each hypothesis, first the current substitution is applied, and then the system checks whether the hypothesis is ``clearly'' true in the current context. If there are variables in the hypotheses of the rule that are not bound by the current substitution, then a weak attempt is made to extend that substitution so that the hypothesis is present in the current context (see [ACL2-pc::hyps]), much as would be done by the theorem prover's rewriter. If in the process above there are free variables (see [free-variables]), but the interactive proof-builder can see how to bind them to relieve all hypotheses, then it will do so in both the [47mshow-rewrites[0m ([47msr[0m) and [47mrewrite[0m commands. But normally, if even one hypothesis remains unrelieved, then no automatic extension of the substitution is made. Except, if [47minstantiate-free[0m is not [47mnil[0m, then that extension to the substitution is kept. (Technical note: in the case of an unrelieved hypothesis and a non-[47mnil[0m value of [47minstantiate-free[0m, if a [47m[bind-free][0m hypothesis produces a list of binding alists, then the last of those alists is the one that is used to extend the substitution.) Finally, the instruction is applied as follows. The current subterm is replaced by applying the final substitution described above to the right-hand side of the selected rule. And, one new subgoal is created for each unrelieved hypothesis of the rule, whose top-level hypotheses are the governors and top-level hypotheses of the current goal and whose conclusion and current subterm are the instance, by that same final substitution, of that unrelieved hypothesis. [31;1mRemark:[0m The substitution argument should be a list whose elements have the form [47m(variable term)[0m, where [47mterm[0m may contain abbreviations.") (run-instr-on-goal (proof-builder-commands) "(macro) auxiliary to THEN See [ACL2-pc::then].") (run-instr-on-new-goals (proof-builder-commands) "(macro) auxiliary to [47mthen[0m See [ACL2-pc::then].") (runes (proof-builder-commands proof-builder-commands-short-list) "(macro) print the runes (definitions, lemmas, ...) used Examples and general forms: (runes t) ; print all [rune]s used during this interactive proof (runes nil) ; print all [rune]s used by the most recent command (runes) ; same as (runes nil) runes ; same as (runes nil) This command does not change the state of the interactive [proof-builder]. Rather, it simply reports runes (see [rune]) that have participated in the interactive proof. Note that [47m(runes nil)[0m will show the [rune]s used by the most recent primitive or macro command (as displayed by [47m:comm[0m).") (s (proof-builder-commands proof-builder-commands-short-list) "(primitive) simplify the current subterm Examples: S -- simplify the current subterm (S :backchain-limit 2 :normalize t :expand (append x z)) -- simplify the current subterm, but during the rewriting process, normalization, which will push IFs to the top-level, and also force the term (append x z) to be expanded during the rewriting process General Form: (s &key rewrite linear normalize backchain-limit repeat in-theory hands-off expand) Simplify the current subterm according to the keyword parameters supplied. First [normalization] is applied (unless the [47m:normalize[0m argument is [47mnil[0m), so that for example, each subterm of the form [47m(f ... (if test x y) ...)[0m is replaced by the term [47m(if test (f ... x ...) (f ... y ...))[0m --- except, of course, when [47mf[0m is [47mif[0m and the indicated [47mif[0m subterm is in the second or third argument position. See [normalize] for details. Then rewriting is applied (unless the rewrite argument is [47mnil[0m). Finally this pair of actions is repeated --- until the rewriting step causes no change in the term. A description of each parameter follows. :rewrite -- default t When non-[47mnil[0m, instructs the system to use ACL2's rewriter (or, something close to it) during simplification. :linear -- default t (except, default nil if :rewrite has value nil) When non-[47mnil[0m, instructs the system to use ACL2's linear arithmetic (see [LINEAR-ARITHMETIC]) to build a suitable context (a ``linear pot list'') from the assumptions (the top-level hypotheses and the governors (see [ACL2-PC::HYPS])). Note that linear arithmetic is used by the rewriter regardless; by default, when [47m:s[0m invokes the rewriter then linear arithmetic can take advantage of the information in the top-level hypotheses and the governors. :normalize -- default t When non-[47mnil[0m, instructs the system to use [normalization] (as described above) during simplification. :backchain-limit -- default 0 Sets the number of recursive calls to the rewriter that are allowed for backchaining. Even with the default of 0, some reasoning is allowed (technically speaking, type reasoning (see [TYPE-REASONING]) is allowed) in the relieving of hypotheses. The value should be [47mnil[0m or a non-negative integer, and limits backchaining only for rewriting, not for type reasoning. :repeat -- default 0 Sets the number of times the current term is to be rewritten. If this value is [47mt[0m, then the default is used (as specified by the constant [47m*default-s-repeat-limit*[0m). :in-theory, :hands-off, :expand These have their usual meaning; see [hints]. [31;1mRemark:[0m if conditional rewrite rules are used that cause case splits because of the use of [47mforce[0m, then appropriate new subgoals will be created, i.e., with the same current subterm (and address) but with each new (forced) hypothesis being negated and then used to create a corresponding new subgoal. In that case, the current goal will have all such new hypotheses added to the list of top-level hypotheses.") (s-prop (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) simplify propositionally Example: s-prop General Form: (s-prop &rest names) Simplify, using the default settings for [47ms[0m (which include [normalization] and rewriting without real backchaining), but with respect to a theory in which only basic functions and rules (the ones in [47m(theory 'minimal-theory)[0m), together with the names (or parenthesized names) in the [47m&rest[0m argument [47mnames[0m, are enabled. Also see [ACL2-pc::s].") (save (proof-builder-commands proof-builder-commands-short-list) "(macro) save the proof-builder state (state-stack) Example: (save lemma3-attempt) General Form: (save &optional name do-it-flg) Saves the current state of the interactive proof-builder by ``associating'' it with the given name, which must be a symbol. Submit [47m(retrieve name)[0m to Lisp to get back to this proof-builder state. If [47mverify[0m was originally supplied with an event name, then the argument can be omitted in favor of that name as the default. [31;1mRemark[0m that if a [47msave[0m has already been done with the indicated name (or the default event name), then the user will be queried regarding whether to go ahead with the save --- except, if [47mdo-it-flg[0m is supplied and not [47mnil[0m, then there will be no query and the [47msave[0m will be effected. Also see [ACL2-pc::retrieve] and [ACL2-pc::unsave].") (sequence (proof-builder-commands) "(meta) run the given list of instructions according to a multitude of options Example: (sequence (induct p prove) t) This is a very general command that is used to define other sequencing commands; see [ACL2-pc::do-all], [ACL2-pc::do-strict], [ACL2-pc::protect], and [ACL2-pc::succeed]. General Form: (sequence instruction-list &optional strict-flg protect-flg success-expr no-prompt-flg no-restore-flg) Each instruction in the list [47minstruction-list[0m is run, and the instruction ``succeeds'' if every instruction in [47minstruction-list[0m ``succeeds''. However, it might ``succeed'' even if some instructions in the list ``fail''; more generally, the various arguments control a number of aspects of the running of the instructions. All this is explained in the paragraphs below. First we embark on a general discussion of the instruction interpreter, including the notions of ``succeed'' and ``fail''. [31;1mRemark:[0m The arguments are [31;1mnot[0m evaluated, except (in a sense) for [47msuccess-expr[0m, as described below. Each primitive and meta instruction can be thought of as returning an [error-triple], say [47m(erp val state)[0m. An instruction (primitive or meta) ``succeeds'' if [47merp[0m is [47mnil[0m and [47mval[0m is not [47mnil[0m; otherwise it ``fails''. (When we use the words ``succeed'' or ``fail'' in this technical sense, we'll always include them in double quotes.) If an instruction ``fails,'' we say that the failure is ``soft'' if [47merp[0m is [47mnil[0m; otherwise the failure is ``hard''. The [47msequence[0m command gives the user control over how to treat ``success'' and ``failure'' when sequencing instructions, though we have created a number of handy macro commands for this purpose, notably [47mdo-all[0m, [47mdo-strict[0m and [47mprotect[0m. Here is precisely what happens when a [47msequence[0m instruction is run. The instruction interpreter is run on the instructions supplied in the argument [47minstruction-list[0m (in order). The interpreter halts the first time there is a hard ``failure.'' except that if [47mstrict-flg[0m is supplied and not [47mnil[0m, then the interpreter halts the first time there is any ``failure.'' The error triple [47m(erp val state)[0m returned by the [47msequence[0m instruction is the triple returned by the last instruction executed (or, the triple [47m(nil t state)[0m if [47minstruction-list[0m is [47mnil[0m), except for the following provision. If [47msuccess-expr[0m is supplied and not [47mnil[0m, then it is evaluated with the state global variables [47mpc-erp[0m and [47mpc-val[0m (in the "ACL2" package) bound to the corresponding components of the error triple returned (as described above). At least two values should be returned, and the first two of these will be substituted for [47merp[0m and [47mval[0m in the triple finally returned by [47msequence[0m. For example, if [47msuccess-expr[0m is [47m(mv erp val)[0m, then no change will be made to the error triple, and if instead it is [47m(mv nil t)[0m, then the [47msequence[0m instruction will ``succeed''. That concludes the description of the error triple returned by a [47msequence[0m instruction, but it remains to explain the effects of the arguments [47mprotect-flg[0m and [47mno-prompt-flg[0m. If [47mprotect-flg[0m is supplied and not [47mnil[0m and if also the instruction ``fails'' (i.e., the error component of the triple is not [47mnil[0m or the value component is [47mnil[0m), then the state is reverted so that the interactive proof-builder's state (including the behavior of [47mrestore[0m) is set back to what it was before the [47msequence[0m instruction was executed. Otherwise, unless [47mno-restore-flg[0m is set, the state is changed so that the [47mrestore[0m command will now undo the effect of this [47msequence[0m instruction (even if there were nested calls to [47msequence[0m). Finally, as each instruction in [47minstruction-list[0m is executed, the prompt and that instruction will be printed, unless the global state variable [47mpc-print-prompt-and-instr-flg[0m is unbound or [47mnil[0m and the parameter [47mno-prompt-flg[0m is supplied and not [47mnil[0m.") (show-abbreviations (proof-builder-commands) "(macro) display the current abbreviations Examples: (show-abbreviations v w) -- assuming that v and w currently abbreviate terms, then this instruction displays them together with the terms they abbreviate show-abbreviations -- display all abbreviations Also see [ACL2-pc::add-abbreviation] for a general discussion of abbreviations and see [ACL2-pc::remove-abbreviations]. General Form: (show-abbreviations &rest vars) Display each argument in [47mvars[0m together with the term it abbreviates (if any). If there are no arguments, i.e. the instruction is simply [47mshow-abbreviations[0m, then display all abbreviations together with the terms they abbreviate. If the term abbreviated by a variable, say [47mv[0m, contains a proper subterm that is also abbreviate by (another) variable, then both the unabbreviated term and the abbreviated term (but not using [47m(? v)[0m to abbreviate the term) are displayed with together with [47mv[0m.") (show-linears (proof-builder-commands) "(macro) display the applicable [linear] rules Example: show-linears General Form: (show-linears &optional rule-id enabled-only-flg) This command displays [linear] rules with a trigger term that matches the current subterm, and shows how they can be applied. This command is analogous to the [47mshow-rewrites[0m [proof-builder] command; see [ACL2-pc::show-rewrites]. Also see [ACL2-pc::apply-linear] for how to apply [linear] rules.") (show-rewrites (proof-builder-commands proof-builder-commands-short-list) "(macro) display the applicable [rewrite] rules Example: show-rewrites General Form: (show-rewrites &optional rule-id enabled-only-flg) This command displays [rewrite] rules whose left-hand side matches the current subterm, and shows how that command can be applied. For each rule displayed, hypotheses are shown that would need to be proved after the rule is applied. Note that hypotheses are omitted from the display when the system can trivially verify that they hold; to see all hypotheses for each rule in a display that is independent of the arguments of the current subterm, use the [47mpl[0m or [47mpr[0m command. Here are details on the arguments and the output. If [47mrule-id[0m is supplied and is a name (non-[47mnil[0m symbol) or a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m [rune], then only the corresponding rewrite rule(s) will be displayed, while if [47mrule-id[0m is a positive integer [47mn[0m, then only the [47mn[0mth rule that would be in the list is displayed. In each case, the display will point out when a rule is currently disabled (in the interactive environment), except that if [47menabled-only-flg[0m is supplied and not [47mnil[0m, then disabled rules will not be displayed at all. Finally, among the free variables of any rule (see [free-variables]), those that would remain free if the rule were applied will be displayed. Also see [rewrite].") (show-type-prescriptions (proof-builder-commands) "(macro) display the applicable [type-prescription] rules Example: show-type-prescriptions General Form: (show-type-prescriptions &optional rule-id) Display [type-prescription] rules that apply to the current subterm. If [47mrule-id[0m is supplied and is a name (non-[47mnil[0m symbol) or a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m [rune], then only the corresponding rewrite rule(s) will be displayed. In each case, the display will point out when a rule is currently disabled (in the interactive environment). Also see [type-prescription].") (skip (proof-builder-commands) "(macro) ``succeed'' without doing anything Example and General Form: skip Make no change in the state-stack, but ``succeed''. Same as [47m(sequence nil)[0m.") (sl (proof-builder-commands) "(atomic macro) simplify with lemmas Examples: sl (sl 3) General Form: (sl &optional backchain-limit) Simplify, but with all function definitions disabled (see [function-theory] in the top-level ACL2 loop), except for a few basic functions (the ones in [47m(theory 'minimal-theory)[0m). The [47mbackchain-limit[0m has a default of 0, but if it is supplied and not [47mnil[0m, then it should be a nonnegative integer; see [ACL2-pc::s]. WARNING: This command completely ignores [47min-theory[0m commands that are executed inside the interactive [proof-builder].") (sls (proof-builder-commands) "(macro) same as SHOW-LINEARS Example: sls General Form: (sls &optional rule-id enabled-only-flg) See [ACL2-pc::show-linears]. NOTE: In analogy to the [47msr[0m abbreviation for [47mshow-rewrites[0m, one might expect this command to be [47msl[0m; but that name was taken (``simplify with lemmas'') before [47msls[0m was implemented.") (split (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) split the current goal into cases Example: split For example, if the current goal has one hypothesis [47m(or x y)[0m and a conclusion of [47m(and a b)[0m, then [47msplit[0m will create four new goals: one with hypothesis X and conclusion A one with hypothesis X and conclusion B one with hypothesis Y and conclusion A one with hypothesis Y and conclusion B. General Form: SPLIT Replace the current goal by subgoals whose conjunction is equivalent (primarily by propositional reasoning) to the original goal, where each such goal cannot be similarly split. [31;1mRemark:[0m The new goals will all have their hypotheses promoted; in particular, no conclusion will have a top function symbol of [47mimplies[0m. Also note that [47msplit[0m will fail if there is exactly one new goal created and it is the same as the existing current goal. The way [47msplit[0m really works is to call the ACL2 theorem prover with only simplification (and preprocessing) turned on, and with only a few built-in functions (especially, propositional ones) enabled, namely, the ones in the list [47m(theory 'minimal-theory)[0m. However, because the prover is called, [type-reasoning] can be used to eliminate some cases. For example, if [47m(true-listp x)[0m is in the hypotheses, then probably [47m(true-listp (cdr x))[0m will be reduced to [47mt[0m.") (sr (proof-builder-commands proof-builder-commands-short-list) "(macro) same as SHOW-REWRITES Example: sr General Form: (sr &optional rule-id enabled-only-flg) See [ACL2-pc::show-rewrites].") (st (proof-builder-commands) "(macro) same as SHOW-TYPE-PRESCRIPTIONS Example: sr General Form: (st &optional rule-id) See [ACL2-pc::show-type-prescriptions].") (succeed (proof-builder-commands) "(macro) run the given instructions, and ``succeed'' Example: (succeed induct p prove) General Form: (succeed &rest instruction-list) Run the indicated instructions until there is a hard ``failure'', and ``succeed''. (See [ACL2-pc::sequence] for an explanation of ``success'' and ``failure''.)") (th (proof-builder-commands proof-builder-commands-short-list) "(macro) print the top-level hypotheses and the current subterm Examples: th -- print all (top-level) hypotheses and the current subterm (th (1 3) (2 4)) -- print hypotheses 1 and 3 and governors 2 and 4, and the current subterm (th (1 3) t) -- print hypotheses 1 and 3 and all governors, and the current subterm General Form: (th &optional hyps-indices govs-indices) Print hypotheses and the current subterm. The printing of hypotheses (and perhaps governors) are controlled as in the [47mhyps[0m command; see [ACL2-pc::hyps]. Historical note: The name [47mth[0m is adapted from the Gypsy Verification Environment, where [47mth[0m abbreviates the command [47mtheorem[0m, which says to print information on the current goal.") (then (proof-builder-commands) "(macro) apply one instruction to current goal and another to new subgoals Example: (then induct prove) General Form: (then first-instruction &optional completion must-succeed-flg) Run [47mfirst-instruction[0m, and then run [47mcompletion[0m (another instruction) on each subgoal created by [47mfirst-instruction[0m. If [47mmust-succeed-flg[0m is supplied and not [47mnil[0m, then halt at the first ``failure'' and remove the effects of the invocation of [47mcompletion[0m that ``failed''. The default for completion is [47mreduce[0m.") (top (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) move to the top of the goal Example and General Form: top For example, if the conclusion is [47m(= x (* (- y) z))[0m and the current subterm is [47my[0m, then after executing [47mtop[0m, the current subterm will be the same as the conclusion, i.e., [47m(= x (* (- y) z))[0m. [47mTop[0m is the same as [47m(up n)[0m, where [47mn[0m is the number of times one needs to execute [47mup[0m in order to get to the top of the conclusion. The [47mtop[0m command fails if one is already at the top of the conclusion. Also see [ACL2-pc::up], [ACL2-pc::dive], [ACL2-pc::nx], and [ACL2-pc::bk].") (type-alist (proof-builder-commands) "(macro) display the [type-alist] from the current context Examples: (type-alist nil t nil) ; display type-alist based on governors (default) type-alist ; same as (type-alist nil t) -- governors only (type-alist t t) ; display type-alist based on conclusion and governors (type-alist t t t) ; as above, but also display forward-chaining report type-alist ; same as (type-alist nil t) -- governors only (type-alist nil) ; same as (type-alist nil t) -- governors only (type-alist t) ; same as (type-alist t nil) -- conclusion only (type-alist nil nil) ; based on neither conclusion nor governors (type-alist nil t nil nil) ; same as type-alist (default) -- governors only (type-alist nil t nil :raw) ; governors only, raw alist format (type-alist nil t nil t) ; governors only, simple alist format General Form: (type-alist &optional concl-flg govs-flg fc-report-flg alistp) where if [47mgovs-flg[0m is omitted then it defaults to [47m(not concl-flg)[0m, and each of the other optional arguments defaults to [47mnil[0m. Display the current assumptions as a [type-alist]. Note that this display includes the result of forward chaining. When [47mfc-report-flg[0m is supplied a non-[47mnil[0m value, the display also includes a forward-chaining report; otherwise,the presence or absence of such a report is controlled by the usual global settings (see [forward-chaining-reports]). By default, the display is organized by type, with terms shown of each type; but when [47malistp[0m is [47m:raw[0m then the underlying type-alist structure is shown, which is made more user-friendly when any other non-[47mnil[0m value of [47malistp[0m is provided. There are two basic reasons contemplated for using this command. 1. The theorem prover has failed (either outside the interactive proof-builder or using a proof-builder command such as [47mbash[0m or [47mreduce[0m and you want to debug by getting an idea of what the prover knows about the context. a. You really are interested in the context for the current term. Include hypotheses and governors (i.e., accounting for tests of surrounding [47mif[0m-expressions that must be true or false) but not the current conclusion (which the theorem prover's heuristics would generally ignore for contextual information). Command: [47m(type-alist nil t)[0m ; equivalently, [47mtype-alist[0m or [47m(type-alist nil)[0m b. You are not thinking in particular about the current term; you just want to get an idea of the context that the prover would build at the top-level, for forward-chaining. Incorporate the conclusion but not the governors. Command: [47m(type-alist t nil)[0m ; equivalently, [47m(type-alist t)[0m 2. You intend to use one of the interactive [proof-builder-commands] that does simplification, such as [47ms[0m or [47mx[0m, and you want to see the context. Then include the surrounding [47mif[0m-term governors but not the goal's conclusion. Command: [47m(type-alist nil t)[0m ; equivalently, [47mtype-alist[0m or [47m(type-alist nil)[0m See [type-set] (also see [type-prescription]) for information about ACL2's type system, which can assist in understanding the output of the [47mtype-alist[0m command.") (undo (proof-builder-commands proof-builder-commands-short-list) "(meta) undo some instructions Examples: (undo 7) undo General Forms: (undo n) -- Undo the last n instructions. The argument n should be a positive integer. undo -- Same as (undo 1). [31;1mRemark:[0m To remove the effect of an [47mundo[0m command, use [47mrestore[0m; see [ACL2-pc::restore]. [31;1mRemark:[0m If the argument [47mn[0m is greater than the total number of interactive instructions in the current session, then [47m(undo n)[0m will simply take you back to the start of the session. The [47mundo[0m meta command always ``succeeds''; it returns [47m(mv nil t state)[0m unless its optional argument is supplied and of the wrong type (i.e. not a positive integer) or there are no instructions to undo.") (unsave (proof-builder-commands) "(macro) remove a proof-builder state Example: (unsave assoc-of-append) General Form: (unsave &optional name) Eliminates the association of an interactive proof-builder state with [47mname[0m, if [47mname[0m is supplied and not [47mnil[0m. The name may be [47mnil[0m or not supplied, in which case it defaults to the event name supplied with the original call to [47mverify[0m (if there is one --- otherwise, the instruction ``fails'' and there is no change). The ACL2 function [47munsave[0m may also be executed outside the interactive loop, with the same syntax. Also see [ACL2-pc::save] and [ACL2-pc::retrieve].") (up (proof-builder-commands proof-builder-commands-short-list) "(primitive) move to the parent (or some ancestor) of the current subterm Examples: if the conclusion is (= x (* (- y) z)) and the current subterm is y, then we have: up or (up 1) -- the current subterm becomes (- y) (up 2) -- the current subterm becomes (* (- y) z) (up 3) -- the current subterm becomes the entire conclusion (up 4) -- no change; can't go up that many levels General Form: (up &optional n) Move up [47mn[0m levels in the conclusion from the current subterm, where [47mn[0m is a positive integer. If [47mn[0m is not supplied or is [47mnil[0m, then move up one level, i.e., treat the instruction as [47m(up 1)[0m. Also see [ACL2-pc::dive], [ACL2-pc::top], [ACL2-pc::nx], and [ACL2-pc::bk].") (use (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) use a lemma instance Example: (USE true-listp-append (:instance assoc-of-append (x a) (y b) (z c))) -- Add two top-level hypotheses, one the lemma called true-listp-append, and the other an instance of the lemma called assoc-of-append by the substitution in which x is assigned a, y is assigned b, and z is assigned c. General Form: (use &rest args) Add the given lemma instances to the list of top-level hypotheses. See [hints] for the syntax of [47m:use[0m hints in [47mdefthm[0m, which is essentially the same as the syntax here (see the example above). This command calls the [47mprove[0m command, and hence should only be used at the top of the conclusion.") (wrap (proof-builder-commands) "(atomic macro) execute the indicated instructions and combine all the new goals Example: (wrap induct) ; induct, then replace first new goal by the conjunction of all ; the new goals, and drop all new goals after the first General Form: (wrap &rest instrs) First the instructions in [47minstrs[0m are executed, as in [47mdo-all[0m. If this ``fails'' then no additional action is taken. Otherwise, the current goal after execution of [47minstrs[0m is conjoined with all ``new'' goals, in the sense that their names are not among the names of goals at the time [47minstrs[0m was begun. This conjunction becomes the new current goal and those ``new'' goals are dropped. See the code for the interactive [proof-builder] command, [47mwrap-induct[0m, for an example of the use of [47mwrap[0m.") (wrap-induct (proof-builder-commands) "(atomic macro) same as induct, but create a single goal Examples: wrap-induct (wrap-induct t) (wrap-induct (append (reverse x) y)) General Form: (wrap-induct &optional term) The [47mwrap-induct[0m command is identical to the interactive [47m[proof-builder][0m's [47minduct[0m command (see [ACL2-pc::induct]), except that only a single goal is created: the conjunction of the base and induction steps. Note: The output will generally indicate that more than goal has been created, e.g.: Creating two new goals: (MAIN . 1) and (MAIN . 2). However, [47mwrap-induct[0m always creates a unique goal (when it succeeds). A subsequent message clarifies this, for example: NOTE: Created ONLY one new goal, which is the current goal: (MAIN . 1)") (wrap1 (proof-builder-commands) "(primitive) combine goals into a single goal Examples: ; Keep (main . 1) and (main . 2) if they exist, as well as the current goal; ; and for each other goal, conjoin it into the current goal and delete it: (wrap1 ((main . 1) (main . 2))) ; As explained below, conjoin all subsequent siblings of the current goal ; into the current goal, and then delete them: (wrap1) General Form: (wrap1 &optional kept-goal-names) If [47mkept-goal-names[0m is not [47mnil[0m, the current goal is replaced by conjoining it with all goals other than the current goal and those indicated by [47mkept-goal-names[0m, and those other goals are deleted. If [47mkept-goal-names[0m is omitted, then the current goal must be of the form [47m(name . n)[0m, and the goals to conjoin into the current goal (and delete) are those with names of the form [47m(name . k)[0m for [47mk[0m >= [47mn[0m. NOTE: [47mWrap1[0m always ``succeeds'', even if there are no other goals to conjoin into the current goal (a message is printed in that case), and it always leaves you with no hypotheses at the top of the current goal's conclusion (as though [47mtop[0m and [47mdemote[0m had been executed, if necessary). Also see [ACL2-pc::wrap].") (x (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) expand and (maybe) simplify function call at the current subterm Examples: x -- expand and simplify. Also see [ACL2-pc::expand] and see [ACL2-pc::x-dumb], which do not perform simplification. For example, if the current subterm is (append a b), then after [47mx[0m the current subterm will probably be (cons (car a) (append (cdr a) b)) if (consp a) is among the top-level hypotheses and governors. If there are no top-level hypotheses and governors, then after [47mx[0m the current subterm will probably be: (if (consp a) (cons (car a) (append (cdr a) b)) b). General Form: (X &key rewrite normalize backchain-limit in-theory hands-off expand) Expand the function call at the current subterm, and simplify using the same conventions as with the [47ms[0m command (see [ACL2-pc::s]). Unlike [47ms[0m, it is permitted to set both [47m:rewrite[0m and [47m:normalize[0m to [47mnil[0m, which will result in no simplification; see [ACL2-pc::x-dumb]. [31;1mRemark[0m (obscure): On rare occasions the current address may be affected by the use of [47mx[0m. For example, suppose we have the definition (defun g (x) (if (consp x) x 3)) and then we enter the interactive proof-builder with (verify (if (integerp x) (equal (g x) 3) t)) . Then after invoking the instruction [47m(dive 2 1)[0m, so that the current subterm is [47m(g x)[0m, followed by the instruction [47mx[0m, we would expect the conclusion to be [47m(if (integerp x) (equal 3 3) t)[0m. However, the system actually replaces [47m(equal 3 3)[0m with [47mt[0m (because we use the ACL2 term-forming primitives), and hence the conclusion is actually [47m(if (integerp x) t t)[0m. Therefore, the current address is put at [47m(2)[0m rather than [47m(2 1)[0m. In such cases, a warning ``[47mNOTE[0m'' will be printed to the terminal. The other primitive commands to which the above ``truncation'' note applies are [47mequiv[0m, [47mrewrite[0m, and [47ms[0m.") (x-dumb (proof-builder-commands proof-builder-commands-short-list) "(atomic macro) expand function call at the current subterm, without simplifying General Form: x-dumb: expand without simplification. Same as [47m(expand t)[0m. See [ACL2-pc::expand]. Also see [ACL2-pc::x], which performs simplification.") (bevier87 (operational-semantics-3__annotated-bibliography) "W. R. Bevier, [3mVerified Operating System Kernel[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/bevier.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1987. [31;1mRelevance:[0m first verified operating system and a component of the CLI stack --------- The verified operating system kernel used in the CLI Verified Stack as reported in [bib::bhmy89] is described here. See the Nqthm script [47mexamples/bevier/kit.events[0m.") (bgm90 (operational-semantics-3__annotated-bibliography) "R. S. Boyer, M. W. Green, and J S. Moore, ``{The Use of a Formal Simulator to Verify a Simple Real Time Control Program | http://www.cs.utexas.edu/users/moore/publications/controller.pdf}'', in W.H.J. Feijen, A.J.M. van Gasteren, D. Gries, and J. Misra, editors, [3mBeauty is Our Business: A Birthday Salute to Edsger W. Dijkstra[0m, Springer-Verlag Texts and Monographs in Computer Science, pp. 54-66, 1990. [31;1mRelevance:[0m operational semantics modeling a hybrid physical/digital system --------- Abstract We present an initial and elementary investigation of the formal specification and mechanical verification of programs that interact with environments. We describe a formal, mechanically produced proof that a simple real time control program keeps a vehicle on a straightline course in a variable crosswind. To formalize the specification we define a mathematical function which models the interaction of the program and its environment. We then state and prove two theorems about this function: the simulated vehicle never gets farther than three units away from the intended course and homes to the course if the wind remains steady for at least four sampling intervals. --------- It is easiest to think of the problem as a one-dimensional control problem, e.g., a thermostat or speed control. But the problem was posed as follows. Consider the task of steering a vehicle along the x-axis with a crosswind along the y-axis. The wind speed varies. The vehicle carries a sensor that indicates whether the vehicle is above, on, or below the x-axis. The vehicle also has actuators that can adjust the sideways velocity of vehicle by a fixed amount. Write, specify, and verify a control program that never allows the vehicle to drift too far from the x-axis and homes to the x-axis when the wind stays steady sufficiently long. This can be modeled as a ``clocked'' state machine, except the clock is a sequence of changes in wind velocity. The ``physics'' is modeled extremely simply because the prover only supported natural numbers; but anybody who has ever written a simulator of a physical system will recognize it. The proof involved defining and verifying an invariant on the state, under the assumption that the wind changed sufficiently smoothly. The work was done at SRI, probably between 1979 and 1980. It was submitted for publication at that time but rejected because its formal approach to real-time control was too unconventional. The reviewers overlooked the fact that this approach accommodated a hybrid system, where the control program was digital but the ``simulator'' was describing the physical world. It was eventually published about a decade after the work was done, when the authors were invited to submit a paper to a volume in honor of Edsger Dijkstra. See the Nqthm script [47mexamples/basic/controller.events[0m.") (bh97 (operational-semantics-3__annotated-bibliography) "B. Brock and W. A. Hunt, Jr., ``{Formally Specifying and Mechanically Verifying Programs for the Motorola Complex Arithmetic Processor DSP | https://ieeexplore.ieee.org/document/628846}'', in [3m1997 IEEE International Conference on Computer Design[0m, IEEE Computer Society, pp. 31-36, October, 1997. [31;1mRelevance:[0m first public announcement of the CAP DSP formalization (this short article was superseded by [bib::bh99]) --------- Abstract We describe our formal specification of Motorola's Complex Arithmetic Processor (CAP) DSP and our subsequent use of this specification to verify the correctness of several DSP algorithms. We wrote the specification in the ACL2 logic and carried out the mechanical proofs using the ACL2 theorem-proving system. Motorola's CAP is a super-scalar, pipelined DSP with seven memories and more than 20 functional units. Our formal specification is bit-for-bit exact, and was created by hand translating Motorola's drawings for the CAP. We believe that the specification developed is the largest of its kind, as this is the only formal specification of which we are aware for a complete commercial design. Proving the correctness of the DSP algorithms (programs) required proving the correctness of programs with 317-bit instructions and a non-interlocking execution pipeline. This Motorola DSP has a 1.8 million transistor implementation. This project involved both CLI and Motorola personnel and represents more than eight man-years of effort. --------- See the discussion of the CAP DSP project in [operational-semantics-2__other-examples].") (bh99 (operational-semantics-3__annotated-bibliography) "B. Brock and W. A. Hunt, Jr., ``{Formal Analysis of the Motorola CAP DSP'' | https://link.springer.com/chapter/10.1007/978-1-4471-0523-7_5#citeas}, in M. Hinchey and J. Bowen, editors, [3mIndustrial-Strength Formal Methods[0m, Springer-Verlag, pp. 81-115, 1999. [31;1mRelevance:[0m first industrial application of operational semantics with ACL2 and the first complete formal specification of a commercially designed microprocessor --------- Abstract We describe our formal specification of Motorola's Complex Arithmetic Processor (CAP) Digital Signal Processor (DSP) and our subsequent use of this specification in formal analyses of the CAP hardware and software. The CAP was designed by Motorola Government Systems and Technology Group (Scottsdale, Arizona), which, as a part of their business, builds and sells purpose-built products. The CAP is an ASIC that was designed to efficiently implement a number of signal processing algorithms required in digital communications. Motorola's CAP is a super-scalar, pipelined DSP with seven memories and more than 20 functional units. Motorola's specification for the CAP was captured using the Cadence Signal Processing (SPW) (Cadence, 1994) toolsuite; the design is represented as a series of drawings that specify register files, data manipulation units, and interconnecting busses. We have completely specified the CAP (Gilfeather et al, 1994) using the formal logic ACL2 (Kaufmann and Moore, 1996). Our specification is executable and can be used as a simulator as well as a basis for proving the correctness of the CAP hardware design and CAP programs. We believe our specification is bit-for-bit exact with respect to the SPW specification produced by Motorola, and was created by hand translating Motorola's SPW drawings for the CAP. We have used our CAP specification to analyse the CAP instruction pipeline and various CAP algorithms. We believe that the specification developed is the largest of its kind, as this is the only formal specification of which we are aware for a complete commercial design. We believe that the use of mathematical logic for modeling and reasoning about hardware designs such as we have demonstrated here can provide assurance of circuit design correctness well beyond what is available from current CAD techniques. --------- See the discussion of the CAP DSP project in [operational-semantics-2__other-examples].") (bhmy89 (operational-semantics-3__annotated-bibliography) "W.R. Bevier, W.A. Hunt, Jr., J S. Moore, and W.D. Young, [3mSpecial Issue on System Verification[0m, [3mJournal of Automated Reasoning[0m, [31;1m5[0m(4), pp. 409-530, 1989. [31;1mRelevance:[0m Computational Logic Inc. (CLI) Verified Stack --- a seminal achievement in formal methods and operational semantics --------- The Computational Logic, Inc (CLI) Verified Stack was reported in this Special Issue of the JAR. The CLI stack was composed of four verified components: a gate-level design for a microprocessor (by Warren Hunt), an assembler/linker/loader that provided an execute-only, stack-based instruction set with subroutine call and return (Moore), a compiler for a small subset of a programming language related to Pascal (Bill Young, see [bib::young88]), and a simple operating system kernel (Bill Bevier; see [bib::bevier87]). All components were verified with Nqthm, so that a high-level program could be compiled, assembled, linked, loaded, and run on the gate-level machine with mathematical certainty that it behaved as specified by the semantics of the high-level programming language. All the models just mentioned involved [operational-semantics] and proofs in the style described in here. Indeed, this project basically convinced the community that this style of semantics was practical for both execution and verification of models. The verification of the relations between each component --- gates to machine code, machine code to assembly language, assembly language to high level language, operating system to assembly language --- must be considered a ``first'' for relating practical machines of each kind. To the best of our knowledge, no one had ever verified a gate-level implementation of an ISA for a practical microprocessor before Hunt's 1985 work [bib::hunt85]. With the same caveat, no one had ever verified an assembler/linker/loader before Moore's 1988 Piton work (see [bib::moore96] for a history) or verified an operating system kernel for a practical machine before Bevier's 1987 work. And while McCarthy and Painter verified (by a traditional ``hand proof'') an expression compiler, which various formal methods researchers tackled in the 1970s (including Boyer and Moore in 1979 [bib::bm79], where a history of the challenge is sketched), both the high- and low- level machines involved in that earlier ``compiler'' work were trivial compared to what Young dealt with in 1988. The messy reality of each component was fundamentally due to the requirement that each layer, starting at the gates, provide sufficient functionality to implement the higher layers. In 1989, the ``hardware'' at the bottom of the CLI stack was a gate-level description of a machine called FM8502. The FM8502 was a 32-bit version of Hunt's earlier 16-bit FM8501; see [bib::hunt85]. Hunt designed and verified FM8502 to make Moore's job of writing an assembler a little easier. Moore, with Matt Kaufmann's help with some proofs, verified that the FM8502 code produced by the assembler/linker/loader implemented the semantics of the Piton assembly language. But the FM8502 could not be fabricated because its gate-level description was not compatible with commercial fabrication tools, e.g., there was unrealistic fan-out. But the 1989 CLI Verified Stack demonstrated that it was practical to prove that a gate-level design implemented a given instruction set architecture (ISA) and that the operational semantic approach allowed the mechanized proofs of formal relations between different abstraction hierarchies. In 1991, Hunt and Bishop Brock designed a formal hardware description language (HDL) and used it to describe the FM9001 microprocessor which they then verified to implement its ISA; see [bib::hb92]. The FM9001 was fabricated. In 1991, Moore retargeted the code-generators in the 1989 assembler/linker/loader and re-verified that part of the stack, making it possible to port the rest of the verified stack to a fabricated, running machine; see [bib::moore96]. In 1992, two other interesting projects related to Piton and FM9001 were completed. Art Flatau completed the implementation and Nqthm verification of a second compiler, one that compiled a small subset of the Nqthm functional programming language into Piton (see [bib::flatau92]). At about the same time, Matt Wilding completed the implementation and verification of several real-time control programs in Piton and verified their functional correctness and resource bounds (instruction counts and stack sizes). See [bib::wilding92] and [bib::wilding93]. One of the programs carried out a winning strategy for the game of Nim (if one exists from the given Nim starting state). Wilding wrote ([bib::wilding93], page 278) ``An FM9001 was fabricated and runs a compiled version of the Nim program. The fabricated FM9001 microprocessor, the Piton compiler, and the Nim program were never tested in a conventional manner during development or after completion. Even so, each worked the first time and we would have been surprised if any had not.''") (bkm96 (operational-semantics-3__annotated-bibliography) "B. Brock, M. Kaufmann, and J S. Moore, ``{ACL2 Theorems about Commercial Microprocessors | http://www.cs.utexas.edu/users/moore/publications/bkm96.pdf}'', in M. Srivas and A. Camilleri, editors, [3mFormal Methods in Computer-Aided Design (FMCAD'96)[0m, Springer-Verlag, LNCS [31;1m1166[0m, pp. 275-293, doi 10.1007/BFb0031816, 1996. [31;1mRelevance:[0m early (mid-1990s) applications of ACL2 in industry (Motorola CAP DSP via operational semantics and the AMD K5 FDIV via a shallow embedding) --------- Abstract ACL2 is a mechanized mathematical logic intended for use in specifying and proving properties of computing machines. In two independent projects, industrial engineers have collaborated with researchers at Computational Logic, Inc. (CLI), to use ACL2 to model and prove properties of state-of-the-art commercial microprocessors prior to fabrication. In the first project, Motorola Inc., and CLI collaborated to specify Motorola's complex arithmetic processor (CAP), a single-chip, digital signal processor (DSP) optimized for communications signal processing. Using the specifications, we proved the correctness of several CAP microcode programs. The second industrial collaboration involving ACL2 was between Advanced Micro Devices, Inc. (AMD) and CLI. In this work we proved the correctness of the kernel of the floating-point division operation on AMD's first Pentium-class microprocessor, the AMD5K86. In this paper, we discuss ACL2 and these industrial applications, with particular attention to the microcode verification work. --------- This paper contains a good sketch of the Motorola CAP digital signal processor project, from capturing the design as an ACL2 operational model to proving microcode correct with respect to the model. The paper also includes a timeline describing how long different phases of the project took. The paper also discusses the first use of ACL2, in 1995, to deal with floating-point arithmetic: verifying microcode for floating-point division on AMD's first Pentium-class microprocessor, the AMD5k86. However, the formalization of the division microcode was not via operational semantics but rather a ``shallow embedding'' of the microcode into ACL2. So while both the CAP project and floating-point project are of great relevance to the use of formal methods in industry, we have stressed the CAP work in this doc topic on operational semantics. For a technical description of the division proof, see J S. Moore, T. Lynch, and M. Kaufmann, ``{A Mechanically Checked Proof of the Correctness of the Kernel of the AMD5k86 Floating-Point Division Program | https://www.cs.utexas.edu/~moore/publications/divide_paper.pdf}'', [3mIEEE Transactions on Computers[0m, [31;1m47[0m(9), pp. 913-926, Sep., 1998.") (bm05 (operational-semantics-3__annotated-bibliography) "B. Brock and J S. Moore, ``{A Mechanically Checked Proof of a Comparator Sort Algorithm | https://www.cs.utexas.edu/~moore/publications/csort/main.pdf}'', in M. Broy, J. Gruenbauer, D. Harel, and C. A. R. Hoare, editors, [3mEngineering Theories of Software Intensive Systems[0m, Springer NATO Science Series II, [31;1m195[0m, pp. 141-175, 2005. [31;1mRelevance:[0m an example of proving that the state transformation effected by running a CAP model on commercial microcode implements the high level specification --------- Abstract We describe a mechanically checked correctness proof for the comparator sort algorithm underlying a microcode program in a commercially designed digital signal processing chip. The abstract algorithm uses an unlimited number of systolic comparator modules to sort a stream of data. In addition to proving that the algorithm produces an ordered permutation of its input, we prove two theorems that are important to verifying the microcode implementation. These theorems describe how positive and negative ``infinities'' can be streamed into the array of comparators to achieve certain effects. Interesting generalizations are necessary in order to prove these theorems inductively. The mechanical proofs were carried out with the ACL2 theorem prover. We find these proofs both mathematically interesting and illustrative of the kind of mathematics that must be done to verify software. --------- For the 1997 ACL2 proof script see [47mbooks/misc/csort.lisp[0m. The long delay between when the work was done (1997) and when it was published (2005) is due both to the understandable sensitivity of companies to permit publication of anything that might reveal proprietary intellectual property, combined with the rarity of suitable venues to describe exceedingly practical formal methods applications. (Despite this phenomenon, working closely with industry is the only way to build tools that meet their needs.) See the discussion of the CAP DSP project in [operational-semantics-2__other-examples].") (bm73 (operational-semantics-3__annotated-bibliography) "R. S. Boyer and J S. Moore, ``{Proving Theorems about LISP Functions | https://www.cs.utexas.edu/~moore/publications/bm-ijcai-73.pdf}'', in [3mProceedings of the Third International Joint Conference on Artificial Intelligence (IJCAI)[0m, Stanford University, pp. 486-493, 1973. [31;1mRelevance:[0m journal article about the Edinburgh Pure Lisp Theorem Prover (PLTP) --------- For a longer, journal version of this paper see R. S. Boyer and J S. Moore, ``{Proving Theorems about LISP Functions | https://www.cs.utexas.edu/~moore/publications/bm75.pdf}'', [3mJournal of the ACM[0m, [31;1m22[0m(1), pp. 129-144, 1975. The IJCAI'73 paper was the first widely accessible description of the Edinburgh Pure Lisp Theorem Prover (PLTP). The key ideas in the theorem prover were the use of Lisp as a logic, the reliance on recursive function definitions, extensive use of rewriting and symbolic evaluation, and an induction heuristic based on the failure of symbolic evaluation. The system was fully automatic; there were no provisions for user supplied lemmas or hints. The ``proveall'' (regression suite) included such theorems as associativity of [47mappend[0m, [47mreverse-reverse[0m, and the correctness of insertion sort. The paper was hailed as a landmark in theorem proving because these theorems had never been proved automatically before. But early critics said that proving theorems about pure Lisp was irrelevant because serious applications were not written in pure Lisp. However, Boyer and Moore argued that Lisp was a logic with features necessary to the specification and proof of program properties, namely recursive definitions and mathematical induction. {The PLTP Archive | https://www.cs.utexas.edu/~moore/best-ideas/pltp/index.html} contains a wealth of information about PLTP and its 1973 implementation in POP-2, including the POP-2 Reference Manual, scanned OCR listings of the PLTP source code, listings of proof output, and modern reconstructions of PLTP in OCaml (by Grant Passmore) and ACL2 (by J Moore).") (bm79 (operational-semantics-3__annotated-bibliography) "R. S. Boyer and J S. Moore, [3m{A Computational Logic | https://archive.org/details/acl_20240626}[0m, Academic Press, 1979. [31;1mRelevance:[0m implementation details of the prover that became Nqthm --------- This book described the ``Boyer-Moore theorem prover'' as it stood in 1979, when the prover was locally known as ``Thm.'' Unlike the Edinburgh Pure Lisp Theorem Prover (PLTP), Thm supported datatypes other than pairs, well-founded ordinals, a conservative definitional principle, and named previously proved lemmas stored as rules. Unlike the later Nqthm, Thm did not support [47mquote[0m-notation and so represented logical constants inefficiently. Thm also lacked the linear-arithmetic decision procedure, and lacked user-supplied hints. Of course, there were also many heuristic changes along the way from PLTP to Nqthm. One outstanding feature of [3mA Computational Logic[0m was noted by Boyer and Moore in the Preface to the First Edition of [bib::bm97] ``we know of three independent successful efforts to construct the theorem prover from the book.'' If you want to a good idea of how Nqthm and ACL2 ``work,'' read this book!") (bm80 (operational-semantics-3__annotated-bibliography) "R. S. Boyer and J S. Moore, ``{On Why It Is Impossible to Prove that the BDX930 Dispatcher Implements a Time-Sharing System | https://www.cs.utexas.edu/~moore/publications/BDX930-Report-1978-81.pdf}'', in Sections 14 and 15 of P.M. Melliar-Smith, K. Levitt, R. Schwartz, R. Boyer, J Moore, D. Hare, R. Shostak, M. Moriconi, M. Green, and W.D. Elliot, [3mInvestigation, Development, and Evaluation of Performance Proving for Fault-Tolerant Computer Final Report, covering the period September 1978 to June 1982[0m, SRI, July 1982. [31;1mRelevance:[0m operational semantic model of (a fragment) of a 1970s flight control computer --------- Boyer and Moore's formalization of a subset of the instruction set of the Bendix BDX930 flight control computer is reported in this document. The document is part of the Final Report for the Software Implemented Fault Tolerance (SIFT) project of SRI, sponsored by the National Aeronautics and Space Administration, Langley Research Center, Hampton, Va 23665. Section 14 explains why it was impossible to verify that the code for the SIFT dispatcher implemented a time-sharing system; Section 15 contains the 30 page listing of the operational semantics for the BDX930 fragment in question, written in the logic of Thm/Nqthm. The two sections do not contain dates. The whole report covers the period 1978 through 1982. Boyer and Moore left SRI in 1981. The BDX930 work was probably done in 1979 or 1980 as it was influential in the evolution of Thm to Nqthm, as noted in [operational-semantics-5__history-etc].") (bm96 (operational-semantics-3__annotated-bibliography) "R. S. Boyer and J S. Moore, ``{Mechanized Formal Reasoning about Programs and Computing Machines | https://www.cs.utexas.edu/~moore/publications/bm96.pdf}'', in R. Veroff, editor, [3mAutomated Reasoning and Its Applications: Essays in Honor of Larry Wos[0m, MIT Press, 1966. [31;1mRelevance:[0m the basic Nqthm/ACL2 style of operational semantics as a book chapter --------- Abstract The design of a new processor often requires the invention and use of a new machine-level programming language, especially when the processor is meant to serve some special purpose. It is possible to specify formally the semantics of such a programming language so that one obtains a simulator for the new language from the formal semantics. Furthermore, it is possible to configure some mechanical theorem provers so that they can be used directly to reason about the behavior of programs in the new language, permitting the expeditious formal modeling of the new design as well as experimentation with and mechanically checked proofs about new programs. We here study a very simple machine-level language to illustrate how such modeling, experimentation, and reasoning may be done using the ACL2 automated reasoning system. Of particular importance is how we control the reasoning system so that it can deal with the complexity of the machine being modeled. The methodology we describe has been used on industrial problems and has been shown to scale to the complexity of state-of-the-art processors. --------- This paper describes the basic methodology used to model and reason about machines with ACL2: states as objects, a step function, a run function, clock functions for programs, lemmas to control expansion, and the basic methodology for specifying and verifying programs. The vehicle for this explanation here is a machine almost identical to M1 and this paper covers essentially the same ground as the documentation topic [operational-semantics-1__simple-example]. Referring to the work described in [operational-semantics-5__history-etc] and early ACL2 work, the paper says The approach we describe is essentially that used in the Nqthm and ACL2 projects described above. Furthermore, the Nqthm and ACL2 users above were taught this method of formalization via examples very similar to this one, primarily in our graduate class, [3mRecursion and Induction[0m, at the University of Texas at Austin. That this technique scales up to languages that are many orders of magnitude more complicated than this one is demonstrated by [5, 9]. Therefore, simplicity [3mhere[0m should be looked upon as a virtue. While the paper does not name the machine being formalized, it was in fact called [47msmall-machine[0m rather than [47mm1[0m and it goes all the way back to Nqthm. Indeed, among the students who learned this methodology in [3mRecursion and Induction[0m in the early 1980s were Bevier, Hunt, Young, Flatau, and Wilding --- all principals in the CLI Verified Stack work [bib::bhmy89]. See the 1991 Nqthm script [47mexamples/basic/small-machine.events[0m, which demonstrates that most of the methodology described here was developed before ACL2. Coincidentally, it also shows that what we're calling [47mm1[0m today --- informally described as a ``toy'' Java Virtual Machine --- predates the Java and the JVM. The ACL2 version of the [47msmall-machine[0m proof script may be found in the ACL2 book at [47mhttps://www.cs.utexas.edu/~moore/publications/small-machine.lisp[0m. By the way, notes for [3mRecursion and Induction[0m have been incorporated into ACL2's documentation. See [recursion-and-induction]. But when the course was taught by Boyer and Moore in the 1980s the notes were essentially just a list of conjectures to prove or disprove and the class was rather free-form in the sense that student participation was critical and often determined the kinds of problems posed in the latter part of the semester. Operational semantics is not mentioned in the recursion-and-induction documentation.") (bm97 (operational-semantics-3__annotated-bibliography) "R. S. Boyer and J S. Moore, [3m{ A Computational Logic Handbook, Second Edition | https://drive.google.com/file/d/0B2yFYLn0Spf1TloxMjNxdzBWN1E/}[0m, Academic Press, New York, 1997. [31;1mRelevance:[0m Nqthm user's manual --------- This book is the ``final'' user's manual for Nqthm. It was written about 8 years after the ACL2 project was started, by which time ACL2 had gained a sizeable user community despite the fact that Nqthm was still being used by some students and industrial researchers.") (boh03 (operational-semantics-3__annotated-bibliography) "R. E. Bryant and D. R. O'Hallaron, [3mComputer Systems: A Programmer's Perspective[0m, Prentice-Hall. First edition 2003, second edition 2011, third edition 2015. [31;1mRelevance:[0mone of the most popular and influential textbooks on modern computer systems; its relevance here is that the book introduced the y86. --------- Abstract For Computer Systems, Computer Organization and Architecture courses in CS, EE, and ECE departments. Few students studying computer science or computer engineering will ever have the opportunity to build a computer system. On the other hand, most students will be required to use and program computers on a near daily basis. [3mComputer Systems: A Programmer's Perspective[0m introduces the important and enduring concepts that underlie computer systems by showing how these ideas affect the correctness, performance, and utility of application programs. The text's hands-on approach (including a comprehensive set of labs) helps students understand the under-the-hood operation of a modern computer system and prepares them for future courses in systems topics such as compilers, computer architecture, operating systems, and networking. --------- The y86 introduced in this textbook is can be thought of as a ``toy'' x86 and is an excellent starting point for the formalization of that larger machine. The y86 has been modeled in ACL2, by Warren A. Hunt, Jr., and M. Kaufmann, and some programs proved correct with it. In particular, the ACL2 book [47m/books/models/y86/y86-basic/y86/y86.lisp[0m is a faithful operational semantic model of the 36-bit y86 described in the first edition of the Bryant-O'Hallaron book.") (by96 (operational-semantics-3__annotated-bibliography) "R. S. Boyer and Y. Yu, ``{Automated Proofs of Object Code for a Widely Used Microprocessor | https://dl.acm.org/doi/10.1145/227595.227603}'', [3mJournal of the ACM[0m [31;1m43[0m(1), pp. 166-192, January, 1996. [31;1mRelevance:[0m operational model of the Motorola 68020 and verification of object code generated by commercial compilers --------- Abstract We have formally described a substantial subset of the MC68020, a widely used microprocessor built by Motorola, within the mathematical logic of the automated reasoning system Nqthm, a.k.a. the Boyer-Moore Theorem Prover. Using this formal description, we have mechanically checked the correctness of MC68020 object code programs for for binary search, Hoare's Quick Sort, twenty-one functions from the Berkeley Unix C string library, and other well-known algorithms. The object code for these examples was generated using the Gnu C, the Verdix Ada, and the AKCL common Lisp compilers. We have mechanized a mathematical theory to facilitate automated reasoning about object code programs. We describe a two-stage methodology we use to do our proofs. --------- See also the Nqthm scripts [47mexamples/yu/[0m where you will find the definition of the MC68020 model and the proofs of the programs mentioned.") (flatau92 (operational-semantics-3__annotated-bibliography) "A. D. Flatau [3mA verified implementation of an applicative language with dynamic storage allocation[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/flatau.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1992 (minus some appendices). [31;1mRelevance:[0m a second verified compiler hosted on the CLI Verified Stack --------- Abstract A compiler for a subset of the Nqthm logic and a mechanically checked proof of its correctness is described. The Nqthm logic defines an applicative programming language very similar to McCarthy's pure Lisp [20]. The compiler compiles programs in the Nqthm logic into the Piton assembly level language [23]. The correctness of the compiler is proven by showing that the result of executing the Piton code is the same as produced by the Nqthm interpreter [47mV&C$[0m. The Nqthm logic defines several different abstract data types, or shells, as they are called in Nqthm. The user can also define additional shells. The definition of a shell includes the definition of a constructor function that returns new objects with the type of that shell. These objects can become garbage, so the run-time system of the compiler includes a garbage collector. The proof of the correctness of the compiler has not been entirely mechanically checked. A plan for completing the proof is described. --------- The version of the compiler presented in the dissertation included code for creating new shells and a garbage collector. But these features of the compiler were not fully verified at the time the dissertation was defended. An earlier version of the compiler dealt only with the Nqthm primitives [47mCAR[0m, [47mCDR[0m, [47mCONS[0m, [47mFALSE[0m, [47mLISTP[0m, [47mNLISTP[0m, [47mTRUE[0m, [47mTRUEP[0m, and [47mIF[0m, as well as recursive functions. The run-time of that simpler system included dynamic storage allocation (to allocate conses in Piton's array space). But it did not include a garbage collector. It was that simpler implementation that was mechanically verified. The completion of the proofs of the full system was never completed. The Nqthm events for this work may be found in the [47m*.events[0m files of [47mexamples/flatau/[0m.") (ghk13 (operational-semantics-3__annotated-bibliography) "S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Abstract Stobjs and Their Application to ISA Modeling | http://eptcs.org/content.cgi?ACL22013}'', in R. Gamboa and J. Davis, editors, [3mProceedings of ACL2 Workshop 2013[0m, Electronic Proceedings in Theoretical Computer Science, Volume 114, pp. 54-69, 2013. [31;1mRelevance:[0m an ACL2 feature introduced to support operational semantic models --------- Abstract We introduce a new ACL2 feature, the abstract stobj, and show how to apply it to modeling the instruction set architecture of a microprocessor. Benefits of abstract stobjs over traditional (``concrete'') stobjs can include faster execution, support for symbolic simulation, more efficient reasoning, and resilience of proof developments under modeling optimization. --------- Aside from the specific advantages abstract stobjs (see [47m[defabsstobj][0m) confer on ACL2 state machines, this papers illustrates how attention to operational semantics has influenced the development of ACL2.") (ghk17 (operational-semantics-3__annotated-bibliography) "S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Engineering a Formal, Executable x86 ISA Simulator for Software Verification | https://link.springer.com/chapter/10.1007/978-3-319-48628-4_8}'', in M. Hinchey, J. P. Bowen, and E.-R. Olderog, editors, [3mProvably Correct Systems[0m Springer, pp. 173-209, 2017. [31;1mRelevance:[0m operational model of the x86 at both the user- and system-level and code proofs --------- Abstract Construction of a formal model of a computing system is a necessary practice in formal verification. The results of formal analysis can only be valued to the same degree as the model itself. Model development is error-prone, not only due to the complexity of the system being modeled, but also because it involves addressing disparate requirements. For example, a formal model should be defined using simple constructs to enable efficient reasoning but it should also be optimized to offer fast concrete simulations. Models of large computing systems are themselves large software systems and must be subject to rigorous validation. We describe our formal, executable model of the x86 instruction-set architecture; we use our model to reason about x86 machine-code programs. Validation of our x86 ISA model is done by co-simulating it regularly against a physical x86 machine. We present design decisions made during model development to optimize both validation and verification, i.e., efficiency of both simulation and reasoning. Our engineering process provides insight into the development of a software verification and model animation framework from the points of view of accuracy, efficiency, scalability, maintainability, and usability. --------- See the collection of ACL2 books and files at [47mbooks/projects/x86isa/[0m. Also relevant are [bib::goel16] and the following earlier papers [bib::hk12], [bib::ghk13],and [bib::ghkg14].") (ghkg14 (operational-semantics-3__annotated-bibliography) "S. Goel, W. A. Hunt, Jr., M. Kaufmann, and S. Ghosh, ``{Simulation and Formal Verification of x86 Machine-Code Programs that Make System Calls | http://www.cs.utexas.edu/users/hunt/FMCAD/FMCAD14/proceedings/18_goel.pdf}'', in [3mProceedings of Formal Methods in Computer-Aided Design (FMCAD'14)[0m, pp. 91-98, 2014. [31;1mRelevance:[0m modeling and verifying machine-code programs that exhibit non-determinism --------- Abstract We present an approach to modeling and verifying machine-code programs that exhibit non-determinism. Specifically, we add support for system calls to our formal, executable model of the user-level x86 instruction-set architecture (ISA). The resulting model, implemented in the ACL2 theorem-proving system, allows both formal analysis and efficient simulation of x86 machine-code programs; the logical mode characterizes an external environment to support reasoning about programs that interact with an operating system, and the execution mode directly queries the underlying operating system to support simulation. The execution mode of our x86 model is validated against both its logical mode and the real machine, providing test-based assurance that our model faithfully represents the semantics of an actual x86 processor. Our framework is the first that enables mechanical proofs of functional correctness of user-level x86 machine-code programs that make system calls. We demonstrate the capabilities of our model with the mechanical verification of a machine-code program, produced by the GCC compiler, that computes the number of characters, lines, and words in an input stream. Such reasoning is facilitated by our libraries of ACL2 lemmas that allow automated proofs of a program's memory-related properties.") (goel16 (operational-semantics-3__annotated-bibliography) "S. Goel, [3m{Formal Verification of Application and System Programs Based on a Validated x86 ISA Model | https://repositories.lib.utexas.edu/server/api/core/bitstreams/858b2f9b-5532-4b2a-bed1-fb889a265f6c/content}[0m, University of Texas at Austin, Ph.D. dissertation, 2016. [31;1mRelevance:[0m details of the x86 model --------- Goel writes on page viii of the dissertation This dissertation demonstrates that formal verification of complex program properties can be made practical, without any loss of accuracy or expressiveness, by employing a machine-code analysis framework implemented using a mechanical theorem prover. To this end, we constructed a formal and executable model of the x86 Instruction-Set Architecture using the ACL2 theorem-proving system. This model includes a specification of 400+ x86 opcodes and architectural features like segmentation and paging. The model's high execution speed allows it to be validated routinely by performing co-simulations against a physical x86 processor --- thus, formal analysis based on this model is reliable. We also developed a general framework for x86 machine-code analysis that can lower the overhead associated with the verification of a broad range of program properties, including correctness with respect to behavior, security, and resource requirements. We illustrate the capabilities of our framework by describing the verification of two application programs, population count and word count, and one system program, zero copy. --------- Because of the concern for validating the ACL2 x86 model against x86 hardware by various manufacturers it was important the ACL2 x86 execute efficiently. When running in the application-level mode the ACL2 model executes at about 3.3 million x86 instructions per second (ips); in the system-level mode it executes at about 912,000 ips. See the collection ACL2 books and files at [47mbooks/projects/x86isa/[0m.") (hb92 (operational-semantics-3__annotated-bibliography) "W. A. Hunt, Jr. and B. Brock, ``{A Formal HDL and its use in the FM9001 Verification | https://royalsocietypublishing.org/doi/abs/10.1098/rsta.1992.0024}'', [3mProceedings of the Royal Society[0m, North Holland, April, 1992. [31;1mRelevance:[0m a formalized hardware description language and the verification of a fabricated microprocessor described with it; this describes three foundational achievements in formal methods --------- Abstract A synchronous, hierarchical, occurrence-oriented, hardware description language (HDL) has been formalized with the Boyer-Moore logic. Well-formed HDL circuits are recognized by a predicate, and a unit-clock simulator defines the meaning of circuits expressed in the HDL. This HDL has been used to specify an implementation of the FM9001 microprocessor that has been mechanically proved to implement the FM9001 instruction-level specification. All proofs were mechanically checked using the Boyer-Moore theorem-proving system. The formalization of the HDL, the FM9001 user-level specification, and the FM9001 HDL implementation architecture specification required more than 700 function definitions. The mechanical proof is composed of thousands of theorem prover proof requests and millions of theorem prover inference steps. --------- The verified fabricated microprocessor described here was used in the final hosting of the CLI Verified Stack [bib::bhmy89]. But aside from its importance to the Verified Stack, this paper describes three foundational achievements in formal methods: * the first formal definition of a hardware description language (HDL), * the first complete proof of a microprocessor design -- including its embedded test logic -- with respect to its high-level ISA specification, and * the first (and still, only) verified microprocessor that was manufactured and demonstrated to function properly. For complete details, see the Nqthm script [47mexamples/fm9001-piton/fm9001/fm9001-replay.events[0m.") (hk12 (operational-semantics-3__annotated-bibliography) "W. A. Hunt, Jr. and M. Kaufmann, ``{Towards a Formal Model of the x86 ISA | http://apps.cs.utexas.edu/tech_reports/reports/tr/TR-2075.pdf}'', University of Texas at Austin, Computer Science Department Technical Report TR-12-07, May, 2012. [31;1mRelevance:[0m a ``toy model'' of the x86, built as a warm up exercise --------- Abstract We present a preliminary formalization of a subset of the x86 instruction set. Our model is written in the logic of the ACL2 theorem prover. It can be executed as a Lisp program on concrete data, which provides the capability to validate the model against results delivered by actual x86 processors. We demonstrate how bugs in our model can also be eliminated by using the ACL2 prover to verify guards (semantic preconditions) for our functions. --------- This work preceded the development of the full x86 model described in [bib::ghk13], [bib::ghkg14], [bib::goel16], and [bib::ghk17].") (hkms17 (operational-semantics-3__annotated-bibliography) "W. A. Hunt, Jr., M. Kaufmann, J S. Moore, and A. Slobodova, ``{Industrial hardware and software verification with ACL2 | https://royalsocietypublishing.org/doi/10.1098/rsta.2015.0399}'' in P. Gardner, P. O'Hearn, M. Gordon, G. Morrisett and F. B. Schneider, editors), [3mVerified Trustworthy Software Systems[0m, Philosophical Transactions A, Royal Society Publishing, [31;1m374[0m, DOI 10.1098/rsta.2015.0399, September, 2017. [31;1mRelevance:[0m how ACL2 is used in industry, and why --------- Abstract The ACL2 theorem prover has seen sustained industrial use since the mid-1990s. Companies that have used ACL2 regularly include AMD, Centaur Technology, IBM, Intel, Kestrel Institute, Motorola/Freescale, Oracle and Rockwell Collins. This paper introduces ACL2 and focuses on how and why ACL2 is used in industry. ACL2 is well-suited to its industrial application to numerous software and hardware systems, because it is an integrated programming/proof environment supporting a subset of the ANSI standard Common Lisp programming language. As a programming language ACL2 permits the coding of efficient and robust programs; as a prover ACL2 can be fully automatic but provides many features permitting domain-specific human-supplied guidance at various levels of abstraction. ACL2 specifications and models often serve as efficient execution engines for the modelled artefacts while permitting formal analysis and proof of properties. Crucially, ACL2 also provides support for the development and verification of other formal analysis tools. However, ACL2 did not find its way into industrial use merely because of its technical features. The core ACL2 user/development community has a shared vision of making mechanized verification routine when appropriate and has been committed to this vision for the quarter century since the Computational Logic, Inc., Verified Stack. The community has focused on demonstrating the viability of the tool by taking on industrial projects (often at the expense of not being able to publish much). --------- This is does not discuss operational semantics [3mper se[0m but instead focuses on how ACL2 is used in industry and how ACL2 gained traction in industrial use. The paper discusses how ACL2 is used at Centaur Technology, Inc. When a previously verified module of a microprocessor design is modified by the designers and checked back in to the data base, ACL2 is run that night to attempt to verify the modified design, ``bugs introduced today are detected tonight and fixed tomorrow.'' The Centaur design and verification teams were acquired by Intel in 2021 and ACL2 continues to be so used at Intel. In addition the paper describes features of ACL2 (and of the ACL2 community of users) that are particularly important to industry.") (hunt85 (operational-semantics-3__annotated-bibliography) "W. A. Hunt, Jr., [3mFM8501: A Verified Microprocessor[0m, University of Texas at Austin, Ph.D. dissertation, 1985 (also published as a book of the same title, Springer-Verlag LNAI 795, Heidelberg, 1994. [31;1mRelevance:[0m first microprocessor verified at the gate level and the bottommost component of the CLI stack --------- The precursor to the verified microprocessor used in the CLI Verified Stack as reported in [bib::bhmy89] is described here. See the Nqthm script [47mexamples/hunt/fm8501.events[0m). FM8501, which had 8 registers and a 16-bit wordsize, was verified to implement a conventional orthogonal instruction set. The semantics of the gate-level design of the FM8501 and of the instruction set were described operationally. The CLI Stack was ultimately based on the FM8502, which was like the FM8501 except (a) the wordsize was 32-bits and (b) extra bits were allocated in the instruction word to permit programmer control over ALU condition code flags. These changes were requested by Moore during his design of an assembler for the machine. For more detail on the evolutionary pressure that the assembler put on the underlying machine see Section 1.5 of [bib::moore96]. Since the gate-level design of the FM8501 was parameterized by the word length (including the ALU), the description and verification of the 32-bit FM8502 was easier for Hunt than one might otherwise expect. The FM8502 is described in more detail in Hunt's article in [bib::bhmy89]. Because of the way the gate-level designs of FM8501 and FM8502 were expressed, it was impractical to fabricate either machine. However, see [bib::hb92].") (kmm00a (operational-semantics-3__annotated-bibliography) "M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: An Approach | https://www.cs.utexas.edu/~moore/publications/acl2-books/car/index.html}[0m, Kluwer Academic Publishers, 2000. [31;1mRelevance:[0m introduction to ACL2 --------- This book explains how to program in the ACL2 functional programming language, how that language is formalized as a logic, and how to use the theorem prover. While the language and logic have acquired additional features in subsequent years, most new features are orthogonal to the system described here. Thus, the system here describes a subset of the functionality of the current version of ACL2. Probably the single most ``incompatible'' addition was the change of representation of the ordinals. But the Errata published online in the link above explains how to restore the default representation assumed in the book. Thus, this is an excellent beginner's introduction to how to use the system. In contains many exercises and the solutions are available online.") (kmm00b (operational-semantics-3__annotated-bibliography) "M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: ACL2 Case Studies | https://www.cs.utexas.edu/~moore/publications/acl2-books/acs/index.html}[0m, Kluwer Academic Publishers, 2000. [31;1mRelevance:[0m tutorial examples of ACL2 applications --------- This book is a companion to [bib::kmm00a]. It contains fourteen articles by ACL2 experts, explaining how they formalized and solved fourteen different problems. It also includes exercises.") (liu06 (operational-semantics-3__annotated-bibliography) "H. Liu, [3m{Formal Specification and Verification of a JVM and its Bytecode Verifier | https://www.cs.utexas.edu/~moore/publications/liu-dissertation.pdf}[0m, University of Texas at Austin, Ph.D. dissertation, 2006 [31;1mRelevance:[0m most complete ACL2 model of the JVM --------- The source files for this effort have been updated in October, 2024 (because of changes to ACL2 since 2006) and now reside in the [community-books], in directory [47mbooks/models/jvm/m6/[0m. This dissertation, available at the link above, describes the ``M6'' model of the JVM and some important proofs about it. It was the most complete model constructed in ACL2. It executed most J2ME Java programs (except those with significant I/O or floating-point). It supported * all data types (except floats), * multi-threading, * dynamic class loading, * class initialization, and * synchronization via monitors. The M6 state includes an ``external class table'' where classes reside until they are loaded. The entire Sun CLDC API library (672 methods in 87 classes) are translated into the external representation and are available for loading, constituting about 500 pages of data. The model includes 21 out of 41 native APIs that appeared in Sun's CLDC API library. The M6 description itself is about 160 pages of ACL2. It was created with support from Sun Microsystems. On page 322, Liu describes the size of the proof effort: ``We have defined 2104 ACL2 functions. We proved over 4764 theorems. 196 of them are ``skip-proofed''. To prove the rest of them, 971 inductions are necessary. The total line count of the ACL2 input is 136000. They are organized in 282 files. The dependency graph between the 282 ACL2 books has 2012 edges.'' [3mNote from J Moore, dissertation supervisor: The [47m[skip-proofs][0m[3m tag on a ``theorem'' means the conjecture is assumed rather than proved. So having even one [47mskip-proofs[0m[3m makes it impossible to fully trust the results. However, the skipped conjectures in this work are relatively low-level results very similar to other theorems already proved. Liu and I agreed that these conjectures were very probably provable and we were more interested in the higher-level conclusions drawn from those assumptions.[0m An informal summary of the dissertation, by Liu, states Will a bytecode-verified Java program run safely? Why? What do we mean by ``safely''? This dissertation sets out to address these questions by first building a precise model of the JVM and its bytecode verifier. The models are written in ACL2, for which we have computer-aided mechanical reasoning support. We studied how static type checking during bytecode verification can provide runtime type safety. We did this by examining the JVM type hierarchy and proving that safety conditions on operations enforced by the bytecode verifier can guarantee runtime type safety of the program. We also studied how the JVM type hierarchy is extended in a safe way by the JVM class loader that introduces new types into the environment. We proved a set of theorems stating that the class loading process preserves the consistency of the JVM type hierarchy. We studied a third aspect of the JVM safety. We focused on the safety across method invocation and return. We studied why the bytecode verifier can examine each method individually and provide a safety guarantee about the runtime execution of a program. We note that the execution of a program is characterized by a stack of partially executed methods and a current executing method. We used the full JVM model in ACL2 to study the first two aspects of JVM safety. We proved a set of theorems that stated the effectiveness of the bytecode verification about individual operations and safety of the JVM class loading. We used a simplified JVM model, which we call the small machine, to study the third aspect of the JVM safety. The small machine has only one data type. It has branching instructions and method invocation and return instructions. We proved that any small program verified by the corresponding simplified JVM bytecode verifier can execute safely without overflowing or underflowing the operand stacks.") (manolios00 (operational-semantics-3__annotated-bibliography) "P. Manolios, ``{Correctness of Pipelined Machines | https://dl.acm.org/doi/10.5555/646186.683220}'', in W. A. Hunt, Jr and S. D. Johnson, editors, [3mFormal Methods in Computer-Aided Design (FMCAD 2000)[0m, Springer-Verlag LNCS [31;1m1954[0m, Heidelberg, pp. 161-178, 2000. [31;1mRelevance:[0m an alternative approach to verifying operational models of a pipelined machine --------- Abstract The correctness of pipelined machines is a subject that has been studied extensively. Most of the recent work has used variants of the Burch and Dill notion of correctness. As new features are modeled, e.g., interrupts, new notions of correctness are developed. Given the plethora of correctness conditions, the question arises: what is a reasonable notion of correctness? We discuss the issue at length and show, by mechanical proof, that variants of the Burch and Dill notion of correctness are flawed. We propose a notion of correctness based on WEBs (Well-founded Equivalence Bisimulations). Briefly, our notion of correctness implies that the ISA (Instruction Set Architecture) and MA (Micro-Architecture) machines have the same observable infinite paths, up to stuttering. This implies that the two machines satisfy the same CTL*X properties and the same safety and liveness properties (up to stuttering). To test the utility of the idea, we use ACL2 to verify several variants of the simple pipelined machine described by Sawada. Our variants extend the basic machine by adding exceptions (to deal with overflows), interrupts, and fleshed-out 128-bit ALUs (one of which is described in a netlist language). In all cases, we prove the same final theorem. We develop a methodology with mechanical support that we used to verify Sawada's machine. The resulting proof is substantially shorter than the original and does not require any intermediate abstractions; in fact, given the definitions and some general-purpose books (collections of theorems), the proof is automatic. A practical and noteworthy feature of WEBs is their compositionality. This allows us to prove the correctness of the more elaborate machines in manageable stages.") (mccarthy62 (operational-semantics-3__annotated-bibliography) "J. McCarthy, ``{Towards a mathematical science of computation | http://jmc.stanford.edu/articles/towards/towards.pdf},'' [3mProceedings of the Information Processing Cong. 62[0m, North-Holland, Munich, West Germany, pp. 21-28, August, 1962. [31;1mRelevance:[0m a seminal paper in the history of formal operational semantics --------- The pdf linked above is dated 1996, but the original paper was written in 1962. In a brief preface (found on the [47m.html[0m file at the same site as the link above) to the 1996 paper McCarthy wrote: ``[3mTowards a Mathematical Science of Computation was given at the congress IFIP-62 and published in the proceedings of that conference. It extends the results of A Basis for a Mathematical Theory of Computation which was first given in 1961.[0m'' In the 1962 paper (page 19) he wrote ``The semantic description of the language must tell what the programs mean. The meaning of a program is its effect on the state vector in the case of a machine independent language, and its effect on the contents of memory in the case of a machine language program.'' He goes on to sketch the approach to operational semantics used most often in ACL2 and its predecessors. See page 22.") (mmrv06 (operational-semantics-3__annotated-bibliography) "J. Matthews, J S. Moore, S. Ray and D. Vroon, ``{ Verification Condition Generation via Theorem Proving | http://ece.ufl.edu/wp-content/uploads/sites/119/publications/lpar06.pdf}'', in [3mProceedings of 13th International Conference on Logic for Programming, Artificial Intelligence, and Reasoning (LPAR 2006)[0m, LNCS [31;1m4246[0m, pp. 362-376, 2006. [31;1mRelevance:[0m how to conduct inductive assertion-style proofs from an operational semantics without a verification condition generator --------- Abstract We present a deductive method to convert (i) a formal operational semantics for a given machine language, and (ii) an off-the-shelf theorem prover, into a high assurance verification condition generator (VCG). Our method automatically generates verification conditions from assertions at join points of basic blocks of a program, analogous to those produced by a custom-built VCG. We show how to achieve this with a theorem prover by symbolic simulation on the operational semantics. Thus no separate VCG needs to be implemented for the target language. Furthermore, we can employ the full power of the theorem prover to generate and discharge the verification conditions. Our method can handle both partial and total correctness, and recursive procedures. It is also compositional, in that the correctness of a subroutine needs only be proved once, rather than at each call site. The method has been used to verify several machine-level programs in the ACL2 theorem prover, including the functional correctness of JVM bytecodes for a CBC-mode encryption algorithm.") (moore03a (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{Proving Theorems about Java and the JVM with ACL2 | https://www.cs.utexas.edu/~moore/publications/marktoberdorf-02/main_final.pdf}'', in M. Broy and M. Pizka, editors, [3mModels, Algebras and Logic of Engineering Software[0m, IOS Press, Amsterdam, pp. 227-290, 2003. [31;1mRelevance:[0m M5: a JVM model with method invocation, classes, and threads, with some example proofs including about mutual-exclusion --------- This paper was the basis for a series of talks at the 2002 Marktoberdorf Summer School, Germany. Among other topics, it describes the M5 JVM model (ACL2 script [47mbooks/models/jvm/m5/m5.lisp[0m) and the use of the model to formalize and prove properties of a variety of JVM programs, including the so-called ``Apprentice Challenge'' [bib::mp02]. You can find the ACL2 scripts for these proofs on the [47mbooks/models/jvm/m5/[0m. See the [47mREADME[0m on that directory. The M5 work here is both a fairly complicated operational model and a good demonstration of the ``clock''-based proof methodology.") (moore03b (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{ Inductive Assertions and Operational Semantics | https://www.cs.utexas.edu/~moore/publications/trecia/long.pdf}'', in D. Geist, editor, CHARME 2003,, Springer Verlag, LNCS [31;1m2860[0m, pp. 289-303, 2003. [31;1mRelevance:[0mThe URL above points to a longer version of the paper presented at CHARME. Using a subset of M5 the paper shows how partial symbolic evaluation of a program can be used to generate and prove verification conditions produced from inductive assertions --------- Abstract This paper shows how classic inductive assertions can be used in conjunction with an operational semantics to prove partial correctness properties of programs. The method imposes only the proof obligations that would be produced by a verification condition generator but does not require the definition of a verification condition generator. The paper focuses on iterative programs but recursive programs are briefly discussed. Assertions are attached to the program by defining a predicate on states. This predicate is then ``completed'' to an alleged invariant by the definition of a partial function defined in terms of the state transition function of the operational semantics. If this alleged invariant can be proved to be an invariant under the state transition function, it follows that the assertions are true every time they are encountered in execution and thus that the post-condition is true if reached from a state satisfying the pre-condition. But because of the manner in which the alleged invariant is defined, the verification conditions are sufficient to prove invariance. Indeed, the ``natural'' proof generates the classical verification conditions as subgoals. The invariant function may be thought of as a state-based verification condition generator for the annotated program. The method allows standard inductive assertion style proofs to be constructed directly in an operational semantics setting. The technique is demonstrated by proving the partial correctness of simple bytecode programs with respect to a pre-existing operational model of the Java Virtual Machine. --------- See also the paper [bib::rm04].") (moore14 (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{ Proof Pearl: Proving a Simple Von Neumann Machine Turing Complete | https://www.cs.utexas.edu/~moore/publications/m1-is-turing-equiv.pdf}'' in G. Klein and R. Gamboa, editors, [3mInteractive Theorem Proving, ITP 2014[0m, Springer LNCS [31;1m8558[0m, doi.org/10.1007/978-3-319-08970-6_26, 2014. [31;1mRelevance:[0mM1 can compute anything a Turing machine can. (The paper ought to be re-titled ``Proving M1 Turing Equivalent.'') --------- The ``Simple Von Neumann machine'' in question is M1. See the ACL2 directory [47mbooks/models/jvm/m1/[0m and the [47mREADME[0m file there. Abstract In this paper we sketch an ACL2-checked proof that a simple but unbounded Von Neumann machine model is Turing Complete, i.e., can do anything a Turing machine can do. The project formally revisits the roots of computer science. It requires re-familiarizing oneself with the definitive model of computation from the 1930s, dealing with a simple ``modern'' machine model, thinking carefully about the formal statement of an important theorem and the specification of both total and partial programs, writing a verifying compiler, including implementing an X86-like call/return protocol and implementing computed jumps, codifying a code proof strategy, and a little ``creative'' reasoning about the non-termination of two machines. --------- See the ACL2 book [47mbooks/models/jvm/m1/theorems-a-and-b.lisp[0m.") (moore15 (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{ Stateman: Using Metafunctions to Manage Large Terms Representing Machine States | https://www.cs.utexas.edu/~moore/publications/stateman.pdf},'' in M. Kaufmann and D. Rager, editors, [3mProceedings of the 13th International Workshop on the ACL2 Theorem Prover[0m, EPTCS, [31;1m192[0m, pp. 93-109, 2015. [31;1mRelevance:[0m some ACL2 tools for managing the terms representing states of operational models --------- Abstract When ACL2 is used to model the operational semantics of computing machines, machine states are typically represented by terms recording the contents of the state components. When models are realistic and are stepped through thousands of machine cycles, these terms can grow quite large and the cost of simplifying them on each step grows. In this paper we describe an ACL2 book that uses HIDE and metafunctions to facilitate the management of large terms representing such states. Because the metafunctions for each state component updater are solely responsible for creating state expressions (i.e., ``writing'') and the metafunctions for each state component accessor are solely responsible for extracting values (i.e., ``reading'') from such state expressions, they can maintain their own normal form, use HIDE to prevent other parts of ACL2 from inspecting them, and use honsing to uniquely represent state expressions. The last feature makes it possible to memoize the metafunctions, which can improve proof performance in some machine models. This paper describes a general-purpose ACL2 book modeling a byte-addressed memory supporting ``mixed'' reads and writes. By ``mixed'' we mean that reads need not correspond (in address or number of bytes) with writes. Verified metafunctions simplify such ``read-over-write'' expressions while hiding the potentially large state expression. A key utility is a function that determines an upper bound on the value of a symbolic arithmetic expression, which plays a role in resolving writes to addresses given by symbolic expressions. We also report on a preliminary experiment with the book, which involves the production of states containing several million function calls. --------- The utility described here is available in the ACL2 book [47mbooks/projects/stateman/stateman22.lisp[0m. See also the other files on that directory. See [bib::moore17] for a description of the ``key utility,'' defined in the [47mstateman22.lisp[0m file, that computes the bounds of an address.") (moore17 (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{ Computing Verified Machine Address Bounds during Symbolic Exploration of Code | https://www.cs.utexas.edu/~moore/publications/ainni.pdf},'' in J. Bowen, H. Langmaack and E.-R. Olderog, editors, [3mProvably Correct Systems[0m, Springer, pp. 151-172, 2017. [31;1mRelevance:[0m an ACL2 tool for determining whether two symbolic machine addresses may be equal --------- Abstract When operational semantics is used as the basis for mechanized verification of machine code programs it is often necessary for the theorem prover to determine whether one expression denoting a machine address is unequal to another. For example, this problem arises when trying to determine whether a read at the address given by expression [3ma[0m is affected by an earlier write at the address given by [3mb[0m. If it can be determined that [3ma[0m and [3mb[0m are definitely unequal, the write does not affect the read. Such address expressions are typically composed of ``machine arithmetic function symbols'' such as [47m+[0m, [47m*[0m, [47mmod[0m, [47mash[0m, [47mlogand[0m, [47mlogxor[0m, etc., as well as numeric constants and values read from other addresses. In this paper we present an abstract interpreter for machine address expressions that attempts to produce a bounded natural number interval guaranteed to contain the value of the expression. The interpreter has been proved correct by the ACL2 theorem prover and is one of several key technologies used to do fast symbolic execution of machine code programs with respect to a formal operational semantics. We discuss the interpreter, what has been proved about it by ACL2, and how it is used in symbolic reasoning about machine code. --------- The utility described here is available in the ACL2 book [47mbooks/projects/stateman/stateman22.lisp[0m.") (moore19 (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{Milestones from The Pure Lisp Theorem Prover to ACL2 | https://doi.org/10.1007/s00165-019-00490-3}'', [3mFormal Aspects of Computing[0m, Springer, DOI https://doi.org/10.1007/s00165-019-00490-3, 2019. [31;1mRelevance:[0m how the Edinburgh Pure Lisp Theorem Prover (PLTP) evolved into ACL2 --------- Abstract We discuss the evolutionary path from the Edinburgh Pure Lisp Theorem Prover of the early 1970s to its modern counterpart, A Computational Logic for Applicative Common Lisp, aka ACL2, which is in regular industrial use. Among the milestones in this evolution are the adoption of a first-order subset of a programming language as a logic; the analysis of recursive definitions to guess appropriate mathematical induction schemes; the use of simplification in inductive proofs; the incorporation of rewrite rules derived from user-suggested lemmas; the generalization of that idea to allow the user to affect other proof techniques soundly; the recognition that evaluation efficiency is paramount so that formal models can serve as prototypes and the logic can be used to reprogram the system; use of the system to prove extensions correct; the incorporation of decision procedures; the provision of hierarchically structured libraries of previously certified results to configure the prover; the provision of system programming features to allow verification tools to be built and verified within the system; the release of many verified collections of lemmas supporting floating point, programming languages, and hardware platforms; a verified ``bit-bashing'' tool exploiting verified BDD and checked external SAT procedures; and the provision of certain higher-order features within the first-order setting. As will become apparent, some of these milestones were suggested or even prototyped by users. Some additional non-technical aspects of the project are also critical. Among these are a devotion to soundness, good documentation, freely available source code, production of a system usable by industry, responsiveness to user needs, and a dedicated, passionate, and brilliant user community.") (moore73 (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{Computational Logic: Structure Sharing and Proof of Program Properties | http://www.era.lib.ed.ac.uk/handle/1842/2245}, University of Edinburgh, Ph.D. dissertation, 1973. [31;1mRelevance:[0m details of the Edinburgh Pure Lisp Theorem Prover (PLTP) --------- Part II of Moore's dissertation describes the Edinburgh Pure Lisp Theorem Prover (PLTP) in detail. The work was carried out jointly with Bob Boyer.") (moore96 (operational-semantics-3__annotated-bibliography) "J S. Moore, [3mPiton: A Mechanically Verified Assembly-Level Language[0m, J S. Moore, Automated Reasoning Series, Kluwer Academic Publishers, 1996. [31;1mRelevance:[0m verified assembler/linker/loader and a component of the CLI Verified Stack --------- The verified assembler/linker/loader in the final version of the CLI Stack (see [bib::bhmy89]) is described here. See also the 1991 Nqthm script [47mexamples/fm9001-piton/piton.events[0m. The Preface to the book and the comment at the top of the [47m.events[0m file give a lot of history of the evolution of the components of the CLI Stack. Of particular interest to users who wish to verify the correct implementation of one programming language on top of a state machine is decomposition of the main theorem into ``commuting diagrams'' that stack various layers of abstraction between the assembly language and the binary image. Among other things these layers of abstraction solve the problem of ``hidden resources,'' in which the lower level machine state has resources that are not reflected in the upper level. For example at the high level, if one pushes items on the high level stack and then pops them off, there is no change to the stack when viewed from the high level. But the low level machine still records, in the region of memory dedicated to the stack but beyond the current top of stack, the items last pushed. Furthermore, those residual values can be accessed by the low level machine. So one has to prove that they are not. The Piton proof dealt with this by imposing an intermediate abstract machine just above the low level machine but with an instruction set in which it is impossible to access beyond the top of stack.") (moore99a (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{Proving Theorems about Java-like Byte Code | https://www.cs.utexas.edu/~moore/publications/tjvm/main.pdf},'' in E.-R. Olderog and B. Steffen, editors, [3mCorrect System Design -- Recent Insights and Advances[0m, LNCS [31;1m1710[0m, pp. 139-162, 1999. [31;1mRelevance:[0m M2: a JVM model similar to M1 but with method invocation (i.e., subroutine call) --------- Recall that in [operational-semantics-1__simple-example] we described a simple machine akin to the JVM but providing only a few stack-based arithmetic instructions and conditional and unconditional jump instructions. In this paper a similar machine is formalized which provides method invocation and return for both static and virtual methods, and simple class-like instance objects with inheritance. In the paper this machine is called the ``toy JVM'' or ``tjvm.'' But if we place it in the evolving sequence of approximations to the JVM it should be named ``M2.'' The ACL2 scripts providing the definition and theorems of the paper (but now using the name [47mm2[0m instead of [47mtjvm[0m) may be found in the ACL2 directory [47mbooks/models/jvm/m2/[0m. See the [47mREADME[0m file there.") (moore99b (operational-semantics-3__annotated-bibliography) "J S. Moore, ``{A Mechanically Checked Proof of a Multiprocessor Result via a Uniprocessor View | https://www.cs.utexas.edu/~moore/publications/multi-v-uni.pdf}'', J S. Moore, [3mFormal Methods in System Design[0m, [31;1m14[0m(2), pp. 213-228, March, 1999. [31;1mRelevance:[0m proving a relationship between two state machines --------- Abstract We describe a mechanically checked correctness proof for a system of [3mn[0m processes, each running a simple, non-blocking counter algorithm. We prove that if the system runs longer than [3m5n[0m steps, the counter is increased. The theorem is formalized in applicative Common Lisp and proved with the ACL2 theorem prover. The value of this paper lies not so much in the trivial algorithm addressed as in the method used to prove it correct. The method allows one to reason accurately about the behavior of a concurrent, multiprocess system by reasoning about the sequential computation carried out by a selected process, against a memory that is changed externally. Indeed, we prove general lemmas that allow shifting between the multiprocess and uniprocess views. We prove a safety property using a multiprocess view, project the property to a uniprocess view, and then prove a global progress property via a local, sequential computation argument. Our uniprocessor view is a formal compositional semantics for a shared memory system. --------- See the ACL2 script [47mbooks/misc/multi-v-uni.lisp[0m.") (mp02 (operational-semantics-3__annotated-bibliography) "J S. Moore and G. Porter, ``{The Apprentice Challenge | https://www.cs.utexas.edu/~moore/publications/m5/apprentice.pdf}'', [3mACM TOPLAS[0m, [31;1m24[0m(3), pp. 1-24, May, 2002. [31;1mRelevance:[0m M5 and mutual-exclusion via monitors: an unbounded number of JVM threads competing for access to a shared resource --------- Abstract We describe a mechanically checked proof of a property of a small system of Java programs involving an unbounded number of threads and synchronization via monitors. We adopt the output of the [47mjavac[0m compiler as the semantics and verify the system at the bytecode level under an operational semantics for the JVM. We assume a sequentially consistent memory model and atomicity at the bytecode level. Our operational semantics is expressed in ACL2, a Lisp-based logic of recursive functions. Our proofs are checked with the ACL2 theorem prover. The proof involves reasoning about arithmetic, infinite loops, the creation and modification of instance objects in the heap, including threads, the inheritance of fields from superclasses, pointer chasing and smashing, the invocation of instance methods (and the concomitant dynamic method resolution), use of the [47mstart[0m method on thread objects, the use of monitors to attain synchronization between threads, and consideration of all possible interleavings (at the bytecode level) over an unbounded number of threads. Readers familiar with monitor-based proofs of mutual-exclusion will recognize our proof as fairly classical. The novelty here comes from (i) the complexity of the individual operations on the abstract machine, (ii) the dependencies between Java threads, heap objects, and synchronization, (iii) the bytecode-level interleaving, (iv) the unbounded number of threads, (v) the presence in the heap of incompletely initialized threads and other objects, and (vi) the proof engineering permitting automatic mechanical verification of code-level theorems. We discuss these issues. The problem posed here is also put forth as a benchmark against which to measure other approaches to formally proving properties of multi-threaded Java programs.") (mp67 (operational-semantics-3__annotated-bibliography) "J. McCarthy and J. Painter, ``{Correctness of a Compiler for Arithmetic Expressions | http://jmc.stanford.edu/articles/mcpain/mcpain.pdf}'', [3mProceedings of Symposia in Applied Mathematics[0m, [31;1m19[0m, American Mathematical Society, 1967. [31;1mRelevance:[0m an early (perhaps the first) compiler proof --------- This paper by gives a conventional ``hand proof'' (not a mechanized proof) of the correctness of a compiler for simple arithmetic expressions. It demonstrates the use of an operational semantics for the underlying machine. This was a famous and popular challenge problem in the early history of formal methods. See Chapter 17 [bib::bm79] for a mechanized proof a similar result and a discussion of the history of the mechanization of such compiler proofs.") (plotkin04a (operational-semantics-3__annotated-bibliography) "G. D. Plotkin, ``{ A Structural Approach to Operational Semantics | https://homepages.inf.ed.ac.uk/gdp/publications/sos_jlap.pdf}'', Computer Science Department, Aarhus University, Denmark, DAIMI FN-19, 1981 (reprised in a 2004 submission to the [3mThe Journal of Logic and Algebraic Programming[0m). [31;1mRelevance:[0m Plotkin's introduction of the term ``structural operational semantics'' --------- In the introduction to this historically important ``Aahus note'' Plotkin wrote: 1.1 Introduction It is the purpose of these notes to develop a simple and direct method for specifying the semantics of programming languages. Very little is required in the way of mathematical background; all that will be involved is ``symbol-pushing'' of one kind or another of the sort which will already be familiar to readers with experience of either the non-numerical aspects of programming languages or else formal deductive systems of the kind employed in mathematical logic. Apart from a simple kind of mathematics the method is intended to produce concise comprehensible semantic definitions. Indeed the method is even intended as a direct formalisation of (many aspects of) the usual informal natural language descriptions. I should really confess here that while I have some experience what has been expressed above is rather a pious hope than a statement of fact. I would therefore be most grateful to readers for their comments and particularly their criticisms. I will follow the approach to programming languages taken by such authors as Gordon [Gor] and Tennent [Ten] considering the main syntactic classes --- expressions, commands and declarations --- and the various features found in each. The linguistic approach is that developed by the Scott-Strachey school (together with Landin and McCarthy and others) but within an operational rather than a denotational framework. These notes should be considered as an attempt at showing the feasibility of such an approach. Apart from various inadequacies of the treatment as presented many topics of importance are omitted. These include data structures and data types; various forms of control structure from jumps to exceptions and coroutines; concurrency including semaphores, monitors and communicating process.") (plotkin04b (operational-semantics-3__annotated-bibliography) "G. D. Plotkin, ``{ The origins of structural operational semantics | https://www.sciencedirect.com/science/article/pii/S1567832604000268}'', [3mThe Journal of Logic and Algebraic Programming[0m, [31;1m60[0m and [31;1m61[0m, pp. 3-15, July and December 2004. [31;1mRelevance:[0m an interesting historical account of the most popular (non-ACL2) approach to operational semantics --------- The term ``structural Operational Semantics'' was introduced by Gordon Plotkin in technical note DAIMI FN-19, Computer Science Department, Aarhus University, 1981. That sense of ``operational semantics'' is probably the most popular today and the literature has grown enormously since the original note. For that reason, we cite this ``origins'' paper because it was published in a two volume special issue of [3mThe Journal of Logic and Algebraic Programming[0m. Furthermore, the original 1981 ``Aarhus note'' is included in that issue, and that special issue can be downloaded in full from this citation. The approach to operational semantics most widely used in the ACL2 community is different from structural operational semantics. Plotkin formalized machines operationally but as inference rules (reminiscent of Hoare logic), whereas in ACL2 the logic is fixed --- it is the logic of the ACL2 theorem prover --- and in ACL2 the theory is extended via conservative definitions to describe the operation of the machines in question. In this origins paper, Plotkin writes ``The IBM Vienna school [41,42] were interested in specifying real programming languages, and, in particular, worked on an abstract interpreting machine for PL/I using VDL, their Vienna Definition Language; they were influenced by the ideas of McCarthy, Landin and Elgot [18]. I remember attending a seminar at Edinburgh where the intricacies of their PL/I abstract machine were explained. The states of these machines are tuples of various kinds of complex trees and there is also a stack of environments; the transition rules involve much tree traversal to access syntactical control points, handle jumps, and to manage concurrency. I recall not much liking this way of doing operational semantics. It seemed far too complex, burying essential semantical ideas in masses of detail; further, the machine states were too big. The lesson I took from this was that abstract interpreting machines do not scale up well when used as a human-oriented method of specification for real languages (but see below for further comment).'' There is no doubt that interpretive operational semantics for commercial microprocessors is enormously complicated and much of that complexity is buried in data structures, but we in the ACL2 community tend to regard that as an unavoidable consequence of how the machines are designed and the fact that the structure of the designs manifest themselves in behaviors that users see. Would a structural operational semantics for the system-level view of x86 be less complex than the ACL2 x86 model described in [bib::goel16]? We also agree with Plotkin's observation that the interpretive approach does not scale well [3mwhen used as a human-oriented method of specification for real languages[0m. However, our focus is on [3mmechanized[0m reasoning about machines and we are optimistic that mechanization can manage the complexity. Furthermore, we believe the examples discussed in [operational-semantics-2__other-examples] support our optimism. Of course, as noted in [operational-semantics-1__simple-example], the ACL2 user is responsible for configuring ACL2's prover to manage the complexity but the evidence is that expert users are capable of doing that, exploiting such ACL2 features as rewrite rules, metafunctions, enabling and disabling, pragmas for controlling rules, and hints (including computed hints).") (rhmm07 (operational-semantics-3__annotated-bibliography) "S. Ray, W. A. Hunt, Jr., J. Matthews, and J S. Moore, `{A Mechanical Analysis of Program Verification Strategies | https://link.springer.com/article/10.1007/s10817-008-9098-1},'' [3mJournal of Automated Reasoning[0m, [31;1m40[0m(4), pp. 245-269, May, 2008. [31;1mRelevance:[0m stepwise invariants, clock functions, and inductive assertion proof styles are all equivalent --------- Abstract We analyze three proof strategies commonly used in deductive verification of deterministic sequential programs formalized with operational semantics. The strategies are (i) stepwise invariants, (ii) clock functions, and (iii) inductive assertions. We show how to formalize the strategies in the logic of the ACL2 theorem prover. Based on our formalization, we prove that each strategy is both sound and complete. The completeness result implies that given any proof of correctness of a sequential program one can derive a proof in each of the above strategies. The soundness and completeness theorems have been mechanically checked with ACL2. --------- See also [bib::rm04].") (rm04 (operational-semantics-3__annotated-bibliography) "S. Ray and J S. Moore, ``{Proof Styles in Operational Semantics | https://www.ece.ufl.edu/wp-content/uploads/sites/119/publications/fmcad04.pdf},'' in A. J. Hu and A. K. Martin, editors, [3mFormal Methods in Computer-Aided Design (FMCAD-2004)[0m, Springer, LNCS [31;1m3312[0m, pp. 67-81, 2004. [31;1mRelevance:[0m ACL2 tools for transforming inductive assertion-style proofs to clock function style and vice versa --------- Abstract We relate two well-studied methodologies in deductive verification of operationally modeled sequential programs, namely the use of inductive invariants and clock functions. We show that the two methodologies are equivalent and one can mechanically transform a proof of a program in one methodology to a proof in the other. Both partial and total correctness are considered. This mechanical transformation is compositional; different parts of a program can be verified using different methodologies to achieve a complete proof of the entire program. The equivalence theorems have been mechanically checked by the ACL2 theorem prover and we implement automatic tools to carry out the transformation between the two methodologies in ACL2. --------- See also the files by S. Ray on the ACL2 directory [47mbooks/proofstyles/[0m.") (sawada00 (operational-semantics-3__annotated-bibliography) "J. Sawada, ``Verification of a Simple Pipelined Machine Model,'' in M. Kaufmann, P. Manolios, J S. Moore, editors, [3mComputer-Aided Reasoning: ACL2 Case Studies[0m, Kluwer Academic Publishers, Chapter 9, pp. 137-150, 2000. (See also pubs::pubs-books.) [31;1mRelevance:[0m operational model of a pipelined machine and its verification --------- Abstract The difficulty of pipelined machine verification derives from the fact that there is a complex time-abstraction between the pipelined implementation and its specification which executes instructions sequentially. To study this problem, we define a simple three-stage pipelined machine in ACL2. We prove that this pipelined machine returns the same result as its specification machine. In order to ease the proof, we define an intermediate abstraction called MAETT. This abstraction models the behavior of instructions in the pipelined architecture, and it allows us to define directly and verify invariant conditions about executed instructions. The author used a similar approach to verify a more realistic pipelined machine. This chapter serves as an introduction to the verification of pipelined machines.") (sh98 (operational-semantics-3__annotated-bibliography) "J. Sawada and W. A. Hunt, Jr, ``{Processor Verification with Precise Exceptions and Speculative Execution | https://link.springer.com/chapter/10.1007/BFb0028740}'', in A. J. Hu and M. Y. Vardi, editors, [3mComputer Aided Verification, (CAV '98)[0m, Springer-Verlag LNCS [31;1m1427[0m, Heidelberg, pp. 135-146, 1998. [31;1mRelevance:[0m proof method for dealing with exceptions and speculative execution --------- Abstract We describe a framework for verifying a pipelined microprocessor whose implementation contains precise exceptions, external interrupts, and speculative execution. We present our correctness criterion which compares the state transitions of pipelined and non-pipelined machines in presence of external interrupts. To perform the verification, we created a table-based model of pipeline execution. This model records committed and in-flight instructions as performed by the microarchitecture. Given that certain requirements are met by this table-based model, we have mechanically verified our correctness criterion using the ACL2 theorem prover.") (wilding92 (operational-semantics-3__annotated-bibliography) "M. M. Wilding, [3mMachine-checked real-time system verification[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/wilding.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1996. [31;1mRelevance:[0m a non-trivial applications program on the CLI Verified Stack --------- In the introduction to this dissertation, the author writes: ``The complexity and importance of real-time systems makes their formalization and verification crucial. We ensure proper real-time system behavior in several ways through mathematical proof. We check proofs using Nqthm, a mechanical proof system also known as the Boyer-Moore theorem prover. ... We verify a high-level language application that, using a proved compiler and microprocessor design, assures the optimality and timely behavior of an application. The verified program uses a clever algorithm to meet its specification and a method for structuring proofs allows large verified programs to be developed. An interpreter-based language semantics allows reliable execution behavior reasoning, including reasoning about timing.'' --------- The dissertation deals with several programs written in the Piton assembly language ([bib::moore96]) for the FM9001 ([bib::hb92]). In addition to establishing functional correctness, the proofs ensure that the Piton images fit in the space provided by the fabricated FM9001, provide upper bounds on the instruction counts, and the sizes of both the control stack and the temporary stack implemented by Piton on the FM9001. See also [bib::wilding93] for a discussion of one of these programs, namely one that implements a winning strategy for the game of Nim. See the Nqthm scripts by downloading and extracting the [47m*.events[0m files from [47mftp://ftp.cs.utexas.edu/pub/boyer/diss/wilding-diss-events.tar[0m.") (wilding93 (operational-semantics-3__annotated-bibliography) "M. M. Wilding, ``{A Mechanically Verified Application for a Mechanically Verified Environment | https://link.springer.com/content/pdf/10.1007/3-540-56922-7_22}, in C. Courcoubetis, editor, [3mProceedings of Computer-Aided Verification -- CAV '93[0m, Springer-Verlag, LNCS [31;1m697[0m, Heidelberg, pp. 268-279, DOI:10.1007/3-540-56922-7_22, 1993. [31;1mRelevance:[0m functional correctness and resource utilization of a Nim-playing program on the CLI Verified Stack --------- Abstract We have developed a verified application proved to be both effective and efficient. The application generates moves in the puzzle-game Nim and is coded in Piton, a language with a formal semantics and a compiler verified to preserve its semantics on the underlying machine. The Piton compiler is targeted to the FM9001, a recently fabricated verified microprocessor. The Nim program correctness proof makes use of the language semantics that the compiler is proved to implement. Like the Piton compiler proof and FM9001 design proof, the Nim correctness proof is generated using Nqthm, a proof system sometimes known as the Boyer-Moore theorem prover. --------- The paper proves that a Piton program constructed by the author implements a winning strategy (if one exists for a given starting state) of the game of Nim. In addition, he proved a bound on the number of instructions executed on each move as well as bounds on the sizes of both the control stack and the temporary stack. In the conclusion of the paper (page 278) the author writes ``Mechanical verification of programs in this manner is time-consuming and difficult. Nevertheless, and quite remarkably, the experience of building the Nim program suggests that development time scales linearly with program length. Once a Piton subroutine has been proved correct, a call to this subroutine can be reasoned about as easily as any basic Piton statement. ... An FM9001 was fabricated and runs a compiled version of the Nim program. The fabricated FM9001 microprocessor, the Piton compiler, and the Nim program were never tested in a conventional manner during development or after completion. Even so, each worked the first time and we would have been surprised if any had not.''") (young88 (operational-semantics-3__annotated-bibliography) "W. D. Young, [3mA Verified Code Generator for a Subset of Gypsy[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/young.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1988. [31;1mRelevance:[0m a verified compiler (from a small Pascal-like subset to an assembly language) and a component of the CLI Verified Stack --------- The verified compiler used in the CLI Verified Stack as reported in [bib::bhmy89] is described here. By the way, we could not find the original Nqthm script for this effort, but the complete script is included in Appendix B of the linked pdf file above, pages 206-860.") (yu92 (operational-semantics-3__annotated-bibliography) "Y. Yu, [3mAutomated proofs of object code for a widely used microprocessor[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/yu.pdf)[0m, University of Texas at Austin, Ph.D. dissertation, 1992. [31;1mRelevance:[0m details of the operational model of the Motorola 68020 --------- Abstract Computing devices can be specified and studied mathematically. Formal specification of computing devices has many advantages --- it provides a precise characterization of the computational model and allows for mathematical reasoning about models of the computing devices and programs executed on them. While there has been a large body of research on program proving, work has almost exclusively focused on programs written in high level programming languages. This thesis addresses the very important but largely ignored problem of machine code program proving. In this thesis we have formally described a substantial subset of the MC68020, a widely used microprocessor built by Motorola, within the mathematical logic of the automated reasoning system Nqthm, a.k.a. the Boyer-Moore Theorem Proving System. Based on this formal model, we have mechanized a mathematical theory to facilitate automated reasoning about object code programs. We then have mechanically checked the correctness of MC68020 object code programs for binary search, Hoare's Quick Sort, the Berkeley Unix C string library, and other well-known algorithms. The object code for these examples were generated using the Gnu C, the Verdix Ada, and the AKCL common Lisp compilers. --------- See also the Nqthm scripts [47mexamples/yu/[0m where you will find the definition of the MC68020 model and the proofs of the programs mentioned.")))