OAT utilities documentation

Data structures

`oxDNA_analysis_tools.UTILS.data_structures.Chunk`	Dataclass to hold information about a chunk of a trajectory
`oxDNA_analysis_tools.UTILS.data_structures.ConfInfo`	Dataclass to hold metadata about a single configuration
`oxDNA_analysis_tools.UTILS.data_structures.TrajInfo`	Dataclass to hold metadata about a trajectory file
`oxDNA_analysis_tools.UTILS.data_structures.Configuration`	Dataclass/numpy representation for oxDNA configurations
`oxDNA_analysis_tools.UTILS.data_structures.TopInfo`	Dataclass to hold metadata about a topology file
`oxDNA_analysis_tools.UTILS.data_structures.System`	Object hierarchy representation of an oxDNA configuration
`oxDNA_analysis_tools.UTILS.data_structures.Strand`	Object hierarchy representation of an oxDNA strand.
`oxDNA_analysis_tools.UTILS.data_structures.Monomer`	A Dataclass containing information about oxDNA monomers.

class oxDNA_analysis_tools.UTILS.data_structures.Chunk(block: str, offset: int, is_last: bool, file_size: int)

Bases: object

Dataclass to hold information about a chunk of a trajectory

Parameters:

block (str) – The file contents of the chunk
offset (int) – The start byte of the chunk
is_last (bool) – Whether this is the last chunk of the trajectory
file_size (int) – The total size of the file

block: str

file_size: int

is_last: bool

offset: int

class oxDNA_analysis_tools.UTILS.data_structures.ConfInfo(offset: int, size: int, id: int)

Bases: object

Dataclass to hold metadata about a single configuration

Parameters:

offset (int) – The start byte of the configuration
size (int) – The size of the configuration in bytes
idx (int) – The index of the configuration in the trajectory

id: int

offset: int

size: int

class oxDNA_analysis_tools.UTILS.data_structures.TrajInfo(path: str, nconfs: int, idxs: List[ConfInfo], incl_v: bool)

Bases: object

Dataclass to hold metadata about a trajectory file

Parameters:

path (str) – The path to the trajectory file
nconfs (int) – The number of configurations in the trajectory
idxs (List[ConfInfo]) – A list of ConfInfo objects locating configurations in the trajectory
incl_v (bool) – Are the velocities included in the trajectory?

idxs: List[ConfInfo]

incl_v: bool

nconfs: int

path: str

class oxDNA_analysis_tools.UTILS.data_structures.Configuration(time: int, box: ndarray, energy: ndarray, positions: ndarray, a1s: ndarray, a3s: ndarray)

Bases: object

Dataclass/numpy representation for oxDNA configurations

Parameters:

time (int) – The time step of the configuration
box (numpy.ndarray) – The box size for the simulation
energy (numpy.ndarray) – The potential, kinetic and total energy for the configuration
positions (numpy.ndarray) – The positions of the nucleotides
a1s (numpy.ndarray) – the orientations of the base pairing sites
a3s (numpy.ndarray) – the orientations of the stacking sites

a1s: ndarray

a3s: ndarray

box: ndarray

energy: ndarray

positions: ndarray

time: int

class oxDNA_analysis_tools.UTILS.data_structures.TopInfo(path: str, nbases: int)

Bases: object

Dataclass to hold metadata about a topology file

Parameters:

path (str) – The path to the topology file
nbases (int) – The number of nucleotides in the topology

nbases: int

path: str

class oxDNA_analysis_tools.UTILS.data_structures.System(top_file: str = '', strands: List[Strand] = [])

Bases: object

Object hierarchy representation of an oxDNA configuration

Can be accessed and modified using Python list syntax (implements __getitem__, __setitem__, and __iter__) for accessing Strand objects.

Parameters:

top_file (str) – The path to the topology file creating the system
strands (List[Strand]) – A list of Strand objects

append(strand: Strand)

Append a strand to the system.

Modifies this system in-place.

Parameters:: strand (Strand) – The strand to append

strands: List[Strand]

top_file: str

class oxDNA_analysis_tools.UTILS.data_structures.Strand(id, *initial_data, **kwargs)

Bases: object

Object hierarchy representation of an oxDNA strand.

Can be accessed and modified using Python list syntax (implements __getitem__, __setitem__, and __iter__) for accessing Monomer objects.

Parameters:

id (int) – The id of the strand
*initial_data (list[dict]) – Set additional attributes of the strand object (currently unused)
**kwargs (dict) – Set addtional attributes of the strand object from key:value pairs.

_from_old

Was this created from an old-style topology file? (default : False)

Type:: bool

id

ID of this strand in the topology file

Type:: int

monomers

List of consitutent monomer objects (default : [])

Type:: list[Monomer]

type

Type of molecule this represents (default : DNA)

Type:: str

circular

Is this a circular strand? (default : False)

Type:: bool

append(monomer: Monomer)

Append a monomer to the strand.

Modifies this strand in-place.

Parameters:: monomer (Monomer) – The monomer to append

circular: bool

get_kwdata() → Dict[str, str]

Returns all attributes of this object which do not begin with ‘__’

Used for writing out new-style topology files.

get_length() → int: Returns the number of monomers in the Strand.

get_sequence() → str: Returns the sequence of the Strand as a string.

id: int

is_circular() → bool: Returns the circular attribute.

is_old(): Returns whether this Strand came from an old-style topology file.

monomers: List[Monomer]

set_old(from_old): Sets the _from_old attribute read by is_old.

set_sequence(new_seq: str) → None: Modify the sequence of the Strand. Note that the new sequence must be the same length as the old sequence.

type: str

Bases: object

A Dataclass containing information about oxDNA monomers.

a1: ndarray | None = None

a3: ndarray | None = None

btype: str

id: int

n3: int | None = None

n5: int | None = None

pair: int | None = None

pos: ndarray | None = None

strand: Strand | None = None

Geometry utilities

`oxDNA_analysis_tools.UTILS.geom.fit_plane`
`oxDNA_analysis_tools.UTILS.geom.get_RNA_axis`	Returns the axis of a RNA duplex
`oxDNA_analysis_tools.UTILS.geom.get_DNA_axis`	Returns the axis of a DNA duplex

oxDNA_analysis_tools.UTILS.geom.fit_plane(points)

oxDNA_analysis_tools.UTILS.geom.get_RNA_axis(particles, d)

Returns the axis of a RNA duplex

Parameters:

particles (oxpy.config_info) – The positions/orientations of the particles
d (duplex_list) – A duplex_list object with members “start1”, “end1”, “end2”, “start2” containing integer values of the corresponding particle IDs.

oxDNA_analysis_tools.UTILS.geom.get_DNA_axis(particles, d)

Returns the axis of a DNA duplex

Parameters:

particles (oxpy.config_info) – The positions/orientations of the particles
d (duplex_list) – A duplex_list object with members “start1”, “end1”, “end2”, “start2” containing integer values of the corresponding particle IDs.

iPython oxView plugin

`oxDNA_analysis_tools.UTILS.oxview.display_files`	Generate an iframe displaying the provided files in oxview
`oxDNA_analysis_tools.UTILS.oxview.from_path`	Display oxview frame based on the string path provided
`oxDNA_analysis_tools.UTILS.oxview.oxdna_conf`	Display an oxDNA configuration in oxview
`oxDNA_analysis_tools.UTILS.oxview.loro_patchy_conf`	Display a loro patchy configuration in oxview
`oxDNA_analysis_tools.UTILS.oxview.flro_patchy_conf`	Display a flro patchy configuration in oxview

oxDNA_analysis_tools.UTILS.oxview.display_files(system_list, inbox_settings=['Monomer', 'Origin'], oxview_src='https://sulcgroup.github.io/oxdna-viewer/')

Generate an iframe displaying the provided files in oxview

Parameters:

system_list (tuple) – a list of lists of tuples (file_string, extension)
inbox_settings (list[str]) – a list of strings, the inbox settings to use
oxview_src (str) – the url of the oxview source

Returns:

The iframe-id for reuse

oxDNA_analysis_tools.UTILS.oxview.from_path(*args: List[str] | List[List[str]], **kwargs)

Display oxview frame based on the string path provided

Parameters:

args (Union[List[str],List[List[str]]]) – contains the paths to the files or a list of lists of paths
kwargs (dict) – the properties to oxview defaults to = {“inbox_settings”:[“Monomer”, “Origin”], “oxview_src” : “https://sulcgroup.github.io/oxdna-viewer/”}

Usage:: from_path(“conf.top”, “conf.dat”,**{“inbox_settings”:[“Monomer”, “Origin”]})

oxDNA_analysis_tools.UTILS.oxview.oxdna_conf(top: TopInfo, conf: Configuration, overlay=None, forces_path=None, par_file_path=None, script_file_path=None, inbox_settings=['Monomer', 'Origin'], oxview_src='https://sulcgroup.github.io/oxdna-viewer/')

Display an oxDNA configuration in oxview

Parameters:

top (TopInfo) – the top file data
conf (Configuration) – the configuration data
overlay (str) – (optional) the path to the overlay file
forces_path (str) – (optional) the path to the forces file
par_file_path (str) – (optional) the path to the par file
script_file_path (str) – (optional) the path to the script file (js)
inbox_settings (list[str]) – (optional) a list of strings, the inbox settings to use
oxview_src (str) – (optional) the url of the oxview source

oxDNA_analysis_tools.UTILS.oxview.loro_patchy_conf(top_path: str, conf: Configuration, matrix_path: str, inbox_settings=['Monomer', 'Origin'], oxview_src='https://sulcgroup.github.io/oxdna-viewer/')

Display a loro patchy configuration in oxview

Parameters:

top (str) – the top file path
conf (Configuration) – the configuration data
matrix_path (str) – the path to the matrix file
inbox_settings (list[str]) – (optional) a list of strings, the inbox settings to use
oxview_src (str) – (optional) the url of the oxview source

oxDNA_analysis_tools.UTILS.oxview.flro_patchy_conf(top_path: str, conf: Configuration, particles_path: str, inbox_settings=['Monomer', 'Origin'], oxview_src='https://sulcgroup.github.io/oxdna-viewer/')

Display a flro patchy configuration in oxview

Parameters:

top (str) – the top file path
conf (Configuration) – the configuration data
patricles (str) – the path to the particles file
inbox_settings (list[str]) – (optional) a list of strings, the inbox settings to use
oxview_src (str) – (optional) the url of the oxview source

Multiprocesser

oxDNA_analysis_tools.UTILS.oat_multiprocesser.oat_multiprocesser

Runs a function on a trajectory by distributing chunks of the trajectory to each processor.

oxDNA_analysis_tools.UTILS.oat_multiprocesser.oat_multiprocesser(nconfs: int, ncpus: int, function: Callable, callback: Callable, ctx: NamedTuple)

Runs a function on a trajectory by distributing chunks of the trajectory to each processor. Accumulates the results with a callback function.

Parameters:

nconfs (int) – The total number of configurations to process
ncpus (int) – The number of processors to use
function (function) – The function to run on each chunk
callback (function) – The function to call after each chunk is processed
ctx (NamedTuple) – A NamedTuple containing the arguments for the function

The callback function must use the nonlocal keyword to update a variable in the main thread.

Rye reader

`oxDNA_analysis_tools.UTILS.RyeReader.Chunker`	Generator that yields chunks of a fixed number of bytes
`oxDNA_analysis_tools.UTILS.RyeReader.linear_read`	Read a trajecory without multiprocessing.
`oxDNA_analysis_tools.UTILS.RyeReader.get_confs`	Read a chunk of configurations from a trajectory file.
`oxDNA_analysis_tools.UTILS.RyeReader.get_top_info`	Get data from topology file header
`oxDNA_analysis_tools.UTILS.RyeReader.get_top_info_from_traj`	Retrieve top and traj info without providing a topology.
`oxDNA_analysis_tools.UTILS.RyeReader.get_traj_info`	Get the information of a trajectory file
`oxDNA_analysis_tools.UTILS.RyeReader.describe`	retrieve top and traj info for a provided pair
`oxDNA_analysis_tools.UTILS.RyeReader.strand_describe`	Retrieve all information from a topology file and return a System object which maps nucleotides to strands.
`oxDNA_analysis_tools.UTILS.RyeReader.get_input_parameter`	Gets the value of a parameter in an oxDNA input file
`oxDNA_analysis_tools.UTILS.RyeReader.inbox`	Modify the positions attribute such that all positions are inside the box.
`oxDNA_analysis_tools.UTILS.RyeReader.write_conf`	write the conf to a file
`oxDNA_analysis_tools.UTILS.RyeReader.conf_to_str`	Write configuration as a string
`oxDNA_analysis_tools.UTILS.RyeReader.get_top_string`	Write topology file from system object.

oxDNA_analysis_tools.UTILS.RyeReader.Chunker(file, fsize, size=1000000) → Iterator[Chunk]

Generator that yields chunks of a fixed number of bytes

Parameters:

file (file) – The file to read
fsize (int) – The size of the file
size (int) – The size of the chunks

Returns:

An iterator object which yields chunks.

Return type:

(Iterator[Chunk])

oxDNA_analysis_tools.UTILS.RyeReader.linear_read(traj_info: TrajInfo, top_info: TopInfo, chunk_size: int = -1) → Iterator[List[Configuration]]

Read a trajecory without multiprocessing.

Produces an iterator that yields a list of <chunk_size> configurations.

Parameters:

traj_info (TrajInfo) – The trajectory info
top_info (TopInfo) – The topology info
chunk_size (int) – The number of confs to read at a time. Defaults to config.get_chunk_size()

Returns:

An iterator object which yields lists of <chunk_size> configurations.

Return type:

iterator[Configuration]

oxDNA_analysis_tools.UTILS.RyeReader.get_confs(top_info: TopInfo, traj_info: TrajInfo, start_conf: int, n_confs: int) → List[Configuration]

Read a chunk of configurations from a trajectory file.

Parameters:

top_info (TopInfo) – Contains the number of bases in the configuration
traj_info (TrajInfo) – Contains metadata about the trajectory file
start_conf (int) – The index of the first conf to read
n_confs (int) – The number of confs to read

Returns:

A list of n_confs configurations starting from <start_conf>

Return type:

List[Configuration]

oxDNA_analysis_tools.UTILS.RyeReader.get_top_info(top: str) → TopInfo

Get data from topology file header

Parameters:: top (str) – path to the topology file
Returns:: A TopInfo object which contains the path to the file and the number of bases.
Return type:: TopInfo

oxDNA_analysis_tools.UTILS.RyeReader.get_top_info_from_traj(traj: str) → TopInfo

Retrieve top and traj info without providing a topology.

Note its not implemented, but if it were, this would not return the number of strands.

Parameters:: traj (str) – path to the trajectory file
Returns:: topology info
Return type:: TopInfo

oxDNA_analysis_tools.UTILS.RyeReader.get_traj_info(traj: str) → TrajInfo

Get the information of a trajectory file

Parameters:: traj (str) – path to the trajectory file
Returns:: trajectory info object
Return type:: TrajInfo

oxDNA_analysis_tools.UTILS.RyeReader.describe(top: str | None, traj: str) → Tuple[TopInfo, TrajInfo]

retrieve top and traj info for a provided pair

You can provide None as the topology and it will read the first conf of the traj to get the number of particles. The TopInfo will be missing the path parameter if no topology is provided.

Parameters:

top (str or None) – path to the topology file
traj (str) – path to the trajectory file

Returns:

topology and trajectory info

Return type:

(TopInfo, TrajInfo)

oxDNA_analysis_tools.UTILS.RyeReader.strand_describe(top: str) → Tuple[System, list]

Retrieve all information from a topology file and return a System object which maps nucleotides to strands.

This is returned as two objects so that monomers can be indexed either via strand or via global index. This function will automatically detect whether the input topology file is new or old format.

Parameters:: top (str) – path to topology file
Returns:: The System object and the list of Monomer objects.
Return type:: (System, List[Monomer])

oxDNA_analysis_tools.UTILS.RyeReader.get_input_parameter(input_file, parameter) → str

Gets the value of a parameter in an oxDNA input file

Parameters:

input_file (str) – The path to the input file
parameter (str) – The parameter you want to get the value of

Returns:

The value of the parameter

Return type:

(str)

oxDNA_analysis_tools.UTILS.RyeReader.inbox(conf: Configuration, center: bool = True, centerpoint: str | ndarray = 'bc') → Configuration

Modify the positions attribute such that all positions are inside the box.

For cohesive structures, you almost always want center=True. For diffuse simulations, you probably want center=False.

Parameters:

conf (Configuration) – The configuration to inbox
center (bool) – If True, center the configuration in the box (default True)
centerpoint (str|np.ndarray) – If ‘bc’, center in the box, if array, center on the array (default ‘bc’)

Returns:

The inboxed configuration

Return type:

(Configuration)

oxDNA_analysis_tools.UTILS.RyeReader.write_conf(path: str, conf: Configuration, append: bool = False, include_vel: bool = True) → None

write the conf to a file

Parameters:

path (str) – path to the file
conf (Configuration) – the configuration to write
append (bool) – if True, append to the file, if False, overwrite
include_vel (bool) – Include velocities in the output trajectory? Defaults to True.

oxDNA_analysis_tools.UTILS.RyeReader.conf_to_str(conf: Configuration, include_vel: bool = True) → str

Write configuration as a string

Parameters:

conf (Configuration) – The configuration to write
include_vel (bool) – Include velocities in the output string? Defaults to True.

Returns:

The configuration as a string

Return type:

(str)

oxDNA_analysis_tools.UTILS.RyeReader.get_top_string(system: System, old_format: bool = False) → str

Write topology file from system object.

Parameters:

system (System) – System object
old_format (bool) – Use the old 3’-5’ format? (default: False)

Returns:

string representation of the system in .top format

Return type:

(str)