kTAM¶
rgrow.KTAM
¶
__module__ = 'rgrow.rgrow'
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
alpha
property
¶
bond_names
property
¶
energy_ns
property
¶
energy_we
property
¶
g_se
property
¶
has_duples
property
¶
kf
property
¶
tile_colors
property
¶
tile_concs
property
¶
tile_edges
property
¶
tile_names
property
¶
Names of tiles, by tile number.
__repr__()
method descriptor
¶
Return repr(self).
calc_committor(state, cutoff_size, num_trials, max_time=None, max_events=None)
method descriptor
¶
Calculate the committor function for a state: the probability that when a simulation is started from that state, the assembly will grow to a larger size (cutoff_size) rather than melting to zero tiles.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The state to analyze |
required |
cutoff_size
|
int
|
Size threshold for commitment |
required |
num_trials
|
int
|
Number of trials to run |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum events per trial |
None
|
Returns:
| Type | Description |
|---|---|
float
|
Probability of reaching cutoff_size (between 0.0 and 1.0) |
calc_committor_adaptive(state, cutoff_size, conf_interval_margin, max_time=None, max_events=None)
method descriptor
¶
Calculate the committor function for a state using adaptive sampling: the probability that when a simulation is started from that state, the assembly will grow to a larger size (cutoff_size) rather than melting to zero tiles. Automatically determines the number of trials needed to achieve a specified confidence interval margin.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The state to analyze |
required |
cutoff_size
|
int
|
Size threshold for commitment |
required |
conf_interval_margin
|
float
|
Confidence interval margin (e.g., 0.05 for 5%) |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum events per trial |
None
|
Returns:
| Type | Description |
|---|---|
tuple[float, int]
|
Tuple of (probability of reaching cutoff_size, number of trials run) |
calc_committor_threshold_test(state, cutoff_size, threshold, confidence_level, max_time=None, max_events=None, max_trials=None, return_on_max_trials=False)
method descriptor
¶
Determine whether the committor probability for a state is above or below a threshold with a specified confidence level using adaptive sampling.
This function uses adaptive sampling to determine with the desired confidence whether the true committor probability is above or below the given threshold. It continues sampling until the confidence interval is narrow enough to make a definitive determination.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The state to analyze |
required |
cutoff_size
|
int
|
Size threshold for commitment |
required |
threshold
|
float
|
The probability threshold to compare against (e.g., 0.5) |
required |
confidence_level
|
float
|
Confidence level for the threshold test (e.g., 0.95 for 95% confidence) |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum events per trial |
None
|
max_trials
|
int
|
Maximum number of trials to run (default: 100000) |
None
|
return_on_max_trials
|
bool
|
If True, return results even when max_trials is exceeded (default: False) |
False
|
ci_confidence_level
|
float
|
Confidence level for the returned confidence interval (default: None, no CI returned) Can be different from confidence_level (e.g., test at 95%, show 99% CI) |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, float, tuple[float, float] | None, int, bool]
|
Tuple of (is_above_threshold, probability_estimate, confidence_interval, num_trials, exceeded_max_trials) where: - is_above_threshold: True if probability is above threshold with given confidence - probability_estimate: The estimated probability - confidence_interval: Tuple of (lower_bound, upper_bound) or None if ci_confidence_level not provided - num_trials: Number of trials performed - exceeded_max_trials: True if max_trials was exceeded (warning flag) |
calc_committors_adaptive(states, cutoff_size, conf_interval_margin, max_time=None, max_events=None)
method descriptor
¶
Calculate the committor function for multiple states using adaptive sampling.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
List[State]
|
The states to analyze |
required |
cutoff_size
|
int
|
Size threshold for commitment |
required |
conf_interval_margin
|
float
|
Confidence interval margin (e.g., 0.05 for 5%) |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum events per trial |
None
|
Returns:
| Type | Description |
|---|---|
tuple[NDArray[float64], NDArray[usize]]
|
Tuple of (committor probabilities, number of trials for each state) |
calc_dimers()
method descriptor
¶
Calculate information about the dimers the system is able to form.
Returns:
| Type | Description |
|---|---|
List[DimerInfo]
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the system doesn't support dimer calculation |
calc_forward_probabilities_adaptive(states, conf_interval_margin, forward_step=1, max_time=None, max_events=None)
method descriptor
¶
Calculate forward probabilities adaptively for multiple states.
Uses adaptive sampling for each state in parallel to determine forward probabilities with specified confidence intervals.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
list[State]
|
List of initial states to analyze |
required |
forward_step
|
int
|
Number of tiles to grow beyond current size for each state (default: 1) |
1
|
conf_interval_margin
|
float
|
Desired confidence interval margin (e.g., 0.05 for 5%) |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum number of events per trial |
None
|
Returns:
| Type | Description |
|---|---|
tuple[NDArray[float64], NDArray[usize]]
|
Tuple of (forward probabilities, number of trials for each state) |
calc_forward_probability(state, num_trials, forward_step=1, max_time=None, max_events=None)
method descriptor
¶
Calculate forward probability for a given state.
This function calculates the probability that a state will grow by at least
forward_step tiles before shrinking to size 0. Unlike calc_committor which
uses a fixed cutoff size, this uses a dynamic cutoff based on the current
state size plus the forward_step parameter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The initial state to analyze |
required |
forward_step
|
int
|
Number of tiles to grow beyond current size (default: 1) |
1
|
num_trials
|
int
|
Number of simulation trials to run |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum number of events per trial |
None
|
Returns:
| Type | Description |
|---|---|
float
|
Probability of reaching forward_step additional tiles (between 0.0 and 1.0) |
calc_forward_probability_adaptive(state, conf_interval_margin, forward_step=1, max_time=None, max_events=None)
method descriptor
¶
Calculate forward probability adaptively for a given state.
Uses adaptive sampling to determine the number of trials needed based on a confidence interval margin. Runs until the confidence interval is narrow enough.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The initial state to analyze |
required |
forward_step
|
int
|
Number of tiles to grow beyond current size (default: 1) |
1
|
conf_interval_margin
|
float
|
Desired confidence interval margin (e.g., 0.05 for 5%) |
required |
max_time
|
float
|
Maximum simulation time per trial |
None
|
max_events
|
int
|
Maximum number of events per trial |
None
|
Returns:
| Type | Description |
|---|---|
tuple[float, int]
|
Tuple of (forward probability, number of trials run) |
calc_mismatch_locations(state)
method descriptor
¶
Calculate the locations of mismatches in the state.
This returns a copy of the canvas, with the values set to 0 if there is no mismatch in the location, and > 0, in a model defined way, if there is at least one mismatch. Most models use v = 8N + 4E + 2*S + W, where N, E, S, W are the four directions. Thus, a tile with mismatches to the E and W would have v = 4+2 = 6.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State or FFSStateRef
|
The state to calculate mismatches for. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
An array of the same shape as the state's canvas, with the values set as described above. |
calc_mismatches(state)
method descriptor
¶
Calculate the number of mismatches in a state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State or FFSStateRef
|
The state to calculate mismatches for. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The number of mismatches. |
See also
calc_mismatch_locations Calculate the location and direction of mismatches, not jus the number.
color_canvas(state)
method descriptor
¶
Returns the current canvas for state as an array of tile colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State, FFSStateRef, or NDArray
|
The state or canvas array to colorize. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[uint8]
|
The current canvas for the state, as an array of RGBA colors with shape (rows, cols, 4). |
evolve(state, for_events=None, total_events=None, for_time=None, total_time=None, size_min=None, size_max=None, for_wall_time=None, require_strong_bound=True, show_window=False, start_window_paused=True, parallel=True, initial_timescale=None, initial_max_events_per_sec=None)
method descriptor
¶
evolve(state: State, for_events: int | None = None, total_events: int | None = None, for_time: float | None = None, total_time: float | None = None, size_min: int | None = None, size_max: int | None = None, for_wall_time: float | None = None, require_strong_bound: bool = True, show_window: bool = False, start_window_paused: bool = True, parallel: bool = True, initial_timescale: float | None = None, initial_max_events_per_sec: int | None = None) -> EvolveOutcome
evolve(state: Sequence[State], for_events: int | None = None, total_events: int | None = None, for_time: float | None = None, total_time: float | None = None, size_min: int | None = None, size_max: int | None = None, for_wall_time: float | None = None, require_strong_bound: bool = True, show_window: bool = False, start_window_paused: bool = True, parallel: bool = True, initial_timescale: float | None = None, initial_max_events_per_sec: int | None = None) -> List[EvolveOutcome]
evolve(state: State | Sequence[State], for_events: int | None = None, total_events: int | None = None, for_time: float | None = None, total_time: float | None = None, size_min: int | None = None, size_max: int | None = None, for_wall_time: float | None = None, require_strong_bound: bool = True, show_window: bool = False, start_window_paused: bool = True, parallel: bool = True, initial_timescale: float | None = None, initial_max_events_per_sec: int | None = None) -> EvolveOutcome | List[EvolveOutcome]
Evolve a state (or states), with some bounds on the simulation.
If evolving multiple states, the bounds are applied per-state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State or Sequence[State]
|
The state or states to evolve. |
required |
for_events
|
int
|
Stop evolving each state after this many events. |
None
|
total_events
|
int
|
Stop evelving each state when the state's total number of events (including previous events) reaches this. |
None
|
for_time
|
float
|
Stop evolving each state after this many seconds of simulated time. |
None
|
total_time
|
float
|
Stop evolving each state when the state's total time (including previous steps) reaches this. |
None
|
size_min
|
int
|
Stop evolving each state when the state's number of tiles is less than or equal to this. |
None
|
size_max
|
int
|
Stop evolving each state when the state's number of tiles is greater than or equal to this. |
None
|
for_wall_time
|
float
|
Stop evolving each state after this many seconds of wall time. |
None
|
require_strong_bound
|
bool
|
Require that the stopping conditions are strong, i.e., they are guaranteed to be eventually satisfied under normal conditions. |
True
|
show_window
|
bool
|
Show a graphical UI window while evolving (requires rgrow-gui to be installed, and a single state). |
False
|
start_window_paused
|
bool
|
If show_window is True, start the GUI window in a paused state. Defaults to True. |
True
|
parallel
|
bool
|
Use multiple threads. |
True
|
initial_timescale
|
float
|
If show_window is True, set the initial timescale (sim_time/real_time) in the GUI. None means unlimited. |
None
|
initial_max_events_per_sec
|
int
|
If show_window is True, set the initial max events per second limit in the GUI. None means unlimited. |
None
|
Returns:
| Type | Description |
|---|---|
EvolveOutcome or List[EvolveOutcome]
|
The outcome (stopping condition) of the evolution. If evolving a single state, returns a single outcome. |
name_canvas(state)
method descriptor
¶
Returns the current canvas for state as an array of tile names. 'empty' indicates empty locations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State or FFSStateRef
|
The state to return. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[str]
|
The current canvas for the state, as an array of tile names. |
place_tile(state, point, tile, replace=True)
method descriptor
¶
Place a tile at a point in the given state.
This updates tile counts and rates but does not increment the event counter or record events in the state tracker.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
PyState
|
The state to modify. |
required |
point
|
tuple of int
|
The coordinates at which to place the tile (i, j). |
required |
tile
|
int
|
The tile number to place. |
required |
replace
|
bool
|
If True (default), any existing tile at the target site is removed first. If False, raises an error if the site is occupied. |
True
|
Returns:
| Type | Description |
|---|---|
float
|
The energy change from placing the tile. |
read_json(filename)
staticmethod
¶
Read a system from a JSON file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The name of the file to read from. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
|
run_ffs(config=Ellipsis, **kwargs)
method descriptor
¶
Run FFS.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
FFSRunConfig
|
The configuration for the FFS run. |
Ellipsis
|
**kwargs
|
Any
|
FFSRunConfig parameters as keyword arguments. |
required |
Returns:
| Type | Description |
|---|---|
FFSRunResult
|
The result of the FFS run. |
set_param(param_name, value)
method descriptor
¶
Set a system parameter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
param_name
|
str
|
The name of the parameter to set. |
required |
value
|
Any
|
The value to set the parameter to. |
required |
Returns:
| Type | Description |
|---|---|
NeededUpdate
|
The type of state update needed. This can be passed to
|
state_energy(state)
method descriptor
¶
Calculate the total free energy of the entire state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The state to calculate energy for. |
required |
Returns:
| Type | Description |
|---|---|
float
|
The total energy of the state. |
tile_color(tile_number)
method descriptor
¶
Given a tile number, return the color of the tile.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tile_number
|
int
|
The tile number. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
The color of the tile, as a list of 4 integers (RGBA). |
tile_number_from_name(tile_name)
method descriptor
¶
Given a tile name, return the tile number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tile_name
|
str
|
The name of the tile. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The tile number. |
total_free_energy_from_point(state, p)
method descriptor
¶
Calculate the total free energy contribution from a specific point. This includes the energy from the N and W bonds, and the entropic cost of mixing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The state to calculate free energy for. |
required |
p
|
tuple[int, int]
|
The (row, col) coordinates of the point. |
required |
Returns:
| Type | Description |
|---|---|
float
|
The total free energy contribution from the point. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the point is out of bounds. |
update_state(state, needed=Ellipsis)
method descriptor
¶
Recalculate a state's rates.
This is usually needed when a parameter of the system has been changed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
The state to update. |
required |
needed
|
NeededUpdate
|
The type of update needed. If not provided, all locations will be recalculated. |
Ellipsis
|
write_json(filename)
method descriptor
¶
Write the system to a JSON file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
The name of the file to write to. |
required |