Stores and packs host-resident CHARMM force-field parameters. More...

#include <CharmmParameters.h>

Public Member Functions
	CharmmParameters (void)
	Constructs an empty parameter set.

	CharmmParameters (const std::filesystem::path &filePath)
	Constructs a parameter set from one `.prm` or `.str` file.

	CharmmParameters (const std::vector< std::filesystem::path > &filePaths)
	Constructs a parameter set by reading files in the supplied order.

const std::map< BondKey, BondValues > &	getBondParams (void) const
	Returns the parsed harmonic bond-parameter map.

const std::map< AngleKey, BondValues > &	getUreybParams (void) const
	Returns the parsed Urey-Bradley parameter map.

const std::map< AngleKey, AngleValues > &	getAngleParams (void) const
	Returns the parsed harmonic angle-parameter map.

const std::map< DihedralKey, std::vector< DihedralValues > > &	getDihedralParams (void) const
	Returns the parsed proper-dihedral parameter map.

const std::map< DihedralKey, ImDihedralValues > &	getImproperParams (void) const
	Returns the parsed harmonic improper-dihedral parameter map.

const std::map< std::string, VdwParameters > &	getVdwParams (void) const
	Returns the parsed regular Lennard-Jones parameter map.

const std::map< std::string, VdwParameters > &	getVdw14Params (void) const
	Returns the parsed explicit 1-4 Lennard-Jones parameter map.

const std::vector< std::filesystem::path > &	getPrmFilePaths (void) const
	Returns the paths supplied to a file-reading constructor.

BondedParamsAndLists	getBondedParamsAndLists (const std::shared_ptr< CharmmPSF > &psf) const
	Packs bonded parameters and PSF topology into host vectors.

VdwParamsAndTypes	getVdwParamsAndTypes (std::shared_ptr< CharmmPSF > &psf) const
	Packs Lennard-Jones pair coefficients and PSF type indices.

void	readCharmmParameterFile (const std::filesystem::path &filePath)
	Reads and merges one CHARMM parameter file.

Detailed Description

Stores and packs host-resident CHARMM force-field parameters.

The object parses one or more CHARMM .prm or .str files into bonded, Lennard-Jones, and NBFIX lookup tables. It does not store topology, charges, coordinates, device memory, CUDA streams, or synchronization state. CharmmPSF supplies topology and atom types when packed force data is needed.

Parsed record text is comment-stripped, trimmed, and converted to uppercase; constructor file paths are retained as std::filesystem::path objects without canonicalization. Compiler-generated copy construction and assignment deep-copy all owned containers; move construction and assignment transfer their contents and leave the source valid but otherwise unspecified. Destruction is non-throwing, releases the host storage, and performs no CUDA work.

The class provides no internal synchronization. Concurrent const access requires that no thread mutate, assign, move, or destroy the same object.

See also: charmm_parameters

Constructor & Destructor Documentation

◆ CharmmParameters() [1/3]

CharmmParameters::CharmmParameters ( void )

Constructs an empty parameter set.

Postcondition: All parameter tables and the constructor-file list are empty.

◆ CharmmParameters() [2/3]

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

Constructs a parameter set from one .prm or .str file.

Parameters

[in] filePath Non-empty file-system path. The path is copied and is not retained as a pointer or reference.

Exceptions

ApoCharmmError	with code `ApoCharmmErrorCode::InvalidArgument` if `filePath` is empty.
ApoCharmmError	with code `ApoCharmmErrorCode::Runtime` if the file cannot be opened or read, a required TOPPAR parameter block is absent, a NONBONDED header continuation is unterminated, or a parsed record has an invalid shape or numeric field.
std::bad_alloc	If host-side string or container allocation fails.

Postcondition: On successful construction, filePath is the sole entry returned by getPrmFilePaths().

◆ CharmmParameters() [3/3]

CharmmParameters::CharmmParameters ( const std::vector< std::filesystem::path > & filePaths )

Constructs a parameter set by reading files in the supplied order.

Later files are merged into the existing tables. Duplicate precedence depends on the parameter section and is described on CharmmParameters.

Parameters

[in] filePaths Non-empty ordered list of non-empty .prm or .str paths. All strings are copied.

Exceptions

ApoCharmmError	with code `ApoCharmmErrorCode::InvalidArgument` if `filePaths` is empty or any contained path is empty.
ApoCharmmError	with code `ApoCharmmErrorCode::Runtime` if any file cannot be opened or read, a required TOPPAR parameter block is absent, a NONBONDED header continuation is unterminated, or a parsed record has an invalid shape or numeric field.
std::bad_alloc	If host-side string or container allocation fails.

Postcondition: On successful construction, getPrmFilePaths() equals filePaths in the original order.

Member Function Documentation

◆ getAngleParams()

const std::map< AngleKey, AngleValues > & CharmmParameters::getAngleParams ( void ) const

Returns the parsed harmonic angle-parameter map.

Returns: Borrowed const reference to the map owned by this object. Equilibrium angles are stored in radians.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Later successful reads are observable through the same map.

◆ getBondedParamsAndLists()

BondedParamsAndLists CharmmParameters::getBondedParamsAndLists ( const std::shared_ptr< CharmmPSF > & psf ) const

Packs bonded parameters and PSF topology into host vectors.

Exact parameter matching is attempted first. Proper dihedrals then permit an X-middle-middle-X wildcard, and impropers permit an outer-X-X-outer wildcard. Missing Urey-Bradley terms are allowed, and terms with abs(kub) <= 0.01 are omitted. CMAP output is always empty.

Parameters

[in] psf Borrowed shared pointer to a non-null CharmmPSF. The pointee is read but not mutated or retained after return.

Returns: Owned host-side copies in BondedParamsAndLists layout.

Exceptions

ApoCharmmError	with code `ApoCharmmErrorCode::InvalidArgument` if `psf` is null.
ApoCharmmError	with code `ApoCharmmErrorCode::Runtime` if a required bond, angle, proper-dihedral, or improper-dihedral parameter cannot be matched to the PSF.
std::bad_alloc	If host-side packing allocation fails.

Postcondition: Neither this object nor *psf is modified.

Note: The operation performs no CUDA transfer or synchronization.

Warning: The current improper row layout does not match imdihe_pot's mode-field contract; see CharmmParameters.

◆ getBondParams()

const std::map< BondKey, BondValues > & CharmmParameters::getBondParams ( void ) const

Returns the parsed harmonic bond-parameter map.

Returns: Borrowed const reference to the map owned by this object. Keys are canonical atom-type pairs and values use AKMA bond units.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Later successful reads are observable through the same map.

◆ getDihedralParams()

const std::map< DihedralKey, std::vector< DihedralValues > > & CharmmParameters::getDihedralParams ( void ) const

Returns the parsed proper-dihedral parameter map.

Each key maps to all Fourier terms encountered for that key, in file-read order.

Returns: Borrowed const reference to the map owned by this object. Phase offsets are stored in degrees.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Appending a later matching term can invalidate references and iterators into that key's std::vector<DihedralValues>.

◆ getImproperParams()

const std::map< DihedralKey, ImDihedralValues > & CharmmParameters::getImproperParams ( void ) const

Returns the parsed harmonic improper-dihedral parameter map.

Returns: Borrowed const reference to the map owned by this object. Equilibrium phases are stored in degrees.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Later successful reads are observable through the same map.

◆ getPrmFilePaths()

const std::vector< std::filesystem::path > & CharmmParameters::getPrmFilePaths ( void ) const

Returns the paths supplied to a file-reading constructor.

Calls to readCharmmParameterFile() do not append to this list.

Returns: Borrowed const reference to the owned file-system paths in constructor order. The paths are not canonicalized.

Note: The reference remains valid only while this object is alive and has not been assigned from or moved.

◆ getUreybParams()

const std::map< AngleKey, BondValues > & CharmmParameters::getUreybParams ( void ) const

Returns the parsed Urey-Bradley parameter map.

Every parsed ANGLES record creates an entry; records without explicit Urey-Bradley fields store zero values.

Returns: Borrowed const reference to the map owned by this object. Values use AKMA bond units.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Later successful reads are observable through the same map.

◆ getVdw14Params()

const std::map< std::string, VdwParameters > & CharmmParameters::getVdw14Params ( void ) const

Returns the parsed explicit 1-4 Lennard-Jones parameter map.

Only NONBONDED records containing the optional three 1-4 fields contribute entries.

Returns: Borrowed const reference to the atom-type map owned by this object. Values contain epsilon in kcal mol^-1 and Rmin/2 in angstroms.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Later explicit 1-4 records can replace mapped values in place.

◆ getVdwParams()

const std::map< std::string, VdwParameters > & CharmmParameters::getVdwParams ( void ) const

Returns the parsed regular Lennard-Jones parameter map.

Returns: Borrowed const reference to the atom-type map owned by this object. Values contain epsilon in kcal mol^-1 and Rmin/2 in angstroms.

Note: The reference aliases this object and remains valid only while the object is alive and has not been assigned from or moved. Later NONBONDED records can replace mapped values in place.

◆ getVdwParamsAndTypes()

VdwParamsAndTypes CharmmParameters::getVdwParamsAndTypes ( std::shared_ptr< CharmmPSF > & psf ) const

Packs Lennard-Jones pair coefficients and PSF type indices.

Distinct PSF atom types are sorted lexicographically. Normal pair values use CHARMM geometric epsilon and additive Rmin/2 combination unless an NBFIX entry overrides the pair. The 1-4 table substitutes explicit per-type 1-4 values where available.

Parameters

[in] psf Borrowed shared pointer to a non-null CharmmPSF. The pointee is read but not mutated or retained after return.

Returns: Owned host-side copies in VdwParamsAndTypes layout. Each coefficient pair stores C6 = 2 * epsilon * Rmin^6 followed by C12 = epsilon * Rmin^12.

Exceptions

ApoCharmmError	with code `ApoCharmmErrorCode::InvalidArgument` if `psf` is null.
ApoCharmmError	with code `ApoCharmmErrorCode::Runtime` if any PSF atom type lacks a regular NONBONDED parameter.
std::bad_alloc	If host-side table construction fails.

Postcondition: Neither this object nor *psf is modified.

Note: The operation performs no CUDA transfer or synchronization.

Warning: The current implementation uses regular NBFIX values when packing both normal and 1-4 pair tables, even when explicit NBFIX 1-4 values were parsed.

◆ readCharmmParameterFile()

void CharmmParameters::readCharmmParameterFile ( const std::filesystem::path & filePath )

Reads and merges one CHARMM parameter file.

The parser recognizes BONDS, ANGLES, DIHEDRALS, IMPROPER, NONBONDED, and NBFIX records. ATOMS, CMAP, and HBOND sections are currently ignored. Record text is stripped of ! comments, normalized to uppercase, and parsed on the host. This method does not append filePath to the constructor path list returned by getPrmFileNames().

Bond, angle, Urey-Bradley, improper, and NBFIX maps keep the first matching key. Proper-dihedral records append Fourier terms. Regular and explicit 1-4 NONBONDED values replace earlier values for the same atom type.

Parameters

[in] filePath Non-empty file-system path. The path is used only for this call; parsed records, not the path string, are retained.

Exceptions

ApoCharmmError	with code `ApoCharmmErrorCode::InvalidArgument` if `filePath` is empty.
ApoCharmmError	with code `ApoCharmmErrorCode::Runtime` if the file cannot be opened or read, a file whose final path component contains `TOPPAR` has no CHARMM parameter block, a NONBONDED header continuation is unterminated, or a recognized record has an invalid token count or numeric field.
std::bad_alloc	If host-side parsing or map growth requires an allocation that fails.

Postcondition: On success, supported records are merged into the existing host maps.

Warning: The update is not transactional. A failure can leave records read earlier in the same call observable in this object.

Note: The operation performs no CUDA transfer or synchronization.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CharmmParameters() [1/3]

◆ CharmmParameters() [2/3]

◆ CharmmParameters() [3/3]

Member Function Documentation

◆ getAngleParams()

◆ getBondedParamsAndLists()

◆ getBondParams()

◆ getDihedralParams()

◆ getImproperParams()

◆ getPrmFilePaths()

◆ getUreybParams()

◆ getVdw14Params()

◆ getVdwParams()

◆ getVdwParamsAndTypes()

◆ readCharmmParameterFile()