The core module

This module contains the Python bindings of the C++ code. Every object described here is contained in the same module and can be accessed as oxpy.core.object or as oxpy.object.

`Context`	A context manager that performs some initialisation and clean up.
`OxpyManager`	The object in charge of initialising and running a simulation.
`BaseParticle`	A simulation particle.
`DNANucleotide`	A DNA nucleotide.
`RNANucleotide`	A RNA nucleotide.
`Molecule`	A set of particles connected by bonds.
`BaseInteraction`	The class that takes care of computing the interaction between the particles.
`ConfigInfo`	This singleton object stores all the details of the simulation (particles, neighbour lists, input file, interaction, external forces)
`FlattenedConfigInfo`	An object storing particle types, positions, a1 and a3 orientation vectors in flat arrays that can be used as or converted to numpy arrays.
`FlattenedVectorArray`	This is a view of a Nx3 matrix (where N is the number of particles in the simulation).
`BaseBox`	The interface class for forces.
`InputFile`	Handles the options provided by the user to control and tune the behaviour of the simulation/analysis/generation of the initial configuration.

class oxpy.core.Context(self: oxpy.core.Context, print_coda: bool = True)

Bases: pybind11_object

A context manager that performs some initialisation and clean up.

Use it with a with command before using any of the oxpy functionalities:

with oxpy.Context():
    # your code using oxpy goes here

The default constructor takes an optional parameter that controls whether the final message gets printed or not.

Parameters:: print_coda (bool) – If True (default value) a message asking to cite the oxDNA JOSS paper will be printed at the end of the simulation.

class oxpy.core.OxpyManager(*args, **kwargs)

Bases: SimManager

The object in charge of initialising and running a simulation.

Overloaded function.

__init__(self: oxpy.core.OxpyManager, input_filename: str) -> None

The default constructor takes the input filename as its only parameter.

Parameters:: input_filename (str) – The name of the input file that will be used to run the simulation

__init__(self: oxpy.core.OxpyManager, input: oxpy.core.InputFile) -> None

This constructor takes an InputFile as its only argument.

Parameters:: input (InputFile) – The object storing the simulations’ options.

add_output(self: oxpy.core.OxpyManager, filename: str, print_every: int, observables: List[oxpy.core.observables.BaseObservable]) → None

Add an output file to the simulation, to be populated with the given observables. Added outputs can be subsequently removed with remove_output().

Parameters:

filename (str) – The name of the file where the output will be printed.
print_every (int) – The frequency (in simulation time steps) with which the output should be computed and printed.
observables (List(BaseObservable)) – A list of observables that will be used to populate the output.

config_info(self: oxpy.core.OxpyManager) → oxpy.core.ConfigInfo

Return the simulation’s ConfigInfo.

Returns:: The object that stores all the simulation’s details (particles, interaction, etc).
Return type:: ConfigInfo

property current_step: The current time step.

init(self: oxpy.core.OxpyManager) → None: Deprecated since version 3.2.2.

This method does nothing and it exists only for backward compatibility reasons.

load_options(self: oxpy.core.OxpyManager) → None: Deprecated since version 3.2.2.

This method does nothing and it exists only for backward compatibility reasons.

print_configuration(self: oxpy.core.OxpyManager, also_last: bool = True) → None

Append the current configuration to the trajectory file and, by default, print it in the “lastconf_file”.

Parameters:: also_last (bool) – If True (default value) prints the current configuration also in the “lastconf_file” file.

print_timings(self: oxpy.core.OxpyManager) → None: Print the timings taking into account the number of steps run by the manager.

remove_output(self: oxpy.core.OxpyManager, filename: str) → None

Remove an output file from the simulation. Once an output is removed, the simulation will stop updating it.

Parameters:: filename (str) – The name of the output file, which should be the same name used to add it (for instance via add_output()).

run(self: oxpy.core.OxpyManager, steps: int, print_output: bool = True) → None

Run the simulation for the given number of steps. The second argument controls whether the simulations output (configurations and observables) should be printed or not.

Parameters:

steps (int) – The number of steps to be run.
print_output (bool) – If True (the default value) the simulation output will be printed.

run_complete(self: oxpy.core.SimManager) → None: Run the simulation till completion (that is, till the simulation has run number of steps specified in the input file).

steps_run(self: oxpy.core.OxpyManager) → int

Return the number of steps run using this manager.

Returns:: The number of steps run.
Return type:: int

system_energy(self: oxpy.core.OxpyManager) → float

Compute the potential energy of the system in its current state.

Returns:: The system’s potential energy.
Return type:: float

update_CPU_data_structures(self: oxpy.core.OxpyManager) → None

Update the CPU data structures. Useful only when running CUDA simulations.

This method copies simulation data from the GPU to the CPU, and as such calling it too often may severely decrease performance. It is automatically invoked by meth:run, and therefore it makes sense to call it only in specific cases (e.g. to access simulation data from callbacks).

update_temperature(self: oxpy.core.OxpyManager, new_T: float) → None

Change the temperature at which the simulation is run.

Parameters:: new_T (float) – The new temperature.

class oxpy.core.BaseParticle(self: oxpy.core.BaseParticle)

Bases: pybind11_object

A simulation particle.

The default constructor takes no parameters.

property L: The angular momentum of the particle.

property btype: The btype of the particle.

property ext_potential: The potential energy due to the external forces acting on the particle.

property force: The force exerted on the particle.

property index: The index of the particle.

property int_centers: The interaction sites of the particle.

is_bonded(self: oxpy.core.BaseParticle, q: oxpy.core.BaseParticle) → bool

Return whether the current particle and q are bonded neighbours.

Parameters:: q (BaseParticle) – The other Particle.
Returns:: True if the current particle and q are bonded neighbours.
Return type:: bool

property n3: The n3 neighbour.

property n5: The n5 neighbour.

property orientation: The orientation of the particle as a 3x3 matrix.

property pos: The position of the particle.

property strand_id: The id of the strand to which the particle belongs.

property torque: The torque exerted on the particle.

property type: The type of the particle.

property vel: The velocity of the particle.

class oxpy.core.DNANucleotide(self: oxpy.core.DNANucleotide, grooving: bool)

Bases: BaseParticle

A DNA nucleotide.

The constructor takes a single mandatory parameter.

Parameters:: grooving (bool) – The type of DNA to consider (with major/minor grooving or without).

backbone_site(self: oxpy.core.DNANucleotide) → LR_vector

Return the position of the backbone site.

Returns:: The position of the site.
Return type:: numpy.ndarray

base_site(self: oxpy.core.DNANucleotide) → LR_vector

Return the position of the base site.

Returns:: The position of the site.
Return type:: numpy.ndarray

stacking_site(self: oxpy.core.DNANucleotide) → LR_vector

Return the position of the stacking site.

Returns:: The position of the site.
Return type:: numpy.ndarray

class oxpy.core.RNANucleotide(self: oxpy.core.RNANucleotide)

Bases: BaseParticle

A RNA nucleotide. This class exposes the Site enum to access the nucleotide’s sites.

The constructor takes no parameters.

backbone_site(self: oxpy.core.RNANucleotide) → LR_vector

Return the position of the backbone site.

Returns:: The position of the site.
Return type:: numpy.ndarray

base_site(self: oxpy.core.RNANucleotide) → LR_vector

Return the position of the base site.

Returns:: The position of the site.
Return type:: numpy.ndarray

bbvector3_site(self: oxpy.core.RNANucleotide) → LR_vector

Return the position of the bbvector3 site.

Returns:: The position of the site.
Return type:: numpy.ndarray

bbvector5_site(self: oxpy.core.RNANucleotide) → LR_vector

Return the position of the bbvector5 site.

Returns:: The position of the site.
Return type:: numpy.ndarray

stack3_site(self: oxpy.core.RNANucleotide) → LR_vector

Return the position of the stack3 site.

Returns:: The position of the site.
Return type:: numpy.ndarray

stack5_site(self: oxpy.core.RNANucleotide) → LR_vector

Return the position of the stack5 site.

Returns:: The position of the site.
Return type:: numpy.ndarray

stacking_site(self: oxpy.core.RNANucleotide) → LR_vector

Returns the position of the stacking site.

Returns:: The position of the site.
Return type:: numpy.ndarray

class oxpy.core.Molecule

Bases: pybind11_object

A set of particles connected by bonds. For DNA and RNA this would be a strand.

property id: The index of the molecule.

property particles: The list of particles that compose the molecule.

property topology_id: The “topology” index of the molecule. For DNA and RNA this value is the id of the strand as listed in the topology file.

class oxpy.core.BaseInteraction(self: oxpy.core.BaseInteraction)

Bases: pybind11_object

The class that takes care of computing the interaction between the particles.

The default constructor takes no parameters.

begin_energy_computation(self: oxpy.core.BaseInteraction) → None: Signals the interaction that an energy (or force) computation is about to begin.

has_custom_stress_tensor(self: oxpy.core.BaseInteraction) → bool

Return whether the interaction computes the stress tensor internally or not.

Returns:: True if the interaction computes the stress tensor internally, False otherwise.
Return type:: bool

pair_interaction(self: oxpy.core.BaseInteraction, p: oxpy.core.BaseParticle, q: oxpy.core.BaseParticle, compute_r: bool = True, update_forces: bool = False) → float

Compute the pair interaction between p and q.

Parameters:

p (BaseParticle) – The first particle of the pair. Note that some interactions require that the two particles are passed to the method with a specific order.
q (BaseParticle) – The second particle of the pair.
compute_r (bool) – If True (default value), the distance between p and q will be computed from scratch. If not, it will use a private member that can be set through the set_computed_r() method.
update_forces (bool) – If True, the forces and torques acting on the two particles will be updated (defaults to False).

Returns:

The energy of the pair interaction.

Return type:

float

pair_interaction_bonded(self: oxpy.core.BaseInteraction, p: oxpy.core.BaseParticle, q: oxpy.core.BaseParticle, compute_r: bool = True, update_forces: bool = False) → float: Compute the bonded pair interaction between p and q. See pair_interaction() for details on the parameters and on the return value.

pair_interaction_nonbonded(self: oxpy.core.BaseInteraction, p: oxpy.core.BaseParticle, q: oxpy.core.BaseParticle, compute_r: bool = True, update_forces: bool = False) → float: Compute the unbonded pair interaction between p and q. See pair_interaction() for details on the parameters and on the return value.

pair_interaction_term(self: oxpy.core.BaseInteraction, term_id: int, p: oxpy.core.BaseParticle, q: oxpy.core.BaseParticle, compute_r: bool = True, update_forces: bool = False) → float

Compute the pair interaction between p and q due to the specified term.

Parameters:

term_id (int) – The id of the energy term to be computed.
p (BaseParticle) – The first particle of the pair. Note that some interactions require that the two particles are passed to the method with a specific order.
q (BaseParticle) – The second particle of the pair.
compute_r (bool) – If True (default value), the distance between p and q will be computed from scratch. If not, it will use a private member that can be set through the set_computed_r() method.
update_forces (bool) – If True, the forces and torques acting on the two particles will be updated (defaults to False).

Returns:

The energy of the pair interaction due to the specified term.

Return type:

float

set_computed_r(self: oxpy.core.BaseInteraction, r: LR_vector) → None

Set the distance vector used by the pair_interaction_* methods when they are called with compute_r = False (see pair_interaction() for additional details).

Parameters:: r (numpy.ndarray) – The distance vector to be stored.

class oxpy.core.ConfigInfo

Bases: pybind11_object

This singleton object stores all the details of the simulation (particles, neighbour lists, input file, interaction, external forces)

N(self: oxpy.core.ConfigInfo) → int

Return the current number of particles.

Returns:: The number of particles in the simulation box.
Return type:: int

property box: The simulation box, which is an instance of a child class of BaseBox.

property box_sides: The length of the edges of the simulation box.

property current_step: The current time step.

property flattened_conf: A flattened (that is, composed by arrays rather than class instances) view of the current configuration, stored in a FlattenedConfigInfo object.

property forces: The external forces.

get_force_by_id(self: oxpy.core.ConfigInfo, arg0: str) → oxpy.core.forces.BaseForce

Return the force with the given id, which can be set in the external forces file with id = FORCE_ID.

Returns:: The external force with the given id, or None if the id does not correspond to any external force.
Return type:: BaseForce

get_observable_by_id(self: oxpy.core.ConfigInfo, arg0: str) → oxpy.core.observables.BaseObservable

Return the observable with the given id, which can be set in the portion of the input file relative to the observable id = OBSERVABLE_ID.

Returns:: The observable with the given id, or None if the id does not correspond to any observable.
Return type:: BaseObservable

property interaction: The simulation’s IBaseInteraction object.

molecules(self: oxpy.core.ConfigInfo) → List[Molecule]

Return a list of all the molecules.

Returns:: A list containing all the molecules.
Return type:: List(Molecule)

notify(self: oxpy.core.ConfigInfo, event: str) → None

Notify the triggering of an event. Any callback associated to the event will be invoked.

Parameters:: event (str) – The triggered event.

property observables: The simulation observables.

particles(self: oxpy.core.ConfigInfo) → List[oxpy.core.BaseParticle]

Return a list of all the particles.

Returns:: A list containing all the particles in the simulation box.
Return type:: List(BaseParticle)

subscribe(self: oxpy.core.ConfigInfo, event: str, callback: Callable[[], None]) → None

Assign a callback to the given event.

The callback will be invoked every time the event is triggered.

Parameters:

event (str) – The event associated to the callback.
callback (callable) – A callable that takes no parameters.

property temperature: The current simulation temperature.

class oxpy.core.FlattenedConfigInfo

Bases: pybind11_object

An object storing particle types, positions, a1 and a3 orientation vectors in flat arrays that can be used as or converted to numpy arrays.

Note that the data stored in this object is updated maximum once per time step. The update is performed when the object is accessed from the ConfigInfo object, meaning that it is better not to store pointers to this object if you do not want to risk accessing outdated data. The vector types are stored in FlattenedVectorArray objects, which can be used like this:

flat_positions = manager.config_info().flattened_conf.positions
np_poss = np.array(flat_positions, copy=False)
print(np.average(flat_positions, axis=0) == np.average(np_poss, axis=0))

property a1s: Particle a1 orientation vectors

property a3s: Particle a3 orientation vectors

property positions: Particle positions

property types: Particle types

class oxpy.core.FlattenedVectorArray

Bases: pybind11_object

This is a view of a Nx3 matrix (where N is the number of particles in the simulation).

Instances can be transparently converted to numpy arrays:

# this assumes that va is a FlattenedVectorArray
np_va = np.array(va)             # this will copy the data over to Python
np_va = np.array(va, copy=False) # this will *not* copy the data

class oxpy.core.BaseBox(self: oxpy.core.BaseBox)

Bases: pybind11_object

The interface class for forces.

The default constructor takes no parameters.

property V: The volume of the simulation box.

property box_sides

get_abs_pos(self: oxpy.core.BaseBox, p: BaseParticle) → LR_vector

Return the absolute (unwrapped) position of a particle.

Parameters:: p (BaseParticle) – The particle of interest.
Returns:: The absolute (unwrapped) position of the given particle.
Return type:: numpy.ndarray

get_settings(self: oxpy.core.BaseBox, inp: oxpy.core.InputFile) → None

Parse the options relative to this box.

Parameters:: inp (input_file) – The input file of the simulation.

init(self: oxpy.core.BaseBox, arg0: float, arg1: float, arg2: float) → None: Initialise the box. Calling this method fires off a “box_changed” event.

min_image(self: oxpy.core.BaseBox, p: BaseParticle, q: BaseParticle) → LR_vector

Compute and return the PBC-aware distance vector between two particles. The resulting vector points from particle p to particle q.

Parameters:

p (BaseParticle) – The first particle.
q (BaseParticle) – The second particle.

Returns:

The distance vector connecting p to q.

Return type:

numpy.ndarray

sqr_min_image_distance(self: oxpy.core.BaseBox, p: BaseParticle, q: BaseParticle) → float

Compute and return the PBC-aware squared distance between two particles. The result is the squared length of the vector that points from particle p to particle q.

Parameters:

p (BaseParticle) – The first particle.
q (BaseParticle) – The second particle.

Returns:

The squared length of the vector connecting p to q.

Return type:

float

class oxpy.core.InputFile(self: oxpy.core.InputFile)

Bases: pybind11_object

Handles the options provided by the user to control and tune the behaviour of the simulation/analysis/generation of the initial configuration.

Options can be read, set or overwritten by using square brackets:

my_input["sim_type"] = "VMMC"
print(my_input["sim_type"])

Options can also be deleted:

del my_input["log_file"]

To check if a specific option has been set you can use in:

if "debug" in my_input:
        # do something

get_bool(self: oxpy.core.InputFile, arg0: str) → bool

Return the boolean value of an input option.

Returns:: The boolean value of the option.
Return type:: bool

init_from_filename(self: oxpy.core.InputFile, filename: str) → None

Initialise the object from the input file passed as parameter.

Parameters:: filename (str) – The name of the input file whence the options will be loaded.

keys(self: oxpy.core.InputFile) → List[str]

Return the list of keys stored in the input file. For instance, the following code prints all the options stored in an input file:

keys = my_input.keys()
for key in keys:
        print(f"Option '{key}' is set to '{my_input[key]}'")

Returns:: The list of keys stored in the input file.
Return type:: List(str)