Updated comments.

package.lisp

@@ -1,4 +1,4 @@
-;;;; package.lisp
+:;;;; package.lisp
 
 (defpackage #:cat
   (:use #:cl)
@@ -301,6 +301,7 @@
            CHCM-HOMOLOGY-GEN
            CHCM-MAT
            HOMOLOGIE
+           MAT-ALEAT
 
            ;; k-pi-n.lisp
 
@@ -578,4 +579,3 @@
            Z2-WHITEHEAD-SINTR
 
            ))
-

src/classes.lisp

@@ -178,9 +178,16 @@ Intances of this class represent chain complexes. The class has 8 slots:
 4. DFFR, the differential morphism, an instance of the class MORPHISM. Its
    reader function is DFFR1.
 
-5. GRMD, ???   Its reader function is GRMD.
+5. GRMD, refers to some chain-complex considered as a reference for the
+   underlying graded module structure. Sometimes, it is better to check two
+   chain-complexes have the same underlying graded module. Typically if C1 is
+   a chain-complex and C2 is obtained from C1 by perturbing the differential,
+   then (eq (grmd C1) (grmd C2)) should return T. Its reader function is GRMD.
 
-6. EFHM, ???   Its reader function is EFHM.
+6. EFHM, if the effective homology of the chain complex has already been
+   computed, then this slot points to the HOMOTOPY-EQUIVALENCE which IS the
+   effective homology  of this object. Otherwise the slot is unbound. Its
+   reader function is EFHM.
 
 7. IDNM, an integer, a system generated identifier for this object. Its reader
    function is IDNM.
@@ -240,11 +247,22 @@ degree -1. The class has 10 slots:
 
 3. DEGR, an integer, the degree of the morphism. Its reader function is DEGR.
 
-4. INTR, a Lisp function implementing the morphism, taking account of the
-   strategy STRT. Its reader function is INTR.
+4. INTR, a Lisp INTeRnal function implementing the morphism, taking account
+   of the strategy STRT. Its reader function is INTR.
 
 5. STRT, a symbol, one of :GNRT or :CMBN. Its reader function is STRT.
 
+   If this slot is :GNRT, the implementation of INTR is a function:
+     (function (degr gnrt) cmbn)
+   and for any call of this function, the result is stored in the slot
+   RSLTS to avoid later a possibly long recalculation for  the same
+   argument.
+
+   If this slot is :CMBN, the implementation of INTR is a function:
+     (function (cmbn) cmbn)
+   and the RSLTS slot is not used. Think for example to an identity or
+   null function, where storing a result is wasted time.
+
 6. ???-CLNM, an integer updated by the system for internal statistics. Its
    reader function is ???-CLNM.
 
@@ -352,7 +370,14 @@ The class has 7 slots:
    ;; IDentification NuMber
    (idnm :type fixnum :initform (incf *idnm-counter*) :reader idnm)
    ;; ORiGiN
-   (orgn :type list          :initarg :orgn :reader orgn)))
+   (orgn :type list          :initarg :orgn :reader orgn))
+  (:documentation
+   "----------------------------------------------------------------[class-doc]
+HOMOTOPY-EQUIVALENCE
+A homotopy-equivalence is essentially a pair of respective reductions from an
+intermediate chain complex TCC to the LBCC (left bottom) and RBCC (rigth
+bottom) chain complexes. It is an equivalence between LBCC and RBCC.
+-----------------------------------------------------------------------------"))
 
 #+allegro
 (eval-when (:compile-toplevel :load-toplevel :execute)
@@ -365,9 +390,31 @@ The class has 7 slots:
 
 
 (DEFSTRUCT (matrice (:conc-name nil))
+  "------------------------------------------------------------------[type-doc]
+MATRICE
+Slots: (leftcol uplig)
+A MATRICE is made of two vectors LEFTCOL and UPLIG. LEFTCOL is a
+vector of size m+1 if m is the number of rows of the matrix, UPLIG is
+a vector of size n+1 if n is the number of columns.
+Every element of LEFTCOL and UPLIG is a T-MAT with the value NIL
+indicating it is a fake term.
+------------------------------------------------------------------------------"
   leftcol uplig)
 
 (DEFSTRUCT (t-mat (:conc-name nil))
+  "------------------------------------------------------------------[type-doc]
+T-MAT
+Slots: (val ilig icol left up)
+A T-MAT (= Terme de Matrice) has five components:
+
+  VAL  = A value, an integer, in principle a non-null integer.
+  ILIG = the line (row is better) index of this term
+  ICOL = the column index of this term
+  LEFT = a pointer to the next term on the left on the same line,
+         or to a fake term, an element of LEFTCOL of the matrice.
+  UP   = a pointer to the next term above on the same column,
+         or to a fake term, an element of UPLIG of the matrice.
+------------------------------------------------------------------------------"
   val ilig icol left up)
 
 
@@ -379,11 +426,26 @@ The class has 7 slots:
   (conx (:type '(member 0 1)))
   (icon (:type 'gnrt)))
 
+;; Given a morphism f : C1 -> C0 between two chain complexes,
+;; the cone of f is a chain complex made of C0 as such,
+;; C1 suspended.
+;; The differential of the C0 component is unchanged.
+;; If x is an element of C1, then d_cone(x) = -dx + fx
+;;   with dx computed as in the original C1.
+;; A CONE generator is an conx 0 (resp. 1) and
+;;   and an icon (= internal cone generator) being a
+;;   generator of C0 (resp. C1).
 
 (DEFSTRUCT (BICN (:conc-name nil) (:print-function bicn-print))
   (bcnx (:type '(member :bcnb :bcnc :bcnd)))
   (ibicn (:type 'gnrt)))
 
+;; Analogous with two morphisms f: B -> C and g: D -> C.
+
+;; Intended to become the central part of a zigzag :
+;;                  A <- B -> C <- D -> E
+;; The key structure to compose two equivalences:
+;;   A <- B -> C   and   C <- D -> E
 
 ;;;
 ;;;  TENSOR-PRODUCTS