nuri.core

The core module of NuriKit.

This module contains the core classes of NuriKit. The core module is not very useful by itself, but is a dependency of many other modules. Chemical data structures, such as elements, isotopes, and molecules, and also the graph structure and algorithms, are defined in this module.

class nuri.core.Molecule

A molecule. Refer to the nuri::Molecule class in the C++ API Reference for more details.

__init__(self: Molecule) → None

Create an empty molecule.

atom(self: Molecule, idx: int) → Atom

Get an atom of the molecule.

Parameters:

idx – The index of the atom to get.

Returns:

The atom at the index.

Return type:

Atom

Note

The returned atom is invalidated when a mutator context is exited. If the atom must be kept alive, copy the atom data first with Atom.copy_data() method.

num_atoms(self: Molecule) → int

Get the number of atoms in the molecule. Equivalent to len(mol).

bonds(self: Molecule) → nuri.core._core._BondsWrapper

Return type:

Sequence[Bond]

A wrapper object to access the bonds of the molecule. You can iterate the bonds of the molecule with this object.

bond(*args, **kwargs)

Overloaded function.

1. bond(self: nuri.core._core.Molecule, idx: int) -> nuri.core._core.Bond

Get a bond of the molecule.

Parameters:

idx – The index of the bond to get.

Returns:

The bond at the index.

Return type:

Bond

Note

The returned bond is invalidated when a mutator context is exited. If the bond must be kept alive, copy the bond data first with Bond.copy_data() method.

2. bond(self: nuri.core._core.Molecule, src: int, dst: int) -> nuri.core._core.Bond

Get a bond of the molecule. src and dst are interchangeable.

Parameters:

• src – The index of the source atom of the bond.

• dst – The index of the destination atom of the bond.

Returns:

The bond from the source to the destination atom.

Return type:

Bond

Raises:

• ValueError – If the bond does not exist.

• IndexError – If the source or destination atom does not exist.

See also

neighbor()

Note

The returned bond may not have bond.src.id == src and bond.dst.id == dst, as the source and destination atoms of the bond may be swapped.

Note

The returned bond is invalidated when a mutator context is exited. If the bond must be kept alive, copy the bond data first with Bond.copy_data() method.

3. bond(self: nuri.core._core.Molecule, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> nuri.core._core.Bond

Get a bond of the molecule. src and dst are interchangeable.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Returns:

The bond from the source to the destination atom.

Return type:

Bond

Raises:

ValueError – If the bond does not exist, or any of the atoms does not belong to the molecule.

See also

neighbor()

Note

The returned bond may not have bond.src.id == src.id and bond.dst.id == dst.id, as the source and destination atoms of the bond may be swapped.

Note

The returned bond is invalidated when a mutator context is exited. If the bond must be kept alive, copy the bond data first with Bond.copy_data() method.

has_bond(*args, **kwargs)

Overloaded function.

1. has_bond(self: nuri.core._core.Molecule, src: int, dst: int) -> bool

Check if two atoms are connected by a bond.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Returns:

Whether the source and destination atoms are connected by a bond.

Raises:

IndexError – If the source or destination atom does not exist.

2. has_bond(self: nuri.core._core.Molecule, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> bool

Check if two atoms are connected by a bond.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Returns:

Whether the source and destination atoms are connected by a bond.

Raises:

ValueError – If any of the atoms does not belong to the molecule.

num_bonds(self: Molecule) → int

Get the number of bonds in the molecule. Equivalent to len(mol.bonds).

neighbor(*args, **kwargs)

Overloaded function.

1. neighbor(self: nuri.core._core.Molecule, src: int, dst: int) -> nuri.core._core.Neighbor

Get a neighbor of the molecule.

Parameters:

• src – The index of the source atom of the neighbor.

• dst – The index of the destination atom of the neighbor.

Returns:

The neighbor from the source to the destination atom.

Return type:

Neighbor

Raises:

• ValueError – If the underlying bond does not exist.

• IndexError – If the source or destination atom does not exist.

See also

bond()

Note

Unlike bond(), the returned neighbor is always guaranteed to have nei.src.id == src and nei.dst.id == dst.

Note

The returned neighbor is invalidated when a mutator context is exited.

2. neighbor(self: nuri.core._core.Molecule, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> nuri.core._core.Neighbor

Get a neighbor of the molecule.

Parameters:

• src – The source atom of the neighbor.

• dst – The destination atom of the neighbor.

Returns:

The neighbor from the source to the destination atom.

Return type:

Neighbor

Raises:

ValueError – If the underlying bond does not exist, or any of the atoms does not belong to the molecule.

See also

bond()

Note

Unlike bond(), the returned neighbor is always guaranteed to have nei.src.id == src.id and nei.dst.id == dst.id.

Note

The returned neighbor is invalidated when a mutator context is exited.

mutator(self: Molecule) → Mutator

Get a mutator for the molecule. Use this as a context manager to make changes to the molecule.

Note

The mutator will invalidate all atom and bond objects when the context is exited, whether or not the changes are made. If the objects must be kept alive, copy the data first with Atom.copy_data() and Bond.copy_data() methods.

Note

Successive calls to this method will raise an exception if the previous mutator is not finalized.

get_conf(self: Molecule, conf: int = 0) → ndarray[numpy.float64]

Get the coordinates of the atoms in a conformation.

Parameters:

conf – The index of the conformation to get the coordinates from.

Returns:

The coordinates of the atoms in the conformation, as a 2D array of shape (num_atoms, 3).

Note

The returned array is a copy of the coordinates. To update the coordinates, use the set_conf() method.

set_conf(self: Molecule, coords: object, conf: int = 0) → None

Set the coordinates of the atoms in a conformation.

Parameters:

• coords – The coordinates of the atoms in the conformation. Must be convertible to a numpy array of shape (num_atoms, 3).

• conf – The index of the conformation to set the coordinates to.

num_confs(self: Molecule) → int

Get the number of conformations of the molecule.

add_conf(*args, **kwargs)

Overloaded function.

1. add_conf(self: nuri.core._core.Molecule, coords: object) -> int

Add a conformation to the molecule at the end.

Parameters:

coords – The coordinates of the atoms in the conformation. Must be convertible to a numpy array of shape (num_atoms, 3).

Returns:

The index of the added conformation.

2. add_conf(self: nuri.core._core.Molecule, coords: object, conf: int) -> int

Add a conformation to the molecule.

Parameters:

• coords – The coordinates of the atoms in the conformation. Must be convertible to a numpy array of shape (num_atoms, 3).

• conf – The index of the conformation to add the coordinates to. If negative, counts from back to front (i.e., the new conformer will be created at max(0, num_confs() + conf)). Otherwise, the coordinates are added at min(conf, num_confs()). This resembles the behavior of Python’s list.insert() method.

Returns:

The index of the added conformation.

add_from(*args, **kwargs)

Overloaded function.

1. add_from(self: nuri.core._core.Molecule, other: nuri.core._core.Molecule) -> None

Add all atoms and bonds from another molecule to the molecule.

Parameters:

other – The molecule to add from.

2. add_from(self: nuri.core._core.Molecule, other: nuri.core._core.Substructure) -> None

Add all atoms and bonds from a substructure to the molecule.

Parameters:

other – The substructure to add from.

3. add_from(self: nuri.core._core.Molecule, other: nuri.core._core.ProxySubstructure) -> None

Add all atoms and bonds from a substructure to the molecule.

Parameters:

other – The substructure to add from.

clear(self: Molecule) → None

Effectively resets the molecule to an empty state.

Note

Invalidates all atom and bond objects.

Warning

Molecules with active mutator context cannot be cleared.

See also

Mutator.clear()

clear_atoms(self: Molecule) → None

Clear all atoms and bonds of the molecule. Other metadata are left unmodified.

Note

Invalidates all atom and bond objects.

Warning

Molecules with active mutator context cannot clear atoms.

See also

Mutator.clear_atoms()

clear_bonds(self: Molecule) → None

Clear all bonds of the molecule. Atoms and other metadata are left unmodified.

Note

Invalidates all atom and bond objects.

Warning

Molecules with active mutator context cannot clear bonds.

See also

Mutator.clear_bonds()

clear_confs(self: Molecule) → None

Remove all conformations from the molecule.

conceal_hydrogens(self: Molecule) → None

Convert trivial explicit hydrogen atoms of the molecule to implicit hydrogens.

Trivial explicit hydrogen atoms are the hydrogen atoms that are connected to only one heavy atom with a single bond and have no other neighbors (including implicit hydrogens).

Note

Invalidates all atom and bond objects.

conformers(self: Molecule) → nuri.core._core._ConformerIterator

Get an iterable object of all conformations of the molecule. Each conformation is a 2D array of shape (num_atoms, 3). It is not available to update the coordinates from the returned conformers; you should manually assign to the conformers to update the coordinates.

Return type:

Iterable[ndarray]

See also

get_conf(), set_conf()

copy(self: Molecule) → Molecule

Return a deep copy of self.

del_conf(self: Molecule, conf: int) → None

Remove a conformation from the molecule.

Parameters:

conf – The index of the conformation to remove.

num_fragments(self: Molecule) → int

The number of connected components (fragments) in the molecule.

Warning

This might return incorrect value if the molecule is in a mutator context.

num_sssr(self: Molecule) → int

The number of smallest set of smallest rings (SSSR) in the molecule.

Warning

This might return incorrect value if the molecule is in a mutator context.

reveal_hydrogens(self: Molecule, update_confs: bool = True, optimize: bool = True) → None

Convert implicit hydrogen atoms of the molecule to explicit hydrogens.

Parameters:

• update_confs – If True, the conformations of the molecule will be updated to include the newly added hydrogens. When set to False, the coordinates of the added hydrogens will have garbage values. Default to True.

• optimize – If True, the conformations will be optimized after adding hydrogens. Default to True. This parameter is ignored if update_confs is False.

Raises:

ValueError – If the hydrogens cannot be added. This can only happen if update_confs is True and the molecule has at least one conformation.

Note

Invalidates all atom and bond objects.

sanitize(self: Molecule, *, conjugation: bool = True, aromaticity: bool = True, hyb: bool = True, valence: bool = True) → None

Sanitize the molecule.

Parameters:

• conjugation – If True, sanitize conjugation.

• aromaticity – If True, sanitize aromaticity.

• hyb – If True, sanitize hybridization.

• valence – If True, sanitize valence.

Raises:

ValueError – If the sanitization fails.

Note

The sanitization is done in the order of conjugation, aromaticity, hybridization, and valence. If any of the sanitization fails, the subsequent sanitization will not be attempted.

Note

The sanitization is done in place. The state of molecule will be mutated even if the sanitization fails.

Note

If any of the other three sanitization is requested, the conjugation will be automatically turned on.

Warning

This interface is experimental and may change in the future.

sub(self: nuri.core._core.Molecule, atoms: Optional[Iterable[Union[nuri.core._core.Atom, int]]] = None, bonds: Optional[Iterable[Union[nuri.core._core.Bond, int]]] = None, cat: nuri.core._core.SubstructureCategory = <SubstructureCategory.Unknown: 0>) → Substructure

Create a substructure of the molecule.

Parameters:

• atoms (Iterable[Atom | int]) – The atoms to include in the substructure.

• bonds (Iterable[Bond | int]) – The bonds to include in the substructure.

• cat – The category of the substructure.

This has three mode of operations:

1. If both atoms and bonds are given, a substructure is created with the given atoms and bonds. The atoms connected by the bonds will also be added to the substructure, even if they are not in the atoms list.

2. If only atoms are given, a substructure is created with the given atoms. All bonds between the atoms will also be added to the substructure.

3. If only bonds are given, a substructure is created with the given bonds. The atoms connected by the bonds will also be added to the substructure.

4. If neither atoms nor bonds are given, an empty substructure is created.

Tip

Pass empty list to bonds to create an atoms-only substructure.

property name

Type:

str

property props

Type:

MutableMapping[str, str]

A dictionary-like object to store additional properties of the molecule. The keys and values are both strings.

property subs

Type:

SubstructureContainer

A container of substructures of the molecule. You can iterate the substructures of the molecule with this object.

class nuri.core.Mutator

A mutator for a molecule. Use this as a context manager to make changes to a molecule:

>>> from nuri.core import Molecule, AtomData
>>> mol = Molecule()
>>> print(mol.num_atoms())
0
>>> with mol.mutator() as mut:  
...     src = mut.add_atom(6)
...     dst = mut.add_atom(6)
...     mut.add_bond(src, dst)
>>> print(mol.num_atoms())
2
>>> print(mol.num_bonds())
1
>>> print(mol.atom(0).atomic_number)
6
>>> print(mol.bond(0).order)
BondOrder.Single

Note

The mutator is invalidated when the context is exited. It is an error to use the mutator after the context is exited.

add_atom(*args, **kwargs)

Overloaded function.

1. add_atom(self: nuri.core._core.Mutator, data: nuri.core._core.AtomData = None) -> nuri.core._core.Atom

Add an atom to the molecule.

Parameters:

data – The data of the atom to add. If not given, the atom is added with default properties.

Returns:

The created atom.

2. add_atom(self: nuri.core._core.Mutator, atomic_number: int) -> nuri.core._core.Atom

Add an atom to the molecule.

Parameters:

atomic_number – The atomic number of the atom to add. Other properties of the atom are set to default.

Returns:

The created atom.

add_bond(*args, **kwargs)

Overloaded function.

1. add_bond(self: nuri.core._core.Mutator, src: int, dst: int, order: nuri.core._core.BondOrder = <BondOrder.Single: 1>) -> nuri.core._core.Bond

Add a bond to the molecule.

Parameters:

• src – The index of the source atom.

• dst – The index of the destination atom.

• order – The order of the bond to add. Other properties of the bond are set to default. If not given, the bond is added with single bond order.

Returns:

The created bond.

2. add_bond(self: nuri.core._core.Mutator, src: nuri.core._core.Atom, dst: nuri.core._core.Atom, order: nuri.core._core.BondOrder = <BondOrder.Single: 1>) -> nuri.core._core.Bond

Add a bond to the molecule.

Parameters:

• src – The source atom.

• dst – The destination atom.

• order – The order of the bond to add. Other properties of the bond are set to default. If not given, the bond is added with single bond order.

Returns:

The created bond.

3. add_bond(self: nuri.core._core.Mutator, src: int, dst: int, data: nuri.core._core.BondData) -> nuri.core._core.Bond

Add a bond to the molecule.

Parameters:

• src – The index of the source atom.

• dst – The index of the destination atom.

• data – The data of the bond to add.

Returns:

The created bond.

4. add_bond(self: nuri.core._core.Mutator, src: nuri.core._core.Atom, dst: nuri.core._core.Atom, data: nuri.core._core.BondData) -> nuri.core._core.Bond

Add a bond to the molecule.

Parameters:

• src – The source atom.

• dst – The destination atom.

• data – The data of the bond to add.

Returns:

The created bond.

clear(self: Mutator) → None

Effectively resets the molecule to an empty state.

Note

Invalidates all atom and bond objects.

clear_atoms(self: Mutator) → None

Clear all atoms and bonds of the molecule. Other metadata are left unmodified.

Note

Invalidates all atom and bond objects.

clear_bonds(self: Mutator) → None

Clear all bonds of the molecule. Atoms and other metadata are left unmodified.

Note

Invalidates all atom and bond objects.

mark_atom_erase(*args, **kwargs)

Overloaded function.

1. mark_atom_erase(self: nuri.core._core.Mutator, arg0: int) -> None

Mark an atom to be erased from the molecule. The atom is not erased until the context manager is exited.

Parameters:

idx – The index of the atom to erase.

2. mark_atom_erase(self: nuri.core._core.Mutator, arg0: nuri.core._core.Atom) -> None

Mark an atom to be erased from the molecule. The atom is not erased until the context manager is exited.

Parameters:

atom – The atom to erase.

mark_bond_erase(*args, **kwargs)

Overloaded function.

1. mark_bond_erase(self: nuri.core._core.Mutator, src: int, dst: int) -> None

Mark a bond to be erased from the molecule. The bond is not erased until the context manager is exited.

Parameters:

• src – The index of the source atom of the bond.

• dst – The index of the destination atom of the bond.

Raises:

ValueError – If the bond does not exist.

2. mark_bond_erase(self: nuri.core._core.Mutator, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> None

Mark a bond to be erased from the molecule. The bond is not erased until the context manager is exited.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Raises:

ValueError – If the bond does not exist.

3. mark_bond_erase(self: nuri.core._core.Mutator, idx: int) -> None

Mark a bond to be erased from the molecule. The bond is not erased until the context manager is exited.

Parameters:

idx – The index of the bond to erase.

4. mark_bond_erase(self: nuri.core._core.Mutator, bond: nuri.core._core.Bond) -> None

Mark a bond to be erased from the molecule. The bond is not erased until the context manager is exited.

Parameters:

bond – The bond to erase.

class nuri.core.Atom

An atom of a molecule.

This is a proxy object to the AtomData of the atom in a molecule. The proxy object is invalidated when any changes are made to the molecule. If underlying data must be kept alive, copy the data first with copy_data() method.

We only document the differences from the original class. Refer to the AtomData class for common properties and methods.

Note

Unlike the underlying data object, the atom cannot be created directly. Use the Mutator.add_atom() method to add an atom to a molecule.

property id

Type:

int

A unique identifier of the atom in the molecule. The identifier is guaranteed to be unique within the atoms of the molecule.

This is a read-only property.

Note

Implementation detail: the identifier is the index of the atom.

count_neighbors(self: Atom) → int

Count connected atoms to the atom. Includes both explicit and implicit neighbors.

Note

This is not same with len(atom). The length of the atom is the number of explicit neighbors, or, the iterable neighbors of the atom. Implicit hydrogens could not be iterated, thus not counted in the length.

count_heavy_neighbors(self: Atom) → int

Count heavy neighbors connected to the atom. A heavy atom is an atom that is not hydrogen.

count_hydrogens(self: Atom) → int

Count hydrogen atoms connected to the atom. Includes both explicit and implicit hydrogens.

get_pos(self: Atom, conf: int = 0) → ndarray[numpy.float64]

Get the position of the atom.

Parameters:

conf – The index of the conformation to get the position from. Defaults to 0.

Returns:

The position of the atom.

Note

The position could not be directly set from Python. Use the set_pos() method to set the position.

set_pos(self: Atom, pos: object, conf: int = 0) → None

Set the position of the atom.

Parameters:

• pos – The 3D vector to set the position to. Must be convertible to a numpy array of shape (3,).

• conf – The index of the conformation to set the position to. Defaults to 0.

copy_data(self: Atom) → AtomData

Copy the underlying AtomData object.

Returns:

A copy of the underlying AtomData object.

class nuri.core.Bond

A bond of a molecule.

This is a proxy object to the BondData of the bond in a molecule. The proxy object is invalidated when any changes are made to the molecule. If underlying data must be kept alive, copy the data first with copy_data() method.

We only document the differences from the original class. Refer to the BondData class for common properties and methods.

Note

Unlike the underlying data object, the bond cannot be created directly. Use the Mutator.add_bond() method to add a bond to a molecule.

property id

Type:

int

A unique identifier of the bond in the molecule. The identifier is guaranteed to be unique within the bonds of the molecule.

This is a read-only property.

Note

Implementation detail: the identifier is the index of the bond.

property src

Type:

Atom

The source atom of the bond.

property dst

Type:

Atom

The destination atom of the bond.

length(self: Bond, conf: int = 0) → float

Calculate the length of the bond.

Parameters:

conf – The index of the conformation to calculate the length from. Defaults to 0.

Returns:

The length of the bond.

sqlen(self: Bond, conf: int = 0) → float

Calculate the square of the length of the bond.

Parameters:

conf – The index of the conformation to calculate the length from. Defaults to 0.

Returns:

The square of the length of the bond.

rotate(self: Bond, angle: float, rotate_src: bool = False, strict: bool = True, conf: int | None = None) → None

Rotate the bond by the given angle. The components connected only to the destination atom (excluding this bond) are rotated around the bond axis. Rotation is done in the direction of the right-hand rule, i.e., the rotation is counter-clockwise with respect to the src -> dst vector.

Parameters:

• angle – The angle to rotate the bond by, in degrees.

• rotate_src – If True, the source atom side is rotated instead.

• strict – If True, rotation will fail for multiple bonds and conjugated bonds. If False, the rotation will be attempted regardless.

• conf – The index of the conformation to rotate the bond in. If not given, all conformations are rotated.

Raises:

ValueError – If the bond is not rotatable. If strict is False, it will be raised only if the bond is a member of a ring, as it will be impossible to rotate the bond without breaking the ring.

copy_data(self: Bond) → BondData

Copy the underlying BondData object.

Returns:

A copy of the underlying BondData object.

class nuri.core.Neighbor

A neighbor of an atom in a molecule.

property bond

Type:

Bond

The bond between the source and destination atoms.

Note

There is no guarantee that nei.src.id == bond.src.id and nei.dst.id == bond.dst.id; the source and destination atoms of the bond may be swapped.

property dst

Type:

Atom

The destination atom of the bond.

property src

Type:

Atom

The source atom of the bond.

class nuri.core.Substructure

A substructure of a molecule.

This will invalidate when the parent molecule is modified.

add_atoms(self: Substructure, atoms: Iterable[Atom | int], add_bonds: bool = True) → None

Add atoms to the substructure.

Parameters:

• atoms (Iterable[Atom | int]) – The atoms to add to the substructure. The atoms must belong to the same molecule as the substructure. All duplicate atoms are ignored.

• add_bonds (bool) – If True, the bonds between the added atoms are also added to the substructure. If False, the bonds are not added.

Raises:

• TypeError – If any atom is not an Atom or int.

• ValueError – If any atom does not belong to the same molecule.

• IndexError – If any atom index is out of range.

Note

Due to the implementation, it is much faster to add atoms in bulk than adding them one by one. Thus, we explicitly provide only the bulk addition method.

add_bonds(self: Substructure, bonds: Iterable[Bond | int]) → None

Add bonds to the substructure. If any atom of the bond does not belong to the substructure, the atom is also added to the substructure.

Parameters:

bonds (Iterable[Bond | int]) – The bonds to add to the substructure. The bonds must belong to the same molecule as the substructure. All duplicate bonds are ignored.

Raises:

• TypeError – If any bond is not a Bond or int.

• ValueError – If any bond does not belong to the same molecule.

• IndexError – If any bond index is out of range.

Note

Due to the implementation, it is much faster to add bonds in bulk than adding them one by one. Thus, we explicitly provide only the bulk addition method.

atom(*args, **kwargs)

Overloaded function.

1. atom(self: nuri.core._core.Substructure, idx: int) -> nuri.core._core.SubAtom

Get a substructure atom by index.

Parameters:

idx – The index of the atom.

Returns:

The atom at the given index.

Return type:

SubAtom

Note

The returned atom is invalidated when the parent molecule is modified, or if the substructure is modified. If the atom must be kept alive, copy the atom data first.

2. atom(self: nuri.core._core.Substructure, atom: nuri.core._core.Atom) -> nuri.core._core.SubAtom

Get a substructure atom from a parent atom.

Parameters:

atom – The parent atom to get the sub-atom of.

Returns:

The sub-atom of the parent atom.

Return type:

SubAtom

Note

The returned atom is invalidated when the parent molecule is modified, or if the substructure is modified. If the atom must be kept alive, copy the atom data first.

bond(*args, **kwargs)

Overloaded function.

1. bond(self: nuri.core._core.Substructure, idx: int) -> nuri.core._core.SubBond

Get a bond by index.

Parameters:

idx – The index of the bond.

Returns:

The bond at the given index.

Return type:

SubBond

2. bond(self: nuri.core._core.Substructure, bond: nuri.core._core.Bond) -> nuri.core._core.SubBond

Get a substructure bond from a parent bond.

Parameters:

bond – The parent bond to get the sub-bond of.

Returns:

The sub-bond of the parent bond.

Return type:

SubBond

Note

The returned bond is invalidated when the parent molecule is modified, or if the substructure is modified. If the bond must be kept alive, copy the bond data first.

3. bond(self: nuri.core._core.Substructure, src: nuri.core._core.SubAtom, dst: nuri.core._core.SubAtom) -> nuri.core._core.SubBond

Get a bond of the substructure. src and dst are interchangeable.

Parameters:

• src – The source sub-atom of the bond.

• dst – The destination sub-atom of the bond.

Returns:

The bond from the source to the destination sub-atom.

Return type:

SubBond

Raises:

ValueError – If the bond does not exist, or any of the sub-atoms does not belong to the substructure.

See also

neighbor()

Note

The returned bond may not have bond.src.id == src.id and bond.dst.id == dst.id, as the source and destination atoms of the bond may be swapped.

Note

The returned bond is invalidated when the parent molecule is modified, or if the substructure is modified. If the bond must be kept alive, copy the bond data first.

4. bond(self: nuri.core._core.Substructure, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> nuri.core._core.SubBond

Get a bond of the substructure. src and dst are interchangeable.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Returns:

The bond from the source to the destination atom.

Return type:

SubBond

Raises:

ValueError – If the bond does not exist, the source or destination atom does not belong to the substructure, or any of the atoms does not belong to the same molecule.

See also

neighbor()

Note

The source and destination atoms of the bond may be swapped.

Note

The returned bond is invalidated when the parent molecule is modified, or if the substructure is modified. If the bond must be kept alive, copy the bond data first.

bonds(self: Substructure) → nuri.core._core._SubBonds

Return type:

Sequence[SubBond]

Get a collection of bonds in the substructure. Invalidated when the parent molecule is modified, or if the substructure is modified.

clear(self: Substructure) → None

Effectively reset the substructure to an empty state.

clear_atoms(self: Substructure) → None

Remove all atoms from the substructure. The bonds are also removed. Other metadata of the substructure is not affected.

clear_bonds(self: Substructure) → None

Remove all bonds from the substructure. The atoms and other metadata of the substructure is not affected.

conceal_hydrogens(self: Substructure) → None

Convert trivial explicit hydrogen atoms of the substructure to implicit hydrogens.

Trivial explicit hydrogen atoms are the hydrogen atoms that are connected to only one heavy atom with a single bond and have no other neighbors (including implicit hydrogens).

Note

Invalidates all atom and bond objects.

conformers(self: Substructure) → nuri.core._core._SubConformersIterator

Get an iterable object of all conformations of the substructure. Each conformation is a 2D array of shape (num_atoms, 3). It is not available to update the coordinates from the returned conformers; you should manually assign to the conformers to update the coordinates.

Return type:

Iterable[ndarray]

See also

get_conf(), set_conf()

erase_atom(*args, **kwargs)

Overloaded function.

1. erase_atom(self: nuri.core._core.Substructure, sub_atom: nuri.core._core.SubAtom) -> None

Remove an atom from the substructure. Any bonds connected to the atom are also removed.

Parameters:

sub_atom – The sub-atom to remove.

Note

The parent molecule is not modified by this operation.

2. erase_atom(self: nuri.core._core.Substructure, atom: nuri.core._core.Atom) -> None

Remove an atom from the substructure. Any bonds connected to the atom are also removed.

Parameters:

atom – The parent atom to remove.

Raises:

ValueError – If the atom is not in the substructure.

Note

The parent molecule is not modified by this operation.

erase_bond(*args, **kwargs)

Overloaded function.

1. erase_bond(self: nuri.core._core.Substructure, sub_bond: nuri.core._core.SubBond) -> None

Remove a bond from the substructure.

Parameters:

sub_bond – The sub-bond to remove.

Note

The parent molecule is not modified by this operation.

2. erase_bond(self: nuri.core._core.Substructure, bond: nuri.core._core.Bond) -> None

Remove a bond from the substructure.

Parameters:

bond – The parent bond to remove.

Raises:

ValueError – If the bond is not in the substructure.

Note

The parent molecule is not modified by this operation.

3. erase_bond(self: nuri.core._core.Substructure, src: nuri.core._core.SubAtom, dst: nuri.core._core.SubAtom) -> None

Remove a bond from the substructure. The source and destination atoms are interchangeable.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Raises:

ValueError – If the bond is not in the substructure.

Note

The parent molecule is not modified by this operation.

4. erase_bond(self: nuri.core._core.Substructure, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> None

Remove a bond from the substructure. The source and destination atoms are interchangeable.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Raises:

ValueError – If the bond is not in the substructure or does not exist.

Note

The parent molecule is not modified by this operation.

get_conf(self: Substructure, conf: int = 0) → ndarray[numpy.float64]

Get the coordinates of the atoms in a conformation of the substructure.

Parameters:

conf – The index of the conformation to get the coordinates from.

Returns:

The coordinates of the atoms in the substructure, as a 2D array of shape (num_atoms, 3).

Note

The returned array is a copy of the coordinates. To update the coordinates, use the set_conf() method.

has_bond(*args, **kwargs)

Overloaded function.

1. has_bond(self: nuri.core._core.Substructure, src: nuri.core._core.SubAtom, dst: nuri.core._core.SubAtom) -> bool

Check if two atoms are connected by a bond.

Parameters:

• src – The source sub-atom of the bond.

• dst – The destination sub-atom of the bond.

Returns:

Whether the source and destination atoms are connected by a bond.

Raises:

ValueError – If any of the sub-atoms does not belong to the substructure.

2. has_bond(self: nuri.core._core.Substructure, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> bool

Check if two atoms are connected by a bond.

Parameters:

• src – The source atom of the bond.

• dst – The destination atom of the bond.

Returns:

Whether the source and destination atoms are connected by a bond.

Raises:

ValueError – If any of the atoms does not belong to the molecule.

neighbor(*args, **kwargs)

Overloaded function.

1. neighbor(self: nuri.core._core.Substructure, src: nuri.core._core.SubAtom, dst: nuri.core._core.SubAtom) -> nuri.core._core.SubNeighbor

Get a neighbor of the substructure.

Parameters:

• src – The source sub-atom of the neighbor.

• dst – The destination sub-atom of the neighbor.

Returns:

The neighbor from the source to the destination sub-atom.

Return type:

SubNeighbor

Raises:

ValueError – If the underlying bond does not exist, or any of the sub-atoms does not belong to the substructure.

See also

bond()

Note

Unlike bond(), the returned neighbor is always guaranteed to have nei.src.id == src.id and nei.dst.id == dst.id.

Note

The returned neighbor is invalidated when the parent molecule is modified, or if the substructure is modified.

2. neighbor(self: nuri.core._core.Substructure, src: nuri.core._core.Atom, dst: nuri.core._core.Atom) -> nuri.core._core.SubNeighbor

Get a neighbor of the substructure.

Parameters:

• src – The source atom of the neighbor.

• dst – The destination atom of the neighbor.

Returns:

The neighbor from the source to the destination atom.

Return type:

SubNeighbor

Raises:

ValueError – If the underlying bond does not exist, the source or destination atom does not belong to the substructure, or any of the atoms does not belong to the same molecule.

See also

bond()

Note

Unlike bond(), the returned neighbor is always guaranteed to have the source and destination atoms in the same order as the arguments.

Note

The returned neighbor is invalidated when the parent molecule is modified, or if the substructure is modified.

num_atoms(self: Substructure) → int

The number of atoms in the substructure. Equivalent to len(sub).

num_bonds(self: Substructure) → int

The number of bonds in the substructure. Equivalent to len(sub.bonds).

num_confs(self: Substructure) → int

Get the number of conformations of the substructure.

parent_atoms(self: Substructure) → list

The parent atom indices of the substructure atoms. The indices are guaranteed to be unique and in ascending order.

Return type:

list[int]

Note

The returned list is a copy of the internal list, so modifying the list does not affect the substructure.

parent_bonds(self: Substructure) → list

The parent bond indices of the substructure bonds. The indices are guaranteed to be unique and in ascending order.

Return type:

list[int]

Note

The returned list is a copy of the internal list, so modifying the list does not affect the substructure.

refresh_bonds(self: Substructure) → None

Refresh the bonds of the substructure. All bonds between the atoms of the substructure are removed, and new bonds are added based on the parent molecule.

set_conf(self: Substructure, coords: object, conf: int = 0) → None

Set the coordinates of the atoms in a conformation of the substructure.

Parameters:

• coords – The coordinates of the atoms in the conformation. Must be convertible to a numpy array of shape (num_atoms, 3).

• conf – The index of the conformation to set the coordinates to.

Note

The coordinates of the atoms that are not in the substructure are not affected.

property category

Type:

SubstructureCategory

The category of the substructure. This is used to categorize the substructure.

property id

Type:

int

An integral identifier of the substructure. The identifier is mostly for use in the protein residue numbering system.

Warning

This is not guaranteed to be unique within the molecule.

property molecule

Type:

Molecule

The parent molecule of the substructure.

property name

Type:

str

A name of the substructure. This is for user convenience and has no effect on the substructure’s behavior.

property props

Type:

MutableMapping[str, str]

A dictionary-like object to store additional properties of the substructure. The keys and values are both strings.

class nuri.core.ProxySubstructure

This represents a substructure managed by a molecule. If a user wishes to create a short-lived substructure not managed by a molecule, use Molecule.substructure() method instead.

This will invalidate when the parent molecule is modified, or any substructures are removed from the parent molecule. If the substructure must be kept alive, convert the substructure first with copy() method.

See also

Substructure

Here, we only provide the methods that are additional to the Substructure class.

copy(self: ProxySubstructure) → Substructure

Create a copy of the substructure. The returned substructure is not managed by the parent molecule.

class nuri.core.SubAtom

Atom of a substructure.

as_parent(self: SubAtom) → Atom

Returns the parent atom of this atom.

copy_data(self: SubAtom) → AtomData

Copy the underlying AtomData object.

Returns:

A copy of the underlying AtomData object.

get_isotope(self: SubAtom, explicit: bool = False) → Isotope

Get the isotope of the atom.

Parameters:

explicit – If True, returns the explicit isotope of the atom. Otherwise, returns the isotope of the atom. Defaults to False.

Returns:

The isotope of the atom. If the atom does not have an explicit isotope,

• If explicit is False, the representative isotope of the element is returned.

• If explicit is True, None is returned.

get_pos(self: SubAtom, conf: int = 0) → ndarray[numpy.float64]

Get the position of the atom.

Parameters:

conf – The index of the conformation to get the position from. Defaults to 0.

Returns:

The position of the atom.

Note

The position could not be directly set from Python. Use the set_pos() method to set the position.

set_element(*args, **kwargs)

Overloaded function.

1. set_element(self: nuri.core._core.SubAtom, atomic_number: int) -> nuri.core._core.SubAtom

Set the element of the atom.

Parameters:

atomic_number – The atomic number of the element to set.

See also

update()

2. set_element(self: nuri.core._core.SubAtom, symbol_or_name: str) -> nuri.core._core.SubAtom

Set the element of the atom.

Parameters:

symbol_or_name – The atomic symbol or name of the element to set.

Note

The symbol or name is case-insensitive. Symbol is tried first, and if it fails, name is tried.

3. set_element(self: nuri.core._core.SubAtom, element: nuri.core._core.Element) -> nuri.core._core.SubAtom

Set the element of the atom.

Parameters:

element – The element to set.

See also

update()

set_isotope(*args, **kwargs)

Overloaded function.

1. set_isotope(self: nuri.core._core.SubAtom, mass_number: int) -> nuri.core._core.SubAtom

Set the isotope of the atom.

Parameters:

mass_number – The mass number of the isotope to set.

2. set_isotope(self: nuri.core._core.SubAtom, isotope: nuri.core._core.Isotope) -> nuri.core._core.SubAtom

Set the isotope of the atom.

Parameters:

isotope – The isotope to set.

set_pos(self: SubAtom, pos: object, conf: int = 0) → None

Set the position of the atom.

Parameters:

• pos – The 3D vector to set the position to. Must be convertible to a numpy array of shape (3,).

• conf – The index of the conformation to set the position to. Defaults to 0.

update(self: SubAtom, *, hyb: Hyb | None = None, implicit_hydrogens: int | None = None, formal_charge: int | None = None, partial_charge: float | None = None, atomic_number: int | None = None, element: Element = None, aromatic: bool | None = None, conjugated: bool | None = None, ring: bool | None = None, chirality: Chirality | None = None, name: str | None = None) → SubAtom

Update the atom data. If any of the arguments are not given, the corresponding property is not updated.

Note

atomic_number and element are mutually exclusive. If both are given, an exception is raised.

Note

It is illegal to set the number of implicit hydrogens to a negative number.

update_from(*args, **kwargs)

Overloaded function.

1. update_from(self: nuri.core._core.SubAtom, atom: nuri.core._core.Atom) -> nuri.core._core.SubAtom

Update the atom data.

Parameters:

atom – The atom to copy the data from.

2. update_from(self: nuri.core._core.SubAtom, atom: nuri.core._core.ProxySubAtom) -> nuri.core._core.SubAtom

Update the atom data.

Parameters:

atom – The atom to copy the data from.

3. update_from(self: nuri.core._core.SubAtom, atom: nuri.core._core.SubAtom) -> nuri.core._core.SubAtom

Update the atom data.

Parameters:

atom – The atom to copy the data from.

4. update_from(self: nuri.core._core.SubAtom, data: nuri.core._core.AtomData) -> nuri.core._core.SubAtom

Update the atom data.

Parameters:

data – The atom data to update from.

property aromatic

Type:

bool

Whether the atom is aromatic.

See also

update()

property atomic_number

Type:

int

The atomic number of the atom.

See also

set_element(), update()

property atomic_weight

Type:

float

The atomic weight of the atom. Equivalent to data.element.atomic_weight.

property chirality

Type:

Chirality

Explicit chirality of the atom. Note that this does not imply the atom is a stereocenter chemically and might not correspond to the geometry of the molecule. See Chirality for formal definition.

Tip

Assigning None clears the explicit chirality.

See also

Chirality, update()

property conjugated

Type:

bool

Whether the atom is conjugated.

See also

update()

property element

Type:

Element

The element of the atom.

See also

set_element(), update()

property element_name

Type:

str

The IUPAC element name of the atom.

See also

set_element()

property element_symbol

Type:

str

The IUPAC element symbol of the atom.

See also

set_element()

property formal_charge

Type:

int

The formal charge of the atom.

See also

update()

property hyb

Type:

Hyb

The hybridization of the atom.

See also

update()

property id

Type:

int

A unique identifier of the atom in the substructure. The identifier is guaranteed to be unique within the atoms of the substructure.

This is a read-only property.

Warning

This is not the same as the parent atom’s identifier. Convert this to the parent atom using as_parent() if you need the parent atom’s identifier.

Note

Implementation detail: the identifier is the index of the atom in the substructure’s atom list.

property implicit_hydrogens

Type:

int

The number of implicit hydrogens of the atom. Guaranteed to be non-negative.

Note

It is illegal to set the number of implicit hydrogens to a negative number.

See also

update()

property name

Type:

str

The name of the atom. Returns an empty string if the name is not set.

See also

update()

property partial_charge

Type:

float

The partial charge of the atom.

See also

update()

property props

Type:

MutableMapping[str, str]

A dictionary-like object to store additional properties of the atom. The keys and values are both strings.

Note

The properties are shared with the underlying AtomData object. If the properties are modified, the underlying object is also modified.

As a result, the property map is also invalidated when any changes are made to the molecule. If the properties must be kept alive, copy the properties first with copy() method.

property ring

Type:

bool

Whether the atom is a ring atom.

Note

Beware updating this property when the atom is owned by a molecule. The molecule may not be aware of the change.

See also

update()

class nuri.core.SubBond

Bond of a substructure.

approx_order(self: SubBond) → float

The approximate bond order of the bond.

as_parent(self: SubBond) → Bond

Returns the parent bond of this bond.

copy_data(self: SubBond) → BondData

Copy the underlying BondData object.

Returns:

A copy of the underlying BondData object.

length(self: SubBond, conf: int = 0) → float

Calculate the length of the bond.

Parameters:

conf – The index of the conformation to calculate the length from. Defaults to 0.

Returns:

The length of the bond.

rotatable(self: SubBond) → bool

Whether the bond is rotatable.

Note

The result is calculated as the bond order is BondOrder.Single or BondOrder.Other, and the bond is not a conjugated or a ring bond.

sqlen(self: SubBond, conf: int = 0) → float

Calculate the square of the length of the bond.

Parameters:

conf – The index of the conformation to calculate the length from. Defaults to 0.

Returns:

The square of the length of the bond.

update(self: SubBond, *, order: BondOrder | None = None, aromatic: bool | None = None, conjugated: bool | None = None, ring: bool | None = None, config: BondConfig | None = None, name: str | None = None) → SubBond

Update the bond data. If any of the arguments are not given, the corresponding property is not updated.

update_from(*args, **kwargs)

Overloaded function.

1. update_from(self: nuri.core._core.SubBond, bond: nuri.core._core.Bond) -> nuri.core._core.SubBond

Update the bond data.

Parameters:

bond – The bond to copy the data from.

2. update_from(self: nuri.core._core.SubBond, bond: nuri.core._core.ProxySubBond) -> nuri.core._core.SubBond

Update the bond data.

Parameters:

bond – The bond to copy the data from.

3. update_from(self: nuri.core._core.SubBond, bond: nuri.core._core.SubBond) -> nuri.core._core.SubBond

Update the bond data.

Parameters:

bond – The bond to copy the data from.

4. update_from(self: nuri.core._core.SubBond, data: nuri.core._core.BondData) -> nuri.core._core.SubBond

Update the bond data.

Parameters:

data – The bond data to update from.

property aromatic

Type:

bool

Whether the bond is aromatic.

See also

update()

property config

Type:

BondConfig

The explicit configuration of the bond. Note that this does not imply the bond is a torsionally restricted bond chemically.

Note

For bonds with more than 3 neighboring atoms, BondConfig.Cis or BondConfig.Trans configurations are not well defined terms. In such cases, this will return whether the first neighbors are on the same side of the bond. For example, in the following structure (assuming the neighbors are ordered in the same way as the atoms), the bond between atoms 0 and 1 is considered to be in a cis configuration (first neighbors are marked with angle brackets):

<2>     <4>
  \     /
   0 = 1
  /     \
 3       5

On the other hand, when the neighbors are ordered in the opposite way, the bond between atoms 0 and 1 is considered to be in a trans configuration:

<2>      5
  \     /
   0 = 1
  /     \
 3      <4>

Tip

Assigning None clears the explicit bond configuration.

See also

update()

property conjugated

Type:

bool

Whether the atom is conjugated.

See also

update()

property dst

Type:

Atom

The destination atom of the bond.

property id

Type:

int

A unique identifier of the bond in the substructure. The identifier is guaranteed to be unique within the atoms of the substructure.

This is a read-only property.

Warning

This is not the same as the parent bond’s identifier. Convert this to the parent bond using as_parent() if you need the parent bond’s identifier.

Note

Implementation detail: the identifier is the index of the bond in the substructure’s bond list.

property name

Type:

str

The name of the bond. Returns an empty string if the name is not set.

See also

update()

property order

Type:

BondOrder

The bond order of the bond.

See also

update()

property props

Type:

MutableMapping[str, str]

A dictionary-like object to store additional properties of the bond. The keys and values are both strings.

Note

The properties are shared with the underlying BondData object. If the properties are modified, the underlying object is also modified.

As a result, the property map is invalidated when any changes are made to the molecule. If the properties must be kept alive, copy the properties first with copy() method.

property ring

Type:

bool

Whether the bond is a ring bond.

Note

Beware updating this property when the bond is owned by a molecule. The molecule may not be aware of the change.

See also

update()

property src

Type:

Atom

The source atom of the bond.

class nuri.core.SubNeighbor

Neighbor of a substructure.

as_parent(self: SubNeighbor) → Neighbor

Returns the parent version of this neighbor.

property bond

Bond between the source and destination atoms.

property dst

Destination atom of the neighbor.

property src

Source atom of the neighbor.

class nuri.core.AtomData

Data of an atom in a molecule. Refer to the nuri::AtomData class in the C++ API Reference for more details.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: nuri.core._core.AtomData) -> None

2. __init__(self: nuri.core._core.AtomData, atomic_number: int) -> None

3. __init__(self: nuri.core._core.AtomData, element: nuri.core._core.Element) -> None

copy(self: AtomData) → AtomData

Return a deep copy of self.

get_isotope(self: AtomData, explicit: bool = False) → Isotope

Get the isotope of the atom.

Parameters:

explicit – If True, returns the explicit isotope of the atom. Otherwise, returns the isotope of the atom. Defaults to False.

Returns:

The isotope of the atom. If the atom does not have an explicit isotope,

• If explicit is False, the representative isotope of the element is returned.

• If explicit is True, None is returned.

set_element(*args, **kwargs)

Overloaded function.

1. set_element(self: nuri.core._core.AtomData, atomic_number: int) -> nuri.core._core.AtomData

Set the element of the atom.

Parameters:

atomic_number – The atomic number of the element to set.

See also

update()

2. set_element(self: nuri.core._core.AtomData, symbol_or_name: str) -> nuri.core._core.AtomData

Set the element of the atom.

Parameters:

symbol_or_name – The atomic symbol or name of the element to set.

Note

The symbol or name is case-insensitive. Symbol is tried first, and if it fails, name is tried.

3. set_element(self: nuri.core._core.AtomData, element: nuri.core._core.Element) -> nuri.core._core.AtomData

Set the element of the atom.

Parameters:

element – The element to set.

See also

update()

set_isotope(*args, **kwargs)

Overloaded function.

1. set_isotope(self: nuri.core._core.AtomData, mass_number: int) -> nuri.core._core.AtomData

Set the isotope of the atom.

Parameters:

mass_number – The mass number of the isotope to set.

2. set_isotope(self: nuri.core._core.AtomData, isotope: nuri.core._core.Isotope) -> nuri.core._core.AtomData

Set the isotope of the atom.

Parameters:

isotope – The isotope to set.

update(self: AtomData, *, hyb: Hyb | None = None, implicit_hydrogens: int | None = None, formal_charge: int | None = None, partial_charge: float | None = None, atomic_number: int | None = None, element: Element = None, aromatic: bool | None = None, conjugated: bool | None = None, ring: bool | None = None, chirality: Chirality | None = None, name: str | None = None) → AtomData

Update the atom data. If any of the arguments are not given, the corresponding property is not updated.

Note

atomic_number and element are mutually exclusive. If both are given, an exception is raised.

Note

It is illegal to set the number of implicit hydrogens to a negative number.

update_from(*args, **kwargs)

Overloaded function.

1. update_from(self: nuri.core._core.AtomData, atom: nuri.core._core.Atom) -> nuri.core._core.AtomData

Update the atom data.

Parameters:

atom – The atom to copy the data from.

2. update_from(self: nuri.core._core.AtomData, atom: nuri.core._core.ProxySubAtom) -> nuri.core._core.AtomData

Update the atom data.

Parameters:

atom – The atom to copy the data from.

3. update_from(self: nuri.core._core.AtomData, atom: nuri.core._core.SubAtom) -> nuri.core._core.AtomData

Update the atom data.

Parameters:

atom – The atom to copy the data from.

4. update_from(self: nuri.core._core.AtomData, data: nuri.core._core.AtomData) -> nuri.core._core.AtomData

Update the atom data.

Parameters:

data – The atom data to update from.

property aromatic

Type:

bool

Whether the atom is aromatic.

See also

update()

property atomic_number

Type:

int

The atomic number of the atom.

See also

set_element(), update()

property atomic_weight

Type:

float

The atomic weight of the atom. Equivalent to data.element.atomic_weight.

property chirality

Type:

Chirality

Explicit chirality of the atom. Note that this does not imply the atom is a stereocenter chemically and might not correspond to the geometry of the molecule. See Chirality for formal definition.

Tip

Assigning None clears the explicit chirality.

See also

Chirality, update()

property conjugated

Type:

bool

Whether the atom is conjugated.

See also

update()

property element

Type:

Element

The element of the atom.

See also

set_element(), update()

property element_name

Type:

str

The IUPAC element name of the atom.

See also

set_element()

property element_symbol

Type:

str

The IUPAC element symbol of the atom.

See also

set_element()

property formal_charge

Type:

int

The formal charge of the atom.

See also

update()

property hyb

Type:

Hyb

The hybridization of the atom.

See also

update()

property implicit_hydrogens

Type:

int

The number of implicit hydrogens of the atom. Guaranteed to be non-negative.

Note

It is illegal to set the number of implicit hydrogens to a negative number.

See also

update()

property name

Type:

str

The name of the atom. Returns an empty string if the name is not set.

See also

update()

property partial_charge

Type:

float

The partial charge of the atom.

See also

update()

property props

Type:

MutableMapping[str, str]

A dictionary-like object to store additional properties of the atom. The keys and values are both strings.

property ring

Type:

bool

Whether the atom is a ring atom.

Note

Beware updating this property when the atom is owned by a molecule. The molecule may not be aware of the change.

See also

update()

class nuri.core.BondData

Data of a bond in a molecule. Refer to the nuri::BondData class in the C++ API Reference for more details.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: nuri.core._core.BondData) -> None

2. __init__(self: nuri.core._core.BondData, order: nuri.core._core.BondOrder) -> None

Create a bond data with the given bond order.

Parameters:

order (BondOrder|int) – The bond order of the bond.

approx_order(self: BondData) → float

The approximate bond order of the bond.

copy(self: BondData) → BondData

Return a deep copy of self.

rotatable(self: BondData) → bool

Whether the bond is rotatable.

Note

The result is calculated as the bond order is BondOrder.Single or BondOrder.Other, and the bond is not a conjugated or a ring bond.

update(self: BondData, *, order: BondOrder | None = None, aromatic: bool | None = None, conjugated: bool | None = None, ring: bool | None = None, config: BondConfig | None = None, name: str | None = None) → BondData

Update the bond data. If any of the arguments are not given, the corresponding property is not updated.

update_from(*args, **kwargs)

Overloaded function.

1. update_from(self: nuri.core._core.BondData, bond: nuri.core._core.Bond) -> nuri.core._core.BondData

Update the bond data.

Parameters:

bond – The bond to copy the data from.

2. update_from(self: nuri.core._core.BondData, bond: nuri.core._core.ProxySubBond) -> nuri.core._core.BondData

Update the bond data.

Parameters:

bond – The bond to copy the data from.

3. update_from(self: nuri.core._core.BondData, bond: nuri.core._core.SubBond) -> nuri.core._core.BondData

Update the bond data.

Parameters:

bond – The bond to copy the data from.

4. update_from(self: nuri.core._core.BondData, data: nuri.core._core.BondData) -> nuri.core._core.BondData

Update the bond data.

Parameters:

data – The bond data to update from.

property aromatic

Type:

bool

Whether the bond is aromatic.

See also

update()

property config

Type:

BondConfig

The explicit configuration of the bond. Note that this does not imply the bond is a torsionally restricted bond chemically.

Note

For bonds with more than 3 neighboring atoms, BondConfig.Cis or BondConfig.Trans configurations are not well defined terms. In such cases, this will return whether the first neighbors are on the same side of the bond. For example, in the following structure (assuming the neighbors are ordered in the same way as the atoms), the bond between atoms 0 and 1 is considered to be in a cis configuration (first neighbors are marked with angle brackets):

<2>     <4>
  \     /
   0 = 1
  /     \
 3       5

On the other hand, when the neighbors are ordered in the opposite way, the bond between atoms 0 and 1 is considered to be in a trans configuration:

<2>      5
  \     /
   0 = 1
  /     \
 3      <4>

Tip

Assigning None clears the explicit bond configuration.

See also

update()

property conjugated

Type:

bool

Whether the atom is conjugated.

See also

update()

property name

Type:

str

The name of the bond. Returns an empty string if the name is not set.

See also

update()

property order

Type:

BondOrder

The bond order of the bond.

See also

update()

property props

Type:

MutableMapping[str, str]

A dictionary-like object to store additional properties of the bond. The keys and values are both strings.

property ring

Type:

bool

Whether the bond is a ring bond.

Note

Beware updating this property when the bond is owned by a molecule. The molecule may not be aware of the change.

See also

update()

class nuri.core.BondConfig

Members:

Unknown

Trans

Cis

Cis = <BondConfig.Cis: 1>

Trans = <BondConfig.Trans: 2>

Unknown = <BondConfig.Unknown: 0>

property name

property value

class nuri.core.BondOrder

Members:

Other

Single

Double

Triple

Quadruple

Aromatic

Aromatic = <BondOrder.Aromatic: 5>

Double = <BondOrder.Double: 2>

Other = <BondOrder.Other: 0>

Quadruple = <BondOrder.Quadruple: 4>

Single = <BondOrder.Single: 1>

Triple = <BondOrder.Triple: 3>

property name

property value

class nuri.core.Chirality

Chirality of an atom.

When viewed from the first neighboring atom of a “chiral” atom, the chirality is determined by the spatial arrangement of the remaining neighbors. That is, when the remaining neighbors are arranged in a clockwise direction, the chirality is “clockwise” (CW), and when they are arranged in a counter-clockwise direction, the chirality is “counter-clockwise” (CCW). If the atom is not a stereocenter or the chirality is unspecified, the chirality is “unknown” (Unknown).

If the atom has an implicit hydrogen, it will be always placed at the end of the neighbor list. This is to ensure that the chirality of the atom is not affected by adding back the implicit hydrogen (which will be placed at the end).

Note

It is worth noting that this chirality definition (“NuriKit Chirality”) is not strictly equivalent to the chirality definition in SMILES (“SMILES Chirality”), although it appears to be similar and often resolves to the same chirality.

One notable difference is that most SMILES parser implementations place the implicit hydrogen where it appears in the SMILES string. [1] For example, consider the stereocenter in the following SMILES string:

[C@@H](F)(Cl)Br

The SMILES Chirality of the atom is “clockwise” because the implicit hydrogen is interpreted as the first neighbor. On the other hand, the NuriKit Chirality of the atom is “counter-clockwise” because the implicit hydrogen is interpreted as the last neighbor.

This is not a problem in most cases, because when the stereocenter is not the first atom of a fragment, the SMILES Chirality and the NuriKit Chirality are consistent. For example, a slightly modified SMILES string of the above example will result in a “counter-clockwise” configuration in both definitions:

F[C@H](Cl)Br

Another neighbor ordering inconsistency might occur when ring closure is involved. This is because a ring-closing bond addition could only be done after the partner atom is added, but the SMILES Chirality is resolved in the order of the appearance of the bonds in the SMILES string. For example, consider the following SMILES string, in which the two stereocenters are both “clockwise” in terms of the SMILES Chirality (atoms are numbered for reference):

1 2  3  4 5     6 7
C[C@@H]1C[C@@]1(F)C

The NuriKit Chirality of atom 2 is “counter-clockwise” because the order of the neighbors is 1, 3, 5, 4 in the SMILES Chirality (atom 5 precedes atom 4 because the ring-closing bond between atoms 2 and 5 appears before the bond between atoms 2 and 4), but 1, 3, 4, 5 in the NuriKit Chirality (atom 4 precedes atom 5 because the ring-closing bond is added after the bond between atoms 2 and 4).

On the other hand, the NuriKit Chirality of atom 5 is “clockwise” because the order of the neighbors is 4, 2, 6, 7 in both definitions. Unlike the other stereocenter, the partner of the ring-closing bond (atom 2) is already added, and the ring-closing bond can now be added where it appears in the SMILES string.

Footnotes

[1]

Note that this behavior of the implementations is not strictly conforming to the OpenSMILES specification, which states that the implicit hydrogen should be considered to be the first atom in the clockwise or anticlockwise accounting.

Members:

Unknown

CW

CCW

CCW = <Chirality.CCW: 2>

CW = <Chirality.CW: 1>

Unknown = <Chirality.Unknown: 0>

property name

property value

class nuri.core.Element

An element.

All instances of this class are immutable and singleton. If you want to compare two instances, just use the is operator. You can also compare two elements using the comparison operators, which in turn compares their atomic_number (added for convenience).

>>> from nuri import periodic_table
>>> periodic_table["H"] < periodic_table["He"]
True

Refer to the nuri::Element class in the C++ API Reference for more details.

get_isotope(self: Element, mass_number: int) → Isotope

Get an isotope of this element by mass number.

Parameters:

mass_number – The mass number of the isotope.

Raises:

ValueError – If no such isotope exists.

property atomic_number

Type:

int

property atomic_weight

Type:

float

property covalent_radius

Type:

float

property eneg

Type:

float

property group

Type:

int

property isotopes

Type:

Sequence[Isotope]

property major_isotope

Type:

Isotope

property name

Type:

str

property period

Type:

int

property symbol

Type:

str

property vdw_radius

Type:

float

class nuri.core.Hyb

Members:

Unbound

Terminal

SP

SP2

SP3

SP3D

SP3D2

Other

Other = <Hyb.Other: 7>

SP = <Hyb.SP: 2>

SP2 = <Hyb.SP2: 3>

SP3 = <Hyb.SP3: 4>

SP3D = <Hyb.SP3D: 5>

SP3D2 = <Hyb.SP3D2: 6>

Terminal = <Hyb.Terminal: 1>

Unbound = <Hyb.Unbound: 0>

property name

property value

class nuri.core.Isotope

An isotope of an element.

All instances of this class are immutable and singleton. If you want to compare two instances, just use the is operator. You can also compare two elements using the comparison operators, which in turn compares their mass_number (added for convenience).

Refer to the nuri::Element class in the C++ API Reference for more details.

property abundance

Type:

float

property atomic_weight

Type:

float

property element

Type:

Element

The element of this isotope.

property mass_number

Type:

int

class nuri.core.PeriodicTable

The periodic table of elements.

The periodic table is a singleton object. You can access the periodic table via the nuri.periodic_table attribute, or the factory static method PeriodicTable.get(). Both of them refer to the same object. Note that PeriodicTable object is not constructible from the Python side.

You can access the periodic table as a dictionary-like object. The keys are atomic numbers, atomic symbols, and atomic names, tried in this order. The returned values are Element objects. For example:

>>> from nuri import periodic_table
>>> periodic_table[1]
<Element H>
>>> periodic_table["H"]
<Element H>
>>> periodic_table["Hydrogen"]
<Element H>

The symbols and names are case insensitive. If no such element exists, a KeyError is raised.

>>> periodic_table[1000]
Traceback (most recent call last):
  ...
KeyError: '1000'

You can also test for the existence of an element using the in operator.

>>> 1 in periodic_table
True
>>> "H" in periodic_table
True
>>> "Hydrogen" in periodic_table
True
>>> 1000 in periodic_table
False

The periodic table itself is an iterable object. You can iterate over the elements in the periodic table.

>>> for elem in periodic_table:
...     print(elem)
...
<Element Xx>
<Element H>
...
<Element Og>

Refer to the nuri::PeriodicTable class in the C++ API Reference for details.

static get() → PeriodicTable

Get the singleton PeriodicTable object (same as nuri.periodic_table).

class nuri.core.SubstructureCategory

The category of a substructure.

This is used to categorize the substructure. Mainly used for the proteins.

Members:

Unknown

Residue

Chain

Chain = <SubstructureCategory.Chain: 2>

Residue = <SubstructureCategory.Residue: 1>

Unknown = <SubstructureCategory.Unknown: 0>

property name

property value

class nuri.core.SubstructureContainer

A collection of substructures of a molecule.

add(*args, **kwargs)

Overloaded function.

1. add(self: nuri.core._core.SubstructureContainer, atoms: Optional[Iterable[Union[nuri.core._core.Atom, int]]] = None, bonds: Optional[Iterable[Union[nuri.core._core.Bond, int]]] = None, cat: nuri.core._core.SubstructureCategory = <SubstructureCategory.Unknown: 0>) -> nuri.core._core.ProxySubstructure

Add a substructure to the collection and return it.

Parameters:

• atoms (Iterable[Atom]) – The atoms to include in the substructure.

• bonds (Iterable[Bond]) – The bonds to include in the substructure.

• cat – The category of the substructure.

Returns:

The newly added substructure.

This has three mode of operations:

1. If both atoms and bonds are given, a substructure is created with the given atoms and bonds. The atoms connected by the bonds will also be added to the substructure, even if they are not in the atoms list.

2. If only atoms are given, a substructure is created with the given atoms. All bonds between the atoms will also be added to the substructure.

3. If only bonds are given, a substructure is created with the given bonds. The atoms connected by the bonds will also be added to the substructure.

4. If neither atoms nor bonds are given, an empty substructure is created.

Tip

Pass empty list to bonds to create an atoms-only substructure.

2. add(self: nuri.core._core.SubstructureContainer, idx: int, atoms: Optional[Iterable[Union[nuri.core._core.Atom, int]]] = None, bonds: Optional[Iterable[Union[nuri.core._core.Bond, int]]] = None, cat: nuri.core._core.SubstructureCategory = <SubstructureCategory.Unknown: 0>) -> nuri.core._core.ProxySubstructure

Add a substructure to the collection at the given index and return it. Effectively invalidates all currently existing substructures.

Parameters:

• idx – The index of the new substructure. If negative, counts from back to front (i.e., the new substructure will be created at max(0, len(subs) + idx)). Otherwise, the substructure is added at min(idx, len(subs)). This resembles the behavior of Python’s list.insert() method.

• atoms (Iterable[Atom]) – The atoms to include in the substructure.

• bonds (Iterable[Bond]) – The bonds to include in the substructure.

• cat – The category of the substructure.

Returns:

The newly added substructure.

This has three mode of operations:

1. If both atoms and bonds are given, a substructure is created with the given atoms and bonds. The atoms connected by the bonds will also be added to the substructure, even if they are not in the atoms list.

2. If only atoms are given, a substructure is created with the given atoms. All bonds between the atoms will also be added to the substructure.

3. If only bonds are given, a substructure is created with the given bonds. The atoms connected by the bonds will also be added to the substructure.

4. If neither atoms nor bonds are given, an empty substructure is created.

Tip

Pass empty list to bonds to create an atoms-only substructure.

append(*args, **kwargs)

Overloaded function.

1. append(self: nuri.core._core.SubstructureContainer, other: nuri.core._core.Substructure) -> None

Add a substructure to the collection.

Parameters:

other (Substructure) – The substructure to add.

Note

The given substructure is copied to the collection.

2. append(self: nuri.core._core.SubstructureContainer, other: nuri.core._core.ProxySubstructure) -> None

Add a substructure to the collection.

Parameters:

other (ProxySubstructure) – The substructure to add.

Note

The given substructure is copied to the collection.

clear(self: SubstructureContainer) → None

Remove all substructures from the collection. Effectively invalidates all currently existing substructures.

insert(*args, **kwargs)

Overloaded function.

1. insert(self: nuri.core._core.SubstructureContainer, idx: int, other: nuri.core._core.Substructure) -> None

Add a substructure to the collection at the given index. Effectively invalidates all currently existing substructures.

Parameters:

• idx – The index of the new substructure. If negative, counts from back to front (i.e., the new substructure will be created at max(0, len(subs) + idx)). Otherwise, the substructure is added at min(idx, len(subs)). This resembles the behavior of Python’s list.insert() method.

• other (Substructure) – The substructure to add.

Note

The given substructure is copied to the collection, so modifying the given substructure does not affect the collection.

2. insert(self: nuri.core._core.SubstructureContainer, idx: int, other: nuri.core._core.ProxySubstructure) -> None

Add a substructure to the collection at the given index. Effectively invalidates all currently existing substructures.

Parameters:

• idx – The index of the new substructure. If negative, counts from back to front (i.e., the new substructure will be created at max(0, len(subs) + idx)). Otherwise, the substructure is added at min(idx, len(subs)). This resembles the behavior of Python’s list.insert() method.

• other (ProxySubstructure) – The substructure to add.

Note

The given substructure is copied to the collection, so modifying the given substructure does not affect the collection.

pop(self: SubstructureContainer, idx: int | None = None) → Substructure

Remove a substructure from the collection and return it.

Parameters:

idx – The index of the substructure to remove. If not given, removes the last substructure.

Geometry Utilities

from nuri.core import geometry as ngeo

nuri.core.geometry.align_points(query: object, template: object, method: str = 'qcp', reflection: bool = False) → tuple[ndarray[numpy.float64], float]

Find a 4x4 best-fit rigid-body transformation tensor, to align query to template.

Parameters:

• query – The query points. Must be representable as a 2D numpy array of shape (N, 3).

• template – The template points. Must be representable as a 2D numpy array of shape (N, 3).

• method –

  The alignment method to use. Defaults to "qcp". Currently supported methods are:

  • "qcp": The Quaternion Characteristic Polynomial (QCP) method, based on the implementation of Liu and Theobald [2][3][4]. Unlike the original implementation, this version can also handle reflection based on the observations of Coutsias, Seok, and Dill[5].

  • "kabsch": The Kabsch algorithm. [6][7] This implementation is based on the implementation in TM-align. [8]

• reflection – Whether to allow reflection in the alignment. Defaults to False.

Returns:

A tuple of the transformation tensor and the RMSD of the alignment.

nuri.core.geometry.align_rmsd(query: object, template: object, method: str = 'qcp', reflection: bool = False) → float

Calculate the RMSD of the best-fit rigid-body alignment of query to template.

Parameters:

• query – The query points. Must be representable as a 2D numpy array of shape (N, 3).

• template – The template points. Must be representable as a 2D numpy array of shape (N, 3).

• method –

  The alignment method to use. Defaults to "qcp". Currently supported methods are:

  • "qcp": The Quaternion Characteristic Polynomial (QCP) method, based on the implementation of Liu and Theobald [2][3][4]. Unlike the original implementation, this version can also handle reflection based on the observations of Coutsias, Seok, and Dill[5].

  • "kabsch": The Kabsch algorithm. [6][7] This implementation is based on the implementation in TM-align. [8]

• reflection – Whether to allow reflection in the alignment. Defaults to False.

Returns:

The RMSD of the alignment.

nuri.core.geometry.transform(tensor: object, pts: object) → ndarray[numpy.float64]

Transform a set of points using a 4x4 transformation tensor.

Effectively, this function is roughly equivalent to the following Python code:

def transform(tensor, pts):
    rotated = tensor[:3, :3] @ pts.T
    translated = rotated + tensor[:3, 3, None]
    return translated.T

Parameters:

• tensor – The transformation tensor. Must be representable as a 2D numpy array of shape (4, 4).

• pts – The points to transform. Must be representable as a 2D numpy array of shape (N, 3).

Returns:

The transformed points.

Warning:

This function does not check if the transformation tensor is a valid affine transformation matrix.

[2] (1,2)

Douglas L. Theobald. Rapid calculation of RMSDs using a quaternion-based characteristic polynomial. Acta Crystallographica Section A, 61(4):478–480, Jul 2005. doi:10.1107/S0108767305015266.

[3] (1,2)

Pu Liu, Dimitris K. Agrafiotis, and Douglas L. Theobald. Fast determination of the optimal rotational matrix for macromolecular superpositions. Journal of Computational Chemistry, 31(7):1561–1563, 2010. doi:10.1002/jcc.21439.

[4] (1,2)

Gerald R. Kneller. Comment on “fast determination of the optimal rotational matrix for macromolecular superpositions” [j. comp. chem. 31, 1561 (2010)]. Journal of Computational Chemistry, 32(1):183–184, 2011. doi:10.1002/jcc.21607.

[5] (1,2)

Evangelos A. Coutsias, Chaok Seok, and Ken A. Dill. Using quaternions to calculate rmsd. Journal of Computational Chemistry, 25(15):1849–1857, 2004. doi:10.1002/jcc.20110.

[6] (1,2)

W. Kabsch. A solution for the best rotation to relate two sets of vectors. Acta Crystallographica Section A, 32(5):922–923, Sep 1976. doi:10.1107/S0567739476001873.

[7] (1,2)

W. Kabsch. A discussion of the solution for the best rotation to relate two sets of vectors. Acta Crystallographica Section A, 34(5):827–828, Sep 1978. doi:10.1107/S0567739478001680.

[8] (1,2)

Yang Zhang and Jeffrey Skolnick. TM-align: a protein structure alignment algorithm based on the TM-score. Nucleic Acids Research, 33(7):2302–2309, 01 2005. doi:10.1093/nar/gki524.