Improve overview in documentation

[mgkurtz]

When I want to get a mathematical structure in Oscar, I often feel somewhat lost, how to find it in the docs. For the case of rings, they can either occur (a) in the “Rings” section in the docs hierarchy, (b) in some other section like “Number Theory” or “Commutative Algebra”, (c) in no section, or (d) not at all.

Personally, I would prefer all rings to appear in the “Rings” section. Quite likely, others prefer everything related to number theory in its own section. I hope, that maybe we could provide both? Maybe by adding overview doc pages with a list of all rings or pages with all number theory related topics? Or maybe by linking a page like “Orders” as a subsection of both “Rings” and “Number Theory” in the docs?

As a beginning, I created an overview over some of the basic rings and fields in Oscar. Of course the same could be done for groups and other topics. If you like the idea, I could work on that.

overview tables

Rings in Oscar

The rings ℤ, ℚ, ℚ̅, ℝ and ℂ

Symbol	Name in Oscar	Example Elements
ℤ	ZZ	$42=$ ZZ(42)
ℚ	QQ	$\frac{22}7=$ QQ(22, 7)
ℚ̅	QQBar	$\sqrt2=$ sqrt(QQBar(2)), $\varphi=$ roots(x^2+x+1, QQBar)[1] [1]
ℂ [2]	CC = CalciumField()	$\sqrt2=$ sqrt(CC(2)), $\varphi=$ roots(x^2+x+1, CC)[1], $1+2\mathrm i=$ CC(1+2im) [1]
ℝ [3]	RR = Nemo.RealField()	$\sqrt2\approx$ sqrt(RR(2)), $\varphi\approx$ roots(x^2+x+1, RR)[2], $0.1\approx$ RR("0.1"), $\frac23\pm0.001\approx$ RR(QQ(2,3)) + RR("0 +/- 0.001")
ℂ [4]	CC_ = Nemo.ComplexField()	$\sqrt2\approx$ sqrt(CC_(2)), $\varphi\approx$ roots(x^2+x+1, CC_)[2], $0.1+0.3\mathrm i\approx$ CC_("0.1")+CC_("0.3")*onei(CC_), $0.1+0.3\mathrm i\pm0.001\pm0.001\mathrm i\approx$ CC_("0.1 +/- 0.001") + CC_("0.3 +/- 0.001")*onei(CC_)

1: Assuming that x was defined by _, x = PolynomialField(ZZ) or the like.
2: We cannot provide CC as a constant, since (a) CalciumFields are not threadsafe and (b) you can give various options to CalciumField() to change behaviour.
3: Implements interval arithmetic. Not provided as a constant. The precision can be given as the argument to RealField().
4: Implements rectangle arithmetic. Not provided as a constant. The precision can be given as the argument to ComplexField().

The rings ℤ/nℤ, 𝔽ₚ, 𝔽_{pⁿ}, ℤₚ, ℚ̅ₚ, ℤ_{pⁿ}, ℚ_{pⁿ}

Let $p$ be a prime and $n$ a natural number. Additionaly choose some prec::Int as precision.

Symbol	Name in Oscar	Example Elements
ℤ/nℤ [1]	ZZnZ = ResidueRing(ZZ, n)	ZZnZ(42)
𝔽ₚ	FFp = GF(p)	FFp(42), FFp(ZZnZ(42)) [2]
𝔽_{pⁿ}	FFpn, o = FiniteField(p, n)	1+o, o^-42
ℤₚ	QQp = PadicField(p, prec)	QQp(QQ(2, 3))
ℚ̅ₚ	ZZp = MaximalOrder(QQp)	ZZp(QQ(p-1, p+1))
ℤ_{pⁿ}	QQpn, a = QadicField(p, n, prec)	QQpn(QQ(2, 3)), a^-42
ℚ_{pⁿ}	ZZpn = MaximalOrder(QQpn)	ZZpn(QQ(p-1, p+1)), ZZpn(a)^-42

1: Actually a special case of R/r1 in the table below.
2: In the case, this works mathematically, i. e. $p$ divides $n$.

Rings from other Rings

In the following, let R be some ring and r1,r2,r3 elements of R.

Symbol	Name in Oscar	Aliases	Example Elements
$R[x]$	Rx, x = PolynomialRing(R, "x")	PolynomialRing(R), R["x"], R[:x]	x^3 + 2x^2 + 3x + 4 = Rx([4, 3, 2, 1])
$R[x1,x2]$	Rx1x2, (x1, x2) = PolynomialRing(R, ["x1", "x2"])	PolynomialRing(R, 2), R["x1", "x2"], R[:x1, :x2]†	x1^3*x2 - 2x1*x2^3, see documentation
$Frac(R)$	FracR = FractionField(R)		FracR(42), FracR(r1) = r1//1, FracR(r1, r2) = r1//r2 [1]
$R/r1$	Rmodr1 = ResidueRing(R, r1)	quo(R, r1)[1]†, quo(R, ideal(R, r1))[1]†, quo(R, ideal(R, [r1]))[1]† [2]	Rmodr1(r2)
$R/(r1, r2)$	Rmodr1r2 = ?	quo(R, [r1, r2])[1], quo(R, ideal(R, [r1, r2]))[1]† [2]	Rmodr1r2(r3) [3]
$R[[x]]$	Rxx, xx = PowerSeriesRing(R, prec, "x") [4]		42 + O(xx^2), 2xx - 1 = Rxx(2x - 1)† = rel_series(R, [-1, 2], 2, prec, 0)
$R[x, 1/x]$	R_x, x_ = LaurentPolynomialRing(R, "x")		x + 2 + 3x^-1 + 4x^-2 = R_x(Rx([4, 3, 2, 1]), -2)
$R[[x, 1/x]]$	R_xx, xx_ = LaurentSeriesRing(R, prec, "x") [4]		42 + O(xx_^2), 2xx_^-1 - 1 = Rxx(2x_^-1 - 1)†

†: Currently not implemented/only implemented in some cases.
1: Caveat: The FracR constructor does not reduce automatically.
2: The second return value is the residue map.
3: Caveat: Elements will not be normalized automatically.
4: Also documented here.

To be continued

…

some pages not linked or existent in Oscar docs

In the tables above, I have kept the trailing / for all pages from Nemo and AbstractAlgebra, not linked in the Oscar docs. Additionally AlgAss from Hecke does not have its own docs page at all.

What do you think about adding such overviews to the docs? And of course about where to put pages, including the missing pages, in the docs?