trimem.mc package

Module contents

Trimem python module.

Algorithms to minimize and sample the Helfrich bending energy.

Subpackages

• trimem.mc.output package
  • Module contents
  • Submodules
    • trimem.mc.output.checkpoint module
      • CheckpointReader
      • CheckpointWriter
    • trimem.mc.output.util module
      • create_backup()
      • make_output()
    • trimem.mc.output.vtu module
      • VtuWriter
    • trimem.mc.output.xdmf module
      • XdmfWriter
    • trimem.mc.output.xyz module
      • XyzWriter

Submodules

trimem.mc.app module

Trimem command line interface

Command line application for the trimem package. It is installed as mc_app. See mc_app --help.

trimem.mc.app.cli()

Shell entrypoint.

trimem.mc.app.config(args)

Command action to write default config.

trimem.mc.app.run(args)

Command action to run a simulation.

trimem.mc.config module

Trimem run configuration.

Utilities to set up, read and write configuration files providing control on the trimem functionality.

trimem.mc.config.config_to_params(config)

Translate config to energy params.

Parameters:

config (ConfigParser) – config to be translated

Returns:

Instance of helfrich._core.EnergyParams parametrized by config.

Return type:

EnergyParams

trimem.mc.config.print_config(config)

Print config to stdout.

Parameters:

config (ConfigParser) – configuration to print.

trimem.mc.config.read_config(fname)

Read config from file.

Parameters:

fname (str, path-like) – file name to read from.

trimem.mc.config.update_config_defaults(config, **kwargs)

Update default section with kwargs.

Parameters:

config (ConfigParser) – config to be updated.

Keyword Arguments:

kwargs (dict) – dictionary to be written to the DEFAULT section.

trimem.mc.config.write_default_config(fname, strip=True)

Write default config to fname.

Parameters:

fname (str, path-like) – file name to write to.

Keyword Arguments:

strip (bool) – Strip comments from output (default: True).

trimem.mc.evaluators module

Evaluators for helfirch._core.EnergyManager.

Wrapper classes controlling the access to the functionality of the helfrich._core.EnergyManager that is provided by the _core C++ module.

Evaluators for energy, gradient and callback are defined as functions of vertex positions.

class trimem.mc.evaluators.EnergyEvaluators(mesh, estore, output, options)

Functions to evaluate energy, gradient and callback on a per step basis.

Exposes methods fun(), grad() as functions of vertex positions x that are used for generic algorithms that act on a state not defined by the mesh (including connectivity) but on the vertex positions only.

A step counter is provided that is used from the callback() to inject trimem specific features into generic sampling or minimization algorithms.

Parameters:

• mesh (Mesh) – mesh representing the state to be evaluated. It’s vertices will be updated prior to the evaluation of fun, gradient and callback.

• estore (EnergyManager) – backend to energy and gradient evaluations.

• output (callable) – object with callable attribute write_points_cells having signature (points, cells). Usually one of the writers constructed by make_output.

• options (dict) –

  additional (optional) parametrization:

  • info_step (default: 100): show info every n’th step

  • output_step (default: 1000): write trajectory output every n’th step

  • cpt_step (default: 0): write checkpoint data every n’th step

  • refresh_step (default: 10): refresh EnergyManager every n’th step

  • flatten (default: False): ravel gradient to (N,1) array. E.g., needed when used with scipy

  • num_steps (default: None): number of steps the calling algorithm runs

  • init_step (default: 0): initial step number of the calling algorithm

  • write_cpt (default: lambda m,e,s: None): handle to write checkpoint data. Must have signature (points, cells, stepnum). See, e.g., write_checkpoint_handle

callback(x, *args, **kwargs)

Callback.

Allows for the injection of custom trimem functionality into generic sampling and minimization algorithms:

• stdout verbosity

• writing of output trajectories

• writing of checkpoint files

• update of the internal state of self.estore

Parameters:

• x (ndarray[float]) – (N,3) array of vertex positions with N being the number of vertices in self.mesh.

• steps (collections.Counter) – step counter dictionary

• args – ignored

Keyword Arguments:

kwargs – ignored

fun(x, *args, **kwargs)

Evaluate energy.

Updates self.mesh with x and calls self.estore.energy(x).

Parameters:

• x (ndarray[float]) – (N,3) array of vertex positions with N being the number of vertices in self.mesh.

• args – ignored

Keyword Arguments:

kwargs – ignored

Returns:

Value of the Energy represented by self.estore.

Return type:

float

grad(x, *args, **kwargs)

Evaluate gradient.

Updates self.mesh with x and calls self.estore.gradient(x).

Parameters:

• x (ndarray[float]) – (N,3) array of vertex positions with N being the number of vertices in self.mesh.

• args – ignored

Keyword Arguments:

kwargs – ignored

Returns:

Gradient with respect to x of the Energy represented by self.estore.

Return type:

ndarray[float]

class trimem.mc.evaluators.TimingEnergyEvaluators(mesh, estore, output, options)

EnergyEvaluators with timings for steps.

Extends EnergyEvaluators with periodic measurements of the simulation performance and an estimate on the expected runtime.

callback(x, steps)

Callback with timings.

Wraps EnergyEvaluators.callback() with timing functionality.

trimem.mc.hmc module

Monte Carlo Sampling.

A vanilla Hamiltonian Monte Carlo implementation with optional cooling. Additionally, a multi-proposal Monte Carlo algorithm is available that is capable to integrate trimem-specific edge-flip functionality as flip proposals into the Monte Carlo framework.

class trimem.mc.hmc.HMC(x, nlog_prob, grad_nlog_prob, callback=None, counter={'flip': 0, 'move': 0}, options={})

Simple Hamiltonian Monte Carlo (with optional cooling).

This class implements the marching only. Recording of the generated chain/trajectory must be provided by the user within the callable callback given as optional argument to the constructor. This callback must implement the signature callback(x) with x being an element of the sample space.

Parameters:

• x (ndarray[float]) – initial state

• nlog_prob (callable) – negative log of probability density function

• grad_nlog_prob (callable) – gradient of negative log of pdf

Keyword Arguments:

• callback (callable) – step callback with signature callback(x) (defaults to no-op.)

• options (dict-like) –

  algorithm parametrization (optional):

  • mass (default: 1.0): scaling factor for unit-diagonal mass matrix used in the time integration

  • time_step (default: 1.0e-4): time step for time integration

  • num_integration_steps (default: 100): number of time integration steps

  • initial_temperature (default: 1.0): initial temperature for simulated annealing

  • minimal_temperature (default: 1.0e-6): minimal temperature for annealing

  • cooling_factor (default: 0.0): factor for exponential cooling

  • cooling_start_step (default: 0): start simulated annealing at this step

  • info_step (default: 100): print info every n’th step

  • init_step (default: 0): start value for step counter

info()

Print algorithmic information.

run(N)

Run HMC for N steps.

step()

Make one step.

class trimem.mc.hmc.MeshFlips(mesh, estore, counter={'flip': 0, 'move': 0}, options={})

Flipping edges as a step in a Markov Chain.

This class wraps the flip functionality available from the core C++-module such that it fits into a multi-proposal Monte Carlo framework.

Parameters:

• mesh (Mesh) – initial state.

• estore (EnergyManager) – backend for performing flipping on edges.

Keyword Arguments:

options (dict-like) –

flip parametrization (optional):

• flip_type (default: ‘parallel’): ‘serial’ or ‘parallel’ flip evaluation

• flip_ration (default: 0.1): proportion of edges in the mesh for which a flip is attempted

• info_step (default: 100): print info every n’th step

• init_step (default: 0): initial value for the step counter

info()

Print algorithmic information.

run(N)

Make N flip-sweeps.

step()

Make one step.

class trimem.mc.hmc.MeshHMC(mesh, nlog_prob, grad_nlog_prob, callback=None, counter={'flip': 0, 'move': 0}, options={})

HMC with mesh as state.

A lightweight extension of HMC that can be initialized with a mesh as the state in the sampling space.

Parameters:

• x (Mesh) – initial state

• nlog_prob (callable) – negative log of probability density function

• grad_nlog_prob (callable) – gradient of negative log of pdf

Keyword Arguments:

• callback (callable) – step callback with signature callback(x) (defaults to no-op.)

• options (dict-like) – algorithm parametrization. (see HMC)

step()

Make a step and explicitly update the mesh vertices.

class trimem.mc.hmc.MeshMonteCarlo(hmc, flips, counter={'flip': 0, 'move': 0}, callback=None)

MonteCarlo with two-step moves.

Bundles HMC and MeshFlips into a bi-step Monte Carlo algorithm where each step comprises a step of the HMC or a step of MeshFlips with equal probability.

Parameters:

• hmc (HMC) – HMC algorithm

• flips (MeshFlips) – Monte Carlo flip algorithm

Keyword Arguments:

callback (callable) – step callback with signature callback(x,s) with x begin the state and s being compatible with collections.Counter (defaults to no-op.)

run(N)

Run for N steps.

step()

Make one step each with each algorithm.

trimem.mc.hmc.get_step_counters()

Counter to manage the accounting of steps for moves and flips.

Returns:

Counter with keys for vertex-moves and edge-flips.

Return type:

collections.Counter

trimem.mc.mesh module

Lightweight wrapper for helfrich._core.TriMesh.

Gives easy and consistent access to the simulation state that is comprised of vertices and triangles.

class trimem.mc.mesh.Mesh(points=None, cells=None)

Lightweight wrapper around helfrich._core.TriMesh.

Setters and getters are provided for the vertices and face-indices that encapsulate the necessities coping with the fact that the corresponding data structures for vertices and faces are not kept on the python side.

Keyword Arguments:

• points (ndarray[float]) – (N,3) array of vertex positions with N being the number of vertices int the mesh.

• cells (ndarray[int]) – (M,3) array of triangle definitions with M being the number of triangles in the mesh.

copy()

Make a deep copy.

property f

Mesh triangles.

property x

Mesh vertices.

trimem.mc.mesh.read_trimesh(filename)

Read a mesh from file.

Parameters:

filename (str) – name of the file to read the mesh from.

trimem.mc.util module

Trimem run module.

High level building blocks to run simulations. These blocks are utilized from the mc_app cli but can also be used standalone as a python module.

trimem.mc.util.read_checkpoint(config, restartnum)

Read checkpoint file.

Acquire checkpoint prefix from config and read the checkpoint with number ‘restartnum’.

Note: Continuation params are taken from the checkpoint. Note: ‘init_step’ is set from the HMC section if given.

Parameters:

• config (dict-like) – run-config file.

• restartnum (int) – checkpoint file number to read.

Returns:

A tuple (mesh, config) with mesh being of type Mesh and config being of type ConfigParser.

trimem.mc.util.run(config, restart=None)

Run algorithm.

Runs an algorithm defined by the run-config. Performs a restart in case.

Parameters:

• config (dict-like) – run-config file.

• restart (None or int) – checkpoint file number to restart from.

trimem.mc.util.run_mc(mesh, estore, config)

Run Monte Carlo sampling.

Perform Monte Carlo sampling of the Helfrich bending energy as defined by the config.

Parameters:

• mesh (mesh.Mesh) – initial geometry.

• estore (EnergyManager) – EnergyManager.

• config (dict-like) – run-config file.

trimem.mc.util.run_minim(mesh, estore, config)

Run (precursor) minimization.

Performs a minimization of the Helfrich bending energy as defined by the config.

Parameters:

• mesh (mesh.Mesh) – initial geometry.

• estore (EnergyManager) – EnergyManager.

• config (dict-like) – run-config file.

trimem.mc.util.setup_energy_manager(config)

Setup energy manager.

Create EnergyManager and Mesh from config file.

Parameters:

config (dict-like) – run-config file.

Returns:

A tuple (estore, mesh) where estore is of type EnergyManager and mesh is of type Mesh.

trimem.mc.util.write_checkpoint_handle(config)

Create checkpoint write handle.

Parameters:

config (dict-like) – run-config file.

Keyword Arguments:

fix_step (None or int) – fix step input in handle signature.

Returns:

A function handle with signature (mesh, estore, step) that allows to write the mesh and the state of the EnergyManager to a checkpoint file. ‘step’ can be fixed to a particular value by the fix_step argument.