From 654953037057b379f137d1e65a780a212fbe2464 Mon Sep 17 00:00:00 2001 From: Gerd Heber Date: Sat, 15 Aug 2015 21:16:14 -0500 Subject: [PATCH] Documentation updates. --- package.lisp | 3 + src/effective-homology.lisp | 106 ++++++++++++++++++++++++++++++++++-- src/macros.lisp | 52 ++++++++++++++++++ 3 files changed, 155 insertions(+), 6 deletions(-) diff --git a/package.lisp b/package.lisp index 42b1442..568fb3e 100644 --- a/package.lisp +++ b/package.lisp @@ -274,6 +274,7 @@ CHECK-RDCT CMPS PRE-CHECK-RDCT + RDCT TRIVIAL-HMEQ TRIVIAL-RDCT @@ -409,11 +410,13 @@ F DFFR DGNL + G GMSM1 GNRT GNRT-NAME GRIN GRML + H I-ADD I-CMPS I-SBTR diff --git a/src/effective-homology.lisp b/src/effective-homology.lisp index 8472b30..27afc0d 100644 --- a/src/effective-homology.lisp +++ b/src/effective-homology.lisp @@ -22,18 +22,43 @@ #+clisp(eval-when (:compile-toplevel :load-toplevel :execute) (setf (ext:package-lock :clos) t)) + (DEFUN RDCT (n) (declare (fixnum n)) - "Retrieve the N-th user created reduction from the list *RDCT-LIST*. -Return NIL if it doesn't exist." + "--------------------------------------------------------------[function-doc] +RDCT +Args: (n) +Returns the N-th user-created reduction from the list *RDCT-LIST*. Returns NIL +if it doesn't exist. +------------------------------------------------------------------------------" (the (or null reduction) (find n *rdct-list* :key #'idnm))) + (DEFUN BUILD-RDCT (&key f g h orgn) (declare (type morphism f g h) (list orgn)) - "Create a reduction. Use this function instead of the generic MAKE-INSTANCE." + "--------------------------------------------------------------[function-doc] +BUILD-RDCT +Args: (&key f g h orgn) +Returns an instance of the class REDUCTION. The keyword arguments are as +follows: + +:F F, an object of type morphism representing the morphism f of a reduction + +:G G, an object of type morphism representing the morphism g of a reduction + +:H H, an object of type morphism representing the morphism h of a reduction + +:ORGN ORGN, a list containing a relevant and carefully chosen comment about + the origin of the chain complex. This comment should be unique + for a Kenzo session (between calls of CAT-INIT), as it is used + for caching purposes. + +Use this function instead of creating instances via the standard constructor +MAKE-INSTANCE. +------------------------------------------------------------------------------" (the reduction (progn (unless orgn @@ -70,21 +95,42 @@ Return NIL if it doesn't exist." (push rdct *rdct-list*) rdct))))))) + (DEFUN TRIVIAL-RDCT (chcm) (declare (type chain-complex chcm)) + "--------------------------------------------------------------[function-doc] +TRIVIAL-RDCT +Args: (chcm) +Builds the trivial reduction according to the following diagram, which +involves the chain complex CHCM only: + + Zero s + C -------> C + ^ + | | + Id | | Id + | | + v + C + +Zero is the zero morphism of degree 1 of C and Id is its identity morphism. + +See also: ZERO-MRPH, IDNT-MRPH. +------------------------------------------------------------------------------" (build-rdct :f (idnt-mrph chcm) :g (idnt-mrph chcm) - :h (zero-mrph chcm chcm +1) + :h (zero-mrph chcm chcm +1) :orgn `(trivial-rdct ,chcm))) + ;;; ;;; HOMOTOPY-EQUIVALENCES ;;; ;;(defgeneric build-hmeq (keyword lrdct &key &allow-other-keys) -(DEFGENERIC BUILD-HMEQ (keyword lrdct &key) - (:documentation "needed by ECL")) +(DEFGENERIC BUILD-HMEQ (keyword lrdct &key)) + (DEFMETHOD BUILD-HMEQ ((keyword1 (eql :lrdct)) lrdct &key rrdct orgn) (declare @@ -167,6 +213,40 @@ Return NIL if it doesn't exist." ;; Functions. (DEFUN PRE-CHECK-RDCT (rdct) + "--------------------------------------------------------------[function-doc] +PRE-CHECK-RDCT +Args: (rdct) +Assigns the following Lisp global variables, using morphisms from RDCT and the +differentials and identity morphisms of the underlying chain complexes, +according to these formulas: + +*TDD* = d ° d + ^ ^ + C C + +*BDD* = d ° d + C C + +*ID-FG* = Id - f ° g + C + +*ID-GF-DH-HD* = Id - g ° f - (d ° h + h ° d ) + ^ ^ ^ + C C C + +*HH* = h ° h +*FH* = f ° h +*HG* = h ° g + +*DF-FD* = d ° f - f ° d + C ^ + C + +*DG-GD* = d ° g - g ° d + ^ C + C + +------------------------------------------------------------------------------" (declare (type reduction rdct)) (with-slots (bcc tcc f g h) rdct (declare @@ -192,6 +272,19 @@ Return NIL if it doesn't exist." (DEFUN CHECK-RDCT () + "--------------------------------------------------------------[function-doc] +CHECK-RDCT +Args: () +Maps combinations of the top and bottom chain complexes of a reduction using +the morphisms created by PRE-CHECK-RDCT. Having no parameters, the +combinations must be provided via the Lisp global variables *TC* and *BC*, +for the top and bottom chain complex, respectively. If the morphisms are +coherent, the result of each mapping is a null combination. + +Note: This function is intended for interactive use. It pauses after each +evaluation for the user to inspect the result. Resume execution, by pressing +the key. +------------------------------------------------------------------------------" (dolist (cmbn '(*tc* *bc*)) (declare (type symbol cmbn)) (format t "~%~A => ~A" cmbn (eval cmbn))) @@ -206,6 +299,7 @@ Return NIL if it doesn't exist." (read-line)) (done)) + (DEFMETHOD CMPS ((brdct reduction) (trdct reduction) &optional dummy) (declare (ignore dummy)) (when (eq (first (orgn brdct)) 'trivial-rdct) diff --git a/src/macros.lisp b/src/macros.lisp index 0e9d9ca..5980920 100644 --- a/src/macros.lisp +++ b/src/macros.lisp @@ -254,6 +254,17 @@ See also the macro ?. ;;; (DEFMACRO BCC (&rest rest) + "-----------------------------------------------------------------[macro-doc] +BCC +Args: (&rest rest) +Args: (rdct) +Args: (rdct cmbn) +Args: (rdct degr gnrt) +With only one argument, a reduction RDCT, this macro returns the bottom +chain complex of the reduction. Otherwise, it applies the differential of +the bottom chain complex of RDCT to a combination provided in additional +arguments such as CMBN or DEGR GNRT. +------------------------------------------------------------------------------" (case (length rest) (1 `(bcc1 ,@rest)) (otherwise @@ -261,6 +272,17 @@ See also the macro ?. (DEFMACRO TCC (&rest rest) + "-----------------------------------------------------------------[macro-doc] +TCC +Args: (&rest rest) +Args: (rdct) +Args: (rdct cmbn) +Args: (rdct degr gnrt) +With only one argument, a reduction RDCT, this macro returns the top +chain complex of the reduction. Otherwise, it applies the differential of +the top chain complex of RDCT to a combination provided in additional +arguments such as CMBN or DEGR GNRT. +------------------------------------------------------------------------------" (case (length rest) (1 `(tcc1 ,@rest)) (otherwise @@ -268,6 +290,16 @@ See also the macro ?. (DEFMACRO F (&rest rest) + "-----------------------------------------------------------------[macro-doc] +F +Args: (&rest rest) +Args: (rdct) +Args: (rdct cmbn) +Args: (rdct degr gnrt) +With only one argument, a reduction RDCT, this macro returns the morphism f +of the reduction. Otherwise, it applies f to a combination provided in +additional arguments such as CMBN or DEGR GNRT. +------------------------------------------------------------------------------" (case (length rest) (1 `(f1 ,@rest)) (otherwise @@ -275,6 +307,16 @@ See also the macro ?. (DEFMACRO G (&rest rest) + "-----------------------------------------------------------------[macro-doc] +G +Args: (&rest rest) +Args: (rdct) +Args: (rdct cmbn) +Args: (rdct degr gnrt) +With only one argument, a reduction RDCT, this macro returns the morphism g +of the reduction. Otherwise, it applies g to a combination provided in +additional arguments such as CMBN or DEGR GNRT. +------------------------------------------------------------------------------" (case (length rest) (1 `(g1 ,@rest)) (otherwise @@ -282,6 +324,16 @@ See also the macro ?. (DEFMACRO H (&rest rest) + "-----------------------------------------------------------------[macro-doc] +H +Args: (&rest rest) +Args: (rdct) +Args: (rdct cmbn) +Args: (rdct degr gnrt) +With only one argument, a reduction RDCT, this macro returns the morphism h +of the reduction. Otherwise, it applies h to a combination provided in +additional arguments such as CMBN or DEGR GNRT. +------------------------------------------------------------------------------" (case (length rest) (1 `(h1 ,@rest)) (otherwise