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 = [])

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

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

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.

is_circular() → bool

Returns the circular attribute.

is_old()

Returns whether this Strand came from an old-style topology file.

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.

class oxDNA_analysis_tools.UTILS.data_structures.Monomer(id: int, btype: str, strand: Strand | None, n3: int | None, n5: int | None, pair: int | None)

Bases: object

A Dataclass containing information about oxDNA monomers.

btype: str

id: int

n3: int | None

n5: int | None

pair: int | None

strand: Strand | 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

• start1 (int) – Particle ID of the first particle in the first strand

• end1 (int) – Particle ID of the last particle in the first strand

• end2 (int) – Particle ID of the particle complimentary to start1

• start2 (int) – Particle ID of the particle complimentary to end1

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

• start1 (int) – Particle ID of the first particle in the first strand

• end1 (int) – Particle ID of the last particle in the first strand

• end2 (int) – Particle ID of the particle complimentary to start1

• start2 (int) – Particle ID of the particle complimentary to end1

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(files_with_ext, inbox_settings=['Monomer', 'Origin'], oxview_src='https://sulcgroup.github.io/oxdna-viewer/')

Generate an iframe displaying the provided files in oxview

Parameters:

• files_with_ext (tuple) – a list 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], **kwargs)

Display oxview frame based on the string path provided

Parameters:

• args (List[str]) – contains the paths to the files

• kwargs (dict) – the properties to oxview defaults to = {“inbox_settings”:[“Monomer”, “Origin”], “oxview_src” : “https://sulcgroup.github.io/oxdna-viewer/”}

Usage:

raw(“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 and trajectory info

Return type:

(TopInfo, TrajInfo)

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=False) → Configuration

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

Parameters:

• conf (Configuration) – The configuration to inbox

• center (bool) – If True, center the configuration on the box

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)