apocharmm.atom_reference.AtomReference Class Reference

Owns one topology-aware zero-based atom identity. More...

Inherits _ApoObject.

Public Member Functions
None	__init__ (self, CharmmPsf psf, int atom_index)
	Constructs a reference to one atom in one PSF.
int	getAtomIndex (self)
	Returns the stored zero-based atom index.
bool	hasSameTopology (self, "AtomReference" other)
	Tests native PSF object identity.
bool	__eq__ (self, object other)
	Tests topology identity and atom-index equality.

Protected Member Functions
"AtomReference"	_from_handle (cls, ctypes.c_void_p handle)
	Adopts one newly owned non-NULL C atom-reference handle.

Detailed Description

Owns one topology-aware zero-based atom identity.

The native object retains shared const ownership of its source PSF and one validated atom index. This Python wrapper owns only the returned C handle; it deliberately does not retain the source CharmmPsf Python wrapper.

Two references have the same topology only when their native PSF shared owners point to the same native CharmmPSF object. Equality additionally requires equal atom indices. Parsing the same PSF file into two independent CharmmPsf objects therefore produces different topologies.

close(), destroy(), context-manager exit, or finalization releases the handle and is idempotent. Methods on a closed reference raise RuntimeError. References are equality-comparable but unordered and unhashable. Construction and queries are host-only and have no coordinate, CUDA, stream, or synchronization state.

See also

atom_selection

Constructor & Destructor Documentation

__init__()

None apocharmm.atom_reference.AtomReference.__init__	(		self,
		CharmmPsf	psf,
		int	atom_index
	)

Constructs a reference to one atom in one PSF.

Parameters

[in]	psf	Live CharmmPsf instance. The Python object is borrowed only during construction; native shared PSF ownership is copied into the new reference.
[in]	atom_index	Zero-based atom index representable by signed C int.

Exceptions

TypeError	If psf is not a CharmmPsf, if atom_index is not an int, or if atom_index is bool.
ValueError	If atom_index does not fit signed C int.
RuntimeError	If psf has been closed or if the C ABI reports success but returns a NULL handle.
ApoCharmmError	With native status APO_STATUS_NOT_INITIALIZED when the PSF atom count is negative, APO_STATUS_INVALID_ARGUMENT when the native PSF handle or atom index is invalid, or APO_STATUS_RUNTIME_ERROR for allocation or another translated native failure.

Postcondition

On success, this wrapper owns one atom-reference handle and does not retain psf as a Python object.

Member Function Documentation

__eq__()

bool apocharmm.atom_reference.AtomReference.__eq__	(		self,
		object	other
	)

Tests topology identity and atom-index equality.

Parameters

[in]

other

Object to compare.

Returns

True only for another live AtomReference with the same native PSF object and index. Returns NotImplemented for unrelated Python types so Python can apply normal reflected-comparison behavior.

Exceptions

RuntimeError	If either compared AtomReference has been closed.
ApoCharmmError	If either native handle is invalid or another native failure is translated.

_from_handle()

"AtomReference" apocharmm.atom_reference.AtomReference._from_handle (   cls, ctypes.c_void_p  handle  )

protected

Adopts one newly owned non-NULL C atom-reference handle.

This factory is for wrappers such as AtomSelector.selectAtom() that already own a newly created C handle. It does not repeat PSF or index construction.

Parameters

[in]

handle

Newly owned ctypes.c_void_p handle.

Returns

A new wrapper that adopts handle without retaining another Python object.

Exceptions

TypeError	If handle is not a ctypes.c_void_p.
RuntimeError	If handle is NULL.

getAtomIndex()

int apocharmm.atom_reference.AtomReference.getAtomIndex

(

self

)

Returns the stored zero-based atom index.

Returns

The dimensionless zero-based index supplied at construction or selected by AtomSelector.selectAtom().

Exceptions

RuntimeError	If this reference has been closed.
ApoCharmmError	If the native handle is invalid or another native failure is translated.

hasSameTopology()

bool apocharmm.atom_reference.AtomReference.hasSameTopology	(		self,
		"AtomReference"	other
	)

Tests native PSF object identity.

Parameters

[in]

other

Live AtomReference to compare.

Returns

True only when both references retain the same native CharmmPSF object.

Exceptions

TypeError	If other is not an AtomReference.
RuntimeError	If either reference has been closed.
ApoCharmmError	If either native handle is invalid or another native failure is translated.