Allowed assumptions poorly documented and missing validation of assumptions

[HDembinski]

The Symbol class allows one to specify assumptions. Assumptions are frequently needed in engineering and physics to express that certain variables are real and positive (e.g. mass of a particle). Which assumptions are understood by Sympy is not well documented and mistyping the assumptions does not cause an error, which is bad.

Documentation issues

1. Docstring of function symbols

The docstring mentions assumptions and shows integer and real in examples, but does not list all possible assumptions nor does it point to the place where such a list can be found (the latter would be better, the assumptions should be documented in the Symbol class, I suppose).

2. Docstring of class Symbol

The docstring mentions assumptions in the class docstring but does not list all possible assumptions. The docstring of assumptions0 (why the 0 at the end?) also does not list all possible assumptions, they only appear by chance in the example code.

3. Searching for "assumption" in Sympy docs yields results, but not on first hit

When you search in the Sympy online docs for the string "assumption" you find these hits (in that order):

• https://docs.sympy.org/latest/modules/assumptions/index.html?highlight=assumption#module-sympy.assumptions
  The first hit is very confusing and not what one was searching for.
• https://docs.sympy.org/latest/modules/core.html?highlight=assumption#module-sympy.core.assumptions
  The second hit is finally listing all possible assumptions. This is what the user wants to see.
• https://docs.sympy.org/latest/modules/assumptions/index.html?highlight=assumption
  This is again a variation of the first hit and therefore not useful.

Validation issues

The class Symbol does not validate the assumptions. One can pass arbitrary arguments. The user is not informed about typos, this is bad.

>>> from sympy import Symbol

>>> Symbol("x", real=True).assumptions0 # OK, real is a valid assumption
{'real': True, 'complex': True, 'imaginary': False, 'hermitian': True, 'infinite': False, 'finite': True, 'commutative': True, 'extended_real': True}
>>> Symbol("x", is_real=True).assumptions0 # BAD, is_real is not a valid assumption, this should raise an error
{'is_real': True, 'commutative': True}

[oscarbenjamin]

I did write a lengthy page for the docs about assumptions here: #20090

I think it needs to be reorganised though.

[HDembinski]

@oscarbenjamin Glad to see your contribution, I quickly read over the new docs and this is very much what I feel is missing in the user guide. Complementary to that I think the docstrings need to be improved as well to point the user to the right info.

[oscarbenjamin]

I've merged #20090.

It should appear in the dev docs once they are updated.

Which docstrings should be changed to point to that information?

[oscarbenjamin]

The link to those added docs are here:
https://docs.sympy.org/dev/guides/assumptions.html

There is still improvement that can be done on those but I think it's just good to have something up.