API

Profiles

Input/Output

class dcma.profiles.Profiles(bin_edges, free_energy, diffusion)

Bases: object

Diffusion and free energy profiles. Diffusion is in 10^-5 cm^2/s, Free energy in kbT.

Parameters

• bin_edges (np.array) – bin edges in Angstrom.

• free_energy (np.array) – Free energy profile in kbT.

• diffusion (np.array) – Diffusion profile in 10^-5 cm^2/s.

property bin_centers

property bin_edges

property bin_widths

calculate_permeability(skip=None, threshold=0.05)

Permeability in cm/s

Parameters

• skip – Number of bins before membrane starts (overwrites threshold).

• threshold – Relative deviation of free energy and diffusion profiles that mark the end of the water phase and the start of the membrane.

Returns

• Permeability in cm/s

• resistivity in s/cm,

• start index of membrane

• end index of membrane

Return type

A quadruple

concentration_in_membrane(num_permeants, area, skip=None, threshold=0.05)

Concentration of permeant in the membrane in #molecules/A^3

Parameters

• num_permeants (int) – Total number of permeants in the system

• area (float) – Cross section area of the membrane in Angstrom^2

• skip (int) – Number of bins in the water phase on one side of the membrane

• threshold (float) – See calculate_permeability.

Returns

The average concentration of permeant in the membrane

Return type

float

concentration_in_water(num_permeants, area, water_width=None, threshold=0.05)

Concentration of permeant in water in #molecules/A^3

Parameters

• num_permeants (int) – Total number of permeants in the system

• area (float) – Cross section area of the membrane in Angstrom^2

• water_width (int) – Number of bins in the water phase on one side of the membrane

• threshold (float) – See calculate_permeability.

Returns

The concentration of permeant in the water phase.

Return type

float

property diffusion

Diffusion in 10^-5 cm^2/s.

find_membrane_bounds(threshold=0.05)

Exclude water phase from the permeability calculation. :param threshold: :param start_index:

Returns: min_index, max_index

property free_energy

Free energy in kbT.

static from_file(filename)

static from_rate_matrix(rate)

make_rate_matrix()

property n_bins

reference_free_energy(water_width=None, threshold=0.05)

Reference free energy in the water phase.

Parameters

• water_width (int) – Number of bins belonging to the water phase on one side of the membrane

• threshold (float) – see calculate_permeability

Returns

The reference free energy.

save(filename)

class dcma.profiles.SetOfProfiles(profiles_list, weights=None)

Bases: object

A set of profile objects to obtain statistics.

static from_files(filenames, weights=None)

Get profiles from files.

get_average()

Returns

An instance of Profiles containing the average diffusion and free energy profiles.

get_percentile(percent)

Parameters

percentile – A number between 0.0 and 100.0. Returns a set of profiles so that the specified percentage of the data is below the returned profile. E.g., for 95% confidence interval, use percent=2.5 and percent=9.75.

Returns

An instance of Profiles containing the quantiles.

dcma.profiles.extrapolate_to_infinite_lag(finite_profiles, lag_times, weights=None)

Matrices

• Coarsen rate matrices

• Coarsen transition matrix

class dcma.matrices.Transitions(matrix, lag_time, edges, weight=1.0)

Bases: object

Class representing a transition matrix and context information (mainly edges and lag time).

property bin_centers

property bin_widths

coarsen(new_edges)

property edges

static from_file(filename, weight=1.0)

Read a transition matrix and context information from file.

property lag_time

property matrix

save(filename, dt=1.0, count='pbc')

save transition matrix to file

Parameters

• dt (float) – The dt that is written into the header.

• count (str) – That count that is written into the header.

property weight

dcma.matrices.coarsen_rate_matrix(rate, new_edges)

dcma.matrices.collapse_transition_matrices(transition_matrices)

Combines all transition matrices with equal lag times into one transition matrix each. :param transition_matrices: A list of transition matrices. Different transition matrices might share a lag time.

Returns

A list of transition matrices. Only one transition matrix per lag time.

Optimization

Interface to the c++ core. The data in c++ is dimensionless. The optimize function defined in this module manages the conversion.

class dcma.opt.ProfileGenerator(transition_matrices, energy=None, diffusion=None, dm='cos', em='cos', ds=6, es=9)

Bases: object

Generate Profiles from raw coefficients.

static from_log(logfile)

Create profile generator (and read data) from a log file.

Parameters

logfile – logfile from a previous optimization run

Returns

A tuple (generator, logs, best_coeff, best_f)

• generator: A ProfileGenerator instance

• logs (np.array): An array generated from the logs (time(s), objective, coeff1, coeff2, …)

• best_coeff (np.array): The optimal coefficients

• best_f (float): The optimal objective function value

dcma.opt.optimize(transition_matrices, energy=None, diffusion=None, dm='cos', em='cos', ds=6, es=9, cma_tolerance=None, logfile='', bias=<dcma.biasing.Bias object>)

Optimize profiles using CMA-ES method.

Parameters

• transition_matrices (list of matrices.Transitions) – The observed transitions

• energy (np.array) – Energy profile of shape (n_bins, ) if only D should be optimized (em=”const”)

• diffusion (np.array) – Diffusion profile of shape (nbins, ) if only F should be optimized (dm=”const”)

• dm (str) – Type of diffusion model (see dcma opt –help for available settings)

• em (str) – Type of energy model (see dcma opt –help for available settings)

• ds (int) – Number of coefficients for the diffusion profile

• es (int) – Number of coefficients for the energy profile

• cma_tolerance (float) – Tolerance for the optimization

• logfile (str) – Path to log file (default=no logging)

• bias (biasing.Bias) – A bias that was applied during simulation

Returns

the optimal profiles

Return type

profiles.Profiles

Utility

Basic general toolbox.

class dcma.tools.UnitConverter(edges, weights=None, test_bin_consistency=True)

Bases: object

In the c++ part of the program, all diffusion (and free energy profiles) are normalized, i.e. they are agnostic of the coordinates. This converter class helps to convert between units.

• Permeabilities are given in cm/s.

• Diffusion profiles are given in [10^-5 cm^2/s].

• Free energies are given in [k_B T].

property bin_centers

bin centers in Angstrom

property bin_widths

bin width in Angstrom

denormalize_diffusion(diff)

The reverse transformation of normalize_diffusion.

property edges

static from_transitions(transition_matrices)

get_generalized_centers()

Returns an array of size (n_bins + 2) that contains the bin centers plus “virtual” centers to the left and right. The latter are required to properly define the effect of biasing potentials at the edges.

property n_bins

number of bins

normalize_diffusion(diff, apply_log=False)

Parameters

• diff – diffusion profile in 10^-5 cm^2/s

• apply_log – Whether to apply a natural logarithm to the dimensionless diffusion. (log D is used internally by the c++ code and constant diffusion profiles (initial profiles) are given as log D)

Returns

Dimensionless diffusion profile

dcma.tools.are_edges_consistent(edges_list, weights=None)

Check if the bin edges for different replicas are consistent. :param edges_list: a list of numpy arrays, where each array holds a set of edges :param weights: weights for the replicas

Returns

A boolean

dcma.tools.bin_edges_to_centers(edges)

dcma.tools.bin_edges_to_widths(edges)

dcma.tools.comma_string_to_list(some_string, converter=<class 'float'>)

Converts “1,1,1” to [1.0, 1.0, 1.0].

dcma.tools.path_relative_to_module(relative_path)

Get file from a path that is relative to caller’s module. Returns: absolute path as string

Biasing

High-level interface to specify biasing potentials and forces that were applied to the simulation.

class dcma.biasing.Bias(pulling_force=None, bias_file=None, bias_function=None, temperature=None)

Bases: object

A class to process command line options that handle biased simulations.

Parameters

• pulling_force – Pulling force in Piconewton.

• bias_file – A file containing a vector of biases (length: n_bins + 2).

• bias_function – A string containing a lambda function.

• temperature – in Kelvin, required to convert pulling_force into the right units

get_biasing_type()

get_potential(unit_converter)

Parameters

unit_converter – An instance of UnitConverter

Returns

Biasing potential in units of kT.

Return type

np.array