Core Functions¶

The core functions module contains the fundamental building blocks for creating and manipulating DNA megastructures.

Megastructures¶

The main class for representing and manipulating DNA megastructures.

crisscross.core_functions.megastructures ¶

Megastructure ¶

Megastructure(
    slat_array=None,
    slat_coordinate_dict=None,
    layer_interface_orientations=None,
    connection_angle="90",
    slat_type_dict=None,
    import_design_file=None,
)

Convenience class that bundles the entire details of a megastructure including slat positions, seed handles and cargo.

PARAMETER	DESCRIPTION
`slat_array`	Array of slat positions (3D - X,Y, layer ID) containing the positions of all slats in the design. DEFAULT: `None`
`slat_coordinate_dict`	Dictionary of slat coordinates (key = (layer, slat ID), value = list of (y,x) coordinates). This is optional, but required to properly adjust positions of double-barrel slats. DEFAULT: `None`
`layer_interface_orientations`	The direction each slat will be facing in the design. E.g. for a 2 layer design, [2, 5, 2] implies that the bottom layer will have H2 handles sticking out, the connecting interface will have H5 handles and the top layer will have H2 handles again. DEFAULT: `None`
`connection_angle`	The angle at which the slats will be connected. For now, only 90 and 60 grids are supported. DEFAULT: `'90'`
`slat_type_dict`	Dictionary of slat types (key = (layer, slat ID), value = slat type string) DEFAULT: `None`
`import_design_file`	If provided, the design will be imported from the specified file instead of being built from scratch. DEFAULT: `None`

direct_handle_assign ¶

direct_handle_assign(
    slat,
    slat_position_index,
    slat_side,
    handle_val,
    category,
    descriptor,
    sel_plates=None,
    update=False,
    suppress_warnings=False,
)

Assigns a handle to a slat's specific side/position.

PARAMETER	DESCRIPTION
`slat`	Slat object to attach to.
`slat_position_index`	Position along slat (1-indexed).
`slat_side`	2 or 5.
`handle_val`	Actual payload handle value.
`category`	SEED, CARGO, ASSEMBLY_HANDLE OR ASSEMBLY_ANTIHANDLE
`descriptor`	Long-form description of handle contents
`sel_plates`	Plates from which to extract sequence data DEFAULT: `None`
`update`	Only update a handle's value instead of setting a new one. DEFAULT: `False`
`suppress_warnings`	Set to true to suppress warnings when overwriting existing handles. DEFAULT: `False`

smart_set_slat_handle ¶

smart_set_slat_handle(
    slat_key,
    position,
    side,
    handle_val,
    category,
    descriptor,
    sel_plates=None,
    suppress_warnings=False,
    coordinate_to_slats=None,
)

Sets a handle on a slat and propagates it through phantom slats and linked handles according to the design rules.

PARAMETER	DESCRIPTION
`slat_key`	Slat ID string (e.g., 'layer1-slat5')
`position`	Position index on the slat (1-based)
`side`	Handle side (2 or 5)
`handle_val`	Handle value/ID
`category`	Handle category ('ASSEMBLY_HANDLE', 'ASSEMBLY_ANTIHANDLE', 'CARGO', 'SEED', etc.)
`descriptor`	Longer-form description of handle contents
`sel_plates`	Optional plate object to extract handle sequences from DEFAULT: `None`
`suppress_warnings`	If True, suppresses overwrite warnings DEFAULT: `False`
`coordinate_to_slats`	Dictionary mapping (y, x, layer) to a list of (slat_key, position) at that coordinate (if not provided will be computed on-the-fly). DEFAULT: `None`

RETURNS	DESCRIPTION
	N/A

smart_handle_delete ¶

smart_handle_delete(slat_key, slat_position, slat_side, coordinate_to_slats=None)

Deletes a handle from a slat and propagates it through phantom slats and linked handles according to standard design rules.

PARAMETER	DESCRIPTION
`slat_key`	The target slat ID. Cannot be a phantom slat.
`slat_position`	Position index on the slat (1-based).
`slat_side`	2 or 5
`coordinate_to_slats`	Can pre-compute slat lookup map if desired. DEFAULT: `None`

enforce_phantom_links_on_assembly_handle_array ¶

enforce_phantom_links_on_assembly_handle_array(handle_array, modify_in_place=True)

Synchronizes handle values across all linked positions in an assembly handle array.

This method ensures that: 1. Phantom slats share handle values with their parent reference slats 2. Physically connected slats at layer interfaces have matching handle/antihandle pairs 3. Explicitly linked handles (via link_manager) share the same values 4. Enforced values (zeros or specific handle IDs) are applied where required

IMPORTANT: Call this after random handle generation but before evolution scoring, to ensure the handle array respects all linking constraints.

Algorithm: - Iterates through every non-zero position in the 3D handle array - For each position, triggers _recursive_propagate_handle to propagate the value through all linked handles (phantoms, physical attachments, explicit links) - The recursion handles phantom networks, physical attachments, and explicit links

PARAMETER	DESCRIPTION
`handle_array`	3D numpy array of handle values with shape (y, x, layer_interface)
`modify_in_place`	If True, modifies the input array; if False, creates a copy DEFAULT: `True`

RETURNS	DESCRIPTION
	Modified handle array with all links enforced

assign_assembly_handles ¶

assign_assembly_handles(
    handle_arrays,
    crisscross_handle_plates=None,
    crisscross_antihandle_plates=None,
    suppress_warnings=False,
)

Assigns crisscross handles to the slats based on the handle arrays provided. V.IMP - NO PHANTOM HANDLE VALIDATION OCCURS HERE, MAKE SURE TO DO THIS BEFORE RUNNING THIS FUNCTION.

PARAMETER	DESCRIPTION
`handle_arrays`	3D array of handle values (X, Y, layer) where each value corresponds to a handle ID.
`crisscross_handle_plates`	Crisscross handle plates. If not supplied, a placeholder will be added to the slat instead. DEFAULT: `None`
`crisscross_antihandle_plates`	Crisscross anti-handle plates. If not supplied, a placeholder will be added to the slat instead. TODO: this function assumes the pattern is always handle -> antihandle -> handle -> antihandle etc. Can we make this customizable? DEFAULT: `None`

RETURNS	DESCRIPTION
	N/A

assign_seed_handles ¶

assign_seed_handles(seed_dict, seed_plate=None)

Assigns seed handles to the slats based on the seed dictionary provided.

generate_slat_occupancy_grid ¶

generate_slat_occupancy_grid(use_original_slat_array=False, category='original_slats')

Generates a 3D occupancy grid of the slats in the design.

PARAMETER	DESCRIPTION
`use_original_slat_array`	If True, uses the original slat array instead of the current slat state. DEFAULT: `False`
`category`	'original_slats', 'phantom_slats' or 'all_slats' - for phantoms, the phantom parent IDs are used. DEFAULT: `'original_slats'`

RETURNS	DESCRIPTION
	3D numpy array with slat IDs at each position (X, Y, layer)

generate_assembly_handle_grid ¶

generate_assembly_handle_grid(category='original_slats', create_mutation_mask=False)

Generates a 3D occupancy grid of the assembly handles in the design.

PARAMETER	DESCRIPTION
`category`	'original_slats', 'phantom_slats' or 'all_slats' DEFAULT: `'original_slats'`
`create_mutation_mask`	If True, creates an integer mask indicating positions that can be mutated. Areas with linked handles are given the same integers. These integers have nothing to do with handle IDs. DEFAULT: `False`

RETURNS	DESCRIPTION
	3D numpy array with handle IDs at each position (X, Y, layer)

assign_cargo_handles_with_dict ¶

assign_cargo_handles_with_dict(cargo_dict, cargo_plate=None)

Assigns cargo handles to the megastructure slats based on the cargo dictionary provided.

PARAMETER	DESCRIPTION
`cargo_dict`	Dictionary of cargo placements (key = slat position, layer, handle orientation, value = cargo ID)
`cargo_plate`	The cargo plate from which cargo will be assigned. If not provided, a placeholder will be assigned instead. DEFAULT: `None`

RETURNS	DESCRIPTION
	N/A

convert_cargo_array_into_cargo_dict ¶

convert_cargo_array_into_cargo_dict(
    cargo_array, cargo_keymap, layer, handle_orientation=None
)

Converts a cargo array into a dictionary that can be used to assign cargo handles to the slats.

PARAMETER	DESCRIPTION
`cargo_array`	Numpy array with cargo IDs (and 0s where no cargo is present).
`cargo_keymap`	A dictionary converting cargo ID numbers into unique strings.
`layer`	The layer the cargo should be assigned to (either top, bottom or a specific number)
`handle_orientation`	The specific slat handle orientation to which the cargo is assigned. DEFAULT: `None`

RETURNS	DESCRIPTION
	Dictionary of converted cargo.

assign_cargo_handles_with_array ¶

assign_cargo_handles_with_array(
    cargo_array, cargo_key, cargo_plate=None, layer="top", handle_orientation=None
)

Assigns cargo handles to the megastructure slats based on the cargo array provided.

PARAMETER	DESCRIPTION
`cargo_array`	2D array containing cargo IDs (must match plate provided).
`cargo_key`	Dictionary mapping cargo IDs to cargo unique names for proper identification.
`cargo_plate`	Plate class with sequences to draw from. If not provided, a placeholder will be assigned instead. DEFAULT: `None`
`layer`	Either 'top' or 'bottom', or the exact layer ID required. DEFAULT: `'top'`
`handle_orientation`	If a middle layer is specified, then the handle orientation must be provided since there are always two options available. DEFAULT: `None`

patch_placeholder_handles ¶

patch_placeholder_handles(plates)

Patches placeholder handles with actual handles based on the plates provided.

PARAMETER	DESCRIPTION
`plates`	List of plates from which to extract handles.

RETURNS	DESCRIPTION
	N/A

patch_flat_staples ¶

patch_flat_staples(flat_plate)

Fills up all remaining holes in slats with no-handle control sequences.

PARAMETER	DESCRIPTION
`flat_plate`	Plate class with flat sequences to draw from.

get_slats_by_assembly_stage ¶

get_slats_by_assembly_stage(minimum_handle_cutoff=16)

Runs through the design and separates out all slats into groups sorted on their predicted assembly stage.

PARAMETER	DESCRIPTION
`minimum_handle_cutoff`	Minimum number of handles that need to be present for a slat to be considered stably setup. DEFAULT: `16`

RETURNS	DESCRIPTION
	Dict of slats (key = slat ID, value = assembly order)

get_slat_match_counts ¶

get_slat_match_counts(use_external_handle_array=None)

Runs through the design and counts how many slats have a certain number of connections (matches) to other slats. Useful for computing the hamming distance of a design with variable slat types.

RETURNS	DESCRIPTION
	Dictionary of match counts (key = number of matches, value = number of slat pairs with that many matches), and a connection graph that lists all slat pairs with a certain number of matches. TODO: what to do in the case of slats with multiple layers e.g. the sierpinski slats? TODO: as with other functions, this function also assumes handle -> antihandle -> handle -> antihandle pattern.

get_bag_of_slat_handles ¶

get_bag_of_slat_handles(
    use_original_slat_array=False,
    use_external_handle_array=None,
    remove_blank_slats=False,
)

Obtains two dictionaries - both containing the arrays corresponding to the handle positions of each slat in the megastructure (one for handles and one for antihandles). The keys correspond to the slat ID while the values contain individual numpy handle arrays, one for each slat. The handle arrays represent the actual 2D shape of the slat in the design. Non-2D 60 degree slats are converted into 2D triangular coordinates to make handle match computation significantly simpler.

get_parasitic_interactions ¶

get_parasitic_interactions()

Computes the match strength score of the megastructure design based on the assembly handles present. 4 items are provided in a dictionary: - the worst match score (i.e. the maximum number of matches between any two slats in the design) - the mean log score (i.e. the log of the mean number of matches between all slat pairs in the design) - the similarity score (i.e. the maximum number of matches between slats of the same type, which could result in a slat taking the place of another slat in the design if strong enough) - the full match histogram, which could be helpful for investigating designs with unexpected scores.

create_graphical_slat_view ¶

create_graphical_slat_view(
    save_to_folder=None,
    instant_view=True,
    include_cargo=True,
    include_seed=True,
    filename_prepend="",
    colormap=None,
    cargo_colormap=None,
)

Creates a graphical view of the slats, cargo and seeds in the design. Refer to the graphics module for more details.

PARAMETER	DESCRIPTION
`save_to_folder`	Set to the filepath of a folder where all figures will be saved. DEFAULT: `None`
`instant_view`	Set to True to plot the figures immediately to your active view. DEFAULT: `True`
`include_cargo`	Set to True to include cargo in the graphical view. DEFAULT: `True`
`include_seed`	Set to True to include the seed in the graphical view. DEFAULT: `True`
`filename_prepend`	String to prepend to the filename of generated figures. DEFAULT: `''`
`colormap`	The colormap to sample from for each additional layer. DEFAULT: `None`
`cargo_colormap`	The colormap to sample from for each cargo type. DEFAULT: `None`

RETURNS	DESCRIPTION
	N/A

create_graphical_assembly_handle_view ¶

create_graphical_assembly_handle_view(
    save_to_folder=None, instant_view=True, filename_prepend="", colormap=None
)

Creates a graphical view of the assembly handles in the design. Refer to the graphics module for more details.

PARAMETER	DESCRIPTION
`save_to_folder`	Set to the filepath of a folder where all figures will be saved. DEFAULT: `None`
`instant_view`	Set to True to plot the figures immediately to your active view. DEFAULT: `True`
`filename_prepend`	String to prepend to the filename of generated figures. DEFAULT: `''`
`colormap`	The colormap to sample from for each additional layer. DEFAULT: `None`

RETURNS	DESCRIPTION
	N/A

create_graphical_3D_view ¶

create_graphical_3D_view(
    save_folder,
    window_size=(2048, 2048),
    filename_prepend="",
    colormap=None,
    cargo_colormap=None,
)

Creates a 3D video of the megastructure slat design.

PARAMETER	DESCRIPTION
`save_folder`	Folder to save all video to.
`window_size`	Resolution of video generated. 2048x2048 seems reasonable in most cases. DEFAULT: `(2048, 2048)`
`filename_prepend`	String to prepend to the filename of the video. DEFAULT: `''`
`colormap`	Colormap to extract layer colors from DEFAULT: `None`
`cargo_colormap`	Colormap to extract cargo colors from DEFAULT: `None`

RETURNS	DESCRIPTION
	N/A

create_blender_3D_view ¶

create_blender_3D_view(
    save_folder,
    animate_assembly=False,
    animation_type="translate",
    custom_assembly_groups=None,
    slat_translate_dict=None,
    minimum_slat_cutoff=15,
    camera_spin=False,
    correct_slat_entrance_direction=True,
    force_slat_color_by_layer=True,
    colormap=None,
    cargo_colormap=None,
    slat_flip_list=None,
    include_bottom_light=False,
    filename_prepend="",
)

Creates a 3D model of the megastructure slat design as a Blender file.

PARAMETER	DESCRIPTION
`save_folder`	Folder to save all video to.
`animate_assembly`	Set to true to also generate an animation of the design being assembled group by group. DEFAULT: `False`
`animation_type`	Type of animation to generate. Options are 'translate' and 'wipe_in'. DEFAULT: `'translate'`
`custom_assembly_groups`	If set, will use the specific provided dictionary to assign slats to the animation order. DEFAULT: `None`
`slat_translate_dict`	If set, will use the specific provided dictionary to assign specific animation translation distances to each slat. DEFAULT: `None`
`minimum_slat_cutoff`	Minimum number of slats that need to be present for a slat to be considered stable. You might want to vary this number as certain designs have staggers that don't allow for a perfect 16-slat binding system. DEFAULT: `15`
`camera_spin`	Set to true to have camera spin around object during the animation. DEFAULT: `False`
`correct_slat_entrance_direction`	If set to true, will attempt to correct the slat entrance animation to always start from a place that is supported. DEFAULT: `True`
`force_slat_color_by_layer`	If set to true, will force the slat color to be the same as the layer color, regardless of the animation groups. DEFAULT: `True`
`colormap`	Colormap to extract layer colors from DEFAULT: `None`
`cargo_colormap`	Colormap to extract cargo colors from DEFAULT: `None`
`slat_flip_list`	List of slat IDs - if a slat is in this list, its animation direction will be flipped. This cannot be used in conjunction with the correct_slat_entrance_direction parameter. DEFAULT: `None`
`include_bottom_light`	Set to true to add a light source at the bottom of the design. DEFAULT: `False`
`filename_prepend`	String to prepend to the filename of the Blender file. DEFAULT: `''`

RETURNS	DESCRIPTION
	N/A

create_standard_graphical_report ¶

create_standard_graphical_report(
    output_folder,
    generate_3d_video=True,
    colormap=None,
    cargo_colormap=None,
    filename_prepend="",
)

Generates entire set of graphical reports for the megastructure design.

PARAMETER	DESCRIPTION
`output_folder`	Output folder to save all images to.
`generate_3d_video`	If set to true, will generate a 3D video of the design. DEFAULT: `True`
`colormap`	Colormap to extract layer colors from. DEFAULT: `None`
`cargo_colormap`	Colormap to extract cargo colors from. DEFAULT: `None`
`filename_prepend`	String to prepend to the filename of generated figures. DEFAULT: `''`

RETURNS	DESCRIPTION
	N/A

export_design ¶

export_design(filename, folder)

Exports the entire design to a single excel file. All individual slat, cargo, handle and seed arrays are exported into separate sheets.

PARAMETER	DESCRIPTION
`filename`	Output .xlsx filename
`folder`	Output folder

RETURNS	DESCRIPTION
	N/A

import_design ¶

import_design(file)

Reads in a complete megastructure from an excel file formatted with each array separated in a different sheet.

PARAMETER	DESCRIPTION
`file`	Path to Excel file containing megastructure design

RETURNS	DESCRIPTION
	All arrays and metadata necessary to regenerate the design

Slats¶

Core slat functionality for DNA structure components.

crisscross.core_functions.slats ¶

Slat ¶

Slat(
    ID,
    layer,
    slat_coordinates,
    non_assembly_slat=False,
    unique_color=None,
    layer_color=None,
    slat_type="tube",
    phantom_parent=None,
)

Wrapper class to hold all of a slat's handles and related details.

PARAMETER	DESCRIPTION
`ID`	Slat unique ID (string)
`layer`	Layer position for slat (normally 1 and above, but can set to 0 for special slats such as crossbars)
`slat_coordinates`	Exact positions slat occupies on a 2D grid - either a list of tuples or a dict of lists, where the key is the handle number on the slat
`non_assembly_slat`	If True, this slat is not used for assembly (e.g., crossbar slats) DEFAULT: `False`
`unique_color`	Optional hexcode color to assign a unique color to the slat for graphics DEFAULT: `None`
`phantom_parent`	If this slat is a linked copy of another slat (and thus a 'fake' slat used for handle linking purposes), then set the parent slat here. DEFAULT: `None`

reverse_direction ¶

reverse_direction()

Reverses the handle order on the slat (this should not affect the design placement of the slat).

get_sorted_handles ¶

get_sorted_handles(side='h2')

Returns a sorted list of all handles on the slat (as they can be jumbled up sometimes, depending on the order they were created).

PARAMETER	DESCRIPTION
`side`	h2 or h5 DEFAULT: `'h2'`

RETURNS	DESCRIPTION
	tuple of handle ID and handle dict contents

set_placeholder_handle ¶

set_placeholder_handle(
    handle_id, slat_side, category, value, descriptor, suppress_warnings=False
)

Assigns a placeholder to the slat, instead of a full handle.

PARAMETER	DESCRIPTION
`handle_id`	Handle position on slat
`slat_side`	H2 or H5
`descriptor`	Description to use for placeholder

RETURNS	DESCRIPTION
	N/A

remove_handle ¶

remove_handle(handle_id, slat_side)

Removes a handle from the slat.

PARAMETER	DESCRIPTION
`handle_id`	Handle position on slat
`slat_side`	H2 or H5

RETURNS	DESCRIPTION
	N/A

update_placeholder_handle ¶

update_placeholder_handle(
    handle_id,
    slat_side,
    sequence,
    well,
    plate_name,
    category,
    value,
    concentration,
    descriptor="No Desc.",
)

Updates a placeholder handle with the actual handle.

PARAMETER	DESCRIPTION
`handle_id`	Handle position on slat
`slat_side`	H2 or H5
`sequence`	Exact handle sequence
`well`	Exact plate well
`plate_name`	Exact plate name
`descriptor`	Exact description of handle DEFAULT: `'No Desc.'`

RETURNS	DESCRIPTION
	N/A

set_handle ¶

set_handle(
    handle_id,
    slat_side,
    sequence,
    well,
    plate_name,
    category,
    value,
    concentration,
    descriptor="No Desc.",
)

Defines the full details of a handle on a slat.

PARAMETER	DESCRIPTION
`handle_id`	Handle position on slat
`slat_side`	H2 or H5
`sequence`	Exact handle sequence
`well`	Exact plate well
`plate_name`	Exact plate name
`descriptor`	Exact description of handle DEFAULT: `'No Desc.'`

RETURNS	DESCRIPTION
	N/A

get_molecular_weight ¶

get_molecular_weight()

Calculates the molecular weight of the slat, based on the handles assigned.

RETURNS	DESCRIPTION
	Molecular weight of the slat (in Da)

get_slat_key ¶

get_slat_key(layer, slat_id, phantom_id=None)

Convenience function to generate slat key string.

convert_slat_array_into_slat_objects ¶

convert_slat_array_into_slat_objects(slat_array)

Converts a slat array into a dictionary of slat objects for easy access.

PARAMETER	DESCRIPTION
`slat_array`	3D numpy array of slats - each point should either be a 0 (no slat) or a unique ID (slat here)

RETURNS	DESCRIPTION
	Dictionary of slats

Handle linking system¶

System for managing links between specific handles (links, value enforcing and direct blocks).

crisscross.core_functions.handle_link_manager ¶

HandleLinkManager ¶

HandleLinkManager(handle_link_df=None)

Manages handle linking information for megastructures.

This class tracks three types of constraints on handle values:

Linked Groups: Handles that must share the same value. When one handle in a group changes, all others must change to match.
Stored in: handle_link_to_group (key → group_id) and handle_group_to_link (group_id → list of keys)
Enforced Values: Groups that must have a specific handle value.
Stored in: handle_group_to_value (group_id → value)
Blocked Handles: Individual handles that must be zero (deleted).
Stored in: handle_blocks (list of keys)

Handle keys use the convention: (slat_name, position, helix_side) Example: ('layer1-slat5', 3, 2) means position 3 on H2 side of layer1-slat5.

All group IDs are numeric integers, persisted to file on export.

add_block ¶

add_block(key)

Adds a block to a handle.

PARAMETER	DESCRIPTION
`key`	(slat_name, position, side)

remove_block ¶

remove_block(key)

Removes a block from a handle.

PARAMETER	DESCRIPTION
`key`	(slat_name, position, side)

remove_link ¶

remove_link(key)

Removes a link from a handle.

PARAMETER	DESCRIPTION
`key`	(slat_name, position, side)

remove_group ¶

remove_group(group_id)

Removes an entire handle link group.

PARAMETER	DESCRIPTION
`group_id`	Group ID to remove

add_link ¶

add_link(key_1, key_2)

Adds a link between two handles.

PARAMETER	DESCRIPTION
`key_1`	(slat_name, position, side)
`key_2`	(slat_name, position, side)