fp::Triangulation Class Reference

Implementation of Triangulation of two-dimensional surfaces in 3D. More...

#include <Triangulation.hpp>

Public Member Functions
	Triangulation (Json const &nodes_input, Real verlet_radius_inp)
	Constructor that can re-initiate a triangulation from the stored data.
	Triangulation (Index n_nodes_iter, Real R_initial_input, Real verlet_radius_inp)
	Constructor that can initiate a spherical triangulation from scratch.
void	make_verlet_list ()
	Create a Verlet list.
void	translate_all_nodes (vec3< Real > const &translation_vector)
	Adds the same 3D vector to the positions of each node of the triangulation.
vec3< Real >	calculate_mass_center () const
	Calculate the area-weighted average of node positions.
void	move_node (Index node_id, vec3< Real > const &displacement_vector)
	Move an individual node of the triangulation and update all the geometric quantities of the triangulation that changed.
void	emplace_before (Index center_node_id, Index anchor_id, Index new_value)
	Adds a new node to the next neighbor list of a given node and calculates their mutual distance.
BondFlipData	flip_bond (Index node_id, Index nn_id, Real min_bond_length_square, Real max_bond_length_square)
	Securely flip the bond inside a quadrilateral formed by the nodes given by node_id, nn_id and their two common next neighbors, if all topological requirements are satisfied.
void	unflip_bond (Index node_id, Index nn_id, BondFlipData const &common_nns)
	Un-flip a bond that was just flipped.
BondFlipData	flip_bond_unchecked (Index node_id, Index nn_id, Index common_nn_j_m_1, Index common_nn_j_p_1)
void	update_bulk_node_geometry (Index node_id)
	Update the geometric quantities associated with the given node.
Geometry	get_two_ring_geometry (Index node_id) const
	Aggregates and Returns the geometric quantities of the center node and its next neighbor nodes.
void	update_two_ring_geometry (Index node_id)
	Updates the geometric quantities of the center node and its next neighbor nodes.
void	scale_node_coordinates (Real x_stretch, Real y_stretch=1, Real z_stretch=1)
	Method for stretching or squeezing the initial triangulation shape.
Geometry	calculate_diamond_geometry (Index node_id, Index nn_id, Index cnn_0, Index cnn_1) const
	Aggregates the geometric quantities of the diamond configuration of nodes associated with a bond flip.
void	update_diamond_geometry (Index node_id, Index nn_id, Index cnn_0, Index cnn_1)
	Calculates and updates the geometric quantities of the diamond configuration of nodes associated with a bond flip.
Index	size () const
	Returns the number of nodes in the triangulation.
const Node &	operator[] (Index idx) const
	Returns a constant reference to the node with the given id.
const Nodes &	nodes () const
	Returns a constant reference to the underlying Nodes container.
Json	make_egg_data () const
	Creates a JSON object with the data of the triangulation.
const Geometry &	global_geometry () const
	Information about the global geometric quantities of the triangulation, like global area, volume, and total unit bending energy.
void	make_global_geometry ()
	Initiates the global geometry of the triangulation.
Neighbors	previous_and_next_neighbour_global_ids (Index node_id, Index nn_id) const

Static Public Member Functions
static Triangulation	experimental_load_sphere_from_stl (std::filesystem::path const &stl_file_path, Real verlet_radius_inp)
	Special constructor that can initialize a triangulation with spherical topology from a binary stl stl file.
static Real	mixed_area (vec3< Real > const &lij, vec3< Real > const &lij_p_1, Real triangle_area, Real cot_at_j, Real cot_at_j_p_1)
	The node-associated area inside a triangle.

Related Symbols
(Note that these are not member symbols.)
void	set_verlet_radius (Real R)
	Set the radius of the Verlet list to a new value.

Detailed Description

Implementation of Triangulation of two-dimensional surfaces in 3D.

*‍/

/**

Figure tr 1. Visualization of the triangulation.

Visualization of the triangulation. A: Triangulated sphere with \(N_{\mathrm{nodes}}=2252\). Black edges highlight the local neighborhood of a node. Circular arrows show the counterclockwise orientation of the nodes. This choice guarantees that all normal vectors point to the outside of the sphere. B: An arbitrary node \(i\), with its curvature vector \(\vec{K}_{i}\) and a highlighted angle \(\alpha^j_{i,j+1}\) at neighbour \(j\) opposite to the edge \(i, j+1\). Superscript \(j\) denotes the neighboring node to which the angle belongs and subscript \(i,j+1\) denotes the edge opposite of the angle. C: Node \(i\) with its associated Voronoi area \(A_i\) highlighted in red. The node has an associated area inside each triangle it is part of. We also highlight the triangle \(i,j,j+1\) (light red with stripes) with the face normal \(\vec{n}_{i,j,j+1}\) and the area \(A_{i,j,j+1}\). The part of this triangle that is associated with node \(i\) is highlighted in dark red and has the area \(A_{ij}\). The convention is to use the central and rightmost nodes in the subscript. Since the nodes are ordered counterclockwise, this convention is unambiguous. D: Volume associated with node \(i\) is made up of tetrahedrons that have as their base the triangles that make up the Voronoi cell of the node. The head of the tetrahedron points to some lab frame origin \(\cal{O}\). \(V_{ij}\) is the part of the volume associated to node \(i\) that has its base in the triangle \(i,j,j+1\).

Constructor & Destructor Documentation

Triangulation() [1/2]

fp::Triangulation::Triangulation ( Json const & nodes_input, Real verlet_radius_inp )

inline

Constructor that can re-initiate a triangulation from the stored data.

Parameters

nodes_input	json object that contains data generated by make_egg_data() function, or similarly structured data.
verlet_radius_inp	Value for Verlet radius.

Triangulation() [2/2]

fp::Triangulation::Triangulation ( Index n_nodes_iter, Real R_initial_input, Real verlet_radius_inp )

inline

Constructor that can initiate a spherical triangulation from scratch.

Parameters

n_nodes_iter	Number of sub-triangulations.
R_initial_input	Initial radius of the spherical triangulation.
verlet_radius_inp	Value for Verlet radius.

Member Function Documentation

experimental_load_sphere_from_stl()

static Triangulation fp::Triangulation::experimental_load_sphere_from_stl ( std::filesystem::path const & stl_file_path, Real verlet_radius_inp )

inlinestatic

Special constructor that can initialize a triangulation with spherical topology from a binary stl stl file.

This constructor is intended for initializing a triangulation with spherical topology from an stl file.

Warning

: This constructor is experimental and is not fully tested. The constructor trusts the stl file that it is a properly formed triangulation with spherical topology and a well oriented surface. currently there are no catches in place to gracefully handle malformed stl files. malformed stl files will simply result in runtime errors.

Parameters

stl_file_path	an absolute or relative path to a binary stl file
verlet_radius_inp	stl_file specification has no provision for additional information, thus verlet radius of the triangulation must be provided additionally.

Returns

This function tries to construct and return a spherical triangulation. If the stl file contains a triangulation of a different topology then the returned triangulation object will be malformed.

Here is the call graph for this function:

make_verlet_list()

void fp::Triangulation::make_verlet_list ( )

inline

Create a Verlet list.

This method creates a Verlet list for each node of the triangulation. All nodes that are inside the verlet_radius, of a given node, are included in its Verlet list (Node.verlet_list),

Here is the call graph for this function:

translate_all_nodes()

void fp::Triangulation::translate_all_nodes ( vec3< Real > const & translation_vector )

inline

Adds the same 3D vector to the positions of each node of the triangulation.

This method is most helpful in shifting a triangulation after its initiation. For example, to set up initial conditions for a simulation where several triangulated vesicles interact.

Parameters

translation_vector

A fixed 3D vector by which the triangulation is to be shifted.

Here is the call graph for this function:

calculate_mass_center()

vec3< Real > fp::Triangulation::calculate_mass_center ( ) const

inline

Calculate the area-weighted average of node positions.

This method calculates the average position of the mass center of the triangulation, by averaging the positions of each node of the triangulation. The average is weighted by the area associated with each node.

Returns

position of the mass center.

Here is the call graph for this function:

move_node()

void fp::Triangulation::move_node ( Index node_id, vec3< Real > const & displacement_vector )

inline

Move an individual node of the triangulation and update all the geometric quantities of the triangulation that changed.

Parameters

node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
displacement_vector	3D vector by which the chosen node is to be displaced.

Here is the call graph for this function:

Here is the caller graph for this function:

emplace_before()

void fp::Triangulation::emplace_before ( Index center_node_id, Index anchor_id, Index new_value )

inline

Adds a new node to the next neighbor list of a given node and calculates their mutual distance.

Note

The direct use of this method is discouraged unless a very specific type of edge flipping is required. Triangulation::flip_bond is a more high-level method, suitable for most basic bond-flipping needs.

This method finds the anchor node in the Nodes::nn_ids vector of the center_node and uses Node classes own method Node::emplace_nn_id to emplace the new_value there (together with its distance to the center_node).

Parameters

center_node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1. The new node is emplaced in the Node.nn_ids vector of this node.
anchor_id	Local index in the Node::nn_ids vector, a number between 0 and Node::nn_ids.size() - 1. This is the index of the next neighbor (inside nn_ids vector of the node center_node_id), before which the new node id is emplaced.
new_value	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1. The id of the new node.

Here is the call graph for this function:

Here is the caller graph for this function:

flip_bond()

BondFlipData fp::Triangulation::flip_bond ( Index node_id, Index nn_id, Real min_bond_length_square, Real max_bond_length_square )

inline

Securely flip the bond inside a quadrilateral formed by the nodes given by node_id, nn_id and their two common next neighbors, if all topological requirements are satisfied.

flip_bond function takes a lot of care to keep the triangulation intact, i.e., not introduce holes or additional bonds in it. To this end, the function performs a lot of checks to determine if the proposed bond fip is allowed by the topology. The information if the flip was allowed and succeeded or not will be encoded in the BondFlipData struct, which this function will return. The struct also contains information on the new end nodes of the bond, which is useful if one wishes to undo the flip. A bond flip can fail if:

• if the provided nodes id's do not correspond to neighboring nodes.
• one of the donor nodes have already too few bonds (bonds less than BOND_DONATION_CUTOFF).
• if a new bond that would be created, would be
  • too long (length squared is larger than max_bond_length_square)
  • too short (length squared is smaller than min_bond_length_square)

Parameters

node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
nn_id	Global id of the next neighbor Node, which is a number between 0 and max_number_of_nodes - 1.
min_bond_length_square	Square of the minimal allowed bond length, in the triangulation.
max_bond_length_square	Square of the maximal allowed bond length, in the triangulation.

Returns

If the flip was successful, the returned BondFlipData struct will contain a boolean state variable BondFlipData::flipped = true. The members BondFlipData::common_nn_0 and BondFlipData::common_nn_1 will contain global ids of new end nodes of the flipped bond. If the flip was not successful, then a default initialized BondFlipData struct will be returned with BondFlipData::flipped = false.

Note

Regardless of the return values, the primary purpose of the function, that of flipping a bond, is accomplished as a side-effect.

Here is the call graph for this function:

Here is the caller graph for this function:

unflip_bond()

void fp::Triangulation::unflip_bond ( Index node_id, Index nn_id, BondFlipData const & common_nns )

inline

Un-flip a bond that was just flipped.

This method reverses a flip between two nodes that used to be connected and had their node just flipped away, provided their id's and the BondFlipData that holds the information on the current bond holders.

This means that node_id and nn_id are (pre-flip) owners of the bond. And common_nns contains the id's of the current bond owners (to which the bond was flipped to). The edge will be taken away from the current two neighbors and added to the previous owners. All geometric information of the triangulation will be updated.

Warning

This method only works correctly if there were no bond flips after that flip which is being reversed. I.e., this method can only reverse the last flip. Furthermore, the method assumes that the arguments are provided correctly and will result in an illegal triangulation if this is not the case.

Note

This method does not check the validity of its input to provide a fast way of flip reversal. It relies on the fact that the user usually has the exact knowledge of all four node id's that participated in a flip and can provide those id's in the correct order. For a safer way of un-fliping, the Triangulation::flip_bond method can be used twice, with interchanged order of arguments.

The following example implementation of a Monte Carlo flip update method shows the proper way to use the Triangulation.flip_bond and Triangulation.unflip_bond methods.

++
 // `e_old`, `e_new`, `triangulation and `parameters` are data members of the updater
 void mc_flipp_update(fp::Node const& node)
 {
      e_old = energy_function(node, triangulation, parameters);
      Index number_nn_ids = node.nn_ids.size();
      Index nn_id = node.nn_ids[std::uniform_int_distribution<Index>(0, number_nn_ids-1)(rng)];
      auto bond_flip_data = triangulation.flip_bond(node.id, nn_id, min_bond_length_square, max_bond_length_square);
      if (bond_flip_data.flipped) {
          e_new = energy_function(node, triangulation, parameters);
          if (move_needs_undoing()) { triangulation.unflip_bond(node.id, nn_id, bond_flip_data); }
      }
  }

See also

Triangulation.flip_bond BondFlipData

Parameters

node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
nn_id	Global id of the next neighbor Node, which is a number between 0 and max_number_of_nodes - 1.
common_nns	BondFlipData containing information on the common next neighbor ids.

Here is the call graph for this function:

Here is the caller graph for this function:

flip_bond_unchecked()

BondFlipData fp::Triangulation::flip_bond_unchecked ( Index node_id, Index nn_id, Index common_nn_j_m_1, Index common_nn_j_p_1 )

inline

Exchange the next neighborhood between four nodes in a manner that will correspond to a bond flip if the provided information was correct.

Warning

This method may lead to an unphysical state (broken lattice that no longer represents a triangulation) if the provided arguments are not correct.

Note

For most use-cases the high level methods Triangulation::flip_bond and Triangulation::unflilp_bond are recommended. They guarantee that the performed flips result in a legal triangulation and reject the flip otherwise. This method should only be used by advanced users that have very specific needs for a flip updater.

The correct functioning of this method requires that, node_id and nn_id need to be next neighbours, and common_nn_j_m_1 and common_nn_j_p_1 need to be common next neighbors of both node_id and nn_id. Moreover, the nodes need to be ordered in the Node::nn_ids vector of the Node represented by node_id as follows: ... common_nn_j_m_1, node_id, common_nn_j_p_1 ..., or a cyclic permutation thereof.

Parameters

node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
nn_id	Global id of the next neighbor Node, which is a number between 0 and max_number_of_nodes - 1.
common_nn_j_m_1
common_nn_j_p_1

Returns

BondFlipData, where the flipped field is always set to True.

Here is the call graph for this function:

Here is the caller graph for this function:

update_bulk_node_geometry()

void fp::Triangulation::update_bulk_node_geometry ( Index node_id )

inline

Update the geometric quantities associated with the given node.

This is the core update function of the triangulation. It updates the geometric quantities of the given node after its position in the triangulation has been changed through a node move, or its neighborhood structure has been changed through a bond flip. Calculate and update the local curvature, area, volume, and unit bending energy of the node (See Figure tr1 B, C and D).

See also

Node::curvature_vec, Node::area, Node::volume, Node::unit_bending_energy

Parameters

node_id

Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.

Here is the call graph for this function:

Here is the caller graph for this function:

mixed_area()

static Real fp::Triangulation::mixed_area ( vec3< Real > const & lij, vec3< Real > const & lij_p_1, Real triangle_area, Real cot_at_j, Real cot_at_j_p_1 )

inlinestatic

The node-associated area inside a triangle.

This function is calculating the area associated with a node inside a triangle. As depicted in Figure tr1. A. This can be found in the description of the Triangulation class.

Every node of the triangulation has its own associated area. In the simplest case, the area associated with a node is the area of the Voronoi cell of that node. Where the Voronoi tessellation of the surface is the dual lattice of the triangulation. This function returns the area associated with a node inside a triangle. If that triangle is not obtuse, then this area is simply the area of the Voronoi cell of the node that is inside the triangle. This Voronoi area becomes negative for obtuse triangles, and thus an exception has to be made. If the triangle has an obtuse angle at the node, then the area associated with the node inside the triangle is half of the triangle area, otherwise, it is the quarter of the triangle area. This procedure is described in detail by Meyer et al. 2003

Parameters

lij	Distance vector between the node and its next neighbor. (Next neighbors are ordered according to the right-hand rule. See Figure tr1. A and C)
lij_p_1	Distance vector between the node and its next neighbor. (Next neighbors are ordered according to the right-hand rule)
triangle_area	area of the triangle i,j,j+1. See Area \(A_{i,j,j+1}\) in Figure tr1. C.
cot_at_j	Cotangent of the angle at the node j, opposite to the edge i,j+1. See Figure tr1. B.
cot_at_j_p_1	Cotangent of the angle at the node j+1, opposite to the edge i,j. See Figure tr1. B.

Returns

Area associated with the node inside the triangle. See Area \(A_{ij}\) in Figure tr1. C.

Here is the call graph for this function:

Here is the caller graph for this function:

get_two_ring_geometry()

Geometry fp::Triangulation::get_two_ring_geometry ( Index node_id ) const

inlinenodiscard

Aggregates and Returns the geometric quantities of the center node and its next neighbor nodes.

This function aggregates area volume and squared curvature integrated over the area for the two-ring of the associated with the node, using the stored quantities. Two-ring refers to the second concentric ring of the next-nearest-neighbor nodes surrounding the center node.

Parameters

node_id

Returns

Geometry object containing the geometric quantities of the center node and its next neighbor nodes.

Here is the caller graph for this function:

update_two_ring_geometry()

void fp::Triangulation::update_two_ring_geometry ( Index node_id )

inline

Updates the geometric quantities of the center node and its next neighbor nodes.

This function calculates and updates the area volume and squared curvature integrated over the area for the two-ring of the associated with the node. Two-ring refers to the second concentric ring of the next-nearest-neighbor nodes surrounding the center node.

Parameters

node_id

Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.

Here is the call graph for this function:

scale_node_coordinates()

void fp::Triangulation::scale_node_coordinates ( Real x_stretch, Real y_stretch = 1, Real z_stretch = 1 )

inline

Method for stretching or squeezing the initial triangulation shape.

This method is most useful for transforming a spherical triangulation into an ellipse.

The method stretches x, y, and z components of each node by a factor provided in the function argument. Triangulation's local and global geometric properties are updated after the stretch.

Note

The stretch will happen with respect to the lab frame and not the mass center of the triangulation. Thus, to get the intended results, the stretch is most likely desired, when the triangulation is centered around the origin of the lab frame, This is the case right after the initiation.

Parameters

x_stretch	Stretching factor of the x component of the position of the triangulation nodes.
y_stretch	Stretching factor of the y component of the position of the triangulation nodes.
z_stretch	Stretching factor of the z component of the position of the triangulation nodes.

Here is the call graph for this function:

calculate_diamond_geometry()

Geometry fp::Triangulation::calculate_diamond_geometry ( Index node_id, Index nn_id, Index cnn_0, Index cnn_1 ) const

inlinenodiscard

Aggregates the geometric quantities of the diamond configuration of nodes associated with a bond flip.

State of the diamond, which contains all nodes that participate in a bond flip.
 before the flip
 
     common nn 1
     /          \
    /            \
  node --------- nn
    \            /
     \          /
    common nn 0

Parameters

node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
nn_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
cnn_0	Global id of the common next nearest neighbor of node_id and nn_id.
cnn_1	Global id of the common next nearest neighbor of node_id and nn_id.

Returns

Geometric quantities aggregated over the diamond configuration of nodes associated with a bond flip.

Here is the caller graph for this function:

update_diamond_geometry()

void fp::Triangulation::update_diamond_geometry ( Index node_id, Index nn_id, Index cnn_0, Index cnn_1 )

inline

Calculates and updates the geometric quantities of the diamond configuration of nodes associated with a bond flip.

State of the diamond, which contains all nodes that participate in a bond flip.
 before the flip
 
     common nn 1
     /          \
    /            \
  node --------- nn
    \            /
     \          /
    common nn 0

Parameters

node_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
nn_id	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.
cnn_0	Global id of the common next nearest neighbor of node_id and nn_id.
cnn_1	Global id of the common next nearest neighbor of node_id and nn_id.

Here is the call graph for this function:

Here is the caller graph for this function:

size()

Index fp::Triangulation::size ( ) const

inlinenodiscard

Returns the number of nodes in the triangulation.

Returns

Number of the nodes in the triangulation.

Here is the call graph for this function:

operator[]()

const Node & fp::Triangulation::operator[] ( Index idx ) const

inline

Returns a constant reference to the node with the given id.

Triangulation will never give non-constant access to a node. In order to change a node, one has to use the methods of the Triangulation class. This guarantees that the triangulation is always in a consistent state.

Parameters

idx	Global id of the Node, which is a number between 0 and max_number_of_nodes - 1.

Returns

Constant reference to the node with the given id.

nodes()

const Nodes & fp::Triangulation::nodes ( ) const

inline

Returns a constant reference to the underlying Nodes container.

Returns

Constant reference to the underlying Nodes container.

Here is the caller graph for this function:

make_egg_data()

Json fp::Triangulation::make_egg_data ( ) const

inlinenodiscard

Creates a JSON object with the data of the triangulation.

Egg refers to the fact that the data can be used to recreate the triangulation using the Triangulation(Json const& nodes_input, Real verlet_radius_inp) constructor.

Note

The Triangulation(Json const& nodes_input, Real verlet_radius_inp) constructor is currently only implemented for a spherical Triangulation!

Returns

Triangulation data in JSON format.

Here is the call graph for this function:

global_geometry()

const Geometry & fp::Triangulation::global_geometry ( ) const

inlinenodiscard

Information about the global geometric quantities of the triangulation, like global area, volume, and total unit bending energy.

Returns

Geometric quantities of the triangulation aggregated over all nodes.

make_global_geometry()

void fp::Triangulation::make_global_geometry ( )

inline

Initiates the global geometry of the triangulation.

The global geometry is calculated by summing up the local geometries of all nodes.

Here is the call graph for this function:

previous_and_next_neighbour_global_ids()

Neighbors fp::Triangulation::previous_and_next_neighbour_global_ids ( Index node_id, Index nn_id ) const

inline

j+1 / \ i--—j \ / j-1 given i and j, this function finds the global ids of j-1 and j+1 nodes and returns them IN THAT ORDER; This function relies on the fact that i & j are neighbors and will throw a nasty runtime error if they are not

Here is the caller graph for this function:

Friends And Related Symbol Documentation

set_verlet_radius()

void set_verlet_radius ( Real R )

related

Set the radius of the Verlet list to a new value.

Parameters

R	new radius ()

---

The documentation for this class was generated from the following file:

• flippy/Triangulation.hpp