MCUniverseGenerator

class pylimer_tools_cpp.MCUniverseGenerator(self: pylimer_tools_cpp.MCUniverseGenerator, lx: float = 10.0, ly: float = 10.0, lz: float = 10.0)

Bases: pybind11_object

A pylimer_tools_cpp.Universe generator using a Monte-Carlo procedure.

Please cite Gusev and Bernhard [GB24] and/or Bernhard and Gusev [BG25] if you use this method in your work.

Methods Summary

add_crosslinkers(self, nr_of_crosslinkers[, ...])

Add crosslinkers at random positions.

add_crosslinkers_at(self, coordinates[, ...])

Add crosslinkers at specific coordinates.

add_end_functionalized_strands(self, ...[, ...])

Add strands with crosslinkers at the ends.

add_monofunctional_strands(self, ...[, ...])

Add multiple monofunctional strands with specified bead types.

add_randomly_functionalized_strands(self, ...)

Add strands with randomly distributed crosslinkers in between.

add_solvent_chains(self, ...[, ...])

Randomly distribute additional, free chains.

add_strands(self, nr_of_strands, strand_lengths)

Add strands.

config_nr_of_mc_steps(self[, n_steps])

Set the number of Monte-Carlo steps during bond length equilibration.

config_primary_loop_probability(self[, ...])

Configure an additional weight reduction for the primary loop formation.

config_secondary_loop_probability(self[, ...])

Configure an additional weight reduction for the secondary loop formation.

disable_max_distance(self)

get_current_crosslinker_conversion(self)

Get the current conversion of crosslinkers, i.e., the fraction of crosslinkers that have been linked to strands.

get_current_nr_of_atoms(self)

get_current_nr_of_bonds(self)

get_force_balance(self)

Get an instance of the force balance procedure.

get_force_balance2(self)

Get an instance of the force balance procedure.

get_force_relaxation(self)

Get an instance of the force relaxation procedure.

get_mean_bead_distance(self)

Get the currently configured mean bead distance.

get_mean_squared_bead_distance(self)

Get the currently configured mean squared bead distance.

get_nr_of_atoms(self)

Get the current number of atoms that the universe would/will have.

get_nr_of_bonds(self)

Get the current number of bonds that the universe would/will have.

get_universe(self)

Fetch the current (or final) state of the universe.

link_strand(self, strand_idx[, c_infinity])

Link one particular strand to a crosslinker.

link_strand_to(self, strand_idx, link_idx)

Link a strand to a specific crosslinker.

link_strands_to_conversion(self, ...[, ...])

Actually link the previously added strands to the previously added crosslinkers, until a certain crosslink conversion is reached.

link_strands_to_soluble_fraction(self, ...)

Actually link the previously added strands to the previously added crosslinkers, until a certain soluble fraction is reached.

relax_crosslinks(self)

Run force relaxation with the crosslinkers and their strands, to have the crosslinks in their statistically most probable position.

remove_soluble_fraction(self[, rescale_box])

Remove soluble fraction (as determined by phantom force relaxation) of the strands and crosslinks.

set_bead_distance(self, distance[, ...])

Set the mean distance between beads when doing MC stepping.

set_mean_squared_bead_distance(self, ...[, ...])

Set the mean squared distance between beads.

set_seed(self, seed)

Set the seed for the random generator.

use_linear_max_distance(self, multiplier)

Converts the \(N\) to a maximum distance within which to sample.

use_zscore_max_distance(self, std_multiplier)

Converts the \(N\) to a maximum distance within which to sample.

validate(self)

Check whether the internal state of the generator is valid.

Methods Documentation

add_crosslinkers(self: pylimer_tools_cpp.MCUniverseGenerator, nr_of_crosslinkers: int, crosslinker_functionality: int = 4, crosslinker_type: int = 2, white_noise: bool = True) → None

Add crosslinkers at random positions.

Parameters:

  • nr_of_crosslinkers – Number of crosslinkers to add.

  • crosslinker_functionality – Functionality of the crosslinkers (default: 4).

  • crosslinker_type – Atom type of the crosslinkers (default: 2).

  • white_noise – Whether to use white noise (true) or blue noise (false) for the positions of the crosslinkers (default: true).

add_crosslinkers_at(self: pylimer_tools_cpp.MCUniverseGenerator, coordinates: numpy.ndarray[numpy.float64[m, 1]], crosslinker_functionality: int = 4, crosslinker_type: int = 2) → None

Add crosslinkers at specific coordinates.

Parameters:

  • coordinates – Coordinates of the crosslinkers.

  • crosslinker_functionality – Functionality of the crosslinkers (default: 4).

  • crosslinker_type – Atom type of the crosslinkers (default: 2).

add_end_functionalized_strands(self: pylimer_tools_cpp.MCUniverseGenerator, nr_of_strands: int, strand_length: list[int], crosslinker_functionality: int = 4, crosslinker_type: int = 2, strand_atom_type: int = 1, white_noise: bool = True) → None

Add strands with crosslinkers at the ends.

Parameters:

  • nr_of_strands – Number of strands to add.

  • strand_length – Length of each strand.

  • crosslinker_functionality – Functionality of the crosslinkers (default: 4).

  • crosslinker_type – Atom type of the crosslinkers (default: 2).

  • strand_atom_type – Atom type of the beads that are not at the ends (default: 1).

  • white_noise – Whether to use white noise (true) or blue noise (false) for the positions of the crosslinkers (default: true).

add_monofunctional_strands(self: pylimer_tools_cpp.MCUniverseGenerator, nr_of_monofunctional_strands: int, monofunctional_strand_length: list[int], monofunctional_strand_atom_type: int = 4) → None

Add multiple monofunctional strands with specified bead types.

add_randomly_functionalized_strands(self: pylimer_tools_cpp.MCUniverseGenerator, nr_of_strands: int, strand_length: list[int], functionalization_probability: float, crosslinker_functionality: int = 4, crosslinker_type: int = 2, strand_atom_type: int = 1, white_noise: bool = True) → None

Add strands with randomly distributed crosslinkers in between.

Parameters:

  • nr_of_strands – Number of strands to add.

  • strand_length – Length of each strand.

  • functionalization_probability – Proportion of beads that are made crosslink.

  • crosslinker_functionality – Functionality of the crosslinkers (default: 4).

  • crosslinker_type – Atom type of the crosslinkers (default: 2).

  • strand_atom_type – Atom type of the beads that stay (default: 1).

  • white_noise – Whether to use white noise (true) or blue noise (false) for the positions of the crosslinkers (default: true).

add_solvent_chains(self: pylimer_tools_cpp.MCUniverseGenerator, nr_of_solvent_chains: int, solvent_chain_length: int, solvent_atom_type: int = 3, white_noise: bool = True) → None

Randomly distribute additional, free chains.

add_strands(self: pylimer_tools_cpp.MCUniverseGenerator, nr_of_strands: int, strand_lengths: list[int], strand_atom_type: int = 1) → None

Add strands. Adds them unconnected at first. To link them to crosslinkers, use some of the link_strand_ methods.

Parameters:

  • nr_of_strands – Number of strands to add.

  • strand_lengths – A list of integers representing the number of beads of each of the strands.

  • strand_atom_type – Type of atoms for the strands (default: 1).

config_nr_of_mc_steps(self: pylimer_tools_cpp.MCUniverseGenerator, n_steps: int = 2000) → None

Set the number of Monte-Carlo steps during bond length equilibration.

Parameters:

n_steps – Number of MC steps to perform (default: 2000)

config_primary_loop_probability(self: pylimer_tools_cpp.MCUniverseGenerator, probability: float = 1.0) → None

Configure an additional weight reduction for the primary loop formation.

Defaults to 1., which means the general \(P(\vec{R})\) is used without any bias. This results in more primary loops for shorter chains than for longer ones.

Set to 0. to disable the formation of primary loops.

config_secondary_loop_probability(self: pylimer_tools_cpp.MCUniverseGenerator, probability: float = 1.0) → None

Configure an additional weight reduction for the secondary loop formation.

Defaults to 1., which means the general \(P(\vec{R})\) is used without any bias. This results in more secondary loops for shorter chains than for longer ones.

Set to 0. to disable the formation of secondary loops.

disable_max_distance(self: pylimer_tools_cpp.MCUniverseGenerator) → None
get_current_crosslinker_conversion(self: pylimer_tools_cpp.MCUniverseGenerator) → float

Get the current conversion of crosslinkers, i.e., the fraction of crosslinkers that have been linked to strands.

get_current_nr_of_atoms(self: pylimer_tools_cpp.MCUniverseGenerator) → int
get_current_nr_of_bonds(self: pylimer_tools_cpp.MCUniverseGenerator) → int
get_force_balance(self: pylimer_tools_cpp.MCUniverseGenerator) → pylimer_tools::sim::mehp::MEHPForceBalance

Get an instance of the force balance procedure. This is a useful shorthand e.g. to skip the sampling of beads within in the strands.

Note

due to the universe missing, some methods will not work; you won’t be able to query the fraction of active and dangling and soluble structures, for example.

get_force_balance2(self: pylimer_tools_cpp.MCUniverseGenerator) → pylimer_tools::sim::mehp::MEHPForceBalance2

Get an instance of the force balance procedure. This is a useful shorthand e.g. to skip the sampling of beads within in the strands.

Note

due to the universe missing, some methods will not work; you won’t be able to query the fraction of active and dangling and soluble structures, for example.

get_force_relaxation(self: pylimer_tools_cpp.MCUniverseGenerator) → pylimer_tools::sim::mehp::MEHPForceRelaxation

Get an instance of the force relaxation procedure. This is a useful shorthand e.g. to skip the sampling of beads within in the strands.

get_mean_bead_distance(self: pylimer_tools_cpp.MCUniverseGenerator) → float

Get the currently configured mean bead distance.

Returns:

The currently configured mean distance between beads

get_mean_squared_bead_distance(self: pylimer_tools_cpp.MCUniverseGenerator) → float

Get the currently configured mean squared bead distance.

Returns:

The currently configured mean squared distance between beads

get_nr_of_atoms(self: pylimer_tools_cpp.MCUniverseGenerator) → int

Get the current number of atoms that the universe would/will have.

Returns:

Number of atoms in the generated universe

get_nr_of_bonds(self: pylimer_tools_cpp.MCUniverseGenerator) → int

Get the current number of bonds that the universe would/will have.

Returns:

Number of bonds in the generated universe

get_universe(self: pylimer_tools_cpp.MCUniverseGenerator) → pylimer_tools_cpp.Universe

Fetch the current (or final) state of the universe.

Use this method to actually (MC) place beads between the crosslinks and retrieve the generated structure.

Link one particular strand to a crosslinker. This strand will have one bond made, to an appropriate crosslinker, as chosen by the parameters associated with the strand.

Parameters:

  • strand_idx – Index of the strand to be linked.

  • c_infinity – As needed for the end-to-end distribution, given by \(\langle R^2\rangle_0 = C_{\infty} N b^2\).

Link a strand to a specific crosslinker. This assumes that you keep track of the order in which you added the crosslinkers and strands.

Parameters:

  • strand_idx – Index of the strand to be linked.

  • link_idx – Index of the crosslinker to be linked.

Actually link the previously added strands to the previously added crosslinkers, until a certain crosslink conversion is reached.

Parameters:

  • crosslinker_conversion – Target conversion of crosslinkers (0: no connections to crosslinks; 1: all crosslinkers fully connected).

  • c_infinity – As needed for the end-to-end distribution, given by \(\langle R^2\rangle_0 = C_{\infty} N b^2\).

Actually link the previously added strands to the previously added crosslinkers, until a certain soluble fraction is reached.

Parameters:

  • soluble_fraction – Target soluble_fraction (0: no connections to crosslinks; 1: all crosslinkers fully connected).

  • c_infinity – As needed for the end-to-end distribution, given by \(\langle R^2\rangle_0 = C_{\infty} N b^2\).

Run force relaxation with the crosslinkers and their strands, to have the crosslinks in their statistically most probable position.

remove_soluble_fraction(self: pylimer_tools_cpp.MCUniverseGenerator, rescale_box: bool = True) → None

Remove soluble fraction (as determined by phantom force relaxation) of the strands and crosslinks.

set_bead_distance(self: pylimer_tools_cpp.MCUniverseGenerator, distance: float, update_mean_squared: bool = True) → None

Set the mean distance between beads when doing MC stepping. Also used for the target crosslinker partner sampling.

NOTE: Mainly the mean squared bead distance is effectively used in the Monte-Carlo simulation.

Parameters:

  • distance – Mean distance between beads.

  • update_mean_squared – Whether to update the mean squared distance as well, deduced from the assumed gaussian distribution in 3D (default: true).

set_mean_squared_bead_distance(self: pylimer_tools_cpp.MCUniverseGenerator, mean_squared_distance: float, update_mean: bool = True) → None

Set the mean squared distance between beads.

Parameters:

  • mean_squared_distance – Mean squared distance between beads

  • update_mean – Whether to update the mean bead distance as well, deduced from the assumed gaussian distribution in 3D (default: true)

set_seed(self: pylimer_tools_cpp.MCUniverseGenerator, seed: int) → None

Set the seed for the random generator.

use_linear_max_distance(self: pylimer_tools_cpp.MCUniverseGenerator, multiplier: float) → None

Converts the \(N\) to a maximum distance within which to sample. The distance will be calculated as \(N \times \text{multiplier}\). For example, commonly, a maximum distance is \(N \times <b>\), in which case the multiplier is \(<b>\).

Useful only for performance improvements in large systems.

use_zscore_max_distance(self: pylimer_tools_cpp.MCUniverseGenerator, std_multiplier: float, in_sqrt_multiplier: float = 1.0) → None

Converts the \(N\) to a maximum distance within which to sample. The distance will be calculated as \(\text{std_multiplier} \times \sqrt{N \times \text{in_sqrt_multiplier}}\). Useful only for performance improvements in large systems.

Parameters:

  • std_multiplier – The Z-Score, the multiplier of the standard deviation of the end-to-end distribution. E.g., 3. for 99.9994% of all conformations.

  • in_sqrt_multiplier – The multiplier with the \(N\) in the square root. Probably \(<b^2>\).

validate(self: pylimer_tools_cpp.MCUniverseGenerator) → None

Check whether the internal state of the generator is valid. Throws errors if not. Should in principle always be valid when called from Python; if not, there is a bug in the code.