stormm::testing::MdlMol Class Reference

A molecular three-dimensional feature. This special class of MOL object properies has its own data lines. More...

#include <mdlmol.h>

Public Member Functions
const std::string &	getTitle () const
	Get the title of the MDL MOL entry (for its first three lines)
int	getAtomCount () const
	Get the system's atom count.
int	getBondCount () const
	Get the number of bonds in the system.
int	getPropertiesCount () const
	Get the number of properties found in the MDL MOL entry.
int	getDataItemCount () const
	Get the number of data items (XML-like note found after the MDL section of the entry in a BIOVIA Structure Data (SD)-format file).
const MdlMol *	getSelfPointer () const
	Get a const pointer to the object, useful if a pointer is needed and the object is available by const reference.
PhaseSpace	exportPhaseSpace () const
	Export the coordinates as a PhaseSpace object suitable for basic molecular mechanics force computations.
CoordinateFrame	exportCoordinateFrame () const
	Export the coordinates as a stripped-down CoordinateFrame object suitable for molecular mechanics energy computations.
char4	getAtomSymbol (int index) const
	Get the atomic symbol for a particular atom.
const std::vector< char4 > &	getAtomSymbols () const
	Get a const reference to the atomic symbols for all atoms.
int	getAtomicNumber (int index) const
	Get the atomic number of a particular atom.
const std::vector< int > &	getAtomicNumbers () const
	Get a const reference to the vector of all atomic numbers in the system.
int	getFormalCharge (int index) const
	Get the formal charge on a particular atom.
const std::vector< int > &	getFormalCharges () const
	Get a const reference to the vector of all formal charges.
void	addProperty (const MdlMolProperty *mmprop)
	Add a property to the object. Properties must follow a list of pre-approved BIOVIA codes, but provide a means of extending the V2000 format to include information found in the V3000 format.
void	addProperty (const MdlMolProperty &mmprop)
MdlMolDataItemKind	getDataItemKind (int item_index) const
	Get the classification of a data item from within the MDL MOL entry.
StateVariable	getTrackedState (int item_index) const
	Get the state variable that one of the data items is tracking.
void	addLineToDataItem (const std::string &text, int item_index)
	Add a line of text to a specific data item within the MDL MOL entry. This text may contain a pre-formatted string displaying some energy quantity, or more complex syntax.
const std::string &	getDataItemName (int item_index) const
	Get the name of a data item based on its number.
const std::string &	getDataItemOutputName (int item_index) const
	Get the name of a data item based on its number, fit for output in the proper Biovia SD file format standard.
int	getDataItemIndex (const std::string &item_name) const
	Get the index of a data item based on a name.
	MdlMol (ExceptionResponse policy_in=ExceptionResponse::WARN)
	Constructors for the MDL molecule format object (known as MolObj in RDKit)
	MdlMol (const std::string &filename, ExceptionResponse policy_in=ExceptionResponse::WARN, ModificationPolicy dimod_policy=ModificationPolicy::DO_NOT_MODIFY, ExceptionResponse dimod_notify=ExceptionResponse::WARN)
	MdlMol (const char *filename, ExceptionResponse policy_in=ExceptionResponse::WARN, ModificationPolicy dimod_policy=ModificationPolicy::DO_NOT_MODIFY, ExceptionResponse dimod_notify=ExceptionResponse::WARN)
	MdlMol (const TextFile &tf, int line_start=0, int line_end=-1, CaseSensitivity capitalization=CaseSensitivity::YES, ExceptionResponse policy_in=ExceptionResponse::WARN, ModificationPolicy dimod_policy=ModificationPolicy::DO_NOT_MODIFY, ExceptionResponse dimod_notify=ExceptionResponse::WARN)
template<typename T>
	MdlMol (const ChemicalFeatures *chemfe, const T *xcrd, const T *ycrd, const T *zcrd, double inv_scale, int molecule_index=0)
template<typename T>
	MdlMol (const ChemicalFeatures *chemfe, const T *xcrd, const T *ycrd, const T *zcrd, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const CoordinateFrameReader cfr, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const CoordinateFrame *cf, int molecule_index=0)
	MdlMol (const ChemicalFeatures &chemfe, const CoordinateFrame &cf, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const PhaseSpaceReader psr, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const PhaseSpace *ps, int molecule_index=0)
	MdlMol (const ChemicalFeatures &chemfe, const PhaseSpace &ps, int molecule_index=0)
template<typename T>
	MdlMol (const ChemicalFeatures *chemfe, const CoordinateSeriesReader< T > csr, int frame_index, int molecule_index=0)
template<typename T>
	MdlMol (const ChemicalFeatures *chemfe, const CoordinateSeries< T > *cs, int frame_index, int molecule_index=0)
template<typename T>
	MdlMol (const ChemicalFeatures &chemfe, const CoordinateSeries< T > &cs, int frame_index, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const PsSynthesisReader poly_psr, int system_index, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const PhaseSpaceSynthesis *poly_ps, int system_index, int molecule_index=0)
	MdlMol (const ChemicalFeatures &chemfe, const PhaseSpaceSynthesis &poly_ps, int system_index, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const CondensateReader *cdnsr, int system_index, int molecule_index=0)
	MdlMol (const ChemicalFeatures *chemfe, const Condensate *cdns, int system_index, int molecule_index=0)
	MdlMol (const ChemicalFeatures &chemfe, const Condensate &cdns, int system_index, int molecule_index=0)
	MdlMol (const MdlMol &original)=default
	Default copy and move constructors, as well as assignment operators, are appropriate for this object which consists entirely of scalar data types, Standard Template Library objects, and no const members.
	MdlMol (MdlMol &&original)=default
MdlMol &	operator= (const MdlMol &original)=default
MdlMol &	operator= (MdlMol &&original)=default
double3	getCoordinates (int index) const
	Get the { X, Y, Z } coordinate tuple for a particular atom, or for all atoms.
const std::vector< double3 > &	getCoordinates () const
std::vector< double >	getCoordinates (CartesianDimension dim) const
template<typename T>
void	impartCoordinates (const T *xcrd, const T *ycrd, const T *zcrd, double scale_factor)
	Impart a new set of coordinates to the atoms based on one of STORMM's major coordinate classes. This will permanently modify the underlying coordinates of the object and also any properties dependent of the structure. If providing a standalone coordinate object, the atom count of the incoming coordinate set will be checked. In all cases, the order of atoms in the incoming coordinate set is expect to match this object's own arrangement. If presenting an abstract of a PhaseSpace object, the coordinates of the WHITE stage in the time cycle will be taken. When presenting the original objects, the developer may select the stage in the time cycle.
template<typename T>
void	impartCoordinates (const T *xcrd, const T *ycrd, const T *zcrd, double scale_factor, const ChemicalDetailsKit &cdk, int molecule_index)
void	impartCoordinates (const llint *xcrd, const llint *ycrd, const llint *zcrd, const int *xcrd_ovrf, const int *ycrd_ovrf, const int *zcrd_ovrf, double scale_factor)
void	impartCoordinates (const llint *xcrd, const llint *ycrd, const llint *zcrd, const int *xcrd_ovrf, const int *ycrd_ovrf, const int *zcrd_ovrf, double scale_factor, const ChemicalDetailsKit &cdk, int molecule_index)
void	impartCoordinates (const PhaseSpaceReader &psr)
void	impartCoordinates (const PhaseSpaceWriter &psw)
void	impartCoordinates (const PhaseSpace *ps, CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const PhaseSpace *ps, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const PhaseSpace &ps, CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const PhaseSpace &ps, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const CoordinateFrameReader &cfr)
void	impartCoordinates (const CoordinateFrameWriter &cfw)
void	impartCoordinates (const CoordinateFrame *cf, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const CoordinateFrame &cf, HybridTargetLevel tier=HybridTargetLevel::HOST)
template<typename T>
void	impartCoordinates (const CoordinateSeriesReader< T > &cs, int frame_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
template<typename T>
void	impartCoordinates (const CoordinateSeriesWriter< T > &cs, int frame_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
template<typename T>
void	impartCoordinates (const CoordinateSeries< T > *cs, int frame_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
template<typename T>
void	impartCoordinates (const CoordinateSeries< T > &cs, int frame_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const PhaseSpaceSynthesis *poly_ps, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	impartCoordinates (const PhaseSpaceSynthesis &poly_ps, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
void	addDataItem (const MdlMolDataRequest &ask, const AtomGraph &ag, const RestraintApparatus &ra)
	Add a data item to the object. These data items follow the classifications set forth in the DataRequestKind enumerator (see molecule_format_enumerators.h). Each overload is designed to serve a particular case.
const std::vector< std::string > &	getDataItemContent (int item_index) const
	Get the lines from a data item as an array of strings.
std::vector< std::string >	getDataItemContent (const std::string &item_name) const
void	writeMdl (std::ofstream *foutp, MdlMolVersion vformat) const
	Write a set of molecular coordinates, bonds, and their annotations in MDL MOL format. Apply all properties already stored in the object, such that the result is not an exact reversal of the operations for reading such a file but correctly conveys the relevant information to any other SDF / MDL MOL reader. The data items are not part of this output–for that section of the SD file format, use writeDataItems() below. The intention is that different coordinates can then be edited for a new structure while the (smaller) data section is re-written separately for a more efficient file I/O process.
void	writeMdl (const std::string &fname, MdlMolVersion vformat, PrintSituation expectation) const
std::string	writeMdl (MdlMolVersion vformat=MdlMolVersion::V3000) const
void	writeDataItems (std::ofstream *foutp, int mol_index=0) const
	Write the non-MDL components of an SD file, including all applicable data items, to a string or file. This is to be used in concert with the writeMdl() member function above.
void	writeDataItems (const std::string &fname, PrintSituation expectation, int mol_index=0) const
std::string	writeDataItems (int mol_index=0) const

Detailed Description

A molecular three-dimensional feature. This special class of MOL object properies has its own data lines.

A molecule read from an MDL .mol file, or one of many read from a concatenated SDF file. Many of the enumerators above are translated according to member functions of this object based on the documentation in the ctfileformats.pdf file in this library's directory, also available at:

http://help.accelrysonline.com/ (...) ulm/onelab/1.0/content/ulm_pdfs/direct/reference/ctfileformats2016.pdf

Constructor & Destructor Documentation

MdlMol()

stormm::structure::MdlMol::MdlMol

(

ExceptionResponse

policy_in = ExceptionResponse::WARN

)

Constructors for the MDL molecule format object (known as MolObj in RDKit)

Overloaded:

• Basic constructor for creating a blank MdlMol, referenced by all other constructors' initializer lists
• Constructors based on a file name (string or const char* array)
• Constructor based on a TextFile object from an SDF container previously committed to RAM

Parameters

filename	Name of the file to read, containing one MDL file
tf	Text file data previously read into memory (this is the way to handle an SDF file)
line_start	The irst line at which to begin reading the TextFile object
line_end	Last relevant line of the TextFile object at which reading will stop
capitalization	Indicate whether atomic symbol capitalization can be ignored when assigning elements to each atom
policy_in	Course of action to take if errors are encountered when inferring atomic elements or other critical features of the structure
dimod_policy	Preferred course of action if the names of some data items are found to break the strict Biovia standard: should they be repaired (modified) or left as they are?
dimod_notify	Indicate whether to alert the user if modifications are made to data items.

Member Function Documentation

addDataItem()

void stormm::structure::MdlMol::addDataItem	(	const MdlMolDataRequest &	ask,
		const AtomGraph &	ag,
		const RestraintApparatus &	ra )

Add a data item to the object. These data items follow the classifications set forth in the DataRequestKind enumerator (see molecule_format_enumerators.h). Each overload is designed to serve a particular case.

Overloaded:

• Add a molecular mechanics energy term, with a value supplied by evaluating the structure coordinates with the topology and restraint apparatus.
• Add a summary of the valence interaction influences (including restraints) on each atom in a mask, with forces and energies supplied by evaluating the topology and restraints.
• Track down a specific restraint or topological energy term based on a series of atom types and display its settings.
• Add a user-defined string as a message in the SD output.

Parameters

ask	The request for an item to impart ot the SD file
ag	The topology guiding the motion of the system
ra	The system of restraints guiding the structure alongside the topology

addLineToDataItem()

void stormm::structure::MdlMol::addLineToDataItem	(	const std::string &	text,
		int	item_index )

Add a line of text to a specific data item within the MDL MOL entry. This text may contain a pre-formatted string displaying some energy quantity, or more complex syntax.

Parameters

text	The text to append
item_index	Index of the data item to update

addProperty()

void stormm::structure::MdlMol::addProperty

(

const MdlMolProperty *

mmprop

)

Add a property to the object. Properties must follow a list of pre-approved BIOVIA codes, but provide a means of extending the V2000 format to include information found in the V3000 format.

Overloaded:

• Provide the property by pointer
• Provide the property by reference

Parameters

mmprop

The property to add /{

getAtomicNumber()

int stormm::structure::MdlMol::getAtomicNumber

(

int

index

)

const

Get the atomic number of a particular atom.

Parameters

index

Index number of the atom of interest

getAtomSymbol()

char4 stormm::structure::MdlMol::getAtomSymbol

(

int

index

)

const

Get the atomic symbol for a particular atom.

Parameters

index

Index of the atom of interest

getCoordinates()

double3 stormm::structure::MdlMol::getCoordinates

(

int

index

)

const

Get the { X, Y, Z } coordinate tuple for a particular atom, or for all atoms.

Overloaded:

• Get a unique, modifiable tuple for a single atom.
• Get a const reference to the array of tuples for coordinates of all atoms.
• Get a modifiable vector of all Cartesian X, Y, or Z coordinates.

Parameters

index	Index of the atom of interest
dim	The Cartesian dimension of interest

getDataItemContent()

const std::vector< std::string > & stormm::structure::MdlMol::getDataItemContent

(

int

item_index

)

const

Get the lines from a data item as an array of strings.

Overloaded:

• Accept the index of the data item and return a const reference to its content (this is possible because a data item with a valid index will have content to reference)
• Accept the name of the data item and return a copy of the content, if any data item is found (if the search fails, a const reference to a temporary would be dangerous)

Parameters

item_index	Index of the data item of interest
item_name	Name of the data item of interest

getDataItemIndex()

int stormm::structure::MdlMol::getDataItemIndex

(

const std::string &

item_name

)

const

Get the index of a data item based on a name.

Parameters

item_name

Name of the data item of interest

getDataItemKind()

MdlMolDataItemKind stormm::structure::MdlMol::getDataItemKind

(

int

item_index

)

const

Get the classification of a data item from within the MDL MOL entry.

Parameters

item_index

Position of the data item of interest in the data_items array

getDataItemName()

const std::string & stormm::structure::MdlMol::getDataItemName

(

int

item_index

)

const

Get the name of a data item based on its number.

Parameters

item_index

Index of the data item of interest

getDataItemOutputName()

const std::string & stormm::structure::MdlMol::getDataItemOutputName

(

int

item_index

)

const

Get the name of a data item based on its number, fit for output in the proper Biovia SD file format standard.

Parameters

item_index

Index of the data item of interest

getFormalCharge()

int stormm::structure::MdlMol::getFormalCharge

(

int

index

)

const

Get the formal charge on a particular atom.

Parameters

index

Index number of the atom of interest

impartCoordinates()

template<typename T>

void stormm::structure::MdlMol::impartCoordinates	(	const T *	xcrd,
		const T *	ycrd,
		const T *	zcrd,
		double	scale_factor )

Impart a new set of coordinates to the atoms based on one of STORMM's major coordinate classes. This will permanently modify the underlying coordinates of the object and also any properties dependent of the structure. If providing a standalone coordinate object, the atom count of the incoming coordinate set will be checked. In all cases, the order of atoms in the incoming coordinate set is expect to match this object's own arrangement. If presenting an abstract of a PhaseSpace object, the coordinates of the WHITE stage in the time cycle will be taken. When presenting the original objects, the developer may select the stage in the time cycle.

Overloaded:

• Present three C-style arrays for X, Y, and Z coordinates with trusted lengths
• Present a PhaseSpace object, or abstract thereof
• Present a CoordinateFrame object, or abstract thereof
• Present a CoordinateSeries object, or abstract thereof, with a frame index number

Parameters

xcrd	Cartesian X coordinates of all particles, trusted to describe a number of atoms equal to that found in the MdlMol and in the same order unless supplemented with a ChemicalDetailsKit and molecule index, which can indicate the proper subset and indices of the atomic coordinates to use
ycrd	Cartesian Y coordinates of all particles
zcrd	Cartesian Z coordinates of all particles
xcrd_ovrf	Overflow bits for Cartesian X coordinates of all particles
ycrd_ovrf	Overflow bits for Cartesian Y coordinates of all particles
zcrd_ovrf	Overflow bits for Cartesian Z coordinates of all particles
scale_factor	The scaling factor by which to multiply coordinates in order to take them into units of Angstroms (in general, this is the inverse scaling factor found in the abstracts of fixed-precision coordinate objects)
cdk	Contains indices of the atoms of interest within the (likely larger) arrays provided
molecule_index	Index of the molecule of interest within some larger topology
ps	Coordinates to transfer
cf	Coordinates to transfer
cs	A series of frames, one containing the coordinates to transfer
poly_ps	A complex collection of systems containing coordinates to transfer
frame_index	Frame within the coordinate series to transfer
system_index	System within the phase space synthesis to transfer
tier	Indicate whether to obtain coordinates from either the CPU host or GPU device memory

writeDataItems()

void stormm::structure::MdlMol::writeDataItems	(	std::ofstream *	foutp,
		int	mol_index = 0 ) const

Write the non-MDL components of an SD file, including all applicable data items, to a string or file. This is to be used in concert with the writeMdl() member function above.

Overloaded:

• Write to an output file
• Write to a string

Parameters

foutp	Output file stream
fname	Name of the output file
expectation	Anticipated (or required) condition of the output file that is to be opened, if only its name is provided
mol_index	Index of the molecule within the SD file (a detail which may be added to each data item's header line)

writeMdl()

void stormm::structure::MdlMol::writeMdl	(	std::ofstream *	foutp,
		MdlMolVersion	vformat ) const

Write a set of molecular coordinates, bonds, and their annotations in MDL MOL format. Apply all properties already stored in the object, such that the result is not an exact reversal of the operations for reading such a file but correctly conveys the relevant information to any other SDF / MDL MOL reader. The data items are not part of this output–for that section of the SD file format, use writeDataItems() below. The intention is that different coordinates can then be edited for a new structure while the (smaller) data section is re-written separately for a more efficient file I/O process.

Overloaded:

• Write to an output file
• Write to a string

Parameters

foutp	Output file stream
fname	Name of the output file
vformat	Format version of the MDL MOL standard to use. If provided as either V2000 or V3000, this will override information stored in the object.
expectation	Anticipated (or required) condition of the output file that is to be opened, if only its name is provided

---

The documentation for this class was generated from the following files:

• src/MoleculeFormat/mdlmol.h
• src/MoleculeFormat/mdlmol.cpp