segmentmodel.py

import pdb
import subprocess
from pathlib import Path
import numpy as np
import random
from .arbdmodel import PointParticle, ParticleType, Group, ArbdModel
from .arbdmodel.coords import rotationAboutAxis, quaternion_from_matrix, quaternion_to_matrix
from .arbdmodel.nonbonded import *
from copy import copy, deepcopy
from .model.nbPot import nbDnaScheme

from . import get_resource_path

import re

from scipy.special import erf
import scipy.optimize as opt
from scipy import interpolate

from .model.CanonicalNucleotideAtoms import canonicalNtFwd, canonicalNtRev, seqComplement
from .model.CanonicalNucleotideAtoms import enmTemplateHC, enmTemplateSQ, enmCorrectionsHC

from .model.spring_from_lp import k_angle as angle_spring_from_lp
from .model.spring_from_lp import k_twist as twist_spring_from_lp

import csv

# import pdb
"""
TODO:
 + fix handling of crossovers for atomic representation
 + map to atomic representation
    + add nicks
    + transform ssDNA nucleotides 
    - shrink ssDNA
    + shrink dsDNA backbone
    + make orientation continuous
    + sequence
    + handle circular dna
 + ensure crossover bead potentials aren't applied twice 
 + remove performance bottlenecks
 - test for large systems
 + assign sequence
 + ENM
 - rework Location class 
 - remove recursive calls
 - document
 - develop unit test suite
 - refactor parts of Segment into an abstract_polymer class
 - make each call generate_bead_model, generate_atomic_model, generate_oxdna_model return an object with only have a reference to original object
"""

_DEBUG_TRACE = False

class CircularDnaError(Exception):
    pass

class ParticleNotConnectedError(Exception):
    pass

class Location():
    """ Site for connection within an object """
    def __init__(self, container, address, type_, on_fwd_strand = True):
        ## TODO: remove cyclic references(?)
        self.container = container
        self.address = address  # represents position along contour length in segment
        # assert( type_ in ("end3","end5") ) # TODO remove or make conditional
        self.on_fwd_strand = on_fwd_strand
        self.type_ = type_
        self.particle = None
        self.connection = None
        self.is_3prime_side_of_connection = None

        self.combine = None     # some locations might be combined in bead model 

    def get_connected_location(self):
        if self.connection is None:
            return None
        else:
            return self.connection.other(self)

    def set_connection(self, connection, is_3prime_side_of_connection):
        self.connection = connection # TODO weakref? 
        self.is_3prime_side_of_connection = is_3prime_side_of_connection

    def get_nt_pos(self):
        try:
            pos = self.container.contour_to_nt_pos(self.address, round_nt=True)
        except:
            if self.address == 0:
                pos = 0
            elif self.address == 1:
                pos = self.container.num_nt-1
            else:
                raise
        return pos

    def delete(self):
        if self.connection is not None:
            self.connection.delete()
        if self.container is not None:
            self.container.locations.remove(self)

    def __repr__(self):
        if self.on_fwd_strand:
            on_fwd = "on_fwd_strand"
        else:
            on_fwd = "on_rev_strand"
        try:
            return "<Location {}.{}[{:d},{}]>".format( self.container.name, self.type_, self.get_nt_pos(), on_fwd )
        except:
            return "<Location {}.{}[{:.2f},{:d}]>".format( self.container.name, self.type_, self.address, self.on_fwd_strand)
        
class Connection():
    """ Abstract base class for connection between two elements """
    def __init__(self, A, B, type_ = None):
        assert( isinstance(A,Location) )
        assert( isinstance(B,Location) )
        self.A = A
        self.B = B
        self.type_ = type_
        
    def other(self, location):
        if location is self.A:
            return self.B
        elif location is self.B:
            return self.A
        else:
            raise Exception("OutOfBoundsError")

    def delete(self):
        self.A.container.connections.remove(self)
        if self.B.container is not self.A.container:
            self.B.container.connections.remove(self)
        self.A.connection = None
        self.B.connection = None

    def __repr__(self):
        return "<Connection {}--{}--{}]>".format( self.A, self.type_, self.B )
        

        
# class ConnectableElement(Transformable):
class ConnectableElement():
    """ Abstract base class """
    def __init__(self, connection_locations=None, connections=None):
        if connection_locations is None: connection_locations = []
        if connections is None: connections = []

        ## TODO decide on names
        self.locations = self.connection_locations = connection_locations
        self.connections = connections

    def get_locations(self, type_=None, exclude=()):
        locs = [l for l in self.connection_locations if (type_ is None or l.type_ == type_) and l.type_ not in exclude]
        counter = dict()
        for l in locs:
            if l in counter:
                counter[l] += 1
            else:
                counter[l] = 1
        assert( np.all( [counter[l] == 1 for l in locs] ) )
        return locs

    def get_location_at(self, address, on_fwd_strand=True, new_type=None):
        loc = None
        if (self.num_nt == 1):
            # import pdb
            # pdb.set_trace()
            ## Assumes that intrahelical connections have been made before crossovers
            for l in self.locations:
                if l.on_fwd_strand == on_fwd_strand and l.connection is None:
                    assert(loc is None)
                    loc = l
            # assert( loc is not None )
        else:
            for l in self.locations:
                if l.address == address and l.on_fwd_strand == on_fwd_strand:
                    assert(loc is None)
                    loc = l
        if loc is None and new_type is not None:
            loc = Location( self, address=address, type_=new_type, on_fwd_strand=on_fwd_strand )
        return loc

    def get_connections_and_locations(self, connection_type=None, exclude=()):
        """ Returns a list with each entry of the form:
            connection, location_in_self, location_in_other """
        type_ = connection_type
        ret = []
        for c in self.connections:
            if (type_ is None or c.type_ == type_) and c.type_ not in exclude:
                if   c.A.container is self:
                    ret.append( [c, c.A, c.B] )
                elif c.B.container is self:
                    ret.append( [c, c.B, c.A] )
                else:
                    import pdb
                    pdb.set_trace()
                    raise Exception("Object contains connection that fails to refer to object")
        return ret

    def _connect(self, other, connection, in_3prime_direction=None):
        ## TODO fix circular references        
        A,B = [connection.A, connection.B]
        if in_3prime_direction is not None:
            A.is_3prime_side_of_connection = not in_3prime_direction
            B.is_3prime_side_of_connection = in_3prime_direction
            
        A.connection = B.connection = connection
        self.connections.append(connection)
        if other is not self:
            other.connections.append(connection)

        l = A.container.locations
        if A not in l: l.append(A)
        l = B.container.locations
        if B not in l: l.append(B)
        

    # def _find_connections(self, loc):
    #     return [c for c in self.connections if c.A == loc or c.B == loc]

class SegmentParticle(PointParticle):
    def __init__(self, type_, position, name="A", **kwargs):
        self.name = name
        self.contour_position = None
        PointParticle.__init__(self, type_, position, name=name, **kwargs)
        self.intrahelical_neighbors = []
        self.other_neighbors = []
        self.locations = []

    def get_intrahelical_above(self, all_types=True):
        """ Returns bead directly above self """
        # assert( len(self.intrahelical_neighbors) <= 2 )
        for b in self.intrahelical_neighbors:
            if b.get_contour_position(self.parent, self.contour_position) > self.contour_position:
                if all_types or isinstance(b,type(self)):
                    return b

    def get_intrahelical_below(self, all_types=True):
        """ Returns bead directly below self """
        # assert( len(self.intrahelical_neighbors) <= 2 )
        for b in self.intrahelical_neighbors:
            if b.get_contour_position(self.parent, self.contour_position) < self.contour_position:
                if all_types or isinstance(b,type(self)):
                    return b

    def _neighbor_should_be_added(self,b):
        if type(self.parent) != type(b.parent):
            return True

        c1 = self.contour_position
        c2 = b.get_contour_position(self.parent,c1)
        if c2 < c1:
            b0 = self.get_intrahelical_below()
        else:
            b0 = self.get_intrahelical_above()

        if b0 is not None:            
            c0 = b0.get_contour_position(self.parent,c1)
            if np.abs(c2-c1) < np.abs(c0-c1):
                ## remove b0
                self.intrahelical_neighbors.remove(b0)
                b0.intrahelical_neighbors.remove(self)
                return True
            else:
                return False
        return True
        
    def make_intrahelical_neighbor(self,b):
        add1 = self._neighbor_should_be_added(b)
        add2 = b._neighbor_should_be_added(self)
        if add1 and add2:
            # assert(len(b.intrahelical_neighbors) <= 1)
            # assert(len(self.intrahelical_neighbors) <= 1)
            self.intrahelical_neighbors.append(b)
            b.intrahelical_neighbors.append(self)

    def conceptual_get_position(self, context):
        """ 
        context: object

Q: does this function do too much?
Danger of mixing return values

Q: does context describe the system or present an argument?
        """

        ## Validate Inputs
        ...

        ## Algorithm
        """
context specifies:
  - kind of output: real space, nt within segment, fraction of segment
  - absolute or relative
  - constraints: e.g. if passing through
        """
        """
given context, provide the position
        input
"""

    def get_nt_position(self, seg, near_address=None):
        """ Returns the "address" of the nucleotide relative to seg in
        nucleotides, taking the shortest (intrahelical) contour length route to seg
        """
        if seg == self.parent:
            pos = self.contour_position
        else:
            pos = self.get_contour_position(seg,near_address)
        return seg.contour_to_nt_pos(pos)

    def get_contour_position(self,seg, address = None):
        """ TODO: fix paradigm where a bead maps to exactly one location in a polymer
        - One way: modify get_contour_position to take an optional argument that indicates where in the polymer you are looking from
        """

        if seg == self.parent:
            return self.contour_position
        else:
            cutoff = 30*3
            target_seg = seg

            ## depth-first search
            ## TODO cache distances to nearby locations?
            def descend_search_tree(seg, contour_in_seg, distance=0, visited_segs=None):
                nonlocal cutoff
                if visited_segs is None: visited_segs = []

                if seg == target_seg:
                    # pdb.set_trace()
                    ## Found a segment in our target
                    sign = 1 if contour_in_seg == 1 else -1
                    if sign == -1: assert( contour_in_seg == 0 )
                    if distance < cutoff: # TODO: check if this does anything
                        cutoff = distance
                    return [[distance, contour_in_seg+sign*seg.nt_pos_to_contour(distance)]], [(seg, contour_in_seg, distance)]
                if distance > cutoff:
                    return None,None
                    
                ret_list = []
                hist_list = []
                ## Find intrahelical locations in seg that we might pass through
                conn_locs = seg.get_connections_and_locations("intrahelical")
                if isinstance(target_seg, SingleStrandedSegment):
                    tmp = seg.get_connections_and_locations("sscrossover")
                    conn_locs = conn_locs + list(filter(lambda x: x[2].container == target_seg, tmp))
                for c,A,B in conn_locs:
                    if B.container in visited_segs: continue
                    dx = seg.contour_to_nt_pos( A.address, round_nt=False ) - seg.contour_to_nt_pos( contour_in_seg, round_nt=False)
                    dx = np.abs(dx)
                    results,history = descend_search_tree( B.container, B.address,
                                                   distance+dx, visited_segs + [seg] )
                    if results is not None:
                        ret_list.extend( results )
                        hist_list.extend( history )
                return ret_list,hist_list

            results,history = descend_search_tree(self.parent, self.contour_position)
            if results is None or len(results) == 0:
                raise Exception("Could not find location in segment") # TODO better error
            if address is not None:
                return sorted(results,key=lambda x:(x[0],(x[1]-address)**2))[0][1]
            else:
                return sorted(results,key=lambda x:x[0])[0][1]
            # nt_pos = self.get_nt_position(seg)
            # return seg.nt_pos_to_contour(nt_pos)

    def combine(self, other):
        assert(other in self.intrahelical_neighbors)
        assert(self in other.intrahelical_neighbors)

        self.intrahelical_neighbors.remove(other)
        other.intrahelical_neighbors.remove(self)
        for b in other.intrahelical_neighbors:
            b.intrahelical_neighbors.remove(other)
            b.intrahelical_neighbors.append(self)
            self.intrahelical_neighbors.append(b)
        for l in other.locations:
            self.locations.append(l)
            l.particle = self
        
        ## Remove bead
        other.parent.children.remove(other)
        if other in other.parent.beads:
            other.parent.beads.remove(other)
        if 'orientation_bead' in other.__dict__:
            other.parent.children.remove(other.orientation_bead)

        for b in list(other.parent.bonds):
            if other in b[:2]: other.parent.bonds.remove(b)

    def update_position(self, contour_position):
        self.contour_position = contour_position
        self.position = self.parent.contour_to_position(contour_position)
        if 'orientation_bead' in self.__dict__:
            o = self.orientation_bead
            o.contour_position = contour_position
            orientation = self.parent.contour_to_orientation(contour_position)
            if orientation is None:
                print("WARNING: local_twist is True, but orientation is None; using identity")
                orientation = np.eye(3)
            o.position = self.position + orientation.dot( np.array((Segment.orientation_bond.r0,0,0)) )
            
    def __repr__(self):
        return "<SegmentParticle {} on {}[{:.2f}]>".format( self.name, self.parent, self.contour_position)


## TODO break this class into smaller, better encapsulated pieces
class Segment(ConnectableElement, Group):

    """ Base class that describes a segment of DNA. When built from
    cadnano models, should not span helices """

    """Define basic particle types"""
    dsDNA_particle = ParticleType("D",
                                  diffusivity = 43.5,
                                  mass = 300,
                                  radius = 3,                 
                              )
    orientation_particle = ParticleType("O",
                                        diffusivity = 100,
                                        mass = 300,
                                        radius = 1,
                                    )

    # orientation_bond = HarmonicBond(10,2)
    orientation_bond = HarmonicBond(30,1.5, rRange = (0,500) )

    ssDNA_particle = ParticleType("S",
                                  diffusivity = 43.5,
                                  mass = 150,
                                  radius = 3,                 
                              )

    def __init__(self, name, num_nt, 
                 start_position = None,
                 end_position = None, 
                 segment_model = None,
                 **kwargs):

        if start_position is None: start_position = np.array((0,0,0))

        Group.__init__(self, name, children=[], **kwargs)
        ConnectableElement.__init__(self, connection_locations=[], connections=[])

        if 'segname' not in kwargs:
            self.segname = name
        # self.resname = name
        self.start_orientation = None
        self.twist_per_nt = 0

        self.beads = [c for c in self.children] # self.beads will not contain orientation beads

        self._bead_model_generation = 0    # TODO: remove?
        self.segment_model = segment_model # TODO: remove?

        self.strand_pieces = dict()
        for d in ('fwd','rev'):
            self.strand_pieces[d] = []

        self.num_nt = int(num_nt)
        if end_position is None:
            end_position = np.array((0,0,self.distance_per_nt*num_nt)) + start_position
        self.start_position = start_position
        self.end_position = end_position

        ## Used to assign cadnano names to beads
        self._generate_bead_callbacks = []
        self._generate_nucleotide_callbacks = []

        ## Set up interpolation for positions
        self._set_splines_from_ends()

        self.sequence = None

    def __repr__(self):
        return "<{} {}[{:d}]>".format( str(type(self)).split('.')[-1], self.name, self.num_nt )

    def set_splines(self, contours, coords):
        tck, u = interpolate.splprep( coords.T, u=contours, s=0, k=1)
        self.position_spline_params = (tck,u)

    def set_orientation_splines(self, contours, quaternions):
        tck, u = interpolate.splprep( quaternions.T, u=contours, s=0, k=1)
        self.quaternion_spline_params = (tck,u)

    def get_center(self):
        tck, u = self.position_spline_params
        return np.mean(self.contour_to_position(u), axis=0)

    def get_bounding_box( self, num_points=3 ):
        positions = np.zeros( (num_points, 3) )
        i = 0
        for c in np.linspace(0,1,num_points):
            positions[i] = self.contour_to_position(c)
            i += 1
        min_ = np.array([np.min(positions[:,i]) for i in range(3)])
        max_ = np.array([np.max(positions[:,i]) for i in range(3)])
        return min_,max_

    def _get_location_positions(self):
        return [self.contour_to_nt_pos(l.address) for l in self.locations]

    def insert_dna(self, at_nt: int, num_nt: int, seq=tuple()):
        assert(np.isclose(np.around(num_nt),num_nt))
        if at_nt < 0:
            raise ValueError("Attempted to insert DNA into {} at a negative location".format(self))
        if at_nt > self.num_nt-1:
            raise ValueError("Attempted to insert DNA into {} at beyond the end of the Segment".format(self))
        if num_nt < 0:
            raise ValueError("Attempted to insert DNA a negative amount of DNA into {}".format(self))

        num_nt = np.around(num_nt)
        nt_positions = self._get_location_positions()
        new_nt_positions = [p if p <= at_nt else p+num_nt for p in nt_positions]

        ## TODO: handle sequence

        self.num_nt = self.num_nt+num_nt

        for l,p in zip(self.locations, new_nt_positions):
            l.address = self.nt_pos_to_contour(p)

    def remove_dna(self, first_nt:int, last_nt:int, remove_locations:bool = False):
        """ Removes nucleotides between first_nt and last_nt, inclusive """
        assert(np.isclose(np.around(first_nt),first_nt))
        assert(np.isclose(np.around(last_nt),last_nt))
        tmp = min((first_nt,last_nt))
        last_nt = max((first_nt,last_nt))
        fist_nt = tmp

        if first_nt < 0 or first_nt > self.num_nt-2:
            raise ValueError("Attempted to remove DNA from {} starting at an invalid location {}".format(self, first_nt))
        if last_nt < 1 or last_nt > self.num_nt-1:
            raise ValueError("Attempted to remove DNA from {} ending at an invalid location {}".format(self, last_nt))
        if first_nt == last_nt:
            return

        def _transform_contour_positions(contours):
            nt = self.contour_to_nt_pos(contours)
            first = first_nt if first_nt > 0 else -np.inf
            last = last_nt if last_nt < self.num_nt-1 else np.inf
            bad_ids = (nt >= first) * (nt <= last)
            nt[nt>last] = nt[nt>last]-removed_nt
            nt[bad_ids] = np.nan
            return self.nt_pos_to_contour(nt)* self.num_nt/num_nt

        first_nt = np.around(first_nt)
        last_nt = np.around(last_nt)

        removed_nt = last_nt-first_nt+1
        num_nt = self.num_nt-removed_nt

        c = np.array([l.address for l in self.locations])
        new_c = _transform_contour_positions(c)

        if np.any(np.isnan(new_c)) and not remove_locations:
            raise Exception("Attempted to remove DNA containing locations from {} between {} and {}".format(self,first_nt,last_nt))

        for l,v in zip(list(self.locations),new_c):
            if np.isnan(v):
                l.delete()
            else:
                l.address = v

        assert( len(self.locations) == np.logical_not(np.isnan(new_c)).sum() )
        tmp_nt = np.array([l.address*num_nt+0.5 for l in self.locations])
        assert(np.all( (tmp_nt < 1) + (tmp_nt > num_nt-1) + np.isclose((np.round(tmp_nt) - tmp_nt), 0) ))

        if self.sequence is not None and len(self.sequence) == self.num_nt:
            self.sequence = [s for s,i in zip(self.sequence,range(self.num_nt)) 
                                if i < first_nt or i > last_nt]
            assert( len(self.sequence) == num_nt )

        ## Rescale splines
        def _rescale_splines(u, get_coord_function, set_spline_function):
            new_u = _transform_contour_positions(u)
            ids = np.logical_not(np.isnan(new_u))
            new_u = new_u[ids]
            new_p = get_coord_function(u[ids])
            set_spline_function( new_u, new_p )

        _rescale_splines(self.position_spline_params[1],
                         self.contour_to_position,
                         self.set_splines)

        if self.quaternion_spline_params is not None:
            def _contour_to_quaternion(contours):
                os = [self.contour_to_orientation(c) for c in contours]
                qs = [quaternion_from_matrix( o ) for o in os]
                return np.array(qs)
            _rescale_splines(self.quaternion_spline_params[1],
                             self.contour_to_quaternion,
                             self.set_splines)

        self.num_nt = num_nt

    def delete(self):
        for c,loc,other in self.get_connections_and_locations():
            c.delete()
        self.parent.segments.remove(self)

    def __filter_contours(contours, positions, position_filter, contour_filter):
        u = contours
        r = positions

        ## Filter
        ids = list(range(len(u)))
        if contour_filter is not None:
            ids = list(filter(lambda i: contour_filter(u[i]), ids))
        if position_filter is not None:
            ids = list(filter(lambda i: position_filter(r[i,:]), ids))
        return ids

    def translate(self, translation_vector, position_filter=None, contour_filter=None):
        dr = np.array(translation_vector)
        tck, u = self.position_spline_params
        r = self.contour_to_position(u)

        ids = Segment.__filter_contours(u, r, position_filter, contour_filter)
        if len(ids) == 0: return

        ## Translate
        r[ids,:] = r[ids,:] + dr[np.newaxis,:]
        self.set_splines(u,r)

    def rotate(self, rotation_matrix, about=None, position_filter=None, contour_filter=None):
        tck, u = self.position_spline_params
        r = self.contour_to_position(u)

        ids = Segment.__filter_contours(u, r, position_filter, contour_filter)
        if len(ids) == 0: return

        if about is None:
            ## TODO: do this more efficiently
            r[ids,:] = np.array([rotation_matrix.dot(r[i,:]) for i in ids])
        else:
            dr = np.array(about)
            ## TODO: do this more efficiently
            r[ids,:] = np.array([rotation_matrix.dot(r[i,:]-dr) + dr for i in ids])

        self.set_splines(u,r)

        if self.quaternion_spline_params is not None:
            ## TODO: performance: don't shift between quaternion and matrix representations so much
            tck, u = self.quaternion_spline_params
            orientations = np.array([self.contour_to_orientation(v) for v in u])
            for i in ids:
                orientations[i,:] = rotation_matrix.dot(orientations[i])
            quats = np.array([quaternion_from_matrix(o) for o in orientations])
            self.set_orientation_splines(u, quats)

    def _set_splines_from_ends(self, resolution=4):
        self.quaternion_spline_params = None
        r0 = np.array(self.start_position)[np.newaxis,:]
        r1 = np.array(self.end_position)[np.newaxis,:]
        u = np.linspace(0,1, max(3,self.num_nt//int(resolution)))
        s = u[:,np.newaxis]
        coords = (1-s)*r0 + s*r1
        self.set_splines(u, coords)

    def clear_all(self):
        Group.clear_all(self)  # TODO: use super?
        self.beads = []
        # for c,loc,other in self.get_connections_and_locations():
        #     loc.particle = None
        #     other.particle = None
        for l in self.locations:
            l.particle = None

    def contour_to_nt_pos(self, contour_pos, round_nt=False):
        nt = contour_pos*(self.num_nt) - 0.5
        if round_nt:
            assert( np.isclose(np.around(nt),nt) )
            nt = np.around(nt)
        return nt

    def nt_pos_to_contour(self,nt_pos):
        return (nt_pos+0.5)/(self.num_nt)

    def contour_to_position(self,s):
        p = interpolate.splev( s, self.position_spline_params[0] )
        if len(p) > 1: p = np.array(p).T
        return p

    def contour_to_tangent(self,s):
        t = interpolate.splev( s, self.position_spline_params[0], der=1 )
        t = (t / np.linalg.norm(t,axis=0))
        return t.T
        

    def contour_to_orientation(self,s):
        assert( isinstance(s,float) or isinstance(s,int) or len(s) == 1 )   # TODO make vectorized version

        if self.quaternion_spline_params is None:
            axis = self.contour_to_tangent(s)
            axis = axis / np.linalg.norm(axis)
            rotAxis = np.cross(axis,np.array((0,0,1)))
            rotAxisL = np.linalg.norm(rotAxis)
            zAxis = np.array((0,0,1))

            if rotAxisL > 0.001:
                theta = np.arcsin(rotAxisL) * 180/np.pi
                if axis.dot(zAxis) < 0: theta = 180-theta
                orientation0 = rotationAboutAxis( rotAxis/rotAxisL, theta, normalizeAxis=False ).T
            else:
                orientation0 = np.eye(3) if axis.dot(zAxis) > 0 else \
                               rotationAboutAxis( np.array((1,0,0)), 180, normalizeAxis=False )
            if self.start_orientation is not None:
                orientation0 = orientation0.dot(self.start_orientation)

            orientation = rotationAboutAxis( axis, self.twist_per_nt*self.contour_to_nt_pos(s), normalizeAxis=False )
            orientation = orientation.dot(orientation0)
        else:
            q = interpolate.splev( s, self.quaternion_spline_params[0] )
            if len(q) > 1: q = np.array(q).T # TODO: is this needed?
            orientation = quaternion_to_matrix(q)

        return orientation

    def _ntpos_to_seg_and_ntpos(self, nt_pos, is_fwd=True, visited_segs=tuple()):
        """ Cross intrahelical to obtain a tuple of the segment nucleotide position """
        """ TODO: This function could perhaps replace parts of SegmentParticle.get_contour_position """

        if nt_pos >= 0 and nt_pos < self.num_nt:
            return (self,nt_pos,is_fwd)
        else:
            try:
                c,A,B = self.get_contour_sorted_connections_and_locations(type_='intrahelical')[0 if nt_pos < 0 else -1]
            except:
                return None

            ## Special logic for circular segments
            assert(A.container == self)
            if A.container == B.container:
                if (nt_pos < 0 and A.address > B.address) or (nt_pos >= self.num_nt and A.address < B.address):
                    A,B = (B,A)

            other_seg = B.container
            if A.address == (0 if nt_pos < 0 else 1) and other_seg not in visited_segs:
                ## Cross the crossover
                other_pos = (nt_pos-self.num_nt) if nt_pos >= self.num_nt else -nt_pos-1
                if B.address > 0.5:
                    other_pos = (other_seg.num_nt-1) - other_pos
                other_fwd = not is_fwd if A.address == B.address else is_fwd
                return other_seg._ntpos_to_seg_and_ntpos(other_pos, other_fwd,
                                                         list(visited_segs)+[self])

            else:
                ## Could not find a path to nt_pos
                return None
        assert(False)


    def get_contour_sorted_connections_and_locations(self,type_):
        sort_fn = lambda c: c[1].address
        cl = self.get_connections_and_locations(type_)
        return sorted(cl, key=sort_fn)
    
    def randomize_unset_sequence(self):
        bases = list(seqComplement.keys())
        # bases = ['T']        ## FOR DEBUG
        if self.sequence is None:
            self.sequence = [random.choice(bases) for i in range(self.num_nt)]
        else:
            assert(len(self.sequence) == self.num_nt) # TODO move
            for i in range(len(self.sequence)):
                if self.sequence[i] is None:
                    self.sequence[i] = random.choice(bases)

    def _get_num_beads(self, max_basepairs_per_bead, max_nucleotides_per_bead ):
        raise NotImplementedError

    def _generate_one_bead(self, contour_position, nts):
        raise NotImplementedError

    def _generate_atomic_nucleotide(self, contour_position, is_fwd, seq, scale, strand_segment):
        """ Seq should include modifications like 5T, T3 Tsinglet; direction matters too """

        # print("Generating nucleotide at {}".format(contour_position))
        
        pos = self.contour_to_position(contour_position)
        orientation = self.contour_to_orientation(contour_position)

        """ deleteme
        ## TODO: move this code (?)
        if orientation is None:
            import pdb
            pdb.set_trace()
            axis = self.contour_to_tangent(contour_position)
            angleVec = np.array([1,0,0])
            if axis.dot(angleVec) > 0.9: angleVec = np.array([0,1,0])
            angleVec = angleVec - angleVec.dot(axis)*axis
            angleVec = angleVec/np.linalg.norm(angleVec)
            y = np.cross(axis,angleVec)
            orientation = np.array([angleVec,y,axis]).T
            ## TODO: improve placement of ssDNA
            # rot = rotationAboutAxis( axis, contour_position*self.twist_per_nt*self.num_nt, normalizeAxis=True )
            # orientation = rot.dot(orientation)
        else:
            orientation = orientation                            
        """
        key = seq
        nt_dict = canonicalNtFwd if is_fwd else canonicalNtRev

        atoms = nt_dict[ key ].generate() # TODO: clone?
        atoms.orientation = orientation.dot(atoms.orientation)
        if isinstance(self, SingleStrandedSegment):
            if scale is not None and scale != 1:
                for a in atoms:
                    a.position = scale*a.position
            atoms.position = pos - atoms.atoms_by_name["C1'"].collapsedPosition()
        else:
            if scale is not None and scale != 1:
                if atoms.sequence in ("A","G"):
                    r0 = atoms.atoms_by_name["N9"].position
                else:
                    r0 = atoms.atoms_by_name["N1"].position
                for a in atoms:
                    if a.name[-1] in ("'","P","T"):
                        a.position = scale*(a.position-r0) + r0
                    else:
                        a.fixed = 1
            atoms.position = pos
        
        atoms.contour_position = contour_position
        strand_segment.add(atoms)

        for callback in self._generate_nucleotide_callbacks:
            callback(atoms)

        return atoms

    def _generate_oxdna_nucleotide(self, contour_position, is_fwd, seq):
        bp_center = self.contour_to_position(contour_position)
        orientation = self.contour_to_orientation(contour_position)

        DefaultOrientation = rotationAboutAxis([0,0,1], 90)
        if is_fwd: 
            DefaultOrientation = rotationAboutAxis([1,0,0], 180).dot(DefaultOrientation)

        o = orientation.dot(DefaultOrientation)

        if isinstance(self, SingleStrandedSegment):
            pos = bp_center
        else:
            pos = bp_center - 5*o.dot(np.array((1,0,0)))

        nt = PointParticle("oxdna_nt", position= pos,
                             orientation = o)

        nt.contour_position = contour_position
        return nt


    def add_location(self, nt, type_, on_fwd_strand=True):
        ## Create location if needed, add to segment
        c = self.nt_pos_to_contour(nt)
        assert(c >= 0 and c <= 1)
        # TODO? loc = self.Location( address=c, type_=type_, on_fwd_strand=is_fwd )
        loc = Location( self, address=c, type_=type_, on_fwd_strand=on_fwd_strand )
        self.locations.append(loc)

    ## TODO? Replace with abstract strand-based model?

    def add_nick(self, nt, on_fwd_strand=True):
        if on_fwd_strand:
            self.add_3prime(nt,on_fwd_strand)
            self.add_5prime(nt+1,on_fwd_strand)
        else:
            self.add_5prime(nt,on_fwd_strand)
            self.add_3prime(nt+1,on_fwd_strand)


    def add_5prime(self, nt, on_fwd_strand=True):
        if isinstance(self,SingleStrandedSegment):
            on_fwd_strand = True
        self.add_location(nt,"5prime",on_fwd_strand)

    def add_3prime(self, nt, on_fwd_strand=True):
        if isinstance(self,SingleStrandedSegment):
            on_fwd_strand = True
        self.add_location(nt,"3prime",on_fwd_strand)

    ## Real work
    def _connect_ends(self, end1, end2, type_, force_connection=False):
        debug = False
        ## TODO remove self?
        ## validate the input
        for end in (end1, end2):
            assert( isinstance(end, Location) )
            assert( end.type_ in ("end3","end5") )
        assert( end1.type_ != end2.type_ )

        ## Remove other connections involving these points
        if end1.connection is not None:
            if debug: print("WARNING: reconnecting {}".format(end1))
            end1.connection.delete()
        if end2.connection is not None:
            if debug: print("WARNING: reconnecting {}".format(end2))
            end2.connection.delete()

        ## Create and add connection
        if end2.type_ == "end5":
            end1.container._connect( end2.container, Connection( end1, end2, type_=type_ ), in_3prime_direction=True )
        else:
            end2.container._connect( end1.container, Connection( end2, end1, type_=type_ ), in_3prime_direction=True )

    def get_3prime_locations(self):
        return sorted(self.get_locations("3prime"),key=lambda x: x.address)
    
    def get_5prime_locations(self):
        ## TODO? ensure that data is consistent before _build_model calls
        return sorted(self.get_locations("5prime"),key=lambda x: x.address)

    def get_blunt_DNA_ends(self):
        if isinstance(self, SingleStrandedSegment): return []
        ret = []
        cl = self.get_connections_and_locations("intrahelical")
        if not any([c[1].address == 0 for c in cl]):
            ret.append((self.start5,self.start3,-1))
        if not any([c[1].address == 1 for c in cl]):
            ret.append((self.end5,self.end3,1))
        # return [c for c in cl if c[1].address == 0 or c[1].address == 1]
        return ret

    def iterate_connections_and_locations(self, reverse=False):
        ## connections to other segments
        cl = self.get_contour_sorted_connections_and_locations()
        if reverse:
            cl = cl[::-1]
            
        for c in cl:
            yield c

    ## TODO rename
    def _add_strand_piece(self, strand_piece):
        """ Registers a strand segment within this object """

        ## TODO use weakref
        d = 'fwd' if strand_piece.is_fwd else 'rev'

        ## Validate strand_piece (ensure no clashes)
        for s in self.strand_pieces[d]:
            l,h = sorted((s.start,s.end))
            for value in (strand_piece.start,strand_piece.end):
                if value >= l and value <= h:
                    raise Exception("Strand piece already exists! DNA may be circular.")

        ## Add strand_piece in correct order
        self.strand_pieces[d].append(strand_piece)
        self.strand_pieces[d] = sorted(self.strand_pieces[d],
                                       key = lambda x: x.start)

    ## TODO rename
    def get_strand_segment(self, nt_pos, is_fwd, move_at_least=0.5):
        """ Walks through locations, checking for crossovers """
        # if self.name in ("6-1","1-1"):
        #     import pdb
        #     pdb.set_trace()
        move_at_least = 0

        ## Iterate through locations
        # locations = sorted(self.locations, key=lambda l:(l.address,not l.on_fwd_strand), reverse=(not is_fwd))
        def loc_rank(l):
            nt = l.get_nt_pos()
            ## optionally add logic about type of connection
            return (nt, not l.on_fwd_strand)
        # locations = sorted(self.locations, key=lambda l:(l.address,not l.on_fwd_strand), reverse=(not is_fwd))
        locations = sorted(self.locations, key=loc_rank, reverse=(not is_fwd))
        # print(locations)

        for l in locations:
            # TODOTODO probably okay
            if l.address == 0:
                pos = 0.0
            elif l.address == 1:
                pos = self.num_nt-1
            else:
                pos = self.contour_to_nt_pos(l.address, round_nt=True)

            ## DEBUG


            ## Skip locations encountered before our strand
            # tol = 0.1
            # if is_fwd:
            #     if pos-nt_pos <= tol: continue 
            # elif   nt_pos-pos <= tol: continue
            if (pos-nt_pos)*(2*is_fwd-1) < move_at_least: continue
            ## TODO: remove move_at_least
            if np.isclose(pos,nt_pos):
                if l.is_3prime_side_of_connection: continue

            ## Stop if we found the 3prime end
            if l.on_fwd_strand == is_fwd and l.type_ == "3prime" and l.connection is None:
                if _DEBUG_TRACE:
                    print("  found end at",l)
                return pos, None, None, None, None

            ## Check location connections
            c = l.connection
            if c is None: continue
            B = c.other(l)            

            ## Found a location on the same strand?
            if l.on_fwd_strand == is_fwd:
                if _DEBUG_TRACE:
                    print("  passing through",l)
                    print("from {}, connection {} to {}".format(nt_pos,l,B))
                Bpos = B.get_nt_pos()
                return pos, B.container, Bpos, B.on_fwd_strand, 0.5
                
            ## Stop at other strand crossovers so basepairs line up
            elif c.type_ == "crossover":
                if nt_pos == pos: continue
                if _DEBUG_TRACE:
                    print("  pausing at",l)
                return pos, l.container, pos+(2*is_fwd-1), is_fwd, 0

        raise Exception("Shouldn't be here")
        # print("Shouldn't be here")
        ## Made it to the end of the segment without finding a connection
        return 1*is_fwd, None, None, None