add solve_output to explanations

[smichr]

References to other Issues or PRs

Brief description of what is fixed or changed

Other comments

Release Notes

• other
  • an explanation about solve output was been added

[sympy-bot]

✅

Hi, I am the SymPy bot (v167). I'm here to help you write a release notes entry. Please read the guide on how to write release notes.

Your release notes are in good order.

Here is what the release notes will look like:

• other
  • an explanation about solve output was been added (#23902 by @smichr)

This will be added to https://github.com/sympy/sympy/wiki/Release-Notes-for-1.12.

Click here to see the pull request description that was parsed.

<!-- Your title above should be a short description of what
was changed. Do not include the issue number in the title. -->

#### References to other Issues or PRs
<!-- If this pull request fixes an issue, write "Fixes #NNNN" in that exact
format, e.g. "Fixes #1234" (see
https://tinyurl.com/auto-closing for more information). Also, please
write a comment on that issue linking back to this pull request once it is
open. -->


#### Brief description of what is fixed or changed


#### Other comments


#### Release Notes

<!-- Write the release notes for this release below between the BEGIN and END
statements. The basic format is a bulleted list with the name of the subpackage
and the release note for this PR. For example:

* solvers
  * Added a new solver for logarithmic equations.

* functions
  * Fixed a bug with log of integers.

or if no release note(s) should be included use:

NO ENTRY

See https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more
information on how to write release notes. The bot will check your release
notes automatically to see if they are formatted correctly. -->

<!-- BEGIN RELEASE NOTES -->
* other
  * an explanation about solve output was been added
<!-- END RELEASE NOTES -->

Update

The release notes on the wiki have been updated.

[github-actions]

Benchmark results from GitHub Actions

Lower numbers are good, higher numbers are bad. A ratio less than 1
means a speed up and greater than 1 means a slowdown. Green lines
beginning with + are slowdowns (the PR is slower then master or
master is slower than the previous release). Red lines beginning
with - are speedups.

Significantly changed benchmark results (PR vs master)

Significantly changed benchmark results (master vs previous release)

       before           after         ratio
     [8ce582b4]       [f0154339]
-      3.78±0.2ms       1.64±0.2ms     0.43  solve.TimeSparseSystem.time_linear_eq_to_matrix(20)
-      7.19±0.2ms       2.40±0.2ms     0.33  solve.TimeSparseSystem.time_linear_eq_to_matrix(30)

Full benchmark results can be found as artifacts in GitHub Actions
(click on checks at the top of the PR).

[oscarbenjamin]

This guide should be referenced in the solve docstring. It should probably also link to and be linked from the other solving guides.

[oscarbenjamin]

@bertiewooster @asmeurer can you review this docs guide?

[smichr]

I am updating the solve docstring that had way too many examples, many of which are/should be handled in the test_solve_args -- it is too much information.

@oscarbenjamin , please have a read through solve_output again. I really don't want to wander off into solving/substitution methods which are best left for tutorials. Let's keep explanations succinct and focussed.

I don't know how to create a link to another document -- the wiki for documentation tells how to link to objects, not documents (that I could find). I will leave cross referencing to those more adept at this.

[bertiewooster]

This is a helpful summary of the many output formats of solve. Big-picture suggestions are

1. Make the six numbered sections appear in Furo table of contents for the page (right navbar) for easy navigation. I think that would require e.g. h2 headings for the six sections. For practical reasons, that also means each section header would fairly short.
2. I'm wondering whether it's (more) helpful to users to list the input types, then tell them what the output format will be. Or maybe do both: keep it organized by the six output types, and have a list (or table?) of inputs and what their output format would be?

For 1) above, a possible format is e.g.

1. An empty list (or set)

Indicates that no solution was found.

For 2) above, format could be

No solution was found

An empty list (or set)

[smichr]

Thanks for the comments, @bertiewooster . I have made edits. If you have any formatting suggestions, feel free to make a PR to this.

Any other comments welcome, too.

[smichr]

Any final comments?

[bertiewooster]

Thanks for making the six output types into headings so they appear in the page's table of contents (right navbar).

One implication I didn't consider was that those headings appear as sub-bullets on the Explanations main page because that table of contents (.. toctree::) has :maxdepth: 2. My inclination is to limit to :maxdepth: 1 so that only the pages, not also their contents (headings in the page), will be on the Explanations main page, because

• it's now 2+ screens tall of my laptop, and
• a visitor could easily get bogged down in a long, nested list and give up on finding relevant content

I also set :maxdepth: 1 for the Guides main page for the same reason.

[smichr]

Any last comments?

[bertiewooster]

Minor suggestion: Rephrase page title to "Solve Output Varieties" (or "Solve Output Variations"?) so that someone scanning the table of contents on the Explanations page encounters the key word "solve" first. I believe this is also important for visitors using screen readers: if the start of the link text isn't what they're interested in, they may direct their screen reader to jump to the next link.

[smichr]

I will stop tests and squash to a single commit then auto-merge if there is no objection.

[smichr]

Well...now the document is not showing up in the index.

[bertiewooster]

It seems like the file you added, solve_output.rst, is no longer in the branch

[bertiewooster]

Sphinx failed:

The docs build failed with the following errors:
/home/runner/work/sympy/sympy/doc/src/explanation/solve_output.rst:125: WARNING: py:func reference target not found: Equality

The cited line contains :func:`~.Equality` .

I believe the problem is that Equality is a class, so it would need to be :class:`~.Equality` instead.

[bertiewooster]

Suggestions for the solve() docstring

[sympy-bot]

🟠

Hi, I am the SymPy bot (v167). I've noticed that some of your commits add or delete files. Since this is sometimes done unintentionally, I wanted to alert you about it.

This is an experimental feature of SymPy Bot. If you have any feedback on it, please comment at sympy/sympy-bot#75.

The following commits add new files:

• 7fb4484:
  • doc/src/explanation/solve_output.rst

If these files were added/deleted on purpose, you can ignore this message.

[smichr]

@bertiewooster , you suggested ":func:~.subs" -- is that going to work? subs is a method, not a function.

[smichr]

@bertiewooster , it wouldn't let me add your changes to a single commit, so I will squash those this evening and commit unless there are further comments. Note, that the subs reference was changed since (as I expected) this generated a Sphinx error.

[bertiewooster]

As it happens, SymPy's documentation has this exact example (the backticks may not appear correctly below, so recommend you copy from that page):

``:obj:`~sympy.core.basic.Basic.subs```

where :obj: can refer to any kind of object, so it gets around subs being a method instead of a function. (You could use the explicit option :method: instead; here's Sphinx's complete list of Python roles.) And you have to specify which subs because there's more than one, for example there's also sympy.physics.vector.dyadic.Dyadic.subs.