entities.OXDNA
entities.OXDNA(
universe,
name='NewOXDNAObject',
world_scale=0.1,
create_object=True,
)A class to handle oxDNA trajectory data.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| universe | MDAnalysis.Universe |
The MDAnalysis Universe object containing the trajectory data | required |
| world_scale | float | Scaling factor for the world coordinates, by default 0.01 | 0.1 |
Attributes
| Name | Type | Description |
|---|---|---|
| _entity_type | EntityType |
Type of the molecular entity |
| _att_names | tuple | Names of the attributes to track |
Methods
| Name | Description |
|---|---|
| add_style | Add a visual style to the trajectory. |
| assemblies | Get the biological assemblies parsed from the source file. |
| create_asset_nodes | Create asset nodes for the entity object. |
| create_data_object | Create the data object holding the biological assembly transforms. |
| create_object | Create and initialize Blender object for trajectory. |
| fetch | Fetch a structure from an online database into a Universe-backed entity. |
| frames_to_collection | Bake a range of trajectory frames into a collection of frame objects. |
| from_file | Load a single structure file into a Universe-backed entity. |
| get_view | The world-space positions of a view onto this molecule. |
| load | Load an oxDNA topology and trajectory. |
| reset_playback | Set the playback settings to their default values |
add_style
entities.OXDNA.add_style(
style='spheres',
selection=None,
material=_UNSET,
color=None,
assembly=False,
name=None,
**kwargs,
)Add a visual style to the trajectory.
Provides a simple interface for adding visual styles to the molecule. For more complex styling, use the manual node tree creation via the with mol.tree: context manager.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| style | str | Callable | The style to apply. Either a string naming a predefined style (“spheres”, “cartoon”, “ribbon”, “surface”, “sticks”, “ball_and_stick”), or a zero-argument callable returning a style node, evaluated inside the node tree context:: mol.add_style(lambda: mg.StyleCartoon(quality=5, loop_radius=0.6)) A callable defines the style node itself, so selection, material and extra keyword arguments cannot be combined with it - set them inside the callable. Default is “spheres”. |
'spheres' |
| selection | str | AtomGroup | Callable | None | Apply the style only to atoms matching this selection. Can be: - A string naming an existing boolean attribute on the molecule (used directly) - A string MDAnalysis selection phrase (evaluated and stored as a new managed selection attribute) - A AtomGroup object defining a selection criteria - A zero-argument callable returning a boolean socket, evaluated inside the node tree context, e.g. lambda: mg.IsPeptide() & mg.IsSideChain() - None to apply to all atoms (default) A string is treated as an existing attribute name first; only if no such attribute exists is it interpreted as an MDAnalysis selection phrase. |
None |
| material | bpy.types.Material | PresetMaterial | MaterialBuilder | str | None |
The material to apply to the styled atoms. Can be one of the preset materials from mn.material (e.g. mn.material.AmbientOcclusion()), a Blender Material object, a nodebpy MaterialBuilder, a string with a material name to append from the asset file, or None for no material. Default is “MN Default”. |
_UNSET |
| color | str | Sequence[float] | Callable | None | Coloring to apply upstream of the style via a Set Color node. Can be: - "common" / "default" for standard element colors with carbons colored randomly per chain - "plddt" to color by pLDDT (B-factor) confidence - the name of an existing color attribute on the geometry - an RGBA sequence of floats for a single uniform color - a zero-argument callable returning a color socket, evaluated inside the node tree context, e.g. lambda: mg.ColorRainbow(). This is the way to reach the full set of Color* nodes without writing out a whole node tree. - None (default) to add no color node, leaving the baked Color attribute in use. A string that is neither a keyword nor an existing color attribute raises a UserWarning and no color is applied. |
None |
| assembly | bool | Instance the style over the biological assembly transforms parsed from the source file, via an Assembly Instance node. Default is False. |
False |
| name | str | None | Optional label for the added style node, shown in the node editor and style lists. Default is None. | None |
| **kwargs | optional |
Additional keyword arguments passed to the style node, matching that node’s inputs (e.g. quality, scale, sphere for spheres). Unknown names raise a TypeError. Cannot be combined with a callable style. |
{} |
Returns
| Name | Type | Description |
|---|---|---|
| Molecule | Returns self for method chaining. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If an unsupported style string is passed | |
| TypeError | If a callable style is combined with selection, material or extra keyword arguments, or if a keyword argument does not match an input on the style node |
Notes
If a selection is provided, it will be evaluated and stored as a new named attribute on the trajectory with an automatically generated name (sel_N).
assemblies
entities.OXDNA.assemblies(as_array=False)Get the biological assemblies parsed from the source file.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| as_array | bool | Return the assemblies as a structured array of per-chain 4x4 transforms rather than a dict. | False |
Returns
| Name | Type | Description |
|---|---|---|
| dict | np.ndarray | None | The biological assemblies as transformation matrices, or None when the structure has no assembly data. |
create_asset_nodes
entities.OXDNA.create_asset_nodes()Create asset nodes for the entity object.
This creates Select and Color nodes for each property combination. Chains, entities, and segments have nodes created for them if they have IDs. Nodes are created and registered as assets for the current Blender session so they can be added through drag-to-search in the node editor.
create_data_object
entities.OXDNA.create_data_object()Create the data object holding the biological assembly transforms.
create_object
entities.OXDNA.create_object(name='NewUniverseObject')Create and initialize Blender object for trajectory.
Creates mesh, computes attributes, sets up modifiers, registers with MolecularNodes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str | Name for the Blender object | "NewUniverseObject" |
Returns
| Name | Type | Description |
|---|---|---|
bpy.types.Object |
Created Blender object |
fetch
entities.OXDNA.fetch(
code,
format='.bcif',
cache=download.CACHE_DIR,
database='rcsb',
)Fetch a structure from an online database into a Universe-backed entity.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| code | str | The database accession code (e.g. a PDB id). | required |
| format | str | File format to download, by default ".bcif". |
'.bcif' |
| cache | Path | str | None | Directory to cache downloads in. | download.CACHE_DIR |
| database | str | The database to fetch from, by default "rcsb". |
'rcsb' |
Returns
| Name | Type | Description |
|---|---|---|
| Molecule | The Universe-backed entity representing the fetched structure. |
frames_to_collection
entities.OXDNA.frames_to_collection(start=0, stop=None, step=1, name=None)Bake a range of trajectory frames into a collection of frame objects.
Each object in the returned collection holds the atom positions (in Blender world units) for a single frame, in the same vertex order as this molecule’s mesh. The collection can then be read inside geometry nodes (e.g. with the Animate Frames node) to drive positions from baked data, rather than updating the Universe every scene frame.
Re-baking replaces any objects previously baked into the same collection.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| start | int | First trajectory frame to bake (inclusive). | 0 |
| stop | int | None | One past the last frame to bake. Defaults to the number of frames in the trajectory (i.e. bake through the final frame). | None |
| step | int | Stride between baked frames. | 1 |
| name | str | None | Name for the frames collection. Defaults to this molecule’s name. | None |
Returns
| Name | Type | Description |
|---|---|---|
bpy.types.Collection |
The collection of baked frame objects. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If step is not a positive integer. |
from_file
entities.OXDNA.from_file(file_path, name=None)Load a single structure file into a Universe-backed entity.
The file (.pdb/.cif/.bcif/.sdf/.mol) is parsed by the biotite readers and converted into an MDAnalysis Universe via :func:~molecularnodes.converters.universe_from_atoms. Multi-model files become multi-frame universes. Biological assembly and entity/chain metadata parsed from the file are stored on the Blender object.
Small-molecule crystallographic .cif files (e.g. from the ICSD or COD) are instead read by :mod:~molecularnodes.entities.molecule.corecif, which expands the asymmetric unit by the file’s symmetry operators to fill one unit cell. .xyz files are read natively by MDAnalysis, with elements taken from the atom names.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| file_path | str | Path | io.BytesIO | Path to the structure file (or an in-memory bcif buffer). |
required |
| name | str | None | Name for the Blender object. Defaults to the file name (extension included). | None |
Returns
| Name | Type | Description |
|---|---|---|
| Molecule | The Universe-backed entity representing the structure. |
get_view
entities.OXDNA.get_view(selection=None, frame=None)The world-space positions of a view onto this molecule.
Without a selection these are the positions of the geometry the molecule renders; with one they are the positions of the selected atoms. Pass the result to look_at to frame it, or combine views from several selections with + to frame all of them together.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| selection | str | AtomGroup | A selection phrase or AtomGroup When not specified, the whole entity is considered | None |
| frame | int | None | Frame number of trajectory to use for calculating bounds. When not specified, current trajectory frame is used | None |
load
entities.OXDNA.load(
topology,
coordinates,
name='oxDNA',
style='ribbon',
world_scale=0.1,
create_object=True,
)Load an oxDNA topology and trajectory.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| topology | str | Path | Path to the oxDNA topology file. | required |
| coordinates | str | Path | Path to the oxDNA trajectory/configuration file. | required |
| name | str | Name for the created object, by default “oxDNA”. | 'oxDNA' |
| style | str | None | Visual style to apply, by default “ribbon”. If None, no style is added. | 'ribbon' |
| world_scale | float | Scaling factor for world coordinates, by default 0.1. | 0.1 |
| create_object | bool | Whether to create the Blender object immediately, by default True. | True |
Returns
| Name | Type | Description |
|---|---|---|
| OXDNA | The created oxDNA trajectory entity. |
reset_playback
entities.OXDNA.reset_playback()Set the playback settings to their default values