Revision history [back]

In many settings,

• the square function $x \mapsto x^2$ is mostly two-to-one, except at zero
• given $y$ in some ring $R$ with a product operation, there can be zero, one or two values of $x$ for which $x^2 = y$ (i.e. $x \cdot x = y$). When two such $x$ exist, they are opposites of each other, and called "the square roots of $y$"
• in many cases there is a way to extend the ring $R$ to a bigger ring $S$ where all nonzero elements have two square roots. For example if $R$ is the field $\mathbb{R}$ of real numbers then we can take $S$ to be the field $\mathbb{C}$ of complex numbers

When working with the real numbers, - zero is its own unique square root - positive numbers have two square roots in the real numbers - negative numbers have no square root in the real numbers, but two square roots in the complex numbers

The two square roots of a positive number being opposite to each other, one is negative and one is positive. Since we find positive numbers more "natural", we often decide to give the positive root a special role and to call it "square root of $y$", which could be thought of as short for "the positive square root of $y$". The other root is then referred to as "minus square root of $y$".

In computer algebra systems, one has to decide what to do when the user asks for square roots a command such as sqrt(y) or y.sqrt():

• regarding where to look for square roots:
  • stay in the ring where $y$ lives
  • or extend it, if necessary, to a larger ring where square roots exist, if they did not in the ring where $y$ lives
• regarding how many square roots to return:
  • return all the square roots of its argument,
  • or return one particular square root (e.g. the positive one when that makes sense)?

I suppose the documentation you are referring to is the SageMath documentation for sage.structure.element.CommutativeRingElement.sqrt.

It explains that y.sqrt() takes two optional parameters, extend to decide whether to look for square roots in a larger ring if necessary, and all to decide whether to return all square roots or a preferred square root when there is one. There's an additional optional parameter name to name the extra generator of the new ring if you decide to extend.