Introduce snake case function incidence_matrix (#4245)

* introduced incidence_matrix and added docs

* replaced IncidenceMatrix with incidence_matrix in docstrings

* replaced IncidenceMatrix with incidence_matrix in tests

* added method incidence_matrix(::SubObjectIterator)

* adjusted IncidenceMatrix to incidence_matrix in test/book

* added tests for new methods of incidence_matrix

* applied suggestions for incidence_matrix from github

* formatted PolyhedralGeometry/helpers.jl

* keep IncidenceMatrix call in booktests

---------

Co-authored-by: Benjamin Lorenz <benlorenz@users.noreply.github.com>

docs/src/PolyhedralGeometry/intro.md

@@ -159,7 +159,13 @@ Some methods will require input or return output in form of an `IncidenceMatrix`
 IncidenceMatrix
 ```
 
-From the example it can be seen that this type supports `julia`'s matrix functionality. There are also functions to retrieve specific rows or columns as a `Set` over the non-zero indices.
+The unique nature of the `IncidenceMatrix` allows for different ways of construction:
+
+```@docs
+incidence_matrix
+```
+
+From the examples it can be seen that this type supports `julia`'s matrix functionality. There are also functions to retrieve specific rows or columns as a `Set` over the non-zero indices.
 
 ```@docs
 row(i::IncidenceMatrix, n::Int)

experimental/Schemes/src/ToricBlowups/constructors.jl

@@ -137,7 +137,7 @@ julia> rs = [1 1; -1 1]
   1  1
  -1  1
 
-julia> max_cones = IncidenceMatrix([[1, 2]])
+julia> max_cones = incidence_matrix([[1, 2]])
 1×2 IncidenceMatrix
 [1, 2]
 

src/AlgebraicGeometry/ToricVarieties/AlgebraicCycles/special_attributes.jl

@@ -27,7 +27,7 @@ true
 julia> ngens(chow_ring(p2))
 3
 
-julia> v = normal_toric_variety(IncidenceMatrix([[1], [2], [3]]), [[1, 0], [0, 1], [-1, -1]])
+julia> v = normal_toric_variety(incidence_matrix([[1], [2], [3]]), [[1, 0], [0, 1], [-1, -1]])
 Normal toric variety
 
 julia> is_complete(v)

src/AlgebraicGeometry/ToricVarieties/CohomologyClasses/methods.jl

@@ -63,7 +63,7 @@ julia> m = 2;
 
 julia> ray_generators = [e1, -e1, e2, e3, - e2 - e3 - m * e1];
 
-julia> max_cones = IncidenceMatrix([[1,3,4], [1,3,5], [1,4,5], [2,3,4], [2,3,5], [2,4,5]]);
+julia> max_cones = incidence_matrix([[1,3,4], [1,3,5], [1,4,5], [2,3,4], [2,3,5], [2,4,5]]);
 
 julia> X = normal_toric_variety(max_cones, ray_generators; non_redundant = true)
 Normal toric variety

src/AlgebraicGeometry/ToricVarieties/NormalToricVarieties/constructors.jl

@@ -82,7 +82,7 @@ julia> ray_generators = [[1,0], [0, 1], [-1, 5], [0, -1]]
  [-1, 5]
  [0, -1]
 
-julia> max_cones = IncidenceMatrix([[1, 2], [2, 3], [3, 4], [4, 1]])
+julia> max_cones = incidence_matrix([[1, 2], [2, 3], [3, 4], [4, 1]])
 4×4 IncidenceMatrix
 [1, 2]
 [2, 3]

src/PolyhedralGeometry/PolyhedralComplex/constructors.jl

@@ -40,7 +40,7 @@ points and the rows represent the polyhedra.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]])
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]])
 2×4 IncidenceMatrix
 [1, 2, 3]
 [1, 3, 4]
@@ -61,7 +61,7 @@ Polyhedral complex with rays and lineality:
 ```jldoctest
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 

src/PolyhedralGeometry/PolyhedralComplex/properties.jl

@@ -5,7 +5,7 @@ Return the ambient dimension of `PC`.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]])
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]])
 2×4 IncidenceMatrix
 [1, 2, 3]
 [1, 3, 4]
@@ -41,7 +41,7 @@ Optional arguments for `as` include
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> V = [0 0; 1 0; 1 1; 0 1];
 
@@ -63,7 +63,7 @@ julia> matrix(QQ, vertices(PointVector, PC))
 ```
 The following complex has no vertices:
 ```
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
@@ -139,7 +139,7 @@ function is mainly a helper function for [`maximal_polyhedra`](@ref maximal_poly
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
@@ -193,7 +193,7 @@ See also [`rays`](@ref rays(PC::PolyhedralComplex{T}) where {T<:scalar_types}) a
 ```jldoctest
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -259,7 +259,7 @@ See also [`vertices`](@ref vertices(as::Type{PointVector{T}}, PC::PolyhedralComp
 ```jldoctest
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -317,7 +317,7 @@ Optional arguments for `as` include
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0; 1 0; 1 1; 0 1];
 
@@ -333,7 +333,7 @@ julia> matrix(QQ, rays(RayVector, PC))
 ```
 The following complex has no vertices:
 ```
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
@@ -398,7 +398,7 @@ refer to the output of [`vertices_and_rays`](@ref vertices_and_rays(PC::Polyhedr
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]])
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]])
 2×4 IncidenceMatrix
 [1, 2, 3]
 [1, 3, 4]
@@ -435,7 +435,7 @@ Return the number of maximal polyhedra of `PC`
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]])
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]])
 2×4 IncidenceMatrix
 [1, 2, 3]
 [1, 3, 4]
@@ -464,7 +464,7 @@ Determine whether the polyhedral complex is simplicial.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0; 1 0; 1 1; 0 1];
 
@@ -484,7 +484,7 @@ Determine whether the polyhedral complex is pure.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0; 1 0; 1 1; 0 1];
 
@@ -504,7 +504,7 @@ Compute the dimension of the polyhedral complex.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0; 1 0; 1 1; 0 1];
 
@@ -524,7 +524,7 @@ Return the polyhedra of a given dimension in the polyhedral complex `PC`.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> VR = [0 0; 1 0; 1 1; 0 1];
 
@@ -596,7 +596,7 @@ Return the lineality space of `PC`.
 ```jldoctest
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -636,7 +636,7 @@ Return the lineality dimension of `PC`.
 ```jldoctest
 julia> VR = [0 0 0; 1 0 0; 0 1 0; -1 0 0];
 
-julia> IM = IncidenceMatrix([[1,2,3],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,3],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -661,7 +661,7 @@ faces of $PC$ of dimension $i$.
 ```jldoctest
 julia> VR = [0 0; 1 0; -1 0; 0 1];
 
-julia> IM = IncidenceMatrix([[1,2,4],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,4],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -689,7 +689,7 @@ Return the number of rays of `PC`.
 ```jldoctest
 julia> VR = [0 0; 1 0; -1 0; 0 1];
 
-julia> IM = IncidenceMatrix([[1,2,4],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,4],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -711,7 +711,7 @@ Return the number of vertices of `PC`.
 ```jldoctest
 julia> VR = [0 0; 1 0; -1 0; 0 1];
 
-julia> IM = IncidenceMatrix([[1,2,4],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,4],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -733,7 +733,7 @@ Return the total number of polyhedra in the polyhedral complex `PC`.
 ```jldoctest
 julia> VR = [0 0; 1 0; -1 0; 0 1];
 
-julia> IM = IncidenceMatrix([[1,2,4],[1,3,4]]);
+julia> IM = incidence_matrix([[1,2,4],[1,3,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -754,7 +754,7 @@ Compute the codimension of a polyhedral complex.
 ```
 julia> VR = [0 0; 1 0; -1 0; 0 1];
 
-julia> IM = IncidenceMatrix([[1,2],[1,3],[1,4]]);
+julia> IM = incidence_matrix([[1,2],[1,3],[1,4]]);
 
 julia> far_vertices = [2,3,4];
 
@@ -777,7 +777,7 @@ subset of some $\mathbb{R}^n$.
 ```jldoctest
 julia> VR = [0 0; 1 0; -1 0; 0 1];
 
-julia> IM = IncidenceMatrix([[1,2],[1,3],[1,4]]);
+julia> IM = incidence_matrix([[1,2],[1,3],[1,4]]);
 
 julia> PC = polyhedral_complex(IM, VR)
 Polyhedral complex in ambient dimension 2

src/PolyhedralGeometry/PolyhedralComplex/standard_constructions.jl

@@ -5,7 +5,7 @@ Return the common refinement of two polyhedral complexes.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3]])
+julia> IM = incidence_matrix([[1,2,3]])
 1×3 IncidenceMatrix
 [1, 2, 3]
 
@@ -51,7 +51,7 @@ Return the k-skeleton of a polyhedral complex.
 
 # Examples
 ```jldoctest
-julia> IM = IncidenceMatrix([[1,2,3]])
+julia> IM = incidence_matrix([[1,2,3]])
 1×3 IncidenceMatrix
 [1, 2, 3]
 

src/PolyhedralGeometry/PolyhedralFan/constructors.jl

@@ -43,7 +43,7 @@ To obtain the upper half-space of the plane:
 ```jldoctest
 julia> R = [1 0; 1 1; 0 1; -1 0; 0 -1];
 
-julia> IM=IncidenceMatrix([[1,2],[2,3],[3,4],[4,5],[1,5]]);
+julia> IM = incidence_matrix([[1,2],[2,3],[3,4],[4,5],[1,5]]);
 
 julia> PF=polyhedral_fan(IM, R)
 Polyhedral fan in ambient dimension 2
@@ -55,7 +55,7 @@ julia> R = [1 0 0; 0 0 1];
 
 julia> L = [0 1 0];
 
-julia> IM = IncidenceMatrix([[1],[2]]);
+julia> IM = incidence_matrix([[1],[2]]);
 
 julia> PF=polyhedral_fan(IM, R, L)
 Polyhedral fan in ambient dimension 3

src/PolyhedralGeometry/PolyhedralFan/properties.jl

@@ -50,7 +50,7 @@ julia> matrix(QQ, rays(NF))
 ```
 The following fan has no rays:
 ```
-julia> IM = IncidenceMatrix([[1,2],[2,3]]);
+julia> IM = incidence_matrix([[1,2],[2,3]]);
 
 julia> R = [1 0 0; 0 1 0; -1 0 0];
 
@@ -287,7 +287,7 @@ Return the dimension of `PF`.
 This fan in the plane contains a 2-dimensional cone and is thus 2-dimensional
 itself.
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
 
 julia> dim(PF)
 2
@@ -304,7 +304,7 @@ Return the number of maximal cones of `PF`.
 The cones given in this construction are non-redundant. Thus there are two
 maximal cones.
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
 
 julia> n_maximal_cones(PF)
 2
@@ -321,7 +321,7 @@ Return the number of cones of `PF`.
 The cones given in this construction are non-redundant. There are six
 cones in this fan.
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [3]]), [1 0; 0 1; -1 -1])
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [3]]), [1 0; 0 1; -1 -1])
 Polyhedral fan in ambient dimension 2
 
 julia> n_cones(PF)
@@ -441,7 +441,7 @@ This fan consists of two cones, one containing all the points with $y ≤ 0$ and
 one containing all the points with $y ≥ 0$. The fan's lineality is the common
 lineality of these two cones, i.e. in $x$-direction.
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2, 3], [3, 4, 1]]), [1 0; 0 1; -1 0; 0 -1])
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2, 3], [3, 4, 1]]), [1 0; 0 1; -1 0; 0 -1])
 Polyhedral fan in ambient dimension 2
 
 julia> lineality_space(PF)
@@ -500,7 +500,7 @@ Determine whether `PF` is smooth.
 Even though the cones of this fan cover the positive orthant together, one of
 these und thus the whole fan is not smooth.
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [2, 3]]), [0 1; 2 1; 1 0]);
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [2, 3]]), [0 1; 2 1; 1 0]);
 
 julia> is_smooth(PF)
 false
@@ -516,7 +516,7 @@ Determine whether `PF` is regular, i.e. the normal fan of a polytope.
 # Examples
 This fan is not complete and thus not regular.
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
 
 julia> is_regular(PF)
 false
@@ -531,7 +531,7 @@ Determine whether `PF` is pure, i.e. all maximal cones have the same dimension.
 
 # Examples
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
 
 julia> is_pure(PF)
 false
@@ -547,7 +547,7 @@ dimension.
 
 # Examples
 ```jldoctest
-julia> PF = polyhedral_fan(IncidenceMatrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
+julia> PF = polyhedral_fan(incidence_matrix([[1, 2], [3]]), [1 0; 0 1; -1 -1]);
 
 julia> is_fulldimensional(PF)
 true

src/PolyhedralGeometry/SubdivisionOfPoints/constructors.jl

@@ -52,7 +52,7 @@ triangulation.
 ```jldoctest
 julia> moaepts = [4 0 0; 0 4 0; 0 0 4; 2 1 1; 1 2 1; 1 1 2];
 
-julia> moaeimnonreg0 = IncidenceMatrix([[4,5,6],[1,4,2],[2,4,5],[2,3,5],[3,5,6],[1,3,6],[1,4,6]]);
+julia> moaeimnonreg0 = incidence_matrix([[4,5,6],[1,4,2],[2,4,5],[2,3,5],[3,5,6],[1,3,6],[1,4,6]]);
 
 julia> MOAE = subdivision_of_points(moaepts, moaeimnonreg0)
 Subdivision of points in ambient dimension 3