Skip to content

SDC2DSquare — 2D Scaffolded DNA Computer

The rgrow.sdc2d module provides a 2D scaffolded DNA tile assembly model on a square grid. Strands have five glues (North, East, South, West, Bottom); the lateral glue order matches kTAM (clockwise from north), with the bottom glue facing the scaffold. All four lateral edges and the scaffold edge share a single glue namespace.

The model uses unitful (kcal/mol, Molar, Kelvin) thermodynamics with per-glue (ΔG_37, ΔS) parameters, mirroring SDC1D.

SDC2DParams

rgrow.sdc2d.SDC2DParams dataclass

Parameters for an SDC2DSquare system.

Attributes:

Name Type Description
strands list[SDC2DStrand]

Strands available in solution.
scaffold list[list[str | None]]

2D layout of glue names. scaffold[r][c] is the glue at row r, column c; use None for "no scaffold glue here". Border cells outside the canvas-usable region (the 2-cell border that Square canvases enforce) should be None.
scaffold_concentration float

Effective molar concentration of the scaffold.
glue_dg37_ds Mapping[str | tuple[str, str], tuple[float, float] | str]

Per-glue or per-pair (ΔG_37, ΔS) thermodynamics, or a DNA sequence string. Single namespace shared by all four lateral edges and the bottom edge.
k_f float

Forward rate constant (1/(M·s)).
temperature float

Temperature in Celsius.
seed list[tuple[int, int, str]]

Anchor strands as (row, col, strand_name) tuples; pinned strands cannot detach.
Source code in rgrow-python/rgrow/sdc2d.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@dataclass
class SDC2DParams:
    """Parameters for an SDC2DSquare system.

    Attributes
    ----------
    strands
        Strands available in solution.
    scaffold
        2D layout of glue names. ``scaffold[r][c]`` is the glue at row ``r``,
        column ``c``; use ``None`` for "no scaffold glue here". Border cells
        outside the canvas-usable region (the 2-cell border that ``Square``
        canvases enforce) should be ``None``.
    scaffold_concentration
        Effective molar concentration of the scaffold.
    glue_dg37_ds
        Per-glue or per-pair `(ΔG_37, ΔS)` thermodynamics, or a DNA sequence
        string. Single namespace shared by all four lateral edges and the
        bottom edge.
    k_f
        Forward rate constant (1/(M·s)).
    temperature
        Temperature in Celsius.
    seed
        Anchor strands as ``(row, col, strand_name)`` tuples; pinned strands
        cannot detach.
    """

    strands: list[SDC2DStrand] = field(default_factory=list)
    scaffold: list[list[str | None]] = field(default_factory=list)
    scaffold_concentration: float = 1e-9
    glue_dg37_ds: Mapping[
        str | tuple[str, str], tuple[float, float] | str
    ] = field(default_factory=dict)
    k_f: float = 1e6
    temperature: float = 37.0
    seed: list[tuple[int, int, str]] = field(default_factory=list)

SDC2DStrand

rgrow.sdc2d.SDC2DStrand dataclass

A strand with five glues (N, E, S, W, Bottom).

Lateral glue order matches kTAM: clockwise from north (N, E, S, W), followed by the scaffold-facing bottom glue.

Source code in rgrow-python/rgrow/sdc2d.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@dataclass
class SDC2DStrand:
    """A strand with five glues (N, E, S, W, Bottom).

    Lateral glue order matches kTAM: clockwise from north (N, E, S, W),
    followed by the scaffold-facing bottom glue.
    """

    concentration: float = 1e-6
    north_glue: str | None = None
    east_glue: str | None = None
    south_glue: str | None = None
    west_glue: str | None = None
    bottom_glue: str | None = None
    name: str | None = None
    color: str | None = None

SDC2DSquare

Construct an SDC2DSquare system from an SDC2DParams instance. In addition to the kinetic simulation interface (evolve, setup_state, get_param, set_param, etc.), SDC2DSquare exposes exact finite-grid thermodynamics methods. These are exact but exponential in the smaller scaffold dimension.

rgrow.sdc2d.SDC2DSquare

__doc__ = '' 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'.

__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'.

bond_names property

glue_names property

kf property

strand_names property

temperature property

tile_colors property

tile_names property

Names of tiles, by tile number.

__new__(*args, **kwargs) builtin

Create and return a new object. See help(type) for accurate signature.

__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, parallel=True) 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 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.

log_partial_partition_function(constraints) method descriptor

Exact log partition function under per-site tile constraints.

log_partition_function() method descriptor

Exact log partition function, exponential in the smaller grid dimension.

mfe_config() method descriptor

Exact minimum free energy configuration and free energy.

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.

partial_partition_function(constraints) method descriptor

Exact partition function under per-site tile constraints.

partition_function() method descriptor

Exact partition function as a float.

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

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 update_state to update the state.

state_g(state) method descriptor

Physical free energy of a 2D 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.

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