9 9 CHAPTER 1 Introduction MACSYMA is a large interactive computer program which operates on algebraic expressions. It can differentiate, integrate, take limits, solve systems of linear or polyno- mial equations, factor polynomials, expand functions in Laurent or Taylor series, solve differential equations (using direct or transform methods), compute Poisson series, plot curves, and manipulate matrices and tensors. MACSYMA has a language similar to ALGOL-60 to permit the user to write his own programs for transforming symbolic expres- sions. This manual is intended to be a complete reference for the principal features of MACSYMA as of the date shown on the cover. It is not meant to be a tutorial nor does it discuss all of the issues involved in the efficient manipu- lation of algebraic expressions. New features under develop- ment are, for the most part, not mentioned. To make best use of this system, you will have to become sufficiently acquainted with the host operating sys- tem to "log in", "log out", edit a file, send "mail" to other users, and move between jobs using the shell. You should also be acquainted with at least one conventional programming language, such as Fortran, Basic, Pascal. A version of the MACSYMA Primer with specific instruc- tions for your site should be available to you. A brief summary may be available as the on-line UNIX manual page. This manual is intended as a language reference for users. It is not an implementation guide. A brief version of it as a quick reference is in preparation. On first reading, sections with * following their numbers can be omitted. We suggest you re-read this manual from time to time as you work with MACSYMA. As you become more experienced, you may discover additional useful features of the system. Some general comments In a programming system such as MACSYMA there are often many ways to solve a problem. There are constraints imposed by the nature of the built-in data representations and algo- rithms of the the programming system, and, indeed, the Introduction 1-2 Introduction 1-1 computer system it runs on. Some approaches to solving a problem will not succeed due to space or time constraints and others may work but may be unnecessarily slow. Fre- quently a better understanding of the computer facilities (or of the mathematics) will lead to a reformulation of the problem or a solution technique. You many find some useful reading in the references at the end of the main body of the text. _1._1. _G_e_n_e_r_a_l _I_n_f_o_r_m_a_t_i_o_n Command lines to MACSYMA are strings of characters representing mathematical expressions involving equations, arrays, functions, and programs. Extra spaces, tabs, and carriage returns () are ignored (except when these occur in quoted strings). Commands may be any number of lines long. You terminate a command by ";" or "$" (dollar sign), and then a . If you use a ";" the result will be displayed, usually as a single value or expression immediately below the command. If you use a "$", the result is computed and labelled, but not displayed. You can delete characters, words, or lines as you type by using the same characters used in your usual UNIX conven- tion. Many people use backspace (control-H, written ^H) for single character deletions, and ^W to delete a word. By typing ^K, you can obtain a copy of the current com- mand line free of any echoed erasures. If you type the two characters ??, you will delete the whole command line, and the system will redisplay the line number. The command (input) lines are indexed by labels of the form "(ci)" where i is incremented with each new command line typed by the user. Similarly, the results of computa- tions are also indexed. There are two types of output lines. The ordinary output line is indexed by a label of the form "(di)" ; thus, usually the ith input-output pair will be (ci)-(di). Sometimes, however, a computation pro- duces several intermediate results (for example, several solutions to an equation). Then it is convenient to be able to reference these intermediate lines of output. They are indexed by labels of the form "(ej)" where j is incremented by one for each intermediate line. For example*, ____________________ 9 * with programmode set to false. 9 Printed: May 31, 1986 Introduction 1-2 ____________________________________________________ (c1) solve(x^2 + b*x + c, x); 2 sqrt(b - 4 c) + b (e1) x = - ------------------ 2 2 b - sqrt(b - 4 c) (e2) x = - ------------------ 2 (d2) [e1, e2] ____________________________________________________ Note that there is no line d1 since intermediate results were produced and thus the line index was incremented. The general pattern of indexing is of the form ci, ei,ei+1,...,ej, dj . A command line may refer to the results of any previously indexed line (even if it was not displayed) through the use of the line labels. For example, you might type _s_u_b_s_t_i_t_u_t_e(_7,_b,_e_2); which would substitute 7 for _b in the expression _e_2 above. The immediately preceding d-line may be referred to by the alternate name "%". While the display as given above hews fairly closely to what one would see on a conventional fixed-width printing or display terminal, there is an improved type-setting capabil- ity for more flexible terminals which we will use for subse- quent displays. We use it not only to improve readability of the manual but to produce a more compact document. We will be describing a large number of "commands" or "functions"8*9 in MACSYMA. In addition to being used ____________________ 98 *9 The notion of function as used here is not the mathematical notion of a mapping, but the programming no- tion, which is somewhat different. A MACSYMA function may have a variable number of arguments, may be a place-holder for some unknown or undetermined calculational routine, or may be associated with some pre-programmed or user- programmed algorithm or procedure. Most people familiar 9 Printed: May 31, 1986 Introduction 1-3 interactively one command at a time, the commands can be used as built-in functions in a programming language, described in chapter ?. Most serious users find they must learn some of this language, but for the new user, single commands provide a useful way of trying out the capabilities of MACSYMA. Almost every command or function in MACSYMA returns a value which can be displayed, or alternatively "fed" immedi- ately to another command in the usual function-application notation of mathematics and programming languages. Thus if _f and _g are each commands or functions of one argument, and they have the appropriate ranges and domains, (_g(_x) is also a command, with the obvious value. Some commands have "side-effects" which change the way the MACSYMA system behaves subsequently. Side-effects include the assignment of values to "variables", printing of output, consumption of resources of storage and time, and other results not immedi- ately observable as part of the returned value. In the example above, the side-effects (if any) of _g(_x) would occur before the side-effects of the application of _f to that result. Many functions are executed primarily for their value, some for value and side-effect, and a few primarily for side-effects. One function which does not return a value is _l_o_g_o_u_t(). Its side-effect is to exit from MACSYMA and "log you out." _1._2. _O_n-_l_i_n_e _a_s_s_i_s_t_a_n_c_e, _t_u_t_o_r_i_a_l_s, _h_e_l_p If you find yourself stuck and cannot get help from this manual, you should try to save as much information as you can that might help in diagnosing your situation, and seek help from a local expert. Saving your "state" or part of it is usually achieved by using the _s_a_v_e command, (sec- tion ??) (e.g. _s_a_v_e("_p_r_o_b_1/_b_u_g",_b_u_g_1)). On-line mail is often useful in reporting bugs or problems. Your local MACSYMA expert's name, or a means for sending bug reports, should be given to you. For example, to report a bug at UC Berkeley, a concerned user might type ^z {to get out of ____________________ 9with programming languages do not even realize there is an underlying misuse of the term "function," and may be con- fused by this footnote. In that case, ignore it. If you are a novice in the programming language area, and are tempted to make a fuss over this, you should first see the appendix "Computing symbolically". 9 Printed: May 31, 1986 Introduction 1-4 MACSYMA} then % mail vaxima-bugs loadfile("/va/usrname/prob1/bug"); integrate(bug1,x);==> wrong answer. I believe this should be ... . ^D {control-D to end the message} fg {to bring MACSYMA to the "foreground"} The following commands may help you find your way around. describe( 'x_name) (e.g. _d_e_s_c_r_i_b_e(_d_e_s_c_r_i_b_e) ) WHERE: x_name is any MACSYMA command, option, or concept. SIDE EFFECT: prints out a description of that entity. Usu- ally you see printed the appropriate section of this manual, but it is possible that new features post-dating this printing will be described. RETURNS: the atom "done" if successful. NOTE: Since the command must be parsed, certain keywords or built-in operators (e.g. + or _f_o_r) will not work unless you enclose them with double-quotes ("). primer( ['x_file]) e.g. _p_r_i_m_e_r(); or _p_r_i_m_e_r(_h_e_l_p). Details of the cryptic line above are given in section ??. WHERE: x_file, if present, is the name of a primer script. RETURNS: the atom "done" if successful. SIDE EFFECT: Runs an interactive primer teaching MACSYMA. _1._3. _W_h_a_t _t_o _r_e_a_d _n_e_x_t _i_n _t_h_i_s _m_a_n_u_a_l In order to keep future descriptions brief and to the point, we will employ the stylized format illustrated above which describes the types of data appropriate for each com- mand, the return value and the side effects of the command. For those commands which are affected by the settings of MACSYMA variables or flags, this information is noted. Your next order of business is to understand at least some of the data types of MACSYMA in detail so that command Printed: May 31, 1986 Introduction 1-5 descriptions can be stated concisely. The data type descriptions are given in Chapter 2. Chapters 3, .... 9 9 Printed: May 31, 1986