[Maxima-bugs] [ maxima-Bugs-531469 ] need better documentation for "assume"

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Bugs item #531469, was opened at 2002-03-18 13:18
Message generated for change (Comment added) made by lemire
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=104933&aid=531469&group_id=4933

Category: Documentation
Group: None
Status: Open
Resolution: Invalid
Priority: 5
Submitted By: Daniel Lemire (lemire)
Assigned to: Nobody/Anonymous (nobody)
Summary: need better documentation for "assume"

Initial Comment:
Maxima allows for the following very powerful syntax...

(C1) (assume (y>1), integrate(x*log(x),x,1,y));

                                2           2
                             2 y  LOG(y) - y    1
(D1)                         ---------------- + -
                                    4           4

However, the documentation is lacking:
Info from file /usr/local/info/maxima.info:
 - Fonction: ASSUME (pred1, pred2, ...)
     First checks the specified predicates for redundancy and
     consistency with the current data base.  If the predicates 
are
     consistent and non-redundant, they are added to the 
data base; if
     inconsistent or redundant, no action is taken.  ASSUME 
returns a
     list whose entries are the predicates added to the data 
base and
     the atoms REDUNDANT or INCONSISTENT where 
applicable.
(D3)                                 FALSE

----------------------------------------------------------------------

>Comment By: Daniel Lemire (lemire)
Date: 2004-02-27 11:32

Message:
Logged In: YES 
user_id=73205

No, you are right, there is no bug here except for a "request for enhancement" 
regarding the documentation. I'm not bitching about it since, of course, I could 
just sit down and start writting document. But short of that, I hope it is useful 
to at least document in which way the documentation is wong. 

I didn't know about "facts()".  Now, looking at the description of facts, I realize 
that I don't know about "contexts" in maxima as well. Let's not go there today. 

Info from file /usr/share/info/maxima.info: 
 - Function: FACTS (item) 
     If 'item' is the name of a context then FACTS returns a list of 
     the facts in the specified context.  If no argument is given, it 
     lists the current context.  If 'item' is not the name of a context 
     then it returns a list of the facts known about 'item' in the 
     current context.  Facts that are active, but in a different 
     context, are not listed. 

----------------------------------------------------------------------

Comment By: Stavros Macrakis (macrakis)
Date: 2004-02-27 09:18

Message:
Logged In: YES 
user_id=588346

I agree that the documentation could be made MUCH MUCH clearer.

But I am puzzled by some of your other remarks:

> if I do assume(y>0); followed byassume(x>0);
> I would expect the system to know x>0 and y>0.
> It doesn't.

It does on my test system, Maxima 5.9.0 gcl 2.5.0 W2k:
   assume(x>0);
   assume(y>0);
   is( x>0 and y>0 ) => true
If this fails on your system, please include a transcript of
a session, and full configuration information from bug_report().

> each call to assume reset the set of assumptions

No.  Not on my system, at least.  If it does, this is a bug.
 The only assumptions that are reset are those added by
Asksign -- that is also explicit in describe(asksign):
"recorded in the data base for the duration of the current
computation (one 'C-line')".

> In D3, I would expect [x>0,y>0] or something similar.

As documented explicitly in the text you quote, the return
value reports on the predicates **added to** the data base.
To see the list of all current assumptions, use facts().

> I guess I'm supposed to understand that "C comma"
> means... what... the C language? 

Yes, the C programming language has the same construct.  Of
course, if you happen not to know C, that is not very
helpful.  Again, I agree that the documentation needs to be
improved.

----------------------------------------------------------------------

Comment By: Daniel Lemire (lemire)
Date: 2004-02-27 08:41

Message:
Logged In: YES 
user_id=73205

Two things are lacking: 

1) assume is poorly explained or maybe implemented (?).  

You say it isn't local... right... then if I do assume(y>0); followed by 
assume(x>0); I would expect the system to know x>0 and y>0. It doesn't. As 
far as I can tell, each call to assume reset the set of assumptions to whatever 
you provide. The documentation mention something about the "current 
database". I think "assume" clears this database or ignores it. 

(C2) assume(y>0); 

(D2)                                [y > 0] 
(C3) assume(x>0); 

(D3)                                [x > 0] 
(C4) 

(In D3, I would expect [x>0,y>0] or something similar.) 

2) You are damn good if you can know from the documentation that "(a,b,c) 
evaluates a then b then c, and returns the value of c."  But that's good to know. 
I would like to see that much written up about it... 

Here's what I get from "Introduction to Expressions"... 

"""   Most things in MAXIMA are expressions.   A sequence of expressions 
can be made into an expression by separating them by commas and putting 
parentheses around them.   This is similar to the C comma expression.""" 

I guess I'm supposed to understand that "C comma" means... what... the C 
language? 

----------------------------------------------------------------------

Comment By: Daniel Lemire (lemire)
Date: 2004-02-27 08:40

Message:
Logged In: YES 
user_id=73205

Two things are lacking: 

1) assume is poorly explained or maybe implemented (?).  

You say it isn't local... right... then if I do assume(y>0); followed by 
assume(x>0); I would expect the system to know x>0 and y>0. It doesn't. As 
far as I can tell, each call to assume reset the set of assumptions to whatever 
you provide. The documentation mention something about the "current 
database". I think "assume" clears this database or ignores it. 

(C2) assume(y>0); 

(D2)                                [y > 0] 
(C3) assume(x>0); 

(D3)                                [x > 0] 
(C4) 

(In D3, I would expect [x>0,y>0] or something similar.) 

2) You are damn good if you can know from the documentation that "(a,b,c) 
evaluates a then b then c, and returns the value of c."  But that's good to know. 
I would like to see that much written up about it... 

Here's what I get from "Introduction to Expressions"... 

"""   Most things in MAXIMA are expressions.   A sequence of expressions 
can be made into an expression by separating them by commas and putting 
parentheses around them.   This is similar to the C comma expression.""" 

I guess I'm supposed to understand that "C comma" means... what... the C 
language? 

----------------------------------------------------------------------

Comment By: Stavros Macrakis (macrakis)
Date: 2004-02-23 19:11

Message:
Logged In: YES 
user_id=588346

What exactly do you think is lacking in this documentation?

You talk about the "syntax" -- do you mean the comma 
syntax (xxx, yyy)?  That is not specific to assume -- and 
beware, the assumptions are NOT local!  The comma syntax is 
documented under "Introduction to Expressions":

>>>>>
A sequence of expressions
can be made into an expression by separating them by 
commas and putting parentheses around them.   This is similar 
to the C comma expression.
<<<<<

In other words, (a,b,c) evaluates a then b then c, and 
returns the value of c.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=104933&aid=531469&group_id=4933

[Maxima-bugs] [ maxima-Bugs-531469 ] need better documentation for "assume"

Computer Algebra System written in Common Lisp

[Maxima-bugs] [ maxima-Bugs-531469 ] need better documentation for "assume"