Opened 3 years ago

Closed 2 years ago

#22386 closed enhancement (fixed)

Rearrange the table of contents of the reference manual

Reported by: klee Owned by:
Priority: minor Milestone: sage-7.6
Component: documentation Keywords: days85
Cc: Merged in:
Authors: Kwankyu Lee Reviewers: Julian Rüth, Dima Pasechnik
Report Upstream: N/A Work issues:
Branch: bf2278c (Commits) Commit: bf2278c2fd0b3be9e6e1603952f63098b0e5e955
Dependencies: Stopgaps:

Description (last modified by klee)

As I see it, the current table of contents of the reference manual needs some rearrangement.

In the patch, I tried to arrange the mathematics topics such that those basic and having wider interest come first and those more advanced and having narrow interest come later.

Change History (34)

comment:1 Changed 3 years ago by klee

  • Branch set to u/klee/22386

comment:2 Changed 3 years ago by git

  • Commit set to 606ac666e3d8d2b22802a1d4bb1e180600efc51d

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

606ac66Rearrange the TOC

comment:3 Changed 3 years ago by klee

  • Description modified (diff)

comment:4 Changed 3 years ago by klee

  • Status changed from new to needs_review

comment:5 follow-up: Changed 3 years ago by jhpalmieri

For non-mathematicians, the integers, rationals, reals, and complexes are going to be more familiar and useful than monoids, groups, semirings, and algebras. So moving the latter earlier does not put the topics with wider interest first.

comment:6 in reply to: ↑ 5 ; follow-up: Changed 3 years ago by klee

Replying to jhpalmieri:

For non-mathematicians, the integers, rationals, reals, and complexes are going to be more familiar and useful than monoids, groups, semirings, and algebras. So moving the latter earlier does not put the topics with wider interest first.

I agree. I put that there because I thought "algebraic structures" are more mathematically *basic* than "rings and fields". Where do you think is better place for "algebraic structures"?

The purpose of this ticket is to improve the TOC than to make it perfect, which I think is impossible as we all may have different ideas...

comment:7 in reply to: ↑ 6 Changed 3 years ago by jhpalmieri

Replying to klee:

Replying to jhpalmieri:

For non-mathematicians, the integers, rationals, reals, and complexes are going to be more familiar and useful than monoids, groups, semirings, and algebras. So moving the latter earlier does not put the topics with wider interest first.

I agree. I put that there because I thought "algebraic structures" are more mathematically *basic* than "rings and fields". Where do you think is better place for "algebraic structures"?

Where it was before, after basic rings and fields and linear algebra.

Last edited 3 years ago by jhpalmieri (previous) (diff)

comment:8 Changed 3 years ago by git

  • Commit changed from 606ac666e3d8d2b22802a1d4bb1e180600efc51d to 24fcda33f46f121b68022f7c8512dc4a4d459750

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

24fcda3Put algebraic structures behind basic rings

comment:9 Changed 3 years ago by git

  • Commit changed from 24fcda33f46f121b68022f7c8512dc4a4d459750 to da38c8bf7396d44b67f17de2db3cf72444db64a0

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

da38c8bPut algebraic structures behind linear algebra

comment:10 Changed 3 years ago by wuthrich

Most things in elliptic curves is number theory not algebraic geometry. Best change the title of that new section to Arithmetic geometry and put it after number theory.

comment:11 Changed 3 years ago by klee

I did not intend to go down to that level, but let's do that. I think we need to keep "Algebraic Geometry" section. How about this?

Algebraic Geometry
--------------------
Schemes
Plane Curves

Number Theory
---------------
...

Arithmetic Geometry
---------------------

Elliptic and Hyperelliptic Curves

Then do you think "Modular Abelian Varieties" also should go under "Arithmetic Geometry"?

Last edited 3 years ago by klee (previous) (diff)

comment:12 Changed 3 years ago by wuthrich

I did not mean to split it up further. Just replace "Algebraic geometry" with "Arithmetic geometry" or "Algebraic and arithmetic geometry". Then it is clear that this section will contain lots of number theory, too. No I would not move modular abelian varieties.

comment:13 Changed 3 years ago by klee

I think it is good to have both "Algebraic Geometry" and "Arithmetic Geometry", and to keep

Schemes

Plane Curves

under "Algebraic Geometry" section. Why not?

Last edited 3 years ago by klee (previous) (diff)

comment:14 Changed 3 years ago by git

  • Commit changed from da38c8bf7396d44b67f17de2db3cf72444db64a0 to 6038cf7299d6793c549b30b86b41603a08c0b61c

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

608f015Add arithmetic geometry section
92043c9Combine algebraic geometry and arithmetic geometry section
6038cf7Make new special topics section

comment:15 Changed 3 years ago by klee

  • Authors set to Kwankyu Lee

It is not easy to separate out algebraic geometry from arithmetic geometry in Sage. So I follow wuthrich's suggestion.

comment:16 Changed 3 years ago by dimpase

Why would numerical optimisation be in "Special topics", but "SAT solvers" not? (these are close to each other topics, if you asked me).

And "numerical" is misleading in itself---for instance we have arbitrary precision LP solvers which output exact answers, and this is very close to other polyhedral computation tools.

comment:17 follow-up: Changed 3 years ago by jsrn

Good idea to review this index.

Some thoughts:

  • Does it really make sense that Cryptography is not listed under the same headline as Coding Theory? Why not put Cryptography, Symbolic Logic, and SAT Solvers under Discrete Mathematics?
  • I now realise that clicking on Basic Infrastructure goes to an index with the immensely useful list of Mathematical Data Structures. Perhaps the headline should therefore instead be Core infrastructure and Mathematical Data structures?
  • What about putting Other Algebraic Structures after Discrete Mathematics?
  • What about putting Calculus earlier, right after Linear Algebra -- most students will use Sage for calculus.
  • I agree with Dima that Numberical Optimization is a weird category that I can't figure out where should go, but that it is semantically linked to SAT Solvers. Perhaps they should simply have their own headline called Solvers or something.

comment:18 Changed 3 years ago by dimpase

Numerical Optimization should be split into parts. It's a weird mix of discrete optimization (Knapsack)--- out of place there, as it's not "numerical", but discrete, with numerical root finding, least squares approximation, and optimization of functions of one variable, and linear (LP), integer linear (ILP)---again, a discrete problem--- and semidefinite programming (SDP).

By right, LP and SDP should be put into its own "Convex optimization", Knapsack and ILP into "Discrete optimization", and univariate things into "Calculus/numerical methods". I also think that the code for the latter and for Knapsack should be split into separate files - currently they are all dumped in numerical/optimize.py, which also contains a little function to demonstrate the direct use of cvxopt LP solver---the latter should also be somewhere else.

Note that ILP and LP are solved by the same frontend, specifying appropriate parameters, so I don't quite know how to structure the corresponding documentation. (Probably one would have to link to .rst files that further point at the concrete code documentation?)

comment:19 Changed 3 years ago by git

  • Commit changed from 6038cf7299d6793c549b30b86b41603a08c0b61c to bc6ff6a8e8aa207954d0ff3d90f5cb55f1d0ba2b

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

bc6ff6aPut calculus right after linear algebra

comment:20 in reply to: ↑ 17 ; follow-up: Changed 3 years ago by klee

Replying to jsrn:

Does it really make sense that Cryptography is not listed under the same headline as Coding Theory? Why not put Cryptography, Symbolic Logic, and SAT Solvers under Discrete Mathematics?

I moved Symbolic Logic to under Discrete Mathematics as suggested.

It is controversial if we could see cryptography as a branch of discrete mathematics in traditional sense. I personally do not agree.

I now realise that clicking on Basic Infrastructure goes to an index with the immensely useful list of Mathematical Data Structures. Perhaps the headline should therefore instead be Core infrastructure and Mathematical Data structures?

The title Basic infrastructure is short and appropriate to keep the list under it. I would keep it.

What about putting Other Algebraic Structures after Discrete Mathematics?

Done.

What about putting Calculus earlier, right after Linear Algebra -- most students will use Sage for calculus.

Done. Also Probability and statistics still follows it.

I agree with Dima that Numberical Optimization is a weird category that I can't figure out where should go, but that it is semantically linked to SAT Solvers. Perhaps they should simply have their own headline called Solvers or something.

Numerical optimization section seems to require a rearrangement on its own level. This ticket is not intended for that. I will open a separate one so that further discussions could be carried on there.

comment:21 Changed 3 years ago by klee

Now for Numerical Optimization section reorganization, we have

https://trac.sagemath.org/ticket/22472

comment:22 in reply to: ↑ 20 Changed 3 years ago by jsrn

Thanks for the changes. I agree that the Numerical Optimization issues can be considered as beyond this ticket.

Replying to klee:

Replying to jsrn:

Does it really make sense that Cryptography is not listed under the same headline as Coding Theory? Why not put Cryptography, Symbolic Logic, and SAT Solvers under Discrete Mathematics?

I moved Symbolic Logic to under Discrete Mathematics as suggested.

It is controversial if we could see cryptography as a branch of discrete mathematics in traditional sense. I personally do not agree.

I see your point, and I won't insist on anything. One could, however, see the role of cryptography in the mathematics software Sage as being the discrete mathematics side of cryptography. There is no numerical side to crypto, for instance.

I now realise that clicking on Basic Infrastructure goes to an index with the immensely useful list of Mathematical Data Structures. Perhaps the headline should therefore instead be Core infrastructure and Mathematical Data structures?

The title Basic infrastructure is short and appropriate to keep the list under it. I would keep it.

It is certainly short but not appropriate. The heading "Basic infrastructure" sounds like something I shouldn't care about as a user (together with Parent, Element, the coercion framework and all that jazz). In complete opposition to this, it is *immensely* useful for a user to know the basic mathematical data structures. Besides, would you really look under the heading Basic Infrastructure for Subset?

comment:23 Changed 3 years ago by git

  • Commit changed from bc6ff6a8e8aa207954d0ff3d90f5cb55f1d0ba2b to 00724aeb6a14c6738e9f12a27f46fc283ef3ceba

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

2b13fe5Add basic structures heading
00724aeRelocate basic structures section

comment:24 Changed 3 years ago by klee

I moved Sets to a new Mathematcal Structures section. This also put Monoids and others back before Discrete Mathematics. Leave comments if you do not like this.

comment:25 Changed 3 years ago by git

  • Commit changed from 00724aeb6a14c6738e9f12a27f46fc283ef3ceba to 8f272041351e1f3caa02a5df564f93816db15862

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

bdbce74Merge branch 'develop' into trac22386
8f27204Put back conf.py to a symlink

comment:26 Changed 3 years ago by dimpase

OK, I'd like to propose few more changes.

  • rename: Calculus -> Calculus and Analysis
  • move Numerical Optimization to Calculus and Analysis
  • move Cryprography and SAT Solvers to Discrete Mathematics
  • remove the heading Special Topics (as it's empty after these moves).

Otherwise it looks better already...

comment:27 Changed 3 years ago by git

  • Commit changed from 8f272041351e1f3caa02a5df564f93816db15862 to a7ed64ee3de7ba25a8a664396204ec7ad7e66003

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

a7ed64eRemove unpopular special topics section

comment:28 Changed 3 years ago by pbruin

Typo in one of the section titles: please change "Arithemtic" to "Arithmetic".

comment:29 Changed 3 years ago by git

  • Commit changed from a7ed64ee3de7ba25a8a664396204ec7ad7e66003 to bf2278c2fd0b3be9e6e1603952f63098b0e5e955

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

bf2278cCorrect a typo

comment:30 Changed 3 years ago by saraedum

  • Reviewers set to Julian Rüth
  • Status changed from needs_review to positive_review

Looks good to me, unless you want to make further changes. I think that this improves the situation quite a bit.

comment:31 Changed 3 years ago by klee

Thank you and all that have left comments!

comment:32 Changed 3 years ago by dimpase

  • Reviewers changed from Julian Rüth to Julian Rüth, Dima Pasechnik

comment:33 Changed 3 years ago by saraedum

  • Keywords days85 added

comment:34 Changed 2 years ago by vbraun

  • Branch changed from u/klee/22386 to bf2278c2fd0b3be9e6e1603952f63098b0e5e955
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.