def algebraic_topological_model_delta_complex(K, base_ring=None):
r"""
Algebraic topological model for cell complex ``K``
with coefficients in the field ``base_ring``.
This has the same basic functionality as
:func:`algebraic_topological_model`, but it also works for
`\Delta`-complexes. For simplicial and cubical complexes it is
somewhat slower, though.
INPUT:
- ``K`` -- a simplicial complex, a cubical complex, or a
`\Delta`-complex
- ``base_ring`` -- coefficient ring; must be a field
OUTPUT: a pair ``(phi, M)`` consisting of
- chain contraction ``phi``
- chain complex `M`
See :func:`algebraic_topological_model` for the main
documentation. The difference in implementation between the two:
this uses matrix and vector algebra. The other function does more
of the computations "by hand" and uses cells (given as simplices
or cubes) to index various dictionaries. Since the cells in
`\Delta`-complexes are not as nice, the other function does not
work for them, while this function relies almost entirely on the
structure of the associated chain complex.
EXAMPLES::
sage: from sage.homology.algebraic_topological_model import algebraic_topological_model_delta_complex as AT_model
sage: RP2 = simplicial_complexes.RealProjectivePlane()
sage: phi, M = AT_model(RP2, GF(2))
sage: M.homology()
{0: Vector space of dimension 1 over Finite Field of size 2,
1: Vector space of dimension 1 over Finite Field of size 2,
2: Vector space of dimension 1 over Finite Field of size 2}
sage: T = delta_complexes.Torus()
sage: phi, M = AT_model(T, QQ)
sage: M.homology()
{0: Vector space of dimension 1 over Rational Field,
1: Vector space of dimension 2 over Rational Field,
2: Vector space of dimension 1 over Rational Field}
If you want to work with cohomology rather than homology, just
dualize the outputs of this function::
sage: M.dual().homology()
{0: Vector space of dimension 1 over Rational Field,
1: Vector space of dimension 2 over Rational Field,
2: Vector space of dimension 1 over Rational Field}
sage: M.dual().degree_of_differential()
1
sage: phi.dual()
Chain homotopy between:
Chain complex endomorphism of Chain complex with at most 3 nonzero terms over Rational Field
and Chain complex morphism:
From: Chain complex with at most 3 nonzero terms over Rational Field
To: Chain complex with at most 3 nonzero terms over Rational Field
In degree 0, the inclusion of the homology `M` into the chain
complex `C` sends the homology generator to a single vertex::
sage: K = delta_complexes.Simplex(2)
sage: phi, M = AT_model(K, QQ)
sage: phi.iota().in_degree(0)
[0]
[0]
[1]
In cohomology, though, one needs the dual of every degree 0 cell
to detect the degree 0 cohomology generator::
sage: phi.dual().iota().in_degree(0)
[1]
[1]
[1]
TESTS::
sage: T = cubical_complexes.Torus()
sage: C = T.chain_complex()
sage: H, M = AT_model(T, QQ)
sage: C.differential(1) * H.iota().in_degree(1).column(0) == 0
True
sage: C.differential(1) * H.iota().in_degree(1).column(1) == 0
True
sage: coC = T.chain_complex(cochain=True)
sage: coC.differential(1) * H.dual().iota().in_degree(1).column(0) == 0
True
sage: coC.differential(1) * H.dual().iota().in_degree(1).column(1) == 0
True
"""
def conditionally_sparse(m):
"""
Return a sparse matrix if the characteristic is zero.
Multiplication of matrices with low density seems to be quicker
if the matrices are sparse, when over the rationals. Over
finite fields, dense matrices are faster regardless of
density.
"""
if base_ring == QQ:
return m.sparse_matrix()
else:
return m
if not base_ring.is_field():
raise ValueError('the coefficient ring must be a field')
# The following are all dictionaries indexed by dimension.
# For each n, gens[n] is an ordered list of the n-cells generating the complex M.
gens = {}
pi_data = {}
phi_data = {}
iota_data = {}
for n in range(-1, K.dimension()+1):
gens[n] = []
C = K.chain_complex(base_ring=base_ring)
n_cells = []
pi_cols = []
iota_cols = {}
for dim in range(K.dimension()+1):
# old_cells: cells one dimension lower.
old_cells = n_cells
# n_cells: the standard basis for the vector space C.free_module(dim).
n_cells = C.free_module(dim).gens()
diff = C.differential(dim)
# diff is sparse and low density. Dense matrices are faster
# over finite fields, but for low density matrices, sparse
# matrices are faster over the rationals.
if base_ring != QQ:
diff = diff.dense_matrix()
rank = len(n_cells)
old_rank = len(old_cells)
# Create some matrix spaces to try to speed up matrix creation.
MS_pi_t = MatrixSpace(base_ring, old_rank, len(gens[dim-1]))
pi_old = MS_pi_t.matrix(pi_cols).transpose()
iota_cols_old = iota_cols
iota_cols = {}
pi_cols_old = pi_cols
pi_cols = []
phi_old = MatrixSpace(base_ring, rank, old_rank, sparse=(base_ring==QQ)).zero()
phi_old_cols = phi_old.columns()
phi_old = conditionally_sparse(phi_old)
to_be_deleted = []
zero_vector = vector(base_ring, rank)
pi_nrows = pi_old.nrows()
for c_idx, c in enumerate(n_cells):
# c_bar = c - phi(bdry(c)):
# Avoid a bug in matrix-vector multiplication (trac 19378):
if not diff:
c_bar = c
pi_bdry_c_bar = False
else:
if base_ring == QQ:
c_bar = c - phi_old * (diff * c)
pi_bdry_c_bar = conditionally_sparse(pi_old) * (diff * c_bar)
else:
c_bar = c - phi_old * diff * c
pi_bdry_c_bar = conditionally_sparse(pi_old) * diff * c_bar
# One small typo in the published algorithm: it says
# "if bdry(c_bar) == 0", but should say
# "if pi(bdry(c_bar)) == 0".
if not pi_bdry_c_bar:
# Append c to list of gens.
gens[dim].append(c_idx)
# iota(c) = c_bar
iota_cols[c_idx] = c_bar
# pi(c) = c
pi_cols.append(c)
else:
# Take any u in gens so that lambda_i = <u, pi(bdry(c_bar))> != 0.
# u_idx will be the index of the corresponding cell.
(u_idx, lambda_i) = pi_bdry_c_bar.leading_item()
for (u_idx, lambda_i) in pi_bdry_c_bar.iteritems():
if u_idx not in to_be_deleted:
break
# This element/column needs to be deleted from gens and
# iota_old. Do that later.
to_be_deleted.append(u_idx)
# pi(c) = 0.
pi_cols.append(zero_vector)
for c_j_idx, c_j in enumerate(old_cells):
# eta_ij = <u, pi(c_j)>.
# That is, eta_ij is the u_idx entry in the vector pi_old * c_j:
eta_ij = c_j.dot_product(pi_old.row(u_idx))
if eta_ij:
# Adjust phi(c_j).
phi_old_cols[c_j_idx] += eta_ij * lambda_i**(-1) * c_bar
# Adjust pi(c_j).
pi_cols_old[c_j_idx] -= eta_ij * lambda_i**(-1) * pi_bdry_c_bar
# The matrices involved have many zero entries. For
# such matrices, using sparse matrices is faster over
# the rationals, slower over finite fields.
phi_old = matrix(base_ring, phi_old_cols, sparse=(base_ring==QQ)).transpose()
keep = vector(base_ring, pi_nrows, {i:1 for i in range(pi_nrows)
if i not in to_be_deleted})
cols = [v.pairwise_product(keep) for v in pi_cols_old]
pi_old = MS_pi_t.matrix(cols).transpose()
# Here cols is a temporary storage for the columns of iota.
cols = [iota_cols_old[i] for i in sorted(iota_cols_old.keys())]
for r in sorted(to_be_deleted, reverse=True):
del cols[r]
del gens[dim-1][r]
iota_data[dim-1] = matrix(base_ring, len(gens[dim-1]), old_rank, cols).transpose()
# keep: rows to keep in pi_cols_old. Start with all
# columns, then delete those in to_be_deleted.
keep = sorted(set(range(pi_nrows)).difference(to_be_deleted))
# Now cols is a temporary storage for columns of pi.
cols = [v.list_from_positions(keep) for v in pi_cols_old]
pi_data[dim-1] = matrix(base_ring, old_rank, len(gens[dim-1]), cols).transpose()
phi_data[dim-1] = phi_old
V_gens = VectorSpace(base_ring, len(gens[dim]))
if pi_cols:
cols = []
for v in pi_cols:
cols.append(V_gens(v.list_from_positions(gens[dim])))
pi_cols = cols
pi_data[dim] = matrix(base_ring, rank, len(gens[dim]), pi_cols).transpose()
cols = [iota_cols[i] for i in sorted(iota_cols.keys())]
iota_data[dim] = matrix(base_ring, len(gens[dim]), rank, cols).transpose()
# M_data will contain (trivial) matrices defining the differential
# on M. Keep track of the sizes using "M_rows" and "M_cols", which are
# just the ranks of consecutive graded pieces of M.
M_data = {}
M_rows = 0
for n in range(K.dimension()+1):
M_cols = len(gens[n])
M_data[n] = zero_matrix(base_ring, M_rows, M_cols)
M_rows = M_cols
M = ChainComplex(M_data, base_ring=base_ring, degree=-1)
pi = ChainComplexMorphism(pi_data, C, M)
iota = ChainComplexMorphism(iota_data, M, C)
phi = ChainContraction(phi_data, pi, iota)
return phi, M
def algebraic_topological_model_delta_complex(K, base_ring=None):
r"""
Algebraic topological model for cell complex ``K``
with coefficients in the field ``base_ring``.
This has the same basic functionality as
:func:`algebraic_topological_model`, but it also works for
`\Delta`-complexes. For simplicial and cubical complexes it is
somewhat slower, though.
INPUT:
- ``K`` -- a simplicial complex, a cubical complex, or a
`\Delta`-complex
- ``base_ring`` -- coefficient ring; must be a field
OUTPUT: a pair ``(phi, M)`` consisting of
- chain contraction ``phi``
- chain complex `M`
See :func:`algebraic_topological_model` for the main
documentation. The difference in implementation between the two:
this uses matrix and vector algebra. The other function does more
of the computations "by hand" and uses cells (given as simplices
or cubes) to index various dictionaries. Since the cells in
`\Delta`-complexes are not as nice, the other function does not
work for them, while this function relies almost entirely on the
structure of the associated chain complex.
EXAMPLES::
sage: from sage.homology.algebraic_topological_model import algebraic_topological_model_delta_complex as AT_model
sage: RP2 = simplicial_complexes.RealProjectivePlane()
sage: phi, M = AT_model(RP2, GF(2))
sage: M.homology()
{0: Vector space of dimension 1 over Finite Field of size 2,
1: Vector space of dimension 1 over Finite Field of size 2,
2: Vector space of dimension 1 over Finite Field of size 2}
sage: T = delta_complexes.Torus()
sage: phi, M = AT_model(T, QQ)
sage: M.homology()
{0: Vector space of dimension 1 over Rational Field,
1: Vector space of dimension 2 over Rational Field,
2: Vector space of dimension 1 over Rational Field}
If you want to work with cohomology rather than homology, just
dualize the outputs of this function::
sage: M.dual().homology()
{0: Vector space of dimension 1 over Rational Field,
1: Vector space of dimension 2 over Rational Field,
2: Vector space of dimension 1 over Rational Field}
sage: M.dual().degree_of_differential()
1
sage: phi.dual()
Chain homotopy between:
Chain complex endomorphism of Chain complex with at most 3 nonzero terms over Rational Field
and Chain complex morphism:
From: Chain complex with at most 3 nonzero terms over Rational Field
To: Chain complex with at most 3 nonzero terms over Rational Field
In degree 0, the inclusion of the homology `M` into the chain
complex `C` sends the homology generator to a single vertex::
sage: K = delta_complexes.Simplex(2)
sage: phi, M = AT_model(K, QQ)
sage: phi.iota().in_degree(0)
[0]
[0]
[1]
In cohomology, though, one needs the dual of every degree 0 cell
to detect the degree 0 cohomology generator::
sage: phi.dual().iota().in_degree(0)
[1]
[1]
[1]
TESTS::
sage: T = cubical_complexes.Torus()
sage: C = T.chain_complex()
sage: H, M = AT_model(T, QQ)
sage: C.differential(1) * H.iota().in_degree(1).column(0) == 0
True
sage: C.differential(1) * H.iota().in_degree(1).column(1) == 0
True
sage: coC = T.chain_complex(cochain=True)
sage: coC.differential(1) * H.dual().iota().in_degree(1).column(0) == 0
True
sage: coC.differential(1) * H.dual().iota().in_degree(1).column(1) == 0
True
"""
def conditionally_sparse(m):
"""
Return a sparse matrix if the characteristic is zero.
Multiplication of matrices with low density seems to be quicker
if the matrices are sparse, when over the rationals. Over
finite fields, dense matrices are faster regardless of
density.
"""
if base_ring == QQ:
return m.sparse_matrix()
else:
return m
if not base_ring.is_field():
raise ValueError('the coefficient ring must be a field')
# The following are all dictionaries indexed by dimension.
# For each n, gens[n] is an ordered list of the n-cells generating the complex M.
gens = {}
pi_data = {}
phi_data = {}
iota_data = {}
for n in range(-1, K.dimension()+1):
gens[n] = []
C = K.chain_complex(base_ring=base_ring)
n_cells = []
pi_cols = []
iota_cols = {}
for dim in range(K.dimension()+1):
# old_cells: cells one dimension lower.
old_cells = n_cells
# n_cells: the standard basis for the vector space C.free_module(dim).
n_cells = C.free_module(dim).gens()
diff = C.differential(dim)
# diff is sparse and low density. Dense matrices are faster
# over finite fields, but for low density matrices, sparse
# matrices are faster over the rationals.
if base_ring != QQ:
diff = diff.dense_matrix()
rank = len(n_cells)
old_rank = len(old_cells)
# Create some matrix spaces to try to speed up matrix creation.
MS_pi_t = MatrixSpace(base_ring, old_rank, len(gens[dim-1]))
pi_old = MS_pi_t.matrix(pi_cols).transpose()
iota_cols_old = iota_cols
iota_cols = {}
pi_cols_old = pi_cols
pi_cols = []
phi_old = MatrixSpace(base_ring, rank, old_rank, sparse=(base_ring==QQ)).zero()
phi_old_cols = phi_old.columns()
phi_old = conditionally_sparse(phi_old)
to_be_deleted = []
zero_vector = vector(base_ring, rank)
pi_nrows = pi_old.nrows()
for c_idx, c in enumerate(n_cells):
# c_bar = c - phi(bdry(c)):
# Avoid a bug in matrix-vector multiplication (trac 19378):
if not diff:
c_bar = c
pi_bdry_c_bar = False
else:
if base_ring == QQ:
c_bar = c - phi_old * (diff * c)
pi_bdry_c_bar = conditionally_sparse(pi_old) * (diff * c_bar)
else:
c_bar = c - phi_old * diff * c
pi_bdry_c_bar = conditionally_sparse(pi_old) * diff * c_bar
# One small typo in the published algorithm: it says
# "if bdry(c_bar) == 0", but should say
# "if pi(bdry(c_bar)) == 0".
if not pi_bdry_c_bar:
# Append c to list of gens.
gens[dim].append(c_idx)
# iota(c) = c_bar
iota_cols[c_idx] = c_bar
# pi(c) = c
pi_cols.append(c)
else:
# Take any u in gens so that lambda_i = <u, pi(bdry(c_bar))> != 0.
# u_idx will be the index of the corresponding cell.
(u_idx, lambda_i) = pi_bdry_c_bar.leading_item()
for (u_idx, lambda_i) in iteritems(pi_bdry_c_bar):
if u_idx not in to_be_deleted:
break
# This element/column needs to be deleted from gens and
# iota_old. Do that later.
to_be_deleted.append(u_idx)
# pi(c) = 0.
pi_cols.append(zero_vector)
for c_j_idx, c_j in enumerate(old_cells):
# eta_ij = <u, pi(c_j)>.
# That is, eta_ij is the u_idx entry in the vector pi_old * c_j:
eta_ij = c_j.dot_product(pi_old.row(u_idx))
if eta_ij:
# Adjust phi(c_j).
phi_old_cols[c_j_idx] += eta_ij * lambda_i**(-1) * c_bar
# Adjust pi(c_j).
pi_cols_old[c_j_idx] -= eta_ij * lambda_i**(-1) * pi_bdry_c_bar
# The matrices involved have many zero entries. For
# such matrices, using sparse matrices is faster over
# the rationals, slower over finite fields.
phi_old = matrix(base_ring, phi_old_cols, sparse=(base_ring==QQ)).transpose()
keep = vector(base_ring, pi_nrows, {i:1 for i in range(pi_nrows)
if i not in to_be_deleted})
cols = [v.pairwise_product(keep) for v in pi_cols_old]
pi_old = MS_pi_t.matrix(cols).transpose()
# Here cols is a temporary storage for the columns of iota.
cols = [iota_cols_old[i] for i in sorted(iota_cols_old.keys())]
for r in sorted(to_be_deleted, reverse=True):
del cols[r]
del gens[dim-1][r]
iota_data[dim-1] = matrix(base_ring, len(gens[dim-1]), old_rank, cols).transpose()
# keep: rows to keep in pi_cols_old. Start with all
# columns, then delete those in to_be_deleted.
keep = sorted(set(range(pi_nrows)).difference(to_be_deleted))
# Now cols is a temporary storage for columns of pi.
cols = [v.list_from_positions(keep) for v in pi_cols_old]
pi_data[dim-1] = matrix(base_ring, old_rank, len(gens[dim-1]), cols).transpose()
phi_data[dim-1] = phi_old
V_gens = VectorSpace(base_ring, len(gens[dim]))
if pi_cols:
cols = []
for v in pi_cols:
cols.append(V_gens(v.list_from_positions(gens[dim])))
pi_cols = cols
pi_data[dim] = matrix(base_ring, rank, len(gens[dim]), pi_cols).transpose()
cols = [iota_cols[i] for i in sorted(iota_cols.keys())]
iota_data[dim] = matrix(base_ring, len(gens[dim]), rank, cols).transpose()
# M_data will contain (trivial) matrices defining the differential
# on M. Keep track of the sizes using "M_rows" and "M_cols", which are
# just the ranks of consecutive graded pieces of M.
M_data = {}
M_rows = 0
for n in range(K.dimension()+1):
M_cols = len(gens[n])
M_data[n] = zero_matrix(base_ring, M_rows, M_cols)
M_rows = M_cols
M = ChainComplex(M_data, base_ring=base_ring, degree=-1)
pi = ChainComplexMorphism(pi_data, C, M)
iota = ChainComplexMorphism(iota_data, M, C)
phi = ChainContraction(phi_data, pi, iota)
return phi, M
