# Formal modules generated by polyhedra¶

class sage.geometry.polyhedron.modules.formal_polyhedra_module.FormalPolyhedraModule(base_ring, dimension, basis, category)

Class for formal modules generated by polyhedra.

It is formal because it is free – it does not know about linear relations of polyhedra.

A formal polyhedral module is graded by dimension.

INPUT:

• base_ring – base ring of the module; unrelated to the base ring of the polyhedra

• dimension – the ambient dimension of the polyhedra

• basis – the basis

EXAMPLES:

sage: from sage.geometry.polyhedron.modules.formal_polyhedra_module import FormalPolyhedraModule
sage: def closed_interval(a,b): return Polyhedron(vertices=[[a], [b]])


A three-dimensional vector space of polyhedra:

sage: I01 = closed_interval(0, 1); I01.rename("conv(, )")
sage: I11 = closed_interval(1, 1); I11.rename("{}")
sage: I12 = closed_interval(1, 2); I12.rename("conv(, )")
sage: basis = [I01, I11, I12]
sage: M = FormalPolyhedraModule(QQ, 1, basis=basis); M
Free module generated by {conv(, ), {}, conv(, )} over Rational Field
sage: M.get_order()
[conv(, ), {}, conv(, )]


A one-dimensional subspace; bases of subspaces just use the indexing set $$0, \dots, d-1$$, where $$d$$ is the dimension:

sage: M_lower = M.submodule([M(I11)]); M_lower
Free module generated by {0} over Rational Field
sage: M_lower.print_options(prefix='S')
sage: M_lower.is_submodule(M)
True
sage: x = M(I01) - 2*M(I11) + M(I12)
sage: M_lower.reduce(x)
[conv(, )] + [conv(, )]
sage: M_lower.retract.domain() is M
True
sage: y = M_lower.retract(M(I11)); y
S
sage: M_lower.lift(y)
[{}]


Quotient space; bases of quotient space are families indexed by elements of the ambient space:

sage: M_mod_lower = M.quotient_module(M_lower); M_mod_lower
Free module generated by {conv(, ), conv(, )} over Rational Field
sage: M_mod_lower.print_options(prefix='Q')
sage: M_mod_lower.retract(x)
Q[conv(, )] + Q[conv(, )]
sage: M_mod_lower.retract(M(I01) - 2*M(I11) + M(I12)) ==  M_mod_lower.retract(M(I01) + M(I12))
True

degree_on_basis(m)

The degree of an element of the basis is defined as the dimension of the polyhedron.

INPUT:

• m – an element of the basis (a polyhedron)

EXAMPLES:

sage: from sage.geometry.polyhedron.modules.formal_polyhedra_module import FormalPolyhedraModule
sage: def closed_interval(a,b): return Polyhedron(vertices=[[a], [b]])
sage: I01 = closed_interval(0, 1); I01.rename("conv(, )")
sage: I11 = closed_interval(1, 1); I11.rename("{}")
sage: I12 = closed_interval(1, 2); I12.rename("conv(, )")
sage: I02 = closed_interval(0, 2); I02.rename("conv(, )")
sage: M = FormalPolyhedraModule(QQ, 1, basis=[I01, I11, I12, I02])


We can extract homogeneous components:

sage: O = M(I01) + M(I11) + M(I12)
sage: O.homogeneous_component(0)
[{}]
sage: O.homogeneous_component(1)
[conv(, )] + [conv(, )]


We note that modulo the linear relations of polyhedra, this would only be a filtration, not a grading, as the following example shows:

sage: X = M(I01) + M(I12) - M(I02)
sage: X.degree()
1

sage: Y = M(I11)
sage: Y.degree()
0