1

XEROX COMMON LISP DESIGN DOCUMENT
CMLIRRAT
1

CMLIRRAT
6

Kelly Roach
23-Mar-86
Section 12.5.  Covering transcendental arithmetic.  Exponentials, logarithms, trigonometric functions, and hyperbolic functions.  The "irrational functions."  The following Common Lisp functions will be implemented in CMLIRRAT:
     SQRT,EXPT,EXP,SINH,COSH,TANH,LOG,ASINH,ACOSH,
     ATANH,SIN,COS,TAN,ASIN,ACOS,ATAN,CIS
2

Issues
1

(1) Complex numbers and ordinairy complex arithmetic needs to be already implemented.  This may involve typemasking and microcode punting as with BIGNUMs.  Probably easy to create a DEFPRINT for complex numbers.  More than this, e.g., reading requires cooperation of Common Lisp reader/printer implementor.
(2) Common Lisp does not have RADIANSFLG.  Common Lisp angles taken to mean radians but Interlisp interprets RADIANSFLG=NIL to mean degrees.
(3) Common Lisp does not have exact equivalents for ARCTAN and ARCTAN2.  Common Lisp has (ATAN Y &OPTIONAL X).  Interlisp has (ARCTAN X RADIANSFLG) and (ARCTAN2 Y X RADIANSFLG).
(4) SQRT, EXPT, LOG must be extended to complex arithmetic.
(5) New fns SINH, COSH, TANH, ASINH, ACOSH, ATANH.
(6) Calls to some fns like Common Lisp ROUND which haven't been implemented yet.
(7) There needs to be a benchmark and a diagnostic.  The benchmark measures speed on typical user problems.  Diagnostic probes CMLIRRAT at the tricky cases along branch cuts etc.  Checks that identities hold up reasonably well on random arguments.
(8) Common Lisp has up to four kinds of floating point numbers, SHORT-FLOATs, SINGLE-FLOATs, DOUBLE-FLOATs and LONG-FLOATs.  See section 2.1.3.
(9) Branch cuts and singularities.
(10) Common Lisp has EXP which is the same as Interlisp ANTILOG.
(11) Spice Lisp implements CIS in ARITH.SLISP.  But CIS is described on p207 of section 12.5 and is a trig fn.
(12) Nonissue:  Various definitions in 12.5.3 like
     arccosh z = log(z+(z+1)sqrt((z-1)(z+1)))
appear that they could be simplified but Common Lisp manual warns that they can't be simplified.  The reason being that branch cuts can be altered in a wrong way.
2

Decisions
1

(1) At first, implement complex numbers and ordinairy complex arithmetic without microcode support.  Probably easy to create a DEFPRINT for complex numbers.  More than this, e.g., reading, will require cooperation of the Common Lisp reader/printer implementor.  Complex is merely (defstruct complex realpart imagpart) or some such, and ratio is merely (defstruct ratio numerator denominator), done so that the accessor functions generated by the defstruct do the "right" thing to make the functions in the book come out right.  Will write a separate design document on complex/rational arithmetic design and implementation.
(2)Common Lisp transcendental functions can share some of the implementation with the Interlisp versions, but are completely separate functions. Whether Interlisp transcendental functions die out is almost irrelevant. We probably will expect them to. We don't see that users have to be made more aware of SIN/COS dying than they do of any of the rest of Interlisp. Interlisp SIN, COS, TAN, ARCSIN, ARCCOS, ARCTAN, and ARCTAN2 will remain in Interlisp package as IL:SIN, IL:COS, IL:TAN, IL:ARCSIN, IL:ARCCOS, IL:ARCTAN, and IL:ARCTAN2.  These fns will probably die out.  Study Interlisp coded versions carefully to see that new implementations--SIN, COS, TAN, ASIN, and ACOS--are at least as good in terms of speed and accuracy. But note that there are some Serious ARs existing on the Interlisp-D versions of SIN, COS, TAN etc that they are *NOT* good enough in terms of accuracy. We might be better off with new implementations of all of these functions, based on a reexamination of the "approved" IEEE standard approximations. This may require some library search.  Packages like CROCK that use Interlisp trig fns can be rewritten to call Common Lisp trig fns, but need not be.
(3)  IL:ARCTAN and IL:ARCTAN2 will probably die out.  It appears to me that
     Interlisp  (ARCTAN X T) = Common Lisp (ATAN X)
     Interlisp (ARCTAN2 Y X T) = Common Lisp (ATAN Y X)
The Interlisp IL:ARCTAN and IL:ARCTAN2 are also reputedly *NOT* good enough in terms of accuracy.
(4) Since SQRT, EXPT, LOG will be extended without backwards incomaptibility, we can make IL:SQRT, IL:EXPT, IL:LOG = CL:SQRT, CL:EXPT, CL:LOG.  Implement as CL:SQRT, CL:EXPT, CL:LOG first, MOVDing on to SQRT, EXPT, LOG in CMLIRRAT filecoms when reasonably confident.  Ultimately, Interlisp coded versions should go away.  Study Interlisp coded versions carefully to see that new implementations are at least as good in terms of speed and accuracy.  Existing SQRT is said to have good accuracy.
(5) No major decisions.  Breakdown of files into chapters is only a rough guide -- we can put things where they belong. If we're working on arithmetic then we should be able to edit CMLARITH if necessary.
(6) Implement ROUND by adapting from Spice Lisp's ARITH.SLISP.  Put into CMLARITH2.  Probably a few other functions like ROUND which will have to be taken care of.
(7) Will have to be written.  This can be done after all CMLIRRAT functions are implemented and can be done in parallel with implementation of microcode support by microcoder.
(8) Our FLOATPs are most like Common Lisp SINGLE-FLOATs.  According to the silver book, how many of the 4 kinds of FLOATs are actually implemented is up to the implementation.  But I think there will be an expectation in the community that a good Common Lisp implementation will support at least two kinds of FLOATs.  XCLISPCORE^ group has decided that LONG-FLOATs will not be implemented in first release of Common Lisp.  Postpone LONG-FLOATs  until everything about SHORT-FLOATs is implemented and until after first release of Common Lisp.  When (if?) we do LONG-FLOATs, we will follow IEEE ideas as much as possible in a Lisp implementation of LONG-FLOATs.  Ultimately requires some additional mods to reader and printer.  Could use microcode support.
(9) Go through the trouble of diagraming on paper the complex domain and range of each function noting singularities etc.  I'm good at this kind of thing.  Don't believe the Spice Lisp fns have done the right thing on these tricky issues unless I know so after rigorous examination and testing.
(10) Interlisp ANTILOG will not be dedocumented, but we can expect that it will fall into disuse.  Common Lisp EXP code equals Interlisp ANTILOG code.  There will be a MOVD of EXP on to ANTILOG for backwards compatibility.  Eventually ANTILOG will probably die.  ANTILOG is another item to shovel into the Interlisp, The Language chapter, which some day we may well abandon in the greater Xerox AI Environment.  But we won't be too quick to kill little pieces, it doesn't help and is just an irritation.
(11) CMLIRRAT will implement CIS.  CMLARITH2 will not.
(12) These kinds of formulas can be simplified if you do case analysis on quadrants of the domain and range etc. and throw in the needed sign changes etc.  The Spice Lisp implementation does a lot of this, for example.  The case analysis makes the overall code somewhat more complicated than the compact definitions listed in section 12.5.3, but the code runs faster since each case will be simpler than the original windy definition.  The windy definitions in section 12.5.3 can be used to check that the fast but complicated definitions are returning the right values.
2

Design overview
1

Sections 12.5 and 12.6 of the silver book have been written fairly carefully and will be used as the design.  It will probably be wise to study and use record declarations from Interlisp LLFLOAT in adapting Spice Lisp SPIRRAT.SLISP.  The following Common Lisp functions will be implemented in CMLIRRAT:
     SQRT,EXPT,EXP,SINH,COSH,TANH,LOG,ASINH,ACOSH,
     ATANH,SIN,COS,TAN,ASIN,ACOS,ATAN, CIS
Obsolete Interlisp functions will exist in Interlisp package only being called IL:COS etc.  There will be no backwards incompatible changes to trig fns COS and SIN to impact packages like CROCK.  We're making *no* backward incompatible changes to the functions that CROCK calls... CROCK is by default in the Interlisp package and thus calls the Interlisp versions... IL:COS etc. If the author of the CROCK LispUsers package, Kelly Roach, wishes to upgrade CROCK to be CommonLisp compatible, well, that's OK, but Kelly Roach will have to actually edit CROCK to call CL:COS instead of IL:COS. (Details of how all of this works pending the Packages design document.)
2

Algorithms & Data Structures
1

Steal algorithms from SPIRRAT.SLISP.  Steal data structures from LLFLOAT.  From p203 of the silver book: "There is a 'floating-point cookbook' by Cody and Waite that may be a useful aid."  The standard reference seems to be Computer Approximations by Hart et al (QA 297 C35).  There is roughly 150 pages of recipes in chapter 7 of this book for rational approximations to the functions that CMLIRRAT pretends to offer as well as error function and Bessel functions.
Dependencies
1

Reader and printer need to know how to read and print complex numbers.  We've proposed no implementation of LONG-FLOAT this time around, there are no reader changes required, except for the general abiliy to read & print numbers in other formats (xxxD12).
Performance points
1

Compiler / evaluator:
     Compiler should understand floating point declarations.  There has to be cruft to handle boxing and unboxing.
Optimizer macros:
    CONSTANTEXPRESSIONP should know that the functions in CMLIRRAT are side effect free etc constant expressions.  CONSTANTEXPRESSIONP isn't in Common Lisp, so we don't know how it affect optimizations. Likely the "new" compiler may have a different way of doing source level analysis/transformations.
Microcode:
     Punting on complex numbers.  LONG-FLOAT arithmetic functions.  Microcode already punts for complex numbers -- it punts for any datatypes it doesn't recognize. The main thing is the integration of the new lisp code with the old UFNs if we implement any of Common Lisp using the old Interlisp opcodes.  Look at how \SLOWIPLUS2 on LLARITH currently calls \BIGNUM.PLUS, for example.  The design/description of the "/" opcode needs to be written.
Environment support
1

Environmental impact (tools needed, etc.): None.
Tasks
1

(1) Rudimentary complex arithmetic.  No reader, printer, or microcode support.
(2) Trig fns.
(3) Exp and log fns.
(4) Hyperbolic fns.
(5) Reader and printer support for complex numbers.
(6) Microcode punting for complex numbers.
(7) LONG-FLOATs, fns for LONG-FLOATs, and reading and printing LONG-FLOATs.
Testing issues
1

Potential edges in algorithms and structures:
     Real numbers will get preferential treatment wrt complex numbers.
2

Phasing and Timing
1


Implementation is phased: (1)-(7) as in Tasks section.
Time estimate: 1 month.
Follow on and overlap with reading, printing, microcode, complex numbers, and LONG-FLOATs mean CMLIRRAT will tend to drag on into many months to come.  If the overlapping portions were already implemented, I estimate about a month to do CMLIRRAT down to the gorey complex, LONG-FLOAT, reader/printer, microcoded detail.
2

Appendix
1


References: Computer Approximations by Hart et al.
(EXP NUMBER)
(EXPT BASE-NUMBER POWER-NUMBER)
(LOG NUMBER &OPTIONAL BASE)
(SQRT NUMBER)
(ISQRT INTEGER)
(SIN RADIANS)
(COS RADIANS)
(TAN RADIANS)
(CIS RADIANS)
(ASIN NUMBER)
(ATAN Y &OPTIONAL X)
PI
(SINH NUMBER)
(COSH NUMBER)
(TANH NUMBER)
(ASINH NUMBER)
(ACOSH NUMBER)
(ATANH NUMBER)
(LIST ((PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((HEADING NIL (HEADINGTYPE FOOTINGR) (72 27 540 36) NIL) (TEXT NIL NIL (72 72 504 648) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (288 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (72 27 540 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (72 762 540 36) NIL) (TEXT NIL NIL (72 72 504 648) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (288 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (72 27 540 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (72 762 540 36) NIL) (TEXT NIL NIL (72 72 504 648) NIL)))))
/``

�

T/


�

T/



�

T)

T)2

T(``)``

T)``

TB
�

�
PAGEHEADING	RECTOHEADA
�




�
PAGEHEADINGFOOTINGR	HELVETICAMODERN
MODERNMODERNMODERN

TIMESROMAN

HRULE.GETFN
MODERN


"			
HRULE.GETFN
MODERN

	
HRULE.GETFN
MODERN
�3*
HRULE.GETFN
MODERN

HRULE.GETFN
MODERN

3��<3Q��#Ao3.�
HRULE.GETFN
MODERN


HRULE.GETFN
MODERN




T


i
C

'
N
rL48:'


��

@

c��
'
"q

S

7;
HRULE.GETFN
MODERN

HRULE.GETFN
MODERN

/3+�
�


HRULE.GETFN
MODERN

HRULE.GETFN
MODERN

�

HRULE.GETFN
MODERN


I�


HRULE.GETFN
MODERN



s

s�



D�
R<


HRULE.GETFN
MODERN


1
HRULE.GETFN
MODERN


O



4
+
L
HRULE.GETFN
MODERN


.
G
HRULE.GETFN
MODERN

HRULE.GETFN
MODERN


7


@
HRULE.GETFN
MODERN
	
HRULE.GETFN
MODERN


3


 
















,�
z�