Opened 13 months ago

# Cross-link documentation of sum, prod, product

Reported by: Owned by: slelievre major sage-9.4 documentation beginner, sum, prod, product slelievre N/A u/gh-SaintNerevar/cross_link_documentation_of_sum__prod__product 3277e9e588bfd94d9b52d7f6036481941f3fa416

The documentation strings for `sum`, `prod`, and `product` should

• mention the Python builtin `sum` vs Sage's `symbolic_sum`

A tutorial could describe sum and product functions more in-depth, mentioning more recipes, subtleties, variations, and related concepts:

• weighted sums, linear combinations
• the `mean` function
• sum and product with numpy arrays
• numpy's cumulative sum function
• the `product` function from `itertools`
• product, dot-product, cartesian product, tensor product

Related user questions:

### comment:1 Changed 8 months ago by mkoeppe

• Milestone changed from sage-9.2 to sage-9.3

### comment:2 Changed 8 months ago by slelievre

• Description modified (diff)
• Type changed from PLEASE CHANGE to enhancement

### comment:3 Changed 8 months ago by slelievre

• Description modified (diff)

### comment:4 Changed 8 months ago by slelievre

• Description modified (diff)

### comment:5 Changed 3 months ago by mkoeppe

• Milestone changed from sage-9.3 to sage-9.4

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

### comment:6 Changed 8 weeks ago by gh-nikitamahoviya

• Description modified (diff)

### comment:7 Changed 7 weeks ago by gh-SaintNerevar

I'd like to fix the first two points. I've looked around in the codebase and what I understand from the description is that docstrings in `sage.misc.functional.symbolic_sum` (aliased as `sum`), `sage.misc.functional.symbolic_prod` (aliased as `product`) and `sage.misc.misc_c.prod` should be linked to each other. Also, the docstring for `symbolic_sum` is a little confusing and the distinction between Sage's `symbolic_sum` and Python's `sum` must be made clear. Is this correct? I'm new to Sage so please tell me if I've understood this wrong, in which case, any references will be appreciated.

### comment:8 Changed 7 weeks ago by slelievre

That is correct. Looking forward to your contribution.

### comment:9 Changed 7 weeks ago by gh-arvganesh

Hi, I'm new to Sage. Would I be able to contribute to this as well?

### comment:10 Changed 7 weeks ago by gh-SaintNerevar

I've fixed the first two points. Review needed. I'm not sure how to link the commits like I've seen in other tickets.

Last edited 7 weeks ago by gh-SaintNerevar (previous) (diff)

### comment:11 Changed 7 weeks ago by slelievre

• Commit set to b551baa572ee0edfb42126f8fb5801422be30a8f

Please fix the repeated typo `sybmolic` for `symbolic`.

New commits:

 ​1b505dc `Add cross-links in documentation for `prod()`, `sum()` and `product()`` ​b551baa `Add Note to clarify Sage's `symbolic_sum()` vs Python's `sum()`.`

### comment:12 Changed 7 weeks ago by slelievre

Trac automatically links to the commits. Sometimes this takes a while and links appear with the next comment that gets posted. They ended up appearing alongside my comments.

### comment:13 Changed 7 weeks ago by git

• Commit changed from b551baa572ee0edfb42126f8fb5801422be30a8f to 3277e9e588bfd94d9b52d7f6036481941f3fa416

Branch pushed to git repo; I updated commit sha1. New commits:

 ​3277e9e `Fix typo`

### comment:14 Changed 7 weeks ago by gh-SaintNerevar

Thanks for the explanation! I fixed the typos.

### comment:15 Changed 4 weeks ago by gh-vemulasaikrishna03

```Code highlighting:
{{{#!python sum finding
from builtins import sum as python_sum
python_sum([2,3,4])

}}}
```

### comment:16 in reply to: ↑ description Changed 4 weeks ago by gh-vemulasaikrishna03

The documentation strings for `sum`, `prod`, and `product` should

• mention the Python builtin `sum` vs Sage's `symbolic_sum`

A tutorial could describe sum and product functions more in-depth, mentioning more recipes, subtleties, variations, and related concepts:

• weighted sums, linear combinations
• the `mean` function
• sum and product with numpy arrays
• numpy's cumulative sum function
• the `product` function from `itertools`
• product, dot-product, cartesian product, tensor product

Related user questions:

```  from builtins import sum as python_sum
python_sum([2,3,4])

```

### comment:17 Changed 4 weeks ago by slelievre

Make sure the alternative suggestion more transparently matches the original:

```         Also, only a limited number of functions are recognized in symbolic products::

sage: product(valuation(n, 2), n, 1, 5)
Traceback (most recent call last):
...
TypeError: unable to convert n to an integer

Again, use ``prod()``::

-            sage: prod(valuation(n, 2) for n in range(1, 6))
+            sage: prod(valuation(n+1, 2) for n in range(5))
0
```

Maybe even improve the example to one that returns a nonzero value:

```         Also, only a limited number of functions are recognized in symbolic products::

-            sage: product(valuation(n, 2), n, 1, 5)
+            sage: product(valuation(2*n, 2), n, 1, 5)
Traceback (most recent call last):
...
TypeError: unable to convert n to an integer

Again, use ``prod()``::

-            sage: prod(valuation(n, 2) for n in range(1, 6))
-            0
+            sage: prod(valuation(2*n, 2) for n in range(1, 6))
+            6
```

Make sure to avoid trailing whitespace (the two spaces after `0`.)

Note: See TracTickets for help on using tickets.