Opened 13 months ago

Last modified 4 weeks ago

#29516 new enhancement

Cross-link documentation of sum, prod, product

Reported by: slelievre Owned by:
Priority: major Milestone: sage-9.4
Component: documentation Keywords: beginner, sum, prod, product
Cc: slelievre Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: u/gh-SaintNerevar/cross_link_documentation_of_sum__prod__product (Commits, GitHub, GitLab) Commit: 3277e9e588bfd94d9b52d7f6036481941f3fa416
Dependencies: Stopgaps:

Status badges

Description (last modified by gh-nikitamahoviya)

The documentation strings for sum, prod, and product should

  • link to each other
  • 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:

Change History (17)

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)
  • Keywords beginner added
  • 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

  • Branch set to u/gh-SaintNerevar/cross_link_documentation_of_sum__prod__product

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:

1b505dcAdd cross-links in documentation for `prod()`, `sum()` and `product()`
b551baaAdd 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:

3277e9eFix 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

Replying to slelievre:

The documentation strings for sum, prod, and product should

  • link to each other
  • 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.