# Module Achain

`module Achain: `sig  end``
The abstract chain topological collection.

` 'new_acell : `int -> seq -> seq -> acell``
Creates a new acell of a given dimension. `new_acell(d, fl, cfl)` creates a new acell `sp` of dimension `d` with faces `fl` and cofaces `cfl`. Faces and cofaces are given as sequences. The cofaces and faces of the acells in theses sequences are updated to reflect the creation of the new acell. However, existing achains that include a coface of `sp` are not updated.
` 'new_vertex : `unit -> acell``
Creates a new acell of dimension 0.
` 'new_edge : `acell -> acell -> acell``
Creates a new acell of dimension 1. The arguments are two acells of dimension 0.
` 'new_face : `acell -> acell -> acell -> acell``
Creates a new acell of dimension 2. The argument are three acells of dimension 1.
` 'dimension : `achain -> int``
`acell -> int `

Return the dimension of a acell or a achain.

` 'faces : `acell -> seq``
`achain -> acell -> seq `

Return the sequence of faces of a cell or the values in a chain. `faces(c)` returns the sequence of the faces of `c`. `faces(ch,c)` returns the sequence of the values of the faces of `c` in the chain `ch`.

` 'cofaces : `acell -> seq``
`achain -> acell -> seq `

Return the sequence of cofaces of a cell or the values in a chain. `cofaces(c)` returns the sequence of the faces of `c`. `cofaces(ch,c)` returns the sequence of the values of the cofaces of `c` in the chain `ch`.

` 'icells : `achain -> acell -> int -> seq``
`acell -> int -> seq `

Return the sequence of icells of a cell or the values in a chain. The icells of dimension `i` of a cell `c` are the cells of dimension `i` that are parts of `c` or that include `c`. `icells(c,i)` returns the sequence of the icells of dimension `i` of `c`. `icells(ch,c,i)` returns the sequence of the values of the icells of dimension `i` of `c` in the chain `ch`.

` 'ccells : `achain -> acell -> int -> seq``
`acell -> int -> seq `

Return the sequence of ccells of a cell or the values in a chain. The ccells through dimension `i` of a cell `c` are the cells with the same dimension as `c` that share an icell with `c`. `ccells(c,i)` returns the sequence of the ccells through dimension `i` of `c`. `ccells(ch,c,i)` returns the sequence of the values of the icells through dimension `i` of `c` in the chain `ch`.

` 'transitive_faces : `achain -> acell -> seq``
`acell -> seq `

Return the sequence of faces of a cell and the faces of the faces, recursively.
See : 'faces

` 'transitive_cofaces : `achain -> acell -> seq``
`acell -> seq `

Return the sequence of cofaces of a cell and the cofaces of the cofaces, recursively.
See : 'cofaces

` 'common_faces : `achain -> acell -> acell -> seq``
`acell -> acell -> seq `

Return the sequence of the faces shared by two cells.
See : 'faces

` 'common_cofaces : `achain -> acell -> acell -> seq``
`acell -> acell -> seq `

Return the sequence of the cofaces shared by two cells.
See : 'cofaces

` 'common_transitive_faces : `achain -> acell -> acell -> seq``
`acell -> acell -> seq `

Return the sequence of the transitive faces shared by two cells.
See : 'faces
See : 'transitive_faces
See : 'common_faces

` 'common_transitive_cofaces : `achain -> acell -> acell -> seq``
`acell -> acell -> seq `

Return the sequence of the transitive cofaces shared by two cells.
See : 'cofaces
See : 'transitive_cofaces
See : 'common_cofaces

` 'facespos : `achain -> acell -> seq``
Return the sequence of faces of a cell in a chain. `facespos(ch,c)` returns the sequence of the faces of `c` in the chain `ch`.
See : 'faces
` 'cofacespos : `achain -> acell -> seq``
Return the sequence of cofaces of a cell in a chain. `cofacespos(ch,c)` returns the sequence of the cofaces of `c` in the chain `ch`.
See : 'cofaces
` 'icellspos : `achain -> acell -> int -> seq``
Return the sequence of icells of a cell in a chain. `icellspos(ch,c,i)` returns the sequence of the icells of dimension `i` of `c` in the chain `ch`.
See : 'icells
` 'ccellspos : `achain -> acell -> int -> seq``
Return the sequence of ccells of a cell in a chain. `ccellspos(ch,c,i)` returns the sequence of the ccells through dimension `i` of `c` in the chain `ch`.
See : 'ccells
` 'transitive_facespos : `achain -> acell -> seq``
Return the sequence of faces of a cell and the faces of the faces in a chain, recursively.
See : 'facespos
` 'transitive_cofacespos : `achain -> acell -> seq``
Return the sequence of cofaces of a cell and the cofaces of the cofaces in a chain, recursively.
See : 'cofacespos
` 'common_facespos : `achain -> acell -> acell -> seq``
Return the sequence of the faces shared by two cells in a chain.
See : 'facespos
` 'common_cofacespos : `achain -> acell -> acell -> seq``
Return the sequence of the cofaces shared by two cells in a chain.
See : 'cofacespos
` 'common_transitive_facespos : `achain -> acell -> acell -> seq``
Return the sequence of the transitive faces shared by two cells in a chain.
See : 'facespos
See : 'transitive_facespos
See : 'common_facespos
` 'common_transitive_cofacespos : `achain -> acell -> acell -> seq``
Return the sequence of the transitive cofaces shared by two cells in a chain.
See : 'cofacespos
See : 'transitive_cofacespos
See : 'common_cofacespos
` 'foldD : `funct -> any -> achain -> int``
Fold a function over the elements of a particular dimension of a collection.

`foldD` is an operator that acts over absract chains. If `c1, c2, ..., cn` of dimension `d` are the elements of an achain `c`, then `foldD(f, zero, c, d)` computes `f(c1, f(c2, ... f(cn, zero)))`. If the collection has no element of dimension `d`, then `zero` is returned.
See : fold

` 'iterD : `funct -> achain -> int -> undef``
Iter a function over the elements of a particular dimension of a collection.

`iterD` is an operator that acts over abstract chains. The results is undef. It is used for the side-effect of the function applied to the collection's elements.
See : iter

` 'iterD_indexed : `funct -> achain -> int -> undef``
Iter a function over the elements of a particular dimension of a collection with their position.

`iter_indexed(f, c)` is an expression that iterates the function `f` over the elements of the collection `c`. The function `f` takes 2 arguments: the first one is a position `p` and the second is the value at position `p` in the collection `c`.
See : iterD
See : iter_indexed

` 'foldD_indexed : `funct -> any -> achain -> int -> any``
Fold a function over the elements of a particular dimension of a collection with their position.
See : foldD
See : fold_indexed
` 'forallD : `funct -> achain -> int -> bool``
Universal predicate. `'forall(p, c, d)` checks if all elements of dimension `d` of the collection `c` satisfy the predicate `p`. If the collection is empty, `true` is returned.
` 'existsD : `funct -> achain -> int -> bool``
Existential predicate. `'exists(p, c, d)` checks if at least one element of dimension `d` of the collection satisfies the predicate `p`. If the collection is empty, `false` is returned.
` 'filtration : `funct -> achain -> seq``
Computes the filtration of an abstract chain.

`filtration(fct,ch)` returns the filtration of the abstract chain `ch` whose elements are partially ordered by the function `fct` and the face/coface relationship. A filtration is a total order on a set of achains. This total order is computed using two partial orders:

• the first one partially compares two acells of different dimension. If `c1` is a transitive_face of `c2`, `c1` is lower than `c2`, and reciprocally if `c1` is a transitive_coface of `c2`, `c1` is greater than `c2`. Otherwise, `c1` and `c2` can't be compared.
• The second partial order is computed using `fct`, that is a function of 3 arguments. `fct(d,v1,v2)` has to return an integer `i`, that depends on `d` the dimension of the compared abstract cells, and the values `v1` and `v2` associated with these cells in `ch`. `i` is negative if `v1` is lower than `v2`, positive when `v1` is greater than `v2`, null if `v1 = v2`. In fact, `fct` is a total order between cells with same dimension
As an example, consider the two following abstract chains `ch1` and `ch2`:

`v1 := new_vertex() ;;`

`v2 := new_vertex() ;;`

`v3 := new_vertex() ;;`

`e1 := new_edge(v1,v2) ;;`

`e2 := new_edge(v2,v3) ;;`

`ch1 := 1*v1 + 2*e1 + 3*v2 + 4*e2 + 5*v3 ;;`

`ch2 := 1*v1 + 4*e1 + 3*v2 + 2*e2 + 5*v3 ;;`

Let compute the filtration of `ch1` and `ch2` using the standard comparison function `compare` provided by mgs:

`filtration((\d.(compare)),ch1) ;;`

returns the sequence

`(v1, v2, e1, v3, e2)`

while

`filtration((\d.(compare)),ch2) ;;`

returns

`(v1, v2, v3, e2, e1)`

` 'boundary : `acell -> achain``
returns the boundary of an acell as a chain of integers.
` 'coboundary : `acell -> achain``
returns the coboundary of an acell as a chain of integers.
` 'normalise : `funct -> achain``
Build a new achain where the acell that have the same faces are quotiented. `normalise(fct, ch)` build a new achain where the acells are the acells of `ch` quotiented by the relation "having exactly the same faces". The values of the acell that have the same faces are combined in a random order using the binary function `fct` and becomes the value of the quotient acell.
See : quotient
` 'cartesian_prod : `funct -> achain -> achain -> achain``
Return the cartesian product of the two achain arguments. The first argument is a function used to build the value that labels a acell in the result, from the values of the originating acells in the achain arguments.
` 'quotient : `funct -> seq -> achain``
Build a new achain where the acell have been quotiented. `quotient(fct, rel, ch)` build a new achain where the acells are the acells of `ch` quotiented by the relation rel. This relation is represented by a sequence `rel` of couples. A couple is a sequence of two elements `(a, b)` specifying that `a` must be identified with `b`. The value of the acells that have been quotiented is computed using the fonction `fct` to combine (in a random order) the values of the initial acells.
See : normalise
` 'cofaces_in_achain : `achain -> acell -> seq``
Return the sequence of cofaces of a acell belonging to a given achain. If a acell belong to a achain, then all its face belongs also to the same achain. However, the acell can have as coface, cofaces that belongs to other achains. The function `'cofaces` return all the cofaces of a acell. `'cofaces_in_achain(c, s)` returns only the cofaces of `s` that belong also to the achain `c`.
See : 'cofaces
See : 'transitive_cofaces_in_achain
` 'transitive_cofaces_in_achain : `achain -> acell -> seq``
Return the sequence of recursive cofaces of a acell belonging to a given achain. If a acell belong to a achain, then all its face belongs also to the same achain. However, the acell can have as coface, cofaces that belongs to other achains. The function `'transitive_cofaces` return all the cofaces of a acell (and the cofaces of them, recursively). `'cofaces_in_achain(c, s)` returns only the recursive cofaces of `s` that belong also to the achain `c`.
See : 'cofaces_in_achain
See : 'transitive_cofaces
` 'common_cofaces_in_achain : `achain -> acell -> acell -> seq``
Return the sequence of the cofaces shared by two acells in a given achain.
` 'common_transitive_cofaces_in_achain : `achain -> acell -> acell -> seq``
Return the sequence of the transitive cofaces shared by two acells in a given achain.
See : transitive_cofaces