Struct CMap2

pub struct CMap2<T: CoordsFloat> { /* private fields */ }

2D combinatorial map implementation

Information regarding maps can be found in the user guide. This documentation focuses on the implementation and its API.

Notes on implementation:

• We encode β₀ as the inverse function of β₁. This is extremely useful (read required) to implement correct and efficient i-cell computation. Additionally, while β₀ can be accessed using the beta method, we do not define the 0-sew / 0-unsew operations.
• We chose a boundary-less representation of meshes (i.e. darts on the boundary are 2-free).
• The null dart will always be encoded as 0.

Generics

• T: CoordsFloat – Generic FP type for coordinates representation

Example

The following code corresponds to this flow of operations:

Note that:

• we create the map using its builder structure: CMapBuilder
• we insert a few assertions to demonstrate the progressive changes applied to the structure
• even though the faces are represented in the figure, they are not stored in the structure
• we use a lot of methods with the force_ prefix; these are convenience methods when synchronization isn’t needed

use honeycomb_core::{
    cmap::{CMap2, CMapBuilder, Orbit2, OrbitPolicy},
    geometry::Vertex2
};

// build a triangle (A)
let mut map: CMap2<f64> = CMapBuilder::default().n_darts(3).build().unwrap(); // three darts
map.force_link::<1>(1, 2); // beta1(1) = 2 & beta0(2) = 1
map.force_link::<1>(2, 3); // beta1(2) = 3 & beta0(3) = 2
map.force_link::<1>(3, 1); // beta1(3) = 1 & beta0(1) = 3
map.force_write_vertex(1, (0.0, 0.0));
map.force_write_vertex(2, (1.0, 0.0));
map.force_write_vertex(3, (0.0, 1.0));

// we can go through the face using an orbit
let mut face = Orbit2::new(&map, OrbitPolicy::Face, 1);
assert_eq!(face.next(), Some(1));
assert_eq!(face.next(), Some(2));
assert_eq!(face.next(), Some(3));
assert_eq!(face.next(), None);

// build a second triangle (B)
let first_added_dart_id = map.add_free_darts(3);
assert_eq!(first_added_dart_id, 4);
map.force_link::<1>(4, 5);
map.force_link::<1>(5, 6);
map.force_link::<1>(6, 4);
map.force_write_vertex(4, (0.0, 2.0));
map.force_write_vertex(5, (2.0, 0.0));
map.force_write_vertex(6, (1.0, 1.0));

// there should be two faces now
let faces: Vec<_> = map.iter_faces().collect();
assert_eq!(&faces, &[1, 4]);

// sew both triangles (C)
map.force_sew::<2>(2, 4);

// there are 5 edges now, making up a square & its diagonal
let edges: Vec<_> = map.iter_edges().collect();
assert_eq!(&edges, &[1, 2, 3, 5, 6]);

// adjust bottom-right & top-left vertex position (D)
assert_eq!(
    map.force_write_vertex(2, Vertex2::from((1.0, 0.0))),
    Some(Vertex2(1.5, 0.0)) // `write` act as a `replace`
);
assert_eq!(
    map.force_write_vertex(3, Vertex2::from((0.0, 1.0))),
    Some(Vertex2(0.0, 1.5)) // these values were the average of sewn vertices
);

// separate the diagonal from the rest (E)
map.force_unsew::<1>(1);
map.force_unsew::<1>(2);
map.force_unsew::<1>(6);
map.force_unsew::<1>(4);
// break up & remove the diagonal
map.force_unsew::<2>(2); // this makes dart 2 and 4 free
map.remove_free_dart(2);
map.remove_free_dart(4);
// sew the square back up
map.force_sew::<1>(1, 5);
map.force_sew::<1>(6, 3);

// there's only the square face left
let faces: Vec<_> = map.iter_faces().collect();
assert_eq!(&faces, &[1]);
// we can check the vertices
let vertices = map.iter_vertices();
let mut value_iterator = vertices.map(|vertex_id| map.force_read_vertex(vertex_id).unwrap());
assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 0.0)))); // vertex ID 1
assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 1.0)))); // vertex ID 3
assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 0.0)))); // vertex ID 5
assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 1.0)))); // vertex ID 6

Implementations

impl<T: CoordsFloat> CMap2<T>

Dart-related methods

pub fn n_darts(&self) -> usize

Return the current number of darts.

pub fn n_unused_darts(&self) -> usize

Return the current number of unused darts.

pub fn add_free_dart(&mut self) -> DartIdType

Add a new free dart to the map.

Return

Return the ID of the new dart.

pub fn add_free_darts(&mut self, n_darts: usize) -> DartIdType

Add n_darts new free darts to the map.

Return

Return the ID of the first new dart. Other IDs are in the range ID..ID+n_darts.

pub fn insert_free_dart(&mut self) -> DartIdType

Insert a new free dart in the map.

The dart may be inserted into an unused spot of the existing dart list. If no free spots exist, it will be pushed to the end of the list.

Return

Return the ID of the new dart.

pub fn remove_free_dart(&mut self, dart_id: DartIdType)

Remove a free dart from the map.

The removed dart identifier is added to the list of free dart. This way of proceeding is necessary as the structure relies on darts indexing for encoding data, making reordering of any sort extremely costly.

Arguments

• dart_id: DartIdentifier – Identifier of the dart to remove.

Panics

This method may panic if:

• the dart is not i-free for all i,
• the dart is already marked as unused.

impl<T: CoordsFloat> CMap2<T>

Beta-related methods

pub fn beta<const I: u8>(&self, dart_id: DartIdType) -> DartIdType

Return β_I(dart_id).

Panics

The method will panic if I is not 0, 1 or 2.

pub fn beta_rt(&self, i: u8, dart_id: DartIdType) -> DartIdType

Return β_i(dart_id).

Panics

The method will panic if i is not 0, 1 or 2.

pub fn beta_transac<const I: u8>( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> StmResult<DartIdType>

Return β_I(dart_id).

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

Panics

The method will panic if I is not 0, 1 or 2.

pub fn beta_rt_transac( &self, trans: &mut Transaction, i: u8, dart_id: DartIdType, ) -> StmResult<DartIdType>

Return β_i(dart_id).

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

Panics

The method will panic if i is not 0, 1 or 2.

pub fn is_i_free<const I: u8>(&self, dart_id: DartIdType) -> bool

Check if a given dart is I-free.

Return

Return a boolean indicating if the dart is I-free, i.e.:

• true if β_I(dart_id) = NULL_DART_ID,
• false else.

Panics

The function will panic if I is not 0, 1 or 2.

pub fn is_free(&self, dart_id: DartIdType) -> bool

Check if a given dart is i-free, for all i.

Return

Return a boolean indicating if the dart is 0-free, 1-free and 2-free.

impl<T: CoordsFloat> CMap2<T>

I-cell-related methods

pub fn vertex_id(&self, dart_id: DartIdType) -> VertexIdType

Compute the ID of the vertex a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 0-cell orbit.

pub fn vertex_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> StmResult<VertexIdType>

Compute the ID of the vertex a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 0-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn edge_id(&self, dart_id: DartIdType) -> EdgeIdType

Compute the ID of the edge a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 1-cell orbit.

pub fn edge_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> StmResult<EdgeIdType>

Compute the ID of the edge a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 1-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn face_id(&self, dart_id: DartIdType) -> FaceIdType

Compute the ID of the face a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 2-cell orbit.

pub fn face_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> StmResult<FaceIdType>

Compute the ID of the face a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 2-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn i_cell<const I: u8>(&self, dart_id: DartIdType) -> Orbit2<'_, T>

Return the orbit defined by a dart and its I-cell.

Usage

The Orbit2 can be iterated upon to retrieve all dart member of the cell. Note that the dart passed as an argument is included as the first element of the returned orbit.

Panics

The method will panic if I is not 0, 1 or 2.

pub fn iter_vertices(&self) -> impl Iterator<Item = VertexIdType> + '_

Return an iterator over IDs of all the map’s vertices.

pub fn iter_edges(&self) -> impl Iterator<Item = EdgeIdType> + '_

Return an iterator over IDs of all the map’s edges.

pub fn iter_faces(&self) -> impl Iterator<Item = FaceIdType> + '_

Return an iterator over IDs of all the map’s faces.

impl<T: CoordsFloat> CMap2<T>

Built-in vertex-related methods

pub fn n_vertices(&self) -> usize

Return the current number of vertices.

pub fn read_vertex( &self, trans: &mut Transaction, vertex_id: VertexIdType, ) -> StmResult<Option<Vertex2<T>>>

Return the vertex associated to a given identifier.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

This method return a Option taking the following values:

• Some(v: Vertex2) if there is a vertex associated to this ID,
• None otherwise.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn write_vertex( &self, trans: &mut Transaction, vertex_id: VertexIdType, vertex: impl Into<Vertex2<T>>, ) -> StmResult<Option<Vertex2<T>>>

Replace the vertex associated to a given identifier and return its old value.

Arguments

• vertex_id: VertexIdentifier – Identifier of the vertex to replace.
• vertex: impl Into<Vertex2> – New Vertex2 value.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex2) if there was an old value,
• None otherwise.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn remove_vertex( &self, trans: &mut Transaction, vertex_id: VertexIdType, ) -> StmResult<Option<Vertex2<T>>>

Remove the vertex associated to a given identifier and return it.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually,

The result contains an Option taking the following values:

• Some(v: Vertex2) if there was a value,
• None otherwise.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn force_read_vertex(&self, vertex_id: VertexIdType) -> Option<Vertex2<T>>

Read the vertex associated to a given identifier.

This variant is equivalent to read_vertex, but internally uses a transaction that will be retried until validated.

pub fn force_write_vertex( &self, vertex_id: VertexIdType, vertex: impl Into<Vertex2<T>>, ) -> Option<Vertex2<T>>

Replace the vertex associated to a given identifier and return its old value.

This variant is equivalent to write_vertex, but internally uses a transaction that will be retried until validated.

pub fn force_remove_vertex(&self, vertex_id: VertexIdType) -> Option<Vertex2<T>>

Remove the vertex associated to a given identifier and return it.

This variant is equivalent to remove_vertex, but internally uses a transaction that will be retried until validated.

impl<T: CoordsFloat> CMap2<T>

Generic attribute-related methods

pub fn read_attribute<A: AttributeBind + AttributeUpdate>( &self, trans: &mut Transaction, id: A::IdentifierType, ) -> StmResult<Option<A>>

Return the attribute A value associated to a given identifier.

The kind of cell A binds to is automatically deduced using its AttributeBind implementation.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

This method return a Option taking the following values:

• Some(a: A) if there is a value associated to this ID,
• None otherwise, or if there is no storage for this kind of attribute in the map.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn write_attribute<A: AttributeBind + AttributeUpdate>( &self, trans: &mut Transaction, id: A::IdentifierType, val: A, ) -> StmResult<Option<A>>

Replace the attribute A value associated to a given identifier and return its old value.

Arguments

• index: A::IdentifierType – Identifier of the cell’s value to replace.
• val: A – Attribute value.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(a: A) if there was an old value,
• None otherwise, or if there is no storage for this kind of attribute in the map.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn remove_attribute<A: AttributeBind + AttributeUpdate>( &self, trans: &mut Transaction, id: A::IdentifierType, ) -> StmResult<Option<A>>

Remove the attribute A value associated to a given identifier and return it.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(a: A) if there was a value,
• None otherwise, or if there is no storage for this kind of attribute in the map.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn force_read_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, ) -> Option<A>

Return the attribute A value associated to a given identifier.

This variant is equivalent to read_attribute, but internally uses a transaction that will be retried until validated.

pub fn force_write_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, val: A, ) -> Option<A>

Replace the attribute A value associated to a given identifier and return its old value.

This variant is equivalent to write_attribute, but internally uses a transaction that will be retried until validated.

pub fn force_remove_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, ) -> Option<A>

Remove the attribute A value associated to a given identifier and return it.

This variant is equivalent to remove_attribute, but internally uses a transaction that will be retried until validated.

pub fn remove_attribute_storage<A: AttributeBind + AttributeUpdate>(&mut self)

Remove the attribute A’s storage from the map.

This method is useful when implementing routines that uses attributes to run; Those can then be removed before the final result is returned.

impl<T: CoordsFloat> CMap2<T>

Link operations

pub fn link<const I: u8>( &self, trans: &mut Transaction, ld: DartIdType, rd: DartIdType, ) -> StmResult<()>

I-link operator.

Description

This operation corresponds to coherently linking two darts via their β images. Unlike sewing, this does not alter associated attributes. For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Link dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• ld: DartIdType – First dart ID.
• rd: DartIdType – Second dart ID.

Errors

This method should be called in a transactional context. The Result is then used to validate the transaction; Errors should not be processed manually, only processed via the ? operator. The policy in case of failure can be defined when creating the transaction, using Transaction::with_control.

Panics

The method may panic if:

• I >= 3 or I == 0,
• the two darts are not I-linkable.

pub fn unlink<const I: u8>( &self, trans: &mut Transaction, ld: DartIdType, ) -> StmResult<()>

I-unlink operator.

Description

This operation corresponds to unlinking two darts by resetting their β images. Unlike unsewing, this does not alter associated attributes. For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Unlink dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• ld: DartIdType – First dart ID.

The second dart ID is fetched using I and ld.

Errors

This method should be called in a transactional context. The Result is then used to validate the transaction; Errors should not be processed manually, only processed via the ? operator. The policy in case of failure can be defined when creating the transaction, using Transaction::with_control.

Panics

The method may panic if:

• I >= 3 or I == 0,
• ld is already I-free.

pub fn force_link<const I: u8>(&self, ld: DartIdType, rd: DartIdType)

I-link operator.

This variant is equivalent to link, but internally uses a transaction that will be retried until validated.

pub fn force_unlink<const I: u8>(&self, ld: DartIdType)

I-unlink operator.

This variant is equivalent to unlink, but internally uses a transaction that will be retried until validated.

impl<T: CoordsFloat + 'static> CMap2<T>

Serialization methods

pub fn to_vtk_binary(&self, writer: impl Write)

Generate a legacy VTK file from the map.

Panics

This function may panic if the internal writing routine fails, i.e.:

• vertex coordinates cannot be cast to f32 or f64,
• a vertex cannot be found.

pub fn to_vtk_ascii(&self, writer: impl Write)

Generate a legacy VTK file from the map.

Panics

This function may panic if the internal writing routine fails, i.e.:

• vertex coordinates cannot be cast to f32 or f64,
• a vertex cannot be found.

impl<T: CoordsFloat> CMap2<T>

Sew implementations

pub fn sew<const I: u8>( &self, trans: &mut Transaction, ld: DartIdType, rd: DartIdType, ) -> CMapResult<()>

I-sew operator.

Description

This operation corresponds to:

• coherently linking two darts via their β images,
• merging the attributes associated to their respective original I-cells.

For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Sew dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• ld: DartIdType – First dart ID.
• rd: DartIdType – Second dart ID.

Errors

This variant will abort the sew operation and raise an error if:

• the transaction cannot be completed,
• one (or more) attribute merge fails,
• for I == 2: orientation is inconsistent.

The returned error can be used in conjunction with transaction control to avoid any modifications in case of failure at attribute level. The user can then choose to retry or abort as he wishes using Transaction::with_control.

Panics

The method may panic if:

• I >= 3 or I == 0,
• the two darts are not I-sewable.

pub fn unsew<const I: u8>( &self, trans: &mut Transaction, ld: DartIdType, ) -> CMapResult<()>

I-unsew operator.

Description

This operation corresponds to:

• unlinking two darts by resetting their β images,
• splitting the attributes associated to the original I-cell.

For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Unsew dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• ld: DartIdType – First dart ID.

The second dart ID is fetched using I and ld.

Errors

This variant will abort the unsew operation and raise an error if:

• the transaction cannot be completed,
• one (or more) attribute split fails,

The returned error can be used in conjunction with transaction control to avoid any modifications in case of failure at attribute level. The user can then choose to retry or abort as he wishes using Transaction::with_control.

Panics

The method may panic if:

• I >= 3 or I == 0,
• ld is already I-free.

pub fn force_sew<const I: u8>(&self, ld: DartIdType, rd: DartIdType)

I-sew operator.

This variant is equivalent to sew, but internally uses a transaction that will be retried until validated.

pub fn force_unsew<const I: u8>(&self, ld: DartIdType)

I-unsew operator.

This variant is equivalent to unsew, but internally uses a transaction that will be retried until validated.

impl<T: CoordsFloat> CMap2<T>

Utilities

pub fn set_beta<const I: u8>(&self, dart_id: DartIdType, new_val: DartIdType)

Set the value of β_I(dart_id) to new_val.

pub fn set_betas(&self, dart_id: DartIdType, [b0, b1, b2]: [DartIdType; 3])

Set the values of the beta functions of a dart.

Arguments

• dart_id: DartIdentifier – ID of the dart of interest.
• betas: [DartIdentifier; 3] – Value of the images as [ β₀(dart_id), β₁(dart_id), β₂(dart_id) ]

Trait Implementations

impl<T: CoordsFloat> Send for CMap2<T>

impl<T: CoordsFloat> Sync for CMap2<T>