Owns CHARMM PSF topology, per-atom metadata, and derived topology tables. More...

#include <CharmmPSF.h>

Public Member Functions
	CharmmPSF (void)
	Constructs an uninitialized, empty PSF object.

	CharmmPSF (const std::filesystem::path &filePath)
	Constructs and derives topology from a CHARMM PSF file.

	CharmmPSF (const CharmmPSF &other)
	Constructs an independent deep copy of another PSF object.

	CharmmPSF (const CharmmPSF &&other)
	Constructs an independent copy from a const rvalue.

void	setNumAtoms (const int numAtoms)
	Sets the atom count and resizes the seven per-atom host arrays.

void	setAtomCharges (const std::vector< double > &charges)
	Replaces all per-atom partial charges.

int	getNumAtoms (void) const
	Returns the stored atom count.

int	getNumBonds (void) const
	Returns the stored bond count.

int	getNumAngles (void) const
	Returns the stored angle count.

int	getNumDihedrals (void) const
	Returns the stored proper-dihedral count.

int	getNumImpropers (void) const
	Returns the stored improper-dihedral count.

int	getNumCrossTerms (void) const
	Returns the stored cross-term count.

const std::vector< std::string > &	getSegmentIdentifiers (void) const
	Returns the per-atom segment identifiers.

const std::vector< int > &	getResidueIdentifiers (void) const
	Returns the per-atom residue identifiers.

const std::vector< std::string > &	getResidueNames (void) const
	Returns the per-atom residue names.

const std::vector< std::string > &	getAtomNames (void) const
	Returns the per-atom atom names.

const std::vector< std::string > &	getAtomTypes (void) const
	Returns the per-atom CHARMM atom types.

const std::vector< double > &	getCharges (void) const
	Returns the per-atom partial charges.

const std::vector< double > &	getMasses (void) const
	Returns the per-atom masses.

const std::vector< Bond > &	getBonds (void) const
	Returns the parsed covalent bonds.

const std::vector< Angle > &	getAngles (void) const
	Returns the parsed valence angles.

const std::vector< Dihedral > &	getDihedrals (void) const
	Returns the parsed proper dihedrals.

const std::vector< Dihedral > &	getImpropers (void) const
	Returns the parsed improper dihedrals.

const std::vector< CrossTerm > &	getCrossTerms (void) const
	Returns the parsed CMAP cross-term records.

const std::vector< std::set< int > > &	getConnected12 (void) const
	Returns the per-atom direct-bond connectivity sets.

const std::vector< std::set< int > > &	getConnected13 (void) const
	Returns the per-atom two-bond connectivity sets.

const std::vector< std::set< int > > &	getConnected14 (void) const
	Returns the per-atom three-bond connectivity sets.

const std::vector< int > &	getIblo14 (void) const
	Returns the cumulative CHARMM exclusion offsets.

const std::vector< int > &	getInb14 (void) const
	Returns the flattened CHARMM exclusion atom numbers.

const CudaContainer< int4 > &	getWaterMolecules (void) const
	Returns recognized three-site water tuples.

const CudaContainer< int2 > &	getResidues (void) const
	Returns contiguous residue intervals.

const CudaContainer< int2 > &	getGroups (void) const
	Returns contiguous connected-component intervals.

const std::filesystem::path &	getFilePath (void) const
	Returns the path supplied to the file constructor.

std::vector< std::string > &	getSegmentIdentifiers (void)
	Returns unchecked mutable access to segment identifiers.

std::vector< int > &	getResidueIdentifiers (void)
	Returns unchecked mutable access to residue identifiers.

std::vector< std::string > &	getResidueNames (void)
	Returns unchecked mutable access to residue names.

std::vector< std::string > &	getAtomNames (void)
	Returns unchecked mutable access to atom names.

std::vector< std::string > &	getAtomTypes (void)
	Returns unchecked mutable access to atom types.

std::vector< double > &	getCharges (void)
	Returns unchecked mutable access to per-atom charges.

std::vector< double > &	getMasses (void)
	Returns unchecked mutable access to per-atom masses.

std::vector< Bond > &	getBonds (void)
	Returns unchecked mutable access to bond records.

std::vector< Angle > &	getAngles (void)
	Returns unchecked mutable access to angle records.

std::vector< Dihedral > &	getDihedrals (void)
	Returns unchecked mutable access to proper-dihedral records.

std::vector< Dihedral > &	getImpropers (void)
	Returns unchecked mutable access to improper-dihedral records.

std::vector< CrossTerm > &	getCrossTerms (void)
	Returns unchecked mutable access to cross-term records.

std::vector< std::set< int > > &	getConnected12 (void)
	Returns unchecked mutable access to direct-bond connectivity.

std::vector< std::set< int > > &	getConnected13 (void)
	Returns unchecked mutable access to two-bond connectivity.

std::vector< std::set< int > > &	getConnected14 (void)
	Returns unchecked mutable access to three-bond connectivity.

std::vector< int > &	getIblo14 (void)
	Returns unchecked mutable access to cumulative exclusion offsets.

std::vector< int > &	getInb14 (void)
	Returns unchecked mutable access to flattened exclusion atom numbers.

CudaContainer< int4 > &	getWaterMolecules (void)
	Returns unchecked mutable access to recognized water tuples.

CudaContainer< int2 > &	getResidues (void)
	Returns unchecked mutable access to residue intervals.

CudaContainer< int2 > &	getGroups (void)
	Returns unchecked mutable access to connected-component intervals.

std::filesystem::path &	getFilePath (void)
	Returns unchecked mutable access to the stored file path.

double	getNetCharge (void) const
	Computes the sum of all stored atom charges.

double	getTotalMass (void) const
	Computes the sum of all stored atom masses.

InclusionExclusion	getInclusionExclusionLists (void) const
	Builds owned 1-4 inclusion and 1-2/1-3 exclusion pair lists.

Detailed Description

Owns CHARMM PSF topology, per-atom metadata, and derived topology tables.

A CharmmPSF stores segment and residue identifiers, atom names and types, charges, masses, bonded topology, topological connectivity, CHARMM-style exclusion arrays, residue intervals, connected-component intervals, and recognized water molecules. Per-atom metadata and bonded records are host-resident. Residue, connected-component, and water records are stored in CudaContainer objects with independent host and device mirrors.

The file constructor parses the PSF synchronously on the calling host thread. It then derives residue intervals, water tuples, connected components, and topological exclusions. The object stores the supplied path but does not retain a reference to the caller's string.

Parsed bonds, angles, proper dihedrals, and improper dihedrals use zero-based atom indices. The current cross-term parser retains one-based indices; see CrossTerm and CharmmPSF for the associated implementation defect.

Const accessors return borrowed references to object-owned storage. Mutable accessors are unchecked escape hatches: they do not update stored counts, dependent tables, or host/device coherence. See Native mutable access.

Copy construction deep-copies all host vectors and both mirrors of each CudaContainer. The const CharmmPSF && overload also copies and leaves its source unchanged; it is not an ownership-transferring move constructor. The compiler-generated copy-assignment operator performs memberwise assignment and can leave partially assigned state if a later allocation or CUDA operation fails. No move assignment operator is generated.

The compiler-generated destructor is non-throwing. Nested CUDA-owning containers use non-throwing destruction and discard CUDA cleanup failures during destruction.

The class provides no internal locking. Callers must externally synchronize concurrent mutation, destruction, or access that can overlap CUDA operations.

Warning: Parsed and derived state is consistent only until unchecked mutable access or a partial low-level reconfiguration changes one component without rebuilding its dependents.

See also: charmm_psf

Constructor & Destructor Documentation

◆ CharmmPSF() [1/4]

CharmmPSF::CharmmPSF ( void )

Constructs an uninitialized, empty PSF object.

The atom, bond, angle, proper-dihedral, improper-dihedral, and cross-term counts are initialized to -1. All host vectors and CudaContainer members are empty, and the stored file name is empty.

Postcondition: Aggregate methods requiring an initialized atom count report ApoCharmmErrorCode::NotInitialized.

◆ CharmmPSF() [2/4]

CharmmPSF::CharmmPSF ( const std::filesystem::path & filePath )

Constructs and derives topology from a CHARMM PSF file.

The file is read completely into host memory and parsed in section order. The parser requires TITLE, ATOM, BOND, ANGLE, DIHEDRAL, IMPROPER, DONOR, ACCEPTOR, and CROSS-TERM sections. Donor and acceptor records, and sections between ACCEPTOR and CROSS-TERM, are skipped rather than retained.

Atom metadata is stored in file-record order. Charges and masses must be finite. Topology atom numbers must be in the one-based range [1, getNumAtoms()]. After parsing, the constructor derives water, connected-component, residue, and exclusion data.

Parameters

[in] filePath Borrowed non-empty path to a PSF file. The path is copied into the object, retained without canonicalization, and not retained by reference.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `filePath` is empty.
ApoCharmmError	With `ApoCharmmErrorCode::Runtime` if the file cannot be opened or read, a required section or record is missing, a record has an invalid field count, a numeric field is malformed or non-finite, a topology atom number is out of range, or a supported section count exceeds `int`.
ApoCharmmError	With `ApoCharmmErrorCode::Cuda` if allocation, copying, launch checking, or cleanup for a derived CudaContainer fails.
std::bad_alloc	If host-side parsing, topology storage, or diagnostic construction cannot allocate memory.
std::length_error	If a file, container, or diagnostic exceeds an implementation-defined size limit.

Postcondition: On success, all stored nonnegative counts and parser-owned vectors describe the parsed PSF, and all constructor-derived tables have been created.

Note: Construction does not select a CUDA device or stream and does not issue a CharmmPSF-level device-wide synchronization.

◆ CharmmPSF() [3/4]

CharmmPSF::CharmmPSF ( const CharmmPSF & other )

Constructs an independent deep copy of another PSF object.

All scalar values and host vectors are copied. Each CudaContainer copies its host and device mirrors independently, preserving any pre-existing host/device divergence in other.

Parameters

[in] other PSF object to copy. The source remains unchanged and is not retained.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::Cuda` if copying a CudaContainer device allocation fails.
std::bad_alloc	If a host or device-copy diagnostic allocation fails.
std::length_error	If copied storage exceeds an implementation-defined limit.

Postcondition: On success, the new object owns storage independent of other.

◆ CharmmPSF() [4/4]

CharmmPSF::CharmmPSF ( const CharmmPSF && other )

Constructs an independent copy from a const rvalue.

This compatibility overload performs the same deep-copy operations as the const-lvalue copy constructor. Because the source is const, no ownership is transferred and the source remains unchanged.

Parameters

[in] other PSF object to copy. The source is not moved from or retained.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::Cuda` if copying a CudaContainer device allocation fails.
std::bad_alloc	If a host or device-copy diagnostic allocation fails.
std::length_error	If copied storage exceeds an implementation-defined limit.

Postcondition: On success, the new object owns storage independent of other.

Warning: This overload is not a C++ move constructor.

Member Function Documentation

◆ getAngles() [1/2]

std::vector< Angle > & CharmmPSF::getAngles ( void )

Returns unchecked mutable access to angle records.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update the angle count or any dependent force data held by collaborators. Atom indices are not validated. See Native mutable access.

◆ getAngles() [2/2]

const std::vector< Angle > & CharmmPSF::getAngles ( void ) const

Returns the parsed valence angles.

Returns: Borrowed const reference to object-owned host storage. Parsed records contain zero-based atom indices in PSF order. No ownership is transferred.

◆ getAtomNames() [1/2]

std::vector< std::string > & CharmmPSF::getAtomNames ( void )

Returns unchecked mutable access to atom names.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Resizing does not update the atom count or any derived state. See Native mutable access.

◆ getAtomNames() [2/2]

const std::vector< std::string > & CharmmPSF::getAtomNames ( void ) const

Returns the per-atom atom names.

Returns: Borrowed const reference to the host vector owned by this object. Values are in atom-record order. No ownership is transferred, and the reference must not outlive this CharmmPSF.

◆ getAtomTypes() [1/2]

std::vector< std::string > & CharmmPSF::getAtomTypes ( void )

Returns unchecked mutable access to atom types.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not rebuild recognized water tuples, and resizing does not update the atom count. See Native mutable access.

◆ getAtomTypes() [2/2]

const std::vector< std::string > & CharmmPSF::getAtomTypes ( void ) const

Returns the per-atom CHARMM atom types.

Returns: Borrowed const reference to the host vector owned by this object. Values are in atom-record order. No ownership is transferred, and the reference must not outlive this CharmmPSF.

◆ getBonds() [1/2]

std::vector< Bond > & CharmmPSF::getBonds ( void )

Returns unchecked mutable access to bond records.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update the bond count, connectivity, connected-component intervals, or exclusion arrays. Atom indices are not validated. See Native mutable access.

◆ getBonds() [2/2]

const std::vector< Bond > & CharmmPSF::getBonds ( void ) const

Returns the parsed covalent bonds.

Returns: Borrowed const reference to object-owned host storage. Parsed records contain zero-based atom indices in PSF order. No ownership is transferred.

◆ getCharges() [1/2]

std::vector< double > & CharmmPSF::getCharges ( void )

Returns unchecked mutable access to per-atom charges.

Returns: Borrowed mutable reference to object-owned host storage in elementary-charge units. No ownership is transferred.

Warning: Resizing does not update the atom count. A length mismatch causes getNetCharge() to throw ApoCharmmErrorCode::Runtime. See Native mutable access.

◆ getCharges() [2/2]

const std::vector< double > & CharmmPSF::getCharges ( void ) const

Returns the per-atom partial charges.

Returns: Borrowed const reference to the host vector owned by this object. Elements are in atom-record order and use elementary-charge units. No ownership is transferred, and the reference must not outlive this CharmmPSF.

Note: PSF parsing requires finite values but does not impose a physical charge range.

◆ getConnected12() [1/2]

std::vector< std::set< int > > & CharmmPSF::getConnected12 ( void )

Returns unchecked mutable access to direct-bond connectivity.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update 1-3 or 1-4 connectivity, getIblo14(), getInb14(), or bonded records. See Native mutable access.

◆ getConnected12() [2/2]

const std::vector< std::set< int > > & CharmmPSF::getConnected12 ( void ) const

Returns the per-atom direct-bond connectivity sets.

Returns: Borrowed const reference to a host vector normally containing one set per atom. Each set stores zero-based atoms connected by one bond. No ownership is transferred.

◆ getConnected13() [1/2]

std::vector< std::set< int > > & CharmmPSF::getConnected13 ( void )

Returns unchecked mutable access to two-bond connectivity.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update 1-4 connectivity or either CHARMM exclusion array. See Native mutable access.

◆ getConnected13() [2/2]

const std::vector< std::set< int > > & CharmmPSF::getConnected13 ( void ) const

Returns the per-atom two-bond connectivity sets.

Returns: Borrowed const reference to a host vector normally containing one set per atom. Each set stores zero-based atoms reached by the current two-bond construction. No ownership is transferred.

◆ getConnected14() [1/2]

std::vector< std::set< int > > & CharmmPSF::getConnected14 ( void )

Returns unchecked mutable access to three-bond connectivity.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation affects later inclusion-list construction but does not update either CHARMM exclusion array. See Native mutable access.

◆ getConnected14() [2/2]

const std::vector< std::set< int > > & CharmmPSF::getConnected14 ( void ) const

Returns the per-atom three-bond connectivity sets.

Returns: Borrowed const reference to a host vector normally containing one set per atom. Each set stores zero-based atoms reached by the current three-bond construction. No ownership is transferred.

Note: These sets are filtered against 1-2 and 1-3 connectivity when getInclusionExclusionLists() produces explicit inclusion pairs.

◆ getCrossTerms() [1/2]

std::vector< CrossTerm > & CharmmPSF::getCrossTerms ( void )

Returns unchecked mutable access to cross-term records.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update the cross-term count. The current parsed representation is one-based, but direct mutation is not validated. See Native mutable access.

◆ getCrossTerms() [2/2]

const std::vector< CrossTerm > & CharmmPSF::getCrossTerms ( void ) const

Returns the parsed CMAP cross-term records.

Returns: Borrowed const reference to object-owned host storage. No ownership is transferred.

Warning: The current parser stores these atom numbers in one-based PSF form, unlike the other topology records. See CrossTerm.

◆ getDihedrals() [1/2]

std::vector< Dihedral > & CharmmPSF::getDihedrals ( void )

Returns unchecked mutable access to proper-dihedral records.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update the proper-dihedral count or dependent force data. Atom indices are not validated. See Native mutable access.

◆ getDihedrals() [2/2]

const std::vector< Dihedral > & CharmmPSF::getDihedrals ( void ) const

Returns the parsed proper dihedrals.

Returns: Borrowed const reference to object-owned host storage. Parsed records contain zero-based atom indices in PSF order. No ownership is transferred.

◆ getFilePath() [1/2]

std::filesystem::path & CharmmPSF::getFilePath ( void )

Returns unchecked mutable access to the stored file path.

Returns: Borrowed mutable reference to object-owned file-system path. No ownership is transferred.

Warning: Changing this path does not read another file, reparse topology, or change any other stored data. See Native mutable access.

◆ getFilePath() [2/2]

const std::filesystem::path & CharmmPSF::getFilePath ( void ) const

Returns the path supplied to the file constructor.

Returns: Borrowed const reference to the object-owned file-system path. The path is retained without canonicalization.

◆ getGroups() [1/2]

CudaContainer< int2 > & CharmmPSF::getGroups ( void )

Returns unchecked mutable access to connected-component intervals.

Returns: Borrowed mutable reference to the object-owned CudaContainer<int2>. No ownership is transferred.

Warning: Mutation does not update bonds or connectivity. Host and device mirrors require explicit transfer after one-sided mutation. See Native mutable access.

◆ getGroups() [2/2]

const CudaContainer< int2 > & CharmmPSF::getGroups ( void ) const

Returns contiguous connected-component intervals.

Returns: Borrowed const reference to the object-owned CudaContainer<int2>. Each element stores a zero-based inclusive [x, y] interval. No ownership is transferred.

Warning: The current construction assumes every bonded component occupies one contiguous atom-index interval.

◆ getIblo14() [1/2]

std::vector< int > & CharmmPSF::getIblo14 ( void )

Returns unchecked mutable access to cumulative exclusion offsets.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation is not validated against getInb14() or the atom count. See Native mutable access.

◆ getIblo14() [2/2]

const std::vector< int > & CharmmPSF::getIblo14 ( void ) const

Returns the cumulative CHARMM exclusion offsets.

Returns: Borrowed const reference to object-owned host storage. A normally parsed object has one dimensionless entry per atom. getIblo14()[i] is the cumulative number of entries in getInb14() through atom i.

◆ getImpropers() [1/2]

std::vector< Dihedral > & CharmmPSF::getImpropers ( void )

Returns unchecked mutable access to improper-dihedral records.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not update the improper-dihedral count or dependent force data. Atom indices are not validated. See Native mutable access.

◆ getImpropers() [2/2]

const std::vector< Dihedral > & CharmmPSF::getImpropers ( void ) const

Returns the parsed improper dihedrals.

Returns: Borrowed const reference to object-owned host storage. Parsed records contain zero-based atom indices in PSF order. No ownership is transferred.

◆ getInb14() [1/2]

std::vector< int > & CharmmPSF::getInb14 ( void )

Returns unchecked mutable access to flattened exclusion atom numbers.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation is not validated against getIblo14(), the atom count, or the one-based CHARMM atom-number convention. See Native mutable access.

◆ getInb14() [2/2]

const std::vector< int > & CharmmPSF::getInb14 ( void ) const

Returns the flattened CHARMM exclusion atom numbers.

Returns: Borrowed const reference to object-owned host storage. Entries use CHARMM's one-based atom-number convention and include only neighbors whose zero-based index is greater than the source atom's index.

◆ getInclusionExclusionLists()

InclusionExclusion CharmmPSF::getInclusionExclusionLists ( void ) const

Builds owned 1-4 inclusion and 1-2/1-3 exclusion pair lists.

Every pair is emitted once with its lower zero-based atom index first. Inclusion pairs are 1-4 connections not also present in the source atom's 1-2 or 1-3 sets. Exclusion pairs are the ordered union of the source atom's 1-2 and 1-3 sets. Inclusion pairs precede exclusion pairs in the returned flattened vector.

Returns: Owned host-side InclusionExclusion value. sizes[0] is the inclusion-pair count, sizes[1] is the exclusion-pair count, and in14_ex14 contains the corresponding zero-based pairs.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::NotInitialized` if the atom count is negative.
ApoCharmmError	With `ApoCharmmErrorCode::Runtime` if any outer connectivity vector length differs from the atom count.
std::bad_alloc	If temporary or returned host vectors cannot allocate storage.
std::length_error	If temporary or returned storage exceeds an implementation-defined vector size limit.

Postcondition: The PSF object and its connectivity sets are unchanged.

◆ getMasses() [1/2]

std::vector< double > & CharmmPSF::getMasses ( void )

Returns unchecked mutable access to per-atom masses.

Returns: Borrowed mutable reference to object-owned host storage in atomic mass units. No ownership is transferred.

Warning: Resizing does not update the atom count. A length mismatch causes getTotalMass() to throw ApoCharmmErrorCode::Runtime. See Native mutable access.

◆ getMasses() [2/2]

const std::vector< double > & CharmmPSF::getMasses ( void ) const

Returns the per-atom masses.

Returns: Borrowed const reference to the host vector owned by this object. Elements are in atom-record order and use atomic mass units. No ownership is transferred, and the reference must not outlive this CharmmPSF.

Note: PSF parsing requires finite values but does not require positive masses.

◆ getNetCharge()

double CharmmPSF::getNetCharge ( void ) const

Computes the sum of all stored atom charges.

Returns: Net partial charge in elementary-charge units. An initialized zero-atom object returns 0.0.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::NotInitialized` if the atom count is negative.
ApoCharmmError	With `ApoCharmmErrorCode::Runtime` if the charge vector length differs from the atom count.
std::bad_alloc	If constructing an error diagnostic fails.
std::length_error	If an error diagnostic exceeds an implementation-defined limit.

Postcondition: The PSF object is unchanged.

◆ getNumAngles()

int CharmmPSF::getNumAngles ( void ) const

Returns the stored angle count.

Returns: Dimensionless angle count, or -1 before a PSF has initialized the angle section.

Note: Unchecked mutation of getAngles() does not update this value.

◆ getNumAtoms()

int CharmmPSF::getNumAtoms ( void ) const

Returns the stored atom count.

Returns: Dimensionless atom count, or -1 for a default-constructed object whose atom count has not been initialized.

Note: The value is stored independently from the lengths of the mutable per-atom vectors.

◆ getNumBonds()

int CharmmPSF::getNumBonds ( void ) const

Returns the stored bond count.

Returns: Dimensionless bond count, or -1 before a PSF has initialized the bond section.

Note: Unchecked mutation of getBonds() does not update this value.

◆ getNumCrossTerms()

int CharmmPSF::getNumCrossTerms ( void ) const

Returns the stored cross-term count.

Returns: Dimensionless cross-term count, or -1 before a PSF has initialized the cross-term section.

Note: Unchecked mutation of getCrossTerms() does not update this value.

◆ getNumDihedrals()

int CharmmPSF::getNumDihedrals ( void ) const

Returns the stored proper-dihedral count.

Returns: Dimensionless proper-dihedral count, or -1 before a PSF has initialized the proper-dihedral section.

Note: Unchecked mutation of getDihedrals() does not update this value.

◆ getNumImpropers()

int CharmmPSF::getNumImpropers ( void ) const

Returns the stored improper-dihedral count.

Returns: Dimensionless improper-dihedral count, or -1 before a PSF has initialized the improper section.

Note: Unchecked mutation of getImpropers() does not update this value.

◆ getResidueIdentifiers() [1/2]

std::vector< int > & CharmmPSF::getResidueIdentifiers ( void )

Returns unchecked mutable access to residue identifiers.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Mutation does not rebuild getResidues() and resizing does not update the atom count. See Native mutable access.

◆ getResidueIdentifiers() [2/2]

const std::vector< int > & CharmmPSF::getResidueIdentifiers ( void ) const

Returns the per-atom residue identifiers.

Returns: Borrowed const reference to the host vector owned by this object. Values are dimensionless integers in atom-record order. No ownership is transferred, and the reference must not outlive this CharmmPSF.

Note: The parser preserves the integer identifiers written in the PSF.

◆ getResidueNames() [1/2]

std::vector< std::string > & CharmmPSF::getResidueNames ( void )

Returns unchecked mutable access to residue names.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Resizing does not update the atom count or any derived state. See Native mutable access.

◆ getResidueNames() [2/2]

const std::vector< std::string > & CharmmPSF::getResidueNames ( void ) const

Returns the per-atom residue names.

Returns: Borrowed const reference to the host vector owned by this object. Values are in atom-record order. No ownership is transferred, and the reference must not outlive this CharmmPSF.

◆ getResidues() [1/2]

CudaContainer< int2 > & CharmmPSF::getResidues ( void )

Returns unchecked mutable access to residue intervals.

Returns: Borrowed mutable reference to the object-owned CudaContainer<int2>. No ownership is transferred.

Warning: Mutation does not update residue metadata. Host and device mirrors require explicit transfer after one-sided mutation. See Native mutable access.

◆ getResidues() [2/2]

const CudaContainer< int2 > & CharmmPSF::getResidues ( void ) const

Returns contiguous residue intervals.

Returns: Borrowed const reference to the object-owned CudaContainer<int2>. Each element stores a zero-based inclusive [x, y] atom interval. No ownership is transferred.

Warning: The current parser starts a new interval only when the numeric residue identifier changes; a segment change alone does not split an interval.

◆ getSegmentIdentifiers() [1/2]

std::vector< std::string > & CharmmPSF::getSegmentIdentifiers ( void )

Returns unchecked mutable access to segment identifiers.

Returns: Borrowed mutable reference to object-owned host storage. No ownership is transferred.

Warning: Resizing does not update the atom count. Mutation does not rebuild residue intervals or any topology-derived state. See Native mutable access.

◆ getSegmentIdentifiers() [2/2]

const std::vector< std::string > & CharmmPSF::getSegmentIdentifiers ( void ) const

Returns the per-atom segment identifiers.

Returns: Borrowed const reference to the host vector owned by this object. Values are in atom-record order. No ownership is transferred, and the reference must not outlive this CharmmPSF.

Note: A normally parsed vector has getNumAtoms() entries, but unchecked mutable access can violate that relationship.

◆ getTotalMass()

double CharmmPSF::getTotalMass ( void ) const

Computes the sum of all stored atom masses.

Returns: Total mass in atomic mass units. An initialized zero-atom object returns 0.0.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::NotInitialized` if the atom count is negative.
ApoCharmmError	With `ApoCharmmErrorCode::Runtime` if the mass vector length differs from the atom count.
std::bad_alloc	If constructing an error diagnostic fails.
std::length_error	If an error diagnostic exceeds an implementation-defined limit.

Postcondition: The PSF object is unchanged.

◆ getWaterMolecules() [1/2]

CudaContainer< int4 > & CharmmPSF::getWaterMolecules ( void )

Returns unchecked mutable access to recognized water tuples.

Returns: Borrowed mutable reference to the object-owned CudaContainer<int4>. No ownership is transferred.

Warning: Host and device mirrors are not automatically coherent. Host mutation requires transferToDevice() before device consumers can observe it; device mutation requires transferToHost() before host consumers can observe it. See Native mutable access.

◆ getWaterMolecules() [2/2]

const CudaContainer< int4 > & CharmmPSF::getWaterMolecules ( void ) const

Returns recognized three-site water tuples.

Returns: Borrowed const reference to the object-owned CudaContainer<int4>. Each host/device element stores zero-based (oxygen, hydrogen1, hydrogen2, 0) components in x, y, z, w order. No ownership is transferred.

Note: File construction recognizes only consecutive atom types OT, HT, HT.

◆ setAtomCharges()

void CharmmPSF::setAtomCharges ( const std::vector< double > & charges )

Replaces all per-atom partial charges.

The input is copied into host-owned storage. No topology, aggregate cache, CudaContainer, or device allocation is changed.

Parameters

[in] charges Host vector containing exactly getNumAtoms() finite or non-finite double values in elementary-charge units. This setter does not validate finiteness or physical range.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::NotInitialized` if the atom count is negative.
ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `charges.size()` differs from the initialized atom count.
std::bad_alloc	If copying the vector cannot allocate storage.
std::length_error	If the input exceeds an implementation-defined vector size limit.

Postcondition: On success, getCharges() contains an independent copy of charges.

Warning: Existing references, pointers, and iterators into the charge vector can be invalidated.

◆ setNumAtoms()

void CharmmPSF::setNumAtoms ( const int numAtoms )

Sets the atom count and resizes the seven per-atom host arrays.

The segment identifiers, residue identifiers, residue names, atom names, atom types, charges, and masses are resized to numAtoms. Newly added strings are empty, newly added residue identifiers are zero, and newly added charges and masses are 0.0.

This method does not change any bonded-topology count or record. It also does not rebuild residue intervals, water tuples, connected components, topological connectivity, or CHARMM exclusion arrays.

Parameters

[in] numAtoms New dimensionless atom count. The value must be nonnegative.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `numAtoms` is negative.
std::bad_alloc	If resizing a per-atom host vector cannot allocate storage.
std::length_error	If `numAtoms` exceeds a host vector's maximum size.

Postcondition: getNumAtoms() == numAtoms and every per-atom host vector has length numAtoms.

Warning: Existing element references, pointers, and iterators into a resized vector can be invalidated.; Calling this method on a parsed object can leave topology and derived tables inconsistent with the new atom count.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CharmmPSF() [1/4]

◆ CharmmPSF() [2/4]

◆ CharmmPSF() [3/4]

◆ CharmmPSF() [4/4]

Member Function Documentation

◆ getAngles() [1/2]

◆ getAngles() [2/2]

◆ getAtomNames() [1/2]

◆ getAtomNames() [2/2]

◆ getAtomTypes() [1/2]

◆ getAtomTypes() [2/2]

◆ getBonds() [1/2]

◆ getBonds() [2/2]

◆ getCharges() [1/2]

◆ getCharges() [2/2]

◆ getConnected12() [1/2]

◆ getConnected12() [2/2]

◆ getConnected13() [1/2]

◆ getConnected13() [2/2]

◆ getConnected14() [1/2]

◆ getConnected14() [2/2]

◆ getCrossTerms() [1/2]

◆ getCrossTerms() [2/2]

◆ getDihedrals() [1/2]

◆ getDihedrals() [2/2]

◆ getFilePath() [1/2]

◆ getFilePath() [2/2]

◆ getGroups() [1/2]

◆ getGroups() [2/2]

◆ getIblo14() [1/2]

◆ getIblo14() [2/2]

◆ getImpropers() [1/2]

◆ getImpropers() [2/2]

◆ getInb14() [1/2]

◆ getInb14() [2/2]

◆ getInclusionExclusionLists()

◆ getMasses() [1/2]

◆ getMasses() [2/2]

◆ getNetCharge()

◆ getNumAngles()

◆ getNumAtoms()

◆ getNumBonds()

◆ getNumCrossTerms()

◆ getNumDihedrals()

◆ getNumImpropers()

◆ getResidueIdentifiers() [1/2]

◆ getResidueIdentifiers() [2/2]

◆ getResidueNames() [1/2]

◆ getResidueNames() [2/2]

◆ getResidues() [1/2]

◆ getResidues() [2/2]

◆ getSegmentIdentifiers() [1/2]

◆ getSegmentIdentifiers() [2/2]

◆ getTotalMass()

◆ getWaterMolecules() [1/2]

◆ getWaterMolecules() [2/2]

◆ setAtomCharges()

◆ setNumAtoms()