proteindf_bridge.atom module

class proteindf_bridge.atom.Atom(*args, **kwargs)

Bases: object

Represents an atom in a molecular structure.

Encapsulates atomic properties such as atomic number, element symbol, atom name, label, partial charge, hierarchical path, 3D coordinates, and forces.

Parameters:

  • *args – At most 1 positional argument. - If an Atom: Clones the properties of the given atom. - If a str: Element symbol (e.g., “C”, “Fe”). - If an int: Atomic number (Z). - If a dict: Dictionary with keys “Z”, “name”, “Q”, “xyz”, “force”.

  • **kwargs – Keyword arguments for atom properties: - symbol (str): Element symbol. - name (str): Atom name. - label (str): Atom label. - charge (float): Partial atomic charge. - path (str): Hierarchical path. - position or xyz (Position, sequence of floats, or str): 3D coordinates. - force (Position, sequence of floats, or str): Force vector.

Raises:

  • TypeError – If positional arguments exceed 1 or argument types are invalid.

  • BrValueError – If the element symbol is unknown.

  • BrInputError – If coordinate parsing fails from a string or slice.

atomic_number

The atomic number (Z) of the atom.

charge

The partial atomic charge.

force

The force vector acting on the atom as a Position object.

get_raw_data()

Returns the atom properties as a dictionary.

Returns:

A dictionary with keys ‘Z’, ‘name’, ‘Q’, ‘xyz’, and ‘force’.

is_real

True if the atom represents a real element (atomic number > 0), False otherwise.

label

The atom label.

move_to(pos)

Moves the atom to the specified position in-place.

Parameters:

pos – The target position as a Position, a sequence of 3 floats, or a coordinate string.

Returns:

The Atom object itself (self).

Raises:
name

The atom name (e.g., ‘CA’, ‘CB’).

path

The hierarchical path of the atom in the structure tree.

position

Alias for xyz. The 3D coordinates of the atom as a Position object.

rotate(rotmat)

Rotates the atom coordinates in-place using a 3x3 rotation matrix.

Parameters:

rotmat – A 3x3 rotation matrix (Matrix or an object with rows, cols, and get(row, col)).

Raises:

  • TypeError – If rotmat is not a Matrix or an object with rows, cols, and get(row, col).

  • ValueError – If matrix dimensions are not 3x3.

set_by_raw_data(data)

Updates the atom properties from a dictionary in-place.

Parameters:

data – A dictionary containing atom attributes (‘Z’, ‘name’, ‘Q’, ‘xyz’, ‘force’).

Raises:

  • TypeError – If values in the dictionary cannot be converted to expected types.

  • BrInputError – If position or force coordinates cannot be parsed.

shift_by(dir)

Translates the atom coordinates by a displacement vector in-place.

Parameters:

dir – The displacement vector as a Position, a sequence of 3 floats, or a coordinate string.

Returns:

The Atom object itself (self).

Raises:
symbol

The chemical element symbol (e.g., ‘C’, ‘N’, ‘O’).

vdw

The van der Waals radius of the atom in Angstroms.

weight()

Returns the standard atomic weight of the element.

Returns:

The atomic weight in unified atomic mass units (Da) as a float, or 0.0 for dummy atoms.

Raises:

BrValueError – If the atomic number has no standard atomic weight (Z > 118).

xyz

The 3D coordinates of the atom as a Position object.