trimem.core module

C++ library with python bindings for trimem.

This module encapsulates the heavy lifting involved in the energy/gradient evaluations associated with trimem in a C++ library offering bindings to be called from python.

class trimem.core.BondParams

Tether regularization parameters.

__init__()
property a0

Reference face area (for BondType::Area).

Type:

float

property lc0

Onset distance for attracting force (for BondType::Edge).

Type:

float

property lc1

Onset distance for repelling force (for BondType::Edge).

Type:

float

property r

Steepness of regularization potential (must be >=1).

Type:

int.

property type

Type of potential (edge-based, area-based).

Type:

BondType

class trimem.core.BondType

Types for the tether potential.

Members:

Edge : Smoothed well/box potential on edges.

Area : Harmonic potential on face area.

None : None

__init__()
class trimem.core.ContinuationParams

Parameters used for smooth continuation.

__init__()
property delta

Interpolation blending time step.

property lam

Interpolation state.

class trimem.core.EnergyManager

Helfrich functional evaluation.

Manages a particular parametrization of the Helfrich functional with additional penalties and tether-regularization. At its core it provides methods energy() and gradient() for the evaluation of the full Hamiltonian and its gradient.

__init__(self: trimem.core.EnergyManager, mesh: trimem.core.TriMesh, eparams: trimem.core.EnergyParams) → None

Initialization.

Initializes the EnergyManager’s state from the initial mesh and the parametrization provided by eparams. This comprises the setup of the initial state of the parameter continuation, the set up of the reference properties for area, volume and curvature (see initial_props) according to the current state of the parameter continuation as well as the construction of the neighbour list structures for the repulsion penalty.

energy(*args, **kwargs)

Overloaded function.

  1. energy(self: trimem.core.EnergyManager, mesh: trimem.core.TriMesh) -> float

    Evaluation of the Hamiltonian.

    Args:
    mesh (TriMesh): mesh representing the state to be evaluated

    defined by vertex positions as well as connectivity.

    Returns:

    The value of the nonlinear Hamiltonian by computing the vector of VertexProperties and reducing it to the value of the Hamiltonian.

  2. energy(self: trimem.core.EnergyManager, vprops: trimem.core.VertexProperties) -> float

    Evaluation of the Hamiltonian.

    Args:
    vprops (VertexProperties): vector of VertexProperties that has

    already been evaluated beforehand by properties().

    Returns:

    The value of the nonlinear Hamiltonian by directly reducing on the provided VertexProperties vprops.

property eparams

Parametrization of the Hamiltonian.

Type:

EnergyParams

gradient(self: trimem.core.EnergyManager, mesh: trimem.core.TriMesh) → numpy.ndarray[numpy.float64]

Evaluate gradient of the Hamiltonian.

Parameters:

mesh (TriMesh) – mesh representing the state to be evaluated defined by vertex positions as well as connectivity.

Returns:

(N,3) array of the gradient of the Hamiltonian given by energy() with respect to the vertex positions. N is the number of vertices in mesh.

property initial_props

Initial reference properties.

Initial reference properties computed from the definition of the target properties for area, volume and curvature. Created upon construction.

print_info(self: trimem.core.EnergyManager, mesh: trimem.core.TriMesh) → None

Print energy information evaluated on the state given by mesh.

properties(self: trimem.core.EnergyManager, mesh: trimem.core.TriMesh) → trimem.core.VertexProperties

Evaluation of vertex averaged properties.

Triggers the evaluation of a vector of vertex-averaged properties VertexProperties that comprises the basic per-vertex quantities.

Parameters:

mesh (TriMesh) – mesh representing the state to be evaluated defined by vertex positions as well as connectivity.

Returns:

(N,1) array of VertexProperties with N being the number of vertices.

update_reference_properties(self: trimem.core.EnergyManager) → None

Update reference configurations.

Uses the parameter continuation defined in the parametrization eparams to update reference values for area, volume and curvature from the target configuration.

update_repulsion(self: trimem.core.EnergyManager, arg0: trimem.core.TriMesh) → None

Update repulsion penalty.

Updates internal references to neighbour lists and repulsion penalties based on the state of the mesh passed in as arg0.

class trimem.core.EnergyParams

Parametrization of the Helfrich functional.

Modularized POD structure containing parameters for the Helfrich functional, the area, volume and area-difference penalties, the repulsion penalty and the tether regularization.

__init__()
property area_frac

Target surface area fraction wrt. the initial geometry.

Type:

float

property bond_params

Parameters for the tether regularization.

Type:

BondParams

property continuation_params

Parameters for the parameter continuation.

Type:

ContinuationParams

property curvature_frac

Target curvature fraction wrt. the initial geometry.

Type:

float

property kappa_a

Weight of the surface area penalty.

Type:

float

property kappa_b

Weight of the Helfrich functional.

Type:

float

property kappa_c

Weight of the area-difference penalty.

Type:

float

property kappa_r

Weight of the surface repulsion penalty.

Type:

float

property kappa_t

Weight of the tether regularization.

Type:

float

property kappa_v

Weight of the volume penalty.

Type:

float

property repulse_params

Parameters for the surface repulsion.

Type:

SurfaceRepulsionParams

property volume_frac

Target volume fraction wrt. the initial geometry.

Type:

float

class trimem.core.HalfedgeHandle

OpenMesh::HalfedgeHandle.

Handle/Reference to halfedges used by several functions within trimem.

__init__(self: trimem.core.HalfedgeHandle) → None
class trimem.core.NeighbourList

Neighbour list interface

Abstract representation of a neighbour list data structure operating on a TriMesh. Can be either a cell_list or a verlet_list. See make_nlist() for its construction.

__init__(*args, **kwargs)
distance_matrix(self: trimem.core.NeighbourList, mesh: trimem.core.TriMesh, rdist: float) → Tuple[List[float], List[int], List[int]]

Compute sparse distance matrix.

Parameters:

  • mesh (TriMesh) – mesh subject to pair-wise vertex distance compuation

  • rdist (float) – distance cutoff. This cutoff is additional to the cutoff that was used during list creation! That is, it is meaningful to specify a smaller cutoff than the cutoff used at list creation but a larger cutoff has no effect.

Returns:

A sparse distance matrix (as a tuple of lists) containing all vertices within a distance < rdist.

point_distances(self: trimem.core.NeighbourList, mesh: trimem.core.TriMesh, pid: int, rdist: float) → Tuple[List[trimem.core.Point], List[int]]

Compute distances for vertex pid.

Parameters:

  • mesh (TriMesh) – mesh containing vertices to be tested against pid.

  • pid (int) – vertex in mesh for which distances to other vertices are to be found.

  • rdist (float) – distance cutoff. This cutoff is additional to the cutoff that was used during list creation! That is, it is meaningful to specify a smaller cutoff than the cutoff used at list creation but a larger cutoff has no effect.

Returns:

A tuple (distances, ids) of vectors of distance components (in 3D) between pid and vertices in ids with distance < rdist.

class trimem.core.Point

OpenMesh::TriMesh::Point

Typedef of a vector-like quantity describing vertices/points in 3D.

__init__(*args, **kwargs)
class trimem.core.SurfaceRepulsionParams

Parameters for the surface repulsion penalty.

__init__()
property exclusion_level

Connected neighbourhood exclusion for neighbour lists.

Type:

int

Levels of exclusion are inclusive, i.e. 0<1<2. Can be one of:

  • 0: exclude self

  • 1: exclude directly connected neighbourhood (1 edge)

  • 2: exclude indirectly connected neighbourhood (2 edges)

property lc1

Onset distance for repelling force.

Type:

float

Type of neighbour list structures.

Type:

str

Can be cell_list or verlet_list.

property r

Steepness of repelling potential (must be >=1).

Type:

int.

property rlist

Neighbour search distance cutoff.

class trimem.core.TriMesh

Triangulation.

Specialization of OpenMesh::TriMesh_ArrayKernelT<MeshTraits>.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: trimem.core.TriMesh) -> None

    Initialize empty mesh.

    Returns:

    TriMesh with zero vertices and no faces.

  2. __init__(self: trimem.core.TriMesh, points: numpy.ndarray[numpy.float64], faces: numpy.ndarray[numpy.int32]) -> None

    Initialize from arrays of vertices and faces.

    Args:

    points ((N,3) float-array): array of vertices in 3 dimensions. faces ((N,3) int-array): array of face indices.

    Returns:

    TriMesh with vertices and faces defined by the input.

fv_indices(self: trimem.core.TriMesh) → numpy.ndarray[numpy.int32]

Get face-vertex indices.

Returns:

An (N,3) array of type int with N being the number of faces that contains the vertex indices defining each face.

halfedge_handle(self: trimem.core.TriMesh, edge: int) → trimem.core.HalfedgeHandle

Returns handle to first halfedge of edge i.

n_edges(self: trimem.core.TriMesh) → int

Number of edges in the mesh.

n_vertices(self: trimem.core.TriMesh) → int

Number of vertices in the mesh.

next_halfedge_handle(self: trimem.core.TriMesh, edge: trimem.core.HalfedgeHandle) → trimem.core.HalfedgeHandle

Returns handle to halfedge next to halfedge he.

opposite_halfedge_handle(self: trimem.core.TriMesh, edge: trimem.core.HalfedgeHandle) → trimem.core.HalfedgeHandle

Returns handle to the opposite of halfedge he.

points(self: trimem.core.TriMesh) → numpy.ndarray[numpy.float64]

Get vertex positions.

Returns:

An (N,3) array of type float with N being the number of vertices.

class trimem.core.VertexProperties

Container for vertex-averaged properties.

The vertex averaged quantities area, volume, curvature and bending energy are at the core of the evaluations involved in the Helfrich functional that is represented by EnergyManager. class:VertexProperties encapsulates access to these quantities. It further allows for the automatic reduction on vectors of VertexProperties by implementing the operators += and -=.

Its current usage in trimem implies an AoS approach that might be replaced by an SoA approach if required by performance considerations. In this case the idea is to still keep the container ‘interface’ as is and manage the data layout behind the scenes.

__init__(self: trimem.core.VertexProperties) → None
property area

Face area

property bending

Bending energy

property curvature

Edge curvature

property repulsion

Repulsion penalty

property tethering

Tether regularization

property volume

Face volume

trimem.core.area(mesh: trimem.core.TriMesh) → float

Compute surface area.

Parameters:

mesh (TriMesh) – input mesh to be evaluated

Returns:

The value of the surface area of mesh.

trimem.core.avg_tri_props(mesh: trimem.core.TriMesh) → Tuple[float, float]

Average triangle area and edge length

Parameters:

mesh (TriMesh) – mesh to process.

Returns:

A tuple (a, l) with a being the mesh’s average face area and l being the mesh’s average edge length. (Used for automatic detection of the characteristic lengths involved in the tether and repulsion penalties.)

trimem.core.dihedral_angle(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → float

Evaluate dihedral angle.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The dihedral angle between the face associated to halfedge_handle and the face associated to the opposite halfedge_handle.

trimem.core.dihedral_angle_grad(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → numpy.ndarray[numpy.float64]

Evaluate gradient of dihedral angle.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The gradient of the dihedral angle between the face associated to halfedge_handle and the face associated to the opposite halfedge_handle wrt to the coordinates of both faces.

trimem.core.edge_length(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → float

Evaluate edge length.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The lenght of the edge referred to by halfedge_handle.

trimem.core.edge_length_grad(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → numpy.ndarray[numpy.float64]

Evaluate gradient of edge length.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The gradient of the edge length referred to by halfedge_handle wrt.the coordinates of the vertices that are connected to halfedge_handle.

trimem.core.edges_length(mesh: trimem.core.TriMesh) → float

Compute cumulative edge length.

Parameters:

mesh (TriMesh) – input mesh to be evaluated

Returns:

The cumulated value of the length of all edges in mesh.

trimem.core.face_area(arg0: trimem.core.TriMesh, arg1: trimem.core.HalfedgeHandle) → float

Evaluate face area.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The area of the face associated to halfedge_handle.

trimem.core.face_area_grad(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → numpy.ndarray[numpy.float64]

Evaluate gradient of face area.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The gradient of the area of the face that is associated to halfedge_handle wrt. the coordinates of the vertices of that face.

trimem.core.face_volume(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → float

Evaluate face volume.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The volume of the tetrahedron given by the face associated to halfedge_handle and the origin.

trimem.core.face_volume_grad(mesh: trimem.core.TriMesh, halfedge_handle: trimem.core.HalfedgeHandle) → numpy.ndarray[numpy.float64]

Evaluate gradient of face volume.

Parameters:

  • mesh (TriMesh) – mesh containing halfedge_handle.

  • halfedge_handle (HalfedgeHandle) – handle to halfedge of interest.

Returns:

The gradient of the volume of the tetrahedron given by the face associated to halfedge_handle and the origin wrt to the coordinates of the face’s vertices.

trimem.core.flip(mesh: trimem.core.TriMesh, estore: trimem.core.EnergyManager, flip_ratio: float) → int

Serial flip sweep.

Performs a sweep over a fraction flip_ratio of edges in mesh trying to flip each edge sequentially and evaluating the energies associated to the flip against the Metropolis criterion.

Parameters:

  • mesh (TriMesh) – input mesh to be used

  • estore (EnergyManager) – instance of EnergyManager used in combination with the mesh to evaluate energy differences necessary for flip acceptance/rejection.

  • flip_ratio (float) – ratio of edges to test (must be in [0,1]).

trimem.core.gradient(mesh: trimem.core.TriMesh, estore: trimem.core.EnergyManager, gradient: numpy.ndarray[numpy.float64], epsilon: float) → None

Finite difference gradient of energy.

This is merely for testing/debugging. Use the gradient function exposed by the EnergyManager class.

Parameters:

  • mesh (TriMesh) – mesh instance.

  • estore (EnergyManager) – energy evaluation.

  • gradient (numpy.ndarray) – (N,3) array filled with the gradient.

  • epsilon (float) – finite difference perturbation magnitude.

trimem.core.make_nlist(mesh: trimem.core.TriMesh, eparams: trimem.core.EnergyParams) → trimem.core.NeighbourList

Neighbour list factory

Parameters:

  • mesh (TriMesh) – a mesh whose vertices are subject to neighbour search

  • eparams (EnergyParams) – parametrization of the list structure. Parameters are extracted from the sub-structure SurfaceRepulsionParams.

Returns:

An interface of type NeighbourList representing either a cell list or a verlet-list.

trimem.core.pflip(mesh: trimem.core.TriMesh, estore: trimem.core.EnergyManager, flip_ratio: float) → int

Batch parallel flip sweep.

Performs a sweep over a fraction flip_ratio of edges in mesh in a batch parallel fashion albeit maintaining chain ergodicity. To this end, a batch of edges is selected at random. If an edge is free to be flipped independently, i.e., no overlap of its patch with the patch of other edges (realized by a locking mechanism), it is flipped and its differential contribution to the Hamiltonian is evaluated in parallel for the whole batch. Ergodicity is maintained by subsequently evaluating the Metropolis criterion for each edge in the batch sequentially. This is repeated for a number of flip_ratio / batch_size * mesh.n_edges times.

Parameters:

  • mesh (TriMesh) – input mesh to be used

  • estore (EnergyManager) – instance of EnergyManager used in combination with the mesh to evaluate energy differences necessary for flip acceptance/rejection.

  • flip_ratio (float) – ratio of edges to test (must be in [0,1]).

trimem.core.read_mesh(fname: str) → trimem.core.TriMesh

Read mesh from fname

Uses OpenMesh::IO::read_mesh.

Parameters:

fname (str) – file name to read mesh from

Returns:

An instance of TriMesh read from fname.