Improvements for projection into affine hull

[kliem]

This ticket renames affine_hull of Polyhedron_base to affine_hull_projection and adds a deprecation warning.

Before, this function was hard to recognize, as by the name one expected to obtain the affine hull and not the polyhedron projected into it.

Also this ticket makes use of #28724 to simplify construction: We determine a transformation matrix A and a vector b and basically return A*P - b, where P is the polyhedron.

CC: @jplab @LaisRast

Component: geometry

Keywords: polyhedra, affine hull

Author: Jonathan Kliem

Branch/Commit: 32e59c0

Reviewer: Laith Rastanawi

Issue created by migration from https://trac.sagemath.org/ticket/29326

[kliem]

Branch: public/29326

[kliem]

Description changed:

--- 
+++ 
@@ -1,5 +1,5 @@
-This ticket renames `affine_hull` of `Polyhedron_base` to `in_affine_hull` and adds a deprecation warning.
+This ticket renames `affine_hull` of `Polyhedron_base` to `affine_hull_projection` and adds a deprecation warning.
 
-Before, this function was hard to find, as an affine hull of a polyhedron usually defined to be the smallest affine subspace containing the polyhedron.
+Before, this function was hard to recognize, as by the name one expected to obtain the affine hull and not the polyhedron projected into it.
 
-Also this ticket makes use of #28724 to simplify this construction: We determine a transformation matrix `A` and a vector `b` and basically return `A*P - b`, where `P` is the polyhedron.
+Also this ticket makes use of #28724 to simplify construction: We determine a transformation matrix `A` and a vector `b` and basically return `A*P - b`, where `P` is the polyhedron.

[kliem]

New commits:

f9e1283	simplified projection into affine_hull
6d12f79	rename `affine_hull` to `affine_hull_projection`

[kliem]

Commit: 6d12f79

[LaisRast]

Reviewer: Laith Rastanawi

[LaisRast]

comment:2

• In polyhedra_quickref.rst:

-    :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.affine_hull_projection` | constructs an affinely equivalent full dimensional polyhedra
+    :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.affine_hull_projection` | constructs an affinely equivalent full-dimensional polyhedron

• Make the second paragraph in the docstring look like a one paragraph.
• In the "OUTPUT" section:

-        A full-dimensional polyhedron or a linear transformation,
+        A full-dimensional polyhedron or an affine transformation,
        depending on the parameter ``as_affine_map``.

• Remove the following line from "TODO" section:

-            - allow to return ``as_affine_map=True`` for default setting

• The new name affine_hull_projection is definitively better than the old name, but I am not sure if this is the best name. How about full_dimensional_copy? I am also not sure about this suggestion. So maybe we need another opinion.

[kliem]

comment:3

The name has been discussed in https://groups.google.com/forum/#!topic/sage-devel/MEmAIPDPcHY
If you want to propose a different name, please do so there, so that everyone is involved.

[LaisRast]

comment:4

Replying to @kliem:

The name has been discussed in https://groups.google.com/forum/#!topic/sage-devel/MEmAIPDPcHY
If you want to propose a different name, please do so there, so that everyone is involved.

I just wanted to hear some other opinions, and since many people already agreed for the name, I am also fine with it.